@mkbabb/glass-ui 6.0.0 → 7.0.0

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

@@ -1,96 +1,17 @@
 import { type Ref } from "vue";
-/**
- * BD.W-DOCK-CORE (the width-seizure cure) — the dock morph SIZE measure.
- *
- * 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.
- */
-export declare function dimOf(axis: "horizontal" | "vertical"): "width" | "height";
 export declare function getSize(el: HTMLElement, axis: "horizontal" | "vertical"): number;
 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).
-     */
+    expandedEl: Ref<HTMLElement | null>;
+    collapsedEl: Ref<HTMLElement | null>;
     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>;
 }
-export interface DockMorphMeasureFailure {
-    readonly code: "invalid-morph-min";
-    readonly token: string;
-}
-export interface UseDockExpandedSizeReturn {
-    /** The single fail-closed state for an unreadable semantic geometry token. */
-    failure: Readonly<Ref<DockMorphMeasureFailure | null>>;
-}
-/** Resolve the inherited semantic token through CSS itself, including max()/rem/var(). */
-export declare function resolveDockMorphMin(root: HTMLElement): number | null;
 /**
- * BD.W-DOCK-CORE — capture the two convex-blend endpoints ONCE PER STATE off the
- * ROOT box.
- *
- * 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 = ∞`.
- *
- * 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.
+ * Measure the dock's two rendered pane compositions. The inactive pane remains
+ * laid out (visibility, never display, hides it), so the first morph can derive
+ * both endpoints from real content—coarse controls bring their own 44px floor;
+ * non-interactive visuals receive no invented one.
  */
-export declare function useDockExpandedSize(options: UseDockExpandedSizeOptions): UseDockExpandedSizeReturn;
+export declare function useDockExpandedSize(options: UseDockExpandedSizeOptions): void;

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

@@ -7,4 +7,4 @@ export type { UseDockHoldOptions, UseDockHoldReturn } from "./useDockHold";
 export { isTeleportedTarget } from "./isTeleportedTarget";
 export { provideDockContext, useDockContext, useOptionalDockContext, DOCK_CONTEXT_KEY, type DockContext, type DockOrientation, } from "./dockContext";
 export { provideDockCrossfadeContext, useDockCrossfadeContext, useOptionalDockCrossfadeContext, DOCK_CROSSFADE_KEY, type DockFaceDescriptor, type DockFaceRegistration, type DockCrossfadeContext, } from "./dockCrossfadeContext";
-export { useDockMorphOrchestrator, provideDockMorphContext, useOptionalDockMorphContext, DOCK_MORPH_KEY, type DockMorphContext, type DockMorphGroupRegistration, type DockMorphGroupHandle, type UseDockMorphOrchestratorOptions, type UseDockMorphOrchestratorReturn, } from "./dockMorphContext";
+export { useDockMorphOrchestrator, type UseDockMorphOrchestratorOptions, type UseDockMorphOrchestratorReturn, } from "./useDockMorph";

package/dist/components/dock/composables/useDockClickIntegrity.d.ts

@@ -18,7 +18,7 @@ export interface UseDockClickIntegrityOptions {
     visualExpanded: Ref<boolean>;
 }
 /**
- * The dock click-integrity guard (R5-3). Returns the three capture-phase handlers
+ * The dock click-integrity guard. Returns the three capture-phase handlers
  * the GlassDock SFC wires onto its root. The guard is a pure DOM-timing concern: it
  * holds the press-time element identity + the settle-window deadline and decides, on
  * the click, whether the click landed on the SAME control it was aimed at. Owns its

package/dist/components/dock/composables/useDockHold.d.ts

@@ -1,6 +1,6 @@
 import type { ComputedRef } from "vue";
 /**
- * AX.W03 — the host-native dock hold.
+ * Host-native dock hold.
  *
  * `keepDockOpen` is a FIRST-CLASS, synchronous morph-state input to the dock's
  * one state machine: while a continuous pointer/touch gesture is live on a
@@ -17,9 +17,8 @@ import type { ComputedRef } from "vue";
  * Slot/forwardRef boundary — vue-tsc + units pass, only a real drag catches it
  * (the canonical binding-verification class, `feedback_glass_ui_binding_*`). A
  * native `addEventListener` on the RESOLVED host element is immune: the event
- * always reaches the DOM node the user actually presses. This is the
- * device-proven fix (AX.W03 §Scope.1/2 — slice-2 F0/F2; ratified host-native
- * over a reka `dragging`-ref subscription, which reka does not publicly expose
+ * always reaches the DOM node the user actually presses. This host-native behavior is
+ * preferable to a Reka `dragging`-ref subscription, which Reka does not publicly expose
  * and which would re-introduce the same forwarding fragility).
  *
  * The hold is INSTANT-ON (Apple "Building Fluid Interfaces", facet 5): the first
@@ -34,7 +33,7 @@ import type { ComputedRef } from "vue";
  * hold path, no parallel `touchGate` watch).
  *
  * DI: consumes the EXISTING typed `DockContext` via `useOptionalDockContext()`
- * (the `keepOpen`/`release` pair, O.W2 single-typed-key collapse). A control
+ * through the `keepOpen` and `release` pair. A control
  * rendered OUTSIDE a `<GlassDock>` gets the befitting-silent default (no dock) —
  * every hook is a no-op, a primitive may legitimately render outside a dock.
  */

package/dist/components/dock/composables/useDockMorph.d.ts

@@ -0,0 +1,26 @@
+import type { Ref } from "vue";
+/**
+ * The dock collapse/expand morph has one job: project the current outer face
+ * onto the shared `--dock-morph-t` spring. Controlled face swaps belong to
+ * `DockCrossfade`; they do not register with, or resize, the dock shell.
+ */
+export interface UseDockMorphOrchestratorOptions {
+    /** The `.glass-dock` root carrying the shared scalar. */
+    rootEl: Ref<HTMLElement | null>;
+    /** The outer collapsed/expanded face id. */
+    outerActiveLayer: Ref<string>;
+    /** Notifies the shell when the spring arms and settles. */
+    onMorphActiveChange?: (active: boolean) => void;
+}
+export interface UseDockMorphOrchestratorReturn {
+    /** The outer face that currently owns layout and interaction. */
+    outerCurrentLayer: Readonly<Ref<string>>;
+    /** The face fading out, or null after settle. */
+    outerLeavingLayer: Readonly<Ref<string | null>>;
+}
+/**
+ * Drive the outer collapsed/expanded pair from the sole dock spring. Mid-flight
+ * reversals complement both position and velocity so the painted trajectory is
+ * continuous; reduced motion seats the same endpoint immediately.
+ */
+export declare function useDockMorphOrchestrator(options: UseDockMorphOrchestratorOptions): UseDockMorphOrchestratorReturn;

package/dist/components/dock/composables/useDockOverflowFit.d.ts

@@ -1,14 +1,12 @@
 import { type Ref } from "vue";
 /**
- * useDockOverflowFit — the fits-vs-scrollable mode resolution for the dock's native
- * scroll track (BI.W-DOCK-OVERFLOW, PASS-1 §2.5). A MEASURED branch (the wave's "single
- * container-query / measured branch"): it toggles `[data-dock-overflow]` on the dock root
+ * useDockOverflowFit resolves fits-vs-scrollable mode for the dock's native scroll
+ * track. It toggles `[data-dock-overflow]` on the dock root
  * when content exceeds the horizontal full-layer port or vertical root scroll host.
  * The overflow.css scroll track + FadingScroll edge mask engage ONLY under that attr, so
- * at rest (fits) the mask is `none` (T-52 a — no 0px-fade shave) and the fisheye is FREE
- * (fisheye.css gates on `:not([data-dock-overflow])`, the exclusive-mode ruling).
+ * at rest (fits) the mask is `none`.
  *
- * G9 / O5 — ZERO SCROLL LISTENER. The measure is RESIZE- and CONTENT-driven (a
+ * The measure is resize- and content-driven, with no scroll listener (a
  * `ResizeObserver` on the dock + the port, plus a narrowly filtered `MutationObserver`
  * on dock content). It never listens to `scroll` — the traveling indicator (`useSelectionIndicator`)
  * lives inside the scroll port and travels WITH scroll in content coordinates, needing no

package/dist/components/dock/composables/useDockSearch.d.ts

@@ -1,7 +1,7 @@
 import { type MaybeRefOrGetter, type Ref } from "vue";
 import type { UseDockStateReturn } from "./useDockState";
 import { type FuzzySearchState, type SearchableItem, type SearchResult } from "../../search/composables";
-import { type UseScrollChromeReturn } from "../../../composables/motion/useScrollChrome";
+import { type UseScrollChromeReturn } from "../../../composables/motion/scroll/useScrollChrome";
 export interface UseDockSearchOptions<T extends SearchableItem = SearchableItem> {
     /** Composes the existing dock state machine (no fork) — `armSearch`/`disarmSearch`
         ride its `onClickCollapsed`/`keepOpen`/`release`. */
@@ -34,19 +34,19 @@ export interface UseDockSearchOptions<T extends SearchableItem = SearchableItem>
     /** The dock element the collapse-on-scroll writes `--chrome-collapse-t` onto. */
     chromeRef?: MaybeRefOrGetter<HTMLElement | null>;
     /**
-     * Result-select hook — wires the ToC subsume: `ensureTargetWindow(id)` (warm the
-     * window so the target renders) + `scrollTo(id)` (the rAF-retry scroll-to-and-land).
+     * Result-select hook — wires the ToC subsume: `ensureTargetWindow(id)` (seat the
+     * target's bounded render window) + `scrollTo(id)` (the rAF-retry scroll-to-and-land).
      * The dock owns the gesture; the consumer passes the two leaves' bound functions.
      */
     onResultSelect?: (result: SearchResult<T>) => void;
     /**
-     * The virtual-window warm step (composed `useVirtualSectionWindow.ensureTargetWindow`).
-     * Called BEFORE `scrollTo` on a result-select so the windowed target is rendered.
+     * Consumer-provided target-window step. Called BEFORE `scrollTo` on result
+     * selection so a windowed target can render before the scroll lands.
      */
     ensureTargetWindow?: (id: string) => void;
     /**
      * The ToC scroll-to (composed `useScrollTo.scrollTo`) — the rAF-retry scroll-to-id.
-     * Called AFTER the warm step on a result-select.
+     * Called AFTER the target-window step on a result-select.
      */
     scrollTo?: (id: string) => void;
 }
@@ -71,9 +71,9 @@ export interface UseDockSearchReturn<T extends SearchableItem = SearchableItem>
  * `useScrollChrome`); the `armSearch`/`disarmSearch`/`autocompleteText`/
  * `acceptAutocomplete` surface; the async `onSearch` adapter; the `onResultSelect` →
  * `ensureTargetWindow` + `scrollTo` wire. Does NOT edit the morph engine
- * (`dockMorphContext`/`DOCK_SPRING` byte-untouched — the box-inviolate fence); the
+ * (`useDockMorph`/`DOCK_SPRING` byte-untouched — the box-inviolate fence); the
  * pill→field morph is the dock's OWN `--dock-morph-t`/`--dock-t` plate glide, and the
- * results dropdown re-hosts on a top-layer `popover` (BI.W-DOCK-ESCAPE — `useDockPopover`).
+ * results surface is consumer-authored and can be portaled independently of the dock.
  *
  * @example
  * ```ts

package/dist/components/dock/composables/useDockShellProps.d.ts

@@ -1,9 +1,10 @@
 import { type ComputedRef } from "vue";
 export type DockSize = "sm" | "md" | "lg" | "xl";
 export type DockBackdropMode = "live" | "static";
+export type DockInteraction = "auto" | "manual";
 /**
- * The ONE GlassDock prop shape (AZ.W-DOCK-TAXONOMY — the discriminated union is
- * gone). Every dock — horizontal or vertical — reads the SAME surface; orientation
+ * The GlassDock prop shape. Every dock—horizontal or vertical—reads the same
+ * surface; orientation
  * is the single layout axis and the collapse surface applies on both.
  */
 export interface DockProps {
@@ -16,37 +17,29 @@ export interface DockProps {
      */
     backdropMode?: DockBackdropMode;
     /**
-     * Never collapse — render permanently expanded; the single opt-OUT of the
+     * Never collapse: render permanently expanded, the single opt-out of the
      * collapse↔expand machinery. Default `false` (every dock is collapsible).
-     * AZ.W-DOCK-TAXONOMY — vertical docks are NO LONGER force-pinned here (a
-     * vertical dock morphs its height too; the prior `variant="rail"`
-     * always-expanded-by-construction is removed). A `layout="grid"` dock is
-     * `alwaysExpanded` BY CONTRACT (a 2D tile panel does not read as a collapsible
-     * pill). A vertical nav column that wants the static always-expanded look opts
-     * in via this prop. (A positive `collapsible` boolean was considered and
-     * rejected: Vue coerces an absent boolean prop to `false`, so a `collapsible`
-     * defaulting to `true` would need a `withDefaults` second default-path; the
-     * existing `alwaysExpanded` opt-out — which correctly defaults `false` — is the
-     * one knob, no Vue boolean-trap.)
+     * A vertical dock morphs its height too. A `layout="grid"` dock is
+     * always expanded by contract (a 2D tile panel does not read as a collapsible
+     * pill). A vertical navigation column can opt into the static expanded posture.
      */
     alwaysExpanded?: boolean;
     /**
      * Corner treatment.
      *   `"pill"`    — the stadium silhouette (default).
      *   `"rounded"` — a finite rounded radius (`--radius-xl`).
-     *   `"card"`    — the AW.W3b big-dock card shell: a finite concentric
+     *   `"card"`    — a finite concentric big-dock shell
      *                 radius (`--dock-card-radius`, default `--radius-3xl`)
      *                 ABOVE 2xl, below pill — does NOT collapse to a stadium.
      *                 Collapsed it returns to a pill; the pill↔card swap
-     *                 morphs on the `--dock-motion-resize` spring. AX.W56's
+     *                 morphs on the `--dock-motion-resize` spring. The
      *                 squircle policy applies `corner-shape:
      *                 var(--corner-shape-bigdock)` here under `@supports
      *                 (corner-shape: superellipse(2))` — the big-dock is the ONE
      *                 surface where the superellipse reads (cards/pills stay
      *                 round); the border-radius arc is the cross-engine contract.
      *
-     * Paints on BOTH orientations (AZ.W-DOCK-TAXONOMY — `shape` is no longer
-     * variant-gated; a vertical dock reads `shape="rounded"` for the tool-palette
+     * Paints on both orientations: a vertical dock reads `shape="rounded"` for the tool-palette
      * look, a horizontal dock reads `shape="card"` for the big-dock shell).
      */
     shape?: "pill" | "rounded" | "card";
@@ -54,7 +47,7 @@ export interface DockProps {
      * Layout axis of the dock. `"horizontal"` (default) lays items out
      * left-to-right and animates `width`; `"vertical"` lays items out
      * top-to-bottom and animates `height`. This is the SINGLE layout axis — there
-     * is no `variant` second-way to express "vertical" (AZ.W-DOCK-TAXONOMY).
+     * is no `variant` second-way to express "vertical".
      */
     orientation?: "horizontal" | "vertical";
     /**
@@ -66,9 +59,7 @@ export interface DockProps {
      * Overflow strategy when the expanded content exceeds the dock's
      * axis cap (`--dock-max-inline-size` horizontally,
      * `--dock-max-block-size` vertically). The ONE knob governing every
-     * overflow behaviour (AT.W7-dock-a clean break — collapsed from the
-     * prior `wrap` boolean + `overflow` pair + `containerName` clip-lift,
-     * which all touched overflow divergently).
+     * overflow behavior.
      *   `"grow"`   — content grows to fit then overflows visibly past
      *                the cap (the default; nothing clips or scrolls).
      *   `"wrap"`   — expanded content wraps to multiple rows via CONTENT-DRIVEN
@@ -84,8 +75,7 @@ export interface DockProps {
      *                `.dock-overflow-wrap` class is not emitted for a vertical
      *                orientation.
      *
-     * BG.W-DOCK-CAP-SCROLL-FADE — the `"scroll"` opt-in RETIRED (clean break,
-     * no alias). A capped axis is INTRINSICALLY a scroll axis: a horizontal
+     * A capped axis is intrinsically a scroll axis: a horizontal
      * dock's inline axis reads `.dock-scroll-x` unconditionally (the CSS
      * `overflow-x: auto` scrolls ONLY when the row exceeds
      * `--dock-max-inline-size`; under the cap nothing scrolls), and a vertical
@@ -99,27 +89,45 @@ export interface DockProps {
      * subject (`container-type: inline-size; container-name: <value>`) so
      * descendants can query the named container via `@container <value>
      * (...)` rules. ORTHOGONAL to the `overflow` clip: opting into a
-     * container subject does NOT silently change the dock's clip shell
-     * (AT.W7-dock-a — the prior clip-lift was folded out; use
-     * `overflow="wrap"` to allow multi-line content).
+     * container subject does not change the dock's clip shell; use
+     * `overflow="wrap"` for multi-line content.
      *
-     * ALWAYS-EXPANDED-ONLY (AY.W-DOCK2 §F1): `container-type: inline-size`
+     * Always-expanded only: `container-type: inline-size`
      * clamps the box to its contained intrinsic size, so on a COLLAPSIBLE
      * dock the collapse↔expand FLIP measures collapsed→collapsed and the
      * morph FREEZES. A collapsible dock that needs deterministic targeting
      * uses a plain `data-testid` (no layout side-effect).
      */
     containerName?: string;
+    /**
+     * Opt this dock into a consumer-owned shared-element View Transition. Leave
+     * unset for ordinary route transitions so the dock remains in the root
+     * snapshot rather than becoming a separate backdrop-filter snapshot.
+     */
+    viewTransitionName?: string;
     /**
      * Idle-collapse delay in ms (default 2000). Inert on an always-expanded dock.
      */
     collapseDelay?: number;
     /**
      * Start in the collapsed state (default true). Applies on BOTH orientations
-     * (AZ.W-DOCK-TAXONOMY — a vertical dock starts collapsed and morphs its block
-     * axis open too). Inert on an always-expanded dock.
+     * and a vertical dock morphs its block axis open too. Inert on an always-expanded dock.
      */
     startCollapsed?: boolean;
+    /**
+     * Posture ownership on a COLLAPSIBLE dock.
+     *   `"auto"`   (default) — the built-in FSM owns posture.
+     *   `"manual"` — the consumer owns posture. Every internal environmental writer
+     *                (hover, focus, idle timer, outside-click, collapsed-tap, touch)
+     *                is suppressed at BOTH poles; only `expand()`/`collapse()` write.
+     *                Mount pole from `startCollapsed`. Read posture via `expanded`.
+     *                a11y: the consumer MUST author a focusable disclosure in a
+     *                never-inert slot (`#persistent`/`#collapsed`) — glass does not
+     *                auto-expand on focus in manual and provides no fallback.
+     * Resolved to `"auto"` on an always-expanded dock (that pole is force-pinned;
+     * interaction is meaningless there — no dead combination reaches the FSM).
+     */
+    interaction?: DockInteraction;
     /**
      * In-cap arrangement. `"linear"` (default) lays the active layer out as a
      * linear row/column. `"grid"` makes the active layer a self-wrapping tile
@@ -135,11 +143,9 @@ export interface DockProps {
      */
     layout?: "linear" | "grid";
     /**
-     * AZ.W-ADAPTIVE-AUTO Arm 2 (H3 arm a) — the sampled-luminance observer that
-     * DYNAMICALLY refines the W55 declarative bright-bucket darken (the iOS-27
-     * "darken dynamically" register). Default `true` (default-ON for the dock — the
-     * surface most often over a live/bright backdrop). It REFINES the floor (the
-     * unconditional self-engage + the declarative bucket stay the guarantee); a
+     * The sampled-luminance observer dynamically refines the declarative bright-
+     * backdrop tint. Default `true` because docks commonly sit over live fields.
+     * It refines the material floor; a
      * dark-substrate consumer opts out with `:auto-luminance="false"` (or
      * `--glass-tint-strength: 0%` on the dock). The observer is rAF-throttled ≤ 4 Hz,
      * IntersectionObserver-gated, and parks under `prefers-reduced-motion: reduce`.
@@ -148,19 +154,15 @@ export interface DockProps {
     /**
      * The KNOWN background-layer canvas the dock floats over (an aurora/blob
      * `<canvas>`) — an element, a getter, or a CSS selector. When present, the
-     * observer downsamples it under the dock's box each settle (the ANIMATED-backdrop
+     * observer downsamples it under the dock's box after settling (the animated-backdrop
      * case); absent, it stack-walks the painted page background (the static case).
      */
     backgroundCanvas?: HTMLCanvasElement | (() => HTMLCanvasElement | null) | string | null;
     /**
-     * BC.W-DOCK-SEARCH — the dock-as-native-dynamic-search-bar MODE (additive,
-     * default `false`). When true the dock stamps `[data-search]` (the CSS hook the
-     * `dock/search.css` active-field tint seam + the `.glass-menu-row` result rows
-     * target) and renders the `#search` slot INSIDE the existing morph aperture — the
-     * consumer composes `useDockSearch` (the gesture/shrink/dropdown seam) and slots
-     * its search field + fuzzy dropdown there. The pill→field morph is the dock's OWN
-     * `--dock-morph-t` glide (box-inviolate — no second engine). A non-search dock is
-     * byte-identical to HEAD (the slot + the data-attr are present only when authored).
+     * Native dynamic-search mode. Default `false`. When enabled, the dock stamps
+     * `[data-search]` and renders `#search` inside the existing morph aperture. The
+     * consumer composes `useDockSearch` and supplies its field and result menu. The
+     * dock's `--dock-morph-t` remains the sole pill-to-field motion scalar.
      */
     search?: boolean;
 }
@@ -169,6 +171,7 @@ export interface DockShellProps {
     containerStyle: ComputedRef<Record<string, string> | undefined>;
     collapseDelay: ComputedRef<number>;
     startCollapsed: ComputedRef<boolean>;
+    interaction: ComputedRef<DockInteraction>;
     layoutValue: ComputedRef<"linear" | "grid">;
     shape: ComputedRef<"pill" | "rounded" | "card">;
     orientation: ComputedRef<"horizontal" | "vertical">;

package/dist/components/dock/composables/useDockSpring.d.ts

@@ -1,16 +1,10 @@
 /**
- * BG.W-DOCK-ENGINE-UNIFY — the ONE `SpringProgress` owner for the dock band.
+ * the ONE `SpringProgress` owner for the dock band.
  *
- * The dock's collapse↔expand morph (`dockMorphContext`), the V↔H orientation
- * morph (`useDockOrientationMorph`), and the fission detach (`useDockFission`)
- * each hand-rolled their OWN `new SpringProgress` on the SAME `DOCK_SPRING` clock
- * (the demo-only `useDockItemDrag` fling — a fourth copy — retired at
- * BI.W-DOCK-FOLD, counted by W-DOCK-SPRING-UNIFY SU1) — copies of the
- * identical iOS interruptible-physics dance (create-carrying-prior-velocity →
- * play the glide writing the scalar → self-dispose on settle → PRM-jump). This
- * factory owns that dance ONCE. A consumer supplies the `(response, ζ)` pair +
- * its per-frame writer; the spring construction, the velocity-continuous
- * re-base, and the teardown live here — the sole `new SpringProgress` site.
+ * The outer dock morph and controlled face crossfade share this one spring
+ * factory instead of duplicating the interruptible-physics lifecycle. A consumer
+ * supplies the `(response, ζ)` pair and per-frame writer; construction, velocity-
+ * continuous re-base, and teardown live here — the sole `new SpringProgress` site.
  *
  * `SpringProgress` owns its own rAF via `.play(onFrame)` and carries no static
  * value.js edge, so this leaf never imports `AnimationGroup`/`./engine`. The
@@ -37,6 +31,8 @@ export interface DockSpringPlayOptions {
      * `|velocity|`). Called once per frame while the glide runs.
      */
     onFrame: (value: number, velocity: number) => void;
+    /** Coordinate transform applied when carrying a live episode's velocity. */
+    inheritVelocityScale?: number;
     /** Fired ONCE on settle, immediately BEFORE the self-dispose. */
     onSettle?: () => void;
 }

package/dist/components/dock/composables/useDockState.d.ts

@@ -1,4 +1,5 @@
 import type { ComputedRef, Ref } from "vue";
+import type { DockInteraction } from "./useDockShellProps";
 export interface UseDockStateOptions {
     /** Delay before auto-collapse after mouse leaves (ms) */
     collapseDelay?: number;
@@ -6,6 +7,15 @@ export interface UseDockStateOptions {
     rootEl: Ref<HTMLElement | null>;
     /** Disable collapse behavior and keep the dock expanded. */
     alwaysExpanded?: Ref<boolean> | boolean;
+    /**
+     * Posture ownership. `"auto"` (default) runs the built-in FSM; `"manual"`
+     * suppresses every environmental writer (hover, focus, idle timer,
+     * outside-click, collapsed-tap) at BOTH poles, leaving only `expand()` /
+     * `collapse()` operative — the consumer owns posture.
+     */
+    interaction?: Ref<DockInteraction> | DockInteraction;
+    /** Mount-only posture for a collapsible dock. */
+    initialExpanded?: boolean;
     /** Ref that suppresses click-away during an active dock animation. */
     isTransitioning?: Ref<boolean>;
     /** Owner id for dock-owned teleported targets. */
@@ -15,9 +25,8 @@ export interface UseDockStateOptions {
 }
 export type DockState = "collapsed" | "hover" | "pinned";
 /**
- * Canonical return shape for `useDockState`. Named per the O.W6 Lane A
- * `UseClipboardReturn` precedent + P.W2 Lane D (Pγ.3 "useDockState inline
- * return"); freezes today's surface so consumers wrapping `<GlassDock>` (or
+ * Canonical return shape for `useDockState`, paralleling other named composable return
+ * types. It lets consumers wrapping `<GlassDock>` (or
  * authoring a custom dock chassis) can type the composable handle from `/api`
  * or the `/dock` subpath without reaching for `ReturnType<typeof useDockState>`.
  */

package/dist/components/dock/composables/useDockTouchGate.d.ts

@@ -1,35 +1,26 @@
 import type { Ref } from "vue";
 /**
- * BG.W-DOCK-DECOMPOSE — the dock touch-gate wiring, carved off the `GlassDock.vue`
- * god-SFC (the F6.5 one-writer-per-concern seam). It owns the `useTouchGate`
- * instance + the tap/scroll discrimination handlers + the collapse-on-deactivate
- * watch — ONE structural concern (the collapsed-pill tap-to-expand gesture), NEVER
- * a morph-scalar writer (`--dock-morph-t`/`--dock-morph-v` stay the orchestrator's).
+ * Own collapsed-pill tap/scroll discrimination and collapse-on-deactivate state.
+ * Morph scalars remain owned by the Dock orchestrator.
  *
- * AT.W6-dock-b — shape B′ touch-gate. The gate's job is to DISTINGUISH a tap from a
- * vertical scroll on the floating collapsed pill (the 150ms pending window + the
- * >10px scroll-check inside `useTouchGate`), NOT to SWALLOW the tap. It therefore
- * does NOT `preventDefault()`/`stopPropagation()` the activating `touchstart`/
- * `touchend`: the browser's native tap→click compatibility event is allowed to flow
- * to the tapped control, so a SINGLE tap on a collapsed dock control BOTH expands the
- * dock AND activates that control (via the native click) — the iOS Now-Playing
- * mini-bar single-tap-play contract. No `elementFromPoint`, no synthetic dispatch. A
- * scroll gesture cancels the pending tap inside the gate and never emits a tap-click,
- * so vertical scrolling on the pill stays browser-owned. (Swallowing the tap was the
- * root cause of the double-tap field defect — a prevented touch sequence emits no
- * compatibility click, so the control under the finger fired nothing.)
- *
- * AZ.W-DOCK-TAXONOMY — the gate applies to ANY collapsible dock, not just the
- * horizontal one (a vertical dock now collapses too), so it must distinguish a tap
- * from a vertical scroll on its pill as well.
+ * The gate distinguishes a tap from vertical scrolling without preventing the
+ * browser's compatibility click. A single tap can expand the Dock and activate its
+ * control; a scroll cancels the pending tap. No hit-test lookup or synthetic
+ * dispatch is used. The same behavior applies to both orientations.
  */
 export interface UseDockTouchGateOptions {
     /** The dock's auto-collapse delay (ms) — the gate's deactivation timer. */
     collapseDelay: number;
     /** The dock body root — the tap discrimination anchors on it. */
     rootEl: Ref<HTMLElement | null>;
-    /** True when the dock cannot collapse (the gate no-ops — no tap-to-expand). */
-    alwaysExpanded: Readonly<Ref<boolean>>;
+    /**
+     * True when every environmental writer is suppressed — an always-expanded dock
+     * (force-pinned) OR a manual dock (the consumer owns posture). The gate no-ops:
+     * no tap-to-expand, no collapse-on-deactivate. Without folding `manual` in here
+     * the gate would leak a `collapse()` on deactivate (in manual `isPinned` is
+     * false and `alwaysExpanded` is false, so the collapse guard would fire).
+     */
+    quiet: Readonly<Ref<boolean>>;
     /** The painted expand state (`alwaysExpanded || expanded`). */
     visualExpanded: Readonly<Ref<boolean>>;
     /** The raw expand ref (the collapse-on-deactivate guard reads it). */