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

package/index.js

@@ -18,41 +18,49 @@ function forEachActivationTarget(host, focused, visit) {
     isFocusedTarget = false;
   }
 }
-function getActiveLayersForFocused(targetLayers, host, focused) {
+function getActivationPath(host, focused) {
+  const path = new Set;
+  forEachActivationTarget(host, focused, (current) => {
+    path.add(current);
+  });
+  return path;
+}
+function getActiveLayersForFocused(state, host, focused) {
+  if (state.activeLayersCacheVersion === state.activeLayersVersion && state.activeLayersCacheFocused === focused) {
+    return state.activeLayersCache;
+  }
   const activeLayers = [];
-  forEachActivationTarget(host, focused, (current, isFocusedTarget) => {
-    const bucket = targetLayers.get(current);
-    if (!bucket) {
-      return;
-    }
-    if (isFocusedTarget) {
-      activeLayers.push(...bucket.focusLayers);
+  const activationPath = getActivationPath(host, focused);
+  for (const layer of state.sortedLayers) {
+    if (isLayerActiveForFocused(host, layer, focused, activationPath)) {
+      activeLayers.push(layer);
     }
-    activeLayers.push(...bucket.focusWithinLayers);
-  });
+  }
+  state.activeLayersCacheVersion = state.activeLayersVersion;
+  state.activeLayersCacheFocused = focused;
+  state.activeLayersCache = activeLayers;
   return activeLayers;
 }
-function isLayerActiveForFocused(host, layer, focused) {
-  const target = layer.indexTarget;
+function invalidateCachedActiveLayers(state) {
+  state.activeLayersCacheVersion = -1;
+  state.activeLayersCacheFocused = undefined;
+  state.activeLayersCache = [];
+}
+function isLayerActiveForFocused(host, layer, focused, activationPath = getActivationPath(host, focused)) {
+  const target = layer.target;
+  if (!target) {
+    return true;
+  }
   if (host.isTargetDestroyed(target)) {
     return false;
   }
-  if (layer.scope === "focus") {
+  if (layer.targetMode === "focus") {
     return target === focused;
   }
-  let isActive = false;
-  forEachActivationTarget(host, focused, (current) => {
-    if (current === target) {
-      isActive = true;
-      return false;
-    }
-    return true;
-  });
-  return isActive;
+  return activationPath.has(target);
 }
 
 // src/services/keys.ts
-var keyMatches = new Map;
 function normalizeBindingTokenName(token) {
   const normalized = token.trim().toLowerCase();
   if (!normalized) {
@@ -117,14 +125,14 @@ function resolveKeyMatch(input) {
   return createKeyMatch(input);
 }
 function createKeyMatch(input) {
-  return getOrCreateKeyMatch(buildKeyMatchId(normalizeKeyStroke(input)));
+  return `key:${buildKeyMatchId(normalizeKeyStroke(input))}`;
 }
 function createTextKeyMatch(id) {
   const normalized = id.trim();
   if (!normalized) {
     throw new Error("Invalid keymap match id: id cannot be empty");
   }
-  return getOrCreateKeyMatch(`text:${normalized}`);
+  return `text:${normalized}`;
 }
 function stringifyKeyStroke(input, options) {
   if ("stroke" in input) {
@@ -161,15 +169,6 @@ function stringifyCanonicalStroke(stroke) {
 function buildKeyMatchId(stroke) {
   return `${stroke.name}:${stroke.ctrl ? 1 : 0}:${stroke.shift ? 1 : 0}:${stroke.meta ? 1 : 0}:${stroke.super ? 1 : 0}:${stroke.hyper ? 1 : 0}`;
 }
-function getOrCreateKeyMatch(id) {
-  const existing = keyMatches.get(id);
-  if (existing) {
-    return existing;
-  }
-  const match = Symbol(id);
-  keyMatches.set(id, match);
-  return match;
-}
 
 // src/services/activation.ts
 function getLiveHost(host) {
@@ -205,13 +204,15 @@ class ActivationService {
   notify;
   conditions;
   catalog;
-  constructor(state, host, hooks, notify, conditions, catalog) {
+  options;
+  constructor(state, host, hooks, notify, conditions, catalog, options = {}) {
     this.state = state;
     this.host = host;
     this.hooks = hooks;
     this.notify = notify;
     this.conditions = conditions;
     this.catalog = catalog;
+    this.options = options;
   }
   getFocusedTarget() {
     return getLiveHost(this.host).getFocusedTarget();
@@ -220,10 +221,12 @@ class ActivationService {
     return getFocusedTargetIfAvailable(this.host);
   }
   setPendingSequence(next) {
-    if (isSamePendingSequence(this.state.projection.pendingSequence, next)) {
+    const previous = this.state.projection.pendingSequence;
+    if (isSamePendingSequence(previous, next)) {
       return;
     }
     this.state.projection.pendingSequence = next;
+    this.options.onPendingSequenceChanged?.(previous, next);
     this.invalidateCaches();
     this.notifyPendingSequenceChange();
     this.notify.queueStateChange();
@@ -246,6 +249,15 @@ class ActivationService {
     }
     return this.state.projection.pendingSequence ?? undefined;
   }
+  revalidatePendingSequenceIfNeeded() {
+    if (this.host.isDestroyed || !this.state.projection.pendingSequence) {
+      return;
+    }
+    this.ensureValidPendingSequence();
+  }
+  hasPendingSequenceState() {
+    return !this.host.isDestroyed && this.state.projection.pendingSequence !== null;
+  }
   getPendingSequence() {
     const projections = this.state.projection;
     const derivedStateVersion = this.state.notify.derivedStateVersion;
@@ -335,11 +347,24 @@ class ActivationService {
     }
     return activeKeys;
   }
+  getActiveKeysForCaptures(captures, options) {
+    const includeBindings = options?.includeBindings === true;
+    const includeMetadata = options?.includeMetadata === true;
+    const focused = this.getFocusedTarget();
+    const activeView = this.catalog.getActiveCommandView(focused);
+    return this.collectActiveKeysFromPending(captures, includeBindings, includeMetadata, focused, activeView);
+  }
   nodeHasReachableBindings(node, focused) {
     return this.hasMatchingBindings(node.reachableBindings, focused, this.catalog.getActiveCommandView(focused));
   }
   getActiveLayers(focused) {
-    return getActiveLayersForFocused(this.state.layers.targetLayers, this.host, focused);
+    return getActiveLayersForFocused(this.state.layers, this.host, focused);
+  }
+  refreshActiveLayers(focused = this.getFocusedTargetIfAvailable()) {
+    getActiveLayersForFocused(this.state.layers, this.host, focused);
+  }
+  invalidateActiveLayers() {
+    invalidateCachedActiveLayers(this.state.layers);
   }
   isLayerActiveForFocused(layer, focused) {
     return isLayerActiveForFocused(this.host, layer, focused);
@@ -415,7 +440,7 @@ class ActivationService {
     }
     return parts;
   }
-  getMatchingBindings(bindings, focused, activeView) {
+  collectMatchingBindings(bindings, focused, activeView) {
     const matches = [];
     for (const binding of bindings) {
       if (this.conditions.matchesConditions(binding) && this.catalog.isBindingVisible(binding, focused, activeView)) {
@@ -432,7 +457,7 @@ class ActivationService {
     }
     return false;
   }
-  getNodePresentation(node, focused, activeView, reachableBindings = this.getMatchingBindings(node.reachableBindings, focused, activeView)) {
+  getNodePresentation(node, focused, activeView, reachableBindings = this.collectMatchingBindings(node.reachableBindings, focused, activeView)) {
     if (!node.stroke) {
       return { display: "" };
     }
@@ -561,16 +586,17 @@ class ActivationService {
     if (!node.stroke) {
       return;
     }
-    const reachableBindings = this.getMatchingBindings(node.reachableBindings, focused, activeView);
+    const reachableBindings = this.collectMatchingBindings(node.reachableBindings, focused, activeView);
     if (reachableBindings.length === 0) {
       return;
     }
-    const prefixBindings = this.getMatchingBindings(node.bindings, focused, activeView);
+    const prefixBindings = this.selectActiveBindings(node.bindings, focused, activeView);
     return {
       ...this.getNodePresentation(node, focused, activeView, reachableBindings),
       continues: true,
-      firstBinding: prefixBindings[0],
-      bindings: includeBindings && prefixBindings.length > 0 ? prefixBindings : undefined,
+      firstBinding: prefixBindings?.bindings[0],
+      commandBinding: prefixBindings?.commandBinding,
+      bindings: includeBindings && prefixBindings && prefixBindings.bindings.length > 0 ? [...prefixBindings.bindings] : undefined,
       stop: true
     };
   }
@@ -701,7 +727,7 @@ class ActivationService {
 // src/schema.ts
 var RESERVED_COMMAND_FIELDS = new Set(["name", "run"]);
 var RESERVED_BINDING_FIELDS = new Set(["key", "cmd", "event", "preventDefault", "fallthrough"]);
-var RESERVED_LAYER_FIELDS = new Set(["target", "scope", "priority", "bindings", "commands"]);
+var RESERVED_LAYER_FIELDS = new Set(["target", "targetMode", "priority", "bindings", "commands"]);
 
 // src/services/primitives/field-invariants.ts
 function mergeRequirement(target, name, value, source) {
@@ -770,6 +796,16 @@ var SNAPSHOT_FROZEN_COMMAND_METADATA_OPTIONS = Object.freeze({
   preserveNonPlainObjects: true
 });
 var EMPTY_COMMAND_FIELDS = Object.freeze({});
+function createCommandChainCacheState() {
+  return {
+    resolvedWithoutRecordChains: new Map,
+    resolvedWithRecordChains: new Map,
+    fallbackWithoutRecord: new Map,
+    fallbackWithRecord: new Map,
+    fallbackWithoutRecordErrors: new Set,
+    fallbackWithRecordErrors: new Set
+  };
+}
 function normalizeBindingCommand(command) {
   if (command === undefined || typeof command === "function") {
     return command;
@@ -864,10 +900,41 @@ class CommandCatalogService {
   }
   getResolvedCommandChain(command, focused, includeRecord) {
     const view = this.getActiveCommandView(focused);
-    const entries = this.getResolvedCommandChainFromView(view, command, focused, includeRecord);
+    const entries = this.getResolvedCommandChainFromView(view, command, focused, includeRecord, "active", view.chainsByName.get(command));
     const hadError = (includeRecord ? view.fallbackWithRecordErrors : view.fallbackWithoutRecordErrors).has(command);
     return { entries, hadError };
   }
+  getRegisteredResolvedEntries(command, includeRecord) {
+    const view = this.getRegisteredCommandView();
+    const cache = includeRecord ? view.resolvedWithRecordChains : view.resolvedWithoutRecordChains;
+    const cached = cache.get(command);
+    if (cached) {
+      return cached.length > 0 ? cached : undefined;
+    }
+    const chain = view.chainsByName.get(command);
+    if (!chain || chain.length === 0) {
+      cache.set(command, []);
+      return;
+    }
+    const resolved = [];
+    for (const entry of chain) {
+      resolved.push({
+        target: entry.layer.target,
+        resolved: resolveRegisteredCommand(entry.command, { includeRecord })
+      });
+    }
+    cache.set(command, resolved);
+    return resolved;
+  }
+  getRegisteredResolverFallback(command, includeRecord) {
+    const view = this.getRegisteredCommandView();
+    const fallback = this.getFallbackResolvedCommand(view, command, null, includeRecord, "registered");
+    const hadError = (includeRecord ? view.fallbackWithRecordErrors : view.fallbackWithoutRecordErrors).has(command);
+    return {
+      resolved: fallback?.resolved,
+      hadError
+    };
+  }
   getCommandAttrs(command, focused) {
     const top = this.getTopResolvedCommand(command, focused, false);
     return top?.resolved.attrs;
@@ -876,6 +943,36 @@ class CommandCatalogService {
     const top = this.getTopResolvedCommand(command, focused, true);
     return top?.resolved.record;
   }
+  getTopRegisteredCommandRecord(command) {
+    const top = this.getTopRegisteredCommand(command);
+    return top ? getRegisteredCommandRecord(top.command) : undefined;
+  }
+  getDispatchUnavailableCommandState(command, focused, includeRecord) {
+    const view = this.getRegisteredCommandView();
+    const chain = view.chainsByName.get(command);
+    if (!chain || chain.length === 0) {
+      return;
+    }
+    let inactiveEntry;
+    let disabledEntry;
+    for (const entry of chain) {
+      if (!isLayerActiveForFocused(this.host, entry.layer, focused)) {
+        inactiveEntry ??= entry;
+        continue;
+      }
+      if (!this.conditions.layerMatchesRuntimeState(entry.layer) || !this.conditions.matchesConditions(entry.command)) {
+        disabledEntry ??= entry;
+      }
+    }
+    const unavailableEntry = disabledEntry ?? inactiveEntry;
+    if (!unavailableEntry) {
+      return;
+    }
+    return {
+      reason: disabledEntry ? "disabled" : "inactive",
+      command: includeRecord ? getRegisteredCommandRecord(unavailableEntry.command) : undefined
+    };
+  }
   getActiveCommandView(focused) {
     const currentFocused = getFocusedTargetIfAvailable(this.host);
     const derivedStateVersion = this.state.notify.derivedStateVersion;
@@ -888,7 +985,7 @@ class CommandCatalogService {
     const chainsByName = new Map;
     let cacheable = true;
     if (this.state.layers.layersWithCommands > 0) {
-      for (const layer of getActiveLayersForFocused(this.state.layers.targetLayers, this.host, focused)) {
+      for (const layer of getActiveLayersForFocused(this.state.layers, this.host, focused)) {
         if (layer.commands.length === 0 || !this.conditions.layerMatchesRuntimeState(layer)) {
           continue;
         }
@@ -923,12 +1020,7 @@ class CommandCatalogService {
       reachable,
       reachableByName,
       chainsByName,
-      resolvedWithoutRecordChains: new Map,
-      resolvedWithRecordChains: new Map,
-      fallbackWithoutRecord: new Map,
-      fallbackWithRecord: new Map,
-      fallbackWithoutRecordErrors: new Set,
-      fallbackWithRecordErrors: new Set
+      ...createCommandChainCacheState()
     };
     if (focused === currentFocused && view.cacheable) {
       this.state.commands.activeCommandViewVersion = derivedStateVersion;
@@ -936,6 +1028,37 @@ class CommandCatalogService {
     }
     return view;
   }
+  getRegisteredCommandView() {
+    const cacheVersion = this.state.commands.commandMetadataVersion;
+    if (this.state.commands.registeredCommandViewVersion === cacheVersion && this.state.commands.registeredCommandView) {
+      return this.state.commands.registeredCommandView;
+    }
+    const entries = [];
+    const chainsByName = new Map;
+    for (const layer of this.state.layers.sortedLayers) {
+      if (layer.commands.length === 0) {
+        continue;
+      }
+      for (const command of layer.commands) {
+        const entry = { layer, command };
+        entries.push(entry);
+        const existing = chainsByName.get(command.name);
+        if (existing) {
+          existing.push(entry);
+        } else {
+          chainsByName.set(command.name, [entry]);
+        }
+      }
+    }
+    const view = {
+      entries,
+      chainsByName,
+      ...createCommandChainCacheState()
+    };
+    this.state.commands.registeredCommandViewVersion = cacheVersion;
+    this.state.commands.registeredCommandView = view;
+    return view;
+  }
   isBindingVisible(binding, focused, activeView) {
     if (binding.command === undefined || binding.run) {
       return true;
@@ -946,7 +1069,7 @@ class CommandCatalogService {
     if (activeView.reachableByName.has(binding.command)) {
       return true;
     }
-    return this.getFallbackResolvedCommand(activeView, binding.command, focused, false) !== undefined;
+    return this.getFallbackResolvedCommand(activeView, binding.command, focused, false, "active") !== undefined;
   }
   getBindingCommandAttrs(binding, focused, activeView) {
     if (typeof binding.command !== "string") {
@@ -956,7 +1079,7 @@ class CommandCatalogService {
     if (active) {
       return active.command.attrs;
     }
-    const fallback = this.getFallbackResolvedCommand(activeView, binding.command, focused, false);
+    const fallback = this.getFallbackResolvedCommand(activeView, binding.command, focused, false, "active");
     return fallback?.resolved.attrs;
   }
   getCommandResolutionStatus(command, layerCommands) {
@@ -997,16 +1120,20 @@ class CommandCatalogService {
         resolved: resolveRegisteredCommand(active.command, { includeRecord })
       };
     }
-    return this.getFallbackResolvedCommand(activeView, command, focused, includeRecord);
+    return this.getFallbackResolvedCommand(activeView, command, focused, includeRecord, "active");
+  }
+  getTopRegisteredCommand(command) {
+    const view = this.getRegisteredCommandView();
+    return view.chainsByName.get(command)?.[0];
   }
-  getFallbackResolvedCommand(activeView, command, focused, includeRecord) {
-    const cache = includeRecord ? activeView.fallbackWithRecord : activeView.fallbackWithoutRecord;
-    const errorCache = includeRecord ? activeView.fallbackWithRecordErrors : activeView.fallbackWithoutRecordErrors;
+  getFallbackResolvedCommand(view, command, focused, includeRecord, mode) {
+    const cache = includeRecord ? view.fallbackWithRecord : view.fallbackWithoutRecord;
+    const errorCache = includeRecord ? view.fallbackWithRecordErrors : view.fallbackWithoutRecordErrors;
     if (cache.has(command)) {
       const cached = cache.get(command);
       return cached ? { resolved: cached } : undefined;
     }
-    const lookup = this.resolveCommandWithResolvers(command, focused, { includeRecord });
+    const lookup = this.resolveCommandWithResolvers(command, focused, { includeRecord, mode });
     cache.set(command, lookup.resolved ?? null);
     if (lookup.hadError) {
       errorCache.add(command);
@@ -1016,23 +1143,23 @@ class CommandCatalogService {
     }
     return { resolved: lookup.resolved };
   }
-  getResolvedCommandChainFromView(activeView, command, focused, includeRecord) {
-    const cache = includeRecord ? activeView.resolvedWithRecordChains : activeView.resolvedWithoutRecordChains;
+  getResolvedCommandChainFromView(view, command, focused, includeRecord, mode, activeChain) {
+    const cache = includeRecord ? view.resolvedWithRecordChains : view.resolvedWithoutRecordChains;
     const cached = cache.get(command);
     if (cached) {
       return cached.length > 0 ? cached : undefined;
     }
     const resolved = [];
-    const activeChain = activeView.chainsByName.get(command);
-    if (activeChain) {
-      for (const entry of activeChain) {
+    const chain = activeChain;
+    if (chain) {
+      for (const entry of chain) {
         resolved.push({
           target: entry.layer.target,
           resolved: resolveRegisteredCommand(entry.command, { includeRecord })
         });
       }
     }
-    const fallback = this.getFallbackResolvedCommand(activeView, command, focused, includeRecord);
+    const fallback = this.getFallbackResolvedCommand(view, command, focused, includeRecord, mode);
     if (fallback) {
       resolved.push(fallback);
     }
@@ -1101,7 +1228,7 @@ class CommandCatalogService {
     if (!activeView) {
       return;
     }
-    for (const layer of getActiveLayersForFocused(this.state.layers.targetLayers, this.host, context.focused)) {
+    for (const layer of getActiveLayersForFocused(this.state.layers, this.host, context.focused)) {
       if (layer.compiledBindings.length === 0 || !this.conditions.layerMatchesRuntimeState(layer)) {
         continue;
       }
@@ -1139,20 +1266,26 @@ class CommandCatalogService {
   }
   resolveCommandWithResolvers(command, focused, options) {
     const includeRecord = options?.includeRecord === true;
-    const context = this.createCommandResolverContext(includeRecord, focused);
+    const context = this.createCommandResolverContext(includeRecord, focused, options?.mode ?? "active");
     return resolveCommandWithResolvers(command, this.state.commands.commandResolvers.values(), context, (error) => {
       this.notify.emitError("command-resolver-error", error, `[Keymap] Error in command resolver for "${command}":`);
     });
   }
-  createCommandResolverContext(includeRecord, focused) {
+  createCommandResolverContext(includeRecord, focused, mode) {
     return {
       getCommandAttrs: (name) => {
+        if (mode === "registered") {
+          return this.getTopRegisteredCommand(name)?.command.attrs;
+        }
         return this.getCommandAttrs(name, focused);
       },
       getCommandRecord: (name) => {
         if (!includeRecord) {
           return;
         }
+        if (mode === "registered") {
+          return this.getTopRegisteredCommandRecord(name);
+        }
         return this.getTopCommandRecord(name, focused);
       }
     };
@@ -1523,6 +1656,72 @@ class CommandExecutorService {
     this.options = options;
   }
   runCommand(cmd, options) {
+    let normalized;
+    try {
+      normalized = normalizeBindingCommand(cmd);
+    } catch {
+      return { ok: false, reason: "invalid-args" };
+    }
+    if (typeof normalized !== "string") {
+      return { ok: false, reason: "not-found" };
+    }
+    const includeRecord = options?.includeCommand === true;
+    const focused = options?.focused ?? this.activation.getFocusedTargetIfAvailable();
+    const event = options?.event ?? this.options.createCommandEvent();
+    const data = this.runtime.getReadonlyData();
+    const chain = this.catalog.getRegisteredResolvedEntries(normalized, includeRecord);
+    let rejectedResult;
+    if (chain?.length === 1) {
+      const [entry] = chain;
+      if (entry) {
+        const execution = this.executeResolvedCommand(normalized, entry.resolved, {
+          keymap: this.options.keymap,
+          event,
+          focused,
+          target: options?.target ?? entry.target ?? null,
+          data
+        });
+        if (execution.status === "handled" || execution.status === "error") {
+          return execution.result;
+        }
+        rejectedResult = execution.result;
+      }
+    } else if (chain) {
+      for (const entry of chain) {
+        const context = {
+          keymap: this.options.keymap,
+          event,
+          focused,
+          target: options?.target ?? entry.target ?? null,
+          data
+        };
+        const execution = this.executeResolvedCommand(normalized, entry.resolved, context);
+        if (execution.status === "handled" || execution.status === "error") {
+          return execution.result;
+        }
+        rejectedResult = execution.result;
+      }
+    }
+    const fallback = this.catalog.getRegisteredResolverFallback(normalized, includeRecord);
+    if (fallback.resolved) {
+      const execution = this.executeResolvedCommand(normalized, fallback.resolved, {
+        keymap: this.options.keymap,
+        event,
+        focused,
+        target: options?.target ?? null,
+        data
+      });
+      if (execution.status === "handled" || execution.status === "error") {
+        return execution.result;
+      }
+      rejectedResult = execution.result;
+    }
+    if (fallback.hadError) {
+      return { ok: false, reason: "error" };
+    }
+    return rejectedResult ?? { ok: false, reason: "not-found" };
+  }
+  dispatchCommand(cmd, options) {
     let normalized;
     try {
       normalized = normalizeBindingCommand(cmd);
@@ -1539,7 +1738,22 @@ class CommandExecutorService {
     const chainLookup = this.catalog.getResolvedCommandChain(normalized, focused, includeRecord);
     const chain = chainLookup.entries;
     let rejectedResult;
-    if (chain) {
+    if (chain?.length === 1) {
+      const [entry] = chain;
+      if (entry) {
+        const execution = this.executeResolvedCommand(normalized, entry.resolved, {
+          keymap: this.options.keymap,
+          event,
+          focused,
+          target: options?.target ?? entry.target ?? null,
+          data
+        });
+        if (execution.status === "handled" || execution.status === "error") {
+          return execution.result;
+        }
+        rejectedResult = execution.result;
+      }
+    } else if (chain) {
       for (const entry of chain) {
         const context = {
           keymap: this.options.keymap,
@@ -1558,6 +1772,10 @@ class CommandExecutorService {
     if (chainLookup.hadError) {
       return { ok: false, reason: "error" };
     }
+    const unavailable = this.catalog.getDispatchUnavailableCommandState(normalized, focused, includeRecord);
+    if (unavailable) {
+      return unavailable.command ? { ok: false, reason: unavailable.reason, command: unavailable.command } : { ok: false, reason: unavailable.reason };
+    }
     return rejectedResult ?? { ok: false, reason: "not-found" };
   }
   runBinding(bindingLayer, binding, event, focused) {
@@ -1580,7 +1798,23 @@ class CommandExecutorService {
       return false;
     }
     const chain = this.catalog.getResolvedCommandChain(binding.command, focused, false).entries;
-    if (chain) {
+    if (chain?.length === 1) {
+      const [entry] = chain;
+      if (entry) {
+        const execution = this.executeResolvedCommand(binding.command, entry.resolved, {
+          keymap: this.options.keymap,
+          event,
+          focused,
+          target: entry.target ?? bindingLayer.target ?? null,
+          data
+        });
+        if (execution.status === "rejected") {
+          return false;
+        }
+        applyBindingEventEffects(binding, event);
+        return true;
+      }
+    } else if (chain) {
       for (const entry of chain) {
         const context = {
           keymap: this.options.keymap,
@@ -1714,13 +1948,14 @@ class CompilerService {
       parseObjectKey: (value, options) => this.parseObjectKeyPart(value, options)
     });
   }
-  compileBindings(bindings, tokens, sourceScope, sourceTarget, sourceLayerOrder, compileFields) {
+  compileBindings(bindings, tokens, sourceTarget, sourceLayerOrder, compileFields) {
     const root = createSequenceNode(null, null, null);
     const compiledBindings = [];
     let hasTokenBindings = false;
     const bindingExpanders = this.state.environment.bindingExpanders.values();
     const bindingParsers = this.state.environment.bindingParsers.values();
     const bindingFieldCompilers = this.state.environment.bindingFields;
+    const allowExactPrefixAmbiguity = this.state.dispatch.disambiguationResolvers.has();
     const warnUnknownField = this.options.warnUnknownField;
     const warnUnknownToken = this.options.warnUnknownToken;
     const conditions = this.conditions;
@@ -1817,7 +2052,6 @@ class CompilerService {
               command,
               event,
               sourceBinding: snapshotParsedBindingInput(compiledInput),
-              sourceScope,
               sourceTarget,
               sourceLayerOrder,
               sourceBindingIndex: bindingIndex,
@@ -1842,7 +2076,7 @@ class CompilerService {
               throw new Error("Keymap release bindings only support a single key stroke");
             }
             if (event === "press") {
-              this.insertBinding(root, compiledBinding);
+              this.insertBinding(root, compiledBinding, allowExactPrefixAmbiguity);
             }
             compiledBindings.push(compiledBinding);
           } catch (error) {
@@ -1911,13 +2145,13 @@ class CompilerService {
     }
     return [parsedBinding, ...extraBindings];
   }
-  insertBinding(root, binding) {
+  insertBinding(root, binding, allowExactPrefixAmbiguity) {
     let node = root;
     const touchedNodes = [];
     const createdNodes = [];
     try {
       for (const part of binding.sequence) {
-        if (node.bindings.some((candidate) => candidate.command !== undefined)) {
+        if (!allowExactPrefixAmbiguity && node.bindings.some((candidate) => candidate.command !== undefined)) {
           throw new Error("Keymap bindings cannot use the same sequence as both an exact match and a prefix in the same layer");
         }
         const bindingKey = part.match;
@@ -1931,7 +2165,7 @@ class CompilerService {
         touchedNodes.push(child);
         node = child;
       }
-      if (binding.command !== undefined && node.children.size > 0) {
+      if (!allowExactPrefixAmbiguity && binding.command !== undefined && node.children.size > 0) {
         throw new Error("Keymap bindings cannot use the same sequence as both an exact match and a prefix in the same layer");
       }
       node.bindings = [...node.bindings, binding];
@@ -2096,20 +2330,7 @@ class ConditionService {
   hasNoConditions(target) {
     return target.requires.length === 0 && target.matchers.length === 0;
   }
-  registerRuntimeMatchable(target) {
-    for (const matcher of target.matchers) {
-      if (!matcher.subscribe) {
-        continue;
-      }
-      try {
-        matcher.dispose = matcher.subscribe(() => {
-          target.matchCacheDirty = true;
-          this.notify.queueStateChange();
-        });
-      } catch (error) {
-        this.notify.emitError("reactive-matcher-subscribe-error", error, getErrorMessage(error, `Failed to subscribe to reactive matcher from ${matcher.source}`));
-      }
-    }
+  indexRuntimeMatchable(target) {
     if (target.conditionKeys.length > 0) {
       for (const key of target.conditionKeys) {
         const dependents = this.state.conditions.runtimeKeyDependents.get(key);
@@ -2124,18 +2345,7 @@ class ConditionService {
       target.matchCacheDirty = true;
     }
   }
-  unregisterRuntimeMatchable(target) {
-    for (const matcher of target.matchers) {
-      if (!matcher.dispose) {
-        continue;
-      }
-      try {
-        matcher.dispose();
-      } catch (error) {
-        this.notify.emitError("reactive-matcher-dispose-error", error, getErrorMessage(error, `Failed to dispose reactive matcher from ${matcher.source}`));
-      }
-      matcher.dispose = undefined;
-    }
+  unindexRuntimeMatchable(target) {
     if (target.conditionKeys.length === 0) {
       return;
     }
@@ -2225,7 +2435,31 @@ class ConditionService {
   }
 }
 
+// src/types.ts
+var KEY_DISAMBIGUATION_DECISION = Symbol("keymap-disambiguation-decision");
+var KEY_DEFERRED_DISAMBIGUATION_DECISION = Symbol("keymap-deferred-disambiguation-decision");
+
 // src/services/dispatch.ts
+function createSyncDecision(action, handler) {
+  return {
+    [KEY_DISAMBIGUATION_DECISION]: true,
+    action,
+    handler
+  };
+}
+function createDeferredDecision(action) {
+  return {
+    [KEY_DEFERRED_DISAMBIGUATION_DECISION]: true,
+    action
+  };
+}
+function isSyncDecision(value) {
+  return !!value && typeof value === "object" && value[KEY_DISAMBIGUATION_DECISION] === true;
+}
+function isDeferredDecision(value) {
+  return !!value && typeof value === "object" && value[KEY_DEFERRED_DISAMBIGUATION_DECISION] === true;
+}
+
 class DispatchService {
   state;
   notify;
@@ -2234,8 +2468,12 @@ class DispatchService {
   conditions;
   executor;
   compiler;
+  catalog;
+  layers;
   eventMatchResolverContext;
-  constructor(state, notify, runtime, activation, conditions, executor, compiler) {
+  pendingDisambiguation = null;
+  nextPendingDisambiguationId = 0;
+  constructor(state, notify, runtime, activation, conditions, executor, compiler, catalog, layers) {
     this.state = state;
     this.notify = notify;
     this.runtime = runtime;
@@ -2243,6 +2481,8 @@ class DispatchService {
     this.conditions = conditions;
     this.executor = executor;
     this.compiler = compiler;
+    this.catalog = catalog;
+    this.layers = layers;
     this.eventMatchResolverContext = {
       resolveKey: (key) => {
         return this.compiler.parseTokenKey(key).match;
@@ -2271,6 +2511,27 @@ class DispatchService {
   clearEventMatchResolvers() {
     this.state.dispatch.eventMatchResolvers.clear();
   }
+  prependDisambiguationResolver(resolver) {
+    return this.mutateDisambiguationResolvers(() => this.state.dispatch.disambiguationResolvers.prepend(resolver), resolver);
+  }
+  appendDisambiguationResolver(resolver) {
+    return this.mutateDisambiguationResolvers(() => this.state.dispatch.disambiguationResolvers.append(resolver), resolver);
+  }
+  clearDisambiguationResolvers() {
+    if (!this.state.dispatch.disambiguationResolvers.has()) {
+      return;
+    }
+    this.notify.runWithStateChangeBatch(() => {
+      this.state.dispatch.disambiguationResolvers.clear();
+      this.layers.recompileBindings();
+    });
+  }
+  handlePendingSequenceChange(_previous, _next) {
+    if (!this.pendingDisambiguation) {
+      return;
+    }
+    this.cancelPendingDisambiguation();
+  }
   handleRawSequence(sequence) {
     const hooks = this.state.dispatch.rawHooks.entries();
     if (hooks.length === 0) {
@@ -2296,6 +2557,9 @@ class DispatchService {
     return false;
   }
   handleKeyEvent(event, release) {
+    if (!release) {
+      this.cancelPendingDisambiguation();
+    }
     const hooks = this.state.dispatch.keyHooks.entries();
     const context = {
       event,
@@ -2335,6 +2599,27 @@ class DispatchService {
     }
     this.dispatchLayers(event);
   }
+  mutateDisambiguationResolvers(register, resolver) {
+    return this.notify.runWithStateChangeBatch(() => {
+      const hadResolvers = this.state.dispatch.disambiguationResolvers.has();
+      const off = register();
+      if (!hadResolvers && this.state.dispatch.disambiguationResolvers.has()) {
+        this.layers.recompileBindings();
+      }
+      return () => {
+        this.notify.runWithStateChangeBatch(() => {
+          const hadBeforeRemoval = this.state.dispatch.disambiguationResolvers.has();
+          off();
+          if (this.state.dispatch.disambiguationResolvers.values().includes(resolver)) {
+            return;
+          }
+          if (hadBeforeRemoval && !this.state.dispatch.disambiguationResolvers.has()) {
+            this.layers.recompileBindings();
+          }
+        });
+      };
+    });
+  }
   dispatchReleaseLayers(event) {
     const focused = this.activation.getFocusedTarget();
     const activeLayers = this.activation.getActiveLayers(focused);
@@ -2387,74 +2672,357 @@ class DispatchService {
       this.activation.setPendingSequence(null);
       return;
     }
-    let handledExact = false;
-    captureLoop:
-      for (let index = 0;index < advancedCaptures.length; index += 1) {
-        const capture = advancedCaptures[index];
-        if (!capture) {
-          continue;
-        }
-        if (capture.node.children.size > 0) {
-          if (handledExact) {
-            continue;
-          }
-          this.activation.setPendingSequence({
-            captures: advancedCaptures.filter((candidate, candidateIndex) => {
-              return candidateIndex >= index && candidate.node.children.size > 0;
-            })
-          });
-          event.preventDefault();
-          event.stopPropagation();
-          return;
-        }
-        const result = this.runBindings(capture.layer, capture.node.bindings, event, focused);
-        if (!result.handled) {
+    this.dispatchPendingCapturesFromIndex(advancedCaptures, 0, false, event, focused);
+  }
+  dispatchPendingCapturesFromIndex(advancedCaptures, startIndex, handledExact, event, focused) {
+    let hasHandledExact = handledExact;
+    for (let index = startIndex;index < advancedCaptures.length; index += 1) {
+      const capture = advancedCaptures[index];
+      if (!capture) {
+        continue;
+      }
+      if (capture.node.children.size > 0) {
+        if (hasHandledExact) {
           continue;
         }
-        handledExact = true;
-        if (result.stop) {
-          this.activation.setPendingSequence(null);
+        const continuationCaptures = this.collectPendingCapturesFromAdvanced(advancedCaptures, index);
+        if (this.tryResolvePendingAmbiguity(advancedCaptures, index, continuationCaptures, capture, event, focused, hasHandledExact)) {
           return;
         }
-        continue captureLoop;
+        this.activation.setPendingSequence({ captures: continuationCaptures });
+        event.preventDefault();
+        event.stopPropagation();
+        return;
       }
+      const result = this.runBindings(capture.layer, capture.node.bindings, event, focused);
+      if (!result.handled) {
+        continue;
+      }
+      hasHandledExact = true;
+      if (result.stop) {
+        this.activation.setPendingSequence(null);
+        return;
+      }
+    }
     this.activation.setPendingSequence(null);
   }
   dispatchFromRoot(activeLayers, matchKeys, event, focused) {
+    this.dispatchFromRootAtIndex(activeLayers, 0, matchKeys, event, focused);
+  }
+  dispatchFromRootAtIndex(activeLayers, startIndex, matchKeys, event, focused) {
     const hasLayerConditions = this.state.layers.layersWithConditions > 0;
-    layerLoop:
-      for (let index = 0;index < activeLayers.length; index += 1) {
-        const layer = activeLayers[index];
-        if (!layer) {
-          continue;
-        }
-        if (layer.root.children.size === 0) {
-          continue;
-        }
-        if (hasLayerConditions && !this.conditions.hasNoConditions(layer) && !this.conditions.matchesConditions(layer)) {
-          continue;
-        }
-        const nextNode = this.getReachableChild(layer.root, matchKeys, focused);
-        if (!nextNode) {
-          continue;
-        }
-        if (nextNode.children.size > 0) {
-          this.activation.setPendingSequence({
-            captures: this.collectPendingCapturesFromRoot(activeLayers, index, matchKeys, focused)
-          });
-          event.preventDefault();
-          event.stopPropagation();
+    for (let index = startIndex;index < activeLayers.length; index += 1) {
+      const layer = activeLayers[index];
+      if (!layer) {
+        continue;
+      }
+      if (layer.root.children.size === 0) {
+        continue;
+      }
+      if (hasLayerConditions && !this.conditions.hasNoConditions(layer) && !this.conditions.matchesConditions(layer)) {
+        continue;
+      }
+      const nextNode = this.getReachableChild(layer.root, matchKeys, focused);
+      if (!nextNode) {
+        continue;
+      }
+      if (nextNode.children.size > 0) {
+        const continuationCaptures = this.collectPendingCapturesFromRoot(activeLayers, index, matchKeys, focused);
+        if (this.tryResolveRootAmbiguity(activeLayers, index, matchKeys, continuationCaptures, layer, nextNode, event, focused)) {
           return;
         }
-        const result = this.runBindings(layer, nextNode.bindings, event, focused);
-        if (!result.handled) {
-          continue;
+        this.activation.setPendingSequence({ captures: continuationCaptures });
+        event.preventDefault();
+        event.stopPropagation();
+        return;
+      }
+      const result = this.runBindings(layer, nextNode.bindings, event, focused);
+      if (!result.handled) {
+        continue;
+      }
+      if (result.stop) {
+        return;
+      }
+    }
+  }
+  tryResolveRootAmbiguity(activeLayers, layerIndex, matchKeys, continuationCaptures, layer, node, event, focused) {
+    const applyExact = () => {
+      this.activation.setPendingSequence(null);
+      const result = this.runBindings(layer, node.bindings, event, focused);
+      if (!result.stop) {
+        this.dispatchFromRootAtIndex(activeLayers, layerIndex + 1, matchKeys, event, focused);
+      }
+    };
+    return this.tryResolveAmbiguity({
+      event,
+      focused,
+      continuationCaptures,
+      exactBindingsSource: node.bindings,
+      runExact: applyExact
+    });
+  }
+  tryResolvePendingAmbiguity(advancedCaptures, captureIndex, continuationCaptures, capture, event, focused, handledExact) {
+    const applyExact = () => {
+      this.activation.setPendingSequence(null);
+      const result = this.runBindings(capture.layer, capture.node.bindings, event, focused);
+      if (result.stop) {
+        return;
+      }
+      this.dispatchPendingCapturesFromIndex(advancedCaptures, captureIndex + 1, handledExact || result.handled, event, focused);
+    };
+    return this.tryResolveAmbiguity({
+      event,
+      focused,
+      continuationCaptures,
+      exactBindingsSource: capture.node.bindings,
+      runExact: applyExact
+    });
+  }
+  tryResolveAmbiguity(options) {
+    const { event, focused, continuationCaptures, exactBindingsSource, runExact } = options;
+    if (!this.state.dispatch.disambiguationResolvers.has() || continuationCaptures.length === 0) {
+      return false;
+    }
+    const activeView = this.catalog.getActiveCommandView(focused);
+    const exactBindings = this.activation.collectMatchingBindings(exactBindingsSource, focused, activeView);
+    if (!exactBindings.some((binding) => binding.command !== undefined)) {
+      return false;
+    }
+    const continueSequence = () => {
+      this.activation.setPendingSequence({ captures: continuationCaptures });
+      event.preventDefault();
+      event.stopPropagation();
+    };
+    const clear = () => {
+      this.activation.setPendingSequence(null);
+      event.preventDefault();
+      event.stopPropagation();
+    };
+    let sequence;
+    const getSequence = () => {
+      sequence ??= this.activation.collectSequencePartsFromPending({ captures: continuationCaptures });
+      return sequence;
+    };
+    const decision = this.resolveDisambiguation({
+      event,
+      focused,
+      getSequence,
+      exactBindings,
+      continuationCaptures,
+      activeView
+    });
+    if (!decision) {
+      this.warnUnresolvedAmbiguity(getSequence());
+      continueSequence();
+      return true;
+    }
+    return this.applySyncDecision(decision, continuationCaptures, runExact, continueSequence, clear, focused, getSequence);
+  }
+  applySyncDecision(decision, continuationCaptures, runExact, continueSequence, clear, focused, getSequence) {
+    if (decision.action === "run-exact") {
+      runExact();
+      return true;
+    }
+    if (decision.action === "continue-sequence") {
+      continueSequence();
+      return true;
+    }
+    if (decision.action === "clear") {
+      clear();
+      return true;
+    }
+    continueSequence();
+    this.scheduleDeferredDisambiguation(continuationCaptures, decision.handler, focused, getSequence(), (nextDecision) => {
+      if (!nextDecision) {
+        return;
+      }
+      if (nextDecision.action === "run-exact") {
+        runExact();
+        return;
+      }
+      if (nextDecision.action === "continue-sequence") {
+        continueSequence();
+        return;
+      }
+      clear();
+    });
+    return true;
+  }
+  resolveDisambiguation(options) {
+    const activation = this.activation;
+    const runtime = this.runtime;
+    let sequence;
+    let exact;
+    let continuations;
+    let strokePart;
+    const ctx = {
+      event: options.event,
+      focused: options.focused,
+      get sequence() {
+        sequence ??= cloneKeySequence(options.getSequence());
+        return sequence;
+      },
+      get stroke() {
+        const stroke = options.getSequence().at(-1);
+        if (!stroke) {
+          throw new Error("Disambiguation context expected a non-empty sequence");
         }
-        if (result.stop) {
+        strokePart ??= {
+          ...stroke,
+          stroke: cloneKeyStroke(stroke.stroke)
+        };
+        return strokePart;
+      },
+      get exact() {
+        exact ??= activation.collectActiveBindings(options.exactBindings, options.focused, options.activeView).map((binding) => ({
+          ...binding,
+          sequence: cloneKeySequence(binding.sequence)
+        }));
+        return exact;
+      },
+      get continuations() {
+        continuations ??= activation.getActiveKeysForCaptures(options.continuationCaptures, {
+          includeBindings: true,
+          includeMetadata: true
+        });
+        return continuations;
+      },
+      getData: (name) => {
+        return runtime.getData(name);
+      },
+      setData: (name, value) => {
+        runtime.setData(name, value);
+      },
+      runExact: () => createSyncDecision("run-exact"),
+      continueSequence: () => createSyncDecision("continue-sequence"),
+      clear: () => createSyncDecision("clear"),
+      defer: (run) => createSyncDecision("defer", run)
+    };
+    for (const resolver of this.state.dispatch.disambiguationResolvers.values()) {
+      let result;
+      try {
+        result = resolver(ctx);
+      } catch (error) {
+        this.notify.emitError("disambiguation-resolver-error", error, "[Keymap] Error in disambiguation resolver:");
+        continue;
+      }
+      if (result === undefined) {
+        continue;
+      }
+      if (isPromiseLike(result)) {
+        this.notify.emitError("invalid-disambiguation-resolver-return", result, "[Keymap] Disambiguation resolvers must return synchronously; use ctx.defer(...) for async handling");
+        continue;
+      }
+      if (!isSyncDecision(result)) {
+        this.notify.emitError("invalid-disambiguation-decision", result, "[Keymap] Invalid disambiguation decision returned by resolver:");
+        continue;
+      }
+      return result;
+    }
+    return;
+  }
+  scheduleDeferredDisambiguation(captures, handler, focused, sequence, apply) {
+    this.cancelPendingDisambiguation();
+    const controller = new AbortController;
+    const pending = {
+      id: this.nextPendingDisambiguationId++,
+      controller,
+      captures,
+      apply
+    };
+    this.pendingDisambiguation = pending;
+    queueMicrotask(() => {
+      this.executeDeferredDisambiguation(pending, handler, focused, sequence);
+    });
+  }
+  executeDeferredDisambiguation(pending, handler, focused, sequence) {
+    if (!this.isPendingDisambiguationCurrent(pending)) {
+      return;
+    }
+    const ctx = {
+      signal: pending.controller.signal,
+      sequence: cloneKeySequence(sequence),
+      focused,
+      sleep: (ms) => {
+        return this.sleepWithSignal(ms, pending.controller.signal);
+      },
+      runExact: () => createDeferredDecision("run-exact"),
+      continueSequence: () => createDeferredDecision("continue-sequence"),
+      clear: () => createDeferredDecision("clear")
+    };
+    let result;
+    try {
+      result = handler(ctx);
+    } catch (error) {
+      if (this.isPendingDisambiguationCurrent(pending)) {
+        this.notify.emitError("deferred-disambiguation-error", error, "[Keymap] Error in deferred disambiguation handler:");
+        this.finishPendingDisambiguation(pending);
+      }
+      return;
+    }
+    if (isPromiseLike(result)) {
+      result.then((resolved) => {
+        this.applyDeferredDisambiguationResult(pending, resolved);
+      }).catch((error) => {
+        if (!this.isPendingDisambiguationCurrent(pending)) {
           return;
         }
-        continue layerLoop;
-      }
+        this.notify.emitError("deferred-disambiguation-error", error, "[Keymap] Error in deferred disambiguation handler:");
+        this.finishPendingDisambiguation(pending);
+      });
+      return;
+    }
+    this.applyDeferredDisambiguationResult(pending, result);
+  }
+  applyDeferredDisambiguationResult(pending, result) {
+    if (!this.isPendingDisambiguationCurrent(pending)) {
+      return;
+    }
+    if (result !== undefined && !isDeferredDecision(result)) {
+      this.notify.emitError("invalid-deferred-disambiguation-decision", result, "[Keymap] Invalid deferred disambiguation decision returned by handler:");
+      this.finishPendingDisambiguation(pending);
+      return;
+    }
+    this.finishPendingDisambiguation(pending);
+    pending.apply(result);
+  }
+  finishPendingDisambiguation(pending) {
+    if (!this.isPendingDisambiguationCurrent(pending)) {
+      return;
+    }
+    this.pendingDisambiguation = null;
+  }
+  cancelPendingDisambiguation() {
+    const pending = this.pendingDisambiguation;
+    if (!pending) {
+      return;
+    }
+    this.pendingDisambiguation = null;
+    pending.controller.abort();
+  }
+  isPendingDisambiguationCurrent(pending) {
+    return this.pendingDisambiguation === pending;
+  }
+  sleepWithSignal(ms, signal) {
+    if (signal.aborted) {
+      return Promise.resolve(false);
+    }
+    return new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(true);
+      }, Math.max(0, ms));
+      const onAbort = () => {
+        clearTimeout(timeout);
+        signal.removeEventListener("abort", onAbort);
+        resolve(false);
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+  warnUnresolvedAmbiguity(sequence) {
+    const display = stringifyKeySequence(sequence, { preferDisplay: true });
+    this.notify.warnOnce(`unresolved-disambiguation:${display}`, "unresolved-disambiguation", { sequence: display }, `[Keymap] Ambiguous exact/prefix sequence "${display}" fell back to prefix handling because no disambiguation resolver resolved it`);
   }
   collectPendingCapturesFromRoot(activeLayers, startIndex, matchKeys, focused) {
     const captures = [];
@@ -2478,6 +3046,11 @@ class DispatchService {
     }
     return captures;
   }
+  collectPendingCapturesFromAdvanced(advancedCaptures, startIndex) {
+    return advancedCaptures.filter((candidate, candidateIndex) => {
+      return candidateIndex >= startIndex && candidate.node.children.size > 0;
+    });
+  }
   resolveEventMatchKeys(event) {
     const resolvers = this.state.dispatch.eventMatchResolvers.values();
     if (resolvers.length === 0) {
@@ -2500,7 +3073,7 @@ class DispatchService {
         continue;
       }
       for (const candidate of resolved) {
-        if (typeof candidate !== "symbol") {
+        if (typeof candidate !== "string") {
           this.notify.emitError("invalid-event-match-resolver-candidate", candidate, "[Keymap] Invalid event match resolver candidate:");
           continue;
         }
@@ -2578,7 +3151,7 @@ function resolveSingleEventMatchKeys(resolver, event, ctx, notify) {
   }
   if (resolved.length === 1) {
     const [candidate] = resolved;
-    if (typeof candidate !== "symbol") {
+    if (typeof candidate !== "string") {
       notify.emitError("invalid-event-match-resolver-candidate", candidate, "[Keymap] Invalid event match resolver candidate:");
       return [];
     }
@@ -2587,7 +3160,7 @@ function resolveSingleEventMatchKeys(resolver, event, ctx, notify) {
   const keys = [];
   const seen = new Set;
   for (const candidate of resolved) {
-    if (typeof candidate !== "symbol") {
+    if (typeof candidate !== "string") {
       notify.emitError("invalid-event-match-resolver-candidate", candidate, "[Keymap] Invalid event match resolver candidate:");
       continue;
     }
@@ -2749,14 +3322,13 @@ class EnvironmentService {
 
 // src/services/layers.ts
 var NOOP2 = () => {};
-function sortByPriorityAndOrder(items, options) {
-  const orderDirection = options?.order ?? "asc";
-  return [...items].sort((a, b) => {
-    const priorityDiff = b.priority - a.priority;
+function sortLayers(layers) {
+  return [...layers].sort((left, right) => {
+    const priorityDiff = right.priority - left.priority;
     if (priorityDiff !== 0) {
       return priorityDiff;
     }
-    return orderDirection === "desc" ? b.order - a.order : a.order - b.order;
+    return right.order - left.order;
   });
 }
 function createCommandLookup(commands) {
@@ -2805,7 +3377,6 @@ function buildLayerBindingAnalyses(root, compiledBindings) {
       preventDefault: binding.preventDefault,
       fallthrough: binding.fallthrough,
       sourceBinding: snapshotParsedBindingInput(binding.sourceBinding),
-      sourceScope: binding.sourceScope,
       sourceTarget: binding.sourceTarget,
       sourceLayerOrder: binding.sourceLayerOrder,
       sourceBindingIndex: binding.sourceBindingIndex,
@@ -2835,7 +3406,6 @@ class LayerService {
         this.notify.emitError("destroyed-layer-target", { target }, "Cannot register a keymap layer for a destroyed keymap target");
         return NOOP2;
       }
-      let scope;
       let bindingInputs;
       let requires;
       let matchers;
@@ -2844,10 +3414,9 @@ class LayerService {
       let compileFields;
       let commands;
       let commandLookup;
-      let indexTarget;
+      let targetMode;
       try {
-        scope = this.normalizeScope(layer);
-        indexTarget = layer.target ?? this.options.host.rootTarget;
+        targetMode = this.normalizeTargetMode(layer);
         bindingInputs = snapshotBindingInputs(layer.bindings ?? []);
         commands = !layer.commands || layer.commands.length === 0 ? [] : this.options.commands.normalizeCommands(layer.commands);
         commandLookup = createCommandLookup(commands);
@@ -2857,12 +3426,11 @@ class LayerService {
         return NOOP2;
       }
       const order = this.state.core.order++;
-      const compiledBindings = this.options.compiler.compileBindings(bindingInputs, this.state.environment.tokens, scope, target, order, compileFields);
+      const compiledBindings = this.options.compiler.compileBindings(bindingInputs, this.state.environment.tokens, target, order, compileFields);
       if (compiledBindings.bindings.length === 0 && !compiledBindings.hasTokenBindings && commands.length === 0) {
         return NOOP2;
       }
       this.runLayerAnalyzers({
-        scope,
         target,
         order,
         commandLookup,
@@ -2874,8 +3442,7 @@ class LayerService {
       const registeredLayer = {
         order,
         target,
-        indexTarget,
-        scope,
+        targetMode,
         priority: layer.priority ?? 0,
         requires,
         matchers,
@@ -2901,14 +3468,16 @@ class LayerService {
       if (registeredLayer.requires.length > 0 || registeredLayer.matchers.length > 0) {
         this.state.layers.layersWithConditions += 1;
       }
-      this.conditions.registerRuntimeMatchable(registeredLayer);
+      this.connectRuntimeMatchable(registeredLayer);
       for (const command of registeredLayer.commands) {
-        this.conditions.registerRuntimeMatchable(command);
+        this.connectRuntimeMatchable(command);
       }
       for (const binding of registeredLayer.compiledBindings) {
-        this.conditions.registerRuntimeMatchable(binding);
+        this.connectRuntimeMatchable(binding);
       }
       this.indexLayer(registeredLayer);
+      this.activation.invalidateActiveLayers();
+      this.activation.refreshActiveLayers();
       if (target) {
         const onTargetDestroy = () => {
           this.unregisterLayer(registeredLayer);
@@ -2931,37 +3500,41 @@ class LayerService {
         if (!layer.hasTokenBindings) {
           continue;
         }
-        nextCompilations.set(layer, this.options.compiler.compileBindings(layer.bindingInputs, nextTokens, layer.scope, layer.target, layer.order, layer.compileFields));
+        nextCompilations.set(layer, this.compileLayerBindings(layer, nextTokens));
       }
       this.state.environment.tokens = nextTokens;
       let shouldClearPending = false;
       for (const [layer, compilation] of nextCompilations) {
-        this.runLayerAnalyzers({
-          scope: layer.scope,
-          target: layer.target,
-          order: layer.order,
-          commandLookup: layer.commandLookup,
-          bindingInputs: layer.bindingInputs,
-          compiledBindings: compilation.bindings,
-          root: compilation.root,
-          hasTokenBindings: compilation.hasTokenBindings
-        });
-        for (const binding of layer.compiledBindings) {
-          this.conditions.unregisterRuntimeMatchable(binding);
+        if (this.applyCompiledBindings(layer, compilation)) {
+          shouldClearPending = true;
         }
-        layer.root = compilation.root;
-        layer.compiledBindings = compilation.bindings;
-        for (const binding of layer.compiledBindings) {
-          this.conditions.registerRuntimeMatchable(binding);
+      }
+      if (shouldClearPending) {
+        this.activation.setPendingSequence(null);
+      }
+      if (nextCompilations.size > 0) {
+        this.notify.queueStateChange();
+      }
+    });
+  }
+  recompileBindings() {
+    this.notify.runWithStateChangeBatch(() => {
+      let recompiledLayers = 0;
+      let shouldClearPending = false;
+      for (const layer of this.state.layers.layers) {
+        if (layer.bindingInputs.length === 0) {
+          continue;
         }
-        if (this.state.projection.pendingSequence?.captures.some((capture) => capture.layer === layer)) {
+        const compilation = this.compileLayerBindings(layer, this.state.environment.tokens);
+        if (this.applyCompiledBindings(layer, compilation)) {
           shouldClearPending = true;
         }
+        recompiledLayers += 1;
       }
       if (shouldClearPending) {
         this.activation.setPendingSequence(null);
       }
-      if (nextCompilations.size > 0) {
+      if (recompiledLayers > 0) {
         this.notify.queueStateChange();
       }
     });
@@ -2975,17 +3548,27 @@ class LayerService {
   clearLayerAnalyzers() {
     this.state.layers.layerAnalyzers.clear();
   }
-  normalizeScope(layer) {
-    if (layer.scope) {
-      if (layer.scope !== "global" && !layer.target) {
-        throw new Error(`Keymap scope "${layer.scope}" requires a target`);
+  cleanup() {
+    for (const layer of this.state.layers.layers) {
+      this.disconnectRuntimeMatchable(layer);
+      for (const command of layer.commands) {
+        this.disconnectRuntimeMatchable(command);
+      }
+      for (const binding of layer.compiledBindings) {
+        this.disconnectRuntimeMatchable(binding);
       }
-      return layer.scope;
+      layer.offTargetDestroy?.();
+      layer.offTargetDestroy = undefined;
     }
-    if (layer.target) {
-      return "focus-within";
+  }
+  normalizeTargetMode(layer) {
+    if (layer.targetMode) {
+      if (!layer.target) {
+        throw new Error(`Keymap targetMode "${layer.targetMode}" requires a target`);
+      }
+      return layer.targetMode;
     }
-    return "global";
+    return layer.target ? "focus-within" : undefined;
   }
   runLayerAnalyzers(options) {
     const analyzers = this.state.layers.layerAnalyzers.values();
@@ -2994,7 +3577,6 @@ class LayerService {
     }
     const bindings = buildLayerBindingAnalyses(options.root, options.compiledBindings);
     const ctx = {
-      scope: options.scope,
       target: options.target,
       order: options.order,
       bindingInputs: options.bindingInputs,
@@ -3062,41 +3644,38 @@ class LayerService {
       compileFields: Object.keys(compileFields).length > 0 ? Object.freeze(compileFields) : undefined
     };
   }
-  getOrCreateTargetBucket(target) {
-    const existing = this.state.layers.targetLayers.get(target);
-    if (existing) {
-      return existing;
+  compileLayerBindings(layer, tokens) {
+    return this.options.compiler.compileBindings(layer.bindingInputs, tokens, layer.target, layer.order, layer.compileFields);
+  }
+  applyCompiledBindings(layer, compilation) {
+    this.runLayerAnalyzers({
+      target: layer.target,
+      order: layer.order,
+      commandLookup: layer.commandLookup,
+      bindingInputs: layer.bindingInputs,
+      compiledBindings: compilation.bindings,
+      root: compilation.root,
+      hasTokenBindings: compilation.hasTokenBindings
+    });
+    for (const binding of layer.compiledBindings) {
+      this.disconnectRuntimeMatchable(binding);
     }
-    const bucket = {
-      focusLayers: [],
-      focusWithinLayers: []
-    };
-    this.state.layers.targetLayers.set(target, bucket);
-    return bucket;
+    layer.root = compilation.root;
+    layer.compiledBindings = compilation.bindings;
+    layer.hasUnkeyedBindings = compilation.bindings.some((binding) => binding.hasUnkeyedMatchers);
+    layer.hasTokenBindings = compilation.hasTokenBindings;
+    for (const binding of layer.compiledBindings) {
+      this.connectRuntimeMatchable(binding);
+    }
+    return this.state.projection.pendingSequence?.captures.some((capture) => capture.layer === layer) ?? false;
   }
   indexLayer(layer) {
-    const bucket = this.getOrCreateTargetBucket(layer.indexTarget);
-    if (layer.scope === "focus") {
-      bucket.focusLayers = sortByPriorityAndOrder([...bucket.focusLayers, layer], { order: "desc" });
-    } else {
-      bucket.focusWithinLayers = sortByPriorityAndOrder([...bucket.focusWithinLayers, layer], { order: "desc" });
-    }
-    layer.bucket = bucket;
+    this.state.layers.sortedLayers = sortLayers([...this.state.layers.sortedLayers, layer]);
+    this.state.layers.activeLayersVersion += 1;
   }
   removeLayerFromIndex(layer) {
-    const bucket = layer.bucket;
-    if (!bucket) {
-      return;
-    }
-    if (layer.scope === "focus") {
-      bucket.focusLayers = bucket.focusLayers.filter((candidate) => candidate !== layer);
-    } else {
-      bucket.focusWithinLayers = bucket.focusWithinLayers.filter((candidate) => candidate !== layer);
-    }
-    if (bucket.focusLayers.length === 0 && bucket.focusWithinLayers.length === 0) {
-      this.state.layers.targetLayers.delete(layer.indexTarget);
-    }
-    layer.bucket = undefined;
+    this.state.layers.sortedLayers = this.state.layers.sortedLayers.filter((candidate) => candidate !== layer);
+    this.state.layers.activeLayersVersion += 1;
   }
   unregisterLayer(layer) {
     this.notify.runWithStateChangeBatch(() => {
@@ -3111,14 +3690,16 @@ class LayerService {
         this.state.commands.commandMetadataVersion += 1;
         removeRegisteredCommandNames(this.state.commands.registeredNames, layer.commands);
       }
-      this.conditions.unregisterRuntimeMatchable(layer);
+      this.disconnectRuntimeMatchable(layer);
       for (const command of layer.commands) {
-        this.conditions.unregisterRuntimeMatchable(command);
+        this.disconnectRuntimeMatchable(command);
       }
       for (const binding of layer.compiledBindings) {
-        this.conditions.unregisterRuntimeMatchable(binding);
+        this.disconnectRuntimeMatchable(binding);
       }
       this.removeLayerFromIndex(layer);
+      this.activation.invalidateActiveLayers();
+      this.activation.refreshActiveLayers();
       layer.offTargetDestroy?.();
       layer.offTargetDestroy = undefined;
       if (this.state.projection.pendingSequence?.captures.some((capture) => capture.layer === layer)) {
@@ -3129,6 +3710,49 @@ class LayerService {
       this.notify.queueStateChange();
     });
   }
+  connectRuntimeMatchable(target) {
+    this.attachReactiveMatchers(target);
+    this.conditions.indexRuntimeMatchable(target);
+  }
+  disconnectRuntimeMatchable(target) {
+    this.detachReactiveMatchers(target);
+    this.conditions.unindexRuntimeMatchable(target);
+  }
+  attachReactiveMatchers(target) {
+    for (const matcher of target.matchers) {
+      if (!matcher.subscribe) {
+        continue;
+      }
+      try {
+        matcher.dispose = matcher.subscribe(() => {
+          target.matchCacheDirty = true;
+          if (!this.activation.hasPendingSequenceState()) {
+            this.notify.queueStateChange();
+            return;
+          }
+          this.notify.runWithStateChangeBatch(() => {
+            this.activation.revalidatePendingSequenceIfNeeded();
+            this.notify.queueStateChange();
+          });
+        });
+      } catch (error) {
+        this.notify.emitError("reactive-matcher-subscribe-error", error, getErrorMessage(error, `Failed to subscribe to reactive matcher from ${matcher.source}`));
+      }
+    }
+  }
+  detachReactiveMatchers(target) {
+    for (const matcher of target.matchers) {
+      if (!matcher.dispose) {
+        continue;
+      }
+      try {
+        matcher.dispose();
+      } catch (error) {
+        this.notify.emitError("reactive-matcher-dispose-error", error, getErrorMessage(error, `Failed to dispose reactive matcher from ${matcher.source}`));
+      }
+      matcher.dispose = undefined;
+    }
+  }
 }
 
 // src/lib/emitter.ts
@@ -3195,6 +3819,8 @@ class Emitter {
 }
 
 // src/services/notify.ts
+var MAX_STATE_CHANGE_FLUSH_ITERATIONS = 1000;
+
 class NotificationService {
   state;
   events;
@@ -3227,10 +3853,11 @@ class NotificationService {
   }
   emitWarning(code, warning, message) {
     if (!this.events.has("warning")) {
+      const consoleMessage = `[${code}] ${message}`;
       if (warning instanceof Error) {
-        console.warn(message, warning);
+        console.warn(consoleMessage, warning);
       } else {
-        console.warn(message);
+        console.warn(consoleMessage);
       }
       return;
     }
@@ -3238,10 +3865,11 @@ class NotificationService {
   }
   emitError(code, error, message) {
     if (!this.events.has("error")) {
+      const consoleMessage = `[${code}] ${message}`;
       if (error instanceof Error) {
-        console.error(message, error);
+        console.error(consoleMessage, error);
       } else {
-        console.error(message);
+        console.error(consoleMessage);
       }
       return;
     }
@@ -3270,7 +3898,14 @@ class NotificationService {
     }
     this.state.notify.flushingStateChange = true;
     try {
+      let iterations = 0;
       while (this.state.notify.stateChangePending && this.state.notify.stateChangeDepth === 0) {
+        if (iterations >= MAX_STATE_CHANGE_FLUSH_ITERATIONS) {
+          this.state.notify.stateChangePending = false;
+          this.emitError("state-change-feedback-loop", { iterations: MAX_STATE_CHANGE_FLUSH_ITERATIONS }, `[Keymap] Possible infinite state listener feedback loop detected after ${MAX_STATE_CHANGE_FLUSH_ITERATIONS} iterations; pending state notifications were dropped`);
+          break;
+        }
+        iterations += 1;
         this.state.notify.stateChangePending = false;
         this.hooks.emit("state");
       }
@@ -3416,12 +4051,17 @@ function createKeymapState() {
     },
     dispatch: {
       eventMatchResolvers: new OrderedRegistry,
+      disambiguationResolvers: new OrderedRegistry,
       keyHooks: new PriorityRegistry,
       rawHooks: new PriorityRegistry
     },
     layers: {
       layers: new Set,
-      targetLayers: new WeakMap,
+      sortedLayers: [],
+      activeLayersVersion: 0,
+      activeLayersCacheVersion: -1,
+      activeLayersCacheFocused: undefined,
+      activeLayersCache: [],
       layersWithConditions: 0,
       layersWithCommands: 0,
       layerAnalyzers: new OrderedRegistry
@@ -3432,6 +4072,8 @@ function createKeymapState() {
       commandResolvers: new OrderedRegistry,
       activeCommandViewVersion: -1,
       activeCommandView: undefined,
+      registeredCommandViewVersion: -1,
+      registeredCommandView: undefined,
       registeredCommandEntriesCacheVersion: -1,
       registeredCommandEntriesCache: []
     },
@@ -3509,7 +4151,11 @@ class Keymap {
         this.activation.ensureValidPendingSequence();
       }
     });
-    this.activation = new ActivationService(this.state, this.host, this.hooks, this.notify, this.conditions, this.catalog);
+    this.activation = new ActivationService(this.state, this.host, this.hooks, this.notify, this.conditions, this.catalog, {
+      onPendingSequenceChanged: (previous, next) => {
+        this.dispatch?.handlePendingSequenceChange(previous, next);
+      }
+    });
     this.runtime = new RuntimeService(this.state, this.notify, this.conditions, this.activation);
     this.executor = new CommandExecutorService(this.notify, this.runtime, this.activation, this.catalog, {
       keymap: this,
@@ -3532,7 +4178,7 @@ class Keymap {
       }
     });
     this.environment = new EnvironmentService(this.state, this.notify, this.compiler, this.layers);
-    this.dispatch = new DispatchService(this.state, this.notify, this.runtime, this.activation, this.conditions, this.executor, this.compiler);
+    this.dispatch = new DispatchService(this.state, this.notify, this.runtime, this.activation, this.conditions, this.executor, this.compiler, this.catalog, this.layers);
     this.keypressListener = (event) => {
       this.dispatch.handleKeyEvent(event, false);
     };
@@ -3567,18 +4213,7 @@ class Keymap {
       resource.dispose();
     }
     this.resources.clear();
-    for (const layer of this.state.layers.layers) {
-      this.conditions.unregisterRuntimeMatchable(layer);
-      for (const command of layer.commands) {
-        this.conditions.unregisterRuntimeMatchable(command);
-      }
-      for (const binding of layer.compiledBindings) {
-        this.conditions.unregisterRuntimeMatchable(binding);
-      }
-      layer.offTargetDestroy?.();
-      layer.offTargetDestroy = undefined;
-      layer.bucket = undefined;
-    }
+    this.layers.cleanup();
     for (const cleanupListener of this.cleanupListeners.splice(0)) {
       cleanupListener();
     }
@@ -3646,6 +4281,9 @@ class Keymap {
   runCommand(cmd, options) {
     return this.executor.runCommand(cmd, options);
   }
+  dispatchCommand(cmd, options) {
+    return this.executor.dispatchCommand(cmd, options);
+  }
   on(name, fn) {
     if (name === "warning") {
       return this.events.hook(name, fn);
@@ -3730,9 +4368,20 @@ class Keymap {
   clearEventMatchResolvers() {
     this.dispatch.clearEventMatchResolvers();
   }
+  prependDisambiguationResolver(resolver) {
+    return this.dispatch.prependDisambiguationResolver(resolver);
+  }
+  appendDisambiguationResolver(resolver) {
+    return this.dispatch.appendDisambiguationResolver(resolver);
+  }
+  clearDisambiguationResolvers() {
+    this.dispatch.clearDisambiguationResolvers();
+  }
   handleFocusedTargetChange(_focused) {
     this.notify.runWithStateChangeBatch(() => {
       this.activation.setPendingSequence(null);
+      this.activation.invalidateActiveLayers();
+      this.activation.refreshActiveLayers(_focused);
       this.notify.queueStateChange();
     });
   }