@mkbabb/glass-ui 6.0.0 → 8.0.0

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

@@ -0,0 +1,123 @@
+import { type ComputedRef, type Ref } from "vue";
+import { type SelectionDeform, type SelectionOption } from "./useSelectionIndicator.js";
+import type { SelectionValue } from "../../../components/_shared/selection.js";
+import { type TabActivation } from "../../../components/tabs/composables/useTabRovingFocus.js";
+/**
+ * useSelectionGroup is the library's single headless selection engine. The dock
+ * control run and `<SegmentedTabs>` are the SAME thing — a roving-focus selection
+ * strip with a traveling indicator — and both compose it (BK #19 W-SELECTION-ONE
+ * made SegmentedTabs the second; the arm at `tests/gates/overfit-structure.test.ts`
+ * forbids a third assembly). `<ToggleGroup>` is the THIRD consumer, adopted at
+ * **BK #84 W-TOGGLE-ROW**: reka retired from that component entirely and it now
+ * feeds this engine from an item registry, taking the role-per-mode ARIA, the
+ * roving machine and the recenter while DECLINING the indicator — `indicatorRef`
+ * omitted, which is the "plain toggle row" the param below already named as a
+ * first-class caller. The C-1 `SelectionOption["value"]` widening landed with it
+ * (`string` → `SelectionValue`), so the engine's consumer set is THREE, and this
+ * doc says three. The assembly, reka-free and engine-free so it ships on
+ * `/motion-core`:
+ *
+ *   • the SELECTION MODEL — `single` (one scalar) | `multiple` (an array of them),
+ *     at the OPTION TYPE's own value (`O["value"]`), 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 and tabs indicator is Safari-identical by construction;
+ *   • the RECENTER CALL — `el.scrollIntoView({inline:'nearest', block:'nearest'})`
+ *     on every select, 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 one option value; a `multiple`-mode group an
+     * array of them. Keyed to `O["value"]` rather than fixed at `string` (BK #84
+     * C-1), so a caller whose options carry `SelectionValue` keeps its own scalar
+     * end to end and a caller whose options carry `string` sees exactly what it saw
+     * before — the widening is by DERIVATION, so it breaks nothing.
+     */
+    model: Ref<O["value"] | O["value"][] | 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>;
+    /** Whether roving focus selects immediately. Defaults to automatic. */
+    activation?: ComputedRef<TabActivation> | TabActivation;
+    /** The container scroller root (observed by the indicator's ResizeObserver). */
+    containerRef: Ref<HTMLElement | null>;
+    /**
+     * The traveling-indicator element (the deform write target). Omit (or leave
+     * null) for a group with no glide indicator at all (a paper-hairline strip, a
+     * plain toggle row) — the SQUISH then no-ops, which is HEAD's accurate half and
+     * is restored here. ~~The MEASURE does not no-op, and BK #84's rewording asserted
+     * that it did: `useSelectionIndicator` attaches its `ResizeObserver`
+     * unconditionally — that is the Safari-identical guarantee — and
+     * `updateSingleSlider` keeps writing a `singleSliderStyle` such a caller never
+     * reads. Economizing it is the indicator writer's own change to make.~~
+     * [2026-08-08 · BK #71 W-EYEGLASS, RT-84O: the change was made, in the file this
+     * text routed it to. `updateSingleSlider` now returns before its first rect read
+     * when `indicatorRef` is null, so such a caller runs ZERO layout. What #84 wrote
+     * was true of #84's HEAD and is false of this one — the `ResizeObserver` still
+     * attaches unconditionally (that guarantee is untouched), and a strip that
+     * appears late is measured on arrival because the indicator is a CHILD of the
+     * container, so the container watcher already covers it.]
+     */
+    indicatorRef?: Ref<HTMLElement | null>;
+    /**
+     * What the travelling body is made of — `"plate"` (default, the full body and
+     * the eyeglass host), `"mark"` (a hairline: length only), `"none"`. STATED, not
+     * inferred: a multi-toggle group has no single travelling body, and that is a
+     * different fact from a hairline having no area, even though the old null-ref
+     * sentinel spelled both the same way.
+     */
+    deform?: ComputedRef<SelectionDeform>;
+    /** Per-option item refs, index-aligned to `options`. */
+    buttonRefs: Ref<HTMLElement[]>;
+    /**
+     * A per-commit side effect the CALLER owns, fired on every committed selection
+     * (pointer AND keyboard) before the model write — e.g. SegmentedTabs' press
+     * squish on the pressed button. The engine stays the one selection path; a
+     * caller that needs a local flourish hangs it here rather than forking `select`.
+     */
+    onSelect?: (value: O["value"], idx: number) => void;
+}
+export interface UseSelectionGroupReturn<V extends SelectionValue = string> {
+    /** The active option values (one for `single`, N for `multiple`). */
+    activeValues: ComputedRef<V[]>;
+    /** True when `value` is currently selected. */
+    isSelected: (value: V) => boolean;
+    /**
+     * Commit a selection at `idx` — writes the model (toggle in `multiple`),
+     * fires the travel-squish, and recenters the item via `scrollIntoView`.
+     */
+    select: (value: V, 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: V) => Record<string, string>;
+}
+export declare function useSelectionGroup<O extends SelectionOption>(params: UseSelectionGroupParams<O>): UseSelectionGroupReturn<O["value"]>;

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

@@ -0,0 +1,113 @@
+import { type Ref, type ComputedRef } from "vue";
+import type { SelectionValue } from "../../../components/_shared/selection.js";
+/**
+ * useSelectionIndicator is the library's single traveling-indicator writer. The dock
+ * is SegmentedTabs/ToggleGroup wearing chrome, 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 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 travel deform: a velocity-driven `--stretch` scalar the active indicator
+ * reads so it lengthens along its travel axis as it glides and settles to fit
+ * (the Material-3 ELASTIC, Apple Liquid-Glass register). Honors
+ * `prefers-reduced-motion` (no deform under reduce).
+ *
+ * WHAT DEFORMS IS A POLICY, AND IT IS A PARAMETER. It used to be inferred from
+ * `indicatorRef` being null, which was an OVERLOADED sentinel: the same null meant
+ * "this group has no single slider" to `useSelectionGroup` and "this material does
+ * not squish" here, so neither meaning could be stated without lying about the
+ * other. `deform` says it outright:
+ *   • `"plate"` (default) — the full body: `--stretch` plus, where the surface arms
+ *     the organ, the EYEGLASS span/swell/lean. A body of glass with area to move.
+ *   • `"mark"` — `--stretch` only. A hairline lengthens along its travel; it has no
+ *     area to inflate and no cross axis to swell.
+ *   • `"none"` — no deform at all (a multi-toggle group has no single travelling
+ *     body to deform).
+ * The `if (!el)` guard below stays what it always should have been: null-safety.
+ *
+ * THE EYEGLASS is armed by the SURFACE, in its own cascade, by declaring
+ * `--eyeglass-span-max`. Where it is armed the deform stops being a centre-pump and
+ * becomes the measured organ — it spans origin and destination, leans 2:1 into its
+ * travel, swells across, and clamps at the track's inner edge. Where it is not
+ * declared the fraction law is byte-identical to what shipped. See `eyeglass.ts`.
+ *
+ * The writer emits the selected item's full physical border box from the
+ * container's padding-box origin. Measuring both axes keeps the resting fill
+ * exact across orientation, fractional geometry, and writing direction; the
+ * `vertical` param only selects the transient squish axis.
+ *
+ * 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.~~
+ * [2026-08-08 · BK #84 C-1: it carries exactly one, `import type { SelectionValue }`,
+ * and the claim is restated at the level that is actually load-bearing — no
+ * component-tree RUNTIME import. A `type` import is erased at emit, so the
+ * `/motion-core` chunk's bytes are unchanged; what changed is that the scalar
+ * identity is now named once in the library instead of respelled here.]
+ */
+/**
+ * The minimal option shape the indicator measures against.
+ *
+ * `value` is the library's `SelectionValue` (BK #84 C-1). It used to be `string`,
+ * which is why `<ToggleGroup>` — whose public value has been `string | number`
+ * since it shipped — could not compose this engine without narrowing its own
+ * surface. Widening here rather than narrowing there is the direction C-1 ruled:
+ * the engine only ever compares the value with `===` and interpolates it into a
+ * reset key, so it never needed the narrower type in the first place.
+ */
+export interface SelectionOption {
+    value: SelectionValue;
+    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;
+/**
+ * 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;
+/**
+ * The deform POLICY — what the travelling body is made of, stated rather than
+ * inferred from a null ref. See the module docstring for why the sentinel had to go.
+ */
+export type SelectionDeform = "plate" | "mark" | "none";
+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), at the option type's own scalar. */
+    model: Ref<O["value"] | undefined>;
+    /** The active option values (used by the initial squish seed). */
+    activeValues: ComputedRef<O["value"][]>;
+    /** True for the vertical (block-axis) orientation. */
+    vertical: ComputedRef<boolean>;
+    /** What the travelling body is made of. Defaults to `"plate"`. */
+    deform?: ComputedRef<SelectionDeform>;
+}
+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/{useAnimatedNumberMap.d.ts → number/useAnimatedNumberMap.d.ts}

@@ -1,5 +1,5 @@
 import { type ComputedRef } from "vue";
-import { type UseAnimatedNumberOptions } from "./useAnimatedNumber";
+import { type UseAnimatedNumberOptions } from "./useAnimatedNumber.js";
 export interface UseAnimatedNumberMapOptions extends UseAnimatedNumberOptions {
 }
 /**

package/dist/composables/motion/{pointerFieldMappings.d.ts → pointer/pointerFieldMappings.d.ts}

@@ -1,4 +1,4 @@
-import type { PointerVec2 } from "./usePointerVelocityField";
+import type { PointerVec2 } from "./usePointerVelocityField.js";
 export type { PointerVec2 };
 /**
  * A plain-value read of the pointer field for ONE frame. The renderer snapshots the field
@@ -22,7 +22,7 @@ export interface PointerFieldSnapshot {
 }
 /** The default bias gain — the curve advances at most ±BIAS_GAIN faster/slower (≤0.15). */
 export declare const FOURIER_BIAS_GAIN = 0.15;
-/** The default centroid-lean fraction (the subtle lean; supersedes FOLLOW_REACH=0.7). */
+/** The default centroid-lean fraction (the subtle lean). */
 export declare const FOURIER_FOLLOW_LEAN = 0.15;
 export interface FourierLeanGeometry {
     /** The canvas backing aspect (w/h) — the model→clip fit inverse. */
@@ -85,13 +85,15 @@ export interface BlobPullResult {
  * deceleration magnitude (a fast flick that brakes grows a pseudopod, then it relaxes).
  */
 export declare function blobPullMapping(snap: PointerFieldSnapshot, options?: BlobPullOptions): BlobPullResult;
-/** The default aurora cursor influence radius (the prior cursorModel default). */
+/** The default aurora cursor influence radius. */
 export declare const AURORA_CURSOR_RADIUS = 0.25;
 export interface AuroraCursorOptions {
-    /** The active strength ceiling (cfg.strength; default 0.8 — the prior setCursor default). */
+    /** The active strength ceiling (cfg.strength; default 0.8). */
     strength?: number;
     /** The influence radius (0.05..0.5; default {@link AURORA_CURSOR_RADIUS}). */
     radius?: number;
+    /** How much the pointer-field burst lifts the projected strength (0..1). */
+    amplitude?: number;
 }
 export interface AuroraCursorResult {
     /** The cursor position (0..1, CSS-top-origin — the bridge flips Y). */
@@ -101,16 +103,11 @@ export interface AuroraCursorResult {
     strength: number;
     /** The influence radius. */
     radius: number;
-    /** The velocity for the velocity-reactive swirl (normalized/second). */
-    velX: number;
-    velY: number;
-    /** The transient flick-burst (0..1). */
-    burst: number;
 }
 /**
  * The aurora cursor mapping (PURE). The attractor is the cursor position, the engagement
- * envelope drives the strength (so the cursor-local luminance lean reads on the SMOOTH
- * medium), and the velocity + burst pass straight onto the `uCursor*` uniforms.
+ * envelope drives the steady strength and the named amplitude folds the transient burst
+ * into that same scalar. Both engines therefore receive the same cursor field.
  */
 export declare function auroraCursorMapping(snap: PointerFieldSnapshot, options?: AuroraCursorOptions): AuroraCursorResult;
 export interface ConstellationWellResult {

package/dist/composables/motion/{usePointerVelocityField.d.ts → pointer/usePointerVelocityField.d.ts}

@@ -134,7 +134,7 @@ export interface UsePointerVelocityField {
     tick: (deltaMs: number) => void;
     /** Snap the whole field to rest (position held, velocity/accel/burst zeroed). */
     reset: () => void;
-    /** Tear down the cached PRM listener (auto-run on scope dispose). */
+    /** Tear down the shared-preference watch (auto-run on scope dispose). */
     dispose: () => void;
 }
 /**

package/dist/composables/motion/{useRoutePointer.d.ts → pointer/useRoutePointer.d.ts}

@@ -1,5 +1,5 @@
 import { type MaybeRefOrGetter, type Ref } from "vue";
-import type { PointerVec2 } from "./usePointerVelocityField";
+import type { PointerVec2 } from "./usePointerVelocityField.js";
 export type { PointerVec2 };
 export interface RoutePointerContext {
     /** The viewport-normalized pointer (0..1 across the viewport). */

package/dist/composables/motion/{useLiquidReveal.d.ts → reveal/useLiquidReveal.d.ts}

@@ -1,18 +1,19 @@
 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;
+import { type ElementMorphPreset } from "../morph/useElementMorph.js";
+/** The reveal spring register — `bloom` (the room-sized growth, the default: a surface
+ *  expanding to fill a sheet or a screen IS this row's one job) or `panel` (the emphatic
+ *  fired deploy, the one row that rebounds). */
+export type LiquidRevealPreset = Extract<ElementMorphPreset, "bloom" | "panel">;
 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). When null at reveal time, the bloom degrades to a center-anchored self-scale
-     * (still spring-clocked, never the flat bezier zoom).
+     * cure). When null at reveal time, the explicit-endpoint episode completes
+     * immediately; no invented geometry substitutes for a missing trigger.
      */
     trigger?: Ref<HTMLElement | ComponentPublicInstance | null>;
-    /** The spring register (default `snappy`). */
+    /** The spring register (default `bloom`). */
     preset?: LiquidRevealPreset;
     /** The starting filter-blur radius in px (the decongest start). Default 4. */
     blur?: number;
@@ -28,12 +29,12 @@ export interface UseLiquidRevealReturn {
 }
 /**
  * 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).
+ * reveal as an explicit trigger→surface episode, with opacity + blur
+ * coupled. See `useElementMorph` for managed playback, PRM, and compositor writes.
  *
  * @example
  * ```ts
- * const { reveal, conceal } = useLiquidReveal(surfaceRef, { trigger: triggerRef, preset: "bouncy" })
+ * const { reveal, conceal } = useLiquidReveal(surfaceRef, { trigger: triggerRef, preset: "panel" })
  * watch(open, (o) => (o ? reveal() : conceal()))
  * ```
  */

package/dist/composables/motion/{useStagger.d.ts → reveal/useStagger.d.ts}

@@ -6,7 +6,7 @@ export interface UseStaggerOptions {
      * Delay between consecutive reveals.
      *
      * Default 80ms — mirrors the `--motion-stagger-default` token in
-     * `tokens.css` (AJ-W4-κ canon). Consumers driving per-row CSS
+     * `tokens.css` (AJ--κ canon). Consumers driving per-row CSS
      * `animation-delay` cascades on the same surface should also read
      * `--motion-stagger-default` so the JS-driven cascade (this composable)
      * and the CSS-driven cascade stay in lockstep.
@@ -24,8 +24,8 @@ export interface UseStaggerOptions {
      * When true, honour `prefers-reduced-motion: reduce` by flipping every
      * slot true synchronously instead of cascading the timeline. Mirrors
      * the canonical opt-in on `useAnimatedNumber` and the global
-     * `transitions.css` / `utilities.css` reduced-motion brackets. SSR
-     * environments (no `window.matchMedia`) treat the option as a no-op.
+     * `transitions.css` / `utilities.css` reduced-motion brackets. SSR treats the
+     * option as a no-op.
      * Default true.
      */
     respectReducedMotion?: boolean;

package/dist/composables/motion/route/routeGrammar.d.ts

@@ -0,0 +1,60 @@
+import type { SpringPresetName } from "../spring/springPresets.js";
+/** The four nav classes. One mechanism each; a navigation is exactly one of them. */
+export type RouteNavClass = "route" | "zoom" | "lateral" | "collapse";
+/**
+ * A row is what the mechanism and the CSS mirror both READ. Nothing that neither reads
+ * belongs here: whether a window travels is `nav !== "route"` at the one site that needs
+ * it (`useRouteTransition`), and which channels a class moves is the recipe body's own
+ * keyframe list in `styles/view-transition.css` — a second copy of either would be prose
+ * in a type position, drifting the moment one of them is retuned.
+ */
+export interface RouteNavRow {
+    readonly nav: RouteNavClass;
+    /** The spring row the FOREGROUND binds, or `null` where the class takes a bezier. */
+    readonly foreground: SpringPresetName | null;
+    /** The bezier a `null`-foreground class takes instead (§7 — an exit is never a spring). */
+    readonly ease: "--ease-in" | null;
+    /** The row the WORLD recedes/recovers on; `null` where no world moves. */
+    readonly world: SpringPresetName | null;
+    /** The class's foreground clock: `duration` on an entrance, `exit-duration` on an exit. */
+    readonly clock: "duration" | "exit-duration";
+    /** The world starts only after the foreground is gone — an exit's recovery order. */
+    readonly worldWaitsForForeground: boolean;
+    readonly comment: string;
+}
+/** The grammar. Order is the reading order of the record, not a precedence. */
+export declare const ROUTE_GRAMMAR: readonly RouteNavRow[];
+/**
+ * The measured constants of the codex row, carried in ONE table.
+ *
+ * Every one traces to `EXEMPLARS-CODEX.md` rows I4 (`:131`, the icon↔app morph) and I4b
+ * (`:132`, the windowing transition). They are measurements of a corpus, not derivations,
+ * so they cannot be re-derived from the spring table — which is exactly why they are
+ * fenced here rather than sprinkled. Three of the four are mirrored into
+ * `tokens/motion-registers.css` for the recipe to read, and those two sites are the whole
+ * census: `route-motion.test.ts` reads every stylesheet under `src/` and every module on
+ * the `composables/motion` surface, comments and string literals stripped, and reds on a
+ * third site or on a `--route-*` token declared in a second file.
+ */
+export declare const ROUTE_CONSTANTS: {
+    /** I4: "the tapped icon alone scales to 1.57× in 42ms, razor sharp, z-lifted". */
+    readonly inhaleScale: 1.57;
+    /** I4, the same beat's window. The label is already gone by the time it ends. */
+    readonly inhaleMs: 42;
+    /** I4b: "the lateral push runs parallax ~1:8". One ratio, both parallax cases. */
+    readonly parallax: number;
+    /** I4: "opacity held then CUT at the last tenth" — the hold ends at 90% of the exit. */
+    readonly opacityCutAt: 0.9;
+};
+/** Look one class up by name. */
+export declare function routeNav(nav: RouteNavClass): RouteNavRow;
+/** The curve the foreground rides: a spring row's curve, or the exit bezier. */
+export declare function foregroundCurveToken(row: RouteNavRow): string;
+/**
+ * The foreground's clock. An exit reverses `zoom`, so it reads THAT row's exit reader —
+ * BK #26's law that a register binds the exit reader of its own entering row, which is
+ * what stops a recede outlasting the arrival it undoes.
+ */
+export declare function foregroundClockToken(row: RouteNavRow): string;
+/** The world's clock, or `null` where no world moves. */
+export declare function worldClockToken(row: RouteNavRow): string | null;

package/dist/composables/motion/route/useRouteTransition.d.ts

@@ -0,0 +1,45 @@
+import type { RouteNavClass } from "./routeGrammar.js";
+/** The name the travelling window carries. One per document state, always. */
+export declare const ROUTE_WINDOW_NAME = "gl-route-window";
+/** The name the window's own label carries, so it can leave before the window does. */
+export declare const ROUTE_LABEL_NAME = "gl-route-label";
+/** The attribute a destination marks its window with, read after the mutation. */
+export declare const ROUTE_WINDOW_ATTR = "data-route-window";
+/** The attribute a source marks its label with, read before the mutation. */
+export declare const ROUTE_LABEL_ATTR = "data-route-label";
+/** The root property the `lateral` class reads its push direction from. */
+export declare const ROUTE_DIRECTION_PROP = "--route-direction";
+export interface RouteTransitionOptions {
+    /** Which grammar class this navigation is. */
+    nav: RouteNavClass;
+    /** The DOM mutation — typically an awaited router push plus a render tick. */
+    mutate: () => void | Promise<void>;
+    /**
+     * The tapped element. Named `gl-route-window` for the OLD state; its
+     * `[data-route-label]` descendant, if any, is named `gl-route-label`.
+     */
+    source?: HTMLElement | null;
+    /**
+     * Resolves the destination's window AFTER `mutate` settles, still inside the update
+     * callback — the last moment before the new state is snapshotted.
+     */
+    target?: () => HTMLElement | null;
+    /** `lateral` only: +1 forward, −1 back, 0 unknown (the push degrades to a fade). */
+    direction?: number;
+}
+/**
+ * Run a route mutation under the typed grammar.
+ *
+ * @returns `{ finished }` — await it to route focus, per the substrate's a11y MANDATORY.
+ *
+ * @example
+ *   await routeTransition({
+ *       nav: "zoom",
+ *       source: cardEl,
+ *       target: () => document.querySelector("[data-route-window]"),
+ *       mutate: async () => { await router.push(to); await nextTick(); },
+ *   }).finished;
+ */
+export declare function routeTransition(options: RouteTransitionOptions): {
+    finished: Promise<void>;
+};

package/dist/composables/motion/{useScrollChrome.d.ts → scroll/useScrollChrome.d.ts}

@@ -1,4 +1,4 @@
-import { type MaybeRefOrGetter, type Ref } from "vue";
+import { type ComponentPublicInstance, type MaybeRefOrGetter, type Ref } from "vue";
 export interface UseScrollChromeOptions {
     /** Opt-in: collapse on scroll. DEFAULT FALSE — persistent-by-default (the iOS-27 lesson). */
     collapseOnScroll?: boolean;
@@ -22,7 +22,7 @@ export interface UseScrollChromeOptions {
      * so the `.scroll-chrome` recipe reads it with no consumer `:style` plumbing. When
      * absent, the consumer reads the `collapseT` ref and applies it itself.
      */
-    chromeRef?: MaybeRefOrGetter<HTMLElement | null>;
+    chromeRef?: MaybeRefOrGetter<HTMLElement | ComponentPublicInstance | null>;
     /** Honor `prefers-reduced-motion: reduce` (drop the ramp to a discrete snap). Default true. */
     respectReducedMotion?: boolean;
     /**

package/dist/composables/motion/{useScrollProgress.d.ts → scroll/useScrollProgress.d.ts}

@@ -10,18 +10,21 @@ interface ScrollProgressConfig {
      * bottom, 1 when target top reaches viewport top.
      */
     trackExit?: boolean;
+    /** Attach the reader only while this source is truthy. */
+    enabled?: MaybeRef<boolean>;
 }
 /**
  * Map a target element's scroll position in the viewport to a reactive
  * `Ref<number>` in [0, 1]. Drives things like scroll-linked typography
  * axes, parallax depth, or progress indicators.
  *
- * AQ.W5: on an engine with native scroll-driven animations, the listener +
- * `ResizeObserver` machinery does NOT attach — prefer the `.scroll-progress`
- * CSS recipe (scroll-driven.css), which runs the same 0..1 axis on the
- * compositor. This composable is the feature-detected fallback (the sole writer
- * when the native feature is absent); `computeProgress()` still runs once on
- * mount for a correct initial value.
+ * THE READER ALWAYS ATTACHES. The prior form gated the whole machine behind a
+ * module-load `supportsScrollTimeline()` probe, so on a supporting engine the
+ * returned ref froze at its mount value while reading alive at every call site —
+ * a silent inert arm, not a fallback (its ONE consumer opted out of it with
+ * `reactive: true`, which is how the arm survived untested in both directions).
+ * A CSS-authored axis belongs in the `.scroll-progress` recipe and never calls
+ * this composable at all; a caller who wants the NUMBER gets the number.
  */
 export declare function useScrollProgress(options: ScrollProgressConfig): Ref<number>;
 export {};

package/dist/composables/motion/{useScrollScene.d.ts → scroll/useScrollScene.d.ts}

@@ -1,5 +1,5 @@
 import { type MaybeRefOrGetter, type Ref } from "vue";
-import { type ScrollReader, type ScrollSource } from "./scrollReader";
+import { type ScrollReader, type ScrollSource } from "./scrollReader.js";
 /** 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. */
@@ -28,13 +28,14 @@ export interface UseScrollSceneOptions {
     /** 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`.
+     * For the `spring` register: the damping ratio ζ. < 1 overshoots (the felt slam).
+     * Defaults to the `world` row's own damping — the substrate-travel register —
+     * read from the table rather than restated. 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`). */
+    /** The custom property name to write the damped 0..1 onto (e.g. `--scene-t`). */
     property?: string;
     /** Honor `prefers-reduced-motion: reduce` (scrub → 0, snap 1:1). Default true. */
     respectReducedMotion?: boolean;

package/dist/composables/motion/spring/springPresets.d.ts

@@ -0,0 +1,32 @@
+/** A glass-ui named-spring preset name. */
+export type SpringPresetName = "press" | "present" | "dock" | "panel" | "bloom" | "world";
+/** One named-spring row: the analytic (response, dampingFraction) pair + its register doc. */
+export interface SpringPresetRow {
+    /** The token suffix for the generated `--spring-<name>` CSS pair. */
+    readonly name: SpringPresetName;
+    /** Response time in seconds (the spring's `response` solver input). */
+    readonly response: number;
+    /** Damping fraction ζ (1 = critical; <1 overshoots). */
+    readonly dampingFraction: number;
+    /** LAW 0b — the settle band the emitted `linear()` and `-settle` clock normalize over. */
+    readonly settleBand: 0.02 | 0.005;
+    /** The register this curve serves (the doc-table derives from this one string). */
+    readonly comment: string;
+}
+/**
+ * The six rows. Every row owns exactly ONE job; no job is owned twice; no row
+ * ships without a rider. The names match the `--spring-*` CSS tokens AND the CSS
+ * consumers that read `var(--spring-press)` etc. directly, so a rename is a
+ * clean break across the library and its consumers, never an alias.
+ *
+ * Exactly one row rebounds and it is the fired deploy — the measured corpus
+ * ceiling is a clip edge, and a celebration's liveliness belongs to the LIGHT
+ * channel (engageEnvelopes), never to a geometry bounce.
+ *
+ * Every figure describing these rows is GENERATED — the register mirror in
+ * scheme-spring.css is emitted from this table by scripts/regen-spring-tokens.mjs.
+ * Nothing here states a settle, a peak, or a clock in prose.
+ */
+export declare const SPRING_PRESETS: readonly SpringPresetRow[];
+/** Lookup one Glass semantic spring preset by name. */
+export declare function springPreset(name: SpringPresetName): SpringPresetRow;

package/dist/composables/motion/{springProjection.d.ts → spring/springProjection.d.ts}

@@ -1,15 +1,17 @@
 import { type TimingFunction } from "@mkbabb/keyframes.js";
-import type { SpringPresetRow } from "./springPresets";
-type SpringParameters = Pick<SpringPresetRow, "response" | "dampingFraction">;
+import type { SpringPresetRow } from "./springPresets.js";
+type SpringParameters = Pick<SpringPresetRow, "response" | "dampingFraction"> & Partial<Pick<SpringPresetRow, "settleBand">>;
 /** Internal projection shared by token generation and the Springs lab. */
 export interface SpringProjection {
     readonly settleSeconds: number;
     readonly sampleCount: number;
     readonly stops: string;
     readonly timingFunction: TimingFunction;
+    /** The maximum of the timing function across the sampled horizon — the
+     *  overshoot the Springs lab must contain within available travel. */
+    readonly peak: number;
 }
-export declare const SPRING_TOKEN_SAMPLE_COUNT = 48;
-/** Numeric 2%-band settle, rounded to the token register's nearest 10 ms. */
+/** Numeric settle over the row's OWN band, rounded to the token register's nearest 10 ms. */
 export declare function springSettleDurationSeconds(parameters: SpringParameters): number;
 /** Project one spring through the exact horizon and density used by CSS tokens. */
 export declare function springProjection(parameters: SpringParameters): SpringProjection;