@weasel-js/labkit 0.1.0

package/dist/passthrough/weasel-ui.d.ts

@@ -0,0 +1,2826 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, CSSProperties, ButtonHTMLAttributes, ReactElement, PointerEvent as PointerEvent$1, KeyboardEvent as KeyboardEvent$1, RefCallback } from 'react';
+import { b as NodeId, O as Op, V as View, B as Bounds, D as DrawCommand } from '../_dts/fitViewToBounds-rWrBI4a6.js';
+import { TextFieldProps, ValidationResult, CheckboxProps as CheckboxProps$1, SwitchProps as SwitchProps$1, TabProps as TabProps$1, TabListProps as TabListProps$1, TabPanelProps as TabPanelProps$1, TabsProps as TabsProps$1, RadioProps as RadioProps$1, RadioGroupProps as RadioGroupProps$1, NumberFieldProps as NumberFieldProps$1, SelectProps as SelectProps$1, ListBoxItemProps, ComboBoxProps as ComboBoxProps$1, SliderProps as SliderProps$1, ModalOverlayProps, DialogProps as DialogProps$1 } from 'react-aria-components';
+
+/**
+ * Namespaced, opt-in console tracing. Off by default; production builds
+ * may strip the calls entirely depending on the bundler.
+ *
+ * Enable in the browser:
+ *
+ *   localStorage.setItem('weasel.debug', '*')               // all namespaces
+ *   localStorage.setItem('weasel.debug', 'curve-editor')    // just curve editor
+ *   localStorage.setItem('weasel.debug', 'curve-editor,layer-stack')
+ *
+ * Each component picks a stable namespace and calls `dlog(namespace, ...)`.
+ * Useful for tracing pointer/event flows that are hard to capture
+ * post-hoc (drag handlers, gesture sequences, selection mutations).
+ *
+ * The flag is read once and cached for the page session — reload to
+ * pick up changes. Cheap hot-path checks (one nullish-coalesce + Set
+ * lookup) so leaving calls in place is fine.
+ *
+ * Mirrors `src/debug/flag.ts` in the kit. Two impls live here because
+ * weasel-ui doesn't depend on the kit, but both read the same
+ * localStorage keys so behavior is uniform. See the kit copy for the
+ * canonical list of kit-level namespaces.
+ *
+ * Known weasel-ui namespaces:
+ *   - plot2d        — Plot2D mount / unmount
+ *   - curve-editor  — CurveEditor pointer flow
+ */
+/** True when `namespace` (or `*`) is enabled. */
+declare function isDebugEnabled(namespace: string): boolean;
+/** Conditional `console.debug` — no-op unless `namespace` (or `*`) is enabled.
+ *  Each call is prefixed with `[namespace]` so the source is searchable. */
+declare function dlog(namespace: string, ...args: unknown[]): void;
+
+interface ActionBarProps {
+    /** Group key — only actions with `action.group === group` are rendered. */
+    group: string;
+    /** Layout direction. Defaults to `'horizontal'`. */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Per-id icon overrides — keyed by `action.id`. When an entry is provided
+     * it replaces the action's own `icon` for this bar only. Mirrors
+     * `PathfinderPanelProps.icons` so call sites that ship custom glyph sets
+     * can swap them in without re-registering actions.
+     */
+    icons?: Record<string, ReactNode>;
+    /**
+     * Per-id label overrides — keyed by `action.id`. Drives both `aria-label`
+     * and `title`. When omitted, the action's own `label` is used.
+     */
+    labels?: Record<string, string>;
+    /** Additional class for the toolbar root. */
+    className?: string;
+}
+/**
+ * Generic group-keyed action toolbar. Reads the parent `ActionsRegistry`,
+ * filters to actions whose `group` matches `props.group`, and renders one
+ * icon button per match. Disabled state is derived from each action's
+ * `enabled` predicate via `evaluateEnabled` (so the button greys out and
+ * swallows clicks while the keybinding — if any — still fires through the
+ * registry's keydown listener; that's the registry's contract, not ours).
+ *
+ * Visual parity with the WeaselDraw `<PathfinderPanel>` is intentional;
+ * this is the generic, registry-driven version. No keyboard navigation
+ * (roving tabindex) yet — bar consumers today are short flat strips. Add
+ * if/when a long bar lands.
+ */
+declare function ActionBar(props: ActionBarProps): react_jsx_runtime.JSX.Element;
+
+type BadgeShape = 'pill' | 'plain' | 'square' | 'notched' | 'perforated' | 'hexagon' | 'starburst' | 'scalloped' | 'shield' | 'ribbon' | 'beavis' | 'sparkler' | 'postage' | 'cloud' | 'house' | 'plaque' | 'crest' | 'urn' | 'coffin' | 'receipt' | 'wood' | 'quatrefoil';
+type BadgeTone = 'accent' | 'info' | 'warn' | 'danger' | 'muted' | 'neutral' | 'custom';
+type BadgeVariant = 'outline' | 'solid' | 'subtle';
+type BadgeSize = 'sm' | 'md';
+
+interface SquareParams {
+    /** 0..1 fraction of the maximum corner rounding (1 = full pill). */
+    erosion?: number;
+}
+
+interface NotchedParams {
+    /** 0..1 fraction of max corner radius. */
+    erosion?: number;
+    /** rx/ry eccentricity of the corner arcs. */
+    eccentricity?: number;
+}
+
+interface PerforatedParams {
+    holeRadius?: number;
+    holePitch?: number;
+}
+
+interface HexagonParams {
+    tipHeight?: number;
+    /** Truncate the top and bottom tips, leaving a horizontal flat edge.
+     *  Measured as a distance from each tip vertically (0 = sharp point, tipHeight = fully flat). */
+    tipTruncation?: number;
+}
+
+interface StarburstParams {
+    points?: number;
+    outerR?: number;
+    innerR?: number;
+    rotation?: number;
+    erosion?: number;
+}
+
+interface ScallopedParams {
+    scallopRadius?: number;
+    scallopSpacing?: number;
+    irregularity?: number;
+}
+
+interface ShieldParams {
+    pointDepth?: number;
+    shoulderY?: number;
+    curveTightness?: number;
+    /** 0..1 fraction of max top-corner rounding. */
+    erosion?: number;
+}
+
+type RibbonEnd$1 = 'inward' | 'outward' | 'flat';
+interface RibbonParams$1 {
+    left?: RibbonEnd$1;
+    right?: RibbonEnd$1;
+    /** Taper depth in CSS px. The actual pointer width stays fixed regardless
+     *  of badge width — the underlying base recomputes viewBox vertices at
+     *  build time using the rendered box dimensions. */
+    taperWidth?: number;
+}
+
+interface BeavisParams {
+    points?: number;
+    cornerRadius?: number;
+    spikeLen?: number;
+    spikeBaseWidth?: number;
+    irregularity?: number;
+}
+
+interface SparklerParams {
+    points?: number;
+    outerR?: number;
+    innerR?: number;
+    rotation?: number;
+}
+
+interface PostageParams {
+    biteRadius?: number;
+    biteSpacing?: number;
+    irregularity?: number;
+}
+
+interface CloudParams {
+    bumpWidth?: number;
+    puffiness?: number;
+    /** 0..1 fraction of max body roundness. */
+    erosion?: number;
+    irregularity?: number;
+}
+
+interface HouseParams {
+    eaveY?: number;
+    peakHeight?: number;
+    roofOverhang?: number;
+}
+
+type PlaqueCorner = 'tl' | 'tr' | 'bl' | 'br';
+interface PlaqueParams {
+    bevelWidth?: number;
+    lightFrom?: PlaqueCorner;
+    rivetRadius?: number;
+    rivetInset?: number;
+    sheenIntensity?: number;
+}
+
+interface CrestParams {
+    topInset?: number;
+    pointDepth?: number;
+}
+
+interface CoffinParams {
+    headX?: number;
+    headHalfHeight?: number;
+    shoulderX?: number;
+    shoulderHalfHeight?: number;
+    footX?: number;
+    footHalfHeight?: number;
+}
+
+interface ReceiptParams {
+    teeth?: number;
+    tearDepth?: number;
+    sideToTopRatio?: number;
+}
+
+interface QuatrefoilParams$1 {
+    spikeR?: number;
+    lobeR?: number;
+    valleyR?: number;
+    valleyAt?: number;
+    spikeCurvature?: number;
+    spikeBend?: number;
+    spikeTipErosion?: number;
+    lobeCurvature?: number;
+    lobeBend?: number;
+    lobeTipErosion?: number;
+    valleySmooth?: number;
+    rotation?: number;
+    samples?: number;
+}
+
+interface BadgeShapeParams {
+    pill: Record<string, never>;
+    plain: Record<string, never>;
+    square: SquareParams;
+    notched: NotchedParams;
+    perforated: PerforatedParams;
+    hexagon: HexagonParams;
+    starburst: StarburstParams;
+    scalloped: ScallopedParams;
+    shield: ShieldParams;
+    ribbon: RibbonParams$1;
+    beavis: BeavisParams;
+    sparkler: SparklerParams;
+    postage: PostageParams;
+    cloud: CloudParams;
+    house: HouseParams;
+    plaque: PlaqueParams;
+    crest: CrestParams;
+    urn: Record<string, never>;
+    coffin: CoffinParams;
+    receipt: ReceiptParams;
+    wood: Record<string, never>;
+    quatrefoil: QuatrefoilParams$1;
+}
+
+interface ChamferedRectParams {
+    /** CSS px length of each 45° corner chamfer. */
+    chamfer?: number;
+}
+
+interface RoundedRectParams {
+    /** 0..1 fraction of the maximum corner rounding (1 = full pill / ellipse). */
+    erosion?: number;
+    /** Stretch the corner arcs horizontally vs vertically. 1 = circular at the badge's
+     *  native aspect; >1 wider corner arcs; <1 taller corner arcs. */
+    eccentricity?: number;
+    /** 0..1 vertical squeeze applied to the left and right ends, linearly tapering toward
+     *  the middle. 1 = ends fully collapsed to the centerline (lemon/lens silhouette). */
+    pinch?: number;
+}
+
+interface PolygonParams {
+    /** Vertices in viewBox 0..100 coordinates, traced clockwise. */
+    vertices?: [number, number][];
+}
+
+type PuzzleEdge = 'flat' | 'out' | 'in';
+interface PuzzleParams {
+    top?: PuzzleEdge;
+    right?: PuzzleEdge;
+    bottom?: PuzzleEdge;
+    left?: PuzzleEdge;
+    /** Tab radius in viewBox units (0..50). */
+    tabSize?: number;
+    /** Sample density per tab arc. */
+    arcSamples?: number;
+}
+
+/**
+ * 8-fold-symmetric polar shape. The whole silhouette is defined by a single curve r(s)
+ * over s ∈ [0, 1], where s=0 is the cardinal direction and s=1 is the diagonal. The full
+ * shape comes from reflecting that octant curve eight times around the center. The curve
+ * itself is two superellipse segments meeting at a valley:
+ *
+ *   s ∈ [0, valleyAt]      → spike segment, from `spikeR` down to `valleyR`
+ *   s ∈ [valleyAt, 1]      → lobe segment, from `valleyR` up to `lobeR`
+ *
+ * Each segment has its own curvature, bend bias, and tip-erosion controls.
+ */
+interface QuatrefoilParams {
+    /** Radius at s=0 (cardinal direction). */
+    spikeR?: number;
+    /** Radius at s=1 (diagonal direction). */
+    lobeR?: number;
+    /** Radius at the junction between spike and lobe segments. */
+    valleyR?: number;
+    /** Position of the junction in [0, 1]. 0.5 = symmetric octant; <0.5 narrows the spike side. */
+    valleyAt?: number;
+    /** Spike-segment curvature (superellipse exponent). 1 = flat diagonal sides; <1 caves
+     *  inward (concave/star); >1 bulges outward (convex/square-shouldered). */
+    spikeCurvature?: number;
+    /** Spike-segment bend bias. Positive shifts the curve's bend toward the tip; negative
+     *  toward the base. */
+    spikeBend?: number;
+    /** Flat-top truncation of the cardinal tip (0..1). */
+    spikeTipErosion?: number;
+    /** Lobe-segment curvature, same semantics as spike. */
+    lobeCurvature?: number;
+    /** Lobe-segment bend bias. */
+    lobeBend?: number;
+    /** Flat-top truncation of the diagonal lobe peak (0..1). */
+    lobeTipErosion?: number;
+    /** Smooth the corner at the valley junction. 0 = sharp, higher = puffier crossover. */
+    valleySmooth?: number;
+    /** Rotate the pattern in degrees. */
+    rotation?: number;
+    /** Polygon sample count. */
+    samples?: number;
+}
+
+/**
+ * Symmetric polar-spline base. The silhouette comes from a single curve r(s) over
+ * s ∈ [0, 1] that gets reflected/rotated to fill the full circle:
+ *
+ *  - `mode: 'octant'`: 1/8 of the perimeter (cardinal → diagonal), mirrored within each
+ *    quadrant and rotated to fill the rest. 8-fold symmetric.
+ *  - `mode: 'quadrant'`: 1/4 of the perimeter (cardinal → next cardinal), rotated 4 times
+ *    with no internal mirror. 4-fold rotational symmetry; endpoints share radius.
+ *
+ * The interpolant is a **clamped natural cubic spline** with zero slope at both endpoints
+ * (so the reflected/rotated full curve has no kink crossing the symmetry axes). C² across
+ * the whole octant — continuous curvature, not just slope — which removes the "lumpy" feel
+ * that local Hermite splines have when anchors are uneven.
+ */
+interface OctantSplineParams {
+    mode?: 'octant' | 'quadrant';
+    /** Number of active anchors (3..12). */
+    count?: number;
+    s0?: number;
+    s1?: number;
+    s2?: number;
+    s3?: number;
+    s4?: number;
+    s5?: number;
+    s6?: number;
+    s7?: number;
+    s8?: number;
+    s9?: number;
+    s10?: number;
+    s11?: number;
+    r0?: number;
+    r1?: number;
+    r2?: number;
+    r3?: number;
+    r4?: number;
+    r5?: number;
+    r6?: number;
+    r7?: number;
+    r8?: number;
+    r9?: number;
+    r10?: number;
+    r11?: number;
+    /** Per-anchor weight (0..3). The spline is constructed to pass through every anchor exactly;
+     *  the weight biases how strongly that anchor influences the rest of the curve. Implementation
+     *  detail: blends the C² interpolant with a polynomial fit weighted by w. Default 1 = pure
+     *  C² interpolation; <1 lets the curve sweep past the anchor (anchor still passed through);
+     *  >1 makes the curve hug the anchor more tightly (sharper local bend). */
+    w0?: number;
+    w1?: number;
+    w2?: number;
+    w3?: number;
+    w4?: number;
+    w5?: number;
+    w6?: number;
+    w7?: number;
+    w8?: number;
+    w9?: number;
+    w10?: number;
+    w11?: number;
+    rotation?: number;
+    samples?: number;
+}
+
+/**
+ * Symmetric polar NURBS base. Same anchor concept as `octant-spline` but the curve is an
+ * **approximating** cubic NURBS — the control points pull the curve without sitting on it.
+ * Each anchor's weight increases the local pull toward that control point.
+ *
+ * Endpoint behaviour: the curve uses mirror-phantom control points just outside [0, 1]
+ * derived from the second-from-end anchors, which enforces zero slope at s=0 and s=1 so
+ * the reflected/rotated full silhouette closes cleanly across the symmetry axes.
+ */
+interface OctantBSplineParams {
+    mode?: 'octant' | 'quadrant';
+    count?: number;
+    s0?: number;
+    s1?: number;
+    s2?: number;
+    s3?: number;
+    s4?: number;
+    s5?: number;
+    s6?: number;
+    s7?: number;
+    s8?: number;
+    s9?: number;
+    s10?: number;
+    s11?: number;
+    r0?: number;
+    r1?: number;
+    r2?: number;
+    r3?: number;
+    r4?: number;
+    r5?: number;
+    r6?: number;
+    r7?: number;
+    r8?: number;
+    r9?: number;
+    r10?: number;
+    r11?: number;
+    w0?: number;
+    w1?: number;
+    w2?: number;
+    w3?: number;
+    w4?: number;
+    w5?: number;
+    w6?: number;
+    w7?: number;
+    w8?: number;
+    w9?: number;
+    w10?: number;
+    w11?: number;
+    rotation?: number;
+    samples?: number;
+}
+
+type RibbonEnd = 'inward' | 'outward' | 'flat';
+interface RibbonParams {
+    left?: RibbonEnd;
+    right?: RibbonEnd;
+    /** Taper depth in CSS px. Stays fixed regardless of badge width — viewBox
+     *  vertices are computed at build time using `boxW`. */
+    taperWidth?: number;
+}
+
+type EdgeProfile = (t: number, depth: number) => number;
+type BuiltInEdgeName = 'flat' | 'chevron' | 'slant' | 'slant-up' | 'round' | 'scallop' | 'concave-chevron';
+type EdgeCap = BuiltInEdgeName | EdgeProfile;
+declare const EDGE_PROFILES: Record<BuiltInEdgeName, EdgeProfile>;
+
+interface PowerlineParams {
+    /** Profile for the left edge (the cap segment N inherits from segment N-1). */
+    leftEdge?: EdgeCap;
+    /** Profile for the right edge (this segment's own end cap). */
+    rightEdge?: EdgeCap;
+    /** Protrusion depth in CSS px (positive values stick out beyond the rect). */
+    depth?: number;
+}
+
+type BadgeBase = 'chamfered-rect' | 'rounded-rect' | 'polygon' | 'puzzle' | 'quatrefoil' | 'octant-spline' | 'octant-bspline' | 'ribbon' | 'powerline';
+interface BadgeBaseParams {
+    'chamfered-rect': ChamferedRectParams;
+    'rounded-rect': RoundedRectParams;
+    'polygon': PolygonParams;
+    'puzzle': PuzzleParams;
+    'quatrefoil': QuatrefoilParams;
+    'octant-spline': OctantSplineParams;
+    'octant-bspline': OctantBSplineParams;
+    'ribbon': RibbonParams;
+    'powerline': PowerlineParams;
+}
+
+interface RangeMaskParams {
+    /** Optional `[start, end]` as fractions of totalCss (0..1). Restricts the effect to a
+     *  contiguous slice of the perimeter; `end < start` wraps around. */
+    range?: [number, number];
+}
+
+interface SpikesEffectParams extends RangeMaskParams {
+    count?: number;
+    length?: number;
+    baseWidth?: number;
+    vertScale?: number;
+    horzScale?: number;
+    diagonalScale?: number;
+    irregularity?: number;
+    /**
+     * 0..1 strength of curvature-based shortening on corners. At 1 we fully cancel the tip-arc
+     * expansion `(1 + κL)` so neighbouring spike tips stay roughly evenly spaced even on tight
+     * corner arcs; at 0 spikes are constant length and visibly fan outward around corners.
+     */
+    cornerCompensation?: number;
+}
+
+interface PuffsEffectParams extends RangeMaskParams {
+    bumpWidth?: number;
+    puffiness?: number;
+    irregularity?: number;
+}
+
+interface BitesEffectParams extends RangeMaskParams {
+    biteRadius?: number;
+    biteSpacing?: number;
+    irregularity?: number;
+}
+
+interface ScallopsEffectParams extends RangeMaskParams {
+    scallopRadius?: number;
+    scallopSpacing?: number;
+    irregularity?: number;
+}
+
+type Corner$2 = 'tl' | 'tr' | 'bl' | 'br';
+interface BevelEffectParams {
+    /** Bevel band width in CSS px. */
+    bevelWidth?: number;
+    /** Which corner the light originates from (drives the highlight/shadow distribution across edges). */
+    lightFrom?: Corner$2;
+}
+
+type Corner$1 = 'tl' | 'tr' | 'bl' | 'br';
+interface SheenEffectParams {
+    lightFrom?: Corner$1;
+    /** Peak gradient opacity (0..1). */
+    intensity?: number;
+}
+
+type Corner = 'tl' | 'tr' | 'bl' | 'br';
+interface RivetsEffectParams {
+    /** Rivet radius in CSS px. */
+    radius?: number;
+    /** Inset from each corner in CSS px. */
+    inset?: number;
+    /** Light origin (drives which side of each rivet gets the highlight). */
+    lightFrom?: Corner;
+}
+
+interface ShadowEffectParams {
+    /** Offset in CSS px. */
+    dx?: number;
+    dy?: number;
+    /** Alpha 0..1. */
+    opacity?: number;
+}
+
+interface WoodgrainEffectParams {
+    /** Number of grain curves. */
+    lines?: number;
+    /** Number of knot circles. */
+    knots?: number;
+    /** Overall grain opacity (0..1). */
+    intensity?: number;
+}
+
+interface PerforationsEffectParams extends RangeMaskParams {
+    /** Hole radius in CSS px. */
+    holeRadius?: number;
+    /** Spacing between hole centers along the perimeter, in CSS px. */
+    holeSpacing?: number;
+}
+
+interface Bevel2EffectParams {
+    /** Bevel band width in CSS px. */
+    bevelWidth?: number;
+    /** Compass angle the light originates from, in degrees. 0° = top, 90° =
+     *  right, 180° = bottom, 270° = left (CSS `linear-gradient` convention). */
+    lightFrom?: number;
+}
+
+interface OutlineEffectParams {
+    /** Stroke width in CSS px. */
+    width?: number;
+    /** Stroke color. */
+    color?: string;
+    /** Optional SVG dasharray (e.g. "4 2"). */
+    dash?: string;
+    /** CSS mix-blend-mode: 'normal', 'multiply', 'screen', 'overlay', 'darken', 'lighten',
+     *  'difference', etc. Useful when the outline color should react to whatever's behind it. */
+    blendMode?: string;
+    /** 0..1 stroke opacity. */
+    opacity?: number;
+}
+
+interface SunbeamsEffectParams {
+    /** Number of beams (parallelograms) cast across the body. */
+    count?: number;
+    /** Beam width in CSS px (measured horizontally before the skew). */
+    width?: number;
+    /** Gap between adjacent beams in CSS px. */
+    gap?: number;
+    /** Skew angle in degrees. 0 = vertical bars; positive = leaning right. */
+    angle?: number;
+    /** 0..1 lightness opacity. */
+    opacity?: number;
+    /** Beam color. Defaults to white. */
+    color?: string;
+    /** Drift the beam pattern left/right by N CSS px (lets you slide the "window" over the body). */
+    offset?: number;
+    /** 0..1 perturbs each beam's width, opacity, and angle slightly with a deterministic
+     *  per-beam noise; 0 = perfectly regular. */
+    irregularity?: number;
+    /** Gradient mask angle in degrees. 0 = left→right, 90 = top→bottom. */
+    gradientAngle?: number;
+    /** Position along the gradient axis (0..1) where the mask is fully opaque (beams visible). */
+    gradientStart?: number;
+    /** Position along the gradient axis (0..1) where the mask is fully transparent (beams faded out). */
+    gradientEnd?: number;
+}
+
+/**
+ * Aqua-glass treatment — composes onto any badge silhouette by walking the
+ * sampler's perimeter and painting four layered sub-effects in one pass:
+ *
+ *  1. Body gradient    — vertical tint that runs translucent-top through a
+ *                        bright equator band into a dark base.
+ *  2. Specular gloss   — upper-hemisphere white-fade clipped to the body.
+ *  3. Bezel highlight  — bright stroke along perimeter segments whose
+ *                        outward normal points up (`ny < 0`). On a pill that's
+ *                        the upper half; on a hex it's the three top edges;
+ *                        on a starburst it's the upward tips. Normal-aware,
+ *                        not bbox-aligned, which is what makes it work on
+ *                        arbitrary silhouettes.
+ *  4. Rim outline      — faint dark stroke along the full perimeter.
+ *
+ * For the *truly* translucent look (with backdrop-filter blur reading the
+ * surface behind the badge), use this with `variant="outline"` so the badge's
+ * own flat fill doesn't paint behind the gradient, and set
+ * `backdrop-filter: blur(...)` on the host element via CSS.
+ */
+interface AquaEffectParams {
+    /** Body tint. Defaults to `var(--badge-edge)` so the badge's tone drives it. */
+    accent?: string;
+    /** Stop opacities along the body gradient (0..1). */
+    topAlpha?: number;
+    upperAlpha?: number;
+    /** Equator Y position in viewBox units (0..100). */
+    equator?: number;
+    /** Half-width of the transition band around the equator (viewBox units). */
+    equatorSpread?: number;
+    /** Mix ratios for the bright equator and dark base stops (0..100, % accent). */
+    equatorTint?: number;
+    baseTint?: number;
+    /** Specular gloss params. */
+    glossTopAlpha?: number;
+    glossMidAlpha?: number;
+    /** Y extent the gloss covers, in viewBox units. 50 = upper hemisphere. */
+    glossExtent?: number;
+    /** Normal-aware bezel highlight. */
+    bezelAlpha?: number;
+    bezelWidth?: number;
+    /** Full-perimeter rim. */
+    rimAlpha?: number;
+    rimWidth?: number;
+}
+
+/**
+ * Metal — opaque cousin of the Aqua treatment. Same four sub-passes (body
+ * gradient, specular gloss, normal-aware bezel, perimeter rim), but tuned
+ * for an opaque metallic surface with a single tunable `specularity`
+ * parameter that drives how sharp / contrasty the highlights read.
+ *
+ * Low specularity → matte aluminum / brushed pewter feel: muted contrast,
+ *  soft gloss, faint bezel.
+ * High specularity → chrome / polished steel: sharp specular peak at the
+ *  equator, bright bezel and rim, hard transitions in the body gradient.
+ *
+ * The same `specularity` knob multiplies the equator brightness, gloss
+ * alpha, bezel alpha, and rim alpha — so one slider moves the whole
+ * surface along a coherent matte-to-mirror axis.
+ */
+interface MetalEffectParams {
+    /** Base metal color. Defaults to a neutral steel; pass e.g. `'#c8a657'` for brass. */
+    accent?: string;
+    /** 0 = matte, 1 = mirror. Multiplies the brightness of the equator, gloss,
+     *  bezel, and rim simultaneously. */
+    specularity?: number;
+    /** Equator Y position (viewBox units, 0..100). */
+    equator?: number;
+    /** Half-width of the bright equator band. Smaller = sharper specular. */
+    equatorSpread?: number;
+    /** How dark the upper and lower extremes are (% accent vs black, 0..100). */
+    topDarkness?: number;
+    baseDarkness?: number;
+    /** Gloss params. */
+    glossExtent?: number;
+    /** Per-zone alpha *baselines* — scaled by `specularity`. */
+    glossAlphaTop?: number;
+    bezelAlpha?: number;
+    bezelWidth?: number;
+    rimAlpha?: number;
+    rimWidth?: number;
+}
+
+type BadgeEffect = 'spikes' | 'puffs' | 'bites' | 'scallops' | 'bevel' | 'bevel2' | 'sheen' | 'sunbeams' | 'rivets' | 'shadow' | 'woodgrain' | 'perforations' | 'outline' | 'aqua' | 'metal';
+interface BadgeEffectParams {
+    spikes: SpikesEffectParams;
+    puffs: PuffsEffectParams;
+    bites: BitesEffectParams;
+    scallops: ScallopsEffectParams;
+    bevel: BevelEffectParams;
+    bevel2: Bevel2EffectParams;
+    sheen: SheenEffectParams;
+    rivets: RivetsEffectParams;
+    shadow: ShadowEffectParams;
+    woodgrain: WoodgrainEffectParams;
+    perforations: PerforationsEffectParams;
+    outline: OutlineEffectParams;
+    sunbeams: SunbeamsEffectParams;
+    aqua: AquaEffectParams;
+    metal: MetalEffectParams;
+}
+interface EffectSpec<E extends BadgeEffect = BadgeEffect> {
+    type: E;
+    params?: BadgeEffectParams[E];
+}
+
+interface BadgeBaseProps {
+    tone?: BadgeTone;
+    variant?: BadgeVariant;
+    size?: BadgeSize;
+    /** "Edge bloat": offset every base perimeter sample outward by N CSS px along the normal
+     *  before any compose effects run. Negative values shrink the silhouette. Photoshop-style
+     *  expand-selection on the body. */
+    bloat?: number;
+    padding?: number | string;
+    /**
+     * For CSS-rendered shapes (pill, plain) that fragment across line wraps, controls how the
+     * background/border behaves at each break.
+     * - `'slice'` (default): decoration is severed at the break (looks like one continuous badge cut by the line).
+     * - `'clone'`: each fragment paints its own complete decoration (looks like two separate badges).
+     */
+    breakStyle?: 'slice' | 'clone';
+    /** When set, perimeter-pattern shapes (beavis, cloud, postage, scalloped) continuously shift their pattern. */
+    crawl?: boolean | number;
+    /** Compose-mode: base shape underneath the badge content. When set, overrides the `shape` prop. */
+    base?: BadgeBase;
+    baseParams?: BadgeBaseParams[BadgeBase];
+    /** Compose-mode: layered effects applied around / over the base. */
+    effects?: EffectSpec[];
+    onClick?: () => void;
+    onRemove?: () => void;
+    removeLabel?: string;
+    href?: string;
+    as?: 'span' | 'button' | 'a';
+    children: ReactNode;
+    className?: string;
+    /** Optional style overrides merged with the badge's own style. Useful for setting CSS
+     *  custom properties (e.g. `--badge-edge` to inject a custom tone color). */
+    style?: CSSProperties;
+    'aria-label'?: string;
+}
+type BadgePropsByShape = {
+    [S in BadgeShape]: BadgeBaseProps & {
+        shape?: S;
+        shapeParams?: BadgeShapeParams[S];
+    };
+}[BadgeShape];
+type BadgeProps = BadgePropsByShape;
+declare function Badge(props: BadgeProps): react_jsx_runtime.JSX.Element;
+
+type ButtonVariant = 'primary' | 'secondary' | 'ghost';
+type ButtonSize = 'sm' | 'md';
+type ButtonBase = {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    disabled?: boolean;
+    loading?: boolean;
+    leadingIcon?: ReactNode;
+    trailingIcon?: ReactNode;
+    fullWidth?: boolean;
+    type?: 'button' | 'submit' | 'reset';
+    className?: string;
+    style?: ButtonHTMLAttributes<HTMLButtonElement>['style'];
+    children?: ReactNode;
+    onClick?: ButtonHTMLAttributes<HTMLButtonElement>['onClick'];
+};
+type ButtonRegular = ButtonBase & {
+    iconOnly?: false;
+    ariaLabel?: string;
+};
+type ButtonIconOnly = ButtonBase & {
+    iconOnly: true;
+    ariaLabel: string;
+};
+type ButtonProps = ButtonRegular | ButtonIconOnly;
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface DataGridColumn<Row> {
+    id: string;
+    header: ReactNode;
+    /** Pull a sortable value from the row. Defaults to `(row as any)[column.id]`. */
+    accessor?: (row: Row) => string | number | null | undefined;
+    /** Render the cell. Defaults to `String(accessor(row) ?? '')`. */
+    render?: (row: Row) => ReactNode;
+    /** Default true. Set false to suppress the sort affordance on this column. */
+    sortable?: boolean;
+    /** Optional CSS class on every <td> in this column. */
+    className?: string;
+}
+interface DataGridProps<Row extends {
+    id: string;
+}> {
+    rows: readonly Row[];
+    columns: readonly DataGridColumn<Row>[];
+    /** Initial sort. Omit for unsorted (rows render in input order). */
+    defaultSort?: {
+        columnId: string;
+        direction: 'asc' | 'desc';
+    };
+    /** Enable drag handles in a leading column. Receives the reorder spec
+     *  (the existing `useReorderDragList` semantics — see weasel-ui). */
+    onReorder?: (ids: string[], targetIndex: number) => void;
+    /** Empty-state row text. Default `'—'`. */
+    empty?: ReactNode;
+    className?: string;
+}
+declare function DataGrid<Row extends {
+    id: string;
+}>(props: DataGridProps<Row>): react_jsx_runtime.JSX.Element;
+
+type KeycapKind = 'modifier' | 'wide' | 'square';
+declare function inferKeycapKind(label: string): KeycapKind;
+type KeyCapVariant = 'default' | 'minimal';
+interface KeyCapProps {
+    /** Glyph rendered in the chip (modifier or key). */
+    label: string;
+    /** Marks the chip as not required to trigger the action. In the default
+     *  variant the chip face inverts (dark face / light glyph) for
+     *  emphasis. In the `'minimal'` variant the chip's border becomes
+     *  dotted to read as "may be held, but isn't required." */
+    inverted?: boolean;
+    /** Visual style. `'default'` (default) renders a filled chip; `'minimal'`
+     *  renders an unfilled chip whose border and legend are `currentColor`
+     *  — useful inline in colored prose / next to colored badges where the
+     *  chip should take the surrounding text color. */
+    variant?: KeyCapVariant;
+    className?: string;
+    /** Optional inline style. Useful for one-off width overrides (e.g.
+     *  building a keyboard-layout where the space bar spans several
+     *  standard-key widths). The component sets no inline styles of its
+     *  own — everything else comes from the CSS module. */
+    style?: CSSProperties;
+    /** Override the chip's font-family. Accepts any CSS font-family
+     *  string. When omitted, the chip inherits from the design-system
+     *  UI font token (`--wzl-font-ui`). Useful for one-off cases where
+     *  a different face is desired — though the canonical move is to
+     *  override the CSS variable at the consumer's scope, not the prop. */
+    font?: string;
+}
+/** Single bordered keycap chip for one glyph (modifier or key). Use
+ *  `KeySequence` to render a full shortcut. */
+declare function KeyCap({ label, inverted, variant, className, style, font }: KeyCapProps): react_jsx_runtime.JSX.Element;
+
+interface KeySpec$1 {
+    /** Glyph rendered in the chip (modifier or key). */
+    label: string;
+    /** When true, the chip renders inverted to mark it as not required to
+     *  trigger the action (e.g. an optional modifier). Defaults to false. */
+    optional?: boolean;
+}
+interface KeySequenceProps {
+    /** Keys to render. `undefined` or empty renders a muted em-dash.
+     *  Modifiers are always rendered first regardless of input order; relative
+     *  order within each group is preserved. */
+    keys: readonly KeySpec$1[] | undefined;
+    /** Character inserted between the trailing modifier chip and the first
+     *  non-modifier chip (e.g. `'+'` renders `⌘ + K`). `null` or `''`
+     *  suppresses it. Defaults to `'+'`. */
+    separator?: string | null;
+    /** Forwarded to every `KeyCap` in the sequence. `'minimal'` renders
+     *  unfilled chips whose border + legend are `currentColor`. */
+    variant?: KeyCapVariant;
+    /** Forwarded to every `KeyCap` in the sequence. Overrides the design-
+     *  system UI font for that chip only. */
+    font?: string;
+    className?: string;
+}
+/** Renders a shortcut as a row of `KeyCap` chips, one per key. Optional
+ *  keys render inverted to distinguish them from required ones. */
+declare function KeySequence({ keys, separator, variant, font, className }: KeySequenceProps): react_jsx_runtime.JSX.Element;
+
+/** Apple-style glyph for a DOM `KeyboardEvent.key` value. Covers escape,
+ *  delete/backspace, arrows, enter/return, tab, space. Unknown keys are
+ *  upper-cased (so `'a'` reads as `A` on a keycap) and returned unchanged
+ *  otherwise — making this safe to apply uniformly without a `has-glyph`
+ *  check at the call site. */
+declare function keyGlyph(rawKey: string): string;
+
+/** 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 the Apple-style glyph everywhere a symbolic form
+ *    exists. Entries without a widely-recognized symbol still fall
+ *    back to text.
+ *  - `'text'` always spells the label out (Cmd / Option / Esc / Enter). */
+type LegendStyle = 'auto' | 'symbol' | 'text';
+interface LogicalModSpec {
+    name: LogicalMod;
+    /** Marks this modifier as optional (may be held but isn't required).
+     *  Forwarded as the resulting `KeySpec.optional`. */
+    optional?: boolean;
+}
+interface KeySpecsFromModsOptions {
+    /** Override OS detection. Defaults to the detected platform, or
+     *  `'macos'` when detection is unavailable (e.g. in tests, or when
+     *  `navigator` is missing). */
+    platform?: Platform;
+    /** Defaults to `'auto'` (symbol on macOS, text everywhere else). Pass
+     *  `'symbol'` or `'text'` to force a specific style regardless of
+     *  platform. */
+    legend?: LegendStyle;
+}
+/** Detect the user's OS from the browser environment. UA sniffing — not
+ *  100% reliable, but adequate for picking a modifier-glyph convention.
+ *  Falls back to `'macos'` (matches the kit's docs convention) when
+ *  `navigator` is unavailable. */
+declare function detectPlatform(): Platform;
+/**
+ * Map a list of **logical** modifiers (`'mod'`, `'shift'`, …) to **visual**
+ * `KeySpec`s appropriate for the current platform.
+ *
+ * The kit-side gesture grammar uses logical names so the same route reads
+ * correctly on every OS — `'mod'` means "Cmd on Mac, Ctrl on Win/Linux".
+ * `KeySequence` is purely visual and renders the labels you give it; this
+ * helper is the bridge.
+ *
+ * ```ts
+ * <KeySequence
+ *   keys={keySpecsFromMods([{ name: 'mod' }, { name: 'shift', optional: true }])}
+ * />
+ * ```
+ *
+ * On a Mac: renders `⌘ ⇧`. On Windows: renders `Ctrl Shift`. Pass an
+ * explicit `platform` to override detection (e.g. for docs that always
+ * show the macOS form). Pass `legend: 'text'` to force "Cmd" over "⌘"
+ * even on macOS.
+ */
+declare function keySpecsFromMods(mods: readonly LogicalModSpec[], opts?: KeySpecsFromModsOptions): readonly KeySpec$1[];
+/**
+ * Render a raw `KeyboardEvent.key` value as a platform-appropriate
+ * `KeySpec`. 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 is only meaningful on macOS — Windows / Linux keyboards
+ * print the text form on the physical key, so symbol mode there falls
+ * back to text.
+ */
+declare function keySpecFromKey(raw: string, opts?: KeySpecsFromModsOptions & {
+    optional?: boolean;
+}): KeySpec$1;
+
+type ThumbRenderCtx = {
+    width: number;
+    height: number;
+    isActive: boolean;
+};
+type ThumbShape = 'round' | 'notched' | {
+    render: (ctx: ThumbRenderCtx) => ReactNode;
+};
+type Thumb = {
+    value: number;
+    label?: string;
+    shape?: ThumbShape;
+    bounds?: [number, number] | ((ctx: BoundsCtx) => [number, number]);
+};
+type BoundsCtx = {
+    thumbs: readonly Thumb[];
+    index: number;
+};
+type TrackCtx = {
+    trackWidth: number;
+    valueToFraction: (v: number) => number;
+};
+type SliderProps<T extends Thumb = Thumb> = {
+    thumbs: readonly T[];
+    onChange: (next: T[]) => void;
+    onCommit?: (next: T[]) => void;
+    min: number;
+    max: number;
+    step?: number;
+    constraint?: 'free' | 'ordered';
+    onAddThumb?: (atValue: number) => T | null;
+    onRemoveThumb?: (index: number) => boolean;
+    allowShiftAll?: boolean;
+    renderTrack?: (ctx: TrackCtx) => ReactNode;
+    trackHeight?: number;
+    renderReadout?: (thumb: T, index: number) => ReactNode;
+    readoutPlacement?: 'none' | 'inline-after' | 'below-thumb';
+    ariaLabel?: string;
+    className?: string;
+};
+declare function Slider<T extends Thumb = Thumb>(props: SliderProps<T>): ReactElement;
+
+type ToggleBarItem<V extends string | number = string> = {
+    value: V;
+    label?: ReactNode;
+    ariaLabel?: string;
+    disabled?: boolean;
+};
+type ToggleBarSize = 'sm' | 'md';
+type ToggleBarVariant = 'default' | 'minimal';
+type CommonProps = {
+    ariaLabel?: string;
+    className?: string;
+    height?: number;
+    /** Size variant. `sm` is ~60% of the default height with reduced padding
+     *  and font size — sized for dense surfaces like lab control panels. */
+    size?: ToggleBarSize;
+    /** Visual variant. `minimal` strips the pill track and glass treatment;
+     *  selection becomes a flat accent. For dense diagnostic surfaces. */
+    variant?: ToggleBarVariant;
+};
+type ToggleBarProps<V extends string | number = string> = (CommonProps & {
+    mode?: 'single';
+    items: readonly ToggleBarItem<V>[];
+    value: V | null;
+    onChange: (next: V | null) => void;
+    allowDeselect?: boolean;
+}) | (CommonProps & {
+    mode: 'multiple';
+    items: readonly ToggleBarItem<V>[];
+    value: readonly V[];
+    onChange: (next: V[]) => void;
+});
+declare function ToggleBar<V extends string | number = string>(props: ToggleBarProps<V>): ReactElement;
+
+type OptionsBarItem<V extends string | number = string> = {
+    value: V;
+    label?: ReactNode;
+    ariaLabel?: string;
+    disabled?: boolean;
+    selected: boolean;
+    onChange: (next: boolean) => void;
+};
+type OptionsBarSize = 'sm' | 'md';
+type OptionsBarVariant = 'default' | 'minimal';
+type OptionsBarProps<V extends string | number = string> = {
+    items: readonly OptionsBarItem<V>[];
+    ariaLabel?: string;
+    className?: string;
+    height?: number;
+    /** Size variant. `sm` is ~60% of the default height with reduced padding
+     *  and font size — sized for dense surfaces like lab control panels. */
+    size?: OptionsBarSize;
+    /** Visual variant. `minimal` strips the pill track and glass treatment;
+     *  selection becomes a flat accent. For dense diagnostic surfaces. */
+    variant?: OptionsBarVariant;
+};
+declare function OptionsBar<V extends string | number = string>(props: OptionsBarProps<V>): ReactElement;
+
+type ActionsBarItem<V extends string | number = string> = {
+    value: V;
+    label?: ReactNode;
+    ariaLabel?: string;
+    disabled?: boolean;
+    onAction: () => void;
+};
+type ActionsBarSize = 'sm' | 'md';
+type ActionsBarVariant = 'default' | 'minimal';
+type ActionsBarProps<V extends string | number = string> = {
+    items: readonly ActionsBarItem<V>[];
+    ariaLabel?: string;
+    className?: string;
+    height?: number;
+    size?: ActionsBarSize;
+    variant?: ActionsBarVariant;
+};
+declare function ActionsBar<V extends string | number = string>(props: ActionsBarProps<V>): ReactElement;
+
+interface PowerlineSegment {
+    text: ReactNode;
+    /** Cap on this segment's right edge. Next segment's left edge adopts the same profile. */
+    endCap?: EdgeCap;
+    tone?: BadgeTone;
+    variant?: BadgeVariant;
+    size?: BadgeSize;
+    onClick?: () => void;
+    href?: string;
+    'aria-label'?: string;
+}
+interface PowerlineProps {
+    segments: PowerlineSegment[];
+    /** Left edge of the first segment. Defaults to 'flat'. */
+    startCap?: EdgeCap;
+    /** Default size for every segment (per-segment `size` wins). */
+    size?: BadgeSize;
+    /** Default variant for every segment (per-segment `variant` wins). */
+    variant?: BadgeVariant;
+    /** Protrusion depth in CSS px, passed through to every segment's base. */
+    depth?: number;
+    /** Visible gap between adjacent segments. Number → px; string → literal CSS length.
+     *  Default: `0.2em` (scales with the row's font size). Pass `0` for flush. */
+    gap?: number | string;
+    className?: string;
+    'aria-label'?: string;
+}
+declare function Powerline({ segments, startCap, size, variant, depth, gap, className, ...rest }: PowerlineProps): react_jsx_runtime.JSX.Element;
+
+/** API returned by {@link useSelection}. */
+interface SelectionApi {
+    /** Current selection. Re-renders trigger when this reference changes. */
+    current: readonly NodeId[];
+    /** Imperative read for use inside event callbacks (avoids stale closures). */
+    get(): NodeId[];
+    /** Replace selection. */
+    set(ids: NodeId[]): void;
+    /** Add id (multi-mode appends; single-mode replaces). */
+    add(id: NodeId): void;
+    /** Remove id from selection. */
+    remove(id: NodeId): void;
+    /** Toggle id in/out of selection. */
+    toggle(id: NodeId): void;
+    /** Clear selection. */
+    clear(): void;
+    /** True if id is selected. */
+    contains(id: NodeId): boolean;
+    /**
+     * Apply a click to the selection per the configured mode/extend key.
+     * - `single`: replaces selection with `[id]`, regardless of modifiers.
+     * - `multi`: with the extend key held, toggles `id` in/out of the selection;
+     *   otherwise replaces with `[id]`.
+     */
+    applyClick(id: NodeId, modifiers: {
+        shift: boolean;
+        meta: boolean;
+        ctrl: boolean;
+    }): void;
+    /** Pre-built methods for spreading into an adapter that needs them. */
+    adapterMethods: {
+        getSelection: () => NodeId[];
+        setSelection: (ids: NodeId[]) => void;
+    };
+}
+
+type HandleKind = 'corner' | 'rotation' | 'anchor';
+type HitShape = {
+    kind: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+} | {
+    kind: 'circle';
+    cx: number;
+    cy: number;
+    r: number;
+} | {
+    kind: 'path';
+    d: Path2D;
+};
+interface DebugSink {
+    recordHitbox(id: string, kind: 'body' | 'handle' | 'rotation' | 'anchor', shape: HitShape): void;
+    recordHandle(id: string, position: {
+        x: number;
+        y: number;
+    }, kind: HandleKind): void;
+    recordBounds(id: string, bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    recordOrigin(id: string, point: {
+        x: number;
+        y: number;
+    }): void;
+    recordSnapCandidate(point: {
+        x: number;
+        y: number;
+    }, accepted: boolean): void;
+    recordLayer(id: string, label: string, space: 'world' | 'screen', index: 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. */
+    clearSnap(): void;
+}
+
+/**
+ * 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';
+
+/** 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';
+
+/** 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$1 = '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$1 | '*';
+}
+
+/**
+ * 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;
+
+type ContainerBounds = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+interface LayoutChild<TPose> {
+    id: string;
+    pose: TPose;
+}
+interface DropTarget<TPose> {
+    /** Where the dragged child lands if this target is picked. */
+    pose: TPose;
+    /** Reference point for distance metrics (snap algorithms). */
+    origin: {
+        x: number;
+        y: number;
+    };
+    /** Optional axis-aligned region (world units) used by region-aware snaps
+     *  (e.g. `containedThenNearest`). When present, a pointer inside this rect
+     *  is treated as a containment hit on this target. Strategies that emit
+     *  region-shaped targets (gutters, drop-zones) should populate this.
+     *  Strategies whose targets are point-like (free-form, snap-point) can omit
+     *  it and rely on `origin`-distance snaps. */
+    hitBounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Strategy-private metadata (e.g. cell coords for tile-grid). */
+    meta?: unknown;
+}
+interface LayoutSnap<TPose> {
+    pickTarget(targets: DropTarget<TPose>[], pointer: {
+        x: number;
+        y: number;
+    }): DropTarget<TPose> | null;
+}
+interface LayoutContainer {
+    id: string;
+    bounds: ContainerBounds;
+}
+interface LayoutDragged<TPose> {
+    id: string;
+    /** The pose the dragged child currently has (pre-drop). */
+    originPose: TPose;
+    /** The pose the gesture proposes (pointer-driven, pre-snap). */
+    pose: TPose;
+    sourceContainerId: string | null;
+}
+interface LayoutStrategy<TPose> {
+    childPoses(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>): Map<string, TPose>;
+    getDropTargets(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>, dragged: LayoutDragged<TPose>): DropTarget<TPose>[];
+    reflowPoses(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>, dragged: LayoutDragged<TPose>, target: DropTarget<TPose> | null): Map<string, TPose>;
+    commitDrop(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>, dragged: LayoutDragged<TPose>, target: DropTarget<TPose> | null): Op[];
+    snap: LayoutSnap<TPose>;
+    /** Optional: predicate for whether a world-space point is inside this
+     *  container. When absent, callers fall back to an axis-aligned bounding-box
+     *  test on the container's pose. Strategies whose containers aren't
+     *  rectangular (circles, irregular zones) implement this to override the
+     *  AABB default. */
+    contains?(containerPose: TPose, point: {
+        x: number;
+        y: number;
+    }): boolean;
+}
+
+/**
+ * SnapTarget — where a dragged node would re-parent to if released.
+ *
+ * `slotPose` is the pose (in world coordinates) the node should snap to
+ * within the target. `metadata` is an opaque pass-through for app-specific
+ * snap details (slot index, visual hint, etc.).
+ */
+interface SnapTarget<TPose = unknown> {
+    parentId: string;
+    slotPose: TPose;
+    metadata?: unknown;
+}
+/**
+ * Narrow adapter for `useMove`. Includes optional snap-target
+ * lookup; apps without container-snapping leave it out.
+ */
+interface MoveAdapter<TNode extends {
+    id: string;
+}, TPose> {
+    getNode(id: string): TNode | undefined;
+    /** Enumerate all nodes. `<Canvas>` derives a default rect-pose `pickEvery`
+     *  and the scene-iteration loop from this. */
+    getNodes(): TNode[];
+    getPose(id: string): TPose;
+    /** Optional. Required only by hierarchy-aware paths: layout-pass drop
+     *  targeting (`getLayout` present), nested-hit collapse
+     *  (`pickTopMostHit`), and group-pose composition. Flat scenes may omit. */
+    getParent?(id: string): string | null;
+    setPose(id: string, pose: TPose): void;
+    /** Optional. Used only by reparent ops (e.g. drag-into-container drops via
+     *  layout strategies). Flat scenes that never reparent may omit. */
+    setParent?(id: string, parentId: string | null): void;
+    /** Optional: see SceneAdapter.applyOps. */
+    applyOps?(ops: Op[], label: string): void;
+    findSnapTarget?(draggedId: string, worldX: number, worldY: number): SnapTarget<TPose> | null;
+    /** Optional: direct children of `id`. When present (alongside the
+     *  `cascadeWorldPose` option on `useMove`), dragging a node
+     *  auto-cascades its descendants in the live overlay so structurally-
+     *  grouped children visually follow the parent during the drag. No
+     *  additional ops are generated — children's local poses don't change
+     *  when the parent's local pose moves. */
+    getChildren?(id: string): string[];
+    /** Optional: layout strategy attached to a container, or null if the
+     *  container uses absolute positioning (default behavior). When present,
+     *  `useMove` uses the strategy to compute drop targets, sibling reflow,
+     *  and the commit op batch when a drag ends over the container. */
+    getLayout?(containerId: string): LayoutStrategy<TPose> | null;
+}
+
+/** Snapshot of modifier-key state at gesture dispatch. */
+interface ModifierState {
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+    ctrl: boolean;
+}
+/** Pointer position in both world and client coords. */
+interface PointerState {
+    worldX: number;
+    worldY: number;
+    clientX: number;
+    clientY: number;
+}
+/**
+ * Per-gesture context passed to behaviors. `current` is the running pose
+ * map; behaviors mutate proposed poses by returning new TPose values from
+ * onMove. `scratch` is per-gesture key/value storage that resets at the
+ * next gesture start.
+ */
+interface GestureContext<TPose, TNode extends {
+    id: string;
+} = {
+    id: string;
+}> {
+    draggedIds: string[];
+    origin: Map<string, TPose>;
+    current: Map<string, TPose>;
+    snap: SnapTarget<TPose> | null;
+    modifiers: ModifierState;
+    pointer: PointerState;
+    adapter: MoveAdapter<TNode, TPose>;
+    /**
+     * Per-gesture mutable store. Keys should be namespaced by behavior name to avoid
+     * collisions: `'behaviorName'` for a single value, `'behaviorName.field'` for
+     * sub-keys. Two behaviors sharing a key will silently clobber each other.
+     */
+    scratch: Record<string, unknown>;
+}
+/**
+ * Generalized base behavior. Each hook defines an alias that pins the
+ * proposed-pose shape (TProposed) and the onMove return shape (TMoveResult).
+ * onEnd is uniform: first non-undefined return wins (Op[] = commit those,
+ * null = abort, undefined = defer).
+ *
+ * `defaultTransient`: when at least one behavior in a gesture sets this true
+ * AND the hook's `options.transient` is not explicitly set, the gesture
+ * commits its ops via `adapter.applyOps(ops)` (no history entry). When
+ * `options.transient` is set explicitly, that value wins.
+ */
+interface ActionBehavior<TPose, TProposed, TMoveResult> {
+    defaultTransient?: boolean;
+    onStart?(ctx: GestureContext<TPose>): void;
+    onMove?(ctx: GestureContext<TPose>, proposed: TProposed): TMoveResult | void;
+    onEnd?(ctx: GestureContext<TPose>): Op[] | null | void;
+}
+
+/** Per-invocation options the dispatcher reads from a `GestureBinding`'s
+ *  `opts` field and passes to `OngoingInvoker.start`. Today carries
+ *  behaviors; extensible. */
+interface BindingOpts {
+    behaviors?: ActionBehavior<unknown, unknown, unknown>[];
+    /** Per-binding action parameters. The action's invoker reads
+     *  these via the second arg to `run` (or via InvocationCtx for ongoing
+     *  invokers, when needed). Loose typing (Record<string, unknown>) for
+     *  now; consider per-action typing later via BindingOpts<A>.
+     *
+     *  params may also be a thunk evaluated each time the
+     *  dispatcher (or invoker) needs the value. Thunks let tools close over
+     *  refs that mutate during a gesture (e.g. polygon `sides` adjusted
+     *  mid-drag via ArrowUp). For ongoing invokers that want the latest
+     *  values at commit, the invoker can re-call the thunk inside `onEnd`
+     *  via `resolveParams(opts?.params)`. */
+    params?: Record<string, unknown> | (() => Record<string, unknown>);
+}
+
+/**
+ * GestureBinding — connects a GestureSpec to an Action id (with per-binding
+ * options). Tools own arrays of these on their `bindings` field; ambient
+ * gesture-bindings are registered globally.
+ *
+ * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md`.
+ */
+
+interface GestureBinding {
+    spec: GestureSpec;
+    actionId: string;
+    opts?: BindingOpts;
+}
+
+/** The full vocabulary of capability tags shipped in the default preset.
+ *  Apps and other consumers can add their own tags; this list is what
+ *  `weasel-modes` itself uses. */
+declare const ALL_TAGS: readonly ["navigation", "creates-selection", "creates-paths", "creates-shapes", "creates-text", "edits-anchors", "edits-text", "transforms-selection", "samples-color", "applies-fill", "edits-page"];
+type CapabilityTag = (typeof ALL_TAGS)[number] | (string & {});
+
+interface WorkspaceVisual {
+    tint?: string;
+    gradient?: 'top-down' | 'bottom-up';
+    intensity?: number;
+}
+interface ModeDefinition {
+    id: string;
+    kind: 'soft' | 'strict';
+    /** Capability tags this mode allows beyond IMPLICIT_TAGS. */
+    allows: CapabilityTag[];
+    /** When true, out-of-target objects dim at the renderer layer. */
+    scoping: boolean;
+    workspace?: WorkspaceVisual;
+    entry?: {
+        shortcut?: string;
+        trigger?: 'double-click-target';
+    };
+    exit?: {
+        shortcut?: string;
+    };
+    commit?: {
+        shortcut?: string;
+    };
+    cancel?: {
+        shortcut?: string;
+    };
+}
+
+interface ModeRegistry {
+    current(): ModeDefinition;
+    setMode(id: string): void;
+    byId(id: string): ModeDefinition;
+    getVersion(): number;
+    subscribe(listener: () => void): () => void;
+}
+
+/**
+ * Configurable activation-key descriptor for tools that expose their
+ * keybinding to the host (currently Lasso and Eyedropper). Captures
+ * only the fields meaningful to a caller-supplied tool-select key —
+ * dispatcher-internal fields (`skipInEditable`, `enabled`,
+ * `preventDefault`) live on `KeyBinding` in keyHelpers.ts and are
+ * not part of the configurable surface.
+ */
+interface ToolKeybinding {
+    /** Key or list of keys to match (case-insensitive against `event.key`). */
+    key: string | readonly string[];
+    /** Require Cmd (mac) / Ctrl (others). Default `false`. */
+    mod?: boolean;
+    /** Require Alt. Default `false`. */
+    alt?: boolean;
+    /**
+     * Shift policy. `undefined`/`false` forbids shift, `true` requires
+     * shift, `'optional'` allows either.
+     */
+    shift?: boolean | 'optional';
+}
+
+/** Common payload for any hit that references a scene node. */
+interface NodeRef {
+    id: NodeId;
+    pose: unknown;
+    data: unknown;
+    meta?: Record<string, unknown>;
+}
+/** No hit — pointer landed on the background. */
+interface EmptyHit {
+    category: 'empty';
+    kind: 'empty';
+}
+/** Hit on a scene node's body. */
+interface NodeHit extends NodeRef {
+    category: 'node';
+    kind: string;
+}
+/** Hit on a node's affordance chrome (handle, anchor, etc.). */
+interface AffordanceHit extends NodeRef {
+    category: 'affordance';
+    kind: string;
+}
+/** Hit on a tool-defined target (anchor, handle, segment, etc.) supplied
+ *  via the tool's `hitOverride`. The `kind` string is the tool's own
+ *  vocabulary; the dispatcher does not interpret it. */
+interface ToolHit {
+    category: 'tool';
+    kind: string;
+    extra?: unknown;
+}
+/** Full discriminated union — every routed action's `ctx.target`. */
+type HitResult = EmptyHit | NodeHit | AffordanceHit | ToolHit;
+
+/** Phase the route was resolved against. Mirrors the spec's two-phase
+ *  vocabulary — `initial` (idle, scratch null) or `engaged` (mid-gesture). */
+type RoutePhase = 'initial' | 'engaged';
+/** Gesture channel the route fired on. */
+type RouteGesture = GestureName;
+/** Snapshot of one route resolution, emitted by the factory on each
+ *  successful lookup. Captured by the dispatcher as the "last resolved
+ *  route" for debug-overlay consumers. */
+interface RouteResolvedInfo {
+    toolId: string;
+    phase: RoutePhase;
+    gesture: RouteGesture;
+    /** Argument captured at match time for arg-bearing gestures
+     *  (`wheel` direction, `keyDown`/`keyUp` key, `multiTouchTap` fingers).
+     *  Undefined for no-arg gestures. */
+    arg: string | undefined;
+    /** Route-table key that matched (post-precedence). E.g. 'rect:selected',
+     *  '*:selected', 'rect', '*', 'empty'. For function-form `drag` (no
+     *  table), this is '*'. For keyDown/keyUp, it's the key name ('Escape',
+     *  'Enter', etc.). */
+    matchedKey: string;
+    modifiers: ModifierCombo;
+    /** The full HitResult at resolution time (snapshot — safe to read). */
+    target: HitResult;
+    /** Monotonic timestamp (ms since page load via performance.now()).
+     *  Used for "resolved Nms ago" displays. */
+    timestamp: number;
+}
+
+/** Outcome of a channel handler. `'claim'` stops dispatch for this event;
+ *  `'pass'` lets the next slot try. Handlers that return nothing are
+ *  treated as `'pass'`. */
+type Decision = 'claim' | 'pass' | void;
+/** Modifier-key snapshot at event dispatch time. `space` is included
+ *  because tools commonly use space as a hotkey-slot trigger and may
+ *  also want to read it as a flag mid-gesture. */
+interface ToolModifiers {
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+    ctrl: boolean;
+    space: boolean;
+}
+/** Per-event context passed to every channel handler. `scratch` is typed
+ *  via the tool's `TScratch` parameter; it survives across a single
+ *  gesture (pointer-down through end/cancel) and is replaced on next
+ *  gesture start by `initScratch()`. */
+interface ToolCtx<TScratch = unknown> {
+    worldX: number;
+    worldY: number;
+    modifiers: ToolModifiers;
+    /** Hit-test result for the current event. Populated by the dispatcher
+     *  before each handler call. Tools that don't use declarative routing
+     *  can ignore this. Optional for migration; will become
+     *  required once the routing migration is complete. */
+    target?: HitResult;
+    selection: SelectionApi;
+    /** Adapter/scene access — opaque at this layer; tools that need it
+     *  cast to a known shape. This layer doesn't constrain it. */
+    adapter: unknown;
+    applyOps: (ops: Op[], label: string) => void;
+    /** Current viewport. Reflects camera-position semantics — see
+     *  `View` JSDoc. */
+    view: View;
+    /** Mutate the viewport. In controlled mode this calls the consumer's
+     *  `onViewChange`; in uncontrolled mode it updates Canvas's internal
+     *  state. View changes are not undoable. */
+    setView: (next: View) => void;
+    /** Bounding rect of the canvas element in viewport coords. Used by
+     *  zoom/pan tools to convert event clientX/clientY to canvas-relative
+     *  anchors. */
+    canvasRect: DOMRect;
+    /** Screen-space pointer coords relative to `canvasRect`. Useful for
+     *  viewport tools that pan/zoom in screen space (e.g. hand-pan
+     *  computes deltas in pixels, not world units). Optional — populated
+     *  by the dispatcher on pointer events; absent on keyboard events. */
+    screenPoint?: {
+        x: number;
+        y: number;
+    };
+    /** Optional debug sink. When `<Canvas debug={...}>` is enabled, Canvas
+     *  threads its sink here so tool-internal hit math (handle hitboxes,
+     *  rotation handle, etc.) lands in the same overlay as Canvas's own
+     *  bounds/origin records. Tools should call this conditionally with `?.`. */
+    debug?: DebugSink;
+    /** Kit-internal: route-resolution reporter. The dispatcher populates
+     *  this; the declarative routing factory calls it after each successful
+     *  resolveRoute() hit so the dispatcher can publish the last-resolved
+     *  snapshot to debug-overlay consumers. Underscore prefix signals
+     *  "do not consume in tool code." */
+    __reportRoute?: (info: RouteResolvedInfo) => void;
+    scratch: TScratch;
+}
+interface PointerChannel<TScratch> {
+    onDown?: (e: PointerEvent, ctx: ToolCtx<TScratch>) => Decision;
+    onClick?: (e: PointerEvent, ctx: ToolCtx<TScratch>) => Decision;
+}
+interface DragChannel<TScratch> {
+    onStart?: (e: PointerEvent, ctx: ToolCtx<TScratch>) => Decision;
+    onMove?: (e: PointerEvent, ctx: ToolCtx<TScratch>) => Decision;
+    onEnd?: (e: PointerEvent, ctx: ToolCtx<TScratch>) => Decision;
+    onCancel?: (ctx: ToolCtx<TScratch>) => void;
+}
+interface KeyboardChannel<TScratch> {
+    onDown?: (e: KeyboardEvent, ctx: ToolCtx<TScratch>) => Decision;
+    onUp?: (e: KeyboardEvent, ctx: ToolCtx<TScratch>) => Decision;
+}
+interface WheelChannel<TScratch> {
+    onWheel?: (e: WheelEvent, ctx: ToolCtx<TScratch>) => Decision;
+}
+/** Double-tap (double-click) channel. Fires on the pointerup of the second
+ *  sub-threshold tap when it follows a previous sub-threshold tap within the
+ *  dispatcher's `dblTap.windowMs` and `dblTap.maxDistance` (CSS px). The
+ *  scratch handed to the handler is fresh — `dblTap` is not part of a drag
+ *  pipeline, so `initScratch()` runs immediately before the call. A `'claim'`
+ *  return suppresses the regular `pointer.onClick` for this gesture. */
+interface DblTapChannel<TScratch> {
+    onTap?: (e: PointerEvent, ctx: ToolCtx<TScratch>) => Decision;
+}
+/** World-space AABB shape used by `previewBounds`. Alias of the kit-wide
+ *  `Bounds` type — the optional `rotation` field carries through so a tool
+ *  can report an oriented preview rect (e.g. mid-rotate). */
+type ToolBounds = Bounds;
+/** Presentation metadata for tool palettes / menus. Optional on every
+ *  tool — consumers that render a palette (`<ToolPalette>`) read these
+ *  fields to display the tool; consumers that don't can ignore them.
+ *
+ *  Note: cursor is NOT here. The top-level `Tool.cursor` field below is
+ *  already plumbed through `<Canvas>` to `style.cursor` on the host. */
+interface ToolPresentation<TScratch = unknown> {
+    /** Human-readable label, distinct from the `id`. Falls back to `id`. */
+    label?: string;
+    /** Inline-SVG icon component output. May be a static `ReactNode` or a
+     *  function of scratch state (rare; useful for shape-aware affordances). */
+    icon?: react.ReactNode | ((scratch?: TScratch) => react.ReactNode);
+    /** Palette grouping key. Tools sharing a group render contiguously
+     *  with separators between groups. Free-form string; the kit
+     *  recommends 'select' | 'shape' | 'draw' | 'type' | 'view'. */
+    group?: string;
+    /** Display override for the keyboard shortcut. When omitted the palette
+     *  derives one from `Tool.keybinding` via its own formatter. */
+    shortcut?: string;
+}
+/** Full Tool record. */
+interface Tool<TScratch = unknown> {
+    id: string;
+    /**
+     * App-level capability tags for modality. The `weasel-modes` package's
+     * `eligibleForMode(mode, capabilities)` predicate consumes these to decide
+     * whether the tool is usable in the active mode. Tags are extensible
+     * strings — apps can define their own. Untagged tools are treated as
+     * ineligible by all modes except those whose `allows` list includes
+     * every implicit-or-declared tag (i.e. `normal` in the default preset).
+     */
+    capabilities?: CapabilityTag[];
+    /** Optional caller-supplied key. Most built-in tools have their activation
+     *  key declared in `BUILTIN_SELECT_KEYS` in `useKeybindings.ts`; this field
+     *  is for tools that want their activation key to be configurable by the
+     *  host (currently Lasso and Eyedropper). The dynamic loop in
+     *  `useKeybindings.ts` picks this up and appends a binding entry to the
+     *  consolidated `tool.activate` action (with `opts.params.toolId` set so
+     *  the invoker knows which tool to switch to). */
+    keybinding?: ToolKeybinding;
+    initScratch?: () => TScratch;
+    onActivate?: (ctx: ToolCtx<TScratch>) => void;
+    onDeactivate?: (ctx: ToolCtx<TScratch>) => void;
+    pointer?: PointerChannel<TScratch>;
+    drag?: DragChannel<TScratch>;
+    keyboard?: KeyboardChannel<TScratch>;
+    wheel?: WheelChannel<TScratch>;
+    /** Double-tap channel — fires when two sub-threshold taps land within
+     *  `dblTap.windowMs` / `dblTap.maxDistance` of each other. Lets tools
+     *  enter modal modes (e.g. select → edit-anchors) without consumers
+     *  attaching `onDoubleClick` to a wrapper DOM node. */
+    dblTap?: DblTapChannel<TScratch>;
+    /**
+     * State-aware predicate. When true, this tool claims every pointerdown
+     * and bypasses the affordance layer hit-test pipeline. Used by tools
+     * in modal states (pen mid-path, text mid-edit) where affordance hits
+     * would otherwise interrupt the in-progress gesture.
+     *
+     * Default: undefined (treated as false). Called once per pointerdown
+     * with the tool's current ctx (scratch + view + modifiers).
+     */
+    claimsAll?: (ctx: ToolCtx<TScratch>) => boolean;
+    cursor?: string | ((ctx: ToolCtx<TScratch>) => string);
+    /** Presentation metadata for tool palettes. See `ToolPresentation`. */
+    presentation?: ToolPresentation<TScratch>;
+    /** Returns the in-flight preview pose for `id` if this tool is mid-gesture
+     *  on it; otherwise `null`. Lets `Canvas.helpersRef.getEffectivePose`
+     *  reflect live gesture state without reaching into hook internals. The
+     *  return type is `unknown` here because the Tool interface is pose-agnostic;
+     *  callers that know the pose shape (e.g. Canvas typed by `TPose`) cast at
+     *  the use site. */
+    previewPose?: (id: string) => unknown;
+    /** Returns the in-flight preview bounds for `id` if this tool is mid-gesture
+     *  on it; otherwise `null`. Optional companion to `previewPose` for tools that
+     *  can compute bounds without round-tripping through a geometry adapter. */
+    previewBounds?: (id: string) => ToolBounds | null;
+    /** Returns ids whose committed scene-render should be suppressed while this
+     *  tool is mid-gesture (e.g. cascade move's dragged + descendant ids whose
+     *  preview ghosts replace the committed pose). The standard scene slot
+     *  consults this alongside `previewPose` to avoid double-rendering. Returns
+     *  `null` when no gesture is in flight. */
+    previewIds?: () => Iterable<string> | null;
+    /** Optional overlay layer rendered on top of the scene/chrome whenever
+     *  this tool is in any active slot (active, hotkey, or ambient).
+     *  The layer's `draw` function reads from this tool's scratch via React
+     *  closure (re-evaluated each render). Return early from `draw` to render
+     *  nothing — typically gated on a scratch field like
+     *  `if (!scratch.overlay) return`. */
+    overlay?: RenderLayer<unknown>;
+    /** Declarative gesture-bindings the
+     *  dispatcher consults while this tool is active. Empty/undefined keeps
+     *  legacy imperative-channel behavior. See
+     *  `docs/superpowers/specs/2026-05-16-registry-unification-design.md`. */
+    bindings?: GestureBinding[];
+    /**
+     * Optional. When set, the dispatcher consults this before its built-in
+     * node/empty hit-test. If it returns a value, that target replaces the
+     * default `target` on the routed action's ctx. The string `target` is
+     * the tool's own vocabulary — the dispatcher does not interpret it.
+     *
+     * Used for tools that need richer sub-object hit categories (e.g., pen
+     * edit-mode's anchor/handle/segment vs the default node/empty).
+     */
+    hitOverride?(ctx: {
+        worldX: number;
+        worldY: number;
+        scratch: TScratch;
+        view: View;
+        modifiers: ToolModifiers;
+    }): {
+        target: string;
+        extra?: unknown;
+    } | null;
+    /** Reflection escape hatch: when this `Tool` was produced by `defineTool`,
+     *  the source `ToolDef` is attached here so introspection consumers
+     *  (`buildActionRegistry`, `findConflicts`, the toolkit-builder UI, the
+     *  reflection demo) can walk the declarative source rather than the
+     *  translated runtime channels. Tools constructed without `defineTool`
+     *  may leave this undefined. Typed as `unknown` to keep this file from
+     *  importing the routing types — consumers cast at the use site. */
+    def?: unknown;
+}
+/** Internal alias for "a Tool of any scratch type" — used in registries and
+ *  dispatchers that hold tools of heterogeneous scratch shapes. `any` is
+ *  intentional: `Tool<TScratch>` is invariant in TScratch, so `Tool<unknown>`
+ *  is too strict for containers that accept any concrete `Tool<T>`. */
+type AnyTool = Tool<any>;
+
+/**
+ * @experimental
+ * Result of an affordance hit — what the dispatcher wires up as the gesture.
+ * Nominates the drag channel and (optionally) initial scratch state.
+ */
+interface AffordanceBinding<TScratch = unknown> {
+    drag: DragChannel<TScratch>;
+    /** Initial scratch passed to drag.onStart. Lets the affordance pre-fill
+     *  state from what its region's binding already computed (anchor: 'br',
+     *  targetId: 'g1', etc.) so the tool's onStart doesn't re-derive it. */
+    initialScratch?: TScratch;
+}
+
+/**
+ * Canvas size in CSS pixels — passed to `draw` for layers that anchor to
+ * canvas edges (e.g. the debug overlay's layer-list panel). The GL backend
+ * supplies it explicitly so layers don't have to know about DPR.
+ */
+interface Dims {
+    width: number;
+    height: number;
+}
+/**
+ * A single named render sub-layer within a canvas renderer.
+ *
+ * @template TData - The data object passed to each draw call.
+ */
+interface RenderLayer<TData> {
+    /** Unique identifier used in visibility maps and ordering arrays. */
+    id: string;
+    /** Human-readable name for UI toggles. */
+    label: string;
+    /**
+     * Emit a DrawCommand tree for the GL backend to dispatch.
+     *
+     * For world-space layers (the default), emit commands in WORLD COORDS —
+     * `drawLayers` automatically wraps them in `{ kind: 'group', transform:
+     * viewToMat3(view), ... }` before handing them to the renderer. Do NOT
+     * apply the view transform yourself.
+     *
+     * For screen-space layers (`space: 'screen'`), emit commands in CSS-pixel
+     * coords directly; `drawLayers` passes them through unchanged. If part
+     * of a screen-space layer's output needs to track the view, wrap that
+     * subset manually with `viewToMat3(view)`.
+     */
+    draw: (data: TData, view: View, dims: Dims) => DrawCommand[];
+    /**
+     * Whether the layer is shown when no explicit visibility entry exists.
+     * Defaults to `true` when absent.
+     */
+    defaultVisible?: boolean;
+    /**
+     * When true, the layer is always drawn regardless of the visibility map.
+     * Useful for layers that must never be hidden (e.g. base grid).
+     */
+    alwaysOn?: boolean;
+    /**
+     * Coordinate space the layer draws in.
+     *
+     * - `'world'` (default): the layer's `draw` returns world-space commands;
+     *   `drawLayers` wraps them in a `kind: 'group'` with `viewToMat3(view)`
+     *   automatically.
+     * - `'screen'`: the layer's `draw` returns screen-space (CSS-pixel)
+     *   commands; `drawLayers` passes them through unchanged. World-anchored
+     *   chrome inside a screen-space layer must call `worldToScreen` or wrap
+     *   the relevant subset with `viewToMat3(view)` manually.
+     */
+    space?: 'world' | 'screen';
+    /**
+     * Optional hit-test. When defined, the dispatcher consults this on
+     * pointerdown (top-down layer order) before falling through to the
+     * active tool's slot walk. First non-null result wins; null means
+     * "I don't claim this hit, try the next layer."
+     *
+     * Coordinates are world-space. The `data` arg is the layer's
+     * configured data slot (same as `draw`); `view` and `dims` mirror
+     * `draw`'s arguments.
+     */
+    hitTest?: (worldX: number, worldY: number, data: TData, view: View, dims: Dims, 
+    /** Chrome-caps visibility predicate. When supplied, the layer must
+     *  not return a hit from any chrome element whose id reports
+     *  `false`. Absent → every element is hittable. */
+    isVisible?: (id: string) => boolean) => AffordanceBinding | null;
+    /**
+     * Called on every pointermove when no gesture is currently captured.
+     * Lets layers (e.g. HUD widgets) track hover state without participating
+     * in the drag pipeline. Coords are world-space; the layer is responsible
+     * for any further conversion (e.g. world→screen for screen-space layers)
+     * and for its own throttling.
+     */
+    onUncapturedMove?: (worldX: number, worldY: number, evt: PointerEvent, view: View, dims: Dims) => void;
+    /**
+     * Called when the cursor leaves the canvas element. Lets layers clear
+     * any hover state they're holding.
+     */
+    onUncapturedLeave?: () => void;
+}
+
+interface ToolsDispatcher {
+    onPointerDown: (e: PointerEvent) => void;
+    onPointerMove: (e: PointerEvent) => void;
+    onPointerUp: (e: PointerEvent) => void;
+    onKeyDown: (e: KeyboardEvent) => void;
+    onKeyUp: (e: KeyboardEvent) => void;
+    onWheel: (e: WheelEvent) => void;
+    /** Force-cancel any in-flight gesture (used on explicit tool switch). */
+    cancelGesture: () => void;
+    /** Whether a gesture is currently in flight. Used by `useTools` to
+     *  decide whether a modifier-key press should engage the hotkey slot
+     *  (no, if mid-gesture). */
+    hasActiveGesture: () => boolean;
+    /** Scratch of the in-flight gesture, or `null` when idle. Exposed so
+     *  consumers (cursor resolution, debug overlays) can read what the active
+     *  tool is currently tracking. Read-only — do NOT mutate via this getter. */
+    getActiveScratch: () => unknown;
+    /** Most recent route resolution emitted by a declarative tool, or null
+     *  if none has fired yet. Snapshot — safe to read on every render. */
+    getLastRoute: () => RouteResolvedInfo | null;
+    /** Resolve a synthetic (phase, gesture, hit, modifiers) query against the
+     *  current slot occupants WITHOUT executing the matched action. Walks slots
+     *  in real precedence order (hotkey > active > ambient) and consults each
+     *  tool's attached `def` (the declarative `ToolDef` produced by
+     *  `defineTool`). Tools without an attached `def` (imperative-only) are
+     *  invisible to this query. Returns the first match, or null if no slot
+     *  resolves the query. Pure: no scratch mutation, no scene mutation, no
+     *  RouteResolvedInfo emission. */
+    resolveOnly: (query: ResolveQuery) => ResolveResult | null;
+}
+/** Synthetic resolution query — what the static widget asks "if a pointer
+ *  event landed on `hit` with these `modifiers`, which declarative route
+ *  would the dispatcher fire in this phase + gesture?" */
+interface ResolveQuery {
+    phase: 'initial' | 'engaged';
+    gesture: 'click' | 'drag' | 'pointerDown' | 'dblTap' | 'wheel';
+    hit: HitResult;
+    modifiers: ToolModifiers;
+}
+/** Successful resolution: which tool, in which slot, matched which route-table
+ *  key. `matchedKey` is `'*'` for function-form drag (no table to discriminate)
+ *  and for wheel routes (single ActionFn). */
+interface ResolveResult {
+    toolId: string;
+    slot: 'hotkey' | 'active' | 'ambient';
+    gesture: 'click' | 'drag' | 'pointerDown' | 'dblTap' | 'wheel';
+    phase: 'initial' | 'engaged';
+    matchedKey: string;
+}
+
+interface ToolsApi {
+    /** Current active-slot tool id. */
+    active: string;
+    /** Set the active-slot tool. Cancels any in-flight gesture. */
+    setActive: (id: string) => void;
+    /** Currently hotkey-engaged tool id (or `null`). Derived as the top of
+     *  the hotkey stack for backwards compat with the pre-stack API. */
+    hotkeyEngaged: string | null;
+    /** Engage a hotkey-slot tool by id. No-op if a gesture is in flight. */
+    engageHotkey: (id: string) => void;
+    /** Disengage the hotkey-slot tool, if any. */
+    disengageHotkey: () => void;
+    /** All always-on tools, in registration order. */
+    ambient: readonly AnyTool[];
+    /** Full registry — for userland UI (palette buttons, etc.). */
+    registry: Readonly<Record<string, AnyTool>>;
+    /** The dispatcher `<Canvas>` wires to its DOM events. */
+    dispatcher: ToolsDispatcher;
+    /** Increments whenever an in-flight gesture starts, transitions phase, or
+     *  ends. Consumers (e.g. `<Canvas>` cursor resolution) include this in
+     *  their render deps to re-evaluate derived state on real DOM events
+     *  rather than waiting for an unrelated re-render. */
+    gestureTick: number;
+    /** Returns true if a tool with the given id is in the registry or ambient list. */
+    has(id: string): boolean;
+    /** All overlay layers from currently-engaged tools (active slot, hotkey
+     *  slot if engaged, all ambient slot tools). Filters out tools with no
+     *  `overlay` field. Order: active, then hotkey (if engaged), then
+     *  ambient (registration order). */
+    getActiveOverlays(): RenderLayer<unknown>[];
+}
+
+interface SidebarProps {
+    /**
+     * Edge the sidebar docks to. Adds a class hook (`s.left` / `s.right`)
+     * so consumers can target either edge for borders, shadows, etc.
+     * Purely cosmetic — layout is the parent's job.
+     */
+    side?: 'left' | 'right';
+    /**
+     * Accessible label — rendered onto the `<aside>`. Without it, screen
+     * readers fall back to "complementary landmark," which is fine for
+     * apps with a single sidebar but ambiguous when there's both a left
+     * and a right.
+     */
+    ariaLabel?: string;
+    children?: ReactNode;
+    className?: string;
+    /** Inline style — useful for width-as-custom-property handles or any
+     *  other one-off CSS property the consumer wants to set dynamically. */
+    style?: CSSProperties;
+}
+/**
+ * Generic sidebar shell — `<aside>` with column layout and token-driven
+ * surface treatment. Width, sticky positioning, and resize handles stay
+ * the consumer's concern (every app has its own layout grid); the kit
+ * just provides the chrome.
+ *
+ * Pair with `<SidebarPanel>` for collapsible sections.
+ */
+declare function Sidebar(props: SidebarProps): react_jsx_runtime.JSX.Element;
+
+interface SidebarPanelProps {
+    /** Title rendered in the panel's header row. */
+    title?: ReactNode;
+    /**
+     * Collapsed state — when true, only the header paints; the body is
+     * omitted. Caller owns the state (typically via prefs) and flips it
+     * back via `onToggleCollapse`.
+     */
+    collapsed?: boolean;
+    /**
+     * Click handler for the title row. When provided, the header renders
+     * as a button (chevron + label) and acts as the collapse toggle.
+     * When omitted, the title is static text and the panel can't collapse.
+     */
+    onToggleCollapse?(): void;
+    /**
+     * Optional close handler — when provided, the header gains a `×`
+     * button on the trailing edge. Caller flips its "hidden" state and
+     * conditionally unmounts the panel from the parent.
+     */
+    onHide?(): void;
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * Generic collapsible panel section for sidebars. Pure presentation —
+ * caller manages `collapsed`/`hidden` state externally (the pattern is
+ * to drive it from app prefs so the Preferences modal and inline
+ * chevrons toggle the same map).
+ *
+ * Pair with `<Sidebar>` for the docked column layout.
+ */
+declare function SidebarPanel(props: SidebarPanelProps): react_jsx_runtime.JSX.Element;
+
+interface ToolButtonProps {
+    /** Icon node (typically an SVG component). */
+    icon: ReactNode;
+    /** Human-readable label shown under the icon. */
+    label: string;
+    /** Optional shortcut hint (e.g. "V" or "⌘Z"). */
+    shortcut?: string;
+    /** Selected/active state — toggles the active visual treatment. */
+    active?: boolean;
+    /** Disabled state — passes through to the underlying button. */
+    disabled?: boolean;
+    /**
+     * When true, sets `aria-disabled="true"` on the button without using the
+     * native `disabled` attribute. This keeps the button focusable and reachable
+     * by keyboard (roving-tabindex still applies) while marking it as ineligible
+     * to screen readers. The caller is responsible for making `onClick` a no-op.
+     */
+    ariaDisabled?: boolean;
+    /**
+     * Whether this button is the currently tabbable member of its toolbar.
+     * Toolbars use roving tabindex: exactly one button has `tabIndex=0` at
+     * a time; the rest are `-1`. Caller manages which.
+     */
+    tabbable?: boolean;
+    /** Click handler. */
+    onClick(): void;
+    /**
+     * Tooltip content. Defaults to `label` (plus `shortcut` if provided).
+     */
+    title?: string;
+    /** Additional class for the root button. */
+    className?: string;
+}
+/**
+ * Generic icon-+-label toolbar button — building block for `ToolPalette`
+ * and similar surfaces. Headless about layout direction (parent group
+ * supplies flex direction via `ToolGroup`). Theme via `--wzl-*` tokens.
+ */
+declare function ToolButton(props: ToolButtonProps): react_jsx_runtime.JSX.Element;
+
+interface ToolGroupProps {
+    children: ReactNode;
+    /**
+     * Lays children along an axis. `'vertical'` (default) stacks them in
+     * a column; `'horizontal'` lays them in a row. Independent of the
+     * parent toolbar's own orientation.
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /**
+     * Optional `data-group` attribute — useful for parents that want to
+     * select the group from CSS or tests by name.
+     */
+    groupKey?: string;
+    /** Accessible name for the group (rendered as `aria-label`). */
+    ariaLabel?: string;
+    className?: string;
+}
+/**
+ * Generic toolbar group — a `role="group"` flex container that arranges
+ * `<ToolButton>`s (or any children) along a chosen axis. No visual chrome
+ * beyond layout; theming lives on the buttons.
+ */
+declare function ToolGroup(props: ToolGroupProps): react_jsx_runtime.JSX.Element;
+
+interface ShortcutInput {
+    key: string | readonly string[];
+    mod?: boolean;
+    alt?: boolean;
+    shift?: boolean | 'optional';
+}
+/** Format a shortcut as an array of display chips, one per key — modifier
+ *  icons (⌘, ↑, ⌥) followed by the key glyph. 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): readonly string[] | undefined;
+/** Format a shortcut as a single display string. Order: mod, shift, alt,
+ *  key. 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): string | undefined;
+
+interface ToolPaletteProps {
+    tools: ToolsApi;
+    orientation?: 'vertical' | 'horizontal';
+    className?: string;
+    /** Derive the keyboard shortcut for a tool button from the action registry.
+     *  Called with the tool's id; return `undefined` to suppress a chip. When
+     *  omitted, falls back to `tool.keybinding` (legacy path). */
+    lookupShortcut?: (toolId: string) => ShortcutInput | undefined;
+    /**
+     * Optional mode registry. When provided, tools whose `capabilities` do not
+     * match the current mode are rendered greyed-out, aria-disabled, and their
+     * onClick is suppressed. When omitted, all tools are treated as eligible
+     * (preserves existing behaviour in consumers that haven't wired a registry).
+     */
+    modeRegistry?: ModeRegistry;
+    /**
+     * Presentation-group display order. Groups not listed keep their registry
+     * insertion order after the listed ones; `misc` always renders last.
+     * Defaults to `['select', 'shape', 'draw', 'type', 'view']`.
+     */
+    groupOrder?: readonly string[];
+}
+declare function ToolPalette(props: ToolPaletteProps): react_jsx_runtime.JSX.Element;
+
+type FieldOrientation = 'stacked' | 'row';
+type FieldProps = {
+    orientation?: FieldOrientation;
+    className?: string;
+    children?: ReactNode;
+};
+/**
+ * Layout primitive that arranges a label, control, hint, and error in the
+ * canonical weasel-ui form-row shape. The control itself owns its semantics
+ * (RAC `TextField`, `Checkbox`, etc.); this just paints the layout.
+ *
+ * Most users will instead reach for `Input` / `Checkbox` / `Switch`, which
+ * compose Field internally. Use Field directly when you need a custom
+ * control to sit in the same visual rhythm.
+ */
+declare function Field({ orientation, className, children }: FieldProps): react_jsx_runtime.JSX.Element;
+declare const fieldClasses: {
+    root: string;
+    row: string;
+    label: string;
+    hint: string;
+    error: string;
+};
+
+type InputProps = Omit<TextFieldProps, 'children' | 'className'> & {
+    label?: ReactNode;
+    description?: ReactNode;
+    errorMessage?: ReactNode | ((v: ValidationResult) => ReactNode);
+    placeholder?: string;
+    leadingAdornment?: ReactNode;
+    trailingAdornment?: ReactNode;
+    className?: string;
+};
+/**
+ * Single-line text input wrapping React Aria's TextField. Supplies a
+ * default skin against the `--wzl-*` token system, and exposes the
+ * familiar label / description / errorMessage / adornment slot shape.
+ *
+ * `ref` forwards to the underlying `<input>`.
+ */
+declare const Input: react.ForwardRefExoticComponent<Omit<TextFieldProps, "children" | "className"> & {
+    label?: ReactNode;
+    description?: ReactNode;
+    errorMessage?: ReactNode | ((v: ValidationResult) => ReactNode);
+    placeholder?: string;
+    leadingAdornment?: ReactNode;
+    trailingAdornment?: ReactNode;
+    className?: string;
+} & react.RefAttributes<HTMLInputElement>>;
+
+type CheckboxProps = Omit<CheckboxProps$1, 'children' | 'className'> & {
+    children?: ReactNode;
+    className?: string;
+};
+/**
+ * Single checkbox wrapping React Aria's Checkbox. Supports indeterminate
+ * via `isIndeterminate`. The label is supplied as children.
+ */
+declare const Checkbox: react.ForwardRefExoticComponent<Omit<CheckboxProps$1, "children" | "className"> & {
+    children?: ReactNode;
+    className?: string;
+} & react.RefAttributes<HTMLLabelElement>>;
+
+type SwitchProps = Omit<SwitchProps$1, 'children' | 'className'> & {
+    children?: ReactNode;
+    className?: string;
+};
+declare const Switch: react.ForwardRefExoticComponent<Omit<SwitchProps$1, "children" | "className"> & {
+    children?: ReactNode;
+    className?: string;
+} & react.RefAttributes<HTMLLabelElement>>;
+
+type TabsProps = Omit<TabsProps$1, 'className' | 'children'> & {
+    children?: ReactNode;
+    className?: string;
+};
+declare function Tabs({ children, className, ...rest }: TabsProps): react_jsx_runtime.JSX.Element;
+type TabListProps<T extends object> = Omit<TabListProps$1<T>, 'className'> & {
+    className?: string;
+};
+declare function TabList<T extends object>({ className, ...rest }: TabListProps<T>): react_jsx_runtime.JSX.Element;
+type TabProps = Omit<TabProps$1, 'className' | 'children'> & {
+    children?: ReactNode;
+    className?: string;
+};
+declare function Tab({ children, className, ...rest }: TabProps): react_jsx_runtime.JSX.Element;
+type TabPanelProps = Omit<TabPanelProps$1, 'className' | 'children'> & {
+    children?: ReactNode;
+    className?: string;
+};
+declare function TabPanel({ children, className, ...rest }: TabPanelProps): react_jsx_runtime.JSX.Element;
+
+type RadioGroupProps = Omit<RadioGroupProps$1, 'children' | 'className'> & {
+    label?: ReactNode;
+    description?: ReactNode;
+    errorMessage?: ReactNode | ((v: ValidationResult) => ReactNode);
+    children?: ReactNode;
+    className?: string;
+};
+declare function RadioGroup(props: RadioGroupProps): react_jsx_runtime.JSX.Element;
+type RadioProps = Omit<RadioProps$1, 'className' | 'children'> & {
+    children?: ReactNode;
+    className?: string;
+};
+declare function Radio({ children, className, ...rest }: RadioProps): react_jsx_runtime.JSX.Element;
+
+type NumberFieldProps = Omit<NumberFieldProps$1, 'children' | 'className'> & {
+    label?: ReactNode;
+    description?: ReactNode;
+    errorMessage?: ReactNode | ((v: ValidationResult) => ReactNode);
+    /** Hide the up/down stepper buttons. Defaults to false. */
+    hideSteppers?: boolean;
+    /** Native input placeholder — e.g. `'Mixed'` for a multi-selection
+     *  editor with no shared value. */
+    placeholder?: string;
+    className?: string;
+};
+declare const NumberField: react.ForwardRefExoticComponent<Omit<NumberFieldProps$1, "children" | "className"> & {
+    label?: ReactNode;
+    description?: ReactNode;
+    errorMessage?: ReactNode | ((v: ValidationResult) => ReactNode);
+    /** Hide the up/down stepper buttons. Defaults to false. */
+    hideSteppers?: boolean;
+    /** Native input placeholder — e.g. `'Mixed'` for a multi-selection
+     *  editor with no shared value. */
+    placeholder?: string;
+    className?: string;
+} & react.RefAttributes<HTMLInputElement>>;
+
+type SelectOption = {
+    value: string;
+    label: ReactNode;
+    isDisabled?: boolean;
+};
+type Key$1 = string | number;
+type SelectProps<T extends Key$1 = string> = Omit<SelectProps$1<object>, 'children' | 'className' | 'selectedKey' | 'defaultSelectedKey' | 'onSelectionChange'> & {
+    label?: ReactNode;
+    description?: ReactNode;
+    errorMessage?: ReactNode | ((v: ValidationResult) => ReactNode);
+    placeholder?: string;
+    /** Either pass `options` for a quick render, or `children` for full control. */
+    options?: ReadonlyArray<SelectOption & {
+        value: T;
+    }>;
+    children?: ReactNode;
+    selectedKey?: T | null;
+    defaultSelectedKey?: T;
+    onSelectionChange?: (key: T) => void;
+    className?: string;
+};
+/**
+ * Form select wrapping React Aria's Select. Pass either `options` for a
+ * quick declarative render or `children` of `<SelectItem>` for control over
+ * each row.
+ *
+ * The selection key type is parameterized so consumers with a string-literal
+ * union for `value` (e.g. `'r' | 'g' | 'b'`) get a typed `onSelectionChange`.
+ */
+declare function Select<T extends Key$1 = string>(props: SelectProps<T>): react_jsx_runtime.JSX.Element;
+type SelectItemProps = Omit<ListBoxItemProps, 'className' | 'children'> & {
+    children?: ReactNode;
+    className?: string;
+};
+declare function SelectItem({ children, className, ...rest }: SelectItemProps): react_jsx_runtime.JSX.Element;
+
+type ComboBoxOption = {
+    value: string;
+    label: ReactNode;
+    textValue?: string;
+    isDisabled?: boolean;
+};
+type Key = string | number;
+type ComboBoxProps<T extends Key = string> = Omit<ComboBoxProps$1<object>, 'children' | 'className' | 'selectedKey' | 'defaultSelectedKey' | 'onSelectionChange'> & {
+    label?: ReactNode;
+    description?: ReactNode;
+    errorMessage?: ReactNode | ((v: ValidationResult) => ReactNode);
+    placeholder?: string;
+    options?: ReadonlyArray<ComboBoxOption & {
+        value: T;
+    }>;
+    children?: ReactNode;
+    selectedKey?: T | null;
+    defaultSelectedKey?: T;
+    onSelectionChange?: (key: T | null) => void;
+    emptyLabel?: ReactNode;
+    className?: string;
+};
+/**
+ * Filterable single-select wrapping React Aria's ComboBox. The user can
+ * type to filter; selection commits to `onSelectionChange`. When no value
+ * is in the input, selection clears (key becomes null).
+ */
+declare function ComboBox<T extends Key = string>(props: ComboBoxProps<T>): react_jsx_runtime.JSX.Element;
+type ComboBoxItemProps = Omit<ListBoxItemProps, 'className'> & {
+    className?: string;
+};
+declare function ComboBoxItem({ className, ...rest }: ComboBoxItemProps): react_jsx_runtime.JSX.Element;
+
+type RangeSliderProps = Omit<SliderProps$1, 'children' | 'className'> & {
+    label?: ReactNode;
+    /** Show the current value next to the label. Defaults to true when a
+     *  label is supplied. */
+    showOutput?: boolean;
+    /** Format the rendered value(s). Useful for units (`v => `${v}%``). */
+    formatOutput?: (v: number | number[]) => ReactNode;
+    className?: string;
+};
+/**
+ * Linear range slider on React Aria. Single-value by default; pass an array
+ * to `value` / `defaultValue` for multi-thumb. Distinct from the kit's
+ * canvas-scrub `Slider`, which is shaped for tool-canvas interactions.
+ */
+declare function RangeSlider(props: RangeSliderProps): react_jsx_runtime.JSX.Element;
+
+type DialogProps = Omit<ModalOverlayProps, 'children' | 'className'> & {
+    /** Heading rendered in the dialog's default header. Omit when supplying
+     *  a custom `header` slot via children. */
+    title?: ReactNode;
+    /** Show the built-in close button. Defaults to true when `onOpenChange`
+     *  is wired so the user has an escape hatch. */
+    showCloseButton?: boolean;
+    /** Body content. */
+    children?: ReactNode;
+    /** Footer slot — typically action buttons. */
+    footer?: ReactNode;
+    /** ARIA role. Defaults to `dialog`. Use `alertdialog` for confirms. */
+    role?: DialogProps$1['role'];
+    /** Class applied to the modal box (inside the overlay). */
+    className?: string;
+};
+/**
+ * Modal dialog wrapping React Aria. Supplies a default header (title +
+ * close), scrollable body, and footer slot. Pass `isOpen` + `onOpenChange`
+ * for controlled visibility, or omit both and use a `<DialogTrigger>` from
+ * `react-aria-components` upstream of this component.
+ *
+ * Escape, click-outside, focus trap, and scroll lock all come from the
+ * underlying primitives.
+ */
+declare function Dialog(props: DialogProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Coordinate transforms (model ↔ plot) for Plot2D. Pure / deterministic —
+ * no DOM, no React, no state.
+ *
+ * Model space: caller-defined xRange × yRange. Y axis goes UP.
+ * Plot space: 0..width × 0..height in CSS pixels. Y axis goes DOWN (SVG).
+ */
+interface Point {
+    x: number;
+    y: number;
+}
+
+interface GridSettings {
+    /** Number of evenly-spaced internal grid lines per axis (excluding
+     *  the edges). Applied to both x and y. Default 3. */
+    divisions?: number;
+    /** Stroke color override. When omitted, uses `var(--plot-grid)`. */
+    color?: string;
+}
+interface AxesSettings {
+    /** Stroke color override. When omitted, uses `var(--plot-axis)`. */
+    color?: string;
+}
+interface Plot2DCoords {
+    plot: Point;
+    model: Point;
+}
+interface Plot2DProps {
+    width: number;
+    height: number;
+    /** Model-space x range. Default [0, 1]. */
+    xRange?: readonly [number, number];
+    /** Model-space y range. Default [0, 1]. */
+    yRange?: readonly [number, number];
+    /** Background grid. `false` / `null` / omitted = no grid. Pass `{}`
+     *  for default (3 divisions per axis) or populated GridSettings. */
+    grid?: GridSettings | false | null;
+    /** Axis lines. `false` / `null` = no axes. Omitted = default-styled
+     *  axes (on). Pass AxesSettings to customize. */
+    axes?: AxesSettings | false | null;
+    /** Forwarded to the underlying svg. Consumer opts into focus this way. */
+    tabIndex?: number;
+    className?: string;
+    style?: CSSProperties;
+    /** Pointer down on the SVG. Receives both plot- and model-space coords
+     *  pre-computed so consumers don't repeat the rect/transform dance. */
+    onPointerDown?: (e: PointerEvent$1<SVGSVGElement>, coords: Plot2DCoords) => void;
+    onKeyDown?: (e: KeyboardEvent$1<SVGSVGElement>) => void;
+    children?: ReactNode;
+}
+interface Plot2DHandle {
+    readonly svg: SVGSVGElement | null;
+    plotToModel(pt: Point): Point;
+    modelToPlot(pt: Point): Point;
+    /** Convert a DOM event's clientX/clientY (e.g. from a window-attached
+     *  pointermove during drag) to plot-space. */
+    clientToPlot(e: {
+        clientX: number;
+        clientY: number;
+    }): Point;
+    /** Convenience: clientToPlot → plotToModel. */
+    clientToModel(e: {
+        clientX: number;
+        clientY: number;
+    }): Point;
+    readonly width: number;
+    readonly height: number;
+}
+declare const Plot2D: react.ForwardRefExoticComponent<Plot2DProps & react.RefAttributes<Plot2DHandle>>;
+
+/**
+ * Interpolation mode dispatcher for CurveEditor. The vocabulary of
+ * supported algorithms and the unified `sample(...)` entry point that
+ * picks the right one. All algorithms produce
+ * `(n-1) * samplesPerSegment + 1` points and pass through every
+ * anchor — CurveEditor is strictly interpolating, never approximating.
+ */
+
+/** Supported interpolation modes. All are interpolating (pass through
+ *  every anchor); the differences are in tangent computation and
+ *  parameterization. */
+type InterpolationMode = 'linear' | 'catmull-rom' | 'catmull-rom-uniform' | 'catmull-rom-chordal' | 'monotone';
+
+/**
+ * Built-in function/curve layer for LayeredCurveEditor. Bundles the
+ * curve-render + anchor-render + drag/insert/delete gestures that were
+ * the entirety of the original `CurveEditor`. Multiple instances coexist
+ * by id; consumers can compose several to plot e.g. a primary function
+ * and a derived (read-only) curve on the same chart.
+ */
+
+interface ControlPoint {
+    x: number;
+    y: number;
+    /** When true, this control point can't be moved or deleted by the
+     *  user. Render as a smaller diamond with locked styling. */
+    locked?: boolean;
+}
+type CurveDomain = '1d' | '2d';
+type EndpointMode = 'free' | 'pinned-x' | 'pinned-both';
+type AddPointMode = 'click-curve' | 'click-empty' | 'never';
+interface AnchorRenderProps {
+    point: ControlPoint;
+    index: number;
+    cx: number;
+    cy: number;
+    isActive: boolean;
+    isLocked: boolean;
+    isPinnedEndpoint: boolean;
+    isEndpoint: boolean;
+}
+interface CurveSettings {
+}
+interface FillSettings {
+    side: 'below' | 'above';
+    color?: string;
+}
+
+interface CurveEditorProps {
+    value: readonly ControlPoint[];
+    onChange: (next: ControlPoint[]) => void;
+    onChangeCommit?: (next: ControlPoint[], prev: readonly ControlPoint[]) => void;
+    domain?: CurveDomain;
+    interpolation?: InterpolationMode;
+    endpoints?: EndpointMode;
+    xRange?: readonly [number, number];
+    yRange?: readonly [number, number];
+    width: number;
+    height: number;
+    grid?: GridSettings | false | null;
+    axes?: AxesSettings | false | null;
+    curve?: CurveSettings | false | null;
+    fill?: FillSettings | false | null;
+    hideNonInteractive?: boolean;
+    constrain?: 'none' | 'function';
+    history?: boolean;
+    minPoints?: number;
+    maxPoints?: number;
+    addPointMode?: AddPointMode;
+    renderAnchor?: (info: AnchorRenderProps) => ReactNode;
+    /** Extra SVG content rendered behind the curve and anchors. */
+    decorations?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+declare function CurveEditor(props: CurveEditorProps): react_jsx_runtime.JSX.Element;
+
+interface PointPlotterProps {
+    /** Plotted points; caller-owned. */
+    value: readonly ControlPoint[];
+    /** Fires every frame during drag with the live in-flight value. */
+    onChange: (next: ControlPoint[]) => void;
+    /** Fires once per discrete user action (drag-end, add, delete) with
+     *  the new value and the value at gesture start. Wire history here. */
+    onChangeCommit?: (next: ControlPoint[], prev: readonly ControlPoint[]) => void;
+    /** Model-space x range. Default [0, 1]. */
+    xRange?: readonly [number, number];
+    /** Model-space y range. Default [0, 1]. */
+    yRange?: readonly [number, number];
+    width: number;
+    height: number;
+    grid?: GridSettings | false | null;
+    axes?: AxesSettings | false | null;
+    /** Minimum allowed point count. User-initiated deletion is refused
+     *  while `value.length <= minPoints`. */
+    minPoints?: number;
+    /** Maximum allowed point count. User-initiated insertion is refused
+     *  while `value.length >= maxPoints`. */
+    maxPoints?: number;
+    /** How new points are added. Default `'click-empty'`. Set to `'never'`
+     *  to disable insertion entirely. */
+    addPointMode?: 'click-empty' | 'never';
+    /** Built-in undo/redo via keyboard when the component has focus.
+     *  Default `true`. See `CurveEditor.history` for details. */
+    history?: boolean;
+    /** Custom per-anchor renderer. See `CurveEditor.renderAnchor`. */
+    renderAnchor?: (info: AnchorRenderProps) => ReactNode;
+    /** Extra SVG content beneath the anchors. See `CurveEditor.decorations`. */
+    decorations?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * 2D point plotter — a CurveEditor with the curve hidden. Anchors,
+ * drag, shift+click delete, right-click delete, and click-empty insert
+ * are inherited from CurveEditor verbatim, so the two components share
+ * gesture semantics and stay in sync as CurveEditor evolves.
+ *
+ * Differences from CurveEditor: no curve `<path>` drawn, no fill, no
+ * endpoint pinning, no interpolation, default `addPointMode` is
+ * `'click-empty'` (CurveEditor defaults to `'click-curve'`, which
+ * doesn't make sense without a curve to hit-test against).
+ */
+declare function PointPlotter(props: PointPlotterProps): react_jsx_runtime.JSX.Element;
+
+type GradientTrackOpts = {
+    gradient: (t: number) => string;
+    samples?: number;
+    activeRange?: [number, number];
+    hatch?: {
+        angleDeg?: number;
+        stripe?: number;
+        gap?: number;
+        dim?: number;
+    };
+};
+declare function paintGradientTrack(opts: GradientTrackOpts): (ctx: TrackCtx) => ReactNode;
+
+type ChromaCurve = {
+    lRange: [number, number];
+    midL: number;
+    cBot: number;
+    cPeak: number;
+    cTop: number;
+};
+type ChromaCurvePoint = {
+    L: number;
+    C: number;
+};
+declare function oklchToHex(L: number, C: number, Hdeg: number): string;
+declare function chromaAt(L: number, curve: ChromaCurve): number;
+
+interface LayerListItem {
+    id: string;
+    label: ReactNode;
+    /** Locked rows cannot be dragged, cannot be crossed by drops, and
+     *  never combine with other rows in a multi-selection. */
+    locked?: boolean;
+    /** Optional color swatch rendered before the label. Any CSS color string. */
+    swatch?: string;
+}
+interface UseReorderDragListOptions {
+    items: LayerListItem[];
+    selectedIds: string[];
+    onReorder(ids: string[], targetIndex: number): void;
+    /** Pointer-move distance (px) before pending drag engages. Default 4. */
+    threshold?: number;
+}
+interface ReorderDragState {
+    draggedIds: string[] | null;
+    targetIndex: number | null;
+}
+interface ReorderDragHandlers {
+    rowProps(id: string, index: number): {
+        onPointerDown(e: PointerEvent$1): void;
+    };
+    containerProps: {
+        ref: RefCallback<HTMLElement>;
+        onPointerMove(e: PointerEvent$1): void;
+        onPointerUp(e: PointerEvent$1): void;
+        onPointerCancel(e: PointerEvent$1): void;
+    };
+    state: ReorderDragState;
+}
+declare function useReorderDragList(opts: UseReorderDragListOptions): ReorderDragHandlers;
+
+/**
+ * Display-formatter for numbers. Use this anywhere a number is shown to
+ * a user. The whole point: negative values get prefixed with the real
+ * MINUS SIGN (U+2212) instead of the ASCII HYPHEN-MINUS (U+002D) that
+ * `toLocaleString` and template literals produce by default.
+ *
+ * U+2212 is the same visual width as `+` and reads as a sign rather
+ * than a hyphen — columns of signed numbers align cleanly and the
+ * glyph doesn't get confused with a bullet or list dash.
+ */
+declare const MINUS_SIGN = "\u2212";
+declare function formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+
+export { ActionBar, ActionsBar, Badge, Button, Checkbox, ComboBox, ComboBoxItem, CurveEditor, DataGrid, Dialog, EDGE_PROFILES, Field, Input, KeyCap, KeySequence, MINUS_SIGN, NumberField, OptionsBar, Plot2D, PointPlotter, Powerline, Radio, RadioGroup, RangeSlider, Select, SelectItem, Sidebar, SidebarPanel, Slider, Switch, Tab, TabList, TabPanel, Tabs, ToggleBar, ToolButton, ToolGroup, ToolPalette, chromaAt, detectPlatform, dlog, fieldClasses, formatNumber, formatShortcut, formatShortcutParts, inferKeycapKind, isDebugEnabled, keyGlyph, keySpecFromKey, keySpecsFromMods, oklchToHex, paintGradientTrack, useReorderDragList };
+export type { ActionBarProps, ActionsBarItem, ActionsBarProps, ActionsBarSize, ActionsBarVariant, AddPointMode, AnchorRenderProps, AxesSettings, BadgeProps, BadgeShape, BadgeSize, BadgeTone, BadgeVariant, BoundsCtx, BuiltInEdgeName, ButtonProps, ButtonSize, ButtonVariant, CheckboxProps, ChromaCurve, ChromaCurvePoint, ComboBoxItemProps, ComboBoxOption, ComboBoxProps, ControlPoint, CurveDomain, CurveEditorProps, DataGridColumn, DataGridProps, DialogProps, EdgeCap, EdgeProfile, EndpointMode, FieldOrientation, FieldProps, FillSettings, GradientTrackOpts, GridSettings, InputProps, InterpolationMode, KeyCapProps, KeyCapVariant, KeySequenceProps, KeySpec$1 as KeySpec, KeycapKind, LayerListItem, LogicalMod, LogicalModSpec, NumberFieldProps, OptionsBarItem, OptionsBarProps, OptionsBarSize, OptionsBarVariant, Platform, Plot2DCoords, Plot2DHandle, Plot2DProps, PointPlotterProps, PowerlineProps, PowerlineSegment, RadioGroupProps, RadioProps, RangeSliderProps, ReorderDragHandlers, ReorderDragState, SelectItemProps, SelectOption, SelectProps, SidebarPanelProps, SidebarProps, SliderProps, SwitchProps, TabListProps, TabPanelProps, TabProps, TabsProps, Thumb, ThumbRenderCtx, ThumbShape, ToggleBarItem, ToggleBarProps, ToggleBarSize, ToggleBarVariant, ToolButtonProps, ToolGroupProps, ToolPaletteProps, TrackCtx, UseReorderDragListOptions };