@opentui/keymap 0.0.0-20260423-618ea9b1 → 0.1.106

package/package.json

@@ -4,7 +4,7 @@
   "main": "index.js",
   "types": "src/index.d.ts",
   "type": "module",
-  "version": "0.0.0-20260423-618ea9b1",
+  "version": "0.1.106",
   "description": "Standalone keymap package for OpenTUI",
   "license": "MIT",
   "repository": {
@@ -50,7 +50,7 @@
     }
   },
   "dependencies": {
-    "@opentui/core": "0.0.0-20260423-618ea9b1"
+    "@opentui/core": "0.1.106"
   },
   "devDependencies": {
     "@opentui/react": "workspace:*",
@@ -63,8 +63,8 @@
     "typescript": "^5"
   },
   "peerDependencies": {
-    "@opentui/react": "0.0.0-20260423-618ea9b1",
-    "@opentui/solid": "0.0.0-20260423-618ea9b1",
+    "@opentui/react": "0.1.106",
+    "@opentui/solid": "0.1.106",
     "react": ">=19.0.0",
     "solid-js": "1.9.12"
   },

package/react/index.js

@@ -57,46 +57,45 @@ function useBindings(createLayer, deps = []) {
   const layerRef = useRef(layer);
   const disposeRef = useRef(undefined);
   const registeredLayerRef = useRef(undefined);
-  const registeredScopeRef = useRef(undefined);
+  const registeredTargetModeRef = useRef(undefined);
   const registeredTargetRef = useRef(undefined);
   layerRef.current = layer;
   const unregister = useCallback(() => {
     disposeRef.current?.();
     disposeRef.current = undefined;
     registeredLayerRef.current = undefined;
-    registeredScopeRef.current = undefined;
+    registeredTargetModeRef.current = undefined;
     registeredTargetRef.current = undefined;
   }, []);
   useEffect(() => {
     const currentLayer = layerRef.current;
     const hasExplicitTarget = currentLayer.targetRef !== undefined;
     const explicitTarget = resolveBindingsTarget(currentLayer.targetRef);
-    const resolvedScope = currentLayer.scope ?? (hasExplicitTarget ? "focus-within" : "global");
-    const nextTarget = resolvedScope === "global" ? undefined : explicitTarget;
-    if (!hasExplicitTarget && resolvedScope !== "global") {
+    const nextTargetMode = currentLayer.targetMode ?? (hasExplicitTarget ? "focus-within" : undefined);
+    const nextTarget = nextTargetMode ? explicitTarget : undefined;
+    if (!hasExplicitTarget && nextTargetMode) {
       throw new Error("useBindings local bindings need a targetRef");
     }
-    if (registeredLayerRef.current === currentLayer && registeredScopeRef.current === resolvedScope && registeredTargetRef.current === nextTarget) {
+    if (registeredLayerRef.current === currentLayer && registeredTargetModeRef.current === nextTargetMode && registeredTargetRef.current === nextTarget) {
       return;
     }
     unregister();
-    if (!nextTarget && resolvedScope !== "global") {
+    if (!nextTarget && nextTargetMode) {
       registeredLayerRef.current = currentLayer;
-      registeredScopeRef.current = resolvedScope;
+      registeredTargetModeRef.current = nextTargetMode;
       registeredTargetRef.current = undefined;
       return;
     }
-    const { scope: _scope, targetRef: _targetRef, ...baseLayer } = currentLayer;
-    disposeRef.current = keymap.registerLayer(resolvedScope === "global" ? {
-      ...baseLayer,
-      scope: "global"
+    const { targetRef: _targetRef, targetMode: _targetMode, ...baseLayer } = currentLayer;
+    disposeRef.current = keymap.registerLayer(!nextTargetMode ? {
+      ...baseLayer
     } : {
       ...baseLayer,
-      scope: resolvedScope,
-      target: nextTarget
+      target: nextTarget,
+      targetMode: nextTargetMode
     });
     registeredLayerRef.current = currentLayer;
-    registeredScopeRef.current = resolvedScope;
+    registeredTargetModeRef.current = nextTargetMode;
     registeredTargetRef.current = nextTarget;
   });
   useEffect(() => {

package/solid/index.js

@@ -68,12 +68,11 @@ function useBindings(createLayer) {
     const layer = createLayer();
     const hasExplicitTarget = layer.target !== undefined;
     const explicitTarget = resolveBindingsTarget(layer.target);
-    const resolvedScope = layer.scope ?? (hasExplicitTarget ? "focus-within" : "global");
-    const { scope: _scope, target: _target, ...baseLayer } = layer;
-    if (resolvedScope === "global") {
+    const nextTargetMode = layer.targetMode ?? (hasExplicitTarget ? "focus-within" : undefined);
+    const { target: _target, targetMode: _targetMode, ...baseLayer } = layer;
+    if (!nextTargetMode) {
       const dispose2 = keymap.registerLayer({
-        ...baseLayer,
-        scope: "global"
+        ...baseLayer
       });
       onCleanup(() => {
         dispose2();
@@ -88,8 +87,8 @@ function useBindings(createLayer) {
     }
     const dispose = keymap.registerLayer({
       ...baseLayer,
-      scope: resolvedScope,
-      target: explicitTarget
+      target: explicitTarget,
+      targetMode: nextTargetMode
     });
     onCleanup(() => {
       dispose();

package/src/addons/opentui/edit-buffer-bindings.d.ts

@@ -6,8 +6,10 @@ export interface EditBufferCommandOptions {
     commandNames?: Partial<Record<EditBufferCommandName, string>>;
     descriptions?: Partial<Record<EditBufferCommandName, string>>;
 }
-export type ManagedTextareaLayer = Omit<Layer<Renderable, KeyEvent>, "bindings"> & {
+export type ManagedTextareaLayer = Omit<Layer<Renderable, KeyEvent>, "bindings" | "target" | "targetMode"> & {
     bindings?: Bindings<Renderable, KeyEvent>;
+    target?: never;
+    targetMode?: never;
 };
 /**
  * Returns the default textarea bindings with any overrides prepended so they
@@ -30,7 +32,7 @@ export declare function registerTextareaMappingSuspension(keymap: Keymap<Rendera
  */
 export declare function registerEditBufferCommands(keymap: Keymap<Renderable, KeyEvent>, renderer: CliRenderer, options?: EditBufferCommandOptions): () => void;
 /**
- * High-level textarea integration: registers the edit-buffer commands,
+ * High-level global textarea integration: registers the edit-buffer commands,
  * suspends the textarea's built-in key handling while focused, and installs
  * the layer with default bindings plus overrides. Safe to combine with the
  * lower-level helpers because they are reference-counted.

package/src/addons/universal/enabled.d.ts

@@ -5,12 +5,7 @@ import type { Keymap, KeymapEvent, ReactiveMatcher } from "../../index.js";
  */
 export type Enabled = boolean | (() => boolean) | ReactiveMatcher;
 /**
- * Adds an `enabled` layer field for boolean, callback, or reactive matcher
- * gating.
+ * Adds `enabled` layer and command fields for boolean, callback, or reactive
+ * matcher gating.
  */
-export declare function registerEnabledField<TTarget extends object, TEvent extends KeymapEvent>(keymap: Keymap<TTarget, TEvent>): () => void;
-/**
- * Adds an `enabled` command field for boolean, callback, or reactive matcher
- * gating.
- */
-export declare function registerEnabledCommandField<TTarget extends object, TEvent extends KeymapEvent>(keymap: Keymap<TTarget, TEvent>): () => void;
+export declare function registerEnabledFields<TTarget extends object, TEvent extends KeymapEvent>(keymap: Keymap<TTarget, TEvent>): () => void;

package/src/addons/universal/index.d.ts

@@ -4,12 +4,12 @@ export { registerBackspacePopsPendingSequence } from "./backspace-pops-pending-s
 export { registerCommaBindings } from "./comma-bindings.js";
 export { registerDeadBindingWarnings } from "./dead-bindings.js";
 export { registerEscapeClearsPendingSequence } from "./escape-clears-pending-sequence.js";
-export { registerEnabledField } from "./enabled.js";
-export { registerEnabledCommandField } from "./enabled.js";
+export { registerEnabledFields } from "./enabled.js";
 export { registerEmacsBindings } from "./emacs-bindings.js";
 export { registerExCommands } from "./ex-commands.js";
 export { registerLeader } from "./leader.js";
 export { registerMetadataFields } from "./metadata.js";
+export { registerNeovimDisambiguation } from "./neovim-disambiguation.js";
 export { registerTimedLeader } from "./timed-leader.js";
 export { registerUnresolvedCommandWarnings } from "./unresolved-commands.js";
 export type { Aliases } from "./aliases.js";
@@ -18,4 +18,5 @@ export type { EscapeClearsPendingSequenceOptions } from "./escape-clears-pending
 export type { Enabled } from "./enabled.js";
 export type { ExCommand } from "./ex-commands.js";
 export type { LeaderOptions } from "./leader.js";
+export type { NeovimDisambiguationOptions } from "./neovim-disambiguation.js";
 export type { TimedLeaderOptions } from "./timed-leader.js";

package/src/addons/universal/metadata.d.ts

@@ -2,5 +2,8 @@ import type { Keymap, KeymapEvent } from "../../index.js";
 /**
  * Maps `desc`, `group`, `title`, and `category` fields into binding and
  * command attrs.
+ *
+ * Layer fields intentionally do not compile into attrs in the current model,
+ * so this addon only registers binding and command field compilers.
  */
 export declare function registerMetadataFields<TTarget extends object, TEvent extends KeymapEvent>(keymap: Keymap<TTarget, TEvent>): () => void;

package/src/addons/universal/neovim-disambiguation.d.ts

@@ -0,0 +1,10 @@
+import type { Keymap, KeymapEvent } from "../../index.js";
+export interface NeovimDisambiguationOptions {
+    timeoutMs?: number;
+}
+/**
+ * Defers ambiguous exact-vs-prefix bindings and runs the exact binding if no
+ * continuation arrives before the timeout, matching Neovim-style timeout-based
+ * disambiguation.
+ */
+export declare function registerNeovimDisambiguation<TTarget extends object, TEvent extends KeymapEvent>(keymap: Keymap<TTarget, TEvent>, options?: NeovimDisambiguationOptions): () => void;

package/src/index.d.ts

@@ -1,3 +1,3 @@
 export { Keymap } from "./keymap.js";
 export { stringifyKeySequence, stringifyKeyStroke } from "./services/keys.js";
-export type { KeyLike, KeyMatch, ActiveBinding, KeyStringifyInput, StringifyOptions, Attributes, BindingCommand, BindingParser, BindingParserContext, BindingParserResult, BindingExpander, BindingExpanderContext, BindingEvent, BindingFieldCompiler, BindingFieldContext, BindingInput, BindingTransformer, BindingTransformerContext, ParsedBindingInput, BindingShorthand, Bindings, ActiveKey, ActiveKeyOptions, KeymapActiveKey, KeymapBindingInput, KeymapCommandEntry, KeymapCommandDefinition, KeymapCommandRecord, Listener, ErrorEvent, CommandDefinition, CommandEntry, CommandFilter, CommandQuery, CommandQueryValue, CommandRecord, RunCommandOptions, RunCommandResult, CommandHandler, CommandFieldCompiler, CommandFieldContext, CommandContext, CommandResolver, CommandResolverContext, CommandResult, EventData, KeyInputContext, KeymapEvent, KeymapHost, FocusLayer, FocusWithinLayer, GlobalLayer, LayerAnalysisContext, LayerBindingAnalysis, LayerAnalyzer, LayerFieldCompiler, LayerFieldContext, LayerFields, Layer, EventName, Events, InterceptName, Intercepts, KeyInterceptOptions, ParsedCommand, RawInterceptOptions, RawInputContext, ReactiveMatcher, WarningEvent, ResolvedBindingCommand, Scope, EventMatchResolverContext, EventMatchResolver, TargetLayer, KeyToken, ResolvedKeyToken, KeySequencePart, NormalizedKeyStroke, KeyStrokeInput, } from "./types.js";
+export type { KeyLike, KeyMatch, ActiveBinding, KeyStringifyInput, StringifyOptions, Attributes, BindingCommand, BindingParser, BindingParserContext, BindingParserResult, BindingExpander, BindingExpanderContext, BindingEvent, BindingFieldCompiler, BindingFieldContext, BindingInput, BindingTransformer, BindingTransformerContext, ParsedBindingInput, BindingShorthand, Bindings, ActiveKey, ActiveKeyOptions, Listener, ErrorEvent, CommandDefinition, CommandEntry, CommandFilter, CommandQuery, CommandQueryValue, CommandRecord, RunCommandOptions, RunCommandResult, CommandHandler, CommandFieldCompiler, CommandFieldContext, CommandContext, CommandResolver, CommandResolverContext, CommandResult, EventData, KeyInputContext, KeymapEvent, KeymapHost, FocusLayer, FocusWithinLayer, GlobalLayer, LayerAnalysisContext, LayerBindingAnalysis, LayerAnalyzer, LayerFieldCompiler, LayerFieldContext, LayerFields, Layer, EventName, Events, InterceptName, Intercepts, KeyInterceptOptions, ParsedCommand, RawInterceptOptions, RawInputContext, ReactiveMatcher, WarningEvent, ResolvedBindingCommand, TargetMode, EventMatchResolverContext, EventMatchResolver, KeyDisambiguationContext, KeyDisambiguationDecision, KeyDeferredDisambiguationContext, KeyDeferredDisambiguationDecision, KeyDeferredDisambiguationHandler, KeyDisambiguationResolver, TargetLayer, KeyToken, ResolvedKeyToken, KeySequencePart, NormalizedKeyStroke, KeyStrokeInput, } from "./types.js";

package/src/keymap.d.ts

@@ -1,4 +1,4 @@
-import type { ActiveKey, ActiveKeyOptions, BindingInput, BindingExpander, BindingParser, BindingFieldCompiler, Bindings, BindingTransformer, Events, CommandFieldCompiler, CommandEntry, CommandQuery, CommandRecord, KeymapEvent, KeymapHost, LayerAnalyzer, Listener, RunCommandOptions, RunCommandResult, CommandResolver, KeyInterceptOptions, KeyInputContext, Layer, LayerFieldCompiler, RawInterceptOptions, RawInputContext, EventMatchResolver, KeyStringifyInput, KeyToken, KeyLike, KeySequencePart } from "./types.js";
+import type { ActiveKey, ActiveKeyOptions, BindingInput, BindingExpander, BindingParser, BindingFieldCompiler, Bindings, BindingTransformer, Events, CommandFieldCompiler, CommandEntry, CommandQuery, CommandRecord, KeymapEvent, KeymapHost, LayerAnalyzer, Listener, RunCommandOptions, RunCommandResult, CommandResolver, KeyInterceptOptions, KeyInputContext, Layer, LayerFieldCompiler, KeyDisambiguationResolver, RawInterceptOptions, RawInputContext, EventMatchResolver, KeyStringifyInput, KeyToken, KeyLike, KeySequencePart } from "./types.js";
 export declare class Keymap<TTarget extends object, TEvent extends KeymapEvent = KeymapEvent> {
     private readonly host;
     private readonly state;
@@ -37,6 +37,7 @@ export declare class Keymap<TTarget extends object, TEvent extends KeymapEvent =
     normalizeBindings(bindings: Bindings<TTarget, TEvent>): BindingInput<TTarget, TEvent>[];
     acquireResource(key: symbol, setup: () => () => void): () => void;
     runCommand(cmd: string, options?: RunCommandOptions<TTarget, TEvent>): RunCommandResult;
+    dispatchCommand(cmd: string, options?: RunCommandOptions<TTarget, TEvent>): RunCommandResult;
     on(name: "state", fn: Listener<Events<TTarget, TEvent>["state"]>): () => void;
     on(name: "pendingSequence", fn: Listener<Events<TTarget, TEvent>["pendingSequence"]>): () => void;
     on(name: "warning", fn: Listener<Events<TTarget, TEvent>["warning"]>): () => void;
@@ -66,6 +67,9 @@ export declare class Keymap<TTarget extends object, TEvent extends KeymapEvent =
     prependEventMatchResolver(resolver: EventMatchResolver<TEvent>): () => void;
     appendEventMatchResolver(resolver: EventMatchResolver<TEvent>): () => void;
     clearEventMatchResolvers(): void;
+    prependDisambiguationResolver(resolver: KeyDisambiguationResolver<TTarget, TEvent>): () => void;
+    appendDisambiguationResolver(resolver: KeyDisambiguationResolver<TTarget, TEvent>): () => void;
+    clearDisambiguationResolvers(): void;
     private handleFocusedTargetChange;
     private warnUnknownField;
     private warnUnknownToken;

package/src/react/index.d.ts

@@ -12,19 +12,17 @@ export interface UseBindingsTargetRef<TRenderable extends Renderable = Renderabl
 }
 type UseBindingsLayerBase = LayerFields<Renderable, KeyEvent>;
 export interface UseGlobalBindingsLayer extends UseBindingsLayerBase {
-    scope?: "global";
     targetRef?: undefined;
 }
 export interface UseFocusBindingsLayer<TRenderable extends Renderable = Renderable> extends UseBindingsLayerBase {
-    scope: "focus";
+    targetMode: "focus";
     targetRef: UseBindingsTargetRef<TRenderable>;
 }
 export interface UseFocusWithinBindingsLayer<TRenderable extends Renderable = Renderable> extends UseBindingsLayerBase {
-    scope: "focus-within";
+    targetMode?: "focus-within";
     targetRef: UseBindingsTargetRef<TRenderable>;
 }
 export interface UseInferredFocusWithinBindingsLayer<TRenderable extends Renderable = Renderable> extends UseBindingsLayerBase {
-    scope?: undefined;
     targetRef: UseBindingsTargetRef<TRenderable>;
 }
 export type UseTargetBindingsLayer<TRenderable extends Renderable = Renderable> = UseFocusBindingsLayer<TRenderable> | UseFocusWithinBindingsLayer<TRenderable> | UseInferredFocusWithinBindingsLayer<TRenderable>;

package/src/services/activation.d.ts

@@ -1,9 +1,12 @@
 import type { Emitter } from "../lib/emitter.js";
-import type { ActiveKey, ActiveKeyOptions, Hooks, KeymapEvent, KeymapHost, KeySequencePart, PendingSequenceState, RegisteredLayer, SequenceNode } from "../types.js";
+import type { ActiveBinding, ActiveKey, ActiveKeyOptions, CompiledBinding, Hooks, KeymapEvent, KeymapHost, PendingSequenceCapture, KeySequencePart, PendingSequenceState, RegisteredLayer, SequenceNode } from "../types.js";
 import type { CommandCatalogService } from "./command-catalog.js";
 import type { ConditionService } from "./conditions.js";
 import type { NotificationService } from "./notify.js";
-import type { State } from "./state.js";
+import type { ActiveCommandView, State } from "./state.js";
+interface ActivationOptions<TTarget extends object, TEvent extends KeymapEvent> {
+    onPendingSequenceChanged?: (previous: PendingSequenceState<TTarget, TEvent> | null, next: PendingSequenceState<TTarget, TEvent> | null) => void;
+}
 export declare class ActivationService<TTarget extends object, TEvent extends KeymapEvent> {
     private readonly state;
     private readonly host;
@@ -11,26 +14,32 @@ export declare class ActivationService<TTarget extends object, TEvent extends Ke
     private readonly notify;
     private readonly conditions;
     private readonly catalog;
-    constructor(state: State<TTarget, TEvent>, host: KeymapHost<TTarget, TEvent>, hooks: Emitter<Hooks<TTarget, TEvent>>, notify: NotificationService<TTarget, TEvent>, conditions: ConditionService<TTarget, TEvent>, catalog: CommandCatalogService<TTarget, TEvent>);
+    private readonly options;
+    constructor(state: State<TTarget, TEvent>, host: KeymapHost<TTarget, TEvent>, hooks: Emitter<Hooks<TTarget, TEvent>>, notify: NotificationService<TTarget, TEvent>, conditions: ConditionService<TTarget, TEvent>, catalog: CommandCatalogService<TTarget, TEvent>, options?: ActivationOptions<TTarget, TEvent>);
     getFocusedTarget(): TTarget | null;
     getFocusedTargetIfAvailable(): TTarget | null;
     setPendingSequence(next: PendingSequenceState<TTarget, TEvent> | null): void;
     ensureValidPendingSequence(): PendingSequenceState<TTarget, TEvent> | undefined;
+    revalidatePendingSequenceIfNeeded(): void;
+    hasPendingSequenceState(): boolean;
     getPendingSequence(): readonly KeySequencePart[];
     popPendingSequence(): boolean;
     getActiveKeys(options?: ActiveKeyOptions): readonly ActiveKey<TTarget, TEvent>[];
+    getActiveKeysForCaptures(captures: readonly PendingSequenceCapture<TTarget, TEvent>[], options?: ActiveKeyOptions): readonly ActiveKey<TTarget, TEvent>[];
     nodeHasReachableBindings(node: SequenceNode<TTarget, TEvent>, focused: TTarget | null): boolean;
     getActiveLayers(focused: TTarget | null): RegisteredLayer<TTarget, TEvent>[];
+    refreshActiveLayers(focused?: TTarget | null): void;
+    invalidateActiveLayers(): void;
     isLayerActiveForFocused(layer: RegisteredLayer<TTarget, TEvent>, focused: TTarget | null): boolean;
     layerCanCacheActiveKeys(layer: RegisteredLayer<TTarget, TEvent>): boolean;
     activeLayersCanCacheActiveKeys(activeLayers: readonly RegisteredLayer<TTarget, TEvent>[]): boolean;
     private collectNodesFromNode;
-    private collectSequencePartsFromPending;
-    private getMatchingBindings;
+    collectSequencePartsFromPending(pending: PendingSequenceState<TTarget, TEvent>): KeySequencePart[];
+    collectMatchingBindings(bindings: readonly CompiledBinding<TTarget, TEvent>[], focused: TTarget | null, activeView: ActiveCommandView<TTarget, TEvent>): CompiledBinding<TTarget, TEvent>[];
     private hasMatchingBindings;
     private getNodePresentation;
     private toActiveBinding;
-    private collectActiveBindings;
+    collectActiveBindings(bindings: readonly CompiledBinding<TTarget, TEvent>[], focused: TTarget | null, activeView: ActiveCommandView<TTarget, TEvent>): ActiveBinding<TTarget, TEvent>[];
     private collectActiveKeysAtRoot;
     private collectActiveKeysFromPending;
     private selectActiveKey;
@@ -43,3 +52,4 @@ export declare class ActivationService<TTarget extends object, TEvent extends Ke
     private invalidateCaches;
     private notifyPendingSequenceChange;
 }
+export {};

package/src/services/command-catalog.d.ts

@@ -1,7 +1,7 @@
 import type { Attributes, BindingCommand, CommandEntry, CommandDefinition, CommandResolutionStatus, CommandQuery, CommandRecord, CommandResolver, CompiledBinding, KeymapEvent, KeymapHost, RegisteredCommand, ResolvedBindingCommand } from "../types.js";
 import type { ConditionService } from "./conditions.js";
 import type { NotificationService } from "./notify.js";
-import type { ActiveCommandView, ResolvedCommandEntry, State } from "./state.js";
+import type { ActiveCommandView, RegisteredCommandView, ResolvedCommandEntry, State } from "./state.js";
 interface CommandCatalogOptions {
     onCommandResolversChanged(): void;
 }
@@ -24,14 +24,26 @@ export declare class CommandCatalogService<TTarget extends object, TEvent extend
         entries?: readonly ResolvedCommandEntry<TTarget, TEvent>[];
         hadError: boolean;
     };
+    getRegisteredResolvedEntries(command: string, includeRecord: boolean): readonly ResolvedCommandEntry<TTarget, TEvent>[] | undefined;
+    getRegisteredResolverFallback(command: string, includeRecord: boolean): {
+        resolved?: ResolvedBindingCommand<TTarget, TEvent>;
+        hadError: boolean;
+    };
     getCommandAttrs(command: string, focused: TTarget | null): Readonly<Attributes> | undefined;
     getTopCommandRecord(command: string, focused: TTarget | null): CommandRecord | undefined;
+    getTopRegisteredCommandRecord(command: string): CommandRecord | undefined;
+    getDispatchUnavailableCommandState(command: string, focused: TTarget | null, includeRecord: boolean): {
+        reason: "inactive" | "disabled";
+        command?: CommandRecord;
+    } | undefined;
     getActiveCommandView(focused: TTarget | null): ActiveCommandView<TTarget, TEvent>;
+    getRegisteredCommandView(): RegisteredCommandView<TTarget, TEvent>;
     isBindingVisible(binding: CompiledBinding<TTarget, TEvent>, focused: TTarget | null, activeView: ActiveCommandView<TTarget, TEvent>): boolean;
     getBindingCommandAttrs(binding: CompiledBinding<TTarget, TEvent>, focused: TTarget | null, activeView: ActiveCommandView<TTarget, TEvent>): Readonly<Attributes> | undefined;
     getCommandResolutionStatus(command: string, layerCommands?: ReadonlyMap<string, RegisteredCommand<TTarget, TEvent>>): CommandResolutionStatus;
     private mutateCommandResolvers;
     private getTopResolvedCommand;
+    private getTopRegisteredCommand;
     private getFallbackResolvedCommand;
     private getResolvedCommandChainFromView;
     private getRegisteredLayerCommandEntries;

package/src/services/command-executor.d.ts

@@ -16,6 +16,7 @@ export declare class CommandExecutorService<TTarget extends object, TEvent exten
     private readonly options;
     constructor(notify: NotificationService<TTarget, TEvent>, runtime: RuntimeService<TTarget, TEvent>, activation: ActivationService<TTarget, TEvent>, catalog: CommandCatalogService<TTarget, TEvent>, options: CommandExecutorOptions<TTarget, TEvent>);
     runCommand(cmd: string, options?: RunCommandOptions<TTarget, TEvent>): RunCommandResult;
+    dispatchCommand(cmd: string, options?: RunCommandOptions<TTarget, TEvent>): RunCommandResult;
     runBinding(bindingLayer: RegisteredLayer<TTarget, TEvent>, binding: CompiledBinding<TTarget, TEvent>, event: TEvent, focused: TTarget | null): boolean;
     private executeResolvedCommand;
 }

package/src/services/compiler.d.ts

@@ -1,7 +1,7 @@
 import type { ConditionService } from "./conditions.js";
 import type { State } from "./state.js";
 import type { NotificationService } from "./notify.js";
-import type { BindingInput, Scope, CompiledBindingsResult, KeyLike, KeymapEvent, KeySequencePart, ResolvedKeyToken } from "../types.js";
+import type { BindingInput, CompiledBindingsResult, KeyLike, KeymapEvent, KeySequencePart, ResolvedKeyToken } from "../types.js";
 export interface CompilerOptions {
     warnUnknownField: (kind: "binding" | "layer", fieldName: string) => void;
     warnUnknownToken: (token: string, sequence: string) => void;
@@ -13,7 +13,7 @@ export declare class CompilerService<TTarget extends object, TEvent extends Keym
     private readonly options;
     constructor(state: State<TTarget, TEvent>, notify: NotificationService<TTarget, TEvent>, conditions: ConditionService<TTarget, TEvent>, options: CompilerOptions);
     parseTokenKey(key: KeyLike): KeySequencePart;
-    compileBindings(bindings: readonly BindingInput<TTarget, TEvent>[], tokens: ReadonlyMap<string, ResolvedKeyToken>, sourceScope: Scope, sourceTarget: TTarget | undefined, sourceLayerOrder: number, compileFields?: Readonly<Record<string, unknown>>): CompiledBindingsResult<TTarget, TEvent>;
+    compileBindings(bindings: readonly BindingInput<TTarget, TEvent>[], tokens: ReadonlyMap<string, ResolvedKeyToken>, sourceTarget: TTarget | undefined, sourceLayerOrder: number, compileFields?: Readonly<Record<string, unknown>>): CompiledBindingsResult<TTarget, TEvent>;
     private parseObjectKeyPart;
     private normalizeBindingEvent;
     private applyBindingTransformers;

package/src/services/conditions.d.ts

@@ -7,8 +7,8 @@ export declare class ConditionService<TTarget extends object, TEvent extends Key
     constructor(state: State<TTarget, TEvent>, notify: NotificationService<TTarget, TEvent>);
     buildRuntimeMatcher(matcher: (() => boolean) | ReactiveMatcher, source: string): RuntimeMatcher;
     hasNoConditions(target: RuntimeMatchable): boolean;
-    registerRuntimeMatchable(target: RuntimeMatchable): void;
-    unregisterRuntimeMatchable(target: RuntimeMatchable): void;
+    indexRuntimeMatchable(target: RuntimeMatchable): void;
+    unindexRuntimeMatchable(target: RuntimeMatchable): void;
     invalidateRuntimeConditionKey(name: string): void;
     matchesConditions(target: RuntimeMatchable): boolean;
     layerMatchesRuntimeState(layer: RegisteredLayer<TTarget, TEvent>): boolean;

package/src/services/dispatch.d.ts

@@ -1,11 +1,13 @@
 import type { CompilerService } from "./compiler.js";
 import type { ActivationService } from "./activation.js";
 import type { CommandExecutorService } from "./command-executor.js";
+import type { CommandCatalogService } from "./command-catalog.js";
 import type { ConditionService } from "./conditions.js";
+import type { LayerService } from "./layers.js";
 import type { NotificationService } from "./notify.js";
 import type { RuntimeService } from "./runtime.js";
 import type { State } from "./state.js";
-import type { EventMatchResolver, KeyInterceptOptions, KeyInputContext, KeymapEvent, RawInterceptOptions, RawInputContext } from "../types.js";
+import { type EventMatchResolver, type KeyDisambiguationResolver, type KeyInterceptOptions, type KeyInputContext, type KeymapEvent, type PendingSequenceState, type RawInterceptOptions, type RawInputContext } from "../types.js";
 export declare class DispatchService<TTarget extends object, TEvent extends KeymapEvent> {
     private readonly state;
     private readonly notify;
@@ -14,20 +16,45 @@ export declare class DispatchService<TTarget extends object, TEvent extends Keym
     private readonly conditions;
     private readonly executor;
     private readonly compiler;
+    private readonly catalog;
+    private readonly layers;
     private readonly eventMatchResolverContext;
-    constructor(state: State<TTarget, TEvent>, notify: NotificationService<TTarget, TEvent>, runtime: RuntimeService<TTarget, TEvent>, activation: ActivationService<TTarget, TEvent>, conditions: ConditionService<TTarget, TEvent>, executor: CommandExecutorService<TTarget, TEvent>, compiler: CompilerService<TTarget, TEvent>);
+    private pendingDisambiguation;
+    private nextPendingDisambiguationId;
+    constructor(state: State<TTarget, TEvent>, notify: NotificationService<TTarget, TEvent>, runtime: RuntimeService<TTarget, TEvent>, activation: ActivationService<TTarget, TEvent>, conditions: ConditionService<TTarget, TEvent>, executor: CommandExecutorService<TTarget, TEvent>, compiler: CompilerService<TTarget, TEvent>, catalog: CommandCatalogService<TTarget, TEvent>, layers: LayerService<TTarget, TEvent>);
     intercept(name: "key", fn: (ctx: KeyInputContext<TEvent>) => void, options?: KeyInterceptOptions): () => void;
     intercept(name: "raw", fn: (ctx: RawInputContext) => void, options?: RawInterceptOptions): () => void;
     prependEventMatchResolver(resolver: EventMatchResolver<TEvent>): () => void;
     appendEventMatchResolver(resolver: EventMatchResolver<TEvent>): () => void;
     clearEventMatchResolvers(): void;
+    prependDisambiguationResolver(resolver: KeyDisambiguationResolver<TTarget, TEvent>): () => void;
+    appendDisambiguationResolver(resolver: KeyDisambiguationResolver<TTarget, TEvent>): () => void;
+    clearDisambiguationResolvers(): void;
+    handlePendingSequenceChange(_previous: PendingSequenceState<TTarget, TEvent> | null, _next: PendingSequenceState<TTarget, TEvent> | null): void;
     handleRawSequence(sequence: string): boolean;
     handleKeyEvent(event: TEvent, release: boolean): void;
+    private mutateDisambiguationResolvers;
     private dispatchReleaseLayers;
     private dispatchLayers;
     private dispatchPendingSequence;
+    private dispatchPendingCapturesFromIndex;
     private dispatchFromRoot;
+    private dispatchFromRootAtIndex;
+    private tryResolveRootAmbiguity;
+    private tryResolvePendingAmbiguity;
+    private tryResolveAmbiguity;
+    private applySyncDecision;
+    private resolveDisambiguation;
+    private scheduleDeferredDisambiguation;
+    private executeDeferredDisambiguation;
+    private applyDeferredDisambiguationResult;
+    private finishPendingDisambiguation;
+    private cancelPendingDisambiguation;
+    private isPendingDisambiguationCurrent;
+    private sleepWithSignal;
+    private warnUnresolvedAmbiguity;
     private collectPendingCapturesFromRoot;
+    private collectPendingCapturesFromAdvanced;
     private resolveEventMatchKeys;
     private runReleaseBindings;
     private getReachableChild;

package/src/services/layers.d.ts

@@ -20,15 +20,22 @@ export declare class LayerService<TTarget extends object, TEvent extends KeymapE
     constructor(state: State<TTarget, TEvent>, notify: NotificationService<TTarget, TEvent>, conditions: ConditionService<TTarget, TEvent>, activation: ActivationService<TTarget, TEvent>, options: LayersOptions<TTarget, TEvent>);
     registerLayer(layer: Layer<TTarget, TEvent>): () => void;
     applyTokenState(nextTokens: Map<string, ResolvedKeyToken>): void;
+    recompileBindings(): void;
     prependLayerAnalyzer(analyzer: LayerAnalyzer<TTarget, TEvent>): () => void;
     appendLayerAnalyzer(analyzer: LayerAnalyzer<TTarget, TEvent>): () => void;
     clearLayerAnalyzers(): void;
-    private normalizeScope;
+    cleanup(): void;
+    private normalizeTargetMode;
     private runLayerAnalyzers;
     private compileLayerRuntimeState;
-    private getOrCreateTargetBucket;
+    private compileLayerBindings;
+    private applyCompiledBindings;
     private indexLayer;
     private removeLayerFromIndex;
     private unregisterLayer;
+    private connectRuntimeMatchable;
+    private disconnectRuntimeMatchable;
+    private attachReactiveMatchers;
+    private detachReactiveMatchers;
 }
 export {};

package/src/services/notify.d.ts

@@ -2,6 +2,7 @@ import type { Events, HookName, Hooks, KeymapEvent } from "../types.js";
 import type { State } from "./state.js";
 import { Emitter } from "../lib/emitter.js";
 type DiagnosticEvents<TTarget extends object, TEvent extends KeymapEvent> = Pick<Events<TTarget, TEvent>, "warning" | "error">;
+export declare const MAX_STATE_CHANGE_FLUSH_ITERATIONS = 1000;
 export declare class NotificationService<TTarget extends object, TEvent extends KeymapEvent> {
     private readonly state;
     private readonly events;

package/src/services/primitives/active-layers.d.ts

@@ -1,5 +1,8 @@
-import type { KeymapEvent, KeymapHost, RegisteredLayer, RegisteredLayerBucket } from "../../types.js";
+import type { KeymapEvent, KeymapHost, RegisteredLayer } from "../../types.js";
+import type { LayersState } from "../state.js";
 export declare function getFocusedTargetIfAvailable<TTarget extends object, TEvent extends KeymapEvent>(host: KeymapHost<TTarget, TEvent>): TTarget | null;
 export declare function forEachActivationTarget<TTarget extends object, TEvent extends KeymapEvent>(host: KeymapHost<TTarget, TEvent>, focused: TTarget | null, visit: (target: TTarget, isFocusedTarget: boolean) => boolean | void): void;
-export declare function getActiveLayersForFocused<TTarget extends object, TEvent extends KeymapEvent>(targetLayers: WeakMap<TTarget, RegisteredLayerBucket<TTarget, TEvent>>, host: KeymapHost<TTarget, TEvent>, focused: TTarget | null): RegisteredLayer<TTarget, TEvent>[];
-export declare function isLayerActiveForFocused<TTarget extends object, TEvent extends KeymapEvent>(host: KeymapHost<TTarget, TEvent>, layer: RegisteredLayer<TTarget, TEvent>, focused: TTarget | null): boolean;
+export declare function getActivationPath<TTarget extends object, TEvent extends KeymapEvent>(host: KeymapHost<TTarget, TEvent>, focused: TTarget | null): Set<TTarget>;
+export declare function getActiveLayersForFocused<TTarget extends object, TEvent extends KeymapEvent>(state: LayersState<TTarget, TEvent>, host: KeymapHost<TTarget, TEvent>, focused: TTarget | null): readonly RegisteredLayer<TTarget, TEvent>[];
+export declare function invalidateCachedActiveLayers<TTarget extends object, TEvent extends KeymapEvent>(state: LayersState<TTarget, TEvent>): void;
+export declare function isLayerActiveForFocused<TTarget extends object, TEvent extends KeymapEvent>(host: KeymapHost<TTarget, TEvent>, layer: RegisteredLayer<TTarget, TEvent>, focused: TTarget | null, activationPath?: ReadonlySet<TTarget>): boolean;

package/src/services/state.d.ts

@@ -1,4 +1,4 @@
-import type { ActiveKey, BindingExpander, BindingFieldCompiler, BindingParser, BindingTransformer, CommandFieldCompiler, CommandResolver, EventData, EventMatchResolver, KeyInputContext, KeySequencePart, KeymapEvent, LayerAnalyzer, LayerFieldCompiler, PendingSequenceState, RawInputContext, RegisteredCommand, RegisteredLayer, RegisteredLayerBucket, ResolvedBindingCommand, RuntimeMatchable } from "../types.js";
+import type { ActiveKey, BindingExpander, BindingFieldCompiler, BindingParser, BindingTransformer, CommandFieldCompiler, CommandResolver, EventData, KeyDisambiguationResolver, EventMatchResolver, KeyInputContext, KeySequencePart, KeymapEvent, LayerAnalyzer, LayerFieldCompiler, PendingSequenceState, RawInputContext, RegisteredCommand, RegisteredLayer, ResolvedBindingCommand, RuntimeMatchable } from "../types.js";
 import { OrderedRegistry, PriorityRegistry } from "../lib/registry.js";
 export interface CoreState {
     order: number;
@@ -12,8 +12,9 @@ export interface EnvironmentState<TTarget extends object, TEvent extends KeymapE
     bindingFields: Map<string, BindingFieldCompiler>;
     commandFields: Map<string, CommandFieldCompiler>;
 }
-export interface DispatchState<TEvent extends KeymapEvent> {
+export interface DispatchState<TTarget extends object, TEvent extends KeymapEvent> {
     eventMatchResolvers: OrderedRegistry<EventMatchResolver<TEvent>>;
+    disambiguationResolvers: OrderedRegistry<KeyDisambiguationResolver<TTarget, TEvent>>;
     keyHooks: PriorityRegistry<(ctx: KeyInputContext<TEvent>) => void, {
         priority: number;
         release: boolean;
@@ -24,7 +25,11 @@ export interface DispatchState<TEvent extends KeymapEvent> {
 }
 export interface LayersState<TTarget extends object, TEvent extends KeymapEvent> {
     layers: Set<RegisteredLayer<TTarget, TEvent>>;
-    targetLayers: WeakMap<TTarget, RegisteredLayerBucket<TTarget, TEvent>>;
+    sortedLayers: RegisteredLayer<TTarget, TEvent>[];
+    activeLayersVersion: number;
+    activeLayersCacheVersion: number;
+    activeLayersCacheFocused: TTarget | null | undefined;
+    activeLayersCache: readonly RegisteredLayer<TTarget, TEvent>[];
     layersWithConditions: number;
     layersWithCommands: number;
     layerAnalyzers: OrderedRegistry<LayerAnalyzer<TTarget, TEvent>>;
@@ -37,12 +42,7 @@ export interface ResolvedCommandEntry<TTarget extends object, TEvent extends Key
     target?: TTarget;
     resolved: ResolvedBindingCommand<TTarget, TEvent>;
 }
-export interface ActiveCommandView<TTarget extends object, TEvent extends KeymapEvent> {
-    cacheable: boolean;
-    entries: readonly LayerCommandEntry<TTarget, TEvent>[];
-    reachable: readonly LayerCommandEntry<TTarget, TEvent>[];
-    reachableByName: ReadonlyMap<string, LayerCommandEntry<TTarget, TEvent>>;
-    chainsByName: ReadonlyMap<string, readonly LayerCommandEntry<TTarget, TEvent>[]>;
+export interface CommandChainCacheState<TTarget extends object, TEvent extends KeymapEvent> {
     resolvedWithoutRecordChains: Map<string, readonly ResolvedCommandEntry<TTarget, TEvent>[]>;
     resolvedWithRecordChains: Map<string, readonly ResolvedCommandEntry<TTarget, TEvent>[]>;
     fallbackWithoutRecord: Map<string, ResolvedBindingCommand<TTarget, TEvent> | null>;
@@ -50,12 +50,25 @@ export interface ActiveCommandView<TTarget extends object, TEvent extends Keymap
     fallbackWithoutRecordErrors: Set<string>;
     fallbackWithRecordErrors: Set<string>;
 }
+export interface ActiveCommandView<TTarget extends object, TEvent extends KeymapEvent> extends CommandChainCacheState<TTarget, TEvent> {
+    cacheable: boolean;
+    entries: readonly LayerCommandEntry<TTarget, TEvent>[];
+    reachable: readonly LayerCommandEntry<TTarget, TEvent>[];
+    reachableByName: ReadonlyMap<string, LayerCommandEntry<TTarget, TEvent>>;
+    chainsByName: ReadonlyMap<string, readonly LayerCommandEntry<TTarget, TEvent>[]>;
+}
+export interface RegisteredCommandView<TTarget extends object, TEvent extends KeymapEvent> extends CommandChainCacheState<TTarget, TEvent> {
+    entries: readonly LayerCommandEntry<TTarget, TEvent>[];
+    chainsByName: ReadonlyMap<string, readonly LayerCommandEntry<TTarget, TEvent>[]>;
+}
 export interface CommandsState<TTarget extends object, TEvent extends KeymapEvent> {
     commandMetadataVersion: number;
     registeredNames: Map<string, number>;
     commandResolvers: OrderedRegistry<CommandResolver<TTarget, TEvent>>;
     activeCommandViewVersion: number;
     activeCommandView?: ActiveCommandView<TTarget, TEvent>;
+    registeredCommandViewVersion: number;
+    registeredCommandView?: RegisteredCommandView<TTarget, TEvent>;
     registeredCommandEntriesCacheVersion: number;
     registeredCommandEntriesCache: readonly LayerCommandEntry<TTarget, TEvent>[];
 }
@@ -91,7 +104,7 @@ export interface NotifyState {
 export interface State<TTarget extends object, TEvent extends KeymapEvent> {
     core: CoreState;
     environment: EnvironmentState<TTarget, TEvent>;
-    dispatch: DispatchState<TEvent>;
+    dispatch: DispatchState<TTarget, TEvent>;
     layers: LayersState<TTarget, TEvent>;
     commands: CommandsState<TTarget, TEvent>;
     projection: ProjectionState<TTarget, TEvent>;

package/src/solid/index.d.ts

@@ -10,19 +10,17 @@ export declare function KeymapProvider(props: KeymapProviderProps): JSX.Element;
 export type UseBindingsTarget<TRenderable extends Renderable = Renderable> = () => TRenderable | null | undefined;
 type UseBindingsLayerBase = LayerFields<Renderable, KeyEvent>;
 export interface UseGlobalBindingsLayer extends UseBindingsLayerBase {
-    scope?: "global";
     target?: undefined;
 }
 export interface UseFocusBindingsLayer<TRenderable extends Renderable = Renderable> extends UseBindingsLayerBase {
-    scope: "focus";
+    targetMode: "focus";
     target: UseBindingsTarget<TRenderable>;
 }
 export interface UseFocusWithinBindingsLayer<TRenderable extends Renderable = Renderable> extends UseBindingsLayerBase {
-    scope: "focus-within";
+    targetMode?: "focus-within";
     target: UseBindingsTarget<TRenderable>;
 }
 export interface UseInferredFocusWithinBindingsLayer<TRenderable extends Renderable = Renderable> extends UseBindingsLayerBase {
-    scope?: undefined;
     target: UseBindingsTarget<TRenderable>;
 }
 export type UseTargetBindingsLayer<TRenderable extends Renderable = Renderable> = UseFocusBindingsLayer<TRenderable> | UseFocusWithinBindingsLayer<TRenderable> | UseInferredFocusWithinBindingsLayer<TRenderable>;