@kehto/services 0.8.0 → 0.9.1

package/README.md

@@ -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
 
@@ -344,7 +344,7 @@ 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/nub/media` — `mediaCreateSession({ owner: 'napplet', ... })`, `mediaReportState`, and `mediaOnCommand` against the real backend.
 
 ## Public API
 

package/dist/index.d.ts

@@ -1981,4 +1981,300 @@ 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;
+
+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 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 };

package/dist/index.js

@@ -2396,6 +2396,227 @@ function toErrorMessage3(err) {
   return "upload failed";
 }
 
+// src/intent-service.ts
+var INTENT_SERVICE_VERSION = "1.0.0";
+var INTENT_DESCRIPTOR = {
+  name: "intent",
+  version: INTENT_SERVICE_VERSION,
+  description: "NAP-INTENT archetype intent dispatch \u2014 invoke/available/handlers"
+};
+function toErrorMessage4(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  return "intent request failed";
+}
+function createIntentService(options) {
+  if (!options || typeof options.resolver !== "object" || options.resolver === null) {
+    throw new Error("createIntentService: options.resolver is required");
+  }
+  const { resolver } = options;
+  const windows = /* @__PURE__ */ new Map();
+  resolver.onChanged?.((availability) => {
+    for (const send of windows.values()) {
+      send({ type: "intent.changed", availability });
+    }
+  });
+  function settle(call, send, resultType, id, onValue) {
+    let pending;
+    try {
+      pending = Promise.resolve(call());
+    } catch (err) {
+      send({ type: resultType, id, error: toErrorMessage4(err) });
+      return;
+    }
+    pending.then((value) => send(onValue(value))).catch((err) => send({ type: resultType, id, error: toErrorMessage4(err) }));
+  }
+  function handleInvoke(windowId, msg, send) {
+    const m = msg;
+    const id = m.id ?? "";
+    const request = m.request;
+    if (!request || typeof request !== "object" || typeof request.archetype !== "string" || request.archetype.length === 0) {
+      send({ type: "intent.invoke.result", id, error: "invalid request" });
+      return;
+    }
+    settle(
+      () => resolver.invoke(request, { windowId }),
+      send,
+      "intent.invoke.result",
+      id,
+      (result) => ({ type: "intent.invoke.result", id, result })
+    );
+  }
+  function handleAvailable(msg, send) {
+    const m = msg;
+    const id = m.id ?? "";
+    if (typeof m.archetype !== "string" || m.archetype.length === 0) {
+      send({ type: "intent.available.result", id, error: "invalid archetype" });
+      return;
+    }
+    const archetype = m.archetype;
+    settle(
+      () => resolver.available(archetype),
+      send,
+      "intent.available.result",
+      id,
+      (availability) => ({ type: "intent.available.result", id, availability })
+    );
+  }
+  function handleHandlers(msg, send) {
+    const m = msg;
+    const id = m.id ?? "";
+    settle(
+      () => resolver.handlers(),
+      send,
+      "intent.handlers.result",
+      id,
+      (handlers) => ({ type: "intent.handlers.result", id, handlers })
+    );
+  }
+  return {
+    descriptor: INTENT_DESCRIPTOR,
+    handleMessage(windowId, message, send) {
+      windows.set(windowId, send);
+      switch (message.type) {
+        case "intent.invoke":
+          handleInvoke(windowId, message, send);
+          return;
+        case "intent.available":
+          handleAvailable(message, send);
+          return;
+        case "intent.handlers":
+          handleHandlers(message, send);
+          return;
+        default:
+          return;
+      }
+    },
+    onWindowDestroyed(windowId) {
+      windows.delete(windowId);
+    }
+  };
+}
+
+// src/catalog-intent-resolver.ts
+function candidatesFor(catalog, archetype, defaultHandler) {
+  const candidates = [];
+  for (const entry of catalog) {
+    const support = entry.archetypes[archetype];
+    if (!support) continue;
+    candidates.push({
+      dTag: entry.dTag,
+      ...entry.title === void 0 ? {} : { title: entry.title },
+      actions: support.actions,
+      protocols: support.protocols,
+      ...entry.dTag === defaultHandler ? { isDefault: true } : {}
+    });
+  }
+  return candidates;
+}
+function fail(archetype, action, error) {
+  return { ok: false, archetype, action, handled: false, error };
+}
+function createCatalogIntentResolver(options) {
+  if (!options || typeof options.loadCatalog !== "function") {
+    throw new Error("createCatalogIntentResolver: options.loadCatalog is required");
+  }
+  if (!options.windows || typeof options.windows.open !== "function") {
+    throw new Error("createCatalogIntentResolver: options.windows is required");
+  }
+  const { loadCatalog, windows, getDefaultHandler, chooseHandler, defaultProtocol } = options;
+  const listeners = /* @__PURE__ */ new Set();
+  async function availabilityFor(archetype) {
+    const catalog = await loadCatalog();
+    const def = getDefaultHandler?.(archetype);
+    const candidates = candidatesFor(catalog, archetype, def);
+    return {
+      archetype,
+      available: candidates.length > 0,
+      candidates,
+      hasDefault: def !== void 0 && candidates.some((c) => c.dTag === def)
+    };
+  }
+  async function pickHandler(archetype, candidates, preference, callerWindowId) {
+    if (typeof preference === "string" && preference !== "default" && preference !== "choose") {
+      return preference;
+    }
+    if (preference === "choose") {
+      const picked = await chooseHandler?.(archetype, candidates, callerWindowId);
+      return picked ?? null;
+    }
+    const def = getDefaultHandler?.(archetype);
+    if (def !== void 0 && candidates.some((c) => c.dTag === def)) return def;
+    if (candidates.length === 1) return candidates[0].dTag;
+    if (chooseHandler) {
+      const picked = await chooseHandler(archetype, candidates, callerWindowId);
+      return picked ?? null;
+    }
+    return candidates[0].dTag;
+  }
+  async function invoke(request, context) {
+    const archetype = request.archetype;
+    const action = request.action ?? "open";
+    const catalog = await loadCatalog();
+    const candidates = candidatesFor(catalog, archetype, getDefaultHandler?.(archetype));
+    if (candidates.length === 0) return fail(archetype, action, "no handler");
+    const pickedDTag = await pickHandler(archetype, candidates, request.handler, context.windowId);
+    if (pickedDTag === null) return fail(archetype, action, "user cancelled");
+    const handler = candidates.find((c) => c.dTag === pickedDTag);
+    if (!handler) return fail(archetype, action, "no handler");
+    if (!handler.actions.includes(action)) return fail(archetype, action, "unsupported action");
+    const protocol = request.protocol ?? defaultProtocol?.(archetype) ?? handler.protocols[0];
+    if (protocol !== void 0 && handler.protocols.length > 0 && !handler.protocols.includes(protocol)) {
+      return fail(archetype, action, "unsupported protocol");
+    }
+    let windowId;
+    try {
+      const opened = await windows.open({
+        dTag: handler.dTag,
+        archetype,
+        action,
+        ...protocol === void 0 ? {} : { protocol },
+        ...request.payload === void 0 ? {} : { payload: request.payload },
+        ...request.behavior === void 0 ? {} : { behavior: request.behavior },
+        callerWindowId: context.windowId
+      });
+      windowId = opened.windowId;
+    } catch {
+      return fail(archetype, action, "invoke failed");
+    }
+    return {
+      ok: true,
+      archetype,
+      action,
+      handled: true,
+      handler: handler.dTag,
+      windowId,
+      ...protocol === void 0 ? {} : { protocol }
+    };
+  }
+  async function handlers() {
+    const catalog = await loadCatalog();
+    const archetypes = /* @__PURE__ */ new Set();
+    for (const entry of catalog) {
+      for (const slug of Object.keys(entry.archetypes)) archetypes.add(slug);
+    }
+    return Promise.all([...archetypes].map((a) => availabilityFor(a)));
+  }
+  return {
+    invoke,
+    available: availabilityFor,
+    handlers,
+    onChanged(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    notifyChanged(archetype) {
+      if (listeners.size === 0) return;
+      void availabilityFor(archetype).then((availability) => {
+        for (const listener of listeners) listener(availability);
+      });
+    }
+  };
+}
+
 // src/cvm-service.ts
 var CVM_SERVICE_VERSION = "1.0.0";
 var CVM_DESCRIPTOR = {
@@ -2438,7 +2659,7 @@ function createCvmService(options) {
     const m = msg;
     const id = m.id ?? "";
     void transport.discover(m.query).then((servers) => send({ type: "cvm.discover.result", id, servers })).catch(
-      (err) => send({ type: "cvm.discover.result", id, servers: [], error: toErrorMessage4(err) })
+      (err) => send({ type: "cvm.discover.result", id, servers: [], error: toErrorMessage5(err) })
     );
   }
   function handleRequest(windowId, msg, send) {
@@ -2454,7 +2675,7 @@ function createCvmService(options) {
     }
     openSession(windowId, m.server, send);
     void transport.request(m.server, m.message, m.options).then((message) => send({ type: "cvm.request.result", id, message })).catch(
-      (err) => send({ type: "cvm.request.result", id, error: toErrorMessage4(err) })
+      (err) => send({ type: "cvm.request.result", id, error: toErrorMessage5(err) })
     );
   }
   function handleClose(windowId, msg, send) {
@@ -2465,7 +2686,7 @@ function createCvmService(options) {
       return;
     }
     closeSession(windowId, m.server.pubkey);
-    void transport.close(m.server).then(() => send({ type: "cvm.close.result", id })).catch((err) => send({ type: "cvm.close.result", id, error: toErrorMessage4(err) }));
+    void transport.close(m.server).then(() => send({ type: "cvm.close.result", id })).catch((err) => send({ type: "cvm.close.result", id, error: toErrorMessage5(err) }));
   }
   return {
     descriptor: CVM_DESCRIPTOR,
@@ -2496,7 +2717,7 @@ function createCvmService(options) {
     }
   };
 }
-function toErrorMessage4(err) {
+function toErrorMessage5(err) {
   if (err instanceof Error) return err.message;
   if (typeof err === "string") return err;
   return "cvm request failed";
@@ -2505,11 +2726,13 @@ export {
   createAudioService,
   createBrowserMediaBridge,
   createCacheService,
+  createCatalogIntentResolver,
   createConfigService,
   createCoordinatedRelay,
   createCvmService,
   createHttpUploader,
   createIdentityService,
+  createIntentService,
   createKeysService,
   createMediaService,
   createNotificationService,