DEVELOPER REFERENCE · 0.4

Build for curious people.

Wayfarer is a Windows desktop browser built with Electron and Chromium. Websites use standard web APIs. The browser interface runs separately from the websites it hosts.

Building a website

Use standard HTML, CSS and JavaScript and serve your site over HTTPS. The Location bar accepts HTTP localhost addresses for local development, such as http://localhost:3000. Opening a sidebar reduces the page viewport by 320 pixels; use responsive layouts and measure the page viewport rather than the screen.

const canObserve = 'ResizeObserver' in window;
const width = document.documentElement.clientWidth;

Use feature detection instead of assuming that every Chromium feature is available. Open Settings → Developer reference for the current Chromium version and user agent. JavaScript DevTools are available through Inspect current page or F12.

Current capabilities and limits

Working on Wayfarer itself

main.js
Creates the native window and website views, owns navigation, and validates the trusted sender for shell IPC.
preload.js
Exposes the limited browser-interface bridge through contextBridge. It is loaded only for the trusted interface.
renderer.js
Updates toolbar controls, tabs, sidebar content, notes, and settings.
library.js
Persists notes, journey snapshots, recent history and preferences.
style.css + chrome.css
Browser layout and branded controls. These styles are never injected into websites.
assets/
Original supplied SVG branding, toolbar icons, raster application icon, and Windows ICO.
Build Portable.ps1
Copies the runtime and application, then stamps the Windows executable with Wayfarer's icon and version metadata.

Home Port customization

Home Port uses home.html, home.js, home.css and portal.js. Blocks have stable IDs, type, title, content, width (span), visibility and checklist state. Its schema 1 JSON can be exported independently or included in a portable profile with bookmarks and browser preferences.

CSS can target .portal, #portal-grid, .portal-block, .block-title, .block-content and [data-type="checklist"]. Color variables are --paper, --ink, --muted, --accent, --card and --edge. CSS applies only to the local portal. Scripts, external stylesheets and font imports are blocked. Images may use HTTPS or embedded raster data URLs.

portal-preload.js exposes window.homePort only on the local home.html page. Every command is restricted in the main process to that exact local file, the main frame and an existing Wayfarer tab. Remote pages have no portal controls. This internal bridge is not a public plugin API. Optional account sync is not connected; portable profile import/export works locally.

Trusted interface bridge

These examples are for Wayfarer's own renderer. window.wayfarer is not exposed to websites. This internal bridge is not a supported third-party plugin API.

await window.wayfarer.command('new');
await window.wayfarer.command('navigate', 'https://example.com');
await window.wayfarer.command('panel', 'notes');
window.wayfarer.onState(state => {
  // tabs, active, url, loading, bookmarks, preferences,
  // journeys, history, note, noteKey and developer metadata
});

Main-process handlers also provide navigation, zoom, bookmarks, notes, journey save/resume/remove, preferences, and developer tools. Website code cannot invoke those handlers: IPC accepts commands only from the trusted shell webContents.

Local storage

Settings shows the profile path through Copy runtime diagnostics. bookmarks.json contains saved destinations. library.json contains notes, journeys, history, and preferences. A page note is keyed by its HTTP/HTTPS URL with the fragment removed. Each saved journey records an ID, name, timestamp, and website tabs with title, URL and a note snapshot. Resuming keeps newer existing page notes.

Run, test and package

npm.cmd install
npm.cmd start
npm.cmd test
npm.cmd run smoke
powershell -ExecutionPolicy Bypass -File "Build Portable.ps1"

Close the portable application before rebuilding. Smoke tests use isolated profiles and write smoke-result.json. They verify live browsing, notes, journeys, persistence, sidebar sizing, home-port customization, branding, selection rules, and developer settings.

Discovery, Guno and filtering

discovery.js obtains live Wiby random destinations and avoids recent hosts; it also prepares a guarded submission to Guno’s existing website form. protection.js routes Ghostery network and cosmetic filtering according to global and per-host preferences. Both master-off and site exceptions bypass all filters for the relevant pages. Cookie-notice hiding is an independent choice while protection is enabled. Bundled filter engines and their source lists live under assets/filters; updates are cached in the user profile.

Destination folders

bookmarks.js owns the saved-link tree; bookmarks-ui.js renders the bar, folder manager, editor, and drag/drop actions. bookmarks.json is an ordered array of items with stable id, type (link or folder), title, parentId, and URL for links. Cycles and non-HTTP/HTTPS URLs are rejected. Import assigns fresh IDs while preserving parent relationships. The profile migration preserves existing links.

The optional Guno toolbar increases browser chrome height by 32 pixels. Measure website viewport changes rather than assuming a fixed window-to-content offset.