@mkbabb/glass-ui 4.0.1 → 4.1.0

package/dist/components/custom/constellation/shaders/constellation-points.wgsl.d.ts

@@ -0,0 +1 @@
+export declare const CONSTELLATION_POINTS_WGSL = "\n// \u2500\u2500 Node storage row + uniforms (the typed-struct source-of-truth \u2014 uniformBridgeWGPU.ts) \u2500\u2500\nstruct Node {\n  // (pos.x, pos.y, radius, dim)\n  data: vec4<f32>,\n};\n\nstruct ConstellationUniforms {\n  // u0: (resolution.x, resolution.y, dpr, kVis)\n  u0: vec4<f32>,\n  // u1: (time, lineWidth, opacityCeiling, alpha)\n  u1: vec4<f32>,\n  // uEdge: (edgeAlpha, edgeFocusAlpha, edgeAccentAlpha, edgeFloor)\n  uEdge: vec4<f32>,\n  // colours (premultiplied-ready rgba)\n  uNode: vec4<f32>,\n  uNodeDim: vec4<f32>,\n  uLine: vec4<f32>,\n  uAccent: vec4<f32>,\n};\n\n@group(0) @binding(0) var<uniform> u: ConstellationUniforms;\n@group(0) @binding(1) var<storage, read> nodes: array<Node>;\n\nstruct VSOut {\n  @builtin(position) pos: vec4<f32>,\n  @location(0) uv: vec2<f32>,   // [-1,1] billboard-local \u2192 fragment SDF coord\n  @location(1) dim: f32,        // 0 = full node, 1 = dim node\n};\n\n@vertex\nfn vs_main(\n  @builtin(vertex_index) vIdx: u32,\n  @builtin(instance_index) iIdx: u32,\n) -> VSOut {\n  // Two-triangle quad corners in billboard-local space.\n  var QUAD = array<vec2<f32>, 6>(\n    vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, -1.0), vec2<f32>(-1.0, 1.0),\n    vec2<f32>(-1.0,  1.0), vec2<f32>(1.0, -1.0), vec2<f32>(1.0,  1.0),\n  );\n  let corner = QUAD[vIdx];\n\n  let node = nodes[iIdx].data;\n  let res = u.u0.xy;\n  let dpr = u.u0.z;\n  let kVis = u.u0.w;\n\n  // center: node px \u2192 clip space (y-flip \u2014 px is y-down, clip is y-up).\n  let centerPx = node.xy;\n  let centerNdc = vec2<f32>(\n    centerPx.x / max(res.x, 1.0) * 2.0 - 1.0,\n    1.0 - centerPx.y / max(res.y, 1.0) * 2.0,\n  );\n  // half-extent: radius\u00B7kVis in CSS px \u2192 backing-store px (\u00B7dpr) \u2192 NDC half (\u00B72/res).\n  // (the DPR-aware crispness leg \u2014 the disc samples at device resolution.)\n  // (half is a WGSL reserved keyword \u2014 name it halfExt.)\n  let radPx = node.z * kVis * dpr;\n  let halfExt = vec2<f32>(radPx / max(res.x, 1.0) * 2.0, radPx / max(res.y, 1.0) * 2.0);\n\n  var out: VSOut;\n  out.pos = vec4<f32>(centerNdc + corner * halfExt, 0.0, 1.0);\n  out.uv = corner;\n  out.dim = node.w;\n  return out;\n}\n\n@fragment\nfn fs_main(in: VSOut) -> @location(0) vec4<f32> {\n  // SDF: distance to the unit-circle edge in billboard-local space (0 at the rim, neg inside).\n  let d = length(in.uv) - 1.0;\n  // fwidth(d) = |dpdx(d)| + |dpdy(d)| \u2014 the pixel footprint of the SDF, the resolution-\n  // independent AA width (~1px band at ANY DPR/zoom/size).\n  let aa = max(fwidth(d), 1e-4);\n  let coverage = 1.0 - smoothstep(-aa, aa, d);\n  if (coverage <= 0.0) { discard; }\n  let col = mix(u.uNode, u.uNodeDim, in.dim);\n  let a = col.a * coverage * u.u1.z;  // \u00B7opacityCeiling\n  // premultiplied-alpha output.\n  return vec4<f32>(col.rgb * a, a);\n}\n";

package/dist/components/custom/deck/DeckPager.vue.d.ts

@@ -0,0 +1,29 @@
+type __VLS_Props = {
+    /** Total slide count. */
+    total: number;
+    /** Window to `fit` dots centered on the active dot. Off → show every dot. */
+    windowFit?: number;
+    /** Encapsulate the rail in the glass pager pill chassis. Default false —
+        a deck owns its own ambient glass host, so the dots sit FLUSH on it. */
+    ring?: boolean;
+    /** Accessible name for the rail group. */
+    ariaLabel?: string;
+};
+type __VLS_ModelProps = {
+    /** v-model:index — the active 0-based slide index. */
+    "index"?: number;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:index": (value: number) => any;
+} & {
+    select: (index: number) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onSelect?: ((index: number) => any) | undefined;
+    "onUpdate:index"?: ((value: number) => any) | undefined;
+}>, {
+    ariaLabel: string;
+    ring: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/custom/deck/composables/useDeck.d.ts

@@ -0,0 +1,27 @@
+import { type ComputedRef, type Ref } from "vue";
+export interface DeckCore {
+    /** The 0-based active slide index (clamped to [0, total-1]). */
+    index: Ref<number>;
+    /** The total slide count. */
+    total: number;
+    /** 1-based completion as a percentage (slide 1 of N → 100/N), for a bar. */
+    progress: ComputedRef<number>;
+    /** The accessible "Slide N of M" announcement off the live index (§3 — the
+        portable aria-live seam; surface it in an `sr-only` polite region). */
+    liveMessage: ComputedRef<string>;
+    go: (i: number) => void;
+    next: () => void;
+    prev: () => void;
+    first: () => void;
+    last: () => void;
+}
+export interface UseDeckOptions {
+    /** The initial 0-based index (clamped). Default 0. */
+    initial?: number;
+    /** Fired AFTER a navigation commits, with the new + previous index. */
+    onChange?: (to: number, from: number) => void;
+    /** Resolve a per-slide accessible name for the live announcement (e.g. the
+        manifest title). When set, `liveMessage` reads "Slide N of M: <name>". */
+    label?: (index: number) => string;
+}
+export declare function useDeck(total: number, opts?: UseDeckOptions): DeckCore;

package/dist/components/custom/deck/composables/useDeckKeyboard.d.ts

@@ -0,0 +1,25 @@
+import { type MaybeRefOrGetter } from "vue";
+/** The minimal move surface the handler drives (a structural subset of DeckCore,
+    so the consumer can pass its `DeckCore` directly). */
+export interface DeckMoves {
+    next(): void;
+    prev(): void;
+    first(): void;
+    last(): void;
+    go(i: number): void;
+}
+export interface DeckKeyOptions {
+    /** Override the focused-control test (defaults to `target.closest(controls)`). */
+    isControl?: (target: EventTarget | null) => boolean;
+}
+/** Handle ONE keydown against the deck. Returns true if it navigated (and called
+    `preventDefault`), false if the key was left for the page/control. */
+export declare function handleDeckKey(e: KeyboardEvent, deck: DeckMoves, opts?: DeckKeyOptions): boolean;
+export interface UseDeckKeyboardOptions extends DeckKeyOptions {
+    /** The element the listener binds to. Default `window` (deck-global paging). */
+    target?: MaybeRefOrGetter<EventTarget | null | undefined>;
+}
+/** Bind the focus-guarded deck keyboard contract to a target (default `window`)
+    for the component lifetime. The `target` may be a ref/getter so a not-yet-mounted
+    element resolves at `onMounted`. */
+export declare function useDeckKeyboard(deck: DeckMoves, opts?: UseDeckKeyboardOptions): void;

package/dist/components/custom/deck/composables/useDeckSpring.d.ts

@@ -0,0 +1,22 @@
+/** The deck spring preset, re-exported from the colocated constants for consumers
+    sampling the same `(response, ζ)` row. */
+export { DECK_SPRING } from "../constants";
+/**
+ * Count-up easing. Defaults to a monotone cubic-out so a still render (or a failed
+ * engine chunk) is always faithful; replaced in-place with the engine's
+ * `springTimingFunction(.smooth)` once keyframes.js resolves. Callers read
+ * `deckEase.fn` each frame, so the swap is picked up live with no re-wiring.
+ */
+export declare const deckEase: {
+    fn: (t: number) => number;
+};
+/**
+ * Swap `deckEase.fn` to the engine's matching JS easing once keyframes.js resolves.
+ * Idempotent. No-op off-DOM (SSR / export tooling) and a silent no-op if the engine
+ * chunk fails — the count-up keeps its monotone cubic fallback.
+ *
+ * The slide transition needs no JS write: `--spring-deck: var(--spring-smooth)`
+ * (glass-ui's `.smooth` `linear()` token) resolves the declarative half at first
+ * paint.
+ */
+export declare function installDeckSpring(): void;

package/dist/components/custom/deck/constants.d.ts

@@ -0,0 +1,14 @@
+/** SwiftUI `.smooth` — the deck's slide-transition + count-up curve: a calm settle
+    with a barely-there micro-overshoot, the right cadence for a content deck (the
+    page change reads as a settle, not a bounce). It is the SAME family the
+    `--spring-smooth` token derives from (`springLinearStops()` output), so the deck
+    inherits the constellation's iOS curve instead of forking a third easing
+    vocabulary — `--spring-deck: var(--spring-smooth)`. */
+export declare const DECK_SPRING: {
+    readonly response: 0.5;
+    readonly dampingFraction: 0.85;
+};
+/** The focused-control selector the keyboard handler tests: when a control (button
+    / link / field) is focused, Space + digit jumps reach that control's native
+    activation instead of being stolen for navigation (the C6 correctness fix). */
+export declare const CONTROL_SELECTOR = "button, a, input, textarea, select, [role=button]";

package/dist/components/custom/deck/index.d.ts

@@ -0,0 +1,8 @@
+export { useDeck } from "./composables/useDeck";
+export type { DeckCore, UseDeckOptions } from "./composables/useDeck";
+export { useDeckKeyboard, handleDeckKey } from "./composables/useDeckKeyboard";
+export type { DeckMoves, DeckKeyOptions, UseDeckKeyboardOptions, } from "./composables/useDeckKeyboard";
+export { installDeckSpring, deckEase, DECK_SPRING, } from "./composables/useDeckSpring";
+export { default as DeckPager } from "./DeckPager.vue";
+export { CONTROL_SELECTOR } from "./constants";
+export type { PagerWindow } from "../pager-dots/pagerWindow";

package/dist/components/custom/dock/DockIconButton.vue.d.ts

@@ -22,6 +22,17 @@ import { type ButtonHTMLAttributes, type Component, type HTMLAttributes } from "
 type __VLS_Props = {
     /** Compact variant: auto-sized instead of fixed 2.5rem square. */
     compact?: boolean;
+    /**
+     * Selected/toggled state (BC.W-DOCK-ENGINE cross-repo fold — fourier-M #10).
+     * The icon button is otherwise STATELESS (hover/press only); a consumer
+     * building a selectable dock control (a filter toggle, a mode picker) had to
+     * hand-roll the active register. Setting `active` stamps `aria-pressed` (the
+     * load-bearing AT-selectable semantic) + `data-active` (the CSS hook reading
+     * the existing `--dock-control-active-bg` "selected reads as glass" tier —
+     * NEVER a saturated brand hue, per W-REGISTER-IOS). Ergonomic sugar over the
+     * shipped register; no new token, no new paint.
+     */
+    active?: boolean;
     /** Button type attribute (default: "button" to prevent form submission). */
     type?: ButtonHTMLAttributes["type"];
     /** Host tag/component (reka-ui Primitive `as`; default "button"). */
@@ -35,6 +46,7 @@ type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_8) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    active: boolean;
     type: "button" | "reset" | "submit";
     compact: boolean;
     asChild: boolean;

package/dist/components/custom/dock/DockStack.vue.d.ts

@@ -0,0 +1,65 @@
+import { type Component } from "vue";
+import type { DockStackItem } from "./constants";
+/**
+ * <DockStack> — BC.W-DOCK-STACK-RAIL. The macOS Dock hover-expand STACK (the clean-break
+ * rebuild of the retired divider-carousel `DockRail`). It renders in `GlassDock`'s `#rail`
+ * slot, over the KEPT `.glass-dock-frame` non-clipping escape, so it extends BEYOND the
+ * dock edge into its own gutter WITHOUT touching the dock box (the box-INVIOLATE
+ * discipline — `deltaW = deltaH = 0`).
+ *
+ * THE STACK. A `core` anchor item (the always-visible glyph, sitting in the dock(1)) +
+ * `items: readonly DockStackItem[]` (the members). On hover (pointer-enter) OR focus of
+ * the core item, the members FAN OUT next to the rail — a column (vertical dock) / row
+ * (horizontal dock) of FULLY-VISIBLE glass icons springing open beside the line, each on
+ * the iOS liquid clock, staggered by `--dock-stack-stagger * var(--i)` in reading order.
+ * The hover-collapse reverses on the no-overshoot `--ease-out`. Every member is a clear
+ * `--glass-bg-floating` glass icon — NEVER a shadowed half-tucked chip (the "NOT shadowed"
+ * verbatim ask). At rest only the core (1) shows; expanded, the n members.
+ *
+ * 3 CONFIGURABLE, SCROLLABLE, N-STACK. `visibleCount` (default 3) members fan at rest;
+ * an >visibleCount stack routes the fanned column through `<FadingScroll>` (the one
+ * scroll-fade port) so the n-stack is reachable by scrolling the rail, NOT by overflowing
+ * the dock box.
+ *
+ * THE HOVER-HYSTERESIS (REUSED, not re-forked — AZ.W-DOCK-FLICKER). The pointer-enter
+ * commits the open only after the `HOVER_INTENT_MS` intent-dwell (the SAME constant the
+ * dock-collapse hysteresis reads), so a sweeping-edge enter does not flash the stack open.
+ * Focus opens immediately (keyboard intent is explicit); blur/leave closes.
+ *
+ * ONE REGISTRY (R2 KEPT). The members write the consumer-owned `v-model:selected`; this
+ * primitive owns NO internal `ref()`/`reactive()` shadow of the active member. The hover
+ * `expanded` is a transient UI state (optionally `v-model:expanded` controlled), NOT a
+ * selection shadow.
+ */
+type __VLS_Props = {
+    /** The stack members — the fan-out contents (NOT facet chips; the macOS stack). */
+    items: readonly DockStackItem[];
+    /** The core anchor glyph (the always-visible dock(1) item). Default: a layers glyph. */
+    core?: Component;
+    /** The core's accessible label (the stack's name). */
+    coreLabel?: string;
+    /** Members visible at rest before scrolling (the verbatim "3 configurable"). */
+    visibleCount?: number;
+    /** Which dock edge the stack anchors to. */
+    position?: "start" | "end";
+};
+type __VLS_ModelProps = {
+    "selected"?: string;
+    "expanded"?: boolean;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    select: (id: string) => any;
+    "update:selected": (value: string | undefined) => any;
+    "update:expanded": (value: boolean) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onSelect?: ((id: string) => any) | undefined;
+    "onUpdate:selected"?: ((value: string | undefined) => any) | undefined;
+    "onUpdate:expanded"?: ((value: boolean) => any) | undefined;
+}>, {
+    position: "start" | "end";
+    visibleCount: number;
+    coreLabel: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/custom/dock/GlassDock.vue.d.ts

@@ -1,5 +1,5 @@
 import { type DockProps } from "./composables/useDockShellProps";
-declare var __VLS_1: {}, __VLS_3: {}, __VLS_5: {}, __VLS_7: {};
+declare var __VLS_1: {}, __VLS_3: {}, __VLS_5: {}, __VLS_7: {}, __VLS_9: {};
 type __VLS_Slots = {} & {
     persistent?: (props: typeof __VLS_1) => any;
 } & {
@@ -7,7 +7,9 @@ type __VLS_Slots = {} & {
 } & {
     collapsed?: (props: typeof __VLS_5) => any;
 } & {
-    rail?: (props: typeof __VLS_7) => any;
+    search?: (props: typeof __VLS_7) => any;
+} & {
+    rail?: (props: typeof __VLS_9) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<DockProps, {
     expanded: import("vue").Ref<boolean, boolean>;

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

@@ -24,6 +24,17 @@ export declare function dimOf(axis: "horizontal" | "vertical"): "width" | "heigh
 export declare function morphAxisProp(axis: "horizontal" | "vertical"): "inline-size" | "block-size";
 export declare function getSize(el: HTMLElement, axis: "horizontal" | "vertical"): number;
 export declare function clearMorphVars(el: HTMLElement): void;
+/**
+ * BC.W-LIQUID-MORPH (M3) — the reserve-floor in px (the measure-failure floor). The
+ * CSS reserve floors the box at `max(var(--dock-morph-to), var(--dock-morph-min))`
+ * (layers.css), but the SCALAR ratio still runs toward `--dock-morph-to`, so a
+ * `to:0` mis-measure would interpolate toward a degenerate target. The orchestrator's
+ * measure-failure guard seats the measured `to` at THIS px so the morph interpolates
+ * toward a visible footprint, never 0 — "visible at the floor," never "white." Reads
+ * the element's RESOLVED `--dock-morph-min` (density-scaled), falling back to the WCAG
+ * ~44px touch floor when the token is unset / unresolvable. Pure read — no write.
+ */
+export declare function morphMinFloorPx(el: HTMLElement | null): number;
 /**
  * BA-VJS-1 (valuejs-fold A-1) — the OTHER registered targets whose container is a
  * DOM DESCENDANT of `outerEl` (a nested `<DockLayerGroup>` stack inside the outer
@@ -73,3 +84,72 @@ export interface MorphSeatCallbacks {
  * resolves to the class endpoint with `[data-morphing]` cleared).
  */
 export declare function seatTargetSync(t: MorphMeasureTarget, id: number, root: HTMLElement | null, targets: Iterable<MorphMeasureTarget>, cb: MorphSeatCallbacks): void;
+/**
+ * The swap-while-morphing sibling re-base. The shared scalar resets to 0 for the
+ * new span; if SIBLING targets are mid-morph, re-base their `from` to their CURRENT
+ * painted px first, so resetting the scalar keeps them visually continuous (they
+ * interpolate fresh from where they are, toward their unchanged `to`) rather than
+ * snapping back to their old `from`. PURE over the swapping target + the target set.
+ */
+export declare function rebaseSiblingSpans(swapping: MorphMeasureTarget, targets: Iterable<MorphMeasureTarget>): void;
+/**
+ * BC.W-DOCK-ROOT-MORPH — clear the ROOT box's own morph span (the `inline-size` =
+ * f(scalar) recipe in layers.css reads `--dock-root-morph-from/to`; clearing them
+ * hands the box back to the at-rest shrink-wrap once the morph settles). PURE on
+ * the root element — no orchestrator closure.
+ */
+export declare function clearRootMorphSpan(root: HTMLElement | null): void;
+/**
+ * BC.W-DOCK-ROOT-MORPH — pin the ROOT box's own from→to span on the dock root.
+ *
+ * THE SNAP ROOT CAUSE: the inner `.dock-layers` reserves its SETTLED `to`
+ * footprint (`inline-size: var(--dock-morph-to)`, layers.css — the E4-frozen
+ * CDP-Layout-flat mechanism) and morphs VISUALLY via `transform: scaleX()`. A
+ * `transform` is paint-only — a parent does NOT shrink-wrap to a scaled child —
+ * so the root `.glass-dock` (display:inline-flex) shrink-wraps to the inner's
+ * RESERVED full `to` width and SNAPS to full on frame 0, while the inner's scaled
+ * box rides the spring smoothly. The gate (and the page) measure the ROOT box, so
+ * the root must ALSO ramp. The layers.css recipe reads
+ * `inline-size: calc(from + (to−from)·--dock-morph-t)` (the SAME scalar the spring
+ * glides, NO CSS transition — proof:no-layout-animation stays GREEN; a `calc()`
+ * over the registered `--dock-morph-t` is not a transition). PURE on the root.
+ */
+export declare function armRootMorphSpan(root: HTMLElement | null, rootFrom: number, rootTo: number): void;
+/** The orchestrator callbacks the rAF measure-and-arm window composes — the arm
+ *  step re-pins the per-target + root spans on the shared scalar. */
+export interface MorphMeasureArmCallbacks {
+    /** Arm the per-target `--dock-morph-from/to` span + ensure the shared spring. */
+    armTarget(t: MorphMeasureTarget, id: number, fromSize: number, toSize: number): void;
+}
+/**
+ * BC.W-DOCK-ROOT-MORPH / BA-VJS-1 / BC.W-LIQUID-MORPH (M3) — the rAF measure-and-arm
+ * window: ONE rAF (post-flush) later, lift the pin for a single synchronous
+ * measurement of the now-correct shrink-wrapped to-size, then re-pin + start the
+ * spring IN THE SAME FRAME. The measurement + arm are gated on THIS target's own
+ * `txId`, so a sibling target swapping in the same tick does NOT clobber it.
+ *
+ * BA-VJS-1 — the nested-`DockLayerGroup` measure-ORDERING fix: force every OTHER
+ * registered target whose container is a DOM descendant of this outer's container
+ * to its own-axis `max-content` (clearing its pinned calc span) for the single
+ * synchronous measurement, then RESTORE its exact prior inline state, so the outer
+ * shrink-wraps around the inner's TRUE intrinsic content, not its pinned collapse.
+ *
+ * BC.W-DOCK-ROOT-MORPH — for the OUTER target, LIFT the root's own pinned span for
+ * the duration of this synchronous measure (clearing `--dock-root-morph-from/to`,
+ * which the layers.css recipe constrains the root by) so the root shrink-wraps to
+ * its TRUE expanded width, read it DIRECTLY (sidestepping the chrome-offset
+ * arithmetic + the empty-summary `inner-to:0` trap), then RESTORE the pin and
+ * arm the root from→to span so its `inline-size` ramps on the SAME scalar.
+ *
+ * BC.W-LIQUID-MORPH (M3) — the measure-failure guard: a `to:0` mis-measure (a
+ * mid-morph re-grab, a nested collapsible still pinned, a race the ordering fix
+ * missed) seats the measured `to` at the resolved floor (`--dock-morph-min`,
+ * density-scaled, WCAG ~44px fallback) so the morph interpolates toward a visible
+ * footprint, never toward 0 — "visible at the floor," never "white." Inert on a
+ * healthy measurement.
+ *
+ * PURE over its explicit deps (the orchestrator passes the live element/targets/
+ * outer identity + the `armTarget` re-pin callback) — no module-level state, so the
+ * extraction is behaviour-identical to the prior inline rAF closure.
+ */
+export declare function measureAndArmMorph(t: MorphMeasureTarget, id: number, axis: "horizontal" | "vertical", fromSize: number, rootFromSize: number, isOuter: boolean, rootEl: HTMLElement | null, targets: Iterable<MorphMeasureTarget>, cb: MorphMeasureArmCallbacks): void;

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

@@ -1,5 +1,7 @@
 export { useDockState } from "./useDockState";
 export type { UseDockStateOptions, UseDockStateReturn, DockState } from "./useDockState";
+export { useDockSearch } from "./useDockSearch";
+export type { UseDockSearchOptions, UseDockSearchReturn } from "./useDockSearch";
 export { useLayerTransition } from "./useLayerTransition";
 export type { UseLayerTransitionOptions, UseLayerTransitionReturn } from "./useLayerTransition";
 export { useDockHold } from "./useDockHold";

package/dist/components/custom/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` glide + the `morph-bridge.css`
+ * metaball.
+ *
+ * @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/custom/dock/composables/useDockShellProps.d.ts

@@ -143,6 +143,17 @@ export interface DockProps {
      * 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 {

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

@@ -1,18 +1,22 @@
 import type { Component } from "vue";
 /**
- * AZ.W-RAIL3 — one `<DockRail>` chip descriptor: the visible facet the floating
- * carousel strip renders (id + label + glyph). A `<script setup>` SFC cannot
- * re-export a named type through the `export { default }` barrel, so the chip
- * descriptor lives here (the colocated types home) and the SFC imports it; the
- * barrel re-exports it for consumers typing their `items` array.
+ * 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 DockRailItem {
-    /** The context id this chip selects (written to `v-model:context`). */
+export interface DockStackItem {
+    /** Stable identifier — the `v-for` key + the selected-member id. */
     id: string;
-    /** The chip label. */
+    /** The member's accessible label (the `aria-label` + tooltip). */
     label: string;
-    /** The chip glyph (a `@lucide/vue` icon or any component). */
+    /** The member glyph (a `@lucide/vue` icon or any component). */
     icon?: Component;
+    /** Optional per-member select handler (fired alongside the model write). */
+    onSelect?: () => void;
 }
 /**
  * BA.W-DOCK-SECTIONS — the three named zone kinds the declarative `<DockSection>`
@@ -42,12 +46,12 @@ export interface DockSectionDescriptor {
     /** Optional accessible label for the grouped zone. */
     label?: string;
     /**
-     * For a `section` kind: the contextual facets this section carries. When present
-     * (length > 1) the section's facets are the rail's chips (the W-RAIL3 move OUT of
-     * the dock body — the facets ride the seam rail, never re-inflate the box). The
-     * descriptor names them; `<DockRail :items>` renders them.
+     * 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 DockRailItem[];
+    layers?: readonly DockStackItem[];
 }
 /**
  * The ONE dock-morph spring authority — the iOS-26 interruptible-physics tuning the

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

@@ -7,8 +7,8 @@ export { default as DockTabButton } from "./DockTabButton.vue";
 export { default as DockSelectTrigger } from "./DockSelectTrigger.vue";
 export { default as DockDropdownTrigger } from "./DockDropdownTrigger.vue";
 export { default as DockSeparator } from "./DockSeparator.vue";
-export { default as DockRail } from "./DockRail.vue";
-export type { DockRailItem } from "./constants";
+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";
@@ -16,3 +16,6 @@ export { useLayerTransition } from "./composables";
 export type { UseLayerTransitionOptions, UseLayerTransitionReturn, } from "./composables";
 export { DOCK_CONTEXT_KEY, useDockContext, useOptionalDockContext, provideDockContext, type DockContext, type DockOrientation, type DockLayout, } from "./composables/dockContext";
 export { useDockOrientationMorph, type DockMorphOrientation, type UseDockOrientationMorphOptions, type UseDockOrientationMorphReturn, } from "./composables/useDockOrientationMorph";
+export { useDockCtaReceive, type UseDockCtaReceiveOptions, type UseDockCtaReceiveReturn, type DockCtaReceivePreset, } from "../../../composables/motion/useDockCtaReceive";
+export { useDockSearch } from "./composables";
+export type { UseDockSearchOptions, UseDockSearchReturn } from "./composables";

package/dist/components/custom/dot-flow-field/DotFlowField.vue.d.ts

@@ -1,18 +1,22 @@
 import type { FlowFieldConfig } from "./constants";
 /**
- * DotFlowField — small dots seeded along undulating streamlines, rippling in waves.
+ * DotFlowField — a calm anchored dot-matrix a slow LARGE wave sweeps through
+ * (BC.W-VIZ-DOTFLOW retopology — NOT the BB free-advecting particle cloud).
  *
- * A curl-noise flow field traced by advected particles, where the scalar potential
- * undulates as a Gerstner/Tessendorf sum-of-sines water-wave field (the cited SOTA
- * math — `composables/flowField.ts`). WebGPU-FIRST: the compute pass advects N
- * particles through the analytic ∇⊥ψ velocity, the render pass draws instanced
- * billboard quads; a Canvas2D point-cloud fallback steps the SAME evaluator where
- * WebGPU is absent (the ~5-10% tail). It composes `useDotFlowField` → the
- * `createGpuSubstrate` picker over the ONE canvas lifecycle leaf (offscreen-pause,
- * live-PRM freeze, consumer-owned DPR) — it never bootstraps its own context.
+ * Each dot is anchored to a deterministic lattice cell and eases toward its sub-cell
+ * displacement target with a restoring spring (no advection, no re-seed); a broad
+ * bright iso-band sweeps the lattice, lighting the dots it passes — the low-frequency
+ * Gerstner/Tessendorf sum-of-sines height (`composables/flowField.ts`). WebGPU-FIRST:
+ * the compute pass pulls the lattice to its target, the render pass draws instanced
+ * billboard quads lit by the sweeping band; a pure WebGL2 FRAGMENT fallback evaluates
+ * the SAME field where WebGPU is absent (no Canvas2D — the §E "no canvas" mandate). It
+ * composes `useDotFlowField` → the `createGpuSubstrate` picker over the ONE canvas
+ * lifecycle leaf (offscreen-pause, live-PRM freeze, the shared pointer field) — it never
+ * bootstraps its own context.
  *
- * The DEFAULT palette is the warm-cream library identity; the reference teal-on-navy
- * is a DEMO preset (presets-in-consumers — never a library token).
+ * The DEFAULT palette is the warm-cream library identity; the mono-dim-on-near-black
+ * reference + the globe mask are DEMO presets (presets-in-consumers — never a library
+ * token). The teal-on-navy is GONE entirely (clean break).
  */
 type __VLS_Props = {
     /** The full author schema (the studio's `useConfiguratorState` model). */

package/dist/components/custom/dot-flow-field/composables/flowField.d.ts

@@ -29,13 +29,55 @@ export declare function curlFBM(p: Vec2): Vec2;
 /**
  * The COMPOSITE flow velocity v(p,t): the Gerstner sum-of-sines analytic ∇⊥h PLUS the
  * `curlStrength`-weighted fbm curl-noise braiding term. The SINGLE math source the WGSL
- * compute kernel transcribes; `proof:flow-field` clause 3 round-trips the two paths.
+ * compute kernel transcribes; `proof:viz-dotflow` clause F3 round-trips the two paths.
+ *
+ * RETOPOLOGY (BC.W-VIZ-DOTFLOW). The curl domain-scale dropped 1.7→0.55 (coarse braiding,
+ * not fine chatter) per the §3.2 regime inversion. The velocity is no longer an advection
+ * integrand (the lattice does not advect) — it is the DISPLACEMENT field's perp-gradient
+ * source. `sampleDisplacement` is the per-frame sub-cell offset; `sampleVelocity` stays as
+ * the round-trip anchor + the analytic ∇⊥h the displacement reads.
  */
 export declare function sampleVelocity(p: Vec2, timeSec: number, waves: readonly WaveComponent[], windSpeed: number, curlStrength: number): Vec2;
+/** The shipped domain half-extent (the lattice is laid out over [-half, half]²). */
+export declare const FLOW_DOMAIN_HALF = 0.85;
 /**
- * Build the default 6-octave Phillips-spectrum wave ladder about a dominant wind
- * direction. Amplitudes follow `A_i ∝ exp(−1/(k_i·L)²) / k_i²` (Tessendorf §4), so the
- * field is energy-realistic. The directions spread about `windDirection` so the
- * streamlines braid like a river delta (not a flat band).
+ * The deterministic lattice origin for a particle index — the WGSL `instance_index →
+ * origin` mapping matches this EXACTLY (the F3 round-trip anchor). `cols` columns, square
+ * pitch in DOMAIN units; the grid is centered on the origin so the field reads symmetric.
+ * Index `i` walks row-major (`col = i % cols`, `row = floor(i / cols)`).
  */
-export declare function buildWaveLadder(windDirection: number, octaves?: number): WaveComponent[];
+export declare function gridOrigin(index: number, cols: number, pitch: number): Vec2;
+/**
+ * The scalar Gerstner HEIGHT at an origin — the brightness driver (the moving bright
+ * stripe the lattice paints). `h(o,t) = Σ_i A_i·sin(k_i·(D_i·o) − ω_i·t + φ_i)`, the SAME
+ * sum the velocity derives from (no second wave table). The brightness field reads at the
+ * ANCHOR (`o`), not the live position, so the sweep is stable + low-frequency.
+ */
+export declare function sampleHeight(o: Vec2, timeSec: number, waves: readonly WaveComponent[], windSpeed: number): number;
+/**
+ * The sub-cell DISPLACEMENT for an origin — the divergence-free ∇⊥h (the Gerstner perp-
+ * gradient) PLUS a faint coarse curl break. The dot eases toward `o + disp·displaceAmp`
+ * (the restoring spring lives in the kernel); this is the target offset, NOT an advection
+ * step. Capped LOW by `displaceAmp` so the dot never leaves its cell by > ~0.5 pitch.
+ */
+export declare function sampleDisplacement(o: Vec2, timeSec: number, waves: readonly WaveComponent[], windSpeed: number, curlStrength: number): Vec2;
+/**
+ * The sweeping bright-stripe band: a `smoothstep` band centered `center` width `width`
+ * over the normalized height — the moving iso-band that lights the dots it passes. The
+ * band is symmetric about the center (a soft ridge crossing the lattice as `h` sweeps).
+ */
+export declare function waveBand(h: number, center: number, width: number): number;
+/**
+ * Build the wave ladder about a dominant wind direction. BC.W-VIZ-DOTFLOW REGIME
+ * INVERSION (research/viz/dot-flow-field.md §3.2): the LOW-frequency coherent regime — a
+ * LARGE base wavelength (≈½–1 period across the view → ONE dominant sweeping wave), 2-3
+ * octaves (no fine chatter), a steep amplitude persistence (×0.38 → the base wave
+ * dominates, detail a whisper), the λ falloff floored so the finest λ ≥ ~⅓ view. The
+ * directions spread MODESTLY about `windDirection` (the sweep reads as ONE coherent form,
+ * not a braided delta).
+ *
+ * `lambda0Mul` is λ₀ as a MULTIPLE of the domain extent (default 2.5 — the §1 target);
+ * `octaves` is 2-3 (the coherent band). Amplitudes follow the Phillips falloff × the
+ * per-octave persistence so the field stays energy-realistic.
+ */
+export declare function buildWaveLadder(windDirection: number, octaves?: number, lambda0Mul?: number): WaveComponent[];