@kehto/services 0.11.0 → 0.12.0

package/README.md

@@ -1,6 +1,6 @@
 # @kehto/services
 
-Reference service handlers for the napplet protocol — audio, notifications, identity, relay pool, cache, keys, media, notify, theme.
+Reference service handlers for the napplet protocol — audio, notifications, identity, relay pool, cache, keys, media, notify, theme, link, common, lists, serial, BLE, WebRTC.
 
 > **Alpha status:** Kehto is an early runtime implementation for a draft NIP-5D
 > protocol. NAP contracts and service envelopes are not final; treat these
@@ -23,22 +23,27 @@ Current draft posture:
 - The v1.1 signer service is deleted outright. Its responsibilities split into two: read-only identity lookups go through `createIdentityService` (`getPublicKey`, `getRelays`, `getProfile`, `getFollows`, `getList`, `getZaps`, `getMutes`, `getBlocked`, `getBadges`); signing happens inside the shell as part of `relay.publish` / `relay.publishEncrypted` and is never exposed to napplets.
 - `createKeysService` and `createMediaService` ship real reference backends as of v1.4 (see the dedicated sections below). `createKeysService` attaches a document-level `keydown` listener by default and delivers `keys.action` push envelopes to registered napplets; `createMediaService` mirrors session metadata and playback state to `navigator.mediaSession` and emits `media.command` push envelopes on OS transport events. Both accept a host-bridge option (`HostKeysBridge` / `HostMediaBridge`) so Electron / Tauri / native shells can swap in OS-level backends without re-implementing the wire-protocol bookkeeping.
 - `createNotifyService` (NIP-5D `notify.*` NAP) coexists with the legacy `createNotificationService` (inc-emit `notifications:*` channel). Both may be registered simultaneously while hosts migrate.
+- `createResourceService` supports `resource.bytesMany` from draft NAP-RESOURCE. Bulk requests return ordered per-URL items and keep per-URL failures local while preserving legacy single-fetch fields for existing Kehto callers.
 
 ## Quick Start
 
 ```ts
 import {
   createIdentityService,
+  createListsService,
   createNotificationService,
+  createBleService,
+  createSerialService,
+  createWebrtcService,
 } from '@kehto/services';
 
 // Identity service — read-only lookups backed by a signer adapter.
 runtime.registerService(
   'identity',
   createIdentityService({
-    getPublicKey: () => signer.getPublicKey(),
-    getRelays: () => signer.getRelays(),
+    getSigner: () => signer,
     getProfile: (pk) => nostrClient.fetchProfile(pk),
+    getFollows: (pk) => contactListCache.getFollows(pk),
   }),
 );
 
@@ -47,6 +52,70 @@ runtime.registerService(
   'notifications',
   createNotificationService({ onChange: (list) => updateBadge(list) }),
 );
+
+// Lists service — shell-owned NIP-51 metadata and mutations.
+runtime.registerService(
+  'lists',
+  createListsService({
+    supported: () => [{ kind: 10003, type: 'bookmarks', addressable: false }],
+    add: (_list, items) => ({ ok: true, added: items.length }),
+    remove: (_list, items) => ({ ok: true, removed: items.length }),
+  }),
+);
+
+// Serial service — runtime-owned serial sessions and host-owned device access.
+runtime.registerService(
+  'serial',
+  createSerialService({
+    open: () => ({ session: { id: 'host-session-1', state: 'open' } }),
+    write: (_sessionId, _data) => {},
+    close: (_sessionId) => {},
+  }),
+);
+
+// BLE service — runtime-owned BLE/GATT sessions and host-owned device access.
+runtime.registerService(
+  'ble',
+  createBleService({
+    open: () => ({
+      session: {
+        id: 'host-ble-1',
+        state: 'open',
+        device: { id: 'host-device-1', name: 'Host BLE' },
+      },
+    }),
+    services: () => [],
+    read: () => [87],
+    write: (_sessionId, _target, _data) => {},
+    subscribe: (_sessionId, _target) => {},
+    unsubscribe: (_sessionId, _target) => {},
+    close: (_sessionId) => {},
+  }),
+);
+
+// WebRTC service — runtime-owned sessions and host-owned signaling/transport.
+runtime.registerService(
+  'webrtc',
+  createWebrtcService({
+    open: (request, ctx) => {
+      const id = 'host-webrtc-1';
+      ctx.emit({ type: 'state', sessionId: id, state: 'open' });
+      return {
+        session: {
+          id,
+          scope: request.scope,
+          channel: request.channel ?? 'default',
+          protocol: request.protocol,
+          state: 'open',
+        },
+      };
+    },
+    send: (sessionId, payload, ctx) => {
+      ctx.emit({ type: 'message', sessionId, from: 'host', payload });
+    },
+    close: (_sessionId) => {},
+  }),
+);
 ```
 
 ## Keys Service
@@ -353,6 +422,8 @@ Each factory returns a `ServiceHandler` registrable via `runtime.registerService
 ### Identity NAP
 - `createIdentityService` — `identity.*` reads (`identity:read`). No signing surface; shell mediates signing internally.
 
+`createIdentityService` uses `getSigner()` for `identity.getPublicKey` and `identity.getRelays`. Hosts may also pass optional read-only provider hooks for `getProfile`, `getFollows`, `getList`, `getZaps`, `getMutes`, `getBlocked`, and `getBadges`. These hooks receive the current signer pubkey (or `""` when no signer is connected) and return the payload portion of the corresponding `.result` envelope. Kehto does not query relays itself; the hooks are for hosts that already maintain profile, contact-list, list, zap, moderation, or badge data.
+
 ### Notify NAP
 - `createNotifyService` — canonical `notify.*` envelopes (`notify:send` / `notify:channel`).
 - `createNotificationService` — legacy inc-emit `notifications:*` channel; coexists with `createNotifyService` until retired.
@@ -368,6 +439,9 @@ Each factory returns a `ServiceHandler` registrable via `runtime.registerService
 ### Media NAP
 - `createMediaService` — owner-aware `media.session.create` / `update` / `destroy` / `media.state` / `media.capabilities` + `media.command` push envelopes (`media:control`). Napplet-owned sessions mirror to `navigator.mediaSession` by default; shell-owned creates are rejected until a host playback/fetch bridge is supplied. Implement the `HostMediaBridge` interface to swap in native backends. See [Media Service](#media-service) for the full contract.
 
+### WebRTC NAP
+- `createWebrtcService` — `webrtc.open`, `webrtc.send`, `webrtc.close` + host-pushed `webrtc.event` envelopes. The reference handler owns only the NAP request/result bookkeeping; host bridges own signaling, SDP, ICE, peer connection lifecycle, and policy.
+
 ### Theme NAP
 - `createThemeService` — `theme.get` + `theme.changed` fan-out (`theme:read`). Returns a `ThemeService` with `publishTheme()` / `setTheme()` utilities for host-side updates.
 
@@ -375,7 +449,7 @@ Each factory returns a `ServiceHandler` registrable via `runtime.registerService
 - `createAudioService` — `audio:*` inc-emit topic handler. Browser-agnostic registry of per-window audio sources; host wires `onChange` to update transport UI.
 
 ### Types
-`AudioSource`, `AudioServiceOptions`, `Notification`, `NotificationServiceOptions`, `IdentityServiceOptions`, `RelayPoolServiceOptions`, `CacheServiceOptions`, `CoordinatedRelayOptions`, `KeysServiceOptions`, `MediaServiceOptions`, `NotifyServiceOptions`, `ThemeServiceOptions`, `ThemeService`.
+`AudioSource`, `AudioServiceOptions`, `Notification`, `NotificationServiceOptions`, `IdentityServiceOptions`, `RelayPoolServiceOptions`, `CacheServiceOptions`, `CoordinatedRelayOptions`, `KeysServiceOptions`, `MediaServiceOptions`, `NotifyServiceOptions`, `ThemeServiceOptions`, `ThemeService`, `WebrtcServiceOptions`, `WebrtcServiceContext`.
 
 ## API Reference
 

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ServiceHandler, Signer } from '@kehto/runtime';
-import { NostrFilter, NostrEvent, EventTemplate } from '@napplet/core';
+import { IdentityGetProfileMessage, IdentityGetProfileResultMessage, IdentityGetFollowsMessage, IdentityGetFollowsResultMessage, IdentityGetListMessage, IdentityGetListResultMessage, IdentityGetZapsMessage, IdentityGetZapsResultMessage, IdentityGetMutesMessage, IdentityGetMutesResultMessage, IdentityGetBlockedMessage, IdentityGetBlockedResultMessage, IdentityGetBadgesMessage, IdentityGetBadgesResultMessage } from '@napplet/nap/identity/types';
+import { NostrFilter, NostrEvent, EventTemplate, LinkOpenOptions, LinkOpenResult, ListSupport, ListRef, ListItem, ListOptions, ListMutationResult, SerialOpenRequest, SerialOpenResult, BleOpenRequest, BleOpenResult, BleService, BleAttribute, BleWriteOptions, WebrtcEvent, WebrtcOpenRequest, WebrtcOpenResult, CommonProfileTarget, CommonProfileResult, CommonFollowsResult, CommonActionResult, CommonReaction, CommonReportTarget, CommonReportReason } from '@napplet/core';
 import { MediaMetadata, MediaAction } from '@napplet/nap/media/types';
 export { MediaAction } from '@napplet/nap/media/types';
 import { NotifySendMessage } from '@napplet/nap/notify/types';
@@ -189,11 +190,12 @@ declare function createNotificationService(options?: NotificationServiceOptions)
  *
  * Handles 9 identity.* request types from @napplet/nap/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. Host apps plug real backends via
- * runtime.registerService('identity', realHandler).
+ * remaining read-only queries can be backed by optional host providers. When a
+ * provider is absent, the service keeps returning spec-shaped empty results.
  */
 
+/** A value that may be returned synchronously or through a Promise. */
+type MaybePromise<T> = T | Promise<T>;
 /**
  * Options for creating the identity service.
  *
@@ -212,14 +214,75 @@ interface IdentityServiceOptions {
      * availability can change dynamically.
      */
     getSigner: () => Signer | null;
+    /**
+     * Optional host-backed profile lookup for the current user.
+     *
+     * Kehto does not query relays itself; hosts that already maintain kind-0
+     * metadata can provide it here without replacing the whole identity service.
+     *
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getProfile request envelope.
+     * @returns Profile metadata, or null when unavailable.
+     */
+    getProfile?: (pubkey: string, message: IdentityGetProfileMessage) => MaybePromise<IdentityGetProfileResultMessage['profile']>;
+    /**
+     * Optional host-backed follow-list lookup for the current user.
+     *
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getFollows request envelope.
+     * @returns Hex-encoded followed pubkeys.
+     */
+    getFollows?: (pubkey: string, message: IdentityGetFollowsMessage) => MaybePromise<IdentityGetFollowsResultMessage['pubkeys']>;
+    /**
+     * Optional host-backed categorized-list lookup for the current user.
+     *
+     * @param listType - Requested list category from the wire envelope.
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getList request envelope.
+     * @returns List entries.
+     */
+    getList?: (listType: string, pubkey: string, message: IdentityGetListMessage) => MaybePromise<IdentityGetListResultMessage['entries']>;
+    /**
+     * Optional host-backed zap receipt lookup for the current user.
+     *
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getZaps request envelope.
+     * @returns Zap receipts.
+     */
+    getZaps?: (pubkey: string, message: IdentityGetZapsMessage) => MaybePromise<IdentityGetZapsResultMessage['zaps']>;
+    /**
+     * Optional host-backed mute-list lookup for the current user.
+     *
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getMutes request envelope.
+     * @returns Hex-encoded muted pubkeys.
+     */
+    getMutes?: (pubkey: string, message: IdentityGetMutesMessage) => MaybePromise<IdentityGetMutesResultMessage['pubkeys']>;
+    /**
+     * Optional host-backed block-list lookup for the current user.
+     *
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getBlocked request envelope.
+     * @returns Hex-encoded blocked pubkeys.
+     */
+    getBlocked?: (pubkey: string, message: IdentityGetBlockedMessage) => MaybePromise<IdentityGetBlockedResultMessage['pubkeys']>;
+    /**
+     * Optional host-backed badge lookup for the current user.
+     *
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getBadges request envelope.
+     * @returns Badges awarded to the user.
+     */
+    getBadges?: (pubkey: string, message: IdentityGetBadgesMessage) => MaybePromise<IdentityGetBadgesResultMessage['badges']>;
 }
 /**
  * Create an identity service that handles NIP-5D identity.* envelope messages.
  *
  * Supports the 9 read-only identity.* request types from @napplet/nap/identity.
  * The two 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.
+ * caller-supplied signer; the remaining read-only queries resolve through
+ * optional host providers or return default/empty payloads with spec-correct
+ * envelope shapes so napplets always receive a result envelope.
  *
  * @param options - Identity service configuration (getSigner)
  * @returns A ServiceHandler ready for runtime.registerService('identity', handler)
@@ -1343,11 +1406,12 @@ declare function createConfigService(options: ConfigServiceOptions): ConfigServi
  *
  * Shell-side reference implementation for the canonical NAP-RESOURCE wire
  * protocol (`internal-resource.ts` in @kehto/shell/src/types; kehto-internal
- * model per PROJECT.md Decision #31 — diverges from upstream `@napplet/nap/
- * resource` in field names + error vocabulary). Handles the canonical
- * 4-message protocol:
- *   Inbound:  resource.bytes, resource.cancel
- *   Outbound: resource.bytes.result, resource.bytes.error
+ * model per PROJECT.md Decision #31. Kehto keeps legacy single-fetch fields
+ * for existing callers and also emits the current NAP-RESOURCE fields.
+ * Handles:
+ *   Inbound:  resource.bytes, resource.bytesMany, resource.cancel
+ *   Outbound: resource.bytes.result, resource.bytes.error,
+ *             resource.bytesMany.result, resource.bytesMany.error
  *
  * ──────────────────────── SCOPE BOUNDARY (RESOURCE-01) ────────────────────────
  * NAP-RESOURCE is an **authenticated fetch proxy** — read-only, atomic.
@@ -1454,10 +1518,8 @@ type ResourceService = ServiceHandler;
 /**
  * Create a NAP-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).
+ * Implements the NAP-RESOURCE request/response protocol: `resource.bytes`,
+ * `resource.bytesMany`, `resource.cancel`, and their result/error envelopes.
  *
  * 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
@@ -2338,4 +2400,222 @@ interface ManifestArchetypeInput {
  */
 declare function manifestToIntentCatalogEntry(manifest: ManifestArchetypeInput): IntentCatalogEntry;
 
-export { type AudioServiceOptions, type AudioSource, type CacheServiceOptions, type CatalogIntentResolver, type CatalogIntentResolverOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type HostCacheBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityServiceOptions, type IntentArchetypeSupport, type IntentAvailability, type IntentBehavior, type IntentCandidate, type IntentCatalogEntry, type IntentHandlerPreference, type IntentOpenParams, type IntentRequest, type IntentResolver, type IntentResolverContext, type IntentResult, type IntentServiceOptions, type IntentWindowController, type KeysServiceOptions, type ManifestArchetypeInput, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type NostrTag, 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 RailServerConfig, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceService, type ResourceServiceOptions, type SignEvent, type ThemeService, type ThemeServiceOptions, type UploadDimensions, type UploadRail, type UploadRequest, type UploadResult, type UploadServiceOptions, type UploadState, type UploadStatus, type Uploader, type UploaderContext, createAudioService, createBrowserMediaBridge, createCacheService, createCatalogIntentResolver, createConfigService, createCoordinatedRelay, createHttpUploader, createIdentityService, createIntentService, createKeysService, createMediaService, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createThemeService, createUploadService, manifestToIntentCatalogEntry };
+/**
+ * link-service.ts — NAP-LINK reference service.
+ *
+ * Shell-mediated user-visible navigation. The napplet requests `link.open`;
+ * the shell validates policy and hands navigation to a host-owned context.
+ */
+
+/**
+ * Host context passed to {@link LinkServiceOptions.open}.
+ */
+interface LinkOpenContext {
+    /** Window id of the requesting napplet. */
+    windowId: string;
+    /** Parsed absolute URL after validation. */
+    url: URL;
+    /** Optional untrusted napplet display hints. */
+    options?: LinkOpenOptions;
+}
+/**
+ * Options for {@link createLinkService}.
+ */
+interface LinkServiceOptions {
+    /**
+     * Protocols allowed before host policy runs. Defaults to `http:` and `https:`.
+     */
+    allowedProtocols?: readonly string[];
+    /**
+     * Host-owned opener. Return `{ status: "opened" }` after handing navigation
+     * to the host context, or `{ status: "denied" }` to reject by policy/user.
+     * When omitted, all otherwise-valid URLs are denied.
+     */
+    open?: (context: LinkOpenContext) => LinkOpenResult | Promise<LinkOpenResult>;
+}
+/**
+ * Create the NAP-LINK reference service.
+ *
+ * @param options - Host policy and opener hooks for link.open requests.
+ * @returns A runtime service handler for the `link` domain.
+ *
+ * @example
+ * ```ts
+ * const service = createLinkService({
+ *   open: ({ url }) => ({ status: url.protocol === 'https:' ? 'opened' : 'denied' }),
+ * });
+ * ```
+ */
+declare function createLinkService(options?: LinkServiceOptions): ServiceHandler;
+
+/**
+ * lists-service.ts — NAP-LISTS reference service.
+ *
+ * Shell-mediated NIP-51 list metadata and mutation hooks. The napplet requests
+ * `lists.*`; the shell owns list lookup, validation, signing, publishing, and
+ * private-item policy.
+ */
+
+/** Context passed to host-provided NAP-LISTS hooks. */
+interface ListsServiceContext {
+    /** Window id of the requesting napplet. */
+    windowId: string;
+}
+/** Options for {@link createListsService}. */
+interface ListsServiceOptions {
+    /** Host-owned supported list metadata. */
+    supported?: (context: ListsServiceContext) => readonly ListSupport[] | Promise<readonly ListSupport[]>;
+    /** Host-owned add mutation. */
+    add?: (list: ListRef, items: readonly ListItem[], options: ListOptions | undefined, context: ListsServiceContext) => ListMutationResult | Promise<ListMutationResult>;
+    /** Host-owned remove mutation. */
+    remove?: (list: ListRef, items: readonly ListItem[], options: ListOptions | undefined, context: ListsServiceContext) => ListMutationResult | Promise<ListMutationResult>;
+}
+/**
+ * Create the NAP-LISTS reference service.
+ *
+ * @param options - Host list metadata and mutation hooks for lists.* requests.
+ * @returns A runtime service handler for the `lists` domain.
+ */
+declare function createListsService(options?: ListsServiceOptions): ServiceHandler;
+
+/**
+ * serial-service.ts — NAP-SERIAL reference service.
+ *
+ * Shell-mediated serial sessions. The napplet requests `serial.*`; the shell
+ * owns device selection, permissions, session handles, reads, write ordering,
+ * close events, and policy.
+ */
+
+/** Context passed to host-provided NAP-SERIAL hooks. */
+interface SerialServiceContext {
+    /** Window id of the requesting napplet. */
+    windowId: string;
+}
+/** Options for {@link createSerialService}. */
+interface SerialServiceOptions {
+    /** Host-owned serial open hook. */
+    open?: (request: SerialOpenRequest, context: SerialServiceContext) => SerialOpenResult | Promise<SerialOpenResult>;
+    /** Host-owned serial write hook. */
+    write?: (sessionId: string, data: readonly number[], context: SerialServiceContext) => void | Promise<void>;
+    /** Host-owned serial close hook. */
+    close?: (sessionId: string, reason: string | undefined, context: SerialServiceContext) => void | Promise<void>;
+    /** Optional host cleanup when a napplet window is destroyed. */
+    destroyWindow?: (windowId: string) => void;
+}
+/**
+ * Create the NAP-SERIAL reference service.
+ *
+ * @param options - Host serial session hooks for serial.* requests.
+ * @returns A runtime service handler for the `serial` domain.
+ */
+declare function createSerialService(options?: SerialServiceOptions): ServiceHandler;
+
+/**
+ * ble-service.ts — NAP-BLE reference service.
+ *
+ * Shell-mediated BLE/GATT sessions. The napplet requests `ble.*`; the shell
+ * owns chooser UI, permissions, GATT handles, notifications, and policy.
+ */
+
+/** Context passed to host-provided NAP-BLE hooks. */
+interface BleServiceContext {
+    /** Window id of the requesting napplet. */
+    windowId: string;
+}
+/** Options for {@link createBleService}. */
+interface BleServiceOptions {
+    /** Host-owned BLE open hook. */
+    open?: (request: BleOpenRequest, context: BleServiceContext) => BleOpenResult | Promise<BleOpenResult>;
+    /** Host-owned GATT service listing hook. */
+    services?: (sessionId: string, context: BleServiceContext) => BleService[] | Promise<BleService[]>;
+    /** Host-owned GATT read hook. */
+    read?: (sessionId: string, target: BleAttribute, context: BleServiceContext) => number[] | Promise<number[]>;
+    /** Host-owned GATT write hook. */
+    write?: (sessionId: string, target: BleAttribute, data: readonly number[], options: BleWriteOptions | undefined, context: BleServiceContext) => void | Promise<void>;
+    /** Host-owned notification subscription hook. */
+    subscribe?: (sessionId: string, target: BleAttribute, context: BleServiceContext) => void | Promise<void>;
+    /** Host-owned notification unsubscribe hook. */
+    unsubscribe?: (sessionId: string, target: BleAttribute, context: BleServiceContext) => void | Promise<void>;
+    /** Host-owned BLE close hook. */
+    close?: (sessionId: string, reason: string | undefined, context: BleServiceContext) => void | Promise<void>;
+    /** Optional host cleanup when a napplet window is destroyed. */
+    destroyWindow?: (windowId: string) => void;
+}
+/**
+ * Create the NAP-BLE reference service.
+ *
+ * @param options - Host BLE session hooks for ble.* requests.
+ * @returns A runtime service handler for the `ble` domain.
+ */
+declare function createBleService(options?: BleServiceOptions): ServiceHandler;
+
+/**
+ * webrtc-service.ts — NAP-WEBRTC reference service.
+ *
+ * Shell-mediated WebRTC sessions. The napplet requests `webrtc.*`; the shell
+ * owns signaling, signing/encryption, SDP, ICE, peer connections, and policy.
+ */
+
+/** Context passed to host-provided NAP-WEBRTC hooks. */
+interface WebrtcServiceContext {
+    /** Window id of the requesting napplet. */
+    windowId: string;
+    /** Emit a runtime-owned WebRTC event back to the requesting napplet. */
+    emit(event: WebrtcEvent): void;
+}
+/** Options for {@link createWebrtcService}. */
+interface WebrtcServiceOptions {
+    /** Host-owned WebRTC open hook. */
+    open?: (request: WebrtcOpenRequest, context: WebrtcServiceContext) => WebrtcOpenResult | Promise<WebrtcOpenResult>;
+    /** Host-owned WebRTC send hook. */
+    send?: (sessionId: string, payload: unknown, context: WebrtcServiceContext) => void | Promise<void>;
+    /** Host-owned WebRTC close hook. */
+    close?: (sessionId: string, reason: string | undefined, context: WebrtcServiceContext) => void | Promise<void>;
+    /** Optional host cleanup when a napplet window is destroyed. */
+    destroyWindow?: (windowId: string) => void;
+}
+/**
+ * Create the NAP-WEBRTC reference service.
+ *
+ * @param options - Host WebRTC session hooks for webrtc.* requests.
+ * @returns A runtime service handler for the `webrtc` domain.
+ */
+declare function createWebrtcService(options?: WebrtcServiceOptions): ServiceHandler;
+
+/**
+ * common-service.ts — NAP-COMMON reference service.
+ *
+ * Shell-mediated public NIP-19 helpers and common social actions. The napplet
+ * requests `common.*`; the shell owns identity, consent, event construction,
+ * signing, publishing, relay access, and NIP-19 handling.
+ */
+
+/** Context passed to host-provided NAP-COMMON hooks. */
+interface CommonServiceContext {
+    /** Window id of the requesting napplet. */
+    windowId: string;
+}
+/** Options for {@link createCommonService}. */
+interface CommonServiceOptions {
+    /** Host-owned profile lookup. */
+    getProfile?: (target: CommonProfileTarget, context: CommonServiceContext) => CommonProfileResult | Promise<CommonProfileResult>;
+    /** Host-owned current-user follows lookup. */
+    follows?: (context: CommonServiceContext) => CommonFollowsResult | Promise<CommonFollowsResult>;
+    /** Host-owned follow action. */
+    follow?: (pubkeys: string[], context: CommonServiceContext) => CommonActionResult | Promise<CommonActionResult>;
+    /** Host-owned unfollow action. */
+    unfollow?: (pubkeys: string[], context: CommonServiceContext) => CommonActionResult | Promise<CommonActionResult>;
+    /** Host-owned reaction action. */
+    react?: (targetEventId: string, reaction: CommonReaction, customEmojiHref: string | undefined, context: CommonServiceContext) => CommonActionResult | Promise<CommonActionResult>;
+    /** Host-owned report action. */
+    report?: (target: CommonReportTarget, reason: CommonReportReason, text: string, context: CommonServiceContext) => CommonActionResult | Promise<CommonActionResult>;
+}
+/**
+ * Create the NAP-COMMON reference service.
+ *
+ * @param options - Host profile/social hooks for common.* requests.
+ * @returns A runtime service handler for the `common` domain.
+ */
+declare function createCommonService(options?: CommonServiceOptions): ServiceHandler;
+
+export { type AudioServiceOptions, type AudioSource, type BleServiceContext, type BleServiceOptions, type CacheServiceOptions, type CatalogIntentResolver, type CatalogIntentResolverOptions, type CommonServiceContext, type CommonServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type HostCacheBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityServiceOptions, type IntentArchetypeSupport, type IntentAvailability, type IntentBehavior, type IntentCandidate, type IntentCatalogEntry, type IntentHandlerPreference, type IntentOpenParams, type IntentRequest, type IntentResolver, type IntentResolverContext, type IntentResult, type IntentServiceOptions, type IntentWindowController, type KeysServiceOptions, type LinkOpenContext, type LinkServiceOptions, type ListsServiceContext, type ListsServiceOptions, type ManifestArchetypeInput, type MaybePromise, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type NostrTag, 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 RailServerConfig, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceService, type ResourceServiceOptions, type SerialServiceContext, type SerialServiceOptions, type SignEvent, type ThemeService, type ThemeServiceOptions, type UploadDimensions, type UploadRail, type UploadRequest, type UploadResult, type UploadServiceOptions, type UploadState, type UploadStatus, type Uploader, type UploaderContext, type WebrtcServiceContext, type WebrtcServiceOptions, createAudioService, createBleService, createBrowserMediaBridge, createCacheService, createCatalogIntentResolver, createCommonService, createConfigService, createCoordinatedRelay, createHttpUploader, createIdentityService, createIntentService, createKeysService, createLinkService, createListsService, createMediaService, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createSerialService, createThemeService, createUploadService, createWebrtcService, manifestToIntentCatalogEntry };