@weasel-js/routing 1.11.0 → 1.12.0

package/dist/{chunk-QBQQIFPI.js → chunk-ARDHI47M.js}

@@ -1,10 +1,10 @@
 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';
-import { prefIsShown, prefIsEnabled, isPrefLeaf, prefAliasTarget, prefLeafAt, prefAliasedLeaf, prefNumberAt, resolvePrefUnit, prefDisplayBounds, prefUnitAccepts } from '@weasel-js/prefs';
+import { prefIsShown, prefIsEnabled, isPrefLeaf, prefAliasTarget, prefLeafAt, prefAliasedLeaf, prefNumberAt, resolvePrefUnit, prefDisplayBounds, prefUnitAccepts, prefValueAtPath } from '@weasel-js/prefs';
 import { endlessAllows } from '@weasel-js/quantity';
 
 // src/interactions/actions/actionItems.ts
@@ -34,6 +34,21 @@ function actionItemTitle(item) {
   return `${item.action.label}: ${item.label}`;
 }
 
+// src/interactions/actions/actionSettings.ts
+var EMPTY = { values: {} };
+function readActionSettings(action, deps) {
+  const settings = action.settings;
+  if (!settings) return null;
+  try {
+    return settings.read(deps ?? {});
+  } catch {
+    return EMPTY;
+  }
+}
+function actionSettingsParams(settings, path, value) {
+  return settings.params ? settings.params(path, value) : { [path]: value };
+}
+
 // src/interactions/actions/binding.ts
 function actionBindings(action) {
   const gs = action.defaultBinding;
@@ -270,13 +285,21 @@ var DepNode = class extends ScopeNode {
       };
     },
     get: (name) => {
+      const stacks = [...this.start().chain()].map((n) => n.sources.get(name) ?? []);
+      return readFrom(stacks, 0, (stacks[0]?.length ?? 0) - 1);
+    },
+    subscribe: (listener) => this.tree.listeners.subscribe(listener),
+    list: () => {
+      const found = /* @__PURE__ */ new Map();
+      let depth = 0;
       for (const n of this.start().chain()) {
-        const source = n.sources.get(name)?.at(-1);
-        if (source) return source();
+        for (const [name, stack] of n.sources) {
+          if (!found.has(name)) found.set(name, { name, depth, stacked: stack.length });
+        }
+        depth++;
       }
-      return void 0;
+      return [...found.values()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
     },
-    subscribe: (listener) => this.tree.listeners.subscribe(listener),
     changed: () => this.changed()
   };
   constructor(parent, descends) {
@@ -284,6 +307,11 @@ var DepNode = class extends ScopeNode {
     NODES.set(this.registry, this);
   }
 };
+function readFrom(stacks, scope, index) {
+  if (scope >= stacks.length) return void 0;
+  if (index < 0) return readFrom(stacks, scope + 1, (stacks[scope + 1]?.length ?? 0) - 1);
+  return stacks[scope][index](() => readFrom(stacks, scope, index - 1));
+}
 var NODES = /* @__PURE__ */ new WeakMap();
 function depNodeOf(registry) {
   return registry ? NODES.get(registry) ?? null : null;
@@ -438,6 +466,49 @@ 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/actions/toolOffhand.ts
 var TOOL_OFFHAND_ID = "tool.offhand";
@@ -460,7 +531,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" }];
@@ -520,7 +591,8 @@ function routesForSpec(spec) {
   const phases = phaseAtomsForSpec("phase" in spec ? spec.phase : void 0);
   const target = descriptor.hasTarget ? routeTargetForSpec("target" in spec ? spec.target : void 0) ?? "*" : void 0;
   const args = descriptor.arg ? routeArgsForSpec(spec, descriptor.arg.default) : [void 0];
-  return args.map((arg) => formatRoute({ phases, gesture, arg, target, modifiers }));
+  const held = spec.kind === "hover" && spec.held !== void 0 ? { held: spec.held === true ? "required" : "optional" } : {};
+  return args.map((arg) => formatRoute({ phases, gesture, arg, target, modifiers, ...held }));
 }
 function entryFor(ownerId, spec, actionId) {
   const gesture = routeGestureForSpecKind(spec.kind);
@@ -671,11 +743,11 @@ function matchSortedWithBarred(e, bindings, isMac, engagedChannels, opts = {}) {
     const scopeBarred = [];
     for (const sb of bindings) {
       if (sb.scope !== scope) continue;
-      const admitted = admits(sb);
-      if (!admitted && !opts.collectBarred) continue;
+      const admitted2 = admits(sb);
+      if (!admitted2 && !opts.collectBarred) continue;
       const phaseCtx = { selfChannel: sb.ownerId, engagedChannels: engaged };
       if (matchSpec(e, sb.binding.spec, isMac, phaseCtx)) {
-        (admitted ? scopeMatches : scopeBarred).push({ binding: sb.binding, scope, ownerId: sb.ownerId });
+        (admitted2 ? scopeMatches : scopeBarred).push({ binding: sb.binding, scope, ownerId: sb.ownerId });
       }
     }
     scopeMatches.sort((a, b) => compareSpecificity(a.binding.spec, b.binding.spec));
@@ -933,33 +1005,14 @@ function buildRuleCtx(args) {
     device: args.device
   };
 }
-var DEV2 = isDev();
-var TRACE_LIMIT = 200;
-var traceLog = DEV2 && typeof window !== "undefined" ? window.__weaselDispatchLog__ ??= [] : [];
-function recordTrace(entry) {
-  if (!DEV2) return;
-  traceLog.push(entry);
-  if (traceLog.length > TRACE_LIMIT) traceLog.shift();
-}
-function publishLiveDispatch(explain2) {
-  if (!DEV2 || typeof window === "undefined") return;
-  window.__weaselDispatchLive__ = explain2;
-}
-function recordModeSwitch(mode, from, to, detail) {
-  recordTrace({
-    kind: "mode",
-    ts: Date.now(),
-    mode,
-    from,
-    to,
-    ...detail !== void 0 ? { detail } : {}
-  });
-}
 
 // src/interactions/dispatcher/gestureIds.ts
 function pointerGestureId(pointerId) {
   return `pointer-${pointerId ?? "mouse"}`;
 }
+function carryGestureId(pointerId) {
+  return `carry-${pointerId ?? "mouse"}`;
+}
 function multiTouchGestureId(fingers) {
   return `multitouch-${fingers}`;
 }
@@ -977,7 +1030,7 @@ function gestureIdFor(event) {
     return multiTouchGestureId(event.fingers);
   }
   if (event.kind === "carry") {
-    return `carry-${event.pointerId ?? "mouse"}`;
+    return carryGestureId(event.pointerId);
   }
   return `ongoing-${event.kind}`;
 }
@@ -986,17 +1039,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 });
     }
   }
@@ -1018,10 +1072,56 @@ function assembleEntries(entries, inputs) {
     state: {
       focusedId: inputs.focusedId,
       engagedIds: new Set(inputs.hotkeyStack),
+      ...inputs.openKeymap ? { openKeymap: inputs.openKeymap } : {},
       ...allowed ? { allows: (tags) => capabilitiesAllowed(allowed, tags) } : {}
     }
   };
 }
+function createTraceRing(limit = 200, dev = isDev()) {
+  const entries = [];
+  const pushed = createEmitter();
+  let total = 0;
+  let watchers = 0;
+  const recording = () => dev || watchers > 0;
+  return {
+    recording,
+    push(entry) {
+      if (!recording()) return;
+      entries.push(entry);
+      if (entries.length > limit) entries.shift();
+      total++;
+      pushed.emit();
+    },
+    since(cursor) {
+      const first = total - entries.length;
+      return { entries: entries.slice(Math.max(cursor, first) - first), cursor: total };
+    },
+    watch() {
+      watchers++;
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        watchers--;
+      };
+    },
+    subscribe: pushed.subscribe
+  };
+}
+function createDispatchTrace(limit, dev) {
+  const ring = createTraceRing(limit, dev);
+  let explain2 = null;
+  return {
+    ...ring,
+    recordModeSwitch(mode, from, to, detail) {
+      ring.push({ kind: "mode", ts: Date.now(), mode, from, to, ...detail !== void 0 ? { detail } : {} });
+    },
+    setLive(next) {
+      explain2 = next;
+    },
+    live: () => explain2?.() ?? null
+  };
+}
 
 // src/interactions/dispatcher/inputFacts.ts
 function modifiersOf(e) {
@@ -1043,6 +1143,7 @@ function worldPointOf(event) {
   }
 }
 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) {
@@ -1109,6 +1210,7 @@ function immediateParams(event, resolved) {
         affordance: event.affordance,
         bodyTarget: event.bodyTarget,
         mods: modifiersOf(event),
+        held: event.held === true,
         ...resolved
       };
     case "carry":
@@ -1118,6 +1220,9 @@ function immediateParams(event, resolved) {
         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
       };
@@ -1139,6 +1244,10 @@ function liveInView(binding, view) {
   const views = binding.opts?.views;
   return views === void 0 || views.includes(view);
 }
+function liveForKeys(binding, reach) {
+  if (reach === void 0) return true;
+  return binding.opts?.over ? reach.over : reach.held;
+}
 function namesView(binding, view) {
   return binding.opts?.views?.includes(view) ?? false;
 }
@@ -1557,7 +1666,7 @@ function pumpCarry(run, event) {
   if (event.stage === "enter") return void 0;
   const gestureId = gestureIdFor(event);
   const handle = run.inFlight.handles.get(gestureId);
-  if (!handle) return event.stage === "drop" ? void 0 : "unhandled";
+  if (!handle) return event.stage === "leave" ? "unhandled" : void 0;
   if (event.stage === "move") {
     handle.onMove?.(ctxFor(run, event, {}, gestureId));
     return "handled";
@@ -1566,7 +1675,7 @@ function pumpCarry(run, event) {
 }
 function carryStageFits(event, timing) {
   if (event.kind !== "carry") return true;
-  return event.stage === (timing === "immediate" ? "drop" : "enter");
+  return timing === "immediate" ? event.stage === "drop" : event.stage === "enter" || event.stage === "move";
 }
 function invokeAction(run, event, match, action, deps) {
   if (action.invoker && !carryStageFits(event, action.invoker.timing)) return "empty-handle";
@@ -1690,22 +1799,29 @@ 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 result = scopeBindings(ordered, state).filter((sb) => liveInView(sb.binding, view));
+  const live = (b) => liveInView(b, view) && liveForKeys(b, ctx.keyReach);
+  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 (!liveInView(binding, view)) continue;
-      result.push({ binding, scope: targetScope, ownerId: null });
+      if (live(binding)) result.push({ binding, scope: targetScope, ownerId: null });
     }
   }
   return result;
 }
+function anyBinding(ctx, test) {
+  return assembleScopedBindings(ctx).some((sb) => test(sb.binding.spec));
+}
 function buildActionMap(registry) {
   const map = /* @__PURE__ */ new Map();
   for (const action of registry.list()) {
@@ -1871,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) {
@@ -1893,10 +2071,17 @@ function createDispatcher(opts) {
     const pumped = pumpGesture(run, event);
     if (pumped !== void 0) return pumped;
     if (event.kind === "hover") return hover(event, ctx);
-    const r = rank(event, ctx, inFlight.engagedOwners(), DEV2);
+    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);
     const outcome = walked.stop === "fired" ? "handled" : "unhandled";
-    if (DEV2) recordTrace(buildDispatchRecord(r, walked, event, ctx, false, outcome));
+    trace?.push(buildDispatchRecord(r, walked, event, ctx, false, outcome));
     return outcome;
   }
   function hover(event, ctx) {
@@ -2112,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) {
@@ -2238,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) {
@@ -2253,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) => {
@@ -2264,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));
@@ -2333,6 +2746,20 @@ function normalizeMime(raw) {
   const bare = raw.split(";")[0].trim().toLowerCase();
   return bare || FALLBACK_MIME;
 }
+var admitted = /* @__PURE__ */ new Map();
+function admitIngestMime(mime) {
+  const key = normalizeMime(mime);
+  admitted.set(key, (admitted.get(key) ?? 0) + 1);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const n = (admitted.get(key) ?? 1) - 1;
+    if (n > 0) admitted.set(key, n);
+    else admitted.delete(key);
+  };
+}
+var keepsString = (mime) => INGEST_STRING_MIMES.has(mime) || admitted.has(mime);
 function itemsFromFiles(files) {
   return files.map((file) => ({ kind: "file", mime: normalizeMime(file.type), file }));
 }
@@ -2346,7 +2773,7 @@ function itemsFromDataTransfer(dt) {
       if (file) files.push({ kind: "file", mime: normalizeMime(file.type), file });
     } else if (item.kind === "string") {
       const mime = normalizeMime(item.type);
-      if (INGEST_STRING_MIMES.has(mime)) {
+      if (keepsString(mime)) {
         const slot = strings.length;
         strings.push(null);
         reads.push(
@@ -2372,7 +2799,7 @@ function itemTypesFromDataTransfer(dt) {
   for (const item of Array.from(dt.items ?? [])) {
     const mime = item.type ? normalizeMime(item.type) : "";
     if (item.kind === "file") mimes.push(mime && mime !== "application/x-moz-file" ? mime : UNKNOWN_MIME);
-    else if (INGEST_STRING_MIMES.has(mime)) mimes.push(mime);
+    else if (keepsString(mime)) mimes.push(mime);
   }
   if (mimes.length === 0 && Array.from(dt.types ?? []).includes("Files")) mimes.push(UNKNOWN_MIME);
   return mimes.map((mime) => ({ mime }));
@@ -2382,7 +2809,7 @@ function itemsFromClipboardData(cd) {
   for (const file of Array.from(cd.files ?? [])) {
     out.push({ kind: "file", mime: normalizeMime(file.type), file });
   }
-  for (const mime of INGEST_STRING_MIMES) {
+  for (const mime of /* @__PURE__ */ new Set([...INGEST_STRING_MIMES, ...admitted.keys()])) {
     const text = cd.getData(mime);
     if (text) out.push({ kind: "string", mime, text });
   }
@@ -2473,6 +2900,7 @@ var sep = (key) => ({ kind: "separator", key });
 function itemOf(ctx, it, key, label, off, access) {
   const deps = ctx.src.depsFor(it.action);
   const point = ctx.at ? { worldX: ctx.at.x, worldY: ctx.at.y } : {};
+  if (it.action.settings) return settingsOf(ctx, it, key, label, off || !evaluateEnabled(it.action, deps, ctx.at).enabled, access);
   return {
     kind: "item",
     key,
@@ -2487,6 +2915,32 @@ function itemOf(ctx, it, key, label, off, access) {
     }
   };
 }
+function settingsOf(ctx, it, key, label, off, access) {
+  const settings = it.action.settings;
+  const state = off ? null : readActionSettings(it.action, ctx.src.depsFor(it.action));
+  const mixed = new Set(state?.mixed ?? []);
+  const values = (path) => mixed.has(path) ? void 0 : prefValueAtPath(state?.values, path);
+  const onChange = (path, value) => {
+    const params = actionSettingsParams(settings, path, value);
+    if (params) ctx.src.trigger(it.action.id, { ...ctx.params, ...it.params, ...params });
+  };
+  const form = {
+    ...ctx,
+    src: { ...ctx.src, values, onChange, over: settings.schema },
+    root: settings.schema,
+    read: (path, from) => from === "item" ? void 0 : values(path)
+  };
+  const entries = state ? tidy(groupRows(form, settings.schema, "", false)) : [];
+  return {
+    kind: "submenu",
+    key,
+    label,
+    ...it.icon ? { icon: it.icon } : {},
+    ...withAccess(access),
+    ...entries.length === 0 ? { disabled: true } : {},
+    entries
+  };
+}
 function itemsNamed(ctx, name) {
   const action = ctx.byId.get(name);
   if (action) return actionItems(action);
@@ -2584,9 +3038,23 @@ function colorRows(ctx, leaf, key, path, off) {
   if (!ctx.src.values) return [];
   return [{ kind: "color", key, label: leaf.name, ...withAccess(leaf.access), ...off ? { disabled: true } : {}, value: textAt(ctx, path) }];
 }
-function stringRows(ctx, leaf, key, path) {
-  if (!ctx.src.values) return [];
-  return [{ kind: "item", key, label: `${leaf.name}: ${textAt(ctx, path) ?? "\u2014"}`, ...withAccess(leaf.access), disabled: true, run: noop }];
+function stringRows(ctx, leaf, key, path, off) {
+  const { values, onChange } = ctx.src;
+  if (!values) return [];
+  if (leaf.readout || !onChange) {
+    return [{ kind: "item", key, label: `${leaf.name}: ${textAt(ctx, path) ?? "\u2014"}`, ...withAccess(leaf.access), disabled: true, run: noop }];
+  }
+  const stored = values(path);
+  return [{
+    kind: "text",
+    key,
+    label: leaf.name,
+    ...withAccess(leaf.access),
+    ...leaf.icon ? { icon: leaf.icon } : {},
+    ...off ? { disabled: true } : {},
+    value: typeof stored === "string" ? stored : void 0,
+    set: (text) => onChange(path, text)
+  }];
 }
 function leafRows(ctx, leaf, key, path, off) {
   switch (leaf.kind) {
@@ -2605,7 +3073,7 @@ function leafRows(ctx, leaf, key, path, off) {
     case "color":
       return colorRows(ctx, leaf, key, path, off);
     case "string":
-      return stringRows(ctx, leaf, key, path);
+      return stringRows(ctx, leaf, key, path, off);
     case "separator":
       return [sep(key)];
     case "label":
@@ -2703,6 +3171,7 @@ function createMenuHost(src) {
         client: req.client,
         world: req.world,
         ...req.under ? { under: req.under } : {},
+        ...req.above ? { above: true } : {},
         source: req.source ?? "pointer"
       };
       emit();
@@ -2720,6 +3189,6 @@ function createMenuHost(src) {
   };
 }
 
-export { ALWAYS, ActionDisabledReason, COARSE_TARGET_SCALE, DEFAULT_ALLOWED_CAPABILITIES, DEFAULT_DEVICE_PROFILE, DEV2 as DEV, DepNode, INGEST_STRING_MIMES, LONG_PRESS_HAPTIC_MS, NEVER, PREDICATE_TARGET, ScopeNode, TOOL_OFFHAND_ID, actionBindings, actionCursor, actionItemTitle, actionItems, actionShortcuts, addCarrySurface, assembleEntries, buildDepsFromRequires, buildRouteRegistry, buildRuleCtx, buildToolOffhandBindings, clientToCanvas, clientToCanvasRect, createDepRegistry, createDispatcher, createLongPressStore, createMenuHost, depNodeOf, describeRule, dlog, dwarn, evaluate, evaluateActive, evaluateEnabled, findConflicts, gestureIdFor, heldKeySpec, historyKey, isDebugEnabled, isTool, itemTypesFromDataTransfer, itemsFromClipboardData, itemsFromDataTransfer, itemsFromFiles, keySpecShortcut, keysHeld, liveScope, makeToolOffhandAction, matchBest, matchSorted, matchSortedWithBarred, matchesKeyBinding, mergeMenuDefs, multiTouchGestureId, offhandKeyFor, openPointerSession, pickMenu, pointerGestureId, publishLiveDispatch, pushOwner, recordModeSwitch, reportRouteConflicts, resolveDeviceProfile, resolveMenu, resolveParams, resolveSchemaMenu, roleReader, routesForSpec, ruleCanHoldIn, rulesExclusive, scopeBindings, startCarry, targetConsultsAffordance, tuneAction, tunedParams, validateActionDefaultBinding, validateActionId };
-//# sourceMappingURL=chunk-QBQQIFPI.js.map
-//# sourceMappingURL=chunk-QBQQIFPI.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, 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-ARDHI47M.js.map
+//# sourceMappingURL=chunk-ARDHI47M.js.map