Wayfarer Toolbar SDK · schema 1

Build compact native toolbars with JSON. No executable extension code is supported in this initial SDK.

# Wayfarer Toolbar SDK · schema 1

This initial SDK creates declarative native toolbars. It does not run third-party JavaScript, HTML, CSS, background workers or native code, and is not a Chrome extension API. Wayfarer renders all controls using its own interface. A toolbar cannot read pages, cookies, history, account credentials or clipboard data.

## Build a toolbar

Use UTF-8 JSON under 64 KB with schema, id, name, version, publisher, description and controls. IDs use lowercase letters, digits and hyphens; the toolbar ID has 3–50 characters. Give each control a unique ID. Labels are at most 24 characters. Unknown properties are rejected, including executable content.

A toolbar may have one to six controls and at most one search field. `link` controls use an HTTPS `url`. `search` controls use an HTTPS URL with exactly one `{query}` placeholder in its query string. Submitted terms are URL-encoded; search controls send terms to their destination only when the user submits them. URLs cannot contain credentials or fragments. `action` controls use one of: find, source, instruments, home, openSettings, goblinChat, updatesPage. These open user-facing browser tools; they do not return page data to a toolbar.

## Example

```json
{
  "schema": 1,
  "id": "web-explorer",
  "name": "Web Explorer",
  "version": "1.0.0",
  "publisher": "Hamelton Software",
  "description": "A small-web search and shortcuts toolbar with an old-web spirit.",
  "controls": [
    {
      "id": "search",
      "type": "search",
      "label": "Wikipedia",
      "url": "https://en.wikipedia.org/w/index.php?search={query}"
    },
    {
      "id": "archive",
      "type": "link",
      "label": "Internet Archive",
      "url": "https://archive.org/"
    },
    {
      "id": "wiby",
      "type": "link",
      "label": "Wiby",
      "url": "https://wiby.me/"
    }
  ]
}```

## Install and distribute

Open Settings → Add-ons & toolbars → Import toolbar JSON. The main process validates it and shows the publisher, destination origins and browser actions before installation or replacement. Publisher names in imported JSON are self-reported; these packages are not signed or store-reviewed. All replacements require review again. Export installed manifests to share them. Community submissions, publisher verification, signed updates and broader Chrome extension compatibility are planned rather than available.

## Space and recovery

Guno and custom toolbars share one 32-pixel shelf. Select one toolbar at a time. Extra controls scroll horizontally; they cannot add rows or change shelf height. Up to twelve toolbars may be installed. Installation does not select a toolbar. Users can disable individual toolbars, disable all, remove/export them, or undo the most recent removal during that session. Toolbars are stored locally in addons.json, outside account sync and portable-profile exports. Launch Wayfarer.exe --safe-toolbars to disable custom toolbars for that launch without deleting them.

## Future store

The bundled catalog is a store preview, not an open community marketplace. Native toolbars are the first supported category. Skins continue through Appearance & skins; executable extensions and Chrome API compatibility need separate permission, isolation, review and signing work before release.