@kehto/services 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,810 @@
+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';
+
+/**
+ * @kehto/services — Shared types for reference service implementations.
+ *
+ * These types describe the internal state that services manage and expose
+ * to the shell host via callbacks. They are NOT NIP-01 wire types.
+ */
+/**
+ * An active audio source registered by a napplet.
+ *
+ * @example
+ * ```ts
+ * const source: AudioSource = {
+ *   windowId: 'win-1',
+ *   nappletClass: 'music-player',
+ *   title: 'Now Playing',
+ *   muted: false,
+ * };
+ * ```
+ */
+interface AudioSource {
+    /** The napplet window that registered this audio source. */
+    windowId: string;
+    /** The napplet class/type (e.g., 'music-player'). */
+    nappletClass: string;
+    /** Human-readable title for the audio source. */
+    title: string;
+    /** Whether this source is currently muted. */
+    muted: boolean;
+}
+/**
+ * Options for creating an audio service via createAudioService().
+ *
+ * @example
+ * ```ts
+ * const audioService = createAudioService({
+ *   onChange: (sources) => console.log('Audio sources changed:', sources.size),
+ * });
+ * ```
+ */
+interface AudioServiceOptions {
+    /**
+     * Called when the audio source registry changes (register, unregister,
+     * mute, state update). The shell host uses this to update UI.
+     */
+    onChange?: (sources: ReadonlyMap<string, AudioSource>) => void;
+}
+/**
+ * A notification created by a napplet.
+ *
+ * @example
+ * ```ts
+ * const notification: Notification = {
+ *   id: 'notif-1',
+ *   windowId: 'win-1',
+ *   title: 'New Message',
+ *   body: 'You have a new message from Alice',
+ *   read: false,
+ *   createdAt: 1711800000,
+ * };
+ * ```
+ */
+interface Notification {
+    /** Unique notification identifier (generated by the service). */
+    id: string;
+    /** The napplet window that created this notification. */
+    windowId: string;
+    /** Short notification title. */
+    title: string;
+    /** Notification body/description. */
+    body: string;
+    /** Whether the notification has been read/acknowledged. */
+    read: boolean;
+    /** Unix timestamp (seconds) when the notification was created. */
+    createdAt: number;
+}
+/**
+ * Options for creating a notification service via createNotificationService().
+ *
+ * @example
+ * ```ts
+ * const notifService = createNotificationService({
+ *   onChange: (notifications) => console.log('Notifications:', notifications.length),
+ *   maxPerWindow: 50,
+ * });
+ * ```
+ */
+interface NotificationServiceOptions {
+    /**
+     * Called when the notification list changes (create, dismiss, read).
+     * The shell host uses this to update UI (toast, badge, etc.).
+     */
+    onChange?: (notifications: readonly Notification[]) => void;
+    /**
+     * Maximum notifications to retain per window. Oldest are evicted
+     * when the limit is exceeded. Default: 100.
+     */
+    maxPerWindow?: number;
+}
+
+/**
+ * audio-service.ts — Audio source registry as a ServiceHandler.
+ *
+ * Tracks which napplet windows are producing audio. Shell hosts wire this
+ * into the runtime via registerService('audio', createAudioService(opts)).
+ * Browser-agnostic — no DOM, no window, no postMessage.
+ */
+
+/**
+ * Create an audio service handler.
+ *
+ * The audio service is a state registry that tracks active audio sources
+ * per napplet window. Napplets announce audio state via `audio:*` topic
+ * events; the service tracks sources and can relay mute commands back.
+ *
+ * @param options - Optional configuration (onChange callback for UI updates)
+ * @returns A ServiceHandler to register with the runtime
+ *
+ * @example
+ * ```ts
+ * import { createAudioService } from '@kehto/services';
+ *
+ * const audio = createAudioService({
+ *   onChange: (sources) => {
+ *     // Update UI with current audio sources
+ *     for (const [windowId, source] of sources) {
+ *       console.log(`${source.title} (${source.muted ? 'muted' : 'playing'})`);
+ *     }
+ *   },
+ * });
+ *
+ * runtime.registerService('audio', audio);
+ * ```
+ */
+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.
+ *
+ * The notification service is a state registry that tracks notifications
+ * per napplet window. Napplets create and manage notifications via
+ * `notifications:*` topic events; the shell host controls presentation
+ * via the onChange callback.
+ *
+ * @param options - Optional configuration (onChange callback, maxPerWindow limit)
+ * @returns A ServiceHandler to register with the runtime
+ *
+ * @example
+ * ```ts
+ * import { createNotificationService } from '@kehto/services';
+ *
+ * const notifications = createNotificationService({
+ *   onChange: (list) => {
+ *     const unread = list.filter(n => !n.read);
+ *     updateBadge(unread.length);
+ *   },
+ *   maxPerWindow: 50,
+ * });
+ *
+ * runtime.registerService('notifications', notifications);
+ * ```
+ */
+declare function createNotificationService(options?: NotificationServiceOptions): ServiceHandler;
+
+/**
+ * identity-service.ts — NIP-5D identity nub reference service.
+ *
+ * MIGRATION from signer-service (v1.1 -> v1.2):
+ *   - signer.getPublicKey  -> identity.getPublicKey   (same shell state)
+ *   - signer.getRelays     -> identity.getRelays      (same shell state)
+ *   - signer.signEvent     -> DELETED (no napplet-visible path; shell signs
+ *                             internally inside relay.publish)
+ *   - signer.nip04.encrypt/decrypt -> DELETED
+ *   - signer.nip44.encrypt/decrypt -> DELETED (shell encrypts internally
+ *                                      inside relay.publishEncrypted)
+ *
+ * See REQUIREMENTS.md DEPS-03 (Phase 15 changelog).
+ *
+ * Handles 9 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).
+ */
+
+/**
+ * Options for creating the identity service.
+ *
+ * @example
+ * ```ts
+ * const identityService = createIdentityService({
+ *   getSigner: () => window.nostr ?? null,
+ * });
+ * runtime.registerService('identity', identityService);
+ * ```
+ */
+interface IdentityServiceOptions {
+    /**
+     * Return the NIP-07-compatible signer (or null) used to resolve
+     * identity.getPublicKey / identity.getRelays. Called on every request —
+     * availability can change dynamically.
+     */
+    getSigner: () => Signer | null;
+}
+/**
+ * Create an identity service that handles NIP-5D identity.* envelope messages.
+ *
+ * Supports all 9 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.
+ *
+ * @param options - Identity service configuration (getSigner)
+ * @returns A ServiceHandler ready for runtime.registerService('identity', handler)
+ *
+ * @example
+ * ```ts
+ * import { createIdentityService } from '@kehto/services';
+ *
+ * const identity = createIdentityService({
+ *   getSigner: () => mySignerAdapter,
+ * });
+ * runtime.registerService('identity', identity);
+ * ```
+ */
+declare function createIdentityService(options: IdentityServiceOptions): ServiceHandler;
+
+/**
+ * relay-pool-service.ts — Relay pool as a ServiceHandler.
+ *
+ * Wraps an existing relay pool implementation (subscribe, publish,
+ * selectRelayTier, isAvailable) as a ServiceHandler that receives
+ * relay NUB envelope messages and manages subscription lifecycle.
+ *
+ * Handles: relay.subscribe, relay.close, relay.publish, relay.publishEncrypted.
+ *
+ * Note on `relay.publishEncrypted`: the canonical napplet→shell path routes
+ * through @kehto/runtime handleRelayMessage, which performs shell-internal
+ * NIP-44/NIP-04 encryption via the signer, then synthesizes a relay.publish
+ * envelope handed to this service. The publishEncrypted branch here is a
+ * fallback for alternate wirings; by the time the service sees the
+ * envelope, content MUST already be ciphertext (the service never encrypts
+ * or decrypts).
+ */
+
+/**
+ * Options for creating a relay pool service.
+ *
+ * @example
+ * ```ts
+ * const relayPoolService = createRelayPoolService({
+ *   subscribe: (filters, cb, urls) => myPool.subscribe(filters, cb, urls),
+ *   publish: (event) => myPool.publish(event),
+ *   selectRelayTier: (filters) => myPool.selectRelays(filters),
+ *   isAvailable: () => myPool.connected,
+ * });
+ * ```
+ */
+interface RelayPoolServiceOptions {
+    /**
+     * Subscribe to events matching filters. Returns handle with unsubscribe().
+     *
+     * @param filters - NIP-01 filter objects
+     * @param callback - Receives matching events or 'EOSE'
+     * @param relayUrls - Optional relay URL hints
+     * @returns Handle to cancel the subscription
+     */
+    subscribe(filters: NostrFilter[], callback: (item: NostrEvent | 'EOSE') => void, relayUrls?: string[]): {
+        unsubscribe(): void;
+    };
+    /**
+     * Publish an event to relays.
+     *
+     * @param event - The event to publish
+     */
+    publish(event: NostrEvent): void;
+    /**
+     * Select relay URLs appropriate for the given filters.
+     *
+     * @param filters - NIP-01 filter objects
+     * @returns Array of relay URLs
+     */
+    selectRelayTier(filters: NostrFilter[]): string[];
+    /**
+     * Whether the relay pool is available and connected.
+     *
+     * @returns true if the relay pool can handle requests
+     */
+    isAvailable(): boolean;
+}
+/**
+ * Create a relay pool service that wraps an existing relay pool
+ * implementation as a ServiceHandler.
+ *
+ * Handles relay.subscribe, relay.close, and relay.publish envelopes.
+ * Tracks subscriptions per windowId:subId for lifecycle management.
+ * Sets a 15-second EOSE fallback timer on each subscription.
+ *
+ * @param options - Relay pool implementation to wrap
+ * @returns A ServiceHandler ready for runtime.registerService('relay', handler)
+ *
+ * @example
+ * ```ts
+ * import { createRelayPoolService } from '@kehto/services';
+ *
+ * const pool = createRelayPoolService({
+ *   subscribe: (f, cb, urls) => applesauce.subscribe(f, cb, urls),
+ *   publish: (e) => applesauce.publish(e),
+ *   selectRelayTier: (f) => applesauce.getRelays(f),
+ *   isAvailable: () => applesauce.connected,
+ * });
+ * runtime.registerService('relay', pool);
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * const cacheService = createCacheService({
+ *   query: (filters) => myIndexedDB.query(filters),
+ *   store: (event) => myIndexedDB.store(event),
+ *   isAvailable: () => true,
+ * });
+ * ```
+ */
+interface CacheServiceOptions {
+    /**
+     * Query cached events matching the given filters.
+     *
+     * @param filters - NIP-01 filter objects
+     * @returns Promise resolving to matching cached events
+     */
+    query(filters: NostrFilter[]): Promise<NostrEvent[]>;
+    /**
+     * Store an event in cache. Best-effort, may silently fail.
+     *
+     * @param event - The event to store
+     */
+    store(event: NostrEvent): void;
+    /**
+     * Whether the cache is available.
+     *
+     * @returns true if the cache can handle requests
+     */
+    isAvailable(): boolean;
+}
+/**
+ * Create a cache service that wraps an existing cache implementation
+ * as a ServiceHandler.
+ *
+ * Cache relay.subscribe subscriptions are one-shot — they query, deliver
+ * results, send EOSE, and are done. No long-lived subscription tracking needed.
+ * Cache query failures are best-effort: EOSE is sent even on failure.
+ *
+ * @param options - Cache implementation to wrap
+ * @returns A ServiceHandler ready for runtime.registerService('cache', handler)
+ *
+ * @example
+ * ```ts
+ * import { createCacheService } from '@kehto/services';
+ *
+ * const cache = createCacheService({
+ *   query: (f) => workerRelay.query(f),
+ *   store: (e) => workerRelay.store(e),
+ *   isAvailable: () => workerRelay.ready,
+ * });
+ * runtime.registerService('cache', cache);
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * const relay = createCoordinatedRelay({
+ *   relayPool: {
+ *     subscribe: (f, cb, urls) => pool.subscribe(f, cb, urls),
+ *     publish: (e) => pool.publish(e),
+ *     selectRelayTier: (f) => pool.selectRelays(f),
+ *     isAvailable: () => pool.connected,
+ *   },
+ *   cache: {
+ *     query: (f) => db.query(f),
+ *     store: (e) => db.store(e),
+ *     isAvailable: () => db.ready,
+ *   },
+ * });
+ * runtime.registerService('relay', relay);
+ * ```
+ */
+interface CoordinatedRelayOptions {
+    /**
+     * Relay pool implementation.
+     * Uses the same interface as RelayPoolServiceOptions.
+     */
+    relayPool: RelayPoolServiceOptions;
+    /**
+     * Local cache implementation.
+     * Uses the same interface as CacheServiceOptions.
+     */
+    cache: CacheServiceOptions;
+    /**
+     * EOSE fallback timeout in milliseconds.
+     * Sent if relay pool doesn't respond within this time.
+     * Default: 15000 (15 seconds).
+     */
+    eoseTimeoutMs?: number;
+}
+/**
+ * Create a coordinated relay service that combines relay pool and cache
+ * into a single ServiceHandler with dedup and unified EOSE.
+ *
+ * On relay.subscribe: queries cache first, then subscribes to relay pool.
+ * Events are deduplicated by ID. EOSE is sent after both sources complete.
+ * On relay.publish: publishes to relay pool and stores in cache.
+ * On relay.close: cancels relay pool subscription.
+ *
+ * @param options - Relay pool and cache implementations to coordinate
+ * @returns A ServiceHandler ready for runtime.registerService('relay', handler)
+ *
+ * @example
+ * ```ts
+ * import { createCoordinatedRelay } from '@kehto/services';
+ *
+ * const relay = createCoordinatedRelay({ relayPool: myPool, cache: myCache });
+ * runtime.registerService('relay', relay);
+ * ```
+ */
+declare function createCoordinatedRelay(options: CoordinatedRelayOptions): ServiceHandler;
+
+/**
+ * keys-service.ts — NIP-5D keys NUB reference service (stub-level).
+ *
+ * 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
+ * { 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).
+ */
+
+/**
+ * Options for creating a keys service via createKeysService().
+ *
+ * @example
+ * ```ts
+ * const keys = createKeysService({
+ *   onForward: (event) => {
+ *     // event has DOM-compatible field names: ctrlKey, altKey, etc.
+ *     hotkeyDispatcher.dispatch(event);
+ *   },
+ * });
+ * ```
+ */
+interface KeysServiceOptions {
+    /**
+     * Called on keys.forward. 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.
+     */
+    onForward?: (event: {
+        key: string;
+        code: string;
+        ctrlKey: boolean;
+        altKey: boolean;
+        shiftKey: boolean;
+        metaKey: boolean;
+    }) => void;
+}
+/**
+ * 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.
+ *
+ * @param options - Optional configuration (onForward callback)
+ * @returns A ServiceHandler to register with the runtime
+ *
+ * @example
+ * ```ts
+ * import { createKeysService } from '@kehto/services';
+ *
+ * const keys = createKeysService({
+ *   onForward: (event) => shellHotkeyDispatcher.execute(event),
+ * });
+ *
+ * runtime.registerService('keys', keys);
+ * ```
+ */
+declare function createKeysService(options?: KeysServiceOptions): ServiceHandler;
+
+/**
+ * media-service.ts — NIP-5D media NUB reference service (stub-level).
+ *
+ * Handles 5 napplet -> shell request types from @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).
+ *
+ * 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
+ * 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.
+ */
+
+/**
+ * Optional host callbacks for the stub media service.
+ *
+ * Host shells can hook session creation and state updates to drive
+ * their own UI (e.g., now-playing banner) without replacing the
+ * ServiceHandler wholesale.
+ *
+ * @example
+ * ```ts
+ * const media = createMediaService({
+ *   onSessionCreate: (windowId, sessionId, metadata) => {
+ *     console.log(`[${windowId}] created session ${sessionId}`, metadata);
+ *   },
+ *   onState: (windowId, sessionId, state) => {
+ *     nowPlaying.update(windowId, state);
+ *   },
+ * });
+ *
+ * runtime.registerService('media', media);
+ * ```
+ */
+interface MediaServiceOptions {
+    /** Called when a napplet creates a session. May inspect/record the session. */
+    onSessionCreate?: (windowId: string, sessionId: string, metadata?: unknown) => void;
+    /** Called on media.state updates — high-frequency; keep handler work minimal. */
+    onState?: (windowId: string, sessionId: string, state: unknown) => void;
+    /** Called when a napplet destroys a session. */
+    onSessionDestroy?: (windowId: string, sessionId: string) => void;
+    /** Called when a napplet updates session metadata. */
+    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;
+}
+/**
+ * Create a stub-level media NUB service handler.
+ *
+ * Implements the 5 napplet->shell media.* request types defined in
+ * `@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.
+ *
+ * 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
+ *
+ * @example
+ * ```ts
+ * import { createMediaService } from '@kehto/services';
+ *
+ * const media = createMediaService();
+ * runtime.registerService('media', media);
+ * ```
+ */
+declare function createMediaService(options?: MediaServiceOptions): ServiceHandler;
+
+/**
+ * notify-service.ts — NIP-5D notify NUB reference service (stub-level).
+ *
+ * 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
+ *   - `notify.channel.register`    -> fire-and-forget
+ *   - `notify.permission.request`  -> `notify.permission.result { granted }`
+ *
+ * Stub-level: no real Notification API calls, no real channel registry.
+ * Host apps wire a real backend via
+ * `runtime.registerService('notify', realHandler)`.
+ *
+ * Coexistence note: this is SEPARATE from
+ * `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.
+ * If the host app registers this service via
+ * `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`,
+ * `notify.dismissed`, `notify.controls`) are not emitted by this stub —
+ * they are the host app's responsibility and are deferred to a future plan.
+ */
+
+/**
+ * Optional configuration for `createNotifyService`.
+ *
+ * @example
+ * ```ts
+ * const notify = createNotifyService({
+ *   generateId: () => crypto.randomUUID(),
+ *   defaultGrant: false,
+ *   onSend: (windowId, msg) => console.log(`napplet ${windowId} sent ${msg.title}`),
+ * });
+ * runtime.registerService('notify', notify);
+ * ```
+ */
+interface NotifyServiceOptions {
+    /**
+     * Generate a shell-assigned notification ID for `notify.send.result`.
+     * Default: a monotonically increasing `shell-<n>` counter.
+     */
+    generateId?: () => string;
+    /**
+     * Default permission grant for `notify.permission.request`.
+     * Host apps that want real permission prompts should replace this
+     * service with a real backend via `runtime.registerService`.
+     * Default: `true`.
+     */
+    defaultGrant?: boolean;
+    /**
+     * Called synchronously when a napplet dispatches `notify.send`.
+     * Intended for host-app plumbing (UI toast, logging, etc.) without
+     * requiring a full backend replacement.
+     */
+    onSend?: (windowId: string, payload: NotifySendMessage) => void;
+}
+/**
+ * Create a stub-level notify service handler.
+ *
+ * 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
+ * needed.
+ *
+ * @param options - Optional service configuration (see NotifyServiceOptions)
+ * @returns A ServiceHandler to register with the runtime under domain `notify`
+ *
+ * @example
+ * ```ts
+ * import { createNotifyService } from '@kehto/services';
+ *
+ * const notify = createNotifyService();
+ * runtime.registerService('notify', notify);
+ * ```
+ */
+declare function createNotifyService(options?: NotifyServiceOptions): ServiceHandler;
+
+/**
+ * theme-service.ts — NIP-5D theme NUB reference service.
+ *
+ * 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:
+ *   1. Replaces the service's internal current theme.
+ *   2. Invokes `options.onBroadcast(envelope)` synchronously with a
+ *      `theme.changed` envelope so the shell adapter (Plan 13-02) can
+ *      fan-out the push to every registered napplet.
+ *   3. Returns the envelope so callers can use it directly if they prefer.
+ *
+ * The default theme values are centralized here and mirrored in the runtime's
+ * fallback path (`packages/runtime/src/runtime.ts`) — runtime does NOT import
+ * from @kehto/services because services depends on runtime (one-way only).
+ *
+ * Host apps replace this via `runtime.registerService('theme', realHandler)`
+ * when real CSS injection / storage / dark-mode logic is needed.
+ *
+ * @example
+ * ```ts
+ * import { createThemeService } from '@kehto/services';
+ *
+ * const theme = createThemeService({
+ *   onBroadcast: (envelope) => broadcastToAllNapplets(envelope),
+ * });
+ * runtime.registerService('theme', theme.handler);
+ *
+ * // Later, when the user flips dark/light mode:
+ * theme.publishTheme(newTheme);
+ * ```
+ */
+
+/**
+ * Configuration for `createThemeService`.
+ *
+ * @example
+ * ```ts
+ * const theme = createThemeService({
+ *   initialTheme: { colors: { background: '#fff', text: '#000', primary: '#00f' } },
+ *   onBroadcast: (envelope) => shellBridge.broadcastToAll(envelope),
+ * });
+ * ```
+ */
+interface ThemeServiceOptions {
+    /**
+     * Override the default theme payload. If omitted, the service starts with
+     * the canonical defaults (`#0a0a0a / #e0e0e0 / #7aa2f7`).
+     */
+    initialTheme?: Theme;
+    /**
+     * Called synchronously from `publishTheme(theme)` with a `theme.changed`
+     * envelope. Intended for the shell adapter (Plan 13-02) to fan-out the
+     * push to every registered napplet via the runtime's sendToNapplet
+     * primitive.
+     *
+     * Keep this callback shape framework-agnostic — the service does NOT
+     * import any shell / browser APIs.
+     */
+    onBroadcast?: (envelope: ThemeChangedMessage) => void;
+}
+/**
+ * A theme service bundle — the ServiceHandler that handles `theme.*`
+ * envelopes, the host-facing `publishTheme(theme)` handle for theme-change
+ * broadcasts, and a `getCurrentTheme()` accessor for host-side reads.
+ */
+interface ThemeService {
+    /** Register this with the runtime via `runtime.registerService('theme', handler)`. */
+    handler: ServiceHandler;
+    /**
+     * Publish a theme-change to the shell adapter. Updates the service's
+     * internal current theme, invokes `options.onBroadcast` with a
+     * `theme.changed` envelope, and returns the envelope.
+     *
+     * @param theme - The new theme payload
+     * @returns A `theme.changed` envelope (same one passed to onBroadcast)
+     */
+    publishTheme: (theme: Theme) => ThemeChangedMessage;
+    /** Return the current theme. Equivalent to the payload a napplet's `theme.get` would receive. */
+    getCurrentTheme: () => Theme;
+}
+/**
+ * Create a theme service that handles the NIP-5D `theme.*` NUB.
+ *
+ * Answers `theme.get` with the current theme (default or
+ * `options.initialTheme`). Exposes `publishTheme(theme)` for the host app to
+ * broadcast theme changes to every registered napplet — the shell adapter
+ * (Plan 13-02) wires `onBroadcast` to `runtime.sendToNapplet` fan-out.
+ *
+ * @param options - Optional service configuration (see ThemeServiceOptions)
+ * @returns A ThemeService bundle ready for `runtime.registerService('theme', service.handler)`
+ *
+ * @example
+ * ```ts
+ * import { createThemeService } from '@kehto/services';
+ *
+ * const theme = createThemeService();
+ * runtime.registerService('theme', theme.handler);
+ * theme.publishTheme({ colors: { background: '#fff', text: '#000', primary: '#00f' } });
+ * ```
+ */
+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 };