@mkbabb/glass-ui 5.0.0 → 7.0.0

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

@@ -2,6 +2,8 @@ import { type WebGLCanvasFrame, type WebGLCanvasOptions } from "../webgl/useWebG
 import type { DprPolicy } from "../webgl/createCanvasLifecycle";
 export type { BackingSize, DprPolicy } from "../webgl/createCanvasLifecycle";
 import { supportsWebGPU, type WebGPUCanvasFrame, type WebGPUCanvasOptions } from "./useWebGPUCanvas";
+import { type RendererStatus } from "./rendererStatus";
+export type { RendererStatus, RendererEngine } from "./rendererStatus";
 export { supportsWebGPU };
 /** Which backend the picker resolved. */
 export type GpuBackend = "webgpu" | "webgl2";
@@ -18,7 +20,7 @@ export interface GpuSubstrateOptions {
     /** The GLSL program builder (the WebGL2 fallback path — always required). */
     setupGL: WebGLCanvasOptions["setup"];
     /**
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G1/G2) — the consumer's DPR policy (a flat multiplier
+     * The consumer's DPR policy: a flat multiplier
      * or a box-aware resolver). When PRESENT the leaf owns the backing-store measurement
      * + sizes it SYNCHRONOUSLY at mount (the ONE sizer; before the async acquire on the
      * WebGPU path), handing the live `BackingSize` to each `setup`'s `resize(s)`. When
@@ -27,17 +29,17 @@ export interface GpuSubstrateOptions {
      */
     dprPolicy?: DprPolicy;
     /**
-     * G3 — compose the leaf IntersectionObserver park (a consumer inherits the
+     * Compose the leaf IntersectionObserver park so a consumer inherits the
      * off-screen IO-park ORed with content-visibility, no per-viz `useIntersectionPause`
      * wiring). Default `false` (OPT-IN): several consumers already write `"off-screen-io"`
      * from their own `useIntersectionPause` and a leaf IO default-on would double-write
      * that reason. A viz with NO IO wiring (concentric/fourier/dot-flow) opts IN.
      */
     composeIntersectionPark?: boolean;
-    /** `rootMargin` for the leaf IO park (G3). Default `"256px"`. */
+    /** `rootMargin` for the leaf IO park. Default `"256px"`. */
     intersectionRootMargin?: string;
     /**
-     * BG.W-VIZ-REVEAL-BLOOM — fire the one-shot cold-first-VISIBLE entrance bloom (a
+     * fire the one-shot cold-first-VISIBLE entrance bloom (a
      * one-shot `data-substrate-reveal` attr on the canvas the CSS `@keyframes
      * substrate-reveal-bloom` reads to ramp `filter: brightness()` from a dim floor,
      * overshoot past 1.0 on `--ease-cartoon-punch`, then settle). Fires at first-visible,
@@ -51,7 +53,7 @@ export interface GpuSubstrateOptions {
     deviceDescriptor?: WebGPUCanvasOptions["deviceDescriptor"];
     /** WebGL2 `getContext("webgl2", …)` attributes. */
     contextAttrs?: WebGLCanvasOptions["contextAttrs"];
-    /** Surface a device-init / validation failure (the WebGPU path). */
+    /** Surface a device-init, validation failure (the WebGPU path). */
     onInitError?: WebGPUCanvasOptions["onInitError"];
     /**
      * Notified when the picker FALLS from WebGPU to the WebGL2 net (the invisible
@@ -64,6 +66,7 @@ export interface GpuSubstrateOptions {
         to: "webgl2";
         error: unknown;
     }) => void;
+    onStatus?: (status: RendererStatus) => void;
 }
 /**
  * The uniform substrate handle. A viz consumer wires its lifecycle (offscreen pause,
@@ -85,7 +88,7 @@ export interface GpuSubstrateHandle {
     /** Synchronous arm (the WebGL2 net arms immediately; the WebGPU path is a no-op until the device resolves). */
     arm: () => void;
     /**
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing store + start the leaf RO
+     * Size the backing store and start the leaf RO
      * SYNCHRONOUSLY, decoupled from the (async) backend acquire. Call it the instant the
      * canvas is in the DOM so the field is sharp from frame 0 while the device resolves
      * (the ≤6s blurry-flash close). `armAsync` already calls it internally on both legs;
@@ -104,10 +107,10 @@ export interface GpuSubstrateHandle {
  * Pick the backend + return the uniform handle. WebGPU-first (`supportsWebGPU()` AND a
  * `setupWGPU` callback is provided); otherwise the WebGL2 net. The decision is NO
  * LONGER committed at construction off a presence check — `armAsync()` ATTEMPTS the
- * WebGPU init and FALLS to the WebGL2 net on ANY failure (no adapter, device reject,
- * device-lost-at-birth, validation throw). The WebGL2 leaf is built lazily — only if
- * the WebGPU path fails OR no WGSL path was provided — so a Baseline host pays no
- * WebGL2-context cost.
+ * WebGPU init and falls to WebGL2 only for recognized acquisition failures that occur
+ * before a WebGPU context is acquired. Setup/pipeline validation stays an explicit
+ * WebGPU error. The WebGL2 leaf is built lazily, so a Baseline host pays no fallback
+ * context cost.
  */
 export declare function createGpuSubstrate(canvas: HTMLCanvasElement, options: GpuSubstrateOptions): GpuSubstrateHandle;
 export type { WebGPUCanvasFrame, WebGLCanvasFrame };

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

@@ -6,7 +6,7 @@ import type { WebGPUCanvasOptions, WebGPUCanvasHandle } from "./webgpuCanvasType
  * The ONE `navigator.gpu` capability probe (the single-bootstrap rule — mirrors
  * `probeWebGL2Renderer`). SSR-safe (returns `false` with no `navigator`). The picker
  * (`useGpuSubstrate`) reads it to decide the backend; a consumer NEVER touches
- * `navigator.gpu` directly (it composes the substrate — `proof:gpu-substrate-single`
+ * `navigator.gpu` directly because it composes the substrate
  * clause A reds a direct call).
  */
 export declare function supportsWebGPU(): boolean;

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

@@ -15,7 +15,7 @@ export interface WebGPUCanvasFrame {
     /** Demand-gate: is there live motion to render next frame? `false` → park. */
     shouldContinue: () => boolean;
     /**
-     * Upload the backing geometry. BD.W-SUBSTRATE-SIZE-UNIFY: when a `dprPolicy` is
+     * Upload the backing geometry.: when a `dprPolicy` is
      * supplied the leaf sizes the backing + passes the live `BackingSize` here (the
      * WGSL swap chain auto-tracks the backing, so the consumer body shrinks to an aspect
      * upload). The arg is optional so a legacy self-measuring consumer keeps compiling.
@@ -43,31 +43,33 @@ export interface WebGPUCanvasOptions {
      */
     respectReducedMotion?: boolean;
     /**
-     * BD.W-SUBSTRATE-SIZE-UNIFY (G1/G2) — the consumer's DPR policy. When PRESENT the
+     * The consumer's DPR policy. When present the
      * leaf sizes the backing SYNCHRONOUSLY at mount (via `presize`, BEFORE the async
      * device acquire — the ≤6s blurry-flash close) and hands the live `BackingSize` to
      * `resize(s)`. When ABSENT the legacy path runs (the consumer self-measures).
      */
     dprPolicy?: DprPolicy;
-    /** Compose the leaf IO park (G3). Default `false` (opt-in; see createCanvasLifecycle). */
+    /** Compose the leaf IO park. Default `false`; see createCanvasLifecycle. */
     composeIntersectionPark?: boolean;
-    /** `rootMargin` for the leaf IO park (G3). */
+    /** `rootMargin` for the leaf IO park. */
     intersectionRootMargin?: string;
-    /** Fire the one-shot cold-first-VISIBLE entrance bloom (BG.W-VIZ-REVEAL-BLOOM — the `data-substrate-reveal` attr). Default `false`. */
+    /** Fire the one-shot cold-first-visible entrance bloom via `data-substrate-reveal`. Default `false`. */
     revealBloom?: boolean;
     /**
      * Build the WGSL pipeline + bind groups on the resolved device. Called on the
      * async arm AND on every device-restore. Returns the per-frame hooks.
      */
     setup: (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;
-    /** Surface a device-init / validation failure (no WebGPU adapter, a `setup` throw). */
+    /** Internal lifecycle projection used by the shared renderer-status owner. */
+    onContextStateChange?: (state: "lost" | "restored") => void;
+    /** Surface a device-init, validation failure (no WebGPU adapter, a `setup` throw). */
     onInitError?: (error: unknown) => void;
 }
 export interface WebGPUCanvasHandle {
     /**
      * Run the expensive ASYNC init (adapter + device + context.configure + `setup`)
      * THEN arm the loop. Resolves once armed (or rejects-via-`onInitError` on a
-     * device-unavailable / `setup` failure). Idempotent; a no-op post-dispose.
+     * device-unavailable, `setup` failure). Idempotent; a no-op post-dispose.
      */
     armAsync: () => Promise<void>;
     /**
@@ -76,17 +78,19 @@ export interface WebGPUCanvasHandle {
      * `armAsync` for the WebGPU path). Idempotent.
      */
     arm: () => void;
-    /** BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing + start the leaf RO synchronously, before the async acquire. */
+    /** Size the backing and start the leaf RO synchronously before async acquire. */
     presize: () => void;
     suspend: (reason?: WebGPUSuspendReason) => void;
     resume: (reason?: WebGPUSuspendReason) => void;
     /** Re-arm a parked loop (a setter that re-introduced motion calls this). */
     wake: () => void;
-    /** Draw one frame at `timeSec` out-of-loop (capture / thumbnail). */
+    /** Draw one frame at `timeSec` out-of-loop (capture, thumbnail). */
     renderAt: (timeSec: number) => void;
     dispose: () => void;
-    /** The live device (null before armAsync / after dispose / mid-loss). */
+    /** The live device (null before armAsync, after dispose, mid-loss). */
     readonly device: GPUDevice | null;
+    /** Runtime-derived adapter identity, available once acquisition succeeds. */
+    readonly adapterClass: string;
     /**
      * The live `prefers-reduced-motion: reduce` state. The shared lifecycle core
      * owns + re-monitors it; consumers read it (e.g. a viz freezes its frame time

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

@@ -1,6 +1,6 @@
 /**
- * The recognizable WebGPU INIT-FAILURE signal (BC.W-WEBGPU-EVERYWHERE — the D8/D8'
- * close). A no-adapter host (`requestAdapter()` returns null), a `requestDevice()`
+ * Recognizable WebGPU initialization-failure signal. A no-adapter host
+ * (`requestAdapter()` returns null), a `requestDevice()`
  * reject, or a device-lost-at-birth is NOT a contract violation — it is a recognized
  * substrate decision the picker (`createGpuSubstrate`) catches to fall to the WebGL2
  * net. `armAsync()` REJECTS with this typed signal (it does NOT `throw` an uncaught
@@ -13,13 +13,12 @@ export declare class WebGPUInitError extends Error {
     constructor(kind: WebGPUInitError["kind"], message: string, cause?: unknown);
 }
 /**
- * Detect a SOFTWARE / CPU WebGPU adapter (SwiftShader / llvmpipe / the Microsoft
+ * Detect a SOFTWARE, CPU WebGPU adapter (SwiftShader, llvmpipe, the Microsoft
  * Basic Render Driver, or a UA-supplied `isFallbackAdapter` software fallback) — the
- * WebGPU twin of `isSoftwareWebGLRenderer` (the `renderMode.ts` WebGL software-raster
- * guard, BB.W-AURORA-SWRASTER).
+ * WebGPU twin of the `renderMode.ts` WebGL software-raster guard.
  *
- * WHY this forces the WebGL2 net (the BC WebGPU re-home regression this closes): on a
- * headless / GPU-blocklisted / CI host, `navigator.gpu` exists AND `requestAdapter()`
+ * WHY this forces the WebGL2 net (the WebGPU re-home regression this closes): on a
+ * headless, GPU-blocklisted, CI host, `navigator.gpu` exists AND `requestAdapter()`
  * SUCCEEDS — it returns a SOFTWARE adapter (SwiftShader). `requestDevice()` succeeds
  * too, so the WebGPU init does NOT reject; `setup()` builds the render pipeline, but the
  * software backend cannot validate/compile it (a metaball `RenderPipeline` is invalid
@@ -28,7 +27,7 @@ export declare class WebGPUInitError extends Error {
  * spew with no fallback (the loop keeps trying to draw the invalid pipeline). A
  * software-rastered WebGPU surface is the same per-composite cost class the WebGL guard
  * forbids. So a software adapter is treated as a recognized INIT FAILURE: the picker's
- * `armAsync` try/catch falls to the WebGL2 net — exactly the silent W-AURORA-SWRASTER
+ * `armAsync` try/catch falls to the WebGL2 net — exactly the silent
  * degrade, never the invalid-pipeline flood.
  *
  * The signal is the `isFallbackAdapter` spec flag (a UA sets it on a software fallback —
@@ -42,19 +41,19 @@ export declare class WebGPUInitError extends Error {
 export declare function isSoftwareWebGPUAdapter(adapter: GPUAdapter): boolean;
 /**
  * The bound on the adapter/device acquisition (ms). The adapter/device request can
- * resolve NEITHER way on a hanging host (a headless / virtualized-Metal + some-Chrome
+ * resolve NEITHER way on a hanging host (a headless, virtualized-Metal + some-Chrome
  * class). A REAL cold acquire on a healthy Metal-3 host was live-measured at ~3478ms
- * (the FIRST device request on a cold GPU process) — well over the prior tight 2500ms
- * ceiling, which converted a slow-but-fine cold acquire into a FALSE hang so the WGSL
- * primary was never exercised (every viz silently downgraded to WebGL2 forever — the
- * Safari-primary surface the "broken TOTALLY" reports live on, masked by the
+ * (the FIRST device request on a cold GPU process) — well over a tight 2500ms
+ * ceiling, which would convert a slow-but-fine cold acquire into a FALSE hang so the WGSL
+ * primary never runs (every viz silently downgrading to WebGL2 — the
+ * Safari-primary surface masked by the
  * always-winning fallback). 6000ms lets the real cold acquire through while a genuine
  * wedge (a device that never settles) still falls to the WebGL2 net before the user
  * perceives a permanent blank. With the SHARED device warm the ceiling is hit at most
  * ONCE per page, not N-times-per-canvas — a single ≤6s race, never N.
  *
- * BG.W-COLOCATE — carved into this device-acquisition-support leaf beside the typed
- * failure signal it throws (ratchet-drain #4). The substrate re-imports + re-exports it.
+ * homed in this device-acquisition-support leaf beside the typed
+ * failure signal it throws. The substrate re-imports + re-exports it.
  */
 export declare const WEBGPU_ACQUIRE_TIMEOUT_MS = 6000;
 /**
@@ -67,6 +66,6 @@ export declare const WEBGPU_ACQUIRE_TIMEOUT_MS = 6000;
  *
  * `label` is the acquisition-step name used in the timeout message (the caller in the
  * substrate passes the concrete step name — the bootstrap tokens stay in the substrate
- * per proof:gpu-substrate-single clause A).
+ * per  clause A).
  */
 export declare function withAcquireTimeout<T>(promise: Promise<T>, label: string): Promise<T>;

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

@@ -0,0 +1,2 @@
+import type { ComponentPublicInstance } from "vue";
+export declare function asElement(value: HTMLElement | ComponentPublicInstance | null | undefined): HTMLElement | null;

package/dist/composables/motion/{constants.d.ts → core/constants.d.ts}

@@ -1,9 +1,8 @@
 /**
  * Shared damping factors for live numeric motion.
  *
- * These values preserve the app-level tuning that used to live in
- * speedtest's local animation utility while making glass-ui the owner of the
- * generic motion contract.
+ * These values are the app-level tuning glass-ui owns for the generic motion
+ * contract.
  */
 export declare const DAMPING: {
     readonly canvasNeedle: 0.08;

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

@@ -1,24 +1,21 @@
-export * from "../constants";
-export * from "../useStaggerReveal";
-export * from "../useStagger";
-export * from "../useScrollProgress";
-export * from "../useRAFLoop";
-export * from "../useIntersectionPause";
-export * from "../useYieldToMain";
-export * from "../usePrioritizedTask";
-export * from "../useViewTransition";
-export * from "../vReveal";
-export * from "../useTextHighlight";
-export * from "../useLiquidFlex";
-export * from "../useLeadTrail";
-export * from "../useGooMorph";
-export * from "../morphSignatures";
-export * from "../usePointerVelocityField";
-export * from "../useRoutePointer";
-export * from "../pointerFieldMappings";
-export * from "../useCharStagger";
-export * from "../useScrollTrigger";
-export * from "../useScrollChrome";
+export * from "./constants";
+export * from "../reveal/useStaggerReveal";
+export * from "../reveal/useStagger";
+export * from "../scroll/useScrollProgress";
+export * from "./useRAFLoop";
+export * from "./useReducedMotion";
+export * from "./useIntersectionPause";
+export * from "./useYieldToMain";
+export * from "./useViewTransition";
+export * from "../reveal/vReveal";
+export * from "../reveal/useTextHighlight";
+export * from "../spring/useLiquidFlex";
+export * from "../morph/useLeadTrail";
+export * from "../pointer/usePointerVelocityField";
+export * from "../pointer/useRoutePointer";
+export * from "../pointer/pointerFieldMappings";
+export * from "../scroll/useScrollTrigger";
+export * from "../scroll/useScrollChrome";
 export * from "./writeVelocityWeight";
-export * from "../useSelectionIndicator";
-export * from "../useSelectionGroup";
+export * from "../morph/useSelectionIndicator";
+export * from "../morph/useSelectionGroup";

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

@@ -0,0 +1,5 @@
+import { type Ref } from "vue";
+/** Read the current OS preference without subscribing (SSR-safe). */
+export declare function readReducedMotion(): boolean;
+/** Share one reactive OS preference and one MediaQueryList listener. */
+export declare function useReducedMotion(): Readonly<Ref<boolean>>;

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

@@ -0,0 +1,44 @@
+/** Options for `startViewTransition`. `types` (Chrome 140+, absent on Firefox
+ *  144) tag the active transition so `:active-view-transition-type(<t>)` CSS can
+ *  author DIRECTION-specific curves. Feature-detected — when the engine lacks the
+ *  object-with-`types` overload the call degrades to the plain-callback form
+ * one symmetric curve, which is functionally identical because the swap still runs. */
+export interface ViewTransitionOptions {
+    types?: string[];
+}
+export interface ViewTransitionResult {
+    /**
+     * Resolves when the transition's `finished` promise settles (or
+     * immediately in the fallback path). Use to route focus per the a11y
+     * MANDATORY: `await startViewTransition(mutate).finished; el.focus()`.
+     * Never rejects — a skipped/aborted transition settles cleanly.
+     */
+    finished: Promise<void>;
+    /** True when the native API ran; false when the instant fallback ran. */
+    transitioned: boolean;
+}
+/**
+ * True when `document.startViewTransition` is available — the feature-detected
+ * predicate consumers gate optional VT-only styling on.
+ */
+export declare function supportsViewTransitions(): boolean;
+/**
+ * Wrap a DOM mutation in `document.startViewTransition` with an instant
+ * fallback. The mutation may be synchronous or asynchronous.
+ *
+ * @param mutate the DOM/state change to animate between.
+ * @param options optional `{ types }` — directional transition types tagged on
+ *   the active transition for `:active-view-transition-type(<t>)` CSS curves
+ *   (Chrome 140+; feature-detected, degrades to one symmetric curve elsewhere).
+ * @returns `{ finished, transitioned }` — await `finished` to route focus.
+ *
+ * @example
+ *   const { finished } = startViewTransition(() => { rows.value = reranked });
+ *   await finished;            // animation done
+ *   firstRow.value?.focus();   // consumer routes focus (the a11y MANDATORY)
+ *
+ * @example
+ *   // directional intent — snappier exit on collapse, softer entry on expand
+ *   startViewTransition(() => mutate(), { types: ["dock-expand"] });
+ */
+export declare function startViewTransition(mutate: () => void | Promise<void>, options?: ViewTransitionOptions): ViewTransitionResult;

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

@@ -1,16 +1,14 @@
-export * from "./constants";
-export * from "./useSpring";
-export * from "./useSpringMount";
-export * from "./useSpringPress";
-export * from "./useLiquidPress";
-export * from "./useDragMorph";
-export * from "./useElementMorph";
-export * from "./useLiquidReveal";
-export * from "./useDockCtaReceive";
-export * from "./useBloomUp";
-export * from "./useNumericTransition";
-export * from "./useAnimatedNumber";
-export * from "./useAnimatedNumberMap";
-export * from "./useCountup";
-export * from "./suite";
-export { SPRING_PRESETS, springPreset, type SpringPresetRow, type SpringPresetName, } from "./springPresets";
+export * from "./core/constants";
+export * from "./spring/useSpring";
+export * from "./spring/useSpringMount";
+export * from "./spring/useLiquidPress";
+export * from "./morph/useDragMorph";
+export * from "./morph/useElementMorph";
+export * from "./reveal/useLiquidReveal";
+export * from "./morph/useDockCtaReceive";
+export * from "./reveal/useBloomUp";
+export * from "./number/useNumericTransition";
+export * from "./number/useAnimatedNumber";
+export * from "./number/useAnimatedNumberMap";
+export * from "./number/useCountup";
+export { SPRING_PRESETS, springPreset, type SpringPresetRow, type SpringPresetName, } from "./spring/springPresets";

package/dist/composables/motion/{useDockCtaReceive.d.ts → morph/useDockCtaReceive.d.ts}

@@ -4,6 +4,55 @@ import { type ElementMorphPreset } from "./useElementMorph";
  *  emphatic land-with-overshoot). Matches `useLiquidReveal`'s register so the two seams
  *  read as ONE family. */
 export type DockCtaReceivePreset = ElementMorphPreset;
+export type DockCtaReceivePath = "fine" | "coarse" | "reduced-motion" | "no-target";
+export type DockCtaReceivePhase = "idle" | "receiving" | "settled" | "handed-off" | "completed" | "reset";
+export interface DockCtaReceiveBand {
+    readonly latencyFactor: readonly [number, number];
+    readonly travelPx: readonly [number, number];
+    readonly scaleRatio: readonly [number, number];
+}
+/** Product bounds relative to the selected spring's measured analytic horizon. */
+export declare const DOCK_CTA_RECEIVE_BANDS: {
+    readonly fine: {
+        readonly latencyFactor: readonly [0.9, 1.2];
+        readonly travelPx: readonly [16, 520];
+        readonly scaleRatio: readonly [0.2, 1.4];
+    };
+    readonly coarse: {
+        readonly latencyFactor: readonly [0.9, 1.2];
+        readonly travelPx: readonly [16, 360];
+        readonly scaleRatio: readonly [0.2, 1.4];
+    };
+    readonly "reduced-motion": {
+        readonly latencyFactor: readonly [0, 0.017];
+        readonly travelPx: readonly [0, 0];
+        readonly scaleRatio: readonly [1, 1];
+    };
+    readonly "no-target": {
+        readonly latencyFactor: readonly [0, 0.017];
+        readonly travelPx: readonly [0, 0];
+        readonly scaleRatio: readonly [1, 1];
+    };
+};
+export interface DockCtaReceiveObservables {
+    readonly phase: DockCtaReceivePhase;
+    readonly path: DockCtaReceivePath | null;
+    readonly run: number;
+    readonly interruptions: number;
+    readonly resets: number;
+    readonly startedAtMs: number | null;
+    readonly settledAtMs: number | null;
+    readonly handedOffAtMs: number | null;
+    readonly completedAtMs: number | null;
+    readonly latencyMs: number | null;
+    readonly travelPx: number;
+    readonly scaleRatio: number;
+    readonly latencyBandMs: readonly [number, number] | null;
+    readonly travelBandPx: readonly [number, number] | null;
+    readonly scaleBand: readonly [number, number] | null;
+    readonly withinBand: boolean | null;
+    readonly supportsReverse: false;
+}
 export interface UseDockCtaReceiveOptions {
     /**
      * The dock control the CTA flies onto — a templateRef to the control ELEMENT or to a
@@ -40,11 +89,16 @@ export interface UseDockCtaReceiveReturn {
     clearPending: () => void;
     /** The reactive seat state — the consumer binds `:class`/`v-if` off it. */
     pending: Readonly<Ref<boolean>>;
+    /** Whether the shared morph owner is currently playing. */
+    playing: Readonly<Ref<boolean>>;
+    /** Live normalized arrival progress from the shared morph owner. */
+    progress: Readonly<Ref<number>>;
+    /** Start/settle/handoff/completion and policy-band readback for the current run. */
+    observables: Readonly<Ref<DockCtaReceiveObservables>>;
 }
 /**
- * The external-CTA-into-dock-control morph. A ≤20-line adapter over `useElementMorph` —
- * declares the receive as a `direction: "out"` FORWARD play flying ONTO the dock control,
- * opacity + blur coupled, the runner's `onSettled` firing the seat clear + `onReceived`.
+ * The external-CTA-into-dock-control morph. A small adapter over `useElementMorph`
+ * declares the CTA→control endpoints and couples opacity + blur to its settle hand-off.
  * The seat writes (`setPending`/`clearPending`) stay wrapper-local (data-attr, not motion).
  *
  * @example

package/dist/composables/motion/{useDragMorph.d.ts → morph/useDragMorph.d.ts}

@@ -1,4 +1,4 @@
-import { type ComputedRef, type Ref } from "vue";
+import { type Ref } from "vue";
 /** The morph axis — `"x"` tracks the inline (horizontal) travel, `"y"` the block. */
 export type DragMorphAxis = "x" | "y";
 /**
@@ -11,8 +11,10 @@ export interface DragMorphSnapTarget<V = string> {
     center: number;
 }
 export interface UseDragMorphParams<V = string> {
-    /** The draggable element ref (the indicator/handle the gesture captures). */
-    el: Ref<HTMLElement | null>;
+    /** The element that captures the pointer gesture. */
+    handle: Ref<HTMLElement | null>;
+    /** The surface that follows the gesture. Defaults to `handle`. */
+    surface?: Ref<HTMLElement | null>;
     /** The morph axis (`"x"` horizontal · `"y"` vertical). May be a getter. */
     axis: DragMorphAxis | (() => DragMorphAxis);
     /**
@@ -41,8 +43,6 @@ export interface UseDragMorphReturn {
     position: Readonly<Ref<number>>;
     /** The live squish scalar (≥1, capped at the live cap). 1 at rest / under PRM. */
     stretch: Readonly<Ref<number>>;
-    /** The `transform: translate` style the consumer binds on the morph element. */
-    dragStyle: ComputedRef<Record<string, string>>;
     /**
      * Re-resolve the snap centers + axis (kf reads `snap` at construction, so a
      * geometry change — a resize, an option change, an orientation flip — calls
@@ -62,8 +62,8 @@ export interface UseDragMorphReturn {
  *
  * @example
  * ```ts
- * const { dragging, stretch, dragStyle, detach } = useDragMorph({
- *   el: indicatorRef,
+ * const { dragging, stretch, detach } = useDragMorph({
+ *   handle: indicatorRef,
  *   axis: () => (isVertical.value ? "y" : "x"),
  *   snapTargets: () => buttonRefs.value.map((b, i) => ({
  *     value: options.value[i].value,

package/dist/composables/motion/morph/useElementMorph.d.ts

@@ -0,0 +1,50 @@
+import { type ComponentPublicInstance, type Ref } from "vue";
+import { type SpringPresetName } from "../spring/springPresets";
+/** A measured endpoint, or the morphed surface's own settled box. */
+export type MorphEndpoint = Ref<HTMLElement | ComponentPublicInstance | null> | "self";
+export type ElementMorphPreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+export interface MorphChannels {
+    opacity?: boolean;
+    blur?: number;
+}
+export interface UseElementMorphOptions {
+    /** Where the episode starts. At least one endpoint normally owns `"self"`. */
+    source: MorphEndpoint;
+    /** Where the episode settles. */
+    destination: MorphEndpoint;
+    channels?: MorphChannels;
+    preset?: ElementMorphPreset;
+    respectReducedMotion?: boolean;
+    onSettled?: () => void;
+    onFrame?: (progress: number) => void;
+}
+export interface ElementMorphMeasurement {
+    readonly travelPx: number;
+    readonly scaleX: number;
+    readonly scaleY: number;
+    readonly durationMs: number;
+}
+export interface UseElementMorphReturn {
+    play: () => void;
+    cancel: () => void;
+    clear: (el?: HTMLElement | null) => void;
+    /** Seat the explicit source→destination geometry without starting a clock. */
+    seat: (progress: number) => void;
+    /** Drive a gesture offset through this same spatial writer. */
+    offset: (x: number, y: number) => void;
+    /** Re-measure and retarget an in-flight episode from its live frame. */
+    refresh: () => void;
+    playing: Readonly<Ref<boolean>>;
+    progress: Readonly<Ref<number>>;
+    measurement: Readonly<Ref<ElementMorphMeasurement | null>>;
+}
+import { asElement } from "../core/asElement";
+export { asElement };
+export declare function lockSpatialTransition(el: HTMLElement): () => void;
+export declare function prefersReducedMotion(): boolean;
+/**
+ * A single explicit-endpoint FLIP owner for reveal, bloom, receive and gesture
+ * configurations. Replacements and resizes retarget from the last painted frame;
+ * disappearing foreign endpoints retain the last valid geometry.
+ */
+export declare function useElementMorph(surface: Ref<HTMLElement | ComponentPublicInstance | null>, options: UseElementMorphOptions): UseElementMorphReturn;

package/dist/composables/motion/{useLeadTrail.d.ts → morph/useLeadTrail.d.ts}

@@ -1,8 +1,8 @@
 import { type Ref } from "vue";
 export interface UseLeadTrailOptions {
-    /** The lead spring response (2π/response = the natural frequency). Default 0.68 (dock). */
+    /** The lead spring response (2π/response = the natural frequency). Default 0.68. */
     response?: number;
-    /** The lead spring damping ratio ζ. Default 0.64 (dock; < 1 → the iOS overshoot). */
+    /** The lead spring damping ratio ζ. Default 0.64. */
     damping?: number;
     /** The trailing follower time constant, seconds. Default 0.27 (≈270ms). */
     trailTau?: number;
@@ -11,7 +11,7 @@ export interface UseLeadTrailOptions {
     /**
      * The per-frame writer the consumer supplies (the DOM-write path, NO reactive
      * thrash). Called each rAF tick with the live numeric edges — the consumer
-     * projects its silhouette (a barbell, an eyeglass) off `lo`/`hi`. Also called
+     * projects its silhouette (for example, a barbell) off `lo`/`hi`. Also called
      * once on `seat` so a static mount paints correctly.
      */
     onFrame?: (edges: LeadTrailEdges) => void;
@@ -40,19 +40,19 @@ export interface UseLeadTrail {
      * Retarget the lead edge (px). The velocity carries — a retarget mid-flight
      * re-seats the target, the spring continues from its LIVE `(position, velocity)`
      * so interruption is free. Under PRM this SEATS instantly (zero in-between frames).
-     * The `drive(fractionalIndex→px)` seam W-CAROUSEL-REBUILD's drag-scrub feeds.
+     * The `drive(fractionalIndex→px)` seam consumed by carousel drag scrubbing.
      */
     drive(target: number): void;
     /** Snap BOTH edges to `value` instantly (mount / resize / PRM). Paints once. */
     seat(value: number): void;
-    /** Tear down the rAF + the cached PRM listener (auto-run on scope dispose). */
+    /** Tear down the rAF + shared-preference watch (auto-run on scope dispose). */
     dispose(): void;
 }
 /**
  * The two-edge lead/trail integrator — a spring LEAD + a damped TRAIL follower in
  * ONE rAF. The gap between the edges is the morph's live elongation; the trail
  * catching the lead is the emergent release. keyframes-FREE + vueuse-FREE. See the
- * module header for the pager-worm / eyeglass reconcile rationale.
+ * module header for the pager-worm rationale.
  *
  * @example
  * ```ts

package/dist/composables/motion/{useSelectionGroup.d.ts → morph/useSelectionGroup.d.ts}

@@ -1,11 +1,12 @@
 import { type ComputedRef, type Ref } from "vue";
 import { type SelectionOption } from "./useSelectionIndicator";
+import { type TabActivation } from "../../../components/tabs/composables/useTabRovingFocus";
 /**
- * useSelectionGroup — the library's ONE headless selection engine
- * (BI.W-DOCK-CONTROLS). The dock control run, `<SegmentedTabs>`, and
+ * useSelectionGroup is the library's single headless selection engine. The dock
+ * control run, `<SegmentedTabs>`, and
  * `<ToggleGroup type="single">` are the SAME thing — a roving-focus selection
  * strip with a traveling indicator. This composable assembles that ONE engine
- * from the parts that already exist (PASS-1 §2.4), reka-FREE + engine-free so it
+ * from the shared parts, reka-free and engine-free so it
  * ships on `/motion-core`:
  *
  *   • the SELECTION MODEL — `single` (a `string`) | `multiple` (a `string[]`),
@@ -17,8 +18,7 @@ import { type SelectionOption } from "./useSelectionIndicator";
  *     center-anchored ResizeObserver measure + the `--stretch` squish), so the
  *     dock/tabs/toggle-group indicator is Safari-identical by construction;
  *   • the RECENTER CALL — `el.scrollIntoView({inline:'nearest', block:'nearest'})`
- *     on every select (the FACILITY is W-DOCK-OVERFLOW's; the CALL lives here in
- *     the engine so a selection past the fold pulls itself into view).
+ *     on every select, so a selection past the fold pulls itself into view.
  *
  * ROLE-PER-MODE rides the engine (the WAI-ARIA contract):
  *   • `radiogroup` — a single-select CHOOSER: `role="radio"` + `aria-checked`;
@@ -46,6 +46,8 @@ export interface UseSelectionGroupParams<O extends SelectionOption> {
     role?: ComputedRef<SelectionRole> | SelectionRole;
     /** True for the vertical (block-axis) orientation. */
     vertical?: ComputedRef<boolean>;
+    /** Whether roving focus selects immediately. Defaults to automatic. */
+    activation?: ComputedRef<TabActivation> | TabActivation;
     /** The container scroller root (observed by the indicator's ResizeObserver). */
     containerRef: Ref<HTMLElement | null>;
     /**