@mkbabb/glass-ui 4.0.1 → 4.2.0

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

@@ -0,0 +1,158 @@
+import { type Ref } from "vue";
+/** The three named fission CONTEXTS — each maps to a goo signature (F3). */
+export type DockSplitContext = "search" | "media" | "nav";
+/** The detach vector family a context selects. */
+export type DockSplitVector = "radial" | "lateral" | "inward-merge";
+/**
+ * BD.W-DOCK-CORE (II.2 — F-1 the headline fix). The placement axis the detached
+ * pieces TRAVEL ALONG to form the sibling island dock. The prior build let each
+ * piece scatter on its own radial center → it read as inline jitter inside the one
+ * pill, NOT a detach. A single COHERENT placement vector flies the whole piece
+ * cluster off the source plate so a second dock visibly materializes beside/above/
+ * below (the iOS-27 split read).
+ */
+export type DockSplitPlacement = "beside" | "above" | "below";
+/** The unit placement vector each `splitPlacement` flies the cluster along. */
+export declare const PLACEMENT_VECTOR: Readonly<Record<DockSplitPlacement, {
+    dx: number;
+    dy: number;
+}>>;
+/** The squish-peak register — WHEN the `useLiquidFlex` swell peaks in the travel. */
+export type DockSplitSquishPeak = "late" | "long" | "coalesce";
+/**
+ * The per-context goo-SIGNATURE descriptor (F3 — the FLOOR, DATA not three code paths).
+ * The orchestrator reads this to compute each piece's vector + stagger + neck phase; the
+ * ONE `fission-bridge.css` recipe paints whatever the pieces carry.
+ */
+export interface DockSplitSignature {
+    /** The context this signature serves. */
+    context: DockSplitContext;
+    /** The detach-vector family. */
+    vector: DockSplitVector;
+    /**
+     * How long the goo neck HOLDS before it snaps (0..1 of `--split-t`). High = the
+     * tense radial pop (neck holds to ~0.55 then snaps); the neck-break offset.
+     */
+    neckHold: number;
+    /**
+     * The per-piece stagger-rank resolver — returns piece `i`'s ordinal in the break
+     * SEQUENCE (innermost-first for radial, outside-in for lateral). The orchestrator
+     * phase-shifts each piece's `--neck-t` by `staggerStep * rank` so the N necks break
+     * in sequence, never simultaneously (the `--split-stagger * rank(i)` idiom).
+     */
+    staggerRank: (i: number, count: number) => number;
+    /** WHEN the `useLiquidFlex` squish swell peaks across the travel. */
+    squishPeak: DockSplitSquishPeak;
+}
+/** The canonical per-context signature MAP (F3 — search/media/nav, descriptor-driven). */
+export declare const DOCK_SPLIT_SIGNATURES: Readonly<Record<DockSplitContext, DockSplitSignature>>;
+/** The per-piece DIRECTION-VECTOR + rank a control registers (the MorphTarget twin). */
+export interface DockFissionPieceRegistration {
+    /** The detaching control element (its `--split-*`/`--neck-t` vars are written here). */
+    el: Ref<HTMLElement | null>;
+    /**
+     * The detach DIRECTION as a unit-ish vector in dock-local space (the bloom/peel
+     * direction). `radial` blooms `(cx_i − cx_dock)`-ward; `lateral` peels cross-axis;
+     * `inward-merge` is the negative radial. May be a getter so a live re-measure
+     * (the FLIP-measured center) re-resolves per read.
+     */
+    vector: {
+        dx: number;
+        dy: number;
+    } | (() => {
+        dx: number;
+        dy: number;
+    });
+    /**
+     * The piece's ordinal in the registration order (the `--i` the bridge reads + the
+     * input to the signature's `staggerRank`). Stable per piece.
+     */
+    rank: number;
+}
+/** The handle a registered piece holds (detach on unmount). */
+export interface DockFissionPieceHandle {
+    /** Detach this piece from the orchestrator (on the control's unmount). */
+    release(): void;
+}
+export interface UseDockFissionOptions {
+    /** The `.glass-dock` root (or the fission scope) the shared `--dock-split-t` writes to. */
+    rootEl: Ref<HTMLElement | null>;
+    /**
+     * The active signature (the context the dock is fissioning under). A `Ref` so a
+     * consumer can swap contexts; the orchestrator reads `.value` at split time.
+     */
+    signature: Ref<DockSplitSignature>;
+    /**
+     * BD.W-DOCK-CORE (II.2 — F-1). The placement the detached pieces fly to form the
+     * sibling island. A `Ref` so a consumer can swap placement. The orchestrator writes
+     * the per-piece travel along this ONE coherent vector (not per-piece radial scatter)
+     * so the cluster reads as a real detach into a second dock beside/above/below.
+     * Defaults to `"beside"`.
+     */
+    placement?: Ref<DockSplitPlacement>;
+    /**
+     * The LOW squish cap the `useLiquidFlex` recoil saturates at (≤1.08 — the anti-taffy
+     * fence). May be a getter so a live `--*-max-stretch` cascade override re-resolves.
+     * Defaults to 1.08 (the `useLiquidFlex` register).
+     */
+    maxStretch?: number | (() => number);
+    /**
+     * The seam-tension cap (F4 — kept LOW ≈0.12, the `useLiquidFlex` maxStretch
+     * register). A fast pull THINS the neck via the existing `clip-path` channel up to
+     * this cap, saturating — never a taffy-pull.
+     */
+    seamTensionCap?: number;
+    /**
+     * The seam-tension velocity gain `k` — `--seam-tension = clamp(0, speed·k, cap)`.
+     * Defaults to 0.6 (a calm gain over the normalized-host velocity).
+     */
+    seamTensionGain?: number;
+    /**
+     * The per-rank stagger STEP — the `--neck-t` phase shift per stagger-rank so the N
+     * necks break in sequence (the `--split-stagger * rank` idiom). Defaults to 0.08.
+     */
+    staggerStep?: number;
+    /** Honor `prefers-reduced-motion: reduce` → instant sync-seat (F5). Default true. */
+    respectReducedMotion?: boolean;
+}
+export interface UseDockFissionReturn {
+    /** The live split scalar (0 rest → 1 fissioned), the last value the spring wrote. */
+    readonly t: Readonly<Ref<number>>;
+    /** True while the dock is fissioned (or mid-fission past the threshold). */
+    readonly fissioned: Readonly<Ref<boolean>>;
+    /**
+     * Register a surviving control as a fission PIECE (the `Set<MorphTarget>` pattern).
+     * The piece carries its DIRECTION-VECTOR + rank; the orchestrator writes its
+     * `--split-dx`/`--split-dy`/`--i`/`--neck-t` off the active signature.
+     */
+    registerPiece(reg: DockFissionPieceRegistration): DockFissionPieceHandle;
+    /** SPLIT — run the scalar 0→1 (carve the pill into the N pieces). */
+    split(): void;
+    /** RE-MERGE — run the scalar 1→0 (the SAME loop, target flipped — F2 bidirectional). */
+    merge(): void;
+    /** Toggle split↔merge from the current state. */
+    toggle(): void;
+    /**
+     * The `@pointermove` handler the consumer binds on the dock host — feeds the raw
+     * pointer to the velocity field (the field is ticked from INSIDE the driver loop).
+     * PRM-gated by the field itself.
+     */
+    onPointerMove(event: PointerEvent): void;
+    /** Tear down the spring + the field listener (auto-run on scope dispose). */
+    dispose(): void;
+}
+/**
+ * The n-ary detach orchestrator. ONE `SpringProgress` on `DOCK_SPRING` writing
+ * `--dock-split-t` + per-piece `--split-dx`/`--split-dy`/`--i`/`--neck-t` off the active
+ * `DockSplitSignature`, the snap-recoil on `useLiquidFlex`, the seam-tension on
+ * `usePointerVelocityField` (fed from inside the ONE loop), PRM sync-seated. See the
+ * module header for the load-bearing-reuse + box-inviolate rationale.
+ *
+ * @example
+ * ```ts
+ * const fission = useDockFission({ rootEl, signature })
+ * const h = fission.registerPiece({ el: searchIconRef, vector: { dx: -1, dy: 0 }, rank: 0 })
+ * fission.split()    // the pill carves into the pieces along the signature
+ * ```
+ */
+export declare function useDockFission(options: UseDockFissionOptions): UseDockFissionReturn;

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

@@ -0,0 +1,18 @@
+import { type Ref } from "vue";
+export interface UseDockItemDragParams {
+    /** The dock root element (the items live in its active layer). */
+    rootEl: Ref<HTMLElement | null>;
+    /** Whether the axis is armed (the `:draggable-items` prop). May be a getter. */
+    enabled: () => boolean;
+    /** The morph axis (`"x"` horizontal · `"y"` vertical). A getter (orientation flips). */
+    axis: () => "x" | "y";
+    /** Fired once on settle with the committed (from, to) item indices. */
+    onReorder?: (from: number, to: number) => void;
+}
+export interface UseDockItemDragReturn {
+    /** True while a dock item is being dragged. */
+    dragging: Readonly<Ref<boolean>>;
+    /** Tear down the gesture + listeners. */
+    detach: () => void;
+}
+export declare function useDockItemDrag(params: UseDockItemDragParams): UseDockItemDragReturn;

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,55 @@ 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;
+    /**
+     * BD.W-DOCK-CORE (A13 / II.2) — arm the SHIPPED fission seam (additive, default
+     * `false`). When true the dock composes `useDockFission` (the n-ary detach
+     * orchestrator on the SAME `DOCK_SPRING` clock, BESIDE the morph engine — box-
+     * INVIOLATE, never editing `dockMorphContext`), auto-registers every child marked
+     * `data-dock-splittable` as a fission PIECE (its detach vector derived from its
+     * FLIP-measured center relative to the dock center), feeds the seam-tension on
+     * `@pointermove`, and exposes `split()`/`merge()`/`toggle()` via `defineExpose`. A
+     * non-splittable dock is byte-identical to HEAD. The ONE `<GooFilter>` mount must be mounted
+     * once at the app root (the goo `<filter>` the necks reference).
+     */
+    splittable?: boolean;
+    /**
+     * BD.W-DOCK-CORE (A13) — the fission CONTEXT (the `DOCK_SPLIT_SIGNATURES` row): the
+     * detach-vector family + neck stagger. `"nav"` (default) is inward-merge; `"search"`
+     * is a radial bloom; `"media"` is a lateral peel.
+     */
+    splitContext?: "search" | "media" | "nav";
+    /**
+     * BD.W-DOCK-CORE (A13) — where the detached sibling dock lands (reads the split
+     * vector). `"beside"` (default) is the radial/lateral lateral landing; `"above"`/
+     * `"below"` are the V-axis landings.
+     */
+    splitPlacement?: "beside" | "above" | "below";
+    /**
+     * BD.W-DOCK-CORE (A12) — arm the draggable-ITEMS axis (additive, default `false`).
+     * When true every child marked `data-dock-draggable` (or, lacking marks, every
+     * `.dock-icon-button` in the active layer) becomes GRABBABLE: a pointer-capture grab
+     * lets the user pull a dock item and the gesture follows ~1:1 with a volume-preserving
+     * gel-squish (the SHIPPED `useDragMorph` composing kf `Draggable` + `useLiquidFlex`
+     * "tanh" velocity-squish — NO second drag engine), then flings velocity-continuously to
+     * the nearest slot, committing a REORDER via `update:order`. Compositor-only
+     * (`transform: translate` — never a layout property); PRM-safe (the gesture still
+     * functions, the squish off, the release an instant nearest-snap); the roving-tabindex
+     * keyboard contract on the dock controls is preserved (a draggable strip that is
+     * keyboard-dead is the worse failure). A non-draggable dock is byte-identical to HEAD.
+     */
+    draggableItems?: boolean;
 }
 /** The resolved shell-prop computeds the GlassDock SFC binds. */
 export interface DockShellProps {

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

@@ -1,18 +1,33 @@
 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;
+    /**
+     * BE.W-DOCK-RAIL-REALIZE — the per-FACET accent hue (the `mode="facets"` context
+     * carousel only — IGNORED by the macOS `mode="stack"` glyph fan). A complete
+     * `<color>` (a consumer DATA/context hue) written to the chip's `--glass-accent`
+     * (the BB.W-GLASS-ACCENT per-instance chromatic-rim axis, `rim.css`/`material.css`),
+     * so each context facet carries its OWN rim+glint hue — the AZ context-carousel
+     * identity. Unset ⇒ the neutral warm-cream rim (the `--glass-accent: transparent`
+     * no-op floor). NOT a plate-background fill (the accent rides the THIN rim/glint;
+     * presets-in-consumers — no consumer hue enters a library token).
+     */
+    accent?: string;
 }
 /**
  * BA.W-DOCK-SECTIONS — the three named zone kinds the declarative `<DockSection>`
@@ -42,12 +57,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
@@ -57,8 +72,8 @@ export interface DockSectionDescriptor {
  * prior copies were a DRY hazard — a re-tune had to touch both).
  */
 export declare const DOCK_SPRING: {
-    readonly response: 0.32;
-    readonly dampingFraction: 0.7;
+    readonly response: number;
+    readonly dampingFraction: number;
 };
 /**
  * The CSS properties whose `transitionend` the dock-morph window watches to know a
@@ -80,4 +95,4 @@ export declare const DOCK_MORPH_LABEL = "glass-ui:dock-morph-context";
  *  edge sweeping past the cursor, not a real exit. */
 export declare const HOVER_INTENT_MS = 60;
 export declare const EDGE_BAND_PX = 24;
-export declare const MORPH_SETTLE_MS = 320;
+export declare const MORPH_SETTLE_MS = 840;

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

@@ -6,9 +6,10 @@ export { default as DockBackgroundToggle } from "./DockBackgroundToggle.vue";
 export { default as DockTabButton } from "./DockTabButton.vue";
 export { default as DockSelectTrigger } from "./DockSelectTrigger.vue";
 export { default as DockDropdownTrigger } from "./DockDropdownTrigger.vue";
+export { default as DockPopoverTrigger } from "./DockPopoverTrigger.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 +17,8 @@ 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";
+export { GooFilter } from "../goo-filter";
+export { useDockFission, DOCK_SPLIT_SIGNATURES, type DockSplitContext, type DockSplitVector, type DockSplitSquishPeak, type DockSplitSignature, type DockFissionPieceRegistration, type DockFissionPieceHandle, type UseDockFissionOptions, type UseDockFissionReturn, } from "./composables/useDockFission";

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,76 @@ 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 cursor-vortex lever set (the √φ-laddered radius + the spin/drag/burst gains). */
+export interface VortexParams {
+    cursor: Vec2;
+    /** Pointer velocity (domain units / sec). */
+    pointerVel: Vec2;
+    /** Flick-burst impulse 0..1. */
+    burst: number;
+    /** Pointer active? (inert when false — the vortex is off). */
+    active: boolean;
+    radius: number;
+    spin: number;
+    dragGain: number;
+    burstShove: number;
+}
+/**
+ * The velocity the cursor injects at `p` — the perturbation `cs_flow` adds to the curl
+ * current. A true tangential vortex (∇⊥ of the radial), plus a drag-along (the streamlines
+ * follow the gesture) and a radial flick shove (the shockwave), all gaussian-falling off the
+ * vortex radius. Returns the un-normalized perturbation in domain/sec.
+ */
+export declare function pointerVortex(p: Vec2, v: VortexParams): 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 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).
+ * 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): WaveComponent[];
+export declare function buildWaveLadder(windDirection: number, octaves?: number, lambda0Mul?: number): WaveComponent[];

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

@@ -0,0 +1,8 @@
+export declare function compileGL(gl: WebGL2RenderingContext, type: number, src: string): WebGLShader;
+export declare function linkGL(gl: WebGL2RenderingContext, vsSrc: string, fsSrc: string): WebGLProgram;
+/** Probe whether an internal format is color-renderable as a float FBO target (R-A). */
+export declare function probeRenderable(gl: WebGL2RenderingContext, internal: number, type: number): boolean;
+/** Pack a Float32Array to half-float (RGBA16F upload) — the RGBA32F-absent fallback (R-A). */
+export declare function float32ToHalf(src: Float32Array): Uint16Array;
+/** IEEE-754 float32 → float16 bits (the standard round-to-nearest packing). */
+export declare function f32ToF16(val: number): number;

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

@@ -0,0 +1,9 @@
+import type { WebGLCanvasFrame } from "../../../../composables/glass/webgl/useWebGLCanvas";
+import { type FlowSetupDeps } from "./useFlowParticles";
+/**
+ * Build the `setupGL(gl)` callback the picker invokes on the WebGL2 path (the LIVE path).
+ * `field` is the kept fullscreen-fragment dot-lattice; `flow` routes to the state-texture
+ * GPGPU + two-FBO trail + point-sprite motes + present composite (flowSetupGLFlow) — the SAME
+ * advected-population gestalt as the WGPU compute path (the ONE math source via the GLSL chunk).
+ */
+export declare function createFlowGLSetup(deps: FlowSetupDeps): (gl: WebGL2RenderingContext) => WebGLCanvasFrame;

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

@@ -0,0 +1,12 @@
+import type { WebGLCanvasFrame } from "../../../../composables/glass/webgl/useWebGLCanvas";
+import { type FlowSetupDeps } from "./useFlowParticles";
+/**
+ * The `flow` WebGL2 channel — the AURORA CURRENT, made real + measurable + equal-gestalt:
+ *   1. STATE-TEXTURE GPGPU advect pass (one texel per mote; pos/speed/life ping-pong),
+ *   2. TRAIL decay-blit (prev → cur at the derived α) on a two-FBO RGBA16F ping-pong,
+ *   3. MOTE point-sprite draw (additive into the trail; speed→hue/brightness),
+ *   4. PRESENT composite (trail over the warm floor + corner-bloom → the swapchain).
+ * The float state/trail RTs fall RGBA32F→RGBA16F where the render extension is absent (R-A);
+ * the trail is pinned NEAREST (no half-float-linear extension dependency).
+ */
+export declare function createFlowGLFlow(deps: FlowSetupDeps): (gl: WebGL2RenderingContext) => WebGLCanvasFrame;

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

@@ -0,0 +1,7 @@
+import type { WebGPUCanvasFrame } from "../../../../composables/glass/webgpu/useWebGPUCanvas";
+import { type FlowSetupDeps } from "./useFlowParticles";
+/**
+ * Build the dot-flow-field `setupWGPU(device, context, format)` callback. Closes over the
+ * config/palette getters + the renderer's demand gate + the pointer `onFrame`/`getPointer`.
+ */
+export declare function createFlowWGPUSetup(deps: FlowSetupDeps): (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;