@mkbabb/glass-ui 4.0.1 → 4.1.0

package/dist/composables/glass/useVizChoreography.d.ts

@@ -0,0 +1,123 @@
+import { type Easing } from "@mkbabb/keyframes.js";
+import { type Ref } from "vue";
+import { type SpringPresetName } from "../motion/springPresets";
+/**
+ * The reveal spring register. `bouncy` is the playful bloom (the dots spring out, the
+ * aurora blooms — the largest overshoot), `smooth` the calm settle, `snappy` the crisp
+ * control build, `gentle`/`dock` the patient/control ends. A named SPRING_PRESETS row —
+ * never a hand (response, ζ).
+ */
+export type VizChoreographyPreset = SpringPresetName;
+export interface UseVizChoreographyOptions {
+    /**
+     * The ENTER spring register (default `bouncy` — the playful liquid bloom the user
+     * named). The per-viz wave picks: `smooth` for a calm field settle, `bouncy` for the
+     * dot-scatter bloom.
+     */
+    preset?: VizChoreographyPreset;
+    /**
+     * The config-TRANSITION lerp duration in seconds. Default the ENTER preset's response
+     * (the spring-timed glide — never a hand wall clock). The cross-fade timing is the
+     * `springTimingFunction` of the SAME preset row.
+     */
+    transitionResponse?: number;
+    /**
+     * Honor `prefers-reduced-motion: reduce` → snap the reveal (zero spring frames, the
+     * fade survives, the scatter/transform leg is the viz's to drop). Default true. (A
+     * deterministic viz capture that ACCEPTS the live build-in opts out.)
+     */
+    respectReducedMotion?: boolean;
+    /**
+     * Start ALREADY revealed (revealT = 1) — for a viz mounted on a route that is already
+     * the active page (no enter beat owed). Default false (the page-enter starts collapsed
+     * and blooms). `enter()` always re-seats from the current value, so this is only the
+     * INITIAL seed.
+     */
+    initiallyRevealed?: boolean;
+}
+export interface UseVizChoreographyReturn {
+    /**
+     * The coupled reveal scalar ∈ [0,1] (may briefly overshoot >1 on a bouncy enter — the
+     * iOS bloom). The viz reads this for BOTH legs: the build-in uniform (settle-from-
+     * scatter) AND the canvas opacity (clamped via `opacity`). 0 = collapsed/scattered,
+     * 1 = fully materialized.
+     */
+    readonly revealT: Readonly<Ref<number>>;
+    /**
+     * The canvas opacity ∈ [0,1] — the coupled fade leg, `revealT` clamped to [0,1] (the
+     * fade does not overshoot; only the spatial build-in overshoots). The viz binds this
+     * to its canvas `style.opacity`.
+     */
+    readonly opacity: Readonly<Ref<number>>;
+    /**
+     * The config-transition progress ∈ [0,1] — the SmoothProgress glide a preset/variant
+     * morph reads to lerp its config uniforms (0 = the outgoing config, 1 = the incoming).
+     * Idle (settled at 1) when no transition is in flight.
+     */
+    readonly transitionT: Readonly<Ref<number>>;
+    /**
+     * True while the spatial build-in (the settle-from-scatter / the bloom transform) is
+     * ACTIVE — false under PRM (the viz drops the scatter, keeps the fade) and false once
+     * settled. The viz gates its scatter/transform leg on this (the P6 keeps-fade-drops-
+     * transform split).
+     */
+    readonly transformActive: Readonly<Ref<boolean>>;
+    /** True once the reveal has fully settled at its target (the loop can quiesce). */
+    readonly settled: Readonly<Ref<boolean>>;
+    /**
+     * A — START: bloom the viz in (revealT → 1) on the page-enter, on the ENTER spring
+     * register. Idempotent; a re-call mid-build re-seats velocity-continuously (the
+     * restart contract). PRM snaps to revealed (the fade survives, the scatter drops).
+     */
+    enter: () => void;
+    /**
+     * C — END: settle the viz out (revealT → 0) on the no-overshoot exit register, then
+     * the loop parks (the viz reads `settled`/`revealT === 0` to stop). PRM snaps to
+     * collapsed. A closing surface must not overshoot past gone (P2).
+     */
+    leave: () => void;
+    /**
+     * B — TRANSITION: glide a config/variant morph. Re-seats `transitionT` 0→1 on the
+     * SmoothProgress lerp; the viz reads `transitionT` to lerp its config uniforms each
+     * frame. `onComplete` (optional) fires once the glide settles. PRM snaps the glide.
+     */
+    transitionTo: (onComplete?: () => void) => void;
+    /**
+     * D — RESTART: re-seat the reveal from the CURRENT (value, velocity) so a restart mid-
+     * build inherits the live trajectory (the iOS interruptible contract — never a jump-
+     * to-zero). Snaps revealT back to 0 then blooms 1 velocity-continuously.
+     */
+    restart: () => void;
+    /**
+     * Advance the choreography ONE renderer frame. The viz calls this from INSIDE its
+     * existing `createCanvasLifecycle` frame callback with the frame `dtMs` (milliseconds).
+     * NO own rAF — the renderer owns the loop. Steps the reveal spring + the transition
+     * lerp analytically (O(1), zero allocation). Returns the live `revealT` (so a renderer
+     * can read inline). A zero/negative `dtMs` is a no-op step (a paused/first frame).
+     */
+    tick: (dtMs: number) => number;
+    /** The transition cross-fade easing (the typed {fn,css} pair) — for a viz that wants
+     *  the spring curve directly (e.g. to time a CSS-side companion). */
+    readonly transitionEasing: Easing;
+}
+/**
+ * The procedural-viz choreography clock. Composes the published-4.3.0 kf
+ * `SpringProgress` (the reveal scalar) + `SmoothProgress` (the config lerp) +
+ * `springTimingFunction` (the cross-fade timing), FED `tick(dt)` from the consuming
+ * viz's frame callback. Owns NO rAF (the one-loop discipline; the viz feed it). See the
+ * module header for the four beats, the coupled-fade drive, the one-loop fence, and the
+ * Oscillator book.
+ *
+ * @example
+ * ```ts
+ * const choreo = useVizChoreography({ preset: "bouncy" });
+ * // inside createCanvasLifecycle's frame(timeSec):
+ * const dtMs = (timeSec - lastSec) * 1000;
+ * choreo.tick(dtMs);
+ * canvas.style.opacity = String(choreo.opacity.value);
+ * gl.uniform1f(uReveal, choreo.revealT.value); // the settle-from-scatter build-in
+ * // page-enter / route-leave:
+ * watch(active, (on) => (on ? choreo.enter() : choreo.leave()));
+ * ```
+ */
+export declare function useVizChoreography(options?: UseVizChoreographyOptions): UseVizChoreographyReturn;

package/dist/composables/glass/webgl/createCanvasLifecycle.d.ts

@@ -41,5 +41,15 @@ export interface CanvasLifecycleHandle {
     readonly disposed: boolean;
     readonly running: boolean;
     readonly reducedMotion: boolean;
+    /**
+     * BC.W-SAFARI-WEBGL — the circuit-breaker has tripped: the surface lost-and-restored
+     * its context more than N times within T ms (a real eviction storm), so the lifecycle
+     * is HOLDING the parked state without re-arming (no throw). Resets once the loss window
+     * passes quiet; a healthy single loss never trips it.
+     */
+    readonly contextHeld: boolean;
 }
+export declare const N_RESTORE_STORM = 3;
+export declare const T_RESTORE_STORM_MS = 2000;
+export declare const RESTORE_DEBOUNCE_MS = 100;
 export declare function createCanvasLifecycle(options: CanvasLifecycleOptions): CanvasLifecycleHandle;

package/dist/composables/glass/webgl/shaders/flow.wgsl.d.ts

@@ -0,0 +1 @@
+export declare const CURL_FBM_WGSL = "\nconst CURL_EPS: f32 = 0.012;\n\n// \u2207\u00D7\u03C8 in 2D \u2014 the divergence-free flow direction. Central finite differences of the\n// scalar potential give the partials; the cross-pairing (\u2202y, \u2212\u2202x) is the 2D curl.\nfn curlFBM(p: vec2f) -> vec2f {\n  let dx = potentialFBM(p + vec2f(CURL_EPS, 0.0)) - potentialFBM(p - vec2f(CURL_EPS, 0.0));\n  let dy = potentialFBM(p + vec2f(0.0, CURL_EPS)) - potentialFBM(p - vec2f(0.0, CURL_EPS));\n  // \u03C8-gradient is (dx, dy)/(2\u00B7eps); the curl rotates it 90\u00B0: (\u2202\u03C8/\u2202y, \u2212\u2202\u03C8/\u2202x).\n  let g = vec2f(dx, dy) / (2.0 * CURL_EPS);\n  return vec2f(g.y, -g.x);\n}\n";

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

@@ -1,2 +1,2 @@
-export { createWebGPUCanvas, supportsWebGPU, type WebGPUCanvasFrame, type WebGPUCanvasHandle, type WebGPUCanvasOptions, type WebGPUSuspendReason, } from "./useWebGPUCanvas";
+export { createWebGPUCanvas, supportsWebGPU, WebGPUInitError, type WebGPUCanvasFrame, type WebGPUCanvasHandle, type WebGPUCanvasOptions, type WebGPUSuspendReason, } from "./useWebGPUCanvas";
 export { createGpuSubstrate, type GpuBackend, type GpuSubstrateHandle, type GpuSubstrateOptions, } from "./useGpuSubstrate";

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

@@ -24,19 +24,36 @@ export interface GpuSubstrateOptions {
     contextAttrs?: WebGLCanvasOptions["contextAttrs"];
     /** Surface a device-init / validation failure (the WebGPU path). */
     onInitError?: WebGPUCanvasOptions["onInitError"];
+    /**
+     * Notified when the picker FALLS from WebGPU to the WebGL2 net (the invisible
+     * insurance fired). The user never sees a "downgrade" — this is a diagnostic hook
+     * (e.g. record the tier-readout for the substrate DELTA), NOT an error. The error
+     * (if any) that triggered the fall is passed for telemetry.
+     */
+    onBackendFallback?: (info: {
+        from: "webgpu";
+        to: "webgl2";
+        error: unknown;
+    }) => void;
 }
 /**
  * The uniform substrate handle. A viz consumer wires its lifecycle (offscreen pause,
  * pause/resume, pointer-`wake`, capture-`renderAt`) against THIS — identical across the
- * WebGPU and WebGL2 backends. `armAsync` is the start seam (the WebGPU path awaits the
- * device; the WebGL2 path resolves immediately); `arm` is the synchronous twin.
+ * WebGPU and WebGL2 backends. `armAsync` is the start seam (it tries WebGPU then falls
+ * to the WebGL2 net on a no-adapter/init failure); `arm` is the synchronous twin (it
+ * arms the WebGL2 net immediately so a consumer that does not await still paints).
  */
 export interface GpuSubstrateHandle {
-    /** The resolved backend (`"webgpu"` where supported + a WGSL path is provided, else `"webgl2"`). */
+    /**
+     * The resolved backend. Starts at the OPTIMISTIC choice (`"webgpu"` where the
+     * platform allows it + a WGSL path is provided, else `"webgl2"`); after
+     * `armAsync()` it reflects the ACTUAL backend (it falls to `"webgl2"` if the
+     * WebGPU init failed — the no-adapter/device-lost-at-birth tail).
+     */
     readonly backend: GpuBackend;
-    /** Acquire the device/context + `setup` + arm the loop. Resolves once armed. */
+    /** Acquire the device/context + `setup` + arm the loop (try WebGPU, fall to the WebGL2 net). Resolves once armed. */
     armAsync: () => Promise<void>;
-    /** Synchronous arm (the WebGL2 path arms immediately; the WebGPU path is a no-op until the device resolves). */
+    /** Synchronous arm (the WebGL2 net arms immediately; the WebGPU path is a no-op until the device resolves). */
     arm: () => void;
     suspend: (reason?: "tab-hidden" | "off-screen" | "off-screen-io" | "manual") => void;
     resume: (reason?: "tab-hidden" | "off-screen" | "off-screen-io" | "manual") => void;
@@ -47,8 +64,12 @@ export interface GpuSubstrateHandle {
 }
 /**
  * Pick the backend + return the uniform handle. WebGPU-first (`supportsWebGPU()` AND a
- * `setupWGPU` callback is provided); otherwise the WebGL2 fallback. The decision is
- * made ONCE at construction (a mount-time device-tier choice, not a reactive one).
+ * `setupWGPU` callback is provided); otherwise the WebGL2 net. The decision is NO
+ * LONGER committed at construction off a presence check — `armAsync()` ATTEMPTS the
+ * WebGPU init and FALLS to the WebGL2 net on ANY failure (no adapter, device reject,
+ * device-lost-at-birth, validation throw). The WebGL2 leaf is built lazily — only if
+ * the WebGPU path fails OR no WGSL path was provided — so a Baseline host pays no
+ * WebGL2-context cost.
  */
 export declare function createGpuSubstrate(canvas: HTMLCanvasElement, options: GpuSubstrateOptions): GpuSubstrateHandle;
 export type { WebGPUCanvasFrame, WebGLCanvasFrame };

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

@@ -1,3 +1,4 @@
+export { WebGPUInitError } from "./webgpuDevice";
 /**
  * The ONE `navigator.gpu` capability probe (the single-bootstrap rule — mirrors
  * `probeWebGL2Renderer`). SSR-safe (returns `false` with no `navigator`). The picker

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

@@ -11,3 +11,6 @@ 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/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

@@ -36,6 +36,25 @@ export interface UseDockCtaReceiveReturn {
      * 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` +
@@ -47,12 +66,18 @@ export interface UseDockCtaReceiveReturn {
  *
  * @example
  * ```ts
- * const { receive, reset } = useDockCtaReceive(ctaRef, {
- *   dockControl: dockTargetRef,
- *   preset: "snappy",
- *   onReceived: () => (ctaConsumed.value = true),
- * })
- * // on the CTA click: morph it into the dock.
+ * 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() }
  * ```
  */

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;

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

@@ -0,0 +1,67 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+/**
+ * A declared trigger-point on the scroll source: a pixel offset, a 0..1 progress
+ * fraction (resolved against the source's scrollable extent), or a named element
+ * whose top crosses the source.
+ */
+export interface TriggerPoint {
+    /**
+     * A pixel offset on the scroll source, OR a 0..1 progress fraction (resolved
+     * against the source's scrollable extent), OR a named element whose top crosses
+     * the source.
+     */
+    at: number | {
+        fraction: number;
+    } | {
+        element: MaybeRefOrGetter<HTMLElement | null>;
+    };
+    /** Fire on which crossing direction. Default "both". */
+    direction?: "down" | "up" | "both";
+    /** Stable id for the event payload + de-dup. */
+    id?: string;
+}
+export interface UseScrollTriggerOptions {
+    triggers?: TriggerPoint[];
+    /**
+     * The flip-delta debounce (px) before a DIRECTION flip commits — the anti-thrash,
+     * mirroring the dock's HOVER_INTENT_MS=60ms hysteresis. Default 8 (the RN
+     * reference).
+     */
+    flipDeltaPx?: number;
+    /** Resolve the continuous `progress` ref against the source (0..1). Default true. */
+    trackProgress?: boolean;
+    /** Honor `prefers-reduced-motion: reduce` (snap `progress` to discrete endpoints). Default true. */
+    respectReducedMotion?: boolean;
+    /** Crossed a trigger in the committed direction (fires ONCE per crossing). */
+    onCross?: (id: string, dir: "down" | "up", scrollPos: number) => void;
+    /** Crossed a trigger scrolling INTO its region (past it, in `down`). */
+    onEnter?: (id: string) => void;
+    /** Crossed OUT of a trigger's region (back before it, in `up`). */
+    onLeave?: (id: string) => void;
+}
+export interface UseScrollTriggerReturn {
+    /** Continuous 0..1 scroll progress off the SAME rAF read (native-timeline-gated). */
+    progress: Ref<number>;
+    /** Current scroll direction (committed past flipDeltaPx). */
+    direction: Ref<"down" | "up" | null>;
+    /** Current scroll velocity (px/s, framerate-independent — Δpos / Δt). */
+    velocity: Ref<number>;
+    /** Force a re-read + re-evaluate every trigger (post-resize/layout). */
+    recalculate: () => void;
+}
+/**
+ * The ONE scroll reader. Composes `createScrollReader` (the shared rAF-coalesced
+ * core); resolves triggers to px; emits direction/velocity/crossing; native-timeline-
+ * gated continuous ramp.
+ *
+ * @example
+ * ```ts
+ * const { progress, direction, velocity } = useScrollTrigger(() => window, {
+ *   triggers: [{ at: 120, id: "shrink", direction: "down" }],
+ *   onCross(id, dir, pos) {  // fires once when crossing 120px scrolling down
+ *     if (id === "shrink" && dir === "down") collapseChrome()
+ *   },
+ * })
+ * ```
+ */
+export declare function useScrollTrigger(scrollSource: MaybeRefOrGetter<HTMLElement | Window | null>, opts?: UseScrollTriggerOptions): UseScrollTriggerReturn;

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

@@ -1,14 +1,14 @@
 import { type UseSpringOptions, type SpringRef } from "./useSpring";
 export interface UseSpringPressOptions extends UseSpringOptions {
     /**
-     * Spring `response`. Default 0.25s (iOS tap-press canonical; faster
-     * than the default `useSpring` 0.5s to keep press feedback under the
-     * 100ms perception threshold).
+     * Spring `response`. Default `0.15s` — the `press` SPRING_PRESETS row (the
+     * Apple `interactiveSpring`): the sub-100ms iOS tap-press window, faster than
+     * the generic `useSpring` 0.5s so the feedback lands under the 100ms threshold.
      */
     response?: number;
     /**
-     * Spring `dampingFraction`. Default 0.7 (overshoots ~5% — feels
-     * springy but doesn't ring).
+     * Spring `dampingFraction`. Default `0.86` — the `press` row's ζ: a tiny
+     * sub-perceptual rebound (springy/alive) that does NOT ring.
      */
     dampingFraction?: number;
 }

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

@@ -25,4 +25,28 @@ export declare function useStaggerReveal(options?: StaggerRevealConfig): {
     register: (el: HTMLElement | null, index?: number) => void;
     revealed: Record<number, boolean>;
 };
+/**
+ * The `[data-scroll-reveal-once]` latch — BC.W-MOTION-PRESETS.
+ *
+ * The `scroll-driven.css` `[data-scroll-reveal]` recipe rides a native `view()`
+ * timeline that RE-FIRES its entrance every time a child re-enters the entry range
+ * — wrong for a virtualized/teleporting list (a row scrolls out + back and re-plays
+ * the fade-lift). A `view()` timeline cannot latch "play once" (the CSS limit), so
+ * the `[data-scroll-reveal-once]` opt-in plays the entrance ONCE: this directive
+ * adds `data-revealed=""` to each child on its FIRST cross and `unobserve`s it (the
+ * SAME `once: true` discipline `useStaggerReveal` runs above — `if (once)
+ * observer?.unobserve(el)`); the CSS plays the one-shot `gl-reveal-once` keyframe
+ * keyed off `[data-revealed]`, NOT the live `view()` range. NO second observer
+ * engine — the same `IntersectionObserver` the composable speaks for the `once`
+ * case, packaged as a Vue directive a consumer binds on the scroller.
+ *
+ * On an engine without `IntersectionObserver` (SSR/old) it reveals immediately so
+ * the terminal state is correct (the CSS animation simply never plays). Under PRM
+ * the scroll-driven.css `@media` outer gate drops the entrance and the row paints
+ * in-place (a flourish — the reveal carve, not a legibility cue).
+ */
+export declare const vScrollRevealOnce: {
+    mounted(scroller: HTMLElement): void;
+    unmounted(scroller: HTMLElement): void;
+};
 export {};

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

@@ -4,4 +4,7 @@ export type { SidebarFollowOptions } from "./useSidebarFollow";
 export { useSidebarState } from "./useSidebarState";
 export type { UseSidebarStateOptions, GenericSidebarState } from "./useSidebarState";
 export { useTreeIndex, buildTreeIndex, isActive, isInActiveChain } from "./useTreeIndex";
-export type { TreeNode, TreeIndexEntry, SidebarSection, SidebarIndexEntry, SidebarState, ScrollTrackerOptions, } from "./types";
+export { useScrollTo } from "./useScrollTo";
+export { useClickDelegate } from "./useClickDelegate";
+export { useLazyLoader } from "./useLazyLoader";
+export type { TreeNode, TreeIndexEntry, SidebarSection, SidebarIndexEntry, SidebarState, ScrollTrackerOptions, ScrollToOptions, ClickDelegateOptions, LazyLoaderOptions, } from "./types";