@pyreon/hotkeys 0.12.14 → 0.13.0

package/lib/analysis/index.js.html

@@ -5386,7 +5386,7 @@ var drawChart = (function (exports) {
   </script>
   <script>
     /*<!--*/
-    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"uid":"b111ad13-1","name":"parse.ts"},{"uid":"b111ad13-3","name":"registry.ts"},{"uid":"b111ad13-5","name":"use-hotkey.ts"},{"uid":"b111ad13-7","name":"use-hotkey-scope.ts"},{"uid":"b111ad13-9","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"b111ad13-1":{"renderedLength":1941,"gzipLength":838,"brotliLength":0,"metaUid":"b111ad13-0"},"b111ad13-3":{"renderedLength":2918,"gzipLength":1080,"brotliLength":0,"metaUid":"b111ad13-2"},"b111ad13-5":{"renderedLength":496,"gzipLength":295,"brotliLength":0,"metaUid":"b111ad13-4"},"b111ad13-7":{"renderedLength":421,"gzipLength":264,"brotliLength":0,"metaUid":"b111ad13-6"},"b111ad13-9":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"b111ad13-8"}},"nodeMetas":{"b111ad13-0":{"id":"/src/parse.ts","moduleParts":{"index.js":"b111ad13-1"},"imported":[],"importedBy":[{"uid":"b111ad13-8"},{"uid":"b111ad13-2"}]},"b111ad13-2":{"id":"/src/registry.ts","moduleParts":{"index.js":"b111ad13-3"},"imported":[{"uid":"b111ad13-11"},{"uid":"b111ad13-0"}],"importedBy":[{"uid":"b111ad13-8"},{"uid":"b111ad13-4"},{"uid":"b111ad13-6"}]},"b111ad13-4":{"id":"/src/use-hotkey.ts","moduleParts":{"index.js":"b111ad13-5"},"imported":[{"uid":"b111ad13-10"},{"uid":"b111ad13-2"}],"importedBy":[{"uid":"b111ad13-8"}]},"b111ad13-6":{"id":"/src/use-hotkey-scope.ts","moduleParts":{"index.js":"b111ad13-7"},"imported":[{"uid":"b111ad13-10"},{"uid":"b111ad13-2"}],"importedBy":[{"uid":"b111ad13-8"}]},"b111ad13-8":{"id":"/src/index.ts","moduleParts":{"index.js":"b111ad13-9"},"imported":[{"uid":"b111ad13-4"},{"uid":"b111ad13-6"},{"uid":"b111ad13-2"},{"uid":"b111ad13-0"}],"importedBy":[],"isEntry":true},"b111ad13-10":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"b111ad13-4"},{"uid":"b111ad13-6"}]},"b111ad13-11":{"id":"@pyreon/reactivity","moduleParts":{},"imported":[],"importedBy":[{"uid":"b111ad13-2"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
+    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"uid":"7a21fee1-1","name":"parse.ts"},{"uid":"7a21fee1-3","name":"registry.ts"},{"uid":"7a21fee1-5","name":"use-hotkey.ts"},{"uid":"7a21fee1-7","name":"use-hotkey-scope.ts"},{"uid":"7a21fee1-9","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"7a21fee1-1":{"renderedLength":1941,"gzipLength":838,"brotliLength":0,"metaUid":"7a21fee1-0"},"7a21fee1-3":{"renderedLength":3232,"gzipLength":1141,"brotliLength":0,"metaUid":"7a21fee1-2"},"7a21fee1-5":{"renderedLength":496,"gzipLength":295,"brotliLength":0,"metaUid":"7a21fee1-4"},"7a21fee1-7":{"renderedLength":421,"gzipLength":264,"brotliLength":0,"metaUid":"7a21fee1-6"},"7a21fee1-9":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"7a21fee1-8"}},"nodeMetas":{"7a21fee1-0":{"id":"/src/parse.ts","moduleParts":{"index.js":"7a21fee1-1"},"imported":[],"importedBy":[{"uid":"7a21fee1-8"},{"uid":"7a21fee1-2"}]},"7a21fee1-2":{"id":"/src/registry.ts","moduleParts":{"index.js":"7a21fee1-3"},"imported":[{"uid":"7a21fee1-11"},{"uid":"7a21fee1-0"}],"importedBy":[{"uid":"7a21fee1-8"},{"uid":"7a21fee1-4"},{"uid":"7a21fee1-6"}]},"7a21fee1-4":{"id":"/src/use-hotkey.ts","moduleParts":{"index.js":"7a21fee1-5"},"imported":[{"uid":"7a21fee1-10"},{"uid":"7a21fee1-2"}],"importedBy":[{"uid":"7a21fee1-8"}]},"7a21fee1-6":{"id":"/src/use-hotkey-scope.ts","moduleParts":{"index.js":"7a21fee1-7"},"imported":[{"uid":"7a21fee1-10"},{"uid":"7a21fee1-2"}],"importedBy":[{"uid":"7a21fee1-8"}]},"7a21fee1-8":{"id":"/src/index.ts","moduleParts":{"index.js":"7a21fee1-9"},"imported":[{"uid":"7a21fee1-4"},{"uid":"7a21fee1-6"},{"uid":"7a21fee1-2"},{"uid":"7a21fee1-0"}],"importedBy":[],"isEntry":true},"7a21fee1-10":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"7a21fee1-4"},{"uid":"7a21fee1-6"}]},"7a21fee1-11":{"id":"@pyreon/reactivity","moduleParts":{},"imported":[],"importedBy":[{"uid":"7a21fee1-2"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
 
     const run = () => {
       const width = window.innerWidth;

package/lib/index.js

@@ -75,6 +75,7 @@ function isMac() {
 const entries = [];
 const activeScopes = signal(new Set(["global"]));
 let listenerAttached = false;
+let keydownHandler = null;
 const INPUT_TAGS = new Set([
 	"INPUT",
 	"TEXTAREA",
@@ -91,7 +92,7 @@ function attachListener() {
 	if (listenerAttached) return;
 	if (typeof window === "undefined") return;
 	listenerAttached = true;
-	window.addEventListener("keydown", (event) => {
+	keydownHandler = (event) => {
 		const scopes = activeScopes.peek();
 		for (const entry of entries) {
 			if (!scopes.has(entry.options.scope)) continue;
@@ -102,7 +103,14 @@ function attachListener() {
 			if (entry.options.stopPropagation) event.stopPropagation();
 			entry.handler(event);
 		}
-	});
+	};
+	window.addEventListener("keydown", keydownHandler);
+}
+function detachListener() {
+	if (!listenerAttached || !keydownHandler) return;
+	window.removeEventListener("keydown", keydownHandler);
+	listenerAttached = false;
+	keydownHandler = null;
 }
 /**
 * Register a keyboard shortcut. Returns an unregister function.
@@ -132,6 +140,7 @@ function registerHotkey(shortcut, handler, options) {
 	return () => {
 		const idx = entries.indexOf(entry);
 		if (idx !== -1) entries.splice(idx, 1);
+		if (entries.length === 0) detachListener();
 	};
 }
 /**
@@ -174,6 +183,7 @@ function getRegisteredHotkeys() {
 function _resetHotkeys() {
 	entries.length = 0;
 	activeScopes.set(new Set(["global"]));
+	detachListener();
 }
 
 //#endregion

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/parse.ts","../src/registry.ts","../src/use-hotkey.ts","../src/use-hotkey-scope.ts"],"sourcesContent":["import type { KeyCombo } from './types'\n\n// ─── Key aliases ─────────────────────────────────────────────────────────────\n\nconst KEY_ALIASES: Record<string, string> = {\n  esc: 'escape',\n  return: 'enter',\n  del: 'delete',\n  ins: 'insert',\n  space: ' ',\n  spacebar: ' ',\n  up: 'arrowup',\n  down: 'arrowdown',\n  left: 'arrowleft',\n  right: 'arrowright',\n  plus: '+',\n}\n\n/**\n * Parse a shortcut string like 'ctrl+shift+s' into a KeyCombo.\n * Supports aliases (esc, del, space, etc.) and mod (ctrl on Windows/Linux, meta on Mac).\n */\nexport function parseShortcut(shortcut: string): KeyCombo {\n  const parts = shortcut.toLowerCase().trim().split('+')\n  const combo: KeyCombo = {\n    ctrl: false,\n    shift: false,\n    alt: false,\n    meta: false,\n    key: '',\n  }\n\n  for (const part of parts) {\n    const p = part.trim()\n    if (p === 'ctrl' || p === 'control') {\n      combo.ctrl = true\n    } else if (p === 'shift') {\n      combo.shift = true\n    } else if (p === 'alt') {\n      combo.alt = true\n    } else if (p === 'meta' || p === 'cmd' || p === 'command') {\n      combo.meta = true\n    } else if (p === 'mod') {\n      // mod = meta on Mac, ctrl elsewhere\n      if (isMac()) {\n        combo.meta = true\n      } else {\n        combo.ctrl = true\n      }\n    } else {\n      combo.key = KEY_ALIASES[p] ?? p\n    }\n  }\n\n  return combo\n}\n\n/**\n * Check if a KeyboardEvent matches a KeyCombo.\n */\nexport function matchesCombo(event: KeyboardEvent, combo: KeyCombo): boolean {\n  if (event.ctrlKey !== combo.ctrl) return false\n  if (event.shiftKey !== combo.shift) return false\n  if (event.altKey !== combo.alt) return false\n  if (event.metaKey !== combo.meta) return false\n\n  const eventKey = event.key.toLowerCase()\n  return eventKey === combo.key\n}\n\n/**\n * Format a KeyCombo back to a human-readable string.\n */\nexport function formatCombo(combo: KeyCombo): string {\n  const parts: string[] = []\n  if (combo.ctrl) parts.push('Ctrl')\n  if (combo.shift) parts.push('Shift')\n  if (combo.alt) parts.push('Alt')\n  if (combo.meta) parts.push(isMac() ? '⌘' : 'Meta')\n  parts.push(combo.key.length === 1 ? combo.key.toUpperCase() : capitalize(combo.key))\n  return parts.join('+')\n}\n\nfunction capitalize(s: string): string {\n  return s.charAt(0).toUpperCase() + s.slice(1)\n}\n\nfunction isMac(): boolean {\n  if (typeof navigator === 'undefined') return false\n  return /mac|iphone|ipad|ipod/i.test(navigator.userAgent)\n}\n","import type { Signal } from '@pyreon/reactivity'\nimport { signal } from '@pyreon/reactivity'\nimport { matchesCombo, parseShortcut } from './parse'\nimport type { HotkeyEntry, HotkeyOptions } from './types'\n\n// ─── State ───────────────────────────────────────────────────────────────────\n\nconst entries: HotkeyEntry[] = []\nconst activeScopes = signal<Set<string>>(new Set(['global']))\nlet listenerAttached = false\n\n// ─── Input detection ─────────────────────────────────────────────────────────\n\nconst INPUT_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT'])\n\nfunction isInputFocused(event: KeyboardEvent): boolean {\n  const target = event.target as HTMLElement | null\n  if (!target) return false\n  if (INPUT_TAGS.has(target.tagName)) return true\n  if (target.isContentEditable) return true\n  return false\n}\n\n// ─── Global listener ─────────────────────────────────────────────────────────\n\nfunction attachListener(): void {\n  if (listenerAttached) return\n  if (typeof window === 'undefined') return\n  listenerAttached = true\n\n  window.addEventListener('keydown', (event) => {\n    const scopes = activeScopes.peek()\n\n    for (const entry of entries) {\n      // Check scope\n      if (!scopes.has(entry.options.scope)) continue\n\n      // Check enabled\n      const enabled =\n        typeof entry.options.enabled === 'function'\n          ? entry.options.enabled()\n          : entry.options.enabled\n      if (!enabled) continue\n\n      // Check input focus\n      if (!entry.options.enableOnInputs && isInputFocused(event)) continue\n\n      // Check key match\n      if (!matchesCombo(event, entry.combo)) continue\n\n      // Match found\n      if (entry.options.preventDefault) event.preventDefault()\n      if (entry.options.stopPropagation) event.stopPropagation()\n      entry.handler(event)\n    }\n  })\n}\n\n// ─── Registration ────────────────────────────────────────────────────────────\n\n/**\n * Register a keyboard shortcut. Returns an unregister function.\n *\n * @example\n * ```ts\n * const unregister = registerHotkey('ctrl+s', (e) => save(), { description: 'Save' })\n * // later: unregister()\n * ```\n */\nexport function registerHotkey(\n  shortcut: string,\n  handler: (event: KeyboardEvent) => void,\n  options?: HotkeyOptions,\n): () => void {\n  attachListener()\n\n  const entry: HotkeyEntry = {\n    shortcut,\n    combo: parseShortcut(shortcut),\n    handler,\n    options: {\n      scope: options?.scope ?? 'global',\n      preventDefault: options?.preventDefault !== false,\n      stopPropagation: options?.stopPropagation === true,\n      enableOnInputs: options?.enableOnInputs === true,\n      enabled: options?.enabled ?? true,\n      ...(options?.description != null ? { description: options.description } : {}),\n    },\n  }\n\n  entries.push(entry)\n\n  return () => {\n    const idx = entries.indexOf(entry)\n    if (idx !== -1) entries.splice(idx, 1)\n  }\n}\n\n// ─── Scope management ────────────────────────────────────────────────────────\n\n/**\n * Activate a hotkey scope. 'global' is always active.\n */\nexport function enableScope(scope: string): void {\n  const current = activeScopes.peek()\n  if (current.has(scope)) return\n  const next = new Set(current)\n  next.add(scope)\n  activeScopes.set(next)\n}\n\n/**\n * Deactivate a hotkey scope. Cannot deactivate 'global'.\n */\nexport function disableScope(scope: string): void {\n  if (scope === 'global') return\n  const current = activeScopes.peek()\n  if (!current.has(scope)) return\n  const next = new Set(current)\n  next.delete(scope)\n  activeScopes.set(next)\n}\n\n/**\n * Get the currently active scopes as a reactive signal.\n */\nexport function getActiveScopes(): Signal<Set<string>> {\n  return activeScopes\n}\n\n/**\n * Get all registered hotkeys (for building help dialogs).\n */\nexport function getRegisteredHotkeys(): ReadonlyArray<{\n  shortcut: string\n  scope: string\n  description?: string\n}> {\n  return entries.map((e) => ({\n    shortcut: e.shortcut,\n    scope: e.options.scope,\n    ...(e.options.description != null ? { description: e.options.description } : {}),\n  }))\n}\n\n// ─── Reset (for testing) ────────────────────────────────────────────────────\n\nexport function _resetHotkeys(): void {\n  entries.length = 0\n  activeScopes.set(new Set(['global']))\n}\n","import { onUnmount } from '@pyreon/core'\nimport { registerHotkey } from './registry'\nimport type { HotkeyOptions } from './types'\n\n/**\n * Register a keyboard shortcut scoped to a component's lifecycle.\n * Automatically unregisters when the component unmounts.\n *\n * @example\n * ```ts\n * function Editor() {\n *   useHotkey('ctrl+s', () => save(), { description: 'Save document' })\n *   useHotkey('ctrl+z', () => undo())\n *   useHotkey('ctrl+shift+z', () => redo())\n *   // ...\n * }\n * ```\n */\nexport function useHotkey(\n  shortcut: string,\n  handler: (event: KeyboardEvent) => void,\n  options?: HotkeyOptions,\n): void {\n  const unregister = registerHotkey(shortcut, handler, options)\n  onUnmount(unregister)\n}\n","import { onUnmount } from '@pyreon/core'\nimport { disableScope, enableScope } from './registry'\n\n/**\n * Activate a hotkey scope for the lifetime of a component.\n * When the component unmounts, the scope is deactivated.\n *\n * @example\n * ```tsx\n * function Modal() {\n *   useHotkeyScope('modal')\n *   useHotkey('escape', () => closeModal(), { scope: 'modal' })\n *   // ...\n * }\n * ```\n */\nexport function useHotkeyScope(scope: string): void {\n  enableScope(scope)\n  onUnmount(() => disableScope(scope))\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/parse.ts","../src/registry.ts","../src/use-hotkey.ts","../src/use-hotkey-scope.ts"],"sourcesContent":["import type { KeyCombo } from './types'\n\n// ─── Key aliases ─────────────────────────────────────────────────────────────\n\nconst KEY_ALIASES: Record<string, string> = {\n  esc: 'escape',\n  return: 'enter',\n  del: 'delete',\n  ins: 'insert',\n  space: ' ',\n  spacebar: ' ',\n  up: 'arrowup',\n  down: 'arrowdown',\n  left: 'arrowleft',\n  right: 'arrowright',\n  plus: '+',\n}\n\n/**\n * Parse a shortcut string like 'ctrl+shift+s' into a KeyCombo.\n * Supports aliases (esc, del, space, etc.) and mod (ctrl on Windows/Linux, meta on Mac).\n */\nexport function parseShortcut(shortcut: string): KeyCombo {\n  const parts = shortcut.toLowerCase().trim().split('+')\n  const combo: KeyCombo = {\n    ctrl: false,\n    shift: false,\n    alt: false,\n    meta: false,\n    key: '',\n  }\n\n  for (const part of parts) {\n    const p = part.trim()\n    if (p === 'ctrl' || p === 'control') {\n      combo.ctrl = true\n    } else if (p === 'shift') {\n      combo.shift = true\n    } else if (p === 'alt') {\n      combo.alt = true\n    } else if (p === 'meta' || p === 'cmd' || p === 'command') {\n      combo.meta = true\n    } else if (p === 'mod') {\n      // mod = meta on Mac, ctrl elsewhere\n      if (isMac()) {\n        combo.meta = true\n      } else {\n        combo.ctrl = true\n      }\n    } else {\n      combo.key = KEY_ALIASES[p] ?? p\n    }\n  }\n\n  return combo\n}\n\n/**\n * Check if a KeyboardEvent matches a KeyCombo.\n */\nexport function matchesCombo(event: KeyboardEvent, combo: KeyCombo): boolean {\n  if (event.ctrlKey !== combo.ctrl) return false\n  if (event.shiftKey !== combo.shift) return false\n  if (event.altKey !== combo.alt) return false\n  if (event.metaKey !== combo.meta) return false\n\n  const eventKey = event.key.toLowerCase()\n  return eventKey === combo.key\n}\n\n/**\n * Format a KeyCombo back to a human-readable string.\n */\nexport function formatCombo(combo: KeyCombo): string {\n  const parts: string[] = []\n  if (combo.ctrl) parts.push('Ctrl')\n  if (combo.shift) parts.push('Shift')\n  if (combo.alt) parts.push('Alt')\n  if (combo.meta) parts.push(isMac() ? '⌘' : 'Meta')\n  parts.push(combo.key.length === 1 ? combo.key.toUpperCase() : capitalize(combo.key))\n  return parts.join('+')\n}\n\nfunction capitalize(s: string): string {\n  return s.charAt(0).toUpperCase() + s.slice(1)\n}\n\nfunction isMac(): boolean {\n  if (typeof navigator === 'undefined') return false\n  return /mac|iphone|ipad|ipod/i.test(navigator.userAgent)\n}\n","import type { Signal } from '@pyreon/reactivity'\nimport { signal } from '@pyreon/reactivity'\nimport { matchesCombo, parseShortcut } from './parse'\nimport type { HotkeyEntry, HotkeyOptions } from './types'\n\n// ─── State ───────────────────────────────────────────────────────────────────\n\nconst entries: HotkeyEntry[] = []\nconst activeScopes = signal<Set<string>>(new Set(['global']))\nlet listenerAttached = false\nlet keydownHandler: ((event: KeyboardEvent) => void) | null = null\n\n// ─── Input detection ─────────────────────────────────────────────────────────\n\nconst INPUT_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT'])\n\nfunction isInputFocused(event: KeyboardEvent): boolean {\n  const target = event.target as HTMLElement | null\n  if (!target) return false\n  if (INPUT_TAGS.has(target.tagName)) return true\n  if (target.isContentEditable) return true\n  return false\n}\n\n// ─── Global listener ─────────────────────────────────────────────────────────\n\nfunction attachListener(): void {\n  if (listenerAttached) return\n  if (typeof window === 'undefined') return\n  listenerAttached = true\n\n  keydownHandler = (event) => {\n    const scopes = activeScopes.peek()\n\n    for (const entry of entries) {\n      // Check scope\n      if (!scopes.has(entry.options.scope)) continue\n\n      // Check enabled\n      const enabled =\n        typeof entry.options.enabled === 'function'\n          ? entry.options.enabled()\n          : entry.options.enabled\n      if (!enabled) continue\n\n      // Check input focus\n      if (!entry.options.enableOnInputs && isInputFocused(event)) continue\n\n      // Check key match\n      if (!matchesCombo(event, entry.combo)) continue\n\n      // Match found\n      if (entry.options.preventDefault) event.preventDefault()\n      if (entry.options.stopPropagation) event.stopPropagation()\n      entry.handler(event)\n    }\n  }\n\n  window.addEventListener('keydown', keydownHandler)\n}\n\nfunction detachListener(): void {\n  if (!listenerAttached || !keydownHandler) return\n  window.removeEventListener('keydown', keydownHandler)\n  listenerAttached = false\n  keydownHandler = null\n}\n\n// ─── Registration ────────────────────────────────────────────────────────────\n\n/**\n * Register a keyboard shortcut. Returns an unregister function.\n *\n * @example\n * ```ts\n * const unregister = registerHotkey('ctrl+s', (e) => save(), { description: 'Save' })\n * // later: unregister()\n * ```\n */\nexport function registerHotkey(\n  shortcut: string,\n  handler: (event: KeyboardEvent) => void,\n  options?: HotkeyOptions,\n): () => void {\n  attachListener()\n\n  const entry: HotkeyEntry = {\n    shortcut,\n    combo: parseShortcut(shortcut),\n    handler,\n    options: {\n      scope: options?.scope ?? 'global',\n      preventDefault: options?.preventDefault !== false,\n      stopPropagation: options?.stopPropagation === true,\n      enableOnInputs: options?.enableOnInputs === true,\n      enabled: options?.enabled ?? true,\n      ...(options?.description != null ? { description: options.description } : {}),\n    },\n  }\n\n  entries.push(entry)\n\n  return () => {\n    const idx = entries.indexOf(entry)\n    if (idx !== -1) entries.splice(idx, 1)\n\n    // Detach listener if no more entries\n    if (entries.length === 0) {\n      detachListener()\n    }\n  }\n}\n\n// ─── Scope management ────────────────────────────────────────────────────────\n\n/**\n * Activate a hotkey scope. 'global' is always active.\n */\nexport function enableScope(scope: string): void {\n  const current = activeScopes.peek()\n  if (current.has(scope)) return\n  const next = new Set(current)\n  next.add(scope)\n  activeScopes.set(next)\n}\n\n/**\n * Deactivate a hotkey scope. Cannot deactivate 'global'.\n */\nexport function disableScope(scope: string): void {\n  if (scope === 'global') return\n  const current = activeScopes.peek()\n  if (!current.has(scope)) return\n  const next = new Set(current)\n  next.delete(scope)\n  activeScopes.set(next)\n}\n\n/**\n * Get the currently active scopes as a reactive signal.\n */\nexport function getActiveScopes(): Signal<Set<string>> {\n  return activeScopes\n}\n\n/**\n * Get all registered hotkeys (for building help dialogs).\n */\nexport function getRegisteredHotkeys(): ReadonlyArray<{\n  shortcut: string\n  scope: string\n  description?: string\n}> {\n  return entries.map((e) => ({\n    shortcut: e.shortcut,\n    scope: e.options.scope,\n    ...(e.options.description != null ? { description: e.options.description } : {}),\n  }))\n}\n\n// ─── Reset (for testing) ────────────────────────────────────────────────\n\nexport function _resetHotkeys(): void {\n  entries.length = 0\n  activeScopes.set(new Set(['global']))\n  detachListener()\n}\n","import { onUnmount } from '@pyreon/core'\nimport { registerHotkey } from './registry'\nimport type { HotkeyOptions } from './types'\n\n/**\n * Register a keyboard shortcut scoped to a component's lifecycle.\n * Automatically unregisters when the component unmounts.\n *\n * @example\n * ```ts\n * function Editor() {\n *   useHotkey('ctrl+s', () => save(), { description: 'Save document' })\n *   useHotkey('ctrl+z', () => undo())\n *   useHotkey('ctrl+shift+z', () => redo())\n *   // ...\n * }\n * ```\n */\nexport function useHotkey(\n  shortcut: string,\n  handler: (event: KeyboardEvent) => void,\n  options?: HotkeyOptions,\n): void {\n  const unregister = registerHotkey(shortcut, handler, options)\n  onUnmount(unregister)\n}\n","import { onUnmount } from '@pyreon/core'\nimport { disableScope, enableScope } from './registry'\n\n/**\n * Activate a hotkey scope for the lifetime of a component.\n * When the component unmounts, the scope is deactivated.\n *\n * @example\n * ```tsx\n * function Modal() {\n *   useHotkeyScope('modal')\n *   useHotkey('escape', () => closeModal(), { scope: 'modal' })\n *   // ...\n * }\n * ```\n */\nexport function useHotkeyScope(scope: string): void {\n  enableScope(scope)\n  onUnmount(() => disableScope(scope))\n}\n"],"mappings":"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"}

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/types.ts","../../../src/use-hotkey.ts","../../../src/use-hotkey-scope.ts","../../../src/registry.ts","../../../src/parse.ts"],"mappings":";;;;;;AAMA;UAAiB,QAAA;EACf,IAAA;EACA,KAAA;EACA,GAAA;EACA,IAAA;EACA,GAAA;AAAA;;;;UAMe,aAAA;EAAa;EAE5B,KAAA;EAF4B;EAI5B,cAAA;EAAA;EAEA,eAAA;EAEA;EAAA,cAAA;EAIA;EAFA,WAAA;EAEO;EAAP,OAAA;AAAA;;;;UAMe,WAAA;EASb;EAPF,QAAA;EAMiB;EAJjB,KAAA,EAAO,QAAA;EAFP;EAIA,OAAA,GAAU,KAAA,EAAO,aAAA;EAFV;EAIP,OAAA,EAAS,QAAA,CACP,IAAA,CACE,aAAA;IAGE,WAAA;EAAA;AAAA;;;;;AA1CR;;;;;;;;;;;AAWA;iBCCgB,SAAA,CACd,QAAA,UACA,OAAA,GAAU,KAAA,EAAO,aAAA,WACjB,OAAA,GAAU,aAAA;;;;;;ADfZ;;;;;;;;;;iBEUgB,cAAA,CAAe,KAAA;;;;AFV/B;;;;;;;;iBG+DgB,cAAA,CACd,QAAA,UACA,OAAA,GAAU,KAAA,EAAO,aAAA,WACjB,OAAA,GAAU,aAAA;;;AHvDZ;iBGsFgB,WAAA,CAAY,KAAA;;;;iBAWZ,YAAA,CAAa,KAAA;;;;iBAYb,eAAA,CAAA,GAAmB,MAAA,CAAO,GAAA;;;AH3F1C;iBGkGgB,oBAAA,CAAA,GAAwB,aAAA;EACtC,QAAA;EACA,KAAA;EACA,WAAA;AAAA;AAAA,iBAWc,aAAA,CAAA;;;;;AH7IhB;;iBIgBgB,aAAA,CAAc,QAAA,WAAmB,QAAA;;;;iBAsCjC,YAAA,CAAa,KAAA,EAAO,aAAA,EAAe,KAAA,EAAO,QAAA;;;;iBAa1C,WAAA,CAAY,KAAA,EAAO,QAAA"}
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/types.ts","../../../src/use-hotkey.ts","../../../src/use-hotkey-scope.ts","../../../src/registry.ts","../../../src/parse.ts"],"mappings":";;;;;;AAMA;UAAiB,QAAA;EACf,IAAA;EACA,KAAA;EACA,GAAA;EACA,IAAA;EACA,GAAA;AAAA;;;;UAMe,aAAA;EAAa;EAE5B,KAAA;EAF4B;EAI5B,cAAA;EAAA;EAEA,eAAA;EAEA;EAAA,cAAA;EAIA;EAFA,WAAA;EAEO;EAAP,OAAA;AAAA;;;;UAMe,WAAA;EASb;EAPF,QAAA;EAMiB;EAJjB,KAAA,EAAO,QAAA;EAFP;EAIA,OAAA,GAAU,KAAA,EAAO,aAAA;EAFV;EAIP,OAAA,EAAS,QAAA,CACP,IAAA,CACE,aAAA;IAGE,WAAA;EAAA;AAAA;;;;;AA1CR;;;;;;;;;;;AAWA;iBCCgB,SAAA,CACd,QAAA,UACA,OAAA,GAAU,KAAA,EAAO,aAAA,WACjB,OAAA,GAAU,aAAA;;;;;;ADfZ;;;;;;;;;;iBEUgB,cAAA,CAAe,KAAA;;;;AFV/B;;;;;;;;iBGyEgB,cAAA,CACd,QAAA,UACA,OAAA,GAAU,KAAA,EAAO,aAAA,WACjB,OAAA,GAAU,aAAA;;;AHjEZ;iBGqGgB,WAAA,CAAY,KAAA;;;;iBAWZ,YAAA,CAAa,KAAA;;;;iBAYb,eAAA,CAAA,GAAmB,MAAA,CAAO,GAAA;;;AH1G1C;iBGiHgB,oBAAA,CAAA,GAAwB,aAAA;EACtC,QAAA;EACA,KAAA;EACA,WAAA;AAAA;AAAA,iBAWc,aAAA,CAAA;;;;;AH5JhB;;iBIgBgB,aAAA,CAAc,QAAA,WAAmB,QAAA;;;;iBAsCjC,YAAA,CAAa,KAAA,EAAO,aAAA,EAAe,KAAA,EAAO,QAAA;;;;iBAa1C,WAAA,CAAY,KAAA,EAAO,QAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/hotkeys",
-  "version": "0.12.14",
+  "version": "0.13.0",
   "description": "Reactive keyboard shortcut management for Pyreon — scope-aware, conflict detection",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/hotkeys#readme",
   "bugs": {
@@ -42,12 +42,13 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
-    "@pyreon/core": "^0.12.14",
-    "@pyreon/reactivity": "^0.12.14",
+    "@pyreon/core": "^0.13.0",
+    "@pyreon/manifest": "0.13.0",
+    "@pyreon/reactivity": "^0.13.0",
     "@vitus-labs/tools-lint": "^1.15.5"
   },
   "peerDependencies": {
-    "@pyreon/core": "^0.12.14",
-    "@pyreon/reactivity": "^0.12.14"
+    "@pyreon/core": "^0.13.0",
+    "@pyreon/reactivity": "^0.13.0"
   }
 }

package/src/manifest.ts

@@ -0,0 +1,119 @@
+import { defineManifest } from '@pyreon/manifest'
+
+export default defineManifest({
+  name: '@pyreon/hotkeys',
+  title: 'Keyboard Shortcuts',
+  tagline:
+    'Keyboard shortcut management — scope-aware, modifier keys, conflict detection',
+  description:
+    'Reactive keyboard shortcut management for Pyreon. Register global or scoped shortcuts with automatic lifecycle management. Supports `mod` alias (Command on Mac, Ctrl elsewhere), multi-key combos, scope-based activation for context-aware shortcuts, and conflict detection. Component-scoped hooks auto-unregister on unmount. Imperative API available for non-component contexts.',
+  category: 'universal',
+  longExample: `import { useHotkey, useHotkeyScope, registerHotkey, getRegisteredHotkeys, enableScope, disableScope } from '@pyreon/hotkeys'
+
+// Global shortcut — auto-unregisters on unmount
+useHotkey('mod+s', (e) => {
+  e.preventDefault()  // prevent browser save dialog
+  save()
+}, { description: 'Save document' })
+
+// Platform-aware: mod = ⌘ on Mac, Ctrl on Windows/Linux
+useHotkey('mod+k', () => openCommandPalette())
+
+// Multi-key combo
+useHotkey('ctrl+shift+p', () => openPreferences())
+
+// Scoped shortcuts — only active when scope is enabled
+useHotkeyScope('editor')  // activates 'editor' scope for this component's lifetime
+
+useHotkey('ctrl+z', () => undo(), { scope: 'editor', description: 'Undo' })
+useHotkey('ctrl+shift+z', () => redo(), { scope: 'editor', description: 'Redo' })
+useHotkey('ctrl+d', () => duplicateLine(), { scope: 'editor' })
+
+// Imperative API — for non-component contexts (stores, middleware)
+const unregister = registerHotkey('ctrl+q', () => quit(), { scope: 'global' })
+// unregister() when done
+
+// Introspection
+const hotkeys = getRegisteredHotkeys()  // all registered shortcuts
+enableScope('modal')                     // programmatically enable a scope
+disableScope('editor')                   // programmatically disable a scope
+
+// Shortcuts can filter input elements — by default, shortcuts
+// don't fire when focused on <input>, <textarea>, <select>.
+// Override with:
+useHotkey('escape', () => closeModal(), { enableOnFormElements: true })`,
+  features: [
+    'useHotkey(shortcut, handler, options?) — component-scoped, auto-unregisters on unmount',
+    'useHotkeyScope(scope) — activate a scope for a component\'s lifetime',
+    'mod alias — Command on Mac, Ctrl elsewhere',
+    'Scope-based activation for context-aware shortcuts',
+    'Imperative API: registerHotkey, enableScope, disableScope, getRegisteredHotkeys',
+    'parseShortcut / matchesCombo / formatCombo utilities',
+  ],
+  api: [
+    {
+      name: 'useHotkey',
+      kind: 'hook',
+      signature:
+        '(shortcut: string, handler: (e: KeyboardEvent) => void, options?: HotkeyOptions) => void',
+      summary:
+        'Register a keyboard shortcut that auto-unregisters when the component unmounts. Shortcut format: `mod+s`, `ctrl+shift+p`, `escape`, etc. `mod` is Command on Mac, Ctrl elsewhere. By default, shortcuts don\'t fire when focused on form elements (input, textarea, select) — override with `enableOnFormElements: true`. Supports `scope` option for context-aware activation and `description` for introspection.',
+      example: `useHotkey('mod+s', (e) => {
+  e.preventDefault()
+  save()
+}, { description: 'Save' })
+
+useHotkey('ctrl+z', () => undo(), { scope: 'editor' })
+useHotkey('escape', () => close(), { enableOnFormElements: true })`,
+      mistakes: [
+        'Forgetting e.preventDefault() for browser-reserved shortcuts (mod+s, mod+p) — the browser dialog fires alongside your handler',
+        'Registering the same shortcut in overlapping scopes without priority — both handlers fire; use scope isolation to prevent conflicts',
+        'Using useHotkey outside a component body — the onUnmount cleanup requires an active component setup context',
+        'Not activating the scope — useHotkey with a scope option does nothing unless useHotkeyScope(scope) is called or enableScope(scope) is invoked',
+      ],
+      seeAlso: ['useHotkeyScope', 'registerHotkey'],
+    },
+    {
+      name: 'useHotkeyScope',
+      kind: 'hook',
+      signature: '(scope: string) => void',
+      summary:
+        'Activate a hotkey scope for the lifetime of the current component. When the component mounts, the scope is enabled; when it unmounts, the scope is disabled. Shortcuts registered with a matching `scope` option only fire when the scope is active. Multiple components can activate the same scope — it stays active until the last one unmounts.',
+      example: `// In an editor component:
+useHotkeyScope('editor')
+useHotkey('ctrl+z', () => undo(), { scope: 'editor' })
+
+// In a modal component:
+useHotkeyScope('modal')
+useHotkey('escape', () => close(), { scope: 'modal' })`,
+      mistakes: [
+        'Using useHotkeyScope outside a component body — the lifecycle hooks require an active setup context',
+        'Assuming scope deactivation is immediate on unmount — if another component also activated the scope, it stays active',
+      ],
+      seeAlso: ['useHotkey', 'enableScope', 'disableScope'],
+    },
+    {
+      name: 'registerHotkey',
+      kind: 'function',
+      signature:
+        '(shortcut: string, handler: (e: KeyboardEvent) => void, options?: HotkeyOptions) => () => void',
+      summary:
+        'Imperative hotkey registration for non-component contexts (stores, global setup). Returns an unregister function. Unlike useHotkey, this does NOT auto-cleanup on unmount — caller is responsible for calling the returned unregister function.',
+      example: `const unregister = registerHotkey('ctrl+q', () => quit(), { scope: 'global' })
+// Later:
+unregister()`,
+      seeAlso: ['useHotkey'],
+    },
+  ],
+  gotchas: [
+    'By default, shortcuts do NOT fire when focused on form elements (input, textarea, select). Pass `enableOnFormElements: true` in options to override. Escape is a common candidate for this override.',
+    {
+      label: 'mod alias',
+      note: '`mod` maps to Command on macOS, Ctrl on Windows/Linux. Write `mod+s` instead of platform-specific `ctrl+s` / `cmd+s` for cross-platform shortcuts.',
+    },
+    {
+      label: 'Scopes',
+      note: 'Scoped shortcuts only fire when their scope is active. Activate with `useHotkeyScope(scope)` (component-scoped) or `enableScope(scope)` (imperative). Without activation, scoped handlers are silently dormant.',
+    },
+  ],
+})

package/src/registry.ts

@@ -8,6 +8,7 @@ import type { HotkeyEntry, HotkeyOptions } from './types'
 const entries: HotkeyEntry[] = []
 const activeScopes = signal<Set<string>>(new Set(['global']))
 let listenerAttached = false
+let keydownHandler: ((event: KeyboardEvent) => void) | null = null
 
 // ─── Input detection ─────────────────────────────────────────────────────────
 
@@ -28,7 +29,7 @@ function attachListener(): void {
   if (typeof window === 'undefined') return
   listenerAttached = true
 
-  window.addEventListener('keydown', (event) => {
+  keydownHandler = (event) => {
     const scopes = activeScopes.peek()
 
     for (const entry of entries) {
@@ -53,7 +54,16 @@ function attachListener(): void {
       if (entry.options.stopPropagation) event.stopPropagation()
       entry.handler(event)
     }
-  })
+  }
+
+  window.addEventListener('keydown', keydownHandler)
+}
+
+function detachListener(): void {
+  if (!listenerAttached || !keydownHandler) return
+  window.removeEventListener('keydown', keydownHandler)
+  listenerAttached = false
+  keydownHandler = null
 }
 
 // ─── Registration ────────────────────────────────────────────────────────────
@@ -93,6 +103,11 @@ export function registerHotkey(
   return () => {
     const idx = entries.indexOf(entry)
     if (idx !== -1) entries.splice(idx, 1)
+
+    // Detach listener if no more entries
+    if (entries.length === 0) {
+      detachListener()
+    }
   }
 }
 
@@ -143,9 +158,10 @@ export function getRegisteredHotkeys(): ReadonlyArray<{
   }))
 }
 
-// ─── Reset (for testing) ────────────────────────────────────────────────────
+// ─── Reset (for testing) ────────────────────────────────────────────────
 
 export function _resetHotkeys(): void {
   entries.length = 0
   activeScopes.set(new Set(['global']))
+  detachListener()
 }

package/src/tests/hotkeys.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import {
   _resetHotkeys,
   disableScope,
@@ -457,3 +457,65 @@ describe('getRegisteredHotkeys', () => {
     expect(getRegisteredHotkeys()).toHaveLength(0)
   })
 })
+
+describe('Event listener cleanup', () => {
+  beforeEach(() => {
+    _resetHotkeys()
+  })
+
+  afterEach(() => {
+    _resetHotkeys()
+  })
+
+  it('attaches listener on first registration', () => {
+    const addEventListenerSpy = vi.spyOn(window, 'addEventListener')
+    const noop = () => {}
+
+    registerHotkey('ctrl+s', noop)
+
+    expect(addEventListenerSpy).toHaveBeenCalledWith('keydown', expect.any(Function))
+    addEventListenerSpy.mockRestore()
+  })
+
+  it('detaches listener when all hotkeys are unregistered', () => {
+    const removeEventListenerSpy = vi.spyOn(window, 'removeEventListener')
+    const noop = () => {}
+
+    const unsub1 = registerHotkey('ctrl+s', noop)
+    const unsub2 = registerHotkey('ctrl+z', noop)
+
+    // Both registered — listener still attached
+    unsub1()
+    expect(removeEventListenerSpy).not.toHaveBeenCalled()
+
+    // Last one unregistered — listener should detach
+    unsub2()
+    expect(removeEventListenerSpy).toHaveBeenCalledWith('keydown', expect.any(Function))
+
+    removeEventListenerSpy.mockRestore()
+  })
+
+  it('reattaches listener when new hotkey registered after cleanup', () => {
+    const addEventListenerSpy = vi.spyOn(window, 'addEventListener')
+    const removeEventListenerSpy = vi.spyOn(window, 'removeEventListener')
+    const noop = () => {}
+
+    const unsub1 = registerHotkey('ctrl+s', noop)
+    expect(addEventListenerSpy).toHaveBeenCalledTimes(1)
+
+    unsub1()
+    expect(removeEventListenerSpy).toHaveBeenCalledTimes(1)
+
+    // Register new hotkey — should reattach
+    registerHotkey('ctrl+z', noop)
+    expect(addEventListenerSpy).toHaveBeenCalledTimes(2)
+
+    addEventListenerSpy.mockRestore()
+    removeEventListenerSpy.mockRestore()
+  })
+
+  it('preserves vi for test environment', () => {
+    // This test just verifies vi is available (vitest spy helpers)
+    expect(typeof vi).toBe('object')
+  })
+})

package/src/tests/manifest-snapshot.test.ts

@@ -0,0 +1,69 @@
+import {
+  renderApiReferenceEntries,
+  renderLlmsFullSection,
+  renderLlmsTxtLine,
+} from '@pyreon/manifest'
+import manifest from '../manifest'
+
+describe('gen-docs — hotkeys snapshot', () => {
+  it('renders to llms.txt bullet', () => {
+    expect(renderLlmsTxtLine(manifest)).toMatchInlineSnapshot(`"- @pyreon/hotkeys — Keyboard shortcut management — scope-aware, modifier keys, conflict detection. By default, shortcuts do NOT fire when focused on form elements (input, textarea, select). Pass \`enableOnFormElements: true\` in options to override. Escape is a common candidate for this override."`)
+  })
+
+  it('renders to llms-full.txt section', () => {
+    expect(renderLlmsFullSection(manifest)).toMatchInlineSnapshot(`
+      "## @pyreon/hotkeys — Keyboard Shortcuts
+
+      Reactive keyboard shortcut management for Pyreon. Register global or scoped shortcuts with automatic lifecycle management. Supports \`mod\` alias (Command on Mac, Ctrl elsewhere), multi-key combos, scope-based activation for context-aware shortcuts, and conflict detection. Component-scoped hooks auto-unregister on unmount. Imperative API available for non-component contexts.
+
+      \`\`\`typescript
+      import { useHotkey, useHotkeyScope, registerHotkey, getRegisteredHotkeys, enableScope, disableScope } from '@pyreon/hotkeys'
+
+      // Global shortcut — auto-unregisters on unmount
+      useHotkey('mod+s', (e) => {
+        e.preventDefault()  // prevent browser save dialog
+        save()
+      }, { description: 'Save document' })
+
+      // Platform-aware: mod = ⌘ on Mac, Ctrl on Windows/Linux
+      useHotkey('mod+k', () => openCommandPalette())
+
+      // Multi-key combo
+      useHotkey('ctrl+shift+p', () => openPreferences())
+
+      // Scoped shortcuts — only active when scope is enabled
+      useHotkeyScope('editor')  // activates 'editor' scope for this component's lifetime
+
+      useHotkey('ctrl+z', () => undo(), { scope: 'editor', description: 'Undo' })
+      useHotkey('ctrl+shift+z', () => redo(), { scope: 'editor', description: 'Redo' })
+      useHotkey('ctrl+d', () => duplicateLine(), { scope: 'editor' })
+
+      // Imperative API — for non-component contexts (stores, middleware)
+      const unregister = registerHotkey('ctrl+q', () => quit(), { scope: 'global' })
+      // unregister() when done
+
+      // Introspection
+      const hotkeys = getRegisteredHotkeys()  // all registered shortcuts
+      enableScope('modal')                     // programmatically enable a scope
+      disableScope('editor')                   // programmatically disable a scope
+
+      // Shortcuts can filter input elements — by default, shortcuts
+      // don't fire when focused on <input>, <textarea>, <select>.
+      // Override with:
+      useHotkey('escape', () => closeModal(), { enableOnFormElements: true })
+      \`\`\`
+
+      > **Note**: By default, shortcuts do NOT fire when focused on form elements (input, textarea, select). Pass \`enableOnFormElements: true\` in options to override. Escape is a common candidate for this override.
+      >
+      > **mod alias**: \`mod\` maps to Command on macOS, Ctrl on Windows/Linux. Write \`mod+s\` instead of platform-specific \`ctrl+s\` / \`cmd+s\` for cross-platform shortcuts.
+      >
+      > **Scopes**: Scoped shortcuts only fire when their scope is active. Activate with \`useHotkeyScope(scope)\` (component-scoped) or \`enableScope(scope)\` (imperative). Without activation, scoped handlers are silently dormant.
+      "
+    `)
+  })
+
+  it('renders to MCP api-reference entries', () => {
+    const record = renderApiReferenceEntries(manifest)
+    expect(Object.keys(record).length).toBe(3)
+  })
+})