@mkbabb/glass-ui 4.2.0 → 6.0.0

package/dist/composables/glass/webgl/shaders/glass-refract.glsl.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The pinned chromatic-dispersion scale — ONE source-of-truth across BOTH refraction
+ * stacks (this GLSL floor + the WGSL `glassShader.wgsl` twin). An ABSOLUTE rim-offset
+ * multiplier: `|ca| = inward · rim · uChromatic · CHROMATIC_SCALE`. Pinned here so a
+ * cross-stack drift (the 0.003/0.004/0.0045 three-way split the Tier-2 literal `0.004`
+ * carried) is impossible — the shipped WGSL twin replaces its literal with this value.
+ */
+export declare const CHROMATIC_SCALE = 0.0045;
+/** The uniform-name contract — the ONE spelling map the JS binder + the fence read. */
+export declare const GLASS_REFRACT_UNIFORMS: {
+    readonly resolution: "uResolution";
+    readonly time: "uTime";
+    readonly panelCount: "uPanelCount";
+    readonly bounds: "uBounds";
+    readonly lightPos: "uLightPos";
+    readonly blurRadius: "uBlurRadius";
+    readonly refractionStrength: "uRefractionStrength";
+    /** the fence operator — refraction=depth, hue=this absolute rim offset. */
+    readonly chromatic: "uChromatic";
+    readonly metalStrength: "uMetalStrength";
+    readonly valveKnee: "uValveKnee";
+    readonly plateAlphaMax: "uPlateAlphaMax";
+    readonly backdrop: "uBackdrop";
+};
+/** The maximum panel count the fragment loop unrolls (mirrors Tier-2 `MAX_PANELS`). */
+export declare const GLASS_REFRACT_MAX_PANELS = 8;
+/** The full-screen-triangle vertex pass (the substrate's standard fullscreen pass). */
+export declare const GLASS_REFRACT_VERT_GLSL = "#version 300 es\nprecision highp float;\nin vec2 aPosition;\nout vec2 vUv;\nvoid main() {\n  vUv = aPosition * 0.5 + 0.5;   // [-1,1]\u00B2 clip \u2192 [0,1]\u00B2 UV\n  gl_Position = vec4(aPosition, 0.0, 1.0);\n}";
+/**
+ * The Tier-1 WebGL2 refraction fragment source. Renders the FULL ship pass: squircle
+ * depth-refraction → 3×3 blur → absolute-rim chromatic split → curl drapery sheen →
+ * ridge-local plate-alpha valve → directional specular + Fresnel rim. Splices the
+ * SHARED `CURL_FBM_GLSL` chunk (the drapery term); `potentialFBM` is defined below
+ * the uniforms per the splice-order law (the host owns the noise basis).
+ */
+export declare const GLASS_REFRACT_FRAG_GLSL = "#version 300 es\nprecision highp float;\n\n#define MAX_PANELS 8\n\nin vec2 vUv;\nout vec4 fragColor;\n\nuniform vec2  uResolution;\nuniform float uTime;\nuniform int   uPanelCount;\nuniform vec4  uBounds[MAX_PANELS];   // per-panel rect: xy = origin (UV), zw = size (UV)\nuniform vec2  uLightPos;             // key-light position (UV)\nuniform float uBlurRadius;           // blur kernel px scale\nuniform float uRefractionStrength;   // the DEPTH knob (squircle displacement)\nuniform float uChromatic;            // the fence operator \u2014 the absolute rim hue split\nuniform float uMetalStrength;        // the drapery/metal sheen composite\nuniform float uValveKnee;            // the K12 plate valve knee (structLuma threshold)\nuniform float uPlateAlphaMax;        // the alpha the valve firms to over a bright ridge\nuniform sampler2D uBackdrop;         // the field render (bound by the keystone FBO pass)\n\n// The pinned cross-stack chromatic scale (ONE source-of-truth; see CHROMATIC_SCALE).\nconst float CHROMATIC_SCALE = 0.0045;\n\n// \u2500\u2500 the ONE backdrop-read wrapper (explicit LOD; the Tier-2 sampleBG discipline) \u2500\u2500\nvec3 sampleBG(vec2 uv) {\n  return textureLod(uBackdrop, clamp(uv, 0.0, 1.0), 0.0).rgb;\n}\n\n// 4th-order squircle bevel profile: f(x)=\u2074\u221A(1-(1-x)\u2074). 0 at centre, 1 at rim, the\n// edge-concentrated slope (Snell n=1.5 thin-interior lens, NOT a uniform radial).\nfloat squircleProfile(float x) {\n  float t = 1.0 - clamp(x, 0.0, 1.0);\n  float t4 = t * t * t * t;\n  return sqrt(sqrt(max(0.0, 1.0 - t4)));\n}\n\nfloat fresnel(float cosTheta, float ior) {\n  float r0 = pow((1.0 - ior) / (1.0 + ior), 2.0);\n  return r0 + (1.0 - r0) * pow(1.0 - cosTheta, 5.0);\n}\n\nfloat luma(vec3 c) { return dot(c, vec3(0.2126, 0.7152, 0.0722)); }\n\n// scalar fbm potential \u2014 the host's noise basis, wrapped so curlFBM stays basis-\n// agnostic (the flow.glsl splice-order law). A cheap value-noise fbm for the sheen.\nfloat hash21(vec2 p) {\n  vec3 p3 = fract(vec3(p.xyx) * 0.1031);\n  p3 += dot(p3, p3.yzx + 33.33);\n  return fract((p3.x + p3.y) * p3.z);\n}\nfloat vnoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 w = f * f * (3.0 - 2.0 * f);\n  return mix(mix(hash21(i), hash21(i + vec2(1.0, 0.0)), w.x),\n             mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0, 1.0)), w.x), w.y);\n}\nfloat potentialFBM(vec2 p) {\n  float v = 0.0, a = 0.5;\n  vec2 q = p;\n  for (int i = 0; i < 3; i++) { v += a * vnoise(q); q = q * 2.02 + vec2(1.7, 9.2); a *= 0.5; }\n  return v;\n}\n\n\nconst float CURL_EPS = 0.012;\n\n// Scalar fbm potential psi \u2014 the host's noise basis, wrapped so the curl operator is\n// basis-agnostic. A host carrying its own fbm defines this as: return fbm(p);\nfloat potentialFBM(vec2 p);\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.\nvec2 curlFBM(vec2 p) {\n  float dx = potentialFBM(p + vec2(CURL_EPS, 0.0)) - potentialFBM(p - vec2(CURL_EPS, 0.0));\n  float dy = potentialFBM(p + vec2(0.0, CURL_EPS)) - potentialFBM(p - vec2(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  vec2 g = vec2(dx, dy) / (2.0 * CURL_EPS);\n  return vec2(g.y, -g.x);\n}\n\n\n// The glass material over one panel rect. Every sample flows through sampleBG.\nvec4 glassSample(vec2 uv, vec4 b) {\n  vec2 gmin = b.xy;\n  vec2 size = b.zw;\n  vec2 local = (uv - gmin) / size;      // 0..1 within panel\n  vec2 centered = local - vec2(0.5);    // -0.5..0.5\n\n  // REFRACTION = DEPTH: rim-concentrated squircle displacement (a pure UV offset).\n  float r = clamp(length(centered) * 2.0, 0.0, 1.0);\n  float prof = squircleProfile(r);\n  vec2 dir = normalize(centered + vec2(1e-5));\n  vec2 disp = dir * prof * (uRefractionStrength * 0.04 / 1.5);   // n=1.5\n  vec2 refrUv = uv + disp;\n\n  // the canonical edge-band rim mask (GLSL source-of-truth) \u2014 hue rides the RIM only.\n  vec2 toEdge = vec2(0.5) - abs(centered);       // 0 at the panel edge, 0.5 at centre\n  float edge = min(toEdge.x, toEdge.y);\n  float rim = 1.0 - smoothstep(0.0, 0.16, edge); // 1 at the rim band, 0 by 16% inward\n\n  vec2 px = 1.0 / uResolution;\n\n  // 3\u00D73 blur around the displaced UV (the demoted-blur read carrier) \u2014 explicit LOD.\n  vec3 col = vec3(0.0);\n  float wsum = 0.0;\n  for (int x = -1; x <= 1; x++) {\n    for (int y = -1; y <= 1; y++) {\n      vec2 o = vec2(float(x), float(y)) * px * max(uBlurRadius, 0.5);\n      float wgt = 1.0 - 0.25 * float(abs(x) + abs(y));\n      col += sampleBG(refrUv + o) * wgt;\n      wsum += wgt;\n    }\n  }\n  col /= wsum;\n\n  // HUE = ABSOLUTE rim offset: split R/B by ca = inward \u00B7 rim \u00B7 uChromatic \u00B7 CHROMATIC_SCALE.\n  vec2 inward = dir;\n  vec2 ca = inward * rim * uChromatic * CHROMATIC_SCALE;\n  float cr = sampleBG(refrUv + ca).r;\n  float cb = sampleBG(refrUv - ca).b;\n  col.r = mix(col.r, cr, rim * 0.6);\n  col.b = mix(col.b, cb, rim * 0.6);\n\n  // FULL PASS \u2014 the curl-drapery metal sheen (2nd curlFBM), gated by uMetalStrength.\n  vec2 flow = curlFBM(local * 3.0 + uTime * 0.05);\n  float sheen = potentialFBM(local * 5.0 + flow * 1.5 + uTime * 0.08);\n  col += vec3(smoothstep(0.55, 0.95, sheen) * uMetalStrength * 0.12);\n\n  // directional specular + Fresnel rim.\n  vec3 n = normalize(vec3(centered * 0.6, 1.0));\n  float spec = fresnel(max(n.z, 0.0), 1.5);\n  vec2 ldir = normalize(uLightPos - uv);\n  float ldot = max(dot(centered, ldir), 0.0);\n  col += vec3(spec * (0.3 + 0.7 * ldot) * 0.15);\n\n  // K12 ridge-local plate VALVE: firm the alpha toward uPlateAlphaMax over a BRIGHT\n  // ridge (AA legibility); the dim valley stays translucent so the metal reads.\n  float structLuma = luma(col);\n  float valve = smoothstep(uValveKnee, 1.0, structLuma);\n  float plateA = mix(0.9, uPlateAlphaMax, valve);\n\n  return vec4(col, plateA);\n}\n\nvoid main() {\n  vec2 uv = vUv;\n  vec3 color = sampleBG(uv);   // BASE: the field passes through unchanged.\n  float alpha = 1.0;\n\n  for (int i = 0; i < MAX_PANELS; i++) {\n    if (i >= uPanelCount) break;\n    vec4 b = uBounds[i];\n    vec2 gmin = b.xy;\n    vec2 gmax = b.xy + b.zw;\n    bool inside = uv.x >= gmin.x && uv.x <= gmax.x && uv.y >= gmin.y && uv.y <= gmax.y;\n    if (inside) {\n      vec4 s = glassSample(uv, b);\n      color = s.rgb;\n      alpha = s.a;\n    }\n  }\n\n  fragColor = vec4(color, alpha);\n}";

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

@@ -76,7 +76,7 @@ export interface WebGLCanvasOptions {
     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`. */
+    /** Fire the one-shot cold-first-VISIBLE entrance bloom (BG.W-VIZ-REVEAL-BLOOM — the `data-substrate-reveal` attr). Default `false`. */
     revealBloom?: boolean;
     /**
      * Build the program + geometry on a fresh context. Called on `arm()` AND on

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

@@ -0,0 +1,42 @@
+import type { CanvasSuspendReason } from "./createCanvasLifecycle";
+/**
+ * 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
+ * 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).
+ */
+export interface CanvasVisibilityDeps {
+    canvas: HTMLCanvasElement;
+    suspend: (reason: CanvasSuspendReason) => void;
+    resume: (reason: CanvasSuspendReason) => void;
+    resize: () => void;
+    wake: () => void;
+    isArmed: () => boolean;
+    hasHooks: () => boolean;
+    isDisposed: () => boolean;
+    isReducedMotion: () => boolean;
+    composeIntersectionPark: boolean;
+    intersectionRootMargin?: string;
+    revealBloom: boolean;
+}
+export interface CanvasVisibility {
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing store + 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.
+     */
+    presize(): void;
+    /** Bind the content-visibility + intersection park observers (called at arm). */
+    bindPark(): void;
+    /** Arm the one-shot first-visible entrance bloom (called at arm, after armed=true). */
+    armRevealBloom(): void;
+    /** Detach every observer/listener owned here. */
+    dispose(): void;
+}
+/**
+ * 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.
+ */
+export declare function createCanvasVisibility(deps: CanvasVisibilityDeps): CanvasVisibility;

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

@@ -0,0 +1,13 @@
+export type RendererEngine = "webgpu" | "webgl2" | "canvas2d" | "css";
+export interface RendererStatus {
+    phase: "initializing" | "ready" | "error";
+    engine: RendererEngine;
+    adapter: string;
+    error?: string;
+}
+export declare const pendingRenderer: (engine: RendererEngine) => RendererStatus;
+export declare const canvas2DRenderer: () => RendererStatus;
+export declare const cssRenderer: () => RendererStatus;
+export declare function describeWebGPUAdapter(info?: GPUAdapterInfo): string;
+export declare function describeWebGL2Adapter(gl: WebGL2RenderingContext | null): string;
+export declare function rendererFailure(engine: RendererEngine, adapter: string, error: unknown): RendererStatus;

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

@@ -2,6 +2,8 @@ import { type WebGLCanvasFrame, type WebGLCanvasOptions } from "../webgl/useWebG
 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 };
 /** Which backend the picker resolved. */
 export type GpuBackend = "webgpu" | "webgl2";
@@ -37,10 +39,11 @@ export interface GpuSubstrateOptions {
     /** `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`.
+     * BG.W-VIZ-REVEAL-BLOOM — 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,
+     * one-shot (zero second bloom), PRM-instant. Default `false` (opt-in per viz).
      */
     revealBloom?: boolean;
     /** WebGPU `context.configure` alpha mode (default `"premultiplied"`). */
@@ -63,6 +66,7 @@ export interface GpuSubstrateOptions {
         to: "webgl2";
         error: unknown;
     }) => void;
+    onStatus?: (status: RendererStatus) => void;
 }
 /**
  * The uniform substrate handle. A viz consumer wires its lifecycle (offscreen pause,

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

@@ -1,6 +1,7 @@
-import { type BackingSize, type DprPolicy } from "../webgl/createCanvasLifecycle";
 export type { BackingSize, DprPolicy } from "../webgl/createCanvasLifecycle";
-export { WebGPUInitError } from "./webgpuDevice";
+export { WebGPUInitError, WEBGPU_ACQUIRE_TIMEOUT_MS } from "./webgpuDevice";
+export type { WebGPUSuspendReason, WebGPUCanvasFrame, WebGPUCanvasOptions, WebGPUCanvasHandle, } from "./webgpuCanvasTypes";
+import type { WebGPUCanvasOptions, WebGPUCanvasHandle } from "./webgpuCanvasTypes";
 /**
  * The ONE `navigator.gpu` capability probe (the single-bootstrap rule — mirrors
  * `probeWebGL2Renderer`). SSR-safe (returns `false` with no `navigator`). The picker
@@ -9,20 +10,6 @@ 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`
@@ -34,99 +21,4 @@ export declare const WEBGPU_ACQUIRE_TIMEOUT_MS = 6000;
  * 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
- * consumer owns the WGSL pipeline + bind groups + the per-frame command-encoder
- * record/submit; the substrate owns the schedule.
- */
-export interface WebGPUCanvasFrame {
-    /**
-     * Draw one frame at `timeSec`: the consumer records a command encoder, begins a
-     * render pass against the current swap-chain texture view
-     * (`context.getCurrentTexture().createView()`), draws, and submits.
-     */
-    frame: (timeSec: number) => void;
-    /** 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.
-     */
-    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. */
-    teardown?: () => void;
-}
-export interface WebGPUCanvasOptions {
-    /** `context.configure` alpha mode (the consumer's — default `"premultiplied"`). */
-    alphaMode?: GPUCanvasAlphaMode;
-    /** Extra device-request options (features/limits). */
-    deviceDescriptor?: GPUDeviceDescriptor;
-    /** Adapter-request options (e.g. `powerPreference`). */
-    adapterOptions?: GPURequestAdapterOptions;
-    /** `"capture"` pre-seeds the `manual` suspension (renderAt-only). Default `"live"`. */
-    mode?: "live" | "capture";
-    /**
-     * Honor `prefers-reduced-motion: reduce` by painting ONE static frame then
-     * parking the loop. The shared lifecycle core live-monitors the query via a
-     * `matchMedia` `change` listener and re-arms (one static frame) on un-reduce.
-     * 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.
-     */
-    setup: (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;
-    /** 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.
-     */
-    armAsync: () => Promise<void>;
-    /**
-     * Synchronous `arm` — a no-op until `armAsync` has resolved the device (the
-     * uniform-handle parity with the synchronous backends; the picker calls
-     * `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). */
-    wake: () => void;
-    /** 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). */
-    readonly device: GPUDevice | null;
-    /**
-     * The live `prefers-reduced-motion: reduce` state. The shared lifecycle core
-     * owns + re-monitors it; consumers read it (e.g. a viz freezes its frame time
-     * at the authored offset while this is `true`).
-     */
-    readonly reducedMotion: boolean;
-}
 export declare function createWebGPUCanvas(canvas: HTMLCanvasElement, options: WebGPUCanvasOptions): WebGPUCanvasHandle;

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

@@ -0,0 +1,98 @@
+import type { BackingSize, DprPolicy } from "../webgl/createCanvasLifecycle";
+export type WebGPUSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
+/**
+ * The per-frame hooks a consumer's `setup(device, context, format)` returns. The
+ * consumer owns the WGSL pipeline + bind groups + the per-frame command-encoder
+ * record/submit; the substrate owns the schedule.
+ */
+export interface WebGPUCanvasFrame {
+    /**
+     * Draw one frame at `timeSec`: the consumer records a command encoder, begins a
+     * render pass against the current swap-chain texture view
+     * (`context.getCurrentTexture().createView()`), draws, and submits.
+     */
+    frame: (timeSec: number) => void;
+    /** 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.
+     */
+    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. */
+    teardown?: () => void;
+}
+export interface WebGPUCanvasOptions {
+    /** `context.configure` alpha mode (the consumer's — default `"premultiplied"`). */
+    alphaMode?: GPUCanvasAlphaMode;
+    /** Extra device-request options (features/limits). */
+    deviceDescriptor?: GPUDeviceDescriptor;
+    /** Adapter-request options (e.g. `powerPreference`). */
+    adapterOptions?: GPURequestAdapterOptions;
+    /** `"capture"` pre-seeds the `manual` suspension (renderAt-only). Default `"live"`. */
+    mode?: "live" | "capture";
+    /**
+     * Honor `prefers-reduced-motion: reduce` by painting ONE static frame then
+     * parking the loop. The shared lifecycle core live-monitors the query via a
+     * `matchMedia` `change` listener and re-arms (one static frame) on un-reduce.
+     * 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 one-shot cold-first-VISIBLE entrance bloom (BG.W-VIZ-REVEAL-BLOOM — the `data-substrate-reveal` attr). 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). */
+    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.
+     */
+    armAsync: () => Promise<void>;
+    /**
+     * Synchronous `arm` — a no-op until `armAsync` has resolved the device (the
+     * uniform-handle parity with the synchronous backends; the picker calls
+     * `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). */
+    wake: () => void;
+    /** 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). */
+    readonly device: GPUDevice | null;
+    /** Runtime-derived adapter identity, available once acquisition succeeds. */
+    readonly adapterClass: string;
+    /**
+     * The live `prefers-reduced-motion: reduce` state. The shared lifecycle core
+     * owns + re-monitors it; consumers read it (e.g. a viz freezes its frame time
+     * at the authored offset while this is `true`).
+     */
+    readonly reducedMotion: boolean;
+}

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

@@ -40,3 +40,33 @@ 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
+ * WebGL2 net on it, exactly like a no-adapter host). The timer is cleared the instant
+ * the acquisition settles (resolve OR reject), so a healthy device leaves no dangling
+ * timeout. SSR-safe: with no `setTimeout` the bare promise passes through (a non-DOM
+ * runtime has no WebGPU surface to hang anyway).
+ *
+ * `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).
+ */
+export declare function withAcquireTimeout<T>(promise: Promise<T>, label: string): Promise<T>;

package/dist/composables/index.d.ts

@@ -5,6 +5,5 @@ export * from "./dom";
 export * from "./motion";
 export * from "./motion/core";
 export * from "./glass";
-export * from "./sortable";
 export * from "./sidebar";
-export * from "../components/custom/infinite-scroll/composables";
+export * from "../components/infinite-scroll/composables";

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

@@ -0,0 +1,29 @@
+import type { Ref } from "vue";
+/** The BE.W-AMBIENT-TINT bound (sub-perceptual; never a flood — the warm-cream identity holds). */
+export declare const AMBIENT_STRENGTH_CEILING = 8;
+/** The live reduced-motion probe (matchMedia, SSR-safe). */
+export declare function prefersReducedMotion(): boolean;
+/** Clamp the ambient-strength target into the bounded warm-cream-identity band `[0, 8]`. */
+export declare function clampStrength(n: number | undefined): number;
+/**
+ * Resolve the FIELD container the 4th color channel writes onto. Explicit `field` ref
+ * wins; else walk up from `dest` to the nearest `[data-glass-field]` ancestor (the
+ * field-marker contract); else `dest.parentElement`. The field is a DIFFERENT element
+ * from the blooming surface — the compositor-only de-risk.
+ */
+export declare function resolveField(dest: HTMLElement, explicit: Ref<HTMLElement | null> | undefined): HTMLElement | null;
+/**
+ * Read the source's dominant hue — the explicit `fieldHue` OR the `--glass-ambient-hue`
+ * computed off the source element (the AMBIENT-TINT source). Returns `null` for a
+ * neutral/absent hue (the field tints nothing).
+ */
+export declare function resolveHue(source: HTMLElement | null, explicit: string | undefined): string | null;
+/** Set the field's dominant hue (the 4th-channel hue, set ONCE — not animated). */
+export declare function writeFieldHue(field: HTMLElement, hue: string): void;
+/** Write the field's ambient strength (the registered @property interpolates it). */
+export declare function writeFieldStrength(field: HTMLElement, pct: number): void;
+/**
+ * Release the field bias back to the no-op floor (0%) and clear the hue so the field returns
+ * to its un-biased `--glass-tint-ink` (the warm-cream identity).
+ */
+export declare function releaseField(field: HTMLElement | null): void;

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

@@ -10,11 +10,15 @@ export * from "../useViewTransition";
 export * from "../vReveal";
 export * from "../useTextHighlight";
 export * from "../useLiquidFlex";
+export * from "../useLeadTrail";
 export * from "../useGooMorph";
-export * from "../useMorphField";
+export * from "../morphSignatures";
 export * from "../usePointerVelocityField";
+export * from "../useRoutePointer";
+export * from "../pointerFieldMappings";
 export * from "../useCharStagger";
 export * from "../useScrollTrigger";
 export * from "../useScrollChrome";
-export * from "./useHaptic";
 export * from "./writeVelocityWeight";
+export * from "../useSelectionIndicator";
+export * from "../useSelectionGroup";

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

@@ -0,0 +1,79 @@
+/** The golden ratio — the barbell body diameter is the golden-minor of the slot pitch. */
+export declare const PHI = 1.618033988749895;
+/** sin(π·p)^k — 0 at the ends, peak at the midpoint. The well shape. */
+export declare function bell(p: number, k: number): number;
+/**
+ * The barbell body diameter `D = step/φ` (a round BLOB, not a plate — the
+ * golden-minor of the slot pitch). Floors the step at 1 so a zero pitch never
+ * collapses D to 0.
+ */
+export declare function bodyDiameter(step: number): number;
+/** The inputs to a single barbell projection frame — all numeric, all pure. */
+export interface BarbellSpan {
+    /** The trailing slot center (px on the travel axis). */
+    A: number;
+    /** The leading slot center (px on the travel axis). */
+    B: number;
+    /** The `from` slot index. */
+    fromIdx: number;
+    /** The `to` slot index. */
+    toIdx: number;
+    /** The live interpolated `--goo-t` scalar (∈ [fromIdx, toIdx] in flight). */
+    gooT: number;
+    /** The resting slot pitch (px) — `D = step/φ` lands the body diameter. */
+    step: number;
+    /** The neck-gap fraction: how near the two bodies draw at the midpoint. */
+    neckGap: number;
+    /** The cartoon-weight lever (0..1; clamped here — 0 under PRM/auto). */
+    weight: number;
+}
+/** The projected barbell geometry the engine writes onto the three elements. */
+export interface BarbellGeometry {
+    /** The body diameter `D = step/φ`. */
+    D: number;
+    /** The trailing body center (bodyA). */
+    cA: number;
+    /** The leading body center (bodyB). */
+    cB: number;
+    /** The neck center (the midpoint of the two bodies). */
+    mid: number;
+    /** The on-axis neck span scale `gap/D` (spans the live centre-to-centre gap). */
+    neckSpanScale: number;
+    /** The cross-axis neck girth (wells → pinches, ~0 at the ends). */
+    neckGirth: number;
+    /** The on-axis body squash (the necking-taffy stretch). */
+    stretchOn: number;
+    /** The cross-axis body stretch (volume-preserving reciprocal). */
+    stretchCross: number;
+    /** The cross-axis lob arc (overlapping action — the merge LOBS, not slides). */
+    arc: number;
+}
+/**
+ * Project the BARBELL for the in-flight scalar `gooT`. `p` is the NORMALIZED
+ * progress over the WHOLE from→to travel (a multi-gap morph spans p∈[0,1] over
+ * the full span, so the barbell necks across the BIG gap on the SAME slow flow
+ * curve). Pure — no closure, no DOM, no state.
+ *   sep(p)      = 1 − bell(p,1)·(1 − neckGap)   // 1 at the slots → neckGap at mid
+ *   mid         = (A + B) / 2 ; half = (B − A)/2 · sep(p)
+ *   cA = mid − half ; cB = mid + half           // bodies travel apart-then-together
+ *   neckGirth(p)= bell(p,1.5)                     // wells, peaks mid, ~0 at the ends
+ */
+export declare function projectBarbell(span: BarbellSpan): BarbellGeometry;
+/**
+ * Compose a BODY transform on the travel axis: translate(center) → -50% → scale +
+ * the on-axis squash-&-stretch reciprocal (volume-preserving). `el` is sized to the
+ * body diameter D, so no scale-to-fit is needed; the squash is the `--stretch` taffy.
+ * The `arc` lobs the body centre on the CROSS axis (overlapping action). Pure string.
+ */
+export declare function composeBodyTransform(center: number, arc: number, stretchOn: number, stretchCross: number, vertical: boolean): string;
+/**
+ * Compose the NECK transform: translate(mid) on-axis, scaleX(gap/D) on-axis so it
+ * spans the live gap, scaleY(neckGirth) cross-axis so it WELLS then PINCHES (~0 at
+ * the ends → the neck vanishes at rest, no ghost throat). Pure string.
+ */
+export declare function composeNeckTransform(mid: number, neckSpanScale: number, neckGirth: number, vertical: boolean): string;
+/**
+ * Compose the RESTING NECK transform — the neck pinched to ~0 at the coalesced
+ * center (no ghost throat at rest). Pure string.
+ */
+export declare function composeRestNeckTransform(center: number, vertical: boolean): string;

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

@@ -4,10 +4,10 @@ export * from "./useSpringMount";
 export * from "./useSpringPress";
 export * from "./useLiquidPress";
 export * from "./useDragMorph";
+export * from "./useElementMorph";
 export * from "./useLiquidReveal";
 export * from "./useDockCtaReceive";
 export * from "./useBloomUp";
-export * from "./useCelebrationBurst";
 export * from "./useNumericTransition";
 export * from "./useAnimatedNumber";
 export * from "./useAnimatedNumberMap";