@kehto/shell 0.16.7 → 0.18.0

package/dist/index.d.ts

@@ -4,6 +4,38 @@ import { NappletMessage, NostrEvent, NostrFilter } from '@napplet/core';
 export { NappletMessage, NostrEvent, NostrFilter, TOPICS, TopicKey, TopicValue } from '@napplet/core';
 import { Theme } from '@napplet/nap/theme/types';
 
+/** NIP-5D identity metadata associated with a registered iframe window. */
+interface OriginIdentity {
+    readonly dTag: string;
+    readonly aggregateHash: string;
+}
+/**
+ * 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'
+ * ```
+ */
+interface OriginRegistry {
+    register(win: Window, windowId: string, identity?: OriginIdentity): void;
+    unregister(windowId: string): void;
+    getWindowId(win: Window): string | undefined;
+    getIframeWindow(windowId: string): Window | null;
+    getAllWindowIds(): string[];
+    getIdentity(win: Window): OriginIdentity | undefined;
+    setEnvironment(win: Window, environment: ShellEnvironment): void;
+    getEnvironment(win: Window): ShellEnvironment | undefined;
+    getRegistrationId(win: Window): number | undefined;
+    clear(): void;
+}
+/** Shell-wide iframe window registry singleton. */
+declare const originRegistry: OriginRegistry;
+
 /**
  * ACL entry controlling what a napplet pubkey is permitted to do.
  * @example
@@ -42,8 +74,13 @@ interface RelayPoolHooks {
     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;
+    /**
+     * Publish to a scoped relay.
+     *
+     * Async hosts settle the returned promise after transport acceptance.
+     * Returns false if no active scoped relay or publication fails.
+     */
+    publishToScopedRelay(windowId: string, event: NostrEvent): boolean | Promise<boolean>;
     /** Select relay URLs for a given set of filters. */
     selectRelayTier(filters: NostrFilter[]): string[];
 }
@@ -54,7 +91,7 @@ interface RelayPoolLike {
             unsubscribe(): void;
         };
     };
-    publish(relayUrls: string[], event: any): void;
+    publish(relayUrls: string[], event: any): void | Promise<void>;
     request(relayUrls: string[], filters: any): {
         subscribe(observer: {
             next: (event: unknown) => void;
@@ -205,8 +242,26 @@ interface WebrtcHooks {
  * environments while still using the production shell-ready path.
  */
 interface CapabilityHooks {
-    /** Bare capability domains to remove from domains, naps, and protocols. */
+    /** Bare capability domains to remove from the delivered environment. */
     readonly disabledDomains?: readonly string[];
+    /**
+     * Narrow the live environment for one trusted creation-time identity.
+     *
+     * The shell supplies copied, frozen live domains and named services. Returned
+     * names are intersected with that exact availability set, so this hook cannot
+     * add aliases, disabled entries, or unwired capabilities.
+     *
+     * @param identity - Identity assigned by the host when the iframe was created.
+     * @param available - Immutable live domains and services before host policy.
+     * @returns The requested subset for this identity.
+     */
+    readonly resolveEnvironment?: (identity: OriginIdentity, available: Readonly<{
+        domains: readonly string[];
+        services: readonly string[];
+    }>) => Readonly<{
+        domains: readonly string[];
+        services: readonly string[];
+    }>;
 }
 /**
  * Event emitted on every ACL enforcement check.
@@ -262,71 +317,21 @@ interface UnroutedMessageInfo {
 }
 /**
  * Static capability set sent to napplet iframes through the shell.ready /
- * shell.init handshake. The current runtime availability primitive is injected
- * `window.napplet.<domain>` presence; this shape remains for older consumers
- * that still read shell.init capability metadata.
- *
- * Current availability is the injected `window.napplet.<domain>` namespace.
- * Compatibility supports() helpers should treat only NAP domains and protocols
- * as advertised capabilities:
+ * shell.init handshake. Optional runtime domain presence is injected before
+ * authored code, while mandatory NAP-SHELL caches this environment for local
+ * capability queries.
  *
- *   - Bare names for NAP-capability lookups, resolved against the `naps`
- *     array — e.g. `supports('relay')`, `supports('identity')`.
- *
- * The sandbox array remains for older payload readers, but Kehto emits it empty.
- * NIP-5D no longer blesses additional browser sandbox tokens as interoperability
- * requirements or napplet-visible capabilities.
- *
- * ## Compatibility NAP-SHELL shape
- *
- * Older shell consumers may read the structured
- * `capabilities.{ domains: string[], protocols: Record<string, string[]> }`
- * alongside the flat `naps` array:
- *
- *   - `supports('relay')`       → true iff `'relay' ∈ capabilities.domains`
- *   - `supports('inc','NAP-01')`→ true iff `capabilities.protocols['inc']`
- *                                  includes `'NAP-01'`
- *
- * `domains` and `protocols` are emitted as a superset alongside the
- * `naps`/`sandbox` fields for back-compat.
+ * NAP-SHELL needs only a truthful set of bare domain names. The shim answers
+ * `shell.supports(domain)` locally from this snapshot after `shell.init`.
  */
 interface ShellCapabilities {
-    /**
-     * Compatibility NAP-SHELL domain list.
-     * Bare NAP domain names the shell offers — `'identity'`, `'storage'`,
-     * `'inc'`, `'theme'`, etc. — with the same conditional entries as `naps`
-     * (`relay`/`outbox` when a relay pool is wired, `upload`/`intent` under their
-     * hooks). Carries NO `inc:NAP-NN` protocol strings (those live in
-     * `protocols`).
-     */
-    domains: string[];
-    /**
-     * Compatibility NAP-SHELL per-domain numbered protocols. Maps a domain to the NAP-NN protocol IDs it
-     * speaks — `{ inc: ['NAP-01','NAP-02','NAP-03','NAP-04','NAP-05','NAP-06'] }`
-     * (derived from `NAP_INC_PROTOCOLS` by stripping the `inc:` prefix).
-     *
-     * Legacy supports helpers resolve `supports('<domain>','NAP-NN')` against this map.
-     */
-    protocols: Record<string, string[]>;
-    /**
-     * NAP-vocabulary domain entries the shell handles (PRIMARY — consumed by
-     * `@napplet/shim >=0.9.0`). Bare domain `inc` (the NAP rename of `inc`)
-     * plus protocol IDs `inc:NAP-01..inc:NAP-06`. Conditional entries:
-     * `relay`, `outbox` prepended when a relay pool is wired; `upload` appended
-     * when an upload backend is wired; `intent` appended when an intent
-     * dispatcher is available.
-     *
-     * Contains NO `NAP-NN` protocol strings (those live in `protocols`).
-     */
-    naps: string[];
-    /**
-     * Empty compatibility field for older `shell.init` payload consumers.
-     *
-     * Current NIP-5D keeps the web sandbox baseline narrow: hosted napplet iframes
-     * use `allow-scripts`, never `allow-same-origin`, and do not receive optional
-     * browser sandbox relaxations as advertised capabilities.
-     */
-    sandbox: string[];
+    /** Immutable bare domain names the shell offers to this napplet. */
+    readonly domains: readonly string[];
+}
+/** Immutable NAP-SHELL environment delivered to one trusted iframe session. */
+interface ShellEnvironment {
+    readonly capabilities: ShellCapabilities;
+    readonly services: readonly string[];
 }
 /**
  * All adapters that the shell requires from the host application.
@@ -532,18 +537,13 @@ interface ShellBridge {
      */
     registerConsentHandler(handler: (request: ConsentRequest) => void): void;
     /**
-     * Publish a theme update to every registered napplet.
+     * Publish a theme update to each eligible 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.
+     * live authenticated session whose frozen environment grants `theme` and
+     * whose current ACL grants `theme:read`. Stale or ineligible sessions are
+     * skipped before origin-registry delivery; recipient code is not trusted
+     * to enforce host authorization.
      *
      * @param theme - The new theme payload to broadcast.
      * @example
@@ -575,6 +575,14 @@ interface ShellBridge {
 }
 declare function createShellBridge(hooks: ShellAdapter): ShellBridge;
 
+/**
+ * The injected implementation must remain one self-contained function: the
+ * renderer serializes it ahead of verified artifact scripts without changing
+ * the signed artifact bytes. Splitting it into imported helpers would leave
+ * unresolved closures in the generated `srcdoc`.
+ *
+ * aislop-ignore-file complexity/file-too-large complexity/function-too-long
+ */
 /**
  * Options for rendering the host-owned NIP-5D `window.napplet` namespace prelude.
  *
@@ -587,7 +595,8 @@ declare function createShellBridge(hooks: ShellAdapter): ShellBridge;
  */
 interface NappletNamespacePreludeOptions {
     /**
-     * Bare NAP domain names the shell exposes to this napplet.
+     * Optional bare NAP domain names the shell exposes to this napplet.
+     * Mandatory `shell` is injected even when omitted here.
      */
     domains: readonly string[];
 }
@@ -621,77 +630,6 @@ declare function renderNappletNamespacePrelude(options: NappletNamespacePreludeO
  */
 declare function injectNappletNamespacePrelude(html: string, options: NappletNamespacePreludeOptions): string;
 
-/**
- * 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;
-    /**
-     * Look up the monotonically increasing registration id for a Window.
-     *
-     * @param win - The Window reference to look up
-     * @returns The registration id, or undefined if the Window is not registered
-     */
-    getRegistrationId(win: Window): number | undefined;
-    /** Clear all registrations. */
-    clear(): void;
-};
-
 /**
  * Manifest cache — persists verified NIP-5A aggregate hashes per napplet identity.
  */
@@ -723,44 +661,17 @@ interface ManifestCacheEntry {
  * 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
-     */
+interface ManifestCache {
     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;
-};
+}
+/** Shell-wide manifest verification cache singleton. */
+declare const manifestCache: ManifestCache;
 
 /**
  * ACL store — manages capability grants, revocations, and blocks for napp identities.
@@ -774,92 +685,22 @@ declare const manifestCache: {
  * 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
-     */
+interface AclStore {
     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;
-};
+}
+/** Shell ACL store singleton. */
+declare const aclStore: AclStore;
 
 /**
  * audio-manager.ts — Shell-side registry of active audio sources.
@@ -895,69 +736,22 @@ interface AudioSource {
  * 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
-     */
+interface AudioManager {
     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;
-};
+}
+/** Shell-wide audio source registry singleton. */
+declare const audioManager: AudioManager;
 
 /**
  * SessionRegistry — windowId to verified napplet pubkey bidirectional mapping.
@@ -978,149 +772,23 @@ declare const audioManager: {
  * 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
-     */
+interface SessionRegistry {
     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;
-};
+}
+/** Shell-wide verified napplet session registry singleton. */
+declare const sessionRegistry: SessionRegistry;
 /** @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;
-};
+declare const nappKeyRegistry: SessionRegistry;
 
 /**
  * hooks-adapter.ts — Converts ShellAdapter (browser-facing) to RuntimeAdapter (environment-agnostic).
@@ -1166,63 +834,36 @@ interface BrowserDeps {
 declare function adaptHooks(shellHooks: ShellAdapter, deps: BrowserDeps): RuntimeAdapter;
 
 /**
- * Build the shell's static capability set from adapter configuration.
- *
- * Returns the compatibility NAP-SHELL `domains`/`protocols` shape alongside
- * the flat `naps` array and the `sandbox` array. Current availability is
- * injected `window.napplet.<domain>` presence; this payload remains for older
- * consumers that still inspect shell.init capabilities.
- *
- * ### naps array (NAP vocabulary)
- * Bare domain `inc` + `inc:NAP-01..inc:NAP-06`.
- * Conditional: `relay`+`outbox` prepended when hooks.relayPool;
- * `upload` appended when hooks.upload;
- * `intent` appended when hooks.intent.isAvailable();
- * `link` appended when hooks.link.isAvailable();
- * `common` appended when hooks.common.isAvailable().
- *
- * The sandbox array is retained as an always-empty compatibility field. Current
- * NIP-5D defines only the `allow-scripts` baseline and does not make additional
- * browser sandbox tokens a napplet capability surface.
- *
- * ### domains array + protocols map (compatibility NAP-SHELL)
- * The structured shape older shell capability consumers read:
- *
- *   - `domains` — bare NAP domain names (the `naps` set MINUS the `inc:NAP-NN`
- *     protocol strings) with the same conditional entries (relay/outbox under
- *     `hooks.relayPool`, upload/intent/link/common under their hooks).
- *   - `protocols` — `{ inc: ['NAP-01'..'NAP-06'] }`, derived from
- *     `NAP_INC_PROTOCOLS` by stripping the `inc:` prefix.
- *
- * Emitted as a superset alongside `naps`/`sandbox` for back-compat.
- *
- * @param hooks - The ShellAdapter provided by the host app
- * @returns ShellCapabilities with domains/protocols (compatibility shape), naps
- *          (NAP vocab), and an empty sandbox compatibility array
+ * Build the shell's immutable live capability snapshot from adapter wiring.
+ *
+ * @param hooks - The ShellAdapter provided by the host app.
+ * @returns Domain-only ShellCapabilities for the current live wiring.
  * @example
  * ```ts
  * const caps = buildShellCapabilities(hooks);
- * // caps.domains => ['relay','outbox','identity','storage','inc','theme','keys','media','notify','config','resource','cvm']
- * //               (relay + outbox present when hooks.relayPool is provided; 'upload'/'intent'
- * //                appended under their hooks)
- * // caps.protocols => { inc: ['NAP-01','NAP-02','NAP-03','NAP-04','NAP-05','NAP-06'] }
- * // caps.naps => ['relay','outbox','identity','storage','inc','theme','keys','media','notify','config','resource','cvm',
- * //               'inc:NAP-01','inc:NAP-02','inc:NAP-03','inc:NAP-04','inc:NAP-05','inc:NAP-06']
- * //              (relay + outbox present when hooks.relayPool is provided; 'upload'
- * //               appended when hooks.upload is provided; 'intent' appended when
- * //               hooks.intent.isAvailable() is true)
- * // caps.sandbox => []   // retained for compatibility; not a NAP capability surface
+ * // caps.domains => ['relay', 'identity', 'storage', 'inc', 'theme', 'keys', 'media', 'notify']
  * ```
  */
 declare function buildShellCapabilities(hooks: ShellAdapter): ShellCapabilities;
+/**
+ * Resolve a trusted creation identity's immutable NAP-SHELL environment.
+ *
+ * This host-adapter API is intentionally not part of `window.napplet`: it
+ * bounds host policy to current runtime wiring before `shell.init` crosses into
+ * an untrusted iframe.
+ *
+ * @param hooks - Shell host wiring and optional per-identity grant policy.
+ * @param identity - The source's creation-time identity.
+ * @returns A fresh immutable environment whose entries are exact live subsets.
+ */
+declare function resolveShellEnvironment(hooks: ShellAdapter, identity: OriginIdentity): ShellEnvironment;
 
 /**
  * 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.
+ * requests to the runtime.
  *
  * By default, `createShellBridge()` does NOT compose this proxy into its
  * dispatch path — the runtime already owns identity.* dispatch per Plan
@@ -1231,10 +872,9 @@ declare function buildShellCapabilities(hooks: ShellAdapter): ShellCapabilities;
  * 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.
+ * Identity changes are deliberately not emitted through this proxy. Hosts
+ * must use `ShellBridge.publishIdentityChanged()`, which enforces the live
+ * session, granted-domain, and current recipient-capability checks.
  */
 
 /**
@@ -1267,9 +907,8 @@ interface IdentityProxyDeps {
 /**
  * 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.
+ * `dispatch` routes napplet→shell requests into the runtime. The deprecated
+ * `emit` member remains only as a fail-closed compatibility trap.
  */
 interface IdentityProxy {
     /**
@@ -1283,13 +922,10 @@ interface IdentityProxy {
      */
     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.
+     * Direct identity delivery is prohibited.
      *
-     * @param windowId - The target napplet's windowId
-     * @param envelope - The NIP-5D NappletMessage envelope to deliver
+     * @deprecated Use `ShellBridge.publishIdentityChanged()` so delivery is
+     * filtered by live session, granted domain, and current ACL.
      */
     emit(windowId: string, envelope: NappletMessage): void;
 }
@@ -1326,12 +962,9 @@ declare function createIdentityProxy(deps: IdentityProxyDeps): IdentityProxy;
  * 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.
+ * `dispatch(windowId, envelope)` routes napplet→shell `theme.get` into the
+ * runtime. Theme changes must use `ShellBridge.publishTheme()` so the host
+ * projection enforces live-session, granted-domain, and current-ACL checks.
  *
  * By default `createShellBridge()` does NOT compose this proxy into its
  * dispatch path — the runtime owns theme.* dispatch. This module is an
@@ -1358,8 +991,8 @@ interface ThemeProxyDeps {
 /**
  * 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.
+ * `dispatch` routes napplet→shell requests into the runtime. The deprecated
+ * `emit` member remains only as a fail-closed compatibility trap.
  */
 interface ThemeProxy {
     /**
@@ -1371,14 +1004,10 @@ interface ThemeProxy {
      */
     dispatch(windowId: string, envelope: NappletMessage): void;
     /**
-     * Push a shell-initiated theme-domain envelope (e.g. `theme.changed`)
-     * into a napplet iframe.
+     * Direct theme delivery is prohibited.
      *
-     * 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
+     * @deprecated Use `ShellBridge.publishTheme()` so delivery is filtered by
+     * live session, granted domain, and current ACL.
      */
     emit(windowId: string, envelope: NappletMessage): void;
 }
@@ -1389,18 +1018,13 @@ interface ThemeProxy {
  * @returns A {@link ThemeProxy} ready to route theme.* envelopes
  * @example
  * ```ts
- * import { createThemeProxy, originRegistry, createShellBridge } from '@kehto/shell';
+ * import { createThemeProxy, originRegistry } from '@kehto/shell';
  *
- * const bridge = createShellBridge(hooks);
  * const themeProxy = createThemeProxy({
- *   runtime: bridge.runtime,
+ *   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 });
- * }
+ * themeProxy.dispatch(windowId, { type: 'theme.get', id: requestId });
  * ```
  */
 declare function createThemeProxy(deps: ThemeProxyDeps): ThemeProxy;
@@ -1408,11 +1032,11 @@ 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.
+ * The runtime already dispatches napplet-originated `keys.*` (forward,
+ * registerAction, unregisterAction) to the keys service. This proxy is the
+ * shell-side composition point for host apps that want to observe requests or
+ * inject shell-originated keys envelopes such as `keys.action` and
+ * `keys.bindings`.
  *
  * Shape mirrors identity-proxy (Plan 12-11):
  *
@@ -1463,10 +1087,6 @@ interface KeysProxy {
      * 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.
      *
@@ -1672,101 +1292,6 @@ interface NotifyProxy {
  */
 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, NAP-05
- * shell-side half).
- *
- * Per `@napplet/nap/keys`, `keys.forward` is fire-and-forget (no result
- * envelope, no correlation id). Field names follow the nap 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 `resolveCapabilitiesNap` '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;
-
 /**
  * @file internal-resource.ts
  *
@@ -1938,4 +1463,4 @@ type ResourceInbound = ResourceInfoRequest | ResourceBytesRequest | ResourceByte
  */
 type ResourceOutbound = ResourceInfoResult | ResourceInfoError | ResourceBytesResult | ResourceBytesError | ResourceBytesManyResult | ResourceBytesManyError;
 
-export { type AclCheckEvent, type AclEntry, type AudioSource, type AuthHooks, type BleHooks, type BrowserDeps, type CapabilityHooks, type CommonHooks, type ConfigHooks, type CryptoHooks, type DmHooks, type HotkeyHooks, type IdentityProxy, type IdentityProxyDeps, type IntentHooks, type KeysForwarder, type KeysForwarderDeps, type KeysForwarderOriginRegistry, type KeysForwarderSessionRegistry, type KeysProxy, type KeysProxyDeps, type LinkHooks, type ListsHooks, type ManifestCacheEntry, type MediaProxy, type MediaProxyDeps, type NappletNamespacePreludeOptions, type NotifyProxy, type NotifyProxyDeps, type ProxyOriginRegistry, type RelayConfigHooks, type RelayPoolHooks, type RelayPoolLike, type ResourceBytesError, type ResourceBytesManyError, type ResourceBytesManyItem, type ResourceBytesManyRequest, type ResourceBytesManyResult, type ResourceBytesRequest, type ResourceBytesResult, type ResourceCancelRequest, type ResourceErrorCode, type ResourceInbound, type ResourceInfo, type ResourceInfoError, type ResourceInfoRequest, type ResourceInfoResult, type ResourceOutbound, type ResourceRequestId, type SerialHooks, type ShellAdapter, type ShellBridge, type ShellCapabilities, type ThemeProxy, type ThemeProxyDeps, type UnroutedMessageInfo, type UploadBackendLike, type UploadHooks, type WebrtcHooks, type WindowManagerHooks, type WorkerRelayHooks, type WorkerRelayLike, adaptHooks, audioManager, buildShellCapabilities, createIdentityProxy, createKeysForwarder, createKeysProxy, createMediaProxy, createNotifyProxy, createShellBridge, createThemeProxy, injectNappletNamespacePrelude, manifestCache, nappKeyRegistry, originRegistry, renderNappletNamespacePrelude, sessionRegistry };
+export { type AclCheckEvent, type AclEntry, type AclStore, type AudioManager, type AudioSource, type AuthHooks, type BleHooks, type BrowserDeps, type CapabilityHooks, type CommonHooks, type ConfigHooks, type CryptoHooks, type DmHooks, type HotkeyHooks, type IdentityProxy, type IdentityProxyDeps, type IntentHooks, type KeysProxy, type KeysProxyDeps, type LinkHooks, type ListsHooks, type ManifestCache, type ManifestCacheEntry, type MediaProxy, type MediaProxyDeps, type NappletNamespacePreludeOptions, type NotifyProxy, type NotifyProxyDeps, type OriginIdentity, type OriginRegistry, type ProxyOriginRegistry, type RelayConfigHooks, type RelayPoolHooks, type RelayPoolLike, type ResourceBytesError, type ResourceBytesManyError, type ResourceBytesManyItem, type ResourceBytesManyRequest, type ResourceBytesManyResult, type ResourceBytesRequest, type ResourceBytesResult, type ResourceCancelRequest, type ResourceErrorCode, type ResourceInbound, type ResourceInfo, type ResourceInfoError, type ResourceInfoRequest, type ResourceInfoResult, type ResourceOutbound, type ResourceRequestId, type SerialHooks, type SessionRegistry, type ShellAdapter, type ShellBridge, type ShellCapabilities, type ShellEnvironment, type ThemeProxy, type ThemeProxyDeps, type UnroutedMessageInfo, type UploadBackendLike, type UploadHooks, type WebrtcHooks, type WindowManagerHooks, type WorkerRelayHooks, type WorkerRelayLike, adaptHooks, audioManager, buildShellCapabilities, createIdentityProxy, createKeysProxy, createMediaProxy, createNotifyProxy, createShellBridge, createThemeProxy, injectNappletNamespacePrelude, manifestCache, nappKeyRegistry, originRegistry, renderNappletNamespacePrelude, resolveShellEnvironment, sessionRegistry };