@kehto/services 0.21.0 → 0.21.2

package/README.md

@@ -43,7 +43,7 @@ Current draft posture:
 - `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` handles direct `notify.*` envelopes. It is not an INC
   topic handler.
-- `createOutboxService` supports `outbox.getEvent` from draft NAP-OUTBOX. Single-event lookups run through shell-owned relay routing and only return events whose ID matches the request. The draft wire contract keeps `outbox.query` one-shot and `outbox.subscribe` streaming; Kehto's concrete `createRelayPoolOutboxRouter` additionally exposes host-side `queryStream()` so verified query events can arrive before asynchronous NIP-65 discovery completes.
+- `createOutboxService` supports `outbox.getEvent` from draft NAP-OUTBOX. Single-event lookups run through shell-owned relay routing and only return events whose ID matches the request. Hosts can provide `getReadRouter` to scope all event-returning reads (`getEvent`, query, and subscription) to the authenticated source window, plus `getQueryRouter` when one-shot queries need an additional decorator. The draft wire contract keeps `outbox.query` one-shot and `outbox.subscribe` streaming; Kehto's concrete `createRelayPoolOutboxRouter` additionally exposes host-side `queryStream()` so verified query events can arrive before asynchronous NIP-65 discovery completes.
 - `createResourceService` implements NAP-RESOURCE at exact draft head `9511232f69313aa7953d110e35d32cc28d506f66` without choosing a runtime's network policy. Single requests carry optional advisory Blossom `servers`; bulk requests use canonical per-resource `requests: [{ url, servers? }]` entries. The service forwards hints to the injected resolver only for `blossom:`, preserves order and per-entry failures, and exposes optional `resource.info.maxServers`. By default it delegates every syntactically valid URL to the resolver; `resource.info.schemes` remains advisory. Runtimes that want hierarchical-origin grants can supply `isOriginGranted`, `getConnectGrants`, and `resolveIdentity` together, while scheme resolvers retain responsibility for hint validation, SSRF protection, redirects, and fallback policy. The service enforces supplied size/bulk caps, scopes cancellation to the requesting window, drops cancelled terminal envelopes, never forwards response headers, and preserves explicit `ResourceServiceError` codes.
 - `createUploadService` supports `upload.info` from draft NAP-UPLOAD. Hosts may expose configured rails, return URL forms, maximum bytes, and MIME type policy without requiring napplets to start an upload.
 - `createConfigService` implements draft NAP-CONFIG's shell-writer boundary: recursive bounded-subset schema validation, per-window schema/subscription state, deterministic defaults, invalid/orphan removal, version rollback rejection, scoped host persistence hooks, and settings-UI commits. Reads before schema registration fail closed with `no-schema`.
@@ -251,6 +251,8 @@ 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
+   *   - remove only this subscription when its unsubscribe handle is called;
+   *     other callbacks for the same chord must remain live
    *   - accept the string chord format documented by @napplet/nap/keys
    *     (e.g. `'Ctrl+Shift+K'`, `'Cmd+P'`)
    */
@@ -300,16 +302,33 @@ keys.destroy();
 Custom bridge path — swap in Electron's `globalShortcut`:
 
 ```ts
-import { createKeysService, type HostKeysBridge } from '@kehto/services';
+import { createKeysService, type HostKeysBridge, type HostKeyEvent } from '@kehto/services';
 import { globalShortcut } from 'electron';
 
+const subscribers = new Map<string, Set<(event: HostKeyEvent) => void>>();
 const electronBridge: HostKeysBridge = {
   subscribe(chord, cb) {
-    globalShortcut.register(chord, () => cb({
-      key: '', code: '',
-      ctrlKey: false, altKey: false, shiftKey: false, metaKey: false,
-    } as KeyboardEvent));
-    return () => globalShortcut.unregister(chord);
+    let callbacks = subscribers.get(chord);
+    if (!callbacks) {
+      const group = new Set<(event: HostKeyEvent) => void>();
+      const registered = globalShortcut.register(chord, () => {
+        for (const callback of group) callback({
+          key: '', code: '',
+          ctrlKey: false, altKey: false, shiftKey: false, metaKey: false,
+        });
+      });
+      if (!registered) throw new Error(`Cannot register ${chord}`);
+      callbacks = group;
+      subscribers.set(chord, callbacks);
+    }
+    callbacks.add(cb);
+    return () => {
+      if (!callbacks.delete(cb)) return;
+      if (callbacks.size === 0) {
+        globalShortcut.unregister(chord);
+        subscribers.delete(chord);
+      }
+    };
   },
 };
 
@@ -322,6 +341,23 @@ Plug a `HostKeysBridge` when the default document listener is insufficient: Elec
 
 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. After a successful bound registration, the service pushes a complete `keys.bindings` list for that napplet/window, using entries shaped as `{ actionId, key }`. It pushes the complete list again after `keys.unregisterAction` removes a binding, including an empty list when no bindings remain. Injected shims use that list to suppress locally-bound keydowns before forwarding.
 
+Action IDs are local to the trusted window passed by the runtime. Two windows may
+each register `game.a`, including with the same suggested key, without replacing
+one another's bindings. Unregistering or destroying one window removes only its
+actions and bridge subscriptions. Binding lists and `keys.action` messages retain
+the original app-local action ID; callers do not need to invent window-specific IDs.
+Re-registering an action in the same window retains the existing rebind behavior:
+a valid available chord replaces that window's binding, a reserved chord removes
+its previous binding, and a malformed chord or failed bridge subscription leaves
+the previous binding intact.
+
+This ownership scope is an explicit Kehto policy for the scope left implicit by
+[NAP-KEYS PR #9 at `cecb642`](https://github.com/napplet/naps/blob/cecb64257e0ac29926bb746832a477c553ab307c/naps/NAP-KEYS.md).
+The draft describes duplicate-action errors but does not mandate service-global
+IDs or forbid same-owner updates. Window-scoped ownership preserves its per-napplet
+binding delivery and adds no wire fields. Chord conflicts retain the existing
+behavior: matching registered actions receive their own `keys.action` push.
+
 ### Reserved Chords
 
 Shell-reserved chords let a host application (window manager, launcher shell, tiling WM) claim specific chords for its own dispatch regardless of what napplets subscribe to. Declare the reserved set once at service construction via the `reservedChords` option on [`KeysServiceOptions`](#keysserviceoptions):

package/dist/index.d.ts

@@ -507,7 +507,7 @@ declare function createCoordinatedRelay(options: CoordinatedRelayOptions): Servi
  *   - keys.forward          -> invokes options.onForward (hotkey passthrough, fire-and-forget)
  *   - keys.registerAction   -> parses action.defaultKey into a normalized chord binding,
  *                              stores bound subscriptions in an in-memory registry keyed
- *                              by actionId, tracks windowId ownership so onWindowDestroyed
+ *                              by windowId + actionId so onWindowDestroyed
  *                              can auto-unsubscribe, echoes { actionId, binding } as .result
  *                              when a binding is assigned, and pushes the window's complete
  *                              keys.bindings list
@@ -577,17 +577,8 @@ interface HostKeyEvent {
  *
  * @example
  * ```ts
- * // Host-app pseudocode (Electron main-process relay):
- * const electronBridge: HostKeysBridge = {
- *   subscribe(chord, cb) {
- *     const handle = globalShortcut.register(chord, () => cb({ key: '', code: '', ctrlKey: false, altKey: false, shiftKey: false, metaKey: false }));
- *     return () => globalShortcut.unregister(chord);
- *   },
- *   registerGlobalHotkey: (chord) => globalShortcut.register(chord, () => {}),
- *   onGlobalHotkey: (cb) => globalHotkeyBridge.on('global-hotkey', (_, chord) => cb(chord)),
- * };
- *
- * const keys = createKeysService({ hostBridge: electronBridge });
+ * declare const hostBridge: HostKeysBridge;
+ * const keys = createKeysService({ hostBridge });
  * runtime.registerService('keys', keys);
  * ```
  */
@@ -599,6 +590,8 @@ 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
+     *   - remove only this subscription when its unsubscribe handle is called;
+     *     other callbacks for the same chord must remain live
      *   - accept the string chord format documented by @napplet/nap/keys
      *     (e.g. `'Ctrl+Shift+K'`, `'Cmd+P'`)
      */
@@ -665,7 +658,7 @@ interface KeysServiceOptions {
     /**
      * Optional pluggable backend for chord subscription. When provided, the
      * service delegates `keys.registerAction` → `bridge.subscribe(chord, cb)`
-     * and stores the returned unsubscribe handle keyed on `actionId`. The
+     * and stores the returned unsubscribe handle keyed on windowId + actionId. The
      * default document-listener path is NOT attached when `hostBridge` is
      * provided — the bridge is authoritative. See {@link HostKeysBridge}.
      */
@@ -1416,6 +1409,8 @@ interface ResourceFetchInit {
     headers?: Record<string, string>;
     /** Request-scoped cancellation signal. */
     signal: AbortSignal;
+    /** Authenticated source window, for runtime-private scoped policy state. */
+    windowId?: string;
     /** Advisory Blossom server origins for this resource only. */
     servers?: readonly string[];
 }
@@ -1715,7 +1710,19 @@ interface OutboxServiceOptions {
     /** The outbox router the shell uses to reach relays. Required. */
     router: OutboxRouter;
     /**
-     * Optionally selects a request-scoped router for a live napplet source.
+     * Optionally selects a source-scoped router for event-returning reads.
+     *
+     * The selected router is used for `outbox.getEvent`, `outbox.query`, and
+     * `outbox.subscribe`. A query-specific router takes precedence when both
+     * hooks are supplied.
+     *
+     * @param windowId - The authenticated source window for the request.
+     * @param context - Narrow runtime context for source-bound policy checks.
+     * @returns Router used for that source's event-returning reads.
+     */
+    getReadRouter?(windowId: string, context: ServiceRuntimeContext | undefined): OutboxRouter;
+    /**
+     * Optionally selects a query-specific router for a live napplet source.
      *
      * @param windowId - The authenticated source window for the request.
      * @param context - Narrow runtime context for source-bound policy checks.

package/dist/index.js

@@ -727,6 +727,9 @@ function createCoordinatedRelay(options) {
 }
 
 // src/keys-service-internals.ts
+function actionRegistryKey(windowId, actionId) {
+  return JSON.stringify([windowId, actionId]);
+}
 var MODIFIER_ALIASES = {
   ctrl: "ctrl",
   control: "ctrl",
@@ -795,7 +798,7 @@ function bindingsForWindow(windowId, registry, windowIndex) {
   if (!actionIds) return [];
   const bindings = [];
   for (const actionId of actionIds) {
-    const entry = registry.get(actionId);
+    const entry = registry.get(actionRegistryKey(windowId, actionId));
     if (!entry || entry.windowId !== windowId) continue;
     bindings.push({ actionId, key: entry.chordString });
   }
@@ -808,10 +811,9 @@ function pushBindings(windowId, registry, windowIndex, send) {
   };
   send(payload);
 }
-function removeActionFromWindowIndex(actionId, windowIndex) {
-  for (const [wid, set] of windowIndex.entries()) {
-    if (set.delete(actionId) && set.size === 0) windowIndex.delete(wid);
-  }
+function removeActionFromWindowIndex(windowId, actionId, windowIndex) {
+  const actions = windowIndex.get(windowId);
+  if (actions?.delete(actionId) && actions.size === 0) windowIndex.delete(windowId);
 }
 
 // src/keys-service.ts
@@ -821,7 +823,7 @@ function rememberActionForWindow(windowIndex, windowId, actionId) {
   windowIndex.get(windowId).add(actionId);
 }
 function bindActionEntry(registry, windowIndex, actionId, windowId, chord, chordString) {
-  registry.set(actionId, { chord, chordString, windowId });
+  registry.set(actionRegistryKey(windowId, actionId), { actionId, chord, chordString, windowId });
   rememberActionForWindow(windowIndex, windowId, actionId);
 }
 function bindActionAndMarkChanged(registry, windowIndex, changedWindowIds, actionId, windowId, chord, chordString) {
@@ -894,6 +896,7 @@ function createKeysService(options = {}) {
     const bridgeSendHandles = /* @__PURE__ */ new Map();
     const unsubscribeHandles = /* @__PURE__ */ new Map();
     const handleBridgeRegisterAction = (windowId, m, send) => {
+      const registryKey = actionRegistryKey(windowId, m.action.id);
       bridgeSendHandles.set(windowId, send);
       let binding;
       const changedWindowIds = /* @__PURE__ */ new Set();
@@ -901,8 +904,8 @@ function createKeysService(options = {}) {
         try {
           const chord = parseChord(m.action.defaultKey);
           const normalizedChord = formatChord(chord);
-          const existingEntry = bridgeActionRegistry.get(m.action.id);
-          const existing = unsubscribeHandles.get(m.action.id);
+          const existingEntry = bridgeActionRegistry.get(registryKey);
+          const existing = unsubscribeHandles.get(registryKey);
           let nextUnsubscribe;
           if (!isUnavailableBinding(chord)) {
             nextUnsubscribe = bridge.subscribe(normalizedChord, (ev) => {
@@ -928,13 +931,13 @@ function createKeysService(options = {}) {
               existing();
             } catch {
             }
-            unsubscribeHandles.delete(m.action.id);
+            unsubscribeHandles.delete(registryKey);
           }
           if (existingEntry) changedWindowIds.add(existingEntry.windowId);
-          removeActionFromWindowIndex(m.action.id, bridgeWindowActions);
-          bridgeActionRegistry.delete(m.action.id);
+          removeActionFromWindowIndex(windowId, m.action.id, bridgeWindowActions);
+          bridgeActionRegistry.delete(registryKey);
           if (nextUnsubscribe) {
-            unsubscribeHandles.set(m.action.id, nextUnsubscribe);
+            unsubscribeHandles.set(registryKey, nextUnsubscribe);
             binding = bindActionAndMarkChanged(
               bridgeActionRegistry,
               bridgeWindowActions,
@@ -964,18 +967,19 @@ function createKeysService(options = {}) {
         send
       );
     };
-    const handleBridgeUnregisterAction = (_windowId, m, send) => {
+    const handleBridgeUnregisterAction = (windowId, m, send) => {
       if (!m.actionId) return;
-      const unsubscribe = unsubscribeHandles.get(m.actionId);
-      const entry = bridgeActionRegistry.get(m.actionId);
+      const registryKey = actionRegistryKey(windowId, m.actionId);
+      const unsubscribe = unsubscribeHandles.get(registryKey);
+      const entry = bridgeActionRegistry.get(registryKey);
       if (!unsubscribe) return;
       try {
         unsubscribe();
       } catch {
       }
-      unsubscribeHandles.delete(m.actionId);
-      bridgeActionRegistry.delete(m.actionId);
-      removeActionFromWindowIndex(m.actionId, bridgeWindowActions);
+      unsubscribeHandles.delete(registryKey);
+      bridgeActionRegistry.delete(registryKey);
+      removeActionFromWindowIndex(windowId, m.actionId, bridgeWindowActions);
       if (entry) {
         const ownerSend = bridgeSendHandles.get(entry.windowId) ?? send;
         pushBindings(entry.windowId, bridgeActionRegistry, bridgeWindowActions, ownerSend);
@@ -995,15 +999,16 @@ function createKeysService(options = {}) {
         const actions = bridgeWindowActions.get(windowId);
         if (!actions) return;
         for (const actionId of actions) {
-          const unsubscribe = unsubscribeHandles.get(actionId);
+          const registryKey = actionRegistryKey(windowId, actionId);
+          const unsubscribe = unsubscribeHandles.get(registryKey);
           if (unsubscribe) {
             try {
               unsubscribe();
             } catch {
             }
           }
-          unsubscribeHandles.delete(actionId);
-          bridgeActionRegistry.delete(actionId);
+          unsubscribeHandles.delete(registryKey);
+          bridgeActionRegistry.delete(registryKey);
         }
         bridgeWindowActions.delete(windowId);
         bridgeSendHandles.delete(windowId);
@@ -1056,13 +1061,13 @@ function createKeysService(options = {}) {
       });
     }
     if (isReserved) return;
-    for (const [actionId, entry] of actionRegistry.entries()) {
+    for (const entry of actionRegistry.values()) {
       if (chordMatches(entry.chord, ev)) {
         const send = sendHandles.get(entry.windowId);
         if (send) {
           const payload = {
             type: "keys.action",
-            actionId
+            actionId: entry.actionId
           };
           send(payload);
         }
@@ -1071,6 +1076,7 @@ function createKeysService(options = {}) {
   };
   target.addEventListener("keydown", listener);
   const handleDocumentRegisterAction = (windowId, m, send) => {
+    const registryKey = actionRegistryKey(windowId, m.action.id);
     sendHandles.set(windowId, send);
     let binding;
     const changedWindowIds = /* @__PURE__ */ new Set();
@@ -1078,11 +1084,11 @@ function createKeysService(options = {}) {
       try {
         const chord = parseChord(m.action.defaultKey);
         const normalizedChord = formatChord(chord);
-        const existing = actionRegistry.get(m.action.id);
+        const existing = actionRegistry.get(registryKey);
         if (existing) {
           changedWindowIds.add(existing.windowId);
-          removeActionFromWindowIndex(m.action.id, windowActions);
-          actionRegistry.delete(m.action.id);
+          removeActionFromWindowIndex(windowId, m.action.id, windowActions);
+          actionRegistry.delete(registryKey);
         }
         if (!isUnavailableBinding(chord)) {
           binding = bindActionAndMarkChanged(actionRegistry, windowActions, changedWindowIds, m.action.id, windowId, chord, normalizedChord);
@@ -1100,10 +1106,12 @@ function createKeysService(options = {}) {
     sendRegisterActionResult(send, m, binding);
     pushChangedBindings(changedWindowIds, actionRegistry, windowActions, sendHandles, send);
   };
-  const handleDocumentUnregisterAction = (_windowId, m, send) => {
-    if (!m.actionId || !actionRegistry.has(m.actionId)) return;
-    const entry = actionRegistry.get(m.actionId);
-    actionRegistry.delete(m.actionId);
+  const handleDocumentUnregisterAction = (windowId, m, send) => {
+    if (!m.actionId) return;
+    const registryKey = actionRegistryKey(windowId, m.actionId);
+    const entry = actionRegistry.get(registryKey);
+    if (!entry) return;
+    actionRegistry.delete(registryKey);
     const set = windowActions.get(entry.windowId);
     if (set) {
       set.delete(m.actionId);
@@ -1123,7 +1131,7 @@ function createKeysService(options = {}) {
     onWindowDestroyed(windowId) {
       const actions = windowActions.get(windowId);
       if (actions) {
-        for (const actionId of actions) actionRegistry.delete(actionId);
+        for (const actionId of actions) actionRegistry.delete(actionRegistryKey(windowId, actionId));
         windowActions.delete(windowId);
       }
       sendHandles.delete(windowId);
@@ -2405,6 +2413,7 @@ async function fetchResourceItem(options, windowId, info, request, signal) {
     const response = await options.fetch(url, {
       method: "GET",
       signal,
+      windowId,
       ...parsedUrl.protocol === "blossom:" && request.servers !== void 0 ? { servers: [...request.servers] } : {}
     });
     const buffer = await response.arrayBuffer();
@@ -2720,7 +2729,7 @@ function createOutboxService(options) {
   if (!options || typeof options.router !== "object" || options.router === null) {
     throw new Error("createOutboxService: options.router is required");
   }
-  const { router, getQueryRouter } = options;
+  const { router, getReadRouter, getQueryRouter } = options;
   let runtimeContext;
   const subscriptions = /* @__PURE__ */ new Map();
   function handleQuery(windowId, msg, send) {
@@ -2731,7 +2740,7 @@ function createOutboxService(options) {
       send({ type: "outbox.query.result", id, events: [], error: "invalid filter" });
       return;
     }
-    const queryRouter = getQueryRouter?.(windowId, runtimeContext) ?? router;
+    const queryRouter = getQueryRouter?.(windowId, runtimeContext) ?? getReadRouter?.(windowId, runtimeContext) ?? router;
     void queryRouter.query(filters, sanitizeQueryOptions(m.options)).then(
       (result2) => send({
         type: "outbox.query.result",
@@ -2763,7 +2772,8 @@ function createOutboxService(options) {
         send({ type: "outbox.closed", subId, ...reason === void 0 ? {} : { reason } });
       }
     };
-    subscriptions.set(subKey, router.subscribe(filters, sanitizeSubscribeOptions(m.options), sink));
+    const readRouter = getReadRouter?.(windowId, runtimeContext) ?? router;
+    subscriptions.set(subKey, readRouter.subscribe(filters, sanitizeSubscribeOptions(m.options), sink));
   }
   function handleClose(windowId, msg, send) {
     const m = msg;
@@ -2818,7 +2828,7 @@ function createOutboxService(options) {
     handleMessage(windowId, message, send) {
       switch (message.type) {
         case "outbox.getEvent":
-          handleGetEvent(router, message, send);
+          handleGetEvent(getReadRouter?.(windowId, runtimeContext) ?? router, message, send);
           return;
         case "outbox.query":
           handleQuery(windowId, message, send);