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 start on one 40-pixel shared shelf. Select one toolbar at a time, or detach up to three favorites into independent rows inside the browser window. Return a row to the shelf with its button. Extra controls scroll horizontally. Manifests cannot change row height or create rows automatically. 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.