@kehto/services 0.21.1 → 0.21.2

package/README.md

@@ -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}.
      */

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);