@mkbabb/glass-ui 4.0.1 → 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;
@@ -41,5 +134,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/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, 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";
+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. */
@@ -24,20 +52,46 @@ 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;
+    /**
+     * 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;
@@ -47,8 +101,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,6 @@
+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
  * `probeWebGL2Renderer`). SSR-safe (returns `false` with no `navigator`). The picker
@@ -6,6 +9,31 @@
  * 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
@@ -21,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. */
@@ -44,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.
@@ -65,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

@@ -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" | "acquire-timeout";
+    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,4 +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/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" | "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. */
@@ -27,6 +27,24 @@ 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, ζ).
+ *
+ * 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";