@weasel-js/gestures 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,669 @@
+/**
+ * Declarative gesture taxonomy. Single source of truth for:
+ *   - which gestures hit-test (have a `.target` slot in the route string)
+ *   - which gestures carry an argument and what values are legal
+ *   - the default arg value (used when none is specified in a route)
+ *
+ * Reflection, matcher, and inspector UI all read this table. Adding a new
+ * gesture name in one place updates every consumer.
+ */
+type GestureName = 'click' | 'pointerDown' | 'dblTap' | 'drag' | 'wheel' | 'keyDown' | 'keyUp' | 'keyHeld' | 'contextMenu' | 'multiTouchTap';
+interface GestureArgSpec {
+    /** Display name for the arg in inspector chips (`direction`, `key`, `fingers`). */
+    name: string;
+    /** Acceptable values. `'free'` means any string (e.g. key names). */
+    values: readonly string[] | 'free';
+    /** Default value when a route omits the arg slot. Must be in `values`
+     *  unless `values === 'free'`. Optional: no default means routes that
+     *  omit the arg slot match every value (only legal for `'free'` args). */
+    default?: string;
+}
+interface GestureDescriptor {
+    name: GestureName;
+    /** Does the route's `.target` slot apply? Targetless gestures (`wheel`,
+     *  `keyDown/Up`, `multiTouchTap`) elide it entirely in the v2 grammar. */
+    hasTarget: boolean;
+    /** Optional argument spec. Encoded as `gesture(value)` in the route string. */
+    arg?: GestureArgSpec;
+}
+declare const GESTURE_DESCRIPTORS: readonly GestureDescriptor[];
+declare function getGestureDescriptor(name: GestureName): GestureDescriptor;
+declare function isKnownGestureName(name: string): name is GestureName;
+
+/** All valid keys for a modifier sub-table in a route entry. Canonical
+ *  order: mod → shift → alt (matches formatShortcut). */
+type ModifierCombo = 'default' | 'mod' | 'shift' | 'alt' | 'mod+shift' | 'mod+alt' | 'shift+alt' | 'mod+shift+alt';
+/** Convenience: produce the canonical ModifierCombo from modifiers passed
+ *  in any order. Useful in computed property syntax:
+ *
+ *  ```ts
+ *  'rect': {
+ *    [mods('shift')]:        addToSelection,
+ *    [mods('alt', 'shift')]: cloneAndAdd,    // → 'shift+alt'
+ *  }
+ *  ```
+ */
+declare function mods(...keys: ReadonlyArray<'mod' | 'shift' | 'alt'>): ModifierCombo;
+
+/** Phase of a gesture lifecycle. `initial` means the tool is idle
+ *  (scratch null); `engaged` means a gesture is in progress (scratch
+ *  populated). The route-grammar's `[phase]` slot draws from this set. */
+type RoutePhase = 'initial' | 'engaged';
+
+/**
+ * Route-string grammar v3:
+ *
+ *   route       = phaseSlot WS gesture WS argSlot? WS targetSlot? WS modSlot?
+ *   phaseSlot   = '[' phaseList ']'
+ *   phaseList   = phaseAtom (WS ',' WS phaseAtom)*
+ *   phaseAtom   = (channel ':')? phaseValue            -- bare phaseValue ≡ '&:phaseValue'
+ *   channel     = '&' | '*' | toolId                   -- '&' = the binding's own tool
+ *   phaseValue  = 'initial' | 'engaged' | '*'
+ *   argSlot     = '(' argValue ')'                     -- whitespace inside parens is significant
+ *   targetSlot  = '=>' WS targetValue                  -- omitted slot defaults to '*' for hasTarget
+ *   modSlot     = modAtom (WS modAtom)*
+ *   modAtom     = sigil modName
+ *   sigil       = '+' | '?'                            -- ! @ # $ % ^ & * reserved as id-prefix
+ *   modName     = 'mod' | 'shift' | 'alt' | 'ctrl' | 'meta'
+ *
+ * Shorthand: a bare phaseValue (no `:`) implies channel `&` ("this tool's
+ * own phase"). `[engaged]` ≡ `[&:engaged]`; `[*]` ≡ `[&:*]`. The truly-loose
+ * form (any channel, any phase) is `[*:*]`.
+ *
+ * Examples:
+ *   [initial] click => empty +shift            -- self idle
+ *   [engaged] wheel                            -- self mid-gesture
+ *   [rect:engaged] wheel                        -- when rect tool is mid-gesture
+ *   [*:engaged] keyDown(Delete)                -- when any tool is mid-gesture
+ *   [initial,engaged] contextMenu => empty     -- either self phase
+ *   [*] click => empty                         -- self, any phase
+ */
+
+/** Channel reference for a phase atom. `'&'` = the binding's own tool;
+ *  `'*'` = any tool; otherwise a registered tool id. */
+type ChannelRef = '&' | '*' | string;
+/** One element of a phase list: a (channel, phase) pair. The default
+ *  channel (omitted in the shorthand) is `'&'`. `phase: '*'` means
+ *  "any phase of the given channel". */
+interface PhaseAtom {
+    channel: ChannelRef;
+    phase: RoutePhase | '*';
+}
+/** Reserved id-prefix sigils. Tool ids, action ids, channel names, target
+ *  kinds, and arg values may not start with any of these — keeps the
+ *  parser unambiguous and reserves single-char prefixes for future grammar
+ *  extensions. */
+declare const RESERVED_ID_PREFIXES: ReadonlySet<string>;
+/** Reserved bareword channel/id names. These are keywords in the phase
+ *  slot — a tool may not register with one of these as its id (collides
+ *  with the bare-phase shorthand). */
+declare const RESERVED_ID_NAMES: ReadonlySet<string>;
+/** v3 modifier requirement on a single modifier key. Absent from a
+ *  `ParsedModifiers` map means "must not be held" (the strict default). */
+type ModRequirement = 'required' | 'optional';
+/** Canonical modifier names accepted in the modSlot, in canonical order.
+ *  Single source of truth: the {@link ModifierKey} type and the runtime
+ *  validator (`MOD_NAME_SET`) are both derived from this tuple. */
+declare const VALID_MOD_NAMES: readonly ["mod", "shift", "alt", "ctrl", "meta"];
+/** A single modifier name accepted in the modSlot. */
+type ModifierKey = (typeof VALID_MOD_NAMES)[number];
+/** Parsed-form modifiers — structured map; absent keys are implicitly
+ *  forbidden. Empty object = "no modifiers held". */
+type ParsedModifiers = Partial<Record<ModifierKey, ModRequirement>>;
+/** Reserved sigil characters. The parser rejects any of these with a
+ *  "reserved for future use" error so introducing them later is
+ *  non-breaking. `*` is NOT in this set — it's the universal wildcard. */
+declare const RESERVED_SIGILS: ReadonlySet<string>;
+/** Active (parseable) sigils today: `+` required, `?` optional. */
+declare const ACTIVE_SIGILS: ReadonlySet<string>;
+declare const MOD_NAME_SET: ReadonlySet<string>;
+
+/** v3 parsed-route shape. */
+interface ParsedRoute {
+    /** One or more phase atoms (channel + phase). Empty array is invalid.
+     *  Bare-phase shorthand in the source string desugars to channel `'&'`,
+     *  so `[engaged]` parses to `[{ channel: '&', phase: 'engaged' }]`. */
+    phases: readonly PhaseAtom[];
+    gesture: GestureName;
+    /** Resolved arg. For arg-bearing gestures, the descriptor's default
+     *  fills in when the slot is omitted (e.g. `wheel` → `arg: '*'`).
+     *  Undefined for gestures whose descriptor has no `arg`. */
+    arg: string | undefined;
+    /** For hasTarget gestures: target string with `'*'` as the wildcard
+     *  sentinel. Defaults to `'*'` when the slot is omitted. Undefined for
+     *  hasTarget=false gestures. */
+    target: string | undefined;
+    /** Structured modifier requirements; empty map = "no modifiers held". */
+    modifiers: ParsedModifiers;
+}
+declare function parseRoute(input: string): ParsedRoute;
+/** Render a single phase atom in canonical shorthand form. `&` channel
+ *  is elided ("`engaged`", "`*`"); other channels use the explicit
+ *  `channel:phase` form ("`rect:engaged`", "`*:*`"). */
+declare function formatPhaseAtom(a: PhaseAtom): string;
+/** Visual-collapse pass: given a list of route strings, fold pairs that
+ *  differ ONLY in `shift` presence (one has `+shift`, the other doesn't,
+ *  everything else identical) into a single route with `?shift`. Useful
+ *  for inspector / palette displays that want to show "Cmd+[" and
+ *  "Cmd+Shift+[" as one Cmd+?Shift+[ chip rather than two rows.
+ *
+ *  Preserves input order — the first member of each fold-pair holds the
+ *  position; the second is dropped. Routes that don't have a `+shift`
+ *  vs absent twin pass through unchanged. Does NOT fold other modifier
+ *  pairs (alt/ctrl/meta/mod) — those tend to carry meaning across the
+ *  same key (e.g., Cmd+Z vs Cmd+Shift+Z are usually two distinct
+ *  actions, but Cmd+] vs Cmd+Shift+] is more often parametric variation
+ *  of one action). Open the helper if a use case for the other
+ *  modifiers shows up.
+ */
+declare function collapseShiftPairs(routes: readonly string[]): string[];
+declare function formatRoute(r: ParsedRoute): string;
+
+/**
+ * GestureSpec — describes the form of a user input event that can fire an action.
+ *
+ * Used by `Action.defaultBinding` (the action's preferred gesture) and by
+ * `GestureBinding.spec` (a tool's binding table entry). The dispatcher matches
+ * incoming input events against registered specs to determine which action to
+ * invoke.
+ *
+ * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md` § "Types".
+ */
+/** Optional modifier-key requirement for a gesture spec.
+ *
+ *  Matching semantics (strict): an omitted modifier field means the
+ *  modifier MUST NOT be held — i.e., a bare `{ kind: 'key', key: 'Escape' }`
+ *  matches only unmodified Escape, NOT Cmd+Escape. A `true` means the
+ *  modifier MUST be held; `false` is the same as omitted (must be absent).
+ *  This mirrors today's `KeyBinding` matcher and keeps conflict detection
+ *  coherent.
+ *
+ *  `mod` is a platform-aware shorthand: matches `metaKey` on mac, `ctrlKey`
+ *  elsewhere (mirrors `KeyBinding.mod`).
+ *
+ *  `shift` additionally accepts `'optional'` meaning "shifted or unshifted
+ *  both acceptable" — the explicit opt-in for loose matching, used by
+ *  actions like nudge whose step size depends on shift but whose firing
+ *  does not. To widen other modifiers similarly, extend their type when
+ *  a real consumer needs it.
+ */
+type ModSpec = Partial<{
+    alt: boolean | 'optional';
+    ctrl: boolean | 'optional';
+    meta: boolean | 'optional';
+    mod: boolean | 'optional';
+    shift: boolean | 'optional';
+}>;
+/** Target selector for click and drag gesture specs. String forms are sugar
+ *  for the kit-owned object-kind registry (TODO.md Tier 1 follow-up); until
+ *  that ships, consumers can pass `{ kindOf: predicate }` to classify hits
+ *  themselves. */
+type TargetSpec = 'empty' | 'selected-body' | 'unselected-body' | `kind:${string}` | `kind:${string}:selected` | `affordance:${string}` | {
+    /** Predicate. `hit` is the raw target (affordance for drag,
+     *  `e.target` otherwise); `bodyTarget` is the optional body-class
+     *  string ('empty' | 'selected-body' | 'unselected-body') when
+     *  `classifyTarget` is wired. Predicates that only need one of the
+     *  two can ignore the other. */
+    kindOf: (hit: unknown, bodyTarget?: string) => boolean;
+};
+/** Phase qualifier on a gesture spec. Restricts when the spec matches based
+ *  on per-tool gesture-lifecycle state.
+ *
+ *  Shorthand forms (most common case — gate on the binding's own tool):
+ *    `'engaged'` → `[{ channel: '&', phase: 'engaged' }]`  // self mid-gesture
+ *    `'initial'` → `[{ channel: '&', phase: 'initial' }]`  // self idle
+ *    `'*'`       → `[{ channel: '&', phase: '*' }]`        // either self phase
+ *
+ *  Array form for explicit channel:phase atoms — e.g. `[{ channel: 'rect',
+ *  phase: 'engaged' }]` for "when the rect tool is mid-gesture, regardless of
+ *  which scope I'm in." See the v3 route grammar in
+ *  `@weasel-js/gestures/grammar` for the full lattice.
+ *
+ *  When omitted, matches in any phase (preserves pre-phase behavior). */
+type PhaseSpec = 'initial' | 'engaged' | '*' | readonly PhaseAtom[];
+/** Single-keystroke gesture (keydown). */
+interface KeySpec {
+    kind: 'key';
+    /** A single key, or an array of acceptable keys (case-insensitive match). */
+    key: string | string[];
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Key-held gesture (keydown opens, keyup closes). Drives "hold space for
+ *  hand tool"-style interactions. */
+interface KeyHeldSpec {
+    kind: 'key-held';
+    /** A single key, or an array of acceptable keys (case-insensitive match). */
+    key: string | string[];
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Wheel-event gesture. `direction` filters by deltaY sign; default `'*'`.
+ *  - `'up'`   → matches only deltaY < 0
+ *  - `'down'` → matches only deltaY > 0
+ *  - `'*'`    → matches either sign (default; universal-wildcard convention) */
+interface WheelSpec {
+    kind: 'wheel';
+    direction?: 'up' | 'down' | '*';
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Click gesture (pointerdown + pointerup without movement past the
+ *  threshold). */
+interface ClickSpec {
+    kind: 'click';
+    target?: TargetSpec;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Double-click: two `click` events within ~500ms and ~5px of each other.
+ *  Synthesized by `useGestureDispatcher`; emitted AFTER the second
+ *  `click`. Bindings that want to handle a double-click should declare
+ *  this kind rather than chasing two `click` events. */
+interface DoubleClickSpec {
+    kind: 'doubleClick';
+    target?: TargetSpec;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Right-click (contextmenu) gesture. The dispatcher calls
+ *  `preventDefault()` on the underlying DOM event so the native menu
+ *  doesn't appear — tools/actions fully own the right-click UX. */
+interface ContextMenuSpec {
+    kind: 'contextMenu';
+    target?: TargetSpec;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Drag gesture (pointerdown + pointermove past the threshold). */
+interface DragSpec {
+    kind: 'drag';
+    target?: TargetSpec;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Multi-touch gesture. `fingers` is the required touch count. */
+interface MultiTouchSpec {
+    kind: 'multiTouch';
+    fingers: number;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** Multi-touch tap gesture — fires when N fingers touch down then release
+ *  together without movement past the tap threshold. Synthesized by the
+ *  dispatcher from the underlying multitouch tracking. */
+interface MultiTouchTapSpec {
+    kind: 'multiTouchTap';
+    fingers: number;
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** OS drag-and-drop of external content onto the canvas. `types` filters by
+ *  MIME glob (`'image/*'`, `'text/plain'`); the spec matches when ANY item's
+ *  MIME matches ANY glob. Omitted or empty = matches any drop. */
+interface DropSpec {
+    kind: 'drop';
+    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 {
+    kind: 'paste';
+    types?: string[];
+    mods?: ModSpec;
+    phase?: PhaseSpec;
+}
+/** The full union of supported gesture spec kinds. New invocation forms
+ *  (long-press, two-stage, modal-dialog) extend this union without touching
+ *  the `Action` type. */
+type GestureSpec = KeySpec | KeyHeldSpec | WheelSpec | ClickSpec | DoubleClickSpec | ContextMenuSpec | DragSpec | MultiTouchSpec | MultiTouchTapSpec | DropSpec | PasteSpec;
+
+/**
+ * Mini-grammar for the `arg` slot of `keyDown` / `keyUp` routes.
+ *
+ *   keyRoute    = key ('?' optionalMod)*
+ *   optionalMod = 'mod' | 'shift' | 'alt' | 'ctrl' | 'meta'
+ *
+ * `?shift` means "shift may or may not be held; either fires this route."
+ * Required modifiers still belong in the route's `:modifiers` slot — this
+ * grammar only widens which events match, never narrows.
+ */
+
+/** An optional modifier in a key route — the same set as the canonical
+ *  {@link ModifierKey}. */
+type OptionalMod = ModifierKey;
+interface ParsedKeyRoute {
+    key: string;
+    optionalMods: readonly OptionalMod[];
+}
+declare function parseKeyRoute(input: string): ParsedKeyRoute;
+declare function formatKeyRoute(r: ParsedKeyRoute): string;
+/** Build a runtime KeySpec from a parsed key route. Each optional modifier
+ *  becomes `mods.<name>: 'optional'`. The matcher's `matchModifiers`
+ *  honors `'optional'` uniformly across `mod`, `shift`, `alt`, `ctrl`,
+ *  and `meta`. */
+declare function keyRouteToSpec(r: ParsedKeyRoute): KeySpec;
+
+/** Glossary for route-vocabulary terms surfaced by `describeRouteParts`.
+ *  Exposed so docs / inspector UIs can render the same definitions. */
+declare const ROUTE_TERMS: {
+    readonly idle: "Not in the middle of a drag or other synchronous operation.";
+    readonly 'mid-gesture': "In the middle of a drag or other synchronous operation.";
+};
+/** Per-field explanations for the slots of a parsed route. Exposed so
+ *  inspector UIs / docs can describe what each setting in a route table
+ *  means without duplicating prose. */
+declare const ROUTE_FIELD_DEFINITIONS: {
+    readonly phases: "Which lifecycle stage(s) a channel must be in for this route to fire. `initial` = the channel is idle; `engaged` = the channel is mid-gesture. The channel is the binding's own tool (`&`), any tool (`*`), or a named tool id.";
+    readonly gesture: "The class of input event that triggers this route — click, drag, double-tap, keyDown/keyUp, wheel, contextMenu, or multiTouchTap.";
+    readonly arg: "Sub-class of the gesture. Direction for wheel (up / down / *), key name for keyDown / keyUp, finger count for multiTouchTap. Other gestures have no arg slot.";
+    readonly target: "Which hit-test result the gesture must land on. `*` matches any target; `empty` matches the empty canvas; otherwise the value names a specific hit-target kind.";
+    readonly modifiers: "Modifier keys the user must hold (`+key`) or may optionally hold (`?key`) for this route to match. Unlisted modifiers must not be held.";
+};
+type RouteFieldName = keyof typeof ROUTE_FIELD_DEFINITIONS;
+type RouteTermLabel = keyof typeof ROUTE_TERMS;
+/** A part of a structured route description. `string` parts are plain prose;
+ *  `term` parts carry a glossary lookup so renderers can attach tooltips. */
+type RouteDescriptionPart = string | {
+    kind: 'term';
+    label: RouteTermLabel;
+    definition: string;
+};
+interface DescribeRouteOptions {
+    /** Capitalize the first letter of the result. Default true. */
+    capitalize?: boolean;
+    /** Trailing period. Default true. */
+    period?: boolean;
+}
+/** Structured description of when a parsed route fires. Returns an array of
+ *  prose strings interspersed with `term` parts (e.g. `idle`, `mid-gesture`)
+ *  so React-based renderers can attach hover-definition tooltips. Use
+ *  `describeRoute()` for a plain-string version. */
+declare function describeRouteParts(parsed: ParsedRoute, opts?: DescribeRouteOptions): readonly RouteDescriptionPart[];
+/** Plain-spoken English summary of when a parsed route fires. Intended for
+ *  developer-facing documentation. Term parts collapse to their label only
+ *  (e.g. `idle`); use `describeRouteParts()` if you want to expose the
+ *  glossary definitions in your renderer. */
+declare function describeRoute(parsed: ParsedRoute, opts?: DescribeRouteOptions): string;
+
+/** Translate the tool-authoring `ModifierCombo` enum (positional string,
+ *  e.g. `'mod+shift'`) to the v3 `ParsedModifiers` structured map
+ *  (every listed modifier becomes `'required'`; unlisted means
+ *  forbidden / absent). `'default'` yields `{}`. */
+declare function modifierComboToParsed(key: ModifierCombo): ParsedModifiers;
+/** Stable canonical serialization of a ParsedModifiers map for use as a
+ *  hash key (conflicts dedup). Sorts mod names alphabetically and emits
+ *  `name=req` pairs joined by `&`. */
+declare function canonicalModifiers(mods: ParsedModifiers): string;
+
+/**
+ * Keyboard/pointer modifier flags carried by every {@link InputEvent} arm.
+ * Factored out so the four booleans are documented once instead of repeated
+ * on all twelve event shapes.
+ */
+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
+ * options, and read by `matchTarget` to resolve string-form `TargetSpec`
+ * values. Absent when `classifyTarget` is not wired.
+ */
+type BodyTarget = 'empty' | 'selected-body' | 'unselected-body';
+/** A keystroke. */
+interface KeyEvent extends EventModifiers {
+    kind: 'key';
+    key: string;
+    repeat?: boolean;
+}
+/** A held key transitioning down or up (e.g. space-to-pan). */
+interface KeyHeldEvent extends EventModifiers {
+    kind: 'key-held';
+    key: string;
+    phase: 'down' | 'up';
+}
+/** A scroll-wheel / trackpad scroll, with raw deltas and client coords. */
+interface WheelEvent extends EventModifiers {
+    kind: 'wheel';
+    deltaX: number;
+    deltaY: number;
+    clientX: number;
+    clientY: number;
+}
+/** A pointer press — the start of any drag, and the richest event shape. */
+interface PointerDownEvent extends EventModifiers {
+    kind: 'pointerdown';
+    target?: unknown;
+    /** World-space coordinates (post view transform). */
+    x?: number;
+    y?: number;
+    /**
+     * Client/screen-space coordinates (raw DOM event). Required for any drag
+     * action whose effect mutates the view itself — world coords shift
+     * mid-gesture and produce self-referential deltas.
+     */
+    clientX?: number;
+    clientY?: number;
+    /** Generic affordance payload (the kit narrows this to `AffordanceHit`). */
+    affordance?: unknown;
+    bodyTarget?: BodyTarget;
+}
+/** A pump-only pointer move. Carried in the union so the dispatcher's
+ *  `handleInput` signature stays uniform; the matcher never matches it. */
+interface PointerMoveEvent extends EventModifiers {
+    kind: 'pointermove';
+    x: number;
+    y: number;
+    clientX?: number;
+    clientY?: number;
+}
+/** A pump-only pointer release. Not matched by the matcher. */
+interface PointerUpEvent extends EventModifiers {
+    kind: 'pointerup';
+    x: number;
+    y: number;
+    clientX?: number;
+    clientY?: number;
+}
+/** A pump-only pointer cancel. Not matched by the matcher. */
+interface PointerCancelEvent extends EventModifiers {
+    kind: 'pointercancel';
+}
+/** A click (down+up on the same target). */
+interface ClickEvent extends EventModifiers {
+    kind: 'click';
+    target?: unknown;
+    /**
+     * World-space coordinates of the click, derived via the `clientToWorld`
+     * thunk supplied to the dispatcher. Absent when the thunk isn't wired.
+     * Forwarded into action params so click invokers can act on the click's
+     * position without their own pointer-listener plumbing.
+     */
+    worldX?: number;
+    worldY?: number;
+    bodyTarget?: BodyTarget;
+}
+/** A double click. `worldX`/`worldY` carry the same meaning as on {@link ClickEvent}. */
+interface DoubleClickEvent extends EventModifiers {
+    kind: 'doubleclick';
+    target?: unknown;
+    worldX?: number;
+    worldY?: number;
+    bodyTarget?: BodyTarget;
+}
+/** A context-menu (right-click) request. */
+interface ContextMenuEvent extends EventModifiers {
+    kind: 'contextmenu';
+    target?: unknown;
+    bodyTarget?: BodyTarget;
+}
+/** A running multitouch gesture (e.g. pinch/rotate). */
+interface MultitouchEvent extends EventModifiers {
+    kind: 'multitouch';
+    fingers: number;
+    /**
+     * Centroid of active pointers in screen space. Populated by
+     * `useGestureDispatcher` on the pointermove-pump of a running multitouch
+     * handle (updated each frame). Absent on the initial pointerdown-triggered
+     * multitouch event.
+     */
+    centroid?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Distance between the two primary pointers (screen space). Populated on
+     * move-pump events alongside `centroid`. Absent on the initial event.
+     */
+    spread?: number;
+}
+/** A multi-finger tap (no drag). */
+interface MultitouchTapEvent extends EventModifiers {
+    kind: 'multitouchtap';
+    fingers: number;
+}
+/**
+ * One piece of external content arriving via OS drop, clipboard paste, or a
+ * file picker — fully materialized (string contents already read), so it is
+ * safe to hold past the originating DOM event. `File` is a lib.dom type;
+ * no runtime DOM dependency.
+ */
+type IngestItem = {
+    kind: 'file';
+    mime: string;
+    file: File;
+} | {
+    kind: 'string';
+    mime: string;
+    text: string;
+};
+/** External content dropped onto the canvas (OS drag-and-drop). */
+interface DropEvent extends EventModifiers {
+    kind: 'drop';
+    items: readonly IngestItem[];
+    /** World-space drop point (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';
+    items: readonly IngestItem[];
+}
+/**
+ * Normalized input-event shape consumed by the pure matcher. Built by the
+ * React seam (`useGestureDispatcher`) from DOM events. Pump-only events
+ * ({@link PointerMoveEvent}, {@link PointerUpEvent}, {@link PointerCancelEvent})
+ * ride in the same union so the dispatcher's `handleInput` signature stays
+ * uniform; the matcher itself never matches them.
+ *
+ * The `affordance?` field on {@link PointerDownEvent} is widened to `unknown`
+ * in this package — the kit narrows it back to `AffordanceHit` at consumption.
+ * This keeps `@weasel-js/gestures` free of any kit-affordance type.
+ */
+type InputEvent = KeyEvent | KeyHeldEvent | WheelEvent | PointerDownEvent | PointerMoveEvent | PointerUpEvent | PointerCancelEvent | ClickEvent | DoubleClickEvent | ContextMenuEvent | MultitouchEvent | MultitouchTapEvent | DropEvent | PasteEvent;
+
+/**
+ * Pure gesture matcher — no React, no state, no DOM.
+ *
+ * The kit's dispatcher orchestrator wraps these primitives with its
+ * actions-layer concerns (BindingScope, ScopedBinding, MatchResult, matchBest).
+ *
+ * ## key-held phase decision
+ * `matchSpec` returns `true` only for `phase: 'down'`, not `phase: 'up'`.
+ * The dispatcher tracks the held key independently and handles the `up` phase
+ * itself; the matcher never sees an "un-match" it needs to distinguish.
+ * This keeps the matcher's output a simple boolean and avoids a three-valued
+ * return type.
+ *
+ * ## TargetSpec string-form decision
+ * String-form TargetSpec values ('empty', 'selected-body', `kind:*`, etc.) are
+ * sugar for the kit-owned object-kind registry, which hasn't shipped yet
+ * (see docs/TODO.md Tier 1). Phase 3 returns `false` for any string-form
+ * target spec so that callers get an explicit no-match rather than a silent
+ * wildcard or a runtime throw.
+ */
+
+type ModifiersEvent = {
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+};
+/**
+ * Strict modifier match.
+ *
+ * - Omitted modifier MUST NOT be held.
+ * - `true`       MUST be held.
+ * - `false`      MUST NOT be held (same as omitted; both forms accepted for clarity).
+ * - `'optional'` accepts either held or unheld. Supported on every modifier
+ *   (`alt`, `ctrl`, `meta`, `mod`, `shift`).
+ * - `mod` is platform-aware: matches `metaKey` on mac, `ctrlKey` elsewhere.
+ *   When `mod` is set, the corresponding `meta`/`ctrl` field is implied AND
+ *   the *other* platform key is forbidden. Callers should not combine `mod`
+ *   with `meta`/`ctrl`.
+ */
+declare function matchModifiers(e: ModifiersEvent, mods: ModSpec | undefined, isMac: boolean): boolean;
+/** Case-insensitive key match; supports string or string[] (any-of). */
+declare function matchKey(eventKey: string, specKey: string | string[]): boolean;
+/**
+ * Match a target value + event against a TargetSpec.
+ *
+ * - `{ kindOf: predicate }` — calls the predicate with the raw target value
+ *   (affordance hit on pointerdown; event.target otherwise) AND the
+ *   `bodyTarget` string. Predicates that only need the target can ignore
+ *   the second arg.
+ * - `'empty'`, `'selected-body'`, `'unselected-body'` — compared against
+ *   `bodyTarget` on the event (populated by `useGestureDispatcher` when a
+ *   `classifyTarget` thunk is supplied). Falls back to `false` when absent
+ *   (kind registry not yet wired).
+ * - Other string-forms (`kind:*`, `affordance:*`) — not yet supported; return false.
+ * - `undefined` spec.target — any target is accepted.
+ */
+declare function matchTarget(target: unknown, specTarget: unknown, bodyTarget?: string): boolean;
+/** Per-tool gesture-lifecycle state at match time.
+ *
+ *  - `selfChannel` is the tool id `'&'` resolves to — i.e., the tool that
+ *    owns the binding being evaluated. `null` for bindings without an
+ *    owning tool (e.g. ambient actions registered without scope ties); in
+ *    that case any `phase: '&'` atom can't match.
+ *  - `engagedChannels` is the set of tool ids that currently have an
+ *    in-flight handle. Derived by the dispatcher from its `inFlight()`
+ *    map keyed by tool id at match time.
+ */
+interface PhaseContext {
+    selfChannel: string | null;
+    engagedChannels: ReadonlySet<string>;
+}
+/** True if the binding's `phase` spec is satisfied by the current
+ *  per-tool engagement state. Omitted spec → always true (no phase
+ *  constraint). Union semantics: a phase atom list matches when ANY
+ *  atom matches. */
+declare function matchPhase(spec: PhaseSpec | undefined, ctx: PhaseContext): boolean;
+/** MIME-glob match: `'image/*'` prefix-matches the major type; anything
+ *  else is an exact (case-insensitive) match; bare `'*'` or `'*\/*'` matches all. */
+declare function mimeMatchesGlob(mime: string, glob: string): boolean;
+/** True if ANY item's MIME matches ANY of the `types` globs.
+ *  `types: []` (empty) ≡ omitted = match any. */
+declare function matchIngestTypes(items: readonly {
+    mime: string;
+}[], types: string[] | undefined): boolean;
+/**
+ * Match a single GestureSpec against an InputEvent.
+ *
+ * For `key-held`, only `phase: 'down'` returns true. The dispatcher tracks the
+ * held state independently and handles `phase: 'up'` itself.
+ *
+ * For TargetSpec string forms, returns false (kind registry not yet available).
+ */
+declare function matchSpec(e: InputEvent, spec: GestureSpec, isMac: boolean, phaseCtx?: PhaseContext): boolean;
+
+export { ACTIVE_SIGILS, type BodyTarget, type ChannelRef, type ClickEvent, type ClickSpec, type ContextMenuEvent, type ContextMenuSpec, type DescribeRouteOptions, type DoubleClickEvent, type DoubleClickSpec, type DragSpec, type DropEvent, type DropSpec, type EventModifiers, GESTURE_DESCRIPTORS, type GestureArgSpec, type GestureDescriptor, type GestureName, type GestureSpec, type IngestItem, type InputEvent, type KeyEvent, type KeyHeldEvent, type KeyHeldSpec, type KeySpec, MOD_NAME_SET, type ModRequirement, type ModSpec, type ModifierCombo, type ModifierKey, type ModifiersEvent, type MultiTouchSpec, type MultiTouchTapSpec, type MultitouchEvent, type MultitouchTapEvent, type OptionalMod, type ParsedKeyRoute, type ParsedModifiers, type ParsedRoute, type PasteEvent, type PasteSpec, type PhaseAtom, type PhaseContext, type PhaseSpec, type PointerCancelEvent, type PointerDownEvent, type PointerMoveEvent, type PointerUpEvent, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, RESERVED_SIGILS, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, type RouteDescriptionPart, type RouteFieldName, type RoutePhase, type RouteTermLabel, type TargetSpec, VALID_MOD_NAMES, type WheelEvent, type WheelSpec, canonicalModifiers, collapseShiftPairs, describeRoute, describeRouteParts, formatKeyRoute, formatPhaseAtom, formatRoute, getGestureDescriptor, isKnownGestureName, keyRouteToSpec, matchIngestTypes, matchKey, matchModifiers, matchPhase, matchSpec, matchTarget, mimeMatchesGlob, modifierComboToParsed, mods, parseKeyRoute, parseRoute };