@mkbabb/glass-ui 6.0.0 → 8.0.0

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

@@ -1,43 +1,57 @@
 import type { ComputedRef } from "vue";
 export type DockOrientation = "horizontal" | "vertical";
 export type DockLayout = "linear" | "grid";
+/**
+ * What KIND of hold a token is. The two are different facts about the dock and
+ * only one of them is a hand:
+ *
+ *  - `"morph"` (the default) — POSTURE only. "Something is open and the dock must
+ *    not idle-collapse under it": an armed search field, an open popover, a
+ *    focused switcher tab. It suppresses the collapse timer and nothing else. It is
+ *    NOT a hand, and it never engages the grasp optic (glass/grasp.css) — a
+ *    search field left open for a minute is not a minute-long touch.
+ *  - `"grasp"` — a live POINTER HOLD on a descendant control (`useDockHold`'s
+ *    acquire, driven by native `pointerdown`/`touchstart` on the resolved host).
+ *    A grasp IMPLIES a morph hold (a finger down must also hold the dock open),
+ *    so it takes both counts; it is the edge the material answers.
+ */
+export type DockHoldKind = "morph" | "grasp";
 /**
  * Dock context surfaces the dock id + orientation + held-state coordination
  * to descendants.
  *
- * O.W2 — canonical typed-key + helper-pair DI shape per invariant 25.
- * The 6 prior string-keyed provides (`glassDockContext`, `glassDockId`,
- * `dockKeepOpen`, `dockRelease`, `dockHeld`, `dockExpanded`) collapse into
- * the single `DOCK_CONTEXT_KEY` typed `InjectionKey<DockContext>`.
- * `dockExpanded` is retired (zero downstream consumers per Rδ audit).
- * `glassDockId` is dedup'd with `context.id`.
- *
+ * One typed key carries id, orientation, layout, and held-state coordination.
  * Paired helpers:
  *  - `useDockContext()` — strict; throws when used outside `<GlassDock>`.
  *  - `useOptionalDockContext()` — befitting silent default for primitives
  *    that may render outside a dock (Slider, popovers, …).
  *
- * J.W3.B — `registerPopover` / `closeOtherPopovers` retired. Hover-driven
- * dock popovers compose `<Popover trigger="hover" keep-dock-open>` (the
- * BI.W-OVERLAY-UNION sealed union; the fine-hover branch is reka's
- * HoverCardRoot). Open/close cadence is owned by reka's hover primitives;
- * cooperative dismissal between sibling popovers is no longer needed (the
- * pointer-leave timer handles the cluster transit case).
+ * Hover-driven dock popovers compose `<Popover trigger="hover" keep-dock-open>`.
+ * Reka's hover primitives own open/close cadence and cluster transit.
  */
 export interface DockContext {
     id: string;
     orientation: ComputedRef<DockOrientation>;
     /**
-     * In-cap arrangement (`linear` row/column vs `grid` tile panel). AX.W45 —
+     * In-cap arrangement (`linear` row/column vs `grid` tile panel).
      * `<DockSeparator>` reads this to paint a full-row section break in a grid dock
      * (a 1px perpendicular hairline is useless in a 2D tile grid).
      */
     layout: ComputedRef<DockLayout>;
-    /** Acquire a keep-open token; suppresses timer-based collapse. */
-    keepOpen: () => void;
-    /** Release a previously-acquired keep-open token. */
-    release: () => void;
-    /** Reactive `keepOpenCount > 0` flag; descendants reflect via `data-held`. */
+    /**
+     * Acquire a hold token; suppresses timer-based collapse. `kind` defaults to
+     * `"morph"` (posture only). Pass `"grasp"` for a live pointer hold — it takes
+     * BOTH counts, so a grasp also holds the dock open.
+     */
+    keepOpen: (kind?: DockHoldKind) => void;
+    /** Release a previously-acquired token of the SAME `kind` that took it. */
+    release: (kind?: DockHoldKind) => void;
+    /**
+     * Reactive GRASP edge — `true` while ≥1 pointer hold is live on a descendant.
+     * This is what the dock root reflects as `data-held` and what the grasp
+     * register answers; it is deliberately NOT the morph-hold count (an open
+     * popover is not a finger).
+     */
     held: ComputedRef<boolean>;
 }
 export declare const DOCK_CONTEXT_KEY: import("vue").InjectionKey<DockContext>;

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

@@ -1,21 +1,20 @@
 import type { Component, Ref } from "vue";
 /**
- * BI.W-DOCK-CROSSFADE — the crossfade face-registration context.
+ * the crossfade face-registration context.
  *
- * `<DockCrossfade :active>` provides this; each face host (`<DockLayer>`) registers
+ * `<DockCrossfade:active>` provides this; each face host (`<DockLayer>`) registers
  * its id + label + icon + host element on mount. The crossfade slot owns ONE face
- * registry — the registration machinery FOLDED here from the retired
- * `DockLayerGroup` `register`/`unregister` + `useLayerTransition` FLIP (PASS-1 §2.6).
- * A switcher rail (where one exists — `<DockLayerGroup>`) reads `faces` for its chip
- * run; the controlled-no-rail 5-pane case (speedtest) consumes `<DockCrossfade>`
- * DIRECTLY and reads only `activeId`/`leavingId` (no rail, no selection engine).
+ * registry.
+ * A switcher (where one exists — `<DockLayerGroup>`) reads `faces` for its chip
+ * run; the controlled-no-switcher 5-pane case (a consumer) consumes `<DockCrossfade>`
+ * DIRECTLY and reads only `activeId`/`leavingId` (no switcher, no selection engine).
  *
  * The context is DISTINCT from `DockContext` (a `<DockCrossfade>` need not live inside
- * a `<GlassDock>`) and from `DockMorphContext` (the plate collapse orchestrator) — the
+ * a `<GlassDock>`) and from the plate collapse orchestrator — the
  * face crossfade is orthogonal to the box morph (the compound: a face-swap DURING a
  * simultaneous collapse rides two independent scalars — per-face `--dock-t` for the
  * opacity overlap, the inheriting `--dock-morph-t` for the plate clip). It keeps its
- * own module-local key (canonical typed-key DI, invariant 25).
+ * own module-local key (canonical typed-key DI).
  */
 export interface DockFaceDescriptor {
     id: string;
@@ -43,8 +42,8 @@ export interface DockCrossfadeContext {
     /** The face currently dissolving out, or `null`. READ-ONLY to faces. */
     leavingId: Readonly<Ref<string | null>>;
     /**
-     * The registered face descriptors in registration order — the switcher rail's
-     * chip source (a `<DockLayerGroup>` reads this; the controlled-no-rail case
+     * The registered face descriptors in registration order — the switcher's
+     * chip source (a `<DockLayerGroup>` reads this; the controlled-no-switcher case
      * ignores it).
      */
     faces: Readonly<Ref<DockFaceDescriptor[]>>;

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

@@ -1,96 +1,16 @@
 import { type Ref } from "vue";
-/**
- * BD.W-DOCK-CORE (the width-seizure cure) — the dock morph SIZE measure.
- *
- * THE BUG THIS RETIRES (the year-old seizure): the prior pipeline measured a
- * per-swap `from/to` FLIP ratio and drove the visible size by
- * `--dock-root-scale = max(ratio + (1−ratio)·t, 0.06)` — a FLOOR with NO CEILING.
- * When the morph target measured small (a degenerate `to` racing the content
- * layout), `ratio = from/max(to,1px)` ran to ~56 → `scaleX(56)` = a ~2451px
- * detonation on collapse / an inversion at the spring overshoot peak. The
- * `transform-origin: center` kept the centroid clean (`cxRange 0`), which is
- * exactly why every prior judge measuring the centroid PASSED while the WIDTH
- * detonated. The whole measure-and-arm FLIP machinery
- * (`measureAndArmMorph`/`seatTargetSync`/`rebaseSiblingSpans`/
- * `forceNestedMaxContent`/`nestedTargetsWithin`/`measureTo`/`armRootMorphSpan`/
- * `clearRootMorphSpan`/`morphMinFloorPx`/the per-target generation gating) is
- * DELETED — clean break, no legacy, no floor that masks a bad measurement.
- *
- * THE CURE — a ratio-FREE measure-ONCE convex blend. The dock measures its two
- * KNOWN footprints ONCE per content change (a `ResizeObserver`, NOT a per-swap
- * rAF race): `--dock-expanded-px` (the expanded content width, read behind the
- * clip aperture) and `--dock-collapsed-px` (the collapsed summary box). The
- * visible size is the convex blend `--dock-live = collapsed + (expanded −
- * collapsed)·--dock-morph-t` and `--dock-size-scale = --dock-live / expanded`
- * (layers.css). A convex blend of two POSITIVE endpoints can NEVER exceed the
- * larger nor invert below the smaller — BOUNDED by construction, no ratio, no
- * `scaleX` explosion, regardless of spring overshoot (the `clamp(0,t,1)` caps the
- * size term; the >1 excursion routes to the orthogonal punch channel).
- *
- * THE FRESHNESS GUARD (challenge 3·R2): a measure-ONCE endpoint can still be read
- * stale — before `fonts.ready`, before async icon SVGs lay out, on a
- * `display:none`→0 route swap, or on a `content-visibility:auto` parent (the RO
- * fires 0). A 0 expanded would give `collapsed/0 = ∞`. So FLOOR `--dock-expanded-px`
- * at `max(measured, --dock-collapsed-px)` and re-measure on `fonts.ready` + the
- * FIRST non-zero RO callback + visibility-enter. This is NOT the deleted magic
- * floor (which masked a per-frame measurement); it is a one-shot endpoint
- * sanity bound on a value that is otherwise stable across the whole morph.
- *
- * `DOCK_SPRING` is byte-fenced — it lives in `../constants`, never touched here.
- */
-export declare function dimOf(axis: "horizontal" | "vertical"): "width" | "height";
-export declare function getSize(el: HTMLElement, axis: "horizontal" | "vertical"): number;
 export interface UseDockExpandedSizeOptions {
-    /** The `.glass-dock` root the `--dock-expanded-px`/`--dock-collapsed-px` write to. */
     rootEl: Ref<HTMLElement | null>;
-    /**
-     * The content element whose intrinsic morph-axis span is observed for size
-     * changes (the active full-pane container — `.dock-layers`). Its resizes are the
-     * RO trigger; the ENDPOINTS are read off the ROOT box (content + chrome), keyed
-     * by the dock's at-rest expanded/collapsed state.
-     */
     contentEl: Ref<HTMLElement | null>;
-    /**
-     * The morph axis (a horizontal dock blends width; a vertical dock blends height).
-     */
+    expandedEl: Ref<HTMLElement | null>;
+    collapsedEl: Ref<HTMLElement | null>;
     axis: Ref<"horizontal" | "vertical">;
-    /**
-     * Whether the dock is currently in its EXPANDED visual state (a `Ref<boolean>`).
-     * The endpoint captured at rest is keyed off this: at rest expanded → the root
-     * box is the `--dock-expanded-px` endpoint; at rest collapsed → the
-     * `--dock-collapsed-px` endpoint. (A reactive read, so a state flip re-captures.)
-     */
     expanded: Ref<boolean>;
 }
-export interface DockMorphMeasureFailure {
-    readonly code: "invalid-morph-min";
-    readonly token: string;
-}
-export interface UseDockExpandedSizeReturn {
-    /** The single fail-closed state for an unreadable semantic geometry token. */
-    failure: Readonly<Ref<DockMorphMeasureFailure | null>>;
-}
-/** Resolve the inherited semantic token through CSS itself, including max()/rem/var(). */
-export declare function resolveDockMorphMin(root: HTMLElement): number | null;
 /**
- * BD.W-DOCK-CORE — capture the two convex-blend endpoints ONCE PER STATE off the
- * ROOT box.
- *
- * The visible morph scales the ROOT (chrome + content), so the two blend endpoints
- * must be the ROOT's OWN expanded/collapsed footprints — NOT the bare content span
- * (which omits the padding/min-width chrome). The endpoints are captured at REST
- * (when `[data-morphing]` is OFF): the dock's settled root box in its current
- * expanded/collapsed state IS that state's endpoint. A `ResizeObserver` on the
- * content re-captures the CURRENT state's endpoint whenever the content reflows
- * (more controls, a font swap), so the blend stays fresh — but it never reads the
- * box MID-MORPH (the scaled box would feed back a degenerate endpoint, the seizure's
- * cousin). The expanded endpoint is FLOORED at `max(captured, collapsed)` — the
- * freshness guard against a 0/degenerate read giving `collapsed/0 = ∞`.
- *
- * The collapsed endpoint starts at the resolved `--dock-morph-min` icon-square floor
- * and is refined to the real collapsed root box the first time the dock rests
- * collapsed; the expanded endpoint is captured the first (and every) time it rests
- * expanded. So the FIRST morph from a freshly-mounted expanded dock already has a
- * real expanded endpoint + a sane collapsed floor — bounded by construction.
+ * Measure the dock's two rendered pane compositions. The inactive pane remains
+ * laid out (visibility, never display, hides it), so the first morph can derive
+ * both endpoints from real content—coarse controls bring their own 44px floor;
+ * non-interactive visuals receive no invented one.
  */
-export declare function useDockExpandedSize(options: UseDockExpandedSizeOptions): UseDockExpandedSizeReturn;
+export declare function useDockExpandedSize(options: UseDockExpandedSizeOptions): void;

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

@@ -0,0 +1,29 @@
+import type { Ref } from "vue";
+/**
+ * The dock switcher tablist context.
+ *
+ * `<DockLayerGroup>` provides it so a `<DockLayer>` face can complete the APG
+ * tablist↔tabpanel linkage: the switcher's `role="tab"` buttons `aria-controls` a face,
+ * and each face is the matching `role="tabpanel"` with a stable `id` +
+ * `aria-labelledby` back to its tab. The id derivation lives HERE (once), keyed off a
+ * group-level uid, so the tab side (`DockLayerGroup`) and the panel side (`DockLayer`)
+ * mint the SAME strings with no shared literal.
+ *
+ * `isTablist` is reactive because the switcher only renders as a tablist when it actually
+ * paints (`showSwitcher && >1 face`) — that is not known until faces register. A face
+ * reads it to decide whether to BECOME a tabpanel: absent (the controlled-no-switcher
+ * `<DockCrossfade>` case, or a 0/1-face group), the face carries no panel role, so a
+ * dangling `aria-labelledby` to a tab that does not exist is never minted.
+ */
+export interface DockSwitcherContext {
+    /** True while the switcher renders as an APG tablist (`showSwitcher && >1 face`). */
+    isTablist: Readonly<Ref<boolean>>;
+    /** The switcher tab button's id for a face id — the panel's `aria-labelledby` target. */
+    tabId: (faceId: string) => string;
+    /** The face panel's id for a face id — the tab's `aria-controls` target. */
+    panelId: (faceId: string) => string;
+}
+export declare const DOCK_SWITCHER_KEY: import("vue").InjectionKey<DockSwitcherContext>;
+export declare function provideDockSwitcherContext(context: DockSwitcherContext): void;
+/** Befitting-silent — `null` when a face is not inside a tablist switcher. */
+export declare const useDockSwitcherContext: () => DockSwitcherContext | null;

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

@@ -1,10 +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";
+export { useDockState } from "./useDockState.js";
+export type { UseDockStateOptions, UseDockStateReturn, DockState } from "./useDockState.js";
+export { useDockSearch } from "./useDockSearch.js";
+export type { UseDockSearchOptions, UseDockSearchReturn } from "./useDockSearch.js";
+export { useDockHold } from "./useDockHold.js";
+export type { UseDockHoldOptions, UseDockHoldReturn } from "./useDockHold.js";
+export { isTeleportedTarget } from "../../_shared/overlay/isTeleportedTarget.js";
+export { provideDockContext, useDockContext, useOptionalDockContext, DOCK_CONTEXT_KEY, type DockContext, type DockOrientation, } from "./dockContext.js";
+export { provideDockCrossfadeContext, useDockCrossfadeContext, useOptionalDockCrossfadeContext, DOCK_CROSSFADE_KEY, type DockFaceDescriptor, type DockFaceRegistration, type DockCrossfadeContext, } from "./dockCrossfadeContext.js";
+export { useDockMorphOrchestrator, type UseDockMorphOrchestratorOptions, type UseDockMorphOrchestratorReturn, } from "./useDockMorph.js";

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

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

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

@@ -1,6 +1,6 @@
-import type { ComputedRef } from "vue";
+import type { Ref } from "vue";
 /**
- * AX.W03 — the host-native dock hold.
+ * Host-native dock hold.
  *
  * `keepDockOpen` is a FIRST-CLASS, synchronous morph-state input to the dock's
  * one state machine: while a continuous pointer/touch gesture is live on a
@@ -8,6 +8,14 @@ import type { ComputedRef } from "vue";
  * dock's `held` edge lights `data-held` on the dock root AND the control for the
  * thumb-halo intensification.
  *
+ * THIS ACQUIRE IS THE HAND. It is the only path in the library driven by an actual
+ * pointer going down, so it is the one the GRASP register (glass/grasp.css) is
+ * sourced from: the token it takes is `keepOpen("grasp")`, which lights the dock's
+ * `held` edge as well as holding posture. The returned `isHeld` is this host's OWN
+ * live-hold flag — it flips with the finger whether or not a dock is present, so a
+ * STANDALONE control engages on its own drag and a control inside a dock does NOT
+ * co-engage off a sibling's hold.
+ *
  * Why NATIVE host listeners (not a Vue `@pointerdown` template binding):
  * reka-ui's `<SliderRoot>` is a FORWARDING component — it renders through a
  * `CollectionSlot` + `resolveDynamicComponent` (SliderHorizontal/Vertical) +
@@ -17,9 +25,8 @@ import type { ComputedRef } from "vue";
  * Slot/forwardRef boundary — vue-tsc + units pass, only a real drag catches it
  * (the canonical binding-verification class, `feedback_glass_ui_binding_*`). A
  * native `addEventListener` on the RESOLVED host element is immune: the event
- * always reaches the DOM node the user actually presses. This is the
- * device-proven fix (AX.W03 §Scope.1/2 — slice-2 F0/F2; ratified host-native
- * over a reka `dragging`-ref subscription, which reka does not publicly expose
+ * always reaches the DOM node the user actually presses. This host-native behavior is
+ * preferable to a Reka `dragging`-ref subscription, which Reka does not publicly expose
  * and which would re-introduce the same forwarding fragility).
  *
  * The hold is INSTANT-ON (Apple "Building Fluid Interfaces", facet 5): the first
@@ -34,9 +41,11 @@ import type { ComputedRef } from "vue";
  * hold path, no parallel `touchGate` watch).
  *
  * DI: consumes the EXISTING typed `DockContext` via `useOptionalDockContext()`
- * (the `keepOpen`/`release` pair, O.W2 single-typed-key collapse). A control
- * rendered OUTSIDE a `<GlassDock>` gets the befitting-silent default (no dock) —
- * every hook is a no-op, a primitive may legitimately render outside a dock.
+ * through the `keepOpen` and `release` pair. A control rendered OUTSIDE a
+ * `<GlassDock>` gets the befitting-silent default (no dock) — the DOCK half is a
+ * no-op, a primitive may legitimately render outside a dock. The HAND half is not
+ * conditional on it: the returned edge tracks the pointer either way, which is what
+ * lets a standalone `<Slider>` grasp.
  */
 export interface UseDockHoldOptions {
     /**
@@ -47,8 +56,13 @@ export interface UseDockHoldOptions {
     enabled?: () => boolean;
 }
 export interface UseDockHoldReturn {
-    /** `true` whenever the dock observes ≥1 held token (the `data-held` edge). */
-    isHeld: ComputedRef<boolean> | undefined;
+    /**
+     * `true` while THIS host's own pointer hold is live — from the native
+     * `pointerdown`/`touchstart` acquire to the window-scoped release. Dock-free by
+     * construction: a control outside a `<GlassDock>` still reports its own hand,
+     * and a control inside one never reports a sibling's.
+     */
+    isHeld: Ref<boolean>;
 }
 /**
  * @param resolveHost A getter that resolves the REAL host element to attach the

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

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

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

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

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

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