@mkbabb/glass-ui 4.1.0 → 5.0.0

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";
+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,40 +12,33 @@ 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.
  *
- * BC.W-SPRING-EASE — the retune that eases the two abrupt curves + mints the press
- * register (USER-DEFECTS §B/§D, the "squishy/quick/coupled" mandate). The retune is
- * SURGICAL — `smooth`/`dock`/`gentle` are byte-frozen KEEPS:
- *   · snappy: response 0.35 / ζ 0.65 → 0.42 / 0.78. The old pair front-loaded — its
- *     2%-band travel collapsed into the first ~16% of the clock then sat dead-flat.
- *     The eased pair spreads the travel so the 90%-point lands mid-clock (the analytic
- *     90%-travel fraction t₉₀/t_settle ≈ 0.57, in the [0.55,0.70] target band), keeping
- *     it QUICK (0.34s clock) with a whisper of life (overshoot ~+2.0%, ≤ the +7% bar).
- *   · bouncy: ζ 0.45 → 0.55. Overshoot drops +20.5% → +12.6%, into the Apple 12-18%
- *     band (apple-ios27.md §5 "ease toward ζ0.55-0.60 if abrupt"; ζ=1−bounce ⇒ bounce
- *     0.45, more playful than Apple's 0.30 but controlled). response stays 0.5. ζ 0.55
- *     is the band floor — the +14% prose target maps here once the overshoot is solved
- *     analytically (ζ 0.60 lands +9.5%, BELOW the band; the proof's S2 floor is ζ≥0.55).
- *   · press: MINTED at response 0.15 / ζ 0.86 — the Apple `interactiveSpring`
- *     (apple-ios27.md §2.2/§2.5). The press answers in the sub-100ms iOS window with a
- *     sub-perceptual alive rebound (~+0.5%). `useSpringPress` defaults re-point onto it.
+ * 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).
  */
 export declare const SPRING_PRESETS: readonly SpringPresetRow[];
 /** Lookup one preset row by name (used by `MOTION_CURVES` spring rows). */

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

@@ -1,2 +1,2 @@
-export { NumericAnimation, SpringProgress, SmoothProgress, Sequence, Timeline, ManualTimeline, RAFPlayback, ScrollTimeline, createNativeTimeline, flip, flipShared, ElementMorph, drag, Draggable, decay, decayRest, stagger, springTimingFunction, springLinearStops, toEasing, resolveEasing, AnimationOptionError, UnknownEasingError, loadAnimationEngine, } from "@mkbabb/keyframes.js";
-export type { Easing, TimingFunction, TimingFunctionNames, SpringProgressOptions, SpringFrameCallback, SpringSubscriber, SpringLinearStopsOptions, SpringTimingFunctionOptions, SmoothProgressOptions, NumericAnimationOptions, NumericFrameCallback, SequenceEntry, SequenceOptions, SequencePosition, TimelineOptions, NativeTimelineSpec, RAFPlaybackOptions, Tickable, FlipOptions, ElementMorphOptions, MorphRect, DragOptions, DragAxis, DragSubscriber, DecayOptions, DecaySample, StaggerFn, StaggerOptions, StaggerOrigin, AnimationEngine, AnimationOptions, AnimationFrame, AnimateOptions, InputAnimationOptions, ResolvedKeyframes, Vars, } from "@mkbabb/keyframes.js";
+export { NumericAnimation, SpringProgress, SmoothProgress, Oscillator, Sequence, Timeline, ManualTimeline, RAFPlayback, KeyframesScrollTimeline, createNativeTimeline, flip, flipShared, ElementMorph, drag, drag2D, Draggable, decay, decayRest, reseatToSpring, probeVelocity, reducedMotionScale, waveformValue, warmEngine, stagger, springTimingFunction, springLinearStops, toEasing, resolveEasing, AnimationOptionError, UnknownEasingError, loadAnimationEngine, } from "@mkbabb/keyframes.js";
+export type { Easing, TimingFunction, TimingFunctionNames, SpringProgressOptions, SpringFrameCallback, SpringSubscriber, SpringLinearStopsOptions, SpringTimingFunctionOptions, SmoothProgressOptions, NumericAnimationOptions, NumericFrameCallback, SequenceEntry, SequenceOptions, SequencePosition, TimelineOptions, NativeTimelineSpec, RAFPlaybackOptions, Tickable, FlipOptions, ElementMorphOptions, MorphRect, DragOptions, DragAxis, DragSubscriber, DecayOptions, DecaySample, StaggerFn, StaggerOptions, StaggerOrigin, AnimationEngine, AnimationOptions, AnimationFrame, InputAnimationOptions, ResolvedKeyframes, Vars, } from "@mkbabb/keyframes.js";

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

@@ -0,0 +1,97 @@
+import { type Ref } from "vue";
+import { type SpringPresetName } from "./springPresets";
+/** The bloom spring register — `snappy` (the quick shared-element default) or `bouncy`
+ *  (the emphatic large-surface bloom). A subset of the named `SPRING_PRESETS` rows,
+ *  matching `useLiquidReveal`/`useDockCtaReceive` so the bloom family reads as ONE. */
+export type BloomUpPreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+export interface UseBloomUpOptions {
+    /** The spring register (default `snappy`). */
+    preset?: BloomUpPreset;
+    /** The starting filter-blur radius in px on the destination (the decongest start). Default 4. */
+    blur?: number;
+    /**
+     * The dominant source hue the FIELD warms toward — a complete `<color>` (an
+     * `oklch()`/`#hex`/named). When omitted, the leaf reads `--glass-ambient-hue` off
+     * the SOURCE element's computed style (the BE.W-AMBIENT-TINT convergence — the
+     * album card carries its own dominant hue). A `transparent`/empty read is the
+     * neutral no-op (the field tints nothing — a gray source warms nothing).
+     */
+    fieldHue?: string;
+    /**
+     * The FIELD CONTAINER the 4th color channel writes onto — the destination's
+     * ancestor field (the DockStage / now-playing field). When omitted, the leaf walks
+     * up from `destRef` to the nearest ancestor carrying `[data-glass-field]` (the
+     * field-marker contract), falling back to `destRef.parentElement`. The hue + the
+     * ramped strength are written HERE, never on the blooming surface (the
+     * compositor-only floor de-risk).
+     */
+    field?: Ref<HTMLElement | null>;
+    /**
+     * The bounded ambient-strength target the field ramps to (a percentage, `0..8`).
+     * Default 8 (the AMBIENT-TINT ceiling — the loudest sub-perceptual warm). Clamped
+     * to `[0, 8]` so a consumer can never flood the field past the warm-cream identity.
+     */
+    fieldStrength?: number;
+    /** Honor `prefers-reduced-motion: reduce` (snap surface to settled, land hue instantly). Default true. */
+    respectReducedMotion?: boolean;
+    /**
+     * Auto-prime the destination the moment it mounts — seat it at the collapsed/hidden
+     * initial state (opacity 0 + the source-FLIP transform) BEFORE the browser paints,
+     * so a freshly-`v-if`-mounted dest never flashes its full-size frame before `bloom()`
+     * fires. A `watch(dest, …, { flush: "pre" })` runs in the SAME tick the element
+     * mounts. Default `true` — the no-flash floor; pass `false` to opt a consumer that
+     * owns its own initial-state seating out. `prime()` is the explicit imperative twin.
+     */
+    autoPrime?: boolean;
+    /**
+     * Fired ONCE when the bloom has settled (the hand-off — the consumer marks the
+     * bloom complete: hides the source, owns the destination). Fires on the animation
+     * settle AND on the PRM/no-rAF snap (the bloom always completes).
+     */
+    onBloomed?: () => void;
+}
+export interface UseBloomUpReturn {
+    /**
+     * Bloom the destination up from the source's rect. Idempotent per call — measures
+     * the source + destination rects fresh, drives the FLIP inversion spring 1→0 on the
+     * surface AND ramps the field hue 0→target. A no-op if the destination element is
+     * not yet mounted (no `onBloomed`).
+     */
+    bloom: () => void;
+    /**
+     * Clear the bloom transform (restore the destination to its settled identity,
+     * opacity 1) AND release the field hue (strength → 0). The abort/reset seam —
+     * cancels any in-flight bloom; does NOT fire `onBloomed`.
+     */
+    reset: () => void;
+    /**
+     * Seat the destination at its collapsed/hidden initial state (opacity 0 + the
+     * source-FLIP transform) WITHOUT animating — so a freshly-mounted dest shows
+     * NOTHING until `bloom()` fires (the no-mount-flash seam). Idempotent; a no-op if
+     * the dest is not yet mounted. The auto-prime (`autoPrime`, default on) calls this
+     * for the consumer; `prime()` is the explicit imperative twin.
+     */
+    prime: () => void;
+    /** The reactive bloom state — `true` while a bloom is in flight, `false` at rest. */
+    blooming: Readonly<Ref<boolean>>;
+}
+/**
+ * The iOS-27 shared-element bloom with the 4th color channel. Composes the kf
+ * `ElementMorph` + `springTimingFunction` into the three-channel geometry bloom on the
+ * DESTINATION surface (scale+fade+blur-decongest from the SOURCE's origin) PLUS a 4th
+ * color channel on the destination FIELD (the field warms to the source's hue on the
+ * SAME spring curve). Compositor-only on the surface + Safari-safe + PRM-snap. See the
+ * module header for the REUSE + the FLIP inversion + the channel split.
+ *
+ * @example
+ * ```ts
+ * const { bloom, reset, blooming } = useBloomUp(albumCardRef, fullscreenRef, {
+ *   preset: "bouncy",
+ *   fieldHue: albumDominantHue, // or omit to read --glass-ambient-hue off the card
+ *   field: nowPlayingFieldRef,
+ *   onBloomed: () => (fullscreenOpen.value = true),
+ * })
+ * function onTapAlbum() { bloom() }
+ * ```
+ */
+export declare function useBloomUp(source: Ref<HTMLElement | null>, dest: Ref<HTMLElement | null>, options?: UseBloomUpOptions): UseBloomUpReturn;

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

@@ -1,16 +1,17 @@
-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">;
+import { type ComponentPublicInstance, type Ref } from "vue";
+import { type ElementMorphPreset } from "./useElementMorph";
+/** The receive spring register — `snappy` (the crisp absorb default) or `bouncy` (the
+ *  emphatic land-with-overshoot). Matches `useLiquidReveal`'s register so the two seams
+ *  read as ONE family. */
+export type DockCtaReceivePreset = ElementMorphPreset;
 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.
+     * The dock control the CTA flies onto — a templateRef to the control ELEMENT or to a
+     * component (e.g. `<DockControl>`), whose root element is resolved via `.$el`. When
+     * null at receive time, the morph is a no-op snap (nowhere to fly) and `onReceived`
+     * fires immediately.
      */
-    dockControl: Ref<HTMLElement | null>;
+    dockControl: Ref<HTMLElement | ComponentPublicInstance | null>;
     /** The spring register (default `snappy`). */
     preset?: DockCtaReceivePreset;
     /** The ending congest blur radius in px (the CTA dissolves into the glass). Default 4. */
@@ -25,60 +26,34 @@ export interface UseDockCtaReceiveOptions {
     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`).
-     */
+    /** Morph the CTA into the dock control (drives the FORWARD play). 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`.
-     */
+    /** Clear the morph transform (restore the CTA to its own rect, opacity 1) — the
+     *  abort/reset seam. Does NOT fire `onReceived`. */
     reset: () => void;
-    /**
-     * ARM the landing SEAT (BC.W-AX-DOCK-CTA-SEAT). Writes `data-cta-pending` on the
-     * `dockControl` element so the seat partial (`src/styles/dock/cta-seat.css`) paints
-     * a dim ghost AND reserves the resting control footprint (a STATIC `min-inline-size`
-     * /`min-block-size` off `--dock-control-size`/`--dock-layer-height`) — the dock box
-     * is already at the seated width, so it does NOT jump when the CTA lands. Idempotent.
-     * A no-op when the `dockControl` is not yet mounted. Sets `pending.value = true`.
-     */
+    /** ARM the landing seat — write `data-cta-pending` on the dock control (the seat
+     *  reserves its resting footprint + shows a dim ghost). Idempotent. */
     setPending: () => void;
-    /**
-     * CLEAR the seat. Removes `data-cta-pending` from the `dockControl`, so the seat
-     * reveals its real content with the FLIP `transition: opacity` (the partial owns the
-     * paint — a calm content fade, NOT the dock morph-stagger). Idempotent. The default
-     * `onReceived` flow calls this on hand-off (the seat reveals as the CTA lands) unless
-     * the consumer drives it manually. Sets `pending.value = false`.
-     */
+    /** CLEAR the seat — remove `data-cta-pending`, so the seat reveals its real content
+     *  with the `transition: opacity` FLIP. Idempotent. */
     clearPending: () => void;
     /** The reactive seat state — the consumer binds `:class`/`v-if` off it. */
     pending: Readonly<Ref<boolean>>;
 }
 /**
- * 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.
+ * The external-CTA-into-dock-control morph. A ≤20-line adapter over `useElementMorph` —
+ * declares the receive as a `direction: "out"` FORWARD play flying ONTO the dock control,
+ * opacity + blur coupled, the runner's `onSettled` firing the seat clear + `onReceived`.
+ * The seat writes (`setPending`/`clearPending`) stay wrapper-local (data-attr, not motion).
  *
  * @example
  * ```ts
- * const { receive, setPending, clearPending, pending, reset } = useDockCtaReceive(
- *   ctaRef,
- *   {
- *     dockControl: dockTargetRef,
- *     preset: "snappy",
- *     onReceived: () => (ctaConsumed.value = true),
- *   },
- * )
- * // ARM the seat (the dock control shows the dim ghost + reserves its footprint).
- * setPending()
- * // on the CTA click: morph it into the dock (the default hand-off clearPending()s,
- * // revealing the seated content with the opacity FLIP — no box jump).
- * function onCta() { receive() }
+ * const { receive, setPending, pending } = useDockCtaReceive(ctaRef, {
+ *   dockControl: dockTargetRef, onReceived: () => (ctaConsumed.value = true),
+ * })
+ * setPending()          // arm the seat (dim ghost + footprint reserve)
+ * function onCta() { receive() }  // morph the CTA in; the default hand-off clearPending()s
  * ```
  */
-export declare function useDockCtaReceive(cta: Ref<HTMLElement | null>, options: UseDockCtaReceiveOptions): UseDockCtaReceiveReturn;
+export declare function useDockCtaReceive(cta: Ref<HTMLElement | ComponentPublicInstance | null>, options: UseDockCtaReceiveOptions): UseDockCtaReceiveReturn;

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

@@ -0,0 +1,99 @@
+import { type MorphRect } from "@mkbabb/keyframes.js";
+import { type ComponentPublicInstance, type Ref } from "vue";
+import { type SpringPresetName } from "./springPresets";
+/** A morph endpoint — a templateRef to an element/component, or the literal `"self"`
+ *  (the morphed surface's OWN settled rect). */
+export type MorphEndpoint = Ref<HTMLElement | ComponentPublicInstance | null> | "self";
+/** The morph register — `snappy` (the quick app-open default) or `bouncy` (the emphatic
+ *  large-surface bloom). A subset of the named `SPRING_PRESETS` rows shared by every
+ *  bloom leaf so the family reads as ONE spring register. */
+export type ElementMorphPreset = Extract<SpringPresetName, "snappy" | "bouncy">;
+/** The declarative channel set the morph couples onto the spring clock. */
+export interface MorphChannels {
+    /** Fade the surface with the morph (opacity = 1 − morphProgress). Default `true`. */
+    opacity?: boolean;
+    /** The `filter: blur()` magnitude in px at the small `to` end (decongest/congest).
+     *  Default `0` (no blur channel). */
+    blur?: number;
+}
+export interface UseElementMorphOptions {
+    /** The `apply(el,0)` endpoint. Default `"self"` (the surface's own settled rect). */
+    from?: MorphEndpoint;
+    /** The `apply(el,1)` endpoint (the foreign trigger/source/dock-control). A null-
+     *  resolving ref degrades to a 92%-inset of the surface's own rect (the no-anchor
+     *  self-scale fallback — still spring-clocked, never a flat zoom). */
+    to?: MorphEndpoint;
+    /** `"in"` = FLIP inversion 1→0 (arrive at `from`); `"out"` = forward 0→1 (depart to
+     *  `to`). Default `"in"`. */
+    direction?: "in" | "out";
+    /** The coupled channels (opacity + blur). */
+    channels?: MorphChannels;
+    /** The spring register (default `snappy`). Sampled via `springPreset(name)`. */
+    preset?: ElementMorphPreset;
+    /** `transform-origin` resolution: anchor at `from`/`to` (relative to the surface),
+     *  `"center"`, or a raw CSS string. Default `"to"`. */
+    origin?: "from" | "to" | "center" | string;
+    /** Honor `prefers-reduced-motion: reduce` (snap to terminal, fade survives). Default `true`. */
+    respectReducedMotion?: boolean;
+    /** Fired ONCE at the terminal (animation settle AND the PRM/SSR snap) — the hand-off
+     *  seam (the cta seat clear + onReceived, the bloom field-land + onBloomed). */
+    onSettled?: () => void;
+    /** Fired each frame with the clamped [0,1] eased ARRIVAL progress — the extra-channel
+     *  hook (the bloom field-strength ramp). Not called on the PRM/SSR snap; `onSettled`
+     *  lands the terminal value there. */
+    onFrame?: (progress: number) => void;
+}
+export interface UseElementMorphReturn {
+    /** Measure `from`/`to` fresh + drive the morph. Interruptible — a mid-flight `play()`
+     *  re-measures + retargets (never restarts from the current computed value). */
+    play: () => void;
+    /** Cancel any in-flight morph + release the transition lock (does NOT clear styles
+     *  or fire `onSettled` — the abort seam). */
+    cancel: () => void;
+    /** Clear the inline morph styles (transform/origin/opacity/filter) — the reset seam. */
+    clear: (el?: HTMLElement | null) => void;
+    /** Statically seat the morph at a fixed [0,1] progress WITHOUT animating (the no-
+     *  mount-flash prime — transform only, no rAF, no lock). */
+    seat: (progress: number) => void;
+    /** `true` while a morph is in flight. */
+    playing: Readonly<Ref<boolean>>;
+    /** The live eased ARRIVAL progress (0 at play start → 1 at settle). */
+    progress: Readonly<Ref<number>>;
+}
+/**
+ * Resolve a templateRef value to its root HTMLElement — accepts an element directly OR a
+ * Vue component public instance (its `.$el`). Returns null for a fragment/text root or a
+ * nullish ref. THIS is the [[glass-ui binding verification]] cure: a `ref` bound to a
+ * COMPONENT resolves to the component public INSTANCE (no `getBoundingClientRect`/
+ * `setAttribute`), so the morph silently no-ops / throws. Every bloom leaf imports this
+ * ONE resolver (the α binding-verification fix) — a surface/trigger binds either an
+ * element ref or a component ref without dying.
+ */
+export declare function asElement(v: HTMLElement | ComponentPublicInstance | null | undefined): HTMLElement | null;
+/** The 92%-inset self-scale fallback (a null-resolving anchor blooms from a small inset
+ *  of the surface's own rect — never a flat zoom). */
+export declare function insetSelf(r: MorphRect): MorphRect;
+/**
+ * The driver-lock seam — set inline `transition-property: none` on `el` (beating the F5.2
+ * liquid-weight `transition` default + any Tailwind `transition*` utility) so the rAF
+ * transform writes are not fought; the returned release restores the prior value.
+ */
+export declare function lockSpatialTransition(el: HTMLElement): () => void;
+/** The live reduced-motion probe (matchMedia, SSR-safe) — exported so a wrapper that owns
+ *  a NON-animated terminal seat (the cta "snap gone + hand off") shares the ONE probe. */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * The ONE compositor FLIP/morph runner. Composes the kf `ElementMorph` +
+ * `springTimingFunction` into a single interruptible, PRM-safe, compositor-only morph the
+ * three bloom leaves collapse onto. See the module header for the two directions + the
+ * channel math + the PRM snap + the driver-lock seam.
+ *
+ * @example
+ * ```ts
+ * const engine = useElementMorph(surfaceRef, {
+ *   to: triggerRef, direction: "in", channels: { opacity: true, blur: 4 },
+ * })
+ * watch(open, (o) => (o ? engine.play() : engine.cancel()))
+ * ```
+ */
+export declare function useElementMorph(surface: Ref<HTMLElement | ComponentPublicInstance | null>, options?: UseElementMorphOptions): UseElementMorphReturn;

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

@@ -0,0 +1,72 @@
+import { type Ref } from "vue";
+/**
+ * The three barbell silhouette elements the engine projects per frame. NOT
+ * `morph.children[i]` index-reaching (the fragile KISS-violating path) — three EXPLICIT
+ * refs the consumer renders + binds.
+ */
+export interface GooBarbellRefs {
+    /** The trailing round body (the OUTGOING droplet). */
+    bodyARef: Ref<HTMLElement | null>;
+    /** The leading round body (the INCOMING droplet). */
+    bodyBRef: Ref<HTMLElement | null>;
+    /** The welling concave-throat neck between the two bodies. */
+    neckRef: Ref<HTMLElement | null>;
+}
+export interface UseGooMorphParams {
+    /**
+     * The barbell silhouette refs — two round bodies + a welling concave neck. The engine
+     * writes their three transforms each frame (the merge needs ≥2 masses; the neck is the
+     * bridge). NO single-element `morphRef` — the barbell IS the morph.
+     */
+    barbellRefs: GooBarbellRefs;
+    /** The geometry origin + the `--goo-t` transition host (the rail/track root). */
+    hostRef: Ref<HTMLElement | null>;
+    /** Travel axis. `false` → horizontal (translateX), `true` → vertical (translateY). */
+    vertical: Ref<boolean>;
+    /**
+     * Live center reader: the on-axis center (px, relative to the host content box)
+     * of slot `i`, on the travel axis. MEASURED off the live DOM (windowFit-correct,
+     * both axes) — never a hardcoded pitch.
+     */
+    centerOf: (i: number) => number | null;
+    /**
+     * The resting slot pitch (px) on the travel axis. The barbell body diameter is the
+     * golden-minor `D = restSize()/φ` (a BLOB, not a plate) — so the consumer passes the
+     * slot STEP, not a pre-shrunk body size.
+     */
+    restSize: () => number;
+    /**
+     * The token prefix for the flow/duration/max-stretch reads. Default `"pager-worm"`
+     * (the dot-pip register). The carousel passes `"carousel-goo"`; the deck `"deck-goo"`
+     * — each reads its OWN `--{prefix}-flow`/`-duration`/`-max-stretch` so a card-scale
+     * barbell dwells/swells at its own scale, the dot at its own. ONE engine, per-consumer
+     * tokens (the no-new-spring fence — they all resolve `--spring-*`-derived `linear()`).
+     */
+    tokenPrefix?: string;
+    /**
+     * The neck-gap fraction — how near the two bodies draw at the midpoint (sep's floor:
+     * 1 at the slots → `neckGap` at mid). Lower = the bodies near closer → a tighter,
+     * gooier waist. Default 0.78 (carousel). Pager 0.7, deck 0.85. (= `--{prefix}-neck-gap`
+     * if the consumer prefers a token; the param is the engine default.)
+     */
+    neckGap?: number;
+}
+export interface UseGooMorphReturn {
+    /**
+     * Travel the barbell from `from` to `to` (slot indices). Sets the `--goo-t`
+     * transition target (the spring glides it) and runs a short rAF that projects the
+     * interpolated scalar onto the three-element barbell each frame. PRM → instant snap to
+     * ONE resting body, no squish.
+     */
+    travel(from: number, to: number): void;
+    /** Snap the barbell to ONE resting body on `index` immediately (first paint / resize / PRM). */
+    snap(index: number): void;
+    /**
+     * Drag-driven continuous drive: set `--goo-t` DIRECTLY to a fractional slot position
+     * (the live drag scrollProgress, e.g. embla's `scrollProgress()*lastIndex`) with NO
+     * transition, and project the barbell for it. The neck wells with the live drag; call
+     * `travel()` on the snap to glide the release. PRM → snap.
+     */
+    drive(fractionalIndex: number): void;
+}
+export declare function useGooMorph(params: UseGooMorphParams): UseGooMorphReturn;