Documentation
    Preparing search index...

    Interface ShellAdapter

    All adapters that the shell requires from the host application.

    const hooks: ShellAdapter = {
    relayPool: myRelayPoolHooks,
    relayConfig: myRelayConfigHooks,
    windowManager: myWindowManagerHooks,
    auth: myAuthHooks,
    config: myConfigHooks,
    hotkeys: myHotkeyHooks,
    workerRelay: myWorkerRelayHooks,
    crypto: myCryptoHooks,
    };
    interface ShellAdapter {
        aclDefaultPolicy?: "permissive" | "restrictive";
        auth: AuthHooks;
        ble?: BleHooks;
        capabilities?: CapabilityHooks;
        common?: CommonHooks;
        config: ConfigHooks;
        crypto: CryptoHooks;
        dm?: DmHooks;
        filterNappletMessage?: (
            windowId: string,
            message: NappletMessage,
        ) => NappletMessageDecision;
        getFocusContext?: (
            windowId: string,
        ) => { focused: boolean; msSinceFocusGain?: number };
        hotkeys: HotkeyHooks;
        intent?: IntentHooks;
        legacyFirewall?: LegacyFirewallAdapter;
        link?: LinkHooks;
        lists?: ListsHooks;
        llm?: LlmHooks;
        onAclCheck?: (event: AclCheckEvent) => void;
        onFirewallEvent?: (event: FirewallEvent) => void;
        onHashMismatch?: (dTag: string, claimed: string, computed: string) => void;
        onNappletMessage?: (windowId: string, message: NappletMessage) => void;
        onNappletRevoked?: (revocation: NappletRevocation) => void;
        onNip5dIframeCreate?: (windowId: string) => OriginIdentity | null;
        onUnroutedMessage?: (info: UnroutedMessageInfo) => void;
        permissions?: PermissionAdapter;
        relayConfig: RelayConfigHooks;
        relayPool: RelayPoolHooks;
        serial?: SerialHooks;
        services?: ServiceRegistry;
        upload?: UploadHooks;
        webrtc?: WebrtcHooks;
        windowManager: WindowManagerHooks;
        workerRelay: WorkerRelayHooks;
        getConfigOverrides?(): RuntimeConfigOverrides;
    }
    Index

    Properties

    aclDefaultPolicy?: "permissive" | "restrictive"

    ACL policy for identities with no stored entry. 'restrictive' starts them with nothing granted. When omitted, the policy is 'permissive' unless persisted ACL state stores another one. When set, it replaces the policy in persisted state on load. Stored entries are kept as they are, so a host moving to 'restrictive' should clear entries it no longer trusts. With permissions set it's a ceiling: an approval can't exceed what the ACL denies, and no prompt is shown for it.

    auth: AuthHooks
    ble?: BleHooks

    Optional shell-mediated BLE backend (NAP-BLE). When present and isAvailable() is true, the shell advertises ble. The host still registers the concrete service via registerService('ble').

    capabilities?: CapabilityHooks

    Optional capability advertisement override. Omitted by production hosts.

    common?: CommonHooks

    Optional shell-mediated common social backend (NAP-COMMON). When present and isAvailable() is true, the shell advertises common. The host still registers the concrete service via registerService('common').

    config: ConfigHooks
    crypto: CryptoHooks
    dm?: DmHooks
    filterNappletMessage?: (
        windowId: string,
        message: NappletMessage,
    ) => NappletMessageDecision

    Decides what happens to each NAP envelope from a bound port, before the runtime sees it. onNappletMessage still observes every envelope first. A filter that throws or returns an unknown value drops the envelope.

    shell.ready never reaches this hook, because NAP-SHELL requires its first shell.init reply. While envelopes are deferred, a later dispatch decision joins the queue so it can't overtake them, and drop still discards. A window holding more than MAX_DEFERRED_MESSAGES is revoked with deferred-overflow.

    Spec gap: NAP docs don't define a request that a host holds or drops. A dropped request gets no reply, and a deferred one gets its reply on release.

    Type Declaration

    getFocusContext?: (
        windowId: string,
    ) => { focused: boolean; msSinceFocusGain?: number }

    Reports whether a napplet window has focus. Without it, every window counts as focused, so unfocusedMultiplier never applies. Focus only scales rate budgets and never blocks a message by itself. The legacy gate and the permissions budgets both use it.

    Type Declaration

      • (windowId: string): { focused: boolean; msSinceFocusGain?: number }
      • Parameters

        • windowId: string

          The napplet window to query

        Returns { focused: boolean; msSinceFocusGain?: number }

        Current focus state and optional milliseconds since focus was gained

    hotkeys: HotkeyHooks
    intent?: IntentHooks

    Optional archetype intent dispatcher (NAP-INTENT). When present and isAvailable() is true, the shell advertises the intent domain so napplets can call window.napplet.intent. The host still registers the concrete service via registerService('intent').

    legacyFirewall?: LegacyFirewallAdapter

    Supplies optional legacy behavioral controls. Its config persistence belongs to the supplied adapter. Without an adapter no temporal limits are installed. Legacy gate only: with permissions set, grants use permissions.persistence.

    link?: LinkHooks

    Optional shell-mediated link backend (NAP-LINK). When present and isAvailable() is true, the shell advertises link. The host still registers the concrete service via registerService('link').

    lists?: ListsHooks

    Optional shell-mediated NIP-51 list backend (NAP-LISTS). When present and isAvailable() is true, the shell advertises lists. The host still registers the concrete service via registerService('lists').

    llm?: LlmHooks

    Optional NAP-LLM wiring state. When omitted, a registered llm service is advertised as supported; when present, isAvailable() gates advertisement and isConfigured() feeds the host's unconfigured indicator.

    onAclCheck?: (event: AclCheckEvent) => void

    Called on every ACL enforcement check. Both allows and denials are reported.

    onFirewallEvent?: (event: FirewallEvent) => void

    Called when the runtime firewall flags, rejects or prompts for a message, so a host can show the user what was refused. Passing messages without a flag are not reported. Legacy gate only: with permissions set, the approval UI sees refusals and permissions.onRateLimit reports budget events.

    onHashMismatch?: (dTag: string, claimed: string, computed: string) => void

    Called when aggregate hash verification fails (computed != declared).

    onNappletMessage?: (windowId: string, message: NappletMessage) => void

    Observe-only: called with each NAP envelope received on a napplet's bound NIP-5D port, before the shell dispatches it. NIP-5D moves NAP traffic off window-level message events, so hosts that logged or tracked readiness from those events use this hook instead. It cannot change or drop the message; host hook errors are swallowed.

    onNappletRevoked?: (revocation: NappletRevocation) => void

    Called once when the shell revokes a NIP-5D napplet binding: a second napplet.hello, any other window-level message, an invalid hello, a second iframe load (see ShellBridge.observeFrame), the port closing, or ShellBridge.revokeNapplet. The shell has already closed the port and revoked the identity binding, sessions and grants. NIP-5D requires the host to remove the iframe here; it MAY create a fresh iframe from the verified bytes but MUST NOT reuse this one.

    onNip5dIframeCreate?: (windowId: string) => OriginIdentity | null

    Called at iframe creation for NIP-5D napplets. Returns identity metadata for originRegistry.register(). Returning null means "not NIP-5D / skip registration".

    onUnroutedMessage?: (info: UnroutedMessageInfo) => void

    Called when ShellBridge.handleMessage drops an incoming postMessage because it cannot be routed to a registered napplet window (no source window, or the source Window is not in originRegistry). Observe-only — the message is still dropped; this hook exists so otherwise-silent drops are diagnosable (the FEED-02 / hyprgate#21 class of "a napplet's messages vanish" bug).

    permissions?: PermissionAdapter

    Shared runtime approval UI/storage and temporal adapters.

    relayConfig: RelayConfigHooks
    relayPool: RelayPoolHooks
    serial?: SerialHooks

    Optional shell-mediated serial backend (NAP-SERIAL). When present and isAvailable() is true, the shell advertises serial. The host still registers the concrete service via registerService('serial').

    services?: ServiceRegistry

    Optional service extensions. Each key is a service name (e.g., 'audio', 'notifications'). Napplets discover available services via kind 29010 service discovery events.

    The runtime copies this object when createShellBridge() runs. A handler added later is neither routed nor advertised until it is also registered with bridge.runtime.registerService().

    const hooks: ShellAdapter = {
    // ... required adapters ...
    services: {
    audio: myAudioServiceHandler,
    notifications: myNotificationServiceHandler,
    },
    };
    upload?: UploadHooks

    Optional shell-mediated upload backend (NAP-UPLOAD). When present, the shell advertises the upload domain so napplets can call window.napplet.upload. The host still registers the concrete service via registerService('upload').

    webrtc?: WebrtcHooks

    Optional shell-mediated WebRTC backend (NAP-WEBRTC). When present and isAvailable() is true, the shell advertises webrtc. The host still registers the concrete service via registerService('webrtc').

    windowManager: WindowManagerHooks
    workerRelay: WorkerRelayHooks

    Methods

    • Optional runtime behavior overrides — demo/debug use only. Called lazily on each relevant operation (replay check, buffer push), so changes take effect immediately without runtime recreation.

      Returns RuntimeConfigOverrides