@kehto/services 0.2.0 → 0.6.0

package/dist/index.d.ts

@@ -1,7 +1,11 @@
 import { ServiceHandler, Signer } from '@kehto/runtime';
-import { NostrFilter, NostrEvent } from '@napplet/core';
-import { NotifySendMessage } from '@napplet/nub-notify';
-import { Theme, ThemeChangedMessage } from '@napplet/nub-theme';
+import { NostrEvent, NappletMessage, NostrFilter, EventTemplate } from '@napplet/core';
+import { MediaMetadata, MediaAction } from '@napplet/nub/media/types';
+export { MediaAction } from '@napplet/nub/media/types';
+import { NotifySendMessage } from '@napplet/nub/notify/types';
+import { Theme, ThemeChangedMessage } from '@napplet/nub/theme/types';
+import { ConfigSchemaErrorCode, ConfigValues, NappletConfigSchema } from '@napplet/nub/config/types';
+export { a as CvmCloseMessage, b as CvmCloseResultMessage, c as CvmDiscoverMessage, d as CvmDiscoverQuery, e as CvmDiscoverResultMessage, f as CvmEventMessage, g as CvmInboundMessage, h as CvmOutboundMessage, i as CvmRequestMessage, j as CvmRequestOptions, k as CvmRequestResultMessage, l as CvmServer, m as CvmServerRef, n as CvmService, o as CvmServiceOptions, C as CvmTransport, p as CvmTransportError, M as McpContentBlock, q as McpMessage, r as McpTool, s as McpToolResult, t as createCvmService } from './cvm-service-CXcOVQ0m.js';
 
 /**
  * @kehto/services — Shared types for reference service implementations.
@@ -138,15 +142,6 @@ interface NotificationServiceOptions {
  */
 declare function createAudioService(options?: AudioServiceOptions): ServiceHandler;
 
-/**
- * notification-service.ts — Notification state registry as a ServiceHandler.
- *
- * Tracks notifications created by napplet windows. Shell hosts wire this
- * into the runtime via registerService('notifications', createNotificationService(opts)).
- * The shell host decides presentation (toast, badge, OS notification, etc.)
- * through the onChange callback. Browser-agnostic — no DOM, no window.
- */
-
 /**
  * Create a notification service handler.
  *
@@ -186,17 +181,53 @@ declare function createNotificationService(options?: NotificationServiceOptions)
  *   - signer.nip04.encrypt/decrypt -> DELETED
  *   - signer.nip44.encrypt/decrypt -> DELETED (shell encrypts internally
  *                                      inside relay.publishEncrypted)
+ *   - identity.decrypt -> ADDED in v1.8 as a shell-mediated decrypt request
+ *                         with class gate + typed error union.
  *
  * See REQUIREMENTS.md DEPS-03 (Phase 15 changelog).
  *
- * Handles 9 identity.* request types from @napplet/nub-identity. getPublicKey
+ * Handles 10 identity.* request types from @napplet/nub/identity. getPublicKey
  * and getRelays return real values sourced from hooks.auth.getSigner(); the
  * remaining 7 (getProfile/getFollows/getList/getZaps/getMutes/getBlocked/
- * getBadges) are stub-level — each returns an empty default payload with the
- * spec-correct envelope shape. Host apps plug real backends via
- * runtime.registerService('identity', realHandler).
+ * getBadges) are stub-level; decrypt delegates to a host-supplied bridge.
+ * Host apps plug real backends via runtime.registerService('identity', realHandler).
  */
 
+type IdentityDecryptErrorCode = 'class-forbidden' | 'signer-denied' | 'signer-unavailable' | 'decrypt-failed' | 'malformed-wrap' | 'impersonation' | 'unsupported-encryption' | 'policy-denied';
+interface Rumor {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+}
+interface IdentityDecryptMessage extends NappletMessage {
+    type: 'identity.decrypt';
+    id: string;
+    event: NostrEvent;
+}
+interface IdentityDecryptResultMessage extends NappletMessage {
+    type: 'identity.decrypt.result';
+    id: string;
+    rumor: Rumor;
+    sender: string;
+}
+interface IdentityDecryptErrorMessage extends NappletMessage {
+    type: 'identity.decrypt.error';
+    id: string;
+    error: IdentityDecryptErrorCode;
+}
+interface GiftWrapDecryptResult {
+    seal: NostrEvent;
+    rumor: Rumor;
+}
+interface HostDecryptBridge {
+    nip04Decrypt(senderPubkey: string, ciphertext: string): Promise<string>;
+    nip44Decrypt(senderPubkey: string, ciphertext: string): Promise<string>;
+    unwrapGiftWrap(wrap: NostrEvent): Promise<GiftWrapDecryptResult>;
+}
+type VerifyEvent = (event: NostrEvent) => boolean | Promise<boolean>;
 /**
  * Options for creating the identity service.
  *
@@ -215,14 +246,27 @@ interface IdentityServiceOptions {
      * availability can change dynamically.
      */
     getSigner: () => Signer | null;
+    /**
+     * Return the host decrypt bridge. Called only after outer event signature
+     * verification and encryption-mode detection succeed. Null means decrypt is
+     * unavailable while the rest of the identity service remains usable.
+     */
+    getDecryptor?: () => HostDecryptBridge | null;
+    /**
+     * Verify a received event before any decrypt attempt. Host shells should
+     * wire this to their canonical Nostr event verifier; tests and old hosts
+     * default to true for backward compatibility with the 9 read-only actions.
+     */
+    verifyEvent?: VerifyEvent;
 }
 /**
  * Create an identity service that handles NIP-5D identity.* envelope messages.
  *
- * Supports all 9 identity.* request types from @napplet/nub-identity. The two
+ * Supports all 10 identity.* request types from @napplet/nub/identity. The two
  * read-only nostr-info queries (getPublicKey, getRelays) resolve through the
  * caller-supplied signer; the remaining 7 return default/empty payloads with
  * spec-correct envelope shapes so napplets always receive a result envelope.
+ * identity.decrypt delegates to the host decrypt bridge.
  *
  * @param options - Identity service configuration (getSigner)
  * @returns A ServiceHandler ready for runtime.registerService('identity', handler)
@@ -328,15 +372,6 @@ interface RelayPoolServiceOptions {
  */
 declare function createRelayPoolService(options: RelayPoolServiceOptions): ServiceHandler;
 
-/**
- * cache-service.ts — Local event cache as a ServiceHandler.
- *
- * Wraps an existing cache implementation (query, store, isAvailable)
- * as a ServiceHandler that receives relay NUB envelope messages. Cache
- * subscriptions are one-shot queries — relay.subscribe triggers a query
- * and immediate EOSE, unlike relay pool subscriptions which stay open.
- */
-
 /**
  * Options for creating a cache service.
  *
@@ -370,6 +405,31 @@ interface CacheServiceOptions {
      */
     isAvailable(): boolean;
 }
+/**
+ * @kehto/services cross-package naming-parity alias for {@link CacheServiceOptions}.
+ *
+ * `HostCacheBridge` matches the v1.4 `HostKeysBridge` / `HostMediaBridge`
+ * convention — it is a pure type alias for `CacheServiceOptions`, NOT a new
+ * type. Existing consumers of `CacheServiceOptions` continue to work
+ * unchanged; new consumers may prefer `HostCacheBridge` for consistency
+ * with the other Host*Bridge names in `@kehto/services`.
+ *
+ * Anti-feature note (PITFALLS.md M-02): `CacheServiceOptions` MUST remain
+ * the primary export. This alias is additive; do not rename or delete
+ * `CacheServiceOptions` when other Host*Bridge names eventually
+ * stabilize.
+ *
+ * @example
+ * ```ts
+ * import type { HostCacheBridge } from '@kehto/services';
+ * const cache: HostCacheBridge = {
+ *   query: (filters) => myIndexedDB.query(filters),
+ *   store: (event) => myIndexedDB.store(event),
+ *   isAvailable: () => true,
+ * };
+ * ```
+ */
+type HostCacheBridge = CacheServiceOptions;
 /**
  * Create a cache service that wraps an existing cache implementation
  * as a ServiceHandler.
@@ -395,17 +455,6 @@ interface CacheServiceOptions {
  */
 declare function createCacheService(options: CacheServiceOptions): ServiceHandler;
 
-/**
- * coordinated-relay.ts — Composite relay + cache ServiceHandler.
- *
- * Combines relay pool and cache into a single service that handles
- * relay.subscribe by querying both sources, deduplicating events by ID,
- * and sending a unified EOSE after both sources complete.
- *
- * This is a convenience helper for shell implementors. Those who need
- * custom coordination can write their own composite service.
- */
-
 /**
  * Options for creating a coordinated relay service.
  *
@@ -468,27 +517,126 @@ interface CoordinatedRelayOptions {
 declare function createCoordinatedRelay(options: CoordinatedRelayOptions): ServiceHandler;
 
 /**
- * keys-service.ts — NIP-5D keys NUB reference service (stub-level).
+ * keys-service.ts — NIP-5D keys NUB reference document-level listener implementation.
  *
- * Handles the 3 napplet -> shell request types from @napplet/nub-keys:
+ * Handles the 3 napplet -> shell request types from @napplet/nub/keys:
  *   - keys.forward          -> invokes options.onForward (hotkey passthrough, fire-and-forget)
- *   - keys.registerAction   -> echoes { actionId, binding: action.defaultKey? } as .result
- *   - keys.unregisterAction -> fire-and-forget (no envelope)
- *
- * Stub-level: no real keyboard listener, no binding persistence. Host apps
- * wire a real backend via runtime.registerService('keys', realHandler).
- *
- * Field-name translation: @napplet/nub-keys uses the compact
+ *   - keys.registerAction   -> parses action.defaultKey into a chord spec, stores the
+ *                              subscription in an in-memory registry keyed by actionId,
+ *                              tracks windowId ownership so onWindowDestroyed can auto-
+ *                              unsubscribe, and echoes { actionId, binding } as .result
+ *   - keys.unregisterAction -> removes the subscription; fire-and-forget (no envelope)
+ *
+ * Real listener: on service construction the handler attaches a single
+ * `keydown` listener to `options.listenerTarget` (default: `document`). Each
+ * keydown is matched against the chord-subscription registry; matches invoke
+ * `options.onForward` with the DOM-shape payload AND push a canonical
+ * `keys.action` envelope back to the owning napplet via the per-window `send`
+ * callback captured at `keys.registerAction` time. Subscriptions persist
+ * across messages; `onWindowDestroyed(windowId)` drops all subscriptions owned
+ * by the destroyed window as well as its cached `send` handle.
+ *
+ * On each document keydown matching a registered action, the service
+ * additionally emits a `keys.action` envelope to the action's owning napplet
+ * via the per-window `send` callback — this is the canonical @napplet/nub/keys
+ * surface the SDK's `keys.onAction(...)` helper consumes. The shape is a
+ * superset of `KeysActionMessage`: `{ type, actionId, chord }` where `chord`
+ * is the parsed `{ ctrl, alt, shift, meta, key }` struct (extension field;
+ * base shape unchanged, downstream SDKs that only read `{ type, actionId }`
+ * ignore `chord` silently).
+ *
+ * Field-name translation: @napplet/nub/keys uses the compact
  * { ctrl, alt, shift, meta } form on the wire; the shell's HotkeyHooks
  * (packages/shell/src/types.ts) expects the DOM-compatible
  * { ctrlKey, altKey, shiftKey, metaKey } form. This service performs the
  * translation so callers of `onForward` see the DOM shape.
  *
- * Shell -> napplet push envelopes (`keys.bindings`, `keys.action`) are
- * NOT emitted by this service — they are the shell-side keys forwarder's
- * responsibility (DRIFT-SHELL-06, tracked under Plan 12-11 / future phase).
+ * Shell -> napplet push envelopes `keys.bindings` remain the shell-side keys
+ * forwarder's responsibility (DRIFT-SHELL-06, tracked under Plan 12-11 /
+ * future phase); `keys.action` is emitted here per Plan 26-01.
  */
 
+/**
+ * Minimal structural subset of the DOM `KeyboardEvent` exposed to
+ * `HostKeysBridge` subscribe callbacks. DOM `KeyboardEvent` satisfies this
+ * structurally with no adapter needed. OS-bridge impls (Electron, Tauri —
+ * out of v1.4 scope) synthesize this from native key events.
+ */
+interface HostKeyEvent {
+    key: string;
+    code: string;
+    ctrlKey: boolean;
+    altKey: boolean;
+    shiftKey: boolean;
+    metaKey: boolean;
+    /** True for OS autorepeat; the service filters these by default. */
+    repeat?: boolean;
+}
+/**
+ * Host-bridge contract for pluggable keyboard backends.
+ *
+ * The browser reference implementation (the default {@link createKeysService}
+ * behaviour when `hostBridge` is omitted) registers a `document`-level keydown
+ * listener and satisfies this interface structurally — it exposes
+ * `subscribe(chord, callback) => unsubscribe` semantics but omits the two
+ * OS-level optional fields (browsers cannot register global hotkeys without
+ * privileged APIs).
+ *
+ * Host apps (Electron, Tauri) implement this interface in their own code and
+ * pass it via `createKeysService({ hostBridge: myBridge })` — the service
+ * then delegates subscription lifecycle to the bridge and remains browser-free.
+ *
+ * Reference implementations for Electron / Tauri are explicitly out of v1.4
+ * scope and live in host-app examples / follow-up milestones (see
+ * REQUIREMENTS.md "Future Requirements").
+ *
+ * @example
+ * ```ts
+ * // Host-app pseudocode (Electron main-process relay):
+ * const electronBridge: HostKeysBridge = {
+ *   subscribe(chord, cb) {
+ *     const handle = globalShortcut.register(chord, () => cb({ key: '', code: '', ctrlKey: false, altKey: false, shiftKey: false, metaKey: false }));
+ *     return () => globalShortcut.unregister(chord);
+ *   },
+ *   registerGlobalHotkey: (chord) => globalShortcut.register(chord, () => {}),
+ *   onGlobalHotkey: (cb) => globalHotkeyBridge.on('global-hotkey', (_, chord) => cb(chord)),
+ * };
+ *
+ * const keys = createKeysService({ hostBridge: electronBridge });
+ * runtime.registerService('keys', keys);
+ * ```
+ */
+interface HostKeysBridge {
+    /**
+     * Subscribe a callback to a chord. Returns an unsubscribe handle.
+     *
+     * Implementations MUST:
+     *   - invoke `callback` exactly once per matching chord event (implementations
+     *     are responsible for any OS-autorepeat filtering)
+     *   - invoke `callback` synchronously during the event delivery
+     *   - accept the string chord format documented by @napplet/nub/keys
+     *     (e.g. `'Ctrl+Shift+K'`, `'Cmd+P'`)
+     */
+    subscribe(chord: string, callback: (event: KeyboardEvent | HostKeyEvent) => void): () => void;
+    /**
+     * Optional: register an OS-level global hotkey (works even when the host
+     * window is not focused). Returns true on success, false if the chord
+     * cannot be registered (e.g. already claimed by another app).
+     *
+     * Omitted by the browser reference implementation — browsers cannot
+     * register OS-level global hotkeys without privileged APIs. Electron
+     * (`globalShortcut`) and Tauri (`GlobalShortcut`) provide this.
+     */
+    registerGlobalHotkey?(chord: string): boolean;
+    /**
+     * Optional: subscribe to OS-level global hotkey events (regardless of
+     * focus). Returns an unsubscribe handle.
+     *
+     * Omitted by the browser reference implementation. See
+     * {@link HostKeysBridge.registerGlobalHotkey}.
+     */
+    onGlobalHotkey?(callback: (chord: string) => void): () => void;
+}
 /**
  * Options for creating a keys service via createKeysService().
  *
@@ -504,7 +652,8 @@ declare function createCoordinatedRelay(options: CoordinatedRelayOptions): Servi
  */
 interface KeysServiceOptions {
     /**
-     * Called on keys.forward. Receives the DOM-style field names
+     * Called on `keys.forward` (napplet-forwarded chord) AND on document keydown
+     * matching a registered action. Receives the DOM-style field names
      * (ctrlKey/altKey/shiftKey/metaKey) to match the shell's HotkeyHooks
      * contract. The service translates from the wire shape
      * ({ ctrl, alt, shift, meta }) before invoking this callback.
@@ -517,17 +666,62 @@ interface KeysServiceOptions {
         shiftKey: boolean;
         metaKey: boolean;
     }) => void;
+    /**
+     * EventTarget to attach the default keydown listener to. Defaults to the
+     * global `document` when running in a DOM environment, else an isolated
+     * `new EventTarget()` (SSR / Node-test safe). Passing a fresh
+     * `new EventTarget()` is useful for unit tests. Mirrors the pattern used
+     * by `@kehto/shell`'s `createKeysForwarder`.
+     *
+     * Ignored when `hostBridge` is provided — the bridge owns subscription
+     * lifecycle and no document listener is attached.
+     */
+    listenerTarget?: EventTarget;
+    /**
+     * Optional pluggable backend for chord subscription. When provided, the
+     * service delegates `keys.registerAction` → `bridge.subscribe(chord, cb)`
+     * and stores the returned unsubscribe handle keyed on `actionId`. The
+     * default document-listener path is NOT attached when `hostBridge` is
+     * provided — the bridge is authoritative. See {@link HostKeysBridge}.
+     */
+    hostBridge?: HostKeysBridge;
+    /**
+     * Optional set of shell-reserved chords. Strings in the `@napplet/nub/keys`
+     * wire format (e.g. `'Ctrl+Shift+K'`, `'Cmd+P'`). When a napplet sends
+     * `keys.forward` with a chord matching this set — or when a document
+     * keydown matches a reserved chord — the service invokes `onForward`
+     * (or the `hostBridge`-registered handler) but suppresses the
+     * `keys.action` push to any napplet that registered the same chord via
+     * `keys.registerAction`. Precedence: reserved > registered. The shell
+     * WANTS the forward — that is why it reserved the chord.
+     *
+     * Normalized once at service construction via the same chord parser used
+     * for `action.defaultKey` — `'Ctrl+K'` / `'Control+k'` / `'ctrl+K'` all
+     * match. Static; no runtime mutation. For dynamic reservation see the
+     * deferred `HostKeysBridge.reserveAbsolute(chords)` extension.
+     *
+     * @example
+     * ```ts
+     * const keys = createKeysService({
+     *   reservedChords: ['Ctrl+Alt+T', 'Super+Space'],
+     *   onForward: (event) => wm.dispatch(event),
+     * });
+     * ```
+     */
+    reservedChords?: ReadonlyArray<string>;
 }
 /**
  * Create a keys service handler.
  *
- * The service is stub-level: it dispatches the 3 napplet -> shell keys
- * request types from @napplet/nub-keys, responds with spec-correct
- * envelopes, and defers real keyboard behavior to an optional
- * onForward callback. No binding persistence, no real keyboard listener.
+ * Attaches a single `keydown` listener to `options.listenerTarget`
+ * (default `document`). Matching chord subscriptions invoke `options.onForward`
+ * with a DOM-shape payload AND push a `keys.action` envelope back to the
+ * owning napplet via the per-window `send` callback captured at
+ * `keys.registerAction` time. Returns a `ServiceHandler` augmented with a
+ * `destroy()` method that detaches the listener and clears all registries.
  *
- * @param options - Optional configuration (onForward callback)
- * @returns A ServiceHandler to register with the runtime
+ * @param options - Optional configuration (onForward callback, listenerTarget)
+ * @returns A ServiceHandler (with `destroy()`) to register with the runtime
  *
  * @example
  * ```ts
@@ -538,32 +732,229 @@ interface KeysServiceOptions {
  * });
  *
  * runtime.registerService('keys', keys);
+ * // Later, on shell teardown:
+ * keys.destroy();
  * ```
  */
-declare function createKeysService(options?: KeysServiceOptions): ServiceHandler;
+declare function createKeysService(options?: KeysServiceOptions): ServiceHandler & {
+    destroy(): void;
+};
+
+/** Minimal subset of navigator.mediaSession the browser bridge depends on. Makes the bridge
+ *  Node/test-safe: unit tests pass a MockMediaSession via mediaSessionTarget.
+ *  The handler parameter uses `details?` (optional) so both the real DOM impl
+ *  (which always passes an object) and test mocks that omit details both satisfy
+ *  this type structurally. */
+type MediaSessionTarget = {
+    metadata: MediaMetadataLike | null;
+    playbackState: 'none' | 'playing' | 'paused';
+    setActionHandler(action: string, handler: ((details?: {
+        action?: string;
+        seekTime?: number;
+    }) => void) | null): void;
+};
+/** Structural subset of the DOM MediaMetadata class — assignable from a plain object
+ *  with title/artist/album/artwork fields. The browser impl uses `new MediaMetadata({...})`;
+ *  tests can pass a plain object. */
+type MediaMetadataLike = {
+    title?: string;
+    artist?: string;
+    album?: string;
+    artwork?: unknown;
+};
+/**
+ * Reference browser implementation of {@link HostMediaBridge}.
+ *
+ * Mirrors metadata to `navigator.mediaSession.metadata` (via the DOM
+ * `MediaMetadata` constructor when available; plain-object fallback in test
+ * envs). Mirrors playback state to `navigator.mediaSession.playbackState`
+ * with the canonical mapping: 'playing' maps to 'playing', 'paused' maps to
+ * 'paused', 'buffering' maps to 'paused', 'stopped' maps to 'none'. Installs
+ * `setActionHandler` callbacks for play/pause/nexttrack/previoustrack/seekto
+ * that fan into the onAction subscriber with the mapped `MediaAction` literal
+ * (and `value` from `details.seekTime` for seekto). When `setActiveSession` is
+ * called with a non-null `actions` parameter, only the declared actions get
+ * active handlers — the remaining are cleared (matching the capabilities
+ * narrowing behavior of Plan 27-01's inline implementation).
+ *
+ * Installs a silent-audio prime (4 kHz silent WAV data URL) when the first
+ * session becomes active (setActiveSession called with a non-null sessionId) —
+ * browsers refuse to render OS media controls without a playing audio element.
+ * Removes the element when destroySession brings the active session count to
+ * zero.
+ *
+ * @param opts.mediaSessionTarget - Override navigator.mediaSession (tests).
+ * @param opts.documentTarget - Override document (tests; pass null to disable silent-audio prime).
+ */
+declare function createBrowserMediaBridge(opts?: {
+    mediaSessionTarget?: MediaSessionTarget;
+    documentTarget?: Document | null;
+}): HostMediaBridge;
 
 /**
- * media-service.ts — NIP-5D media NUB reference service (stub-level).
+ * media-service.ts — NIP-5D media NUB reference service (navigator.mediaSession
+ * reference implementation).
  *
- * Handles 5 napplet -> shell request types from @napplet/nub-media:
+ * Handles the napplet-owned subset of @napplet/nub/media:
  *   media.session.create (result), media.session.update, media.session.destroy,
  *   media.state, media.capabilities.
  *
- * Stub-level: no real MediaSession API integration. Host apps wire real
- * playback backends via runtime.registerService('media', realHandler).
+ * HostMediaBridge contract: {@link HostMediaBridge} defines the pluggable backend
+ * contract for metadata/state mirroring + action routing. The browser reference
+ * implementation is {@link createBrowserMediaBridge} (mirrors to navigator.mediaSession
+ * with setActionHandler matrix). When no hostBridge option is passed, createMediaService
+ * internally uses createBrowserMediaBridge as the default — behavior is identical
+ * to the Plan 27-01 single-path implementation.
+ *
+ * navigator.mediaSession mirroring: on session.create the browser bridge mirrors the
+ * napplet-supplied metadata to navigator.mediaSession.metadata via new MediaMetadata()
+ * and installs setActionHandler callbacks for the 5 OS transport actions
+ * (play / pause / nexttrack / previoustrack / seekto). Each callback emits a canonical
+ * media.command envelope to the owning napplet — that is the @napplet/nub/media
+ * MediaCommandMessage shape consumed by the SDK's mediaOnCommand() helper.
+ *
+ * NAP-MEDIA now distinguishes napplet-owned playback from shell-owned
+ * playback. This reference backend supports `owner: "napplet"` because it
+ * mirrors a napplet's own media element to navigator.mediaSession. It rejects
+ * `owner: "shell"` until a host bridge provides policy-checked source fetching
+ * and playback.
+ *
+ * media.command push: when the OS user clicks a media control (hardware key, lock-screen
+ * transport, OS media overlay), the bridge's onAction callback fires. The service looks
+ * up the active session's owning napplet, invokes the per-window send callback captured
+ * at session.create time, and delivers:
+ *   { type: 'media.command', sessionId, action, value? }
+ * where action is the nub-media MediaAction literal (play|pause|next|prev|seek) and
+ * value is the seekTime (seconds) for seek.
+ *
+ * Silent-audio prime: the browser bridge creates a hidden <audio> element with a
+ * 4 kHz silent WAV data URL and plays it when the first session becomes active
+ * (setActiveSession with a non-null sessionId). Without a playing audio element in
+ * the host page, most browsers refuse to render OS media controls. The element is
+ * cleaned up when the last session is destroyed (via bridge.destroySession).
+ *
+ * Multi-session registry with last-active-wins semantics: every session.create is
+ * tracked in a Map<sessionId, SessionEntry>; any media.state report promotes that
+ * session to active. The active session's metadata and playback state are reflected
+ * via bridge.setMetadata / bridge.setPlaybackState. When the active session is
+ * destroyed, the next-most-recently-touched session is promoted automatically.
  *
  * Note: this is SEPARATE from packages/services/src/audio-service.ts, which
  * is the legacy ifc-topic-based audio source registry (audio:* topic events
- * over ifc.emit). media-service is the canonical @napplet/nub-media NIP-5D
+ * over ifc.emit). media-service is the canonical @napplet/nub/media NIP-5D
  * path and they coexist — audio-service continues to track audio sources for
  * shell UI, while media-service handles the NUB protocol envelope surface.
  *
- * Shell -> Napplet push types (media.command, media.controls) are handled
- * by the shell adapter separately — out of scope for this service.
+ * Shell -> Napplet push types (media.command) are emitted here when
+ * bridge.onAction callbacks fire — this is the canonical Phase 27 real backend.
  */
 
+type MediaPlaybackOwner = 'shell' | 'napplet';
+interface MediaSourceRef {
+    url?: string;
+    blossomHash?: string;
+    nostr?: {
+        eventId?: string;
+        address?: string;
+        relays?: string[];
+    };
+    mimeType?: string;
+}
+interface MediaSessionCreateOptions {
+    owner: MediaPlaybackOwner;
+    sessionId?: string;
+    source?: MediaSourceRef;
+    metadata?: MediaMetadata;
+    capabilities?: MediaAction[];
+    autoplay?: boolean;
+    live?: boolean;
+}
+/**
+ * Host-bridge contract for pluggable media backends.
+ *
+ * The browser reference implementation ({@link createBrowserMediaBridge}) mirrors
+ * napplet-reported metadata/state to `navigator.mediaSession` and installs
+ * `setActionHandler` callbacks that fan into the bridge's onAction subscribers.
+ * It satisfies this interface with all 5 fields implemented (setActiveSession
+ * switches the active session and optionally re-applies action-handler narrowing;
+ * destroySession tears down the silent-audio prime on last-session teardown).
+ *
+ * Host apps (Electron, Tauri) implement this interface in their own code and
+ * pass it via `createMediaService({ hostBridge: myBridge })` — the service
+ * then delegates metadata/state mirroring + action routing to the bridge and
+ * remains browser-free. Session-ownership bookkeeping (which windowId owns
+ * which sessionId, which send callback routes media.command back to which
+ * napplet) stays in the service layer — that's wire-protocol concern, not a
+ * bridge concern.
+ *
+ * Reference implementations for Electron / Tauri are explicitly out of v1.4
+ * scope and live in host-app examples / follow-up milestones (see
+ * REQUIREMENTS.md "Future Requirements").
+ *
+ * @example
+ * ```ts
+ * // Host-app pseudocode (Electron main-process relay):
+ * const electronBridge: HostMediaBridge = {
+ *   setMetadata(sessionId, md) { mediaBridge.sendMetadata({ sessionId, md }); },
+ *   setPlaybackState(sessionId, state) { mediaBridge.sendPlaybackState({ sessionId, state }); },
+ *   onAction(cb) {
+ *     const handler = (_: unknown, msg: { sessionId: string; action: MediaAction; value?: number }) =>
+ *       cb(msg.sessionId, msg.action, msg.value);
+ *     mediaBridge.onAction(handler);
+ *     return () => mediaBridge.offAction(handler);
+ *   },
+ * };
+ * const media = createMediaService({ hostBridge: electronBridge });
+ * runtime.registerService('media', media);
+ * ```
+ */
+interface HostMediaBridge {
+    /**
+     * Set the metadata displayed on the OS transport surface for a session.
+     * Called on session.create (with initial metadata) and on session.update
+     * (with merged metadata) whenever the session is the active session.
+     * Implementations MUST be idempotent.
+     */
+    setMetadata(sessionId: string, metadata: MediaMetadata): void;
+    /**
+     * Set the playback state for a session. Called on media.state reports
+     * whenever the session is the active session. State strings match
+     * nub-media MediaState.status exactly. Implementations MUST be idempotent.
+     */
+    setPlaybackState(sessionId: string, state: 'playing' | 'paused' | 'stopped' | 'buffering'): void;
+    /**
+     * Subscribe to OS-level action events (user clicks play/pause/seek/next/prev
+     * on the transport surface). Returns an unsubscribe handle.
+     *
+     * The callback receives `(sessionId, action, value?)`. `sessionId` is the
+     * bridge's currently-active session (the browser impl tracks this internally
+     * via setActionHandler-at-fire-time; native impls track via setActiveSession).
+     * `value` is populated for `action === 'seek'` (seek target in seconds) and
+     * for `action === 'volume'` (0.0-1.0). The service dispatches the resulting
+     * `media.command` envelope to the owning napplet of that session.
+     */
+    onAction(callback: (sessionId: string, action: MediaAction, value?: number) => void): () => void;
+    /**
+     * Optional: notify the bridge that the active session has changed. The
+     * browser reference impl uses this to switch which session's metadata/state
+     * is mirrored to the singleton navigator.mediaSession and to install (or
+     * clear) action handlers for the session's declared capabilities.
+     *
+     * The optional `actions` parameter carries the session's declared capability
+     * set so the bridge can narrow which OS transport buttons are active. When
+     * omitted, the bridge applies its default set. Native OS bridges that track
+     * active-session state internally may omit this field entirely.
+     */
+    setActiveSession?(sessionId: string | null, actions?: readonly MediaAction[]): void;
+    /**
+     * Optional: tear down per-session resources. The browser reference impl
+     * uses this to remove the silent-audio prime element when the last session
+     * is destroyed. Bridges that need no per-session teardown may omit this field.
+     */
+    destroySession?(sessionId: string): void;
+}
 /**
- * Optional host callbacks for the stub media service.
+ * Optional host callbacks for the media service.
  *
  * Host shells can hook session creation and state updates to drive
  * their own UI (e.g., now-playing banner) without replacing the
@@ -594,12 +985,32 @@ interface MediaServiceOptions {
     onSessionUpdate?: (windowId: string, sessionId: string, metadata: unknown) => void;
     /** Called when a napplet declares capabilities for a session. */
     onCapabilities?: (windowId: string, sessionId: string, actions: unknown) => void;
+    /**
+     * MediaSession target override (used by default browser bridge only).
+     * Defaults to `navigator.mediaSession` when running in a browser. Pass a
+     * MockMediaSession in unit tests. Ignored when `hostBridge` is provided.
+     */
+    mediaSessionTarget?: MediaSessionTarget;
+    /**
+     * DOM document override (used by default browser bridge only).
+     * Defaults to `document` when available. Set to null to disable the silent-audio
+     * prime entirely — useful in unit tests. Ignored when `hostBridge` is provided.
+     */
+    documentTarget?: Document | null;
+    /**
+     * Optional pluggable backend for metadata/state mirroring + OS action handling.
+     * When provided, the service delegates setMetadata / setPlaybackState / onAction
+     * to the bridge and skips navigator.mediaSession entirely. When omitted, the
+     * service internally uses {@link createBrowserMediaBridge} as the default.
+     * See {@link HostMediaBridge}.
+     */
+    hostBridge?: HostMediaBridge;
 }
 /**
- * Create a stub-level media NUB service handler.
+ * Create a media NUB service handler with navigator.mediaSession integration.
  *
  * Implements the 5 napplet->shell media.* request types defined in
- * `@napplet/nub-media`. Only `media.session.create` produces a reply
+ * `@napplet/nub/media`. Only `media.session.create` produces a reply
  * envelope (`media.session.create.result`) — the remaining four
  * (`session.update`, `session.destroy`, `state`, `capabilities`) are
  * fire-and-forget per the NUB spec.
@@ -607,8 +1018,10 @@ interface MediaServiceOptions {
  * Unknown `media.*` actions produce a `<type>.error` envelope so
  * napplets are never left hanging on a malformed request.
  *
- * @param options - Optional host callbacks for session lifecycle + state
- * @returns A ServiceHandler to register with the runtime
+ * @param options - Optional host callbacks for session lifecycle + state, plus
+ *   mediaSessionTarget and documentTarget for test injection, and an optional
+ *   hostBridge for native-OS media backend delegation.
+ * @returns A ServiceHandler (with `destroy()`) to register with the runtime
  *
  * @example
  * ```ts
@@ -616,14 +1029,18 @@ interface MediaServiceOptions {
  *
  * const media = createMediaService();
  * runtime.registerService('media', media);
+ * // Later, on shell teardown:
+ * media.destroy();
  * ```
  */
-declare function createMediaService(options?: MediaServiceOptions): ServiceHandler;
+declare function createMediaService(options?: MediaServiceOptions): ServiceHandler & {
+    destroy(): void;
+};
 
 /**
  * notify-service.ts — NIP-5D notify NUB reference service (stub-level).
  *
- * Handles the 5 napplet -> shell request types from `@napplet/nub-notify`:
+ * Handles the 5 napplet -> shell request types from `@napplet/nub/notify`:
  *   - `notify.send`                -> `notify.send.result` (shell-assigned id)
  *   - `notify.dismiss`             -> fire-and-forget
  *   - `notify.badge`               -> fire-and-forget
@@ -638,9 +1055,9 @@ declare function createMediaService(options?: MediaServiceOptions): ServiceHandl
  * `packages/services/src/notification-service.ts`, which is the legacy
  * ifc-topic-based notification registry (operates on `ifc.emit` topics
  * under `notifications:*`). `notify-service.ts` is the canonical
- * `@napplet/nub-notify` NIP-5D path and lives alongside the legacy module.
+ * `@napplet/nub/notify` NIP-5D path and lives alongside the legacy module.
  * If the host app registers this service via
- * `runtime.registerService('notify', ...)`, @napplet/nub-notify messages
+ * `runtime.registerService('notify', ...)`, @napplet/nub/notify messages
  * land here; the legacy ifc-emit topic path remains untouched.
  *
  * Shell -> napplet push messages (`notify.action`, `notify.clicked`,
@@ -684,7 +1101,7 @@ interface NotifyServiceOptions {
 /**
  * Create a stub-level notify service handler.
  *
- * Answers the 5 napplet->shell request types from `@napplet/nub-notify`.
+ * Answers the 5 napplet->shell request types from `@napplet/nub/notify`.
  * Does NOT implement a real backend (no DOM Notification API, no channel
  * registry, no permission prompt). Host apps replace this via
  * `runtime.registerService('notify', realHandler)` when a real backend is
@@ -706,7 +1123,7 @@ declare function createNotifyService(options?: NotifyServiceOptions): ServiceHan
 /**
  * theme-service.ts — NIP-5D theme NUB reference service.
  *
- * Handles the single napplet->shell request type from @napplet/nub-theme:
+ * Handles the single napplet->shell request type from @napplet/nub/theme:
  *   - `theme.get`         -> `theme.get.result { theme }` (current theme)
  *
  * Exposes a host-facing `publishTheme(theme)` handle that:
@@ -807,4 +1224,576 @@ interface ThemeService {
  */
 declare function createThemeService(options?: ThemeServiceOptions): ThemeService;
 
-export { type AudioServiceOptions, type AudioSource, type CacheServiceOptions, type CoordinatedRelayOptions, type IdentityServiceOptions, type KeysServiceOptions, type MediaServiceOptions, type Notification, type NotificationServiceOptions, type NotifyServiceOptions, type RelayPoolServiceOptions, type ThemeService, type ThemeServiceOptions, createAudioService, createCacheService, createCoordinatedRelay, createIdentityService, createKeysService, createMediaService, createNotificationService, createNotifyService, createRelayPoolService, createThemeService };
+/**
+ * config-service.ts — NUB-CONFIG reference service (9th NUB domain, v1.7 Phase 39).
+ *
+ * Shell-side reference implementation for the canonical NUB-CONFIG wire
+ * protocol (`@napplet/nub/config`, published at `^0.3.0`). Handles the full
+ * 8-message discriminated union: 5 napplet→shell request types + 3
+ * shell→napplet result/push types.
+ *
+ * ──────────────────────────── SCOPE BOUNDARY (CONFIG-04) ─────────────────────────
+ * NUB-CONFIG is **shell-managed per-napplet configuration**. Napplets observe
+ * values via `config.get` (one-shot) or `config.subscribe` (snapshot + live
+ * push). The shell is the **sole writer** — there is intentionally **NO**
+ * `config.set` wire message. Napplets cannot mutate configuration values;
+ * the shell owns persistence and the update flow.
+ *
+ * Do NOT use this service as a general key-value store. NUB-STORAGE
+ * (`state:read` / `state:write`) remains the general KV surface. Using
+ * NUB-CONFIG to store e.g. `{ lastScrollPosition: 420 }` is an anti-pattern
+ * (H-07 in PITFALLS.md) — such state belongs in NUB-STORAGE.
+ * ──────────────────────────────────────────────────────────────────────────────────
+ *
+ * Host integration: provide `getValues()` returning the current
+ * `ConfigValues` snapshot. Call the returned `publishValues(newValues)`
+ * whenever the configuration changes — the service fans the new snapshot
+ * out to every napplet that has an active `config.subscribe`.
+ *
+ * Optional: provide `registerSchema` to accept napplet-declared schemas at
+ * runtime (the ref impl does a minimal shape check using the Core Subset
+ * validator; use `ajv` in host impls that need strict draft-07 conformance).
+ * Provide `openSettings` to open a shell-side UI for the napplet (no
+ * response envelope — fire-and-forget UI hook).
+ *
+ * @example
+ * ```ts
+ * import { createConfigService } from '@kehto/services';
+ *
+ * const configFixtures = { theme: 'dark', density: 'compact', recentSearches: [] };
+ * const config = createConfigService({
+ *   getValues: () => ({ ...configFixtures }),
+ * });
+ * runtime.registerService('config', config.handler);
+ *
+ * // Later, when shell-side values change:
+ * configFixtures.theme = 'light';
+ * config.publishValues({ ...configFixtures });
+ * ```
+ */
+
+/**
+ * Shape returned by a successful `registerSchema` result (ok=true) or a
+ * rejection (ok=false + code + error). Mirrors the wire envelope fields.
+ */
+type ConfigSchemaValidation = {
+    ok: true;
+} | {
+    ok: false;
+    code: ConfigSchemaErrorCode;
+    error: string;
+};
+/**
+ * Configuration options for `createConfigService` (options-as-bridge
+ * per v1.6 Decision 18).
+ *
+ * @example
+ * ```ts
+ * const config = createConfigService({
+ *   getValues: () => ({ theme: 'dark', density: 'compact' }),
+ *   openSettings: (windowId, section) => showSettingsPanel(windowId, section),
+ * });
+ * ```
+ */
+interface ConfigServiceOptions {
+    /**
+     * Returns the current configuration values snapshot.
+     * Called on every `config.get` and at every `config.subscribe` initial push.
+     * Implementations should return a fresh object (not a mutable reference).
+     */
+    getValues(): ConfigValues;
+    /**
+     * Optional: receive notification when a napplet subscribes to config updates.
+     * Fire-and-forget — the service tracks the subscription internally regardless.
+     */
+    onSubscribe?: (windowId: string) => void;
+    /**
+     * Optional: receive notification when a napplet unsubscribes.
+     */
+    onUnsubscribe?: (windowId: string) => void;
+    /**
+     * Optional: validate and store a napplet-provided schema.
+     *
+     * If omitted, the ref impl runs its own Core Subset check (hand-coded
+     * validator; 30-50 lines) and returns ok/reject. Hosts that need strict
+     * draft-07 conformance should provide an ajv-backed implementation.
+     *
+     * Return shape mirrors `config.registerSchema.result` wire envelope
+     * (minus the `id` — the dispatch layer correlates).
+     */
+    registerSchema?: (windowId: string, schema: NappletConfigSchema, version: number | undefined) => ConfigSchemaValidation;
+    /**
+     * Optional: open the shell-side settings UI for this napplet.
+     * Fire-and-forget — no response envelope per the wire spec.
+     * If omitted, `config.openSettings` is silently dropped (D10 allows
+     * the config-demo napplet to function without a settings UI).
+     */
+    openSettings?: (windowId: string, section: string | undefined) => void;
+}
+/**
+ * NUB-CONFIG reference service bundle — `handler` to register with the
+ * runtime, `publishValues` for the host app to push updates live to all
+ * subscribed napplets.
+ */
+interface ConfigService {
+    /** Register this with the runtime via `runtime.registerService('config', handler)`. */
+    handler: ServiceHandler;
+    /**
+     * Broadcast a new values snapshot to every napplet with an active
+     * `config.subscribe`. Each subscriber receives a `config.values` envelope
+     * with no `id` (push form per wire spec — absence of `id` distinguishes
+     * push from correlated `config.get` response).
+     *
+     * @param values - The new configuration snapshot (full object, not a diff)
+     */
+    publishValues(values: ConfigValues): void;
+}
+/**
+ * Create a NUB-CONFIG reference service.
+ *
+ * Shell-writes, napplet-reads. Handles the full `@napplet/nub/config` wire
+ * protocol: `config.get` (correlated snapshot), `config.subscribe` /
+ * `config.unsubscribe` (live push stream), `config.registerSchema` (optional
+ * schema registration + Core Subset validation), `config.openSettings`
+ * (optional UI deep-link, fire-and-forget).
+ *
+ * Returns a `ConfigService` bundle: `{ handler, publishValues }`.
+ * Register `handler` with the runtime; call `publishValues(newValues)` from
+ * the shell whenever config state changes.
+ *
+ * @param options - Host-supplied implementation hooks (options-as-bridge,
+ *   v1.6 Decision 18). `getValues` is required; all other fields are optional.
+ * @returns A ConfigService bundle.
+ *
+ * @see ConfigServiceOptions for the options shape.
+ * @see packages/services/src/theme-service.ts for the sibling pattern.
+ * @see SCOPE BOUNDARY comment at the top of this file re: NUB-STORAGE separation.
+ *
+ * @example
+ * ```ts
+ * import { createConfigService } from '@kehto/services';
+ *
+ * const config = createConfigService({
+ *   getValues: () => ({ theme: 'dark', density: 'compact' }),
+ *   openSettings: (windowId, section) => openSettingsUI(section),
+ * });
+ * runtime.registerService('config', config.handler);
+ *
+ * // Push a live update to all subscribers:
+ * config.publishValues({ theme: 'light', density: 'compact' });
+ * ```
+ */
+declare function createConfigService(options: ConfigServiceOptions): ConfigService;
+
+/**
+ * resource-service.ts — NUB-RESOURCE reference service (10th NUB domain, v1.7 Phase 40).
+ *
+ * Shell-side reference implementation for the canonical NUB-RESOURCE wire
+ * protocol (`internal-resource.ts` in @kehto/shell/src/types; kehto-internal
+ * model per PROJECT.md Decision #31 — diverges from upstream `@napplet/nub/
+ * resource` in field names + error vocabulary). Handles the canonical
+ * 4-message protocol:
+ *   Inbound:  resource.bytes, resource.cancel
+ *   Outbound: resource.bytes.result, resource.bytes.error
+ *
+ * ──────────────────────── SCOPE BOUNDARY (RESOURCE-01) ────────────────────────
+ * NUB-RESOURCE is an **authenticated fetch proxy** — read-only, atomic.
+ *
+ * This service is NOT responsible for:
+ *   - Streaming / chunked responses (host-app concern)
+ *   - Response caching / conditional requests (host-app concern)
+ *   - Upload / POST body construction (NUB-RESOURCE v1.7 is read-only)
+ *   - Redirect limits, MIME sniffing, SVG rasterization (host-fetch concern)
+ *   - Private-IP blocking, SSRF mitigation (host-provided-fetch responsibility)
+ *
+ * These belong to the host-app's `fetch` implementation per D7 and
+ * SHELL-RESOURCE-POLICY.md (Phase 40 Plan 40-03). Kehto ships a reference
+ * service; production hardening is the host app's concern.
+ * ──────────────────────────────────────────────────────────────────────────────
+ *
+ * Host integration: provide `fetch`, `isOriginGranted`, `getConnectGrants`,
+ * and `resolveIdentity`. ALL FOUR are required from day one (H-03 prevention).
+ *
+ * @example
+ * ```ts
+ * import { createResourceService } from '@kehto/services';
+ *
+ * const resourceSvc = createResourceService({
+ *   fetch: (url, init) => globalThis.fetch(url, init),
+ *   isOriginGranted: (origin, grants) => grants.includes(origin),
+ *   getConnectGrants: (dTag, hash) => connectStore.getOrigins(dTag, hash),
+ *   resolveIdentity: (windowId) => sessionRegistry.getEntryByWindowId(windowId) ?? null,
+ * });
+ * runtime.registerService('resource', resourceSvc);
+ * ```
+ */
+
+/**
+ * Options for `createResourceService` (options-as-bridge per v1.6 Decision 18).
+ *
+ * ALL FOUR fields are required. The factory throws at construction if any is
+ * missing — H-03 prevention: the grants source (`getConnectGrants`) MUST be
+ * wired from day one so there is no window where resource requests bypass the
+ * grant check.
+ *
+ * @see PITFALLS.md:228 (H-03) — grants-source coupling must be present at construction
+ */
+interface ResourceServiceOptions {
+    /**
+     * Host-supplied fetch implementation. Receives the URL, a partial init
+     * (method, headers, signal), and must return a `Response`-compatible promise.
+     *
+     * The host's `fetch` is the ONLY place to implement redirect limits, MIME
+     * sniffing, SVG rasterization, private-IP / SSRF blocking, etc.
+     * This service does NOT filter: it proxies transparently.
+     *
+     * @param url - The URL from the resource.bytes request
+     * @param init - Method, headers (from napplet), and an AbortSignal
+     */
+    fetch(url: string, init: {
+        method?: string;
+        headers?: Record<string, string>;
+        signal: AbortSignal;
+    }): Promise<Response>;
+    /**
+     * Returns true if `origin` is present in `grants` (the list returned by
+     * `getConnectGrants` for the napplet's dTag + aggregateHash).
+     *
+     * The reference implementation is simply `grants.includes(origin)`. Host apps
+     * may provide normalized-origin comparison if needed.
+     *
+     * @param origin - Parsed origin of the requested URL (scheme + host + port)
+     * @param grants - Readonly list from getConnectGrants for this napplet identity
+     */
+    isOriginGranted(origin: string, grants: readonly string[]): boolean;
+    /**
+     * Returns the list of allowed fetch origins for the given napplet identity.
+     * Called on every `resource.bytes` request — must be synchronous and fast.
+     *
+     * Typically wraps `connectStore.getOrigins(dTag, aggregateHash)` from
+     * @kehto/shell.
+     *
+     * H-03 prevention: REQUIRED from day one — factory throws on construction
+     * if omitted.
+     *
+     * @param dTag - The napplet's d-tag (from session registry)
+     * @param aggregateHash - The napplet's aggregate hash (from session registry)
+     */
+    getConnectGrants(dTag: string, aggregateHash: string): readonly string[];
+    /**
+     * Resolve a windowId to the napplet's identity (dTag + aggregateHash).
+     * Returns null if the window is not in the session registry.
+     *
+     * Typically wraps `sessionRegistry.getEntryByWindowId(windowId)`.
+     *
+     * @param windowId - The iframe window identifier
+     */
+    resolveIdentity(windowId: string): {
+        dTag: string;
+        aggregateHash: string;
+    } | null;
+}
+/**
+ * Type alias for the ServiceHandler returned by `createResourceService`.
+ * Exported for host apps that need to type-annotate the handler reference.
+ */
+type ResourceService = ServiceHandler;
+/**
+ * Create a NUB-RESOURCE reference service.
+ *
+ * Implements canonical 4-message protocol: `resource.bytes` (napplet → shell
+ * fetch request), `resource.cancel` (napplet → shell in-flight cancellation),
+ * `resource.bytes.result` (shell → napplet success), `resource.bytes.error`
+ * (shell → napplet failure/denial/cancel).
+ *
+ * On-construction guard (H-03 prevention): all four options are validated at
+ * factory call time. If any is missing, the factory throws immediately with a
+ * message containing `[RESOURCE-01 / H-03]` so misconfigured shell apps fail
+ * loudly at startup rather than silently at first dispatch.
+ *
+ * Returns a `ServiceHandler` (no `publishValues`-style surface — resource has
+ * no shell-initiated push beyond the response/error path).
+ *
+ * @param options - REQUIRED: fetch, isOriginGranted, getConnectGrants, resolveIdentity
+ * @returns ServiceHandler to register via `runtime.registerService('resource', handler)`
+ *
+ * @example
+ * ```ts
+ * import { createResourceService } from '@kehto/services';
+ *
+ * const svc = createResourceService({
+ *   fetch: (url, init) => globalThis.fetch(url, init),
+ *   isOriginGranted: (origin, grants) => grants.includes(origin),
+ *   getConnectGrants: (dTag, hash) => connectStore.getOrigins(dTag, hash),
+ *   resolveIdentity: (windowId) => sessionRegistry.getEntryByWindowId(windowId) ?? null,
+ * });
+ * runtime.registerService('resource', svc);
+ * ```
+ */
+declare function createResourceService(options: ResourceServiceOptions): ResourceService;
+
+/**
+ * outbox-service.ts — NAP-OUTBOX (outbox-aware relay routing) reference service.
+ *
+ * Shell-side handler for the NAP-OUTBOX wire protocol. It is a pure envelope
+ * router: it validates `outbox.*` envelopes, delegates the actual relay
+ * discovery / routing / dedup / publish-fanout work to an injected
+ * {@link OutboxRouter}, and posts the correlated result / lifecycle messages
+ * (echoing the request `id` or `subId`) back to the napplet.
+ *
+ * The router is injected (options-as-bridge) so this service has no Nostr
+ * dependency and is fully unit-testable. A concrete relay-pool-backed router
+ * ships alongside as {@link createRelayPoolOutboxRouter}.
+ *
+ * ──────────────────────────── Responsibilities ────────────────────────────
+ *   Inbound:  outbox.query, outbox.subscribe, outbox.close, outbox.publish,
+ *             outbox.resolveRelays
+ *   Outbound: outbox.query.result, outbox.event, outbox.eose, outbox.closed,
+ *             outbox.publish.result, outbox.resolveRelays.result
+ *
+ * The shell owns relay discovery, routing, fallback, deduplication, signature
+ * validation, signing, and publish fanout policy — all of which live behind
+ * the {@link OutboxRouter}. This service only marshals the wire protocol.
+ *
+ * @example
+ * ```ts
+ * import { createOutboxService, createRelayPoolOutboxRouter } from '@kehto/services';
+ *
+ * const router = createRelayPoolOutboxRouter({ relayPool, loadRelayLists, fallbackRelays });
+ * runtime.registerService('outbox', createOutboxService({ router }));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Relay-selection strategy:
+ * - `outbox` — query/publish via author write relays (the outbox model)
+ * - `inbox`  — query/publish via recipient read relays (the inbox model)
+ * - `auto`   — let the shell choose per its policy and relay intelligence
+ */
+type OutboxStrategy = 'outbox' | 'inbox' | 'auto';
+/** Options for a one-shot outbox query. */
+interface OutboxQueryOptions {
+    /** Explicit author hints (augment/override authors derived from filters). */
+    authors?: string[];
+    /** Relay hints; treated as a hint subject to shell validation, not a bypass. */
+    relays?: string[];
+    /** Relay-selection strategy. */
+    strategy?: OutboxStrategy;
+    /** Maximum events to collect. */
+    limit?: number;
+    /** Wall-clock budget for the query, in milliseconds. */
+    timeoutMs?: number;
+}
+/** Options for a live outbox subscription. */
+interface OutboxSubscribeOptions extends OutboxQueryOptions {
+    /** Keep the subscription open for real-time events after EOSE. */
+    live?: boolean;
+}
+/** Options for an outbox publish. */
+interface OutboxPublishOptions {
+    /** Relay hints; treated as a hint subject to shell validation. */
+    relays?: string[];
+    /** Recipient authors whose inbox relays should be included for directed events. */
+    targetAuthors?: string[];
+    /** Relay-selection strategy. */
+    strategy?: OutboxStrategy;
+}
+/** A read/write target for relay-plan resolution. */
+interface OutboxTarget {
+    /** Authors to resolve relays for. */
+    authors?: string[];
+    /** Single pubkey to resolve relays for. */
+    pubkey?: string;
+    /** Whether the plan is for reading (their write relays) or writing (their read relays). */
+    direction?: 'read' | 'write';
+    /** Relay-selection strategy. */
+    strategy?: OutboxStrategy;
+}
+/** The relay plan the shell would use for a target. */
+interface OutboxRelayPlan {
+    /** Resolved relay URLs. */
+    relays: string[];
+    /** Where the plan came from. */
+    source: 'nip65' | 'cache' | 'policy' | 'fallback';
+    /** Authors for which no relay list could be resolved. */
+    missingAuthors?: string[];
+}
+/** Outcome of an outbox query, as returned by the {@link OutboxRouter}. */
+interface OutboxResult {
+    /** Deduplicated, signature-validated events. */
+    events: NostrEvent[];
+    /** Map of event id -> relay URLs where the shell observed the event. */
+    relays: Record<string, string[]>;
+    /** True when some relay lists or connections failed and results are partial. */
+    incomplete?: boolean;
+    /** Error reason when the query could not complete. */
+    error?: string;
+}
+/** Outcome of an outbox publish, as returned by the {@link OutboxRouter}. */
+interface OutboxPublishResult {
+    /** Whether the publish succeeded on at least the required relays. */
+    ok: boolean;
+    /** The signed event returned by the shell. */
+    event?: NostrEvent;
+    /** The published event id. */
+    eventId?: string;
+    /** Map of relay URL -> per-relay publish success. */
+    relays?: Record<string, boolean>;
+    /** Error reason when the publish failed. */
+    error?: string;
+}
+/** Sink an {@link OutboxRouter} streams subscription lifecycle through. */
+interface OutboxSubscriptionSink {
+    /** Deliver a matching event; `relay` is the relay it was observed on, when known. */
+    event(event: NostrEvent, relay?: string): void;
+    /** Signal end-of-stored-events. */
+    eose(): void;
+    /** Signal that the subscription was closed upstream; `reason` is optional. */
+    closed(reason?: string): void;
+}
+/** Handle to a router-owned subscription. */
+interface OutboxRouterSubscription {
+    /** Stop the subscription and release its relay connections. */
+    close(): void;
+}
+/**
+ * Abstract outbox router. Implementors own relay discovery (NIP-65 / NIP-66),
+ * routing, fallback, deduplication, signature validation, signing, and publish
+ * fanout. The service translates wire envelopes into these calls and back.
+ */
+interface OutboxRouter {
+    /** Resolve relays, query them, dedup by id, validate signatures, collect events. */
+    query(filters: NostrFilter[], options?: OutboxQueryOptions): Promise<OutboxResult>;
+    /** Open a live outbox-aware subscription, streaming through `sink`. */
+    subscribe(filters: NostrFilter[], options: OutboxSubscribeOptions | undefined, sink: OutboxSubscriptionSink): OutboxRouterSubscription;
+    /** Sign `template` and fan it out to the relevant write/inbox relays. */
+    publish(template: EventTemplate, options?: OutboxPublishOptions): Promise<OutboxPublishResult>;
+    /** Return the relay plan the shell would use for a read/write target. */
+    resolveRelays(target: OutboxTarget): Promise<OutboxRelayPlan>;
+}
+/** Options for {@link createOutboxService}. */
+interface OutboxServiceOptions {
+    /** The outbox router the shell uses to reach relays. Required. */
+    router: OutboxRouter;
+}
+/**
+ * Create the NAP-OUTBOX service handler.
+ *
+ * @param options - Must provide an {@link OutboxRouter}.
+ * @returns A `ServiceHandler` ready for `runtime.registerService('outbox', handler)`.
+ * @throws If `options.router` is missing.
+ */
+declare function createOutboxService(options: OutboxServiceOptions): ServiceHandler;
+
+/**
+ * relay-pool-outbox-router.ts — concrete {@link OutboxRouter} backed by a relay pool.
+ *
+ * Implements the outbox-model routing that NAP-OUTBOX centralizes so napplets
+ * don't each reinvent it: derive authors, resolve their NIP-65 relays, fan a
+ * per-relay subscription out across the plan, deduplicate by event id (while
+ * recording every relay an event was observed on), validate signatures, and —
+ * for publish — sign the template and fan it out to the relevant write/inbox
+ * relays.
+ *
+ * NIP-65 relay-list *fetching* is the host's concern (it may come from a
+ * kind-10002 cache, a NIP-66 indexer via `@kehto/nip/66`, or a live query), so
+ * it is injected via {@link RelayPoolOutboxRouterOptions.loadRelayLists}. The
+ * relay pool, signer, and signature verifier are injected too — keeping this
+ * router browser-agnostic and unit-testable with mocks.
+ *
+ * Relay-selection model (per the outbox model):
+ * - reading an author's events  → their **write** relays (where they publish)
+ * - writing to reach an author   → their **read**  relays (their inbox)
+ *
+ * `strategy` overrides the direction default: `outbox` forces write relays,
+ * `inbox` forces read relays, `auto` (default) follows the read/write direction.
+ *
+ * @example
+ * ```ts
+ * import { createOutboxService, createRelayPoolOutboxRouter } from '@kehto/services';
+ *
+ * const router = createRelayPoolOutboxRouter({
+ *   relayPool: myOutboxPool,
+ *   loadRelayLists: (pubkeys) => relayListCache.getMany(pubkeys),
+ *   fallbackRelays: ['wss://relay.damus.io', 'wss://nos.lol'],
+ *   signEvent: (tmpl) => signer.signEvent(tmpl),
+ *   verifyEvent: (ev) => verifyEvent(ev),
+ * });
+ * runtime.registerService('outbox', createOutboxService({ router }));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** A NIP-65 relay list for a single pubkey. */
+interface RelayListEntry {
+    /** Relays the author reads from (their inbox). */
+    read: string[];
+    /** Relays the author writes to (where their events land). */
+    write: string[];
+}
+/**
+ * Relay pool contract the router drives. Implementors adapt their pool library
+ * (nostr-tools SimplePool, applesauce-relay, etc.). Unlike the lower-level
+ * relay NUB pool, both methods take an explicit relay-URL set so the router
+ * controls outbox routing and can attribute events to the relay they arrived on.
+ */
+interface OutboxRelayPool {
+    /**
+     * Subscribe to `filters` on exactly `relayUrls`. The callback receives each
+     * matching event or the literal `'EOSE'` once stored events are exhausted.
+     * Returns a handle to cancel the subscription.
+     */
+    subscribe(filters: NostrFilter[], relayUrls: string[], callback: (item: NostrEvent | 'EOSE') => void): {
+        unsubscribe(): void;
+    };
+    /**
+     * Publish `event` to `relayUrls`. May return a per-relay success map; a
+     * `void`/missing return is treated as optimistic success on every target.
+     */
+    publish(event: NostrEvent, relayUrls: string[]): Promise<Record<string, boolean>> | Record<string, boolean> | void;
+    /** Whether the relay pool is connected and able to handle requests. */
+    isAvailable(): boolean;
+}
+/** Options for {@link createRelayPoolOutboxRouter}. */
+interface RelayPoolOutboxRouterOptions {
+    /** Relay pool the router subscribes/publishes through. Required. */
+    relayPool: OutboxRelayPool;
+    /**
+     * Resolve NIP-65 relay lists for a set of pubkeys. Pubkeys with no known
+     * list are simply omitted from the returned map (they become `missingAuthors`).
+     */
+    loadRelayLists(pubkeys: string[]): Promise<Map<string, RelayListEntry>> | Map<string, RelayListEntry>;
+    /** Relays to fall back to when NIP-65 data is absent, stale, or empty. Required. */
+    fallbackRelays: string[];
+    /**
+     * Sign a template before publish (shell-mediated; napplets never sign). When
+     * omitted, `publish` resolves with `{ ok: false, error: 'publish denied' }`.
+     */
+    signEvent?(template: EventTemplate): Promise<NostrEvent>;
+    /**
+     * Validate an event signature before delivering it to a napplet. May be sync
+     * or async. Defaults to accepting every event (host pools often pre-verify).
+     */
+    verifyEvent?(event: NostrEvent): Promise<boolean> | boolean;
+    /**
+     * Gate relay URLs (e.g. block private-network hosts). Defaults to allowing
+     * only `ws://` / `wss://` URLs — `options.relays` hints pass through this too.
+     */
+    isRelayAllowed?(url: string): boolean;
+    /** Default query timeout when `options.timeoutMs` is unset. Default 4000ms. */
+    defaultTimeoutMs?: number;
+}
+/**
+ * Create a relay-pool-backed {@link OutboxRouter}.
+ *
+ * @param options - Relay pool, NIP-65 loader, fallback relays, and optional
+ *   signer / verifier / relay gate / timeout.
+ * @returns An {@link OutboxRouter} for {@link createOutboxService}.
+ * @throws If `relayPool`, `loadRelayLists`, or `fallbackRelays` are missing.
+ */
+declare function createRelayPoolOutboxRouter(options: RelayPoolOutboxRouterOptions): OutboxRouter;
+
+export { type AudioServiceOptions, type AudioSource, type CacheServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type GiftWrapDecryptResult, type HostCacheBridge, type HostDecryptBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type IdentityDecryptErrorCode, type IdentityDecryptErrorMessage, type IdentityDecryptMessage, type IdentityDecryptResultMessage, type IdentityServiceOptions, type KeysServiceOptions, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type Notification, type NotificationServiceOptions, type NotifyServiceOptions, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxStrategy, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceService, type ResourceServiceOptions, type Rumor, type ThemeService, type ThemeServiceOptions, type VerifyEvent, createAudioService, createBrowserMediaBridge, createCacheService, createConfigService, createCoordinatedRelay, createIdentityService, createKeysService, createMediaService, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createThemeService };