@mkbabb/glass-ui 4.0.0 → 4.1.0

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

@@ -0,0 +1,155 @@
+import type { Ref } from "vue";
+/**
+ * BB.W-CARVE4 — the dock morph MEASURE/SEAT helpers, carved out of
+ * `dockMorphContext.ts` to hold the no-god-module bound (the aurora→useAurora /
+ * goo-blob→useMetaballRenderer / fourier-field→useFourierField colocation pattern).
+ * The orchestrator stays the morph DRIVER (it owns the `SpringProgress`, the targets
+ * Set, the per-frame `--dock-morph-t` write); these are the PURE geometry + the
+ * reserved-footprint measure + the SYNCHRONOUS PRM seat it composes. `DOCK_SPRING` is
+ * byte-fenced — it lives in `../constants`, never touched here.
+ *
+ * The functions take their element/axis/target dependencies as explicit params (the
+ * orchestrator's closures collapse onto this seam) — no module-level state, so the
+ * extraction is behaviour-identical to the prior inline closures.
+ */
+/** The minimal morph-target shape the measure/seat helpers read (the orchestrator's
+ *  full `MorphTarget` structurally satisfies it). */
+export interface MorphMeasureTarget {
+    containerEl: Ref<HTMLElement | null>;
+    axis: Ref<"horizontal" | "vertical">;
+    /** PER-TARGET swap generation — the seat gates its pipeline on its own id. */
+    txId: number;
+}
+export declare function dimOf(axis: "horizontal" | "vertical"): "width" | "height";
+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
+ * `.dock-layers`). These are the pinned inner spans the outer measure must see at
+ * their OWN intrinsic `max-content`, not their collapsed pin, or the outer
+ * shrink-wraps to ~0.
+ */
+export declare function nestedTargetsWithin(outer: MorphMeasureTarget, outerEl: HTMLElement, targets: Iterable<MorphMeasureTarget>): MorphMeasureTarget[];
+/**
+ * BA-VJS-1 — force ONE nested target to its own-axis `max-content` (clearing its
+ * reserved `--dock-morph-to` footprint so it sizes to content), and return a closure
+ * that RESTORES its exact prior inline state. The restore re-writes the precise
+ * prior `inline-size`/`block-size` inline value (or removes it if there was none),
+ * so the inner's in-flight pin is byte-identical after the outer's measurement —
+ * the inner target's own spring/pin pipeline is never disturbed.
+ */
+export declare function forceNestedMaxContent(n: MorphMeasureTarget): () => void;
+/**
+ * BB.W-DOCK-MORPH-FAMILY (c) — measure the true `to` for ONE target with the
+ * morph axis forced to `max-content` (the same circular-measure escape the rAF
+ * path uses), composing the BA-VJS-1 nested-descendant `max-content` ordering so
+ * a nested group reads its TRUE intrinsic span (never `to:0`). The element is at
+ * the live painted geometry on entry; this forces+reads+restores the axis. PURE
+ * measure — no spring, no pin write.
+ */
+export declare function measureTo(t: MorphMeasureTarget, el: HTMLElement, targets: Iterable<MorphMeasureTarget>): number;
+/** The orchestrator settle callbacks the synchronous seat composes (it clears the
+ *  morph vars + nulls the leaving layer, then parks the root/spring once no target
+ *  is morphing). */
+export interface MorphSeatCallbacks {
+    /** Settle ONE target (clear its morph vars + null its leavingLayer). */
+    settleTarget(t: MorphMeasureTarget): void;
+    /** Park the shared scalar + spring once NO target is morphing. */
+    maybeSettleRoot(): void;
+}
+/**
+ * BB.W-DOCK-MORPH-FAMILY (c) — the SYNCHRONOUS PRM seat. Under
+ * `prefers-reduced-motion: reduce` there is NO morph to play, so the geometry +
+ * the scalar seat at the target in ONE step (the `useDockOrientationMorph.pin()`
+ * precedent transplanted onto the collapse/expand path): measure the true `to`
+ * (composing the BA-VJS-1 nested ordering), write the box at `to` (the
+ * reserved-footprint reads at scale 1), and set `--dock-morph-t` to the endpoint
+ * for THIS swap — then clear the morph state immediately (no rAF measure-defer,
+ * no spring, no morph window). The box NEVER paints the collapsed `from` sliver
+ * with the scalar at 1 (the P0 terminal failure). Endpoint is the per-swap
+ * incoming-ness `1` (the new pane is fully in; the directional `--dock-expand-t`
+ * 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/composables/useLayerTransition.d.ts

@@ -68,6 +68,19 @@ export interface UseLayerTransitionReturn {
     currentLayer: Ref<string>;
     /** The layer id currently fading out, or null. */
     leavingLayer: Ref<string | null>;
+    /**
+     * BB.W-PERF-PRODUCER A′-4 — `true` while the size morph is in flight (the
+     * reactive twin of the `data-morphing` attr). A floating dock consumer reads
+     * this to hold a reka Popper re-position off the morph's critical frames.
+     */
+    morphing: Ref<boolean>;
+    /**
+     * BB.W-PERF-PRODUCER A′-4 — schedule a reka Popper re-position OFF the
+     * synchronous morph flush. Queued while a morph is live (flushed ONCE on
+     * settle, against the final box), else run on the next rAF. Defers the floating
+     * re-position only — NOT the FLIP measure.
+     */
+    deferReposition(cb: () => void): void;
 }
 /**
  * Coordinates the size morph + crossfade between grid-stacked dock layer panes.

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

@@ -0,0 +1,42 @@
+import type { FlowFieldConfig } from "./constants";
+/**
+ * DotFlowField — a calm anchored dot-matrix a slow LARGE wave sweeps through
+ * (BC.W-VIZ-DOTFLOW retopology — NOT the BB free-advecting particle cloud).
+ *
+ * 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 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). */
+    config?: FlowFieldConfig;
+    /**
+     * The declarative WCAG-2.2.2 pause seam. `v-model:paused` parks the render loop
+     * (the substrate's `manual` suspend) when `true`. Wire `<DockBackgroundToggle>`'s
+     * `@update:paused` to this `v-model`.
+     */
+    paused?: boolean;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    pause: () => void;
+    resume: () => void;
+    wake: () => void;
+    renderAt: (timeSec: number) => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:paused": (value: boolean) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:paused"?: ((value: boolean) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -0,0 +1,83 @@
+/** A 2-vector. */
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+/**
+ * One Gerstner / Tessendorf wave component. `amplitude` A_i, `wavelength` λ_i (so
+ * k_i = 2π/λ_i), `direction` in DEGREES (the unit travel direction), `phase` φ_i.
+ * `ω_i = √(g·k_i)` is derived from the dispersion relation, not stored.
+ */
+export interface WaveComponent {
+    amplitude: number;
+    wavelength: number;
+    /** Travel direction in degrees (0 = +x). */
+    direction: number;
+    phase: number;
+}
+/** Deep-water gravity constant (normalized; scales the dispersion ω). */
+export declare const FLOW_GRAVITY = 9.81;
+/**
+ * The Gerstner-sum velocity v(p,t) = ∇⊥h = (∂h/∂y, −∂h/∂x), ANALYTIC. The single
+ * math source the WGSL kernel transcribes. `windSpeed` scales the dispersion ω;
+ * `windDirection` (deg) is folded into each component's direction by the caller (the
+ * components carry their own absolute direction). Returns the un-normalized flow vector.
+ */
+export declare function gerstnerVelocity(p: Vec2, timeSec: number, waves: readonly WaveComponent[], windSpeed: number): Vec2;
+/** The 2D curl of the scalar fbm potential (the JS twin of `curlFBM`). */
+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: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;
+/**
+ * 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 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[];

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

@@ -0,0 +1,39 @@
+import type { OklchStop } from "../../../../composables/color";
+import { type FlowFieldConfig } from "../constants";
+/** The domain half-extent (the lattice spans [-half, half]²; mirrors flowField.ts). */
+export declare const FLOW_DOMAIN_HALF = 0.85;
+export interface FlowGridGeometry {
+    cols: number;
+    count: number;
+    /** The lattice pitch in DOMAIN units (the px pitch mapped to the domain). */
+    pitchDomain: number;
+}
+/** Compile-time lattice cap (mirrors the WGSL storage-buffer array bound). */
+export declare const FLOW_MAX_LATTICE = 16384;
+export declare function flowGridGeometry(gridPitchPx: number, canvasCssMin: number): FlowGridGeometry;
+export declare const FLOW_COMPUTE_UNIFORM_BYTES: number;
+export interface FlowUniformScratch {
+    buffer: ArrayBuffer;
+    f32: Float32Array;
+    i32: Int32Array;
+}
+export declare function createFlowComputeScratch(): FlowUniformScratch;
+/** Pack the compute uniforms in place. */
+export declare function packFlowComputeUniforms(scratch: FlowUniformScratch, config: FlowFieldConfig, timeSec: number, dt: number, geometry: FlowGridGeometry): FlowUniformScratch;
+export declare const FLOW_RENDER_UNIFORM_BYTES: number;
+export declare function createFlowRenderScratch(): FlowUniformScratch;
+/** The base resting brightness (the calm-lattice floor before the band lights a dot). */
+export declare const FLOW_BASE_BRIGHT = 0.22;
+/** The drift-driven size pulse (a subtle breathing; never a re-seed). */
+export declare const FLOW_SIZE_PULSE = 0.4;
+/** Pack the render uniforms in place. */
+export declare function packFlowRenderUniforms(scratch: FlowUniformScratch, config: FlowFieldConfig, timeSec: number, aspect: number, canvasCssMin: number, geometry: FlowGridGeometry, palette: OklchStop[]): FlowUniformScratch;
+/** The byte size of one lattice dot in the storage buffer (vec4<f32>). */
+export declare const FLOW_PARTICLE_BYTES = 16;
+/**
+ * Seed the lattice storage buffer: each dot starts AT its anchor origin (the restoring
+ * spring needs no initial offset). `(pos.x, pos.y, height=0, |disp|=0)` per index — the
+ * compute kernel re-derives the origin from `gridOrigin(index, cols, pitch)` each frame,
+ * so the seed only needs the starting position (the lattice settles on the first frames).
+ */
+export declare function seedLatticeBuffer(geometry: FlowGridGeometry): Float32Array;

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

@@ -0,0 +1,35 @@
+import { type Ref } from "vue";
+import { type GpuBackend } from "../../../../composables/glass/webgpu/useGpuSubstrate";
+import type { OklchStop } from "../../../../composables/color";
+import type { FlowFieldConfig } from "../constants";
+export interface UseDotFlowFieldOptions {
+    config: FlowFieldConfig;
+    /** Resolve the dot-color palette as OKLCh (the demo themes it; default warm-identity). */
+    getPalette: () => OklchStop[];
+    /** `"capture"` → renderAt-only (the deterministic π capture path). Default `"live"`. */
+    mode?: "live" | "capture";
+}
+/** The uniform handle a consumer wires its lifecycle against (backend-agnostic). */
+export interface DotFlowFieldHandle {
+    /** The resolved backend (`"webgpu"` where supported, else the WebGL2 fragment fallback). */
+    readonly backend: GpuBackend;
+    /** Park the loop (the WCAG-2.2.2 pause seam — `DockBackgroundToggle` wires this). */
+    pause: () => void;
+    /** Re-arm the loop. */
+    resume: () => void;
+    /** Re-arm a parked loop on demand (a pointer/setter that re-introduced motion). */
+    wake: () => void;
+    /** Draw one frame out-of-loop (capture / thumbnail). */
+    renderAt: (timeSec: number) => void;
+    /** The live `prefers-reduced-motion: reduce` state. */
+    readonly reducedMotion: boolean;
+    /** Tear down the renderer + release GPU/GL resources. */
+    dispose: () => void;
+}
+/**
+ * Mount the dot-flow-field renderer on `canvasRef`. The WebGPU primary runs the
+ * compute+render two-pass over the anchored lattice; the WebGL2 fallback evaluates the SAME
+ * `flowField.ts` field as a fullscreen fragment pass (the ONE math source). Returns the
+ * uniform lifecycle handle.
+ */
+export declare function useDotFlowField(canvasRef: Ref<HTMLCanvasElement | null>, options: UseDotFlowFieldOptions): DotFlowFieldHandle;

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

@@ -0,0 +1,31 @@
+import type { WebGPUCanvasFrame } from "../../../../composables/glass/webgpu/useWebGPUCanvas";
+import type { WebGLCanvasFrame } from "../../../../composables/glass/webgl/useWebGLCanvas";
+import type { OklchStop } from "../../../../composables/color";
+import type { FlowFieldConfig } from "../constants";
+export interface FlowSetupDeps {
+    canvas: HTMLCanvasElement;
+    config: FlowFieldConfig;
+    /** The resolved (ColorResolver) palette stops as OKLCh — re-read each frame so a live palette edit reaches the buffer. */
+    getPalette: () => OklchStop[];
+    /** Demand-gate (the renderer's quiescence layer — substrate-agnostic). */
+    shouldContinue: () => boolean;
+    /**
+     * The per-frame pointer hook — useDotFlowField advances the shared
+     * `usePointerVelocityField` here (the no-own-rAF discipline; the renderer's loop feeds
+     * the push-API tick). ZERO own rAF.
+     */
+    onFrame?: (timeSec: number) => void;
+}
+/**
+ * Build the dot-flow-field `setupWGPU(device, context, format)` callback. Closes over the
+ * config/palette getters + the renderer's demand gate + the pointer `onFrame` hook.
+ */
+export declare function createFlowWGPUSetup(deps: FlowSetupDeps): (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;
+/**
+ * Build the `setupGL(gl)` callback the `createGpuSubstrate` WebGL2 path invokes — a clean
+ * aurora-class fullscreen fragment pass (the retopology made the dot-lattice + brightness
+ * model fragment-friendly; the Canvas2D point-cloud is GONE, clean break). It evaluates
+ * the SAME `flowField.ts` height/displacement field the WGSL primary does, splicing the
+ * SHARED GLSL color chunk (the ONE color source → no drift between the two backends).
+ */
+export declare function createFlowGLSetup(deps: FlowSetupDeps): (gl: WebGL2RenderingContext) => WebGLCanvasFrame;