@mkbabb/glass-ui 4.0.0 → 4.1.0

package/dist/composables/glass/webgpu/webgpuDevice.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The recognizable WebGPU INIT-FAILURE signal (BC.W-WEBGPU-EVERYWHERE — the D8/D8'
+ * close). A no-adapter host (`requestAdapter()` returns null), a `requestDevice()`
+ * reject, or a device-lost-at-birth is NOT a contract violation — it is a recognized
+ * substrate decision the picker (`createGpuSubstrate`) catches to fall to the WebGL2
+ * net. `armAsync()` REJECTS with this typed signal (it does NOT `throw` an uncaught
+ * error to the page, and it does NOT fire the consumer's `onInitError` — that contract
+ * is reserved for a genuine POST-arm shader/OOM/validation violation). The picker's
+ * `try`/`catch` recognizes it; a consumer never sees a `no GPU adapter` PAGEERROR.
+ */
+export declare class WebGPUInitError extends Error {
+    readonly kind: "no-adapter" | "device-request" | "no-navigator-gpu" | "software-adapter" | "pipeline-validation";
+    constructor(kind: WebGPUInitError["kind"], message: string, cause?: unknown);
+}
+/**
+ * Detect a SOFTWARE / CPU WebGPU adapter (SwiftShader / llvmpipe / the Microsoft
+ * Basic Render Driver, or a UA-supplied `isFallbackAdapter` software fallback) — the
+ * WebGPU twin of `isSoftwareWebGLRenderer` (the `renderMode.ts` WebGL software-raster
+ * guard, BB.W-AURORA-SWRASTER).
+ *
+ * WHY this forces the WebGL2 net (the BC WebGPU re-home regression this closes): on a
+ * headless / GPU-blocklisted / CI host, `navigator.gpu` exists AND `requestAdapter()`
+ * SUCCEEDS — it returns a SOFTWARE adapter (SwiftShader). `requestDevice()` succeeds
+ * too, so the WebGPU init does NOT reject; `setup()` builds the render pipeline, but the
+ * software backend cannot validate/compile it (a metaball `RenderPipeline` is invalid
+ * under SwiftShader), so the per-frame `pass.setPipeline(...)` floods
+ * `[Invalid RenderPipeline] is invalid due to a previous error` — a never-ending console
+ * spew with no fallback (the loop keeps trying to draw the invalid pipeline). A
+ * software-rastered WebGPU surface is the same per-composite cost class the WebGL guard
+ * forbids. So a software adapter is treated as a recognized INIT FAILURE: the picker's
+ * `armAsync` try/catch falls to the WebGL2 net — exactly the silent W-AURORA-SWRASTER
+ * degrade, never the invalid-pipeline flood.
+ *
+ * The signal is the `isFallbackAdapter` spec flag (a UA sets it on a software fallback —
+ * the spec moved it from `GPUAdapter` to `GPUAdapterInfo`, so it is read off BOTH the
+ * adapter AND its `info` for cross-UA coverage) OR a software/SwiftShader/llvmpipe/
+ * basic-render string in `adapter.info` (vendor/architecture/description). On a real
+ * Metal/Vulkan/D3D adapter both are false/empty, so the WebGPU path is BYTE-UNTOUCHED
+ * (the cardinal ba-gestalt capture holds). The read is defensive (the fields are optional
+ * across UAs); a throwing read is morally "cannot prove software" → keep WebGPU.
+ */
+export declare function isSoftwareWebGPUAdapter(adapter: GPUAdapter): boolean;

package/dist/composables/motion/core/index.d.ts

@@ -10,3 +10,7 @@ export * from "../useViewTransition";
 export * from "../vReveal";
 export * from "../useTextHighlight";
 export * from "../useLiquidFlex";
+export * from "../usePointerVelocityField";
+export * from "../useCharStagger";
+export * from "../useScrollTrigger";
+export * from "../useScrollChrome";

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

@@ -2,6 +2,10 @@ export * from "./constants";
 export * from "./useSpring";
 export * from "./useSpringMount";
 export * from "./useSpringPress";
+export * from "./useLiquidPress";
+export * from "./useDragMorph";
+export * from "./useLiquidReveal";
+export * from "./useDockCtaReceive";
 export * from "./useNumericTransition";
 export * from "./useAnimatedNumber";
 export * from "./useAnimatedNumberMap";

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

@@ -0,0 +1,25 @@
+/** The scroll source: an element with its own scroll-port, the Window, or null. */
+export type ScrollSource = HTMLElement | Window | null;
+export interface ScrollReader {
+    /** The resolved scroll-listener TARGET (the element, or `document` for the window). */
+    readonly target: EventTarget | null;
+    /** The current scroll position on the source (px) — `scrollTop` / `scrollY`. */
+    position: () => number;
+    /** The scrollable extent on the source (px) — `scrollHeight - clientHeight` / doc. */
+    extent: () => number;
+    /** Force a coalesced tick now (post-resize/layout re-read). */
+    schedule: () => void;
+    /** Detach the listener + cancel any in-flight frame. */
+    stop: () => void;
+}
+/**
+ * Attach ONE rAF-coalesced scroll listener to the source and call `onTick(reader)`
+ * once per scroll burst (a single in-flight frame). The `onTick` callback reads the
+ * live `position()`/`extent()` off the returned reader. The listener is the SAME
+ * `{ passive: true }` scroll listener `useScrollTracker` and `useFadingScroll`
+ * already used — factored to ONE site.
+ *
+ * @param source the scroll source (element / Window / null)
+ * @param onTick called once per coalesced scroll frame with the live reader
+ */
+export declare function createScrollReader(source: ScrollSource, onTick: (reader: ScrollReader) => void): ScrollReader;

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

@@ -1,5 +1,5 @@
 /** A glass-ui named-spring preset name. */
-export type SpringPresetName = "smooth" | "snappy" | "bouncy" | "gentle" | "dock";
+export type SpringPresetName = "smooth" | "snappy" | "bouncy" | "gentle" | "dock" | "press";
 /** 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. */
@@ -27,6 +27,25 @@ export interface SpringPresetRow {
  *                       dialog/success entrances, the VT default. Largest overshoot.
  *   GENTLE  → gentle  — critically-damped slow settles (the patient end of the ladder).
  *   DOCK    → dock    — the dock expand/collapse morph AND everything inside it.
+ *   PRESS   → press   — the iOS interactive tap-press: sub-100ms answer, a tiny alive
+ *                       rebound. `useSpringPress` reads this row's (response, ζ).
+ *
+ * BC.W-SPRING-EASE — the retune that eases the two abrupt curves + mints the press
+ * register (USER-DEFECTS §B/§D, the "squishy/quick/coupled" mandate). The retune is
+ * SURGICAL — `smooth`/`dock`/`gentle` are byte-frozen KEEPS:
+ *   · snappy: response 0.35 / ζ 0.65 → 0.42 / 0.78. The old pair front-loaded — its
+ *     2%-band travel collapsed into the first ~16% of the clock then sat dead-flat.
+ *     The eased pair spreads the travel so the 90%-point lands mid-clock (the analytic
+ *     90%-travel fraction t₉₀/t_settle ≈ 0.57, in the [0.55,0.70] target band), keeping
+ *     it QUICK (0.34s clock) with a whisper of life (overshoot ~+2.0%, ≤ the +7% bar).
+ *   · bouncy: ζ 0.45 → 0.55. Overshoot drops +20.5% → +12.6%, into the Apple 12-18%
+ *     band (apple-ios27.md §5 "ease toward ζ0.55-0.60 if abrupt"; ζ=1−bounce ⇒ bounce
+ *     0.45, more playful than Apple's 0.30 but controlled). response stays 0.5. ζ 0.55
+ *     is the band floor — the +14% prose target maps here once the overshoot is solved
+ *     analytically (ζ 0.60 lands +9.5%, BELOW the band; the proof's S2 floor is ζ≥0.55).
+ *   · press: MINTED at response 0.15 / ζ 0.86 — the Apple `interactiveSpring`
+ *     (apple-ios27.md §2.2/§2.5). The press answers in the sub-100ms iOS window with a
+ *     sub-perceptual alive rebound (~+0.5%). `useSpringPress` defaults re-point onto it.
  */
 export declare const SPRING_PRESETS: readonly SpringPresetRow[];
 /** Lookup one preset row by name (used by `MOTION_CURVES` spring rows). */

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

@@ -0,0 +1,44 @@
+import type { MaybeRefOrGetter, Ref } from "vue";
+/** The per-step delay floor matches the shipped `.char-stagger` recipe — the
+ *  glyph spans are mounted via `requestAnimationFrame`-free DOM writes; the CSS
+ *  owns the timing. No magic timing lives here. */
+export interface UseCharStaggerOptions {
+    /**
+     * Split unit. `"char"` (default) splits per UTF-16 code-unit-safe scalar;
+     * `"word"` splits on whitespace and keeps each word as ONE `.char` unit;
+     * `"grapheme"` uses `Intl.Segmenter` so emoji / combining-mark / ZWJ
+     * sequences (a 👨‍👩‍👧 family) are ONE glyph, never split into pieces.
+     */
+    by?: "char" | "word" | "grapheme";
+    /**
+     * Preserve whitespace as non-animating spacer spans so the word spacing
+     * survives the `inline-block` split. Default `true`.
+     */
+    preserveWhitespace?: boolean;
+    /**
+     * Write `--char-total` (the glyph count) on the wrapper, for a length-
+     * proportional / center-out / reverse stagger. Default `true`.
+     */
+    writeTotal?: boolean;
+}
+export interface UseCharStaggerReturn {
+    /** Re-run the split (after a `textContent` change). Idempotent — it restores
+     *  the original text from the cached label and re-mints, so spans never
+     *  accrete across re-splits. */
+    split: () => void;
+    /** The resolved glyph (`.char` unit) count. */
+    count: Ref<number>;
+}
+/**
+ * Split a target element's text into per-glyph `.char` spans + the
+ * `--char-index`/`--char-total` customs the shipped `.char-stagger` CSS reads —
+ * accessible by construction (the wrapper keeps the full text as its
+ * `aria-label`, every glyph span is `aria-hidden`).
+ *
+ * @example
+ * const el = ref<HTMLElement | null>(null);
+ * const { count } = useCharStagger(el, { by: "grapheme" });
+ * // <span ref="el" class="char-stagger" aria-label="Fourier" style="--char-total:7">
+ * //   <span class="char" style="--char-index:0" aria-hidden>F</span> …
+ */
+export declare function useCharStagger(target: MaybeRefOrGetter<HTMLElement | null>, opts?: UseCharStaggerOptions): UseCharStaggerReturn;

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

@@ -0,0 +1,84 @@
+import { type Ref } from "vue";
+import { type SpringPresetName } from "./springPresets";
+/** The receive spring register — `snappy` (the crisp absorb default) or `bouncy`
+ *  (the emphatic land-with-overshoot). A subset of the named `SPRING_PRESETS` rows,
+ *  matching `useLiquidReveal`'s register so the two seams read as ONE family. */
+export type DockCtaReceivePreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+export interface UseDockCtaReceiveOptions {
+    /**
+     * The target dock control the CTA morphs INTO — the destination rect (the
+     * `<DockIconButton>`/dock control element). When null at receive time, the morph
+     * is a no-op snap (no destination to fly to) and `onReceived` fires immediately.
+     */
+    dockControl: Ref<HTMLElement | null>;
+    /** The spring register (default `snappy`). */
+    preset?: DockCtaReceivePreset;
+    /** The ending congest blur radius in px (the CTA dissolves into the glass). Default 4. */
+    blur?: number;
+    /** Honor `prefers-reduced-motion: reduce` (snap to gone, then hand off). Default true. */
+    respectReducedMotion?: boolean;
+    /**
+     * Fired ONCE when the CTA has landed on the dock control (the hand-off seam) — the
+     * consumer hides the CTA + activates the dock control here. Fires on the animation
+     * settle AND on the PRM/no-target snap (the gesture always completes).
+     */
+    onReceived?: () => void;
+}
+export interface UseDockCtaReceiveReturn {
+    /**
+     * Morph the CTA into the dock control. Idempotent per call — measures the CTA +
+     * dock-control rects fresh, drives the spring 0→1 (fly+reshape+fade+congest). A
+     * no-op if the CTA element is not yet mounted (no `onReceived`).
+     */
+    receive: () => void;
+    /**
+     * Clear the morph transform (restore the CTA to its own rect, opacity 1) — the
+     * abort/reset seam. Cancels any in-flight morph; does NOT fire `onReceived`.
+     */
+    reset: () => void;
+    /**
+     * ARM the landing SEAT (BC.W-AX-DOCK-CTA-SEAT). Writes `data-cta-pending` on the
+     * `dockControl` element so the seat partial (`src/styles/dock/cta-seat.css`) paints
+     * a dim ghost AND reserves the resting control footprint (a STATIC `min-inline-size`
+     * /`min-block-size` off `--dock-control-size`/`--dock-layer-height`) — the dock box
+     * is already at the seated width, so it does NOT jump when the CTA lands. Idempotent.
+     * A no-op when the `dockControl` is not yet mounted. Sets `pending.value = true`.
+     */
+    setPending: () => void;
+    /**
+     * CLEAR the seat. Removes `data-cta-pending` from the `dockControl`, so the seat
+     * reveals its real content with the FLIP `transition: opacity` (the partial owns the
+     * paint — a calm content fade, NOT the dock morph-stagger). Idempotent. The default
+     * `onReceived` flow calls this on hand-off (the seat reveals as the CTA lands) unless
+     * the consumer drives it manually. Sets `pending.value = false`.
+     */
+    clearPending: () => void;
+    /** The reactive seat state — the consumer binds `:class`/`v-if` off it. */
+    pending: Readonly<Ref<boolean>>;
+}
+/**
+ * The external-CTA-into-dock-control morph. Composes the SAME kf `ElementMorph` +
+ * `springTimingFunction` substrate `useLiquidReveal` activates, driven FORWARD (the
+ * reveal's inverse): the CTA flies + reshapes from its own rect onto the dock
+ * control's rect, fades + congests into the glass on the spring clock, then hands off.
+ * Compositor-only + PRM-seats. See the module header for the REUSE + the FORWARD-play
+ * mechanism + the channel split.
+ *
+ * @example
+ * ```ts
+ * const { receive, setPending, clearPending, pending, reset } = useDockCtaReceive(
+ *   ctaRef,
+ *   {
+ *     dockControl: dockTargetRef,
+ *     preset: "snappy",
+ *     onReceived: () => (ctaConsumed.value = true),
+ *   },
+ * )
+ * // ARM the seat (the dock control shows the dim ghost + reserves its footprint).
+ * setPending()
+ * // on the CTA click: morph it into the dock (the default hand-off clearPending()s,
+ * // revealing the seated content with the opacity FLIP — no box jump).
+ * function onCta() { receive() }
+ * ```
+ */
+export declare function useDockCtaReceive(cta: Ref<HTMLElement | null>, options: UseDockCtaReceiveOptions): UseDockCtaReceiveReturn;

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

@@ -0,0 +1,77 @@
+import { type ComputedRef, type Ref } from "vue";
+/** The morph axis — `"x"` tracks the inline (horizontal) travel, `"y"` the block. */
+export type DragMorphAxis = "x" | "y";
+/**
+ * One snap target on the drag axis. `value` is the consumer's domain value (the
+ * tab/layer id) committed via `onSnap`; `center` is the target's center coordinate
+ * in the SAME px space the drag tracks (the element's offset-axis center).
+ */
+export interface DragMorphSnapTarget<V = string> {
+    value: V;
+    center: number;
+}
+export interface UseDragMorphParams<V = string> {
+    /** The draggable element ref (the indicator/handle the gesture captures). */
+    el: Ref<HTMLElement | null>;
+    /** The morph axis (`"x"` horizontal · `"y"` vertical). May be a getter. */
+    axis: DragMorphAxis | (() => DragMorphAxis);
+    /**
+     * The ordered snap targets, resolved off the consumer's geometry (the
+     * center-anchored button/layer centers). May be a getter so a re-measure
+     * (a resize, an option change) re-resolves them without reconstruction.
+     */
+    snapTargets: readonly DragMorphSnapTarget<V>[] | (() => readonly DragMorphSnapTarget<V>[]);
+    /**
+     * The live cap getter for the squish (`--tab-indicator-max-stretch`, ≤1.08).
+     * Defaults to the shared 1.08 fence; a getter re-reads the cascade override.
+     */
+    maxStretch?: () => number;
+    /**
+     * Fired ONCE on settle at the nearest snap with the committed value. The
+     * consumer writes its `v-model` here — the single source of truth.
+     */
+    onSnap: (value: V) => void;
+    /** Honor `prefers-reduced-motion: reduce` (squish off, instant snap). Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseDragMorphReturn {
+    /** True while a pointer gesture is in progress (down, not yet settled). */
+    dragging: Readonly<Ref<boolean>>;
+    /** The live drag position on the morph axis (px), for diagnostics/tests. */
+    position: Readonly<Ref<number>>;
+    /** The live squish scalar (≥1, capped at the live cap). 1 at rest / under PRM. */
+    stretch: Readonly<Ref<number>>;
+    /** The `transform: translate` style the consumer binds on the morph element. */
+    dragStyle: ComputedRef<Record<string, string>>;
+    /**
+     * Re-resolve the snap centers + axis (kf reads `snap` at construction, so a
+     * geometry change — a resize, an option change, an orientation flip — calls
+     * this to rebuild the `Draggable` over the SAME reused spring). Idempotent;
+     * a no-op while a gesture is in flight (the rebuild waits for settle).
+     */
+    refresh: () => void;
+    /** Tear down — detach the `Draggable`, dispose the spring + watchers. */
+    detach: () => void;
+}
+/**
+ * The abstract pull/drag-to-morph-squish gesture. Composes kf `Draggable`
+ * (pointer-capture follow + velocity + snap-aware fling) + `SpringProgress` (the
+ * physics core) + `useLiquidFlex` (`"tanh"` velocity-squish) into ONE gesture with
+ * a consumer-wired single-commit `onSnap`. See the module header for the REUSE +
+ * compositor-only + PRM rationale.
+ *
+ * @example
+ * ```ts
+ * const { dragging, stretch, dragStyle, detach } = useDragMorph({
+ *   el: indicatorRef,
+ *   axis: () => (isVertical.value ? "y" : "x"),
+ *   snapTargets: () => buttonRefs.value.map((b, i) => ({
+ *     value: options.value[i].value,
+ *     center: b.offsetLeft + b.offsetWidth / 2,
+ *   })),
+ *   maxStretch: () => readCap(),
+ *   onSnap: (v) => { model.value = v },
+ * })
+ * ```
+ */
+export declare function useDragMorph<V = string>(params: UseDragMorphParams<V>): UseDragMorphReturn;

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

@@ -53,6 +53,17 @@ 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
+     * (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
+     * drive the visible motion through `stretchStyle`/`transform`. See
+     * `docs/precepts/motion-canon.md` P5.
      */
     sizeStyle: ComputedRef<Record<string, string>>;
     /**

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

@@ -0,0 +1,71 @@
+import { type CSSProperties, type ComputedRef, type Ref } from "vue";
+import { type UseSpringPressOptions } from "./useSpringPress";
+export interface UseLiquidPressOptions extends UseSpringPressOptions {
+    /**
+     * The uniform press SHRINK depth — the contraction the press scale reaches at
+     * `t=1` (the iOS uniform shrink the reciprocal squish deforms AROUND). The X axis
+     * reads `shrink·stretch`, the Y axis `shrink/stretch` (the volume preserved on the
+     * travel axis). Default 0.03 (the button `--scale-press-btn` 0.97 magnitude — the
+     * JS path AGREES with the CSS `.tap-squish active:scale` floor). A calmer surface
+     * (the dock control's no-overshoot tap register) passes a smaller depth.
+     */
+    shrinkDepth?: number;
+    /**
+     * The LOW reciprocal-squish cap handed to `useLiquidFlex` (the +N% elongation along
+     * 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;
+    /**
+     * 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
+     * the gleam already reads); the dock control passes `"--dock-press-t"`.
+     */
+    pressVar?: string;
+    /**
+     * 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
+     * reciprocal scale wins ONLY while the press is engaged (the single-source press,
+     * then yields back to the cascade as it settles). Default 0.001.
+     */
+    engageThreshold?: number;
+}
+export interface UseLiquidPressReturn {
+    /** The live spring press value (0 released → 1 pressed, with the spring overshoot). */
+    value: Readonly<Ref<number>>;
+    /** Drive the press to 1 (call on `pointerdown`). Interruptible — re-targets the live spring. */
+    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). */
+    handlers: {
+        onPointerdown: () => void;
+        onPointerup: () => void;
+        onPointercancel: () => void;
+        onPointerleave: () => void;
+    };
+    /**
+     * The coupled press style — the ONE `:style` object a consumer binds. Carries the
+     * reciprocal X/Y `scale` (engaged only past `engageThreshold`) AND the `pressVar`
+     * 0..1 drive scalar the surface CSS reads for the brightness/specular leg.
+     * Compositor-only (`scale` + a custom property — never a layout property).
+     */
+    pressStyle: ComputedRef<CSSProperties>;
+}
+/**
+ * The ONE interruptible, coupled spring-press. Composes `useSpringPress` (the spring
+ * driver, PRM-aware) + `useLiquidFlex` (the volume-preserving reciprocal squish) and
+ * exposes a single `pressStyle` object + the pointer `handlers`.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const press = useLiquidPress()
+ * </script>
+ * <template>
+ *   <button v-bind="press.handlers" :style="press.pressStyle" />
+ * </template>
+ * ```
+ */
+export declare function useLiquidPress(options?: UseLiquidPressOptions): UseLiquidPressReturn;

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

@@ -0,0 +1,51 @@
+import { type Ref } from "vue";
+import { type SpringPresetName } from "./springPresets";
+/** The reveal spring register — `snappy` (the quick app-open default) or `bouncy`
+ *  (the emphatic large-dialog bloom). A subset of the named `SPRING_PRESETS` rows. */
+export type LiquidRevealPreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+export interface UseLiquidRevealOptions {
+    /**
+     * The trigger element the surface blooms FROM — the source rect (the button, the
+     * collapsed dock pill). When null at reveal time, the bloom degrades to a
+     * center-anchored scale-from-self (the no-trigger fallback — still spring-clocked,
+     * never the flat bezier zoom).
+     */
+    trigger?: Ref<HTMLElement | null>;
+    /** The spring register (default `snappy`). */
+    preset?: LiquidRevealPreset;
+    /** The starting backdrop-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.
+     */
+    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.
+     */
+    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.
+ *
+ * @example
+ * ```ts
+ * const { reveal, conceal } = useLiquidReveal(surfaceRef, {
+ *   trigger: triggerRef,
+ *   preset: "bouncy",
+ * })
+ * watch(open, (o) => (o ? reveal() : conceal()))
+ * ```
+ */
+export declare function useLiquidReveal(surface: Ref<HTMLElement | null>, options?: UseLiquidRevealOptions): UseLiquidRevealReturn;

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

@@ -30,9 +30,9 @@ export interface UseNumericTransitionOptions<K extends string> {
      * (a name now resolves only through the ASYNC `resolveEasing`, which crosses
      * the value.js dynamic boundary the dock/motion light surface must never
      * pull in). Narrowing glass-ui's public option to a callable decouples it
-     * from keyframes' name-resolution churn AND is assignable to every supported
-     * keyframes major (2.2 / 3 / 4). A consumer wanting a named curve passes the
-     * function directly (e.g. `(t) => 1 - Math.pow(1 - t, 3)` for easeOutCubic).
+     * from keyframes' name-resolution churn. A consumer wanting a named curve
+     * passes the function directly (e.g. `(t) => 1 - Math.pow(1 - t, 3)` for
+     * easeOutCubic).
      */
     timingFunction?: TimingFunction;
     /** Per-frame consumer. Receives the same zero-allocation record each tick. */

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

@@ -0,0 +1,98 @@
+import { type Ref } from "vue";
+/** A 2-vector in normalized-host space (0..1 across the host box). */
+export interface PointerVec2 {
+    x: number;
+    y: number;
+}
+export interface UsePointerVelocityFieldOptions {
+    /**
+     * The smoothing rate for the eased POSITION (0..1 per second-equivalent; higher
+     * = snappier approach). Default 0.22 (the cursorModel `CURSOR_POS_LERP` snappy
+     * register). The viz reads `position`/`smoothedPosition`; the velocity is its
+     * derivative.
+     */
+    positionLerp?: number;
+    /**
+     * The smoothing rate for the derived VELOCITY (0..1; higher = velocity tracks the
+     * live delta faster, lower = a longer momentum tail). Default 0.3 (the cursorModel
+     * `CURSOR_VELOCITY_LERP`).
+     */
+    velocityLerp?: number;
+    /**
+     * The smoothing rate for the derived ACCELERATION (0..1). Default 0.3 — the accel
+     * term tracks the velocity-delta on the same register as the velocity itself.
+     */
+    accelerationLerp?: number;
+    /**
+     * The per-tick burst decay multiplier (the transient swirl-impulse a fast flick
+     * injects, decaying over ~1s). Default 0.96 (the cursorModel
+     * `CURSOR_BURST_DECAY_PER_FRAME`, ≈0.96^60≈0.09 after 1s at 60fps).
+     */
+    burstDecay?: number;
+    /**
+     * Honor `prefers-reduced-motion: reduce` → `tick(0)` freeze (no live velocity).
+     * Default true. (A deterministic viz capture that ACCEPTS live dynamics opts out.)
+     */
+    respectReducedMotion?: boolean;
+}
+export interface UsePointerVelocityField {
+    /** True while the pointer is over the host (down between enter and leave). */
+    readonly active: Readonly<Ref<boolean>>;
+    /** The RAW live pointer target in normalized-host space (0..1), pre-smoothing. */
+    readonly position: Readonly<Ref<PointerVec2>>;
+    /** The eased/smoothed pointer position the velocity derives from (0..1). */
+    readonly smoothedPosition: Readonly<Ref<PointerVec2>>;
+    /** The smoothed pointer VELOCITY (normalized-host units per second). */
+    readonly velocity: Readonly<Ref<PointerVec2>>;
+    /** The scalar velocity magnitude (`hypot(velocity)`), the common viz read. */
+    readonly speed: Readonly<Ref<number>>;
+    /** The smoothed pointer ACCELERATION (the second derivative — the accel term). */
+    readonly acceleration: Readonly<Ref<PointerVec2>>;
+    /** The transient flick-burst impulse (0..1, decays over ~1s). */
+    readonly burst: Readonly<Ref<number>>;
+    /**
+     * 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
+     * frame. Bind on the host (or call `setPointer` directly from a custom listener).
+     */
+    onPointerMove: (event: PointerEvent) => void;
+    /** Bind on the host `@pointerenter` (sets `active`). */
+    onPointerEnter: () => void;
+    /** Bind on the host `@pointerleave` (clears `active`; the field decays to rest). */
+    onPointerLeave: () => void;
+    /**
+     * Set the raw pointer target directly in normalized-host space (0..1) — for a
+     * viz that already owns its pointer→uv mapping (a WebGPU surface reading
+     * clip-space coords). PRM-gated like `onPointerMove`.
+     */
+    setPointer: (xNorm: number, yNorm: number) => 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
+     * owns the loop. Under PRM (or an explicit `tick(0)`) the field freezes to rest
+     * (no live velocity). Returns the live field (so a renderer can read inline).
+     */
+    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). */
+    dispose: () => void;
+}
+/**
+ * The shared viz-pointer-physics field — pointer POSITION + derived VELOCITY +
+ * derived ACCELERATION (the accel term), advanced by the renderer's frame `tick`
+ * (NO own rAF), frozen under PRM (`tick(0)`). The procedural-viz family reads the
+ * field for pointer dynamics; the position is event-driven, the derivatives are
+ * computed in `tick`.
+ *
+ * @example
+ * ```ts
+ * const field = usePointerVelocityField()
+ * // in the renderer's frame callback (the ONE loop the canvas lifecycle owns):
+ * function onFrame({ delta }) {
+ *   field.tick(delta)                       // advance the physics, no second rAF
+ *   uploadUniforms({ vel: field.velocity.value, accel: field.acceleration.value })
+ * }
+ * ```
+ */
+export declare function usePointerVelocityField(options?: UsePointerVelocityFieldOptions): UsePointerVelocityField;

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

@@ -0,0 +1,58 @@
+import { 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;
+    /** The flip-delta debounce (px) before a direction flip commits. Default 8 (the reader's). */
+    flipDeltaPx?: number;
+    /**
+     * Optional velocity gate (px/s): a flick over this collapses/expands IMMEDIATELY,
+     * a slow drag respects the threshold. Default off (undefined).
+     */
+    velocityGate?: number;
+    /** Snap-to-nearest commits past this fraction of the collapse range on scroll-STOP. Default 0.5. */
+    snapMidpoint?: number;
+    /**
+     * The scroll distance over which the chrome travels 0→1 collapsed (px). Default 116
+     * (the citymall headerHeight×2 reference) — the trigger-point span.
+     */
+    collapseRangePx?: number;
+    /**
+     * The chrome element (a dock, a header). When provided, the composable WRITES
+     * `--chrome-collapse-t` onto it directly (the JS leg of the dual-path single-writer)
+     * 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>;
+    /** Honor `prefers-reduced-motion: reduce` (drop the ramp to a discrete snap). Default true. */
+    respectReducedMotion?: boolean;
+    /**
+     * The scroll-STOP debounce window (ms) — the no-tick window after which the snap
+     * commits (the `onMomentumScrollEnd` analogue). Default 140 (a calm post-scroll beat).
+     */
+    scrollStopMs?: number;
+}
+export interface UseScrollChromeReturn {
+    /** 0..1 collapse fraction (drives the consumer's transform/opacity ramp). */
+    collapseT: Ref<number>;
+    /** True once collapseT past snapMidpoint (the discrete state). */
+    collapsed: Ref<boolean>;
+    /** Committed scroll direction (from the reader). */
+    direction: Ref<"down" | "up" | null>;
+    /** Force a re-read + re-evaluate (post-resize). */
+    recalculate: () => void;
+}
+/**
+ * The floating-chrome collapse-state machine. COMPOSES `useScrollTrigger` (the ONE
+ * scroll reader); ramps `collapseT` on direction + `collapseRangePx`; the optional
+ * `velocityGate` short-circuits on a flick; snaps to the nearest endpoint on scroll-stop.
+ * Writes `--chrome-collapse-t` onto `chromeRef` (when given). PERSISTENT by default
+ * (`collapseOnScroll: false`).
+ *
+ * @example
+ * ```ts
+ * const header = ref<HTMLElement | null>(null)
+ * useScrollChrome(() => window, { collapseOnScroll: true, chromeRef: header })
+ * // header.style sets --chrome-collapse-t; the .scroll-chrome recipe reads it.
+ * ```
+ */
+export declare function useScrollChrome(scrollContainer: MaybeRefOrGetter<HTMLElement | Window | null>, opts?: UseScrollChromeOptions): UseScrollChromeReturn;