@tooee/commands 0.1.19 → 0.1.21

package/src/index.ts

@@ -1,4 +1,5 @@
 export type {
+  ActiveCommandSurface,
   Command,
   CommandContext,
   CommandContextBase,
@@ -6,6 +7,8 @@ export type {
   CommandHandler,
   CommandSequenceCandidate,
   CommandSequenceState,
+  CommandSurfaceEntry,
+  CommandSurfaceRole,
   CommandWhen,
   ParsedHotkey,
   ParsedStep,
@@ -24,13 +27,36 @@ export type {
 } from "./sequence.js"
 export {
   CommandProvider,
+  CommandSurfaceProvider,
+  useActiveCommandSurface,
   useCommandContext,
   useCommandGroup,
   useCommandRegistry,
   useCommandSequenceState,
+  useCommandStore,
   useProvideCommandContext,
+  useSurfaceCommands,
 } from "./context.js"
-export type { CommandProviderProps } from "./context.js"
+export {
+  ROOT_SURFACE_ID,
+  createCommandStore,
+  selectActiveModalSurface,
+  selectGroups,
+  selectSequence,
+  selectSurfaceCommandMap,
+  selectSurfaceCommands,
+} from "./command-store.js"
+export type {
+  CommandStore,
+  CommandStoreConfig,
+  CommandStoreContext,
+  CommandStoreInstance,
+  ContextGetter,
+  CreateCommandStoreOptions,
+  KeyDispatchResult,
+  SurfaceRecord,
+} from "./command-store.js"
+export type { CommandProviderProps, CommandSurfaceProviderProps } from "./context.js"
 export { useCommand } from "./use-command.js"
 export type { UseCommandOptions } from "./use-command.js"
 export { useActions } from "./use-actions.js"

package/src/match.ts

@@ -10,5 +10,6 @@ export function matchStep(event: KeyEvent, step: ParsedStep): boolean {
   if (event.meta !== step.meta) return false
   if (event.shift !== step.shift) return false
   if (event.option !== step.option) return false
+  if ((event.super ?? false) !== (step.super ?? false)) return false
   return true
 }

package/src/mode.tsx

@@ -1,4 +1,12 @@
-import { createContext, useContext, useState, useCallback, useMemo, type ReactNode } from "react"
+import {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from "react"
 
 export type Mode = "cursor" | "insert" | "select"
 
@@ -12,11 +20,31 @@ const ModeContext = createContext<ModeContextValue | null>(null)
 export interface ModeProviderProps {
   children: ReactNode
   initialMode?: Mode
+  /**
+   * Internal: called synchronously whenever `setMode` changes the mode (not
+   * for same-value calls). Used by the command dispatcher to treat mode
+   * changes as transitions (sequence reset) instead of post-render repairs.
+   */
+  onModeChange?: (mode: Mode) => void
 }
 
-export function ModeProvider({ children, initialMode = "cursor" }: ModeProviderProps) {
+export function ModeProvider({
+  children,
+  initialMode = "cursor",
+  onModeChange,
+}: ModeProviderProps) {
   const [mode, setModeState] = useState<Mode>(initialMode)
-  const setMode = useCallback((m: Mode) => setModeState(m), [])
+  const modeRef = useRef(mode)
+  const onModeChangeRef = useRef(onModeChange)
+  onModeChangeRef.current = onModeChange
+
+  const setMode = useCallback((m: Mode) => {
+    if (m !== modeRef.current) {
+      modeRef.current = m
+      onModeChangeRef.current?.(m)
+    }
+    setModeState(m)
+  }, [])
 
   const value = useMemo<ModeContextValue>(() => ({ mode, setMode }), [mode, setMode])
 

package/src/parse.ts

@@ -15,6 +15,14 @@ function normalizeKey(key: string): string {
   return KEY_ALIASES[lower] ?? lower
 }
 
+const warned = new Set<string>()
+
+function warnOnce(message: string): void {
+  if (warned.has(message)) return
+  warned.add(message)
+  console.warn(message)
+}
+
 function parseStep(step: string): ParsedStep {
   const parts = step.toLowerCase().split("+")
   let key = ""
@@ -22,6 +30,7 @@ function parseStep(step: string): ParsedStep {
   let meta = false
   let shift = false
   let option = false
+  let superKey = false
 
   for (const part of parts) {
     const trimmed = part.trim()
@@ -34,13 +43,13 @@ function parseStep(step: string): ParsedStep {
     } else if (trimmed === "option") {
       option = true
     } else if (trimmed === "super") {
-      // super modifier — not tracked in ParsedStep currently
+      superKey = true
     } else {
       key = normalizeKey(trimmed)
     }
   }
 
-  return { key, ctrl, meta, shift, option }
+  return { key, ctrl, meta, shift, option, super: superKey }
 }
 
 /**
@@ -57,9 +66,15 @@ export function parseHotkey(hotkey: string, leaderKey?: string): ParsedHotkey {
   // Handle leader prefix
   const leaderMatch = trimmed.match(/^<leader>(.+)$/)
   if (leaderMatch) {
-    const leaderStep = leaderKey
-      ? parseStep(leaderKey)
-      : { key: "x", ctrl: true, meta: false, shift: false, option: false }
+    if (!leaderKey) {
+      // No leader configured: the hotkey must not spring to life on some
+      // invented default. Zero steps = unmatchable; the dispatcher skips it.
+      warnOnce(
+        `[tooee/commands] Hotkey "${trimmed}" uses <leader> but no leader key is configured; the hotkey is disabled.`,
+      )
+      return { steps: [] }
+    }
+    const leaderStep = parseStep(leaderKey)
     const followStep = parseStep(leaderMatch[1]!)
     return { steps: [leaderStep, followStep] }
   }

package/src/sequence.ts

@@ -19,6 +19,82 @@ export interface SequenceFeedResult {
   pending: SequencePendingMatch | null
 }
 
+// --- Pure matching helpers ---------------------------------------------------
+// These are the sequence-matching primitives, extracted so a store (or any
+// non-React dispatcher) can run them against its own buffer without
+// instantiating SequenceTracker. SequenceTracker delegates to them.
+
+/**
+ * True when the tail of `buffer` fully matches every step of `hotkey`.
+ * Zero-step hotkeys (e.g. a disabled leaderless `<leader>` binding) never
+ * match anything.
+ */
+export function matchesBuffer(buffer: readonly KeyEvent[], hotkey: ParsedHotkey): boolean {
+  const { steps } = hotkey
+  if (steps.length === 0) return false
+  if (buffer.length < steps.length) return false
+
+  const start = buffer.length - steps.length
+  for (let i = 0; i < steps.length; i++) {
+    if (!matchStep(buffer[start + i]!, steps[i]!)) return false
+  }
+  return true
+}
+
+/**
+ * Find the longest buffer tail that is a proper prefix of at least one hotkey.
+ * Returns the prefix length and the indexes of the hotkeys it could still
+ * complete, or null when nothing is pending.
+ */
+export function findPendingMatch(
+  buffer: readonly KeyEvent[],
+  hotkeys: readonly ParsedHotkey[],
+): SequencePendingMatch | null {
+  const maxPrefixLength = Math.min(
+    buffer.length,
+    Math.max(0, ...hotkeys.map((h) => h.steps.length - 1)),
+  )
+
+  for (let prefixLength = maxPrefixLength; prefixLength > 0; prefixLength--) {
+    const start = buffer.length - prefixLength
+    const indexes: number[] = []
+
+    for (let hotkeyIndex = 0; hotkeyIndex < hotkeys.length; hotkeyIndex++) {
+      const hotkey = hotkeys[hotkeyIndex]!
+      if (hotkey.steps.length <= prefixLength) continue
+
+      let matches = true
+      for (let i = 0; i < prefixLength; i++) {
+        if (!matchStep(buffer[start + i]!, hotkey.steps[i]!)) {
+          matches = false
+          break
+        }
+      }
+
+      if (matches) indexes.push(hotkeyIndex)
+    }
+
+    if (indexes.length > 0) return { prefixLength, indexes }
+  }
+
+  return null
+}
+
+/**
+ * Drop buffer entries older than the longest hotkey could ever consume.
+ * Returns the same array when nothing needs pruning.
+ */
+export function pruneBuffer(
+  buffer: readonly KeyEvent[],
+  hotkeys: readonly ParsedHotkey[],
+): readonly KeyEvent[] {
+  const maxLen = Math.max(0, ...hotkeys.map((h) => h.steps.length))
+  if (maxLen > 0 && buffer.length > maxLen) {
+    return buffer.slice(buffer.length - maxLen)
+  }
+  return buffer
+}
+
 export class SequenceTracker {
   private buffer: KeyEvent[] = []
   private timer: ReturnType<typeof setTimeout> | null = null
@@ -46,68 +122,20 @@ export class SequenceTracker {
     this.resetTimer()
 
     for (let i = 0; i < hotkeys.length; i++) {
-      const hotkey = hotkeys[i]!
-      if (this.matchesBuffer(hotkey)) {
+      if (matchesBuffer(this.buffer, hotkeys[i]!)) {
         this.reset()
         return { matchedIndex: i, pending: null }
       }
     }
 
     // Prune buffer if no hotkey could possibly match
-    const maxLen = Math.max(0, ...hotkeys.map((h) => h.steps.length))
-    if (maxLen > 0) {
-      while (this.buffer.length > maxLen) {
-        this.buffer.shift()
-      }
-    }
+    this.buffer = [...pruneBuffer(this.buffer, hotkeys)]
 
-    return { matchedIndex: -1, pending: this.findPendingMatch(hotkeys) }
+    return { matchedIndex: -1, pending: findPendingMatch(this.buffer, hotkeys) }
   }
 
   getPendingMatch(hotkeys: ParsedHotkey[]): SequencePendingMatch | null {
-    return this.findPendingMatch(hotkeys)
-  }
-
-  private matchesBuffer(hotkey: ParsedHotkey): boolean {
-    const { steps } = hotkey
-    if (this.buffer.length < steps.length) return false
-
-    const start = this.buffer.length - steps.length
-    for (let i = 0; i < steps.length; i++) {
-      if (!matchStep(this.buffer[start + i]!, steps[i]!)) return false
-    }
-    return true
-  }
-
-  private findPendingMatch(hotkeys: ParsedHotkey[]): SequencePendingMatch | null {
-    const maxPrefixLength = Math.min(
-      this.buffer.length,
-      Math.max(0, ...hotkeys.map((h) => h.steps.length - 1)),
-    )
-
-    for (let prefixLength = maxPrefixLength; prefixLength > 0; prefixLength--) {
-      const start = this.buffer.length - prefixLength
-      const indexes: number[] = []
-
-      for (let hotkeyIndex = 0; hotkeyIndex < hotkeys.length; hotkeyIndex++) {
-        const hotkey = hotkeys[hotkeyIndex]!
-        if (hotkey.steps.length <= prefixLength) continue
-
-        let matches = true
-        for (let i = 0; i < prefixLength; i++) {
-          if (!matchStep(this.buffer[start + i]!, hotkey.steps[i]!)) {
-            matches = false
-            break
-          }
-        }
-
-        if (matches) indexes.push(hotkeyIndex)
-      }
-
-      if (indexes.length > 0) return { prefixLength, indexes }
-    }
-
-    return null
+    return findPendingMatch(this.buffer, hotkeys)
   }
 
   reset(): void {

package/src/types.ts

@@ -7,9 +7,21 @@ export interface CommandContextBase {
   exit: () => void
 }
 
-export interface CommandContext extends CommandContextBase {
-  [key: string]: any
-}
+/**
+ * The context handed to command handlers. Domain packages contribute typed
+ * fields via module augmentation (the mechanism the shell already uses for
+ * `overlay` and `toast`):
+ *
+ * ```ts
+ * declare module "@tooee/commands" {
+ *   interface CommandContext {
+ *     myDomain: MyDomainContext
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface CommandContext extends CommandContextBase {}
 
 export type CommandHandler = (ctx: CommandContext) => void | Promise<void>
 export type CommandWhen = (ctx: CommandContext) => boolean
@@ -37,6 +49,8 @@ export interface ParsedStep {
   meta: boolean
   shift: boolean
   option: boolean
+  /** Super/Windows/Cmd-as-super modifier. Optional for back-compat. */
+  super?: boolean
 }
 
 export interface CommandRegistry {
@@ -45,6 +59,45 @@ export interface CommandRegistry {
   invoke: (id: string) => void
 }
 
+/**
+ * Interaction role of a command surface.
+ * - `modal`: owns keyboard input while topmost and suspends every lower surface
+ *   (including the root app) — even for keys it does not handle.
+ * - `passive`: never becomes the keyboard owner; purely visual.
+ */
+export type CommandSurfaceRole = "modal" | "passive"
+
+/**
+ * A command surface is an interaction surface that can own keyboard input.
+ * The root app is the implicit base surface; modal overlays push surfaces on
+ * top of it. Each surface carries its own command registry and local mode so
+ * the same command definitions can be rooted in a standalone app or pushed by
+ * an overlay without leaking mode/command state into the parent.
+ */
+export interface CommandSurfaceEntry {
+  id: string
+  role: CommandSurfaceRole
+  /** Nesting depth (root children are depth 0; the first overlay surface is 1). */
+  depth: number
+  /** Monotonic registration order, used to break depth ties. */
+  order: number
+  registry: CommandRegistry
+  /** Reads this surface's current local mode. */
+  getMode: () => Mode
+  /** Builds the command context handed to this surface's command handlers. */
+  buildCtx: () => CommandContext
+}
+
+export interface ActiveCommandSurface {
+  id: string
+  role: CommandSurfaceRole
+  /**
+   * Commands registered on this surface (reactive). Enables surface-aware
+   * which-key/help/palette consumers.
+   */
+  commands: readonly Command[]
+}
+
 export interface CommandGroup {
   id: string
   title: string

package/src/use-actions.ts

@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useRef } from "react"
-import { useCommandRegistry } from "./context.js"
+import { useSurfaceRegistry } from "./context.js"
 import type { Command, CommandHandler, CommandWhen } from "./types.js"
 import type { Mode } from "./mode.js"
 
@@ -17,7 +17,7 @@ export interface ActionDefinition {
 }
 
 export function useActions(actions: ActionDefinition[] | undefined): void {
-  const { registry } = useCommandRegistry()
+  const registry = useSurfaceRegistry()
   const actionsRef = useRef(actions)
   actionsRef.current = actions
 
@@ -26,7 +26,9 @@ export function useActions(actions: ActionDefinition[] | undefined): void {
       actions
         ?.map(
           (a) =>
-            `${a.id}:${a.title}:${a.hotkey ?? ""}:${a.category ?? ""}:${a.group ?? ""}:${a.icon ?? ""}:${a.hidden ?? false}`,
+            // modes and when-presence are frozen into the registration, so
+            // they must participate in the re-registration key.
+            `${a.id}:${a.title}:${a.hotkey ?? ""}:${a.category ?? ""}:${a.group ?? ""}:${a.icon ?? ""}:${a.hidden ?? false}:${a.modes?.join("|") ?? ""}:${a.when ? 1 : 0}`,
         )
         .join(",") ?? "",
     [actions],

package/src/use-command.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef } from "react"
 import type { Command, CommandHandler, CommandWhen } from "./types.js"
 import type { Mode } from "./mode.js"
-import { useCommandRegistry } from "./context.js"
+import { useSurfaceRegistry } from "./context.js"
 
 export interface UseCommandOptions {
   id: string
@@ -17,17 +17,26 @@ export interface UseCommandOptions {
 }
 
 export function useCommand(options: UseCommandOptions): void {
-  const { registry } = useCommandRegistry()
+  const registry = useSurfaceRegistry()
   const optionsRef = useRef(options)
   optionsRef.current = options
 
+  // Key on the modes CONTENT, not the array identity: callers pass inline
+  // array literals, and with a subscribable registry an identity-keyed effect
+  // would re-register on every render — re-notifying the subscriber that
+  // caused the render (an infinite update loop for components that both
+  // register and observe commands, e.g. the command palette provider).
+  const modesKey = options.modes?.join("|") ?? ""
+
   useEffect(() => {
     const command: Command = {
       id: options.id,
       title: options.title,
       handler: (...args: Parameters<Command["handler"]>) => optionsRef.current.handler(...args),
       defaultHotkey: options.hotkey,
-      modes: options.modes,
+      // Read through the ref: the effect is keyed on modesKey (content), and
+      // the ref holds the same-render options when the effect runs.
+      modes: optionsRef.current.modes,
       category: options.category,
       group: options.group,
       icon: options.icon,
@@ -39,7 +48,7 @@ export function useCommand(options: UseCommandOptions): void {
     options.id,
     options.title,
     options.hotkey,
-    options.modes,
+    modesKey,
     options.category,
     options.group,
     options.icon,