@mkbabb/glass-ui 4.2.0 → 5.0.0

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

@@ -0,0 +1,96 @@
+import type { BackingSize, DprPolicy } from "../webgl/createCanvasLifecycle";
+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;
+    /**
+     * Upload the backing geometry. BD.W-SUBSTRATE-SIZE-UNIFY: 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.
+     */
+    resize: (s?: BackingSize) => 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;
+    /**
+     * BD.W-SUBSTRATE-SIZE-UNIFY (G1/G2) — 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). */
+    composeIntersectionPark?: boolean;
+    /** `rootMargin` for the leaf IO park (G3). */
+    intersectionRootMargin?: string;
+    /** Fire the one-shot cold-first-VISIBLE entrance bloom (BG.W-VIZ-REVEAL-BLOOM — the `data-substrate-reveal` attr). 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). */
+    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;
+    /** BD.W-SUBSTRATE-SIZE-UNIFY (G2) — size the backing + start the leaf RO synchronously, before the 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). */
+    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;
+}

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

@@ -40,3 +40,33 @@ export declare class WebGPUInitError extends Error {
  * across UAs); a throwing read is morally "cannot prove software" → keep WebGPU.
  */
 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
+ * 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
+ * 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.
+ */
+export declare const WEBGPU_ACQUIRE_TIMEOUT_MS = 6000;
+/**
+ * Race a WebGPU acquisition promise against a timeout. On a hang the timeout wins and
+ * rejects with the recognized typed `acquire-timeout` signal (the picker falls to the
+ * WebGL2 net on it, exactly like a no-adapter host). The timer is cleared the instant
+ * the acquisition settles (resolve OR reject), so a healthy device leaves no dangling
+ * timeout. SSR-safe: with no `setTimeout` the bare promise passes through (a non-DOM
+ * runtime has no WebGPU surface to hang anyway).
+ *
+ * `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).
+ */
+export declare function withAcquireTimeout<T>(promise: Promise<T>, label: string): Promise<T>;

package/dist/composables/index.d.ts

@@ -5,6 +5,5 @@ export * from "./dom";
 export * from "./motion";
 export * from "./motion/core";
 export * from "./glass";
-export * from "./sortable";
 export * from "./sidebar";
-export * from "../components/custom/infinite-scroll/composables";
+export * from "../components/infinite-scroll/composables";

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

@@ -0,0 +1,29 @@
+import type { Ref } from "vue";
+/** The BE.W-AMBIENT-TINT bound (sub-perceptual; never a flood — the warm-cream identity holds). */
+export declare const AMBIENT_STRENGTH_CEILING = 8;
+/** The live reduced-motion probe (matchMedia, SSR-safe). */
+export declare function prefersReducedMotion(): boolean;
+/** Clamp the ambient-strength target into the bounded warm-cream-identity band `[0, 8]`. */
+export declare function clampStrength(n: number | undefined): number;
+/**
+ * Resolve the FIELD container the 4th color channel writes onto. Explicit `field` ref
+ * wins; else walk up from `dest` to the nearest `[data-glass-field]` ancestor (the
+ * field-marker contract); else `dest.parentElement`. The field is a DIFFERENT element
+ * from the blooming surface — the compositor-only de-risk.
+ */
+export declare function resolveField(dest: HTMLElement, explicit: Ref<HTMLElement | null> | undefined): HTMLElement | null;
+/**
+ * Read the source's dominant hue — the explicit `fieldHue` OR the `--glass-ambient-hue`
+ * computed off the source element (the AMBIENT-TINT source). Returns `null` for a
+ * neutral/absent hue (the field tints nothing).
+ */
+export declare function resolveHue(source: HTMLElement | null, explicit: string | undefined): string | null;
+/** Set the field's dominant hue (the 4th-channel hue, set ONCE — not animated). */
+export declare function writeFieldHue(field: HTMLElement, hue: string): void;
+/** Write the field's ambient strength (the registered @property interpolates it). */
+export declare function writeFieldStrength(field: HTMLElement, pct: number): void;
+/**
+ * Release the field bias back to the no-op floor (0%) and clear the hue so the field returns
+ * to its un-biased `--glass-tint-ink` (the warm-cream identity).
+ */
+export declare function releaseField(field: HTMLElement | null): void;

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

@@ -10,11 +10,15 @@ export * from "../useViewTransition";
 export * from "../vReveal";
 export * from "../useTextHighlight";
 export * from "../useLiquidFlex";
+export * from "../useLeadTrail";
 export * from "../useGooMorph";
-export * from "../useMorphField";
+export * from "../morphSignatures";
 export * from "../usePointerVelocityField";
+export * from "../useRoutePointer";
+export * from "../pointerFieldMappings";
 export * from "../useCharStagger";
 export * from "../useScrollTrigger";
 export * from "../useScrollChrome";
-export * from "./useHaptic";
 export * from "./writeVelocityWeight";
+export * from "../useSelectionIndicator";
+export * from "../useSelectionGroup";

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

@@ -0,0 +1,79 @@
+/** The golden ratio — the barbell body diameter is the golden-minor of the slot pitch. */
+export declare const PHI = 1.618033988749895;
+/** sin(π·p)^k — 0 at the ends, peak at the midpoint. The well shape. */
+export declare function bell(p: number, k: number): number;
+/**
+ * The barbell body diameter `D = step/φ` (a round BLOB, not a plate — the
+ * golden-minor of the slot pitch). Floors the step at 1 so a zero pitch never
+ * collapses D to 0.
+ */
+export declare function bodyDiameter(step: number): number;
+/** The inputs to a single barbell projection frame — all numeric, all pure. */
+export interface BarbellSpan {
+    /** The trailing slot center (px on the travel axis). */
+    A: number;
+    /** The leading slot center (px on the travel axis). */
+    B: number;
+    /** The `from` slot index. */
+    fromIdx: number;
+    /** The `to` slot index. */
+    toIdx: number;
+    /** The live interpolated `--goo-t` scalar (∈ [fromIdx, toIdx] in flight). */
+    gooT: number;
+    /** The resting slot pitch (px) — `D = step/φ` lands the body diameter. */
+    step: number;
+    /** The neck-gap fraction: how near the two bodies draw at the midpoint. */
+    neckGap: number;
+    /** The cartoon-weight lever (0..1; clamped here — 0 under PRM/auto). */
+    weight: number;
+}
+/** The projected barbell geometry the engine writes onto the three elements. */
+export interface BarbellGeometry {
+    /** The body diameter `D = step/φ`. */
+    D: number;
+    /** The trailing body center (bodyA). */
+    cA: number;
+    /** The leading body center (bodyB). */
+    cB: number;
+    /** The neck center (the midpoint of the two bodies). */
+    mid: number;
+    /** The on-axis neck span scale `gap/D` (spans the live centre-to-centre gap). */
+    neckSpanScale: number;
+    /** The cross-axis neck girth (wells → pinches, ~0 at the ends). */
+    neckGirth: number;
+    /** The on-axis body squash (the necking-taffy stretch). */
+    stretchOn: number;
+    /** The cross-axis body stretch (volume-preserving reciprocal). */
+    stretchCross: number;
+    /** The cross-axis lob arc (overlapping action — the merge LOBS, not slides). */
+    arc: number;
+}
+/**
+ * Project the BARBELL for the in-flight scalar `gooT`. `p` is the NORMALIZED
+ * progress over the WHOLE from→to travel (a multi-gap morph spans p∈[0,1] over
+ * the full span, so the barbell necks across the BIG gap on the SAME slow flow
+ * curve). Pure — no closure, no DOM, no state.
+ *   sep(p)      = 1 − bell(p,1)·(1 − neckGap)   // 1 at the slots → neckGap at mid
+ *   mid         = (A + B) / 2 ; half = (B − A)/2 · sep(p)
+ *   cA = mid − half ; cB = mid + half           // bodies travel apart-then-together
+ *   neckGirth(p)= bell(p,1.5)                     // wells, peaks mid, ~0 at the ends
+ */
+export declare function projectBarbell(span: BarbellSpan): BarbellGeometry;
+/**
+ * Compose a BODY transform on the travel axis: translate(center) → -50% → scale +
+ * the on-axis squash-&-stretch reciprocal (volume-preserving). `el` is sized to the
+ * body diameter D, so no scale-to-fit is needed; the squash is the `--stretch` taffy.
+ * The `arc` lobs the body centre on the CROSS axis (overlapping action). Pure string.
+ */
+export declare function composeBodyTransform(center: number, arc: number, stretchOn: number, stretchCross: number, vertical: boolean): string;
+/**
+ * Compose the NECK transform: translate(mid) on-axis, scaleX(gap/D) on-axis so it
+ * spans the live gap, scaleY(neckGirth) cross-axis so it WELLS then PINCHES (~0 at
+ * the ends → the neck vanishes at rest, no ghost throat). Pure string.
+ */
+export declare function composeNeckTransform(mid: number, neckSpanScale: number, neckGirth: number, vertical: boolean): string;
+/**
+ * Compose the RESTING NECK transform — the neck pinched to ~0 at the coalesced
+ * center (no ghost throat at rest). Pure string.
+ */
+export declare function composeRestNeckTransform(center: number, vertical: boolean): string;

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

@@ -4,10 +4,10 @@ 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 "./useCelebrationBurst";
 export * from "./useNumericTransition";
 export * from "./useAnimatedNumber";
 export * from "./useAnimatedNumberMap";

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

@@ -0,0 +1,88 @@
+/** The five motion VECTORS a signature selects (geometry/motion, never an app name). */
+export type MorphVector = "lateral" | "radial" | "inward" | "axial" | "directed";
+/**
+ * The motion SIGNATURE — DATA, the only thing that distinguishes the morphs. `vector`
+ * picks the geometry; `kRest`/`kPeak` are gap-FRACTIONS (not px) the threshold band
+ * scales by; `neckHold` is how long the neck holds before it pinches; `maxStretch` the
+ * LOW squish cap (the anti-taffy fence).
+ */
+export interface MorphSignature {
+    vector: MorphVector;
+    /** The neck-gap fraction at REST (bodies apart) — the threshold band floor. */
+    kRest: number;
+    /** The neck-gap fraction at the PEAK (bodies near, the gooey waist) — the band ceiling. */
+    kPeak: number;
+    /** How long (0..1 of t) the neck HOLDS its girth before it pinches (the tense pop). */
+    neckHold: number;
+    /** The LOW on-axis squish cap (≤~1.14 — the loud register lives in NECK girth, not body taffy). */
+    maxStretch: number;
+}
+/**
+ * The canonical, motion-named SIGNATURE map (DATA — the FLOOR). Every consumer reads a
+ * `MorphSignatureName` row. NO app names, NO three code paths.
+ */
+export declare const MORPH_SIGNATURES: {
+    /** carousel / deck / pager goo: two equal beads bud apart, a concave neck wells, the
+     *  filter merges them into one barbell with a thin pinched waist, then they coalesce. */
+    readonly lateralNeck: {
+        readonly vector: "lateral";
+        readonly kRest: 0.92;
+        readonly kPeak: 0.34;
+        readonly neckHold: 0.5;
+        readonly maxStretch: 1.12;
+    };
+    /** dock fission media: the now-playing anchor stays; flanking transport PEELS along
+     *  the cross axis with a long tapering neck tail. */
+    readonly lateralPeel: {
+        readonly vector: "lateral";
+        readonly kRest: 0.88;
+        readonly kPeak: 0.4;
+        readonly neckHold: 0.4;
+        readonly maxStretch: 1.08;
+    };
+    /** dock fission search: controls fly outward like a bloom; the neck NECKS LATE (the
+     *  tense radial pop), innermost-first — an outward ripple, not a simultaneous scatter. */
+    readonly radialBurst: {
+        readonly vector: "radial";
+        readonly kRest: 0.85;
+        readonly kPeak: 0.3;
+        readonly neckHold: 0.55;
+        readonly maxStretch: 1.08;
+    };
+    /** dock fission nav: the negative radial — N masses collapse INWARD to ONE; the bridge
+     *  runs backward; --stretch peaks at coalescence. */
+    readonly inwardMerge: {
+        readonly vector: "inward";
+        readonly kRest: 0.8;
+        readonly kPeak: 0.28;
+        readonly neckHold: 0.35;
+        readonly maxStretch: 1.1;
+    };
+    /** dock V↔H: column-mass + row-mass are two distributions in ONE topology-free field;
+     *  a gooey teardrop LOBS column→row through the midpoint (no crossfade dodge). */
+    readonly axialNeck: {
+        readonly vector: "axial";
+        readonly kRest: 0.9;
+        readonly kPeak: 0.36;
+        readonly neckHold: 0.5;
+        readonly maxStretch: 1.14;
+    };
+    /** dock collapse: the DEGENERATE 1-body field — a single mass squishes between two
+     *  footprints (no waist, Tier-C). The ratio-free convex blend. */
+    readonly collapse: {
+        readonly vector: "axial";
+        readonly kRest: 1;
+        readonly kPeak: 1;
+        readonly neckHold: 0;
+        readonly maxStretch: 1.14;
+    };
+    /** drag morph: a grabbed rect → drop rect, an optional directed neck. */
+    readonly directed: {
+        readonly vector: "directed";
+        readonly kRest: 0.9;
+        readonly kPeak: 0.42;
+        readonly neckHold: 0.45;
+        readonly maxStretch: 1.1;
+    };
+};
+export type MorphSignatureName = keyof typeof MORPH_SIGNATURES;

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

@@ -0,0 +1,9 @@
+/** The identity tempo — no time scaling (the `@property` initial-value). */
+export declare const MOTION_TEMPO_IDENTITY = 1;
+/**
+ * Read the effective `--motion-tempo` off `el` (or `:root` when omitted). Returns a
+ * positive multiplier (the identity `1` off-DOM, on a malformed value, or on any
+ * value ≤ 0). Read once at spring construction — a tempo change is a settings-level
+ * knob (a re-mount picks it up), never a per-frame read.
+ */
+export declare function motionTempo(el?: Element | null): number;

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

@@ -0,0 +1,161 @@
+import type { PointerVec2 } from "./usePointerVelocityField";
+export type { PointerVec2 };
+/**
+ * A plain-value read of the pointer field for ONE frame. The renderer snapshots the field
+ * refs (`.value`) into this before calling a mapping — the mappings stay Vue-ref-free (pure).
+ */
+export interface PointerFieldSnapshot {
+    /** The raw live pointer target (0..1), pre-smoothing. */
+    position: PointerVec2;
+    /** The snappy critically-damped smoothed position (0..1). */
+    smoothedPosition: PointerVec2;
+    /** The mass-spring-damper attractor — the ONE eased-follow (0..1). */
+    attractor: PointerVec2;
+    /** The smoothed velocity (normalized-host units/second). */
+    velocity: PointerVec2;
+    /** The smoothed acceleration (the second derivative). */
+    acceleration: PointerVec2;
+    /** The transient flick-burst impulse (0..1). */
+    burst: number;
+    /** The smoothed active-engagement envelope (0..1). */
+    engagement: number;
+}
+/** The default bias gain — the curve advances at most ±BIAS_GAIN faster/slower (≤0.15). */
+export declare const FOURIER_BIAS_GAIN = 0.15;
+/** The default centroid-lean fraction (the subtle lean; supersedes FOLLOW_REACH=0.7). */
+export declare const FOURIER_FOLLOW_LEAN = 0.15;
+export interface FourierLeanGeometry {
+    /** The canvas backing aspect (w/h) — the model→clip fit inverse. */
+    aspect: number;
+    /** The fit scale (`model = center + clip·aspect / scale`). */
+    scale: number;
+    /**
+     * The head→cursor direction in CLIP space (the renderer computes it from the head
+     * model position + the cursor clip position). Its dot with the head's travel tangent
+     * is the draw-bias alignment. Omit (or zero) → no draw-bias (phaseRateMul = 1).
+     */
+    headToCursor?: PointerVec2;
+    /** The head's travel TANGENT (clip space), for the draw-bias alignment. Omit → no bias. */
+    headTangent?: PointerVec2;
+}
+export interface FourierLeanOptions {
+    /** The centroid-lean fraction (default {@link FOURIER_FOLLOW_LEAN}). */
+    lean?: number;
+    /** The draw-bias gain (default {@link FOURIER_BIAS_GAIN}; clamped ≤0.15). */
+    biasGain?: number;
+}
+export interface FourierLeanResult {
+    /** The MODEL-space centroid lean the setups subtract from `fit.center`. */
+    leanX: number;
+    leanY: number;
+    /**
+     * The clock phase-rate multiplier (1 = neutral). >1 draws toward the cursor a hair
+     * faster; <1 a hair slower. Bounded [1-biasGain, 1+biasGain].
+     */
+    phaseRateMul: number;
+}
+/**
+ * The fourier draw-bias + subtle-lean mapping (PURE). The lean uses the SAME [0,1]→clip
+ * (y-inverted) → model math the renderer inverts, at the subtle FOLLOW_LEAN (NOT the retired
+ * FOLLOW_REACH teleport), scaled by engagement. The draw-bias modulates the clock phase-rate
+ * by the head-tangent · head→cursor alignment, bounded by biasGain.
+ */
+export declare function fourierLeanMapping(snap: PointerFieldSnapshot, geom: FourierLeanGeometry, options?: FourierLeanOptions): FourierLeanResult;
+/** The steady velocity-lead gain (the body anticipates the heading). */
+export declare const BLOB_LEAD_K = 0.09;
+/** The pseudopod stretch gain off |acceleration| (capped LOW so it swells, never taffies). */
+export declare const BLOB_STRETCH_GAIN = 0.6;
+/** The pseudopod stretch cap. */
+export declare const BLOB_STRETCH_MAX = 0.35;
+export interface BlobPullOptions {
+    leadK?: number;
+    stretchGain?: number;
+    stretchMax?: number;
+}
+export interface BlobPullResult {
+    /** The body-follow target in [-1,1] body space. */
+    x: number;
+    y: number;
+    /** The transient pseudopod stretch (0..stretchMax) off deceleration. */
+    stretch: number;
+}
+/**
+ * The blob heavy-pull mapping (PURE). Maps the field attractor (0..1) → [-1,1] body space
+ * with a steady velocity-lead, and derives a transient pseudopod stretch from the
+ * deceleration magnitude (a fast flick that brakes grows a pseudopod, then it relaxes).
+ */
+export declare function blobPullMapping(snap: PointerFieldSnapshot, options?: BlobPullOptions): BlobPullResult;
+/** The default aurora cursor influence radius (the prior cursorModel default). */
+export declare const AURORA_CURSOR_RADIUS = 0.25;
+export interface AuroraCursorOptions {
+    /** The active strength ceiling (cfg.strength; default 0.8 — the prior setCursor default). */
+    strength?: number;
+    /** The influence radius (0.05..0.5; default {@link AURORA_CURSOR_RADIUS}). */
+    radius?: number;
+}
+export interface AuroraCursorResult {
+    /** The cursor position (0..1, CSS-top-origin — the bridge flips Y). */
+    cx: number;
+    cy: number;
+    /** The engagement-driven attraction strength (0..1). */
+    strength: number;
+    /** The influence radius. */
+    radius: number;
+    /** The velocity for the velocity-reactive swirl (normalized/second). */
+    velX: number;
+    velY: number;
+    /** The transient flick-burst (0..1). */
+    burst: number;
+}
+/**
+ * The aurora cursor mapping (PURE). The attractor is the cursor position, the engagement
+ * envelope drives the strength (so the cursor-local luminance lean reads on the SMOOTH
+ * medium), and the velocity + burst pass straight onto the `uCursor*` uniforms.
+ */
+export declare function auroraCursorMapping(snap: PointerFieldSnapshot, options?: AuroraCursorOptions): AuroraCursorResult;
+export interface ConstellationWellResult {
+    /** The well centre (0..1). */
+    x: number;
+    y: number;
+    /** The well strength (0..1 engagement). */
+    engagement: number;
+    /** The flick-burst impulse (0..1). */
+    burst: number;
+    /** The pointer velocity (normalized/second) — for a directional wake. */
+    velX: number;
+    velY: number;
+}
+/**
+ * The constellation well mapping (PURE). Projects the field onto the pointer-well inputs the
+ * kept per-node integrators read — position + engagement (well strength) + burst (impulse).
+ */
+export declare function constellationWellMapping(snap: PointerFieldSnapshot): ConstellationWellResult;
+/**
+ * Read a `usePointerVelocityField` handle into a plain-value {@link PointerFieldSnapshot} —
+ * the ONE ref→plain bridge the renderers call once per frame before invoking a mapping (the
+ * mappings never touch a Vue ref). Accepts any object exposing the field's `.value`-bearing
+ * refs.
+ */
+export declare function snapshotField(field: {
+    position: {
+        value: PointerVec2;
+    };
+    smoothedPosition: {
+        value: PointerVec2;
+    };
+    attractor: {
+        value: PointerVec2;
+    };
+    velocity: {
+        value: PointerVec2;
+    };
+    acceleration: {
+        value: PointerVec2;
+    };
+    burst: {
+        value: number;
+    };
+    engagement: {
+        value: number;
+    };
+}): PointerFieldSnapshot;

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

@@ -1,5 +1,5 @@
 /** A glass-ui named-spring preset name. */
-export type SpringPresetName = "smooth" | "snappy" | "bouncy" | "gentle" | "dock" | "press" | "timeline-head" | "timeline-fill" | "timeline-press";
+export type SpringPresetName = "smooth" | "snappy" | "bouncy" | "gentle" | "dock" | "press" | "transient" | "eyeglass";
 /** One named-spring row: the analytic (response, dampingFraction) pair + its register doc. */
 export interface SpringPresetRow {
     /** The token suffix — `--spring-<name>` (CSS) and the `MOTION_CURVES` key. */
@@ -12,36 +12,30 @@ export interface SpringPresetRow {
     readonly comment: string;
 }
 /**
- * iOS-canonical (response, dampingFraction) pairs per AL-X4 §3. The names match
- * the `--spring-*` CSS tokens AND the speedtest CSS consumers that read
- * `var(--spring-smooth)` etc. directly, so they MUST stay stable across retunes —
- * only the `(response, ζ)` pair and the emitted curves change.
- *
- * GOVERNED iOS-SPRING VOCABULARY (AX.W05) — the SINGLE source of the register
- * vocabulary. Each row's `comment` names the surface-class that rides it:
+ * iOS-canonical (response, dampingFraction) pairs. The names match the `--spring-*`
+ * CSS tokens AND the CSS consumers that read `var(--spring-smooth)` etc. directly, so
+ * they MUST stay stable across retunes — only the `(response, ζ)` pair and the emitted
+ * curves change. Each row's `comment` describes the register it serves (the doc-table
+ * on /motion/springs derives from that one string):
  *
  *   SETTLE  → smooth  — patient entrances, fades, scale-ins (no overshoot read).
  *   CONTROL → snappy  — crisp position morphs: tab underline glide, progress fill,
  *                       the continuous-marker pop, the generic crisp settle.
  *   PLAYFUL → bouncy  — deliberate emphatic one-shots ONLY: the bouncy toggle press,
- *                       dialog/success entrances, the VT default. Largest overshoot.
+ *                       dialog/success entrances. Largest overshoot.
  *   GENTLE  → gentle  — critically-damped slow settles (the patient end of the ladder).
  *   DOCK    → dock    — the dock expand/collapse morph AND everything inside it.
- *   PRESS   → press   — the iOS interactive tap-press: sub-100ms answer, a tiny alive
- *                       rebound. `useSpringPress` reads this row's (response, ζ).
+ *   PRESS   → press   — the iOS interactive tap-press: a sub-200ms answer, a tiny alive
+ *                       rebound.
+ *   TRANSIENT → transient — the center-seed materialize bloom (Toast + Notification):
+ *                       a deep scale-from with a near-critically-damped settle (no flick).
+ *   EYEGLASS → eyeglass — the iOS tab-pill loupe travel: snappy speed with dock-class give.
  *
- * BD.W-ANIM-IOS27-TUNE — the GLOBAL re-calibration toward the iOS-27
- * weighty-gooey-inertial pole (USER law: "SMOOTH, CONTROLLED, INERTIA, AUDACIOUS;
- * NO overly tight and springy; MORPH MORE on move"). ALL SIX rows are re-tuned in
- * lockstep toward lower stiffness (longer `response` → inertia/weight) + higher
- * through-body damping toward critically-damped-with-a-TOUCH-of-overshoot (kill the
- * pointed flick) + longer settle (the flowing arrival) — WHILE keeping the perceptual
- * arrival AUDACIOUS (t90 mid-clock for smooth/snappy/press; bouncy/dock arrive earlier
- * via the overshoot carry = the FLOWING-mass read). There are NO byte-frozen KEEPS any
- * more (the BC.W-SPRING-EASE surgical KEEP fence is RETIRED). The invariant fences:
- *   · every overshoot ∈ [0%,10%] — the "touch of overshoot" band; the OLD pointed
- *     bouncy 12.6% / dock 10.7% are RETIRED (>10% is the "too springy" defect).
- *   · every NON-gentle settle LENGTHENS vs the pre-BD baseline (the inertia floor);
+ * The whole table sits at the iOS weighty-inertial pole: longer `response` (weight) +
+ * through-body damping toward critically-damped-with-a-touch-of-overshoot, while keeping
+ * the perceptual arrival audacious. The invariant fences:
+ *   · every overshoot ∈ [0%,10%] — the "touch of overshoot" band (>10% reads too springy).
+ *   · every non-gentle settle is at least as long as the calm baseline (the inertia floor);
  *     nothing gets faster (faster = the mechanical-snap defect).
  *   · t90 ∈ [50%,61%] of clock for smooth/snappy/press (the audacious-arrival floor).
  *   · gentle ζ stays EXACTLY 1.0 (the --ease-convergence alias depends on overshoot==0).