@mkbabb/glass-ui 4.1.0 → 4.2.0

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

@@ -1,4 +1,41 @@
 export type CanvasSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
+export interface BackingSize {
+    w: number;
+    h: number;
+    dpr: number;
+    changed: boolean;
+}
+/**
+ * The consumer's DPR policy — either a flat multiplier or a box-aware resolver (e.g.
+ * aurora's 1.5× wash ceiling vs goo-blob's 2× focal `resolveBudgetDpr`). The leaf owns
+ * the MEASUREMENT + the floor; the consumer owns ONLY the DPR number.
+ */
+export type DprPolicy = number | ((box: {
+    w: number;
+    h: number;
+}) => number);
+/**
+ * BD.W-SUBSTRATE-SIZE-UNIFY (G1) — the ONE canonical backing-store sizer.
+ *
+ * Aurora's PROVEN gBCR-ancestor sizer, lifted into the agnostic leaf so it lives ONCE
+ * (DRY) instead of in N drifted consumer `resize()` closures (the three incompatible
+ * `clientWidth || 320` / `clientWidth || canvasSize` / one-parent-gBCR conventions the
+ * DELTA-ASSAY reproduced as the live 300×150 stuck-canvas).
+ *
+ * Measures the LAID-OUT border-box via `getBoundingClientRect` — NOT `clientWidth`,
+ * which reads 0 under a `content-visibility:auto` skip (the born-skipped trap). Walks
+ * ancestors ONLY when our own rect is still zero (truly un-laid-out), and the walk is
+ * BOUNDED (H-B): cap depth at 3 AND stop at the first sized / contained / container /
+ * positioned ancestor — never an unbounded gBCR storm to `<body>` (O(depth) reflow per
+ * tick), never an over-recovered wide flex/grid grandparent that sizes the backing to
+ * the viewport. Idempotent: the realloc (which CLEARS the drawing buffer) is skipped
+ * when the buffer already matches the box.
+ *
+ * Pure CSS-geometry — ZERO dependency on which GPU API is live, so it runs SYNCHRONOUSLY
+ * at mount before the async WebGPU device resolves (G2). Engine-identical in Chromium +
+ * WebKit (gBCR reflects the real box across a CV skip in both).
+ */
+export declare function sizeBacking(canvas: HTMLCanvasElement, dprPolicy: DprPolicy): BackingSize;
 /** The per-frame hooks a backend's `buildContext` returns to the lifecycle core. */
 export interface CanvasFrameHooks {
     /** Draw one frame at `timeSec`. */
@@ -19,8 +56,26 @@ export interface CanvasLifecycleOptions {
      * on a backend context-restore. Throws on backend-unavailable / setup failure.
      */
     buildContext: () => CanvasFrameHooks;
-    /** Resize the backing store + viewport. The consumer owns its DPR policy. */
-    resize: () => void;
+    /**
+     * Upload the backing geometry to the viewport/uniforms.
+     *
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G1): the leaf now MEASURES + sizes the backing store
+     * (via `sizeBacking`, the ONE sizer) and passes the freshly-computed `BackingSize`
+     * here so the consumer can never re-derive a wrong one. The arg is OPTIONAL only so
+     * a legacy consumer that still self-measures keeps compiling during the consumer
+     * cut-over; a consumer SHOULD read `s` and skip its own gBCR/DPR block. When the
+     * leaf owns sizing (`dprPolicy` provided) the buffer is already correct on entry —
+     * the consumer body shrinks to `gl.viewport(0,0,s.w,s.h)` / `uploadResolution`.
+     */
+    resize: (s?: BackingSize) => void;
+    /**
+     * The consumer's DPR policy, handed to the leaf's `sizeBacking`. When PRESENT the
+     * leaf owns the backing-store MEASUREMENT + sizing (the G1 inversion) and the live
+     * `BackingSize` rides every `resize` call. When ABSENT the leaf falls back to the
+     * legacy behaviour (the consumer's `resize()` self-measures) — the migration seam
+     * so a consumer can adopt the leaf sizer one viz at a time without a flag-day break.
+     */
+    dprPolicy?: DprPolicy;
     /**
      * Bind/unbind backend-specific context-loss/restore listeners. `rebuild` re-runs
      * `buildContext` on a fresh context + resumes the loop (the self-heal); the backend
@@ -29,9 +84,47 @@ export interface CanvasLifecycleOptions {
      */
     bindContextEvents?: (rebuild: () => void, markContextLost: () => void) => void;
     unbindContextEvents?: () => void;
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G3) — compose the IntersectionObserver park detector
+     * at the leaf (DRY) so a consumer inherits the off-screen IO-park ORed with the
+     * content-visibility park, with NO per-viz `useIntersectionPause` wiring. The leaf
+     * wires a plain (scope-free, reactivity-free) IO observing the canvas, writing the
+     * DISTINCT `"off-screen-io"` reason. On `isIntersecting → true` it ALSO re-measures
+     * via `sizeBacking` (the reveal belt-and-braces, the load-bearing path on WebKit
+     * where `contentvisibilityautostatechange` support is weaker).
+     *
+     * Default `false` — OPT-IN. Today several consumers (goo-blob, goo-dot-matrix)
+     * already write `"off-screen-io"` from their OWN `useIntersectionPause`; a leaf IO
+     * defaulting on would DOUBLE-WRITE that reason and breach the one-writer invariant.
+     * The atomic retirement of those per-consumer calls (so the leaf IO becomes the sole
+     * writer, default-on) lands in the viz lanes. Until then a viz with NO IO wiring
+     * (concentric / fourier / dot-flow — the live PARK gap) opts IN to inherit the park.
+     */
+    composeIntersectionPark?: boolean;
+    /** `rootMargin` for the leaf-composed IO park (G3). Default `"256px"` (pre-warm). */
+    intersectionRootMargin?: string;
+    /**
+     * BD.W-SUBSTRATE-REVEAL-BLOOM (G6) — the cold-first-paint reveal seam. When set, the
+     * leaf toggles a `--substrate-reveal-t` 0→1 scalar on the canvas at the cold-arm
+     * paint (ONCE, never on an IO/CV re-reveal of an already-seen viz). The shader reads
+     * it to ramp luminance/saturation/drift — a FIELD bloom (the canvas rect stays
+     * `scale(1)`, no box-zoom gutter). Gated on the Band-0 `--ease-cartoon-punch` +
+     * `--motion-weight` tokens (NOT shipped today); absent, this is a no-op so the
+     * substrate paints exactly as before. PRM → the scalar is set to its settled `1`
+     * immediately (zero ramp).
+     */
+    revealBloom?: boolean;
 }
 export interface CanvasLifecycleHandle {
     arm: () => void;
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing store + start the leaf RO
+     * SYNCHRONOUSLY, decoupled from the (async) context acquire. The WebGPU backend
+     * calls this BEFORE `armAsync`'s device request so the canvas is sharp from frame 0
+     * while the device resolves behind it (the ≤6s blurry-flash close). Idempotent: a
+     * no-op once `arm()` has run it. A no-op when no `dprPolicy` was supplied (legacy).
+     */
+    presize: () => void;
     suspend: (reason?: CanvasSuspendReason) => void;
     resume: (reason?: CanvasSuspendReason) => void;
     wake: () => void;

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

@@ -1,3 +1,5 @@
+import { type BackingSize, type DprPolicy } from "./createCanvasLifecycle";
+export type { BackingSize, DprPolicy } from "./createCanvasLifecycle";
 /**
  * The ONE `getContext("webgl2")` capability probe (BB.W-CI-GREEN — the
  * single-bootstrap rule). A throwaway WebGL2 context is created here, in the
@@ -14,6 +16,21 @@
  * `document`).
  */
 export declare function probeWebGL2Renderer(): string | null;
+/**
+ * The WebGPU→WebGL2 fall POISON test — can THIS specific canvas still host WebGL2?
+ * (BD.W-VIZ-BROKEN-FIX — the single-bootstrap home for the probe.) Once `getContext("webgpu")`
+ * has run on a canvas, the HTML one-context-type rule locks it to `webgpu` forever and
+ * `getContext("webgl2")` returns `null`. The picker's fall-to-WebGL2 path probes this to
+ * decide whether it must clone+swap the canvas (genuinely poisoned) or can keep the original
+ * (a fall that ran BEFORE any `getContext("webgpu")` — no-adapter / device-reject / acquire-
+ * timeout — never poisoned it; reusing it avoids orphaning the consumer's captured canvas
+ * reference). The `getContext("webgl2")` bootstrap stays in THIS substrate (the sole webgl2-
+ * creating module per `proof:webgl-substrate-single` clause B); the picker composes this
+ * helper rather than calling `getContext("webgl2")` itself. `getContext` is idempotent for
+ * the same type, so on a clean canvas the probe returns the very context the net re-acquires
+ * (no extra cost). Returns `true` if the canvas can host WebGL2, `false` if poisoned/unable.
+ */
+export declare function canvasCanHostWebGL2(canvas: HTMLCanvasElement): boolean;
 export type WebGLSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
 /** The per-frame hooks a consumer's `setup(gl)` returns. */
 export interface WebGLCanvasFrame {
@@ -21,8 +38,14 @@ export interface WebGLCanvasFrame {
     frame: (timeSec: number) => void;
     /** Demand-gate: is there live motion to render next frame? `false` → park. */
     shouldContinue: () => boolean;
-    /** Size the canvas + set the viewport. The consumer owns its DPR policy. */
-    resize: () => void;
+    /**
+     * Upload the backing geometry to the viewport/uniforms. BD.W-SUBSTRATE-SIZE-UNIFY:
+     * when a `dprPolicy` is supplied the leaf MEASURES + sizes the backing and passes
+     * the live `BackingSize` here (the consumer body shrinks to
+     * `gl.viewport(0,0,s.w,s.h)`); the arg is optional so a legacy self-measuring
+     * consumer keeps compiling until it adopts the leaf sizer.
+     */
+    resize: (s?: BackingSize) => void;
     /** Frame time from elapsed seconds — the consumer owns frozen/reduced-motion. */
     time?: (elapsedSec: number) => number;
     /** Delete GL resources (program/buffers/VAO). Runs on dispose + before a restore re-setup. */
@@ -42,6 +65,19 @@ export interface WebGLCanvasOptions {
      * reads the live value via `handle.reducedMotion` (e.g. aurora's frozen-t).
      */
     respectReducedMotion?: boolean;
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G1/G2) — the consumer's DPR policy. When PRESENT the
+     * leaf owns the backing-store measurement + sizing (the ONE sizer, sized
+     * synchronously at mount before any acquire) and hands the live `BackingSize` to
+     * `resize(s)`. When ABSENT the legacy path runs (the consumer self-measures).
+     */
+    dprPolicy?: DprPolicy;
+    /** Compose the leaf IO park (G3). Default `false` (opt-in; see createCanvasLifecycle). */
+    composeIntersectionPark?: boolean;
+    /** `rootMargin` for the leaf IO park (G3). */
+    intersectionRootMargin?: string;
+    /** Fire the cold-first-paint reveal bloom (G6, gated on Band-0 tokens). Default `false`. */
+    revealBloom?: boolean;
     /**
      * Build the program + geometry on a fresh context. Called on `arm()` AND on
      * every `webglcontextrestored`. Returns the per-frame hooks.
@@ -51,6 +87,8 @@ export interface WebGLCanvasOptions {
 export interface WebGLCanvasHandle {
     /** Run the expensive init (context + `setup` + arm the loop). Idempotent; no-op post-dispose. */
     arm: () => void;
+    /** BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing + start the leaf RO synchronously (pre-acquire). */
+    presize: () => void;
     suspend: (reason?: WebGLSuspendReason) => void;
     resume: (reason?: WebGLSuspendReason) => void;
     /** Re-arm a parked loop (a setter that re-introduced motion calls this). */

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

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

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

@@ -1,4 +1,6 @@
 import { type WebGLCanvasFrame, type WebGLCanvasOptions } from "../webgl/useWebGLCanvas";
+import type { DprPolicy } from "../webgl/createCanvasLifecycle";
+export type { BackingSize, DprPolicy } from "../webgl/createCanvasLifecycle";
 import { supportsWebGPU, type WebGPUCanvasFrame, type WebGPUCanvasOptions } from "./useWebGPUCanvas";
 export { supportsWebGPU };
 /** Which backend the picker resolved. */
@@ -15,6 +17,32 @@ export interface GpuSubstrateOptions {
     setupWGPU?: WebGPUCanvasOptions["setup"];
     /** The GLSL program builder (the WebGL2 fallback path — always required). */
     setupGL: WebGLCanvasOptions["setup"];
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G1/G2) — the consumer's DPR policy (a flat multiplier
+     * or a box-aware resolver). When PRESENT the leaf owns the backing-store measurement
+     * + sizes it SYNCHRONOUSLY at mount (the ONE sizer; before the async acquire on the
+     * WebGPU path), handing the live `BackingSize` to each `setup`'s `resize(s)`. When
+     * ABSENT the legacy path runs (the consumer self-measures) — the per-viz adoption
+     * seam, identical on both backends.
+     */
+    dprPolicy?: DprPolicy;
+    /**
+     * G3 — compose the leaf IntersectionObserver park (a consumer inherits the
+     * off-screen IO-park ORed with content-visibility, no per-viz `useIntersectionPause`
+     * wiring). Default `false` (OPT-IN): several consumers already write `"off-screen-io"`
+     * from their own `useIntersectionPause` and a leaf IO default-on would double-write
+     * that reason. A viz with NO IO wiring (concentric/fourier/dot-flow) opts IN.
+     */
+    composeIntersectionPark?: boolean;
+    /** `rootMargin` for the leaf IO park (G3). Default `"256px"`. */
+    intersectionRootMargin?: string;
+    /**
+     * G6 — fire the cold-first-paint reveal bloom (a one-shot `--substrate-reveal-t`
+     * 0→1 the shader reads to ramp the field from within). Gated on the Band-0
+     * `--ease-cartoon-punch` + `--motion-weight` tokens; a no-op until they land.
+     * Default `false`.
+     */
+    revealBloom?: boolean;
     /** WebGPU `context.configure` alpha mode (default `"premultiplied"`). */
     alphaMode?: WebGPUCanvasOptions["alphaMode"];
     /** WebGPU adapter/device request options. */
@@ -55,6 +83,15 @@ export interface GpuSubstrateHandle {
     armAsync: () => Promise<void>;
     /** Synchronous arm (the WebGL2 net arms immediately; the WebGPU path is a no-op until the device resolves). */
     arm: () => void;
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing store + start the leaf RO
+     * SYNCHRONOUSLY, decoupled from the (async) backend acquire. Call it the instant the
+     * canvas is in the DOM so the field is sharp from frame 0 while the device resolves
+     * (the ≤6s blurry-flash close). `armAsync` already calls it internally on both legs;
+     * exposed so a consumer can presize even earlier (e.g. immediately on mount, before
+     * the awaited `armAsync`). A no-op when no `dprPolicy` was supplied (legacy).
+     */
+    presize: () => void;
     suspend: (reason?: "tab-hidden" | "off-screen" | "off-screen-io" | "manual") => void;
     resume: (reason?: "tab-hidden" | "off-screen" | "off-screen-io" | "manual") => void;
     wake: () => void;

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

@@ -1,3 +1,5 @@
+import { type BackingSize, type DprPolicy } from "../webgl/createCanvasLifecycle";
+export type { BackingSize, DprPolicy } from "../webgl/createCanvasLifecycle";
 export { WebGPUInitError } from "./webgpuDevice";
 /**
  * The ONE `navigator.gpu` capability probe (the single-bootstrap rule — mirrors
@@ -7,6 +9,31 @@ export { WebGPUInitError } from "./webgpuDevice";
  * clause A reds a direct call).
  */
 export declare function supportsWebGPU(): boolean;
+/**
+ * The bound on the adapter/device acquisition (ms). `requestAdapter()` /
+ * `requestDevice()` can resolve NEITHER way on a hanging host (a headless / virtualized-
+ * Metal + some-Chrome class). A REAL cold acquire on a healthy Metal-3 host was live-
+ * measured at ~3478ms (the FIRST `requestDevice` on a cold GPU process) — well over the
+ * prior tight 2500ms ceiling, which converted a slow-but-fine cold acquire into a FALSE
+ * hang so the WGSL primary was never exercised (every viz silently downgraded to WebGL2
+ * forever — the Safari-primary surface the "broken TOTALLY" reports live on, masked by the
+ * always-winning fallback). 6000ms lets the real cold acquire through while a genuine wedge
+ * (a device that never settles) still falls to the WebGL2 net before the user perceives a
+ * permanent blank. With the SHARED device warm (`acquireSharedDevice`) the ceiling is hit
+ * at most ONCE per page, not N-times-per-canvas — a single ≤6s race, never N.
+ */
+export declare const WEBGPU_ACQUIRE_TIMEOUT_MS = 6000;
+/**
+ * Reset the PROCESS-SHARED device memo. The shared-device warm (D3a) is a module-level
+ * singleton — the first canvas on a page pays the cold `requestAdapter` → `requestDevice`
+ * and every later canvas reuses it. That is correct in production (one device per page),
+ * but it makes the memo leak ACROSS isolated unit tests in the same file (a prior test's
+ * resolved device satisfies a later test's `armAsync`, so `requestAdapter` is never called
+ * + the no-adapter path never runs). A test calls this in `beforeEach` to restore a clean
+ * per-test acquire. NOT part of the runtime API surface — exported only for the substrate's
+ * own test isolation (no consumer reaches for it).
+ */
+export declare function __resetSharedGpuDeviceForTest(): void;
 export type WebGPUSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
 /**
  * The per-frame hooks a consumer's `setup(device, context, format)` returns. The
@@ -22,8 +49,13 @@ export interface WebGPUCanvasFrame {
     frame: (timeSec: number) => void;
     /** Demand-gate: is there live motion to render next frame? `false` → park. */
     shouldContinue: () => boolean;
-    /** Size the canvas backing store. The consumer owns its DPR policy. */
-    resize: () => void;
+    /**
+     * Upload the backing geometry. BD.W-SUBSTRATE-SIZE-UNIFY: when a `dprPolicy` is
+     * supplied the leaf sizes the backing + passes the live `BackingSize` here (the
+     * WGSL swap chain auto-tracks the backing, so the consumer body shrinks to an aspect
+     * upload). The arg is optional so a legacy self-measuring consumer keeps compiling.
+     */
+    resize: (s?: BackingSize) => void;
     /** Frame time from elapsed seconds — the consumer owns frozen/reduced-motion. */
     time?: (elapsedSec: number) => number;
     /** Release per-instance GPU resources (pipelines/buffers/bind groups). Runs on dispose + before a restore re-setup. */
@@ -45,6 +77,19 @@ export interface WebGPUCanvasOptions {
      * Default `true` for live mode, `false` for capture mode.
      */
     respectReducedMotion?: boolean;
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G1/G2) — the consumer's DPR policy. When PRESENT the
+     * leaf sizes the backing SYNCHRONOUSLY at mount (via `presize`, BEFORE the async
+     * device acquire — the ≤6s blurry-flash close) and hands the live `BackingSize` to
+     * `resize(s)`. When ABSENT the legacy path runs (the consumer self-measures).
+     */
+    dprPolicy?: DprPolicy;
+    /** Compose the leaf IO park (G3). Default `false` (opt-in; see createCanvasLifecycle). */
+    composeIntersectionPark?: boolean;
+    /** `rootMargin` for the leaf IO park (G3). */
+    intersectionRootMargin?: string;
+    /** Fire the cold-first-paint reveal bloom (G6, gated on Band-0 tokens). Default `false`. */
+    revealBloom?: boolean;
     /**
      * Build the WGSL pipeline + bind groups on the resolved device. Called on the
      * async arm AND on every device-restore. Returns the per-frame hooks.
@@ -66,6 +111,8 @@ export interface WebGPUCanvasHandle {
      * `armAsync` for the WebGPU path). Idempotent.
      */
     arm: () => void;
+    /** BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing + start the leaf RO synchronously, before the async acquire. */
+    presize: () => void;
     suspend: (reason?: WebGPUSuspendReason) => void;
     resume: (reason?: WebGPUSuspendReason) => void;
     /** Re-arm a parked loop (a setter that re-introduced motion calls this). */

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

@@ -9,7 +9,7 @@
  * `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";
+    readonly kind: "no-adapter" | "device-request" | "no-navigator-gpu" | "software-adapter" | "pipeline-validation" | "acquire-timeout";
     constructor(kind: WebGPUInitError["kind"], message: string, cause?: unknown);
 }
 /**

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

@@ -10,7 +10,11 @@ export * from "../useViewTransition";
 export * from "../vReveal";
 export * from "../useTextHighlight";
 export * from "../useLiquidFlex";
+export * from "../useGooMorph";
+export * from "../useMorphField";
 export * from "../usePointerVelocityField";
 export * from "../useCharStagger";
 export * from "../useScrollTrigger";
 export * from "../useScrollChrome";
+export * from "./useHaptic";
+export * from "./writeVelocityWeight";

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

@@ -0,0 +1,48 @@
+import { type MaybeRefOrGetter } from "vue";
+/**
+ * The named haptic register — each maps to a small, bounded `navigator.vibrate` ms
+ * vocabulary (all sub-100ms total, never a buzz). The standard short-pattern set:
+ *   · `tap`        — a single crisp tick (a button press confirm).
+ *   · `snap`       — a fling/drag landing into a slot.
+ *   · `detent`     — a tiny double-tick (a piece seating into a detent).
+ *   · `completion` — the earned-moment confirm (a download done, a personal-best).
+ *   · `error`      — a short three-pulse warn.
+ */
+export type HapticPattern = "tap" | "snap" | "detent" | "completion" | "error";
+export interface UseHapticOptions {
+    /**
+     * The consumer opt-out (the suppression axis — NOT PRM). When falsy, `pulse()` is a
+     * clean no-op. A `MaybeRefOrGetter` so a live reactive flag is honored per-call.
+     * Default `true`.
+     */
+    enabled?: MaybeRefOrGetter<boolean>;
+}
+export interface UseHapticReturn {
+    /**
+     * The feature-detect — `true` iff `navigator.vibrate` is a callable function (false on
+     * iOS Safari + SSR + any non-vibrate engine). A consumer reads it to branch a visual
+     * fallback if it wants one.
+     */
+    readonly supported: boolean;
+    /**
+     * Fire a haptic pulse — a named `HapticPattern`, a single duration (ms), or a raw
+     * `number[]` vibrate pattern. A NO-OP when unsupported or `enabled` is falsy (so iOS
+     * Safari + SSR + an opted-out consumer get a clean no-op, never a throw). Pure
+     * imperative — fire it from inside an existing snap callback.
+     */
+    pulse: (pattern: HapticPattern | number | number[]) => void;
+}
+/**
+ * The library's ONE haptic primitive — a thin, feature-detected `navigator.vibrate`
+ * wrapper with a bounded named-pattern register. Feature-detects to a clean no-op on iOS
+ * Safari + SSR; never throws. See the module header for the no-engine / no-PRM-suppress /
+ * no-buzz rationale.
+ *
+ * @example
+ * ```ts
+ * const haptic = useHaptic({ enabled: () => props.enableHaptic })
+ * // inside an existing snap callback:
+ * onSnap(() => haptic.pulse("snap"))
+ * ```
+ */
+export declare function useHaptic(options?: UseHapticOptions): UseHapticReturn;

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

@@ -0,0 +1,31 @@
+/** The rest weight (1/φ ≈ 0.618) — the centroid of the iOS-27 register triangle. */
+export declare const MOTION_WEIGHT_REST = 0.618;
+/**
+ * Fold the live velocity term into a transient `--motion-weight` boost on the
+ * driving element, and mirror the term onto `--flex-vel` (the non-inheriting live
+ * channel). Call it at an EXISTING `--stretch` write-site with the morphing element
+ * + the saturating velocity term `useLiquidFlex` already computed.
+ *
+ * @param el       the driving element (the same element the cap getter reads weight off)
+ * @param flexVel  the saturating velocity term `tanh(|ṫ|·k) ∈ [0,1]` (the `--flex-vel` value)
+ */
+export declare function writeVelocityWeight(el: HTMLElement | null | undefined, flexVel: number): void;
+/**
+ * The SITE-LOCAL effective-cap derivation (the spike-corrected mechanism). Reads
+ * BOTH the live `--motion-weight` AND the per-velocity boost off the consuming
+ * element, scaling the EXISTING cap token toward 1.0 as weight→0 and toward its
+ * shipped rest value at weight 0.618. NO `--*-stretch-k` coefficient cohort — the
+ * cap token IS the single source, read directly with a `(weight/0.618)` factor:
+ *
+ *   `cap_eff = 1 + (cap_token − 1) · (weight + (1 − weight)·flexVel) / 0.618`
+ *
+ * so `cap_eff == cap_token` at rest weight 0.618 + zero velocity (the UNION fence,
+ * feel byte-identical) AND `cap_eff == 1.0` at weight 0 (the PRM/observer fence).
+ * The `(1 − weight)·flexVel` term lets a fast travel transiently deepen the cap
+ * even before the weight write has propagated (the morph-more-on-move read).
+ *
+ * @param el        the consuming element (live `--motion-weight`/`--flex-vel`)
+ * @param capToken  the resolved `--*-max-stretch` cap value (≥1; the shipped rest cap)
+ * @returns the effective cap to hand `useLiquidFlex` (≥1)
+ */
+export declare function effectiveCap(el: HTMLElement | null | undefined, capToken: number): number;

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

@@ -6,6 +6,8 @@ export * from "./useLiquidPress";
 export * from "./useDragMorph";
 export * from "./useLiquidReveal";
 export * from "./useDockCtaReceive";
+export * from "./useBloomUp";
+export * from "./useCelebrationBurst";
 export * from "./useNumericTransition";
 export * from "./useAnimatedNumber";
 export * from "./useAnimatedNumberMap";

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" | "press";
+export type SpringPresetName = "smooth" | "snappy" | "bouncy" | "gentle" | "dock" | "press" | "timeline-head" | "timeline-fill" | "timeline-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. */
@@ -30,22 +30,21 @@ export interface SpringPresetRow {
  *   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.
+ * BD.W-ANIM-IOS27-TUNE — the GLOBAL re-calibration toward the iOS-27
+ * weighty-gooey-inertial pole (USER law: "SMOOTH, CONTROLLED, INERTIA, AUDACIOUS;
+ * NO overly tight and springy; MORPH MORE on move"). ALL SIX rows are re-tuned in
+ * lockstep toward lower stiffness (longer `response` → inertia/weight) + higher
+ * through-body damping toward critically-damped-with-a-TOUCH-of-overshoot (kill the
+ * pointed flick) + longer settle (the flowing arrival) — WHILE keeping the perceptual
+ * arrival AUDACIOUS (t90 mid-clock for smooth/snappy/press; bouncy/dock arrive earlier
+ * via the overshoot carry = the FLOWING-mass read). There are NO byte-frozen KEEPS any
+ * more (the BC.W-SPRING-EASE surgical KEEP fence is RETIRED). The invariant fences:
+ *   · every overshoot ∈ [0%,10%] — the "touch of overshoot" band; the OLD pointed
+ *     bouncy 12.6% / dock 10.7% are RETIRED (>10% is the "too springy" defect).
+ *   · every NON-gentle settle LENGTHENS vs the pre-BD 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).
  */
 export declare const SPRING_PRESETS: readonly SpringPresetRow[];
 /** Lookup one preset row by name (used by `MOTION_CURVES` spring rows). */

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

@@ -1,2 +1,2 @@
-export { NumericAnimation, SpringProgress, SmoothProgress, Sequence, Timeline, ManualTimeline, RAFPlayback, ScrollTimeline, createNativeTimeline, flip, flipShared, ElementMorph, drag, Draggable, decay, decayRest, stagger, springTimingFunction, springLinearStops, toEasing, resolveEasing, AnimationOptionError, UnknownEasingError, loadAnimationEngine, } from "@mkbabb/keyframes.js";
-export type { Easing, TimingFunction, TimingFunctionNames, SpringProgressOptions, SpringFrameCallback, SpringSubscriber, SpringLinearStopsOptions, SpringTimingFunctionOptions, SmoothProgressOptions, NumericAnimationOptions, NumericFrameCallback, SequenceEntry, SequenceOptions, SequencePosition, TimelineOptions, NativeTimelineSpec, RAFPlaybackOptions, Tickable, FlipOptions, ElementMorphOptions, MorphRect, DragOptions, DragAxis, DragSubscriber, DecayOptions, DecaySample, StaggerFn, StaggerOptions, StaggerOrigin, AnimationEngine, AnimationOptions, AnimationFrame, AnimateOptions, InputAnimationOptions, ResolvedKeyframes, Vars, } from "@mkbabb/keyframes.js";
+export { NumericAnimation, SpringProgress, SmoothProgress, Oscillator, Sequence, Timeline, ManualTimeline, RAFPlayback, KeyframesScrollTimeline, createNativeTimeline, flip, flipShared, ElementMorph, drag, drag2D, Draggable, decay, decayRest, reseatToSpring, probeVelocity, reducedMotionScale, waveformValue, warmEngine, stagger, springTimingFunction, springLinearStops, toEasing, resolveEasing, AnimationOptionError, UnknownEasingError, loadAnimationEngine, } from "@mkbabb/keyframes.js";
+export type { Easing, TimingFunction, TimingFunctionNames, SpringProgressOptions, SpringFrameCallback, SpringSubscriber, SpringLinearStopsOptions, SpringTimingFunctionOptions, SmoothProgressOptions, NumericAnimationOptions, NumericFrameCallback, SequenceEntry, SequenceOptions, SequencePosition, TimelineOptions, NativeTimelineSpec, RAFPlaybackOptions, Tickable, FlipOptions, ElementMorphOptions, MorphRect, DragOptions, DragAxis, DragSubscriber, DecayOptions, DecaySample, StaggerFn, StaggerOptions, StaggerOrigin, AnimationEngine, AnimationOptions, AnimationFrame, InputAnimationOptions, ResolvedKeyframes, Vars, } from "@mkbabb/keyframes.js";

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

@@ -0,0 +1,97 @@
+import { type Ref } from "vue";
+import { type SpringPresetName } from "./springPresets";
+/** The bloom spring register — `snappy` (the quick shared-element default) or `bouncy`
+ *  (the emphatic large-surface bloom). A subset of the named `SPRING_PRESETS` rows,
+ *  matching `useLiquidReveal`/`useDockCtaReceive` so the bloom family reads as ONE. */
+export type BloomUpPreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+export interface UseBloomUpOptions {
+    /** The spring register (default `snappy`). */
+    preset?: BloomUpPreset;
+    /** The starting filter-blur radius in px on the destination (the decongest start). Default 4. */
+    blur?: number;
+    /**
+     * The dominant source hue the FIELD warms toward — a complete `<color>` (an
+     * `oklch()`/`#hex`/named). When omitted, the leaf reads `--glass-ambient-hue` off
+     * the SOURCE element's computed style (the BE.W-AMBIENT-TINT convergence — the
+     * album card carries its own dominant hue). A `transparent`/empty read is the
+     * neutral no-op (the field tints nothing — a gray source warms nothing).
+     */
+    fieldHue?: string;
+    /**
+     * The FIELD CONTAINER the 4th color channel writes onto — the destination's
+     * ancestor field (the DockStage / now-playing field). When omitted, the leaf walks
+     * up from `destRef` to the nearest ancestor carrying `[data-glass-field]` (the
+     * field-marker contract), falling back to `destRef.parentElement`. The hue + the
+     * ramped strength are written HERE, never on the blooming surface (the
+     * compositor-only floor de-risk).
+     */
+    field?: Ref<HTMLElement | null>;
+    /**
+     * The bounded ambient-strength target the field ramps to (a percentage, `0..8`).
+     * Default 8 (the AMBIENT-TINT ceiling — the loudest sub-perceptual warm). Clamped
+     * to `[0, 8]` so a consumer can never flood the field past the warm-cream identity.
+     */
+    fieldStrength?: number;
+    /** Honor `prefers-reduced-motion: reduce` (snap surface to settled, land hue instantly). Default true. */
+    respectReducedMotion?: boolean;
+    /**
+     * Auto-prime the destination the moment it mounts — seat it at the collapsed/hidden
+     * initial state (opacity 0 + the source-FLIP transform) BEFORE the browser paints,
+     * so a freshly-`v-if`-mounted dest never flashes its full-size frame before `bloom()`
+     * fires. A `watch(dest, …, { flush: "pre" })` runs in the SAME tick the element
+     * mounts. Default `true` — the no-flash floor; pass `false` to opt a consumer that
+     * owns its own initial-state seating out. `prime()` is the explicit imperative twin.
+     */
+    autoPrime?: boolean;
+    /**
+     * Fired ONCE when the bloom has settled (the hand-off — the consumer marks the
+     * bloom complete: hides the source, owns the destination). Fires on the animation
+     * settle AND on the PRM/no-rAF snap (the bloom always completes).
+     */
+    onBloomed?: () => void;
+}
+export interface UseBloomUpReturn {
+    /**
+     * Bloom the destination up from the source's rect. Idempotent per call — measures
+     * the source + destination rects fresh, drives the FLIP inversion spring 1→0 on the
+     * surface AND ramps the field hue 0→target. A no-op if the destination element is
+     * not yet mounted (no `onBloomed`).
+     */
+    bloom: () => void;
+    /**
+     * Clear the bloom transform (restore the destination to its settled identity,
+     * opacity 1) AND release the field hue (strength → 0). The abort/reset seam —
+     * cancels any in-flight bloom; does NOT fire `onBloomed`.
+     */
+    reset: () => void;
+    /**
+     * Seat the destination at its collapsed/hidden initial state (opacity 0 + the
+     * source-FLIP transform) WITHOUT animating — so a freshly-mounted dest shows
+     * NOTHING until `bloom()` fires (the no-mount-flash seam). Idempotent; a no-op if
+     * the dest is not yet mounted. The auto-prime (`autoPrime`, default on) calls this
+     * for the consumer; `prime()` is the explicit imperative twin.
+     */
+    prime: () => void;
+    /** The reactive bloom state — `true` while a bloom is in flight, `false` at rest. */
+    blooming: Readonly<Ref<boolean>>;
+}
+/**
+ * The iOS-27 shared-element bloom with the 4th color channel. Composes the kf
+ * `ElementMorph` + `springTimingFunction` into the three-channel geometry bloom on the
+ * DESTINATION surface (scale+fade+blur-decongest from the SOURCE's origin) PLUS a 4th
+ * color channel on the destination FIELD (the field warms to the source's hue on the
+ * SAME spring curve). Compositor-only on the surface + Safari-safe + PRM-snap. See the
+ * module header for the REUSE + the FLIP inversion + the channel split.
+ *
+ * @example
+ * ```ts
+ * const { bloom, reset, blooming } = useBloomUp(albumCardRef, fullscreenRef, {
+ *   preset: "bouncy",
+ *   fieldHue: albumDominantHue, // or omit to read --glass-ambient-hue off the card
+ *   field: nowPlayingFieldRef,
+ *   onBloomed: () => (fullscreenOpen.value = true),
+ * })
+ * function onTapAlbum() { bloom() }
+ * ```
+ */
+export declare function useBloomUp(source: Ref<HTMLElement | null>, dest: Ref<HTMLElement | null>, options?: UseBloomUpOptions): UseBloomUpReturn;