@mkbabb/glass-ui 6.0.0 → 8.0.0

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

@@ -18,9 +18,9 @@ export interface UseBreakpointControls {
  * permanently-`false` ref. Consumers should treat the initial frame as
  * "mobile-first / narrow-default" because the matchMedia subscription only
  * mounts client-side. This is the same shape consumers wrote by hand at the
- * speedtest origin sites.
+ * consumer origin sites.
  *
- * Why this exists (speedtest origin, glass-ui promotion W6-β): the survey
+ * Why this exists (promoted from a consumer): the survey
  * cockpit (`SurveyWizard.vue`) and the admin data-source toggle
  * (`AdminDataSourceToggle.vue`) both hand-rolled the same `matchMedia`
  * subscribe-on-mount + tear-down-on-unmount pattern. Two hand-rolls of one

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

@@ -1,68 +1,44 @@
-import { type Ref } from "vue";
-/**
- * Why a copy did not succeed. `'clipboard-api'` — the async
- * `navigator.clipboard.writeText` channel threw or rejected; `'exec-command'`
- * — the legacy `document.execCommand("copy")` fallback returned/threw failure;
- * `'no-api'` — neither channel exists in this environment (SSR / locked-down).
- */
-export type CopyFailureReason = "clipboard-api" | "exec-command" | "no-api";
+import { type ComputedRef } from "vue";
+export type CopyFailureReason = "clipboard-api" | "no-api";
+export type ClipboardStatus = "idle" | "pending" | "success" | "failure";
 export interface UseClipboardOptions {
-    /** Milliseconds before `copied` auto-resets to `false` (default 1500). */
+    /** Milliseconds before a successful copy resets to `idle` (default 1500). */
     resetMs?: number;
     /**
-     * Called with the NAMED reason when a copy attempt fails on a given
-     * channel. Both the clipboard-API and exec-command arms report through this
-     * (the exec-command arm only after the clipboard-API arm has already
-     * failed). Surfaces the failure instead of swallowing it.
+     * Optional watchdog: a write that has not settled within this many ms is
+     * reported as a `clipboard-api` failure (some platforms leave `writeText`
+     * pending forever). Default: no timeout.
      */
+    timeoutMs?: number;
+    /** Called when the current active copy attempt fails. */
     onCopyError?: (reason: CopyFailureReason) => void;
 }
-/** Result of a composable `copy()` — the success flag plus, on failure, the
- *  named reason the copy did not land. */
-export interface CopyResult {
-    ok: boolean;
-    /** The failure channel when `ok` is false; `undefined` on success. */
-    reason?: CopyFailureReason;
-}
+/** A failed copy always names its channel; a successful copy carries no reason. */
+export type CopyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: CopyFailureReason;
+};
 export interface UseClipboardReturn {
-    /** Reactive flag—flips `true` on successful copy, auto-resets after `resetMs`. */
-    copied: Ref<boolean>;
-    /**
-     * Copy `text` to the clipboard. Resolves `{ ok }` on success or
-     * `{ ok: false, reason }` naming the channel that failed — the failure is
-     * REPORTED, never silently swallowed.
-     */
+    /** The current active attempt's complete feedback state. */
+    status: ComputedRef<ClipboardStatus>;
+    /** Copy `text`, returning a named failure when the platform rejects it. */
     copy: (text: string) => Promise<CopyResult>;
+    /** Invalidate pending or settled feedback because its payload is no longer current. */
+    invalidate: () => void;
 }
 /**
- * Bare clipboard copy—stateless `Promise<boolean>` return, no reactive `copied`
- * flag. Use this when call sites manage their own confirmation state (e.g.
- * hand-rolled `ref + setTimeout`) or in non-component contexts (utility
- * modules, stores). A copy failure is reported through `options.onCopyError`
- * (the boolean return stays the verbatim cross-repo signature).
- *
- * @example
- * import { copyToClipboard } from "@mkbabb/glass-ui";
- *
- * async function shareLink(url: string) {
- *   const ok = await copyToClipboard(url, {
- *     onCopyError: (reason) => toast.show(`Copy failed: ${reason}`),
- *   });
- *   if (ok) toast.show("Link copied");
- * }
+ * Stateless one-shot clipboard write — the honest primitive shared by
+ * `useClipboard` and by consumers that own their own feedback. Returns the
+ * discriminated result (`{ ok }` / `{ ok, reason }`) rather than a lossy
+ * boolean, for identical call ergonomics: `const { ok } = await writeClipboard(text)`.
  */
-export declare function copyToClipboard(text: string, options?: UseClipboardOptions): Promise<boolean>;
+export declare function writeClipboard(text: string): Promise<CopyResult>;
 /**
- * Reactive clipboard copy with auto-reset confirmation flag.
- *
- * @example
- * const { copied, copy } = useClipboard();
- * <button @click="copy(value)">
- *   {{ copied ? "Copied" : "Copy" }}
- * </button>
+ * Reactive clipboard copy with scope-owned confirmation state.
  *
  * @example
- * // Custom reset window (e.g. for paired toast feedback):
- * const { copied, copy } = useClipboard({ resetMs: 2000 });
+ * const { status, copy } = useClipboard({ resetMs: 2000 });
  */
 export declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;

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

@@ -1,6 +1,6 @@
 import { type Ref } from "vue";
 /**
- * Scope-aware `document.visibilityState` leaf (AV.W14) — the single source for
+ * Scope-aware `document.visibilityState` leaf: the single source for
  * the `visibilitychange → document.hidden` pattern that the motion composables
  * (`useRAFLoop`, `useIntersectionPause`) and the WebGL substrate hand-rolled
  * four times over. Returns a `Ref<boolean>` `hidden` that flips on
@@ -16,5 +16,7 @@ import { type Ref } from "vue";
 export interface UseDocumentVisibilityReturn {
     /** Reactive `document.hidden` — `false` under SSR / when the API is absent. */
     hidden: Ref<boolean>;
+    /** Detach the visibility listener before scope teardown. */
+    dispose: () => void;
 }
 export declare function useDocumentVisibility(): UseDocumentVisibilityReturn;

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

@@ -7,6 +7,13 @@ export interface UseDragVelocityParams {
      * element; descendants inherit it (the fill + the cast read it).
      */
     host: () => HTMLElement | null;
+    /**
+     * A SECOND element that receives the same two writes. A teleported organ (the
+     * slider's loupe) is out of the host's inheritance chain, so it cannot read the
+     * vars off an ancestor — and minting a second velocity pole for it would break the
+     * one-owner law. One writer, two hosts.
+     */
+    mirror?: () => HTMLElement | null;
     /**
      * The pointer axis the velocity is measured on. Default `"x"` (the horizontal
      * slider). A getter re-reads on an orientation flip.

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

@@ -2,8 +2,8 @@ import { type Ref } from "vue";
 export interface UseIdleReadyOptions {
     /**
      * `requestIdleCallback` timeout, in ms. Default 2_000 — the canonical
-     * value at every speedtest hand-rolled site (App.vue + useIPInfo both
-     * pass `{ timeout: 2000 }`). Unlike useViewportReady's 10s (which fronts
+     * value at every hand-rolled consumer site (consumers pass
+     * `{ timeout: 2000 }`). Unlike useViewportReady's 10s (which fronts
      * the budget with an IO gate), useIdleReady has no visibility stage, so
      * the timeout is the only ceiling — 2s matches the consumer sites and
      * keeps the deferred work inside a reasonable post-paint window.
@@ -50,10 +50,9 @@ export interface UseIdleReadyControls {
  * a composable not a component). SSR / non-browser flips synchronously so
  * consumers don't stall.
  *
- * Why this exists (speedtest origin, glass-ui promotion AO.W3): the gate is
- * hand-rolled at 5 speedtest sites (App.vue, MapView.vue, DashboardMap.vue,
- * useAutoStart.ts, useIPInfo.ts) — the ≥2-consumer substrate-promotion gate
- * (J inv 10 / L inv 8) fires for a publisher-side absorption.
+ * This gate is
+ * hand-rolled at 5 consumer sites — the ≥2-consumer substrate-promotion gate
+ * fires for a publisher-side absorption.
  *
  * @param options.timeout Default `2000` ms — forwarded to `requestIdleCallback`.
  * @param options.onReady Optional one-shot task run on the idle flip.

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

@@ -1,6 +1,6 @@
 import { type MaybeRefOrGetter, type Ref } from "vue";
 /**
- * The resolver seam (AW.W15) — given a property name + the resolved element,
+ * Given a property name and resolved element,
  * return the property's value. Defaults to the live
  * `getComputedStyle(el).getPropertyValue(prop)` read; an injected resolver lets
  * SSR / tests close the DI loop without touching `document.documentElement`.
@@ -12,7 +12,7 @@ export interface UseTokenColorOptions {
     /** Fallback when the property is unset or `document` is unavailable (SSR). */
     fallback?: string;
     /**
-     * Injected property resolver (AW.W15 DI seam). Defaults to the live
+     * Injected property resolver. Defaults to the live
      * `getComputedStyle(el).getPropertyValue(prop)` read. Pass a custom resolver
      * for SSR / tests / a themed-context override without reaching the DOM.
      */

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

@@ -1,7 +1,6 @@
 /**
- * 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
+ * Options for {@link useUserInvalidAria}. Empty because `:user-invalid` is
+ * Baseline on the target set (no `fallbackClasses` knob); the shape is the
  * canonical options seam for future extension.
  */
 export interface UseUserInvalidAriaOptions {

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

@@ -31,7 +31,7 @@ export interface UseViewportReadyOptions {
     idleTimeout?: number;
     /**
      * IntersectionObserver `threshold`. Default 0.01 (1 % visible). Mirrors
-     * the speedtest origin-site semantic — "any pixel visible counts".
+     * the origin-site semantic — "any pixel visible counts".
      */
     threshold?: number;
 }
@@ -62,11 +62,11 @@ export interface UseViewportReadyControls {
  * disposal (mirrors `useResizeObserver` / `useInterval` upstream); outside
  * a scope callers receive the manual `stop()` control.
  *
- * Why this exists (speedtest origin, glass-ui promotion AJ.W6-α): both
+ * Both
  * `AdminOverviewView` and `ChartsView` shipped a near-identical `chartReady`
- * flag flipped by `requestIdleCallback` alone. The W3-R1 idiom in those
+ * flag flipped by `requestIdleCallback` alone. The idiom in those
  * sites — gate visibility first, then schedule rIC inside the IO callback —
- * is generic across heavy-widget hydration; the speedtest 2-consumer trigger
+ * is generic across heavy-widget hydration; the 2-consumer trigger
  * fired for a publisher-side absorption per `feedback_generic_components`.
  *
  * Usage:

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

@@ -1,9 +1,7 @@
-/** The per-sample result — the luminance AND the ambient hue (the FREE rider). */
+/** The per-sample result — the luminance, the one signal the cascade reads. */
 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
@@ -14,9 +12,9 @@ export type BackgroundCanvasSource = HTMLCanvasElement | (() => HTMLCanvasElemen
 /** 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
+/** Library convention marking the single 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
+ *  non-focal route; also the 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. */
@@ -29,28 +27,29 @@ export declare const SHELL_FIELD_CANVAS_SELECTOR = "[data-glass-field-canvas] ca
  */
 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.
+ * Sample the ANIMATED backdrop: downsample the resolved source canvas under the
+ * surface's bounding box → mean relative luminance. Returns null if no source, an all-transparent
+ * (unrendered) field, or a tainted canvas — the live caller writes `unavailable` on a
+ * null; it NEVER falls to the static stack-walk (that coalescing is forbidden).
+ *
+ * The field canvas is TRANSLUCENT, so each downsampled pixel is composited over the
+ * REAL opaque page `underlay` (resolved by `resolveUnderlayRgb` from the same stack the
+ * static sampler reads) — the same translucent field over a dark page vs a light page
+ * yields DISTINCT luma. Passing a fixed white underlay collapses that distinction and
+ * is the born-RED this repairs. The underlay feeds the EXISTING luma→tint axis; it is
+ * NOT a second opacity/attenuation axis.
  */
-export declare function normalizeToRgb(css: string, ctx: CanvasRenderingContext2D | null): [number, number, number, number] | null;
+export declare function sampleAnimated(el: HTMLElement, source: HTMLCanvasElement | null, ctx: CanvasRenderingContext2D | null, underlay: readonly [number, number, number]): SampleResult | 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.
+ * The REAL opaque page underlay beneath the surface — the color the TRANSLUCENT
+ * animated field composites OVER. Reuses `resolveBackdropRgba` (the same stack the
+ * static sampler reads), dropping alpha to an opaque triple; falls back to the
+ * CSS-initial white viewport when nothing opaque paints under the surface. This is the
+ * luma→tint axis input for `sampleAnimated`, NOT a second opacity/attenuation axis.
  */
-export declare function sampleAnimated(el: HTMLElement, source: HTMLCanvasElement | null, ctx: CanvasRenderingContext2D | null): SampleResult | null;
+export declare function resolveUnderlayRgb(el: HTMLElement, ctx: CanvasRenderingContext2D | null): [number, number, number];
 /**
- * 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.
+ * Sample the STATIC backdrop: reduce the resolved backdrop (`resolveBackdropRgba`) to
+ * relative luminance. The reusable 2D context is passed in.
  */
 export declare function sampleStatic(el: HTMLElement, ctx: CanvasRenderingContext2D | null): SampleResult | null;

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

@@ -1,5 +1,15 @@
 /** WCAG relative luminance of an sRGB triple [0..255]. */
 export declare function relLuminance(r: number, g: number, b: number): number;
+/**
+ * Composite a straight-alpha sRGB pixel [r,g,b] at coverage `a` (0..1) OVER an
+ * opaque sRGB `underlay` triple → the resolved opaque sRGB [r,g,b] (source-over).
+ * The animated field is a TRANSLUCENT canvas; the perceived backdrop is the field
+ * painted over the REAL opaque page beneath it, so the underlay MUST be the actual
+ * page color — a dark page and a light page under the SAME translucent field yield
+ * DISTINCT composited luma. A hardcoded white underlay collapses that distinction
+ * (the born-RED). This is the luma→tint axis input, NOT a second opacity axis.
+ */
+export declare function compositeOver(r: number, g: number, b: number, a: number, underlay: readonly [number, number, number]): [number, 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/canvas2d/index.d.ts

@@ -1,3 +1,3 @@
-export { useCanvas2D, useCanvasLifecycle } from "./useCanvas2D";
-export type { Canvas2DFrame, Canvas2DHandle, Canvas2DOptions, Canvas2DSuspendReason, } from "./useCanvas2D";
-export { resolveCanvasColor } from "./resolveCanvasColor";
+export { useCanvas2D } from "./useCanvas2D.js";
+export type { Canvas2DFrame, Canvas2DHandle, Canvas2DOptions, Canvas2DSuspendReason, } from "./useCanvas2D.js";
+export { resolveCanvasColor } from "./resolveCanvasColor.js";

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

@@ -1,7 +1,8 @@
 import { type MaybeRefOrGetter } from "vue";
+import { type DprPolicy } from "../webgl/createCanvasLifecycle.js";
 /**
  * The suspend reasons that gate the loop. Twins the WebGL substrate's union
- * (`createCanvasLifecycle.CanvasSuspendReason`): the AX.W16 F6 `"off-screen-io"`
+ * (`createCanvasLifecycle.CanvasSuspendReason`): the `"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.
@@ -33,6 +34,11 @@ export interface Canvas2DOptions {
     respectReducedMotion?: boolean;
     /** `getContext("2d", …)` attributes. */
     contextAttrs?: CanvasRenderingContext2DSettings;
+    /**
+     * Backing-store DPR policy. Defaults to the existing Canvas2D ceiling:
+     * `min(devicePixelRatio, 2)`.
+     */
+    dprPolicy?: DprPolicy;
     /** IntersectionObserver `rootMargin` for the offscreen seam. Default `200px`. */
     rootMargin?: string;
 }
@@ -56,14 +62,6 @@ export interface Canvas2DHandle {
  * `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.
+ * ref-bundle).
  */
 export declare function useCanvas2D(options: Canvas2DOptions): Canvas2DHandle;
-/**
- * Alias-of-record for {@link useCanvas2D} — the lifecycle-only framing (the
- * park/freeze/dispose machinery, paralleling the WebGL substrate's
- * `createCanvasLifecycle`). Same factory, same handle; reach for this name when
- * the lifecycle (not the 2D drawing) is the consumer's emphasis.
- */
-export declare const useCanvasLifecycle: typeof useCanvas2D;

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

@@ -1,7 +1,5 @@
-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";
+export { useSpecularTracking, createSpecularWriter, } from "./useSpecularTracking.js";
+export type { UseSpecularTracking, SpecularWriter, } from "./useSpecularTracking.js";
+export { vSpecular } from "./vSpecular.js";
+export { useCanvas2D, resolveCanvasColor } from "./canvas2d/index.js";
+export type { Canvas2DFrame, Canvas2DHandle, Canvas2DOptions, Canvas2DSuspendReason, } from "./canvas2d/index.js";

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

@@ -1,11 +1,11 @@
 import { type Ref } from "vue";
-import { type BackgroundCanvasSource } from "./backdropLuminanceSample";
-/** The discrete bucket the observer derives + writes (re-engages the W55 machinery). */
+import { type BackgroundCanvasSource } from "./backdropLuminanceSample.js";
+/** The discrete backdrop bucket derived and written by the observer. */
 export type GlassBackdropBucket = "light" | "dark";
 export interface UseGlassBackdropLuminanceOptions {
     /**
      * The KNOWN background-layer source for the ANIMATED case — an HTMLCanvasElement
-     * (or a getter / a CSS selector resolved against the document). When present, the
+     * (or a getter, a CSS selector resolved against the document). When present, the
      * observer downsamples this canvas under the surface's bounding box each settle
      * instead of the static `elementsFromPoint` stack-walk. The aurora/blob `<canvas>`
      * the surface floats over.
@@ -26,8 +26,7 @@ export interface UseGlassBackdropLuminanceOptions {
     lightThreshold?: number;
     /**
      * Minimum milliseconds between samples on the live loop (the ≤ 4 Hz throttle floor).
-     * Default 250 (4 Hz). Bounded ≥ 250 (the budget floor — a faster sample is the
-     * C5-9 frame-budget risk the H3 arm-(a) default-on profile must hold).
+     * Default 250 (4 Hz) and bounded to at least 250ms.
      */
     minSampleIntervalMs?: number;
     /**
@@ -37,10 +36,10 @@ export interface UseGlassBackdropLuminanceOptions {
      */
     writeBucket?: boolean;
     /**
-     * BI.W-DOCK-LUMA-SHARE — mark this as the SHARED per-ROUTE observer. It stamps
+     * 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
+     * `--glass-backdrop-luma`, `--glass-backdrop` 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
@@ -72,7 +71,6 @@ export type GlassBackdropSample = {
     mode: "live" | "static";
     source: "canvas" | "elements";
     luma: number;
-    ambientHue: string;
     sampledAt: number;
     targetRect: GlassBackdropTargetRect;
 } | {
@@ -90,24 +88,17 @@ export interface GlassBackdropTargetRect {
     height: number;
 }
 /**
- * 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.
+ * Shared-coverage marker. A route observer stamps this on its target; descendant
+ * surface observers stand down and inherit its custom properties. A DOM marker is
+ * required because provide/inject does not follow the rendered slot ancestry that
+ * the custom properties use.
  */
 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
- * W55 declarative bucket. Default-on for the dock (H3 arm a); a dark-substrate consumer
- * opts out by setting `--glass-tint-strength: 0%` on the surface (the declarative floor
+ * content-glass panel) to write a dynamic backdrop-luminance signal that refines the
+ * declarative bucket. Default on for Dock; a dark-substrate consumer
+ * opts out by setting `--glass-level: 0` on the surface (the declarative floor
  * stays the guarantee — the observer only refines).
  *
  * @param target the glass surface element ref to sample under + write the tokens on

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

@@ -1,15 +1,14 @@
 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 `DockControl.vue`.
+ * `useSpecularTracking` is the pointer-anchored moving-specular writer shared by
+ * Card and DockControl.
  *
  * 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
- * `.glass-material::before` recipe (`glass.css`) MAPS that host write onto its
+ * material-group `::before` recipe (`glass.css`) MAPS that host write onto its
  * typed `--specular-x`/`--specular-y` channel and paints the travelling glow.
  *
- * VOCAB (HARDENING §G #28): `--mouse-x`/`--mouse-y` is the HOST WRITE this seam
+ * VOCAB: `--mouse-x`/`--mouse-y` is the HOST WRITE this seam
  * owns; `--specular-x`/`--specular-y` is the CSS-internal MAPPED channel the
  * recipe reads. The host writes `--mouse-x/y`; the recipe maps it.
  *
@@ -21,20 +20,18 @@ import { ref, type CSSProperties } from "vue";
  *
  * PRM-aware: under `prefers-reduced-motion: reduce` the seam DOES NOT write the
  * position (the CSS half pins the catch-light static at the centred `50%`
- * fallback). The PRM signal is read from a SINGLE cached `matchMedia` listener
- * minted once at composable setup (NOT a fresh `matchMedia` per pointer event) —
- * the AV.W7 `useWebGLCanvas` substrate pattern.
+ * fallback). The PRM signal comes from the shared reduced-motion authority, never a
+ * fresh `matchMedia` read per pointer event.
  *
- * AY.W-A11Y-PERF O-3 — the pointer write is rAF-COALESCED: `onPointerMove` only
+ * The pointer write is rAF-coalesced: `onPointerMove` only
  * stashes the raw event + schedules ONE `requestAnimationFrame`; the rAF callback
  * does the single `getBoundingClientRect()` + style write, so a 120–1000 Hz pointer
  * collapses to ONE batched layout read + ONE style write per animation frame (under
- * 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
+ * each blurred-surface repaint is amortized to the frame rather than the
+ * event). The composable cancels the pending rAF + its shared-preference watch 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
+ * `createSpecularWriter()` owns rAF coalescing, cached PRM, and cleanup. The composable 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,
@@ -47,12 +44,12 @@ export interface UseSpecularTracking {
     onPointerMove: (event: PointerEvent) => void;
 }
 /**
- * The SINGLE position-write core (BB.W-LIQUIDHOVER) — the rAF-coalesced,
+ * The SINGLE position-write core — 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.
+ * Returns the event handler + a `dispose` (cancel the pending rAF + preference watch)
+ * so BOTH deliveries share ONE cleanup discipline.
  */
 export interface SpecularWriter {
     onPointerMove: (event: PointerEvent) => void;

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

@@ -21,24 +21,21 @@ export type DprPolicy = number | ((box: {
     h: number;
 }) => number);
 /**
- * BD.W-SUBSTRATE-SIZE-UNIFY (G1) — the ONE canonical backing-store sizer.
+ * The canonical backing-store sizer.
  *
- * Aurora's PROVEN gBCR-ancestor sizer, lifted into the agnostic leaf so it lives ONCE
- * (DRY) instead of in N drifted consumer `resize()` closures (the three incompatible
- * `clientWidth || 320` / `clientWidth || canvasSize` / one-parent-gBCR conventions the
- * DELTA-ASSAY reproduced as the live 300×150 stuck-canvas).
+ * The shared ancestor-aware sizer replaces per-consumer `resize()` conventions.
  *
  * Measures the LAID-OUT border-box via `getBoundingClientRect` — NOT `clientWidth`,
  * which reads 0 under a `content-visibility:auto` skip (the born-skipped trap). Walks
  * ancestors ONLY when our own rect is still zero (truly un-laid-out), and the walk is
- * BOUNDED (H-B): cap depth at 3 AND stop at the first sized / contained / container /
- * positioned ancestor — never an unbounded gBCR storm to `<body>` (O(depth) reflow per
+ * Bounded: cap depth at 3 and stop at the first sized, contained, container-positioned
+ * ancestor — never an unbounded gBCR walk to `<body>` (O(depth) reflow per
  * tick), never an over-recovered wide flex/grid grandparent that sizes the backing to
  * the viewport. Idempotent: the realloc (which CLEARS the drawing buffer) is skipped
  * when the buffer already matches the box.
  *
  * Pure CSS-geometry — ZERO dependency on which GPU API is live, so it runs SYNCHRONOUSLY
- * at mount before the async WebGPU device resolves (G2). Engine-identical in Chromium +
+ * at mount before the async WebGPU device resolves. Engine-identical in Chromium and
  * WebKit (gBCR reflects the real box across a CV skip in both).
  */
 export declare function sizeBacking(canvas: HTMLCanvasElement, dprPolicy: DprPolicy): BackingSize;

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

@@ -1,5 +1,5 @@
 /**
- * Shared WebGL2 shader compile/link pair (AV.W14) — the single error-checked
+ * Shared WebGL2 shader compile/link pair: the single error-checked
  * source the aurora GL setup (`glSetup.ts`) and the goo-blob renderer
  * (`useMetaballRenderer.ts`) both build their program from. Each consumer was
  * hand-rolling a byte-identical `compile`/`link` differing only in the error