@weasel-js/routing 1.11.1 → 1.13.0-rc.0

package/dist/{chunk-KLBH7VFF.js → chunk-CRF3ROBB.js}

@@ -1,6 +1,6 @@
 import { isDev } from '@weasel-js/react';
 import { createEmitter } from '@weasel-js/registry';
-import { RESERVED_ID_PREFIXES, RESERVED_ID_NAMES, isApplePlatform, routeGestureForSpecKind, getGestureDescriptor, formatRoute, parseTargetSpec, matchSpec, canonicalModifiers, UNKNOWN_MIME, specificity, VALID_MOD_NAMES, stylusOf } from '@weasel-js/gestures';
+import { RESERVED_ID_PREFIXES, RESERVED_ID_NAMES, isApplePlatform, bindingSpec, routeGestureForSpecKind, getGestureDescriptor, formatRoute, parseTargetSpec, matchSpec, canonicalModifiers, UNKNOWN_MIME, specificity, formatShortcut, VALID_MOD_NAMES, stylusOf } from '@weasel-js/gestures';
 export { GESTURE_DESCRIPTORS, LONG_PRESS_MS, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, activatesFocusedControl, canonicalModifiers, collapseShiftPairs, describeRoute, describeRouteParts, focusedControlOwnsKey, formatPhaseAtom, formatRoute, getGestureDescriptor, isEditableTarget, isKnownGestureName, matchKey, matchModifiers, matchPhase, matchSpec, matchTarget, parseRoute, routeGestureForSpecKind, specKindForRouteGesture, specificity } from '@weasel-js/gestures';
 import { activeModeOf, NORMAL, DEFAULT_MODES, capabilitiesAllowed } from '@weasel-js/modes';
 import { resolveCursor } from '@weasel-js/cursor';
@@ -466,6 +466,165 @@ function tuneAction(action, tunings) {
   for (const t of tunings) out = tuneOnce(out, t);
   return out;
 }
+var NO_OVERRIDES = /* @__PURE__ */ new Map();
+function bindingId(b, ownerId, index) {
+  return b.opts?.id ?? (ownerId === null ? `${b.actionId}@${index}` : `${ownerId}#${index}`);
+}
+function resolveBindingOverrides(maps) {
+  if (maps.length === 0) return NO_OVERRIDES;
+  const out = /* @__PURE__ */ new Map();
+  for (const map of maps) {
+    for (const [id, input] of Object.entries(map)) {
+      try {
+        out.set(id, bindingSpec(input));
+      } catch (err) {
+        console.warn(`weasel: binding override "${id}" is not a route: ${err.message}`);
+      }
+    }
+  }
+  return out;
+}
+function overridden(b, id, overrides) {
+  if (!overrides.has(id)) return b;
+  const spec = overrides.get(id);
+  return spec === null ? null : { ...b, spec };
+}
+function overriddenBindings(bindings, ownerId, overrides = NO_OVERRIDES) {
+  const out = [];
+  bindings.forEach((b, i) => {
+    const next = overridden(b, bindingId(b, ownerId, i), overrides);
+    if (next) out.push(next);
+  });
+  return out;
+}
+function overrideActionBindings(action, overrides) {
+  if (overrides.size === 0 || action.defaultBinding === void 0) return action;
+  const declared = actionBindings(action);
+  if (!declared.some((b, i) => overrides.has(bindingId(b, null, i)))) return action;
+  const kept = [];
+  declared.forEach((b, i) => {
+    const id = bindingId(b, null, i);
+    const next = overridden(b, id, overrides);
+    if (next) kept.push({ spec: next.spec, opts: { ...next.opts, id } });
+  });
+  return { ...action, defaultBinding: kept };
+}
+
+// src/interactions/dispatcher/inputFacts.ts
+function modifierStateOf(e) {
+  return { alt: e.altKey, ctrl: e.ctrlKey, meta: e.metaKey, shift: e.shiftKey };
+}
+function worldPointOf(event) {
+  switch (event.kind) {
+    case "pointerdown":
+    case "hover":
+    case "longpress":
+    case "click":
+    case "doubleclick":
+    case "contextmenu":
+      return event.x !== void 0 && event.y !== void 0 ? { x: event.x, y: event.y } : void 0;
+    case "carry":
+      return { x: event.x, y: event.y };
+    default:
+      return void 0;
+  }
+}
+function carriedBy(event) {
+  if (event.kind === "carry") return { items: [], carry: { type: event.type, value: event.value } };
+  return event.kind === "drop" || event.kind === "paste" ? { items: event.items } : void 0;
+}
+function immediateParams(event, resolved) {
+  switch (event.kind) {
+    case "wheel":
+      return {
+        deltaX: event.deltaX,
+        deltaY: event.deltaY,
+        clientX: event.clientX,
+        clientY: event.clientY,
+        affordance: event.affordance,
+        ...resolved
+      };
+    case "pinch":
+      return {
+        scale: event.scale,
+        rotation: event.rotation,
+        clientX: event.clientX,
+        clientY: event.clientY,
+        affordance: event.affordance,
+        ...resolved
+      };
+    case "click":
+    case "doubleclick":
+      return {
+        worldX: event.x,
+        worldY: event.y,
+        affordance: event.affordance,
+        // The press point too: an action that places geometry at the click wants it.
+        ...event.kind === "click" ? { pressX: event.pressX, pressY: event.pressY } : {},
+        mods: modifierStateOf(event),
+        ...resolved
+      };
+    // Only a `stage: 'press'` pointerdown reaches an immediate invoker: the
+    // buffered copy matches `drag` specs, which are ongoing.
+    case "contextmenu":
+      return {
+        worldX: event.x,
+        worldY: event.y,
+        clientX: event.clientX,
+        clientY: event.clientY,
+        affordance: event.affordance,
+        bodyTarget: event.bodyTarget,
+        bodyKind: event.bodyKind,
+        mods: modifierStateOf(event),
+        ...resolved
+      };
+    case "pointerdown":
+    case "longpress":
+      return {
+        worldX: event.x,
+        worldY: event.y,
+        affordance: event.affordance,
+        bodyTarget: event.bodyTarget,
+        mods: modifierStateOf(event),
+        ...resolved
+      };
+    case "hover":
+      return {
+        worldX: event.x,
+        worldY: event.y,
+        clientX: event.clientX,
+        clientY: event.clientY,
+        affordance: event.affordance,
+        bodyTarget: event.bodyTarget,
+        mods: modifierStateOf(event),
+        held: event.held === true,
+        ...resolved
+      };
+    case "carry":
+      return {
+        worldX: event.x,
+        worldY: event.y,
+        clientX: event.clientX,
+        clientY: event.clientY,
+        carry: { type: event.type, value: event.value },
+        affordance: event.affordance,
+        bodyTarget: event.bodyTarget,
+        bodyKind: event.bodyKind,
+        mods: modifierStateOf(event),
+        ...resolved
+      };
+    case "drop":
+    case "paste":
+      return {
+        items: event.items,
+        via: event.kind,
+        ...event.kind === "drop" && event.x !== void 0 ? { worldX: event.x, worldY: event.y } : {},
+        ...resolved
+      };
+    default:
+      return resolved;
+  }
+}
 
 // src/interactions/actions/toolOffhand.ts
 var TOOL_OFFHAND_ID = "tool.offhand";
@@ -488,7 +647,7 @@ function offhandKeyFor(trigger) {
 function buildToolOffhandBindings(specs) {
   return specs.map(({ toolId, key }) => ({
     spec: { ...heldKeySpec(key), phase: BETWEEN_GESTURES },
-    opts: { params: { toolId } }
+    opts: { id: `${TOOL_OFFHAND_ID}.${toolId}`, params: { toolId } }
   }));
 }
 var BETWEEN_GESTURES = [{ channel: "*", phase: "initial" }];
@@ -996,17 +1155,18 @@ function gestureIdFor(event) {
 function liveScope(id, eligibility, state) {
   const tags = eligibility.capabilities;
   if (tags && state.allows && !state.allows(tags)) return null;
+  if (eligibility.keymap) return state.openKeymap === id ? "hotkey" : null;
   if (state.engagedIds?.has(id)) return "hotkey";
   if (eligibility.focus && state.focusedId === id) return "active";
   if (eligibility.always || eligibility.claimed) return "ambient";
   return null;
 }
-function scopeBindings(entries, state) {
+function scopeBindings(entries, state, overrides = NO_OVERRIDES) {
   const out = [];
   for (const entry of entries) {
     const scope = liveScope(entry.id, entry.eligibility ?? {}, state);
     if (scope === null) continue;
-    for (const binding of entry.bindings ?? []) {
+    for (const binding of overriddenBindings(entry.bindings ?? [], entry.id, overrides)) {
       out.push({ binding, scope, ownerId: entry.id });
     }
   }
@@ -1028,6 +1188,7 @@ function assembleEntries(entries, inputs) {
     state: {
       focusedId: inputs.focusedId,
       engagedIds: new Set(inputs.hotkeyStack),
+      ...inputs.openKeymap ? { openKeymap: inputs.openKeymap } : {},
       ...allowed ? { allows: (tags) => capabilitiesAllowed(allowed, tags) } : {}
     }
   };
@@ -1078,122 +1239,6 @@ function createDispatchTrace(limit, dev) {
   };
 }
 
-// src/interactions/dispatcher/inputFacts.ts
-function modifiersOf(e) {
-  return { alt: e.altKey, ctrl: e.ctrlKey, meta: e.metaKey, shift: e.shiftKey };
-}
-function worldPointOf(event) {
-  switch (event.kind) {
-    case "pointerdown":
-    case "hover":
-    case "longpress":
-    case "click":
-    case "doubleclick":
-    case "contextmenu":
-      return event.x !== void 0 && event.y !== void 0 ? { x: event.x, y: event.y } : void 0;
-    case "carry":
-      return { x: event.x, y: event.y };
-    default:
-      return void 0;
-  }
-}
-function carriedBy(event) {
-  if (event.kind === "carry") return { items: [], carry: { type: event.type, value: event.value } };
-  return event.kind === "drop" || event.kind === "paste" ? { items: event.items } : void 0;
-}
-function immediateParams(event, resolved) {
-  switch (event.kind) {
-    case "wheel":
-      return {
-        deltaX: event.deltaX,
-        deltaY: event.deltaY,
-        clientX: event.clientX,
-        clientY: event.clientY,
-        affordance: event.affordance,
-        ...resolved
-      };
-    case "pinch":
-      return {
-        scale: event.scale,
-        rotation: event.rotation,
-        clientX: event.clientX,
-        clientY: event.clientY,
-        affordance: event.affordance,
-        ...resolved
-      };
-    case "click":
-    case "doubleclick":
-      return {
-        worldX: event.x,
-        worldY: event.y,
-        affordance: event.affordance,
-        // The press point too: an action that places geometry at the click wants it.
-        ...event.kind === "click" ? { pressX: event.pressX, pressY: event.pressY } : {},
-        mods: modifiersOf(event),
-        ...resolved
-      };
-    // Only a `stage: 'press'` pointerdown reaches an immediate invoker: the
-    // buffered copy matches `drag` specs, which are ongoing.
-    case "contextmenu":
-      return {
-        worldX: event.x,
-        worldY: event.y,
-        clientX: event.clientX,
-        clientY: event.clientY,
-        affordance: event.affordance,
-        bodyTarget: event.bodyTarget,
-        bodyKind: event.bodyKind,
-        mods: modifiersOf(event),
-        ...resolved
-      };
-    case "pointerdown":
-    case "longpress":
-      return {
-        worldX: event.x,
-        worldY: event.y,
-        affordance: event.affordance,
-        bodyTarget: event.bodyTarget,
-        mods: modifiersOf(event),
-        ...resolved
-      };
-    case "hover":
-      return {
-        worldX: event.x,
-        worldY: event.y,
-        clientX: event.clientX,
-        clientY: event.clientY,
-        affordance: event.affordance,
-        bodyTarget: event.bodyTarget,
-        mods: modifiersOf(event),
-        held: event.held === true,
-        ...resolved
-      };
-    case "carry":
-      return {
-        worldX: event.x,
-        worldY: event.y,
-        clientX: event.clientX,
-        clientY: event.clientY,
-        carry: { type: event.type, value: event.value },
-        affordance: event.affordance,
-        bodyTarget: event.bodyTarget,
-        bodyKind: event.bodyKind,
-        mods: modifiersOf(event),
-        ...resolved
-      };
-    case "drop":
-    case "paste":
-      return {
-        items: event.items,
-        via: event.kind,
-        ...event.kind === "drop" && event.x !== void 0 ? { worldX: event.x, worldY: event.y } : {},
-        ...resolved
-      };
-    default:
-      return resolved;
-  }
-}
-
 // src/interactions/dispatcher/ranking.ts
 function liveInView(binding, view) {
   const views = binding.opts?.views;
@@ -1313,7 +1358,7 @@ function buildDispatchRecord(r, walked, event, ctx, predicted, outcome) {
     input: {
       eventKind: event.kind,
       ...eventKey !== void 0 ? { key: eventKey } : {},
-      modifiers: modifiersOf(event),
+      modifiers: modifierStateOf(event),
       viewId: view,
       ...world !== void 0 ? { world } : {},
       ...r.ruleCtx !== void 0 ? { mode: r.ruleCtx.mode } : {}
@@ -1754,19 +1799,22 @@ function createUiOngoing(inFlight, notify, getAction) {
 // src/interactions/dispatcher/walk.ts
 function assembleScopedBindings(ctx) {
   const allowedCapabilities = ctx.getRuleCtx?.()?.allowedCapabilities;
+  const openKeymap = ctx.keymapPass === "none" ? null : ctx.keymaps?.innermost()?.id ?? null;
   const { ordered, state } = assembleEntries(ctx.entriesById.values(), {
     focusedId: ctx.activeToolId,
     hotkeyStack: ctx.hotkeyStack,
-    ...allowedCapabilities ? { allowedCapabilities } : {}
+    ...allowedCapabilities ? { allowedCapabilities } : {},
+    ...openKeymap ? { openKeymap } : {}
   });
   const view = ctx.viewId ?? null;
   const live = (b) => liveInView(b, view) && liveForKeys(b, ctx.keyReach);
-  const result = scopeBindings(ordered, state).filter((sb) => live(sb.binding));
+  const overrides = ctx.bindingOverrides?.() ?? NO_OVERRIDES;
+  const result = scopeBindings(ordered, state, overrides).filter((sb) => live(sb.binding));
+  if (ctx.keymapPass === "only") return result.filter((sb) => sb.ownerId === openKeymap);
   for (const action of ctx.actions.list()) {
     const targetScope = action.scope === "hotkey" ? "hotkey" : "ambient";
     for (const binding of actionBindings(action)) {
-      if (!live(binding)) continue;
-      result.push({ binding, scope: targetScope, ownerId: null });
+      if (live(binding)) result.push({ binding, scope: targetScope, ownerId: null });
     }
   }
   return result;
@@ -1939,6 +1987,68 @@ function explain(event, ctx, engaged, opts) {
   const walked = walk(r, event, ctx, null, opts?.evaluateShadowed ?? false);
   return buildDispatchRecord(r, walked, event, ctx, true, walked.winner ? "handled" : "unhandled");
 }
+var MODIFIER_KEYS2 = /* @__PURE__ */ new Set(["Shift", "Control", "Alt", "Meta", "AltGraph", "CapsLock"]);
+var STROKES = /* @__PURE__ */ new Set([
+  "click",
+  "doubleclick",
+  "longpress",
+  "contextmenu",
+  "multitouch",
+  "multitouchtap"
+]);
+var isPlainEscape = (e) => e.kind === "key" && e.key === "Escape" && !e.altKey && !e.ctrlKey && !e.metaKey && !e.shiftKey;
+var SETTLES_INTO = ["click", "doubleclick", "longpress", "contextmenu"];
+function stillLive(id, ctx) {
+  const entry = ctx.entriesById.get(id);
+  if (!entry) return false;
+  const allowed = ctx.getRuleCtx?.()?.allowedCapabilities;
+  const allows = allowed ? (tags) => capabilitiesAllowed(allowed, tags) : void 0;
+  return liveScope(id, entry.eligibility, { focusedId: null, openKeymap: id, ...allows ? { allows } : {} }) !== null;
+}
+function routeThroughKeymap(event, ctx, passes) {
+  const stack = ctx.keymaps;
+  const open = stack?.innermost();
+  if (!stack || !open || event.kind === "hover") return void 0;
+  const isKey = event.kind === "key" || event.kind === "key-held";
+  if (isKey && ctx.keyReach && !ctx.keyReach.held) return void 0;
+  if (!stillLive(open.id, ctx)) {
+    stack.closeAll();
+    return void 0;
+  }
+  const verdict = stack.verdict();
+  if (verdict === "taken") return "unhandled";
+  if (verdict === "cascaded") return passes.run("none", event);
+  if (isPlainEscape(event)) {
+    stack.closeInnermost();
+    return "handled";
+  }
+  if (passes.run("only", event) === "handled") {
+    stack.inputSeen();
+    return "handled";
+  }
+  if (isKey) {
+    if (event.kind === "key" && passes.binds({ ...event, kind: "key-held", phase: "down" })) return "unhandled";
+    if (MODIFIER_KEYS2.has(event.key) || event.ctrlKey || event.metaKey || event.key === "Tab") {
+      return passes.run("none", event);
+    }
+    const entry = ctx.entriesById.get(open.id)?.eligibility.keymap;
+    const own = typeof entry === "object" ? entry.unbound : void 0;
+    if ((own ?? ctx.leaderUnbound ?? "modal") === "modal") {
+      stack.swallowed();
+      return "handled";
+    }
+    stack.cascaded();
+    return passes.run("none", event);
+  }
+  if (event.kind === "pointerdown" && SETTLES_INTO.some((kind) => passes.binds({ ...event, kind }))) {
+    return "unhandled";
+  }
+  const outcome = passes.run("none", event);
+  const stroke = STROKES.has(event.kind) || event.kind === "pointerdown" && outcome === "handled";
+  const firstOfDouble = event.kind === "click" && passes.binds({ ...event, kind: "doubleclick" });
+  if (stroke && !firstOfDouble) stack.inputSeen();
+  return outcome;
+}
 
 // src/interactions/dispatcher/dispatcher.ts
 function createDispatcher(opts) {
@@ -1961,6 +2071,12 @@ function createDispatcher(opts) {
     const pumped = pumpGesture(run, event);
     if (pumped !== void 0) return pumped;
     if (event.kind === "hover") return hover(event, ctx);
+    return routeThroughKeymap(event, ctx, {
+      run: (pass, ev) => route(ev, { ...ctx, keymapPass: pass }),
+      binds: (ev) => rank(ev, { ...ctx, keymapPass: "only" }, inFlight.engagedOwners(), false).ordered.length > 0
+    }) ?? route(event, ctx);
+  }
+  function route(event, ctx) {
     const trace = ctx.trace?.recording() ? ctx.trace : null;
     const r = rank(event, ctx, inFlight.engagedOwners(), trace !== null);
     const walked = walk(r, event, ctx, invoking(event), false);
@@ -2181,6 +2297,229 @@ function startCarry(origin, down, payload, cb = {}) {
     cancel: () => session.cancel()
   };
 }
+var KEYMAP_HOLD = "hold";
+function createKeymapStack() {
+  let levels = [];
+  let version = 0;
+  const changed = createEmitter();
+  let depth = 0;
+  let serial = 0;
+  let pending = [];
+  let verdict = null;
+  let snapshot = [];
+  const notify = () => {
+    snapshot = levels.map(({ openedIn: _, ...rest }) => Object.freeze({ ...rest }));
+    version++;
+    changed.emit();
+  };
+  const later = (op) => {
+    if (depth > 0) pending.push(op);
+    else op();
+  };
+  const settle = () => {
+    const before = levels;
+    const opened = (l) => l.openedIn === serial && depth > 0;
+    if (levels.some(opened)) return;
+    for (const l of levels) if (l.heldBy !== void 0) l.usedWhileHeld = true;
+    while (levels.length > 0 && levels.at(-1).heldBy === void 0) levels = levels.slice(0, -1);
+    if (levels !== before) notify();
+  };
+  return {
+    open: () => snapshot,
+    innermost: () => snapshot.at(-1) ?? null,
+    push: (id, label, opts) => {
+      const heldBy = opts?.heldBy;
+      const bindings = opts?.bindings ?? [];
+      const open = levels.findIndex((l) => l.id === id);
+      if (open !== -1) levels = levels.slice(0, open);
+      levels = [...levels, { id, label, bindings, ...heldBy !== void 0 ? { heldBy } : {}, usedWhileHeld: false, openedIn: serial }];
+      if (depth > 0) verdict = "taken";
+      notify();
+    },
+    holdOpened: (heldBy) => {
+      let held = false;
+      levels = levels.map((l) => {
+        if (l.openedIn !== serial || l.heldBy !== void 0) return l;
+        held = true;
+        return { ...l, heldBy };
+      });
+      if (held) notify();
+      return held;
+    },
+    release: (heldBy) => {
+      const i = levels.findIndex((l) => l.heldBy === heldBy);
+      if (i === -1) return;
+      const level = levels[i];
+      if (level.usedWhileHeld) {
+        levels = levels.slice(0, i);
+        while (levels.length > 0 && levels.at(-1).heldBy === void 0) levels = levels.slice(0, -1);
+      } else levels = levels.map((l) => l === level ? { ...l, heldBy: void 0 } : l).map(dropUndefinedHeld);
+      notify();
+    },
+    closeInnermost: () => {
+      if (depth > 0) verdict = "taken";
+      later(() => {
+        if (levels.length === 0) return;
+        levels = levels.slice(0, -1);
+        notify();
+      });
+    },
+    inputSeen: () => {
+      if (depth > 0) verdict ??= "taken";
+      later(settle);
+    },
+    cascaded: () => {
+      if (depth > 0) verdict = "cascaded";
+      later(settle);
+    },
+    swallowed: () => {
+      for (const l of levels) if (l.heldBy !== void 0) l.usedWhileHeld = true;
+    },
+    verdict: () => verdict,
+    closeAll: () => {
+      pending = [];
+      if (levels.length === 0) return;
+      levels = [];
+      notify();
+    },
+    batch: (fn) => {
+      if (depth === 0) {
+        serial++;
+        verdict = null;
+      }
+      depth++;
+      try {
+        return fn();
+      } finally {
+        depth--;
+        if (depth === 0) {
+          const ops = pending;
+          pending = [];
+          depth = 1;
+          try {
+            for (const op of ops) op();
+          } finally {
+            depth = 0;
+          }
+          verdict = null;
+        }
+      }
+    },
+    subscribe: changed.subscribe,
+    getVersion: () => version
+  };
+}
+function dropUndefinedHeld(l) {
+  if (l.heldBy !== void 0) return l;
+  const { heldBy: _, ...rest } = l;
+  return rest;
+}
+
+// src/keymaps/keymapContribution.ts
+var keymapLeaderId = (id) => `keymap.${id}`;
+var keymapLeaderBindingId = (id, index = 0) => index === 0 ? `${keymapLeaderId(id)}.leader` : `${keymapLeaderId(id)}.leader#${index}`;
+function leaderBindings(def) {
+  return [def.leader].flat().map((spec, i) => ({
+    spec: spec.kind === "key-held" ? { ...spec, kind: "key" } : spec,
+    opts: { id: keymapLeaderBindingId(def.id, i) }
+  }));
+}
+var isPlainEscape2 = (spec) => spec.kind === "key" && [spec.key].flat().includes("Escape") && Object.values(spec.mods ?? {}).every((m) => m !== true);
+function keymapContribution(def) {
+  if (def.bindings.some((b) => isPlainEscape2(b.spec))) {
+    throw new Error(`keymap "${def.id}" binds Escape, which always closes a keymap`);
+  }
+  const open = {
+    id: keymapLeaderId(def.id),
+    label: `Open ${def.label} keys`,
+    scope: "hotkey",
+    defaultBinding: leaderBindings(def),
+    requires: ["keymaps"],
+    enabled: (deps) => deps?.keymaps ? true : ActionDisabledReason.NotApplicable,
+    invoker: {
+      timing: "immediate",
+      run: (deps, params) => {
+        deps.keymaps?.push(def.id, def.label, { bindings: def.bindings, ...params?.hold === true ? { heldBy: KEYMAP_HOLD } : {} });
+      }
+    }
+  };
+  return [
+    {
+      id: def.id,
+      eligibility: { keymap: def.unbound ? { unbound: def.unbound } : true },
+      bindings: [...def.bindings],
+      presentation: { label: def.label },
+      ...def.overlay !== void 0 ? { overlay: def.overlay } : {},
+      ...def.overlayPosition ? { overlayPosition: def.overlayPosition } : {}
+    },
+    {
+      id: `${def.id}.leader`,
+      eligibility: { always: true },
+      actions: [open, ...def.actions ?? []]
+    }
+  ];
+}
+var ESCAPE = { shortcut: { key: "Escape", mod: false, alt: false, shift: false }, label: "Close" };
+var GESTURE_WORDS = {
+  click: "click",
+  doubleClick: "double-click",
+  drag: "drag",
+  longPress: "long-press",
+  contextMenu: "right-click",
+  wheel: "scroll",
+  pinch: "pinch",
+  pointerDown: "press"
+};
+var MOD_WORDS = [
+  ["mod", "Mod"],
+  ["ctrl", "Ctrl"],
+  ["meta", "Meta"],
+  ["alt", "Alt"],
+  ["shift", "Shift"]
+];
+function gestureWords(spec) {
+  if (spec.kind === "key-held") {
+    const chip = keySpecShortcut(spec);
+    return chip ? `Hold ${formatShortcut(chip)}` : void 0;
+  }
+  const word = GESTURE_WORDS[spec.kind];
+  if (!word) return void 0;
+  const mods = MOD_WORDS.filter(([m]) => spec.mods?.[m] === true).map(([, w]) => w);
+  const text = [...mods, word].join("-");
+  return text[0].toUpperCase() + text.slice(1);
+}
+function describeKeymap(level, actions, overrides = NO_OVERRIDES) {
+  const byId = new Map(actions.map((a) => [a.id, a]));
+  const labelOf = (b) => {
+    const action = byId.get(b.actionId);
+    const params = resolveParams(b.opts?.params);
+    const variant = params && action?.variants?.find((v) => paramsMatch(params, v.params));
+    return variant ? variant.label : action?.label ?? b.actionId;
+  };
+  const rows = [ESCAPE];
+  for (const b of overriddenBindings(level.bindings, level.id, overrides)) {
+    const label = labelOf(b);
+    const shortcut = b.spec.kind === "key" ? keySpecShortcut(b.spec) : void 0;
+    if (shortcut) rows.push({ shortcut, label });
+    else {
+      const gesture = gestureWords(b.spec);
+      if (gesture) rows.push({ gesture, label });
+    }
+  }
+  return { id: level.id, label: level.label, held: level.heldBy !== void 0, rows };
+}
+function keymapShortcuts(def, overrides = NO_OVERRIDES) {
+  const leaderChip = overriddenBindings(actionBindings({ id: keymapLeaderId(def.id), defaultBinding: leaderBindings(def) }), null, overrides).map((b) => keySpecShortcut(b.spec)).find((c) => c !== void 0);
+  const out = /* @__PURE__ */ new Map();
+  for (const b of overriddenBindings(def.bindings, def.id, overrides)) {
+    if (b.spec.kind !== "key") continue;
+    const chip = keySpecShortcut(b.spec);
+    if (!chip) continue;
+    const withPath = leaderChip ? { ...chip, leader: [{ label: def.label, shortcut: leaderChip }] } : chip;
+    out.set(b.actionId, [...out.get(b.actionId) ?? [], withPath]);
+  }
+  return out;
+}
 
 // src/tools/types.ts
 function isTool(entry) {
@@ -2307,7 +2646,10 @@ function eligibleRule(action) {
   return typeof eligible === "function" ? eligible.rule : eligible;
 }
 function findScopedConflicts(scopes) {
-  const registry = Array.isArray(scopes.registry) ? scopes.registry : Object.values(scopes.registry);
+  const overrides = scopes.overrides;
+  const asBound = (e) => overrides?.size && e.bindings ? { ...e, bindings: overriddenBindings(e.bindings, e.id, overrides) } : e;
+  const registry = (Array.isArray(scopes.registry) ? scopes.registry : Object.values(scopes.registry)).map(asBound);
+  const declaredAmbient = (scopes.ambient ?? []).map(asBound);
   const actions = scopes.actions ?? [];
   const rules = /* @__PURE__ */ new Map();
   for (const a of actions) {
@@ -2322,7 +2664,9 @@ function findScopedConflicts(scopes) {
     (a.eligible !== void 0 ? gatedActions : ungated).push(actionAsEntry(a));
   }
   const modes = scopes.modes ?? KIT_MODES;
-  const ambient = [...scopes.ambient ?? [], ...ungated];
+  const isKeymap = (e) => e.eligibility?.keymap !== void 0;
+  const keymaps = declaredAmbient.filter(isKeymap);
+  const ambient = [...declaredAmbient.filter((e) => !isKeymap(e)), ...ungated];
   const out = [];
   const seen = /* @__PURE__ */ new Set();
   const add = (keyed) => {
@@ -2333,7 +2677,7 @@ function findScopedConflicts(scopes) {
       out.push(conflict);
     }
   };
-  for (const tool of [...registry, ...ambient, ...gatedActions, ...hotkeyActions]) {
+  for (const tool of [...registry, ...ambient, ...keymaps, ...gatedActions, ...hotkeyActions]) {
     add(findConflictsKeyed([tool], rules, modes));
   }
   if (ambient.length > 1) add(findConflictsKeyed(ambient, rules, modes));
@@ -2827,6 +3171,7 @@ function createMenuHost(src) {
         client: req.client,
         world: req.world,
         ...req.under ? { under: req.under } : {},
+        ...req.side ? { side: req.side } : {},
         source: req.source ?? "pointer"
       };
       emit();
@@ -2844,6 +3189,6 @@ function createMenuHost(src) {
   };
 }
 
-export { ALWAYS, ActionDisabledReason, COARSE_TARGET_SCALE, DEFAULT_ALLOWED_CAPABILITIES, DEFAULT_DEVICE_PROFILE, DepNode, INGEST_STRING_MIMES, LONG_PRESS_HAPTIC_MS, NEVER, PREDICATE_TARGET, ScopeNode, TOOL_OFFHAND_ID, actionBindings, actionCursor, actionItemTitle, actionItems, actionSettingsParams, actionShortcuts, addCarrySurface, admitIngestMime, anyBinding, assembleEntries, buildDepsFromRequires, buildRouteRegistry, buildRuleCtx, buildToolOffhandBindings, carryGestureId, clientToCanvas, clientToCanvasRect, createDepRegistry, createDispatchTrace, createDispatcher, createLongPressStore, createMenuHost, createTraceRing, depNodeOf, describeRule, dlog, dwarn, evaluate, evaluateActive, evaluateEnabled, findConflicts, heldKeySpec, historyKey, isDebugEnabled, isTool, itemTypesFromDataTransfer, itemsFromClipboardData, itemsFromDataTransfer, itemsFromFiles, keySpecShortcut, keysHeld, liveScope, makeToolOffhandAction, matchBest, matchSorted, matchSortedWithBarred, matchesKeyBinding, mergeMenuDefs, multiTouchGestureId, offhandKeyFor, openPointerSession, pickMenu, pointerGestureId, pushOwner, readActionSettings, reportRouteConflicts, resolveDeviceProfile, resolveMenu, resolveParams, resolveSchemaMenu, roleReader, routesForSpec, ruleCanHoldIn, rulesExclusive, scopeBindings, startCarry, targetConsultsAffordance, tuneAction, tunedParams, validateActionDefaultBinding, validateActionId };
-//# sourceMappingURL=chunk-KLBH7VFF.js.map
-//# sourceMappingURL=chunk-KLBH7VFF.js.map
+export { ALWAYS, ActionDisabledReason, COARSE_TARGET_SCALE, DEFAULT_ALLOWED_CAPABILITIES, DEFAULT_DEVICE_PROFILE, DepNode, INGEST_STRING_MIMES, KEYMAP_HOLD, LONG_PRESS_HAPTIC_MS, NEVER, NO_OVERRIDES, PREDICATE_TARGET, ScopeNode, TOOL_OFFHAND_ID, actionBindings, actionCursor, actionItemTitle, actionItems, actionSettingsParams, actionShortcuts, addCarrySurface, admitIngestMime, anyBinding, assembleEntries, bindingId, buildDepsFromRequires, buildRouteRegistry, buildRuleCtx, buildToolOffhandBindings, carryGestureId, clientToCanvas, clientToCanvasRect, createDepRegistry, createDispatchTrace, createDispatcher, createKeymapStack, createLongPressStore, createMenuHost, createTraceRing, depNodeOf, describeKeymap, describeRule, dlog, dwarn, evaluate, evaluateActive, evaluateEnabled, findConflicts, heldKeySpec, historyKey, isDebugEnabled, isTool, itemTypesFromDataTransfer, itemsFromClipboardData, itemsFromDataTransfer, itemsFromFiles, keySpecShortcut, keymapContribution, keymapLeaderBindingId, keymapLeaderId, keymapShortcuts, keysHeld, liveScope, makeToolOffhandAction, matchBest, matchSorted, matchSortedWithBarred, matchesKeyBinding, mergeMenuDefs, modifierStateOf, multiTouchGestureId, offhandKeyFor, openPointerSession, overriddenBindings, overrideActionBindings, pickMenu, pointerGestureId, pushOwner, readActionSettings, reportRouteConflicts, resolveBindingOverrides, resolveDeviceProfile, resolveMenu, resolveParams, resolveSchemaMenu, roleReader, routesForSpec, ruleCanHoldIn, rulesExclusive, scopeBindings, startCarry, targetConsultsAffordance, tuneAction, tunedParams, validateActionDefaultBinding, validateActionId };
+//# sourceMappingURL=chunk-CRF3ROBB.js.map
+//# sourceMappingURL=chunk-CRF3ROBB.js.map