@mkbabb/glass-ui 6.0.0 → 8.0.0

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

@@ -0,0 +1,44 @@
+/** Options for `startViewTransition`. `types` (Chrome 140+, absent on Firefox
+ *  144) tag the active transition so `:active-view-transition-type(<t>)` CSS can
+ *  author DIRECTION-specific curves. Feature-detected — when the engine lacks the
+ *  object-with-`types` overload the call degrades to the plain-callback form
+ * one symmetric curve, which is functionally identical because the swap still runs. */
+export interface ViewTransitionOptions {
+    types?: string[];
+}
+export interface ViewTransitionResult {
+    /**
+     * Resolves when the transition's `finished` promise settles (or
+     * immediately in the fallback path). Use to route focus per the a11y
+     * MANDATORY: `await startViewTransition(mutate).finished; el.focus()`.
+     * Never rejects — a skipped/aborted transition settles cleanly.
+     */
+    finished: Promise<void>;
+    /** True when the native API ran; false when the instant fallback ran. */
+    transitioned: boolean;
+}
+/**
+ * True when `document.startViewTransition` is available — the feature-detected
+ * predicate consumers gate optional VT-only styling on.
+ */
+export declare function supportsViewTransitions(): boolean;
+/**
+ * Wrap a DOM mutation in `document.startViewTransition` with an instant
+ * fallback. The mutation may be synchronous or asynchronous.
+ *
+ * @param mutate the DOM/state change to animate between.
+ * @param options optional `{ types }` — directional transition types tagged on
+ *   the active transition for `:active-view-transition-type(<t>)` CSS curves
+ *   (Chrome 140+; feature-detected, degrades to one symmetric curve elsewhere).
+ * @returns `{ finished, transitioned }` — await `finished` to route focus.
+ *
+ * @example
+ *   const { finished } = startViewTransition(() => { rows.value = reranked });
+ *   await finished;            // animation done
+ *   firstRow.value?.focus();   // consumer routes focus (the a11y MANDATORY)
+ *
+ * @example
+ *   // directional intent — snappier exit on collapse, softer entry on expand
+ *   startViewTransition(() => mutate(), { types: ["dock-expand"] });
+ */
+export declare function startViewTransition(mutate: () => void | Promise<void>, options?: ViewTransitionOptions): ViewTransitionResult;

package/dist/composables/motion/dissolve/dissolveGrammar.d.ts

@@ -0,0 +1,88 @@
+/** The five dialects, by the name each is known by in the codex table. */
+export type DissolveDialect = "auto-expiry" | "flicked" | "miniaturize" | "row-dissolve" | "vaporize";
+/**
+ * A row states what the dialect IS, who ended it, and which roster row owns the surface
+ * that speaks it. It carries no figures: a dialect that this library has not built has no
+ * constants to carry, and the one it HAS built keeps its constants in
+ * `VAPORIZE_CONSTANTS` below, where the CSS mirror reads them.
+ */
+export interface DissolveDialectRow {
+    readonly dialect: DissolveDialect;
+    /** Who ended it — the selector the codex row rules by ("who ended it selects the dialect"). */
+    readonly endedBy: "timer" | "gesture" | "system" | "user";
+    /** Built by THIS library today, or named-and-routed. */
+    readonly built: boolean;
+    /** The roster row that owns the surface speaking it. */
+    readonly owner: string;
+    readonly comment: string;
+}
+/** The table. Reading order is the codex row's, not a precedence. */
+export declare const DISSOLVE_DIALECTS: readonly DissolveDialectRow[];
+/** Look one dialect up by name. */
+export declare function dissolveDialect(dialect: DissolveDialect): DissolveDialectRow;
+/**
+ * The vaporize's measured constants, carried in ONE table.
+ *
+ * `channelRatio` traces to `IOS27-ARCHIVE.md` §4b: saturation, dim and blur reach 95% of
+ * their released values at 184 / 250 / 317 ms — 1 : 1.36 : 1.72, monotone, ease-out, zero
+ * overshoot on any channel, saturation always first and blur always last. The absolutes
+ * are the archive's device; the ratio is the mechanism, and it is the ratio we keep.
+ *
+ * The other three are TR#30's amendments, stated there verbatim: the ink collapses by 40%
+ * of the travel, its alpha floors at 0.30 on the way, and its blur peaks at half the
+ * element's own height. `transform-free` and `the backdrop outlives the panel by two
+ * frames` are the amendments that are structural rather than numeric — the first is an
+ * absence the arms check, and the second is a FLOOR the ratio already clears (see
+ * `backdropOutlivesPanel`).
+ */
+export declare const VAPORIZE_CONSTANTS: {
+    /** §4b: sat : dim : blur = 1 : 1.36 : 1.72, saturation first, blur last. */
+    readonly channelRatio: {
+        readonly saturate: 1;
+        readonly dim: 1.36;
+        readonly blur: 1.72;
+    };
+    /** Amendment: the ink's collapse completes at 40% of the travel. */
+    readonly inkCollapseFraction: 0.4;
+    /** Amendment: the ink's alpha floors at 0.30 where the collapse completes. */
+    readonly inkOpacityFloor: 0.3;
+    /** Amendment: the ink's blur peaks at half the element's own block size. */
+    readonly inkBlurHeightRatio: 0.5;
+};
+/**
+ * The total travel is the BLUR channel's clock, because blur is always last. Every other
+ * clock in the recipe is this one times a ratio, so the recipe carries exactly one
+ * duration token and spends it.
+ */
+export declare function channelFraction(channel: keyof typeof VAPORIZE_CONSTANTS.channelRatio): number;
+/**
+ * Where the ink's blur peaks, as a fraction of the travel. The blur leads the fade by the
+ * SAME ratio the saturation leads the blur — the mechanism's one ratio, spent twice,
+ * rather than a second lead figure nobody measured.
+ */
+export declare function inkBlurFraction(): number;
+/**
+ * The panel — plate, rim and cast — is gone when the DIM channel lands; the backdrop's
+ * blur runs on to the end. This is "the backdrop outlives the panel by two frames" stated
+ * as what it is: a floor, in milliseconds, that a given travel either clears or does not.
+ * At the shipped travel it clears it several times over, and the arm checks the arithmetic
+ * rather than a remembered millisecond. The frame the floor is counted in is the shared
+ * `FRAME_MS` (`motion/core/constants.ts`) — this table mints no second one.
+ */
+export declare function backdropOutlivesPanel(travelMs: number): number;
+/**
+ * The corner affordance's placement, from `IOS27-ARCHIVE.md` §3 as adjudicated by CWT O-10
+ * (`:1293`): the disc's centre sits ON the element's corner point, nudged inward by ~6.5%
+ * of its own diameter, so about 70% of it floats free and it visually rests on the corner
+ * arc. `offset` is what both insets take, in units of the diameter — negative, because the
+ * disc hangs outside the box. The diameter itself is 0.42 × a SQUARE host's edge; a
+ * non-square host names its own, which is why `size` is a knob and not a derivation.
+ */
+export declare const CORNER_AFFORDANCE: {
+    /** §3: diameter = 0.42 × the element's edge length (25.3pt on a 60pt icon). */
+    readonly edgeRatio: 0.42;
+    /** §3: the centre is nudged inward by ~6.5% of the disc's own diameter. */
+    readonly inwardNudge: 0.065;
+};
+/** The inset both axes take, in units of the diameter. Negative: the disc hangs out. */
+export declare function cornerAffordanceOffset(): number;

package/dist/composables/motion/engage/engageEnvelopes.d.ts

@@ -0,0 +1,45 @@
+/** An engagement-envelope role name. */
+export type EngageRole = "press-drain" | "medium-exit" | "control-engage" | "signal-decay";
+/** One envelope row: the (attack, release) time constants + who rides it. */
+export interface EngageEnvelopeRow {
+    /** The role this envelope serves — the lookup key. */
+    readonly role: EngageRole;
+    /** τ_up: the first-order attack time constant in ms (the shared acknowledge class). */
+    readonly attackMs: number;
+    /** τ_down: the release time constant in ms. Always slower than the attack. */
+    readonly releaseMs: number;
+    /** The named surface this row was measured on — one rider per row. */
+    readonly rider: string;
+    /** The register this envelope serves. */
+    readonly comment: string;
+}
+/**
+ * The ONE press-acknowledge attack class every role shares. Attacks do not vary by
+ * role — an acknowledge is an acknowledge — so the class is a BAND that every row's
+ * τ_up must sit inside, not a per-row invention. Releases are where the roles differ:
+ * that is what makes a drain feel like a cancel and a decay feel like a level falling.
+ */
+export declare const ENGAGE_ATTACK_CLASS: {
+    readonly minMs: 40;
+    readonly maxMs: 60;
+};
+/**
+ * The acknowledge window: a press must be visibly answered within this budget, measured
+ * as the envelope's t90 rather than its time constant. The class band above is drawn so
+ * that even its slowest attack lands inside this window.
+ */
+export declare const ACKNOWLEDGE_WINDOW_MS = 150;
+/**
+ * The engagement envelopes. No envelope constant may be minted outside this table: a
+ * new engagement earns a new ROW here, never a literal at a call site. That is the same
+ * no-second-authority rule the spring table holds, for the channel springs do not own.
+ */
+export declare const ENGAGE_ENVELOPES: readonly EngageEnvelopeRow[];
+/** Look one engagement envelope up by role. */
+export declare function engageEnvelope(role: EngageRole): EngageEnvelopeRow;
+/**
+ * The role's acknowledge time — when the attack reaches 90% of its target. A first-order
+ * envelope's t90 is `τ·ln(10)`; it is DERIVED here so the acknowledge budget is checked
+ * against the shipped time constant rather than against a remembered millisecond figure.
+ */
+export declare function engageAttackT90Ms(role: EngageRole): number;

package/dist/composables/motion/engage/engageLadder.d.ts

@@ -0,0 +1,86 @@
+import type { EngageRole } from "./engageEnvelopes.js";
+import type { SpringPresetName } from "../spring/springPresets.js";
+/** The five rungs of MOTION-CANON §4, in ascending engagement order. */
+export type EngageRungName = "rest" | "hover" | "press" | "engaged" | "modal";
+/**
+ * The four channels a rung may move (§4 G3). `geometry` is the only one with mass and
+ * therefore the only one a spring may drive; the other three are envelope territory.
+ */
+export type EngageChannel = "geometry" | "luminance" | "blur" | "light";
+/** One rung: what it moves, what it moves ON, and the guards it carries. */
+export interface EngageRungRow {
+    /** The rung name — the lookup key. */
+    readonly rung: EngageRungName;
+    /**
+     * The rank of this rung's LEADING channel. Exactly one channel leads at rank 0
+     * (§4 G2); `null` means the rung sits outside the rank system entirely, which is
+     * true of `rest` alone.
+     */
+    readonly rank: 0 | null;
+    /**
+     * The rank at which the WORLD channel follows the rung's lead, or `null` where the
+     * rung recruits no world. §4 gives the engaged veil +6 and the modal scrim +2.
+     */
+    readonly worldLagRank: number | null;
+    /** The geometry row this rung rides, by name. `null` = the rung moves no rect. */
+    readonly spring: SpringPresetName | null;
+    /** The light row this rung rides, by role. `null` = the rung drives no envelope. */
+    readonly envelope: EngageRole | null;
+    /** Every channel this rung is permitted to move. Length ≤ `CHANNEL_BUDGET` (G3). */
+    readonly channels: readonly EngageChannel[];
+    /** Whether the rung exists only on a fine pointer — `@media (hover: hover)` (G7). */
+    readonly pointerFine: boolean;
+    /** Whether at most one element in the document may hold this rung (G6). */
+    readonly singleton: boolean;
+    /** The rung's ONE job, in the register's own words. */
+    readonly comment: string;
+}
+/**
+ * §4 G3 — "no rung changes more than 2 of {geometry, luminance, blur, light}". The
+ * budget is the reason the ladder reads as one language rather than as five effects
+ * firing at once: a rung that moves three channels has stopped being a rung and become
+ * a scene.
+ */
+export declare const CHANNEL_BUDGET = 2;
+/**
+ * §4 HOVER — "size ≤8%". Stated as the multiplicative ceiling a hover scale may reach,
+ * so a component row's own token is checkable against the ladder without the ladder
+ * knowing that component exists. The shipped `--scale-hover` (1.08) sits exactly on it.
+ */
+export declare const HOVER_GEOMETRY_BUDGET = 1.08;
+/**
+ * Which channel each asymmetry law governs — the ruling the two roots' opposite
+ * charters force (see the header). A checker reads THIS rather than assuming one
+ * direction is universal.
+ *
+ * THE CONTROL SURFACE RUNS TWO CLOCKS, AND THIS IS THE LAW THAT KEEPS THEM APART.
+ * A control's colour/border/shadow legs are clocked by an ATTACK channel and a RELEASE
+ * channel, and neither may be re-pointed at the other:
+ *   · ATTACK is bounded ABOVE by `ACKNOWLEDGE_WINDOW_MS` — `--duration-control` (the
+ *     0.12s control beat, `@utility transition-control`) and `--engage-*-attack` both
+ *     sit inside it. The standing strike against the 0.2s calm clock at
+ *     `utilities/btn.css` is a statement about THIS channel and no other.
+ *   · RELEASE is bounded BELOW by its own attack, by `light` here. A release inside the
+ *     acknowledge window is not a faster acknowledgement, it is a cut.
+ * A gate or a seat that reads one channel's bound as universal will "fix" the other into
+ * nonexistence; that is the collision this constant exists to forbid.
+ */
+export declare const LADDER_EXIT_LAW: {
+    /** Spatial legs depart faster than they arrive; the generator ships 0.6 ×. */
+    readonly geometry: "faster-than-entry";
+    /** Light legs outlive their attack; the envelope table ships release > attack. */
+    readonly light: "slower-than-entry";
+};
+/**
+ * The ladder. Ordered by ascending engagement, which is also the order a control
+ * climbs: no rung may be reached without its predecessor being reachable.
+ */
+export declare const ENGAGE_LADDER: readonly EngageRungRow[];
+/** Look one rung up by name. */
+export declare function engageRung(rung: EngageRungName): EngageRungRow;
+/**
+ * The rungs that ride a given envelope role — the reverse index the light-channel
+ * gate reads so a role's CSS clock can be checked against every rung that consumes it
+ * without the check enumerating rungs by hand.
+ */
+export declare function rungsForEnvelope(role: EngageRole): readonly EngageRungRow[];

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

@@ -1,16 +1,14 @@
-export * from "./constants";
-export * from "./useSpring";
-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 "./useNumericTransition";
-export * from "./useAnimatedNumber";
-export * from "./useAnimatedNumberMap";
-export * from "./useCountup";
-export * from "./suite";
-export { SPRING_PRESETS, springPreset, type SpringPresetRow, type SpringPresetName, } from "./springPresets";
+export * from "./core/constants.js";
+export * from "./spring/useSpring.js";
+export * from "./spring/useSpringMount.js";
+export * from "./spring/useLiquidPress.js";
+export * from "./morph/useDragMorph.js";
+export * from "./morph/useElementMorph.js";
+export { asElement } from "./core/asElement.js";
+export * from "./reveal/useLiquidReveal.js";
+export * from "./morph/useDockCtaReceive.js";
+export * from "./number/useAnimatedNumber.js";
+export * from "./number/useAnimatedNumberMap.js";
+export { SPRING_PRESETS, springPreset, type SpringPresetRow, type SpringPresetName, } from "./spring/springPresets.js";
+export { ENGAGE_ENVELOPES, ENGAGE_ATTACK_CLASS, ACKNOWLEDGE_WINDOW_MS, engageEnvelope, engageAttackT90Ms, type EngageEnvelopeRow, type EngageRole, } from "./engage/engageEnvelopes.js";
+export { ENGAGE_LADDER, CHANNEL_BUDGET, HOVER_GEOMETRY_BUDGET, LADDER_EXIT_LAW, engageRung, rungsForEnvelope, type EngageRungRow, type EngageRungName, type EngageChannel, } from "./engage/engageLadder.js";

package/dist/composables/motion/morph/eyeglass.d.ts

@@ -0,0 +1,141 @@
+/**
+ * §C1: "On a hop it **spans origin and destination** (1.5×, max 1.6×) then retracts
+ * onto the destination." The ceiling, not the nominal — a hop whose real span is
+ * shorter than this spans its real distance and no further. The span law is
+ * geometry-true first and capped second.
+ */
+export declare const EYEGLASS_SPAN_MAX = 1.6;
+/**
+ * §C1 (v1b): "**1.22× vertical swell largest at travel extremes** — a slug piling at
+ * the wall." The cross-axis channel. It is a SWELL, not the reciprocal of the span:
+ * the body thickens as it piles into its travel, which is the whole reason the moving
+ * pill ends up taller than the bar it rides in.
+ */
+export declare const EYEGLASS_SWELL_MAX = 1.22;
+/**
+ * §C1: "**Leading edge outruns trailing 2:1** (one 83ms frame: −54 vs −28px)." The
+ * asymmetry that makes mid-travel "an egg leaning into travel" rather than a symmetric
+ * balloon. Expressed as the ratio itself so the origin below can be derived from it.
+ */
+export declare const EYEGLASS_EDGE_RATIO = 2;
+/**
+ * The transform-origin that PRODUCES the 2:1 asymmetry, measured as a fraction of the
+ * box's longitudinal extent FROM THE LEADING EDGE. Derived, never transcribed:
+ *
+ *   scaling a box of extent w by k about a point at fraction f from the leading edge
+ *   moves the leading edge by (1 − f)·(k − 1)·w and the trailing edge by f·(k − 1)·w,
+ *   so leading : trailing = (1 − f) : f, and (1 − f)/f = R ⇒ f = 1/(1 + R).
+ *
+ * At R = 2 that is exactly 1/3. One scale write, on the compositor, produces the whole
+ * asymmetry — no second channel, no per-edge animation, no layout.
+ */
+export declare const EYEGLASS_ORIGIN_FRACTION: number;
+/**
+ * §C1: "**It breaks its own track**: moving pill ~8px taller than the bar —
+ * `overflow:hidden` kills the organ", and the codex's own gloss, "licensed to overflow
+ * ~10% of height". The fraction of its own cross extent the body hangs outside the
+ * track on EACH side, DERIVED from the swell rather than transcribed beside it: a
+ * symmetric swell of s hangs (s − 1)/2 out per side, so 1.22 gives 11% — the same ~10%
+ * the seat wrote down, arrived at from the other measurement.
+ *
+ * Two independent numbers in the footage agreeing to a point is the corroboration; two
+ * independent numbers in SOURCE is a drift waiting to happen, which is why only one of
+ * them is written here. The figure is a LICENCE, not a target — the swell produces the
+ * overflow and this is what the track must be prepared to let through. A track that
+ * clips is not a tidier track, it is a dead organ.
+ */
+export declare const EYEGLASS_OVERFLOW_LICENSE: number;
+/**
+ * §C3 (the commit cascade) states its ladder in RANKS — "geometry(0) → annotation(+6) →
+ * content(≈+15) → light decay to +30" — and its clock in milliseconds: "recolour
+ * +80–160ms · page content commits +250–450ms · glow decays +500ms after geometry
+ * stops". One unit reconciles them and it is the display frame:
+ *
+ *   +6  × 16.67ms = 100ms  → inside the measured 80–160ms recolour band
+ *   +15 × 16.67ms = 250ms  → the measured content band's own opening edge
+ *   +30 × 16.67ms = 500ms  → the measured glow decay, exactly
+ *
+ * The rank ladder is therefore not a second clock — it is the same clock counted in
+ * frames, which is why the cascade reads as one gesture rather than four timers.
+ */
+export declare const CASCADE_RANK_MS: number;
+/** The ranks §C3 measures, by the name it gives each stage of the one gesture. */
+export declare const CASCADE_RANKS: {
+    /** The object itself. Rank 0 — the pill arrives at t0 and everything else is late. */
+    readonly geometry: 0;
+    /** The selected label taking its ink. §C3's "recolour +80–160ms". */
+    readonly annotation: 6;
+    /** Whatever the strip governs. §C3's "page content commits +250–450ms". */
+    readonly content: 15;
+    /** §C3: "the object stops, the light does not" — the wake's tail, +500ms. */
+    readonly light: 30;
+};
+/** A cascade rank in milliseconds. The ONE conversion; no site does this arithmetic. */
+export declare function cascadeRankMs(rank: number): number;
+/** One longitudinal interval on the travel axis, in the container's own coordinates. */
+export interface EyeglassInterval {
+    /** The leading-edge-most coordinate (left, or top on a vertical strip). */
+    readonly start: number;
+    /** The trailing-edge-most coordinate (right, or bottom on a vertical strip). */
+    readonly end: number;
+}
+export interface EyeglassSpanParams {
+    /** Where the body is leaving. */
+    readonly from: EyeglassInterval;
+    /** Where the body is arriving. */
+    readonly to: EyeglassInterval;
+    /**
+     * The track's own inner interval on the same axis. The body may not span past it —
+     * §C1's "Driven into the end it **clamps**, compressing against the bar's inner
+     * edge". Omit only where no track exists to clamp against.
+     */
+    readonly track?: EyeglassInterval;
+    /** The surface's declared ceiling; defaults to the measured `EYEGLASS_SPAN_MAX`. */
+    readonly spanMax?: number;
+}
+export interface EyeglassSpan {
+    /**
+     * The longitudinal scalar to write, ≥ 1. `1` means the body does not span — a
+     * same-tab commit, or a hop the ceiling has fully absorbed.
+     */
+    readonly span: number;
+    /**
+     * True when the ceiling or the track boundary shortened the geometric span. §C1's
+     * clamp is a REPORTED state, not a silent floor: a paint that wants to read
+     * "compressing against the bar's inner edge" has to know it happened.
+     */
+    readonly clamped: boolean;
+    /**
+     * `1` when travel runs toward increasing coordinates, `-1` when it runs back, `0`
+     * for no travel. The sign the origin below flips on.
+     */
+    readonly direction: -1 | 0 | 1;
+}
+/**
+ * The SPAN law. The body's transient extent is the union of where it is leaving and
+ * where it is arriving — that is what "spans origin and destination" means literally —
+ * expressed as a multiple of the DESTINATION extent, because the destination is what it
+ * retracts onto and therefore what the scale is relative to.
+ *
+ * Two fences, in this order, both of them geometry rather than taste:
+ *   1. the surface's ceiling (`spanMax`), and
+ *   2. the track's inner edge — the body is licensed to overflow its track on the CROSS
+ *      axis (`EYEGLASS_OVERFLOW_LICENSE`) and on that axis only. Longitudinally it
+ *      clamps, which is the compression §C1 photographs at the ends of the bar.
+ */
+export declare function eyeglassSpan(params: EyeglassSpanParams): EyeglassSpan;
+/**
+ * The cross-axis SWELL, largest at travel extremes. `frac` is the travel distance
+ * normalised by the container extent — the same geometry-relative fraction the writer
+ * already computes — so a neighbouring hop barely thickens and a full-strip jump piles
+ * into the wall.
+ */
+export declare function eyeglassSwell(frac: number, swellMax?: number): number;
+/**
+ * The `transform-origin` percentage along the travel axis that yields the 2:1 lead.
+ * Travelling toward increasing coordinates the leading edge is the FAR one, so the
+ * origin sits `EYEGLASS_ORIGIN_FRACTION` in from that end — i.e. at (1 − f) of the box.
+ * Travelling back it mirrors. Zero travel keeps the centre, so a same-tab commit cannot
+ * lean.
+ */
+export declare function eyeglassOriginPercent(direction: -1 | 0 | 1): number;

package/dist/composables/motion/{useDockCtaReceive.d.ts → morph/useDockCtaReceive.d.ts}

@@ -1,9 +1,9 @@
 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;
+import { type ElementMorphPreset } from "./useElementMorph.js";
+/** The receive spring register — `dock` (coordinated travel, the crisp absorb default)
+ *  or `panel` (the emphatic land-with-overshoot). A CTA flying into a dock control IS
+ *  coordinated travel, so it rides the same row the members do. */
+export type DockCtaReceivePreset = Extract<ElementMorphPreset, "dock" | "panel">;
 export type DockCtaReceivePath = "fine" | "coarse" | "reduced-motion" | "no-target";
 export type DockCtaReceivePhase = "idle" | "receiving" | "settled" | "handed-off" | "completed" | "reset";
 export interface DockCtaReceiveBand {
@@ -61,7 +61,7 @@ export interface UseDockCtaReceiveOptions {
      * fires immediately.
      */
     dockControl: Ref<HTMLElement | ComponentPublicInstance | null>;
-    /** The spring register (default `snappy`). */
+    /** The spring register (default `dock`). */
     preset?: DockCtaReceivePreset;
     /** The ending congest blur radius in px (the CTA dissolves into the glass). Default 4. */
     blur?: number;
@@ -97,9 +97,8 @@ export interface UseDockCtaReceiveReturn {
     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 external-CTA-into-dock-control morph. A small adapter over `useElementMorph`
+ * declares the CTA→control endpoints and couples opacity + blur to its settle hand-off.
  * The seat writes (`setPending`/`clearPending`) stay wrapper-local (data-attr, not motion).
  *
  * @example

package/dist/composables/motion/{useDragMorph.d.ts → morph/useDragMorph.d.ts}

@@ -1,4 +1,4 @@
-import { type ComputedRef, type Ref } from "vue";
+import { type Ref } from "vue";
 /** The morph axis — `"x"` tracks the inline (horizontal) travel, `"y"` the block. */
 export type DragMorphAxis = "x" | "y";
 /**
@@ -11,8 +11,10 @@ export interface DragMorphSnapTarget<V = string> {
     center: number;
 }
 export interface UseDragMorphParams<V = string> {
-    /** The draggable element ref (the indicator/handle the gesture captures). */
-    el: Ref<HTMLElement | null>;
+    /** The element that captures the pointer gesture. */
+    handle: Ref<HTMLElement | null>;
+    /** The surface that follows the gesture. Defaults to `handle`. */
+    surface?: Ref<HTMLElement | null>;
     /** The morph axis (`"x"` horizontal · `"y"` vertical). May be a getter. */
     axis: DragMorphAxis | (() => DragMorphAxis);
     /**
@@ -41,8 +43,6 @@ export interface UseDragMorphReturn {
     position: Readonly<Ref<number>>;
     /** The live squish scalar (≥1, capped at the live cap). 1 at rest / under PRM. */
     stretch: Readonly<Ref<number>>;
-    /** The `transform: translate` style the consumer binds on the morph element. */
-    dragStyle: ComputedRef<Record<string, string>>;
     /**
      * Re-resolve the snap centers + axis (kf reads `snap` at construction, so a
      * geometry change — a resize, an option change, an orientation flip — calls
@@ -62,8 +62,8 @@ export interface UseDragMorphReturn {
  *
  * @example
  * ```ts
- * const { dragging, stretch, dragStyle, detach } = useDragMorph({
- *   el: indicatorRef,
+ * const { dragging, stretch, detach } = useDragMorph({
+ *   handle: indicatorRef,
  *   axis: () => (isVertical.value ? "y" : "x"),
  *   snapTargets: () => buttonRefs.value.map((b, i) => ({
  *     value: options.value[i].value,

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

@@ -0,0 +1,50 @@
+import { type ComponentPublicInstance, type Ref } from "vue";
+import { type SpringPresetName } from "../spring/springPresets.js";
+/** A measured endpoint, or the morphed surface's own settled box. */
+export type MorphEndpoint = Ref<HTMLElement | ComponentPublicInstance | null> | "self";
+/** The registers the FLIP runner drives: coordinated travel (the default), the fired
+ *  deploy, and the room-sized bloom its `useLiquidReveal` leaf defaults to. */
+export type ElementMorphPreset = Extract<SpringPresetName, "dock" | "panel" | "bloom">;
+export interface MorphChannels {
+    opacity?: boolean;
+    blur?: number;
+}
+export interface UseElementMorphOptions {
+    /** Where the episode starts. At least one endpoint normally owns `"self"`. */
+    source: MorphEndpoint;
+    /** Where the episode settles. */
+    destination: MorphEndpoint;
+    channels?: MorphChannels;
+    preset?: ElementMorphPreset;
+    respectReducedMotion?: boolean;
+    onSettled?: () => void;
+    onFrame?: (progress: number) => void;
+}
+export interface ElementMorphMeasurement {
+    readonly travelPx: number;
+    readonly scaleX: number;
+    readonly scaleY: number;
+    readonly durationMs: number;
+}
+export interface UseElementMorphReturn {
+    play: () => void;
+    cancel: () => void;
+    clear: (el?: HTMLElement | null) => void;
+    /** Seat the explicit source→destination geometry without starting a clock. */
+    seat: (progress: number) => void;
+    /** Drive a gesture offset through this same spatial writer. */
+    offset: (x: number, y: number) => void;
+    /** Re-measure and retarget an in-flight episode from its live frame. */
+    refresh: () => void;
+    playing: Readonly<Ref<boolean>>;
+    progress: Readonly<Ref<number>>;
+    measurement: Readonly<Ref<ElementMorphMeasurement | null>>;
+}
+export declare function lockSpatialTransition(el: HTMLElement): () => void;
+export declare function prefersReducedMotion(): boolean;
+/**
+ * A single explicit-endpoint FLIP owner for reveal, bloom, receive and gesture
+ * configurations. Replacements and resizes retarget from the last painted frame;
+ * disappearing foreign endpoints retain the last valid geometry.
+ */
+export declare function useElementMorph(surface: Ref<HTMLElement | ComponentPublicInstance | null>, options: UseElementMorphOptions): UseElementMorphReturn;

package/dist/composables/motion/morph/useLeadTrail.d.ts

@@ -0,0 +1,71 @@
+import { type Ref } from "vue";
+/**
+ * The bounded velocity lag — `clamp(v·τ, ±ceil)`. The worm's trail edge and the
+ * carousel's interior content-lag are the same law over different quantities.
+ */
+export declare function trailOffset(velocity: number, tau: number, ceil: number): number;
+export interface UseLeadTrailOptions {
+    /**
+     * The lag ceiling in px, re-read per frame so it can be a live geometry band
+     * (`clamp(pitch, |Δ|·0.55, 3·pitch)`). A plain number is a fixed ceiling.
+     */
+    ceil?: number | (() => number);
+    /** The elongation time constant, seconds. Default 0.08. */
+    tau?: number;
+    /** Honor `prefers-reduced-motion: reduce` → `drive` seats instantly. Default true. */
+    respectReducedMotion?: boolean;
+    /**
+     * The per-frame writer. Called each rAF tick with the live numeric edges — the
+     * consumer projects its silhouette off `lo`/`hi`. Also called once on `seat`
+     * so a static mount paints correctly.
+     */
+    onFrame?: (edges: LeadTrailEdges) => void;
+}
+/** The two-edge state a single frame hands the consumer. */
+export interface LeadTrailEdges {
+    /** The lead edge (px) — springs toward the drive target. */
+    lead: number;
+    /** The trail edge (px) — the lead, offset by the bounded velocity lag. */
+    trail: number;
+    /** The lead's velocity (px/s) — the elongation's own cause. */
+    velocity: number;
+    /** `min(lead, trail)` — direction-agnostic. */
+    lo: number;
+    /** `max(lead, trail)`. */
+    hi: number;
+    /** True once the edges have re-formed on the target. */
+    settled: boolean;
+}
+export interface UseLeadTrail {
+    /** The live lead edge (updated per frame). */
+    readonly lead: Readonly<Ref<number>>;
+    /** The live trail edge (updated per frame). */
+    readonly trail: Readonly<Ref<number>>;
+    /** True while the morph has re-formed on the target (the rAF is parked). */
+    readonly settled: Readonly<Ref<boolean>>;
+    /**
+     * Retarget the lead edge (px). The velocity carries — a retarget mid-flight
+     * continues from the LIVE `(position, velocity)`, so interruption is free.
+     * Under PRM this SEATS instantly (zero in-between frames).
+     */
+    drive(target: number): void;
+    /** Snap BOTH edges to `value` instantly (mount / resize / PRM). Paints once. */
+    seat(value: number): void;
+    /** Tear down the rAF + shared-preference watch (auto-run on scope dispose). */
+    dispose(): void;
+}
+/**
+ * The two-edge morph driver — a governed spring LEAD and a velocity-derived TRAIL
+ * in ONE rAF, with ZERO per-frame style reads. See the module header for the law.
+ *
+ * @example
+ * ```ts
+ * const worm = useLeadTrail({
+ *   ceil: () => elongationCeil(),          // clamp(pitch, |Δ|·0.55, 3·pitch)
+ *   onFrame: ({ lo, hi }) => paintBarbell(lo, hi),
+ * })
+ * worm.seat(centerOf(active))   // mount
+ * worm.drive(centerOf(next))    // hop — the gap peaks with the velocity, then is 0
+ * ```
+ */
+export declare function useLeadTrail(options?: UseLeadTrailOptions): UseLeadTrail;