@kehto/services 0.8.0 → 0.10.0

package/README.md

@@ -3,7 +3,7 @@
 Reference service handlers for the napplet protocol — audio, notifications, identity, relay pool, cache, keys, media, notify, theme.
 
 > **Alpha status:** Kehto is an early runtime implementation for a draft NIP-5D
-> protocol. NUB contracts and service envelopes are not final; treat these
+> protocol. NAP contracts and service envelopes are not final; treat these
 > handlers as reference implementations for the current draft.
 
 ## Install
@@ -22,7 +22,7 @@ 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.*` NUB) coexists with the legacy `createNotificationService` (ifc-emit `notifications:*` channel). Both may be registered simultaneously while hosts migrate.
+- `createNotifyService` (NIP-5D `notify.*` NAP) coexists with the legacy `createNotificationService` (ifc-emit `notifications:*` channel). Both may be registered simultaneously while hosts migrate.
 
 ## Quick Start
 
@@ -51,7 +51,7 @@ runtime.registerService(
 
 ## Keys Service
 
-Reference keyboard / chord backend for the `keys.*` NIP-5D NUB. By default attaches a single `document`-level `keydown` listener that matches incoming events against registered chord subscriptions and delivers a `keys.action` push envelope back to the owning napplet. Implement the [`HostKeysBridge`](#hostkeysbridge-interface) interface to swap in OS-level backends (Electron `globalShortcut`, Tauri `GlobalShortcut`).
+Reference keyboard / chord backend for the `keys.*` NIP-5D NAP. By default attaches a single `document`-level `keydown` listener that matches incoming events against registered chord subscriptions and delivers a `keys.action` push envelope back to the owning napplet. Implement the [`HostKeysBridge`](#hostkeysbridge-interface) interface to swap in OS-level backends (Electron `globalShortcut`, Tauri `GlobalShortcut`).
 
 ### Factory
 
@@ -85,7 +85,7 @@ export interface HostKeysBridge {
    *   - 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
+   *   - accept the string chord format documented by @napplet/nap/keys
    *     (e.g. `'Ctrl+Shift+K'`, `'Cmd+P'`)
    */
   subscribe(chord: string, callback: (event: KeyboardEvent | HostKeyEvent) => void): () => void;
@@ -154,7 +154,7 @@ runtime.registerService('keys', createKeysService({ hostBridge: electronBridge }
 
 Plug a `HostKeysBridge` when the default document listener is insufficient: Electron or Tauri apps that need to register OS-level global hotkeys (chords delivered even when the host window is not focused), native shells that route chords through a platform-specific hotkey manager (macOS Carbon, Linux X11 grab, Windows RegisterHotKey), or test harnesses that inject synthetic events through a controlled `EventTarget`. The bridge owns subscription lifecycle; the service retains per-window bookkeeping (so `onWindowDestroyed` cleanup stays identical across paths).
 
-See the demo: [`apps/playground/napplets/hotkey-chord/src/main.ts`](../../apps/playground/napplets/hotkey-chord/src/main.ts) (the Phase 26 end-to-end exemplar — uses `@napplet/sdk` `keys.registerAction` + `keys.onAction` against the real backend).
+A napplet drives this end to end via `@napplet/sdk` — `keys.registerAction` to claim a chord and `keys.onAction` to receive dispatches against the real backend.
 
 ### Reserved Chords
 
@@ -214,7 +214,7 @@ runtime.registerService('keys', keys);
 
 ## Media Service
 
-Reference media backend for the `media.*` NIP-5D NUB. By default mirrors session metadata + playback state to `navigator.mediaSession` via the DOM `MediaSession` API and installs `setActionHandler` callbacks that emit `media.command` push envelopes on OS transport events (play / pause / next / previous / seek). Implement the [`HostMediaBridge`](#hostmediabridge-interface) interface to swap in native backends (Electron bridge, MPRIS on Linux, MediaRemote on macOS).
+Reference media backend for the `media.*` NIP-5D NAP. By default mirrors session metadata + playback state to `navigator.mediaSession` via the DOM `MediaSession` API and installs `setActionHandler` callbacks that emit `media.command` push envelopes on OS transport events (play / pause / next / previous / seek). Implement the [`HostMediaBridge`](#hostmediabridge-interface) interface to swap in native backends (Electron bridge, MPRIS on Linux, MediaRemote on macOS).
 
 ### Factory
 
@@ -344,31 +344,31 @@ runtime.registerService('media', createMediaService({ hostBridge: electronBridge
 
 Plug a `HostMediaBridge` when `navigator.mediaSession` is insufficient: Electron apps that need to route transport events through the main process (lock-screen integration on Windows, Now Playing integration on macOS), Linux shells that speak MPRIS over D-Bus, native mobile wrappers that forward to AVPlayer / ExoPlayer, or test harnesses that record action events without touching the DOM. The bridge owns metadata/state mirroring and OS action routing; the service retains per-session bookkeeping (sessionRegistry + per-window send handles) so `media.command` dispatch semantics stay identical across paths.
 
-See the demo: [`apps/playground/napplets/media-controller/src/main.ts`](../../apps/playground/napplets/media-controller/src/main.ts) (the Phase 27 end-to-end exemplar — uses `@napplet/nub/media` `mediaCreateSession({ owner: 'napplet', ... })` + `mediaReportState` + `mediaOnCommand` against the real backend).
+A napplet drives this end to end via `@napplet/nap/media` — `mediaCreateSession({ owner: 'napplet', ... })`, `mediaReportState`, and `mediaOnCommand` against the real backend.
 
 ## Public API
 
 Each factory returns a `ServiceHandler` registrable via `runtime.registerService()`. The bullets below note the current NIP-5D domain the handler owns and the ACL capability napplets need in order to reach it.
 
-### Identity NUB
+### Identity NAP
 - `createIdentityService` — `identity.*` reads (`identity:read`). No signing surface; shell mediates signing internally.
 
-### Notify NUB
+### Notify NAP
 - `createNotifyService` — canonical `notify.*` envelopes (`notify:send` / `notify:channel`).
 - `createNotificationService` — legacy ifc-emit `notifications:*` channel; coexists with `createNotifyService` until retired.
 
-### Relay NUB
+### Relay NAP
 - `createRelayPoolService` — `relay.publish`, `relay.publishEncrypted`, `relay.subscribe` fan-out (`relay:read` / `relay:write`).
 - `createCacheService` — offline event cache (`cache:read` / `cache:write`).
 - `createCoordinatedRelay` — composite service that bundles relay-pool + cache with read-through behavior.
 
-### Keys NUB
+### Keys NAP
 - `createKeysService` — `keys.registerAction` / `keys.unregisterAction` / `keys.forward` + `keys.action` push envelopes (`keys:forward`). Document-level chord listener by default; implement the `HostKeysBridge` interface to swap in Electron / Tauri / OS-level backends. See [Keys Service](#keys-service) for the full contract.
 
-### Media NUB
+### 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.
 
-### Theme NUB
+### Theme NAP
 - `createThemeService` — `theme.get` + `theme.changed` fan-out (`theme:read`). Returns a `ThemeService` with `publishTheme()` / `setTheme()` utilities for host-side updates.
 
 ### Audio (legacy ifc-emit)

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { ServiceHandler, Signer } from '@kehto/runtime';
 import { NostrFilter, NostrEvent, 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';
+import { MediaMetadata, MediaAction } from '@napplet/nap/media/types';
+export { MediaAction } from '@napplet/nap/media/types';
+import { NotifySendMessage } from '@napplet/nap/notify/types';
+import { Theme, ThemeChangedMessage } from '@napplet/nap/theme/types';
+import { ConfigSchemaErrorCode, ConfigValues, NappletConfigSchema } from '@napplet/nap/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';
 
 /**
@@ -187,7 +187,7 @@ declare function createNotificationService(options?: NotificationServiceOptions)
  * (An `identity.decrypt` capability was briefly added in v1.8 and removed as a
  * spec violation; decryption belongs to the runtime, inline over the wire.)
  *
- * Handles 9 identity.* request types from @napplet/nub/identity. getPublicKey
+ * 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
@@ -216,7 +216,7 @@ interface IdentityServiceOptions {
 /**
  * Create an identity service that handles NIP-5D identity.* envelope messages.
  *
- * Supports the 9 read-only identity.* request types from @napplet/nub/identity.
+ * 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.
@@ -472,7 +472,7 @@ declare function createCoordinatedRelay(options: CoordinatedRelayOptions): Servi
 /**
  * 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/nap/keys:
  *   - keys.forward          -> invokes options.onForward (hotkey passthrough, fire-and-forget)
  *   - keys.registerAction   -> parses action.defaultKey into a chord spec, stores the
  *                              subscription in an in-memory registry keyed by actionId,
@@ -491,14 +491,14 @@ declare function createCoordinatedRelay(options: CoordinatedRelayOptions): Servi
  *
  * 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
+ * via the per-window `send` callback — this is the canonical @napplet/nap/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
+ * Field-name translation: @napplet/nap/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
@@ -567,7 +567,7 @@ interface HostKeysBridge {
      *   - 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
+     *   - accept the string chord format documented by @napplet/nap/keys
      *     (e.g. `'Ctrl+Shift+K'`, `'Cmd+P'`)
      */
     subscribe(chord: string, callback: (event: KeyboardEvent | HostKeyEvent) => void): () => void;
@@ -639,7 +639,7 @@ interface KeysServiceOptions {
      */
     hostBridge?: HostKeysBridge;
     /**
-     * Optional set of shell-reserved chords. Strings in the `@napplet/nub/keys`
+     * Optional set of shell-reserved chords. Strings in the `@napplet/nap/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`
@@ -748,7 +748,7 @@ declare function createBrowserMediaBridge(opts?: {
  * media-service.ts — NIP-5D media NUB reference service (navigator.mediaSession
  * reference implementation).
  *
- * Handles the napplet-owned subset of @napplet/nub/media:
+ * Handles the napplet-owned subset of @napplet/nap/media:
  *   media.session.create (result), media.session.update, media.session.destroy,
  *   media.state, media.capabilities.
  *
@@ -763,7 +763,7 @@ declare function createBrowserMediaBridge(opts?: {
  * 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
+ * media.command envelope to the owning napplet — that is the @napplet/nap/media
  * MediaCommandMessage shape consumed by the SDK's mediaOnCommand() helper.
  *
  * NAP-MEDIA now distinguishes napplet-owned playback from shell-owned
@@ -794,7 +794,7 @@ declare function createBrowserMediaBridge(opts?: {
  *
  * 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/nap/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.
  *
@@ -963,7 +963,7 @@ interface MediaServiceOptions {
  * 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/nap/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.
@@ -993,7 +993,7 @@ declare function createMediaService(options?: MediaServiceOptions): ServiceHandl
 /**
  * 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/nap/notify`:
  *   - `notify.send`                -> `notify.send.result` (shell-assigned id)
  *   - `notify.dismiss`             -> fire-and-forget
  *   - `notify.badge`               -> fire-and-forget
@@ -1008,9 +1008,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/nap/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/nap/notify messages
  * land here; the legacy ifc-emit topic path remains untouched.
  *
  * Shell -> napplet push messages (`notify.action`, `notify.clicked`,
@@ -1054,7 +1054,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/nap/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
@@ -1076,7 +1076,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/nap/theme:
  *   - `theme.get`         -> `theme.get.result { theme }` (current theme)
  *
  * Exposes a host-facing `publishTheme(theme)` handle that:
@@ -1181,7 +1181,7 @@ declare function createThemeService(options?: ThemeServiceOptions): ThemeService
  * 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
+ * protocol (`@napplet/nap/config`, published at `^0.3.0`). Handles the full
  * 8-message discriminated union: 5 napplet→shell request types + 3
  * shell→napplet result/push types.
  *
@@ -1304,7 +1304,7 @@ interface ConfigService {
 /**
  * Create a NUB-CONFIG reference service.
  *
- * Shell-writes, napplet-reads. Handles the full `@napplet/nub/config` wire
+ * Shell-writes, napplet-reads. Handles the full `@napplet/nap/config` wire
  * protocol: `config.get` (correlated snapshot), `config.subscribe` /
  * `config.unsubscribe` (live push stream), `config.registerSchema` (optional
  * schema registration + Core Subset validation), `config.openSettings`
@@ -1343,7 +1343,7 @@ declare function createConfigService(options: ConfigServiceOptions): ConfigServi
  *
  * 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/
+ * 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
@@ -1981,4 +1981,361 @@ interface HttpUploaderOptions {
  */
 declare function createHttpUploader(options: HttpUploaderOptions): Uploader;
 
-export { type AudioServiceOptions, type AudioSource, type CacheServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type HostCacheBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityServiceOptions, type KeysServiceOptions, 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, createConfigService, createCoordinatedRelay, createHttpUploader, createIdentityService, createKeysService, createMediaService, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createThemeService, createUploadService };
+/**
+ * intent-types.ts — NAP-INTENT (archetype intent dispatch) value types.
+ *
+ * Kehto-internal model for the NAP-INTENT wire contract (upstream draft:
+ * napplet/nubs NAP-INTENT, namespace `window.napplet.intent`). The installed
+ * `@napplet/core` peer predates these types, so — as with {@link ./cvm-types} —
+ * kehto defines them here, wire-compatible with the upstream shapes, rather
+ * than redefining the generic NIP-5D envelope.
+ *
+ * NAP-INTENT standardizes the *envelope*, not the payload. `archetype` is the
+ * routing axis (which role, whose default), `protocol` is the parsing axis
+ * (which NAP-N wire format shapes `payload`); the two are orthogonal.
+ *
+ * @packageDocumentation
+ */
+/**
+ * How the shell should pick the handling napplet for an intent.
+ *
+ * - `"default"` — route to the user's default handler for the archetype.
+ * - `"choose"`  — prompt the user with an "open with…" chooser.
+ * - any other string — a specific napplet dTag (cross-napplet targeting; the
+ *   shell SHOULD require the user to have authorized this for the caller).
+ */
+type IntentHandlerPreference = 'default' | 'choose' | (string & {});
+/** Window-behavior hints carried with an intent invoke. */
+interface IntentBehavior {
+    /** Bring the handler window to the foreground. */
+    focus?: boolean;
+    /** Force a new window rather than reusing an existing handler instance. */
+    newWindow?: boolean;
+    /** Prefer reusing an already-open handler instance when one exists. */
+    reuse?: boolean;
+}
+/** A request to dispatch an action to a napplet of a given archetype. */
+interface IntentRequest {
+    /** Role slug, e.g. `"note"` (see the archetype registry). */
+    archetype: string;
+    /** Verb, default `"open"` (e.g. `"open"` | `"edit"` | `"pick"` | `"share"`). */
+    action?: string;
+    /** NAP-N id shaping `payload`; omit to use the archetype's recommended default. */
+    protocol?: string;
+    /** Opaque payload, typed by `protocol`. */
+    payload?: unknown;
+    /** Handler-selection preference. */
+    handler?: IntentHandlerPreference;
+    /** Window-behavior hints. */
+    behavior?: IntentBehavior;
+}
+/** A napplet that can fulfill an archetype, sourced from the manifest catalog. */
+interface IntentCandidate {
+    /** dTag of the napplet that can fulfill the archetype. */
+    dTag: string;
+    /** Human-readable title from the manifest. */
+    title?: string;
+    /** Verbs this candidate supports for the archetype. */
+    actions: string[];
+    /** NAP-N ids this candidate accepts for the archetype. */
+    protocols: string[];
+    /** Whether this candidate is the user/runtime default for the archetype. */
+    isDefault?: boolean;
+}
+/** Availability of an archetype, sourced from the installed-napplet catalog. */
+interface IntentAvailability {
+    /** The archetype this availability describes. */
+    archetype: string;
+    /** True when at least one installed napplet fulfills the archetype. */
+    available: boolean;
+    /** Candidate napplets that fulfill the archetype (from manifests, not instances). */
+    candidates: IntentCandidate[];
+    /** True when a user/runtime default handler is set for the archetype. */
+    hasDefault: boolean;
+}
+/** The result of an intent invocation. */
+interface IntentResult {
+    /** Whether the intent was dispatched successfully. */
+    ok: boolean;
+    /** The requested archetype, echoed back. */
+    archetype: string;
+    /** The resolved action (defaults to `"open"` when the request omits it). */
+    action: string;
+    /** True when a handler accepted the dispatch. */
+    handled: boolean;
+    /** dTag of the napplet that handled the intent, when one did. */
+    handler?: string;
+    /** Window id the handler was created or focused in. */
+    windowId?: string;
+    /** The wire format actually used to deliver `payload`. */
+    protocol?: string;
+    /** Error reason when the intent could not be fulfilled. */
+    error?: string;
+}
+
+/**
+ * intent-service.ts — NAP-INTENT (archetype intent dispatch) reference service.
+ *
+ * Shell-side handler for the NAP-INTENT wire protocol. It is a pure envelope
+ * router: it validates `intent.*` envelopes, delegates archetype resolution,
+ * default handling, window lifecycle, and payload delivery to an injected
+ * {@link IntentResolver}, and posts the correlated result / push messages
+ * (echoing the request `id`) back to the napplet.
+ *
+ * The resolver is injected (options-as-bridge) so this service has no shell or
+ * window-manager dependency and is fully unit-testable. A concrete
+ * catalog-backed resolver ships alongside as {@link createCatalogIntentResolver}.
+ *
+ * ──────────────────────────── Responsibilities ────────────────────────────
+ *   Inbound:  intent.invoke, intent.available, intent.handlers
+ *   Outbound: intent.invoke.result, intent.available.result,
+ *             intent.handlers.result, intent.changed
+ *
+ * The shell owns archetype→handler resolution, the user's default-handler
+ * preference, the "open with…" chooser, and window creation/focus — all behind
+ * the {@link IntentResolver}. This service only marshals the wire protocol and
+ * fans `intent.changed` pushes out to the napplets it has served.
+ *
+ * @example
+ * ```ts
+ * import { createIntentService, createCatalogIntentResolver } from '@kehto/services';
+ *
+ * const resolver = createCatalogIntentResolver({ loadCatalog, windows });
+ * runtime.registerService('intent', createIntentService({ resolver }));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** Context passed to {@link IntentResolver.invoke} for trust/attribution. */
+interface IntentResolverContext {
+    /** Window id of the napplet that issued the request. */
+    windowId: string;
+}
+/**
+ * Abstract intent resolver. Implementors own the installed-napplet catalog,
+ * archetype→handler resolution, the user's default-handler preference, the
+ * "open with…" chooser, window creation/focus, and payload delivery. The
+ * service translates wire envelopes into these calls and back.
+ */
+interface IntentResolver {
+    /**
+     * Resolve `request.archetype` to a handler, create or focus its window, and
+     * deliver `payload`. Returns once the handler is resolved and the window
+     * created; delivery MAY complete asynchronously.
+     */
+    invoke(request: IntentRequest, context: IntentResolverContext): IntentResult | Promise<IntentResult>;
+    /** Report whether the runtime can currently satisfy `archetype`, and how. */
+    available(archetype: string): IntentAvailability | Promise<IntentAvailability>;
+    /** Report availability for every archetype the runtime can currently satisfy. */
+    handlers(): IntentAvailability[] | Promise<IntentAvailability[]>;
+    /**
+     * Register for availability changes (a napplet installed/removed, or a default
+     * handler changed). The service forwards each change to served napplets as an
+     * `intent.changed` push. Returns an unsubscribe handle. Resolvers whose
+     * catalog never changes at runtime MAY omit this.
+     */
+    onChanged?(listener: (availability: IntentAvailability) => void): () => void;
+}
+/** Options for {@link createIntentService}. */
+interface IntentServiceOptions {
+    /** The intent resolver the shell uses to route archetypes. Required. */
+    resolver: IntentResolver;
+}
+/**
+ * Create the NAP-INTENT service handler.
+ *
+ * @param options - Must provide an {@link IntentResolver}.
+ * @returns A `ServiceHandler` ready for `runtime.registerService('intent', handler)`.
+ * @throws If `options.resolver` is missing.
+ */
+declare function createIntentService(options: IntentServiceOptions): ServiceHandler;
+
+/**
+ * catalog-intent-resolver.ts — NAP-INTENT concrete {@link IntentResolver}.
+ *
+ * A reference resolver that satisfies {@link IntentResolver} from an
+ * installed-napplet catalog plus host-supplied policy: the user's
+ * default-handler preference, an optional "open with…" chooser, the archetype's
+ * recommended default protocol, and a window controller that creates or focuses
+ * the handler window and delivers the payload.
+ *
+ * Resolution policy (mirrors an OS implicit-intent + default-app model):
+ *   1. Gather candidates for the archetype from the catalog.
+ *   2. Pick the handler — an explicit `handler` dTag, a user choice
+ *      (`handler: "choose"`), the user's default, the sole candidate, or a
+ *      deterministic first-candidate fallback.
+ *   3. Validate the resolved handler supports the requested `action` and
+ *      `protocol` (or fall back to the archetype's recommended default protocol,
+ *      then the candidate's first accepted protocol).
+ *   4. Open or focus the handler window and return its id.
+ *
+ * The catalog, defaults, chooser, and window controller are all injected, so
+ * this resolver carries no shell, manifest, or DOM dependency and is fully
+ * unit-testable.
+ *
+ * @packageDocumentation
+ */
+
+/** The actions/protocols a napplet fulfills for a single archetype. */
+interface IntentArchetypeSupport {
+    /** Verbs this napplet supports for the archetype (e.g. `["open", "edit"]`). */
+    actions: string[];
+    /** NAP-N protocol ids this napplet accepts for the archetype. */
+    protocols: string[];
+}
+/**
+ * One installed napplet's intent surface, derived from its signed NIP-5A
+ * manifest. Keyed by archetype slug so a single napplet can fulfill several
+ * roles.
+ */
+interface IntentCatalogEntry {
+    /** The napplet's dTag. */
+    dTag: string;
+    /** Human-readable title from the manifest. */
+    title?: string;
+    /** Archetype slug → the actions/protocols this napplet fulfills for it. */
+    archetypes: Record<string, IntentArchetypeSupport>;
+}
+/** Parameters handed to {@link IntentWindowController.open}. */
+interface IntentOpenParams {
+    /** dTag of the resolved handler napplet. */
+    dTag: string;
+    /** The archetype being dispatched. */
+    archetype: string;
+    /** The resolved action (e.g. `"open"`). */
+    action: string;
+    /** The wire format the payload is delivered with, when one was resolved. */
+    protocol?: string;
+    /** The opaque payload to deliver. */
+    payload?: unknown;
+    /** Window-behavior hints from the request. */
+    behavior?: IntentBehavior;
+    /** Window id of the napplet that issued the intent. */
+    callerWindowId: string;
+}
+/** Creates or focuses the handler window and delivers the intent payload. */
+interface IntentWindowController {
+    /**
+     * Create or focus the handler window and deliver `payload` via `protocol`.
+     * Returns the window id the handler was created or focused in.
+     */
+    open(params: IntentOpenParams): {
+        windowId: string;
+    } | Promise<{
+        windowId: string;
+    }>;
+}
+/** Options for {@link createCatalogIntentResolver}. */
+interface CatalogIntentResolverOptions {
+    /** Return the installed-napplet catalog (signed NIP-5A manifests). Required. */
+    loadCatalog(): IntentCatalogEntry[] | Promise<IntentCatalogEntry[]>;
+    /** Window controller used to create/focus the resolved handler's window. Required. */
+    windows: IntentWindowController;
+    /**
+     * The user's default handler dTag for an archetype, or `undefined` when none
+     * is set. Default-handler settings are user state — never set by napplets.
+     */
+    getDefaultHandler?(archetype: string): string | undefined;
+    /**
+     * Resolve a `handler: "choose"` prompt (or a no-default ambiguity) to a dTag.
+     * Returning `undefined` means the user cancelled. When omitted, ambiguous
+     * resolution falls back to the first candidate.
+     */
+    chooseHandler?(archetype: string, candidates: IntentCandidate[], callerWindowId: string): string | undefined | Promise<string | undefined>;
+    /** The archetype's recommended default protocol when the caller omits one. */
+    defaultProtocol?(archetype: string): string | undefined;
+}
+/**
+ * A {@link IntentResolver} backed by a catalog, with a host hook to announce
+ * catalog/default changes.
+ */
+interface CatalogIntentResolver extends IntentResolver {
+    /**
+     * Announce that the catalog or default handler for `archetype` changed. The
+     * resolver recomputes availability and notifies `onChanged` listeners, which
+     * the intent service forwards to napplets as `intent.changed` pushes.
+     */
+    notifyChanged(archetype: string): void;
+}
+/**
+ * Create a catalog-backed NAP-INTENT resolver.
+ *
+ * @param options - Catalog loader and window controller (required) plus
+ *   optional default-handler, chooser, and default-protocol policy hooks.
+ * @returns A {@link CatalogIntentResolver} for `createIntentService({ resolver })`.
+ * @throws If `options.loadCatalog` or `options.windows` is missing.
+ *
+ * @example
+ * ```ts
+ * const resolver = createCatalogIntentResolver({
+ *   loadCatalog: () => installedNapplets,
+ *   windows: { open: ({ dTag }) => ({ windowId: openWindow(dTag) }) },
+ *   getDefaultHandler: (a) => userDefaults[a],
+ * });
+ * ```
+ */
+declare function createCatalogIntentResolver(options: CatalogIntentResolverOptions): CatalogIntentResolver;
+
+/**
+ * manifest-intent-catalog.ts — signed-manifest → NAP-INTENT catalog adapter.
+ *
+ * Adapts a resolved NIP-5A/5D napplet manifest's archetype tags into an
+ * {@link IntentCatalogEntry} — the shape `createCatalogIntentResolver.loadCatalog`
+ * consumes. This lets NAP-INTENT availability and handler candidacy flow from
+ * verified manifest tags rather than host-injected catalog data.
+ *
+ * To avoid a `@kehto/services → @kehto/nip` dependency cycle (services must stay
+ * dependency-light and `@kehto/nip` is a lower-level NIP utility), the adapter
+ * takes a minimal STRUCTURAL input {@link ManifestArchetypeInput} that the
+ * `@kehto/nip/5d` `NappletManifest` satisfies by duck typing — callers pass
+ * `resolved.manifest` directly without any package coupling.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The structural subset of `@kehto/nip/5d` `NappletManifest` the adapter needs.
+ * Intentionally a duck-typed shape so the playground (or any caller) can pass a
+ * resolved manifest without importing `@kehto/nip`.
+ */
+interface ManifestArchetypeInput {
+    /** The napplet's `d` identifier. */
+    dTag: string;
+    /** Optional human-readable title from the manifest. */
+    title?: string;
+    /**
+     * Archetype slugs this napplet fulfills, from the manifest's `archetype` tags;
+     * the optional `nap` is the recommended default wire protocol.
+     */
+    archetypes: Array<{
+        slug: string;
+        nap?: string;
+    }>;
+}
+/**
+ * Map a resolved napplet manifest's archetype data into an
+ * {@link IntentCatalogEntry}.
+ *
+ * Each archetype `{ slug, nap }` becomes a keyed support record where `actions`
+ * defaults to `['open']` (the NAP-INTENT default action — manifests do not
+ * enumerate actions in this phase) and `protocols` is `[nap]` when a NAP-N is
+ * present, else `[]`. Duplicate slugs keep the last occurrence.
+ *
+ * @param manifest - A resolved manifest's structural archetype data.
+ * @returns The `IntentCatalogEntry` for `createCatalogIntentResolver`.
+ *
+ * @example
+ * ```ts
+ * manifestToIntentCatalogEntry({
+ *   dTag: 'profile-viewer',
+ *   title: 'Profile',
+ *   archetypes: [{ slug: 'profile', nap: 'NAP-1' }],
+ * });
+ * // → { dTag: 'profile-viewer', title: 'Profile',
+ * //     archetypes: { profile: { actions: ['open'], protocols: ['NAP-1'] } } }
+ * ```
+ */
+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 };