@mkbabb/glass-ui 4.2.0 → 5.0.0

package/dist/composables/motion/useDockCtaReceive.d.ts

@@ -1,21 +1,15 @@
 import { type ComponentPublicInstance, type Ref } from "vue";
-import { type SpringPresetName } from "./springPresets";
-/** The receive spring register — `snappy` (the crisp absorb default) or `bouncy`
- *  (the emphatic land-with-overshoot). A subset of the named `SPRING_PRESETS` rows,
- *  matching `useLiquidReveal`'s register so the two seams read as ONE family. */
-export type DockCtaReceivePreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+import { type ElementMorphPreset } from "./useElementMorph";
+/** The receive spring register — `snappy` (the crisp absorb default) or `bouncy` (the
+ *  emphatic land-with-overshoot). Matches `useLiquidReveal`'s register so the two seams
+ *  read as ONE family. */
+export type DockCtaReceivePreset = ElementMorphPreset;
 export interface UseDockCtaReceiveOptions {
     /**
-     * The target dock control the CTA morphs INTO — the destination rect (the
-     * `<DockIconButton>`/dock control element). When null at receive time, the morph
-     * is a no-op snap (no destination to fly to) and `onReceived` fires immediately.
-     */
-    /**
-     * The dock control the CTA flies onto — a templateRef to the control ELEMENT or to
-     * a component (e.g. `<DockIconButton>`), whose root element is resolved via `.$el`.
-     * Resolving both keeps the seam forgiving: a `useTemplateRef<HTMLElement>` annotation
-     * on a component ref (whose value is the component public instance) no longer throws
-     * `setAttribute is not a function` at runtime — the stale element-vs-component class.
+     * The dock control the CTA flies onto — a templateRef to the control ELEMENT or to a
+     * component (e.g. `<DockControl>`), whose root element is resolved via `.$el`. When
+     * null at receive time, the morph is a no-op snap (nowhere to fly) and `onReceived`
+     * fires immediately.
      */
     dockControl: Ref<HTMLElement | ComponentPublicInstance | null>;
     /** The spring register (default `snappy`). */
@@ -32,35 +26,34 @@ export interface UseDockCtaReceiveOptions {
     onReceived?: () => void;
 }
 export interface UseDockCtaReceiveReturn {
-    /**
-     * Morph the CTA into the dock control. Idempotent per call — measures the CTA +
-     * dock-control rects fresh, drives the spring 0→1 (fly+reshape+fade+congest). A
-     * no-op if the CTA element is not yet mounted (no `onReceived`).
-     */
+    /** Morph the CTA into the dock control (drives the FORWARD play). A no-op if the CTA
+     *  element is not yet mounted (no `onReceived`). */
     receive: () => void;
-    /**
-     * Clear the morph transform (restore the CTA to its own rect, opacity 1) — the
-     * abort/reset seam. Cancels any in-flight morph; does NOT fire `onReceived`.
-     */
+    /** Clear the morph transform (restore the CTA to its own rect, opacity 1) — the
+     *  abort/reset seam. Does NOT fire `onReceived`. */
     reset: () => void;
-    /**
-     * ARM the landing SEAT (BC.W-AX-DOCK-CTA-SEAT). Writes `data-cta-pending` on the
-     * `dockControl` element so the seat partial (`src/styles/dock/cta-seat.css`) paints
-     * a dim ghost AND reserves the resting control footprint (a STATIC `min-inline-size`
-     * /`min-block-size` off `--dock-control-size`/`--dock-layer-height`) — the dock box
-     * is already at the seated width, so it does NOT jump when the CTA lands. Idempotent.
-     * A no-op when the `dockControl` is not yet mounted. Sets `pending.value = true`.
-     */
+    /** ARM the landing seat — write `data-cta-pending` on the dock control (the seat
+     *  reserves its resting footprint + shows a dim ghost). Idempotent. */
     setPending: () => void;
-    /**
-     * CLEAR the seat. Removes `data-cta-pending` from the `dockControl`, so the seat
-     * reveals its real content with the FLIP `transition: opacity` (the partial owns the
-     * paint — a calm content fade, NOT the dock morph-stagger). Idempotent. The default
-     * `onReceived` flow calls this on hand-off (the seat reveals as the CTA lands) unless
-     * the consumer drives it manually. Sets `pending.value = false`.
-     */
+    /** CLEAR the seat — remove `data-cta-pending`, so the seat reveals its real content
+     *  with the `transition: opacity` FLIP. Idempotent. */
     clearPending: () => void;
     /** The reactive seat state — the consumer binds `:class`/`v-if` off it. */
     pending: Readonly<Ref<boolean>>;
 }
+/**
+ * The external-CTA-into-dock-control morph. A ≤20-line adapter over `useElementMorph` —
+ * declares the receive as a `direction: "out"` FORWARD play flying ONTO the dock control,
+ * opacity + blur coupled, the runner's `onSettled` firing the seat clear + `onReceived`.
+ * The seat writes (`setPending`/`clearPending`) stay wrapper-local (data-attr, not motion).
+ *
+ * @example
+ * ```ts
+ * const { receive, setPending, pending } = useDockCtaReceive(ctaRef, {
+ *   dockControl: dockTargetRef, onReceived: () => (ctaConsumed.value = true),
+ * })
+ * setPending()          // arm the seat (dim ghost + footprint reserve)
+ * function onCta() { receive() }  // morph the CTA in; the default hand-off clearPending()s
+ * ```
+ */
 export declare function useDockCtaReceive(cta: Ref<HTMLElement | ComponentPublicInstance | null>, options: UseDockCtaReceiveOptions): UseDockCtaReceiveReturn;

package/dist/composables/motion/useElementMorph.d.ts

@@ -0,0 +1,99 @@
+import { type MorphRect } from "@mkbabb/keyframes.js";
+import { type ComponentPublicInstance, type Ref } from "vue";
+import { type SpringPresetName } from "./springPresets";
+/** A morph endpoint — a templateRef to an element/component, or the literal `"self"`
+ *  (the morphed surface's OWN settled rect). */
+export type MorphEndpoint = Ref<HTMLElement | ComponentPublicInstance | null> | "self";
+/** The morph register — `snappy` (the quick app-open default) or `bouncy` (the emphatic
+ *  large-surface bloom). A subset of the named `SPRING_PRESETS` rows shared by every
+ *  bloom leaf so the family reads as ONE spring register. */
+export type ElementMorphPreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+/** The declarative channel set the morph couples onto the spring clock. */
+export interface MorphChannels {
+    /** Fade the surface with the morph (opacity = 1 − morphProgress). Default `true`. */
+    opacity?: boolean;
+    /** The `filter: blur()` magnitude in px at the small `to` end (decongest/congest).
+     *  Default `0` (no blur channel). */
+    blur?: number;
+}
+export interface UseElementMorphOptions {
+    /** The `apply(el,0)` endpoint. Default `"self"` (the surface's own settled rect). */
+    from?: MorphEndpoint;
+    /** The `apply(el,1)` endpoint (the foreign trigger/source/dock-control). A null-
+     *  resolving ref degrades to a 92%-inset of the surface's own rect (the no-anchor
+     *  self-scale fallback — still spring-clocked, never a flat zoom). */
+    to?: MorphEndpoint;
+    /** `"in"` = FLIP inversion 1→0 (arrive at `from`); `"out"` = forward 0→1 (depart to
+     *  `to`). Default `"in"`. */
+    direction?: "in" | "out";
+    /** The coupled channels (opacity + blur). */
+    channels?: MorphChannels;
+    /** The spring register (default `snappy`). Sampled via `springPreset(name)`. */
+    preset?: ElementMorphPreset;
+    /** `transform-origin` resolution: anchor at `from`/`to` (relative to the surface),
+     *  `"center"`, or a raw CSS string. Default `"to"`. */
+    origin?: "from" | "to" | "center" | string;
+    /** Honor `prefers-reduced-motion: reduce` (snap to terminal, fade survives). Default `true`. */
+    respectReducedMotion?: boolean;
+    /** Fired ONCE at the terminal (animation settle AND the PRM/SSR snap) — the hand-off
+     *  seam (the cta seat clear + onReceived, the bloom field-land + onBloomed). */
+    onSettled?: () => void;
+    /** Fired each frame with the clamped [0,1] eased ARRIVAL progress — the extra-channel
+     *  hook (the bloom field-strength ramp). Not called on the PRM/SSR snap; `onSettled`
+     *  lands the terminal value there. */
+    onFrame?: (progress: number) => void;
+}
+export interface UseElementMorphReturn {
+    /** Measure `from`/`to` fresh + drive the morph. Interruptible — a mid-flight `play()`
+     *  re-measures + retargets (never restarts from the current computed value). */
+    play: () => void;
+    /** Cancel any in-flight morph + release the transition lock (does NOT clear styles
+     *  or fire `onSettled` — the abort seam). */
+    cancel: () => void;
+    /** Clear the inline morph styles (transform/origin/opacity/filter) — the reset seam. */
+    clear: (el?: HTMLElement | null) => void;
+    /** Statically seat the morph at a fixed [0,1] progress WITHOUT animating (the no-
+     *  mount-flash prime — transform only, no rAF, no lock). */
+    seat: (progress: number) => void;
+    /** `true` while a morph is in flight. */
+    playing: Readonly<Ref<boolean>>;
+    /** The live eased ARRIVAL progress (0 at play start → 1 at settle). */
+    progress: Readonly<Ref<number>>;
+}
+/**
+ * Resolve a templateRef value to its root HTMLElement — accepts an element directly OR a
+ * Vue component public instance (its `.$el`). Returns null for a fragment/text root or a
+ * nullish ref. THIS is the [[glass-ui binding verification]] cure: a `ref` bound to a
+ * COMPONENT resolves to the component public INSTANCE (no `getBoundingClientRect`/
+ * `setAttribute`), so the morph silently no-ops / throws. Every bloom leaf imports this
+ * ONE resolver (the α binding-verification fix) — a surface/trigger binds either an
+ * element ref or a component ref without dying.
+ */
+export declare function asElement(v: HTMLElement | ComponentPublicInstance | null | undefined): HTMLElement | null;
+/** The 92%-inset self-scale fallback (a null-resolving anchor blooms from a small inset
+ *  of the surface's own rect — never a flat zoom). */
+export declare function insetSelf(r: MorphRect): MorphRect;
+/**
+ * The driver-lock seam — set inline `transition-property: none` on `el` (beating the F5.2
+ * liquid-weight `transition` default + any Tailwind `transition*` utility) so the rAF
+ * transform writes are not fought; the returned release restores the prior value.
+ */
+export declare function lockSpatialTransition(el: HTMLElement): () => void;
+/** The live reduced-motion probe (matchMedia, SSR-safe) — exported so a wrapper that owns
+ *  a NON-animated terminal seat (the cta "snap gone + hand off") shares the ONE probe. */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * The ONE compositor FLIP/morph runner. Composes the kf `ElementMorph` +
+ * `springTimingFunction` into a single interruptible, PRM-safe, compositor-only morph the
+ * three bloom leaves collapse onto. See the module header for the two directions + the
+ * channel math + the PRM snap + the driver-lock seam.
+ *
+ * @example
+ * ```ts
+ * const engine = useElementMorph(surfaceRef, {
+ *   to: triggerRef, direction: "in", channels: { opacity: true, blur: 4 },
+ * })
+ * watch(open, (o) => (o ? engine.play() : engine.cancel()))
+ * ```
+ */
+export declare function useElementMorph(surface: Ref<HTMLElement | ComponentPublicInstance | null>, options?: UseElementMorphOptions): UseElementMorphReturn;

package/dist/composables/motion/useLeadTrail.d.ts

@@ -0,0 +1,69 @@
+import { type Ref } from "vue";
+export interface UseLeadTrailOptions {
+    /** The lead spring response (2π/response = the natural frequency). Default 0.68 (dock). */
+    response?: number;
+    /** The lead spring damping ratio ζ. Default 0.64 (dock; < 1 → the iOS overshoot). */
+    damping?: number;
+    /** The trailing follower time constant, seconds. Default 0.27 (≈270ms). */
+    trailTau?: number;
+    /** Honor `prefers-reduced-motion: reduce` → `drive` seats instantly. Default true. */
+    respectReducedMotion?: boolean;
+    /**
+     * The per-frame writer the consumer supplies (the DOM-write path, NO reactive
+     * thrash). Called each rAF tick with the live numeric edges — the consumer
+     * projects its silhouette (a barbell, an eyeglass) off `lo`/`hi`. Also called
+     * once on `seat` so a static mount paints correctly.
+     */
+    onFrame?: (edges: LeadTrailEdges) => void;
+}
+/** The two-edge state a single frame hands the consumer. */
+export interface LeadTrailEdges {
+    /** The lead edge (px) — springs toward the drive target. */
+    lead: number;
+    /** The trail edge (px) — lags then catches the lead. */
+    trail: number;
+    /** `min(lead, trail)` — the trailing silhouette edge (direction-agnostic). */
+    lo: number;
+    /** `max(lead, trail)` — the leading silhouette edge (direction-agnostic). */
+    hi: number;
+    /** True once the edges have re-formed on the target (the emergent release). */
+    settled: boolean;
+}
+export interface UseLeadTrail {
+    /** The live lead edge (updated per frame; the consumer usually reads `onFrame`). */
+    readonly lead: Readonly<Ref<number>>;
+    /** The live trail edge (updated per frame). */
+    readonly trail: Readonly<Ref<number>>;
+    /** True while the worm has re-formed on the target (the rAF is parked). */
+    readonly settled: Readonly<Ref<boolean>>;
+    /**
+     * Retarget the lead edge (px). The velocity carries — a retarget mid-flight
+     * re-seats the target, the spring continues from its LIVE `(position, velocity)`
+     * so interruption is free. Under PRM this SEATS instantly (zero in-between frames).
+     * The `drive(fractionalIndex→px)` seam W-CAROUSEL-REBUILD's drag-scrub feeds.
+     */
+    drive(target: number): void;
+    /** Snap BOTH edges to `value` instantly (mount / resize / PRM). Paints once. */
+    seat(value: number): void;
+    /** Tear down the rAF + the cached PRM listener (auto-run on scope dispose). */
+    dispose(): void;
+}
+/**
+ * The two-edge lead/trail integrator — a spring LEAD + a damped TRAIL follower in
+ * ONE rAF. The gap between the edges is the morph's live elongation; the trail
+ * catching the lead is the emergent release. keyframes-FREE + vueuse-FREE. See the
+ * module header for the pager-worm / eyeglass reconcile rationale.
+ *
+ * @example
+ * ```ts
+ * const worm = useLeadTrail({
+ *   onFrame({ lo, hi }) {
+ *     // project the barbell off the two edges (no getComputedStyle)
+ *     paintBarbell(lo, hi)
+ *   },
+ * })
+ * worm.seat(centerOf(active))   // mount
+ * worm.drive(centerOf(next))    // hop — the lead springs, the trail lags then reels in
+ * ```
+ */
+export declare function useLeadTrail(options?: UseLeadTrailOptions): UseLeadTrail;

package/dist/composables/motion/useLiquidPress.d.ts

@@ -23,6 +23,15 @@ export interface UseLiquidPressOptions extends UseSpringPressOptions {
      * the gleam already reads); the dock control passes `"--dock-press-t"`.
      */
     pressVar?: string;
+    /**
+     * BG.W-MOTION-SPINE — the press-tower collapse toggle. `true` (default) is the coupled
+     * squishy register: `useLiquidFlex`'s volume-preserving X/Y reciprocal deform rides the
+     * spring value (the Card `:pressable` register). `false` is the BARE mode — the press
+     * drive (`pressVar`) + a UNIFORM shrink `scale`, no reciprocal deform, no `--flex-vel`
+     * (the calmer no-overshoot register a dock control rides). ONE wrapper, two registers —
+     * so `useSpringPress`-alone is no longer a second public press face for one behaviour.
+     */
+    squish?: boolean;
     /**
      * Below this travel threshold the inline `scale` is OMITTED from `pressStyle` so the
      * surface's at-rest CVA/utility transforms (a hover `scale`) win unimpeded; the JS

package/dist/composables/motion/useLiquidReveal.d.ts

@@ -1,53 +1,39 @@
 import { type ComponentPublicInstance, type Ref } from "vue";
-import { type SpringPresetName } from "./springPresets";
-/** The reveal spring register — `snappy` (the quick app-open default) or `bouncy`
- *  (the emphatic large-dialog bloom). A subset of the named `SPRING_PRESETS` rows. */
-export type LiquidRevealPreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+import { type ElementMorphPreset } from "./useElementMorph";
+/** The reveal spring register — `snappy` (the quick app-open default) or `bouncy` (the
+ *  emphatic large-dialog bloom). */
+export type LiquidRevealPreset = ElementMorphPreset;
 export interface UseLiquidRevealOptions {
     /**
      * The trigger element the surface blooms FROM — the source rect (the button, the
      * collapsed dock pill). A templateRef to the trigger ELEMENT or to a COMPONENT (e.g.
-     * `<Button>`), whose root element is resolved via `.$el` — the binding-verification
-     * cure: a `ref` on a component is the public instance (no `getBoundingClientRect`),
-     * which silently no-oped the bloom. When null at reveal time, the bloom degrades to a
-     * center-anchored scale-from-self (the no-trigger fallback — still spring-clocked,
-     * never the flat bezier zoom).
+     * `<Button>`), whose root element is resolved via `.$el` (the binding-verification
+     * cure). When null at reveal time, the bloom degrades to a center-anchored self-scale
+     * (still spring-clocked, never the flat bezier zoom).
      */
     trigger?: Ref<HTMLElement | ComponentPublicInstance | null>;
     /** The spring register (default `snappy`). */
     preset?: LiquidRevealPreset;
-    /** The starting backdrop-blur radius in px (the decongest start). Default 4. */
+    /** The starting filter-blur radius in px (the decongest start). Default 4. */
     blur?: number;
     /** Honor `prefers-reduced-motion: reduce` (snap to settled, fade only). Default true. */
     respectReducedMotion?: boolean;
 }
 export interface UseLiquidRevealReturn {
-    /**
-     * Bloom the surface open from the trigger's rect. Idempotent per call — measures
-     * the trigger + settled rects fresh, drives the inversion spring 1→0. A no-op if
-     * the surface element is not yet mounted.
-     */
+    /** Bloom the surface open from the trigger's rect (drives the FLIP inversion). A no-op
+     *  if the surface element is not yet mounted. */
     reveal: () => void;
-    /**
-     * Snap the surface to its settled identity (clear the bloom transform/blur). The
-     * EXIT is the CSS recipe's `--ease-out` no-overshoot leg (a closing surface must
-     * not overshoot past gone) — this leaf clears the enter transform so the recipe's
-     * exit owns the close.
-     */
+    /** Clear the bloom transform/blur — the CSS recipe's `--ease-out` exit owns the close. */
     conceal: () => void;
 }
 /**
- * The iOS-27 source-rect bloom. Composes the dormant kf `ElementMorph` +
- * `springTimingFunction` into the three-channel liquid open (scale+fade+blur-settle
- * from the trigger's origin), compositor-only + PRM-snap. See the module header for
- * the REUSE + bloom-mechanism (FLIP inversion) + the channel split.
+ * The iOS-27 source-rect bloom. A ≤20-line adapter over `useElementMorph` — declares the
+ * reveal as a `direction: "in"` FLIP inversion blooming FROM the trigger, opacity + blur
+ * coupled. See `useElementMorph` for the runner (rAF/spring/PRM/compositor-only).
  *
  * @example
  * ```ts
- * const { reveal, conceal } = useLiquidReveal(surfaceRef, {
- *   trigger: triggerRef,
- *   preset: "bouncy",
- * })
+ * const { reveal, conceal } = useLiquidReveal(surfaceRef, { trigger: triggerRef, preset: "bouncy" })
  * watch(open, (o) => (o ? reveal() : conceal()))
  * ```
  */

package/dist/composables/motion/usePointerVelocityField.d.ts

@@ -34,6 +34,43 @@ export interface UsePointerVelocityFieldOptions {
      * Default true. (A deterministic viz capture that ACCEPTS live dynamics opts out.)
      */
     respectReducedMotion?: boolean;
+    /**
+     * The attractor MASS (dimensionless; default 1). Heavier = a slower, weightier
+     * follow (the effective response scales with `√mass`). The `blobPullMapping`
+     * passes ≈1.6 (the visible weight); a light chrome follow keeps 1.
+     */
+    mass?: number;
+    /**
+     * The attractor DAMPING ratio ζ (default 0.85). ζ < 1 lets the follow overshoot
+     * slightly then settle — the overshoot IS the perceived weight (ζ=1 critical reads
+     * weightless). The `blobPullMapping` passes 0.78–0.85.
+     */
+    damping?: number;
+    /**
+     * The base attractor RESPONSE (seconds; default 0.32 — the DOCK_SPRING register).
+     * The effective response is `attractorResponse · √mass`; ω = 2π / effectiveResponse
+     * (the SAME `ω = 2π/response` convention the existing hand-rolled integrators use,
+     * with `mass` as the physical scaler — no second ω-formula).
+     */
+    attractorResponse?: number;
+    /**
+     * The burst-LEAD gain (default 0.12). A fast flick leads the attractor target
+     * toward the heading by `burst · normalize(velocity) · leadGain` — the follow
+     * anticipates the pointer's direction on a quick move.
+     */
+    leadGain?: number;
+    /**
+     * The rest anchor the attractor relaxes to when the pointer lifts (engagement → 0).
+     * Default centre `{0.5, 0.5}`.
+     */
+    restAnchor?: PointerVec2;
+    /**
+     * The engagement-envelope HALF-LIFE (ms; default 120). `engagement` eases toward
+     * `active ? 1 : 0`; after `halfLifeMs` the remaining gap halves (k derived
+     * internally — feel as half-life, never a raw per-tick lerp). Lower = snappier
+     * engage/disengage; a subtle-interactive background passes a longer half-life.
+     */
+    halfLifeMs?: number;
 }
 export interface UsePointerVelocityField {
     /** True while the pointer is over the host (down between enter and leave). */
@@ -50,6 +87,21 @@ export interface UsePointerVelocityField {
     readonly acceleration: Readonly<Ref<PointerVec2>>;
     /** The transient flick-burst impulse (0..1, decays over ~1s). */
     readonly burst: Readonly<Ref<number>>;
+    /**
+     * The smoothed active-ENGAGEMENT envelope (0..1) — a half-life ease of `active`.
+     * The mappings scale their influence by it (strength = engagement·cfg.strength);
+     * the attractor target lerps `restAnchor → position` by it. ε-gated: a fully
+     * decayed envelope reads exactly 0 (the park contract).
+     */
+    readonly engagement: Readonly<Ref<number>>;
+    /**
+     * The mass-spring-damper ATTRACTOR position (0..1) — the ONE eased-follow the
+     * per-viz mappings read (the heavy weighty follow whose slight overshoot is the
+     * perceived mass). Relaxes to `restAnchor` when the pointer lifts.
+     */
+    readonly attractor: Readonly<Ref<PointerVec2>>;
+    /** The attractor's own VELOCITY (normalized-host units per second). */
+    readonly attractorVelocity: Readonly<Ref<PointerVec2>>;
     /**
      * The `@pointermove` handler — schedules NO frame; it only stashes the raw target
      * (PRM-gated). The renderer's `tick` does the smoothing/derivation on its OWN
@@ -66,6 +118,13 @@ export interface UsePointerVelocityField {
      * clip-space coords). PRM-gated like `onPointerMove`.
      */
     setPointer: (xNorm: number, yNorm: number) => void;
+    /**
+     * Set the engagement `active` flag directly — for a push-API consumer that owns its
+     * own hit-test / active gate (the blob SDF hit-test, the aurora stage) rather than
+     * the bound `onPointerEnter`/`onPointerLeave`. Drives the smoothed `engagement`
+     * envelope. Idempotent.
+     */
+    setActive: (active: boolean) => void;
     /**
      * Advance the physics ONE renderer frame. The viz calls this from INSIDE its
      * existing frame callback with the frame `delta` (ms). NO own rAF — the renderer

package/dist/composables/motion/useRoutePointer.d.ts

@@ -0,0 +1,41 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+import type { PointerVec2 } from "./usePointerVelocityField";
+export type { PointerVec2 };
+export interface RoutePointerContext {
+    /** The viewport-normalized pointer (0..1 across the viewport). */
+    readonly pointer: Readonly<Ref<PointerVec2>>;
+    /** True while a live pointer is over the viewport (and not PRM/paused-silenced). */
+    readonly active: Readonly<Ref<boolean>>;
+    /** Tear down the window listeners (auto-run on scope dispose). */
+    dispose(): void;
+}
+export interface UseRoutePointerOptions {
+    /**
+     * The route's paused signal (the WCAG-2.2.2 background pause). While truthy the
+     * broadcaster holds its last value + reports inactive (the backgrounds freeze).
+     */
+    paused?: MaybeRefOrGetter<boolean>;
+    /** Honor `prefers-reduced-motion: reduce` (default true). */
+    respectReducedMotion?: boolean;
+    /**
+     * Force a FRESH provider even if an ancestor already provided one (default false —
+     * the standard behaviour reuses an injected context so there is ONE window listener
+     * per route). A test harness that wants an isolated instance passes `true`.
+     */
+    fresh?: boolean;
+}
+/**
+ * The route pointer broadcaster (FC4). The FIRST caller on a route installs the ONE
+ * capture-phase window listener + provides the context; nested background vizzes reuse the
+ * injected context (no second listener). Returns the shared `{ pointer, active }` a
+ * background viz feeds into its own `usePointerVelocityField.setPointer`.
+ *
+ * @example
+ * ```ts
+ * const route = useRoutePointer({ paused })          // in the route chassis (provides)
+ * // in each background viz (injects the same instance):
+ * const route = useRoutePointer()
+ * watchEffect(() => field.setPointer(route.pointer.value.x, route.pointer.value.y))
+ * ```
+ */
+export declare function useRoutePointer(options?: UseRoutePointerOptions): RoutePointerContext;

package/dist/composables/motion/useSelectionGroup.d.ts

@@ -0,0 +1,83 @@
+import { type ComputedRef, type Ref } from "vue";
+import { type SelectionOption } from "./useSelectionIndicator";
+/**
+ * useSelectionGroup — the library's ONE headless selection engine
+ * (BI.W-DOCK-CONTROLS). The dock control run, `<SegmentedTabs>`, and
+ * `<ToggleGroup type="single">` are the SAME thing — a roving-focus selection
+ * strip with a traveling indicator. This composable assembles that ONE engine
+ * from the parts that already exist (PASS-1 §2.4), reka-FREE + engine-free so it
+ * ships on `/motion-core`:
+ *
+ *   • the SELECTION MODEL — `single` (a `string`) | `multiple` (a `string[]`),
+ *     driven off a caller-owned `model` ref (no shadow registry — the ONE
+ *     registry discipline);
+ *   • the ROVING MACHINE — `useTabRovingFocus` composed VERBATIM (exactly-one-
+ *     tabstop, axis-derived arrows, Home/End, wrap, disabled-skip);
+ *   • the ONE TRAVELING-INDICATOR WRITER — `useSelectionIndicator` (the
+ *     center-anchored ResizeObserver measure + the `--stretch` squish), so the
+ *     dock/tabs/toggle-group indicator is Safari-identical by construction;
+ *   • the RECENTER CALL — `el.scrollIntoView({inline:'nearest', block:'nearest'})`
+ *     on every select (the FACILITY is W-DOCK-OVERFLOW's; the CALL lives here in
+ *     the engine so a selection past the fold pulls itself into view).
+ *
+ * ROLE-PER-MODE rides the engine (the WAI-ARIA contract):
+ *   • `radiogroup` — a single-select CHOOSER: `role="radio"` + `aria-checked`;
+ *   • `tablist` — panel navigation: `role="tab"` + `aria-selected`;
+ *   • `group` — N independent toggles: `aria-pressed` (no item `role`).
+ */
+export type SelectionMode = "single" | "multiple";
+export type SelectionRole = "radiogroup" | "tablist" | "group";
+export interface UseSelectionGroupParams<O extends SelectionOption> {
+    /** The selectable options (index-aligned to `buttonRefs`). */
+    options: ComputedRef<O[]>;
+    /**
+     * The caller-owned selection model — the ONE registry (no shadow state). A
+     * `single`-mode group reads/writes a `string`; a `multiple`-mode group a
+     * `string[]`.
+     */
+    model: Ref<string | string[] | undefined>;
+    /** `single` (default) | `multiple`. */
+    mode?: ComputedRef<SelectionMode> | SelectionMode;
+    /**
+     * The ARIA role register — `radiogroup` (single chooser), `tablist` (panel
+     * navigation), or `group` (N toggles). Defaults to `radiogroup` for `single`
+     * and `group` for `multiple`.
+     */
+    role?: ComputedRef<SelectionRole> | SelectionRole;
+    /** True for the vertical (block-axis) orientation. */
+    vertical?: ComputedRef<boolean>;
+    /** The container scroller root (observed by the indicator's ResizeObserver). */
+    containerRef: Ref<HTMLElement | null>;
+    /**
+     * The traveling-indicator element (the `--stretch` squish target). Omit (or
+     * leave null) for a group with no glide indicator (e.g. a paper-hairline
+     * strip or a plain toggle row) — the squish/measure then no-ops.
+     */
+    indicatorRef?: Ref<HTMLElement | null>;
+    /** Per-option item refs, index-aligned to `options`. */
+    buttonRefs: Ref<HTMLElement[]>;
+}
+export interface UseSelectionGroupReturn {
+    /** The active option values (one for `single`, N for `multiple`). */
+    activeValues: ComputedRef<string[]>;
+    /** True when `value` is currently selected. */
+    isSelected: (value: string) => boolean;
+    /**
+     * Commit a selection at `idx` — writes the model (toggle in `multiple`),
+     * fires the travel-squish, and recenters the item via `scrollIntoView`.
+     */
+    select: (value: string, idx: number) => void;
+    /** The roving tabindex for option `idx` (`0` for the tabstop, `-1` else). */
+    rovingTabindex: (idx: number) => number;
+    /** The strip-root keydown handler (axis-derived arrows + Home/End). */
+    onKeydown: (e: KeyboardEvent) => void;
+    /** Inline style for the single-select traveling indicator (the ONE writer). */
+    singleSliderStyle: Ref<Record<string, string>>;
+    /** Imperatively kick the travel-squish on a selection at `idx`. */
+    squishOnTravel: (toIdx: number) => void;
+    /** The resolved group `role` (`radiogroup` | `tablist` | `group`). */
+    groupRole: ComputedRef<SelectionRole>;
+    /** The per-item ARIA attributes for `value`, role-per-mode. */
+    itemAttrs: (value: string) => Record<string, string>;
+}
+export declare function useSelectionGroup<O extends SelectionOption>(params: UseSelectionGroupParams<O>): UseSelectionGroupReturn;

package/dist/composables/motion/useSelectionIndicator.d.ts

@@ -0,0 +1,90 @@
+import { type Ref, type ComputedRef } from "vue";
+/**
+ * useSelectionIndicator — the library's ONE traveling-indicator writer
+ * (BI.W-DOCK-CONTROLS, promoted from the package-private `tabs/composables/
+ * useTabIndicator.ts`). The dock IS SegmentedTabs/ToggleGroup wearing chrome
+ * (PASS-1 §1 DOCK-D verdict), so the indicator that glides under the active
+ * selection is factored ONCE here on `/motion-core` and consumed by every
+ * selection surface (SegmentedTabs pill, the dock control run, the
+ * ToggleGroup single-select arm) — never re-forked.
+ *
+ * THE ONE WRITER, SAFARI-IDENTICAL BY CONSTRUCTION (the C2 fold). The prior
+ * dual path — a CSS `position-anchor` branch on supporting engines OR a JS
+ * measured slider on the rest — meant Chrome and Safari rendered the indicator
+ * through DIFFERENT code. This promotion RETIRES the CSS-anchor branch: the
+ * indicator ALWAYS measures via `ResizeObserver` + a center-anchored transform,
+ * so the same code paints the same pixels on every engine. There is exactly ONE
+ * indicator writer in the library.
+ *
+ * It owns the JS-measured single-select slider style (the slider geometry, the
+ * offset measure, the model/options re-measure watchers, the RO lifecycle) AND
+ * the AX.W53 travel-squish: a velocity-driven, volume-preserving `--stretch`
+ * scalar the active indicator reads so it STRETCHES along its travel axis as it
+ * glides and settles to fit (the Material-3 ELASTIC / Apple Liquid-Glass
+ * register, capped LOW). Honors `prefers-reduced-motion` (no squish under
+ * reduce). The underline material SLIDES (no squish — a hairline does not
+ * deform), gated by the caller passing no `indicatorRef` element.
+ *
+ * AXIS-DERIVED (the `vertical` param): the writer emits width/translateX on the
+ * inline axis (horizontal) OR height/translateY on the block axis (vertical),
+ * CENTER-ANCHORED (translate = buttonCenter − size/2) so the squish (which
+ * scales from `transform-origin: center`) keeps the indicator center pinned to
+ * the item center.
+ *
+ * Generic over the minimal `SelectionOption` shape (`value` + optional
+ * `disabled`), so it is decoupled from any consumer's option type — the
+ * `/motion-core` home carries no component-tree import.
+ */
+/** The minimal option shape the indicator measures against. */
+export interface SelectionOption {
+    value: string;
+    disabled?: boolean;
+}
+/**
+ * Fallback for `--tab-indicator-max-stretch` when the cascade leaves it unset —
+ * the default travel-squish cap. `--stretch = 1 + frac · (cap − 1)`, so a
+ * full-width jump reaches the cap and a tiny hop stays near 1. The token is the
+ * authority; this is the no-token floor (the SOLE cap source, shared by the
+ * click travel-squish AND the drag pull-morph — the constant + the token in
+ * lockstep, never a fork).
+ */
+export declare const DEFAULT_INDICATOR_MAX_STRETCH = 1.11;
+/**
+ * Fallback for `--tab-indicator-blob-max` when the cascade leaves it unset: the
+ * 5-beat blob's area-inflation overshoot peak. The 2nd `useLiquidFlex` channel
+ * drives `--tab-blob` toward this on the grow-overshoot beat, then de-inflates
+ * to 1 at arrival (shrink-to-fit). Kept LOW so the COMPOSED bbox area
+ * (`blob × stretch` ≈ blob², the squish being volume-preserving) clears the
+ * ≤ ~1.14 anti-taffy fence.
+ */
+export declare const DEFAULT_INDICATOR_BLOB_MAX = 1.045;
+/**
+ * The travel-progress fraction at which the squish RELEASES — the Material
+ * "grow then shrink" close, keyed to ARRIVAL. The squish opens with the glide
+ * and releases when the indicator is within this fraction of its target, so the
+ * stretch peaks DURING travel and shrinks to fit AT arrival, never before.
+ */
+export declare const INDICATOR_RELEASE_AT_ARRIVAL = 0.82;
+export interface UseSelectionIndicatorParams<O extends SelectionOption> {
+    /** The container scroller root (observed by the ResizeObserver). */
+    containerRef: Ref<HTMLElement | null>;
+    /** The active indicator element (the squish `--stretch` write target). */
+    indicatorRef: Ref<HTMLElement | null>;
+    /** Per-option item refs, index-aligned to `options`. */
+    buttonRefs: Ref<HTMLElement[]>;
+    /** The selectable options (re-measure on change). */
+    options: ComputedRef<O[]>;
+    /** The active value (re-measure on change). */
+    model: Ref<string | undefined>;
+    /** The active option values (used by the initial squish seed). */
+    activeValues: ComputedRef<string[]>;
+    /** True for the vertical (block-axis) orientation. */
+    vertical: ComputedRef<boolean>;
+}
+export interface UseSelectionIndicatorReturn {
+    /** Inline style for the single-select JS slider — the ONE writer. */
+    singleSliderStyle: Ref<Record<string, string>>;
+    /** Imperatively kick the travel-squish on a selection at `idx`. */
+    squishOnTravel: (toIdx: number) => void;
+}
+export declare function useSelectionIndicator<O extends SelectionOption>(params: UseSelectionIndicatorParams<O>): UseSelectionIndicatorReturn;