@mkbabb/glass-ui 4.2.0 → 6.0.0

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

@@ -0,0 +1,91 @@
+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 outer pair's fading pane id, or null once settled. */
+    outerLeavingLayer: Readonly<Ref<string | null>>;
+}
+/**
+ * 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/dockMorphMeasure.d.ts

@@ -0,0 +1,96 @@
+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).
+     */
+    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.
+ */
+export declare function useDockExpandedSize(options: UseDockExpandedSizeOptions): UseDockExpandedSizeReturn;

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/useDockClickIntegrity.d.ts

@@ -0,0 +1,27 @@
+import { type Ref } from "vue";
+export interface DockClickIntegrity {
+    /** Capture-phase `pointerdown` handler — records the press-time element + state. */
+    onPointerDownCapture: (event: PointerEvent) => void;
+    /** Capture-phase `pointercancel` handler — clears an abandoned press identity. */
+    onPointerCancelCapture: () => void;
+    /** Capture-phase `click` handler — swallows an identity-changed post-swap click. */
+    onClickCapture: (event: MouseEvent) => void;
+    /** Mark the collapsed→expanded flip so the settle window opens (call on expand). */
+    markExpandFlip: () => void;
+    /** The outer pane retained for the witnessed press, or null. */
+    pressKeepaliveLayer: Readonly<Ref<"full" | null>>;
+}
+export interface UseDockClickIntegrityOptions {
+    /** The dock root element ref — the morph-state owner (`[data-morphing]`). */
+    rootEl: Ref<HTMLElement | null>;
+    /** `true` whenever the dock is visually expanded (collapsed = !this). */
+    visualExpanded: Ref<boolean>;
+}
+/**
+ * The dock click-integrity guard (R5-3). 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
+ * own unmount cleanup.
+ */
+export declare function useDockClickIntegrity(options: UseDockClickIntegrityOptions): DockClickIntegrity;

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 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).
+ *
+ * G9 / O5 — ZERO SCROLL LISTENER. The measure is RESIZE- and CONTENT-driven (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
+ * 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,70 @@
+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;
+    /** Close the active popover and consume Escape so an ancestor layer stays open. */
+    onEscape: (event: KeyboardEvent) => 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,185 @@
+import { type ComputedRef } from "vue";
+export type DockSize = "sm" | "md" | "lg" | "xl";
+export type DockBackdropMode = "live" | "static";
+/**
+ * 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";
+    /**
+     * Backdrop material mode. `"live"` (default) samples and filters the painted
+     * backdrop; `"static"` uses a solid plate with no luminance observer or
+     * backdrop-filter work.
+     */
+    backdropMode?: DockBackdropMode;
+    /**
+     * 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;