@mkbabb/glass-ui 4.1.0 → 5.0.0

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;

package/dist/components/dock/constants.d.ts

@@ -0,0 +1,107 @@
+import type { Component } from "vue";
+/**
+ * BC.W-DOCK-STACK-RAIL — one `<DockStack>` member descriptor: a stack member that fans
+ * OUT of the macOS hover-expand stack (id + label + glyph + optional select handler).
+ * A `<script setup>` SFC cannot re-export a named type through the `export { default }`
+ * barrel, so the descriptor lives here (the colocated types home) and the SFC imports
+ * it; the barrel re-exports it for consumers typing their `items` array. This is the
+ * stack's MEMBER, not a facet chip — the divider-carousel `DockRailItem` is RETIRED
+ * (clean break, no alias).
+ */
+export interface DockStackItem {
+    /** Stable identifier — the `v-for` key + the selected-member id. */
+    id: string;
+    /** The member's accessible label (the `aria-label` + tooltip). */
+    label: string;
+    /** The member glyph (a `@lucide/vue` icon or any component). */
+    icon?: Component;
+    /** Optional per-member select handler (fired alongside the model write). */
+    onSelect?: () => void;
+    /**
+     * BE.W-DOCK-RAIL-REALIZE — the per-FACET accent hue (the `mode="facets"` context
+     * carousel only — IGNORED by the macOS `mode="stack"` glyph fan). A complete
+     * `<color>` (a consumer DATA/context hue) written to the chip's `--glass-accent`
+     * (the BB.W-GLASS-ACCENT per-instance chromatic-rim axis, `rim.css`/`material.css`),
+     * so each context facet carries its OWN rim+glint hue — the AZ context-carousel
+     * identity. Unset ⇒ the neutral warm-cream rim (the `--glass-accent: transparent`
+     * no-op floor). NOT a plate-background fill (the accent rides the THIN rim/glint;
+     * presets-in-consumers — no consumer hue enters a library token).
+     */
+    accent?: string;
+}
+/**
+ * BA.W-DOCK-SECTIONS — the three named zone kinds the declarative `<DockSection>`
+ * descriptor renders (the R8-9 "rail core + sections + nav" three-zone gestalt):
+ *   - `"rail-core"` — the leading home/brand region (the ℱ wordmark / category trigger).
+ *   - `"section"`   — a named, divider-demarcated group of controls; a section
+ *                     carrying `layers` composes the existing `DockLayerGroup`/`DockLayer`
+ *                     registry (NOT a parallel layer machine).
+ *   - `"nav"`       — the trailing nav arrows / utility group.
+ */
+export type DockSectionKind = "rail-core" | "section" | "nav";
+/**
+ * BA.W-DOCK-SECTIONS — one declarative section descriptor. A consumer passes
+ * `sections: readonly DockSectionDescriptor[]` to `<DockSection>` and the dock body
+ * renders the tripartite silhouette (rail-core | divided named sections | nav)
+ * demarcated by `<DockSeparator>` — the IG-A3 / R8-9 "abstract this into a re-usable
+ * component for layering" library gap. A `<script setup>` SFC cannot re-export a named
+ * type through its default barrel, so the descriptor lives here (the colocated types
+ * home, beside `DockRailItem`) and `DockSection.vue` imports it; the barrel re-exports
+ * it for consumers typing their `sections` array.
+ */
+export interface DockSectionDescriptor {
+    /** Which of the three zone kinds this descriptor renders. */
+    kind: DockSectionKind;
+    /** Stable identifier — the `v-for` key + the layer-context id for a `section`. */
+    id: string;
+    /** Optional accessible label for the grouped zone. */
+    label?: string;
+    /**
+     * For a `section` kind: the stack members this section carries. When present
+     * (length > 1) the members ride the dock's `#rail` stack (the macOS hover-expand
+     * stack, OUTSIDE the dock box — never re-inflating it). The descriptor names them;
+     * `<DockStack :items>` fans them out.
+     */
+    layers?: readonly DockStackItem[];
+}
+/**
+ * The ONE dock-morph spring authority — the iOS-26 interruptible-physics tuning the
+ * dock's single `SpringProgress` orchestrator (`dockMorphContext.ts`) AND the
+ * `useLayerTransition` engine both read. Co-located here so the `response`/`damping`
+ * pair is defined ONCE rather than duplicated at the top of each composable (the two
+ * prior copies were a DRY hazard — a re-tune had to touch both).
+ */
+export declare const DOCK_SPRING: {
+    readonly response: number;
+    readonly dampingFraction: number;
+};
+/**
+ * BG.NF.1 W-FALLBACK-EXCISE — the JS token-mirror constants (the NO-MASKING-FALLBACK
+ * single-source floor). The dock composables read a live root token but need a value
+ * when the root is not yet mounted; that value lives HERE ONCE (never a bare drift-prone
+ * literal duplicated at the read site — the 1.14/44 that had already drifted 1.08→1.14).
+ */
+/**
+ * The shape-morph squish cap — mirrors `--dock-morph-max-stretch` (density.css). The
+ * lifted iOS-27 register (BD.W-MOTION-WEIGHT C1·R3 drift fix: the prior 1.08 was stale).
+ */
+export declare const DOCK_MORPH_MAX_STRETCH = 1.14;
+/**
+ * The collapsed-endpoint floor in px — mirrors `--dock-morph-min`'s `2.75rem` = the
+ * WCAG 2.5.5 touch floor at the 16px root (density.css). Used until the collapsed
+ * state has been captured at rest.
+ */
+export declare const DOCK_TAP_FLOOR_PX = 44;
+/** `Symbol()` label for the `DockContext` injection key (`dockContext.ts`). */
+export declare const DOCK_CONTEXT_LABEL = "glass-ui:dock-context";
+/** `Symbol()` label for the `DockCrossfadeContext` injection key (`dockCrossfadeContext.ts`). */
+export declare const DOCK_LAYER_GROUP_LABEL = "glass-ui:dock-layer-group";
+/** `Symbol()` label for the `DockMorphContext` injection key (`dockMorphContext.ts`). */
+export declare const DOCK_MORPH_LABEL = "glass-ui:dock-morph-context";
+/** The intent-dwell before a collapsed→hover expand commits (a sweeping-edge enter is
+ *  canceled by the chasing leave inside this window) — the calmer hover register KEPT
+ *  by W-DOCK-SPINE. BI.W-DOCK-RETIRES deleted the `EDGE_BAND_PX` moving-edge-sweep
+ *  recheck band (the ~120L hysteresis): post-SPINE the hit frame is a STATIONARY
+ *  state-sized box, so a mid-morph leave never sweeps a moving edge past the cursor. */
+export declare const HOVER_INTENT_MS = 60;
+export declare const MORPH_SETTLE_MS = 840;

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

@@ -0,0 +1,19 @@
+export { default as GlassDock } from "./GlassDock.vue";
+export { default as DockLayerGroup } from "./DockLayerGroup.vue";
+export { default as DockLayer } from "./DockLayer.vue";
+export { default as DockCrossfade } from "./DockCrossfade.vue";
+export type { DockFaceDescriptor, DockFaceRegistration, DockCrossfadeContext, } from "./composables/dockCrossfadeContext";
+export { default as DockControl } from "./DockControl.vue";
+export { default as DockTrigger } from "./DockTrigger.vue";
+export { default as DockBackgroundToggle } from "./DockBackgroundToggle.vue";
+export { default as DockSeparator } from "./DockSeparator.vue";
+export { default as DockStack } from "./DockStack.vue";
+export type { DockStackItem } from "./constants";
+export { default as DockSection } from "./DockSection.vue";
+export type { DockSectionDescriptor, DockSectionKind } from "./constants";
+export type { UseDockStateOptions, UseDockStateReturn, DockState } from "./composables";
+export { DOCK_CONTEXT_KEY, useDockContext, useOptionalDockContext, provideDockContext, type DockContext, type DockOrientation, type DockLayout, } from "./composables/dockContext";
+export { useDockCtaReceive, type UseDockCtaReceiveOptions, type UseDockCtaReceiveReturn, type DockCtaReceivePreset, } from "../../composables/motion/useDockCtaReceive";
+export { useDockSearch } from "./composables";
+export type { UseDockSearchOptions, UseDockSearchReturn } from "./composables";
+export { GooFilter } from "../goo-filter";