@tooee/commands 0.1.19 → 0.1.21

package/README.md

@@ -3,3 +3,36 @@
 Vim-inspired modal command system for Tooee.
 
 Part of the [Tooee](https://github.com/gingerhendrix/tooee) monorepo. See the main repo for documentation.
+
+## Raw `useKeyboard` policy
+
+App-level `useKeyboard` handlers MUST guard against active overlays — either
+stand down while an overlay is open, or be ported to `useCommand` registrations
+so the dispatcher arbitrates them:
+
+```tsx
+const hasOverlay = useHasOverlay() // from @tooee/overlays
+
+useKeyboard((key) => {
+  if (hasOverlay) return
+  // ...
+})
+```
+
+Why `key.preventDefault()` is **not** sufficient:
+
+- `useKeyboard` subscribes in an effect, and React runs child effects before
+  parent effects, so app-level raw handlers fire **before** the command
+  dispatcher. A modal surface's `preventDefault` cannot reach them even in
+  principle.
+- The dispatcher only calls `preventDefault()` on keys a command **matches**;
+  keys a modal surface merely swallows are never marked, so raw listeners see
+  them unprevented.
+
+An unguarded raw handler therefore double-handles keys while a modal overlay
+(theme picker, command palette, choose/ask overlays) is open — e.g. Escape
+exiting the app underneath an open picker. Inside `@tooee/commands` itself,
+`useActiveCommandSurface()` can serve as the guard where `@tooee/overlays` is
+not available. There is a regression test documenting this hazard in
+`test/surface.test.tsx` ("raw useKeyboard consumers bypass surface
+arbitration").

package/dist/command-store.d.ts

@@ -0,0 +1,147 @@
+import type { KeyEvent } from "@opentui/core";
+import type { Command, CommandContext, CommandRegistry, CommandSequenceState, CommandSurfaceRole, ParsedStep, RegisteredCommandGroup } from "./types.js";
+import type { Mode } from "./mode.js";
+export declare const ROOT_SURFACE_ID = "__root";
+/**
+ * A surface as tracked by the store. The root app is `surfaces[0]`, always
+ * present, with role `"root"` — it never arbitrates as modal.
+ *
+ * Commands are NOT stored on the record: React mounts children (whose
+ * `useCommand` effects register commands) before the surface's own register
+ * effect pushes the record, and unmount cleanup pops the record before the
+ * children unregister. Per-surface command maps therefore live in
+ * `commandsBySurface`, keyed by surface id, independent of the stack.
+ */
+export interface SurfaceRecord {
+    id: string;
+    role: CommandSurfaceRole | "root";
+    /** Nesting depth (root = 0). */
+    depth: number;
+    /** Monotonic registration order (tie-break), assigned by the wrapper on push. */
+    order: number;
+    /** Reads this surface's current local mode (mode stays in ModeProvider React state). */
+    getMode: () => Mode;
+    /** Builds the command context handed to this surface's handlers. */
+    buildCtx: () => CommandContext;
+}
+export type ContextGetter = () => Partial<CommandContext>;
+export interface CommandStoreContext {
+    /** Surface stack ordered by registration; `surfaces[0]` is the root record. */
+    surfaces: readonly SurfaceRecord[];
+    /** Per-surface command maps, keyed by surface id (see SurfaceRecord docs). */
+    commandsBySurface: ReadonlyMap<string, ReadonlyMap<string, Command>>;
+    /** Command groups keyed by prefixKey. */
+    groups: ReadonlyMap<string, RegisteredCommandGroup>;
+    contextSources: ReadonlyMap<string, ContextGetter>;
+    /** Renderable pending-sequence display state (which-key input). */
+    sequence: CommandSequenceState | null;
+}
+/**
+ * The topmost modal surface: role === "modal", max depth, then max order.
+ * Passive surfaces and the root never win.
+ */
+export declare function selectActiveModalSurface(ctx: CommandStoreContext): SurfaceRecord | null;
+/**
+ * Commands registered on a surface. Returns a fresh array; memoize against
+ * `selectSurfaceCommandMap` identity in render paths.
+ */
+export declare function selectSurfaceCommands(ctx: CommandStoreContext, surfaceId: string): readonly Command[];
+/** Identity-stable per-surface command map (undefined when none registered). */
+export declare function selectSurfaceCommandMap(ctx: CommandStoreContext, surfaceId: string): ReadonlyMap<string, Command> | undefined;
+export declare function selectSequence(ctx: CommandStoreContext): CommandSequenceState | null;
+export declare function selectGroups(ctx: CommandStoreContext): ReadonlyMap<string, RegisteredCommandGroup>;
+export declare function stepsKey(steps: readonly ParsedStep[]): string;
+export declare function formatStepKey(step: ParsedStep): string;
+declare function createBaseStore(initialContext: CommandStoreContext): import("@xstate/store").Store<CommandStoreContext, {
+    commandRegistered: {
+        surfaceId: string;
+        command: Command;
+    };
+    commandUnregistered: {
+        surfaceId: string;
+        command: Command;
+    };
+    groupRegistered: {
+        group: RegisteredCommandGroup;
+    };
+    groupUnregistered: {
+        group: RegisteredCommandGroup;
+    };
+    contextSourceRegistered: {
+        id: string;
+        getter: ContextGetter;
+    };
+    contextSourceUnregistered: {
+        id: string;
+    };
+    surfacePushed: {
+        surface: SurfaceRecord;
+    };
+    surfacePopped: {
+        surface: SurfaceRecord;
+    };
+    modeChanged: {
+        surfaceId: string;
+    };
+    sequencePending: {
+        state: CommandSequenceState;
+    };
+    sequenceReset: unknown;
+}, never>;
+export type CommandStoreInstance = ReturnType<typeof createBaseStore>;
+export interface KeyDispatchResult {
+    handled: boolean;
+    /**
+     * Present on a full command match. The caller (the `useKeyboard` effect)
+     * calls `preventDefault()` and then `invoke()` synchronously, preserving
+     * today's dispatch order and `event.defaultPrevented` semantics.
+     */
+    invoke?: () => void;
+}
+export interface CommandStoreConfig {
+    leader?: string;
+    keymap?: Record<string, string>;
+    sequenceTimeoutMs?: number;
+}
+export interface CreateCommandStoreOptions extends CommandStoreConfig {
+    /** Root surface accessors, provided by the command provider/dispatcher. */
+    root: {
+        getMode: () => Mode;
+        buildCtx: () => CommandContext;
+    };
+}
+/**
+ * The single writer around the store. Owns the two pieces of IO-adjacent,
+ * non-render state: the key buffer (not render state — putting it in store
+ * context would notify subscribers on every keystroke) and the sequence
+ * timeout timer. The renderable `sequence` display state lives in the store.
+ */
+export interface CommandStore {
+    /** The underlying @xstate/store instance (subscribe/getSnapshot/trigger). */
+    store: CommandStoreInstance;
+    /** The always-present root surface record (`surfaces[0]`). */
+    rootRecord: SurfaceRecord;
+    /**
+     * Feed a key event: arbitrates the active surface, filters candidates by
+     * mode/when, runs the pure sequence matchers against the internal buffer,
+     * triggers sequencePending/sequenceReset as needed, schedules/clears the
+     * timeout, and returns what happened so the caller can preventDefault and
+     * invoke synchronously.
+     */
+    key: (event: KeyEvent) => KeyDispatchResult;
+    /** Clears buffer + timer and triggers sequenceReset. Idempotent. */
+    reset: () => void;
+    /** Clears buffer + timer permanently, without touching store state. Called on dispatcher unmount. */
+    dispose: () => void;
+    /** Push a surface record; assigns registration order. Returns the pop cleanup. */
+    pushSurface: (surface: SurfaceRecord) => () => void;
+    /** Notify a (root or surface-local) mode change: clears buffer + pending sequence. */
+    modeChanged: (surfaceId: string) => void;
+    /** Back-compat CommandRegistry facade for a surface record (stable per record). */
+    registryFor: (record: SurfaceRecord) => CommandRegistry;
+    /** Update live config (leader/keymap/timeout are read per dispatch, as before). */
+    setConfig: (config: CommandStoreConfig) => void;
+}
+export declare function createCommandStore(options: CreateCommandStoreOptions): CommandStore;
+export {};
+//# sourceMappingURL=command-store.d.ts.map

package/dist/command-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-store.d.ts","sourceRoot":"","sources":["../src/command-store.ts"],"names":[],"mappings":"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"}

package/dist/command-store.js

@@ -0,0 +1,367 @@
+import { createStore } from "@xstate/store";
+import { parseHotkey } from "./parse.js";
+import { matchStep } from "./match.js";
+import { DEFAULT_SEQUENCE_TIMEOUT_MS, findPendingMatch, matchesBuffer, pruneBuffer, } from "./sequence.js";
+export const ROOT_SURFACE_ID = "__root";
+const DEFAULT_MODES = ["cursor"];
+// --- Selectors ---------------------------------------------------------------
+/**
+ * The topmost modal surface: role === "modal", max depth, then max order.
+ * Passive surfaces and the root never win.
+ */
+export function selectActiveModalSurface(ctx) {
+    let best = null;
+    for (const record of ctx.surfaces) {
+        if (record.role !== "modal")
+            continue;
+        if (best === null ||
+            record.depth > best.depth ||
+            (record.depth === best.depth && record.order > best.order)) {
+            best = record;
+        }
+    }
+    return best;
+}
+/**
+ * Commands registered on a surface. Returns a fresh array; memoize against
+ * `selectSurfaceCommandMap` identity in render paths.
+ */
+export function selectSurfaceCommands(ctx, surfaceId) {
+    const commands = ctx.commandsBySurface.get(surfaceId);
+    return commands ? Array.from(commands.values()) : [];
+}
+/** Identity-stable per-surface command map (undefined when none registered). */
+export function selectSurfaceCommandMap(ctx, surfaceId) {
+    return ctx.commandsBySurface.get(surfaceId);
+}
+export function selectSequence(ctx) {
+    return ctx.sequence;
+}
+export function selectGroups(ctx) {
+    return ctx.groups;
+}
+// --- Step-key helpers (shared by key dispatch and group registration) --------
+export function stepsKey(steps) {
+    return steps.map(formatStepKey).join(" ");
+}
+export function formatStepKey(step) {
+    const modifiers = [];
+    if (step.ctrl)
+        modifiers.push("ctrl");
+    if (step.meta)
+        modifiers.push("meta");
+    if (step.option)
+        modifiers.push("option");
+    if (step.shift)
+        modifiers.push("shift");
+    if (step.super)
+        modifiers.push("super");
+    modifiers.push(step.key);
+    return modifiers.join("+");
+}
+// --- Store -------------------------------------------------------------------
+/**
+ * Sequence-clear rule for surface transitions: a pending chord (display state)
+ * is cleared exactly when the transition changes which surface record owns
+ * keyboard input. Pushing/popping a passive surface (e.g. which-key) keeps the
+ * sequence it is displaying; replacing the active modal surface with a same-id
+ * record clears it (F-09) because the record identity changes.
+ */
+function sequenceAfterStackChange(before, after, sequence) {
+    return before === after ? sequence : null;
+}
+function createBaseStore(initialContext) {
+    return createStore({
+        context: initialContext,
+        on: {
+            commandRegistered: (ctx, event) => {
+                const existing = ctx.commandsBySurface.get(event.surfaceId);
+                const commands = new Map(existing ?? []);
+                commands.set(event.command.id, event.command);
+                const commandsBySurface = new Map(ctx.commandsBySurface);
+                commandsBySurface.set(event.surfaceId, commands);
+                return { ...ctx, commandsBySurface };
+            },
+            commandUnregistered: (ctx, event) => {
+                // Identity-guarded (R-05): with duplicate ids the map holds the last
+                // writer, and the first registrant's unmount must not delete the
+                // second's live command.
+                const existing = ctx.commandsBySurface.get(event.surfaceId);
+                if (!existing || existing.get(event.command.id) !== event.command)
+                    return ctx;
+                const commands = new Map(existing);
+                commands.delete(event.command.id);
+                const commandsBySurface = new Map(ctx.commandsBySurface);
+                if (commands.size === 0) {
+                    commandsBySurface.delete(event.surfaceId);
+                }
+                else {
+                    commandsBySurface.set(event.surfaceId, commands);
+                }
+                return { ...ctx, commandsBySurface };
+            },
+            groupRegistered: (ctx, event) => {
+                const groups = new Map(ctx.groups);
+                groups.set(event.group.prefixKey, event.group);
+                return { ...ctx, groups };
+            },
+            groupUnregistered: (ctx, event) => {
+                // Identity-guarded, as for commands.
+                if (ctx.groups.get(event.group.prefixKey) !== event.group)
+                    return ctx;
+                const groups = new Map(ctx.groups);
+                groups.delete(event.group.prefixKey);
+                return { ...ctx, groups };
+            },
+            contextSourceRegistered: (ctx, event) => {
+                const contextSources = new Map(ctx.contextSources);
+                contextSources.set(event.id, event.getter);
+                return { ...ctx, contextSources };
+            },
+            contextSourceUnregistered: (ctx, event) => {
+                if (!ctx.contextSources.has(event.id))
+                    return ctx;
+                const contextSources = new Map(ctx.contextSources);
+                contextSources.delete(event.id);
+                return { ...ctx, contextSources };
+            },
+            surfacePushed: (ctx, event) => {
+                const before = selectActiveModalSurface(ctx);
+                const surfaces = [...ctx.surfaces, event.surface];
+                const after = selectActiveModalSurface({ ...ctx, surfaces });
+                return { ...ctx, surfaces, sequence: sequenceAfterStackChange(before, after, ctx.sequence) };
+            },
+            surfacePopped: (ctx, event) => {
+                // Identity-based removal: only the exact pushed record is removed.
+                const surfaces = ctx.surfaces.filter((record) => record !== event.surface);
+                if (surfaces.length === ctx.surfaces.length)
+                    return ctx;
+                const before = selectActiveModalSurface(ctx);
+                const after = selectActiveModalSurface({ ...ctx, surfaces });
+                return { ...ctx, surfaces, sequence: sequenceAfterStackChange(before, after, ctx.sequence) };
+            },
+            modeChanged: (ctx, _event) => {
+                // A mode change is a transition, not a post-render repair: any pending
+                // chord is invalidated (F-08 — including surface-local mode changes).
+                return ctx.sequence === null ? ctx : { ...ctx, sequence: null };
+            },
+            sequencePending: (ctx, event) => {
+                return { ...ctx, sequence: event.state };
+            },
+            sequenceReset: (ctx) => {
+                return ctx.sequence === null ? ctx : { ...ctx, sequence: null };
+            },
+        },
+    });
+}
+export function createCommandStore(options) {
+    const rootRecord = {
+        id: ROOT_SURFACE_ID,
+        role: "root",
+        depth: 0,
+        order: 0,
+        getMode: options.root.getMode,
+        buildCtx: options.root.buildCtx,
+    };
+    const store = createBaseStore({
+        surfaces: [rootRecord],
+        commandsBySurface: new Map(),
+        groups: new Map(),
+        contextSources: new Map(),
+        sequence: null,
+    });
+    let config = {
+        leader: options.leader,
+        keymap: options.keymap,
+        sequenceTimeoutMs: options.sequenceTimeoutMs,
+    };
+    // IO-adjacent wrapper state: key buffer, timer, parse cache, order counter.
+    let buffer = [];
+    let timer = null;
+    const parseCache = new Map();
+    const registries = new Map();
+    let orderCounter = 1;
+    function clearTimer() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function armTimer() {
+        clearTimer();
+        timer = setTimeout(reset, config.sequenceTimeoutMs ?? DEFAULT_SEQUENCE_TIMEOUT_MS);
+    }
+    function clearBufferAndTimer() {
+        buffer = [];
+        clearTimer();
+    }
+    function reset() {
+        clearBufferAndTimer();
+        store.trigger.sequenceReset();
+    }
+    function dispose() {
+        clearBufferAndTimer();
+    }
+    function getParsedHotkey(hotkey) {
+        const cacheKey = `${hotkey}:${config.leader ?? ""}`;
+        let parsed = parseCache.get(cacheKey);
+        if (!parsed) {
+            parsed = parseHotkey(hotkey, config.leader);
+            parseCache.set(cacheKey, parsed);
+        }
+        return parsed;
+    }
+    function key(event) {
+        const ctx = store.getSnapshot().context;
+        // Arbitration: a topmost modal surface owns input; otherwise the root app.
+        const surface = selectActiveModalSurface(ctx) ?? rootRecord;
+        const currentMode = surface.getMode();
+        const cmdCtx = surface.buildCtx();
+        const commands = ctx.commandsBySurface.get(surface.id);
+        // Collect eligible commands with their parsed hotkeys
+        const singleStepCandidates = [];
+        const multiStepCandidates = [];
+        if (commands) {
+            for (const command of commands.values()) {
+                const commandModes = command.modes ?? DEFAULT_MODES;
+                if (!commandModes.includes(currentMode))
+                    continue;
+                if (command.when && !command.when(cmdCtx))
+                    continue;
+                const hotkey = config.keymap?.[command.id] ?? command.defaultHotkey;
+                if (!hotkey)
+                    continue;
+                const parsed = getParsedHotkey(hotkey);
+                // Unmatchable hotkeys (e.g. <leader> with no configured leader) register
+                // nothing rather than matching everything.
+                if (parsed.steps.length === 0)
+                    continue;
+                if (parsed.steps.length === 1) {
+                    singleStepCandidates.push({ command, parsed });
+                }
+                else {
+                    multiStepCandidates.push({ command, hotkey, parsed });
+                }
+            }
+        }
+        // Check multi-step sequences first (they consume buffer state)
+        if (multiStepCandidates.length > 0) {
+            const hotkeys = multiStepCandidates.map((candidate) => candidate.parsed);
+            buffer = [...buffer, event];
+            armTimer();
+            let matchedIndex = -1;
+            for (let i = 0; i < hotkeys.length; i++) {
+                if (matchesBuffer(buffer, hotkeys[i])) {
+                    matchedIndex = i;
+                    break;
+                }
+            }
+            if (matchedIndex >= 0) {
+                clearBufferAndTimer();
+                store.trigger.sequenceReset();
+                const matched = multiStepCandidates[matchedIndex].command;
+                return { handled: true, invoke: () => matched.handler(cmdCtx) };
+            }
+            buffer = pruneBuffer(buffer, hotkeys);
+            const pending = findPendingMatch(buffer, hotkeys);
+            if (pending) {
+                const firstCandidate = multiStepCandidates[pending.indexes[0]];
+                const state = {
+                    prefix: firstCandidate.parsed.steps.slice(0, pending.prefixLength),
+                    candidates: pending.indexes
+                        .map((idx) => multiStepCandidates[idx])
+                        .filter(({ command }) => !command.hidden)
+                        .map(({ command, hotkey, parsed }) => ({
+                        command,
+                        hotkey,
+                        steps: parsed.steps,
+                        remainingSteps: parsed.steps.slice(pending.prefixLength),
+                        nextStep: parsed.steps[pending.prefixLength],
+                        group: ctx.groups.get(stepsKey(parsed.steps.slice(0, pending.prefixLength + 1))),
+                    })),
+                };
+                store.trigger.sequencePending({ state });
+                return { handled: true };
+            }
+            store.trigger.sequenceReset();
+        }
+        // Check single-step matches
+        for (const { command, parsed } of singleStepCandidates) {
+            if (matchStep(event, parsed.steps[0])) {
+                store.trigger.sequenceReset();
+                return { handled: true, invoke: () => command.handler(cmdCtx) };
+            }
+        }
+        // A modal surface swallows unhandled keys: dispatch never falls through to
+        // the root app while a modal surface is topmost. (The caller does not
+        // preventDefault unmatched keys — same as today.)
+        return { handled: false };
+    }
+    function pushSurface(surface) {
+        surface.order = orderCounter++;
+        const before = selectActiveModalSurface(store.getSnapshot().context);
+        store.trigger.surfacePushed({ surface });
+        const after = selectActiveModalSurface(store.getSnapshot().context);
+        // Keep the wrapper buffer consistent with the transition's sequence-clear
+        // rule: clear exactly when keyboard ownership changed.
+        if (before !== after)
+            clearBufferAndTimer();
+        return () => {
+            const beforePop = selectActiveModalSurface(store.getSnapshot().context);
+            store.trigger.surfacePopped({ surface });
+            const afterPop = selectActiveModalSurface(store.getSnapshot().context);
+            if (beforePop !== afterPop)
+                clearBufferAndTimer();
+        };
+    }
+    function modeChanged(surfaceId) {
+        clearBufferAndTimer();
+        store.trigger.modeChanged({ surfaceId });
+    }
+    function registryFor(record) {
+        let registry = registries.get(record);
+        if (!registry) {
+            registry = {
+                get commands() {
+                    const current = store.getSnapshot().context.commandsBySurface.get(record.id);
+                    // The registry contract exposes a Map; the store's per-surface maps
+                    // are Maps at runtime (readonly-typed). Consumers must not mutate.
+                    return (current ?? new Map());
+                },
+                register(command) {
+                    store.trigger.commandRegistered({ surfaceId: record.id, command });
+                    return () => {
+                        store.trigger.commandUnregistered({ surfaceId: record.id, command });
+                    };
+                },
+                invoke(id) {
+                    const ctx = store.getSnapshot().context;
+                    const cmd = ctx.commandsBySurface.get(record.id)?.get(id);
+                    if (!cmd)
+                        return;
+                    const cmdCtx = record.buildCtx();
+                    if (!cmd.when || cmd.when(cmdCtx)) {
+                        cmd.handler(cmdCtx);
+                    }
+                },
+            };
+            registries.set(record, registry);
+        }
+        return registry;
+    }
+    function setConfig(next) {
+        config = next;
+    }
+    return {
+        store,
+        rootRecord,
+        key,
+        reset,
+        dispose,
+        pushSurface,
+        modeChanged,
+        registryFor,
+        setConfig,
+    };
+}
+//# sourceMappingURL=command-store.js.map

package/dist/command-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-store.js","sourceRoot":"","sources":["../src/command-store.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -1,14 +1,21 @@
 import { type ReactNode } from "react";
-import type { Command, CommandContext, CommandGroup, CommandRegistry, CommandSequenceState, RegisteredCommandGroup } from "./types.js";
+import type { ActiveCommandSurface, Command, CommandContext, CommandGroup, CommandRegistry, CommandSequenceState, CommandSurfaceRole, RegisteredCommandGroup } from "./types.js";
 import type { Mode } from "./mode.js";
-type ContextGetter = () => Partial<CommandContext>;
+import { type CommandStore, type ContextGetter, type SurfaceRecord } from "./command-store.js";
 interface CommandContextValue {
     registry: CommandRegistry;
     leaderKey?: string;
     contextSources: Map<string, ContextGetter>;
     groups: Map<string, RegisteredCommandGroup>;
 }
-declare const CommandContext: import("react").Context<CommandContextValue | null>;
+/** Internal provider value: the store plus the surface this subtree registers to. */
+interface CommandStoreContextValue {
+    commandStore: CommandStore;
+    /** The surface record `useCommand` registrations under this subtree target. */
+    surface: SurfaceRecord;
+    leaderKey?: string;
+}
+declare const CommandContext: import("react").Context<CommandStoreContextValue | null>;
 export interface CommandProviderProps {
     children: ReactNode;
     leader?: string;
@@ -17,12 +24,54 @@ export interface CommandProviderProps {
     sequenceTimeoutMs?: number;
 }
 export declare function CommandProvider({ children, leader, keymap, initialMode, sequenceTimeoutMs, }: CommandProviderProps): ReactNode;
+export interface CommandSurfaceProviderProps {
+    children: ReactNode;
+    /** Stable id for the surface (typically the overlay id). */
+    id: string;
+    /** Interaction role (default "modal"). */
+    role?: CommandSurfaceRole;
+    /** Initial local mode for this surface (default "cursor"). */
+    initialMode?: Mode;
+}
+/**
+ * Mounts an overlay-owned command surface. Children registered via `useCommand`
+ * target this surface's local registry, and `useMode`/`useSetMode` read/write
+ * this surface's local mode instead of the root app's mode.
+ *
+ * While a `modal` surface is topmost it owns keyboard input and suspends the
+ * parent app's commands; a `passive` surface never becomes the keyboard owner.
+ */
+export declare function CommandSurfaceProvider({ children, id, role, initialMode, }: CommandSurfaceProviderProps): ReactNode;
 export declare function useCommandContext(): {
     commands: Command[];
     invoke: (id: string) => void;
 };
+/**
+ * Internal: the stable registry facade for the nearest surface, without
+ * subscribing to store changes. Registration hooks (useCommand/useActions)
+ * only need the facade; subscribing them would re-render every command host
+ * on unrelated group/context-source registrations.
+ */
+export declare function useSurfaceRegistry(): CommandRegistry;
 export declare function useCommandRegistry(): CommandContextValue;
 export declare function useCommandSequenceState(): CommandSequenceState | null;
+/**
+ * Metadata for the topmost modal command surface, or null when the root app is
+ * the active surface. Intended for which-key/help to read shortcuts from the
+ * active interaction surface. `commands` is reactive (F-13).
+ */
+export declare function useActiveCommandSurface(): ActiveCommandSurface | null;
+/**
+ * Commands registered on a surface (reactive). Defaults to the active modal
+ * surface, falling back to the root surface when none is active.
+ */
+export declare function useSurfaceCommands(surfaceId?: string): readonly Command[];
+/**
+ * Advanced/internal — subject to change. The command store instance backing
+ * this provider tree, for bridges that must reach the dispatch machinery
+ * (e.g. the shell's overlay-replacement sequence reset).
+ */
+export declare function useCommandStore(): CommandStore;
 export declare function useCommandGroup(group: CommandGroup): void;
 export declare function useProvideCommandContext(getter: () => Partial<CommandContext>): void;
 export {};