@mkbabb/glass-ui 4.2.0 → 5.0.0

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

@@ -0,0 +1,89 @@
+import type { Ref } from "vue";
+/**
+ * AX.W02 — ONE morph orchestrator per dock. The dock is a single morph stack
+ * whose active "layer" is `(expandedState × activePane)`: the outer
+ * collapse↔expand swap and the inner `<DockLayerGroup>` pane swaps are
+ * transitions in the SAME group — ONE spring, ONE scalar (`--dock-morph-t`),
+ * ONE clock. No second engine.
+ *
+ * BD.W-DOCK-CORE (the size re-invent) — the orchestrator no longer MEASURES a
+ * per-swap `from/to` span. The visible size is a ratio-free convex blend of two
+ * endpoints measured ONCE per content change (`useDockExpandedSize` writes
+ * `--dock-expanded-px`/`--dock-collapsed-px`; layers.css blends them on
+ * `--dock-morph-t`). So this driver shrinks to its essence: on a layer swap it
+ * arms `[data-morphing]`, swaps the crossfade classes (the a11y-006 3-state
+ * hit-test contract, LOAD-BEARING — KEPT verbatim), and runs ONE `SpringProgress`
+ * gliding `--dock-morph-t` 0→1; on settle it clears the morph state. A re-toggle
+ * mid-flight re-bases the live solver onto a fresh spring CARRYING the prior
+ * velocity (the iOS interruptible-physics continuity).
+ *
+ * LIGHT-surface only: the `useDockSpring` factory's `SpringProgress` owns its own
+ * rAF via `.play(onFrame)` and carries no static value.js edge — the factory never
+ * imports `AnimationGroup` / `./engine`.
+ *
+ * `DOCK_SPRING` is byte-fenced — it lives in `../constants`.
+ */
+export interface DockMorphGroupRegistration {
+    /** The container element owning this group's grid-stacked panes. */
+    containerEl: Ref<HTMLElement | null>;
+    /** The group's currently-active pane id (its `v-model:active`). */
+    activeLayer: Ref<string>;
+    /** Layout axis of the group; matches the group's `orientation`. */
+    axis: Ref<"horizontal" | "vertical">;
+}
+export interface DockMorphGroupHandle {
+    /** The active pane id post-swap (the orchestrator mutates it). */
+    currentLayer: Readonly<Ref<string>>;
+    /** The pane id currently fading out, or null. */
+    leavingLayer: Readonly<Ref<string | null>>;
+    /** Detach this group from the orchestrator (on the group's unmount). */
+    release(): void;
+}
+/**
+ * The provided morph seam. A nested `<DockLayerGroup>` injects this and DEFERS
+ * its pane-swap morph to the dock's single orchestrator via `registerGroup`.
+ */
+export interface DockMorphContext {
+    registerGroup(group: DockMorphGroupRegistration): DockMorphGroupHandle;
+}
+export declare const DOCK_MORPH_KEY: import("vue").InjectionKey<DockMorphContext>;
+export declare function provideDockMorphContext(context: DockMorphContext): void;
+/**
+ * Befitting-silent — returns `null` for a `<DockLayerGroup>` rendered outside a
+ * `<GlassDock>` (the standalone self-orchestrate path).
+ */
+export declare const useOptionalDockMorphContext: () => DockMorphContext | null;
+export interface UseDockMorphOrchestratorOptions {
+    /** The `.glass-dock` root that carries the shared scalar + clip aperture. */
+    rootEl: Ref<HTMLElement | null>;
+    /** The outer collapse↔expand container (`.dock-layers`). */
+    outerEl: Ref<HTMLElement | null>;
+    /** The outer active "layer" id — `(expandedState)` projected to a string. */
+    outerActiveLayer: Ref<string>;
+    /** The outer pair morphs the inline axis (a horizontal dock). */
+    outerAxis: Ref<"horizontal" | "vertical">;
+    /**
+     * BG.NF.1 W-FALLBACK-EXCISE — a NOTIFY seam (NOT a busy-flag shadow): the
+     * orchestrator calls `onMorphActiveChange(true)` when the outer morph spring ARMS
+     * (alongside `setAttribute("data-morphing")`) and `(false)` when it SETTLES
+     * (alongside `removeAttribute`), so a consumer (GlassDock) can drive its OWN
+     * `isTransitioning` off the morph's OWN spring settle — the CSS-transition-era
+     * wrong-clock settle timer + dead `@transitionend` resolver are excised. The
+     * orchestrator holds NO parallel boolean (the single busy signal stays the
+     * `[data-morphing]` attr + the factory's `.live` — proof:dock-engine-unify U3).
+     */
+    onMorphActiveChange?: (active: boolean) => void;
+}
+export interface UseDockMorphOrchestratorReturn {
+    /** Provide-able context: a nested `<DockLayerGroup>` registers through it. */
+    context: DockMorphContext;
+    /** The outer pair's post-swap active layer id (call-site parity). */
+    outerCurrentLayer: Readonly<Ref<string>>;
+}
+/**
+ * The ONE morph engine for a dock instance. Drives a single `useDockSpring` handle
+ * that glides the one `--dock-morph-t` scalar 0→1 on a layer swap; the size is a
+ * ratio-free blend of the measure-ONCE endpoints (layers.css). Crossfade classes
+ * (the 3-state a11y hit-test contract) swap on the swap; the spring is the clock.
+ */
+export declare function useDockMorphOrchestrator(options: UseDockMorphOrchestratorOptions): UseDockMorphOrchestratorReturn;

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

@@ -0,0 +1,10 @@
+export { useDockState } from "./useDockState";
+export type { UseDockStateOptions, UseDockStateReturn, DockState } from "./useDockState";
+export { useDockSearch } from "./useDockSearch";
+export type { UseDockSearchOptions, UseDockSearchReturn } from "./useDockSearch";
+export { useDockHold } from "./useDockHold";
+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";

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

@@ -0,0 +1,24 @@
+import { type Ref } from "vue";
+export interface UseDockFisheyeOptions {
+    /** Arm gate (default always). A parked-until-DEVICE consumer passes `() => false`. */
+    enabled?: () => boolean;
+}
+export interface UseDockFisheyeReturn {
+    /** Re-write each item's layout-time `--x` (call after a content/layout change). */
+    remeasure: () => void;
+}
+/**
+ * useDockFisheye — the ONE rAF-coalesced pointermove `--dock-px` writer for the fits-branch
+ * pure-CSS Gaussian fisheye (BI.W-DOCK-OVERFLOW, G4). It writes exactly ONE per-frame
+ * scalar — `--dock-px` (the pointer's inline position relative to the scroll port, a
+ * unitless number) on the dock; each item carries a LAYOUT-TIME `--x` (its center, unitless,
+ * (re)written on the RO — NOT per frame). The pure-CSS Gaussian in fisheye.css does the
+ * per-item scale. The JS owns NO scale math and NO layout write — it writes two custom
+ * properties and adds the `.dock-fisheye-item` marker class.
+ *
+ * The writer is the ENHANCEMENT layer over the universal native-scroll floor (overflow.css):
+ * the CSS gates the scale on `:not([data-dock-overflow])` + `(hover: hover) and (pointer:
+ * fine)` + PRM-off, so a scrollable / coarse / reduced-motion dock paints flat regardless of
+ * this writer. G9/O5 — this is a `pointermove` listener, NEVER a `scroll` listener.
+ */
+export declare function useDockFisheye(dockEl: Ref<HTMLElement | null>, options?: UseDockFisheyeOptions): UseDockFisheyeReturn;

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

@@ -0,0 +1,22 @@
+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
+ * when the active full layer's over-cap inline content exceeds its clamped port width.
+ * 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).
+ *
+ * G9 / O5 — ZERO SCROLL LISTENER. The measure is RESIZE- and CONTENT-driven (a
+ * `ResizeObserver` on the dock + the port, plus a `MutationObserver` on the port's
+ * content). It never listens to `scroll` — the traveling indicator (`useSelectionIndicator`)
+ * lives inside the scroll port and travels WITH scroll in content coordinates, needing no
+ * scroll listener; this fit measure adds none either.
+ *
+ * The scroll port is discovered from the dock root (`.dock-layer--full`) so the composable
+ * needs only the dock element — no extra template ref threads through GlassDock.
+ */
+export declare function useDockOverflowFit(dockEl: Ref<HTMLElement | null>): {
+    measure: () => void;
+};

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

@@ -0,0 +1,68 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+/** Which dock edge the popover fans from (the JS one-shot resolves the fixed coords). */
+export type DockPopoverSide = "top" | "bottom" | "left" | "right";
+/** How the popover aligns along the anchor's cross axis. */
+export type DockPopoverAlign = "start" | "center" | "end";
+export interface UseDockPopoverOptions {
+    /** The trigger DOM element (a dock control) — resolved lazily (it mounts post-setup). */
+    anchor: () => HTMLElement | null;
+    /** The `popover`-attributed surface element (a plain `<div popover>`). */
+    popover: Ref<HTMLElement | null>;
+    /** The dock edge the surface fans from. Default `"top"`. */
+    side?: MaybeRefOrGetter<DockPopoverSide>;
+    /** The cross-axis alignment. Default `"center"`. */
+    align?: MaybeRefOrGetter<DockPopoverAlign>;
+    /** The gap (px) between the anchor edge and the surface. Default 8. */
+    gap?: number;
+    /** The min gap (px) the surface keeps from the viewport edge on clamp. Default 8. */
+    viewportMargin?: number;
+    /** The hover-open intent dwell (ms) — a sweep-past enter is canceled by a chasing
+     *  leave inside it. Default `HOVER_INTENT_MS`. */
+    hoverIntentMs?: number;
+    /** The hover-close grace (ms) — bridges the anchor→surface pointer gap so the fan does
+     *  not flash shut mid-cross. Default 120. */
+    hoverGraceMs?: number;
+}
+export interface UseDockPopoverReturn {
+    /** Reactive open state (a mirror of the top-layer show — bind styling to it). */
+    open: Ref<boolean>;
+    /** Show the popover (top-layer promote + the JS one-shot place). */
+    show: () => void;
+    /** Hide the popover (+ return focus to the anchor if focus was inside — Esc/blur). */
+    hide: () => void;
+    /** Toggle (the click-invoker path). */
+    toggle: () => void;
+    /** The JS one-shot placement — `getBoundingClientRect` on the anchor, viewport-clamped.
+     *  Re-run on resize/scroll while open. The SAF-1 fence lives here: rect math ONLY, never
+     *  a native `anchor()` read. */
+    place: () => void;
+    /** Pointer entered the anchor → start the intent dwell. */
+    onAnchorEnter: () => void;
+    /** Pointer left the anchor → schedule a graced hide. */
+    onAnchorLeave: () => void;
+    /** Pointer entered the surface → cancel the graced hide (the cross bridged). */
+    onPopoverEnter: () => void;
+    /** Pointer left the surface → schedule a graced hide. */
+    onPopoverLeave: () => void;
+    /** Focus entered the anchor → open immediately (keyboard). */
+    onFocusIn: () => void;
+    /** Focus left the anchor+surface subtree → hide (focus stays while traversing members). */
+    onFocusOut: (event: FocusEvent) => void;
+}
+/**
+ * Wire a dock-anchored top-layer popover: the native `popover` show/hide, the JS one-shot
+ * `getBoundingClientRect` placement (viewport-clamped), the hover-intent × light-dismiss ×
+ * focus-return interop. NO native anchor positioning (the SAF-1 fence — `anchor()` BANKED).
+ *
+ * @example
+ * ```ts
+ * const fanEl = useTemplateRef<HTMLElement>("fanEl");
+ * const stackRoot = useTemplateRef<HTMLElement>("stackRoot");
+ * const pop = useDockPopover({
+ *   anchor: () => stackRoot.value?.querySelector<HTMLElement>(".dock-stack-core") ?? null,
+ *   popover: fanEl,
+ *   side: () => (orientation.value === "vertical" ? "right" : "top"),
+ * });
+ * ```
+ */
+export declare function useDockPopover(options: UseDockPopoverOptions): UseDockPopoverReturn;

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

@@ -0,0 +1,85 @@
+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";
+export interface UseDockSearchOptions<T extends SearchableItem = SearchableItem> {
+    /** Composes the existing dock state machine (no fork) — `armSearch`/`disarmSearch`
+        ride its `onClickCollapsed`/`keepOpen`/`release`. */
+    dockState: UseDockStateReturn;
+    /**
+     * The search items (sync) — a static array or a getter. Drives the composed
+     * `useFuzzySearch` matcher. MUTUALLY EXCLUSIVE with `onSearch` (sync XOR async).
+     */
+    items?: T[] | (() => T[]);
+    /**
+     * The pluggable async data source (the words network case). The consumer owns the
+     * abort/network race-guard; the dock owns the gesture/shrink/dropdown. When set, the
+     * dock awaits the source on each query, cancelling the prior request's
+     * `AbortController` (the generic thin abort). MUTUALLY EXCLUSIVE with `items`.
+     */
+    onSearch?: (query: string, signal: AbortSignal) => Promise<T[]>;
+    /** Debounce delay in ms forwarded to the matcher / the async source. Default 120. */
+    debounceMs?: number;
+    /** Maximum results forwarded to the matcher. Default 30. */
+    maxResults?: number;
+    /**
+     * Opt-in collapse-on-scroll — composes `useScrollChrome` (persistent-default, the
+     * iOS-27 lesson). DEFAULT FALSE: the dock is PERSISTENT; the morph fires on user
+     * intent (tap/focus), never a passive scroll. When true the chrome shrinks+fades on
+     * scroll-down + expands on scroll-up (the transform-only `--chrome-collapse-t` ramp).
+     */
+    collapseOnScroll?: boolean;
+    /** The scroll source for the optional collapse-on-scroll (a container or window). */
+    scrollContainer?: MaybeRefOrGetter<HTMLElement | Window | null>;
+    /** 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).
+     * 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.
+     */
+    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.
+     */
+    scrollTo?: (id: string) => void;
+}
+export interface UseDockSearchReturn<T extends SearchableItem = SearchableItem> {
+    /** The composed `useFuzzySearch` handle (query/results/selectedIndex/onKeydown/…). */
+    fuzzy: FuzzySearchState<T>;
+    /** The ghost-text top-match completion (the unmatched suffix of `results[0].label`). */
+    autocompleteText: Ref<string>;
+    /** The optional collapse-on-scroll machine (null when `collapseOnScroll` is false). */
+    scrollChrome: UseScrollChromeReturn | null;
+    /** Tap/focus → expand + hold (composes `onClickCollapsed` + `keepOpen`). */
+    armSearch: () => void;
+    /** Close → release the hold (composes `release`) + close the fuzzy surface. */
+    disarmSearch: () => void;
+    /** Tab/Space/ArrowRight → fill the ghost-text into the query. */
+    acceptAutocomplete: () => void;
+    /** True while the search field is the armed/morphed surface. */
+    isSearchArmed: Ref<boolean>;
+}
+/**
+ * The dock-search seam — composes `useDockState` + `useFuzzySearch` (+ optional
+ * `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
+ * 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`).
+ *
+ * @example
+ * ```ts
+ * const dockState = useDockState({ rootEl });
+ * const search = useDockSearch({ dockState, items: () => sections.value });
+ * // armSearch() on tap → the pill morphs into the field; type → fuzzy dropdown ranks.
+ * ```
+ */
+export declare function useDockSearch<T extends SearchableItem = SearchableItem>(options: UseDockSearchOptions<T>): UseDockSearchReturn<T>;

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

@@ -0,0 +1,178 @@
+import { type ComputedRef } from "vue";
+export type DockSize = "sm" | "md" | "lg" | "xl";
+/**
+ * The ONE GlassDock prop shape (AZ.W-DOCK-TAXONOMY — the discriminated union is
+ * gone). 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 {
+    fitContent?: boolean;
+    position?: "fixed" | "inline" | "sticky";
+    /**
+     * 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.)
+     */
+    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
+     *                 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
+     *                 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
+     * look, a horizontal dock reads `shape="card"` for the big-dock shell).
+     */
+    shape?: "pill" | "rounded" | "card";
+    /**
+     * 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).
+     */
+    orientation?: "horizontal" | "vertical";
+    /**
+     * Size controls dock padding, gaps, layer height, and inherited
+     * dock control sizing. Root CSS variables can override each rung.
+     */
+    size?: DockSize;
+    /**
+     * 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).
+     *   `"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
+     *                intrinsic flex-wrap (the `.dock-overflow-wrap` recipe). The
+     *                dock shrink-wraps to content and caps that intrinsic width
+     *                at `max-inline-size: var(--dock-max-inline-size)`, so the row
+     *                reflows to N rows EXACTLY when its intrinsic width exceeds
+     *                the cap — at ANY viewport width — and collapses to one row
+     *                when it fits (no viewport breakpoint). The wrapped multi-row silhouette lifts
+     *                onto the card/floating shadow tier as the dock expands.
+     *                HORIZONTAL-ONLY: a vertical dock grows-to-fit + clamps via
+     *                `--dock-max-block-size` (its own overflow story), so the
+     *                `.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
+     * 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
+     * rail's block axis scrolls via the unconditional cap-derived shell rule
+     * (`--dock-max-block-size` is the sole knob). No prop, no unreachable
+     * controls.
+     */
+    overflow?: "grow" | "wrap";
+    /**
+     * When set, the dock root establishes an inline-size container query
+     * 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).
+     *
+     * ALWAYS-EXPANDED-ONLY (AY.W-DOCK2 §F1): `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;
+    /**
+     * 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.
+     */
+    startCollapsed?: boolean;
+    /**
+     * In-cap arrangement. `"linear"` (default) lays the active layer out as a
+     * linear row/column. `"grid"` makes the active layer a self-wrapping tile
+     * grid (Launchpad/Stage-Manager track symmetry — `auto-fill` columns of
+     * `--dock-tile-min`). ORTHOGONAL to `overflow` (the OVER-cap strategy):
+     * `layout` is the IN-cap arrangement.
+     *
+     * Hard contract: a `layout="grid"` dock is `alwaysExpanded` (a 2D panel
+     * does not read as a collapsible pill, and no width morph means no
+     * per-frame grid reflow). The canonical pairing is
+     * `shape="card" layout="grid"` (the props stay independent — no
+     * auto-implication of `shape`).
+     */
+    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
+     * 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`.
+     */
+    autoLuminance?: boolean;
+    /**
+     * 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
+     * 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).
+     */
+    search?: boolean;
+}
+/** The resolved shell-prop computeds the GlassDock SFC binds. */
+export interface DockShellProps {
+    containerStyle: ComputedRef<Record<string, string> | undefined>;
+    collapseDelay: ComputedRef<number>;
+    startCollapsed: ComputedRef<boolean>;
+    layoutValue: ComputedRef<"linear" | "grid">;
+    shape: ComputedRef<"pill" | "rounded" | "card">;
+    orientation: ComputedRef<"horizontal" | "vertical">;
+    size: ComputedRef<DockSize>;
+    scrollClass: ComputedRef<string | null>;
+    alwaysExpanded: ComputedRef<boolean>;
+    fitContent: ComputedRef<boolean>;
+}
+/**
+ * Derive the dock's resolved shell props off the raw `props`. The defaults are
+ * applied at each read site via `?? default` (every shared default has exactly one
+ * resolution point — the one-path precept).
+ */
+export declare function useDockShellProps(props: DockProps): DockShellProps;

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

@@ -0,0 +1,71 @@
+/**
+ * BG.W-DOCK-ENGINE-UNIFY — 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.
+ *
+ * `SpringProgress` owns its own rAF via `.play(onFrame)` and carries no static
+ * value.js edge, so this leaf never imports `AnimationGroup`/`./engine`. The
+ * dock morph is ALWAYS PRM-aware: the one spring is armed with
+ * `respectReducedMotion: true`, which JUMPS the scalar 0→target in one frame
+ * under `prefers-reduced-motion: reduce` (no in-between motion frames — no
+ * blur/sliver). `DOCK_SPRING` stays byte-fenced in `../constants`; the caller
+ * passes its `.response`/`.dampingFraction` through.
+ */
+export interface DockSpringConfig {
+    /**
+     * iOS `response` — pass `DOCK_SPRING.response` (the byte-fenced dock clock,
+     * `springPreset("dock")`). Never a fresh literal — the spring register is
+     * single-sourced.
+     */
+    response: number;
+    /** iOS `dampingFraction` — pass `DOCK_SPRING.dampingFraction`. */
+    dampingFraction: number;
+}
+export interface DockSpringPlayOptions {
+    /**
+     * The per-frame writer. `value` is the spring position; `velocity` is its
+     * live analytic velocity (the F-ARM-1 weight channel — a squish reads
+     * `|velocity|`). Called once per frame while the glide runs.
+     */
+    onFrame: (value: number, velocity: number) => void;
+    /** Fired ONCE on settle, immediately BEFORE the self-dispose. */
+    onSettle?: () => void;
+}
+/**
+ * A single-spring handle. Every dock surface that morphs on the DOCK register
+ * drives one of these — the factory that mints it is the band's sole
+ * `new SpringProgress` site.
+ */
+export interface DockSpring {
+    /**
+     * Play a fresh episode `from`→`to`. A still-live prior episode is RE-BASED:
+     * the new spring starts at `from` CARRYING the prior spring's velocity (the
+     * iOS interruptible-physics continuity), targets `to`, and glides on the
+     * DOCK clock writing `onFrame(value, velocity)` per frame. Self-disposes on
+     * settle (after `onSettle`), so an at-rest dock parks ZERO springs.
+     */
+    playTo(from: number, to: number, options: DockSpringPlayOptions): void;
+    /**
+     * Re-target the LIVE spring to `to` from its CURRENT `(value, velocity)`
+     * without recreating the loop (a mid-flight toggle — the interruptible
+     * re-seat `SpringProgress.set target` performs continuously). A no-op when
+     * no spring is live; call `playTo` to (re)start a parked handle.
+     */
+    retarget(to: number): void;
+    /** True while a spring is running and not yet settled. */
+    readonly live: boolean;
+    /** The live analytic velocity (0 when no spring is live). */
+    readonly velocity: number;
+    /** Tear down any running spring (idempotent). */
+    dispose(): void;
+}
+export declare function useDockSpring(config: DockSpringConfig): DockSpring;

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

@@ -0,0 +1,51 @@
+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).
+ *
+ * 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.
+ */
+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>>;
+    /** The painted expand state (`alwaysExpanded || expanded`). */
+    visualExpanded: Readonly<Ref<boolean>>;
+    /** The raw expand ref (the collapse-on-deactivate guard reads it). */
+    expanded: Ref<boolean>;
+    /** True while a hold token keeps the dock open (suppresses the deactivate collapse). */
+    isPinned: Readonly<Ref<boolean>>;
+    /** Expand the dock (fired on a resolved tap). */
+    expand: () => void;
+    /** Collapse the dock (fired when the gate deactivates with no hold). */
+    collapse: () => void;
+}
+export interface UseDockTouchGateReturn {
+    onTouchStart(event: TouchEvent): void;
+    onTouchMove(event: TouchEvent): void;
+    onTouchEnd(): void;
+    /** Force the gate to rest (a collapse flip clears any pending tap). */
+    deactivate(): void;
+}
+export declare function useDockTouchGate(options: UseDockTouchGateOptions): UseDockTouchGateReturn;