@mkbabb/glass-ui 4.1.0 → 5.0.0

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/useLiquidFlex.d.ts

@@ -71,6 +71,24 @@ export interface UseLiquidFlexReturn {
      * The SFC's CSS pairs `--stretch` reciprocally along the travel axis.
      */
     stretchStyle: ComputedRef<Record<string, string>>;
+    /**
+     * BD.W-MOTION-WEIGHT — the SATURATING velocity term `tanh(|ṫ|·k) ∈ [0,1]` (the
+     * SAME term the squish already computes), exposed so a consumer can fold it into
+     * the universal `--motion-weight` velocity boost (§2c). 0 at rest; rises toward 1
+     * on a fast travel; self-extinguishes as the travel stills. In `"linear"` law it
+     * is the travel FRACTION (clamped to [0,1]); in `"tanh"` law it is `tanh(travel·k)`.
+     * The PRIMITIVE STAYS ELEMENT-LESS — it merely projects the term; the consumer
+     * writes it onto the driving element via the `writeVelocityWeight` helper.
+     */
+    flexVel: ComputedRef<number>;
+    /**
+     * The velocity term as a CSS custom-property style object
+     * (`{ "--flex-vel": "0.42" }`). The consumer binds it on the driving element (the
+     * one extra style object — the term it ALREADY computes); the local
+     * `--motion-weight: calc(0.618 + 0.382 * var(--flex-vel))` boost rides it. The
+     * primitive stays element-less; this is a pure projection.
+     */
+    velStyle: ComputedRef<Record<string, string>>;
     /**
      * Advance the morph: set the normalized progress to `next` (0→1). The squish
      * travel velocity is the |Δt| since the prior `drive`, so calling `drive` on a

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
@@ -30,6 +39,18 @@ export interface UseLiquidPressOptions extends UseSpringPressOptions {
      * then yields back to the cascade as it settles). Default 0.001.
      */
     engageThreshold?: number;
+    /**
+     * BD.W-MOTION-WEIGHT — the pressed element (the host the consumer binds
+     * `pressStyle` on), so the press cap is derived SITE-LOCALLY off the live
+     * `--motion-weight` read at THAT element (the spike-corrected mechanism): the
+     * shipped `maxStretch` cap at rest weight 0.618 (byte-identical feel), 1.0 at
+     * weight 0 (the observer/PRM fence). When omitted, the cap is the static
+     * `maxStretch` (the no-element fallback — still correct at rest weight, the
+     * universal coupling is just not weight-scaled for that surface). The press is
+     * the GENTLE register — a button has no size span, so the weight-coupled cap is a
+     * lively settle, never a taffy-pull.
+     */
+    el?: Ref<HTMLElement | null>;
 }
 export interface UseLiquidPressReturn {
     /** The live spring press value (0 released → 1 pressed, with the spring overshoot). */

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

@@ -1,51 +1,40 @@
-import { 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 ComponentPublicInstance, type Ref } from "vue";
+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). 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).
+     * 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). 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 | null>;
+    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()))
  * ```
  */
-export declare function useLiquidReveal(surface: Ref<HTMLElement | null>, options?: UseLiquidRevealOptions): UseLiquidRevealReturn;
+export declare function useLiquidReveal(surface: Ref<HTMLElement | ComponentPublicInstance | null>, options?: UseLiquidRevealOptions): UseLiquidRevealReturn;

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/useScrollPin.d.ts

@@ -0,0 +1,49 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+import type { ComponentPublicInstance } from "vue";
+import type { ScrollSource } from "./scrollReader";
+export interface UseScrollPinOptions {
+    /**
+     * The tall `.scroll-pin` container (a templateRef to the element or a component). Its
+     * `getBoundingClientRect` gives the pin-slice ratio; `--pin-t` is written onto it (it
+     * `inherits: true` so the sticky stage + phase children read it).
+     */
+    container: MaybeRefOrGetter<HTMLElement | ComponentPublicInstance | null>;
+    /**
+     * The scroll source the pin tracks — the demo passes `main.demo-main-scroller`. Passed
+     * EXPLICITLY (the reader does not auto-discover). Default: the window/document.
+     */
+    source?: MaybeRefOrGetter<ScrollSource>;
+    /**
+     * The pin scrub ∈ [0, 1] — the pin drifts HEAVIER than a control (a scene, not a knob).
+     * Defaults to 1/φ² ≈ 0.382 (the golden heavier-drift rest). PRM → 0.
+     */
+    scrub?: number;
+    /** The spring damping ratio ζ for the felt reveal. < 1 overshoots. Default 0.85. */
+    dampingFraction?: number;
+    /** Honor `prefers-reduced-motion: reduce`. Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseScrollPinReturn {
+    /** The spring-damped 0..1 pin progress (reactive — mirrors `--pin-t`). */
+    pinT: Readonly<Ref<number>>;
+    /** Force a re-read (post-resize). */
+    recalculate: () => void;
+    /** Detach. */
+    dispose: () => void;
+}
+/**
+ * Drive `--pin-t` ∈ [0, 1] onto a sticky `.scroll-pin` stage off the real scroll port,
+ * spring-damped so the pinned reveal arrives with inertia, overshoots, then settles. The
+ * phase recipes (`.scroll-pin-phase-reveal` / `-settle`) read `--pin-t` — no
+ * `animation-timeline`, every engine.
+ *
+ * @example
+ * ```ts
+ * const pinContainer = ref<HTMLElement | null>(null)
+ * useScrollPin({
+ *   container: pinContainer,
+ *   source: () => document.querySelector<HTMLElement>("main.demo-main-scroller"),
+ * })
+ * ```
+ */
+export declare function useScrollPin(options: UseScrollPinOptions): UseScrollPinReturn;

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

@@ -0,0 +1,67 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+import { type ScrollReader, type ScrollSource } from "./scrollReader";
+/** The smoother register — a pure-lag low-pass (`SmoothProgress`) or an overshooting
+ *  spring (`SpringProgress`). The FELT reveal wants the spring (it overshoots, then
+ *  settles — the cartoon slam); the pure-lag legs (a progress number) want the smooth. */
+export type ScrollSceneRegister = "smooth" | "spring";
+export interface UseScrollSceneOptions {
+    /**
+     * The scroll source — an element with its own scroll port (the demo passes
+     * `main.demo-main-scroller`), the Window, or null. Resolved by `createScrollReader`:
+     * an HTMLElement listens on itself, else the document/window. Passed EXPLICITLY (the
+     * reader does NOT auto-discover a scroller).
+     */
+    source: MaybeRefOrGetter<ScrollSource>;
+    /**
+     * Map a fresh reader read to the raw 0..1 target this scene tracks. Default: the
+     * reader's own `position()/extent()` extent-relative progress. A pin passes a custom
+     * mapper keyed off a per-tick `getBoundingClientRect` (the pin-slice ratio).
+     */
+    map?: (reader: ScrollReader) => number;
+    /**
+     * The liquid-weight scrub ∈ [0, 1] — how much lag the scroll carries. 0 = a 1:1 snap
+     * (no weight); higher = heavier drift. Defaults to 1/φ ≈ 0.618 (the golden
+     * liquid-weight rest); a call site overrides per scene. PRM → 0. Mapped to the engine
+     * damping by `scrubToDamping` (a STATED function, no magic affine constants).
+     */
+    scrub?: number;
+    /** The smoother register (default `smooth` — the pure-lag low-pass). */
+    register?: ScrollSceneRegister;
+    /**
+     * For the `spring` register: the damping ratio ζ. < 1 overshoots (the felt slam),
+     * 0.85 ≈ the `--spring-gentle` identity. Default 0.85. Ignored for `smooth`.
+     */
+    dampingFraction?: number;
+    /** The element the damped value is written onto as a custom property (when bound). */
+    bindEl?: MaybeRefOrGetter<HTMLElement | null>;
+    /** The custom property name to write the damped 0..1 onto (e.g. `--pin-t`). */
+    property?: string;
+    /** Honor `prefers-reduced-motion: reduce` (scrub → 0, snap 1:1). Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseScrollSceneReturn {
+    /** The spring-damped 0..1 progress (reactive). The single writer of every felt axis. */
+    progress: Readonly<Ref<number>>;
+    /** Force a coalesced re-read + re-target now (post-resize / layout shift). */
+    recalculate: () => void;
+    /** Detach the reader + stop the smoother. */
+    dispose: () => void;
+}
+/**
+ * The liquid-weight scroll spine. Composes the ONE `createScrollReader` + a keyframes.js
+ * smoother (`SmoothProgress` / `SpringProgress`); on each coalesced scroll tick it sets the
+ * smoother target to the mapped raw progress; the smoother converges with inertia and keeps
+ * moving after scroll stops (the liquid weight). Writes the damped 0..1 to `progress` + the
+ * optional `property` on `bindEl`.
+ *
+ * @example
+ * ```ts
+ * const { progress } = useScrollScene({
+ *   source: () => document.querySelector<HTMLElement>("main.demo-main-scroller"),
+ *   scrub: 0.618,
+ *   bindEl: stageRef,
+ *   property: "--scroll-t",
+ * })
+ * ```
+ */
+export declare function useScrollScene(options: UseScrollSceneOptions): UseScrollSceneReturn;

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;

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

@@ -1,14 +1,14 @@
 import { type UseSpringOptions, type SpringRef } from "./useSpring";
 export interface UseSpringPressOptions extends UseSpringOptions {
     /**
-     * Spring `response`. Default `0.15s` — the `press` SPRING_PRESETS row (the
-     * Apple `interactiveSpring`): the sub-100ms iOS tap-press window, faster than
-     * the generic `useSpring` 0.5s so the feedback lands under the 100ms threshold.
+     * Spring `response`. Default `0.2s` — the `press` SPRING_PRESETS row (the iOS
+     * interactive tap): the sub-200ms iOS tap-press window, faster than the generic
+     * `useSpring` 0.5s so the feedback lands with a hair of inertial carry.
      */
     response?: number;
     /**
-     * Spring `dampingFraction`. Default `0.86` — the `press` row's ζ: a tiny
-     * sub-perceptual rebound (springy/alive) that does NOT ring.
+     * Spring `dampingFraction`. Default `0.8` — the `press` row's ζ: a tiny
+     * sub-perceptual rebound (+1.5%, springy/alive) that does NOT ring.
      */
     dampingFraction?: number;
 }

package/dist/configurator.d.ts

@@ -1 +1 @@
-export * from "./components/custom/configurator";
+export * from "./components/configurator";

package/dist/configurator.js

@@ -1,3 +1,3 @@
-import { a as e, i as t, n, r, t as i } from "./ConfiguratorRow-CaP7U3ZA.js";
-import { n as a, t as o } from "./useConfiguratorState-4xblKfwd.js";
-export { r as CONFIGURATOR_DENSITY_KEY, a as Configurator, n as ConfiguratorLayer, i as ConfiguratorRow, t as provideConfiguratorDensity, o as useConfiguratorState, e as useOptionalConfiguratorDensity };
+import { a as e, i as t, n, r, t as i } from "./ConfiguratorRow-BV6zPjTM.js";
+import { n as a, t as o } from "./useConfiguratorState-Dq35N_7t.js";
+export { r as CONFIGURATOR_SIZE_KEY, a as Configurator, n as ConfiguratorLayer, i as ConfiguratorRow, t as provideConfiguratorSize, o as useConfiguratorState, e as useOptionalConfiguratorSize };