@mkbabb/glass-ui 6.0.0 → 8.0.0

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

@@ -1,6 +1,5 @@
 export type CanvasSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
-import { sizeBacking, type BackingSize, type DprPolicy } from "./backingSize";
-export { sizeBacking };
+import { type BackingSize, type DprPolicy } from "./backingSize.js";
 export type { BackingSize, DprPolicy };
 /** The per-frame hooks a backend's `buildContext` returns to the lifecycle core. */
 export interface CanvasFrameHooks {
@@ -19,38 +18,26 @@ export interface CanvasLifecycleOptions {
     respectReducedMotion?: boolean;
     /**
      * Acquire the backend context + build the per-frame hooks. Called on `arm()` AND
-     * on a backend context-restore. Throws on backend-unavailable / setup failure.
+     * on a backend context-restore. Throws on backend-unavailable, setup failure.
      */
     buildContext: () => CanvasFrameHooks;
     /**
      * Upload the backing geometry to the viewport/uniforms.
      *
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G1): the leaf 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. When the leaf owns sizing (`dprPolicy`
-     * provided) the buffer is already correct on entry — the consumer body is UPLOAD-ONLY,
-     * shrinking to `gl.viewport(0,0,s.w,s.h)` / `uploadResolution` (a WGPU swap-chain leg
-     * is a no-op — it auto-resizes to the backing the leaf set).
-     *
-     * BG.W-VIZ-RESIZE-ADOPT: every GL/WGPU procedural viz has HARD-ADOPTED the leaf sizer
-     * (all 9 pass `dprPolicy` + read `s` upload-only; ZERO viz self-measures the backing —
-     * `proof:viz` enforces `backing == round(gBCR × dpr)` with no surviving `canvas.width =`
-     * self-size). The arg stays optional ONLY for the un-migrated `useCanvas2D` leg + the
-     * substrate contract tests; dropping the `?` (the flag-day) is booked to their adopt.
+     * The leaf measures and 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 buffer is ALWAYS correct on entry — the consumer body
+     * is UPLOAD-ONLY, shrinking to `gl.viewport(0,0,s.w,s.h)`/`uploadResolution` (a WGPU
+     * swap-chain leg is a no-op — it auto-resizes to the backing the leaf set).
      */
-    resize: (s?: BackingSize) => void;
+    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.
-     *
-     * BG.W-VIZ-RESIZE-ADOPT: the GL/WGPU substrate (the `createGpuSubstrate` picker + both
-     * legs) is UNIVERSALLY on this seam now — every one of the 9 procedural viz threads its
-     * budget DPR here (`resolveBudgetDpr` / `resolveAuroraWashDpr`), so the STANDARD is
-     * `dprPolicy`-present; the ABSENT branch survives only for `useCanvas2D`.
+     * The consumer's DPR policy, handed to the leaf's `sizeBacking`. REQUIRED: the leaf
+     * owns backing-store measurement and sizing, and the live `BackingSize` rides every
+     * `resize` call. There is no self-measuring arm — a caller that cannot state a DPR
+     * policy cannot state a backing size either.
      */
-    dprPolicy?: DprPolicy;
+    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
@@ -59,8 +46,12 @@ export interface CanvasLifecycleOptions {
      */
     bindContextEvents?: (rebuild: () => void, markContextLost: () => void) => void;
     unbindContextEvents?: () => void;
+    /** Project the lifecycle's existing loss/rebuild state without creating a second clock. */
+    onContextStateChange?: (state: "lost" | "restored") => void;
+    /** Surface a failed restore or a bounded context-loss storm to the owner. */
+    onContextError?: (error: Error) => void;
     /**
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G3) — compose the IntersectionObserver park detector
+     * 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
@@ -73,16 +64,16 @@ export interface CanvasLifecycleOptions {
      * 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.
+     * (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). */
+    /** `rootMargin` for the leaf-composed IO park. Default `"256px"` for pre-warm. */
     intersectionRootMargin?: string;
     /**
-     * BG.W-VIZ-REVEAL-BLOOM — the one-shot cold-first-VISIBLE entrance bloom. When set,
+     * the one-shot cold-first-VISIBLE entrance bloom. When set,
      * the leaf sets a one-shot `data-substrate-reveal` ATTRIBUTE on the canvas at the
      * moment it FIRST becomes visible (a dedicated one-shot IntersectionObserver — NOT
-     * at `arm()`, which a content-skipped / below-fold viz would burn on an invisible
+     * at `arm()`, which a content-skipped, below-fold viz would burn on an invisible
      * paint). The CANVAS-targeted CSS `@keyframes substrate-reveal-bloom` (`viz-reveal.css`)
      * then ramps `filter: brightness()/saturate()` from a dim floor, OVERSHOOTS past 1.0
      * on the `--ease-cartoon-punch` linear() curve (the EFFECTS-channel sanctioned
@@ -99,11 +90,11 @@ export interface CanvasLifecycleOptions {
 export interface CanvasLifecycleHandle {
     arm: () => void;
     /**
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing store + start the leaf RO
+     * Size the backing store and 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).
+     * no-op once `arm()` has run it.
      */
     presize: () => void;
     suspend: (reason?: CanvasSuspendReason) => void;
@@ -116,7 +107,7 @@ export interface CanvasLifecycleHandle {
     readonly running: boolean;
     readonly reducedMotion: boolean;
     /**
-     * BC.W-SAFARI-WEBGL — the circuit-breaker has tripped: the surface lost-and-restored
+     * 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.

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

@@ -1,36 +1,20 @@
-import { type BackingSize, type DprPolicy } from "./createCanvasLifecycle";
-export type { BackingSize, DprPolicy } from "./createCanvasLifecycle";
+import { type BackingSize, type DprPolicy } from "./createCanvasLifecycle.js";
+export type { BackingSize, DprPolicy } from "./createCanvasLifecycle.js";
 /**
- * The ONE `getContext("webgl2")` capability probe (BB.W-CI-GREEN — the
- * single-bootstrap rule). A throwaway WebGL2 context is created here, in the
- * substrate (the sole webgl2-creating module per `proof:webgl-substrate-single`),
- * so a consumer feature-detecting WebGL2 / reading the unmasked renderer string
+ * The one `getContext("webgl2")` capability probe. A throwaway WebGL2 context is
+ * created here in the substrate,
+ * so a consumer feature-detecting WebGL2, reading the unmasked renderer string
  * NEVER creates a second context of its own. The probe canvas is detached, its
  * context released via `WEBGL_lose_context` under the per-page context cap; the
  * read is one-shot (a mount-time device-tier decision, not a reactive one).
  *
  * Returns the lower-cased `UNMASKED_RENDERER_WEBGL` string (e.g.
- * `"google swiftshader"`), or `null` when WebGL2 / the debug-renderer extension
+ * `"google swiftshader"`), or `null` when WebGL2, the debug-renderer extension
  * is unavailable or the probe throws — the caller treats `null` as "cannot prove"
  * (the conservative-but-lossy fall-back). SSR-safe (returns `null` with no
  * `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 {
@@ -39,13 +23,11 @@ export interface WebGLCanvasFrame {
     /** Demand-gate: is there live motion to render next frame? `false` → park. */
     shouldContinue: () => boolean;
     /**
-     * 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.
+     * Upload the backing geometry to the viewport/uniforms. The leaf MEASURES + sizes
+     * the backing and passes the live `BackingSize` here, so the consumer body is
+     * upload-only (`gl.viewport(0,0,s.w,s.h)`).
      */
-    resize: (s?: BackingSize) => void;
+    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. */
@@ -66,37 +48,40 @@ export interface WebGLCanvasOptions {
      */
     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).
+     * The consumer's DPR policy. REQUIRED: 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)`.
      */
-    dprPolicy?: DprPolicy;
-    /** Compose the leaf IO park (G3). Default `false` (opt-in; see createCanvasLifecycle). */
+    dprPolicy: DprPolicy;
+    /** Compose the leaf IO park. Default `false`; see createCanvasLifecycle. */
     composeIntersectionPark?: boolean;
-    /** `rootMargin` for the leaf IO park (G3). */
+    /** `rootMargin` for the leaf IO park. */
     intersectionRootMargin?: string;
-    /** Fire the one-shot cold-first-VISIBLE entrance bloom (BG.W-VIZ-REVEAL-BLOOM — the `data-substrate-reveal` attr). Default `false`. */
+    /** Fire the one-shot cold-first-visible entrance bloom via `data-substrate-reveal`. Default `false`. */
     revealBloom?: boolean;
     /**
      * Build the program + geometry on a fresh context. Called on `arm()` AND on
      * every `webglcontextrestored`. Returns the per-frame hooks.
      */
     setup: (gl: WebGL2RenderingContext) => WebGLCanvasFrame;
+    /** Internal lifecycle projection used by the shared renderer-status owner. */
+    onContextStateChange?: (state: "lost" | "restored") => void;
+    /** Surface a failed context restore or a bounded loss storm. */
+    onContextError?: (error: Error) => void;
 }
 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). */
+    /** Size the backing and start the leaf RO synchronously before acquire. */
     presize: () => void;
     suspend: (reason?: WebGLSuspendReason) => void;
     resume: (reason?: WebGLSuspendReason) => void;
     /** Re-arm a parked loop (a setter that re-introduced motion calls this). */
     wake: () => void;
-    /** Draw one frame at `timeSec` out-of-loop (capture / thumbnail). */
+    /** Draw one frame at `timeSec` out-of-loop (capture, thumbnail). */
     renderAt: (timeSec: number) => void;
     dispose: () => void;
-    /** The live context (null before arm / after dispose / mid-loss). */
+    /** The live context (null before arm, after dispose, mid-loss). */
     readonly gl: WebGL2RenderingContext | null;
     /**
      * The live `prefers-reduced-motion: reduce` state. The shared lifecycle core

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

@@ -1,7 +1,7 @@
-import type { CanvasSuspendReason } from "./createCanvasLifecycle";
+import type { CanvasSuspendReason } from "./createCanvasLifecycle.js";
 /**
  * The scheduler seam the observers drive. Each observer writes a DISTINCT suspend
- * reason (`tab-hidden` / `off-screen` / `off-screen-io`) — the one-writer-per-reason
+ * reason (`tab-hidden`, `off-screen`, `off-screen-io`) — the one-writer-per-reason
  * invariant — and reads the scheduler's live `armed`/`hooks`/`disposed`/`reducedMotion`
  * state through the getters (never a shared closure var, so the two files stay decoupled).
  */
@@ -21,7 +21,7 @@ export interface CanvasVisibilityDeps {
 }
 export interface CanvasVisibility {
     /**
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing store + start the leaf RO
+     * Size the backing store and start the leaf RO
      * SYNCHRONOUSLY, decoupled from the (async) context acquire. Idempotent: a no-op
      * once it has run. The WebGPU backend calls this BEFORE its async device request so
      * the canvas is sharp from frame 0 while the device resolves.
@@ -36,7 +36,6 @@ export interface CanvasVisibility {
 }
 /**
  * The canvas visibility observers. Constructing this binds the tab-visibility owner +
- * seeds the initial `document.hidden` suspend (the pre-arm seed), matching the prior
- * inline behaviour byte-for-byte.
+ * seeds the initial `document.hidden` suspend (the pre-arm seed).
  */
 export declare function createCanvasVisibility(deps: CanvasVisibilityDeps): CanvasVisibility;

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

@@ -1,10 +1,9 @@
-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";
-import { type RendererStatus } from "./rendererStatus";
-export type { RendererStatus, RendererEngine } from "./rendererStatus";
-export { supportsWebGPU };
+import { type WebGLCanvasFrame, type WebGLCanvasOptions } from "../webgl/useWebGLCanvas.js";
+import type { DprPolicy } from "../webgl/createCanvasLifecycle.js";
+export type { BackingSize, DprPolicy } from "../webgl/createCanvasLifecycle.js";
+import { type WebGPUCanvasFrame, type WebGPUCanvasOptions } from "./useWebGPUCanvas.js";
+import { type RendererStatus } from "./rendererStatus.js";
+export type { RendererStatus, RendererEngine } from "./rendererStatus.js";
 /** Which backend the picker resolved. */
 export type GpuBackend = "webgpu" | "webgl2";
 export interface GpuSubstrateOptions {
@@ -20,26 +19,24 @@ export interface GpuSubstrateOptions {
     /** 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
+     * The consumer's DPR policy: a flat multiplier
+     * or a box-aware resolver). REQUIRED: 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.
+     * WebGPU path), handing the live `BackingSize` to each `setup`'s `resize(s)`.
      */
-    dprPolicy?: DprPolicy;
+    dprPolicy: DprPolicy;
     /**
-     * G3 — compose the leaf IntersectionObserver park (a consumer inherits the
+     * Compose the leaf IntersectionObserver park so 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"`. */
+    /** `rootMargin` for the leaf IO park. Default `"256px"`. */
     intersectionRootMargin?: string;
     /**
-     * BG.W-VIZ-REVEAL-BLOOM — fire the one-shot cold-first-VISIBLE entrance bloom (a
+     * fire the one-shot cold-first-VISIBLE entrance bloom (a
      * one-shot `data-substrate-reveal` attr on the canvas the CSS `@keyframes
      * substrate-reveal-bloom` reads to ramp `filter: brightness()` from a dim floor,
      * overshoot past 1.0 on `--ease-cartoon-punch`, then settle). Fires at first-visible,
@@ -53,7 +50,7 @@ export interface GpuSubstrateOptions {
     deviceDescriptor?: WebGPUCanvasOptions["deviceDescriptor"];
     /** WebGL2 `getContext("webgl2", …)` attributes. */
     contextAttrs?: WebGLCanvasOptions["contextAttrs"];
-    /** Surface a device-init / validation failure (the WebGPU path). */
+    /** 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
@@ -88,12 +85,12 @@ export interface GpuSubstrateHandle {
     /** 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
+     * Size the backing store and 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).
+     * the awaited `armAsync`). Idempotent — a no-op once the backing is already sized.
      */
     presize: () => void;
     suspend: (reason?: "tab-hidden" | "off-screen" | "off-screen-io" | "manual") => void;
@@ -107,10 +104,10 @@ export interface GpuSubstrateHandle {
  * Pick the backend + return the uniform handle. WebGPU-first (`supportsWebGPU()` AND a
  * `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.
+ * WebGPU init and falls to WebGL2 only for recognized acquisition failures that occur
+ * before a WebGPU context is acquired. Setup/pipeline validation stays an explicit
+ * WebGPU error. The WebGL2 leaf is built lazily, so a Baseline host pays no fallback
+ * context cost.
  */
 export declare function createGpuSubstrate(canvas: HTMLCanvasElement, options: GpuSubstrateOptions): GpuSubstrateHandle;
 export type { WebGPUCanvasFrame, WebGLCanvasFrame };

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

@@ -1,12 +1,11 @@
-export type { BackingSize, DprPolicy } from "../webgl/createCanvasLifecycle";
-export { WebGPUInitError, WEBGPU_ACQUIRE_TIMEOUT_MS } from "./webgpuDevice";
-export type { WebGPUSuspendReason, WebGPUCanvasFrame, WebGPUCanvasOptions, WebGPUCanvasHandle, } from "./webgpuCanvasTypes";
-import type { WebGPUCanvasOptions, WebGPUCanvasHandle } from "./webgpuCanvasTypes";
+export type { BackingSize, DprPolicy } from "../webgl/createCanvasLifecycle.js";
+export type { WebGPUSuspendReason, WebGPUCanvasFrame, WebGPUCanvasOptions, WebGPUCanvasHandle, } from "./webgpuCanvasTypes.js";
+import type { WebGPUCanvasOptions, WebGPUCanvasHandle } from "./webgpuCanvasTypes.js";
 /**
  * The ONE `navigator.gpu` capability probe (the single-bootstrap rule — mirrors
  * `probeWebGL2Renderer`). SSR-safe (returns `false` with no `navigator`). The picker
  * (`useGpuSubstrate`) reads it to decide the backend; a consumer NEVER touches
- * `navigator.gpu` directly (it composes the substrate — `proof:gpu-substrate-single`
+ * `navigator.gpu` directly because it composes the substrate
  * clause A reds a direct call).
  */
 export declare function supportsWebGPU(): boolean;

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

@@ -1,4 +1,4 @@
-import type { BackingSize, DprPolicy } from "../webgl/createCanvasLifecycle";
+import type { BackingSize, DprPolicy } from "../webgl/createCanvasLifecycle.js";
 export type WebGPUSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
 /**
  * The per-frame hooks a consumer's `setup(device, context, format)` returns. The
@@ -15,12 +15,11 @@ export interface WebGPUCanvasFrame {
     /** Demand-gate: is there live motion to render next frame? `false` → park. */
     shouldContinue: () => boolean;
     /**
-     * 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.
+     * Upload the backing geometry: the leaf sizes the backing + passes the live
+     * `BackingSize` here (the WGSL swap chain auto-tracks the backing, so the consumer
+     * body is an aspect upload).
      */
-    resize: (s?: BackingSize) => void;
+    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. */
@@ -43,31 +42,32 @@ export interface WebGPUCanvasOptions {
      */
     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).
+     * The consumer's DPR policy. REQUIRED: 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)`.
      */
-    dprPolicy?: DprPolicy;
-    /** Compose the leaf IO park (G3). Default `false` (opt-in; see createCanvasLifecycle). */
+    dprPolicy: DprPolicy;
+    /** Compose the leaf IO park. Default `false`; see createCanvasLifecycle. */
     composeIntersectionPark?: boolean;
-    /** `rootMargin` for the leaf IO park (G3). */
+    /** `rootMargin` for the leaf IO park. */
     intersectionRootMargin?: string;
-    /** Fire the one-shot cold-first-VISIBLE entrance bloom (BG.W-VIZ-REVEAL-BLOOM — the `data-substrate-reveal` attr). Default `false`. */
+    /** Fire the one-shot cold-first-visible entrance bloom via `data-substrate-reveal`. 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.
      */
     setup: (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;
-    /** Surface a device-init / validation failure (no WebGPU adapter, a `setup` throw). */
+    /** Internal lifecycle projection used by the shared renderer-status owner. */
+    onContextStateChange?: (state: "lost" | "restored") => void;
+    /** Surface a device-init, validation failure (no WebGPU adapter, a `setup` throw). */
     onInitError?: (error: unknown) => void;
 }
 export interface WebGPUCanvasHandle {
     /**
      * Run the expensive ASYNC init (adapter + device + context.configure + `setup`)
      * THEN arm the loop. Resolves once armed (or rejects-via-`onInitError` on a
-     * device-unavailable / `setup` failure). Idempotent; a no-op post-dispose.
+     * device-unavailable, `setup` failure). Idempotent; a no-op post-dispose.
      */
     armAsync: () => Promise<void>;
     /**
@@ -76,16 +76,16 @@ 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. */
+    /** Size the backing and start the leaf RO synchronously before 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). */
     wake: () => void;
-    /** Draw one frame at `timeSec` out-of-loop (capture / thumbnail). */
+    /** Draw one frame at `timeSec` out-of-loop (capture, thumbnail). */
     renderAt: (timeSec: number) => void;
     dispose: () => void;
-    /** The live device (null before armAsync / after dispose / mid-loss). */
+    /** The live device (null before armAsync, after dispose, mid-loss). */
     readonly device: GPUDevice | null;
     /** Runtime-derived adapter identity, available once acquisition succeeds. */
     readonly adapterClass: string;

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

@@ -1,6 +1,6 @@
 /**
- * The recognizable WebGPU INIT-FAILURE signal (BC.W-WEBGPU-EVERYWHERE — the D8/D8'
- * close). A no-adapter host (`requestAdapter()` returns null), a `requestDevice()`
+ * Recognizable WebGPU initialization-failure signal. 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
@@ -13,13 +13,12 @@ export declare class WebGPUInitError extends Error {
     constructor(kind: WebGPUInitError["kind"], message: string, cause?: unknown);
 }
 /**
- * Detect a SOFTWARE / CPU WebGPU adapter (SwiftShader / llvmpipe / the Microsoft
+ * 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).
+ * WebGPU twin of the `renderMode.ts` WebGL software-raster guard.
  *
- * 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()`
+ * WHY this forces the WebGL2 net (the 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
@@ -28,7 +27,7 @@ export declare class WebGPUInitError extends Error {
  * 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
+ * `armAsync` try/catch falls to the WebGL2 net — exactly the silent
  * degrade, never the invalid-pipeline flood.
  *
  * The signal is the `isFallbackAdapter` spec flag (a UA sets it on a software fallback —
@@ -40,23 +39,6 @@ export declare class WebGPUInitError extends Error {
  * across UAs); a throwing read is morally "cannot prove software" → keep WebGPU.
  */
 export declare function isSoftwareWebGPUAdapter(adapter: GPUAdapter): boolean;
-/**
- * The bound on the adapter/device acquisition (ms). The adapter/device request 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 device request 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 the ceiling is hit at most
- * ONCE per page, not N-times-per-canvas — a single ≤6s race, never N.
- *
- * BG.W-COLOCATE — carved into this device-acquisition-support leaf beside the typed
- * failure signal it throws (ratchet-drain #4). The substrate re-imports + re-exports it.
- */
-export declare const WEBGPU_ACQUIRE_TIMEOUT_MS = 6000;
 /**
  * Race a WebGPU acquisition promise against a timeout. On a hang the timeout wins and
  * rejects with the recognized typed `acquire-timeout` signal (the picker falls to the
@@ -67,6 +49,6 @@ export declare const WEBGPU_ACQUIRE_TIMEOUT_MS = 6000;
  *
  * `label` is the acquisition-step name used in the timeout message (the caller in the
  * substrate passes the concrete step name — the bootstrap tokens stay in the substrate
- * per proof:gpu-substrate-single clause A).
+ * per  clause A).
  */
 export declare function withAcquireTimeout<T>(promise: Promise<T>, label: string): Promise<T>;

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

@@ -1 +1 @@
-export * from "./useKeyboardShortcuts";
+export * from "./useKeyboardShortcuts.js";

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

@@ -0,0 +1,2 @@
+import type { ComponentPublicInstance } from "vue";
+export declare function asElement(value: HTMLElement | ComponentPublicInstance | null | undefined): HTMLElement | null;

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

@@ -0,0 +1,25 @@
+/**
+ * Shared damping factors for live numeric motion.
+ *
+ * These values are the app-level tuning glass-ui owns for the generic motion
+ * contract.
+ */
+export declare const DAMPING: {
+    readonly canvasNeedle: 0.08;
+    readonly domHero: 0.12;
+    readonly domPill: 0.14;
+    readonly domProgress: 0.18;
+};
+/** Shared absolute snap thresholds for live numeric motion. */
+export declare const SNAP_THRESHOLD: {
+    readonly canvas: 0.002;
+    readonly dom: 0.05;
+    readonly domProgress: 0.5;
+};
+/**
+ * One frame at 60fps, in milliseconds. The display's own beat, which is why it is
+ * shared rather than derived twice: an integrator's first-frame `dt` (before there is
+ * a previous timestamp to difference) and a "this outlives that by N frames" floor are
+ * the same number for the same reason. Anything that means "one frame" reads this.
+ */
+export declare const FRAME_MS: number;

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

@@ -1,24 +1,21 @@
-export * from "../constants";
-export * from "../useStaggerReveal";
-export * from "../useStagger";
-export * from "../useScrollProgress";
-export * from "../useRAFLoop";
-export * from "../useIntersectionPause";
-export * from "../useYieldToMain";
-export * from "../usePrioritizedTask";
-export * from "../useViewTransition";
-export * from "../vReveal";
-export * from "../useTextHighlight";
-export * from "../useLiquidFlex";
-export * from "../useLeadTrail";
-export * from "../useGooMorph";
-export * from "../morphSignatures";
-export * from "../usePointerVelocityField";
-export * from "../useRoutePointer";
-export * from "../pointerFieldMappings";
-export * from "../useCharStagger";
-export * from "../useScrollTrigger";
-export * from "../useScrollChrome";
-export * from "./writeVelocityWeight";
-export * from "../useSelectionIndicator";
-export * from "../useSelectionGroup";
+export * from "./constants.js";
+export * from "../reveal/useStagger.js";
+export * from "../scroll/useScrollProgress.js";
+export * from "./useRAFLoop.js";
+export * from "./useReducedMotion.js";
+export * from "./useIntersectionPause.js";
+export * from "./useYieldToMain.js";
+export * from "./useViewTransition.js";
+export * from "../route/routeGrammar.js";
+export * from "../route/useRouteTransition.js";
+export * from "../dissolve/dissolveGrammar.js";
+export * from "../reveal/vReveal.js";
+export * from "../spring/useLiquidFlex.js";
+export * from "../pointer/usePointerVelocityField.js";
+export * from "../pointer/useRoutePointer.js";
+export * from "../pointer/pointerFieldMappings.js";
+export * from "../scroll/useScrollTrigger.js";
+export * from "../scroll/useScrollChrome.js";
+export * from "./writeVelocityWeight.js";
+export * from "../morph/useSelectionIndicator.js";
+export * from "../morph/useSelectionGroup.js";

package/dist/composables/motion/{motionTempo.d.ts → core/motionTempo.d.ts}

@@ -1,5 +1,3 @@
-/** The identity tempo — no time scaling (the `@property` initial-value). */
-export declare const MOTION_TEMPO_IDENTITY = 1;
 /**
  * Read the effective `--motion-tempo` off `el` (or `:root` when omitted). Returns a
  * positive multiplier (the identity `1` off-DOM, on a malformed value, or on any

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

@@ -0,0 +1,5 @@
+import { type Ref } from "vue";
+/** Read the current OS preference without subscribing (SSR-safe). */
+export declare function readReducedMotion(): boolean;
+/** Share one reactive OS preference and one MediaQueryList listener. */
+export declare function useReducedMotion(): Readonly<Ref<boolean>>;