@kehto/shell 0.17.2 → 0.19.0

package/README.md

@@ -12,6 +12,13 @@ Browser adapter over @kehto/runtime — ShellBridge and domain proxies.
 pnpm add @kehto/shell
 ```
 
+## Published Napplet Compatibility
+
+`@kehto/shell` publishes against `@napplet/core` and `@napplet/nap`
+`>=0.31.0 <0.32.0`. The installed core/nap 0.31.0 contracts are from source
+`7b675622e13870628ce174833d7b2a33cf32a0ab` and release
+`03ad65b66413e5798536ef48695ffc4c2508f2c3`.
+
 ## Overview
 
 `@kehto/shell` is the browser-specific integration layer for kehto. It wraps `@kehto/runtime` with the window/postMessage transport, localStorage persistence hooks, an audio manager, and the five canonical per-domain proxies defined by NIP-5D.
@@ -21,11 +28,62 @@ The primary entry point is `createShellBridge()` — it owns the postMessage lis
 Current draft behaviors this package enforces:
 
 - The shell does not inject a host-provided nostr object into napplets — NIP-5D explicitly forbids napplet-visible signing. Napplets call `relay.publish` / `relay.publishEncrypted` and the shell mediates the signing flow internally (NIP-44 default, NIP-04 opt-in for encrypted envelopes).
-- `injectNappletNamespacePrelude()` implements the NIP-5D injected-domain bootstrap and mandatory NAP-SHELL shim: hosts prepend it to `srcdoc` outside verified artifact bytes, install the parent-bound `shell.init` receiver, emit one `shell.ready`, and expose callable NAP interfaces before authored scripts run. Optional namespaces are filtered to the bare-domain allowlist; `shell` is always retained.
-- `window.napplet.shell.supports()` answers synchronously from the cached NAP-SHELL environment. Optional-domain presence remains the NIP-5D binding, while method semantics and numbered protocols remain owned by their matching NAP specs.
-- Five optional per-domain proxies — `createIdentityProxy`, `createThemeProxy`, `createKeysProxy`, `createMediaProxy`, `createNotifyProxy` — can be composed between napplet and runtime to intercept or augment traffic per NAP. They are NOT wired by default (Kehto's runtime already owns dispatch for the currently supported domains); they exist as host-app composition seams.
+- `injectNappletNamespacePrelude()` implements the NIP-5D injected-domain bootstrap and mandatory NAP-SHELL shim: hosts prepend it to `srcdoc` outside verified artifact bytes, install the parent-bound `shell.init` receiver, emit one `shell.ready`, and expose callable NAP interfaces before authored scripts run. Optional namespaces are filtered to the bare-domain allowlist; `shell` is always retained. Published core 0.31.0 and shim 0.29.0 omit generic mandatory shell, so Kehto retains this host-owned prelude under NAP-SHELL `5ac0490461ca6fec2f0d2e45b4835cf9bc08de24` until an upstream correction is reviewed.
+- `window.napplet.shell.supports(domain)` answers synchronously and locally from the cached first `shell.init` environment. It returns `false` before `shell.init`, for unknown values, and for domains that are not live and granted to that napplet; it never sends a support-query message.
+- Five optional per-domain proxies — `createIdentityProxy`, `createThemeProxy`, `createKeysProxy`, `createMediaProxy`, `createNotifyProxy` — can be composed between napplet and runtime to intercept request traffic per NAP. They are NOT wired by default. Identity/theme proxy `emit()` compatibility members fail closed; hosts must deliver automatic changes through `ShellBridge.publishIdentityChanged()` / `publishTheme()`, which enforce live session, granted domain, and current ACL.
 - `keys.forward` is napplet-to-shell only. Active napplets suppress locally-bound keys from `keys.bindings` before forwarding; shell-initiated action triggers use `keys.action`.
-- `buildShellCapabilities()` advertises `dm` when the host adapter provides `hooks.dm`, and disabled-domain overrides remove it from both `domains` and `naps`.
+- `buildShellCapabilities()` advertises only live domains (including `dm` when the host adapter provides `hooks.dm`); disabled domains are absent from the delivered `domains` and named services snapshots.
+
+### NAP-INC binding and channel contract
+
+The injected INC binding follows merged
+[`naps/NAP-INC.md`](https://github.com/napplet/naps/blob/5ac0490461ca6fec2f0d2e45b4835cf9bc08de24/naps/NAP-INC.md)
+on `napplet/naps` master
+`5ac0490461ca6fec2f0d2e45b4835cf9bc08de24`. The specification remains marked
+draft, but its merged path is the protocol authority.
+
+The released package projection and `window.napplet.inc` binding own
+query-to-text-payload
+transposition: it converts a convention URI query before emitting a stable,
+exact queryless topic identity. Subscriptions reject query-bearing identities.
+The binding never creates a normalized query-bearing wire/discovery identity,
+does not do prefix/wildcard/query-aware matching or service-over-INC prefix
+dispatch, and does not infer payload kinds. Runtime delivery supplies the
+**runtime-attested dTag**; no caller sender is accepted, topic source exclusion
+is runtime-owned, and IDs and payloads are opaque.
+
+Merged NAP-INC and released `@napplet/nap@0.31.0` both deliver one `IncEvent`
+to `on(topic, callback)`.
+
+For channels, runtime ACL checks are open-only rather than per-message. The
+target `inc.channel.opened` before the opener result creates an equivalent target
+handle; `channel.onOpened` exposes it, while symmetric handles expose `on` and
+`onClosed`. The binding retains inbound, early, and terminal lifecycle state in
+order, closes on bounded overflow, and treats teardown as deterministic.
+`channel.list()` is informational only. The downstream tracker is
+[`kehto/web#203`](https://github.com/kehto/web/issues/203), with its [upstream
+resolution reply](https://github.com/kehto/web/issues/203#issuecomment-5060904495);
+the prior opener-only interpretation is obsolete.
+
+### NAP-INTENT binding and delivery
+
+Kehto implements merged [NAP-INTENT at
+`5ac0490461ca6fec2f0d2e45b4835cf9bc08de24`](https://github.com/napplet/naps/blob/5ac0490461ca6fec2f0d2e45b4835cf9bc08de24/naps/NAP-INTENT.md).
+The protected `window.napplet.intent` binding accepts structured
+`invoke(request)` calls and `open(archetype, payload?, opts?)`. It defaults
+`action` to `open`, preserves an optional queryless convention, rejects
+unsupported fields and caller-supplied sender data, and resolves only
+parent-originated correlated results.
+
+Successful results include `handled`, `handler`, `windowId`, and `convention`
+after target dispatch completes. There is no `intent.deliver` or `onDelivery`;
+selected targets consume their convention through the ordinary
+runtime-attested INC binding.
+
+Phase 105 completed released `@napplet/*` package adoption and persistent live
+Paja/playground catalogs and target controllers. The Phase 104 Paja simulator
+and playground catalog builder are historical exact-contract consumers; preserve
+archived planning rather than presenting it as active guidance.
 
 ## Quick Start
 
@@ -41,7 +99,7 @@ const bridge = createShellBridge({
 
 // Register a reference service against the underlying runtime.
 bridge.runtime.registerService(
-  'notifications',
+  'notify',
   createNotificationService({ onChange: updateBadge }),
 );
 ```
@@ -68,15 +126,36 @@ const bridge = createShellBridge({
 ```
 
 ### Shell init
-- `buildShellCapabilities` — construct the current draft `ShellCapabilities` payload emitted during the `shell.ready` / `shell.init` handshake
+- `buildShellCapabilities` — construct the immutable domain-only `ShellCapabilities` payload emitted during the `shell.ready` / `shell.init` handshake
+- `resolveShellEnvironment(hooks, identity)` — host-integrator-only utility that narrows the live environment for a trusted creation-time identity before `shell.init`; it is not installed on `window.napplet` and is not a shim-facing napplet API
 - `injectNappletNamespacePrelude` — insert a host-owned NIP-5D `window.napplet` callable-domain prelude into verified HTML before authored scripts
 - `renderNappletNamespacePrelude` — render only the bootstrap `<script>` for hosts that already own HTML insertion
 
 ### Domain proxies (NIP-5D composition seams)
-- `createIdentityProxy` — intercept `identity.getProfile/getFollows/...` traffic
-- `createThemeProxy` — intercept `theme.get/theme.changed`
+- `createIdentityProxy` — intercept identity read requests; direct `emit()` is prohibited
+- `createThemeProxy` — intercept `theme.get`; direct `emit()` is prohibited
 - `createKeysProxy` — intercept `keys.bind/unbind/bindings`
 - `createMediaProxy` — intercept `media.*` playback control
+
+### Protected identity and theme delivery
+
+The injected identity/theme bindings follow NAP-IDENTITY and NAP-THEME at
+`napplet/naps` master `5ac0490461ca6fec2f0d2e45b4835cf9bc08de24`.
+They are readonly protected objects: identity exposes supported reads and
+`onChanged`, while theme exposes `get` and `onChanged` only. Results and
+automatic changes are accepted only when their `MessageEvent.source` is
+`window.parent`; direct-domain and whole-namespace assignment cannot replace
+the canonical operations.
+
+`ShellBridge` delivers `identity.changed` and `theme.changed` exactly once per
+eligible recipient: a live authenticated `shell.ready` session, its frozen
+environment includes the relevant domain, and its current recipient read
+capability is still granted. Identity sign-out is `pubkey: ""`. Theme updates
+arrive only after the service has stored the complete color state. These are
+automatic change messages, not NAP-INC/intent delivery and not a subscription
+protocol. Kehto's denied/unavailable theme read policy is a complete fixed
+normal result without `error`, deliberately avoiding a mixed theme/error
+payload.
 - `createNotifyProxy` — intercept `notify.send/list/read/dismiss`
 
 ### Session / origin registry
@@ -98,7 +177,13 @@ const bridge = createShellBridge({
 - `TopicKey`, `TopicValue` — typed topic lookup helpers
 
 ### Types
-Exported for host-app integration: `ShellAdapter`, `ShellCapabilities`, `RelayPoolHooks`, `RelayPoolLike`, `RelayConfigHooks`, `WindowManagerHooks`, `AuthHooks`, `ConfigHooks`, `HotkeyHooks`, `WorkerRelayHooks`, `WorkerRelayLike`, `CryptoHooks`, `DmHooks`, `UploadHooks`, `IntentHooks`, `LinkHooks`, `CommonHooks`, `ListsHooks`, `SerialHooks`, `BleHooks`, `WebrtcHooks`, `SessionEntry`, `NappKeyEntry` (deprecated), `AclEntry`, `AclCheckEvent`, `UnroutedMessageInfo`, `ServiceDescriptor`, `ServiceHandler`, `ServiceRegistry`, `NostrEvent`, `NostrFilter`, `NappletMessage`, `ConsentRequest`, and per-proxy `*Deps`/`*Proxy` interfaces.
+Exported for host-app integration: `ShellAdapter`, `ShellCapabilities`, `CapabilityHooks`, `OriginIdentity`, `RelayPoolHooks`, `RelayPoolLike`, `RelayConfigHooks`, `WindowManagerHooks`, `AuthHooks`, `ConfigHooks`, `HotkeyHooks`, `WorkerRelayHooks`, `WorkerRelayLike`, `CryptoHooks`, `DmHooks`, `UploadHooks`, `IntentHooks`, `LinkHooks`, `CommonHooks`, `ListsHooks`, `SerialHooks`, `BleHooks`, `WebrtcHooks`, `SessionEntry`, `NappKeyEntry` (deprecated), `AclEntry`, `AclCheckEvent`, `UnroutedMessageInfo`, `ServiceDescriptor`, `ServiceHandler`, `ServiceRegistry`, `NostrEvent`, `NostrFilter`, `NappletMessage`, `ConsentRequest`, and per-proxy `*Deps`/`*Proxy` interfaces.
+
+`RelayPoolLike.publish()` may return `Promise<void>` when transport acceptance
+is asynchronous. The shell adapter forwards that promise so the runtime does
+not acknowledge or buffer an event before the relay operation settles.
+`RelayPoolHooks.publishToScopedRelay()` may likewise return
+`Promise<boolean>` so asynchronous hosts report the settled outcome.
 
 ### Enforcement re-exports (from @kehto/runtime)
 `createEnforceGate`, `createNapEnforceGate`, `formatDenialReason`, plus `EnforceResult`, `EnforceConfig`, `NapEnforceConfig`, `IdentityResolver`, `AclChecker`, `NapMessage`.

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.
@@ -266,67 +321,17 @@ interface UnroutedMessageInfo {
  * authored code, while mandatory NAP-SHELL caches this environment for local
  * capability queries.
  *
- * Current availability is the injected `window.napplet.<domain>` namespace.
- * NAP-SHELL supports() treats only NAP domains and protocols as advertised
- * capabilities:
- *
- *   - 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.
- *
- * ## NAP-SHELL shape
- *
- * The shell shim reads 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 {
-    /**
-     * 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[];
-    /**
-     * 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).
-     *
-     * Local 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
@@ -630,36 +630,6 @@ declare function renderNappletNamespacePrelude(options: NappletNamespacePreludeO
  */
 declare function injectNappletNamespacePrelude(html: string, options: NappletNamespacePreludeOptions): string;
 
-/** 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;
-    getRegistrationId(win: Window): number | undefined;
-    clear(): void;
-}
-/** Shell-wide iframe window registry singleton. */
-declare const originRegistry: OriginRegistry;
-
 /**
  * Manifest cache — persists verified NIP-5A aggregate hashes per napplet identity.
  */
@@ -864,61 +834,36 @@ interface BrowserDeps {
 declare function adaptHooks(shellHooks: ShellAdapter, deps: BrowserDeps): RuntimeAdapter;
 
 /**
- * Build the shell's static capability set from adapter configuration.
- *
- * Returns the NAP-SHELL `domains`/`protocols` environment used by local
- * `window.napplet.shell.supports()` queries. Flat `naps` and empty `sandbox`
- * fields remain alongside it for older payload readers.
- *
- * ### 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 (NAP-SHELL)
- * The structured environment delivered to the mandatory shell shim:
- *
- *   - `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.
- *
- * `naps`/`sandbox` are emitted as compatibility fields alongside this shape.
+ * Build the shell's immutable live capability snapshot from adapter wiring.
  *
- * @param hooks - The ShellAdapter provided by the host app
- * @returns ShellCapabilities with normative local-query data plus legacy fields
+ * @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
@@ -927,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.
  */
 
 /**
@@ -963,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 {
     /**
@@ -979,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;
 }
@@ -1022,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
@@ -1054,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 {
     /**
@@ -1067,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.
-     *
-     * No-op when the originRegistry cannot resolve the windowId (unknown or
-     * unregistered napplet). Never throws.
+     * Direct theme delivery is prohibited.
      *
-     * @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;
 }
@@ -1085,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;
@@ -1535,4 +1463,4 @@ type ResourceInbound = ResourceInfoRequest | ResourceBytesRequest | ResourceByte
  */
 type ResourceOutbound = ResourceInfoResult | ResourceInfoError | ResourceBytesResult | ResourceBytesError | ResourceBytesManyResult | ResourceBytesManyError;
 
-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 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, 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 };