@weasel-js/gestures 1.10.1 → 1.11.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { MenuShortcut } from '@weasel-js/menu';
+
 /**
  * Declarative gesture taxonomy. Single source of truth for:
  *   - which gestures hit-test (have a `.target` slot in the route string)
@@ -7,7 +9,7 @@
  * Reflection, matcher, and inspector UI all read this table. Adding a new
  * gesture name in one place updates every consumer.
  */
-type GestureName = 'click' | 'pointerDown' | 'hover' | 'dblTap' | 'drag' | 'wheel' | 'pinch' | 'keyDown' | 'keyUp' | 'keyHeld' | 'contextMenu' | 'longPress' | 'multiTouch' | 'multiTouchTap' | 'drop' | 'paste';
+type GestureName = 'click' | 'pointerDown' | 'hover' | 'dblTap' | 'drag' | 'wheel' | 'pinch' | 'keyDown' | 'keyUp' | 'keyHeld' | 'contextMenu' | 'longPress' | 'multiTouch' | 'multiTouchTap' | 'drop' | 'carry' | 'paste';
 /**
  * Gesture kinds an affordance claim can bar, in the spec vocabulary bindings
  * are written in. `'pointer'` is one token because `pointerDown` / `click` /
@@ -397,6 +399,24 @@ interface DropSpec {
     mods?: ModSpec;
     phase?: PhaseSpec;
 }
+/**
+ * A press that began elsewhere on the page, carried over the canvas: a palette
+ * item dragged in, a row dragged out of a list. The in-app sibling of
+ * {@link DropSpec}, which is the OS's drag. A carry is begun with `startCarry`.
+ * `types` filters by the payload's `type`, as globs; omitted or empty matches
+ * any carry.
+ *
+ * An ongoing action bound here starts when the carry comes over the surface:
+ * its moves update it, the release commits it, and leaving the surface or
+ * canceling the press cancels it. An immediate action fires once, on the
+ * release.
+ */
+interface CarrySpec {
+    kind: 'carry';
+    types?: string[];
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
 /** System-clipboard paste of external content. Same `types` semantics as
  *  {@link DropSpec} — omitted or empty = matches any paste. */
 interface PasteSpec {
@@ -406,7 +426,7 @@ interface PasteSpec {
     phase?: PhaseSpec;
 }
 /** The full union of supported gesture spec kinds. */
-type GestureSpec = KeySpec | KeyHeldSpec | WheelSpec | PinchSpec | ClickSpec | DoubleClickSpec | ContextMenuSpec | DragSpec | PointerDownSpec | HoverSpec | LongPressSpec | MultiTouchSpec | MultiTouchTapSpec | DropSpec | PasteSpec;
+type GestureSpec = KeySpec | KeyHeldSpec | WheelSpec | PinchSpec | ClickSpec | DoubleClickSpec | ContextMenuSpec | DragSpec | PointerDownSpec | HoverSpec | LongPressSpec | MultiTouchSpec | MultiTouchTapSpec | DropSpec | CarrySpec | PasteSpec;
 
 /**
  * Mini-grammar for the `arg` slot of `keyDown` / `keyUp` routes.
@@ -447,7 +467,7 @@ declare function keyRouteToSpec(r: ParsedKeyRoute): KeySpec;
  * Wildcards become omitted fields: a `*` target, direction or MIME list, and a
  * `[*:*]` phase slot. `[*]` is `[&:*]`, which an ambient binding never
  * matches, so it stays a phase atom. A `keyDown` / `keyHeld` arg is read as a
- * key route, so `keyDown(z?shift)` yields `mods.shift: 'optional'`; a drop or
+ * key route, so `keyDown(z?shift)` yields `mods.shift: 'optional'`; a drop, carry, or
  * paste arg is a `|`-separated MIME list.
  *
  * Throws on a route no spec can express: `keyUp`, a key or finger-count
@@ -519,13 +539,6 @@ declare function modifierComboToParsed(key: ModifierCombo): ParsedModifiers;
  *  `name=req` pairs joined by `&`. */
 declare function canonicalModifiers(mods: ParsedModifiers): string;
 
-/** Keyboard/pointer modifier flags carried by every {@link InputEvent} arm. */
-interface EventModifiers {
-    altKey: boolean;
-    ctrlKey: boolean;
-    metaKey: boolean;
-    shiftKey: boolean;
-}
 /**
  * Body-target classification from the scene hit-test. Populated by
  * `useGestureDispatcher` when a `classifyTarget` thunk is supplied to its
@@ -552,6 +565,28 @@ interface BodyClassification {
     /** Semantic kind of the hit body. Undefined on empty canvas, and undefined
      *  on a body whose kind the scene can't name — never guessed. */
     kind?: BodyKind;
+    /** The node classified. Matching ignores it. */
+    id?: string;
+    /** What a double-click at this point names, where that is not the body hit: the group a hit
+     *  member belongs to. A double click's targets match against it. Absent, the hit is named. */
+    doubleClick?: {
+        body: BodyTarget;
+        kind?: BodyKind;
+        id?: string;
+    };
+}
+/** The body a double-click names, as a press carries it to the double click it composes. */
+interface DoubleClickBody {
+    bodyTarget: BodyTarget;
+    bodyKind?: BodyKind;
+}
+
+/** Keyboard/pointer modifier flags carried by every {@link InputEvent} arm. */
+interface EventModifiers {
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
 }
 /** A keystroke. */
 interface KeyEvent extends EventModifiers {
@@ -850,6 +885,21 @@ interface DropEvent extends EventModifiers {
     clientX?: number;
     clientY?: number;
 }
+/** A carry over the canvas (`startCarry`). `stage` is what it did here: came
+ *  over, moved, was released, or left — off the surface, or canceled on it. */
+interface CarryEvent extends EventModifiers {
+    kind: 'carry';
+    stage: 'enter' | 'move' | 'drop' | 'leave';
+    pointerId?: number;
+    /** The payload's type, which a spec's `types` globs filter, and the payload. */
+    type: string;
+    value: unknown;
+    /** World-space position (post view transform). */
+    x: number;
+    y: number;
+    clientX: number;
+    clientY: number;
+}
 /** External content pasted from the system clipboard. Carries no point. */
 interface PasteEvent extends EventModifiers {
     kind: 'paste';
@@ -864,7 +914,7 @@ interface PasteEvent extends EventModifiers {
  * The `affordance?` field on {@link PointerDownEvent} is widened to `unknown`
  * in this package — the kit narrows it back to `AffordanceHit` at consumption.
  */
-type InputEvent = KeyEvent | KeyHeldEvent | WheelEvent | PinchEvent | PointerDownEvent | PointerMoveEvent | HoverEvent | PointerUpEvent | PointerCancelEvent | ClickEvent | DoubleClickEvent | ContextMenuEvent | LongPressEvent | MultiTouchEvent | MultiTouchTapEvent | DropEvent | PasteEvent;
+type InputEvent = KeyEvent | KeyHeldEvent | WheelEvent | PinchEvent | PointerDownEvent | PointerMoveEvent | HoverEvent | PointerUpEvent | PointerCancelEvent | ClickEvent | DoubleClickEvent | ContextMenuEvent | LongPressEvent | MultiTouchEvent | MultiTouchTapEvent | DropEvent | CarryEvent | PasteEvent;
 
 /**
  * The stylus fields `src` carries, as a spread-able partial: a sample that
@@ -998,6 +1048,126 @@ declare function matchIngestTypes(items: readonly {
  */
 declare function isApplePlatform(): boolean;
 
+/** One key of a shortcut as a keyboard prints it. */
+interface KeyLegend {
+    /** Glyph drawn for the key (modifier or key). */
+    label: string;
+    /** When true, the key may be held but is not required to trigger the action
+     *  (e.g. an optional modifier). Defaults to false. */
+    optional?: boolean;
+}
+/** Logical modifier name. Matches the kit's `ModifierKey` in shape — kept as a
+ *  local type so `weasel-ui` stays independent of `@weasel-js/core`. */
+type LogicalMod = 'mod' | 'shift' | 'alt' | 'ctrl' | 'meta';
+/** Detected (or overridden) platform. `'mod'` resolves to ⌘ on macOS,
+ *  Ctrl on Windows / Linux. */
+type Platform = 'macos' | 'windows' | 'linux';
+/** Visual form of a modifier or named-key label.
+ *
+ *  - `'auto'` (default): the per-entry, per-platform default — whatever
+ *    label is actually printed on the physical key. macOS keys show the
+ *    Apple glyphs (⌘ ⌥ ⌃ ⇧ ⎋ ↵ ⇥). Windows keys mostly show text
+ *    (Ctrl, Alt, Shift) BUT the Win key shows its logo (⊞) and the
+ *    context-menu key shows ▤. Linux mirrors Windows with Super (⊞).
+ *  - `'symbol'` forces a glyph wherever the key has one: Apple's on macOS,
+ *    ISO/IEC 9995-7's elsewhere (⎈ Ctrl, ⎇ Alt, ⎋ Esc). A key with no
+ *    symbol still falls back to text.
+ *  - `'text'` always spells the label out (Cmd / Option / Esc / Enter). */
+type LegendStyle = 'auto' | 'symbol' | 'text';
+/** A modifier to render, named platform-independently. */
+interface LogicalModSpec {
+    name: LogicalMod;
+    /** Marks this modifier as optional (may be held but isn't required).
+     *  Forwarded as the resulting `KeyLegend.optional`. */
+    optional?: boolean;
+}
+/** Options for {@link keySpecsFromMods}. */
+interface KeySpecsFromModsOptions {
+    /** Override OS detection. Defaults to {@link detectPlatform}. */
+    platform?: Platform;
+    /** Defaults to `'auto'`. Pass `'symbol'` or `'text'` to force a specific
+     *  style regardless of platform. */
+    legend?: LegendStyle;
+    /** Labels that replace the platform and legend tables', by a modifier's
+     *  logical name (`mod`, `shift`, `alt`, `ctrl`, `meta`) or a key's
+     *  `KeyboardEvent.key` (`Escape`, `Home`, `z`): a whole keyboard's worth
+     *  for a layout, a locale, or a keyboard of one's own. */
+    labels?: KeyLabels;
+}
+/** Key labels by modifier name or `KeyboardEvent.key`. See {@link KeySpecsFromModsOptions.labels}. */
+type KeyLabels = Readonly<Record<string, string>>;
+/** Every label {@link keySpecsFromMods} can produce, on any platform and legend. */
+declare const MODIFIER_LABELS: ReadonlySet<string>;
+/** The platform whose key legends to draw. Whether `mod` is ⌘ comes from
+ *  `isApplePlatform`, the same read the dispatcher
+ *  matches `mod` with, so a keycap names the key that fires. With no
+ *  `navigator` (a server render) it answers `'macos'`, the kit's docs
+ *  convention; an unrecognized browser reads as `'linux'`. */
+declare function detectPlatform(): Platform;
+/**
+ * Map a list of **logical** modifiers (`'mod'`, `'shift'`, …) to **visual**
+ * `KeyLegend`s appropriate for the current platform — `'mod'` means "Cmd on
+ * Mac, Ctrl on Win/Linux".
+ *
+ * ```ts
+ * <KeySequence
+ *   keys={keySpecsFromMods([{ name: 'mod' }, { name: 'shift', optional: true }])}
+ * />
+ * ```
+ */
+declare function keySpecsFromMods(mods: readonly LogicalModSpec[], opts?: KeySpecsFromModsOptions): readonly KeyLegend[];
+/**
+ * Render a raw `KeyboardEvent.key` value as a platform-appropriate
+ * `KeyLegend`. Named non-modifier keys (Esc, Enter, Tab, Space, Backspace,
+ * Delete, arrows) get the platform's conventional form. Letter / digit /
+ * other keys pass through upper-cased.
+ *
+ * ```ts
+ * keySpecFromKey('Escape', { platform: 'macos' })   // { label: '⎋' }
+ * keySpecFromKey('Escape', { platform: 'windows' }) // { label: 'Esc' }
+ * keySpecFromKey('p')                               // { label: 'P' }
+ * ```
+ *
+ * Symbol mode off macOS draws ISO/IEC 9995-7's symbols where the key
+ * has one, though Windows and Linux keyboards print the text form.
+ */
+declare function keySpecFromKey(raw: string, opts?: KeySpecsFromModsOptions & {
+    optional?: boolean;
+}): KeyLegend;
+
+/** A keyboard shortcut as the formatters read it: `@weasel-js/menu`'s `MenuShortcut`. */
+type ShortcutInput = MenuShortcut;
+/** Options for {@link formatShortcut} and {@link formatShortcutParts}. */
+interface FormatShortcutOptions {
+    /** Defaults to the detected platform. */
+    platform?: Platform;
+}
+/** Format a shortcut as an array of display chips, one per key: the
+ *  modifiers, then the key, each as the platform's keyboard prints it, so
+ *  `mod` is `⌘` on macOS and `Ctrl` elsewhere. UIs that want a boxed per-key
+ *  look render each chip in its own element. `shift: 'optional'` is treated
+ *  as falsy. */
+declare function formatShortcutParts(b: ShortcutInput | undefined, opts?: FormatShortcutOptions): readonly string[] | undefined;
+/** Format a shortcut as a single display string. Order: mod, shift, alt,
+ *  key. On macOS the glyphs run together (`⌘⇧Z`); elsewhere the keys are
+ *  spelled out and joined with `+` (`Ctrl+Shift+Z`). Returns `undefined` for
+ *  `undefined` input so callers can `??` a fallback. When `key` is an array,
+ *  the first element is used. `shift: 'optional'` is treated as falsy. */
+declare function formatShortcut(b: ShortcutInput | undefined, opts?: FormatShortcutOptions): string | undefined;
+
+/**
+ * A shortcut as key legends, one per key, as `@weasel-js/ui`'s `KeySequence` draws them: mod, shift, alt, then the
+ * key, each in the platform's own legend (`⌘` on macOS, `Ctrl` elsewhere).
+ * `formatShortcutParts` is these labels as strings. `shift: 'optional'`
+ * becomes an optional key; a key list
+ * renders its first key. Returns `undefined` for no shortcut.
+ *
+ * ```tsx
+ * <KeySequence keys={keySpecsFromShortcut({ key: 'z', mod: true, shift: true })} />
+ * ```
+ */
+declare function keySpecsFromShortcut(shortcut: ShortcutInput | undefined, opts?: KeySpecsFromModsOptions): readonly KeyLegend[] | undefined;
+
 /**
  * The nearest element `from` sits inside that can host a portalled overlay,
  * or `null` when there is none and the body is the only answer.
@@ -1027,7 +1197,7 @@ declare function fixedSeat(from: Element | null | undefined): FixedSeat;
  *    [1] mods   — count of required modifier keys (shift/alt/ctrl/meta/mod).
  *                 `'optional'` does NOT count.
  *    [2] phase  — how much the spec's `phase` narrows; see `phaseRank`.
- *    [3] exact  — per-kind tiebreak: 2 for a drop/paste spec with a
+ *    [3] exact  — per-kind tiebreak: 2 for a drop/carry/paste spec with a
  *                 non-empty `types` MIME filter, else 1.
  *
  *  Identical tuples fall back to registration order in the matcher's
@@ -1102,6 +1272,8 @@ interface PressFacts extends EventModifiers {
     affordance?: unknown;
     bodyTarget?: BodyTarget;
     bodyKind?: BodyKind;
+    /** Replayed onto the double click in place of `bodyTarget` and `bodyKind`. */
+    doubleClickBody?: DoubleClickBody;
 }
 /** Where and how a press was released, for the click it turned out to be. */
 interface ReleaseFacts extends EventModifiers {
@@ -1195,6 +1367,8 @@ interface PressSample extends PointerSample {
     affordance?: unknown;
     bodyTarget?: BodyTarget;
     bodyKind?: BodyKind;
+    /** What a double click this press completes lands on, where not the body hit. */
+    doubleClickBody?: DoubleClickBody;
 }
 
 /**
@@ -1233,6 +1407,14 @@ interface PointerRecognizerOptions {
     toSurface?: (client: Point) => Point;
     /** Long-press hold time in ms, read at each press. Default `LONG_PRESS_MS`. */
     longPressMs?: () => number | undefined;
+    /** Longest gap in ms between two clicks of a double click, read at each click. Default `DOUBLE_CLICK_MAX_MS`. */
+    doubleClickMs?: () => number | undefined;
+    /** Farthest two clicks of a double click may land apart, in CSS px. Default `DOUBLE_CLICK_MAX_PX`. */
+    doubleClickPx?: () => number | undefined;
+    /** Farthest a multitouch tap's fingers may travel, in CSS px. Default `TAP_THRESHOLD_PX`. */
+    tapPx?: () => number | undefined;
+    /** Travel in CSS px that makes a press a drag, read at each move. Default `DRAG_THRESHOLD_PX`. */
+    dragPx?: () => number | undefined;
     clicks?: ClickMemory;
     observer?: RecognizerObserver;
 }
@@ -1303,4 +1485,4 @@ declare function activatesFocusedControl(e: KeyboardEvent): boolean;
  */
 declare function focusedControlOwnsKey(e: KeyboardEvent): boolean;
 
-export { ACTIVE_SIGILS, type BodyClassification, type BodyKind, type BodyTarget, CONTROL_SELECTOR, type ChannelRef, type ClaimableGesture, type ClickEvent, type ClickMemory, type ClickObserver, type ClickSpec, type ContextMenuEvent, type ContextMenuSpec, DOUBLE_CLICK_MAX_MS, DOUBLE_CLICK_MAX_PX, DRAG_THRESHOLD_PX, type DescribeRouteOptions, type DoubleClickEvent, type DoubleClickSpec, type DragSpec, type DropEvent, type DropSpec, type EventModifiers, type FixedSeat, GESTURE_DESCRIPTORS, type GestureArgSpec, type GestureDescriptor, type GestureName, type GestureSpec, type HeldPointers, type HeldPress, type HoverEvent, type HoverSpec, type HoverWhere, type IngestItem, type InputEvent, type KeyEvent, type KeyHeldEvent, type KeyHeldSpec, type KeySpec, LONG_PRESS_MS, type LongPressEvent, type LongPressSpec, MOD_NAME_SET, type ModRequirement, type ModSpec, type ModifierCombo, type ModifierKey, type ModifiersEvent, type MultiTouchEvent, type MultiTouchGeometry, type MultiTouchSpec, type MultiTouchTapEvent, type MultiTouchTapSpec, type OptionalMod, type ParsedKeyRoute, type ParsedModifiers, type ParsedRoute, type PasteEvent, type PasteSpec, type PhaseAtom, type PhaseContext, type PhaseSpec, type PinchEvent, type PinchSpec, type Point, type PointerCancelEvent, type PointerDownEvent, type PointerDownSpec, type PointerIdentity, type PointerMoveEvent, type PointerRecognizer, type PointerRecognizerOptions, type PointerSample, type PointerSampleStylus, type PointerUpEvent, type PressFacts, type PressSample, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, RESERVED_SIGILS, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, type RecognizerClock, type RecognizerObserver, type RecognizerSink, type ReleaseFacts, type ReleaseOutcome, type RouteDescriptionPart, type RouteFieldName, type RoutePhase, type RouteTermLabel, TAP_THRESHOLD_PX, type TargetPredicate, type TargetSpec, type TargetSpecForm, UNKNOWN_MIME, VALID_MOD_NAMES, type WheelEvent, type WheelSpec, activatesFocusedControl, bodyPredicate, canonicalModifiers, clickEvents, collapseShiftPairs, createPointerRecognizer, describeRoute, describeRouteParts, fixedSeat, focusedControlOwnsKey, formatKeyRoute, formatPhaseAtom, formatRoute, getGestureDescriptor, heldPointers, hitPredicate, isApplePlatform, isEditableTarget, isInControlWithin, isKnownGestureName, keyRouteToSpec, longPressEvents, matchIngestTypes, matchKey, matchModifiers, matchPhase, matchSpec, matchTarget, mimeMatchesGlob, modifierComboToParsed, mods, multiTouchGeometry, nearestPortalHost, parseKeyRoute, parseRoute, parseTargetSpec, pastDragThreshold, routeGestureForSpecKind, routeToSpec, specKindForRouteGesture, specificity, stylusOf };
+export { ACTIVE_SIGILS, type BodyClassification, type BodyKind, type BodyTarget, CONTROL_SELECTOR, type CarryEvent, type CarrySpec, type ChannelRef, type ClaimableGesture, type ClickEvent, type ClickMemory, type ClickObserver, type ClickSpec, type ContextMenuEvent, type ContextMenuSpec, DOUBLE_CLICK_MAX_MS, DOUBLE_CLICK_MAX_PX, DRAG_THRESHOLD_PX, type DescribeRouteOptions, type DoubleClickBody, type DoubleClickEvent, type DoubleClickSpec, type DragSpec, type DropEvent, type DropSpec, type EventModifiers, type FixedSeat, type FormatShortcutOptions, GESTURE_DESCRIPTORS, type GestureArgSpec, type GestureDescriptor, type GestureName, type GestureSpec, type HeldPointers, type HeldPress, type HoverEvent, type HoverSpec, type HoverWhere, type IngestItem, type InputEvent, type KeyEvent, type KeyHeldEvent, type KeyHeldSpec, type KeyLabels, type KeyLegend, type KeySpec, type KeySpecsFromModsOptions, LONG_PRESS_MS, type LegendStyle, type LogicalMod, type LogicalModSpec, type LongPressEvent, type LongPressSpec, MODIFIER_LABELS, MOD_NAME_SET, type ModRequirement, type ModSpec, type ModifierCombo, type ModifierKey, type ModifiersEvent, type MultiTouchEvent, type MultiTouchGeometry, type MultiTouchSpec, type MultiTouchTapEvent, type MultiTouchTapSpec, type OptionalMod, type ParsedKeyRoute, type ParsedModifiers, type ParsedRoute, type PasteEvent, type PasteSpec, type PhaseAtom, type PhaseContext, type PhaseSpec, type PinchEvent, type PinchSpec, type Platform, type Point, type PointerCancelEvent, type PointerDownEvent, type PointerDownSpec, type PointerIdentity, type PointerMoveEvent, type PointerRecognizer, type PointerRecognizerOptions, type PointerSample, type PointerSampleStylus, type PointerUpEvent, type PressFacts, type PressSample, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, RESERVED_SIGILS, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, type RecognizerClock, type RecognizerObserver, type RecognizerSink, type ReleaseFacts, type ReleaseOutcome, type RouteDescriptionPart, type RouteFieldName, type RoutePhase, type RouteTermLabel, type ShortcutInput, TAP_THRESHOLD_PX, type TargetPredicate, type TargetSpec, type TargetSpecForm, UNKNOWN_MIME, VALID_MOD_NAMES, type WheelEvent, type WheelSpec, activatesFocusedControl, bodyPredicate, canonicalModifiers, clickEvents, collapseShiftPairs, createPointerRecognizer, describeRoute, describeRouteParts, detectPlatform, fixedSeat, focusedControlOwnsKey, formatKeyRoute, formatPhaseAtom, formatRoute, formatShortcut, formatShortcutParts, getGestureDescriptor, heldPointers, hitPredicate, isApplePlatform, isEditableTarget, isInControlWithin, isKnownGestureName, keyRouteToSpec, keySpecFromKey, keySpecsFromMods, keySpecsFromShortcut, longPressEvents, matchIngestTypes, matchKey, matchModifiers, matchPhase, matchSpec, matchTarget, mimeMatchesGlob, modifierComboToParsed, mods, multiTouchGeometry, nearestPortalHost, parseKeyRoute, parseRoute, parseTargetSpec, pastDragThreshold, routeGestureForSpecKind, routeToSpec, specKindForRouteGesture, specificity, stylusOf };

package/dist/index.js

@@ -18,6 +18,7 @@ var GESTURE_DESCRIPTORS = [
   // matches any payload, which is what an omitted arg slot means for a
   // `'free'` arg.
   { name: "drop", hasTarget: false, arg: { name: "types", values: "free" } },
+  { name: "carry", hasTarget: false, arg: { name: "types", values: "free" } },
   { name: "paste", hasTarget: false, arg: { name: "types", values: "free" } }
 ];
 var BY_NAME = new Map(
@@ -490,21 +491,25 @@ function matchSpec(e, spec, isMac, phaseCtx) {
       if (e.fingers !== spec.fingers) return false;
       return matchModifiers(e, spec.mods, isMac);
     }
-    case "drop": {
-      if (e.kind !== "drop") return false;
-      if (!matchIngestTypes(e.items, spec.types)) return false;
-      return matchModifiers(e, spec.mods, isMac);
-    }
-    case "paste": {
-      if (e.kind !== "paste") return false;
-      if (!matchIngestTypes(e.items, spec.types)) return false;
-      return matchModifiers(e, spec.mods, isMac);
-    }
+    case "drop":
+    case "carry":
+    case "paste":
+      return matchArrival(e, spec, isMac);
     default: {
       return false;
     }
   }
 }
+function matchArrival(e, spec, isMac) {
+  if (e.kind !== spec.kind) return false;
+  if (e.kind === "carry") {
+    if (e.stage !== "enter" && e.stage !== "drop") return false;
+    if (!matchIngestTypes([{ mime: e.type }], spec.types)) return false;
+  } else if (e.kind === "drop" || e.kind === "paste") {
+    if (!matchIngestTypes(e.items, spec.types)) return false;
+  }
+  return matchModifiers(e, spec.mods, isMac);
+}
 var EMPTY_ENGAGED = /* @__PURE__ */ new Set();
 
 // src/grammar/specKinds.ts
@@ -523,6 +528,7 @@ var SPEC_KIND_TO_GESTURE = {
   multiTouch: "multiTouch",
   multiTouchTap: "multiTouchTap",
   drop: "drop",
+  carry: "carry",
   paste: "paste"
 };
 var GESTURE_TO_SPEC_KIND = new Map(
@@ -593,6 +599,7 @@ function routeToSpec(parsed) {
       if (arg === void 0) return fail(`a ${kind} spec needs concrete fingers`);
       return withMods({ kind, fingers: Number(arg) });
     case "drop":
+    case "carry":
     case "paste":
       return withMods({ kind, ...arg ? { types: arg.split("|") } : {} });
   }
@@ -710,6 +717,8 @@ function actionClause(parsed, required) {
       return userDoes(required, `drags${target}`);
     case "drop":
       return userDoes(required, `drops ${arg ?? "any"} content onto the canvas`);
+    case "carry":
+      return userDoes(required, `carries ${arg ?? "anything"} onto the canvas`);
     case "paste":
       return userDoes(required, `pastes ${arg ?? "any"} content`);
   }
@@ -784,6 +793,115 @@ function isApplePlatform() {
   return /mac|iphone|ipad|ipod/i.test(raw);
 }
 
+// src/ui/keySpecsFromMods.ts
+var MOD_BY_PLATFORM = {
+  mod: {
+    macos: { auto: "\u2318", symbol: "\u2318", text: "Cmd" },
+    windows: { auto: "Ctrl", symbol: "\u2388", text: "Ctrl" },
+    linux: { auto: "Ctrl", symbol: "\u2388", text: "Ctrl" }
+  },
+  shift: {
+    macos: { auto: "\u21E7", symbol: "\u21E7", text: "Shift" },
+    windows: { auto: "\u21E7", symbol: "\u21E7", text: "Shift" },
+    linux: { auto: "\u21E7", symbol: "\u21E7", text: "Shift" }
+  },
+  // Off macOS the symbols are ISO/IEC 9995-7's: ⎈ for Control, ⎇ for Alt.
+  alt: {
+    macos: { auto: "\u2325", symbol: "\u2325", text: "Option" },
+    windows: { auto: "Alt", symbol: "\u2387", text: "Alt" },
+    linux: { auto: "Alt", symbol: "\u2387", text: "Alt" }
+  },
+  ctrl: {
+    macos: { auto: "\u2303", symbol: "\u2303", text: "Control" },
+    windows: { auto: "Ctrl", symbol: "\u2388", text: "Ctrl" },
+    linux: { auto: "Ctrl", symbol: "\u2388", text: "Ctrl" }
+  },
+  // Windows/Linux Meta has a recognized symbol on the physical key (⊞ Win
+  // logo / Super logo), so `auto` shows it. Use `text` for Win / Super.
+  meta: {
+    macos: { auto: "\u2318", symbol: "\u2318", text: "Cmd" },
+    windows: { auto: "\u229E", symbol: "\u229E", text: "Win" },
+    linux: { auto: "\u229E", symbol: "\u229E", text: "Super" }
+  }
+};
+var MODIFIER_LABELS = new Set(
+  Object.values(MOD_BY_PLATFORM).flatMap(
+    (byPlatform) => Object.values(byPlatform).flatMap((byLegend) => Object.values(byLegend))
+  )
+);
+function detectPlatform() {
+  if (typeof navigator === "undefined" || !navigator) return "macos";
+  if (isApplePlatform()) return "macos";
+  const nav = navigator;
+  const raw = nav.userAgentData?.platform || nav.platform || nav.userAgent || "";
+  return /\bwin/i.test(raw) ? "windows" : "linux";
+}
+function keySpecsFromMods(mods2, opts = {}) {
+  const platform = opts.platform ?? detectPlatform();
+  const legend = opts.legend ?? "auto";
+  return mods2.map((m) => {
+    const label = opts.labels?.[m.name] ?? MOD_BY_PLATFORM[m.name][platform][legend];
+    return m.optional ? { label, optional: true } : { label };
+  });
+}
+var NAMED_KEY = {
+  Escape: { macos: { auto: "\u238B", symbol: "\u238B", text: "Esc" }, windows: { auto: "Esc", symbol: "\u238B", text: "Esc" }, linux: { auto: "Esc", symbol: "\u238B", text: "Esc" } },
+  Enter: { macos: { auto: "\u21B5", symbol: "\u21B5", text: "Return" }, windows: { auto: "Enter", symbol: "\u21B5", text: "Enter" }, linux: { auto: "Enter", symbol: "\u21B5", text: "Enter" } },
+  Return: { macos: { auto: "\u21B5", symbol: "\u21B5", text: "Return" }, windows: { auto: "Enter", symbol: "\u21B5", text: "Enter" }, linux: { auto: "Enter", symbol: "\u21B5", text: "Enter" } },
+  Tab: { macos: { auto: "\u21E5", symbol: "\u21E5", text: "Tab" }, windows: { auto: "Tab", symbol: "\u21E5", text: "Tab" }, linux: { auto: "Tab", symbol: "\u21E5", text: "Tab" } },
+  Space: { macos: { auto: "\u2423", symbol: "\u2423", text: "Space" }, windows: { auto: "Space", symbol: "\u2423", text: "Space" }, linux: { auto: "Space", symbol: "\u2423", text: "Space" } },
+  " ": { macos: { auto: "\u2423", symbol: "\u2423", text: "Space" }, windows: { auto: "Space", symbol: "\u2423", text: "Space" }, linux: { auto: "Space", symbol: "\u2423", text: "Space" } },
+  Backspace: { macos: { auto: "\u232B", symbol: "\u232B", text: "Backspace" }, windows: { auto: "Backspace", symbol: "\u27F5", text: "Backspace" }, linux: { auto: "Backspace", symbol: "\u27F5", text: "Backspace" } },
+  Delete: { macos: { auto: "\u2326", symbol: "\u2326", text: "Delete" }, windows: { auto: "Delete", symbol: "\u2326", text: "Delete" }, linux: { auto: "Delete", symbol: "\u2326", text: "Delete" } },
+  // Context-menu key (the right-Ctrl-area key on Windows / Linux keyboards
+  // with a ▤ icon). Mac has no equivalent; falls back to text 'Menu'.
+  ContextMenu: { macos: { auto: "Menu", symbol: "Menu", text: "Menu" }, windows: { auto: "\u25A4", symbol: "\u25A4", text: "Menu" }, linux: { auto: "\u25A4", symbol: "\u25A4", text: "Menu" } },
+  // Symbol mode only: Apple's arrows for Home, End, and the page keys, and
+  // ISO/IEC 9995-7's symbols for the rest.
+  Home: { macos: { auto: "Home", symbol: "\u2196", text: "Home" }, windows: { auto: "Home", symbol: "\u2196", text: "Home" }, linux: { auto: "Home", symbol: "\u2196", text: "Home" } },
+  End: { macos: { auto: "End", symbol: "\u2198", text: "End" }, windows: { auto: "End", symbol: "\u2198", text: "End" }, linux: { auto: "End", symbol: "\u2198", text: "End" } },
+  PageUp: { macos: { auto: "PgUp", symbol: "\u21DE", text: "PgUp" }, windows: { auto: "PgUp", symbol: "\u21DE", text: "PgUp" }, linux: { auto: "PgUp", symbol: "\u21DE", text: "PgUp" } },
+  PageDown: { macos: { auto: "PgDn", symbol: "\u21DF", text: "PgDn" }, windows: { auto: "PgDn", symbol: "\u21DF", text: "PgDn" }, linux: { auto: "PgDn", symbol: "\u21DF", text: "PgDn" } },
+  PrintScreen: { macos: { auto: "PrtSc", symbol: "\u2399", text: "PrtSc" }, windows: { auto: "PrtSc", symbol: "\u2399", text: "PrtSc" }, linux: { auto: "PrtSc", symbol: "\u2399", text: "PrtSc" } },
+  Insert: { macos: { auto: "Ins", symbol: "\u2380", text: "Insert" }, windows: { auto: "Ins", symbol: "\u2380", text: "Insert" }, linux: { auto: "Ins", symbol: "\u2380", text: "Insert" } },
+  ScrollLock: { macos: { auto: "ScrLk", symbol: "\u21F3", text: "ScrLk" }, windows: { auto: "ScrLk", symbol: "\u21F3", text: "ScrLk" }, linux: { auto: "ScrLk", symbol: "\u21F3", text: "ScrLk" } },
+  Pause: { macos: { auto: "Pause", symbol: "\u2389", text: "Pause" }, windows: { auto: "Pause", symbol: "\u2389", text: "Pause" }, linux: { auto: "Pause", symbol: "\u2389", text: "Pause" } },
+  ArrowUp: { macos: { auto: "\u2191", symbol: "\u2191", text: "\u2191" }, windows: { auto: "\u2191", symbol: "\u2191", text: "\u2191" }, linux: { auto: "\u2191", symbol: "\u2191", text: "\u2191" } },
+  ArrowDown: { macos: { auto: "\u2193", symbol: "\u2193", text: "\u2193" }, windows: { auto: "\u2193", symbol: "\u2193", text: "\u2193" }, linux: { auto: "\u2193", symbol: "\u2193", text: "\u2193" } },
+  ArrowLeft: { macos: { auto: "\u2190", symbol: "\u2190", text: "\u2190" }, windows: { auto: "\u2190", symbol: "\u2190", text: "\u2190" }, linux: { auto: "\u2190", symbol: "\u2190", text: "\u2190" } },
+  ArrowRight: { macos: { auto: "\u2192", symbol: "\u2192", text: "\u2192" }, windows: { auto: "\u2192", symbol: "\u2192", text: "\u2192" }, linux: { auto: "\u2192", symbol: "\u2192", text: "\u2192" } }
+};
+function keySpecFromKey(raw, opts = {}) {
+  const platform = opts.platform ?? detectPlatform();
+  const legend = opts.legend ?? "auto";
+  const entry = NAMED_KEY[raw];
+  const override = opts.labels?.[raw] ?? (raw.length === 1 ? opts.labels?.[raw.toUpperCase()] : void 0);
+  const label = override ?? (entry ? entry[platform][legend] : raw.length === 1 ? raw.toUpperCase() : raw);
+  return opts.optional ? { label, optional: true } : { label };
+}
+
+// src/ui/keySpecsFromShortcut.ts
+function keySpecsFromShortcut(shortcut, opts = {}) {
+  if (!shortcut) return void 0;
+  const mods2 = [];
+  if (shortcut.mod) mods2.push({ name: "mod" });
+  if (shortcut.shift) mods2.push(shortcut.shift === "optional" ? { name: "shift", optional: true } : { name: "shift" });
+  if (shortcut.alt) mods2.push({ name: "alt" });
+  const key = typeof shortcut.key === "string" ? shortcut.key : shortcut.key[0];
+  const keys = keySpecsFromMods(mods2, opts);
+  return key === void 0 ? keys : [...keys, keySpecFromKey(key, opts)];
+}
+
+// src/ui/formatShortcut.ts
+var labels = (b, opts) => b ? keySpecsFromShortcut({ ...b, shift: b.shift === true }, opts)?.map((k) => k.label) : void 0;
+function formatShortcutParts(b, opts = {}) {
+  return labels(b, opts);
+}
+function formatShortcut(b, opts = {}) {
+  const platform = opts.platform ?? detectPlatform();
+  return platform === "macos" ? labels(b, { platform })?.join("") : labels(b, { platform, legend: "text" })?.join("+");
+}
+
 // src/ui/fixedSeat.ts
 var HOST_SELECTOR = "[data-wzl-portal-host],[data-wzl-theme],[data-wzl-mode]";
 function nearestPortalHost(from) {
@@ -849,7 +967,7 @@ function specificity(spec) {
   const mods2 = "mods" in spec ? spec.mods : void 0;
   const m = modsCount(mods2);
   const p = phaseRank("phase" in spec ? spec.phase : void 0);
-  const typed = (spec.kind === "drop" || spec.kind === "paste") && spec.types !== void 0 && spec.types.length > 0 ? 2 : 1;
+  const typed = (spec.kind === "drop" || spec.kind === "carry" || spec.kind === "paste") && spec.types !== void 0 && spec.types.length > 0 ? 2 : 1;
   return [t, m, p, typed];
 }
 
@@ -883,12 +1001,16 @@ function clickEvents(down, up) {
     x: up.worldX,
     y: up.worldY,
     clientX: up.clientX,
-    clientY: up.clientY,
-    ...pressedOn(down)
+    clientY: up.clientY
   };
+  const named = down.doubleClickBody;
   return {
-    click: { kind: "click", ...shared, pressX: down.worldX, pressY: down.worldY },
-    doubleclick: { kind: "doubleclick", ...shared }
+    click: { kind: "click", ...shared, ...pressedOn(down), pressX: down.worldX, pressY: down.worldY },
+    doubleclick: {
+      kind: "doubleclick",
+      ...shared,
+      ...pressedOn(named ? { affordance: down.affordance, ...named } : down)
+    }
   };
 }
 function longPressEvents(down) {
@@ -908,14 +1030,14 @@ function longPressEvents(down) {
 }
 
 // src/recognizer/click.ts
-function composeClick(down, up, clicks, now, dispatch, observer) {
+function composeClick(down, up, clicks, now, dispatch, observer, limits = { maxMs: DOUBLE_CLICK_MAX_MS, maxPx: DOUBLE_CLICK_MAX_PX }) {
   const evs = clickEvents(down, up);
   const world = { x: up.worldX, y: up.worldY };
   dispatch(evs.click);
   observer.click?.(world);
   const t = now();
   const prev = clicks.last;
-  const follows = prev !== null && t - prev.t < DOUBLE_CLICK_MAX_MS && Math.hypot(up.clientX - prev.clientX, up.clientY - prev.clientY) < DOUBLE_CLICK_MAX_PX;
+  const follows = prev !== null && t - prev.t < limits.maxMs && Math.hypot(up.clientX - prev.clientX, up.clientY - prev.clientY) < limits.maxPx;
   if (!follows) {
     clicks.last = { t, clientX: up.clientX, clientY: up.clientY };
     return {};
@@ -969,7 +1091,7 @@ function multiTouchGeometry(positions) {
     angle: Math.atan2(dy, dx) * 180 / Math.PI
   };
 }
-function createMultiTouchEpisode() {
+function createMultiTouchEpisode(tapPx = () => TAP_THRESHOLD_PX) {
   let episode = null;
   return {
     join(positions, centroid, now) {
@@ -990,14 +1112,14 @@ function createMultiTouchEpisode() {
     },
     moved(pointerId, to) {
       const from = episode?.joinedAt.get(pointerId);
-      if (episode && from && Math.hypot(to.x - from.x, to.y - from.y) > TAP_THRESHOLD_PX) episode.moved = true;
+      if (episode && from && Math.hypot(to.x - from.x, to.y - from.y) > tapPx()) episode.moved = true;
     },
     finish(centroid, now, maxHoldMs) {
       const e = episode;
       episode = null;
       if (!e) return null;
       const brief = now - e.startedAt < maxHoldMs;
-      const still = Math.hypot(centroid.x - e.centroid.x, centroid.y - e.centroid.y) <= TAP_THRESHOLD_PX;
+      const still = Math.hypot(centroid.x - e.centroid.x, centroid.y - e.centroid.y) <= tapPx();
       return brief && !e.moved && still ? e.fingers : null;
     },
     abandon() {
@@ -1018,7 +1140,8 @@ function pressFactsOf(s) {
     worldX: s.x,
     worldY: s.y,
     ...modifiersOf(s),
-    ...pressedOn(s)
+    ...pressedOn(s),
+    ...s.doubleClickBody !== void 0 ? { doubleClickBody: s.doubleClickBody } : {}
   };
 }
 var at = (s, world) => ({
@@ -1057,16 +1180,27 @@ function fireLongPress(rec, sink, observer) {
   rec.buffered = null;
   if (rec.holdType) observer.longPress?.(rec.holdType);
 }
+function thresholdsOf(opts) {
+  return {
+    longPressMs: () => opts.longPressMs?.() ?? LONG_PRESS_MS,
+    tapPx: () => opts.tapPx?.() ?? TAP_THRESHOLD_PX,
+    dragPx: () => opts.dragPx?.() ?? DRAG_THRESHOLD_PX,
+    doubleClick: () => ({
+      maxMs: opts.doubleClickMs?.() ?? DOUBLE_CLICK_MAX_MS,
+      maxPx: opts.doubleClickPx?.() ?? DOUBLE_CLICK_MAX_PX
+    })
+  };
+}
 function createPointerRecognizer(opts) {
   const { sink, clock, observer = {}, toSurface = (p) => p } = opts;
   const world = (s) => opts.toWorld?.(s.clientX, s.clientY) ?? { x: s.clientX, y: s.clientY };
   const clicks = opts.clicks ?? { last: null };
   const held = /* @__PURE__ */ new Map();
-  const touches = createMultiTouchEpisode();
+  const { longPressMs, tapPx, dragPx, doubleClick } = thresholdsOf(opts);
+  const touches = createMultiTouchEpisode(tapPx);
   const hold = createLongPressHold(clock, (pending) => {
     observer.holdChanged?.(pending);
   });
-  const longPressMs = () => opts.longPressMs?.() ?? LONG_PRESS_MS;
   const geometry = (extra = []) => heldGeometry(held, toSurface, extra);
   const claimForMultiTouch = (mods2) => {
     hold.cancel();
@@ -1097,7 +1231,7 @@ function createPointerRecognizer(opts) {
       const to = { x: s.clientX, y: s.clientY };
       if (rec) rec.pos = to;
       touches.moved(s.pointerId, to);
-      if (rec?.buffered && pastDragThreshold(rec.down, s)) {
+      if (rec?.buffered && pastDragThreshold(rec.down, s, dragPx())) {
         const press = rec.buffered;
         rec.buffered = null;
         hold.cancel(s.pointerId);
@@ -1133,7 +1267,7 @@ function createPointerRecognizer(opts) {
         worldY: at2.y,
         ...modifiersOf(s)
       };
-      return composeClick(rec.down, up, clicks, () => clock.now(), (ev) => sink.dispatch(ev), observer);
+      return composeClick(rec.down, up, clicks, () => clock.now(), (ev) => sink.dispatch(ev), observer, doubleClick());
     },
     cancel(pointerId) {
       const rec = held.get(pointerId);
@@ -1287,6 +1421,6 @@ function focusedControlOwnsKey(e) {
   return activatesFocusedControl(e) || selectOwnsKey(e);
 }
 
-export { ACTIVE_SIGILS, CONTROL_SELECTOR, DOUBLE_CLICK_MAX_MS, DOUBLE_CLICK_MAX_PX, DRAG_THRESHOLD_PX, GESTURE_DESCRIPTORS, LONG_PRESS_MS, MOD_NAME_SET, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, RESERVED_SIGILS, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, TAP_THRESHOLD_PX, UNKNOWN_MIME, VALID_MOD_NAMES, activatesFocusedControl, bodyPredicate, canonicalModifiers, clickEvents, collapseShiftPairs, createPointerRecognizer, describeRoute, describeRouteParts, fixedSeat, focusedControlOwnsKey, formatKeyRoute, formatPhaseAtom, formatRoute, getGestureDescriptor, heldPointers, hitPredicate, isApplePlatform, isEditableTarget, isInControlWithin, isKnownGestureName, keyRouteToSpec, longPressEvents, matchIngestTypes, matchKey, matchModifiers, matchPhase, matchSpec, matchTarget, mimeMatchesGlob, modifierComboToParsed, mods, multiTouchGeometry, nearestPortalHost, parseKeyRoute, parseRoute, parseTargetSpec, pastDragThreshold, routeGestureForSpecKind, routeToSpec, specKindForRouteGesture, specificity, stylusOf };
+export { ACTIVE_SIGILS, CONTROL_SELECTOR, DOUBLE_CLICK_MAX_MS, DOUBLE_CLICK_MAX_PX, DRAG_THRESHOLD_PX, GESTURE_DESCRIPTORS, LONG_PRESS_MS, MODIFIER_LABELS, MOD_NAME_SET, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, RESERVED_SIGILS, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, TAP_THRESHOLD_PX, UNKNOWN_MIME, VALID_MOD_NAMES, activatesFocusedControl, bodyPredicate, canonicalModifiers, clickEvents, collapseShiftPairs, createPointerRecognizer, describeRoute, describeRouteParts, detectPlatform, fixedSeat, focusedControlOwnsKey, formatKeyRoute, formatPhaseAtom, formatRoute, formatShortcut, formatShortcutParts, getGestureDescriptor, heldPointers, hitPredicate, isApplePlatform, isEditableTarget, isInControlWithin, isKnownGestureName, keyRouteToSpec, keySpecFromKey, keySpecsFromMods, keySpecsFromShortcut, longPressEvents, matchIngestTypes, matchKey, matchModifiers, matchPhase, matchSpec, matchTarget, mimeMatchesGlob, modifierComboToParsed, mods, multiTouchGeometry, nearestPortalHost, parseKeyRoute, parseRoute, parseTargetSpec, pastDragThreshold, routeGestureForSpecKind, routeToSpec, specKindForRouteGesture, specificity, stylusOf };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map