@mkbabb/glass-ui 4.2.0 → 5.0.0

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

@@ -0,0 +1,9 @@
+export { default as Toast } from './Toast.vue';
+export { default as ToastAction } from './ToastAction.vue';
+export { default as ToastClose } from './ToastClose.vue';
+export { default as ToastDescription } from './ToastDescription.vue';
+export { default as ToastTitle } from './ToastTitle.vue';
+export { default as Toaster } from './Toaster.vue';
+export { toast, useToast } from './use-toast';
+export type { Toast as ToastType } from './use-toast';
+export type { ToasterPosition } from './Toaster.vue';

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

@@ -0,0 +1,182 @@
+import type { Component, VNode } from 'vue';
+import type { Surface } from '../_shared/useSurfaceAxis';
+import type { Tone } from '../_shared/axes';
+export interface Toast {
+    id: string;
+    title?: string;
+    description?: string;
+    action?: Component | VNode;
+    tone?: Tone;
+    /**
+     * 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
+     * toast open until dismissed.
+     */
+    duration?: number;
+}
+type ToasterToast = Toast & {
+    id: string;
+    title?: string;
+    description?: string;
+    action?: Component | VNode;
+    open?: boolean;
+    'onUpdate:open'?: (open: boolean) => void;
+};
+type ToastOptions = Omit<ToasterToast, 'id'>;
+declare function toast(props: ToastOptions): {
+    id: string;
+    dismiss: () => void;
+    update: (props: ToasterToast) => void;
+};
+declare function useToast(): {
+    toasts: import("vue").ComputedRef<{
+        id: string;
+        title?: string | undefined;
+        description?: string | undefined;
+        action?: VNode<import("vue").RendererNode, import("vue").RendererElement, {
+            [key: string]: any;
+        }> | import("vue").FunctionalComponent<any, {}, any, {}> | {
+            new (...args: any[]): any;
+            __isFragment?: never;
+            __isTeleport?: never;
+            __isSuspense?: never;
+        } | {
+            [x: string]: any;
+            setup?: ((this: void, props: import("@vue/shared").LooseRequired<any>, ctx: {
+                attrs: import("vue").Attrs;
+                slots: Readonly<{
+                    [name: string]: import("vue").Slot<any> | undefined;
+                }>;
+                emit: ((event: unknown, ...args: any[]) => void) | ((event: string, ...args: any[]) => void);
+                expose: <Exposed extends Record<string, any> = Record<string, any>>(exposed?: Exposed) => void;
+            }) => any) | undefined;
+            name?: string | undefined;
+            template?: string | object | undefined;
+            render?: Function | undefined;
+            components?: Record<string, Component<any, any, any, import("vue").ComputedOptions, import("vue").MethodOptions, {}, any>> | undefined;
+            directives?: Record<string, import("vue").Directive<any, any, string, any>> | undefined;
+            inheritAttrs?: boolean | undefined;
+            emits?: any;
+            slots?: {} | undefined;
+            expose?: string[] | undefined;
+            serverPrefetch?: (() => void | Promise<any>) | undefined;
+            compilerOptions?: {
+                isCustomElement?: ((tag: string) => boolean) | undefined;
+                whitespace?: "preserve" | "condense" | undefined;
+                comments?: boolean | undefined;
+                delimiters?: [string, string] | undefined;
+            } | undefined;
+            call?: ((this: unknown, ...args: unknown[]) => never) | undefined;
+            __isFragment?: never | undefined;
+            __isTeleport?: never | undefined;
+            __isSuspense?: never | undefined;
+            __defaults?: {} | undefined;
+            compatConfig?: {
+                GLOBAL_MOUNT?: boolean | "suppress-warning" | undefined;
+                GLOBAL_MOUNT_CONTAINER?: boolean | "suppress-warning" | undefined;
+                GLOBAL_EXTEND?: boolean | "suppress-warning" | undefined;
+                GLOBAL_PROTOTYPE?: boolean | "suppress-warning" | undefined;
+                GLOBAL_SET?: boolean | "suppress-warning" | undefined;
+                GLOBAL_DELETE?: boolean | "suppress-warning" | undefined;
+                GLOBAL_OBSERVABLE?: boolean | "suppress-warning" | undefined;
+                GLOBAL_PRIVATE_UTIL?: boolean | "suppress-warning" | undefined;
+                CONFIG_SILENT?: boolean | "suppress-warning" | undefined;
+                CONFIG_DEVTOOLS?: boolean | "suppress-warning" | undefined;
+                CONFIG_KEY_CODES?: boolean | "suppress-warning" | undefined;
+                CONFIG_PRODUCTION_TIP?: boolean | "suppress-warning" | undefined;
+                CONFIG_IGNORED_ELEMENTS?: boolean | "suppress-warning" | undefined;
+                CONFIG_WHITESPACE?: boolean | "suppress-warning" | undefined;
+                CONFIG_OPTION_MERGE_STRATS?: boolean | "suppress-warning" | undefined;
+                INSTANCE_SET?: boolean | "suppress-warning" | undefined;
+                INSTANCE_DELETE?: boolean | "suppress-warning" | undefined;
+                INSTANCE_DESTROY?: boolean | "suppress-warning" | undefined;
+                INSTANCE_EVENT_EMITTER?: boolean | "suppress-warning" | undefined;
+                INSTANCE_EVENT_HOOKS?: boolean | "suppress-warning" | undefined;
+                INSTANCE_CHILDREN?: boolean | "suppress-warning" | undefined;
+                INSTANCE_LISTENERS?: boolean | "suppress-warning" | undefined;
+                INSTANCE_SCOPED_SLOTS?: boolean | "suppress-warning" | undefined;
+                INSTANCE_ATTRS_CLASS_STYLE?: boolean | "suppress-warning" | undefined;
+                OPTIONS_DATA_FN?: boolean | "suppress-warning" | undefined;
+                OPTIONS_DATA_MERGE?: boolean | "suppress-warning" | undefined;
+                OPTIONS_BEFORE_DESTROY?: boolean | "suppress-warning" | undefined;
+                OPTIONS_DESTROYED?: boolean | "suppress-warning" | undefined;
+                WATCH_ARRAY?: boolean | "suppress-warning" | undefined;
+                PROPS_DEFAULT_THIS?: boolean | "suppress-warning" | undefined;
+                V_ON_KEYCODE_MODIFIER?: boolean | "suppress-warning" | undefined;
+                CUSTOM_DIR?: boolean | "suppress-warning" | undefined;
+                ATTR_FALSE_VALUE?: boolean | "suppress-warning" | undefined;
+                ATTR_ENUMERATED_COERCION?: boolean | "suppress-warning" | undefined;
+                TRANSITION_CLASSES?: boolean | "suppress-warning" | undefined;
+                TRANSITION_GROUP_ROOT?: boolean | "suppress-warning" | undefined;
+                COMPONENT_ASYNC?: boolean | "suppress-warning" | undefined;
+                COMPONENT_FUNCTIONAL?: boolean | "suppress-warning" | undefined;
+                COMPONENT_V_MODEL?: boolean | "suppress-warning" | undefined;
+                RENDER_FUNCTION?: boolean | "suppress-warning" | undefined;
+                FILTERS?: boolean | "suppress-warning" | undefined;
+                PRIVATE_APIS?: boolean | "suppress-warning" | undefined;
+                MODE?: 2 | 3 | ((comp: Component | null) => 2 | 3) | undefined;
+            } | undefined;
+            data?: ((this: any, vm: any) => any) | undefined;
+            computed?: import("vue").ComputedOptions | undefined;
+            methods?: import("vue").MethodOptions | undefined;
+            watch?: {
+                [x: string]: (string | import("vue").WatchCallback | ({
+                    handler: import("vue").WatchCallback | string;
+                } & import("vue").WatchOptions<boolean>)) | (string | import("vue").WatchCallback | ({
+                    handler: import("vue").WatchCallback | string;
+                } & import("vue").WatchOptions<boolean>))[];
+            } | undefined;
+            provide?: import("vue").ComponentProvideOptions | undefined;
+            inject?: {} | string[] | undefined;
+            filters?: Record<string, Function> | undefined;
+            mixins?: any[] | undefined;
+            extends?: any;
+            beforeCreate?: (() => any) | undefined;
+            created?: (() => any) | undefined;
+            beforeMount?: (() => any) | undefined;
+            mounted?: (() => any) | undefined;
+            beforeUpdate?: (() => any) | undefined;
+            updated?: (() => any) | undefined;
+            activated?: (() => any) | undefined;
+            deactivated?: (() => any) | undefined;
+            beforeDestroy?: (() => any) | undefined;
+            beforeUnmount?: (() => any) | undefined;
+            destroyed?: (() => any) | undefined;
+            unmounted?: (() => any) | undefined;
+            renderTracked?: ((e: import("vue").DebuggerEvent) => void) | undefined;
+            renderTriggered?: ((e: import("vue").DebuggerEvent) => void) | undefined;
+            errorCaptured?: ((err: unknown, instance: import("vue").ComponentPublicInstance | null, info: string) => boolean | void) | undefined;
+            delimiters?: [string, string] | undefined;
+            __differentiator?: string | number | symbol | undefined;
+            __isBuiltIn?: boolean | undefined;
+            __file?: string | undefined;
+            __name?: string | undefined;
+        } | undefined;
+        tone?: Tone
+        /**
+         * 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
+         * toast open until dismissed.
+         */
+         | undefined;
+        duration?: number | undefined;
+        open?: boolean | undefined;
+        'onUpdate:open'?: ((open: boolean) => void) | undefined;
+    }[]>;
+    toast: typeof toast;
+    dismiss: (toastId?: string) => void;
+};
+export { toast, useToast };

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/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/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