@mkbabb/glass-ui 5.0.0 → 7.0.0

package/dist/composables/motion/{useSelectionIndicator.d.ts → morph/useSelectionIndicator.d.ts}

@@ -1,35 +1,28 @@
 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
+ * 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 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,
+ * 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`
+ * the 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
+ * 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.
+ * 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

package/dist/composables/motion/{useAnimatedNumber.d.ts → number/useAnimatedNumber.d.ts}

@@ -18,10 +18,7 @@ export interface UseAnimatedNumberOptions {
     /** Per-frame side-effect hook. Receives the smoothed current value. */
     onValue?: (value: number) => void;
 }
-/**
- * The `useAnimatedNumber` return shape (AW.W15 — named `Use<Name>Return`
- * convention). `AnimatedNumber` is the preserved alias so import sites stay put.
- */
+/** The `useAnimatedNumber` return shape. */
 export interface UseAnimatedNumberReturn {
     /** Reactive smoothed value. Bind in templates. */
     current: Readonly<Ref<number>>;
@@ -34,8 +31,6 @@ export interface UseAnimatedNumberReturn {
     /** Stop the smoother and target watcher. */
     dispose: () => void;
 }
-/** Preserved alias for {@link UseAnimatedNumberReturn} (AW.W15). */
-export type AnimatedNumber = UseAnimatedNumberReturn;
 /**
  * Track a live numeric target with exponentially damped hysteresis.
  *

package/dist/composables/motion/{useCountup.d.ts → number/useCountup.d.ts}

@@ -1,8 +1,5 @@
 import { type Ref } from "vue";
-/**
- * The `useCountup` return shape (AW.W15 — named `Use<Name>Return` convention).
- * `Countup` is the preserved alias so existing import sites do not break.
- */
+/** The `useCountup` return shape. */
 export interface UseCountupReturn {
     /** Animate the count-ups inside the currently-active slide/region. */
     runActive: () => void;
@@ -11,8 +8,6 @@ export interface UseCountupReturn {
     /** Cancel every in-flight tween (also runs on scope-dispose). */
     cancel: () => void;
 }
-/** Preserved alias for {@link UseCountupReturn} — keeps import sites stable (AW.W15). */
-export type Countup = UseCountupReturn;
 export interface UseCountupOptions {
     /**
      * Easing applied to tween progress — a value.js-FREE callable

package/dist/composables/motion/{useNumericTransition.d.ts → number/useNumericTransition.d.ts}

@@ -2,7 +2,7 @@ import type { TimingFunction } from "@mkbabb/keyframes.js";
 import { type Ref } from "vue";
 export type SpringSnapshot<K extends string> = Record<K, number>;
 /**
- * The `useNumericTransition` return shape (AW.W15 — named `Use<Name>Return`).
+ * The named `useNumericTransition` return shape.
  * The transition is driver-only: `start`/`stop` control playback, `progress`
  * (0..1) + `playing` are reactive read-outs.
  */
@@ -22,10 +22,12 @@ 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`.
      *
-     * AW.W27: this is a CALLABLE `TimingFunction`, NOT a string easing name.
+     * This is a callable `TimingFunction`, not a string easing name.
      * keyframes 4 removed string-name acceptance from `NumericAnimationOptions`
      * (a name now resolves only through the ASYNC `resolveEasing`, which crosses
      * the value.js dynamic boundary the dock/motion light surface must never

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

@@ -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/{bloomUpField.d.ts → reveal/bloomUpField.d.ts}

@@ -1,5 +1,5 @@
 import type { Ref } from "vue";
-/** The BE.W-AMBIENT-TINT bound (sub-perceptual; never a flood — the warm-cream identity holds). */
+/** The ambient-strength ceiling (sub-perceptual; never a flood). */
 export declare const AMBIENT_STRENGTH_CEILING = 8;
 /** The live reduced-motion probe (matchMedia, SSR-safe). */
 export declare function prefersReducedMotion(): boolean;

package/dist/composables/motion/reveal/useBloomUp.d.ts

@@ -0,0 +1,33 @@
+import { type Ref } from "vue";
+import { type SpringPresetName } from "../spring/springPresets";
+export type BloomUpPreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+export interface UseBloomUpOptions {
+    /** The spring register (default `snappy`). */
+    preset?: BloomUpPreset;
+    /** Starting destination blur in pixels. Default `4`. */
+    blur?: number;
+    /** Explicit field hue; otherwise read from the source's `--glass-ambient-hue`. */
+    fieldHue?: string;
+    /** Destination field; otherwise use the nearest `[data-glass-field]` ancestor. */
+    field?: Ref<HTMLElement | null>;
+    /** Ambient strength percentage, clamped to `0..8`. Default `8`. */
+    fieldStrength?: number;
+    /** Snap spatial motion under reduced motion. Default `true`. */
+    respectReducedMotion?: boolean;
+    /** Seat a newly mounted destination before paint. Default `true`. */
+    autoPrime?: boolean;
+    /** Fired once when the bloom reaches its terminal state. */
+    onBloomed?: () => void;
+}
+export interface UseBloomUpReturn {
+    bloom: () => void;
+    reset: () => void;
+    prime: () => void;
+    blooming: Readonly<Ref<boolean>>;
+}
+/**
+ * Bloom a destination from a source rect while warming its surrounding field.
+ * Geometry and paint share `useElementMorph`'s one spring clock; this wrapper has no
+ * scheduler or `ElementMorph` instance of its own.
+ */
+export declare function useBloomUp(source: Ref<HTMLElement | null>, dest: Ref<HTMLElement | null>, options?: UseBloomUpOptions): UseBloomUpReturn;

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

@@ -1,5 +1,5 @@
 import { type ComponentPublicInstance, type Ref } from "vue";
-import { type ElementMorphPreset } from "./useElementMorph";
+import { type ElementMorphPreset } from "../morph/useElementMorph";
 /** The reveal spring register — `snappy` (the quick app-open default) or `bouncy` (the
  *  emphatic large-dialog bloom). */
 export type LiquidRevealPreset = ElementMorphPreset;
@@ -8,8 +8,8 @@ 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`). */
@@ -28,8 +28,8 @@ 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

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

@@ -0,0 +1,28 @@
+interface StaggerRevealConfig {
+    /** Delay between each target becoming `revealed`. Default 60ms. */
+    staggerMs?: number;
+    /** When true (default), a target stays revealed after first entering the viewport. */
+    once?: boolean;
+    /** IntersectionObserver rootMargin. Default `0px`. */
+    rootMargin?: string;
+    /** IntersectionObserver threshold. Default 0.15. */
+    threshold?: number;
+}
+/**
+ * Sequence entrance animations for a list/grid. Each registered target
+ * gets a staggered `revealed` flag once it crosses the viewport threshold.
+ * Consumers bind the flag to a Tailwind class (e.g. `opacity-100 translate-y-0`)
+ * and let CSS transitions handle the visual entry.
+ *
+ * On an engine with native `view()` timelines, no `IntersectionObserver`
+ * is constructed — prefer the `[data-scroll-reveal]` CSS recipe
+ * (scroll-driven.css). This composable is the feature-detected fallback (the
+ * sole writer when the native feature is absent); under native, `register()`
+ * reveals immediately so the terminal state is correct and the CSS animates.
+ */
+export declare function useStaggerReveal(options?: StaggerRevealConfig): {
+    targets: import("vue").Ref<HTMLElement[], HTMLElement[]>;
+    register: (el: HTMLElement | null, index?: number) => void;
+    revealed: Record<number, boolean>;
+};
+export {};

package/dist/composables/motion/{useTextHighlight.d.ts → reveal/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).
  *

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,28 @@ interface ScrollProgressConfig {
      * bottom, 1 when target top reaches viewport top.
      */
     trackExit?: boolean;
+    /**
+     * Keep the returned ref live even when CSS scroll timelines are available.
+     * Use this only when JavaScript consumes the value directly (for example a
+     * shader uniform); CSS-authored progress should keep the default compositor
+     * path and attach no reader.
+     */
+    reactive?: 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 +
+ * 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.
+ * mount for a correct initial value. `reactive: true` is the explicit exception
+ * for a non-CSS consumer such as a shader uniform.
  */
 export declare function useScrollProgress(options: ScrollProgressConfig): Ref<number>;
 export {};

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

@@ -1,8 +1,8 @@
 /** A glass-ui named-spring preset name. */
-export type SpringPresetName = "smooth" | "snappy" | "bouncy" | "gentle" | "dock" | "press" | "transient" | "eyeglass";
+export type SpringPresetName = "smooth" | "snappy" | "bouncy" | "gentle" | "dock" | "press" | "transient";
 /** One named-spring row: the analytic (response, dampingFraction) pair + its register doc. */
 export interface SpringPresetRow {
-    /** The token suffix — `--spring-<name>` (CSS) and the `MOTION_CURVES` key. */
+    /** 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;
@@ -27,9 +27,8 @@ export interface SpringPresetRow {
  *   DOCK    → dock    — the dock expand/collapse morph AND everything inside it.
  *   PRESS   → press   — the iOS interactive tap-press: a sub-200ms answer, a tiny alive
  *                       rebound.
- *   TRANSIENT → transient — the center-seed materialize bloom (Toast + Notification):
+ *   TRANSIENT → transient — the center-seed materialize bloom (Toast):
  *                       a deep scale-from with a near-critically-damped settle (no flick).
- *   EYEGLASS → eyeglass — the iOS tab-pill loupe travel: snappy speed with dock-class give.
  *
  * The whole table sits at the iOS weighty-inertial pole: longer `response` (weight) +
  * through-body damping toward critically-damped-with-a-touch-of-overshoot, while keeping
@@ -37,9 +36,11 @@ export interface SpringPresetRow {
  *   · every overshoot ∈ [0%,10%] — the "touch of overshoot" band (>10% reads too springy).
  *   · every non-gentle settle is at least as long as the calm baseline (the inertia floor);
  *     nothing gets faster (faster = the mechanical-snap defect).
- *   · t90 ∈ [50%,61%] of clock for smooth/snappy/press (the audacious-arrival floor).
- *   · gentle ζ stays EXACTLY 1.0 (the --ease-convergence alias depends on overshoot==0).
+ *   · t90 (the 90%-arrival fraction of the response clock) is NOT a single tight band —
+ *     it varies materially by preset (snappy arrives earlier than smooth/press). The
+ *     inertia is carried by the `response`/ζ pair below, not by a t90 fence.
+ *   · gentle ζ stays exactly 1.0: a calm arrival must not overshoot.
  */
 export declare const SPRING_PRESETS: readonly SpringPresetRow[];
-/** Lookup one preset row by name (used by `MOTION_CURVES` spring rows). */
+/** Lookup one Glass semantic spring preset by name. */
 export declare function springPreset(name: SpringPresetName): SpringPresetRow;

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

@@ -0,0 +1,19 @@
+import { type TimingFunction } from "@mkbabb/keyframes.js";
+import type { SpringPresetRow } from "./springPresets";
+type SpringParameters = Pick<SpringPresetRow, "response" | "dampingFraction">;
+/** 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. */
+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;
+export {};

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

@@ -11,11 +11,12 @@ export interface UseLiquidFlexParams {
     axis: LiquidFlexAxis;
     /**
      * The LOW squish cap — the maximum `--stretch` the travel can reach (a +N%
-     * elongation along the travel axis). Defaults to 1.08 (the iOS-segmented register
-     * the tabs-indicator already speaks — `DEFAULT_INDICATOR_MAX_STRETCH`). Kept LOW:
-     * the liquid register is a lively settle, never a rubber-band taffy-pull. May be a
-     * getter so a consumer reading a live cascade override (`--tab-indicator-max-
-     * stretch`) re-resolves the cap per-read without reconstructing the primitive.
+     * elongation along the travel axis). Defaults to 1.14. Kept LOW: the liquid
+     * register is a lively settle, never a rubber-band taffy-pull. The tabs indicator
+     * passes its own tighter cap explicitly (`DEFAULT_INDICATOR_MAX_STRETCH`, 1.11).
+     * May be a getter so a consumer reading a live cascade override
+     * (`--tab-indicator-max-stretch`) re-resolves the cap per-read without
+     * reconstructing the primitive.
      */
     maxStretch?: number | (() => number);
     /**
@@ -54,14 +55,12 @@ export interface UseLiquidFlexReturn {
      * The size as a CSS length style object, keyed on `axis` (`{ width: "Npx" }` or
      * `{ height: "Npx" }`). Bind on the morphing element's style.
      *
-     * DOCTRINE (BB.W-MOTION-CANON, P5 — the SIZESTYLE-LATENT record): `sizeStyle`
-     * is the SETTLED-FOOTPRINT writer — a one-time reserve of the morph TARGET box
+     * `sizeStyle` is the settled-footprint writer: a one-time reserve of the morph target box
      * (the FLIP-measured `to` span), NEVER the per-frame animation channel. The
      * per-frame channel is `transform` (the `stretchStyle` `--stretch` reciprocal
      * scale, a compositor property). Binding `sizeStyle` to a CONTINUOUSLY-animated
-     * element animates `width`/`height` per frame OFF the compositor (the A'-3
-     * reflow-storm class proof:no-layout-animation forbids library-wide) — FORBIDDEN
-     * by the canon. Write the reserved footprint ONCE at the morph endpoint, then
+     * element animates `width`/`height` per frame off the compositor. Write the
+     * reserved footprint once at the morph endpoint, then
      * drive the visible motion through `stretchStyle`/`transform`. See
      * `docs/precepts/motion-canon.md` P5.
      */
@@ -72,7 +71,7 @@ export interface UseLiquidFlexReturn {
      */
     stretchStyle: ComputedRef<Record<string, string>>;
     /**
-     * BD.W-MOTION-WEIGHT — the SATURATING velocity term `tanh(|ṫ|·k) ∈ [0,1]` (the
+     * 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
@@ -109,6 +108,6 @@ export interface UseLiquidFlexReturn {
 /**
  * The shared amorphous flex+squish primitive. PURE projection of a caller-driven
  * normalized scalar onto a size span + a volume-preserving squish — no spring, no
- * rAF, no element. See the module header for the W-LIQUID reconcile rationale.
+ * rAF, no element. See the module header for the reconcile rationale.
  */
 export declare function useLiquidFlex(params: UseLiquidFlexParams): UseLiquidFlexReturn;

package/dist/composables/motion/{useLiquidPress.d.ts → spring/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,16 +15,16 @@ 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
-     * `"--press-t"`. Button passes `"--glass-btn-press-t"` (the W-BUTTON-GLASS drive
+     * `"--press-t"`. Button passes `"--glass-btn-press-t"` (the drive
      * 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
+     * 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`
@@ -40,7 +40,7 @@ export interface UseLiquidPressOptions extends UseSpringPressOptions {
      */
     engageThreshold?: number;
     /**
-     * BD.W-MOTION-WEIGHT — the pressed element (the host the consumer binds
+     * 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
@@ -51,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). */
@@ -59,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/{useSpring.d.ts → spring/useSpring.d.ts}

@@ -2,13 +2,16 @@ import { type MaybeRefOrGetter, type Ref } from "vue";
 export interface UseSpringOptions {
     /**
      * Angular period of oscillation in seconds. Roughly: how long the spring
-     * takes to swing through one cycle if undamped. Default 0.5 (iOS smooth).
+     * takes to swing through one cycle if undamped. Default 0.5 — this
+     * primitive's own bare default, NOT a named preset (the `smooth` preset is
+     * 0.58; pass `springPreset("smooth")` for that).
      */
     response?: number;
     /**
      * Damping ratio ζ. `1` is critically damped (fastest settle, no
      * overshoot); `< 1` rings (overshoots target); `> 1` is overdamped
-     * (sluggish, monotone). Default 0.86 (iOS smooth preset).
+     * (sluggish, monotone). Default 0.86 — this primitive's own bare default,
+     * NOT a named preset (the `smooth` preset's ζ is 0.8).
      */
     dampingFraction?: number;
     /** Starting position. Default 0. */

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

@@ -26,6 +26,13 @@ export interface UseSpringMountOptions {
 export interface SpringMountRef {
     /** Position 0 (mounted) → 1 (dismissed). Bind to `transform: translateY` or scale. */
     position: SpringRef["value"];
+    /**
+     * Mount-hold: true while the surface must stay rendered — logically open, OR
+     * exiting (the spring still riding toward the dismissed endpoint). Bind to
+     * `forceMount` so the spring, not a keyframe, owns unmount timing. Clears once
+     * the dismiss-spring settles while `open` is false.
+     */
+    present: Readonly<Ref<boolean>>;
     /** True while pointer is actively dragging. */
     isDragging: Readonly<Ref<boolean>>;
     /**
@@ -47,6 +54,6 @@ export interface SpringMountRef {
  * The host watches `open` to seat the entrance (1 → 0). Pointer drags
  * re-seat the target mid-flight; on release the threshold decides bounce
  * vs. dismiss. The mid-flight re-target preserves spring continuity per
- * SpringProgress (G-W2-3 verified).
+ * SpringProgress.
  */
 export declare function useSpringMount(options: UseSpringMountOptions): SpringMountRef;

package/dist/composables/sidebar/types.d.ts

@@ -6,9 +6,9 @@ export interface TreeNode {
 }
 /**
  * The flat-hierarchy fields shared by every flattened tree row. Both the
- * sidebar's `TreeIndexEntry` and the virtual-windowing `FlatSection`
- * (`composables/virtual`) extend this — the four fields are declared ONCE,
- * not redeclared independently (BC.W-VIRTUAL-WINDOW type-reconcile).
+ * sidebar's `TreeIndexEntry` and the demo windower's `FlatSection`
+ * (`demo/composables/virtual`) extend this — the four fields are declared ONCE,
+ * not redeclared independently ( type-reconcile).
  */
 export interface SectionHierarchy {
     depth: number;