@mkbabb/glass-ui 4.0.0 → 4.1.0

package/dist/components/ui/switch/Switch.vue.d.ts

@@ -1,7 +1,9 @@
 import { type HTMLAttributes } from 'vue';
 import { type SwitchRootProps } from 'reka-ui';
+import { type ControlSize } from '../_shared/useControlSize';
 type __VLS_Props = SwitchRootProps & {
     class?: HTMLAttributes['class'];
+    size?: ControlSize;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:modelValue": (payload: boolean) => any;

package/dist/components/ui/tags-input/TagsInput.vue.d.ts

@@ -8,13 +8,13 @@ type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_8) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    "update:modelValue": (payload: import("reka-ui").AcceptableInputValue[]) => any;
     invalid: (payload: import("reka-ui").AcceptableInputValue) => any;
+    "update:modelValue": (payload: import("reka-ui").AcceptableInputValue[]) => any;
     addTag: (payload: import("reka-ui").AcceptableInputValue) => any;
     removeTag: (payload: import("reka-ui").AcceptableInputValue) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
-    "onUpdate:modelValue"?: ((payload: import("reka-ui").AcceptableInputValue[]) => any) | undefined;
     onInvalid?: ((payload: import("reka-ui").AcceptableInputValue) => any) | undefined;
+    "onUpdate:modelValue"?: ((payload: import("reka-ui").AcceptableInputValue[]) => any) | undefined;
     onAddTag?: ((payload: import("reka-ui").AcceptableInputValue) => any) | undefined;
     onRemoveTag?: ((payload: import("reka-ui").AcceptableInputValue) => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

package/dist/components/ui/textarea/Textarea.vue.d.ts

@@ -1,10 +1,12 @@
 import type { HTMLAttributes, TextareaHTMLAttributes } from 'vue';
+import { type ControlSize } from '../_shared/useControlSize';
 declare const _default: typeof __VLS_export;
 export default _default;
 declare const __VLS_export: import("vue").DefineComponent<{
     class?: HTMLAttributes["class"];
     defaultValue?: string | number;
     modelValue?: string | number;
+    size?: ControlSize;
     placeholder?: TextareaHTMLAttributes["placeholder"];
     disabled?: TextareaHTMLAttributes["disabled"];
     /**
@@ -29,6 +31,7 @@ declare const __VLS_export: import("vue").DefineComponent<{
     class?: HTMLAttributes["class"];
     defaultValue?: string | number;
     modelValue?: string | number;
+    size?: ControlSize;
     placeholder?: TextareaHTMLAttributes["placeholder"];
     disabled?: TextareaHTMLAttributes["disabled"];
     /**

package/dist/components/ui/toast/Toast.vue.d.ts

@@ -1,18 +1,20 @@
 import { type HTMLAttributes } from 'vue';
 import { type ToastRootProps } from 'reka-ui';
+import { type Surface } from '../_shared/useSurfaceAxis';
 import type { ToastVariant } from './use-toast';
 interface ToastProps extends ToastRootProps {
     class?: HTMLAttributes['class'];
     variant?: ToastVariant;
+    surface?: Surface;
 }
 declare var __VLS_8: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_8) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<ToastProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    pause: () => any;
     "update:open": (value: boolean) => any;
     escapeKeyDown: (event: KeyboardEvent) => any;
-    pause: () => any;
     resume: () => any;
     swipeStart: (event: {
         currentTarget: EventTarget & HTMLElement;
@@ -51,9 +53,9 @@ declare const __VLS_base: import("vue").DefineComponent<ToastProps, {}, {}, {},
         };
     }>, "currentTarget">) => any;
 }, string, import("vue").PublicProps, Readonly<ToastProps> & Readonly<{
+    onPause?: (() => any) | undefined;
     "onUpdate:open"?: ((value: boolean) => any) | undefined;
     onEscapeKeyDown?: ((event: KeyboardEvent) => any) | undefined;
-    onPause?: (() => any) | undefined;
     onResume?: (() => any) | undefined;
     onSwipeStart?: ((event: {
         currentTarget: EventTarget & HTMLElement;
@@ -93,6 +95,7 @@ declare const __VLS_base: import("vue").DefineComponent<ToastProps, {}, {}, {},
     }>, "currentTarget">) => any) | undefined;
 }>, {
     variant: ToastVariant;
+    surface: Surface;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/components/ui/toast/use-toast.d.ts

@@ -1,4 +1,5 @@
 import type { Component, VNode } from 'vue';
+import type { Surface } from '../_shared/useSurfaceAxis';
 export type ToastVariant = 'default' | 'destructive' | 'success' | 'warning' | 'info';
 export interface Toast {
     id: string;
@@ -6,6 +7,12 @@ export interface Toast {
     description?: string;
     action?: Component | VNode;
     variant?: ToastVariant;
+    /**
+     * BB.W-SURFACE-AXIS-COMPLETE — the shared {glass·veil·opaque} surface-decoration
+     * axis on a queued toast (default `glass`). Forwarded through `Toaster.vue`'s
+     * per-toast `v-bind` exactly like `variant`; orthogonal to the tone arm.
+     */
+    surface?: Surface;
     /**
      * Auto-dismiss delay in ms, forwarded to reka-ui's `ToastRoot`. Omit to
      * inherit the `ToastProvider` default; `Number.POSITIVE_INFINITY` keeps the
@@ -152,6 +159,13 @@ declare function useToast(): {
             __name?: string | undefined;
         } | undefined;
         variant?: ToastVariant
+        /**
+         * BB.W-SURFACE-AXIS-COMPLETE — the shared {glass·veil·opaque} surface-decoration
+         * axis on a queued toast (default `glass`). Forwarded through `Toaster.vue`'s
+         * per-toast `v-bind` exactly like `variant`; orthogonal to the tone arm.
+         */
+         | undefined;
+        surface?: Surface
         /**
          * Auto-dismiss delay in ms, forwarded to reka-ui's `ToastRoot`. Omit to
          * inherit the `ToastProvider` default; `Number.POSITIVE_INFINITY` keeps the

package/dist/components/ui/toggle/Toggle.vue.d.ts

@@ -16,8 +16,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
 }>, {
     size: "default" | "sm" | "lg" | null;
-    variant: "default" | "outline" | "card" | null;
     disabled: boolean;
+    variant: "default" | "outline" | "card" | null;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/components/ui/tooltip/TooltipContent.vue.d.ts

@@ -1,7 +1,9 @@
 import { type HTMLAttributes } from 'vue';
 import { type TooltipContentProps } from 'reka-ui';
+import { type Surface } from '../_shared/useSurfaceAxis';
 type __VLS_Props = TooltipContentProps & {
     class?: HTMLAttributes['class'];
+    surface?: Surface;
 };
 declare var __VLS_14: {};
 type __VLS_Slots = {} & {
@@ -14,6 +16,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     onEscapeKeyDown?: ((event: KeyboardEvent) => any) | undefined;
     onPointerDownOutside?: ((event: Event) => any) | undefined;
 }>, {
+    surface: Surface;
     sideOffset: number;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

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

@@ -133,3 +133,5 @@ export interface DeriveBlobPaletteOptions {
  * @param options stop count, harmony, spreads.
  */
 export declare function deriveBlobPalette(seed: string | OklchStop, options?: DeriveBlobPaletteOptions): OklchStop[];
+export { useAccentTone } from "./useAccentTone";
+export type { UseAccentToneOptions, UseAccentToneReturn } from "./useAccentTone";

package/dist/composables/color/useAccentTone.d.ts

@@ -0,0 +1,34 @@
+import { type ComputedRef, type MaybeRefOrGetter } from "vue";
+export interface UseAccentToneOptions {
+    /** Idle fill strength (0..1). Default 0.08. The CSS `--accent-fill-strength`
+     *  twin — passed here so the JS ink-solve composites the matching band. */
+    fillStrength?: number;
+    /** Active band strength (0..1). Default 0.18 (the CSS `--accent-band-strength`). */
+    bandStrength?: number;
+    /** Target ink-over-band contrast. Default 4.5 (AA). */
+    inkContrast?: number;
+    /** The surface the accent paints ON (a CSS `<color>`). Default the warm-cream
+     *  `--card`. A consumer on a dark/other plate passes its concrete surface so
+     *  the ink solves against the right band lightness. */
+    surface?: string;
+}
+export interface UseAccentToneReturn {
+    /** The element-level custom-property style object — bind via `:style`. Carries
+     *  `--tone` (so the CSS channels resolve) + `--accent-ink-resolved` (the
+     *  contrast-safe label colour over the active band). */
+    toneStyle: ComputedRef<Record<string, string>>;
+    /** The resolved contrast-safe ink as a CSS `oklch(...)` string (for a non-CSS
+     *  reader — a canvas label, a test). */
+    ink: ComputedRef<string>;
+}
+/**
+ * `useAccentTone(tone, opts)` — resolve the contrast-safe label ink for the tonal
+ * register. The ink RESOLVES `safeAccentColor(toneColor, bandLightness, …)`:
+ * value.js shifts the tone's OKLCh lightness AWAY from the active-band fill until
+ * it clears the AA bar, so the label reads ON the fill in either mode (a dark band
+ * gets a light ink, a light band a dark ink). The darken/lighten-until-it-passes
+ * math is value.js's — glass-ui re-implements none of it.
+ *
+ * PRM-irrelevant (a colour, not an animation). DOM-free + deterministic.
+ */
+export declare function useAccentTone(tone: MaybeRefOrGetter<string>, opts?: UseAccentToneOptions): UseAccentToneReturn;

package/dist/composables/glass/canvas2d/useCanvas2D.d.ts

@@ -1,6 +1,12 @@
 import { type MaybeRefOrGetter } from "vue";
-/** The suspend reasons that gate the loop. Twins the WebGL substrate's union. */
-export type Canvas2DSuspendReason = "tab-hidden" | "off-screen" | "manual";
+/**
+ * The suspend reasons that gate the loop. Twins the WebGL substrate's union
+ * (`createCanvasLifecycle.CanvasSuspendReason`): the AX.W16 F6 `"off-screen-io"`
+ * key is the IntersectionObserver fallback's OWN reason, distinct from the
+ * content-visibility path's `"off-screen"`, so the two offscreen detectors never
+ * cross-lift each other's suspend.
+ */
+export type Canvas2DSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
 /** The per-frame hooks a consumer's `setup(ctx)` returns. */
 export interface Canvas2DFrame {
     /**
@@ -47,10 +53,11 @@ export interface Canvas2DHandle {
 }
 /**
  * The Canvas2D lifecycle substrate — the park/freeze/dispose twin of
- * `useWebGLCanvas`. Returns an imperative {@link Canvas2DHandle} (the same
- * handle idiom the WebGL twin uses — an imperative canvas seam is NOT a
- * ref-bundle). `useCanvasLifecycle` is the alias-of-record for the
- * lifecycle-only framing; both name the same factory.
+ * `useWebGLCanvas`, a thin Canvas2D backend over the shared
+ * `createCanvasLifecycle` core. Returns an imperative {@link Canvas2DHandle} (the
+ * same handle idiom the WebGL twin uses — an imperative canvas seam is NOT a
+ * ref-bundle). `useCanvasLifecycle` is the alias-of-record for the lifecycle-only
+ * framing; both name the same factory.
  */
 export declare function useCanvas2D(options: Canvas2DOptions): Canvas2DHandle;
 /**

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

@@ -1,4 +1,7 @@
-export { useSpecularTracking } from "./useSpecularTracking";
-export type { UseSpecularTracking } from "./useSpecularTracking";
+export { useSpecularTracking, createSpecularWriter, } from "./useSpecularTracking";
+export type { UseSpecularTracking, SpecularWriter, } from "./useSpecularTracking";
+export { vSpecular } from "./vSpecular";
+export { useSpecularPointer } from "./useSpecularPointer";
+export type { UseSpecularPointer } from "./useSpecularPointer";
 export { useCanvas2D, useCanvasLifecycle, resolveCanvasColor } from "./canvas2d";
 export type { Canvas2DFrame, Canvas2DHandle, Canvas2DOptions, Canvas2DSuspendReason, } from "./canvas2d";

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

@@ -0,0 +1,33 @@
+import { ref, type CSSProperties } from "vue";
+/**
+ * `useSpecularPointer` — the EVOLUTION of `useSpecularTracking` (BB.W-LENSING). It
+ * writes the catch-light POSITION (`--mouse-x`/`--mouse-y`, as today) PLUS the
+ * `--specular-angle` channel — the pointer's angle-from-center the EDGE-glint conic
+ * sweep reads (the `.glass-material::before` recipe, material.css). The angle feed is
+ * what turns the centered disc into a motion-reactive RIM glint (the glass-THICKNESS
+ * read); the leaf is the ONE shared specular source the hover/button waves consume.
+ *
+ * SINGLE-SOURCE (the W-LIQUIDHOVER reconcile, EXTENDED here — NOT a fork). There is
+ * exactly ONE position-write core: `createSpecularWriter` (useSpecularTracking.ts) —
+ * the rAF-coalesced, cached-PRM, scope-dispose seam. This composable WRAPS that core;
+ * the angle is DERIVED in the sink from the SAME `(x, y)` percentage the core already
+ * computes (`angle = atan2(y - 50, x - 50)`), so there is NO duplicate
+ * `getBoundingClientRect` / `--mouse-x` write — the core owns the layout read + the
+ * coordinate math, this leaf only adds the angle derivation onto the existing sink.
+ * `useSpecularTracking` (the position-only delivery) STAYS for the bare-position call
+ * sites; `useSpecularPointer` is the angle-adding delivery for an edge-glint consumer.
+ * Both wrap the ONE core — never two copies of the rAF/PRM/coordinate logic.
+ *
+ * PRM-aware by construction (the wrapped core skips the write under
+ * `prefers-reduced-motion: reduce` — the CSS bracket pins `--specular-x/y` to the
+ * centred 50% and `--specular-angle` to its `0deg` static rest). The composable
+ * disposes the core (cancel the pending rAF + drop the cached PRM listener) on scope
+ * teardown.
+ */
+export interface UseSpecularPointer {
+    /** Bind to the host element's `:style`. Carries `--mouse-x/--mouse-y` + `--specular-angle`. */
+    specularStyle: ReturnType<typeof ref<CSSProperties>>;
+    /** Bind to the host's `@pointermove`. Schedules the rAF-coalesced position+angle write (PRM-gated). */
+    onPointerMove: (event: PointerEvent) => void;
+}
+export declare function useSpecularPointer(): UseSpecularPointer;

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

@@ -32,6 +32,13 @@ import { ref, type CSSProperties } from "vue";
  * W54 maximal-glass every blurred-surface repaint is amortized to the frame, not the
  * event). The composable cancels the pending rAF + removes the matchMedia listener on
  * scope dispose (cleanup discipline).
+ *
+ * BB.W-LIQUIDHOVER — the rAF-coalesce + cached-PRM + cleanup LOGIC is extracted to
+ * `createSpecularWriter()`, the SINGLE position-write core. The composable below wraps
+ * it for the Vue `:style`-ref case (Card's prop-gated `specular` opt-in); the
+ * tier-root auto-arm (`vSpecular`) wraps the SAME core to write directly on the
+ * directive host's `el.style` (the zero-wiring delivery). ONE position-write source,
+ * TWO deliveries — never a re-pasted handler.
  */
 export interface UseSpecularTracking {
     /** Bind to the host element's `:style`. Carries the `--mouse-x/--mouse-y` write. */
@@ -39,4 +46,17 @@ export interface UseSpecularTracking {
     /** Bind to the host's `@pointermove`. Schedules the rAF-coalesced position write (PRM-gated). */
     onPointerMove: (event: PointerEvent) => void;
 }
+/**
+ * The SINGLE position-write core (BB.W-LIQUIDHOVER) — the rAF-coalesced,
+ * PRM-aware `--mouse-x/y` write seam, sink-agnostic. `sink(x, y)` receives the
+ * percentage position once per animation frame; the composable sinks into its
+ * `specularStyle` ref, the `vSpecular` directive sinks into `el.style.setProperty`.
+ * Returns the event handler + a `dispose` (cancel the pending rAF + drop the cached
+ * PRM listener) so BOTH deliveries share ONE cleanup discipline.
+ */
+export interface SpecularWriter {
+    onPointerMove: (event: PointerEvent) => void;
+    dispose: () => void;
+}
+export declare function createSpecularWriter(sink: (xPct: number, yPct: number) => void): SpecularWriter;
 export declare function useSpecularTracking(): UseSpecularTracking;

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

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

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

@@ -0,0 +1,2 @@
+import type { ObjectDirective } from "vue";
+export declare const vSpecular: ObjectDirective<HTMLElement, boolean | undefined>;

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

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

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

@@ -0,0 +1 @@
+export declare const CURL_FBM_GLSL = "\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";

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,19 @@
+/**
+ * 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
+ * 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
+ * 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;
 export type WebGLSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
 /** The per-frame hooks a consumer's `setup(gl)` returns. */
 export interface WebGLCanvasFrame {

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

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

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

@@ -0,0 +1,75 @@
+import { type WebGLCanvasFrame, type WebGLCanvasOptions } from "../webgl/useWebGLCanvas";
+import { supportsWebGPU, type WebGPUCanvasFrame, type WebGPUCanvasOptions } from "./useWebGPUCanvas";
+export { supportsWebGPU };
+/** Which backend the picker resolved. */
+export type GpuBackend = "webgpu" | "webgl2";
+export interface GpuSubstrateOptions {
+    /** `"capture"` → renderAt-only (no auto-loop). Default `"live"`. */
+    mode?: "live" | "capture";
+    /** Honor `prefers-reduced-motion: reduce` (one static frame then park). Default `true`. */
+    respectReducedMotion?: boolean;
+    /**
+     * The WGSL pipeline builder (the WebGPU primary path). Omitting it forces the
+     * WebGL2 fallback even where WebGPU is supported (a viz with no WGSL path yet).
+     */
+    setupWGPU?: WebGPUCanvasOptions["setup"];
+    /** The GLSL program builder (the WebGL2 fallback path — always required). */
+    setupGL: WebGLCanvasOptions["setup"];
+    /** WebGPU `context.configure` alpha mode (default `"premultiplied"`). */
+    alphaMode?: WebGPUCanvasOptions["alphaMode"];
+    /** WebGPU adapter/device request options. */
+    adapterOptions?: WebGPUCanvasOptions["adapterOptions"];
+    deviceDescriptor?: WebGPUCanvasOptions["deviceDescriptor"];
+    /** WebGL2 `getContext("webgl2", …)` attributes. */
+    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 (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. 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 (try WebGPU, fall to the WebGL2 net). Resolves once armed. */
+    armAsync: () => Promise<void>;
+    /** Synchronous arm (the WebGL2 net arms immediately; the WebGPU path is a no-op until the device resolves). */
+    arm: () => void;
+    suspend: (reason?: "tab-hidden" | "off-screen" | "off-screen-io" | "manual") => void;
+    resume: (reason?: "tab-hidden" | "off-screen" | "off-screen-io" | "manual") => void;
+    wake: () => void;
+    renderAt: (timeSec: number) => void;
+    dispose: () => void;
+    readonly reducedMotion: boolean;
+}
+/**
+ * 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.
+ */
+export declare function createGpuSubstrate(canvas: HTMLCanvasElement, options: GpuSubstrateOptions): GpuSubstrateHandle;
+export type { WebGPUCanvasFrame, WebGLCanvasFrame };

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

@@ -0,0 +1,85 @@
+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
+ * (`useGpuSubstrate`) reads it to decide the backend; a consumer NEVER touches
+ * `navigator.gpu` directly (it composes the substrate — `proof:gpu-substrate-single`
+ * clause A reds a direct call).
+ */
+export declare function supportsWebGPU(): boolean;
+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;
+    /** Size the canvas backing store. The consumer owns its DPR policy. */
+    resize: () => 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;
+    /**
+     * 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;
+    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;