@mkbabb/glass-ui 4.2.0 → 6.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/useLiquidPress.d.ts

@@ -1,4 +1,4 @@
-import { type CSSProperties, type ComputedRef, type Ref } from "vue";
+import { type CSSProperties, type ComputedRef, type MaybeRefOrGetter, type Ref } from "vue";
 import { type UseSpringPressOptions } from "./useSpringPress";
 export interface UseLiquidPressOptions extends UseSpringPressOptions {
     /**
@@ -15,7 +15,7 @@ export interface UseLiquidPressOptions extends UseSpringPressOptions {
      * the travel axis). Default 1.04 (a button has no size span — the deform is a
      * lively settle, never a taffy-pull). Kept LOW by the liquid register.
      */
-    maxStretch?: number;
+    maxStretch?: MaybeRefOrGetter<number>;
     /**
      * The custom-property NAME the live press value (0..1) is written under, for the
      * surface CSS to read for the coupled brightness/specular leg. Default
@@ -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
@@ -42,6 +51,8 @@ export interface UseLiquidPressOptions extends UseSpringPressOptions {
      * lively settle, never a taffy-pull.
      */
     el?: Ref<HTMLElement | null>;
+    /** Disable every activation path. A held press is released when this becomes true. */
+    disabled?: MaybeRefOrGetter<boolean | undefined>;
 }
 export interface UseLiquidPressReturn {
     /** The live spring press value (0 released → 1 pressed, with the spring overshoot). */
@@ -50,12 +61,18 @@ export interface UseLiquidPressReturn {
     press: () => void;
     /** Release the press to 0 (call on `pointerup`/`cancel`/`leave`). */
     release: () => void;
-    /** Pointer handlers ready to spread onto an element (the `useSpringPress` ergonomics). */
+    /** True after hydration, when JS exclusively owns the scale channel. */
+    armed: Readonly<Ref<boolean>>;
+    /** Pointer and keyboard handlers for the complete press lifecycle. */
     handlers: {
-        onPointerdown: () => void;
+        onPointerdown: (event?: PointerEvent) => void;
         onPointerup: () => void;
         onPointercancel: () => void;
         onPointerleave: () => void;
+        onPointerenter: (event: PointerEvent) => void;
+        onKeydown: (event: KeyboardEvent) => void;
+        onKeyup: (event: KeyboardEvent) => void;
+        onBlur: () => void;
     };
     /**
      * The coupled press style — the ONE `:style` object a consumer binds. Carries the

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

@@ -22,6 +22,8 @@ export interface UseNumericTransitionOptions<K extends string> {
     to: SpringSnapshot<K>;
     /** Playback duration in ms. */
     duration: number;
+    /** Honor prefers-reduced-motion by snapping to the target. Default true. */
+    respectReducedMotion?: boolean;
     /**
      * keyframes.js timing function — an explicit callable `(t) => number`.
      *

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;

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/composables/motion/useTextHighlight.d.ts

@@ -24,7 +24,8 @@ export interface UseTextHighlightControls {
 /**
  * Drive a named CSS Custom Highlight reactively.
  *
- * @param name registry key — must match a `::highlight(<name>)` style rule.
+ * @param name registry key — must match a caller-owned
+ *   `::highlight(<name>)` style rule. This low-level API does not inject CSS.
  *   Instances sharing a name multiplex: each contributes its own ranges and
  *   the shared paint is their union (last to dispose drops the registry entry).
  *