@mkbabb/glass-ui 4.0.0 → 4.0.1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1 @@
+export declare const CURL_FBM_GLSL = "\nconst float CURL_EPS = 0.012;\n\n// Scalar fbm potential psi \u2014 the host's noise basis, wrapped so the curl operator is\n// basis-agnostic. A host carrying its own fbm defines this as: return fbm(p);\nfloat potentialFBM(vec2 p);\n\n// \u2207\u00D7\u03C8 in 2D \u2014 the divergence-free flow direction. Central finite differences of the\n// scalar potential give the partials; the cross-pairing (\u2202y, \u2212\u2202x) is the 2D curl.\nvec2 curlFBM(vec2 p) {\n  float dx = potentialFBM(p + vec2(CURL_EPS, 0.0)) - potentialFBM(p - vec2(CURL_EPS, 0.0));\n  float dy = potentialFBM(p + vec2(0.0, CURL_EPS)) - potentialFBM(p - vec2(0.0, CURL_EPS));\n  // \u03C8-gradient is (dx, dy)/(2\u00B7eps); the curl rotates it 90\u00B0: (\u2202\u03C8/\u2202y, \u2212\u2202\u03C8/\u2202x).\n  vec2 g = vec2(dx, dy) / (2.0 * CURL_EPS);\n  return vec2(g.y, -g.x);\n}\n";

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

@@ -1,3 +1,19 @@
+/**
+ * The ONE `getContext("webgl2")` capability probe (BB.W-CI-GREEN — the
+ * single-bootstrap rule). A throwaway WebGL2 context is created here, in the
+ * substrate (the sole webgl2-creating module per `proof:webgl-substrate-single`),
+ * so a consumer feature-detecting WebGL2 / reading the unmasked renderer string
+ * NEVER creates a second context of its own. The probe canvas is detached, its
+ * context released via `WEBGL_lose_context` under the per-page context cap; the
+ * read is one-shot (a mount-time device-tier decision, not a reactive one).
+ *
+ * Returns the lower-cased `UNMASKED_RENDERER_WEBGL` string (e.g.
+ * `"google swiftshader"`), or `null` when WebGL2 / the debug-renderer extension
+ * is unavailable or the probe throws — the caller treats `null` as "cannot prove"
+ * (the conservative-but-lossy fall-back). SSR-safe (returns `null` with no
+ * `document`).
+ */
+export declare function probeWebGL2Renderer(): string | null;
 export type WebGLSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
 /** The per-frame hooks a consumer's `setup(gl)` returns. */
 export interface WebGLCanvasFrame {

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

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

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

@@ -0,0 +1,54 @@
+import { type WebGLCanvasFrame, type WebGLCanvasOptions } from "../webgl/useWebGLCanvas";
+import { supportsWebGPU, type WebGPUCanvasFrame, type WebGPUCanvasOptions } from "./useWebGPUCanvas";
+export { supportsWebGPU };
+/** Which backend the picker resolved. */
+export type GpuBackend = "webgpu" | "webgl2";
+export interface GpuSubstrateOptions {
+    /** `"capture"` → renderAt-only (no auto-loop). Default `"live"`. */
+    mode?: "live" | "capture";
+    /** Honor `prefers-reduced-motion: reduce` (one static frame then park). Default `true`. */
+    respectReducedMotion?: boolean;
+    /**
+     * The WGSL pipeline builder (the WebGPU primary path). Omitting it forces the
+     * WebGL2 fallback even where WebGPU is supported (a viz with no WGSL path yet).
+     */
+    setupWGPU?: WebGPUCanvasOptions["setup"];
+    /** The GLSL program builder (the WebGL2 fallback path — always required). */
+    setupGL: WebGLCanvasOptions["setup"];
+    /** WebGPU `context.configure` alpha mode (default `"premultiplied"`). */
+    alphaMode?: WebGPUCanvasOptions["alphaMode"];
+    /** WebGPU adapter/device request options. */
+    adapterOptions?: WebGPUCanvasOptions["adapterOptions"];
+    deviceDescriptor?: WebGPUCanvasOptions["deviceDescriptor"];
+    /** WebGL2 `getContext("webgl2", …)` attributes. */
+    contextAttrs?: WebGLCanvasOptions["contextAttrs"];
+    /** Surface a device-init / validation failure (the WebGPU path). */
+    onInitError?: WebGPUCanvasOptions["onInitError"];
+}
+/**
+ * The uniform substrate handle. A viz consumer wires its lifecycle (offscreen pause,
+ * pause/resume, pointer-`wake`, capture-`renderAt`) against THIS — identical across the
+ * WebGPU and WebGL2 backends. `armAsync` is the start seam (the WebGPU path awaits the
+ * device; the WebGL2 path resolves immediately); `arm` is the synchronous twin.
+ */
+export interface GpuSubstrateHandle {
+    /** The resolved backend (`"webgpu"` where supported + a WGSL path is provided, else `"webgl2"`). */
+    readonly backend: GpuBackend;
+    /** Acquire the device/context + `setup` + arm the loop. Resolves once armed. */
+    armAsync: () => Promise<void>;
+    /** Synchronous arm (the WebGL2 path arms immediately; the WebGPU path is a no-op until the device resolves). */
+    arm: () => void;
+    suspend: (reason?: "tab-hidden" | "off-screen" | "off-screen-io" | "manual") => void;
+    resume: (reason?: "tab-hidden" | "off-screen" | "off-screen-io" | "manual") => void;
+    wake: () => void;
+    renderAt: (timeSec: number) => void;
+    dispose: () => void;
+    readonly reducedMotion: boolean;
+}
+/**
+ * Pick the backend + return the uniform handle. WebGPU-first (`supportsWebGPU()` AND a
+ * `setupWGPU` callback is provided); otherwise the WebGL2 fallback. The decision is
+ * made ONCE at construction (a mount-time device-tier choice, not a reactive one).
+ */
+export declare function createGpuSubstrate(canvas: HTMLCanvasElement, options: GpuSubstrateOptions): GpuSubstrateHandle;
+export type { WebGPUCanvasFrame, WebGLCanvasFrame };

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

@@ -0,0 +1,84 @@
+/**
+ * The ONE `navigator.gpu` capability probe (the single-bootstrap rule — mirrors
+ * `probeWebGL2Renderer`). SSR-safe (returns `false` with no `navigator`). The picker
+ * (`useGpuSubstrate`) reads it to decide the backend; a consumer NEVER touches
+ * `navigator.gpu` directly (it composes the substrate — `proof:gpu-substrate-single`
+ * clause A reds a direct call).
+ */
+export declare function supportsWebGPU(): boolean;
+export type WebGPUSuspendReason = "tab-hidden" | "off-screen" | "off-screen-io" | "manual";
+/**
+ * The per-frame hooks a consumer's `setup(device, context, format)` returns. The
+ * consumer owns the WGSL pipeline + bind groups + the per-frame command-encoder
+ * record/submit; the substrate owns the schedule.
+ */
+export interface WebGPUCanvasFrame {
+    /**
+     * Draw one frame at `timeSec`: the consumer records a command encoder, begins a
+     * render pass against the current swap-chain texture view
+     * (`context.getCurrentTexture().createView()`), draws, and submits.
+     */
+    frame: (timeSec: number) => void;
+    /** Demand-gate: is there live motion to render next frame? `false` → park. */
+    shouldContinue: () => boolean;
+    /** Size the canvas backing store. The consumer owns its DPR policy. */
+    resize: () => void;
+    /** Frame time from elapsed seconds — the consumer owns frozen/reduced-motion. */
+    time?: (elapsedSec: number) => number;
+    /** Release per-instance GPU resources (pipelines/buffers/bind groups). Runs on dispose + before a restore re-setup. */
+    teardown?: () => void;
+}
+export interface WebGPUCanvasOptions {
+    /** `context.configure` alpha mode (the consumer's — default `"premultiplied"`). */
+    alphaMode?: GPUCanvasAlphaMode;
+    /** Extra device-request options (features/limits). */
+    deviceDescriptor?: GPUDeviceDescriptor;
+    /** Adapter-request options (e.g. `powerPreference`). */
+    adapterOptions?: GPURequestAdapterOptions;
+    /** `"capture"` pre-seeds the `manual` suspension (renderAt-only). Default `"live"`. */
+    mode?: "live" | "capture";
+    /**
+     * Honor `prefers-reduced-motion: reduce` by painting ONE static frame then
+     * parking the loop. The shared lifecycle core live-monitors the query via a
+     * `matchMedia` `change` listener and re-arms (one static frame) on un-reduce.
+     * Default `true` for live mode, `false` for capture mode.
+     */
+    respectReducedMotion?: boolean;
+    /**
+     * Build the WGSL pipeline + bind groups on the resolved device. Called on the
+     * async arm AND on every device-restore. Returns the per-frame hooks.
+     */
+    setup: (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;
+    /** Surface a device-init / validation failure (no WebGPU adapter, a `setup` throw). */
+    onInitError?: (error: unknown) => void;
+}
+export interface WebGPUCanvasHandle {
+    /**
+     * Run the expensive ASYNC init (adapter + device + context.configure + `setup`)
+     * THEN arm the loop. Resolves once armed (or rejects-via-`onInitError` on a
+     * device-unavailable / `setup` failure). Idempotent; a no-op post-dispose.
+     */
+    armAsync: () => Promise<void>;
+    /**
+     * Synchronous `arm` — a no-op until `armAsync` has resolved the device (the
+     * uniform-handle parity with the synchronous backends; the picker calls
+     * `armAsync` for the WebGPU path). Idempotent.
+     */
+    arm: () => void;
+    suspend: (reason?: WebGPUSuspendReason) => void;
+    resume: (reason?: WebGPUSuspendReason) => void;
+    /** Re-arm a parked loop (a setter that re-introduced motion calls this). */
+    wake: () => void;
+    /** Draw one frame at `timeSec` out-of-loop (capture / thumbnail). */
+    renderAt: (timeSec: number) => void;
+    dispose: () => void;
+    /** The live device (null before armAsync / after dispose / mid-loss). */
+    readonly device: GPUDevice | null;
+    /**
+     * The live `prefers-reduced-motion: reduce` state. The shared lifecycle core
+     * owns + re-monitors it; consumers read it (e.g. a viz freezes its frame time
+     * at the authored offset while this is `true`).
+     */
+    readonly reducedMotion: boolean;
+}
+export declare function createWebGPUCanvas(canvas: HTMLCanvasElement, options: WebGPUCanvasOptions): WebGPUCanvasHandle;

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

@@ -10,3 +10,4 @@ export * from "../useViewTransition";
 export * from "../vReveal";
 export * from "../useTextHighlight";
 export * from "../useLiquidFlex";
+export * from "../usePointerVelocityField";

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

@@ -2,6 +2,10 @@ export * from "./constants";
 export * from "./useSpring";
 export * from "./useSpringMount";
 export * from "./useSpringPress";
+export * from "./useLiquidPress";
+export * from "./useDragMorph";
+export * from "./useLiquidReveal";
+export * from "./useDockCtaReceive";
 export * from "./useNumericTransition";
 export * from "./useAnimatedNumber";
 export * from "./useAnimatedNumberMap";

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

@@ -0,0 +1,59 @@
+import { type Ref } from "vue";
+import { type SpringPresetName } from "./springPresets";
+/** The receive spring register — `snappy` (the crisp absorb default) or `bouncy`
+ *  (the emphatic land-with-overshoot). A subset of the named `SPRING_PRESETS` rows,
+ *  matching `useLiquidReveal`'s register so the two seams read as ONE family. */
+export type DockCtaReceivePreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+export interface UseDockCtaReceiveOptions {
+    /**
+     * The target dock control the CTA morphs INTO — the destination rect (the
+     * `<DockIconButton>`/dock control element). When null at receive time, the morph
+     * is a no-op snap (no destination to fly to) and `onReceived` fires immediately.
+     */
+    dockControl: Ref<HTMLElement | null>;
+    /** The spring register (default `snappy`). */
+    preset?: DockCtaReceivePreset;
+    /** The ending congest blur radius in px (the CTA dissolves into the glass). Default 4. */
+    blur?: number;
+    /** Honor `prefers-reduced-motion: reduce` (snap to gone, then hand off). Default true. */
+    respectReducedMotion?: boolean;
+    /**
+     * Fired ONCE when the CTA has landed on the dock control (the hand-off seam) — the
+     * consumer hides the CTA + activates the dock control here. Fires on the animation
+     * settle AND on the PRM/no-target snap (the gesture always completes).
+     */
+    onReceived?: () => void;
+}
+export interface UseDockCtaReceiveReturn {
+    /**
+     * Morph the CTA into the dock control. Idempotent per call — measures the CTA +
+     * dock-control rects fresh, drives the spring 0→1 (fly+reshape+fade+congest). A
+     * no-op if the CTA element is not yet mounted (no `onReceived`).
+     */
+    receive: () => void;
+    /**
+     * Clear the morph transform (restore the CTA to its own rect, opacity 1) — the
+     * abort/reset seam. Cancels any in-flight morph; does NOT fire `onReceived`.
+     */
+    reset: () => void;
+}
+/**
+ * The external-CTA-into-dock-control morph. Composes the SAME kf `ElementMorph` +
+ * `springTimingFunction` substrate `useLiquidReveal` activates, driven FORWARD (the
+ * reveal's inverse): the CTA flies + reshapes from its own rect onto the dock
+ * control's rect, fades + congests into the glass on the spring clock, then hands off.
+ * Compositor-only + PRM-seats. See the module header for the REUSE + the FORWARD-play
+ * mechanism + the channel split.
+ *
+ * @example
+ * ```ts
+ * const { receive, reset } = useDockCtaReceive(ctaRef, {
+ *   dockControl: dockTargetRef,
+ *   preset: "snappy",
+ *   onReceived: () => (ctaConsumed.value = true),
+ * })
+ * // on the CTA click: morph it into the dock.
+ * function onCta() { receive() }
+ * ```
+ */
+export declare function useDockCtaReceive(cta: Ref<HTMLElement | null>, options: UseDockCtaReceiveOptions): UseDockCtaReceiveReturn;

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

@@ -0,0 +1,77 @@
+import { type ComputedRef, type Ref } from "vue";
+/** The morph axis — `"x"` tracks the inline (horizontal) travel, `"y"` the block. */
+export type DragMorphAxis = "x" | "y";
+/**
+ * One snap target on the drag axis. `value` is the consumer's domain value (the
+ * tab/layer id) committed via `onSnap`; `center` is the target's center coordinate
+ * in the SAME px space the drag tracks (the element's offset-axis center).
+ */
+export interface DragMorphSnapTarget<V = string> {
+    value: V;
+    center: number;
+}
+export interface UseDragMorphParams<V = string> {
+    /** The draggable element ref (the indicator/handle the gesture captures). */
+    el: Ref<HTMLElement | null>;
+    /** The morph axis (`"x"` horizontal · `"y"` vertical). May be a getter. */
+    axis: DragMorphAxis | (() => DragMorphAxis);
+    /**
+     * The ordered snap targets, resolved off the consumer's geometry (the
+     * center-anchored button/layer centers). May be a getter so a re-measure
+     * (a resize, an option change) re-resolves them without reconstruction.
+     */
+    snapTargets: readonly DragMorphSnapTarget<V>[] | (() => readonly DragMorphSnapTarget<V>[]);
+    /**
+     * The live cap getter for the squish (`--tab-indicator-max-stretch`, ≤1.08).
+     * Defaults to the shared 1.08 fence; a getter re-reads the cascade override.
+     */
+    maxStretch?: () => number;
+    /**
+     * Fired ONCE on settle at the nearest snap with the committed value. The
+     * consumer writes its `v-model` here — the single source of truth.
+     */
+    onSnap: (value: V) => void;
+    /** Honor `prefers-reduced-motion: reduce` (squish off, instant snap). Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseDragMorphReturn {
+    /** True while a pointer gesture is in progress (down, not yet settled). */
+    dragging: Readonly<Ref<boolean>>;
+    /** The live drag position on the morph axis (px), for diagnostics/tests. */
+    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
+     * this to rebuild the `Draggable` over the SAME reused spring). Idempotent;
+     * a no-op while a gesture is in flight (the rebuild waits for settle).
+     */
+    refresh: () => void;
+    /** Tear down — detach the `Draggable`, dispose the spring + watchers. */
+    detach: () => void;
+}
+/**
+ * The abstract pull/drag-to-morph-squish gesture. Composes kf `Draggable`
+ * (pointer-capture follow + velocity + snap-aware fling) + `SpringProgress` (the
+ * physics core) + `useLiquidFlex` (`"tanh"` velocity-squish) into ONE gesture with
+ * a consumer-wired single-commit `onSnap`. See the module header for the REUSE +
+ * compositor-only + PRM rationale.
+ *
+ * @example
+ * ```ts
+ * const { dragging, stretch, dragStyle, detach } = useDragMorph({
+ *   el: indicatorRef,
+ *   axis: () => (isVertical.value ? "y" : "x"),
+ *   snapTargets: () => buttonRefs.value.map((b, i) => ({
+ *     value: options.value[i].value,
+ *     center: b.offsetLeft + b.offsetWidth / 2,
+ *   })),
+ *   maxStretch: () => readCap(),
+ *   onSnap: (v) => { model.value = v },
+ * })
+ * ```
+ */
+export declare function useDragMorph<V = string>(params: UseDragMorphParams<V>): UseDragMorphReturn;

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

@@ -53,6 +53,17 @@ export interface UseLiquidFlexReturn {
     /**
      * The size as a CSS length style object, keyed on `axis` (`{ width: "Npx" }` or
      * `{ height: "Npx" }`). Bind on the morphing element's style.
+     *
+     * DOCTRINE (BB.W-MOTION-CANON, P5 — the SIZESTYLE-LATENT record): `sizeStyle`
+     * is the SETTLED-FOOTPRINT writer — a one-time reserve of the morph TARGET box
+     * (the FLIP-measured `to` span), NEVER the per-frame animation channel. The
+     * per-frame channel is `transform` (the `stretchStyle` `--stretch` reciprocal
+     * scale, a compositor property). Binding `sizeStyle` to a CONTINUOUSLY-animated
+     * element animates `width`/`height` per frame OFF the compositor (the A'-3
+     * reflow-storm class proof:no-layout-animation forbids library-wide) — FORBIDDEN
+     * by the canon. Write the reserved footprint ONCE at the morph endpoint, then
+     * drive the visible motion through `stretchStyle`/`transform`. See
+     * `docs/precepts/motion-canon.md` P5.
      */
     sizeStyle: ComputedRef<Record<string, string>>;
     /**

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

@@ -0,0 +1,71 @@
+import { type CSSProperties, type ComputedRef, type Ref } from "vue";
+import { type UseSpringPressOptions } from "./useSpringPress";
+export interface UseLiquidPressOptions extends UseSpringPressOptions {
+    /**
+     * The uniform press SHRINK depth — the contraction the press scale reaches at
+     * `t=1` (the iOS uniform shrink the reciprocal squish deforms AROUND). The X axis
+     * reads `shrink·stretch`, the Y axis `shrink/stretch` (the volume preserved on the
+     * travel axis). Default 0.03 (the button `--scale-press-btn` 0.97 magnitude — the
+     * JS path AGREES with the CSS `.tap-squish active:scale` floor). A calmer surface
+     * (the dock control's no-overshoot tap register) passes a smaller depth.
+     */
+    shrinkDepth?: number;
+    /**
+     * The LOW reciprocal-squish cap handed to `useLiquidFlex` (the +N% elongation along
+     * the travel axis). Default 1.04 (a button has no size span — the deform is a
+     * lively settle, never a taffy-pull). Kept LOW by the liquid register.
+     */
+    maxStretch?: number;
+    /**
+     * The custom-property NAME the live press value (0..1) is written under, for the
+     * surface CSS to read for the coupled brightness/specular leg. Default
+     * `"--press-t"`. Button passes `"--glass-btn-press-t"` (the W-BUTTON-GLASS drive
+     * the gleam already reads); the dock control passes `"--dock-press-t"`.
+     */
+    pressVar?: string;
+    /**
+     * Below this travel threshold the inline `scale` is OMITTED from `pressStyle` so the
+     * surface's at-rest CVA/utility transforms (a hover `scale`) win unimpeded; the JS
+     * reciprocal scale wins ONLY while the press is engaged (the single-source press,
+     * then yields back to the cascade as it settles). Default 0.001.
+     */
+    engageThreshold?: number;
+}
+export interface UseLiquidPressReturn {
+    /** The live spring press value (0 released → 1 pressed, with the spring overshoot). */
+    value: Readonly<Ref<number>>;
+    /** Drive the press to 1 (call on `pointerdown`). Interruptible — re-targets the live spring. */
+    press: () => void;
+    /** Release the press to 0 (call on `pointerup`/`cancel`/`leave`). */
+    release: () => void;
+    /** Pointer handlers ready to spread onto an element (the `useSpringPress` ergonomics). */
+    handlers: {
+        onPointerdown: () => void;
+        onPointerup: () => void;
+        onPointercancel: () => void;
+        onPointerleave: () => void;
+    };
+    /**
+     * The coupled press style — the ONE `:style` object a consumer binds. Carries the
+     * reciprocal X/Y `scale` (engaged only past `engageThreshold`) AND the `pressVar`
+     * 0..1 drive scalar the surface CSS reads for the brightness/specular leg.
+     * Compositor-only (`scale` + a custom property — never a layout property).
+     */
+    pressStyle: ComputedRef<CSSProperties>;
+}
+/**
+ * The ONE interruptible, coupled spring-press. Composes `useSpringPress` (the spring
+ * driver, PRM-aware) + `useLiquidFlex` (the volume-preserving reciprocal squish) and
+ * exposes a single `pressStyle` object + the pointer `handlers`.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const press = useLiquidPress()
+ * </script>
+ * <template>
+ *   <button v-bind="press.handlers" :style="press.pressStyle" />
+ * </template>
+ * ```
+ */
+export declare function useLiquidPress(options?: UseLiquidPressOptions): UseLiquidPressReturn;