Documentation
    Preparing search index...

    Interface HostKeysBridge

    Host-bridge contract for pluggable keyboard backends.

    The browser reference implementation (the default createKeysService behaviour when hostBridge is omitted) registers a document-level keydown listener and satisfies this interface structurally — it exposes subscribe(chord, callback) => unsubscribe semantics but omits the two OS-level optional fields (browsers cannot register global hotkeys without privileged APIs).

    Host apps (Electron, Tauri) implement this interface in their own code and pass it via createKeysService({ hostBridge: myBridge }) — the service then delegates subscription lifecycle to the bridge and remains browser-free.

    Reference implementations for Electron / Tauri are explicitly out of v1.4 scope and live in host-app examples / follow-up milestones (see REQUIREMENTS.md "Future Requirements").

    // Host-app pseudocode (Electron main-process relay):
    const electronBridge: HostKeysBridge = {
      subscribe(chord, cb) {
        const handle = globalShortcut.register(chord, () => cb({ key: '', code: '', ctrlKey: false, altKey: false, shiftKey: false, metaKey: false }));
        return () => globalShortcut.unregister(chord);
      },
      registerGlobalHotkey: (chord) => globalShortcut.register(chord, () => {}),
      onGlobalHotkey: (cb) => globalHotkeyBridge.on('global-hotkey', (_, chord) => cb(chord)),
    };

    const keys = createKeysService({ hostBridge: electronBridge });
    runtime.registerService('keys', keys);
    interface HostKeysBridge {
        onGlobalHotkey?(callback: (chord: string) => void): () => void;
        registerGlobalHotkey?(chord: string): boolean;
        subscribe(
            chord: string,
            callback: (event: HostKeyEvent | KeyboardEvent) => void,
        ): () => void;
    }
    Index

    Methods

    onGlobalHotkey? registerGlobalHotkey? subscribe

    Methods

    • Optional: register an OS-level global hotkey (works even when the host window is not focused). Returns true on success, false if the chord cannot be registered (e.g. already claimed by another app).

      Omitted by the browser reference implementation — browsers cannot register OS-level global hotkeys without privileged APIs. Electron (globalShortcut) and Tauri (GlobalShortcut) provide this.

      Parameters

      • chord: string

      Returns boolean

    • Subscribe a callback to a chord. Returns an unsubscribe handle.

      Implementations MUST:

      • invoke callback exactly once per matching chord event (implementations are responsible for any OS-autorepeat filtering)
      • invoke callback synchronously during the event delivery
      • accept the string chord format documented by @napplet/nap/keys (e.g. 'Ctrl+Shift+K', 'Cmd+P')

      Parameters

      • chord: string
      • callback: (event: HostKeyEvent | KeyboardEvent) => void

      Returns () => void

    Settings

    Member Visibility

    On This Page

    Methods