@mkbabb/glass-ui 4.2.0 → 6.0.0

package/dist/components/configurator/ConfiguratorRow.vue.d.ts

@@ -0,0 +1,96 @@
+import { type HTMLAttributes } from "vue";
+import { type ConfiguratorSize } from "./size";
+/**
+ * <ConfiguratorRow> — labeled control row for a single field inside a
+ * <ConfiguratorLayer>. Mirrors the demo's PresetEditorField surface
+ * (label + token-name + optional reset + description) but ships from
+ * the library so consumers can compose configurators without re-rolling
+ * the row layout.
+ *
+ * Slot consumes the actual control (Slider, Select, Switch, NumberField,
+ * etc.). The reset button is opt-in via `canReset`; emits a `reset`
+ * event the consumer wires to its own field-clear path.
+ *
+ * # The double-label API (value.js L14)
+ *
+ * The label header is a first-class TRIPLE: `label` (the primary, sans /
+ * medium), the optional `sub` (a SECONDARY descriptive label — sans, muted —
+ * paired inline with the primary), and the optional `name` (the mono token /
+ * spec reference, or a live numeric readout). All three are declarative props,
+ * so a consumer expresses a "double-label" row (primary + secondary) WITHOUT a
+ * `:deep()` reach into the slot or a hand-rolled in-slot sans+mono pair. Use
+ * `sub` for a descriptive secondary label and `name` for a mono token/value.
+ *
+ * # Size axis (BH.W-SIZE-UNIFY)
+ *
+ * The row honors a three-rung size axis (`sm` | `md` | `lg`).
+ * Resolution order:
+ *
+ * 1. Local `size` prop (highest priority).
+ * 2. `<Configurator>` inject (`CONFIGURATOR_SIZE_KEY`).
+ * 3. `undefined` — the row keeps its baked-in `gap-1.5 py-2` recipe and
+ *    emits no `data-size` attribute (bare-row visual preserved).
+ *
+ * When size resolves to a value, the root gets `data-size="…"`
+ * and the token-driven CSS rule overrides the Tailwind gap. The
+ * `"md"` rung is functionally identical to the no-size
+ * fallback; it exists so consumers can be explicit.
+ *
+ * # ConfiguratorRow vs LabeledField — recorded divergence (AZ.W-METRIC-UNIFY §B)
+ *
+ * Both are "label (+ meta) above/beside a slotted control", but they are NOT
+ * interchangeable — they emphasize DIFFERENT features:
+ *  - **ConfiguratorRow** (this) — for TOKEN / PRESET controls. Carries the
+ *    token-`name` reference, the opt-in `reset` affordance (`canReset`), and the
+ *    three-rung `size` axis (local-prop-over-inject). No a11y for/id wiring.
+ *  - **LabeledField** — for FORM fields. Carries the `for`/`id` label↔control
+ *    a11y wiring (`controlId`/`labelId`/`errorId`), the `tooltip`, the `required`
+ *    asterisk, and the `aria-live` `error` region.
+ *
+ * Reach for ConfiguratorRow inside a `<Configurator>` for token sliders/selects;
+ * reach for LabeledField for accessible form inputs. The divergence is recorded
+ * (NOT a forced merge — no ≥2-consumer shared-chassis need surfaced) in
+ * `docs/precepts/design-idioms.md §9`, alongside the `cn`/`focus-ring` keeps.
+ */
+type __VLS_Props = {
+    /** Display label (top-left, primary). */
+    label: string;
+    /**
+     * Optional SECONDARY label (value.js L14 — the double-label API). A
+     * descriptive secondary rung paired inline with the primary `label` (sans,
+     * muted), distinct from the mono `name` token/value. Lets a consumer express
+     * a two-part label declaratively — no `:deep()` reach, no in-slot label pair.
+     */
+    sub?: string;
+    /** Optional token name / spec reference (right of label, monospaced). */
+    name?: string;
+    /** Optional helper / value description (below the control). */
+    description?: string;
+    /** Show the reset affordance (top-right). */
+    canReset?: boolean;
+    /**
+     * Size rung. Overrides the value injected by an ancestor
+     * `<Configurator>` when set. Omit to follow the inject (or to fall
+     * back to the pre-N.W2 `gap-1.5 py-2` recipe when there is no
+     * ancestor configurator).
+     */
+    size?: ConfiguratorSize;
+    class?: HTMLAttributes["class"];
+};
+declare var __VLS_12: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_12) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    reset: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onReset?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/configurator/index.d.ts

@@ -0,0 +1,6 @@
+export { default as Configurator } from "./Configurator.vue";
+export { default as ConfiguratorLayer } from "./ConfiguratorLayer.vue";
+export { default as ConfiguratorRow } from "./ConfiguratorRow.vue";
+export type { ConfiguratorAsideSide, ConfiguratorGalleryPlacement, ConfiguratorPreset, ConfiguratorScrollMode, } from "./Configurator.vue";
+export { CONFIGURATOR_SIZE_KEY, provideConfiguratorSize, useOptionalConfiguratorSize, type ConfiguratorSize, } from "./size";
+export { useConfiguratorState, type ConfiguratorCloneMode, type ConfiguratorState, type ConfiguratorStateOptions, } from "./useConfiguratorState";

package/dist/components/configurator/size.d.ts

@@ -0,0 +1,26 @@
+import type { ComputedRef } from "vue";
+/**
+ * Size axis for `<Configurator>` + `<ConfiguratorRow>` (BH.W-SIZE-UNIFY — the
+ * clean-break of the size/density collision onto the shared Size ordinal). The old
+ * `"mobile"` rung is DROPPED — a coarse-pointer state is a `@media(pointer:coarse)`
+ * concern, never a scale rung (axes.ts §sub-range-law).
+ *
+ * - `"sm"`  — slightly tighter than the default; dense studios (was `"compact"`).
+ * - `"md"`  — current default; matches the `gap-1.5 py-2` recipe (was `"comfortable"`).
+ * - `"lg"`  — generous gap; demo / settings-page surface (was `"spacious"`).
+ *
+ * The `<Configurator>` provides its `size` prop to descendants via
+ * `provide`/`inject` (key: `configuratorSize`). A `<ConfiguratorRow>` may override
+ * locally by setting its own `size` prop — prop wins over inject. When neither is
+ * set, the row falls back to `md` and NO `data-size` attribute is emitted, so the
+ * bare-row visual is bit-for-bit preserved.
+ */
+export type ConfiguratorSize = "sm" | "md" | "lg";
+export declare const CONFIGURATOR_SIZE_KEY: import("vue").InjectionKey<ComputedRef<ConfiguratorSize>>;
+export declare function provideConfiguratorSize(size: ComputedRef<ConfiguratorSize>): void;
+/**
+ * Befitting silent default — returns `null` when there is no ancestor
+ * `<Configurator>`. The consumer null-coalesces to `undefined` so the
+ * `:data-size` binding emits no attribute (bare-row visual preserved).
+ */
+export declare const useOptionalConfiguratorSize: () => ComputedRef<ConfiguratorSize> | null;

package/dist/components/configurator/styles.css

@@ -0,0 +1 @@
+:root { --configurator-pad-inline: 1rem; --configurator-section-gap: 0.5rem; } .configurator-section-label { font-family: var(--font-text); font-size: var(--configurator-section-size); line-height: var(--type-leading-body); font-weight: var(--configurator-section-weight); letter-spacing: var(--type-tracking-tight); color: var(--foreground); } .configurator-presets { padding-block: var(--configurator-preset-row-weight); } .configurator-presets .configurator-gallery-track, .configurator-presets [role="group"] { gap: var(--configurator-preset-row-gap); } .configurator-layer { border-color: var(--configurator-divider-section); background-color: var(--configurator-section-tint); border-radius: max( var(--radius-floor), calc(var(--radius-ctx) - var(--radius-inset)) ); } .configurator-layer + .configurator-layer { margin-block-start: var(--configurator-section-gap); } .configurator-layer-trigger { padding-inline: var(--configurator-pad-inline); } .configurator-layer-body { padding-inline: var(--configurator-pad-inline); } .configurator-layer-body[data-dividers] > * + * { border-color: var(--configurator-divider); } .configurator-aside, .configurator-presets, .configurator-footer { border-color: var(--configurator-divider); } [data-slot="configurator"] > [data-gallery-dock] { grid-row: 1; grid-column: 1; } [data-slot="configurator"] > .configurator-stage { grid-row: 2; grid-column: 1; } [data-slot="configurator"] > .configurator-aside { grid-row: 3; grid-column: 1; } @media (min-width: 1024px) { [data-slot="configurator"] { grid-template-columns: minmax(0, 1fr) minmax( var(--configurator-aside-min, 280px), var(--configurator-aside-max, 360px) ); grid-template-rows: auto minmax(0, 1fr); } [data-slot="configurator"][data-gallery="aside"] > [data-gallery-dock] { grid-row: 1; grid-column: 2; } [data-slot="configurator"][data-gallery="aside"] > .configurator-stage { grid-row: 1 / span 2; grid-column: 1; } [data-slot="configurator"][data-gallery="aside"] > .configurator-aside { grid-row: 2; grid-column: 2; } [data-slot="configurator"][data-gallery="top"] > [data-gallery-dock] { grid-row: 1; grid-column: 1 / span 2; } [data-slot="configurator"][data-gallery="top"] > .configurator-stage { grid-row: 2; grid-column: 1; } [data-slot="configurator"][data-gallery="top"] > .configurator-aside { grid-row: 2; grid-column: 2; } } [data-slot="configurator"] > [data-gallery-dock] { border-color: var(--configurator-divider); } [data-slot="configurator"][data-gallery="aside"] > [data-gallery-dock] { border-bottom-width: 1px; } @media (min-width: 1024px) { [data-slot="configurator"][data-gallery="top"] > [data-gallery-dock] { border-bottom-width: 1px; } } .configurator-preset-tile { inline-size: clamp(160px, 22vw, 232px); border-radius: var(--radius-card); } [data-slot="configurator"][data-gallery="top"] .configurator-preset-tile { inline-size: clamp(200px, 20vw, 288px); } .configurator-preset-well { background-size: cover; background-position: center; image-rendering: auto; } .configurator-preset-well.is-loading { background-image: linear-gradient( 100deg, color-mix(in oklab, var(--card) 84%, transparent) 30%, color-mix(in oklab, var(--foreground) 8%, var(--card)) 50%, color-mix(in oklab, var(--card) 84%, transparent) 70% ); background-size: 200% 100%; animation: configurator-preset-shimmer 1.2s ease-in-out infinite; } @media (prefers-reduced-motion: reduce) { .configurator-preset-well.is-loading { animation: none; } } @keyframes configurator-preset-shimmer { from { background-position: 200% 0; } to { background-position: -200% 0; } } .configurator-preset-tile.is-active { box-shadow: inset 0 0 0 2px var(--focus-ring-color), var(--shadow-cartoon-lg); } .configurator-preset-chip { border-radius: var(--radius-pill); } .configurator-preset-chip.is-active { --glass-capsule-fill: var(--glass-bg-quiet); } @media (min-width: 1024px) { [data-slot="configurator"][data-aside-side="left"] > .configurator-stage { grid-column: 2; } [data-slot="configurator"][data-aside-side="left"] > .configurator-aside { grid-column: 1; } [data-slot="configurator"][data-aside-side="left"][data-gallery="aside"] > [data-gallery-dock] { grid-column: 1; } }

package/dist/components/constellation/Constellation.vue.d.ts

@@ -0,0 +1,39 @@
+import { type ConstellationProps } from "./constellationField";
+import type { RendererStatus } from "../../composables/glass/webgpu/rendererStatus";
+declare const __VLS_export: import("vue").DefineComponent<ConstellationProps, import("./composables/useConstellation").ConstellationExpose, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    rendererStatus: (status: RendererStatus) => any;
+}, string, import("vue").PublicProps, Readonly<ConstellationProps> & Readonly<{
+    onRendererStatus?: ((status: RendererStatus) => any) | undefined;
+}>, {
+    link: number;
+    speed: number;
+    count: number;
+    opacityCeiling: number;
+    parallax: number;
+    pointerReactive: boolean;
+    warpOnClick: boolean;
+    wander: boolean | {
+        minIdle?: number;
+        jitter?: number;
+    };
+    gravityWell: boolean | {
+        holdMs?: number;
+        gain?: number;
+        reach?: number;
+        ramp?: number;
+        maxSpeed?: number;
+        soften?: number;
+    };
+    pinned: boolean | number;
+    accentEdges: boolean;
+    pinnedDrift: boolean | {
+        wanderFrac?: number;
+        durMs?: number;
+        minIdle?: number;
+        jitter?: number;
+    };
+    warpAutoRelease: boolean;
+    backgroundInteractive: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/constellation/composables/useConstellation.d.ts

@@ -0,0 +1,26 @@
+import { type Ref } from "vue";
+import { type ConstellationField, type ConstellationProps } from "../constellationField";
+import { type RendererStatus } from "../../../composables/glass/webgpu/rendererStatus";
+export interface ConstellationRoutePointerRead {
+    x: number;
+    y: number;
+    active: boolean;
+}
+export interface UseConstellationOptions {
+    /** Optional route-owned pointer feed for a non-interactive background field. */
+    routePointer?: () => ConstellationRoutePointerRead | null;
+}
+export interface ConstellationExpose {
+    field: ConstellationField;
+    isFrozen: Ref<boolean>;
+    warpTo(a: {
+        x: number;
+        y: number;
+    } | number, b?: number): number;
+    holdWellAt(x: number, y: number): boolean;
+    releaseWell(): void;
+    warpSettled(): boolean;
+    pinNode(idx: number): void;
+    rendererStatus: Readonly<Ref<RendererStatus>>;
+}
+export declare function useConstellation(props: ConstellationProps, hostRef: Ref<HTMLElement | null>, canvasRef: Ref<HTMLCanvasElement | null>, options?: UseConstellationOptions): ConstellationExpose;

package/dist/components/constellation/constants.d.ts

@@ -0,0 +1,87 @@
+import type { ConstellationPalette, ConstellationWellConfig } from "./constellationField";
+/**
+ * The reference layout width (px) the field's node geometry is authored against. A
+ * live canvas's `k = width / BASE_WIDTH` scales every base-width length (the well
+ * reach/speed, the node spacing) so a 600px and a 1280px canvas read the same shape.
+ */
+export declare const BASE_WIDTH = 1280;
+/**
+ * The neutral palette FALLBACK the draw passes read when the `--constellation-*`
+ * color/alpha tokens are absent (SSR / no-token mount). The fallbacks mirror the §5c
+ * light-arm token defaults so a no-token mount still reads recessive-but-legible.
+ *
+ * `accent`/`edgeFloor`/`edgeAccentAlpha` (AZ.W-CON-GEN G3) are the ACCENT-edge skin
+ * weights the optional `drawEdges(…, accentIndex)` pass reads — the flagged-node EDGE
+ * tint. `accent` mirrors the `--constellation-accent` neutral library default;
+ * `edgeFloor: 0` is the byte-identity (no floor by default — a consumer lifts it so a
+ * distance-faded hairline clears the perceptual floor on a bright ground);
+ * `edgeAccentAlpha: 0.30` is the accent-incident edge multiplier.
+ */
+export declare const DEFAULT_PALETTE: ConstellationPalette;
+/**
+ * Warp spring DEFAULTS — `--constellation-warp-*` tokens override these on mount.
+ * `WARP_RESPONSE` is the keyframes.js angular PERIOD (s, NOT a settle-duration);
+ * `WARP_ZETA = 1.0` is critically damped so a focal mark never rings/overshoots.
+ */
+export declare const WARP_RESPONSE = 0.55;
+export declare const WARP_ZETA = 1;
+/**
+ * Gravity-well tuning DEFAULTS (AY.W-CON2). The `--constellation-well-*` tokens
+ * override these on mount via `field.well.cfg`; these stay the fallback. SET by the
+ * §6 egg-live π readback (the field-perturbs-then-cools capture is the binding
+ * truth) — a moderate gain over a generous reach, a brisk ramp, a tight no-slingshot
+ * speed cap, and the singularity-soften floor.
+ */
+export declare const DEFAULT_WELL_CONFIG: ConstellationWellConfig;
+/**
+ * Auto-DRIFT cadence DEFAULTS (AY.W-CON1 source; tokenised in AY.W-CON2). The
+ * `--constellation-wander-idle`/`-wander-jitter` tokens override these on mount; a
+ * prop `{ minIdle, jitter }` still wins over the token. The 8s/8s default rhythm
+ * re-targets the focal mark every 8–16s (the slides cadence).
+ */
+export declare const DEFAULT_WANDER_IDLE = 8000;
+export declare const DEFAULT_WANDER_JITTER = 8000;
+/**
+ * Autonomous PINNED-ANCHOR drift cadence DEFAULTS (AZ.W-CON-GEN G5). DISTINCT from
+ * `wander` (which re-targets the WARP spring among random nodes): this gently eases
+ * the PINNED node (`field.pinnedIndex`) around its seeded ANCHOR on a jittered
+ * cadence — the flagged point breathes its neighborhood without leaving it. The
+ * `--constellation-pinned-drift-*` tokens override these on mount; a prop still wins.
+ * `wanderFrac` (±0.14 of the canvas) keeps the pinned node clear of the hero type
+ * even as it drifts; `durMs` is the per-leg easeInOutQuad duration; the idle/jitter
+ * is the rest between legs (a long, calm rhythm, NOT a metronome).
+ */
+export declare const DEFAULT_PINNED_DRIFT_FRAC = 0.14;
+export declare const DEFAULT_PINNED_DRIFT_DUR = 2600;
+export declare const DEFAULT_PINNED_DRIFT_IDLE = 6000;
+export declare const DEFAULT_PINNED_DRIFT_JITTER = 8000;
+/** R5-8 — the shipped visual-size floor: `kVisOf` === `k` for every canvas
+ *  ≥ ~0.72·BASE_WIDTH ≈ 922px (incl. the 1280 export frame — byte-identical
+ *  there by construction); below it the marks stop crushing sub-pixel. */
+export declare const DEFAULT_K_FLOOR = 0.72;
+/** Maximum public node count; keeps the quadratic proximity scan bounded. */
+export declare const MAX_NODES = 256;
+/**
+ * Per-node paint-density budget. A denser neighborhood drops its weakest edges so a
+ * pathological link radius cannot turn the quiet lattice into an opaque mesh.
+ */
+export declare const MAX_DEGREE = 12;
+/** Maximum painted edges (`MAX_NODES · MAX_DEGREE`). */
+export declare const E_MAX: number;
+/**
+ * The pointer-parallax depth default (§6). Each node carries a seeded depth `z ∈ [0,1]`;
+ * the pointer offsets node screen positions by `parallax · z · (pointer − center)` — a
+ * cheap pointer-parallax giving the flat lattice apparent depth (the Awwwards "living
+ * network" register). DEFAULT-OFF (`0` — the flat lattice). The prior default-on `0.08`
+ * slid the WHOLE lattice ~58px on a center→corner pointer sweep (every node tracked the
+ * cursor, read as a bug, not depth — `proof` D1-constellation live measure). Depth is now
+ * OPT-IN: a consumer that wants the living-network parallax passes `parallax` (e.g. a
+ * sub-perceptual `0.02`); the bare lattice never tracks the cursor.
+ */
+export declare const DEFAULT_PARALLAX = 0;
+/**
+ * Base Canvas2D node-radius band in CSS px. `seedField` rolls each node's radius in
+ * `[NODE_R_MIN, NODE_R_MIN + NODE_R_SPREAD)`.
+ */
+export declare const NODE_R_MIN = 1.6;
+export declare const NODE_R_SPREAD = 1.6;

package/dist/components/constellation/constellationField.d.ts

@@ -0,0 +1,70 @@
+export { BASE_WIDTH } from "./constants";
+export type * from "./constellationTypes";
+import type { ConstellationNode, ConstellationField, ConstellationPointer } from "./constellationTypes";
+/**
+ * Seed `count` drifting nodes inside `w × h`. `rng` is a `() => number` in
+ * `[0, 1)` (the glass-ui `mulberry32`/`Math.random`); a seeded `rng` lays out a
+ * reproducible field. Every node drifts; a focal node IS pinnable (AX.W17) — the
+ * `field.focalIndex` designation + the engine-owned `warp` spring chase a node,
+ * but the underlying node still drifts (warp re-points an EXISTING node, never
+ * adds one, so node count is conserved).
+ */
+export declare function seedField(rng: () => number, count: number, w: number, h: number, speed: number): ConstellationNode[];
+/**
+ * Re-fit the existing lattice to a NEW canvas size, proportionally, ON the
+ * size-change frame (AY.W-CON1). Without it a field seeded at a transitional
+ * size (the canvas measures mid responsive-scale — the deck slide-enter case)
+ * keeps its small-canvas positions and DRIFTS out to fill the larger box at
+ * `speed` px/frame — the visible "takes a while to expand out" lag the slides
+ * bespoke copy fixed. Scales node + warp positions by the per-axis dimension
+ * ratio; velocities are UNTOUCHED (they are base-width direction vectors
+ * `k`-scaled at step time — scaling them would HEAT the field, breaking the
+ * cool-down invariant). No-op on first layout (`prev ≤ 0`; the seed path owns
+ * it) or unchanged dims.
+ */
+export declare function refitField(field: ConstellationField, prevW: number, prevH: number): void;
+/**
+ * Advance the field one step: drift + wall-bounce every node, then (if the
+ * pointer is live) lean nodes within reach toward the cursor WITHOUT changing
+ * their speed (the slow geometric drift is preserved). `k` is the scale factor.
+ *
+ * `dt` (seconds since the previous frame) advances the focal-node warp spring
+ * via `warpStep` INSIDE this single per-frame call (AX.W17) — NO second rAF,
+ * NO `useSpring`. The warp rides the substrate's ONE parked rAF; a `dt` of `0`
+ * (omitted / first frame) leaves the spring untouched.
+ *
+ * `now` (ms; default `0` — every existing caller stays green) + `rng` (default
+ * `Math.random`) drive the optional auto-DRIFT cadence (AY.W-CON1): AFTER the
+ * warp step, if `field.wander` is set and `now > 0`, the cadence re-points
+ * `setWarpTarget` to a random node when it elapses AND the spring has settled
+ * (a click-warp in flight pre-empts the cadence — `warpSettled` reports false).
+ */
+export declare function stepField(field: ConstellationField, k: number, speed: number, pointer: ConstellationPointer | null, dt?: number, now?: number, rng?: () => number, pointerVel?: ConstellationPointer | null): void;
+import type { ConstellationEdge } from "./constellationTypes";
+/**
+ * Scan the proximity graph and return its edge SET (the `1 − d²/reach²` distance-falloff
+ * weight per pair within `reach = link·k`). `accentIndex ≥ 0` marks the edges incident on
+ * that node (the flagged-node tether). Pure + node-testable; the render loop calls it each
+ * frame and hands the result directly to the Canvas2D edge pass.
+ *
+ * `eMax` caps the result. A denser neighborhood keeps its strongest links.
+ */
+export declare function buildEdges(field: ConstellationField, link: number, accentIndex?: number, eMax?: number): ConstellationEdge[];
+/**
+ * Append the POINTER-WEB tether edges to an existing edge set (the `drawPointerWeb` math
+ * relocated): the cursor is a "virtual node" whose incident edges (to every node within
+ * `reach`) carry `focus = 1` (the render strokes them at the focus alpha). No-op when the
+ * pointer is inactive (`x < 0`). The `eMax` budget is shared with the ambient set.
+ */
+export declare function appendPointerWeb(edges: ConstellationEdge[], field: ConstellationField, link: number, pointer: ConstellationPointer | null, eMax?: number): void;
+/**
+ * The parallax-offset SCREEN position for a node (§6). Offsets the node by
+ * `parallax · z · (pointer − center)` — a cheap pointer-parallax giving the flat lattice
+ * apparent depth (deeper nodes — higher `z` — shift more, the Awwwards "living network"
+ * register). When the pointer is inactive the offset is 0 (the flat lattice). Pure; the
+ * renderer maps each node's `(x,y)` through this before painting the dot.
+ */
+export declare function parallaxNodePos(node: ConstellationNode, pointer: ConstellationPointer | null, w: number, h: number, parallax: number): {
+    x: number;
+    y: number;
+};

package/dist/components/constellation/constellationInteraction.d.ts

@@ -0,0 +1,141 @@
+import type { ConstellationField, ConstellationPinnedDrift, ConstellationWarpConfig, ConstellationWellConfig } from "./constellationField";
+import { DEFAULT_WANDER_IDLE, DEFAULT_WANDER_JITTER, DEFAULT_WELL_CONFIG, WARP_RESPONSE, WARP_ZETA, DEFAULT_PINNED_DRIFT_FRAC, DEFAULT_PINNED_DRIFT_DUR, DEFAULT_PINNED_DRIFT_IDLE, DEFAULT_PINNED_DRIFT_JITTER } from "./constants";
+export { DEFAULT_WANDER_IDLE, DEFAULT_WANDER_JITTER, DEFAULT_WELL_CONFIG, WARP_RESPONSE, WARP_ZETA };
+export { DEFAULT_PINNED_DRIFT_FRAC, DEFAULT_PINNED_DRIFT_DUR, DEFAULT_PINNED_DRIFT_IDLE, DEFAULT_PINNED_DRIFT_JITTER, };
+/**
+ * Read the NUMERIC interaction-tuning tokens (the warp spring + the gravity-well
+ * gains) off a canvas's resolved custom properties — ONCE on mount (AY.W-CON2),
+ * via `parseFloat`, NOT per-frame `getComputedStyle` (the hot loop stays clean).
+ * Returns `{ warp, well }` configs the field carries; every member falls back to
+ * the shipped default when the token is absent (an SSR / no-token mount reads the
+ * byte-identical spring). The tokens are PLAIN numbers (`0.55`, `12000`), immune
+ * to the W30 `light-dark()`-into-Canvas2D leak (they never reach a `fillStyle`).
+ */
+export declare function readInteractionConfig(canvas: HTMLCanvasElement): {
+    warp: ConstellationWarpConfig;
+    well: ConstellationWellConfig;
+    wander: {
+        minIdle: number;
+        jitter: number;
+    };
+};
+export { stepWell } from "./constellationWell";
+/**
+ * The nearest DRIFTING node to `(px, py)` in canvas-local px — a linear O(count)
+ * min-d² scan (count 64 default — negligible; matches the O(count²) edge pass).
+ * "Lattice point" = the nearest drifting NODE (the constellation has NO fixed
+ * lattice). `excludeIdx` drops a node from the candidate set (the focal node
+ * excludes ITSELF, so a cursor-on-focal warp no-ops). Returns `-1` if no
+ * eligible node exists (empty field, or only the excluded node).
+ */
+export declare function nearestNode(field: ConstellationField, px: number, py: number, excludeIdx?: number): number;
+/**
+ * Advance the focal-node warp spring one `dt` (seconds). A per-axis 2nd-order
+ * critically-damped integrator over `field.warp.{x,y}` toward the LIVE position
+ * of `field.nodes[field.warp.targetIdx]` — re-read EACH frame, so the spring
+ * CHASES a drifting target and arrives ON it (the identity-ride). No-ops when no
+ * warp is active (`targetIdx < 0`). `dt` is clamped to {@link WARP_DT_CLAMP} so a
+ * tab-throttle / offscreen-park-resume gap cannot teleport the mark.
+ *
+ *   x += v·dt ;  v += (−2ζω·v − ω²·(x − target))·dt
+ *
+ * Reads `(response, ζ)` from `field.warpCfg` (the tokenised override — AY.W-CON2),
+ * falling back to the shipped `WARP_RESPONSE`/`WARP_ZETA` defaults. `ω = 2π/response`
+ * is the keyframes.js `(response, dampingFraction)` convention (the SHARED house
+ * model — `ω₀` is the angular frequency, `response` its ANGULAR PERIOD, NOT a
+ * settle-duration; at ζ=1 the 2%-settle is `t₂ ≈ 5.83/ω₀ ≈ 0.93·response`). NO
+ * second ω formula is minted (the ω-reconcile). NOT its rAF — the FORBID-useSpring
+ * contract (a second rAF would defeat the parked-substrate one-path freeze).
+ */
+export declare function warpStep(field: ConstellationField, dt: number): void;
+/**
+ * Point the warp at a node INDEX (the live target-source seam). The focal node
+ * re-points to `idx`; the spring chases `nodes[idx]`'s LIVE position FROM the
+ * focal mark's CURRENT position (`warp.{x,y}`) — a continuous spring-eased path,
+ * never a snap. The component seeds `warp.{x,y}` at field-center on first layout,
+ * so even the first warp springs from a real start point. `idx < 0` clears the
+ * warp (the focal mark is removed). Re-pointing does NOT zero the velocity, so a
+ * mid-flight re-target curves smoothly toward the new node.
+ */
+export declare function setWarpTarget(field: ConstellationField, idx: number): void;
+/**
+ * Warp the focal node to the nearest drifting node to a canvas-LOCAL px point
+ * (the `warpTo(point)` primitive). The DEGENERATE case — the click's UNCONSTRAINED
+ * nearest node is already the current focal (cursor on/closest to the focal mark)
+ * — NO-OPS (returns the current focal; a click on yourself does not re-warp). Any
+ * OTHER click re-points to the nearest node, with the focal EXCLUDED from the
+ * candidate set (you never re-warp to yourself; the next-nearest wins). Returns
+ * the chosen node index, or `-1` when no eligible node exists. The component's
+ * `warpTo(clientX, clientY)` sugar maps client→local px via `toLocal` first.
+ */
+export declare function warpTo(field: ConstellationField, px: number, py: number): number;
+/**
+ * Is the warp spring ARRIVED on its target (AY.W-CON1)? True when there is no
+ * active target (`targetIdx < 0`) OR the focal's gap to its LIVE target node is
+ * within {@link WARP_SETTLE_BAND}. A click-warp in flight (hundreds of px out)
+ * reports NOT arrived, so a user click always PRE-EMPTS the auto-drift cadence
+ * (the wander only re-targets a spring that has reached its current node). The
+ * gate is POSITION-only by design — a critically-damped spring tracking a drifting
+ * node carries a non-zero steady-state velocity forever, so a velocity term would
+ * never clear on a live field.
+ */
+export declare function warpSettled(field: ConstellationField): boolean;
+/**
+ * Pick a random eligible node index for the auto-drift re-target (AY.W-CON1) —
+ * any node EXCEPT the current `focalIndex` (so the focal actually MOVES). `rng`
+ * is the seeded `() => number` in `[0, 1)`. A degenerate field (≤1 node, or only
+ * the current focal) returns the current focal, which `setWarpTarget` no-ops
+ * cleanly (no crash, no jump).
+ */
+export declare function pickWanderTarget(field: ConstellationField, rng: () => number): number;
+/**
+ * Build the cold `ConstellationPinnedDrift` state (AZ.W-CON-GEN G5) the field carries
+ * when `pinnedDrift` is on. The anchor is seeded LATER (on the first sized frame, off
+ * the pinned node's layout position) — here it is `(0,0)` until `stepPinnedDrift`
+ * stamps it on the first armed leg. The token-read re-points the un-overridden
+ * cadence members on mount (the same prop-over-token layering as the well/wander).
+ */
+export declare function makePinnedDrift(override?: {
+    wanderFrac?: number;
+    durMs?: number;
+    minIdle?: number;
+    jitter?: number;
+}): ConstellationPinnedDrift;
+/**
+ * Advance the autonomous PINNED-ANCHOR drift one frame (AZ.W-CON-GEN G5). DISTINCT
+ * from `wander` (warp re-target): this gently eases the PINNED node around its seeded
+ * ANCHOR within `wanderFrac` of the canvas, on a jittered cadence, via a closed-form
+ * easeInOutQuad over `now` (no integrator, no second rAF — it rides `stepField`'s ONE
+ * per-frame call). No-ops (skipped) when there is no `field.pinnedDrift`, no pinned
+ * node, or `now <= 0` (the default unit callers stay green) — so an absent
+ * `pinnedDrift` is byte-identical to HEAD.
+ *
+ * The anchor is captured ON the first armed frame off the pinned node's CURRENT
+ * position (its seeded rest), so a consumer that re-anchors the pin (a resize re-fit)
+ * gets a fresh anchor on the next leg. Each leg eases from the node's current point to
+ * a fresh point within `wanderFrac` of the anchor over `durMs`; between legs the node
+ * rests at the leg's end, the next leg arming after `minIdle + rng()*jitter`.
+ */
+export declare function stepPinnedDrift(field: ConstellationField, now: number, rng: () => number): void;
+/** The flick-burst threshold (the shared usePointerVelocityField `burst` 0..1) above which
+ *  a fast flick fires the focal warp + a transient ripple (a slow drag never fires). */
+export declare const BURST_FIRE_THRESHOLD = 0.45;
+/**
+ * Fire a focal BURST off a flick (the §E "reads velocity AND acceleration" mandate). A high
+ * `burst` (from the shared `usePointerVelocityField`, the eased flick impulse) warps the
+ * focal node toward the cursor (the warp spring snaps it) AND drops an expanding ripple at
+ * the focal — the lattice "snaps the focal toward the cursor and drops an expanding ring"
+ * (the Canvas2D ripple / consumer accent-ring overlay). A slow drag (`burst` below the
+ * threshold) never fires (a steady hover is the gentle gather, not a snap). Returns true
+ * when a burst fired. Composes the EXISTING `warpTo` + the ripple list — no new mechanic,
+ * no second rAF (the warp rides the substrate's ONE clock); PRM is enforced by the CALLER
+ * (the shared field's `tick(0)` zeroes `burst` under reduce, so this never fires).
+ */
+export declare function fireBurst(field: ConstellationField, pointer: {
+    x: number;
+    y: number;
+}, burst: number, ripples: {
+    x: number;
+    y: number;
+    start: number;
+}[]): boolean;

package/dist/components/constellation/constellationRender.d.ts

@@ -0,0 +1,15 @@
+import type { ConstellationEdge, ConstellationField, ConstellationPalette, ConstellationPointer, ConstellationRipple } from "./constellationTypes";
+import { DEFAULT_PALETTE } from "./constants";
+/** Visual sizes floor independently from field geometry. */
+export declare function kVisOf(field: ConstellationField): number;
+export { DEFAULT_PALETTE };
+/** Resolve the neutral palette and legibility weights from the canvas tokens. */
+export declare function readPalette(canvas: HTMLCanvasElement): ConstellationPalette;
+/** Paint the edge rows produced by the field's single `buildEdges` scan. */
+export declare function drawEdges(ctx: CanvasRenderingContext2D, field: ConstellationField, edges: readonly ConstellationEdge[], palette: ConstellationPalette, opacity?: number): void;
+/** Paint ambient nodes, applying only the visual parallax offset. */
+export declare function drawNodes(ctx: CanvasRenderingContext2D, field: ConstellationField, palette: ConstellationPalette, opacity?: number, pointer?: ConstellationPointer | null, parallax?: number): void;
+/** Paint the pointer node after its focus edges. */
+export declare function drawPointer(ctx: CanvasRenderingContext2D, field: ConstellationField, pointer: ConstellationPointer | null, palette: ConstellationPalette, opacity?: number): void;
+/** Paint and retire tap/flick ripples. */
+export declare function drawRipples(ctx: CanvasRenderingContext2D, field: ConstellationField, now: number, ripples: ConstellationRipple[], palette: ConstellationPalette, opacity?: number): void;