@mkbabb/glass-ui 4.1.0 → 4.2.0

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

@@ -0,0 +1,50 @@
+import { type Ref } from "vue";
+import { type SpringPresetName } from "./springPresets";
+/** The burst spring register — `bouncy` (the emphatic playful default) or `snappy`. */
+export type CelebrationBurstPreset = Extract<SpringPresetName, "bouncy" | "snappy">;
+export interface UseCelebrationBurstOptions {
+    /** The number of glass petals to bloom. Default 12. */
+    count?: number;
+    /** The spring register (default `bouncy` — the playful overshoot). */
+    preset?: CelebrationBurstPreset;
+    /** The base outward radius in px (each petal lands at `radius × 0.7..1.0` seeded). Default 64. */
+    radius?: number;
+    /**
+     * An OPT-IN destination element whose `[data-reveal]` children get the chip-bloom-in
+     * settle cascade (the burst sets `--d` per child so the EXISTING `icon-chip-reveal`
+     * cascade plays). Omitted → no settle cascade (a pure radial burst).
+     */
+    destination?: Ref<HTMLElement | null>;
+    /**
+     * An OPT-IN `:tone` axis — when set, the petals tint toward this hue (a complete CSS
+     * `<color>` written to `--glass-accent`, the W-GLASS-ACCENT rim-tint seam, for a
+     * hue-keyed burst — a download-complete petal blooms `--viz-download`). Omitted → the
+     * warm-cream identity (the default).
+     */
+    tone?: string;
+    /** Honor `prefers-reduced-motion: reduce` (snap — terminal cascade only). Default true. */
+    respectReducedMotion?: boolean;
+    /** A fired-once callback when the burst settles (the overlay removed). */
+    onSettled?: () => void;
+}
+export interface UseCelebrationBurstReturn {
+    /**
+     * Fire the one-shot earned-moment petal bloom from the origin's center. Idempotent per
+     * call — a re-fire mid-bloom cancels the prior overlay + starts fresh. A no-op if the
+     * origin element is not mounted.
+     */
+    burst: () => void;
+}
+/**
+ * The library's ONE EARNED-moment celebration primitive — a one-shot radial bloom of N
+ * warm-cream glass petals (scale + fade + decongest from the origin on the bouncy spring),
+ * then a coupled chip-bloom-in cascade settles the destination. Compositor-only + PRM-static.
+ * See the module header for the REUSE + burst-mechanism + the channel writes.
+ *
+ * @example
+ * ```ts
+ * const { burst } = useCelebrationBurst(metricCardRef, { preset: "bouncy", destination })
+ * onPersonalBest(() => burst())
+ * ```
+ */
+export declare function useCelebrationBurst(origin: Ref<HTMLElement | null>, options?: UseCelebrationBurstOptions): UseCelebrationBurstReturn;

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

@@ -1,4 +1,4 @@
-import { type Ref } from "vue";
+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,
@@ -10,7 +10,14 @@ export interface UseDockCtaReceiveOptions {
      * `<DockIconButton>`/dock control element). When null at receive time, the morph
      * is a no-op snap (no destination to fly to) and `onReceived` fires immediately.
      */
-    dockControl: Ref<HTMLElement | null>;
+    /**
+     * The 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.
+     */
+    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. */
@@ -56,29 +63,4 @@ export interface UseDockCtaReceiveReturn {
     /** 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.
- *
- * @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() }
- * ```
- */
-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/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;

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

@@ -71,6 +71,24 @@ export interface UseLiquidFlexReturn {
      * The SFC's CSS pairs `--stretch` reciprocally along the travel axis.
      */
     stretchStyle: ComputedRef<Record<string, string>>;
+    /**
+     * BD.W-MOTION-WEIGHT — the SATURATING velocity term `tanh(|ṫ|·k) ∈ [0,1]` (the
+     * SAME term the squish already computes), exposed so a consumer can fold it into
+     * the universal `--motion-weight` velocity boost (§2c). 0 at rest; rises toward 1
+     * on a fast travel; self-extinguishes as the travel stills. In `"linear"` law it
+     * is the travel FRACTION (clamped to [0,1]); in `"tanh"` law it is `tanh(travel·k)`.
+     * The PRIMITIVE STAYS ELEMENT-LESS — it merely projects the term; the consumer
+     * writes it onto the driving element via the `writeVelocityWeight` helper.
+     */
+    flexVel: ComputedRef<number>;
+    /**
+     * The velocity term as a CSS custom-property style object
+     * (`{ "--flex-vel": "0.42" }`). The consumer binds it on the driving element (the
+     * one extra style object — the term it ALREADY computes); the local
+     * `--motion-weight: calc(0.618 + 0.382 * var(--flex-vel))` boost rides it. The
+     * primitive stays element-less; this is a pure projection.
+     */
+    velStyle: ComputedRef<Record<string, string>>;
     /**
      * Advance the morph: set the normalized progress to `next` (0→1). The squish
      * travel velocity is the |Δt| since the prior `drive`, so calling `drive` on a

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

@@ -0,0 +1,108 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+import { type SpringPresetName } from "./springPresets";
+import { type LiquidRevealPreset } from "./useLiquidReveal";
+/** The morph MODES the one scalar drives. */
+export type LiquidMorphMode = "split" | "union" | "expand";
+/**
+ * How a piece's travel ANGLE is resolved:
+ *   • `radial`   — the unit vector host-center -> piece-center (the n-ary fan).
+ *   • `lateral`  — the host's cross-axis (a single side bud).
+ *   • `inward`   — the negated radial (a union pull toward the host).
+ *   • `directed` — the caller's explicit `piece.angle` (radians) — the
+ *                  configurable-angle case the playground's slider drives.
+ */
+export type LiquidMorphVector = "radial" | "lateral" | "inward" | "directed";
+/** The named morphology signature — the goo neck/squish character per mode. */
+export interface LiquidMorphSignature {
+    /** How each piece's travel angle is resolved (default `radial`). */
+    vector: LiquidMorphVector;
+    /** Where the goo neck snaps in the 0..1 travel (0.4 tense -> 0.7 long-tail). */
+    neckHold: number;
+    /** The LOW squish cap the bud-off swell can reach (>1; default 1.08). */
+    maxStretch: number;
+}
+/** The default radial-fan signature (the macOS goo-split read). */
+export declare const RADIAL_SPLIT: LiquidMorphSignature;
+/** The directed-beam signature (the configurable-angle / single-direction case). */
+export declare const DIRECTED_SPLIT: LiquidMorphSignature;
+export interface UseLiquidMorphOptions {
+    /** The host element carrying the `--liquid-morph-t` scalar (a card OR a dock). */
+    rootEl: Ref<HTMLElement | null>;
+    /**
+     * The ORIGIN element the split BUDS FROM (the dock pill). The pieces fan out of
+     * this element's center (a connecting goo neck back to the dock), NOT the host
+     * stage center — the WAVE-1 "bud from the dock" fix. Its center is measured
+     * relative to `rootEl` each episode and written as `--liquid-morph-origin-x/y`
+     * (px-from-the-host-top-left) which the goo group (liquid-morph.css) anchors at.
+     * When unset the goo group falls back to the host center (the standalone case).
+     */
+    originEl?: Ref<HTMLElement | null>;
+    /** The morphology signature (default `RADIAL_SPLIT`). */
+    signature?: LiquidMorphSignature;
+    /**
+     * The spring register the scalar rides — a `SPRING_PRESETS` row name, or a
+     * ref/getter resolved PER-DRIVE so a host can vary the clock by gesture (a smooth
+     * card bloom vs a livelier split). Default `"dock"`. NO new family is minted.
+     */
+    spring?: MaybeRefOrGetter<SpringPresetName>;
+    /** The bloom preset for `expand()` (default `"bouncy"`). */
+    revealPreset?: LiquidRevealPreset;
+    /** Honor `prefers-reduced-motion: reduce` (seat synchronously). Default true. */
+    respectReducedMotion?: boolean;
+}
+/** A registered split piece — its element + its vector descriptor. */
+export interface LiquidMorphPiece {
+    /** The piece element (a free-floating glass shard). */
+    el: Ref<HTMLElement | null>;
+    /**
+     * The explicit travel angle in RADIANS for the `directed` vector. Ignored for
+     * `radial`/`lateral`/`inward` (those derive the angle from geometry).
+     */
+    angle?: number;
+    /** The piece's fan rank (the stagger index; 0-based). */
+    rank?: number;
+    /** The travel distance in px (how far the piece flies). Default 96. */
+    distance?: number;
+}
+export interface RegisteredPiece extends LiquidMorphPiece {
+    /** Detach this piece from the morph (clears its inline customs). */
+    release(): void;
+}
+export interface UseLiquidMorphReturn {
+    /** Register a split piece; returns the live handle. */
+    registerPiece(p: LiquidMorphPiece): RegisteredPiece;
+    /** SPLIT — drive the scalar 0 -> 1 (the pieces bud off through the goo neck). */
+    split(): void;
+    /** UNION — drive the scalar 1 -> 0 (the SAME loop, reversed; bidirectional). */
+    union(): void;
+    /** SEEK — scrub the scalar to an arbitrary 0..1 value (the timeline scrubber). */
+    seek(value: number): void;
+    /** EXPAND — bloom a card FROM a trigger pill (the dock->card materialize). */
+    expand(opts: {
+        card: Ref<HTMLElement | null>;
+        trigger: Ref<HTMLElement | null>;
+    }): void;
+    /** COLLAPSE — conceal the expanded card back to the pill (the bloom's close). */
+    collapse(): void;
+    /** The live normalized scalar (0..1) — what `--liquid-morph-t` reads. */
+    readonly t: Readonly<Ref<number>>;
+    /** Whether a morph is in flight (the host carries `[data-liquid-morphing]`). */
+    readonly morphing: Readonly<Ref<boolean>>;
+}
+/**
+ * The generalized liquid-morph driver. See the module header for the REUSE (the
+ * cloned dock loop shape + the composed reveal/flex leaves), the arbitrary-angle goo
+ * mechanism, and the compositor-only + PRM fences.
+ *
+ * @example
+ * ```ts
+ * const root = ref<HTMLElement | null>(null)
+ * const morph = useLiquidMorph({ rootEl: root, signature: DIRECTED_SPLIT })
+ * for (const el of shardRefs) morph.registerPiece({ el, angle: theta.value })
+ * // n-ary split at an arbitrary angle:
+ * morph.split()
+ * // the dock -> card bloom:
+ * morph.expand({ card: cardRef, trigger: pillRef })
+ * ```
+ */
+export declare function useLiquidMorph(options: UseLiquidMorphOptions): UseLiquidMorphReturn;

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

@@ -30,6 +30,18 @@ export interface UseLiquidPressOptions extends UseSpringPressOptions {
      * then yields back to the cascade as it settles). Default 0.001.
      */
     engageThreshold?: number;
+    /**
+     * BD.W-MOTION-WEIGHT — the pressed element (the host the consumer binds
+     * `pressStyle` on), so the press cap is derived SITE-LOCALLY off the live
+     * `--motion-weight` read at THAT element (the spike-corrected mechanism): the
+     * shipped `maxStretch` cap at rest weight 0.618 (byte-identical feel), 1.0 at
+     * weight 0 (the observer/PRM fence). When omitted, the cap is the static
+     * `maxStretch` (the no-element fallback — still correct at rest weight, the
+     * universal coupling is just not weight-scaled for that surface). The press is
+     * the GENTLE register — a button has no size span, so the weight-coupled cap is a
+     * lively settle, never a taffy-pull.
+     */
+    el?: Ref<HTMLElement | null>;
 }
 export interface UseLiquidPressReturn {
     /** The live spring press value (0 released → 1 pressed, with the spring overshoot). */

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

@@ -1,4 +1,4 @@
-import { type Ref } from "vue";
+import { type ComponentPublicInstance, type Ref } from "vue";
 import { type SpringPresetName } from "./springPresets";
 /** The reveal spring register — `snappy` (the quick app-open default) or `bouncy`
  *  (the emphatic large-dialog bloom). A subset of the named `SPRING_PRESETS` rows. */
@@ -6,11 +6,14 @@ export type LiquidRevealPreset = Extract<SpringPresetName, "snappy" | "bouncy">;
 export interface UseLiquidRevealOptions {
     /**
      * The trigger element the surface blooms FROM — the source rect (the button, the
-     * collapsed dock pill). When null at reveal time, the bloom degrades to a
+     * collapsed dock pill). A templateRef to the trigger ELEMENT or to a COMPONENT (e.g.
+     * `<Button>`), whose root element is resolved via `.$el` — the binding-verification
+     * cure: a `ref` on a component is the public instance (no `getBoundingClientRect`),
+     * which silently no-oped the bloom. When null at reveal time, the bloom degrades to a
      * center-anchored scale-from-self (the no-trigger fallback — still spring-clocked,
      * never the flat bezier zoom).
      */
-    trigger?: Ref<HTMLElement | null>;
+    trigger?: Ref<HTMLElement | ComponentPublicInstance | null>;
     /** The spring register (default `snappy`). */
     preset?: LiquidRevealPreset;
     /** The starting backdrop-blur radius in px (the decongest start). Default 4. */
@@ -48,4 +51,4 @@ export interface UseLiquidRevealReturn {
  * watch(open, (o) => (o ? reveal() : conceal()))
  * ```
  */
-export declare function useLiquidReveal(surface: Ref<HTMLElement | null>, options?: UseLiquidRevealOptions): UseLiquidRevealReturn;
+export declare function useLiquidReveal(surface: Ref<HTMLElement | ComponentPublicInstance | null>, options?: UseLiquidRevealOptions): UseLiquidRevealReturn;

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

@@ -0,0 +1,157 @@
+import { type MaybeRef, type Ref } from "vue";
+/** The five motion VECTORS a signature selects (geometry/motion, never an app name). */
+export type MorphVector = "lateral" | "radial" | "inward" | "axial" | "directed";
+/** The render TIER a morph resolves to (the caps ladder). */
+export type MorphTier = "css" | "svg-goo" | "gpu";
+/** The silhouette a body presents. `capture` = sample its clip-path → SDF (Tier-G, the
+ *  arbitrary-outline element→element morph — HARD-gated on useElementBloom). */
+export type MorphSilhouette = "circle" | "squircle" | "capture";
+/** A measured rectangle (the body endpoints; left/top/width/height in host-local px). */
+export interface MorphFieldRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * 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 — F3, the FLOOR). Every consumer
+ * passes a `MorphSignatureName`; one weld reads the row; one recipe paints it. 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;
+/** A warm "body" the field welds — a measured endpoint pair + an optional silhouette. */
+export interface BodySpec {
+    /** The DOM node this body IS (the weld writes its transform). */
+    el: Ref<HTMLElement | null>;
+    /** The body's REST rect (t=0), measured ONCE (dock-core: no per-frame measure). */
+    at0: () => MorphFieldRect;
+    /** The body's TARGET rect (t=1), measured ONCE. */
+    at1: () => MorphFieldRect;
+    /** The body diameter (px). Default `min(width,height)/φ` — a golden-minor BLOB. */
+    radius?: () => number;
+    /** circle (default) / squircle / capture (arbitrary outline → Tier-G, HARD-gated). */
+    silhouette?: MorphSilhouette;
+}
+export interface MorphFieldOptions {
+    /** 1..N warm masses. 1 body = collapse (no weld); 2 = a neck; (1+N) = fission. */
+    bodies: MaybeRef<BodySpec[]>;
+    /** The motion signature NAME (DATA). The weld reads its row from MORPH_SIGNATURES. */
+    signature: MorphSignatureName;
+    /**
+     * The EXISTING drive scalar this weld READS off the host (NO rename). Default
+     * `--goo-t`; dock passes `--dock-morph-t`, fission `--neck-t`. The consumer's
+     * spring/rAF writes it; the weld only samples + projects.
+     */
+    driveVar?: string;
+    /** The host the drive scalar + the dedicated squish channel are read/written on. */
+    hostRef: Ref<HTMLElement | null>;
+    /** The cartoon-weight scalar source. Read live off the host `--motion-weight` if absent. */
+    weight?: MaybeRef<number>;
+    /** The render tier. `auto` (default) resolves from caps + body count + signature. */
+    tier?: MorphTier | "auto";
+    /** Travel axis for the neck span. `false` (default) horizontal, `true` vertical. */
+    vertical?: MaybeRef<boolean>;
+}
+export interface MorphFieldHandle {
+    /** Mirror of the consumer's drive scalar (last sampled). Read-only. */
+    readonly t: Readonly<Ref<number>>;
+    /** The neck waist FRACTION (waist/body) at the current frame — for π readback. */
+    readonly waist: Readonly<Ref<number>>;
+    /** The resolved render tier. */
+    readonly tier: Readonly<Ref<MorphTier>>;
+    /**
+     * PROJECT the field for an explicit drive value `t` (0..1). Reads the masses'
+     * measured endpoints + the signature, writes each body's transform + the welling
+     * neck + the dedicated squish channel + the live waist. The consumer calls this from
+     * its OWN rAF/spring callback (the weld owns no clock).
+     */
+    project(t: number): void;
+    /**
+     * SEAT the endpoint silhouette at `t` with ZERO neck frames (the PRM cut / first
+     * paint). One resting mass at the endpoint, neck hidden, --stretch 1. The consumer's
+     * PRM branch calls this.
+     */
+    seat(t: number): void;
+}
+export declare function useMorphField(opts: MorphFieldOptions): MorphFieldHandle;

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

@@ -0,0 +1,49 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+import type { ComponentPublicInstance } from "vue";
+import type { ScrollSource } from "./scrollReader";
+export interface UseScrollPinOptions {
+    /**
+     * The tall `.scroll-pin` container (a templateRef to the element or a component). Its
+     * `getBoundingClientRect` gives the pin-slice ratio; `--pin-t` is written onto it (it
+     * `inherits: true` so the sticky stage + phase children read it).
+     */
+    container: MaybeRefOrGetter<HTMLElement | ComponentPublicInstance | null>;
+    /**
+     * The scroll source the pin tracks — the demo passes `main.demo-main-scroller`. Passed
+     * EXPLICITLY (the reader does not auto-discover). Default: the window/document.
+     */
+    source?: MaybeRefOrGetter<ScrollSource>;
+    /**
+     * The pin scrub ∈ [0, 1] — the pin drifts HEAVIER than a control (a scene, not a knob).
+     * Defaults to 1/φ² ≈ 0.382 (the golden heavier-drift rest). PRM → 0.
+     */
+    scrub?: number;
+    /** The spring damping ratio ζ for the felt reveal. < 1 overshoots. Default 0.85. */
+    dampingFraction?: number;
+    /** Honor `prefers-reduced-motion: reduce`. Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseScrollPinReturn {
+    /** The spring-damped 0..1 pin progress (reactive — mirrors `--pin-t`). */
+    pinT: Readonly<Ref<number>>;
+    /** Force a re-read (post-resize). */
+    recalculate: () => void;
+    /** Detach. */
+    dispose: () => void;
+}
+/**
+ * Drive `--pin-t` ∈ [0, 1] onto a sticky `.scroll-pin` stage off the real scroll port,
+ * spring-damped so the pinned reveal arrives with inertia, overshoots, then settles. The
+ * phase recipes (`.scroll-pin-phase-reveal` / `-settle`) read `--pin-t` — no
+ * `animation-timeline`, every engine.
+ *
+ * @example
+ * ```ts
+ * const pinContainer = ref<HTMLElement | null>(null)
+ * useScrollPin({
+ *   container: pinContainer,
+ *   source: () => document.querySelector<HTMLElement>("main.demo-main-scroller"),
+ * })
+ * ```
+ */
+export declare function useScrollPin(options: UseScrollPinOptions): UseScrollPinReturn;

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

@@ -0,0 +1,67 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+import { type ScrollReader, type ScrollSource } from "./scrollReader";
+/** The smoother register — a pure-lag low-pass (`SmoothProgress`) or an overshooting
+ *  spring (`SpringProgress`). The FELT reveal wants the spring (it overshoots, then
+ *  settles — the cartoon slam); the pure-lag legs (a progress number) want the smooth. */
+export type ScrollSceneRegister = "smooth" | "spring";
+export interface UseScrollSceneOptions {
+    /**
+     * The scroll source — an element with its own scroll port (the demo passes
+     * `main.demo-main-scroller`), the Window, or null. Resolved by `createScrollReader`:
+     * an HTMLElement listens on itself, else the document/window. Passed EXPLICITLY (the
+     * reader does NOT auto-discover a scroller).
+     */
+    source: MaybeRefOrGetter<ScrollSource>;
+    /**
+     * Map a fresh reader read to the raw 0..1 target this scene tracks. Default: the
+     * reader's own `position()/extent()` extent-relative progress. A pin passes a custom
+     * mapper keyed off a per-tick `getBoundingClientRect` (the pin-slice ratio).
+     */
+    map?: (reader: ScrollReader) => number;
+    /**
+     * The liquid-weight scrub ∈ [0, 1] — how much lag the scroll carries. 0 = a 1:1 snap
+     * (no weight); higher = heavier drift. Defaults to 1/φ ≈ 0.618 (the golden
+     * liquid-weight rest); a call site overrides per scene. PRM → 0. Mapped to the engine
+     * damping by `scrubToDamping` (a STATED function, no magic affine constants).
+     */
+    scrub?: number;
+    /** The smoother register (default `smooth` — the pure-lag low-pass). */
+    register?: ScrollSceneRegister;
+    /**
+     * For the `spring` register: the damping ratio ζ. < 1 overshoots (the felt slam),
+     * 0.85 ≈ the `--spring-gentle` identity. Default 0.85. Ignored for `smooth`.
+     */
+    dampingFraction?: number;
+    /** The element the damped value is written onto as a custom property (when bound). */
+    bindEl?: MaybeRefOrGetter<HTMLElement | null>;
+    /** The custom property name to write the damped 0..1 onto (e.g. `--pin-t`). */
+    property?: string;
+    /** Honor `prefers-reduced-motion: reduce` (scrub → 0, snap 1:1). Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseScrollSceneReturn {
+    /** The spring-damped 0..1 progress (reactive). The single writer of every felt axis. */
+    progress: Readonly<Ref<number>>;
+    /** Force a coalesced re-read + re-target now (post-resize / layout shift). */
+    recalculate: () => void;
+    /** Detach the reader + stop the smoother. */
+    dispose: () => void;
+}
+/**
+ * The liquid-weight scroll spine. Composes the ONE `createScrollReader` + a keyframes.js
+ * smoother (`SmoothProgress` / `SpringProgress`); on each coalesced scroll tick it sets the
+ * smoother target to the mapped raw progress; the smoother converges with inertia and keeps
+ * moving after scroll stops (the liquid weight). Writes the damped 0..1 to `progress` + the
+ * optional `property` on `bindEl`.
+ *
+ * @example
+ * ```ts
+ * const { progress } = useScrollScene({
+ *   source: () => document.querySelector<HTMLElement>("main.demo-main-scroller"),
+ *   scrub: 0.618,
+ *   bindEl: stageRef,
+ *   property: "--scroll-t",
+ * })
+ * ```
+ */
+export declare function useScrollScene(options: UseScrollSceneOptions): UseScrollSceneReturn;