@kehto/shell 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1617 @@
+import { Capability, ServiceRegistry, RuntimeConfigOverrides, ConsentRequest, Runtime, RuntimeAdapter } from '@kehto/runtime';
+export { ALL_CAPABILITIES, AclChecker, Capability, ConsentRequest, EnforceConfig, EnforceResult, IdentityResolver, NubEnforceConfig, NubMessage, ServiceDescriptor, ServiceHandler, ServiceRegistry, createEnforceGate, createNubEnforceGate, formatDenialReason } from '@kehto/runtime';
+import { NappletMessage, NostrEvent, NostrFilter } from '@napplet/core';
+export { NappletMessage, NostrEvent, NostrFilter, TOPICS, TopicKey, TopicValue } from '@napplet/core';
+import { Theme } from '@napplet/nub-theme';
+
+/**
+ * Registry entry mapping a napplet's pubkey to its runtime metadata.
+ * Created after a successful NIP-42 AUTH handshake or NIP-5D origin registration.
+ * @example
+ * ```ts
+ * const entry: SessionEntry = {
+ *   pubkey: 'abc123...', windowId: 'win-1', origin: '*',
+ *   type: 'chat', dTag: '3chat', aggregateHash: 'deadbeef',
+ *   registeredAt: Date.now(), instanceId: 'guid-123',
+ *   identitySource: 'auth',
+ * };
+ * ```
+ */
+interface SessionEntry {
+    /**
+     * @deprecated NIP-5D: AUTH keypair no longer exists. Empty string for NIP-5D sessions.
+     * Kept for backward compatibility during legacy support period.
+     */
+    pubkey: string;
+    windowId: string;
+    origin: string;
+    type: string;
+    dTag: string;
+    aggregateHash: string;
+    registeredAt: number;
+    /** Persistent GUID for this iframe instance, assigned by the runtime. Survives page reloads. */
+    instanceId: string;
+    /**
+     * How session identity was established.
+     * 'source' = NIP-5D (identity registered at iframe creation via originRegistry).
+     * 'auth' = legacy AUTH handshake (pubkey is the derived keypair pubkey).
+     */
+    identitySource: 'auth' | 'source';
+}
+/** @deprecated Use SessionEntry. Will be removed in v0.9.0. */
+type NappKeyEntry = SessionEntry;
+/**
+ * ACL entry controlling what a napplet pubkey is permitted to do.
+ * @example
+ * ```ts
+ * const entry: AclEntry = {
+ *   pubkey: 'abc123...', capabilities: ['relay:read', 'relay:write'],
+ *   blocked: false, stateQuota: 524288,
+ * };
+ * ```
+ */
+interface AclEntry {
+    pubkey: string;
+    capabilities: Capability[];
+    blocked: boolean;
+    stateQuota?: number;
+}
+/**
+ * Hook for relay pool operations. Host app provides relay connectivity.
+ * @example
+ * ```ts
+ * const relayPoolHooks: RelayPoolHooks = {
+ *   getRelayPool: () => myPool,
+ *   trackSubscription: (key, cleanup) => subscriptions.set(key, cleanup),
+ *   // ...
+ * };
+ * ```
+ */
+interface RelayPoolHooks {
+    /** Get the relay pool instance — returns null if no pool available. */
+    getRelayPool(): RelayPoolLike | null;
+    /** Track a subscription for lifecycle management. */
+    trackSubscription(subKey: string, cleanup: () => void): void;
+    /** Untrack and clean up a subscription. */
+    untrackSubscription(subKey: string): void;
+    /** Open a scoped relay connection (NIP-29 groups). */
+    openScopedRelay(windowId: string, relayUrl: string, subId: string, filters: NostrFilter[], sourceWindow: Window): void;
+    /** Close a scoped relay connection. */
+    closeScopedRelay(windowId: string): void;
+    /** Publish to a scoped relay. Returns false if no active scoped relay. */
+    publishToScopedRelay(windowId: string, event: NostrEvent): boolean;
+    /** Select relay URLs for a given set of filters. */
+    selectRelayTier(filters: NostrFilter[]): string[];
+}
+/** Minimal relay pool interface that the shell requires. */
+interface RelayPoolLike {
+    subscription(relayUrls: string[], filters: any): {
+        subscribe(observer: (item: unknown) => void): {
+            unsubscribe(): void;
+        };
+    };
+    publish(relayUrls: string[], event: any): void;
+    request(relayUrls: string[], filters: any): {
+        subscribe(observer: {
+            next: (event: unknown) => void;
+            complete: () => void;
+            error: () => void;
+        }): {
+            unsubscribe(): void;
+        };
+    };
+}
+/** Hook for relay configuration. */
+interface RelayConfigHooks {
+    /** Add a relay URL to a named tier. */
+    addRelay(tier: string, url: string): void;
+    /** Remove a relay URL from a named tier. */
+    removeRelay(tier: string, url: string): void;
+    /** Get the current relay configuration by tier. */
+    getRelayConfig(): {
+        discovery: string[];
+        super: string[];
+        outbox: string[];
+    };
+    /** Get NIP-66 relay suggestions. */
+    getNip66Suggestions(): unknown;
+}
+/** Hook for window management. */
+interface WindowManagerHooks {
+    /** Create a new window. Returns the window ID or null on failure. */
+    createWindow(options: {
+        title: string;
+        class: string;
+        iframeSrc?: string;
+    }): string | null;
+}
+/** Hook for auth state and signing. */
+interface AuthHooks {
+    /** Get the current user's pubkey, or null if not logged in. */
+    getUserPubkey(): string | null;
+    /** Get the NIP-07 compatible signer, or null if unavailable. */
+    getSigner(): any | null;
+}
+/** Hook for config. */
+interface ConfigHooks {
+    /** Get the napp update behavior policy. */
+    getNappUpdateBehavior(): 'auto-grant' | 'banner' | 'silent-reprompt';
+}
+/** Hook for hotkey dispatch. */
+interface HotkeyHooks {
+    /** Execute a forwarded hotkey from a napp. */
+    executeHotkeyFromForward(event: {
+        key: string;
+        code: string;
+        ctrlKey: boolean;
+        altKey: boolean;
+        shiftKey: boolean;
+        metaKey: boolean;
+    }): void;
+}
+/** Hook for worker relay (local cache). */
+interface WorkerRelayHooks {
+    /** Get the worker relay instance, or null if unavailable. */
+    getWorkerRelay(): WorkerRelayLike | null;
+}
+/** Minimal worker relay interface. */
+interface WorkerRelayLike {
+    event(event: NostrEvent): Promise<any>;
+    query(req: any): Promise<NostrEvent[]>;
+    count?(req: any): Promise<number>;
+}
+/** Hook for crypto verification. */
+interface CryptoHooks {
+    /** Verify a nostr event's signature. */
+    verifyEvent(event: NostrEvent): Promise<boolean>;
+}
+/** Hook for DM sending (NIP-17 gift-wrap). */
+interface DmHooks {
+    /** Send a direct message to a recipient. */
+    sendDm(recipientPubkey: string, message: string): Promise<{
+        success: boolean;
+        eventId?: string;
+        error?: string;
+    }>;
+}
+/**
+ * Event emitted on every ACL enforcement check.
+ * @example
+ * ```ts
+ * hooks.onAclCheck = (event: AclCheckEvent) => {
+ *   console.log(`${event.decision}: ${event.capability} for ${event.identity.pubkey}`);
+ * };
+ * ```
+ */
+interface AclCheckEvent {
+    /** The identity being checked. */
+    identity: {
+        pubkey: string;
+        dTag: string;
+        hash: string;
+    };
+    /** The capability being checked (e.g., 'relay:write', 'state:read'). */
+    capability: string;
+    /** The enforcement decision. */
+    decision: 'allow' | 'deny';
+    /** The triggering message, if available. Accepts NIP-01 arrays or NIP-5D NappletMessage envelopes. */
+    message?: NappletMessage | unknown[];
+}
+/**
+ * Static capability set injected into napplet iframes at creation time.
+ * Used by `window.napplet.shell.supports()` for synchronous capability queries.
+ *
+ * Per canonical NIP-5D (specs/NIP-5D.md lines 81-94), supports() distinguishes
+ * two namespaces:
+ *
+ *   - Bare names (or optional `nub:` prefix) for NUB-capability lookups,
+ *     resolved against the `nubs` array — e.g. `supports('relay')`,
+ *     `supports('identity')`.
+ *   - The `perm:<permission>` prefix for sandbox-permission lookups, resolved
+ *     against the `sandbox` array — e.g. `supports('perm:popups')`,
+ *     `supports('perm:modals')`.
+ *
+ * The two namespaces do not cross: a bare-name lookup never matches a sandbox
+ * entry and a `perm:`-prefixed lookup never matches a NUB entry.
+ */
+interface ShellCapabilities {
+    /**
+     * NUB domain prefixes the shell handles. Canonical 8-domain set from @napplet/nub-*:
+     * relay, identity, storage, ifc, theme, keys, media, notify. `relay` is conditional
+     * on the RelayPoolHooks being provided.
+     *
+     * Entries are bare domain names — `'relay'`, `'identity'`, etc. They MUST NOT
+     * carry the `perm:` prefix; that prefix is reserved for the `sandbox` array.
+     * Napplets query NUB support via `supports('<domain>')` (or, equivalently,
+     * `supports('nub:<domain>')`).
+     */
+    nubs: string[];
+    /**
+     * Sandbox permissions under the `perm:<permission>` namespace. Each entry
+     * MUST begin with the literal prefix `'perm:'` — e.g. `'perm:popups'`,
+     * `'perm:modals'`, `'perm:downloads'`. Napplets call
+     * `shell.supports('perm:<permission>')` to check sandbox entitlements.
+     *
+     * The `perm:` prefix is what separates sandbox permissions from NUB
+     * capabilities; bare-name entries here violate the NIP-5D contract and will
+     * be unreachable through `supports()` (see specs/NIP-5D.md §6 and lines
+     * 81-94). NUB-capability lookups (on `nubs`) retain the bare-name
+     * convention and do NOT use the `perm:` prefix.
+     */
+    sandbox: string[];
+}
+/**
+ * All adapters that the shell requires from the host application.
+ * @example
+ * ```ts
+ * const hooks: ShellAdapter = {
+ *   relayPool: myRelayPoolHooks,
+ *   relayConfig: myRelayConfigHooks,
+ *   windowManager: myWindowManagerHooks,
+ *   auth: myAuthHooks,
+ *   config: myConfigHooks,
+ *   hotkeys: myHotkeyHooks,
+ *   workerRelay: myWorkerRelayHooks,
+ *   crypto: myCryptoHooks,
+ * };
+ * ```
+ */
+interface ShellAdapter {
+    relayPool: RelayPoolHooks;
+    relayConfig: RelayConfigHooks;
+    windowManager: WindowManagerHooks;
+    auth: AuthHooks;
+    config: ConfigHooks;
+    hotkeys: HotkeyHooks;
+    workerRelay: WorkerRelayHooks;
+    crypto: CryptoHooks;
+    dm?: DmHooks;
+    /** Called on every ACL enforcement check. Both allows and denials are reported. */
+    onAclCheck?: (event: AclCheckEvent) => void;
+    /** Called when aggregate hash verification fails (computed != declared). */
+    onHashMismatch?: (dTag: string, claimed: string, computed: string) => void;
+    /**
+     * Called at iframe creation for NIP-5D napplets.
+     * Returns identity metadata for originRegistry.register().
+     * Return null for non-NIP-5D (legacy) iframes.
+     */
+    onNip5dIframeCreate?: (windowId: string) => {
+        dTag: string;
+        aggregateHash: string;
+    } | null;
+    /**
+     * Optional service extensions. Each key is a service name (e.g., 'audio',
+     * 'notifications'). Napplets discover available services via kind 29010
+     * service discovery events.
+     *
+     * @example
+     * ```ts
+     * const hooks: ShellAdapter = {
+     *   // ... required adapters ...
+     *   services: {
+     *     audio: myAudioServiceHandler,
+     *     notifications: myNotificationServiceHandler,
+     *   },
+     * };
+     * ```
+     */
+    services?: ServiceRegistry;
+    /**
+     * 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.
+     */
+    getConfigOverrides?(): RuntimeConfigOverrides;
+}
+
+/**
+ * shell-bridge.ts — Browser adapter over @kehto/runtime.
+ *
+ * Thin shell that converts browser MessageEvents into windowId-based
+ * NIP-5D envelope messages for the runtime engine. All protocol logic
+ * (NUB dispatch, ACL enforcement, subscription lifecycle, signer proxying)
+ * lives in @kehto/runtime.
+ *
+ * The only browser-specific concern here is extracting the source Window
+ * from a MessageEvent, mapping it to a windowId via originRegistry, and
+ * routing shell.ready/shell.init handshake locally.
+ */
+
+/**
+ * Shell-side message bridge that handles NIP-5D communication with napplet iframes.
+ *
+ * The bridge acts as a browser adapter: it receives raw MessageEvents from
+ * window.addEventListener('message', ...), extracts the source Window, resolves
+ * it to a windowId via originRegistry, and delegates NIP-5D envelope messages
+ * to the runtime engine. The shell.ready/shell.init capability handshake is
+ * handled locally within the bridge and never forwarded to the runtime.
+ *
+ * @example
+ * ```ts
+ * import { createShellBridge } from '@kehto/shell';
+ *
+ * const bridge = createShellBridge(hooks);
+ * window.addEventListener('message', bridge.handleMessage);
+ * ```
+ */
+interface ShellBridge {
+    /**
+     * Handle an incoming postMessage from a napplet iframe.
+     *
+     * Only NIP-5D envelope objects (plain objects with a `.type` string) are
+     * accepted. NIP-01 arrays and all other message shapes are silently dropped
+     * (clean break — no legacy array fallback).
+     *
+     * shell.ready messages are handled locally: the bridge responds with shell.init
+     * containing the capability set and registered service list. All other envelopes
+     * are delegated to the runtime's NUB domain dispatch.
+     *
+     * @param event - The raw MessageEvent from window.addEventListener('message', ...)
+     * @example
+     * ```ts
+     * window.addEventListener('message', bridge.handleMessage);
+     * ```
+     */
+    handleMessage(event: MessageEvent): void;
+    /**
+     * Inject a shell-originated event into subscription delivery.
+     *
+     * Under NIP-5D, shell-originated events are forwarded to napplets as
+     * ifc.event envelope messages. The runtime's injectEvent() handles
+     * the per-session routing.
+     *
+     * @param topic - The event topic tag value (e.g., 'auth:identity-changed')
+     * @param payload - The event content
+     * @example
+     * ```ts
+     * bridge.injectEvent('auth:identity-changed', { pubkey: userPubkey });
+     * ```
+     */
+    injectEvent(topic: string, payload: unknown): void;
+    /**
+     * Destroy the bridge instance, cleaning up all internal state.
+     * Persists manifest cache and clears all subscriptions, buffers, and registries.
+     * Call when the shell is shutting down or the bridge is no longer needed.
+     *
+     * @example
+     * ```ts
+     * bridge.destroy();
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Register a handler for consent requests on destructive signing kinds.
+     * Called when a napplet requests signing for kinds 0, 3, 5, or 10002.
+     *
+     * @param handler - Callback receiving the consent request with a resolve function
+     * @example
+     * ```ts
+     * bridge.registerConsentHandler((request) => {
+     *   const allowed = confirm(`Allow signing kind ${request.event.kind}?`);
+     *   request.resolve(allowed);
+     * });
+     * ```
+     */
+    registerConsentHandler(handler: (request: ConsentRequest) => void): void;
+    /**
+     * Publish a theme update to every registered napplet.
+     *
+     * Posts a `theme.changed` envelope (shell → napplet push) to every
+     * window currently tracked by the runtime's sessionRegistry, using
+     * the browser-adapter originRegistry to resolve windowId → iframe.
+     * Napplets whose window cannot be resolved (stale sessions) are
+     * silently skipped; this method never throws.
+     *
+     * ACL is enforced BY THE RECIPIENT NAPPLET — the runtime's
+     * `themeMap` in @kehto/acl assigns `recipientCap: 'theme:read'` for
+     * `theme.changed`, and @napplet/shim drops pushes the napplet lacks
+     * the capability for. Hosts should not self-filter here.
+     *
+     * @param theme - The new theme payload to broadcast.
+     * @example
+     * ```ts
+     * bridge.publishTheme({
+     *   colors: { background: '#0a0a0a', text: '#e0e0e0', primary: '#7aa2f7' },
+     *   title: 'Dark',
+     * });
+     * ```
+     */
+    publishTheme(theme: Theme): void;
+    /**
+     * Access the underlying runtime instance for advanced use cases.
+     * Provides direct access to the runtime's sessionRegistry, aclState,
+     * and manifestCache.
+     */
+    readonly runtime: Runtime;
+}
+/**
+ * Create a ShellBridge instance with dependency injection via hooks.
+ *
+ * Internally creates a Runtime from @kehto/runtime and adapts the
+ * browser-oriented ShellAdapter into environment-agnostic RuntimeAdapter.
+ *
+ * @param hooks - Host application provides relay pool, auth, config, etc.
+ * @returns A ShellBridge instance ready to handle napplet messages
+ * @example
+ * ```ts
+ * import { createShellBridge, type ShellAdapter } from '@kehto/shell';
+ *
+ * const hooks: ShellAdapter = {
+ *   relayPool: myRelayPoolHooks,
+ *   relayConfig: myRelayConfigHooks,
+ *   windowManager: myWindowManagerHooks,
+ *   auth: myAuthHooks,
+ *   config: myConfigHooks,
+ *   hotkeys: myHotkeyHooks,
+ *   workerRelay: myWorkerRelayHooks,
+ *   crypto: myCryptoHooks,
+ * };
+ * const bridge = createShellBridge(hooks);
+ * ```
+ */
+declare function createShellBridge(hooks: ShellAdapter): ShellBridge;
+
+/**
+ * Origin Registry — Window reference to windowId mapping.
+ *
+ * Used by the ShellBridge to validate that postMessage senders are known
+ * napplet iframes. event.source (a Window reference) is the only unforgeable
+ * origin — never trust event.origin from the message payload.
+ */
+/**
+ * Bidirectional registry mapping Window references to windowId strings.
+ * Optionally stores NIP-5D identity metadata (dTag and aggregateHash) per window.
+ *
+ * @example
+ * ```ts
+ * import { originRegistry } from '@kehto/shell';
+ *
+ * originRegistry.register(iframe.contentWindow, 'napp-1');
+ * const id = originRegistry.getWindowId(iframe.contentWindow); // 'napp-1'
+ * ```
+ */
+declare const originRegistry: {
+    /**
+     * Register a window reference with a windowId and optional identity metadata.
+     *
+     * @param win - The iframe's contentWindow reference
+     * @param windowId - The unique identifier for this napplet window
+     * @param identity - Optional NIP-5D identity metadata (dTag and aggregateHash)
+     */
+    register(win: Window, windowId: string, identity?: {
+        dTag: string;
+        aggregateHash: string;
+    }): void;
+    /**
+     * Unregister a window by its windowId, removing the mapping.
+     *
+     * @param windowId - The window identifier to remove
+     */
+    unregister(windowId: string): void;
+    /**
+     * Look up the windowId for a given Window reference.
+     *
+     * @param win - The Window reference (typically from event.source)
+     * @returns The windowId string, or undefined if not registered
+     */
+    getWindowId(win: Window): string | undefined;
+    /**
+     * Look up the Window reference for a given windowId.
+     *
+     * @param windowId - The window identifier to look up
+     * @returns The Window reference, or null if not found
+     */
+    getIframeWindow(windowId: string): Window | null;
+    /**
+     * Get all registered windowId strings.
+     *
+     * @returns Array of all registered window identifiers
+     */
+    getAllWindowIds(): string[];
+    /**
+     * Get identity metadata for a registered Window.
+     *
+     * @param win - The Window reference to look up
+     * @returns Identity metadata, or undefined if not registered or no identity set
+     */
+    getIdentity(win: Window): {
+        dTag: string;
+        aggregateHash: string;
+    } | undefined;
+    /** Clear all registrations. */
+    clear(): void;
+};
+
+/**
+ * Manifest cache — persists verified NIP-5A aggregate hashes per napplet identity.
+ */
+/**
+ * A cached manifest entry for a verified napplet build.
+ * @example
+ * ```ts
+ * const entry: ManifestCacheEntry = {
+ *   pubkey: 'abc123...', dTag: '3chat',
+ *   aggregateHash: 'deadbeef', verifiedAt: Date.now(),
+ * };
+ * ```
+ */
+interface ManifestCacheEntry {
+    pubkey: string;
+    dTag: string;
+    aggregateHash: string;
+    verifiedAt: number;
+}
+/**
+ * Cache for verified napplet manifest entries. Persists to localStorage.
+ * Used to detect napplet updates (aggregateHash changes) across sessions.
+ *
+ * @example
+ * ```ts
+ * import { manifestCache } from '@kehto/shell';
+ *
+ * manifestCache.set({ pubkey: 'abc...', dTag: 'chat', aggregateHash: 'dead', verifiedAt: Date.now() });
+ * const entry = manifestCache.get('abc...', 'chat');
+ * ```
+ */
+declare const manifestCache: {
+    /**
+     * Get a cached manifest entry by pubkey and dTag.
+     *
+     * @param pubkey - The napp's pubkey
+     * @param dTag - The napp's dTag
+     * @returns The cached entry, or undefined if not found
+     */
+    get(pubkey: string, dTag: string): ManifestCacheEntry | undefined;
+    /**
+     * Set (upsert) a manifest cache entry and persist to localStorage.
+     *
+     * @param entry - The manifest entry to cache
+     */
+    set(entry: ManifestCacheEntry): void;
+    /**
+     * Check if a specific hash is cached for a pubkey/dTag combination.
+     *
+     * @param pubkey - The napp's pubkey
+     * @param dTag - The napp's dTag
+     * @param hash - The aggregateHash to check
+     * @returns True if the exact hash matches the cached entry
+     */
+    has(pubkey: string, dTag: string, hash: string): boolean;
+    /**
+     * Remove a cached entry for a pubkey/dTag and persist.
+     *
+     * @param pubkey - The napp's pubkey
+     * @param dTag - The napp's dTag
+     */
+    remove(pubkey: string, dTag: string): void;
+    /** Load the cache from localStorage. */
+    load(): void;
+    /** Persist the cache to localStorage. */
+    persist(): void;
+    /** Clear all cached entries and remove from localStorage. */
+    clear(): void;
+};
+
+/**
+ * ACL Store — composite-keyed capability registry for napplet identity.
+ *
+ * ACL entries are keyed by dTag:aggregateHash — a 2-segment composite key
+ * that ties permissions to a specific napplet build (NIP-5D format).
+ * Old 3-segment keys (pubkey:dTag:hash) are automatically migrated via migrateAclState().
+ *
+ * Default policy is PERMISSIVE: unknown identities have all capabilities granted.
+ */
+
+/**
+ * ACL store — manages capability grants, revocations, and blocks for napp identities.
+ * Persists to localStorage and uses a permissive default policy (all capabilities granted).
+ *
+ * @example
+ * ```ts
+ * import { aclStore } from '@kehto/shell';
+ *
+ * aclStore.grant(pubkey, dTag, hash, 'relay:read');
+ * const allowed = aclStore.check(pubkey, dTag, hash, 'relay:read'); // true
+ * ```
+ */
+declare const aclStore: {
+    /**
+     * Check if a napp identity has a specific capability.
+     * Returns true for unknown identities (permissive default).
+     *
+     * @param pubkey - The napp's pubkey
+     * @param dTag - The napp's dTag
+     * @param aggregateHash - The napp's build hash
+     * @param capability - The capability to check
+     * @returns True if the capability is granted and the napp is not blocked
+     */
+    check(pubkey: string, dTag: string, aggregateHash: string, capability: Capability): boolean;
+    /**
+     * Grant a capability to a napp identity.
+     *
+     * @param pubkey - The napp's pubkey
+     * @param dTag - The napp's dTag
+     * @param aggregateHash - The napp's build hash
+     * @param capability - The capability to grant
+     */
+    grant(pubkey: string, dTag: string, aggregateHash: string, capability: Capability): void;
+    /**
+     * Revoke a capability from a napp identity.
+     *
+     * @param pubkey - The napp's pubkey
+     * @param dTag - The napp's dTag
+     * @param aggregateHash - The napp's build hash
+     * @param capability - The capability to revoke
+     */
+    revoke(pubkey: string, dTag: string, aggregateHash: string, capability: Capability): void;
+    /**
+     * Block a napp identity entirely (all capabilities denied).
+     *
+     * @param pubkey - The napp's pubkey
+     * @param dTag - The napp's dTag
+     * @param aggregateHash - The napp's build hash
+     */
+    block(pubkey: string, dTag: string, aggregateHash: string): void;
+    /**
+     * Unblock a napp identity.
+     *
+     * @param pubkey - The napp's pubkey
+     * @param dTag - The napp's dTag
+     * @param aggregateHash - The napp's build hash
+     */
+    unblock(pubkey: string, dTag: string, aggregateHash: string): void;
+    /**
+     * Check if a napp identity is blocked.
+     *
+     * @param pubkey - The napp's pubkey
+     * @param dTag - The napp's dTag
+     * @param aggregateHash - The napp's build hash
+     * @returns True if the identity is blocked
+     */
+    isBlocked(pubkey: string, dTag: string, aggregateHash: string): boolean;
+    /**
+     * Get the external ACL entry for a napp identity.
+     *
+     * @param pubkey - The napp's pubkey
+     * @param dTag - The napp's dTag
+     * @param aggregateHash - The napp's build hash
+     * @returns The ACL entry, or undefined if no explicit entry exists
+     */
+    getEntry(pubkey: string, dTag: string, aggregateHash: string): AclEntry | undefined;
+    /**
+     * Get all ACL entries.
+     *
+     * @returns Array of all ACL entries
+     */
+    getAllEntries(): AclEntry[];
+    /** Persist the ACL store to localStorage. */
+    persist(): void;
+    /** Load the ACL store from localStorage. Migrates old 3-segment keys to 2-segment format. */
+    load(): void;
+    /**
+     * Get the state quota for a napp identity.
+     *
+     * @param pubkey - The napp's pubkey
+     * @param dTag - The napp's dTag
+     * @param aggregateHash - The napp's build hash
+     * @returns The quota in bytes (defaults to DEFAULT_STATE_QUOTA)
+     */
+    getStateQuota(pubkey: string, dTag: string, aggregateHash: string): number;
+    /** Clear all ACL entries and remove from localStorage. */
+    clear(): void;
+};
+
+/**
+ * audio-manager.ts — Shell-side registry of active audio sources.
+ *
+ * Tracks which windows are producing audio. UI components read the registry
+ * reactively via the version counter and CustomEvent pattern.
+ */
+/**
+ * An active audio source registered by a napplet.
+ * @example
+ * ```ts
+ * const source: AudioSource = {
+ *   windowId: 'win-1', nappletClass: 'music-player',
+ *   title: 'Now Playing', muted: false,
+ * };
+ * ```
+ */
+interface AudioSource {
+    windowId: string;
+    nappletClass: string;
+    title: string;
+    muted: boolean;
+}
+/**
+ * Registry of active audio sources across all napplet windows.
+ * Emits 'napplet:audio-changed' CustomEvents when the registry changes.
+ *
+ * @example
+ * ```ts
+ * import { audioManager } from '@kehto/shell';
+ *
+ * audioManager.register('win-1', 'music', 'My Song');
+ * audioManager.mute('win-1', true);
+ * ```
+ */
+declare const audioManager: {
+    /**
+     * Register a new audio source for a window.
+     *
+     * @param windowId - The window identifier
+     * @param nappletClass - The napplet class/type (e.g., 'music-player')
+     * @param title - Human-readable title for the audio source
+     */
+    register(windowId: string, nappletClass: string, title: string): void;
+    /**
+     * Unregister an audio source for a window.
+     *
+     * @param windowId - The window identifier to remove
+     */
+    unregister(windowId: string): void;
+    /**
+     * Update the state of an audio source (e.g., change title).
+     *
+     * @param windowId - The window identifier
+     * @param update - Partial update with optional title
+     */
+    updateState(windowId: string, update: {
+        title?: string;
+    }): void;
+    /**
+     * Mute or unmute an audio source and notify the napplet via postMessage.
+     *
+     * @param windowId - The window identifier
+     * @param muted - True to mute, false to unmute
+     * @example
+     * ```ts
+     * audioManager.mute('win-1', true); // mute
+     * audioManager.mute('win-1', false); // unmute
+     * ```
+     */
+    mute(windowId: string, muted: boolean): void;
+    /**
+     * Check if a window has a registered audio source.
+     *
+     * @param windowId - The window identifier
+     * @returns True if the window has an active audio source
+     */
+    has(windowId: string): boolean;
+    /**
+     * Get the audio source for a window.
+     *
+     * @param windowId - The window identifier
+     * @returns The AudioSource, or undefined if not found
+     */
+    get(windowId: string): AudioSource | undefined;
+    /**
+     * Get a snapshot of all audio sources.
+     *
+     * @returns A new Map of all active audio sources
+     */
+    getSources(): Map<string, AudioSource>;
+    /** Current version counter (incremented on every change). */
+    readonly version: number;
+    /** Number of active audio sources. */
+    readonly count: number;
+    /** Clear all audio sources and reset version counter. */
+    clear(): void;
+};
+
+/**
+ * SessionRegistry — windowId to verified napplet pubkey bidirectional mapping.
+ *
+ * After a successful AUTH handshake, the ShellBridge registers the napplet's
+ * verified pubkey here. Both mappings are kept in sync.
+ */
+
+/**
+ * A pending napplet update — raised when a napplet reconnects with a different aggregateHash.
+ * @example
+ * ```ts
+ * const update: PendingUpdate = {
+ *   windowId: 'win-1', pubkey: 'abc...', dTag: '3chat',
+ *   oldHash: 'aaa', newHash: 'bbb',
+ *   resolve: (action) => { if (action === 'accept') { // apply } },
+ * };
+ * ```
+ */
+interface PendingUpdate {
+    windowId: string;
+    pubkey: string;
+    dTag: string;
+    oldHash: string;
+    newHash: string;
+    resolve: (action: 'accept' | 'block') => void;
+}
+/**
+ * Bidirectional registry mapping windowIds to verified napplet pubkeys.
+ * Maintained by ShellBridge after successful AUTH handshakes.
+ *
+ * @example
+ * ```ts
+ * import { sessionRegistry } from '@kehto/shell';
+ *
+ * const pubkey = sessionRegistry.getPubkey('win-1');
+ * const entry = pubkey ? sessionRegistry.getEntry(pubkey) : undefined;
+ * ```
+ */
+declare const sessionRegistry: {
+    /**
+     * Register a napplet entry, mapping windowId to pubkey and vice versa.
+     *
+     * @param windowId - The window identifier
+     * @param entry - The verified napplet session entry from AUTH handshake
+     */
+    register(windowId: string, entry: SessionEntry): void;
+    /**
+     * Unregister a napplet by windowId, removing both mappings.
+     *
+     * @param windowId - The window identifier to remove
+     */
+    unregister(windowId: string): void;
+    /**
+     * Get the pubkey associated with a windowId.
+     *
+     * @param windowId - The window identifier
+     * @returns The napplet's pubkey, or undefined if not registered
+     */
+    getPubkey(windowId: string): string | undefined;
+    /**
+     * Get the full entry for a napplet pubkey.
+     *
+     * @param pubkey - The napplet's pubkey
+     * @returns The full SessionEntry, or undefined if not found
+     */
+    getEntry(pubkey: string): SessionEntry | undefined;
+    /**
+     * Get the windowId for a napplet pubkey.
+     *
+     * @param pubkey - The napplet's pubkey
+     * @returns The windowId, or undefined if not found
+     */
+    getWindowId(pubkey: string): string | undefined;
+    /**
+     * Check if a windowId has a registered napplet.
+     *
+     * @param windowId - The window identifier
+     * @returns True if the windowId has a registered napplet
+     */
+    isRegistered(windowId: string): boolean;
+    /**
+     * Get all registered napplet entries.
+     *
+     * @returns Array of all SessionEntry objects
+     */
+    getAllEntries(): SessionEntry[];
+    /**
+     * Set a pending update for a window (napplet reconnected with different hash).
+     *
+     * @param windowId - The window identifier
+     * @param update - The pending update details with resolve callback
+     */
+    setPendingUpdate(windowId: string, update: PendingUpdate): void;
+    /**
+     * Get a pending update for a window.
+     *
+     * @param windowId - The window identifier
+     * @returns The pending update, or undefined if none
+     */
+    getPendingUpdate(windowId: string): PendingUpdate | undefined;
+    /**
+     * Clear a pending update for a window.
+     *
+     * @param windowId - The window identifier
+     */
+    clearPendingUpdate(windowId: string): void;
+    /** Clear all registrations and pending updates. */
+    clear(): void;
+};
+/** @deprecated Use sessionRegistry. Will be removed in v0.9.0. */
+declare const nappKeyRegistry: {
+    /**
+     * Register a napplet entry, mapping windowId to pubkey and vice versa.
+     *
+     * @param windowId - The window identifier
+     * @param entry - The verified napplet session entry from AUTH handshake
+     */
+    register(windowId: string, entry: SessionEntry): void;
+    /**
+     * Unregister a napplet by windowId, removing both mappings.
+     *
+     * @param windowId - The window identifier to remove
+     */
+    unregister(windowId: string): void;
+    /**
+     * Get the pubkey associated with a windowId.
+     *
+     * @param windowId - The window identifier
+     * @returns The napplet's pubkey, or undefined if not registered
+     */
+    getPubkey(windowId: string): string | undefined;
+    /**
+     * Get the full entry for a napplet pubkey.
+     *
+     * @param pubkey - The napplet's pubkey
+     * @returns The full SessionEntry, or undefined if not found
+     */
+    getEntry(pubkey: string): SessionEntry | undefined;
+    /**
+     * Get the windowId for a napplet pubkey.
+     *
+     * @param pubkey - The napplet's pubkey
+     * @returns The windowId, or undefined if not found
+     */
+    getWindowId(pubkey: string): string | undefined;
+    /**
+     * Check if a windowId has a registered napplet.
+     *
+     * @param windowId - The window identifier
+     * @returns True if the windowId has a registered napplet
+     */
+    isRegistered(windowId: string): boolean;
+    /**
+     * Get all registered napplet entries.
+     *
+     * @returns Array of all SessionEntry objects
+     */
+    getAllEntries(): SessionEntry[];
+    /**
+     * Set a pending update for a window (napplet reconnected with different hash).
+     *
+     * @param windowId - The window identifier
+     * @param update - The pending update details with resolve callback
+     */
+    setPendingUpdate(windowId: string, update: PendingUpdate): void;
+    /**
+     * Get a pending update for a window.
+     *
+     * @param windowId - The window identifier
+     * @returns The pending update, or undefined if none
+     */
+    getPendingUpdate(windowId: string): PendingUpdate | undefined;
+    /**
+     * Clear a pending update for a window.
+     *
+     * @param windowId - The window identifier
+     */
+    clearPendingUpdate(windowId: string): void;
+    /** Clear all registrations and pending updates. */
+    clear(): void;
+};
+
+/**
+ * hooks-adapter.ts — Converts ShellAdapter (browser-facing) to RuntimeAdapter (environment-agnostic).
+ *
+ * The adapter bridges the gap between the shell's browser-oriented ShellAdapter interfaces
+ * (Window references, localStorage, postMessage) and the runtime's abstract RuntimeAdapter
+ * (windowId strings, persistence interfaces, sendToNapplet callbacks).
+ */
+
+/**
+ * Browser-specific singletons that the adapter bridges to the runtime.
+ * These use browser APIs (Window, localStorage, postMessage, CustomEvent)
+ * that the runtime cannot access directly.
+ */
+interface BrowserDeps {
+    originRegistry: typeof originRegistry;
+    manifestCache: typeof manifestCache;
+    aclStore: typeof aclStore;
+    audioManager: typeof audioManager;
+    nappKeyRegistry: typeof sessionRegistry;
+}
+/**
+ * Convert ShellAdapter (browser-facing) into RuntimeAdapter (environment-agnostic).
+ *
+ * The adapter is the single translation layer between browser APIs and the
+ * runtime's abstract interfaces. It:
+ * - Converts Window references to windowId strings via originRegistry
+ * - Wraps localStorage-backed singletons into persistence interfaces
+ * - Translates relay pool API shapes (Observable → callback)
+ *
+ * @param shellHooks - The browser-oriented ShellAdapter provided by the host app
+ * @param deps - Browser-specific singletons (originRegistry, aclStore, etc.)
+ * @returns RuntimeAdapter suitable for createRuntime()
+ *
+ * @example
+ * ```ts
+ * const runtimeHooks = adaptHooks(shellHooks, {
+ *   originRegistry, manifestCache, aclStore, audioManager, nappKeyRegistry,
+ * });
+ * const runtime = createRuntime(runtimeHooks);
+ * ```
+ */
+declare function adaptHooks(shellHooks: ShellAdapter, deps: BrowserDeps): RuntimeAdapter;
+
+/**
+ * shell-init.ts — Shell initialization utilities.
+ *
+ * Provides buildShellCapabilities() — derives the shell's static NUB capability
+ * set from the ShellAdapter configuration, used in the shell.ready / shell.init
+ * handshake so napplets can query shell.supports() synchronously.
+ *
+ * Canonical NIP-5D forbids the shell from injecting a NIP-07 proxy object on
+ * the napplet iframe's global scope (specs/NIP-5D.md line 44 + Security §6).
+ * This module therefore does NOT expose any signing proxy to napplet code.
+ * Signing/encryption is mediated by the shell through relay.publish and
+ * relay.publishEncrypted — never via a napplet-visible API surface.
+ */
+
+/**
+ * Build the shell's static capability set from adapter configuration.
+ *
+ * NUB capabilities = canonical 8-domain list from @napplet/nub-*:
+ *   relay (gated on hooks.relayPool), identity, storage, ifc, theme, keys, media, notify.
+ *
+ * Sandbox permissions are left empty by default — host apps may extend after
+ * construction. Sandbox entries returned here (and any host-app extensions)
+ * MUST use the canonical `perm:<permission>` form — e.g. `'perm:popups'`,
+ * `'perm:modals'`, `'perm:downloads'`. Napplets rely on the `perm:` prefix to
+ * distinguish sandbox permissions from NUB-capability lookups (bare names,
+ * resolved against `caps.nubs`); see specs/NIP-5D.md lines 81-94.
+ *
+ * @param hooks - The ShellAdapter provided by the host app
+ * @returns ShellCapabilities with nubs (bare-named) and sandbox (perm:-prefixed) arrays
+ * @example
+ * ```ts
+ * const caps = buildShellCapabilities(hooks);
+ * // caps.nubs => ['relay','identity','storage','ifc','theme','keys','media','notify']
+ * //              (relay present when hooks.relayPool is provided; bare names only)
+ * // caps.sandbox => []   // host app may extend with 'perm:popups', etc.
+ * ```
+ */
+declare function buildShellCapabilities(hooks: ShellAdapter): ShellCapabilities;
+
+/**
+ * identity-proxy.ts — Shell-side per-domain proxy for identity.* envelopes.
+ *
+ * Establishes the canonical proxy shape for @kehto/shell (Plan 12-11): each
+ * per-domain proxy exposes a `dispatch` method that delegates napplet→shell
+ * requests to the runtime and an `emit` method that posts shell→napplet
+ * push envelopes through the origin registry.
+ *
+ * By default, `createShellBridge()` does NOT compose this proxy into its
+ * dispatch path — the runtime already owns identity.* dispatch per Plan
+ * 12-03 (see @kehto/services identity-service). This module exists as an
+ * optional composition point for host apps that want to intercept or
+ * augment identity dispatch (e.g. custom logging, sandboxed rewrites, test
+ * doubles).
+ *
+ * The canonical proxy shape — dispatch + emit — is mirrored verbatim by
+ * theme-proxy, keys-proxy, media-proxy, and notify-proxy. Storage today is
+ * served by `@kehto/runtime` state-handler directly; a storage-proxy using
+ * this shape can be added later if host apps need a composition seam.
+ */
+
+/**
+ * Minimal origin-registry contract used by per-domain proxies.
+ *
+ * Accepts the `@kehto/shell` singleton `originRegistry` as well as any test
+ * double with a matching `getIframeWindow` method.
+ */
+interface ProxyOriginRegistry {
+    /** Resolve a registered napplet windowId to its iframe Window, or null. */
+    getIframeWindow(windowId: string): Window | null;
+}
+/**
+ * Dependencies for `createIdentityProxy`.
+ *
+ * @example
+ * ```ts
+ * const proxy = createIdentityProxy({
+ *   runtime: shellBridge.runtime,
+ *   originRegistry,
+ * });
+ * ```
+ */
+interface IdentityProxyDeps {
+    /** The runtime engine that owns identity.* dispatch (Plan 12-03). */
+    runtime: Runtime;
+    /** Origin registry for resolving windowId → iframe Window. */
+    originRegistry: ProxyOriginRegistry;
+}
+/**
+ * Per-domain proxy for `identity.*` envelopes.
+ *
+ * The canonical proxy shape: `dispatch` routes napplet→shell requests into
+ * the runtime; `emit` pushes shell→napplet envelopes through the iframe's
+ * Window.
+ */
+interface IdentityProxy {
+    /**
+     * Route a napplet-originated identity.* envelope into the runtime.
+     *
+     * Delegation only — the runtime already owns identity.* dispatch after
+     * Plan 12-03. Override by wrapping or replacing this method.
+     *
+     * @param windowId - The source napplet's windowId
+     * @param envelope - The NIP-5D NappletMessage envelope
+     */
+    dispatch(windowId: string, envelope: NappletMessage): void;
+    /**
+     * Push a shell-initiated identity-domain envelope into a napplet iframe.
+     *
+     * No-op when the originRegistry cannot resolve the windowId (unknown or
+     * unregistered napplet). Never throws.
+     *
+     * @param windowId - The target napplet's windowId
+     * @param envelope - The NIP-5D NappletMessage envelope to deliver
+     */
+    emit(windowId: string, envelope: NappletMessage): void;
+}
+/**
+ * Factory for the canonical identity-domain proxy.
+ *
+ * @param deps - Runtime + origin registry
+ * @returns An {@link IdentityProxy} ready to route identity.* envelopes
+ * @example
+ * ```ts
+ * import { createIdentityProxy, originRegistry, createShellBridge } from '@kehto/shell';
+ *
+ * const bridge = createShellBridge(hooks);
+ * const identityProxy = createIdentityProxy({
+ *   runtime: bridge.runtime,
+ *   originRegistry,
+ * });
+ *
+ * // Optional composition: intercept napplet->shell identity requests
+ * const originalDispatch = identityProxy.dispatch;
+ * identityProxy.dispatch = (windowId, envelope) => {
+ *   console.log('identity dispatch', windowId, envelope.type);
+ *   originalDispatch(windowId, envelope);
+ * };
+ * ```
+ */
+declare function createIdentityProxy(deps: IdentityProxyDeps): IdentityProxy;
+
+/**
+ * theme-proxy.ts — Shell-side per-domain proxy for theme.* envelopes.
+ *
+ * Establishes the shell-side shape that Phase 13 composes into. Phase 13 is
+ * expected to add `theme-service.ts` (runtime) + the shell-side `theme.set`
+ * API that emits `theme.changed` push envelopes to registered napplets;
+ * this proxy is the canonical seam those pieces plug into.
+ *
+ * Shape mirrors identity-proxy (Plan 12-11):
+ *
+ *   - `dispatch(windowId, envelope)` routes napplet→shell `theme.get` into
+ *     the runtime (where Phase 13's theme-service will answer).
+ *   - `emit(windowId, envelope)` posts shell→napplet `theme.changed`
+ *     envelopes through the origin registry.
+ *
+ * By default `createShellBridge()` does NOT compose this proxy into its
+ * dispatch path — the runtime owns theme.* dispatch. This module is an
+ * optional composition point for host apps or Phase 13 wiring.
+ */
+
+/**
+ * Dependencies for `createThemeProxy`.
+ *
+ * @example
+ * ```ts
+ * const proxy = createThemeProxy({
+ *   runtime: shellBridge.runtime,
+ *   originRegistry,
+ * });
+ * ```
+ */
+interface ThemeProxyDeps {
+    /** The runtime engine that will own theme.* dispatch (Phase 13). */
+    runtime: Runtime;
+    /** Origin registry for resolving windowId → iframe Window. */
+    originRegistry: ProxyOriginRegistry;
+}
+/**
+ * Per-domain proxy for `theme.*` envelopes.
+ *
+ * Shape: `dispatch` routes napplet→shell requests into the runtime; `emit`
+ * pushes shell→napplet envelopes through the iframe's Window.
+ */
+interface ThemeProxy {
+    /**
+     * Route a napplet-originated theme.* envelope (e.g. `theme.get`) into
+     * the runtime.
+     *
+     * @param windowId - The source napplet's windowId
+     * @param envelope - The NIP-5D NappletMessage envelope
+     */
+    dispatch(windowId: string, envelope: NappletMessage): void;
+    /**
+     * Push a shell-initiated theme-domain envelope (e.g. `theme.changed`)
+     * into a napplet iframe.
+     *
+     * No-op when the originRegistry cannot resolve the windowId (unknown or
+     * unregistered napplet). Never throws.
+     *
+     * @param windowId - The target napplet's windowId
+     * @param envelope - The NIP-5D NappletMessage envelope to deliver
+     */
+    emit(windowId: string, envelope: NappletMessage): void;
+}
+/**
+ * Factory for the canonical theme-domain proxy.
+ *
+ * @param deps - Runtime + origin registry
+ * @returns A {@link ThemeProxy} ready to route theme.* envelopes
+ * @example
+ * ```ts
+ * import { createThemeProxy, originRegistry, createShellBridge } from '@kehto/shell';
+ *
+ * const bridge = createShellBridge(hooks);
+ * const themeProxy = createThemeProxy({
+ *   runtime: bridge.runtime,
+ *   originRegistry,
+ * });
+ *
+ * // Phase 13: broadcast theme.changed to every registered napplet
+ * for (const entry of bridge.runtime.sessionRegistry.getAllEntries()) {
+ *   themeProxy.emit(entry.windowId, { type: 'theme.changed', theme: newTheme });
+ * }
+ * ```
+ */
+declare function createThemeProxy(deps: ThemeProxyDeps): ThemeProxy;
+
+/**
+ * keys-proxy.ts — Shell-side per-domain proxy for keys.* envelopes.
+ *
+ * Per Plan 12-05, the runtime already dispatches `keys.*` (forward,
+ * registerAction, unregisterAction) to the keys-service. This proxy is the
+ * shell-side composition point for host apps that want to observe or
+ * inject keys envelopes — it pairs with `keys-forwarder.ts` (Plan 12-11)
+ * which covers the shell→napplet `keys.forward` push path.
+ *
+ * Shape mirrors identity-proxy (Plan 12-11):
+ *
+ *   - `dispatch(windowId, envelope)` routes napplet→shell keys requests
+ *     into the runtime.
+ *   - `emit(windowId, envelope)` posts shell→napplet pushes (`keys.action`,
+ *     `keys.bindings`, `keys.registerAction.result`) through the origin
+ *     registry.
+ *
+ * By default `createShellBridge()` does NOT compose this proxy into its
+ * dispatch path — the runtime owns keys.* dispatch. This module is an
+ * optional composition point for host apps (e.g. global hotkey UIs).
+ */
+
+/**
+ * Dependencies for `createKeysProxy`.
+ *
+ * @example
+ * ```ts
+ * const proxy = createKeysProxy({
+ *   runtime: shellBridge.runtime,
+ *   originRegistry,
+ * });
+ * ```
+ */
+interface KeysProxyDeps {
+    /** The runtime engine that owns keys.* dispatch (Plan 12-05). */
+    runtime: Runtime;
+    /** Origin registry for resolving windowId → iframe Window. */
+    originRegistry: ProxyOriginRegistry;
+}
+/**
+ * Per-domain proxy for `keys.*` envelopes.
+ *
+ * Shape: `dispatch` routes napplet→shell requests into the runtime; `emit`
+ * pushes shell→napplet envelopes through the iframe's Window.
+ */
+interface KeysProxy {
+    /**
+     * Route a napplet-originated keys.* envelope (e.g. `keys.forward`,
+     * `keys.registerAction`) into the runtime.
+     *
+     * @param windowId - The source napplet's windowId
+     * @param envelope - The NIP-5D NappletMessage envelope
+     */
+    dispatch(windowId: string, envelope: NappletMessage): void;
+    /**
+     * Push a shell-initiated keys-domain envelope (e.g. `keys.action`,
+     * `keys.bindings`) into a napplet iframe.
+     *
+     * Paired with `keys-forwarder.ts`: the forwarder targets the DOM
+     * `keydown` → `keys.forward` path; this `emit` covers the complementary
+     * host-initiated pushes (binding updates, action triggers).
+     *
+     * No-op when the originRegistry cannot resolve the windowId (unknown or
+     * unregistered napplet). Never throws.
+     *
+     * @param windowId - The target napplet's windowId
+     * @param envelope - The NIP-5D NappletMessage envelope to deliver
+     */
+    emit(windowId: string, envelope: NappletMessage): void;
+}
+/**
+ * Factory for the canonical keys-domain proxy.
+ *
+ * @param deps - Runtime + origin registry
+ * @returns A {@link KeysProxy} ready to route keys.* envelopes
+ * @example
+ * ```ts
+ * import { createKeysProxy, originRegistry, createShellBridge } from '@kehto/shell';
+ *
+ * const bridge = createShellBridge(hooks);
+ * const keysProxy = createKeysProxy({
+ *   runtime: bridge.runtime,
+ *   originRegistry,
+ * });
+ *
+ * // Host-app-initiated action trigger:
+ * keysProxy.emit('win-editor', { type: 'keys.action', actionId: 'editor.save' });
+ * ```
+ */
+declare function createKeysProxy(deps: KeysProxyDeps): KeysProxy;
+
+/**
+ * media-proxy.ts — Shell-side per-domain proxy for media.* envelopes.
+ *
+ * Establishes the shell-side composition seam for `@napplet/nub-media`
+ * session-control envelopes. Shape mirrors identity-proxy (Plan 12-11):
+ *
+ *   - `dispatch(windowId, envelope)` routes napplet→shell media requests
+ *     (`media.session.create`, `media.session.update`, `media.session.destroy`,
+ *     `media.state`, `media.capabilities`) into the runtime (Plan 12-06).
+ *   - `emit(windowId, envelope)` posts shell→napplet pushes (`media.command`,
+ *     `media.controls`, `media.session.create.result`) through the origin
+ *     registry.
+ *
+ * By default `createShellBridge()` does NOT compose this proxy into its
+ * dispatch path — the runtime owns media.* dispatch. This module is an
+ * optional composition point for host apps (e.g. shell-rendered playback
+ * UIs that want to send `media.command` pushes).
+ */
+
+/**
+ * Dependencies for `createMediaProxy`.
+ *
+ * @example
+ * ```ts
+ * const proxy = createMediaProxy({
+ *   runtime: shellBridge.runtime,
+ *   originRegistry,
+ * });
+ * ```
+ */
+interface MediaProxyDeps {
+    /** The runtime engine that owns media.* dispatch (Plan 12-06). */
+    runtime: Runtime;
+    /** Origin registry for resolving windowId → iframe Window. */
+    originRegistry: ProxyOriginRegistry;
+}
+/**
+ * Per-domain proxy for `media.*` envelopes.
+ *
+ * Shape: `dispatch` routes napplet→shell requests into the runtime; `emit`
+ * pushes shell→napplet envelopes through the iframe's Window.
+ */
+interface MediaProxy {
+    /**
+     * Route a napplet-originated media.* envelope into the runtime.
+     *
+     * @param windowId - The source napplet's windowId
+     * @param envelope - The NIP-5D NappletMessage envelope
+     */
+    dispatch(windowId: string, envelope: NappletMessage): void;
+    /**
+     * Push a shell-initiated media-domain envelope (e.g. `media.command`,
+     * `media.controls`) into a napplet iframe.
+     *
+     * No-op when the originRegistry cannot resolve the windowId (unknown or
+     * unregistered napplet). Never throws.
+     *
+     * @param windowId - The target napplet's windowId
+     * @param envelope - The NIP-5D NappletMessage envelope to deliver
+     */
+    emit(windowId: string, envelope: NappletMessage): void;
+}
+/**
+ * Factory for the canonical media-domain proxy.
+ *
+ * @param deps - Runtime + origin registry
+ * @returns A {@link MediaProxy} ready to route media.* envelopes
+ * @example
+ * ```ts
+ * import { createMediaProxy, originRegistry, createShellBridge } from '@kehto/shell';
+ *
+ * const bridge = createShellBridge(hooks);
+ * const mediaProxy = createMediaProxy({
+ *   runtime: bridge.runtime,
+ *   originRegistry,
+ * });
+ *
+ * // Shell-UI-initiated media command:
+ * mediaProxy.emit('win-player', {
+ *   type: 'media.command',
+ *   sessionId: 's1',
+ *   action: 'seek',
+ *   value: 120,
+ * });
+ * ```
+ */
+declare function createMediaProxy(deps: MediaProxyDeps): MediaProxy;
+
+/**
+ * notify-proxy.ts — Shell-side per-domain proxy for notify.* envelopes.
+ *
+ * Establishes the shell-side composition seam for `@napplet/nub-notify`
+ * notification envelopes. Shape mirrors identity-proxy (Plan 12-11):
+ *
+ *   - `dispatch(windowId, envelope)` routes napplet→shell notify requests
+ *     (`notify.send`, `notify.dismiss`, `notify.badge`,
+ *     `notify.channel.register`, `notify.permission.request`) into the
+ *     runtime (Plan 12-07).
+ *   - `emit(windowId, envelope)` posts shell→napplet pushes
+ *     (`notify.send.result`, `notify.permission.result`, `notify.action`,
+ *     `notify.clicked`, `notify.dismissed`, `notify.controls`) through the
+ *     origin registry.
+ *
+ * By default `createShellBridge()` does NOT compose this proxy into its
+ * dispatch path — the runtime owns notify.* dispatch. This module is an
+ * optional composition point for host apps (e.g. custom notification UIs
+ * that need to emit `notify.clicked` / `notify.action` pushes).
+ */
+
+/**
+ * Dependencies for `createNotifyProxy`.
+ *
+ * @example
+ * ```ts
+ * const proxy = createNotifyProxy({
+ *   runtime: shellBridge.runtime,
+ *   originRegistry,
+ * });
+ * ```
+ */
+interface NotifyProxyDeps {
+    /** The runtime engine that owns notify.* dispatch (Plan 12-07). */
+    runtime: Runtime;
+    /** Origin registry for resolving windowId → iframe Window. */
+    originRegistry: ProxyOriginRegistry;
+}
+/**
+ * Per-domain proxy for `notify.*` envelopes.
+ *
+ * Shape: `dispatch` routes napplet→shell requests into the runtime; `emit`
+ * pushes shell→napplet envelopes through the iframe's Window.
+ */
+interface NotifyProxy {
+    /**
+     * Route a napplet-originated notify.* envelope into the runtime.
+     *
+     * @param windowId - The source napplet's windowId
+     * @param envelope - The NIP-5D NappletMessage envelope
+     */
+    dispatch(windowId: string, envelope: NappletMessage): void;
+    /**
+     * Push a shell-initiated notify-domain envelope (e.g. `notify.action`,
+     * `notify.clicked`) into a napplet iframe.
+     *
+     * No-op when the originRegistry cannot resolve the windowId (unknown or
+     * unregistered napplet). Never throws.
+     *
+     * @param windowId - The target napplet's windowId
+     * @param envelope - The NIP-5D NappletMessage envelope to deliver
+     */
+    emit(windowId: string, envelope: NappletMessage): void;
+}
+/**
+ * Factory for the canonical notify-domain proxy.
+ *
+ * @param deps - Runtime + origin registry
+ * @returns A {@link NotifyProxy} ready to route notify.* envelopes
+ * @example
+ * ```ts
+ * import { createNotifyProxy, originRegistry, createShellBridge } from '@kehto/shell';
+ *
+ * const bridge = createShellBridge(hooks);
+ * const notifyProxy = createNotifyProxy({
+ *   runtime: bridge.runtime,
+ *   originRegistry,
+ * });
+ *
+ * // Shell-UI notifies napplet that user clicked its toast:
+ * notifyProxy.emit('win-chat', {
+ *   type: 'notify.clicked',
+ *   notificationId: 'shell-42',
+ * });
+ * ```
+ */
+declare function createNotifyProxy(deps: NotifyProxyDeps): NotifyProxy;
+
+/**
+ * keys-forwarder.ts — Shell-side host keydown listener that forwards events
+ * to registered napplets as `keys.forward` envelopes (Plan 12-11, NUB-05
+ * shell-side half).
+ *
+ * Per `@napplet/nub-keys`, `keys.forward` is fire-and-forget (no result
+ * envelope, no correlation id). Field names follow the nub convention:
+ * `{ ctrl, alt, shift, meta }` — NOT the DOM-style `ctrlKey`/etc.
+ *
+ * Capability gate: only forwards to napplets whose ACL grants the
+ * `keys:forward` capability (per Plan 12-10 `resolveCapabilitiesNub` 'keys'
+ * case). The caller wires the cap-lookup via the `hasKeysForwardCap` dep so
+ * this module stays free of any direct ACL-store dependency.
+ *
+ * Lifecycle: `createShellBridge()` attaches a forwarder on construction and
+ * detaches it inside `bridge.destroy()`.
+ */
+
+/**
+ * Minimal origin-registry contract used by the forwarder — matches the
+ * `@kehto/shell` singleton `originRegistry` and test doubles alike.
+ */
+interface KeysForwarderOriginRegistry {
+    /** Resolve a registered napplet windowId to its iframe Window, or null. */
+    getIframeWindow(windowId: string): Window | null;
+}
+/**
+ * Minimal session-registry contract used by the forwarder — matches the
+ * `@kehto/shell` singleton `sessionRegistry` and test doubles alike.
+ */
+interface KeysForwarderSessionRegistry {
+    /** Return every registered napplet session entry. */
+    getAllEntries(): SessionEntry[];
+}
+/**
+ * Dependencies for `createKeysForwarder`.
+ *
+ * @example
+ * ```ts
+ * const forwarder = createKeysForwarder({
+ *   originRegistry,
+ *   sessionRegistry,
+ *   hasKeysForwardCap: (pubkey) =>
+ *     aclStore.getAclEntry(pubkey)?.capabilities.includes('keys:forward') ?? false,
+ * });
+ * ```
+ */
+interface KeysForwarderDeps {
+    /** Origin registry for resolving windowId → iframe Window. */
+    originRegistry: KeysForwarderOriginRegistry;
+    /** Session registry for enumerating napplets to forward to. */
+    sessionRegistry: KeysForwarderSessionRegistry;
+    /**
+     * Capability check: returns true when the given napplet pubkey holds the
+     * `keys:forward` capability. Called per keydown per registered napplet —
+     * keep the implementation cheap.
+     */
+    hasKeysForwardCap(pubkey: string): boolean;
+    /**
+     * Optional EventTarget to attach to. Defaults to the global `window` when
+     * running in a DOM environment. Passing a fresh `new EventTarget()` is
+     * useful for unit tests.
+     */
+    target?: EventTarget;
+}
+/**
+ * Handle returned by `createKeysForwarder`. Call `destroy()` to remove the
+ * keydown listener (e.g. inside `bridge.destroy()`).
+ */
+interface KeysForwarder {
+    /** Detach the keydown listener and release resources. */
+    destroy(): void;
+}
+/**
+ * Create a host-keydown forwarder that posts `keys.forward` envelopes to
+ * every registered napplet granted the `keys:forward` capability.
+ *
+ * @param deps - Origin registry, session registry, cap checker, optional target
+ * @returns A {@link KeysForwarder} — call `destroy()` to detach
+ * @example
+ * ```ts
+ * // Inside createShellBridge():
+ * const keysForwarder = createKeysForwarder({
+ *   originRegistry,
+ *   sessionRegistry,
+ *   hasKeysForwardCap: (pubkey) =>
+ *     aclStore.getAclEntry(pubkey)?.capabilities.includes('keys:forward') ?? false,
+ * });
+ * // ...
+ * // Inside bridge.destroy():
+ * keysForwarder.destroy();
+ * ```
+ */
+declare function createKeysForwarder(deps: KeysForwarderDeps): KeysForwarder;
+
+export { type AclCheckEvent, type AclEntry, type AudioSource, type AuthHooks, type BrowserDeps, type ConfigHooks, type CryptoHooks, type DmHooks, type HotkeyHooks, type IdentityProxy, type IdentityProxyDeps, type KeysForwarder, type KeysForwarderDeps, type KeysForwarderOriginRegistry, type KeysForwarderSessionRegistry, type KeysProxy, type KeysProxyDeps, type ManifestCacheEntry, type MediaProxy, type MediaProxyDeps, type NappKeyEntry, type NotifyProxy, type NotifyProxyDeps, type PendingUpdate, type ProxyOriginRegistry, type RelayConfigHooks, type RelayPoolHooks, type RelayPoolLike, type SessionEntry, type ShellAdapter, type ShellBridge, type ShellCapabilities, type ThemeProxy, type ThemeProxyDeps, type WindowManagerHooks, type WorkerRelayHooks, type WorkerRelayLike, adaptHooks, audioManager, buildShellCapabilities, createIdentityProxy, createKeysForwarder, createKeysProxy, createMediaProxy, createNotifyProxy, createShellBridge, createThemeProxy, manifestCache, nappKeyRegistry, originRegistry, sessionRegistry };