Shortcuts

Shortcuts are keyboard-triggered extension modules. The core app keeps / for search focus; the rest of the default shortcuts are installed through the extension store so they can be updated, removed, and distributed like other extension types.

Where shortcuts live

Local shortcuts live in data/shortcuts. A local file can be a flat JavaScript file such as data/shortcuts/my-action-shortcut.js, or a store package can install a shortcut directory under the same root. Store repositories declare shortcuts with a top-level shortcuts array in package.json.

{
  "shortcuts": [
    {
      "name": "Next tab",
      "description": "Switch to the next visible results tab.",
      "path": "shortcuts/next-tab",
      "version": "1.0.0"
    }
  ]
}

Shortcut module shape

A shortcut module exports an object with a name, optional description, a default binding, and a run function. The run function receives a browser-side context for DOM manipulation.

export default {
  name: "Focus first result",
  description: "Move focus to the first visible result link.",
  defaultBinding: { key: "j", alt: true },
  run({ document }) {
    document.querySelector("#results-list a.result-title")?.focus();
  },
};

Numeric shortcuts use kind: "numeric". Their binding stores only modifiers, and the engine registers one binding per digit, mapping the recorded modifier plus 1 through 9 to the same shortcut. The digit that was pressed is read from event.key inside run, so a single numeric shortcut covers all nine keys. The trigger range is fixed to 1–9.

export default {
  name: "Switch tab by number",
  kind: "numeric",
  defaultBinding: { alt: true },
  run({ document, event }) {
    const n = Number(event.key);
    document.querySelectorAll(".results-tab")[n - 1]?.click();
  },
};

Bindings and settings

User-selected bindings are stored in plugin-settings.json under the shortcuts settings id. The stored values are only the mapping overrides; shortcut source code remains in data/shortcuts or in installed store extension folders.

To rebind a shortcut, click its recorder button in the Shortcuts tab and press the new combination. For numeric shortcuts the recorder prompts for a modifier plus any key, and only the modifiers are saved. Press Escape while recording to cancel, and use the reset action to return a shortcut to its default binding.

Modifier labels are rendered per platform: macOS shows the standard symbols (⌘, ⌥, ⌃, ⇧), Windows shows Win for the meta key, and Linux shows Super. The extension store catalog also renders a shortcut's default binding as CSS keycaps in place of a screenshot.

Creating shortcuts in the UI

Settings includes a Shortcuts tab with an add shortcut action. The editor scaffolds the module syntax, supports syntax highlighting, and handles Tab and Shift+Tab indentation inside the code area. Saving writes a local editable shortcut file to data/shortcuts and reloads the shortcut registry.

Enabling and disabling shortcuts

Each store-installed or locally created shortcut has an on/off toggle on its card in the Shortcuts tab. Toggling writes the disabled setting for that shortcut, the same value exposed on the Extensions tab, so the two stay in sync. A disabled shortcut is skipped when the page registers shortcuts, so it stops firing on the next page load. The built-in / search focus action is part of the core app rather than an extension, so it can be rebound or reset but not disabled.

Deleting shortcuts

The Shortcuts tab can delete editable local shortcut files created in data/shortcuts. Store-installed shortcuts are managed through the store install or uninstall flow, so deleting from the Shortcuts tab does not remove store package files.