@mkbabb/glass-ui 4.0.1 → 4.2.0

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

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

package/dist/composables/motion/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/useCharStagger.d.ts

@@ -0,0 +1,44 @@
+import type { MaybeRefOrGetter, Ref } from "vue";
+/** The per-step delay floor matches the shipped `.char-stagger` recipe — the
+ *  glyph spans are mounted via `requestAnimationFrame`-free DOM writes; the CSS
+ *  owns the timing. No magic timing lives here. */
+export interface UseCharStaggerOptions {
+    /**
+     * Split unit. `"char"` (default) splits per UTF-16 code-unit-safe scalar;
+     * `"word"` splits on whitespace and keeps each word as ONE `.char` unit;
+     * `"grapheme"` uses `Intl.Segmenter` so emoji / combining-mark / ZWJ
+     * sequences (a 👨‍👩‍👧 family) are ONE glyph, never split into pieces.
+     */
+    by?: "char" | "word" | "grapheme";
+    /**
+     * Preserve whitespace as non-animating spacer spans so the word spacing
+     * survives the `inline-block` split. Default `true`.
+     */
+    preserveWhitespace?: boolean;
+    /**
+     * Write `--char-total` (the glyph count) on the wrapper, for a length-
+     * proportional / center-out / reverse stagger. Default `true`.
+     */
+    writeTotal?: boolean;
+}
+export interface UseCharStaggerReturn {
+    /** Re-run the split (after a `textContent` change). Idempotent — it restores
+     *  the original text from the cached label and re-mints, so spans never
+     *  accrete across re-splits. */
+    split: () => void;
+    /** The resolved glyph (`.char` unit) count. */
+    count: Ref<number>;
+}
+/**
+ * Split a target element's text into per-glyph `.char` spans + the
+ * `--char-index`/`--char-total` customs the shipped `.char-stagger` CSS reads —
+ * accessible by construction (the wrapper keeps the full text as its
+ * `aria-label`, every glyph span is `aria-hidden`).
+ *
+ * @example
+ * const el = ref<HTMLElement | null>(null);
+ * const { count } = useCharStagger(el, { by: "grapheme" });
+ * // <span ref="el" class="char-stagger" aria-label="Fourier" style="--char-total:7">
+ * //   <span class="char" style="--char-index:0" aria-hidden>F</span> …
+ */
+export declare function useCharStagger(target: MaybeRefOrGetter<HTMLElement | null>, opts?: UseCharStaggerOptions): UseCharStaggerReturn;

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. */
@@ -36,24 +43,24 @@ export interface UseDockCtaReceiveReturn {
      * abort/reset seam. Cancels any in-flight morph; 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`.
+     */
+    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`.
+     */
+    clearPending: () => void;
+    /** The reactive seat state — the consumer binds `:class`/`v-if` off it. */
+    pending: Readonly<Ref<boolean>>;
 }
-/**
- * The external-CTA-into-dock-control morph. Composes the SAME kf `ElementMorph` +
- * `springTimingFunction` substrate `useLiquidReveal` activates, driven FORWARD (the
- * reveal's inverse): the CTA flies + reshapes from its own rect onto the dock
- * control's rect, fades + congests into the glass on the spring clock, then hands off.
- * Compositor-only + PRM-seats. See the module header for the REUSE + the FORWARD-play
- * mechanism + the channel split.
- *
- * @example
- * ```ts
- * const { receive, reset } = useDockCtaReceive(ctaRef, {
- *   dockControl: dockTargetRef,
- *   preset: "snappy",
- *   onReceived: () => (ctaConsumed.value = true),
- * })
- * // on the CTA click: morph it into the dock.
- * 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;