@mkbabb/glass-ui 4.2.0 → 6.0.0

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).

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

@@ -0,0 +1,16 @@
+import { type TimingFunction } from "@mkbabb/keyframes.js";
+import type { SpringPresetRow } from "./springPresets";
+type SpringParameters = Pick<SpringPresetRow, "response" | "dampingFraction">;
+/** Internal projection shared by token generation and the Springs lab. */
+export interface SpringProjection {
+    readonly settleSeconds: number;
+    readonly sampleCount: number;
+    readonly stops: string;
+    readonly timingFunction: TimingFunction;
+}
+export declare const SPRING_TOKEN_SAMPLE_COUNT = 48;
+/** Numeric 2%-band settle, rounded to the token register's nearest 10 ms. */
+export declare function springSettleDurationSeconds(parameters: SpringParameters): number;
+/** Project one spring through the exact horizon and density used by CSS tokens. */
+export declare function springProjection(parameters: SpringParameters): SpringProjection;
+export {};

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

@@ -18,10 +18,7 @@ export interface UseAnimatedNumberOptions {
     /** Per-frame side-effect hook. Receives the smoothed current value. */
     onValue?: (value: number) => void;
 }
-/**
- * The `useAnimatedNumber` return shape (AW.W15 — named `Use<Name>Return`
- * convention). `AnimatedNumber` is the preserved alias so import sites stay put.
- */
+/** The `useAnimatedNumber` return shape. */
 export interface UseAnimatedNumberReturn {
     /** Reactive smoothed value. Bind in templates. */
     current: Readonly<Ref<number>>;
@@ -34,8 +31,6 @@ export interface UseAnimatedNumberReturn {
     /** Stop the smoother and target watcher. */
     dispose: () => void;
 }
-/** Preserved alias for {@link UseAnimatedNumberReturn} (AW.W15). */
-export type AnimatedNumber = UseAnimatedNumberReturn;
 /**
  * Track a live numeric target with exponentially damped hysteresis.
  *

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

@@ -1,8 +1,5 @@
 import { type Ref } from "vue";
-/**
- * The `useCountup` return shape (AW.W15 — named `Use<Name>Return` convention).
- * `Countup` is the preserved alias so existing import sites do not break.
- */
+/** The `useCountup` return shape. */
 export interface UseCountupReturn {
     /** Animate the count-ups inside the currently-active slide/region. */
     runActive: () => void;
@@ -11,8 +8,6 @@ export interface UseCountupReturn {
     /** Cancel every in-flight tween (also runs on scope-dispose). */
     cancel: () => void;
 }
-/** Preserved alias for {@link UseCountupReturn} — keeps import sites stable (AW.W15). */
-export type Countup = UseCountupReturn;
 export interface UseCountupOptions {
     /**
      * Easing applied to tween progress — a value.js-FREE callable

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

@@ -1,21 +1,64 @@
 import { type ComponentPublicInstance, 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 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 type DockCtaReceivePath = "fine" | "coarse" | "reduced-motion" | "no-target";
+export type DockCtaReceivePhase = "idle" | "receiving" | "settled" | "handed-off" | "completed" | "reset";
+export interface DockCtaReceiveBand {
+    readonly latencyFactor: readonly [number, number];
+    readonly travelPx: readonly [number, number];
+    readonly scaleRatio: readonly [number, number];
+}
+/** Product bounds relative to the selected spring's measured analytic horizon. */
+export declare const DOCK_CTA_RECEIVE_BANDS: {
+    readonly fine: {
+        readonly latencyFactor: readonly [0.9, 1.2];
+        readonly travelPx: readonly [16, 520];
+        readonly scaleRatio: readonly [0.2, 1.4];
+    };
+    readonly coarse: {
+        readonly latencyFactor: readonly [0.9, 1.2];
+        readonly travelPx: readonly [16, 360];
+        readonly scaleRatio: readonly [0.2, 1.4];
+    };
+    readonly "reduced-motion": {
+        readonly latencyFactor: readonly [0, 0.017];
+        readonly travelPx: readonly [0, 0];
+        readonly scaleRatio: readonly [1, 1];
+    };
+    readonly "no-target": {
+        readonly latencyFactor: readonly [0, 0.017];
+        readonly travelPx: readonly [0, 0];
+        readonly scaleRatio: readonly [1, 1];
+    };
+};
+export interface DockCtaReceiveObservables {
+    readonly phase: DockCtaReceivePhase;
+    readonly path: DockCtaReceivePath | null;
+    readonly run: number;
+    readonly interruptions: number;
+    readonly resets: number;
+    readonly startedAtMs: number | null;
+    readonly settledAtMs: number | null;
+    readonly handedOffAtMs: number | null;
+    readonly completedAtMs: number | null;
+    readonly latencyMs: number | null;
+    readonly travelPx: number;
+    readonly scaleRatio: number;
+    readonly latencyBandMs: readonly [number, number] | null;
+    readonly travelBandPx: readonly [number, number] | null;
+    readonly scaleBand: readonly [number, number] | null;
+    readonly withinBand: boolean | null;
+    readonly supportsReverse: false;
+}
 export interface UseDockCtaReceiveOptions {
     /**
-     * The 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. `<DockIconButton>`), whose root element is resolved via `.$el`.
-     * Resolving both keeps the seam forgiving: a `useTemplateRef<HTMLElement>` annotation
-     * on a component ref (whose value is the component public instance) no longer throws
-     * `setAttribute is not a function` at runtime — the stale element-vs-component class.
+     * 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 | ComponentPublicInstance | null>;
     /** The spring register (default `snappy`). */
@@ -32,35 +75,40 @@ 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>>;
+    /** Whether the shared morph owner is currently playing. */
+    playing: Readonly<Ref<boolean>>;
+    /** Live normalized arrival progress from the shared morph owner. */
+    progress: Readonly<Ref<number>>;
+    /** Start/settle/handoff/completion and policy-band readback for the current run. */
+    observables: Readonly<Ref<DockCtaReceiveObservables>>;
 }
+/**
+ * The external-CTA-into-dock-control morph. A ≤20-line adapter over `useElementMorph` —
+ * declares the receive as a `direction: "out"` FORWARD play flying ONTO the dock control,
+ * opacity + blur coupled, the runner's `onSettled` firing the seat clear + `onReceived`.
+ * The seat writes (`setPending`/`clearPending`) stay wrapper-local (data-attr, not motion).
+ *
+ * @example
+ * ```ts
+ * 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 | ComponentPublicInstance | null>, options: UseDockCtaReceiveOptions): UseDockCtaReceiveReturn;

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

@@ -0,0 +1,107 @@
+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>>;
+    /** Geometry and engine horizon measured by this owner for the current play. */
+    measurement: Readonly<Ref<ElementMorphMeasurement | null>>;
+}
+export interface ElementMorphMeasurement {
+    readonly travelPx: number;
+    readonly scaleX: number;
+    readonly scaleY: number;
+    readonly durationMs: 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;