@mkbabb/glass-ui 4.1.0 → 4.2.0

package/dist/components/custom/dock/composables/dockMorphMeasure.d.ts

@@ -1,155 +1,86 @@
-import type { Ref } from "vue";
+import { type Ref } from "vue";
 /**
- * BB.W-CARVE4 — the dock morph MEASURE/SEAT helpers, carved out of
- * `dockMorphContext.ts` to hold the no-god-module bound (the aurora→useAurora /
- * goo-blob→useMetaballRenderer / fourier-field→useFourierField colocation pattern).
- * The orchestrator stays the morph DRIVER (it owns the `SpringProgress`, the targets
- * Set, the per-frame `--dock-morph-t` write); these are the PURE geometry + the
- * reserved-footprint measure + the SYNCHRONOUS PRM seat it composes. `DOCK_SPRING` is
- * byte-fenced — it lives in `../constants`, never touched here.
+ * BD.W-DOCK-CORE (the width-seizure cure) — the dock morph SIZE measure.
  *
- * The functions take their element/axis/target dependencies as explicit params (the
- * orchestrator's closures collapse onto this seam) — no module-level state, so the
- * extraction is behaviour-identical to the prior inline closures.
+ * THE BUG THIS RETIRES (the year-old seizure): the prior pipeline measured a
+ * per-swap `from/to` FLIP ratio and drove the visible size by
+ * `--dock-root-scale = max(ratio + (1−ratio)·t, 0.06)` — a FLOOR with NO CEILING.
+ * When the morph target measured small (a degenerate `to` racing the content
+ * layout), `ratio = from/max(to,1px)` ran to ~56 → `scaleX(56)` = a ~2451px
+ * detonation on collapse / an inversion at the spring overshoot peak. The
+ * `transform-origin: center` kept the centroid clean (`cxRange 0`), which is
+ * exactly why every prior judge measuring the centroid PASSED while the WIDTH
+ * detonated. The whole measure-and-arm FLIP machinery
+ * (`measureAndArmMorph`/`seatTargetSync`/`rebaseSiblingSpans`/
+ * `forceNestedMaxContent`/`nestedTargetsWithin`/`measureTo`/`armRootMorphSpan`/
+ * `clearRootMorphSpan`/`morphMinFloorPx`/the per-target generation gating) is
+ * DELETED — clean break, no legacy, no floor that masks a bad measurement.
+ *
+ * THE CURE — a ratio-FREE measure-ONCE convex blend. The dock measures its two
+ * KNOWN footprints ONCE per content change (a `ResizeObserver`, NOT a per-swap
+ * rAF race): `--dock-expanded-px` (the expanded content width, read behind the
+ * clip aperture) and `--dock-collapsed-px` (the collapsed summary box). The
+ * visible size is the convex blend `--dock-live = collapsed + (expanded −
+ * collapsed)·--dock-morph-t` and `--dock-size-scale = --dock-live / expanded`
+ * (layers.css). A convex blend of two POSITIVE endpoints can NEVER exceed the
+ * larger nor invert below the smaller — BOUNDED by construction, no ratio, no
+ * `scaleX` explosion, regardless of spring overshoot (the `clamp(0,t,1)` caps the
+ * size term; the >1 excursion routes to the orthogonal punch channel).
+ *
+ * THE FRESHNESS GUARD (challenge 3·R2): a measure-ONCE endpoint can still be read
+ * stale — before `fonts.ready`, before async icon SVGs lay out, on a
+ * `display:none`→0 route swap, or on a `content-visibility:auto` parent (the RO
+ * fires 0). A 0 expanded would give `collapsed/0 = ∞`. So FLOOR `--dock-expanded-px`
+ * at `max(measured, --dock-collapsed-px)` and re-measure on `fonts.ready` + the
+ * FIRST non-zero RO callback + visibility-enter. This is NOT the deleted magic
+ * floor (which masked a per-frame measurement); it is a one-shot endpoint
+ * sanity bound on a value that is otherwise stable across the whole morph.
+ *
+ * `DOCK_SPRING` is byte-fenced — it lives in `../constants`, never touched here.
  */
-/** The minimal morph-target shape the measure/seat helpers read (the orchestrator's
- *  full `MorphTarget` structurally satisfies it). */
-export interface MorphMeasureTarget {
-    containerEl: Ref<HTMLElement | null>;
-    axis: Ref<"horizontal" | "vertical">;
-    /** PER-TARGET swap generation — the seat gates its pipeline on its own id. */
-    txId: number;
-}
 export declare function dimOf(axis: "horizontal" | "vertical"): "width" | "height";
-export declare function morphAxisProp(axis: "horizontal" | "vertical"): "inline-size" | "block-size";
 export declare function getSize(el: HTMLElement, axis: "horizontal" | "vertical"): number;
-export declare function clearMorphVars(el: HTMLElement): void;
-/**
- * BC.W-LIQUID-MORPH (M3) — the reserve-floor in px (the measure-failure floor). The
- * CSS reserve floors the box at `max(var(--dock-morph-to), var(--dock-morph-min))`
- * (layers.css), but the SCALAR ratio still runs toward `--dock-morph-to`, so a
- * `to:0` mis-measure would interpolate toward a degenerate target. The orchestrator's
- * measure-failure guard seats the measured `to` at THIS px so the morph interpolates
- * toward a visible footprint, never 0 — "visible at the floor," never "white." Reads
- * the element's RESOLVED `--dock-morph-min` (density-scaled), falling back to the WCAG
- * ~44px touch floor when the token is unset / unresolvable. Pure read — no write.
- */
-export declare function morphMinFloorPx(el: HTMLElement | null): number;
-/**
- * BA-VJS-1 (valuejs-fold A-1) — the OTHER registered targets whose container is a
- * DOM DESCENDANT of `outerEl` (a nested `<DockLayerGroup>` stack inside the outer
- * `.dock-layers`). These are the pinned inner spans the outer measure must see at
- * their OWN intrinsic `max-content`, not their collapsed pin, or the outer
- * shrink-wraps to ~0.
- */
-export declare function nestedTargetsWithin(outer: MorphMeasureTarget, outerEl: HTMLElement, targets: Iterable<MorphMeasureTarget>): MorphMeasureTarget[];
-/**
- * BA-VJS-1 — force ONE nested target to its own-axis `max-content` (clearing its
- * reserved `--dock-morph-to` footprint so it sizes to content), and return a closure
- * that RESTORES its exact prior inline state. The restore re-writes the precise
- * prior `inline-size`/`block-size` inline value (or removes it if there was none),
- * so the inner's in-flight pin is byte-identical after the outer's measurement —
- * the inner target's own spring/pin pipeline is never disturbed.
- */
-export declare function forceNestedMaxContent(n: MorphMeasureTarget): () => void;
-/**
- * BB.W-DOCK-MORPH-FAMILY (c) — measure the true `to` for ONE target with the
- * morph axis forced to `max-content` (the same circular-measure escape the rAF
- * path uses), composing the BA-VJS-1 nested-descendant `max-content` ordering so
- * a nested group reads its TRUE intrinsic span (never `to:0`). The element is at
- * the live painted geometry on entry; this forces+reads+restores the axis. PURE
- * measure — no spring, no pin write.
- */
-export declare function measureTo(t: MorphMeasureTarget, el: HTMLElement, targets: Iterable<MorphMeasureTarget>): number;
-/** The orchestrator settle callbacks the synchronous seat composes (it clears the
- *  morph vars + nulls the leaving layer, then parks the root/spring once no target
- *  is morphing). */
-export interface MorphSeatCallbacks {
-    /** Settle ONE target (clear its morph vars + null its leavingLayer). */
-    settleTarget(t: MorphMeasureTarget): void;
-    /** Park the shared scalar + spring once NO target is morphing. */
-    maybeSettleRoot(): void;
-}
-/**
- * BB.W-DOCK-MORPH-FAMILY (c) — the SYNCHRONOUS PRM seat. Under
- * `prefers-reduced-motion: reduce` there is NO morph to play, so the geometry +
- * the scalar seat at the target in ONE step (the `useDockOrientationMorph.pin()`
- * precedent transplanted onto the collapse/expand path): measure the true `to`
- * (composing the BA-VJS-1 nested ordering), write the box at `to` (the
- * reserved-footprint reads at scale 1), and set `--dock-morph-t` to the endpoint
- * for THIS swap — then clear the morph state immediately (no rAF measure-defer,
- * no spring, no morph window). The box NEVER paints the collapsed `from` sliver
- * with the scalar at 1 (the P0 terminal failure). Endpoint is the per-swap
- * incoming-ness `1` (the new pane is fully in; the directional `--dock-expand-t`
- * resolves to the class endpoint with `[data-morphing]` cleared).
- */
-export declare function seatTargetSync(t: MorphMeasureTarget, id: number, root: HTMLElement | null, targets: Iterable<MorphMeasureTarget>, cb: MorphSeatCallbacks): void;
-/**
- * The swap-while-morphing sibling re-base. The shared scalar resets to 0 for the
- * new span; if SIBLING targets are mid-morph, re-base their `from` to their CURRENT
- * painted px first, so resetting the scalar keeps them visually continuous (they
- * interpolate fresh from where they are, toward their unchanged `to`) rather than
- * snapping back to their old `from`. PURE over the swapping target + the target set.
- */
-export declare function rebaseSiblingSpans(swapping: MorphMeasureTarget, targets: Iterable<MorphMeasureTarget>): void;
-/**
- * BC.W-DOCK-ROOT-MORPH — clear the ROOT box's own morph span (the `inline-size` =
- * f(scalar) recipe in layers.css reads `--dock-root-morph-from/to`; clearing them
- * hands the box back to the at-rest shrink-wrap once the morph settles). PURE on
- * the root element — no orchestrator closure.
- */
-export declare function clearRootMorphSpan(root: HTMLElement | null): void;
-/**
- * BC.W-DOCK-ROOT-MORPH — pin the ROOT box's own from→to span on the dock root.
- *
- * THE SNAP ROOT CAUSE: the inner `.dock-layers` reserves its SETTLED `to`
- * footprint (`inline-size: var(--dock-morph-to)`, layers.css — the E4-frozen
- * CDP-Layout-flat mechanism) and morphs VISUALLY via `transform: scaleX()`. A
- * `transform` is paint-only — a parent does NOT shrink-wrap to a scaled child —
- * so the root `.glass-dock` (display:inline-flex) shrink-wraps to the inner's
- * RESERVED full `to` width and SNAPS to full on frame 0, while the inner's scaled
- * box rides the spring smoothly. The gate (and the page) measure the ROOT box, so
- * the root must ALSO ramp. The layers.css recipe reads
- * `inline-size: calc(from + (to−from)·--dock-morph-t)` (the SAME scalar the spring
- * glides, NO CSS transition — proof:no-layout-animation stays GREEN; a `calc()`
- * over the registered `--dock-morph-t` is not a transition). PURE on the root.
- */
-export declare function armRootMorphSpan(root: HTMLElement | null, rootFrom: number, rootTo: number): void;
-/** The orchestrator callbacks the rAF measure-and-arm window composes — the arm
- *  step re-pins the per-target + root spans on the shared scalar. */
-export interface MorphMeasureArmCallbacks {
-    /** Arm the per-target `--dock-morph-from/to` span + ensure the shared spring. */
-    armTarget(t: MorphMeasureTarget, id: number, fromSize: number, toSize: number): void;
+export interface UseDockExpandedSizeOptions {
+    /** The `.glass-dock` root the `--dock-expanded-px`/`--dock-collapsed-px` write to. */
+    rootEl: Ref<HTMLElement | null>;
+    /**
+     * The content element whose intrinsic morph-axis span is observed for size
+     * changes (the active full-pane container — `.dock-layers`). Its resizes are the
+     * RO trigger; the ENDPOINTS are read off the ROOT box (content + chrome), keyed
+     * by the dock's at-rest expanded/collapsed state.
+     */
+    contentEl: Ref<HTMLElement | null>;
+    /**
+     * The morph axis (a horizontal dock blends width; a vertical dock blends height).
+     */
+    axis: Ref<"horizontal" | "vertical">;
+    /**
+     * Whether the dock is currently in its EXPANDED visual state (a `Ref<boolean>`).
+     * The endpoint captured at rest is keyed off this: at rest expanded → the root
+     * box is the `--dock-expanded-px` endpoint; at rest collapsed → the
+     * `--dock-collapsed-px` endpoint. (A reactive read, so a state flip re-captures.)
+     */
+    expanded: Ref<boolean>;
 }
 /**
- * BC.W-DOCK-ROOT-MORPH / BA-VJS-1 / BC.W-LIQUID-MORPH (M3) — the rAF measure-and-arm
- * window: ONE rAF (post-flush) later, lift the pin for a single synchronous
- * measurement of the now-correct shrink-wrapped to-size, then re-pin + start the
- * spring IN THE SAME FRAME. The measurement + arm are gated on THIS target's own
- * `txId`, so a sibling target swapping in the same tick does NOT clobber it.
- *
- * BA-VJS-1 — the nested-`DockLayerGroup` measure-ORDERING fix: force every OTHER
- * registered target whose container is a DOM descendant of this outer's container
- * to its own-axis `max-content` (clearing its pinned calc span) for the single
- * synchronous measurement, then RESTORE its exact prior inline state, so the outer
- * shrink-wraps around the inner's TRUE intrinsic content, not its pinned collapse.
- *
- * BC.W-DOCK-ROOT-MORPH — for the OUTER target, LIFT the root's own pinned span for
- * the duration of this synchronous measure (clearing `--dock-root-morph-from/to`,
- * which the layers.css recipe constrains the root by) so the root shrink-wraps to
- * its TRUE expanded width, read it DIRECTLY (sidestepping the chrome-offset
- * arithmetic + the empty-summary `inner-to:0` trap), then RESTORE the pin and
- * arm the root from→to span so its `inline-size` ramps on the SAME scalar.
+ * BD.W-DOCK-CORE — capture the two convex-blend endpoints ONCE PER STATE off the
+ * ROOT box.
  *
- * BC.W-LIQUID-MORPH (M3) — the measure-failure guard: a `to:0` mis-measure (a
- * mid-morph re-grab, a nested collapsible still pinned, a race the ordering fix
- * missed) seats the measured `to` at the resolved floor (`--dock-morph-min`,
- * density-scaled, WCAG ~44px fallback) so the morph interpolates toward a visible
- * footprint, never toward 0 — "visible at the floor," never "white." Inert on a
- * healthy measurement.
+ * The visible morph scales the ROOT (chrome + content), so the two blend endpoints
+ * must be the ROOT's OWN expanded/collapsed footprints — NOT the bare content span
+ * (which omits the padding/min-width chrome). The endpoints are captured at REST
+ * (when `[data-morphing]` is OFF): the dock's settled root box in its current
+ * expanded/collapsed state IS that state's endpoint. A `ResizeObserver` on the
+ * content re-captures the CURRENT state's endpoint whenever the content reflows
+ * (more controls, a font swap), so the blend stays fresh — but it never reads the
+ * box MID-MORPH (the scaled box would feed back a degenerate endpoint, the seizure's
+ * cousin). The expanded endpoint is FLOORED at `max(captured, collapsed)` — the
+ * freshness guard against a 0/degenerate read giving `collapsed/0 = ∞`.
  *
- * PURE over its explicit deps (the orchestrator passes the live element/targets/
- * outer identity + the `armTarget` re-pin callback) — no module-level state, so the
- * extraction is behaviour-identical to the prior inline rAF closure.
+ * The collapsed endpoint starts at the resolved `--dock-morph-min` icon-square floor
+ * and is refined to the real collapsed root box the first time the dock rests
+ * collapsed; the expanded endpoint is captured the first (and every) time it rests
+ * expanded. So the FIRST morph from a freshly-mounted expanded dock already has a
+ * real expanded endpoint + a sane collapsed floor — bounded by construction.
  */
-export declare function measureAndArmMorph(t: MorphMeasureTarget, id: number, axis: "horizontal" | "vertical", fromSize: number, rootFromSize: number, isOuter: boolean, rootEl: HTMLElement | null, targets: Iterable<MorphMeasureTarget>, cb: MorphMeasureArmCallbacks): void;
+export declare function useDockExpandedSize(options: UseDockExpandedSizeOptions): void;

package/dist/components/custom/dock/composables/index.d.ts

@@ -11,3 +11,4 @@ export { provideDockContext, useDockContext, useOptionalDockContext, DOCK_CONTEX
 export { provideDockLayerGroupContext, useDockLayerGroupContext, useOptionalDockLayerGroupContext, DOCK_LAYER_GROUP_KEY, type DockLayerDescriptor, type DockLayerGroupContext, } from "./dockLayerContext";
 export { useDockMorphOrchestrator, provideDockMorphContext, useOptionalDockMorphContext, DOCK_MORPH_KEY, type DockMorphContext, type DockMorphGroupRegistration, type DockMorphGroupHandle, type UseDockMorphOrchestratorOptions, type UseDockMorphOrchestratorReturn, } from "./dockMorphContext";
 export { useDockOrientationMorph, type DockMorphOrientation, type UseDockOrientationMorphOptions, type UseDockOrientationMorphReturn, } from "./useDockOrientationMorph";
+export { useDockFission, DOCK_SPLIT_SIGNATURES, type DockSplitContext, type DockSplitVector, type DockSplitSquishPeak, type DockSplitSignature, type DockFissionPieceRegistration, type DockFissionPieceHandle, type UseDockFissionOptions, type UseDockFissionReturn, } from "./useDockFission";

package/dist/components/custom/dock/composables/railProjection.d.ts

@@ -0,0 +1,45 @@
+/** The signed shortest-arc offset on a wrap ring (the "negative-infinity modulus" — a
+ *  naive `raw % N` breaks the backward wrap). Wraps to `[-N/2, N/2)`. */
+export declare function ringOffset(raw: number, n: number): number;
+/** The φ-tiered slot SPAN to a given absolute slot-distance — the chosen→neighbour gap
+ *  is wider than the neighbour→far gap (the recession compresses as items recede, the
+ *  depth read). The tier ratio is EXPRESSED in the accumulation, never a flat resolved
+ *  rebake (the W-CARD-PAD φ-ladder fence). */
+export declare function tieredSpan(adist: number, base: number, ratio: number): number;
+/** The geometry knobs for the facet carousel — the φ-tier spacing + the fade model. */
+export interface RailProjectionGeometry {
+    /** The active→neighbour base slot gap, in px (the tier-0 spacing). Default 44. */
+    slotSpacing?: number;
+    /** The φ tier ratio — each receding tier compresses by this. Default 1.618. */
+    tierRatio?: number;
+    /** The slot-distance at which the fade begins (active + immediate neighbour stay
+     *  full). Default 0.5. */
+    fadeStart?: number;
+    /** The slot-span the fade runs over. Default 2.5. */
+    fadeRange?: number;
+    /** The far floor alpha. Default 0. */
+    fadeMinAlpha?: number;
+    /** The per-slot scale recession (the depth read). Default 0.06. */
+    scaleStep?: number;
+    /** The max slots the scale recession clamps at. Default 4. */
+    scaleClampSlots?: number;
+}
+/** One projected facet — the compositor-only transform tier for the ring item. */
+export interface RailFacetProjection {
+    /** The stable ring index `0..count-1` (the `v-for` key). */
+    index: number;
+    /** The signed shortest-arc slot offset from the active facet. */
+    offset: number;
+    /** The px translate along the rail's main axis. */
+    translate: number;
+    /** The faded alpha (0..1). */
+    opacity: number;
+    /** The recession scale (≤1). */
+    scale: number;
+    /** Whether this is the active facet (offset 0). */
+    active: boolean;
+}
+/** Project the facet ring around the `active` index, fanned by `expand` (0 collapsed → 1
+ *  fully fanned). Returns the virtualized WINDOW of `±ceil(fadeRange+1)` items, each with
+ *  its compositor-only `{ translate, opacity, scale }`. PURE — no state, no measure. */
+export declare function projectFacets(count: number, active: number, expand: number, geometry?: RailProjectionGeometry): RailFacetProjection[];

package/dist/components/custom/dock/composables/useDockContextSilhouette.d.ts

@@ -0,0 +1,192 @@
+import { type MorphRect } from "@mkbabb/keyframes.js";
+import { type Ref } from "vue";
+import { type SpringPresetName } from "../../../../composables/motion/springPresets";
+/** The dock orientation axis (the `dim`-idiom source — slot geometry derives from it). */
+export type SilhouetteOrientation = "horizontal" | "vertical";
+/** The four named silhouette kinds (the descriptor map's contract). */
+export type DockSilhouetteKind = "bar" | "bar+pill" | "split" | "search";
+/**
+ * The silhouette spring register — a subset of the named `SPRING_PRESETS` rows matching
+ * the `useDockCtaReceive`/`useLiquidReveal` register so every dock morph reads as ONE
+ * spring family. `dock` is the default (the dock's own settle clock).
+ */
+export type SilhouettePreset = Extract<SpringPresetName, "dock" | "snappy" | "bouncy">;
+/**
+ * One named SLOT inside a silhouette — a position keyed by `controlId`. The geometry is
+ * ORIENTATION-DERIVED: `main` is the offset along the dock's main axis (the row position
+ * horizontal / the column position vertical), `cross` the cross-axis offset, `size` the
+ * control's extent. The orchestrator resolves these into a concrete `MorphRect` off the
+ * orientation + the dock's measured origin (the `dim`-idiom — never a hardcoded
+ * `inline-size`/`block-size` literal, so vertical is the SAME data with `orientation`
+ * flipped).
+ */
+export interface SilhouetteSlot {
+    /** The control this slot positions (the diff key — present-in-both → FLIP). */
+    controlId: string;
+    /** Offset along the dock's MAIN axis (px from the dock origin). */
+    main: number;
+    /** Offset along the CROSS axis (px from the dock origin). */
+    cross: number;
+    /** The control's main-axis extent (px). */
+    size: number;
+    /** The control's cross-axis extent (px; defaults to `size` for a square control). */
+    thickness?: number;
+    /**
+     * FUSION marker (the `bar+pill` headline): when true, this slot's `to`-rect is the
+     * bar's TOP CROWN and the orchestrator drives `--silhouette-fuse-t` so the slotted
+     * control (the now-playing pill) DOCKS DOWN and MELDS into the bar as ONE plate. A
+     * `bar+pill` descriptor with NO `fuse: true` slot is a pill-ABOVE-bar literal (the
+     * C3 anti-evasion — the gate reds it).
+     */
+    fuse?: boolean;
+}
+/**
+ * One declarative silhouette descriptor — a context's whole geometry as DATA (the
+ * `DockSectionDescriptor` precedent: data, not code paths). The orchestrator reads the
+ * MAP; there is NO per-context hardcoded silhouette literal (the gate's C1 anti-evasion
+ * floor).
+ */
+export interface DockSilhouetteDescriptor {
+    /** Stable identifier — the `setSilhouette` argument + the active-silhouette id. */
+    id: string;
+    /** Which of the four named kinds this context renders. */
+    kind: DockSilhouetteKind;
+    /** The named slots (control positions) this silhouette places. */
+    slots: readonly SilhouetteSlot[];
+    /** This silhouette's spring register (DATA, not an SFC ternary). Default `dock`. */
+    preset?: SilhouettePreset;
+    /**
+     * The neck-hold for any DETACH this transition drives (DATA — fed to `useDockFission`
+     * when a control is present-in-from-only). 0 = no hold (immediate release), 1 = full
+     * hold (the goo necks late then snaps).
+     */
+    neckHold?: number;
+}
+/**
+ * The DETACH hand-off API the orchestrator drives (BE.W-DOCK-FISSION owns the engine).
+ * A control PRESENT-only-in-FROM detaches — the orchestrator registers it as a fission
+ * PIECE via `registerPiece` and the fission orchestrator buds it off the body. Defined
+ * here per the fission spec (`useDockFission` `registerPiece`); the sibling agent builds
+ * it, the orchestrator reconciles the import. The orchestrator never re-implements the
+ * detach physics — it CALLS this.
+ */
+export interface FissionPieceHandle {
+    /** Release the piece (drive its `--dock-split-t` 0→1 detach). */
+    detach: () => void;
+    /** Re-merge the piece (the bidirectional 1→0). */
+    remerge: () => void;
+    /** Unregister the piece (cleanup). */
+    release: () => void;
+}
+/** The fission registrar the orchestrator composes (BE.W-DOCK-FISSION's `registerPiece`). */
+export type RegisterFissionPiece = (el: HTMLElement, spec: {
+    vector: {
+        dx: number;
+        dy: number;
+    };
+    rank: number;
+    neckHold: number;
+}) => FissionPieceHandle;
+/**
+ * The BLOOM-IN hand-off API the orchestrator drives (BE.W-BLOOM-UP owns the engine). A
+ * control PRESENT-only-in-TO blooms in — the inverse FLIP. Defined here per the bloom-up
+ * spec (`useBloomUp(sourceRef, destRef)`); the orchestrator CALLS it, never re-implements
+ * the bloom.
+ */
+export type BloomInPiece = (el: HTMLElement, fromRect: MorphRect, toRect: MorphRect) => void;
+export interface UseDockContextSilhouetteOptions {
+    /** The declarative silhouette descriptor MAP (the four kinds; net-new DATA). */
+    silhouettes: readonly DockSilhouetteDescriptor[];
+    /** The id of the silhouette to seat at construction (defaults to the first). */
+    initial?: string;
+    /** The dock orientation (the `dim`-idiom source). Default `horizontal`. */
+    orientation?: SilhouetteOrientation | Ref<SilhouetteOrientation>;
+    /**
+     * Resolve a control's live element by `controlId` (the orchestrator measures its
+     * current rect for the FLIP). The consumer wires this off its slot refs.
+     */
+    resolveControl: (controlId: string) => HTMLElement | null;
+    /**
+     * The dock ROOT element — the orchestrator measures its origin (to resolve a slot's
+     * orientation-derived `main`/`cross` into a viewport `MorphRect`) AND writes
+     * `--silhouette-fuse-t` onto it for the fusion meld. The fused glass plate is the
+     * dock body itself (C5 — the detach pieces paint in the non-clipping frame; the fused
+     * plate is the dock root).
+     */
+    dockRoot: Ref<HTMLElement | null>;
+    /**
+     * The DETACH registrar (BE.W-DOCK-FISSION's `registerPiece`). When absent, a
+     * present-in-from-only control is simply removed from the FLIP set (no detach
+     * choreography — graceful until fission wires in).
+     */
+    registerFissionPiece?: RegisterFissionPiece;
+    /**
+     * The BLOOM-IN driver (BE.W-BLOOM-UP). When absent, a present-in-to-only control
+     * snaps in (no bloom choreography — graceful until bloom-up wires in).
+     */
+    bloomInPiece?: BloomInPiece;
+    /** Honor `prefers-reduced-motion: reduce` (seat synchronously). Default true. */
+    respectReducedMotion?: boolean;
+    /** Fired once when a silhouette transition has settled (the consumer hand-off). */
+    onSettled?: (toId: string) => void;
+}
+export interface UseDockContextSilhouetteReturn {
+    /** The active silhouette id (reactive — the consumer reads the SHAPE). */
+    active: Readonly<Ref<string>>;
+    /** The active descriptor (reactive). */
+    activeDescriptor: Readonly<Ref<DockSilhouetteDescriptor | null>>;
+    /** Whether a transition is in flight (the consumer guards re-entrancy / `[data-morphing]`). */
+    transitioning: Readonly<Ref<boolean>>;
+    /**
+     * Transition to the silhouette `toId` — DIFFs the slots by `controlId`, FLIPs the
+     * survivors, detaches the from-only, blooms in the to-only, and drives the fusion
+     * meld for a `bar+pill` target. A no-op if `toId` is unknown or already active.
+     */
+    setSilhouette: (toId: string) => void;
+}
+/**
+ * The declarative context→silhouette state machine. Reads a `DockSilhouetteDescriptor[]`
+ * MAP; on `setSilhouette` it DIFFs the slots by `controlId` and FLIPs/detaches/blooms via
+ * the SHIPPED `ElementMorph` + `springTimingFunction` substrate, ONE `DOCK_SPRING`. The
+ * `bar+pill` fusion docks the pill into the bar via `--silhouette-fuse-t`. Compositor-only
+ * + PRM-seats. See the module header for the REUSE + the orientation-derived slots + the
+ * fusion mechanism.
+ *
+ * @example
+ * ```ts
+ * const sil = useDockContextSilhouette({
+ *   silhouettes: [
+ *     { id: "nav",   kind: "bar",      slots: [...] },
+ *     { id: "media", kind: "bar+pill", slots: [{ controlId: "pill", main: 0, cross: -56, size: 240, fuse: true }, ...] },
+ *   ],
+ *   orientation,
+ *   dockRoot,
+ *   resolveControl: (id) => slotRefs.value[id] ?? null,
+ * })
+ * sil.setSilhouette("media") // the pill DOCKS DOWN + MELDS into the bar
+ * ```
+ */
+export declare function useDockContextSilhouette(options: UseDockContextSilhouetteOptions): UseDockContextSilhouetteReturn;
+/**
+ * Compute a detached control's DIRECTION-VECTOR off its slot + the orientation (the
+ * fission `vector` — the `dim`-idiom). A control peels along the CROSS axis (the
+ * `stack-rail.css` gutter direction the fission media=lateral signature reuses): the sign
+ * of `cross` chooses the side, the orientation chooses the axis. This is PURE (exported
+ * for the unit test — the slot-diff vector logic is testable without a DOM).
+ */
+export declare function detachVector(slot: SilhouetteSlot, orientation: SilhouetteOrientation): {
+    dx: number;
+    dy: number;
+};
+/**
+ * PURE slot-diff — exported for the unit test (the diff logic is testable without a DOM).
+ * Classifies each controlId across the from/to slot sets: `survivors` (present-in-both →
+ * FLIP), `bloomIns` (to-only → BLOOM), `detaches` (from-only → DETACH). This is the
+ * load-bearing classification `setSilhouette` runs; testing it directly proves the
+ * descriptor-driven state machine is correct without a browser.
+ */
+export declare function diffSilhouetteSlots(from: readonly SilhouetteSlot[], to: readonly SilhouetteSlot[]): {
+    survivors: string[];
+    bloomIns: string[];
+    detaches: string[];
+};

package/dist/components/custom/dock/composables/useDockFission.d.ts

@@ -0,0 +1,158 @@
+import { type Ref } from "vue";
+/** The three named fission CONTEXTS — each maps to a goo signature (F3). */
+export type DockSplitContext = "search" | "media" | "nav";
+/** The detach vector family a context selects. */
+export type DockSplitVector = "radial" | "lateral" | "inward-merge";
+/**
+ * BD.W-DOCK-CORE (II.2 — F-1 the headline fix). The placement axis the detached
+ * pieces TRAVEL ALONG to form the sibling island dock. The prior build let each
+ * piece scatter on its own radial center → it read as inline jitter inside the one
+ * pill, NOT a detach. A single COHERENT placement vector flies the whole piece
+ * cluster off the source plate so a second dock visibly materializes beside/above/
+ * below (the iOS-27 split read).
+ */
+export type DockSplitPlacement = "beside" | "above" | "below";
+/** The unit placement vector each `splitPlacement` flies the cluster along. */
+export declare const PLACEMENT_VECTOR: Readonly<Record<DockSplitPlacement, {
+    dx: number;
+    dy: number;
+}>>;
+/** The squish-peak register — WHEN the `useLiquidFlex` swell peaks in the travel. */
+export type DockSplitSquishPeak = "late" | "long" | "coalesce";
+/**
+ * The per-context goo-SIGNATURE descriptor (F3 — the FLOOR, DATA not three code paths).
+ * The orchestrator reads this to compute each piece's vector + stagger + neck phase; the
+ * ONE `fission-bridge.css` recipe paints whatever the pieces carry.
+ */
+export interface DockSplitSignature {
+    /** The context this signature serves. */
+    context: DockSplitContext;
+    /** The detach-vector family. */
+    vector: DockSplitVector;
+    /**
+     * How long the goo neck HOLDS before it snaps (0..1 of `--split-t`). High = the
+     * tense radial pop (neck holds to ~0.55 then snaps); the neck-break offset.
+     */
+    neckHold: number;
+    /**
+     * The per-piece stagger-rank resolver — returns piece `i`'s ordinal in the break
+     * SEQUENCE (innermost-first for radial, outside-in for lateral). The orchestrator
+     * phase-shifts each piece's `--neck-t` by `staggerStep * rank` so the N necks break
+     * in sequence, never simultaneously (the `--split-stagger * rank(i)` idiom).
+     */
+    staggerRank: (i: number, count: number) => number;
+    /** WHEN the `useLiquidFlex` squish swell peaks across the travel. */
+    squishPeak: DockSplitSquishPeak;
+}
+/** The canonical per-context signature MAP (F3 — search/media/nav, descriptor-driven). */
+export declare const DOCK_SPLIT_SIGNATURES: Readonly<Record<DockSplitContext, DockSplitSignature>>;
+/** The per-piece DIRECTION-VECTOR + rank a control registers (the MorphTarget twin). */
+export interface DockFissionPieceRegistration {
+    /** The detaching control element (its `--split-*`/`--neck-t` vars are written here). */
+    el: Ref<HTMLElement | null>;
+    /**
+     * The detach DIRECTION as a unit-ish vector in dock-local space (the bloom/peel
+     * direction). `radial` blooms `(cx_i − cx_dock)`-ward; `lateral` peels cross-axis;
+     * `inward-merge` is the negative radial. May be a getter so a live re-measure
+     * (the FLIP-measured center) re-resolves per read.
+     */
+    vector: {
+        dx: number;
+        dy: number;
+    } | (() => {
+        dx: number;
+        dy: number;
+    });
+    /**
+     * The piece's ordinal in the registration order (the `--i` the bridge reads + the
+     * input to the signature's `staggerRank`). Stable per piece.
+     */
+    rank: number;
+}
+/** The handle a registered piece holds (detach on unmount). */
+export interface DockFissionPieceHandle {
+    /** Detach this piece from the orchestrator (on the control's unmount). */
+    release(): void;
+}
+export interface UseDockFissionOptions {
+    /** The `.glass-dock` root (or the fission scope) the shared `--dock-split-t` writes to. */
+    rootEl: Ref<HTMLElement | null>;
+    /**
+     * The active signature (the context the dock is fissioning under). A `Ref` so a
+     * consumer can swap contexts; the orchestrator reads `.value` at split time.
+     */
+    signature: Ref<DockSplitSignature>;
+    /**
+     * BD.W-DOCK-CORE (II.2 — F-1). The placement the detached pieces fly to form the
+     * sibling island. A `Ref` so a consumer can swap placement. The orchestrator writes
+     * the per-piece travel along this ONE coherent vector (not per-piece radial scatter)
+     * so the cluster reads as a real detach into a second dock beside/above/below.
+     * Defaults to `"beside"`.
+     */
+    placement?: Ref<DockSplitPlacement>;
+    /**
+     * The LOW squish cap the `useLiquidFlex` recoil saturates at (≤1.08 — the anti-taffy
+     * fence). May be a getter so a live `--*-max-stretch` cascade override re-resolves.
+     * Defaults to 1.08 (the `useLiquidFlex` register).
+     */
+    maxStretch?: number | (() => number);
+    /**
+     * The seam-tension cap (F4 — kept LOW ≈0.12, the `useLiquidFlex` maxStretch
+     * register). A fast pull THINS the neck via the existing `clip-path` channel up to
+     * this cap, saturating — never a taffy-pull.
+     */
+    seamTensionCap?: number;
+    /**
+     * The seam-tension velocity gain `k` — `--seam-tension = clamp(0, speed·k, cap)`.
+     * Defaults to 0.6 (a calm gain over the normalized-host velocity).
+     */
+    seamTensionGain?: number;
+    /**
+     * The per-rank stagger STEP — the `--neck-t` phase shift per stagger-rank so the N
+     * necks break in sequence (the `--split-stagger * rank` idiom). Defaults to 0.08.
+     */
+    staggerStep?: number;
+    /** Honor `prefers-reduced-motion: reduce` → instant sync-seat (F5). Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseDockFissionReturn {
+    /** The live split scalar (0 rest → 1 fissioned), the last value the spring wrote. */
+    readonly t: Readonly<Ref<number>>;
+    /** True while the dock is fissioned (or mid-fission past the threshold). */
+    readonly fissioned: Readonly<Ref<boolean>>;
+    /**
+     * Register a surviving control as a fission PIECE (the `Set<MorphTarget>` pattern).
+     * The piece carries its DIRECTION-VECTOR + rank; the orchestrator writes its
+     * `--split-dx`/`--split-dy`/`--i`/`--neck-t` off the active signature.
+     */
+    registerPiece(reg: DockFissionPieceRegistration): DockFissionPieceHandle;
+    /** SPLIT — run the scalar 0→1 (carve the pill into the N pieces). */
+    split(): void;
+    /** RE-MERGE — run the scalar 1→0 (the SAME loop, target flipped — F2 bidirectional). */
+    merge(): void;
+    /** Toggle split↔merge from the current state. */
+    toggle(): void;
+    /**
+     * The `@pointermove` handler the consumer binds on the dock host — feeds the raw
+     * pointer to the velocity field (the field is ticked from INSIDE the driver loop).
+     * PRM-gated by the field itself.
+     */
+    onPointerMove(event: PointerEvent): void;
+    /** Tear down the spring + the field listener (auto-run on scope dispose). */
+    dispose(): void;
+}
+/**
+ * The n-ary detach orchestrator. ONE `SpringProgress` on `DOCK_SPRING` writing
+ * `--dock-split-t` + per-piece `--split-dx`/`--split-dy`/`--i`/`--neck-t` off the active
+ * `DockSplitSignature`, the snap-recoil on `useLiquidFlex`, the seam-tension on
+ * `usePointerVelocityField` (fed from inside the ONE loop), PRM sync-seated. See the
+ * module header for the load-bearing-reuse + box-inviolate rationale.
+ *
+ * @example
+ * ```ts
+ * const fission = useDockFission({ rootEl, signature })
+ * const h = fission.registerPiece({ el: searchIconRef, vector: { dx: -1, dy: 0 }, rank: 0 })
+ * fission.split()    // the pill carves into the pieces along the signature
+ * ```
+ */
+export declare function useDockFission(options: UseDockFissionOptions): UseDockFissionReturn;