@weasel-js/routing 1.7.0 → 1.7.2

package/dist/{index-Bmq4lSHY.d.ts → index-BV53gfyB.d.ts}

@@ -126,10 +126,21 @@ type HitShape = {
     cx: number;
     cy: number;
     r: number;
+}
+/** A world-space polygon — for a region that is a turned square on screen,
+ *  which under non-uniform zoom is no rotated rect in world. */
+ | {
+    kind: 'polygon';
+    points: readonly {
+        x: number;
+        y: number;
+    }[];
 } | {
     kind: 'path';
     d: Path2D;
 };
+/** What a recorded viewport change was: a translation or a scale change. */
+type ViewportGestureKind = 'pan' | 'zoom';
 /**
  * Where a tool reports its internal hit math so the debug overlay can draw it.
  * Routing threads a sink through `ToolCtx` and never calls one.
@@ -155,6 +166,16 @@ interface DebugSink {
         y: number;
     }, accepted: boolean): void;
     recordLayer(id: string, label: string, space: 'world' | 'screen', index: number): void;
+    /**
+     * A viewport change a gesture made: the view it started from, the view it
+     * produced, and the world point it held fixed — a pan's grab point, a zoom's
+     * focal point — when it had one. Survives `beginFrame`; the next record
+     * replaces it.
+     */
+    recordViewport(kind: ViewportGestureKind, from: View, to: View, anchor?: {
+        x: number;
+        y: number;
+    }): void;
     /** Clears every non-snap array. Called at the start of each Canvas render. */
     beginFrame(): void;
     /** Clears the snap array. Called at gesture end. */
@@ -1470,6 +1491,7 @@ interface DispatchRecord {
     fired: string | null;
     outcome: 'handled' | 'unhandled';
 }
+/** The input a {@link DispatchRecord} describes, reduced to plain data. */
 interface DispatchRecordInput {
     /** `InputEvent.kind`: `'key'`, `'pointerdown'`, `'wheel'`, … */
     eventKind: string;
@@ -1506,6 +1528,7 @@ interface RecordCandidate {
     /** The action's `eligible` rule as text, when it declares one. */
     eligible?: string;
 }
+/** A matched candidate a filter removed before ranking, and which filter. */
 type DroppedCandidate = 
 /** An exclusive claim on the input barred bindings that do not read the
  *  claim's affordance. */
@@ -1520,6 +1543,7 @@ type DroppedCandidate =
     filter: 'ineligible';
     rule: string;
 };
+/** One field of the `specificity` tuple, in the order it is compared. */
 type SpecificityPart = 'target' | 'mods' | 'phase' | 'exact';
 /** The ranking step that put a candidate below the one before it. */
 type PlacedBy = {
@@ -1582,6 +1606,8 @@ type WalkStep = {
  | {
     kind: 'outranked';
 };
+/** A candidate that survived the filters: why it sits where it does, and
+ *  what the walk did with it. */
 interface RankedCandidate {
     candidate: RecordCandidate;
     placedBy: PlacedBy;
@@ -1666,15 +1692,6 @@ interface ModeSwitchLogEntry {
 }
 /** A trace entry: one {@link DispatchRecord} per resolved input, or a mode switch. */
 type TraceLogEntry = DispatchRecord | ModeSwitchLogEntry;
-/**
- * Dev only: offer the record for what a press at the pointer would do, as a
- * thunk on `window.__weaselDispatchLive__`. The hover pump offers one per move
- * and a reader builds the record only when it looks, so no record is built
- * while nothing is watching. `null` withdraws it when the pointer leaves.
- *
- * @internal
- */
-declare function publishLiveDispatch(explain: (() => DispatchRecord) | null): void;
 /** Push a mode-switch record into the trace log. Safe to call from
  *  anywhere; no-ops outside DEV. */
 declare function recordModeSwitch(mode: string, from: string | null, to: string | null, detail?: string): void;
@@ -1713,35 +1730,6 @@ interface DispatcherContext {
      */
     viewId?: string | null;
 }
-/**
- * Filter `matches` to only those whose backing action has no `eligible`
- * rule, or whose rule evaluates true against `ruleCtx`. Exported for
- * unit testing.
- *
- * @internal
- */
-declare function filterEligible<M extends {
-    binding: {
-        actionId: string;
-    };
-}>(matches: readonly M[], actionLookup: (id: string) => Action | undefined, ruleCtx: RuleCtx): M[];
-/**
- * Among matches tied on scope and specificity, put those whose action is
- * gated by an `eligible` rule that holds now ahead of those with no rule: a
- * binding that applies only in the current context — Escape while editing a
- * path — outranks one that applies everywhere. Otherwise stable.
- *
- * @internal
- */
-declare function preferContextual<M extends {
-    binding: GestureBinding;
-    scope: string;
-}>(matches: readonly M[], actionLookup: (id: string) => Action | undefined, 
-/** Whether a gated action's rule holds; skip re-asking where the matches
- *  were already filtered by it. */
-holds: (action: Action) => boolean, 
-/** The routed view: a binding naming it is never tied with one that does not. */
-view: string | null): M[];
 /**
  * Handle returned by `Dispatcher.beginUiOngoing()` for driving an
  * ongoing invoker from a UI control (color picker, slider).
@@ -2122,6 +2110,85 @@ declare const isControlHandle: (target: unknown) => boolean;
 /** Any of the three anchor-editing affordances (anchor + both controls). */
 declare const isAnchorOrControl: (target: unknown) => boolean;
 
+/**
+ * The long-press the gesture dispatcher is timing, as observable state: where
+ * the press landed, when the hold started, how far through it is, and whether
+ * any binding would fire on it. Feedback — a filling ring, a haptic — reads
+ * this; nothing here decides what the feedback looks like.
+ */
+/** A press being held toward a long-press. */
+interface PendingLongPress {
+    pointerId: number;
+    /** Long-press is synthesized for these two only; a mouse never arms one. */
+    pointerType: 'touch' | 'pen';
+    /** Where the press landed, in client coordinates. */
+    client: {
+        x: number;
+        y: number;
+    };
+    /** The same point in CSS pixels from the canvas element's top-left — what a
+     *  `space: 'screen'` layer draws in. */
+    local: {
+        x: number;
+        y: number;
+    };
+    /** The same point in the routed view's world coordinates. */
+    world: {
+        x: number;
+        y: number;
+    };
+    /** The view the press routed to; `null` is the root view. */
+    viewId: string | null;
+    /** `performance.now()` when the hold started. */
+    startedAt: number;
+    /** How long the hold must last before the long-press fires, in ms. */
+    duration: number;
+    /**
+     * Whether holding to the end would fire anything — a `longPress` binding,
+     * or a `contextMenu` binding through the fallback. Resolved at press time.
+     * Feedback shows only when this is true: a press that will do nothing must
+     * not promise that it will.
+     */
+    armed: boolean;
+}
+/** Read side of the pending long-press. Published as the `longPress` dep. */
+interface LongPressState {
+    /** The press being held, or `null` when none is. Cleared when the
+     *  long-press fires, and when movement, release, cancel or a second
+     *  pointer abandons it. */
+    get(): PendingLongPress | null;
+    /** How far through the hold the pending press is, 0→1, at `now`
+     *  (`performance.now()` by default). 0 when nothing is pending. */
+    progress(now?: number): number;
+    /** Called whenever {@link get} changes. Progress is derived from the
+     *  clock, so it does not notify — a loop drawing it asks for frames. */
+    subscribe(fn: () => void): () => void;
+}
+/** The dispatcher's writable half of {@link LongPressState}. */
+interface LongPressStore extends LongPressState {
+    set(next: PendingLongPress | null): void;
+}
+/** How long a touch or pen press is held before it fires `longPress`, in ms. */
+declare const LONG_PRESS_MS = 500;
+/** How `useGestureDispatcher` times, publishes and signals a long-press. */
+interface LongPressOptions {
+    /** Hold time in ms. Default {@link LONG_PRESS_MS}. */
+    duration?: number;
+    /**
+     * Where the press being held is published: position, start time, progress,
+     * and whether any binding would fire on it. `<SceneCanvas>` passes one and
+     * republishes it as the `longPress` dep, which its default press ring
+     * reads. Omit it and nothing is published.
+     */
+    state?: LongPressStore;
+    /**
+     * Default true. A long-press some binding handled pulses `navigator.vibrate`
+     * briefly, for touch and pen pointers, where the API exists.
+     */
+    haptics?: boolean;
+}
+declare function createLongPressStore(): LongPressStore;
+
 /**
  * The DOM half of a drag: one pointer, held down, from press to release.
  *
@@ -2141,6 +2208,7 @@ type PointerSessionCancelReason =
  | 'aborted'
 /** A new press arrived on this pointer, so the tracked one had ended. */
  | 'superseded';
+/** What {@link openPointerSession} reports. Exactly one of `onEnd` / `onCancel` fires when the session ends. */
 interface PointerSessionCallbacks {
     /** Every move belonging to this pointer, while it is still held. */
     onMove?: (e: PointerEvent) => void;
@@ -2149,13 +2217,16 @@ interface PointerSessionCallbacks {
     /** The session ended without a release. Fires once. */
     onCancel?: (reason: PointerSessionCancelReason) => void;
 }
+/** Options for {@link openPointerSession}. */
 interface PointerSessionOptions {
     /** Ask the origin element to capture the pointer. Default `true`. Capture
      *  keeps hover and click off everything the drag passes over; the session
      *  does not depend on it to keep receiving events. */
     capture?: boolean;
 }
+/** A live drag opened by {@link openPointerSession}. */
 interface PointerSession {
+    /** The pointer this session follows, taken from the press. */
     readonly pointerId: number;
     /** False once the session has ended, by any route. */
     readonly active: boolean;
@@ -2648,9 +2719,11 @@ declare function reportRouteConflicts(scopes: ToolScopes, warn?: (message: strin
  * consumers don't depend on its disappearance.
  */
 /**
- * @internal — runtime shape consumed by `matchesKeyBinding`. Public tool authors
- * should use `ToolKeybinding` from `@weasel-js/core` for declaring
- * configurable activation keys.
+ * A key plus a modifier policy, as {@link matchesKeyBinding} tests it against a
+ * `KeyboardEvent`. Every modifier left unset is forbidden, so `{ key: 'a' }`
+ * does not fire on Cmd+A. The matcher ignores `skipInEditable`, `enabled` and
+ * `preventDefault`; those are for whatever attaches the listener. Tools
+ * declaring an activation key use `ToolKeybinding` instead.
  */
 interface KeyBinding {
     /**
@@ -2856,4 +2929,4 @@ type KernelOverlay = OverlaySchema extends {
     overlay: infer O;
 } ? O : unknown;
 
-export { type HandleKind as $, type ActionsRegistry as A, type BindingOpts as B, type Contribution as C, type Dispatcher as D, COARSE_TARGET_SCALE as E, type Condition as F, type Conflict as G, type ContributionChrome as H, type ContributionDeps as I, type ContributionRouting as J, type KernelOverlay as K, DEFAULT_ALLOWED_CAPABILITIES as L, DEFAULT_DEVICE_PROFILE as M, type DebugSink as N, type OverlayPosition as O, type DetectedDeviceFacts as P, type DeviceProfile as Q, type RuleCtx as R, ScopeNode as S, type DispatchRecord as T, type DispatchRecordInput as U, type DispatcherContext as V, type DragSample as W, type DroppedCandidate as X, type Eligibility as Y, type EligibilityState as Z, type GestureBinding as _, type AffordanceHit as a, clientToCanvasRect as a$, type HitShape as a0, type HotkeyTrigger as a1, INGEST_STRING_MIMES as a2, type ImmediateInvoker as a3, type InvocationCtx as a4, type Invoker as a5, type KeyBinding as a6, type MatchOutcome as a7, type MatchResult as a8, type ModeShortcutHandlers as a9, type SelectionApi as aA, type SelectionExtendKey as aB, type SelectionMode as aC, type Selector as aD, type SpecificityPart as aE, TOOL_OFFHAND_ID as aF, type Tool as aG, type ToolBounds as aH, type ToolCtx as aI, type ToolDef as aJ, type ToolKeybinding as aK, type ToolLifecycleCtx as aL, type ToolModifiers as aM, type ToolOffhandBindingSpec as aN, type ToolPresentation as aO, type ToolSlot as aP, type TraceLogEntry as aQ, type UiOngoingControl as aR, type View as aS, type WalkStep as aT, actionBindings as aU, actionItems as aV, buildDepsFromRequires as aW, buildRouteRegistry as aX, buildRuleCtx as aY, buildToolOffhandBindings as aZ, clientToCanvas as a_, type ModeSwitchLogEntry as aa, type ModifierState as ab, NEVER as ac, type NodeId as ad, type OngoingHandle as ae, type OngoingInvoker as af, type OngoingOverlay as ag, type OverlayRole as ah, type OverlaySchema as ai, PREDICATE_TARGET as aj, type PlacedBy as ak, type Point2 as al, type PointerSession as am, type PointerSessionCallbacks as an, type PointerSessionCancelReason as ao, type PointerSessionOptions as ap, type RankedCandidate as aq, type RecordCandidate as ar, type RegistryEntry as as, type ResizeAnchor as at, type ResolveAllOptions as au, type ResolveOnlyResult as av, type ResolvedCandidate as aw, type Rule as ax, type ScratchKey as ay, type ScratchStore as az, type DepSchema as b, createDepRegistry as b0, createDispatcher as b1, defineTool as b2, deleteScratch as b3, describeRule as b4, dlog as b5, evaluate as b6, evaluateEnabled as b7, filterEligible as b8, findConflicts as b9, pointerGestureId as bA, preferContextual as bB, publishLiveDispatch as bC, recordModeSwitch as bD, reportRouteConflicts as bE, resolveDeviceProfile as bF, resolveParams as bG, routesForSpec as bH, ruleCanHoldIn as bI, rulesExclusive as bJ, scopeBindings as bK, scratchKey as bL, setScratch as bM, targetConsultsAffordance as bN, validateActionDefaultBinding as bO, validateActionId as bP, getScratch as ba, isAnchor as bb, isAnchorOrControl as bc, isBody as bd, isControlHandle as be, isEditableTarget as bf, isEmpty as bg, isResizeHandle as bh, isRotateHandle as bi, isSelectedBody as bj, isTool as bk, isUnselectedBody as bl, itemsFromClipboardData as bm, itemsFromDataTransfer as bn, itemsFromFiles as bo, liveScope as bp, makeToolOffhandAction as bq, matchBest as br, matchSorted as bs, matchSortedWithBarred as bt, matchesKeyBinding as bu, mergeContributions as bv, modeShortcutSpec as bw, modeShortcuts as bx, offhandKeyFor as by, openPointerSession as bz, type DepRegistry as c, type DepName as d, type Action as e, DepNode as f, type AnyToolOf as g, type ScopedBinding as h, ALWAYS as i, type ActionDeps as j, ActionDisabledReason as k, type ActionDispatch as l, type ActionEnabledResult as m, type ActionEntry as n, type ActionItem as o, type ActionPresentation as p, type ActionSource as q, type ActionVariant as r, type ActionsProp as s, type AnyTool as t, type BindingScope as u, type BindingSource as v, type BodyPredicate as w, type BoundGesture as x, type Bounds as y, type BuildRuleCtxArgs as z };
+export { type GestureBinding as $, type ActionsRegistry as A, type BindingOpts as B, type Contribution as C, type DepRegistry as D, COARSE_TARGET_SCALE as E, type Condition as F, type Conflict as G, type ContributionChrome as H, type ContributionDeps as I, type ContributionRouting as J, type KernelOverlay as K, type LongPressOptions as L, DEFAULT_ALLOWED_CAPABILITIES as M, DEFAULT_DEVICE_PROFILE as N, type OverlayPosition as O, type DebugSink as P, type DetectedDeviceFacts as Q, type RuleCtx as R, ScopeNode as S, type DeviceProfile as T, type DispatchRecord as U, type DispatchRecordInput as V, type DispatcherContext as W, type DragSample as X, type DroppedCandidate as Y, type Eligibility as Z, type EligibilityState as _, type DepName as a, actionItems as a$, type HandleKind as a0, type HitShape as a1, type HotkeyTrigger as a2, INGEST_STRING_MIMES as a3, type ImmediateInvoker as a4, type InvocationCtx as a5, type Invoker as a6, type KeyBinding as a7, LONG_PRESS_MS as a8, type LongPressState as a9, type ResolveOnlyResult as aA, type ResolvedCandidate as aB, type Rule as aC, type ScratchKey as aD, type ScratchStore as aE, type SelectionApi as aF, type SelectionExtendKey as aG, type SelectionMode as aH, type Selector as aI, type SpecificityPart as aJ, TOOL_OFFHAND_ID as aK, type Tool as aL, type ToolBounds as aM, type ToolCtx as aN, type ToolDef as aO, type ToolKeybinding as aP, type ToolLifecycleCtx as aQ, type ToolModifiers as aR, type ToolOffhandBindingSpec as aS, type ToolPresentation as aT, type ToolSlot as aU, type TraceLogEntry as aV, type UiOngoingControl as aW, type View as aX, type ViewportGestureKind as aY, type WalkStep as aZ, actionBindings as a_, type LongPressStore as aa, type MatchOutcome as ab, type MatchResult as ac, type ModeShortcutHandlers as ad, type ModeSwitchLogEntry as ae, type ModifierState as af, NEVER as ag, type NodeId as ah, type OngoingHandle as ai, type OngoingInvoker as aj, type OngoingOverlay as ak, type OverlayRole as al, type OverlaySchema as am, PREDICATE_TARGET as an, type PendingLongPress as ao, type PlacedBy as ap, type Point2 as aq, type PointerSession as ar, type PointerSessionCallbacks as as, type PointerSessionCancelReason as at, type PointerSessionOptions as au, type RankedCandidate as av, type RecordCandidate as aw, type RegistryEntry as ax, type ResizeAnchor as ay, type ResolveAllOptions as az, type DepSchema as b, buildDepsFromRequires as b0, buildRouteRegistry as b1, buildRuleCtx as b2, buildToolOffhandBindings as b3, clientToCanvas as b4, clientToCanvasRect as b5, createDepRegistry as b6, createDispatcher as b7, createLongPressStore as b8, defineTool as b9, matchesKeyBinding as bA, mergeContributions as bB, modeShortcutSpec as bC, modeShortcuts as bD, offhandKeyFor as bE, openPointerSession as bF, pointerGestureId as bG, recordModeSwitch as bH, reportRouteConflicts as bI, resolveDeviceProfile as bJ, resolveParams as bK, routesForSpec as bL, ruleCanHoldIn as bM, rulesExclusive as bN, scopeBindings as bO, scratchKey as bP, setScratch as bQ, targetConsultsAffordance as bR, validateActionDefaultBinding as bS, validateActionId as bT, deleteScratch as ba, describeRule as bb, dlog as bc, evaluate as bd, evaluateEnabled as be, findConflicts as bf, getScratch as bg, isAnchor as bh, isAnchorOrControl as bi, isBody as bj, isControlHandle as bk, isEditableTarget as bl, isEmpty as bm, isResizeHandle as bn, isRotateHandle as bo, isSelectedBody as bp, isTool as bq, isUnselectedBody as br, itemsFromClipboardData as bs, itemsFromDataTransfer as bt, itemsFromFiles as bu, liveScope as bv, makeToolOffhandAction as bw, matchBest as bx, matchSorted as by, matchSortedWithBarred as bz, type Action as c, DepNode as d, type AnyToolOf as e, type ScopedBinding as f, type Dispatcher as g, type AffordanceHit as h, ALWAYS as i, type ActionDeps as j, ActionDisabledReason as k, type ActionDispatch as l, type ActionEnabledResult as m, type ActionEntry as n, type ActionItem as o, type ActionPresentation as p, type ActionSource as q, type ActionVariant as r, type ActionsProp as s, type AnyTool as t, type BindingScope as u, type BindingSource as v, type BodyPredicate as w, type BoundGesture as x, type Bounds as y, type BuildRuleCtxArgs as z };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { i as ALWAYS, e as Action, j as ActionDeps, k as ActionDisabledReason, k as ActionDisabledReasonValue, l as ActionDispatch, m as ActionEnabledResult, n as ActionEntry, o as ActionItem, p as ActionPresentation, q as ActionSource, r as ActionVariant, s as ActionsProp, A as ActionsRegistry, a as AffordanceHit, t as AnyTool, g as AnyToolOf, B as BindingOpts, u as BindingScope, v as BindingSource, w as BodyPredicate, x as BoundGesture, y as Bounds, z as BuildRuleCtxArgs, E as COARSE_TARGET_SCALE, F as Condition, G as Conflict, C as Contribution, H as ContributionChrome, I as ContributionDeps, J as ContributionRouting, L as DEFAULT_ALLOWED_CAPABILITIES, M as DEFAULT_DEVICE_PROFILE, N as DebugSink, d as DepName, c as DepRegistry, b as DepSchema, P as DetectedDeviceFacts, Q as DeviceProfile, T as DispatchRecord, U as DispatchRecordInput, D as Dispatcher, V as DispatcherContext, W as DragSample, X as DroppedCandidate, Y as Eligibility, Z as EligibilityState, _ as GestureBinding, $ as HandleKind, a0 as HitShape, a1 as HotkeyTrigger, a2 as INGEST_STRING_MIMES, a3 as ImmediateInvoker, a4 as InvocationCtx, a5 as Invoker, K as KernelOverlay, a6 as KeyBinding, a7 as MatchOutcome, a8 as MatchResult, a9 as ModeShortcutHandlers, aa as ModeSwitchLogEntry, ab as ModifierState, ac as NEVER, ad as NodeId, ae as OngoingHandle, af as OngoingInvoker, ag as OngoingOverlay, O as OverlayPosition, ah as OverlayRole, ai as OverlaySchema, aj as PREDICATE_TARGET, ak as PlacedBy, al as Point2, am as PointerSession, an as PointerSessionCallbacks, ao as PointerSessionCancelReason, ap as PointerSessionOptions, aq as RankedCandidate, ar as RecordCandidate, as as RegistryEntry, at as ResizeAnchor, au as ResolveAllOptions, av as ResolveOnlyResult, aw as ResolvedCandidate, ax as Rule, R as RuleCtx, h as ScopedBinding, ay as ScratchKey, az as ScratchStore, aA as SelectionApi, aB as SelectionExtendKey, aC as SelectionMode, aD as Selector, aE as SpecificityPart, aF as TOOL_OFFHAND_ID, aG as Tool, aH as ToolBounds, aI as ToolCtx, aJ as ToolDef, aK as ToolKeybinding, aL as ToolLifecycleCtx, aM as ToolModifiers, aN as ToolOffhandBindingSpec, aO as ToolPresentation, aP as ToolSlot, aQ as TraceLogEntry, aR as UiOngoingControl, aS as View, aT as WalkStep, aU as actionBindings, aV as actionItems, aW as buildDepsFromRequires, aX as buildRouteRegistry, aY as buildRuleCtx, aZ as buildToolOffhandBindings, a_ as clientToCanvas, a$ as clientToCanvasRect, b0 as createDepRegistry, b1 as createDispatcher, b2 as defineTool, b3 as deleteScratch, b4 as describeRule, b5 as dlog, b6 as evaluate, b7 as evaluateEnabled, b8 as filterEligible, b9 as findConflicts, ba as getScratch, bb as isAnchor, bc as isAnchorOrControl, bd as isBody, be as isControlHandle, bf as isEditableTarget, bg as isEmpty, bh as isResizeHandle, bi as isRotateHandle, bj as isSelectedBody, bk as isTool, bl as isUnselectedBody, bm as itemsFromClipboardData, bn as itemsFromDataTransfer, bo as itemsFromFiles, bp as liveScope, bq as makeToolOffhandAction, br as matchBest, bs as matchSorted, bt as matchSortedWithBarred, bu as matchesKeyBinding, bv as mergeContributions, bw as modeShortcutSpec, bx as modeShortcuts, by as offhandKeyFor, bz as openPointerSession, bA as pointerGestureId, bB as preferContextual, bC as publishLiveDispatch, bD as recordModeSwitch, bE as reportRouteConflicts, bF as resolveDeviceProfile, bG as resolveParams, bH as routesForSpec, bI as ruleCanHoldIn, bJ as rulesExclusive, bK as scopeBindings, bL as scratchKey, bM as setScratch, bN as targetConsultsAffordance, bO as validateActionDefaultBinding, bP as validateActionId } from './index-Bmq4lSHY.js';
+export { i as ALWAYS, c as Action, j as ActionDeps, k as ActionDisabledReason, k as ActionDisabledReasonValue, l as ActionDispatch, m as ActionEnabledResult, n as ActionEntry, o as ActionItem, p as ActionPresentation, q as ActionSource, r as ActionVariant, s as ActionsProp, A as ActionsRegistry, h as AffordanceHit, t as AnyTool, e as AnyToolOf, B as BindingOpts, u as BindingScope, v as BindingSource, w as BodyPredicate, x as BoundGesture, y as Bounds, z as BuildRuleCtxArgs, E as COARSE_TARGET_SCALE, F as Condition, G as Conflict, C as Contribution, H as ContributionChrome, I as ContributionDeps, J as ContributionRouting, M as DEFAULT_ALLOWED_CAPABILITIES, N as DEFAULT_DEVICE_PROFILE, P as DebugSink, a as DepName, D as DepRegistry, b as DepSchema, Q as DetectedDeviceFacts, T as DeviceProfile, U as DispatchRecord, V as DispatchRecordInput, g as Dispatcher, W as DispatcherContext, X as DragSample, Y as DroppedCandidate, Z as Eligibility, _ as EligibilityState, $ as GestureBinding, a0 as HandleKind, a1 as HitShape, a2 as HotkeyTrigger, a3 as INGEST_STRING_MIMES, a4 as ImmediateInvoker, a5 as InvocationCtx, a6 as Invoker, K as KernelOverlay, a7 as KeyBinding, a8 as LONG_PRESS_MS, L as LongPressOptions, a9 as LongPressState, aa as LongPressStore, ab as MatchOutcome, ac as MatchResult, ad as ModeShortcutHandlers, ae as ModeSwitchLogEntry, af as ModifierState, ag as NEVER, ah as NodeId, ai as OngoingHandle, aj as OngoingInvoker, ak as OngoingOverlay, O as OverlayPosition, al as OverlayRole, am as OverlaySchema, an as PREDICATE_TARGET, ao as PendingLongPress, ap as PlacedBy, aq as Point2, ar as PointerSession, as as PointerSessionCallbacks, at as PointerSessionCancelReason, au as PointerSessionOptions, av as RankedCandidate, aw as RecordCandidate, ax as RegistryEntry, ay as ResizeAnchor, az as ResolveAllOptions, aA as ResolveOnlyResult, aB as ResolvedCandidate, aC as Rule, R as RuleCtx, f as ScopedBinding, aD as ScratchKey, aE as ScratchStore, aF as SelectionApi, aG as SelectionExtendKey, aH as SelectionMode, aI as Selector, aJ as SpecificityPart, aK as TOOL_OFFHAND_ID, aL as Tool, aM as ToolBounds, aN as ToolCtx, aO as ToolDef, aP as ToolKeybinding, aQ as ToolLifecycleCtx, aR as ToolModifiers, aS as ToolOffhandBindingSpec, aT as ToolPresentation, aU as ToolSlot, aV as TraceLogEntry, aW as UiOngoingControl, aX as View, aY as ViewportGestureKind, aZ as WalkStep, a_ as actionBindings, a$ as actionItems, b0 as buildDepsFromRequires, b1 as buildRouteRegistry, b2 as buildRuleCtx, b3 as buildToolOffhandBindings, b4 as clientToCanvas, b5 as clientToCanvasRect, b6 as createDepRegistry, b7 as createDispatcher, b8 as createLongPressStore, b9 as defineTool, ba as deleteScratch, bb as describeRule, bc as dlog, bd as evaluate, be as evaluateEnabled, bf as findConflicts, bg as getScratch, bh as isAnchor, bi as isAnchorOrControl, bj as isBody, bk as isControlHandle, bl as isEditableTarget, bm as isEmpty, bn as isResizeHandle, bo as isRotateHandle, bp as isSelectedBody, bq as isTool, br as isUnselectedBody, bs as itemsFromClipboardData, bt as itemsFromDataTransfer, bu as itemsFromFiles, bv as liveScope, bw as makeToolOffhandAction, bx as matchBest, by as matchSorted, bz as matchSortedWithBarred, bA as matchesKeyBinding, bB as mergeContributions, bC as modeShortcutSpec, bD as modeShortcuts, bE as offhandKeyFor, bF as openPointerSession, bG as pointerGestureId, bH as recordModeSwitch, bI as reportRouteConflicts, bJ as resolveDeviceProfile, bK as resolveParams, bL as routesForSpec, bM as ruleCanHoldIn, bN as rulesExclusive, bO as scopeBindings, bP as scratchKey, bQ as setScratch, bR as targetConsultsAffordance, bS as validateActionDefaultBinding, bT as validateActionId } from './index-BV53gfyB.js';
 export { ChannelRef, DRAG_THRESHOLD_PX, DescribeRouteOptions, GESTURE_DESCRIPTORS, GestureArgSpec, GestureDescriptor, GestureName, IngestItem, InputEvent, ModRequirement, ModifierKey, ParsedModifiers, ParsedRoute, PhaseAtom, PhaseContext, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, RouteDescriptionPart, RouteFieldName, RouteTermLabel, canonicalModifiers, collapseShiftPairs, describeRoute, describeRouteParts, formatPhaseAtom, formatRoute, getGestureDescriptor, isKnownGestureName, matchKey, matchModifiers, matchPhase, matchSpec, matchTarget, parseRoute, pastDragThreshold, routeGestureForSpecKind, specKindForRouteGesture, specificity } from '@weasel-js/gestures';
 import '@weasel-js/modes';
 import 'react';

package/dist/index.js

@@ -1,5 +1,5 @@
-import { isDev } from './chunk-Q3Y3DPKH.js';
-export { ALWAYS, COARSE_TARGET_SCALE, DEFAULT_ALLOWED_CAPABILITIES, DEFAULT_DEVICE_PROFILE, GESTURE_DESCRIPTORS, INGEST_STRING_MIMES, NEVER, PREDICATE_TARGET, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, TOOL_OFFHAND_ID, actionBindings, buildDepsFromRequires, buildRouteRegistry, buildRuleCtx, buildToolOffhandBindings, canonicalModifiers, clientToCanvas, clientToCanvasRect, collapseShiftPairs, createDepRegistry, createDispatcher, describeRoute, describeRouteParts, describeRule, dlog, evaluate, filterEligible, findConflicts, formatPhaseAtom, formatRoute, getGestureDescriptor, isEditableTarget, isKnownGestureName, isTool, itemsFromClipboardData, itemsFromDataTransfer, itemsFromFiles, liveScope, makeToolOffhandAction, matchBest, matchKey, matchModifiers, matchPhase, matchSorted, matchSortedWithBarred, matchSpec, matchTarget, matchesKeyBinding, offhandKeyFor, openPointerSession, parseRoute, pointerGestureId, preferContextual, publishLiveDispatch, recordModeSwitch, reportRouteConflicts, resolveDeviceProfile, resolveParams, routeGestureForSpecKind, routesForSpec, ruleCanHoldIn, rulesExclusive, scopeBindings, specKindForRouteGesture, specificity, targetConsultsAffordance, validateActionDefaultBinding, validateActionId } from './chunk-Q3Y3DPKH.js';
+import { isDev } from './chunk-ZGKJWZ4S.js';
+export { ALWAYS, COARSE_TARGET_SCALE, DEFAULT_ALLOWED_CAPABILITIES, DEFAULT_DEVICE_PROFILE, GESTURE_DESCRIPTORS, INGEST_STRING_MIMES, LONG_PRESS_MS, NEVER, PREDICATE_TARGET, RESERVED_ID_NAMES, RESERVED_ID_PREFIXES, ROUTE_FIELD_DEFINITIONS, ROUTE_TERMS, TOOL_OFFHAND_ID, actionBindings, buildDepsFromRequires, buildRouteRegistry, buildRuleCtx, buildToolOffhandBindings, canonicalModifiers, clientToCanvas, clientToCanvasRect, collapseShiftPairs, createDepRegistry, createDispatcher, createLongPressStore, describeRoute, describeRouteParts, describeRule, dlog, evaluate, findConflicts, formatPhaseAtom, formatRoute, getGestureDescriptor, isEditableTarget, isKnownGestureName, isTool, itemsFromClipboardData, itemsFromDataTransfer, itemsFromFiles, liveScope, makeToolOffhandAction, matchBest, matchKey, matchModifiers, matchPhase, matchSorted, matchSortedWithBarred, matchSpec, matchTarget, matchesKeyBinding, offhandKeyFor, openPointerSession, parseRoute, pointerGestureId, recordModeSwitch, reportRouteConflicts, resolveDeviceProfile, resolveParams, routeGestureForSpecKind, routesForSpec, ruleCanHoldIn, rulesExclusive, scopeBindings, specKindForRouteGesture, specificity, targetConsultsAffordance, validateActionDefaultBinding, validateActionId } from './chunk-ZGKJWZ4S.js';
 import { RESERVED_ID_PREFIXES, RESERVED_ID_NAMES } from '@weasel-js/gestures';
 export { DRAG_THRESHOLD_PX, pastDragThreshold } from '@weasel-js/gestures';
 import { modeLabel } from '@weasel-js/modes';

package/dist/internal--mYnGecm.d.ts

@@ -0,0 +1,275 @@
+import { g as Dispatcher, A as ActionsRegistry, C as Contribution, h as AffordanceHit, L as LongPressOptions, R as RuleCtx, b as DepSchema } from './index-BV53gfyB.js';
+import { RefObject } from 'react';
+import { BodyClassification } from '@weasel-js/gestures';
+import { PaintedCursorState } from '@weasel-js/cursor';
+
+/**
+ * Everything about handling an input event that depends on *which view* it
+ * landed in: the dispatcher that runs it, and the three lookups that resolve
+ * a client point against that view's camera.
+ *
+ * @internal One per view. The hook builds the `id: null` one from its flat
+ *   options; `views` supplies the rest, and the hook chooses between them per
+ *   event, so that it — and its listener set — still mounts exactly once.
+ */
+interface DispatcherViewTarget {
+    /** `null` is the root view — the whole canvas. Matches `ViewTarget.id`. */
+    id: string | null;
+    dispatcher: Dispatcher;
+    affordanceAt: UseGestureDispatcherOptions['affordanceAt'];
+    classifyTarget: UseGestureDispatcherOptions['classifyTarget'];
+    clientToWorld: UseGestureDispatcherOptions['clientToWorld'];
+    /**
+     * The deps this view answers for itself — its camera, its selection, and
+     * whatever else is per-view rather than per-canvas. Read per event; every
+     * name it does not carry still resolves through the canvas registry.
+     *
+     * This is why a view does not get a `DepRegistryProvider` of its own. The
+     * registry is where a consumer registers *sources*, and one per view would
+     * fragment that: a consumer overriding `insert` would have to know how many
+     * views exist and override each. An overlay keeps one place to register and
+     * one authority per dep, with the view claiming only what is genuinely its.
+     *
+     * Without this a gesture inside a panel pans the whole canvas and selects
+     * into the canvas's selection — correct coordinates alone do not make
+     * routing correct.
+     */
+    deps?: () => Partial<DepSchema>;
+    /**
+     * This view's chrome-caps rule context, for the eligibility filter. The rule
+     * table is the surface's, but a rule keyed on selection or the in-flight
+     * action answers per view — so an action hidden in one panel must not
+     * decline a gesture in another. `undefined` means "nothing gates here", the
+     * same answer a surface with no mode registry gives.
+     */
+    getRuleCtx?: () => RuleCtx | undefined;
+}
+/**
+ * The part of `features/viewports`' `ViewResolver` the dispatcher needs: which
+ * view a client point belongs to, pinned to the view a gesture began in.
+ *
+ * @internal Structural on purpose — a `ViewResolver` satisfies it, and the
+ *   dispatcher stays free of the viewport module.
+ */
+interface ViewIdResolver {
+    begin(pointerId: number, clientX: number, clientY: number): {
+        id: string | null;
+    };
+    at(pointerId: number | null, clientX: number, clientY: number): {
+        id: string | null;
+    };
+    end(pointerId: number): void;
+}
+/** Per-channel switches for the listeners `useGestureDispatcher` attaches to
+ *  the canvas element. Omitted or `true` attaches the channel. */
+interface DispatcherChannels {
+    /** `pointerdown`, hover `pointermove`, `pointerleave` — press, drag, click,
+     *  long-press, multi-touch and the hover-cursor pump. */
+    pointer?: boolean;
+    /** `wheel`. */
+    wheel?: boolean;
+    /** WebKit's `gesturestart` / `gesturechange` / `gestureend` — Safari's
+     *  trackpad pinch, dispatched as `pinch` events. */
+    pinch?: boolean;
+    /** `contextmenu`. Off leaves the browser's native menu in place. */
+    contextMenu?: boolean;
+    /** OS drop on the element plus `paste` on the window. Off leaves the
+     *  element a non-drop-target and stops `weasel-dropover` being applied. */
+    ingest?: boolean;
+}
+/** Options for `useGestureDispatcher`: the element to listen on, the actions
+ *  and tools in play, and the hooks that turn raw DOM events into the world
+ *  coordinates and hit targets bindings match against. */
+interface UseGestureDispatcherOptions {
+    /** Ref to the canvas element. Pointer/wheel/multitouch listeners attach here. */
+    canvasRef: RefObject<HTMLElement | null>;
+    /** Action registry (ActionsRegistry from registry.tsx). */
+    actions: ActionsRegistry;
+    /** Tool definitions keyed by id. Typically passes an empty Map. */
+    entriesById: ReadonlyMap<string, Contribution<unknown>>;
+    /** Default true. Set false to opt out of dispatcher wiring (e.g. demos that disable it). */
+    enabled?: boolean;
+    /**
+     * Observer fired whenever the dispatcher synthesizes a double click, in
+     * world coordinates. Runs BEFORE the event is dispatched and independently
+     * of which binding (if any) handles it.
+     *
+     * This is deliberately not an Action. `<SceneCanvas onDoubleClick>` is a
+     * notification — "the user double-clicked, here's what they hit" — and a
+     * notification must not compete with behavior for the gesture. As a binding
+     * it would lose to `enterPathEdit` on any body hit and silently never fire.
+     * Routing it here keeps a single definition of "double click" (the point of
+     * consolidating the kit's three detectors) without giving it
+     * first-match-wins semantics it shouldn't have.
+     */
+    onDoubleClick?: (world: {
+        x: number;
+        y: number;
+    }) => void;
+    /**
+     * Default true. Set false to leave the window `keydown`/`keyup` listeners
+     * unattached so keyboard-bound actions never dispatch — pointer, wheel, and
+     * contextmenu channels stay live. `<SceneCanvas>` wires this to
+     * `enableKeybindings`, so opting out of keybindings disables the modern
+     * dispatcher key path as well as the legacy `useKeybindings` hook.
+     *
+     * Every dispatcher hears keys on `window`, and a keystroke one of them
+     * claims — or anything else calls `preventDefault` on — is not dispatched by
+     * the rest. `'first'` listens in the capture phase, so this dispatcher gets
+     * the keystroke ahead of every dispatcher listening normally, whatever the
+     * mount order: the shape for chrome that owns a key only when it can act.
+     */
+    keyboard?: boolean | 'first';
+    /**
+     * Optional affordance classifier. Called with the **world** coordinates of
+     * the pointer — this hook applies the routed view's `clientToWorld` before
+     * calling it, the same conversion that produces `InputEvent.x`/`y`, so a
+     * consumer hit-tests in one space. Returns an `AffordanceHit` when the
+     * pointer lands on a known affordance (resize handle, rotate handle, etc.)
+     * or `null` when the pointer hit open canvas.
+     *
+     * The hit is packed into `InputEvent.pointerdown.affordance` and flows
+     * through into `InvocationCtx.drag.affordance`. Action invokers that require
+     * a specific affordance (e.g. `resizeAction` requires `handle:*`) use this
+     * field as a guard in their `start` body.
+     *
+     * When omitted, `affordance` is always `undefined` — meaning only consumers
+     * that explicitly wire a classifier get affordance-gated behavior.
+     * `<SceneCanvas>` wires the full chrome→dispatcher bridge.
+     */
+    affordanceAt?: (worldPoint: {
+        x: number;
+        y: number;
+    }) => AffordanceHit | null;
+    /**
+     * Optional body classifier. Called on every pointerdown with the world-space
+     * coordinates of the pointer. Its result is packed onto the event as
+     * `bodyTarget` + `bodyKind`, which `matchTarget` reads to resolve the
+     * string-form `TargetSpec` values in `Tool.bindings`.
+     *
+     * `body` is `'empty'` when nothing is under the pointer, `'selected-body'`
+     * when the topmost hit belongs to the current selection, or
+     * `'unselected-body'` when it belongs to a node that isn't selected. `kind`
+     * is the hit node's semantic kind, when the scene can name it.
+     *
+     * When omitted, every body-derived target form (`'empty'`,
+     * `'selected-body'`, `'unselected-body'`, `kind:<k>`, `kind:<k>:selected`)
+     * never matches — bindings using those specs are silently skipped.
+     * `<SceneCanvas>` wires this.
+     *
+     * World coordinates, on every path, for the same reason as `affordanceAt`.
+     */
+    classifyTarget?: (worldPoint: {
+        x: number;
+        y: number;
+    }) => BodyClassification;
+    /**
+     * Optional pre-created `Dispatcher`. When provided, this hook pumps events
+     * into the supplied instance instead of creating its own. Lets a parent
+     * scope (e.g. `<SceneCanvas>`) share one dispatcher between the gesture
+     * mounter and other consumers (the preview-ghost layer).
+     */
+    dispatcher?: Dispatcher;
+    /**
+     * Converts a client-space pointer position (e.g. `e.clientX`, `e.clientY`)
+     * to world-space coordinates. When supplied, every pointer/wheel event's
+     * `x`/`y` is converted before the dispatcher builds `InvocationCtx.world`.
+     *
+     * Without this, `ctx.world` is populated with the raw client coords, which
+     * silently breaks any action whose overlay/output uses absolute world
+     * positions (marquee, lasso polyline, world-space affordances). Actions
+     * that only read `drag.delta` are unaffected because client→world deltas
+     * are equal at scale 1, but as soon as a consumer pans/zooms the view the
+     * deltas diverge too.
+     *
+     * `<SceneCanvas>` always wires this via its canvas rect + current view.
+     * Tests / harnesses without a view can omit it and continue passing raw
+     * coordinates as before.
+     */
+    clientToWorld?: (clientX: number, clientY: number) => {
+        x: number;
+        y: number;
+    };
+    /**
+     * Invoked once per pump event (`pointermove`, `pointerup`, `pointercancel`,
+     * `key-held` up-phase, `multitouch` move) when a dispatcher-side handle is
+     * in flight. Lets the host canvas schedule a redraw so dispatcher-only
+     * overlays (marquee, lasso, preview-ghost) repaint on each frame.
+     *
+     * Required because dispatcher actions don't go through the legacy
+     * `tools.dispatcher.onGestureChange` redraw bump that ambient tool drags
+     * relied on. Without it, the overlay layer's `draw` never runs between
+     * pointerdown and pointerup, and the chrome flashes once at gesture start
+     * and then sits frozen until the gesture ends.
+     *
+     * `<SceneCanvas>` wires this to the canvas's `requestRedraw`. Test
+     * harnesses can omit it; their dispatchers won't paint between events but
+     * that's already the test contract.
+     */
+    requestRedraw?: () => void;
+    /**
+     * The surface's painted-cursor channel, read live because the canvas handle
+     * it lives on arrives a render after this hook runs.
+     *
+     * Given one, a cursor the CSS tier cannot express — sized in world units, or
+     * past the size the browser drops the image at — is published here and drawn
+     * by the painted-cursor layer instead. Without one, such a cursor resolves to
+     * `none` and the pointer shows nothing.
+     */
+    paintedCursor?: () => PaintedCursorState | undefined;
+    /** How touch and pen long-presses are timed, published and felt. */
+    longPress?: LongPressOptions;
+    /**
+     * Thunk returning the live `RuleCtx` for the current frame. When supplied,
+     * the dispatcher filters matched candidates by their declared
+     * `Action.eligible` rule (omitted => always eligible). `<SceneCanvas>`
+     * wires this; tests / harnesses without chrome-caps state can omit it.
+     */
+    getRuleCtx?: () => RuleCtx | undefined;
+    /**
+     * Which of the canvas element's input channels to attach. Every one
+     * defaults to `true`; naming a channel `false` leaves its listeners
+     * unattached, so the element behaves as if the dispatcher were not there.
+     *
+     * A mount that binds two gestures should not also have to take the rest of
+     * the pipeline's side effects: `contextMenu` suppresses the native menu
+     * unconditionally, and `ingest` makes the element a valid drop target and
+     * styles it while an OS drag hovers. `@weasel-js/labkit`'s loupe mounts on
+     * a lab's own canvas host for a wheel and a held key, and turning the other
+     * three off is what keeps right-click and file drops working there.
+     *
+     * The window keyboard channel is `keyboard` instead of an entry here,
+     * because `<SceneCanvas enableKeybindings>` drives it.
+     */
+    channels?: DispatcherChannels;
+    /**
+     * Routing for a canvas hosting more than one view: the non-root dispatch
+     * records to choose between, read fresh per event, and the resolver that
+     * chooses. Omit for a single view — then every event runs on the record the
+     * flat options above describe, which is what they are: view zero.
+     *
+     * A resolved id with no live record falls back to the root, so a view that
+     * unmounts mid-gesture degrades instead of dropping the event.
+     *
+     * Keyboard and paste have no coordinates to resolve; they run on the view
+     * the last coordinate-bearing event resolved to.
+     *
+     * @internal
+     */
+    views?: {
+        targets: () => readonly DispatcherViewTarget[];
+        resolver: ViewIdResolver;
+    };
+}
+/**
+ * Attach the input pipeline to a canvas: DOM pointer, wheel, keyboard and
+ * multitouch listeners in, normalized input events out, routed through the
+ * dispatcher to whichever action a binding names.
+ *
+ * Everything it needs beyond its options — the active tool, the dep registry —
+ * comes from context, so it must be mounted inside `<SceneCanvas>`'s
+ * providers.
+ */
+declare function useGestureDispatcher(opts: UseGestureDispatcherOptions): void;
+
+export { type DispatcherChannels as D, type UseGestureDispatcherOptions as U, type ViewIdResolver as V, type DispatcherViewTarget as a, useGestureDispatcher as u };

package/dist/internal.d.ts

@@ -0,0 +1,7 @@
+export { a as DispatcherViewTarget, V as ViewIdResolver } from './internal--mYnGecm.js';
+import './index-BV53gfyB.js';
+import '@weasel-js/modes';
+import 'react';
+import '@weasel-js/cursor';
+import '@weasel-js/gestures';
+import '@weasel-js/history';

package/dist/internal.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=internal.js.map
+//# sourceMappingURL=internal.js.map

package/dist/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"internal.js"}