@mkbabb/glass-ui 4.1.0 → 5.0.0

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

@@ -0,0 +1,29 @@
+import { type HTMLAttributes } from 'vue';
+import { type ToggleProps } from 'reka-ui';
+import { type ToggleVariants } from './';
+type __VLS_Props = ToggleProps & {
+    class?: HTMLAttributes['class'];
+    variant?: ToggleVariants['variant'];
+    size?: ToggleVariants['size'];
+};
+declare var __VLS_8: {};
+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": (value: boolean) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:modelValue"?: ((value: boolean) => any) | undefined;
+}>, {
+    size: "sm" | "md" | "lg" | 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;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/toggle/index.d.ts

@@ -0,0 +1,26 @@
+import { type VariantProps } from 'class-variance-authority';
+export { default as Toggle } from './Toggle.vue';
+/**
+ * `card` variant — AC.W8e (glass-ui v1.7.0).
+ *
+ * Hoist of speedtest FlowSelector's 17-class glass-card recipe. The pattern
+ * (icon-over-label-over-description on a `.glass-card` surface, hover quiet
+ * fill, `data-state="on"` selected fill + border, active scale press) is
+ * generic enough that other consumers (survey wizards, mode pickers,
+ * settings picker grids) will hit the same shape. The variant bakes:
+ *  - the quiet glass surface ladder (`.glass-card` base + hover/selected
+ *    `--glass-{bg,border,shadow}-quiet` tier composition)
+ *  - the column-stack interior (`flex-col`, `gap-4`, `p-8`, `text-center`)
+ *  - `data-state="on"` + `:hover` contracts threaded through glass tokens,
+ *    not raw `bg-accent` (which would shadow the card surface)
+ *  - the active-press scale (`active:scale-95`) for tactile affordance
+ *
+ * Reads through `.glass-card` so consumers retint via the existing glass
+ * token cascade (`--glass-bg-quiet`, `--glass-border-quiet`, etc.) rather
+ * than re-declaring the surface at the consumer.
+ */
+export declare const toggleVariants: (props?: ({
+    variant?: "default" | "outline" | "card" | null | undefined;
+    size?: "sm" | "md" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type ToggleVariants = VariantProps<typeof toggleVariants>;

package/dist/components/watercolor-dot/WatercolorDot.vue.d.ts

@@ -0,0 +1,74 @@
+/**
+ * WatercolorDot — an organic pastel blob swatch. A CSS/SVG primitive (NO drawing
+ * context — no WebGL/WebGPU/Canvas2D; the deliberate suite counterexample, the mark
+ * that documents WHY it is not a GPU context): the blob shape is a deterministic
+ * per-vertex `border-radius` morph (seeded by `color + seed`), and the wet, bleeding
+ * edge is an SVG turbulence + displacement filter that is INTERNALISED — the component
+ * mounts its own namespaced `<filter>` so there is zero consumer plumbing. Mount the
+ * dot and the filter just works.
+ *
+ * Safari-safe by construction (USER-DEFECTS §H): the SVG `<filter>` rasterizes ONCE
+ * + caches (the HandMark `texture.ts` idiom) and NEVER re-rasterizes per frame; the
+ * `animate` liveness rides a seeded COMPOSITOR `transform` wobble the compositor
+ * accelerates without touching the filter graph (a per-frame `border-radius` paint
+ * under the filter is the §H Safari flash, retired here). The filter `seed` is
+ * per-instance off `hashString(color + seed)` so each dot's wet edge is uniquely
+ * displaced (no twelve-clones).
+ *
+ * Color arrives as a CSS string painted straight onto the swatch background — the
+ * dot needs no resolver because it does not feed a shader; the injected-color seam
+ * shape is "pass the CSS color in". Warm-cream identity by default (the dot bakes no
+ * hue; the demo palette is presets-in-consumers).
+ */
+type __VLS_Props = {
+    /** CSS color painted as the swatch background (any CSS color form). */
+    color: string;
+    /**
+     * Render mode:
+     *   `solid` (default) — the filled organic blob (the swatch background IS the
+     *                       color; the existing register, unchanged).
+     *   `ghost`  — the SAME seeded blob SILHOUETTE traced as a DASHED outline: a
+     *              dashed CSS BORDER reading the SAME seeded `border-radius`
+     *              silhouette the solid dot fills (`activeBorderRadius`), carrying
+     *              the SAME wet `feDisplacementMap` filter so the displacement
+     *              wobbles the dashed border INTO the seeded organic outline. A
+     *              CSS dashed border hugs its own `border-radius`, so the outline
+     *              follows the seeded blob EXACTLY — NOT an ellipse, NOT a circle,
+     *              NOT a dashed rectangle. A low-alpha `color` fill is kept behind
+     *              the border. A `ghost` of a given `color + seed` traces the SAME
+     *              outline the `solid` dot of that seed fills (both read the same
+     *              `useWatercolorBlob` morph — the ONE shape source). The empty-
+     *              palette-slot / placeholder affordance.
+     */
+    variant?: "solid" | "ghost";
+    /** Run the rAF-driven compositor transform wobble (default false → static). */
+    animate?: boolean;
+    /** Host tag — `div` (decorative) or `button` (interactive). */
+    tag?: "div" | "button";
+    /** Base morph cycle duration in ms (default 4000). */
+    cycleDuration?: number;
+    /** Border-radius range [lo, hi] as percentages (default [20, 80]). */
+    range?: [number, number];
+    /** Extra seed string mixed into the shape + wet-edge PRNG for uniqueness. */
+    seed?: string;
+};
+declare var __VLS_11: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_11) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    animate: boolean;
+    range: [number, number];
+    variant: "solid" | "ghost";
+    seed: string;
+    tag: "div" | "button";
+    cycleDuration: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/watercolor-dot/prng.d.ts

@@ -0,0 +1,5 @@
+export { mulberry32, hashString } from "../../composables/glass/procedural/prng";
+/** Generate 8 random border-radius percentages in [lo, hi] using the given PRNG. */
+export declare function randomRadii(rng: () => number, lo: number, hi: number): number[];
+/** Serialise 8 radii into a CSS `border-radius` shorthand (4 corners / 4 corners). */
+export declare function radiiToCSS(r: number[]): string;

package/dist/components/watercolor-dot/useWatercolorBlob.d.ts

@@ -0,0 +1,31 @@
+import { type Ref } from "vue";
+export interface UseWatercolorBlobOptions {
+    /** Enable the rAF animation loop (drives a COMPOSITOR transform wobble). */
+    animate?: boolean;
+    /** Base cycle duration in ms (default 4000). */
+    cycleDuration?: number;
+    /** Border-radius range [lo, hi] as percentages (default [20, 80]). */
+    range?: [number, number];
+    /** Extra seed string mixed into the hash for unique shapes. */
+    seed?: string;
+}
+/**
+ * Drives a watercolor dot's organic blob shape. Deterministic given `color + seed`
+ * (seeds the PRNG), so the same color reproduces the same shape across mounts. The
+ * seeded `border-radius` silhouette is set ONCE (the dot's identity) and is STATIC —
+ * the box never re-paints its radius per frame (the §H Safari fix: a per-frame
+ * `border-radius` write under the SVG filter forces the filter graph to RE-RASTERIZE
+ * every frame, which flashes Safari). In `animate` mode the liveness rides a seeded
+ * COMPOSITOR `transform` wobble (scale/skew/rotate) the compositor handles WITHOUT
+ * touching the cached filter — the HandMark static-filter idiom. The wobble is driven
+ * by the library's ONE `useRAFLoop` (BG.W-WATERCOLOR-RAF) — parked when the tab is
+ * hidden, frozen under `prefers-reduced-motion` — never a hand-rolled zombie rAF.
+ * `nudge()` retargets the wobble for a quick jiggle on hover.
+ */
+export declare function useWatercolorBlob(color: Ref<string> | (() => string), options?: UseWatercolorBlobOptions): {
+    borderRadius: Ref<string, string>;
+    hoverBorderRadius: Ref<string, string>;
+    transform: Ref<string, string>;
+    nudge: () => void;
+};
+export type WatercolorBlob = ReturnType<typeof useWatercolorBlob>;

package/dist/composables/color/accent-tone-solve.d.ts

@@ -0,0 +1,11 @@
+import type { UseAccentToneOptions } from "./useAccentTone";
+/**
+ * Resolve the contrast-safe label ink for a CONCRETE tone (the caller — the shell —
+ * has already screened out `var(--…)` tones; there is no author-time solve for a
+ * cascade var). 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. Returns an
+ * `oklch(...)` string, or `""` on an unparseable tone/surface (fail-explicit — the
+ * consumer falls back to the CSS default ink, a befitting graceful degrade).
+ */
+export declare function solveAccentInk(toneCss: string, opts?: UseAccentToneOptions): string;

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

@@ -11,7 +11,7 @@ export interface OklchStop {
  * prop (the SVG-field surface owns its own color pipeline). The goo-blob no longer
  * injects it: it resolves color internally through `cssToOklch → oklchToGammaRgb`
  * (W-BLOB3 STRIPPED the speculative DI built for an absent value.js consumer that
- * never repatriated; see `docs/consumer-evidence/goo-blob.md`).
+ * never repatriated).
  */
 export type ColorResolver = (css: string) => [number, number, number];
 /**
@@ -121,6 +121,23 @@ export interface DeriveBlobPaletteOptions {
      * the constellation focal share (the set-cohesion accent identity).
      */
     chromaCeiling?: number;
+    /**
+     * BG.W-BLOB-SATELLITE-SHADE (F9.R1 — the `uSatColor[]` companion) — pin the BODY
+     * stop's OKLCh lightness. The default ramp centres L on the seed
+     * (`anchor.L - lightnessSpread/2` at the body, climbing `lightnessSpread` to the
+     * lightest satellite). When set, the body stop (t=0) anchors at exactly this L and
+     * the satellites still climb `lightnessSpread` from it — so a consumer picks the
+     * body luminance directly (the deep-body read) without moving the seed hue/chroma.
+     * `undefined` (the default) leaves the derivation byte-identical to HEAD.
+     */
+    bodyLightness?: number;
+    /**
+     * BG.W-BLOB-SATELLITE-SHADE (F9.R1) — the OKLCh-lightness FLOOR on every derived
+     * stop. Replaces the hardcoded `0.05` low clamp, so a consumer guarantees no stop
+     * reads darker than this (a body/satellite that never collapses toward black). The
+     * `0.98` high clamp is untouched. `undefined` → the byte-identical `0.05` floor.
+     */
+    lightnessFloor?: number;
 }
 /**
  * Seed ONE color into a harmonious, gamut-safe 2-4-stop OKLCh palette for the blob

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

@@ -18,17 +18,15 @@ export interface UseAccentToneReturn {
      *  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). */
+     *  reader — a canvas label, a test). `""` on the `var()` / unset fast path or
+     *  before the concrete-tone solve lands. */
     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.
+ * register. A `var(--…)` / unset tone is value.js-free (`""` ink, the CSS fallback);
+ * a concrete tone loads the value.js `./accent-tone-solve` leaf behind a dynamic
+ * import and upgrades the ink the next tick. PRM-irrelevant (a colour, not an
+ * animation). DOM-free + deterministic.
  */
 export declare function useAccentTone(tone: MaybeRefOrGetter<string>, opts?: UseAccentToneOptions): UseAccentToneReturn;

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

@@ -1,5 +1,6 @@
 export * from "./useResizeObserver";
 export * from "./useTouchGate";
+export * from "./useDragVelocity";
 export * from "./useTokenColor";
 export * from "./useResolveTokenColor";
 export * from "./useClipboard";

package/dist/composables/dom/useDragVelocity.d.ts

@@ -0,0 +1,46 @@
+import { type Ref } from "vue";
+export interface UseDragVelocityParams {
+    /**
+     * The host element resolver — a getter (NOT a ref Slider populates in a sibling
+     * `onMounted`) so it sidesteps the onMounted-ordering trap the slider's
+     * `useDockHold` already documents. The `--atom-drag-v` var is written on THIS
+     * element; descendants inherit it (the fill + the cast read it).
+     */
+    host: () => HTMLElement | null;
+    /**
+     * The pointer axis the velocity is measured on. Default `"x"` (the horizontal
+     * slider). A getter re-reads on an orientation flip.
+     */
+    axis?: "x" | "y" | (() => "x" | "y");
+    /**
+     * The saturating-smear gain (the `tanh` steepness over px/frame). Higher = the
+     * smear reaches its ceiling at a slower drag. Default `0.06`.
+     */
+    gain?: number;
+    /**
+     * The smear CEILING (the clamp the saturated value floors under). Default `0.7`
+     * (challenge #3 R3 — mass wins, the pull never rubber-bands past this).
+     */
+    clamp?: number;
+    /** Honor `prefers-reduced-motion: reduce` (no rAF, value pinned 0). Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseDragVelocityReturn {
+    /** True while a drag gesture is live (between `pointerdown` and `pointerup`). */
+    dragging: Readonly<Ref<boolean>>;
+    /** Detach all listeners + tear down any live rAF. Idempotent. */
+    detach: () => void;
+}
+/**
+ * The drag-window-gated velocity bridge — writes `--atom-drag-v` (0..1, bounded by a
+ * saturating `tanh`) on the host while a pointer drag is live, and tears the rAF DOWN
+ * on release (the no-idle-cost contract). The slider weight-train is its first
+ * consumer; any pull-to-smear atom reads the same var.
+ *
+ * @example
+ * ```ts
+ * const { dragging, detach } = useDragVelocity({ host: getRootEl })
+ * // CSS: .slider-range { transform: scaleX(calc(1 + 0.08 * var(--atom-drag-v))) }
+ * ```
+ */
+export declare function useDragVelocity(params: UseDragVelocityParams): UseDragVelocityReturn;

package/dist/composables/dom/useUserInvalidAria.d.ts

@@ -1,14 +1,10 @@
+/**
+ * Options for {@link useUserInvalidAria}. Empty since the legacy
+ * `fallbackClasses` knob was retired at BG.NF.2 W-LEGACY-LADDER-COLLAPSE
+ * (`:user-invalid` is Baseline on the target set); the shape is kept as the
+ * canonical options seam for future extension.
+ */
 export interface UseUserInvalidAriaOptions {
-    /**
-     * Also toggle the `.user-invalid-fallback` / `.user-valid-fallback`
-     * classes the W4.1 CSS rungs key off (for engines without `:user-invalid`
-     * support).
-     *
-     * Default: auto — `true` only when `CSS.supports('selector(:user-invalid)')`
-     * resolves `false`. Pass an explicit boolean to force the path (e.g. for a
-     * test that stubs feature detection).
-     */
-    fallbackClasses?: boolean;
 }
 export interface UseUserInvalidAriaReturn {
     /**
@@ -29,4 +25,4 @@ export interface UseUserInvalidAriaReturn {
  * the `input` handler only CLEARS — never sets — so a programmatic `v-model`
  * write can at worst clear a stale error, never mint a false one.
  */
-export declare function useUserInvalidAria(opts?: UseUserInvalidAriaOptions): UseUserInvalidAriaReturn;
+export declare function useUserInvalidAria(_opts?: UseUserInvalidAriaOptions): UseUserInvalidAriaReturn;

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

@@ -0,0 +1,27 @@
+/** A 12-bucket chroma×alpha-weighted OKLCh hue accumulator over the SAME pixel pass. */
+export interface HueHistogram {
+    /** chroma×alpha mass per hue bucket (the bucket weight). */
+    weight: Float64Array;
+    /** Σ chroma×alpha·cos(h) per bucket (for the circular-mean refine). */
+    sumCos: Float64Array;
+    /** Σ chroma×alpha·sin(h) per bucket. */
+    sumSin: Float64Array;
+    /** total chroma×alpha mass (the null-detection denominator numerator). */
+    totalMass: number;
+    /** total pixels accumulated (the null-mass denominator). */
+    n: number;
+}
+export declare function makeHueHistogram(): HueHistogram;
+/**
+ * Bin ONE sRGB pixel (composited triple, already over-white) into the histogram,
+ * weighted by its OKLCh chroma × the source alpha — a low-chroma/gray pixel
+ * contributes ~0. The sRGB→OKLCh math is value.js's primitives (NOT hand-rolled).
+ */
+export declare function accumulateHuePixel(h: HueHistogram, r: number, g: number, b: number, alpha: number): void;
+/**
+ * Resolve the histogram → a complete `oklch()` ambient-hue string, or `transparent`
+ * for a NULL (gray) sample. The modal bucket's chroma-weighted CIRCULAR MEAN is the
+ * picked hue; it is emitted at the FIXED sub-perceptual chroma/L (a HUE event, never
+ * the backdrop's saturation).
+ */
+export declare function resolveAmbientHue(h: HueHistogram): string;

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

@@ -0,0 +1,56 @@
+/** The per-sample result — the luminance AND the ambient hue (the FREE rider). */
+export interface SampleResult {
+    /** WCAG relative luminance of the sampled backdrop (0..1). */
+    luma: number;
+    /** A complete `oklch()` ambient-hue string, or `transparent` for a gray null. */
+    ambientHue: string;
+}
+/**
+ * The KNOWN background-layer source for the ANIMATED case — an HTMLCanvasElement, a
+ * getter, a CSS selector resolved against the document, or null. The observer's
+ * `backgroundCanvas` option is this type.
+ */
+export type BackgroundCanvasSource = HTMLCanvasElement | (() => HTMLCanvasElement | null) | string | null;
+/** The downsample resolution for the animated-field read (a 32×32 mean). */
+export declare const SAMPLE_DOWNSAMPLE = 32;
+export declare const FIELD_ALPHA_FLOOR = 0.02;
+/** BG.W-FIELD-ACCENT-RECONCILE — the library convention marking the ONE shell
+ *  field canvas (the recessive shell `<Aurora>` the demo chassis mounts behind every
+ *  non-focal route; also the WS8 BACKDROP-SAMPLE marker). A glass surface that does
+ *  NOT name an explicit `backgroundCanvas` auto-discovers this canvas so it samples
+ *  the LIVE field rather than a static stack-walk; absent it (a focal route where the
+ *  shell stands down, an SSR scope) the static `elementsFromPoint` path is the floor. */
+export declare const SHELL_FIELD_CANVAS_SELECTOR = "[data-glass-field-canvas] canvas, canvas[data-glass-field-canvas]";
+/**
+ * Resolve the animated-case source canvas from the observer's `backgroundCanvas`
+ * option (an element, a getter, a selector, or nullish). A nullish source
+ * auto-discovers the shell field canvas — the rewire to the live shell field
+ * (backward-safe: no field canvas → null → the static elementsFromPoint path).
+ */
+export declare function resolveSourceCanvas(src: BackgroundCanvasSource | undefined): HTMLCanvasElement | null;
+/**
+ * Robust CSS-color → sRGB `[r,g,b,a]`. `parseRgb` is the fast path for the legacy
+ * `rgb()/rgba()` serialization; ANY other valid CSS color form — the MODERN
+ * `oklch()` / `color(srgb …)` / `hsl()` tokens the warm-cream demo basis resolves to —
+ * is normalized by painting it onto the 1×1 corner of the reused 2D canvas (passed in)
+ * and reading the composited pixel back (`getImageData` ALWAYS returns integer sRGB
+ * whatever the source space). BG.W-GLASS-SIGNAL-TRUTH: without this `sampleStatic`
+ * returned null on a `color(srgb …)`/`oklch(…)` backdrop and wrote NOTHING — the static
+ * floor was a DEAD channel. The static floor is now writer-true over ANY backdrop.
+ */
+export declare function normalizeToRgb(css: string, ctx: CanvasRenderingContext2D | null): [number, number, number, number] | null;
+/**
+ * Sample the ANIMATED backdrop: downsample the resolved source canvas under the
+ * surface's bounding box → mean relative luminance + the ambient-hue histogram (a FREE
+ * rider over the SAME pixel pass). Returns null if no source / an all-transparent
+ * (unrendered) field / a tainted canvas — the caller falls to the static stack-walk.
+ */
+export declare function sampleAnimated(el: HTMLElement, source: HTMLCanvasElement | null, ctx: CanvasRenderingContext2D | null): SampleResult | null;
+/**
+ * Sample the STATIC backdrop: stack-walk `elementsFromPoint` at the surface centre,
+ * read the first element under it with a resolved non-transparent background, un-wrap
+ * the `var(--token)` through the resolveTokenColor leaf → relative luminance + the
+ * ambient hue (the single resolved background color binned the SAME way). The reusable
+ * 2D context (for the modern-color normalization paint-read) is passed in.
+ */
+export declare function sampleStatic(el: HTMLElement, ctx: CanvasRenderingContext2D | null): SampleResult | null;

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

@@ -0,0 +1,5 @@
+/** WCAG relative luminance of an sRGB triple [0..255]. */
+export declare function relLuminance(r: number, g: number, b: number): number;
+/** Parse a `rgb()/rgba()` string → [r,g,b,a] (the un-wrapped concrete form). */
+export declare function parseRgb(str: string): [number, number, number, number] | null;
+export declare function isCanvas(v: unknown): v is HTMLCanvasElement;

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

@@ -0,0 +1,91 @@
+/**
+ * The ONE shared texture-upload primitive (BG.W-AUR-IMAGE-SOURCE).
+ *
+ * A photo entering a dual-engine (WebGL2 + WebGPU) shader family has ONE genuine
+ * cross-engine hazard: the WebGL2 and WebGPU uploads DIFFER on premultiply /
+ * colour-space / flip-Y defaults (gpuweb #4356; Safari's
+ * `copyExternalImageToTexture(ImageBitmap)` history). Left ad-hoc per site it bites
+ * invisibly and per-backend. This module NORMALISES the decode + declares the SAME
+ * flag set EXPLICITLY on both upload legs, so a texture reads identically on Chromium
+ * and WebKit — the single seam every image-consuming viz routes through.
+ *
+ * The ≥2-consumer bar is met by construction: `<Aurora source="image">` is consumer
+ * #1 (this wave BUILDS the seam); `BD.W-DOT-IMAGE` (the dot-matrix image variant) is
+ * the booked consumer #2 — whichever landed first BUILDS it, the other CONSUMES it
+ * (the first-to-land-builds contract). Recorded in
+ * `docs/consumer-evidence/texture-upload.md`.
+ *
+ * INTERNAL — off the public `src/composables/glass/index.ts` barrel (the WebGL2 /
+ * WebGPU substrates are likewise): aurora + dot-image compose it via a direct
+ * relative import.
+ *
+ * The decode contract (BOTH legs share it):
+ *   `createImageBitmap(blob, { premultiplyAlpha: "none", colorSpaceConversion: "none" })`
+ * so the decoded bytes are raw sRGB-encoded, un-premultiplied — the shader owns the
+ * sRGB→linear transfer + the premultiply-on-display, exactly like the procedural path.
+ */
+/** The shared decode options — the ONE normalised `createImageBitmap` flag set. */
+export declare const IMAGE_DECODE_OPTIONS: ImageBitmapOptions;
+/**
+ * An already-uploadable image source — a decoded bitmap or a live DOM raster that
+ * both `gl.texImage2D` and `queue.copyExternalImageToTexture` accept directly.
+ */
+export type UploadableImageSource = ImageBitmap | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageData;
+/**
+ * Anything a consumer may hand the axis: a URL string / `Blob` (needs a decode) OR an
+ * already-uploadable source (passed straight through). `resolveImageSource` normalises
+ * every form to an {@link UploadableImageSource} via the shared decode contract.
+ */
+export type ImageInputSource = UploadableImageSource | Blob | string;
+/**
+ * Decode a `Blob` to an `ImageBitmap` through the shared normalised flag set. The
+ * single decode home — a consumer NEVER re-spells `createImageBitmap` with its own
+ * (divergent) options.
+ */
+export declare function decodeImageBitmap(blob: Blob): Promise<ImageBitmap>;
+/**
+ * Normalise any {@link ImageInputSource} to an uploadable source. A URL string is
+ * fetched → blob → decoded; a `Blob` is decoded; an already-uploadable source is
+ * returned as-is. Deterministic + DOM-light (only the URL path touches `fetch`).
+ */
+export declare function resolveImageSource(src: ImageInputSource): Promise<UploadableImageSource>;
+/**
+ * A 1×1 mid-grey placeholder source — the texture a `source:"image"` program samples
+ * BEFORE its real photo has decoded (so the sampler is always complete + the first frame
+ * is a neutral wash, never black garbage). Routed through the SAME upload primitive so
+ * texture creation has exactly ONE home (the anti-evasion floor). DOM-only (`ImageData`).
+ */
+export declare function placeholderImageSource(): ImageData;
+/** The intrinsic pixel dimensions of an uploadable source (both legs size the texture from it). */
+export declare function imageSourceDimensions(src: UploadableImageSource): {
+    width: number;
+    height: number;
+};
+/** WebGL2 upload options — the sampling register the texture is created with. */
+export interface WebGL2TextureOptions {
+    /** Min/mag filter. Default `LINEAR` (the smooth-bokeh dissolve register). */
+    linearFilter?: boolean;
+    /** Wrap mode. Default `CLAMP_TO_EDGE` (a cover-fit backdrop never tiles). */
+    clampToEdge?: boolean;
+}
+/**
+ * Upload an image into a fresh WebGL2 texture through the shared explicit flag set.
+ * Returns the bound texture (the caller sets the sampler uniform to its unit + binds
+ * it per draw). The premultiply/colour-space/flip-Y flags are declared explicitly,
+ * then restored so the primitive leaves no global GL residue.
+ */
+export declare function uploadImageTextureWebGL2(gl: WebGL2RenderingContext, source: UploadableImageSource, opts?: WebGL2TextureOptions): WebGLTexture;
+export interface WebGPUImageTexture {
+    texture: GPUTexture;
+    width: number;
+    height: number;
+}
+/**
+ * Upload an image into a fresh WebGPU texture through the shared explicit flag set.
+ * The `copyExternalImageToTexture` destination declares `premultipliedAlpha: false`
+ * EXPLICITLY (the WebGPU twin of the WebGL2 `UNPACK_PREMULTIPLY_ALPHA_WEBGL:false`) and
+ * the source declares `flipY: false` — so the decoded bytes land in the texture
+ * byte-identically to the WebGL2 leg (the cross-engine parity contract). Returns the
+ * texture + its dims (the caller builds the sampler + the bind group entry).
+ */
+export declare function uploadImageTextureWebGPU(device: GPUDevice, source: UploadableImageSource): WebGPUImageTexture;

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

@@ -1,4 +1,5 @@
 import { type Ref } from "vue";
+import { type BackgroundCanvasSource } from "./backdropLuminanceSample";
 /** The discrete bucket the observer derives + writes (re-engages the W55 machinery). */
 export type GlassBackdropBucket = "light" | "dark";
 export interface UseGlassBackdropLuminanceOptions {
@@ -9,7 +10,7 @@ export interface UseGlassBackdropLuminanceOptions {
      * instead of the static `elementsFromPoint` stack-walk. The aurora/blob `<canvas>`
      * the surface floats over.
      */
-    backgroundCanvas?: HTMLCanvasElement | (() => HTMLCanvasElement | null) | string | null;
+    backgroundCanvas?: BackgroundCanvasSource;
     /**
      * Force the LIVE periodic re-sample loop on (mirrors the `data-glass-sample="live"`
      * attribute on the target). Default: read from the target's
@@ -35,6 +36,17 @@ export interface UseGlassBackdropLuminanceOptions {
      * `--glass-backdrop-luma` is written (a continuous-strength consumer).
      */
     writeBucket?: boolean;
+    /**
+     * BI.W-DOCK-LUMA-SHARE — mark this as the SHARED per-ROUTE observer. It stamps
+     * `GLASS_BACKDROP_SHARED_ATTR` on its target (the route/stage scope) so descendant
+     * glass surfaces (docks) DETECT the coverage and STAND DOWN — inheriting the route's
+     * `--glass-backdrop-luma` / `--glass-backdrop` / `--glass-ambient-*` via the cascade
+     * rather than each mounting its own readback loop (12 per-dock observers over ONE
+     * aurora → ONE per-route readback). Default false: a per-SURFACE observer, which
+     * stands down when a shared ancestor covers it and self-samples as the honest floor
+     * when standalone. N docks over the SAME aurora read ONE per-route signal.
+     */
+    shared?: boolean;
 }
 export interface UseGlassBackdropLuminanceControls {
     /** The last sampled backdrop relative luminance (0..1), or null before the first sample. */
@@ -46,6 +58,20 @@ export interface UseGlassBackdropLuminanceControls {
     /** Stop the loop + detach every observer/listener. */
     dispose: () => void;
 }
+/**
+ * BI.W-DOCK-LUMA-SHARE — the shared-coverage marker. A SHARED route observer
+ * (`shared: true`) stamps this attribute on its target (the route/stage scope); a
+ * per-SURFACE observer detects it on an ANCESTOR (`.closest`) and STANDS DOWN —
+ * inheriting the route's `--glass-backdrop-luma` / `--glass-backdrop` /
+ * `--glass-ambient-*` via the registered inheriting @property cascade instead of
+ * mounting its OWN `drawImage + getImageData` readback loop (the 12 per-dock observers
+ * over ONE DockStage aurora collapse to ONE per-route readback — PERF-6/FAM-5). A DOM
+ * marker, NOT provide/inject: provide/inject does not cross the `<slot>` boundary (the
+ * DockStage renders `<slot>`, the docks are slotted from the route, so the slotted
+ * content's instance-parent is the slot OWNER not the stage), and the marker rides the
+ * SAME DOM ancestry the inheriting custom property itself cascades over.
+ */
+export declare const GLASS_BACKDROP_SHARED_ATTR = "data-glass-backdrop-shared";
 /**
  * The sampled-luminance observer. Wire it on a glass surface (the dock root, a
  * content-glass panel) to write a DYNAMIC backdrop-luminance signal that refines the

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

@@ -1,4 +1,4 @@
-import { ref, type CSSProperties } from "vue";
+import { type ComputedRef, type CSSProperties, type MaybeRefOrGetter } from "vue";
 /**
  * `useSpecularPointer` — the EVOLUTION of `useSpecularTracking` (BB.W-LENSING). It
  * writes the catch-light POSITION (`--mouse-x`/`--mouse-y`, as today) PLUS the
@@ -23,11 +23,30 @@ import { ref, type CSSProperties } from "vue";
  * 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.
+ *
+ * BG.W-GLASS-DYNAMICS — the OPTIONAL press-couple (absorbs 13.5, soft-gated by F5.1).
+ * A consumer may pass `press` (a 0..1 press scalar — a `useSpringPress` `.value`, or
+ * any press signal); it is folded reactively into the emitted style as the ONE
+ * `--glass-btn-press-t` channel the `.glass-material::before` specular magnitude reads
+ * (material.css). Reusing the SINGLE press channel (never a forked `--*-press-t`) keeps
+ * ONE drive, two legs — the gleam SWELLS + SETTLES with the press spring. The merge is
+ * a `computed` so the press tracks the spring INDEPENDENTLY of pointer moves (a press
+ * settles while the pointer is still). SOFT-GATED: when `press` is OMITTED the emitted
+ * style carries NO press channel (the CSS `--glass-btn-press-t` default 0 holds — no
+ * hard F5.1 dependency), and the position/angle write is byte-identical to before.
  */
+export interface UseSpecularPointerOptions {
+    /** Optional 0..1 press scalar (soft-gated) folded into `--glass-btn-press-t`. */
+    press?: MaybeRefOrGetter<number>;
+}
 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 element's `:style`. Carries `--mouse-x/--mouse-y` +
+     * `--specular-angle` (+ the press-coupled `--glass-btn-press-t` when `press` is
+     * supplied).
+     */
+    specularStyle: ComputedRef<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;
+export declare function useSpecularPointer(options?: UseSpecularPointerOptions): UseSpecularPointer;

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

@@ -2,7 +2,7 @@ import { ref, type CSSProperties } from "vue";
 /**
  * `useSpecularTracking` — the pointer-anchored moving-specular write seam
  * (AX.W09). The single DRY home for the catch-light position write that was
- * hand-copied VERBATIM in `Card.vue` and `DockIconButton.vue`.
+ * hand-copied VERBATIM in `Card.vue` and `DockControl.vue`.
  *
  * On pointer-move it writes the cursor position (`--mouse-x`/`--mouse-y`, as
  * percentages of the host box) onto the host's inline style; the unified

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

@@ -0,0 +1,4 @@
+export type { Vec2, CellDriver } from "./waveField";
+export { travelingEnvelope, curlScalar, cellTwist, cellDriver, cellHeight, faceRelief, facePlateau, waveFlow, cursorSwirl, heightField, waveSwell, cellWarpBeforeHeight, } from "./waveField";
+export { WAVE_FIELD_GLSL } from "./waveField.glsl";
+export { WAVE_FIELD_WGSL } from "./waveField.wgsl";