@mkbabb/glass-ui 3.13.0 → 4.0.1

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;

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

@@ -0,0 +1,51 @@
+import { type Ref } from "vue";
+import { type SpringPresetName } from "./springPresets";
+/** The reveal spring register — `snappy` (the quick app-open default) or `bouncy`
+ *  (the emphatic large-dialog bloom). A subset of the named `SPRING_PRESETS` rows. */
+export type LiquidRevealPreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+export interface UseLiquidRevealOptions {
+    /**
+     * The trigger element the surface blooms FROM — the source rect (the button, the
+     * collapsed dock pill). When null at reveal time, the bloom degrades to a
+     * center-anchored scale-from-self (the no-trigger fallback — still spring-clocked,
+     * never the flat bezier zoom).
+     */
+    trigger?: Ref<HTMLElement | null>;
+    /** The spring register (default `snappy`). */
+    preset?: LiquidRevealPreset;
+    /** The starting backdrop-blur radius in px (the decongest start). Default 4. */
+    blur?: number;
+    /** Honor `prefers-reduced-motion: reduce` (snap to settled, fade only). Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseLiquidRevealReturn {
+    /**
+     * Bloom the surface open from the trigger's rect. Idempotent per call — measures
+     * the trigger + settled rects fresh, drives the inversion spring 1→0. A no-op if
+     * the surface element is not yet mounted.
+     */
+    reveal: () => void;
+    /**
+     * Snap the surface to its settled identity (clear the bloom transform/blur). The
+     * EXIT is the CSS recipe's `--ease-out` no-overshoot leg (a closing surface must
+     * not overshoot past gone) — this leaf clears the enter transform so the recipe's
+     * exit owns the close.
+     */
+    conceal: () => void;
+}
+/**
+ * The iOS-27 source-rect bloom. Composes the dormant kf `ElementMorph` +
+ * `springTimingFunction` into the three-channel liquid open (scale+fade+blur-settle
+ * from the trigger's origin), compositor-only + PRM-snap. See the module header for
+ * the REUSE + bloom-mechanism (FLIP inversion) + the channel split.
+ *
+ * @example
+ * ```ts
+ * const { reveal, conceal } = useLiquidReveal(surfaceRef, {
+ *   trigger: triggerRef,
+ *   preset: "bouncy",
+ * })
+ * watch(open, (o) => (o ? reveal() : conceal()))
+ * ```
+ */
+export declare function useLiquidReveal(surface: Ref<HTMLElement | null>, options?: UseLiquidRevealOptions): UseLiquidRevealReturn;

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

@@ -30,9 +30,9 @@ export interface UseNumericTransitionOptions<K extends string> {
      * (a name now resolves only through the ASYNC `resolveEasing`, which crosses
      * the value.js dynamic boundary the dock/motion light surface must never
      * pull in). Narrowing glass-ui's public option to a callable decouples it
-     * from keyframes' name-resolution churn AND is assignable to every supported
-     * keyframes major (2.2 / 3 / 4). A consumer wanting a named curve passes the
-     * function directly (e.g. `(t) => 1 - Math.pow(1 - t, 3)` for easeOutCubic).
+     * from keyframes' name-resolution churn. A consumer wanting a named curve
+     * passes the function directly (e.g. `(t) => 1 - Math.pow(1 - t, 3)` for
+     * easeOutCubic).
      */
     timingFunction?: TimingFunction;
     /** Per-frame consumer. Receives the same zero-allocation record each tick. */

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

@@ -0,0 +1,98 @@
+import { type Ref } from "vue";
+/** A 2-vector in normalized-host space (0..1 across the host box). */
+export interface PointerVec2 {
+    x: number;
+    y: number;
+}
+export interface UsePointerVelocityFieldOptions {
+    /**
+     * The smoothing rate for the eased POSITION (0..1 per second-equivalent; higher
+     * = snappier approach). Default 0.22 (the cursorModel `CURSOR_POS_LERP` snappy
+     * register). The viz reads `position`/`smoothedPosition`; the velocity is its
+     * derivative.
+     */
+    positionLerp?: number;
+    /**
+     * The smoothing rate for the derived VELOCITY (0..1; higher = velocity tracks the
+     * live delta faster, lower = a longer momentum tail). Default 0.3 (the cursorModel
+     * `CURSOR_VELOCITY_LERP`).
+     */
+    velocityLerp?: number;
+    /**
+     * The smoothing rate for the derived ACCELERATION (0..1). Default 0.3 — the accel
+     * term tracks the velocity-delta on the same register as the velocity itself.
+     */
+    accelerationLerp?: number;
+    /**
+     * The per-tick burst decay multiplier (the transient swirl-impulse a fast flick
+     * injects, decaying over ~1s). Default 0.96 (the cursorModel
+     * `CURSOR_BURST_DECAY_PER_FRAME`, ≈0.96^60≈0.09 after 1s at 60fps).
+     */
+    burstDecay?: number;
+    /**
+     * Honor `prefers-reduced-motion: reduce` → `tick(0)` freeze (no live velocity).
+     * Default true. (A deterministic viz capture that ACCEPTS live dynamics opts out.)
+     */
+    respectReducedMotion?: boolean;
+}
+export interface UsePointerVelocityField {
+    /** True while the pointer is over the host (down between enter and leave). */
+    readonly active: Readonly<Ref<boolean>>;
+    /** The RAW live pointer target in normalized-host space (0..1), pre-smoothing. */
+    readonly position: Readonly<Ref<PointerVec2>>;
+    /** The eased/smoothed pointer position the velocity derives from (0..1). */
+    readonly smoothedPosition: Readonly<Ref<PointerVec2>>;
+    /** The smoothed pointer VELOCITY (normalized-host units per second). */
+    readonly velocity: Readonly<Ref<PointerVec2>>;
+    /** The scalar velocity magnitude (`hypot(velocity)`), the common viz read. */
+    readonly speed: Readonly<Ref<number>>;
+    /** The smoothed pointer ACCELERATION (the second derivative — the accel term). */
+    readonly acceleration: Readonly<Ref<PointerVec2>>;
+    /** The transient flick-burst impulse (0..1, decays over ~1s). */
+    readonly burst: Readonly<Ref<number>>;
+    /**
+     * The `@pointermove` handler — schedules NO frame; it only stashes the raw target
+     * (PRM-gated). The renderer's `tick` does the smoothing/derivation on its OWN
+     * frame. Bind on the host (or call `setPointer` directly from a custom listener).
+     */
+    onPointerMove: (event: PointerEvent) => void;
+    /** Bind on the host `@pointerenter` (sets `active`). */
+    onPointerEnter: () => void;
+    /** Bind on the host `@pointerleave` (clears `active`; the field decays to rest). */
+    onPointerLeave: () => void;
+    /**
+     * Set the raw pointer target directly in normalized-host space (0..1) — for a
+     * viz that already owns its pointer→uv mapping (a WebGPU surface reading
+     * clip-space coords). PRM-gated like `onPointerMove`.
+     */
+    setPointer: (xNorm: number, yNorm: number) => void;
+    /**
+     * Advance the physics ONE renderer frame. The viz calls this from INSIDE its
+     * existing frame callback with the frame `delta` (ms). NO own rAF — the renderer
+     * owns the loop. Under PRM (or an explicit `tick(0)`) the field freezes to rest
+     * (no live velocity). Returns the live field (so a renderer can read inline).
+     */
+    tick: (deltaMs: number) => void;
+    /** Snap the whole field to rest (position held, velocity/accel/burst zeroed). */
+    reset: () => void;
+    /** Tear down the cached PRM listener (auto-run on scope dispose). */
+    dispose: () => void;
+}
+/**
+ * The shared viz-pointer-physics field — pointer POSITION + derived VELOCITY +
+ * derived ACCELERATION (the accel term), advanced by the renderer's frame `tick`
+ * (NO own rAF), frozen under PRM (`tick(0)`). The procedural-viz family reads the
+ * field for pointer dynamics; the position is event-driven, the derivatives are
+ * computed in `tick`.
+ *
+ * @example
+ * ```ts
+ * const field = usePointerVelocityField()
+ * // in the renderer's frame callback (the ONE loop the canvas lifecycle owns):
+ * function onFrame({ delta }) {
+ *   field.tick(delta)                       // advance the physics, no second rAF
+ *   uploadUniforms({ vel: field.velocity.value, accel: field.acceleration.value })
+ * }
+ * ```
+ */
+export declare function usePointerVelocityField(options?: UsePointerVelocityFieldOptions): UsePointerVelocityField;

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

@@ -5,6 +5,17 @@
  *  (one symmetric curve), which is functionally identical (the swap still runs). */
 export interface ViewTransitionOptions {
     types?: string[];
+    /**
+     * BA.W-ATLAS-RECONCILE A-4b — take the JS-level INSTANT path under
+     * `prefers-reduced-motion: reduce` (run `mutate` directly, NO snapshot
+     * captured). The HEAD default pushes PRM to CSS only (`view-transition.css`
+     * sets `animation: none` on the VT pseudos) — but that STILL captures a
+     * snapshot. For the navigation case a reduced-motion user wants the swap to
+     * happen with no transition machinery at all; `navigate()` sets this true.
+     * Defaults to `false` so the existing sync-VT consumers (muster J.W5 row
+     * re-rank) keep their exact CSS-handled PRM behaviour. @default false
+     */
+    instantUnderReducedMotion?: boolean;
 }
 export interface ViewTransitionResult {
     /**
@@ -43,4 +54,28 @@ export declare function supportsViewTransitions(): boolean;
  *   // directional intent — snappier exit on collapse, softer entry on expand
  *   startViewTransition(() => mutate(), { types: ["dock-expand"] });
  */
-export declare function startViewTransition(mutate: () => void, options?: ViewTransitionOptions): ViewTransitionResult;
+export declare function startViewTransition(mutate: () => void | Promise<void>, options?: ViewTransitionOptions): ViewTransitionResult;
+/** Options for `navigate` — the directional transition `types` (Chrome 140+,
+ *  feature-detected; tag `["forward"]`/`["back"]` off the navigation direction). */
+export type NavigateOptions = ViewTransitionOptions;
+/**
+ * Run a (possibly ASYNC) navigation callback wrapped in a View Transition, with
+ * the reduced-motion + unsupported instant-paths. The navigation ALWAYS runs
+ * (awaited); the morph is conditional on support + motion preference. Returns the
+ * same `{ finished, transitioned }` contract — `await navigate(go).finished` then
+ * route focus (the a11y MANDATORY).
+ *
+ * @example  the card → masthead route morph
+ *   // both the card title + masthead title carry
+ *   //   view-transition-class: gl-shared-element; view-transition-name: dash-title
+ *   await navigate(() => router.push(`/${slug}`), { types: ["forward"] }).finished;
+ *   mastheadTitle.value?.focus();
+ */
+export declare function navigate(nav: () => void | Promise<void>, options?: NavigateOptions): ViewTransitionResult;
+/**
+ * True when the route-transition morph can run (native VT available). A consumer
+ * gates VT-only navigation styling on this (alias of `supportsViewTransitions`
+ * named for the navigation call site). Under reduced motion the `navigate` helper
+ * still takes the instant path even when this is `true`.
+ */
+export declare function supportsRouteTransitions(): boolean;

package/dist/concentric.d.ts

@@ -0,0 +1 @@
+export * from "./components/custom/concentric";