@remcostoeten/use-shortcut 2.0.1 → 2.1.0

package/README.md

@@ -18,6 +18,8 @@ WIP keyboard shortcut library for React with a chainable API.
   - Runtime controls: `setScopes`, `enableScope`, `disableScope`, `getScopes`, `isScopeActive`
 - Exception predicates/presets with `.except(...)`
 - Recording mode: `$.record({ timeoutMs })`
+- Structured debug stream: `$.onDebug(...)` for every keypress
+- Per-shortcut attempt inspection: `result.onAttempt((matched, event, details) => ...)`
 - Conflict detection (`exact`, `sequence-prefix`)
 - Priority ordering and `stopOnMatch`
 - Global guard/filter support via `eventFilter`
@@ -68,6 +70,31 @@ function App() {
 
 If you already have a builder from `useShortcut()`, you can bulk register with `registerShortcutMap($, shortcutMap)` and unbind the returned handles on cleanup.
 
+## Debug Example
+
+```tsx
+const $ = useShortcut({
+  debug: {
+    console: true,
+    includeCode: true,
+    includeLocation: true,
+    includeKeyCode: true,
+  },
+})
+
+const unsubscribeDebug = $.onDebug((event) => {
+  console.log("key", event.input.combo, event.attempts)
+})
+
+const result = $.shift.key("e").then("e").on(runProbe, {
+  description: "sequence probe",
+})
+
+const unsubscribeAttempt = result.onAttempt?.((matched, _event, details) => {
+  console.log(matched ? "matched" : details?.status, details?.steps)
+})
+```
+
 ## Architecture Notes
 
 - Core runtime lives in `src/builder.ts`

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import{existsSync as h,mkdirSync as f,readFileSync as w,writeFileSync as x}from"fs";import{join as l,dirname as B}from"path";import{fileURLToPath as I}from"url";function m(t){return{"scopes.ts":`/** App-defined scope catalog used by the scaffolded provider. */
+import{existsSync as h,mkdirSync as f,readFileSync as A,writeFileSync as x}from"fs";import{join as l,dirname as B}from"path";import{fileURLToPath as I}from"url";function m(t){return{"scopes.ts":`/** App-defined scope catalog used by the scaffolded provider. */
 export const shortcutScopes = ["global", "navigation", "editor", "modal"] as const
 
 export type ShortcutScope = (typeof shortcutScopes)[number]
@@ -82,7 +82,7 @@ export type ShortcutContextValue = {
     actions: ShortcutActions
     meta: ShortcutMeta
 }
-`,"runtime.ts":`import type { ShortcutMap } from "@remcostoeten/use-shortcut"
+`,"runtime.ts":`import type { HandlerOptions, ShortcutMap } from "@remcostoeten/use-shortcut"
 import { shortcutRegistry, type ShortcutActionId, type ShortcutBindings } from "./registry"
 import type { ShortcutHandlers } from "./types"
 
@@ -120,11 +120,15 @@ export function buildShortcutMap(bindings: ShortcutBindings, handlers: ShortcutH
             continue
         }
 
+        const definitionOptions: Partial<HandlerOptions> = ("options" in definition && definition.options)
+            ? definition.options
+            : {}
+
         map[actionId] = {
             keys: bindings[actionId],
             handler,
             options: {
-                ...definition.options,
+                ...definitionOptions,
                 scopes: definition.scopes,
                 description: definition.description,
             },
@@ -431,6 +435,16 @@ It follows a scalable architecture with a strict split between:
 3. Optionally expose a user-configurable key in your settings UI through \`useShortcutManager().actions.setBinding\`.
 4. Activate scopes from feature boundaries (for example editor route enters \`editor\` scope).
 
+## Wiring A React App
+
+Scaffold the shortcut files into a React app shell:
+
+\`\`\`bash
+npx @remcostoeten/use-shortcut scaffold --framework react --target apps/shortcut-playground/src
+\`\`\`
+
+Then wire those generated files into your app root by wrapping your app in \`<ShortcutProvider handlers={...} />\`.
+
 ${t==="next"?"## Next.js Integration\n\n1. Create a client provider wrapper at `app/shortcut-provider.tsx` and render `<ShortcutProvider />` there.\n2. Render that provider inside `app/layout.tsx` around your app shell.\n3. Keep page/server components pure; shortcut handlers stay in client components.\n":"## React Integration\n\n1. Wrap your app root (for example in `main.tsx`) with `<ShortcutProvider />`.\n2. Keep handlers in a top-level client component and pass them to the provider via `handlers`.\n3. Use `useShortcutManager()` inside feature components to toggle scopes and bindings.\n"}
 ## Rules For Scale
 
@@ -438,16 +452,16 @@ ${t==="next"?"## Next.js Integration\n\n1. Create a client provider wrapper at `
 - Use scopes instead of conditionals in handlers.
 - Persist only key bindings, not executable handlers.
 - Treat \`registry.ts\` as your architectural contract.
-`}}var k=I(import.meta.url),_=B(k),e={reset:"\x1B[0m",green:"\x1B[32m",cyan:"\x1B[36m",yellow:"\x1B[33m",dim:"\x1B[2m",red:"\x1B[31m"};function r(t,o=e.reset){console.log(`${o}${t}${e.reset}`)}function O(){return l(_,"..","src")}function R(t){return l(process.cwd(),t,"use-shortcut")}function C(t,o){return l(process.cwd(),t,o)}function p(t,o,a){let s=t.indexOf(o);if(s===-1)return a;let n=t[s+1];return!n||n.startsWith("--")?a:n}function g(t,o){return t.includes(o)}var P=["index.ts","hook.ts","builder.ts","types.ts","parser.ts","constants.ts","formatter.ts","runtime/types.ts","runtime/binding.ts","runtime/conflicts.ts","runtime/debug.ts","runtime/guards.ts","runtime/keys.ts","runtime/listener.ts","runtime/recording.ts"];function E(t="hooks",o=!1){let a=O(),s=R(t);if(r(`
+`}}var k=I(import.meta.url),O=B(k),e={reset:"\x1B[0m",green:"\x1B[32m",cyan:"\x1B[36m",yellow:"\x1B[33m",dim:"\x1B[2m",red:"\x1B[31m"};function r(t,o=e.reset){console.log(`${o}${t}${e.reset}`)}function _(){return l(O,"..","src")}function R(t){return l(process.cwd(),t,"use-shortcut")}function C(t,o){return l(process.cwd(),t,o)}function p(t,o,a){let s=t.indexOf(o);if(s===-1)return a;let n=t[s+1];return!n||n.startsWith("--")?a:n}function g(t,o){return t.includes(o)}var P=["index.ts","hook.ts","builder.ts","types.ts","parser.ts","constants.ts","formatter.ts","runtime/types.ts","runtime/binding.ts","runtime/conflicts.ts","runtime/debug.ts","runtime/guards.ts","runtime/keys.ts","runtime/listener.ts","runtime/recording.ts"];function E(t="hooks",o=!1){let a=_(),s=R(t);if(r(`
 use-shortcut CLI
 `,e.cyan),h(s)&&!o){r(`Directory already exists: ${s}`,e.yellow),r(`Use --force to overwrite existing files
-`,e.dim);return}f(s,{recursive:!0});let n=0;for(let i of P){let c=l(a,i),d=l(s,i);if(f(B(d),{recursive:!0}),!h(c)){r(`Source file not found: ${i}`,e.yellow);continue}let u=w(c,"utf-8");x(d,u),n+=1,r(`  wrote ${i}`,e.green)}r(`
+`,e.dim);return}f(s,{recursive:!0});let n=0;for(let i of P){let c=l(a,i),d=l(s,i);if(f(B(d),{recursive:!0}),!h(c)){r(`Source file not found: ${i}`,e.yellow);continue}let u=A(c,"utf-8");x(d,u),n+=1,r(`  wrote ${i}`,e.green)}r(`
 Copied ${n} files to:`,e.green),r(`  ${s}
 `,e.dim),r("Usage:",e.cyan),r(`  import { useShortcut } from "@/${t}/use-shortcut"`,e.dim),r("  const $ = useShortcut()",e.dim),r(`  $.mod.key("k").on(() => console.log("Search"))
 `,e.dim)}function y(t,o="src",a="shortcuts",s=!1){let n=C(o,a),i=m(t);r(`
 use-shortcut CLI
 `,e.cyan),r(`Scaffolding ${t} architecture in ${n}
-`,e.dim),f(n,{recursive:!0});let c=0,d=0;for(let[u,A]of Object.entries(i)){let S=l(n,u);if(h(S)&&!s){d+=1,r(`  skipped ${u} (already exists)`,e.yellow);continue}x(S,A),c+=1,r(`  wrote ${u}`,e.green)}r("",e.reset),r(`Architecture scaffold complete: ${c} written, ${d} skipped.`,e.green),r(`Location: ${n}
+`,e.dim),f(n,{recursive:!0});let c=0,d=0;for(let[u,w]of Object.entries(i)){let S=l(n,u);if(h(S)&&!s){d+=1,r(`  skipped ${u} (already exists)`,e.yellow);continue}x(S,w),c+=1,r(`  wrote ${u}`,e.green)}r("",e.reset),r(`Architecture scaffold complete: ${c} written, ${d} skipped.`,e.green),r(`Location: ${n}
 `,e.dim),r("Next steps:",e.cyan),r(`  1. Open ${l(o,a,"registry.ts")} and define your action catalog`,e.dim),r("  2. Wire app handlers into <ShortcutProvider handlers={...} />",e.dim),r("  3. Toggle scopes from feature boundaries via useShortcutManager()",e.dim),r(`  4. Optionally expose setBinding/resetBinding in your settings UI
 `,e.dim)}function b(){r(`
 use-shortcut CLI

package/dist/index.d.ts

@@ -101,6 +101,57 @@ type ShortcutConflict = {
     existingCombo: string;
     reason: "exact" | "sequence-prefix";
 };
+type ShortcutAttemptStatus = "matched" | "partial" | "wrong-order" | "mismatch";
+type ShortcutDebugTokenStatus = "match" | "wrong-order" | "mismatch";
+type ShortcutDebugToken = {
+    token: string;
+    kind: "modifier" | "key";
+    status: ShortcutDebugTokenStatus;
+};
+type ShortcutDebugStep = {
+    index: number;
+    expected: string;
+    actual?: string;
+    status: "match" | "partial" | "pending" | "wrong-order" | "mismatch";
+    tokens: ShortcutDebugToken[];
+};
+type ShortcutDebugInput = {
+    key: string;
+    code: string;
+    location: number;
+    repeat: boolean;
+    keyCode?: number;
+    which?: number;
+    combo: string;
+    modifiers: ModifierState;
+};
+type ShortcutAttemptDebugEvent = {
+    combo: string;
+    display: string;
+    description?: string;
+    status: ShortcutAttemptStatus;
+    matched: boolean;
+    progress: number;
+    expectedSteps: string[];
+    actualSteps: string[];
+    stepIndex: number;
+    input: ShortcutDebugInput;
+    steps: ShortcutDebugStep[];
+};
+type ShortcutDebugEvent = {
+    input: ShortcutDebugInput;
+    attempts: ShortcutAttemptDebugEvent[];
+};
+type ShortcutDebugOptions = {
+    /** Log shortcut attempts to the console (default: true) */
+    console?: boolean;
+    /** Include `KeyboardEvent.code` in console output */
+    includeCode?: boolean;
+    /** Include `KeyboardEvent.location` in console output */
+    includeLocation?: boolean;
+    /** Include deprecated numeric key metadata in console output when available */
+    includeKeyCode?: boolean;
+};
 /**
  * Options for shortcut handler registration
  */
@@ -146,7 +197,7 @@ type ShortcutResult = {
     /** Temporarily disable the shortcut */
     disable: () => void;
     /** Subscribe to shortcut attempt events (useful for visual feedback) */
-    onAttempt?: (callback: (matched: boolean, event: KeyboardEvent) => void) => () => void;
+    onAttempt?: (callback: (matched: boolean, event: KeyboardEvent, details?: ShortcutAttemptDebugEvent) => void) => () => void;
 };
 /**
  * Chainable modifier builder with type-safe exhaustion
@@ -234,6 +285,8 @@ type ShortcutBuilder = ModifierChain<EmptyModifiers> & {
     getScopes: () => string[];
     /** Check if a scope is active */
     isScopeActive: (scope: string) => boolean;
+    /** Subscribe to every keyboard input evaluated by this shortcut registry */
+    onDebug: (callback: (event: ShortcutDebugEvent) => void) => () => void;
     /** Record the next key combo */
     record: (options?: ShortcutRecordingOptions) => Promise<string>;
 };
@@ -241,8 +294,8 @@ type ShortcutBuilder = ModifierChain<EmptyModifiers> & {
  * Options for the `useShortcut` hook
  */
 type UseShortcutOptions = {
-    /** Enable debug logging to console */
-    debug?: boolean;
+    /** Enable debug logging to console or configure structured debug output */
+    debug?: boolean | ShortcutDebugOptions;
     /** Global delay for all handlers in milliseconds */
     delay?: number;
     /** Skip shortcuts when focused on input elements (default: `true`) */
@@ -412,4 +465,4 @@ declare function createShortcutGroup(): ShortcutGroup;
  */
 declare function useShortcutGroup(): ShortcutGroup;
 
-export { type ActionKey, type AlphaKey, type ExceptPredicate, type ExceptPreset, type FunctionKey, type HandlerOptions, type KeyChain, ModifierAliases, type ModifierChain, ModifierDisplayOrder, ModifierDisplaySymbols, type ModifierFlags, ModifierKey, type ModifierName, type ModifierState, type NavigationKey, type NumericKey, type ParsedShortcut, Platform, type ShortcutBuilder, type ShortcutConflict, type ShortcutGroup, type ShortcutHandler, type ShortcutMap, type ShortcutMapEntry, type ShortcutMapResult, type ShortcutRecordingOptions, type ShortcutResult, type ShortcutScope, type SpecialKey, SpecialKeyMap, type SymbolKey, type UseShortcutOptions, createShortcutGroup, detectPlatform, formatShortcut, matchesAnyShortcut, matchesShortcut, parseShortcut, parseShortcuts, registerShortcutMap, useShortcut, useShortcutGroup, useShortcutMap };
+export { type ActionKey, type AlphaKey, type ExceptPredicate, type ExceptPreset, type FunctionKey, type HandlerOptions, type KeyChain, ModifierAliases, type ModifierChain, ModifierDisplayOrder, ModifierDisplaySymbols, type ModifierFlags, ModifierKey, type ModifierName, type ModifierState, type NavigationKey, type NumericKey, type ParsedShortcut, Platform, type ShortcutAttemptDebugEvent, type ShortcutAttemptStatus, type ShortcutBuilder, type ShortcutConflict, type ShortcutDebugEvent, type ShortcutDebugInput, type ShortcutDebugOptions, type ShortcutDebugStep, type ShortcutDebugToken, type ShortcutDebugTokenStatus, type ShortcutGroup, type ShortcutHandler, type ShortcutMap, type ShortcutMapEntry, type ShortcutMapResult, type ShortcutRecordingOptions, type ShortcutResult, type ShortcutScope, type SpecialKey, SpecialKeyMap, type SymbolKey, type UseShortcutOptions, createShortcutGroup, detectPlatform, formatShortcut, matchesAnyShortcut, matchesShortcut, parseShortcut, parseShortcuts, registerShortcutMap, useShortcut, useShortcutGroup, useShortcutMap };