@mkbabb/glass-ui 4.2.0 → 5.0.0

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/constellation/Constellation.vue.d.ts

@@ -0,0 +1,34 @@
+import { type ConstellationProps } from "./constellationField";
+declare const __VLS_export: import("vue").DefineComponent<ConstellationProps, import("./composables/useConstellation").ConstellationExpose, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ConstellationProps> & Readonly<{}>, {
+    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/constellationGLSetup.d.ts

@@ -0,0 +1,10 @@
+import type { WebGLCanvasFrame } from "../../../composables/glass/webgl/useWebGLCanvas";
+import type { ConstellationRenderState } from "./constellationWGPUSetup";
+export interface ConstellationGLSetupDeps {
+    canvas: HTMLCanvasElement;
+    resolveFrame: (timeSec: number) => ConstellationRenderState | null;
+    onResize?: (w: number, h: number) => void;
+    shouldContinue: () => boolean;
+}
+/** Build the `setupGL(gl)` callback the `createGpuSubstrate` WebGL2 path invokes. */
+export declare function createConstellationGLSetup(deps: ConstellationGLSetupDeps): (gl: WebGL2RenderingContext) => WebGLCanvasFrame;

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

@@ -0,0 +1,19 @@
+import type { WebGPUCanvasFrame } from "../../../composables/glass/webgpu/useWebGPUCanvas";
+import { type ConstellationUniformValues, type PackedNode, type PackedEdge } from "./uniformBridgeWGPU";
+/** The per-frame render state the renderer resolves (the stepped field → packed rows). */
+export interface ConstellationRenderState {
+    nodes: PackedNode[];
+    edges: PackedEdge[];
+    uniforms: ConstellationUniformValues;
+}
+export interface ConstellationWGPUSetupDeps {
+    canvas: HTMLCanvasElement;
+    /** Advance the field + the shared pointer field one renderer frame, return the packed render state. */
+    resolveFrame: (timeSec: number) => ConstellationRenderState | null;
+    /** Size the canvas backing store (returns the resolved backing-store [w,h] in device px). */
+    onResize?: (w: number, h: number) => void;
+    /** Demand-gate (the renderer's quiescence layer — substrate-agnostic). */
+    shouldContinue: () => boolean;
+}
+/** Build the constellation `setupWGPU(device, context, format)` callback. */
+export declare function createConstellationWGPUSetup(deps: ConstellationWGPUSetupDeps): (device: GPUDevice, context: GPUCanvasContext, format: GPUTextureFormat) => WebGPUCanvasFrame;

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

@@ -0,0 +1,39 @@
+import { type Ref } from "vue";
+import { type GpuBackend } from "../../../composables/glass/webgpu/useGpuSubstrate";
+import { type ConstellationField, type ConstellationProps } from "../constellationField";
+/** The route-pointer read a background constellation feeds its own field from. */
+export interface ConstellationRoutePointerRead {
+    /** Viewport-normalized route pointer (0..1). */
+    x: number;
+    y: number;
+    /** True while a live pointer is over the viewport (and not PRM/paused-silenced). */
+    active: boolean;
+}
+/** The optional composable seams (BI.W-CONSTELLATION-DEDUPE — the interactive-bg feed). */
+export interface UseConstellationOptions {
+    /**
+     * The interactive-BACKGROUND feed. When provided, the constellation reads the route
+     * chassis broadcaster each frame and drives a SUBTLE pointer WELL over the KEPT
+     * per-node integrator via `constellationWellMapping` (a longer-half-life field, so
+     * the background lean is ~2–6%, not the foreground gravity-well pull). Undefined for
+     * a foreground demo (which owns its own host listeners). Passed by `Constellation.vue`
+     * off the `backgroundInteractive` prop.
+     */
+    routePointer?: () => ConstellationRoutePointerRead | null;
+}
+/** The imperative seam the SFC re-exposes via `defineExpose`. */
+export interface ConstellationExpose {
+    field: ConstellationField;
+    isFrozen: Ref<boolean>;
+    /** The resolved backend (`"webgpu"` where supported, else the WebGL2 instanced twin). */
+    backend: () => GpuBackend;
+    warpTo(a: {
+        x: number;
+        y: number;
+    } | number, b?: number): number;
+    holdWellAt(x: number, y: number): boolean;
+    releaseWell(): void;
+    warpSettled(): boolean;
+    pinNode(idx: number): void;
+}
+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,97 @@
+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;
+/**
+ * The maximum node count the points/edges buffers pre-size for (the slider cap — a count
+ * above this is clamped at upload). ≫ this BOOKS the compute neighbor-bin path.
+ */
+export declare const MAX_NODES = 256;
+/**
+ * The per-node max degree budget — the edge buffer is pre-sized at `MAX_NODES · MAX_DEGREE`
+ * so the CPU all-pairs scan never overflows it (a denser-than-degree neighborhood drops the
+ * weakest edges, never re-allocates). 12 is a generous incident-edge ceiling for a
+ * distance-threshold ε-proximity graph at the default link/count.
+ */
+export declare const MAX_DEGREE = 12;
+/** The pre-sized edge instance budget (`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;
+/**
+ * The base node radius band (CSS px) the DPR-aware SDF circle sizes within (the §1 "Node
+ * size" config axis). `seedField` rolls each node's radius in `[NODE_R_MIN, NODE_R_MIN +
+ * NODE_R_SPREAD)` (the prior `1.6 + rng()*1.6` band, named); the WGSL/GLSL fragment SDF
+ * sizes `half = radius · uKVis · uDpr / uResolution` so the disc samples at full device
+ * resolution and is AA'd by the pixel-footprint derivative — crisp at ANY DPR.
+ */
+export declare const NODE_R_MIN = 1.6;
+export declare const NODE_R_SPREAD = 1.6;
+/** The hairline edge half-width (CSS px) the instanced segment-quad fragment AAs. */
+export declare const DEFAULT_LINE_WIDTH = 1;

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

@@ -0,0 +1,420 @@
+export interface ConstellationNode {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    r: number;
+    dim: boolean;
+    /**
+     * BC.W-VIZ-CONSTELLATION — the seeded parallax DEPTH (`z ∈ [0,1]`, §6). The pointer
+     * offsets the node's SCREEN position by `parallax · z · (pointer − center)` so the flat
+     * lattice reads as having depth (the Awwwards "living network" register). Seeded in
+     * `seedField`; perturbs the GPU node-position write only (never a layout property). A
+     * field literal that omits it is treated as `z = 0.5` (the mid-plane, no parallax bias).
+     */
+    z?: number;
+}
+/**
+ * BC.W-VIZ-CONSTELLATION — ONE edge of the proximity graph, the row the CPU all-pairs scan
+ * (`buildEdges`) writes each frame into the instanced-lines storage buffer. `a`/`b` are the
+ * two endpoint positions in canvas-local CSS px; `alpha` is the distance-falloff weight
+ * (`1 − d²/reach²`, the `drawEdges` math) the segment-quad fragment multiplies; `accent`
+ * (0/1) flags the accented-node tether (the flagged-node edge tint); `focus` (0/1) flags
+ * the pointer-web tether (the cursor's incident edges). The WGSL/GLSL render transcribes
+ * the SHAPE, never re-derives the scan (the ONE math source stays JS).
+ */
+export interface ConstellationEdge {
+    ax: number;
+    ay: number;
+    bx: number;
+    by: number;
+    /** The distance-falloff weight `1 − d²/reach²` (the drawEdges math). */
+    alpha: number;
+    /** 1 when the edge is incident on the accented node (the tether tint), else 0. */
+    accent: number;
+    /** 1 when the edge is a pointer-web tether (the cursor's incident edge), else 0. */
+    focus: number;
+}
+export interface ConstellationRipple {
+    x: number;
+    y: number;
+    /** `performance.now()` at first draw; -1 until stamped. */
+    start: number;
+}
+/** The pointer position in canvas-local CSS px (`-1` = inactive). */
+export interface ConstellationPointer {
+    x: number;
+    y: number;
+}
+/**
+ * The neutral palette + legibility weights resolved off the canvas custom
+ * properties (the FULL `--constellation-*` set — AX.W17). `node`/`nodeDim`/
+ * `line` are the colors; `edgeAlpha`/`edgeFocusAlpha`/`alpha` are the per-mode
+ * legibility multipliers (replacing the `0.17`/`0.24` magic literals).
+ */
+export interface ConstellationPalette {
+    node: string;
+    nodeDim: string;
+    line: string;
+    /** The hairline-edge alpha multiplier (was the `0.17` literal). */
+    edgeAlpha: number;
+    /** The focus-proximity edge multiplier (consumer skins may read it). */
+    edgeFocusAlpha: number;
+    /** The field-yields-to-type translucency knob (the global field dimmer). */
+    alpha: number;
+    /**
+     * The ACCENT-edge skin tint (AZ.W-CON-GEN G3) — the flagged-node EDGE color the
+     * optional `drawEdges(…, accentIndex)` pass strokes for edges incident on the
+     * accented node. Reads `--constellation-accent` (the consumer-preset boundary —
+     * the library ships a neutral default; a consumer aliases it to its brand hue).
+     */
+    accent: string;
+    /**
+     * The neutral-edge alpha FLOOR (AZ.W-CON-GEN G3) — added to a distance-faded
+     * neutral hairline's alpha so it clears the perceptual/sampling floor across its
+     * full length on a bright ground (the "web doesn't read in light mode" fix).
+     * Default `0` is byte-identical (no floor). Reads `--constellation-edge-floor`.
+     */
+    edgeFloor: number;
+    /**
+     * The ACCENT-incident edge alpha multiplier (AZ.W-CON-GEN G3) — the per-mode
+     * weight for an edge touching the accented node. Reads
+     * `--constellation-edge-accent-alpha`; the accented edges read a touch louder
+     * than the neutral lattice (the flagged-node tether).
+     */
+    edgeAccentAlpha: number;
+}
+/**
+ * The per-axis critically-damped warp spring on the focal node (AX.W17). The
+ * focal mark's position is `(x, y)`; `vx`/`vy` its velocity; `targetIdx` the
+ * LIVE node index it chases (re-read each frame so it tracks a DRIFTING target,
+ * not a frozen click-time snapshot). `-1` = no active warp (the focal mark
+ * rides its node's drift directly — the identity-ride at settle).
+ */
+export interface ConstellationWarp {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    /** The chased node's INDEX (live target), or -1 when inactive. */
+    targetIdx: number;
+}
+/**
+ * The auto-DRIFT target-source (AY.W-CON1 — the 2nd half of the AX.W17 "drift +
+ * warp are ONE mechanic" thesis). The warp re-points its focal node to a
+ * periodically-chosen RANDOM node on a jittered cadence: the SAME warp spring,
+ * a different target-PICKER (a click for warp, this cadence for drift). No new
+ * rAF, no second mechanic — `stepField` steps this cadence inline, re-pointing
+ * `setWarpTarget` to a picked node only when the spring has SETTLED (so a
+ * click-warp in flight always pre-empts the cadence). PRM is enforced by the
+ * CALLER (the component does not advance the cadence under reduced-motion — the
+ * `stepField` call lives inside the `!reducedMotion` block — so the focal mark
+ * stays at its seed: the WARP precedent, NOT fire-but-freeze).
+ */
+export interface ConstellationWander {
+    /** ms timestamp of the next auto re-target; -1 until armed on the first stepped frame. */
+    nextAt: number;
+    /** the minimum idle (ms) between auto re-targets. */
+    minIdle: number;
+    /** the random extra idle (ms) added per cadence (so the rhythm is not metronomic). */
+    jitter: number;
+}
+/**
+ * The autonomous PINNED-ANCHOR drift state (AZ.W-CON-GEN G5) — the gentle wander of
+ * the PINNED node (`field.pinnedIndex`) around its seeded ANCHOR. DISTINCT from
+ * `wander` (which re-targets the WARP spring among random nodes): this eases ONE
+ * designated node a small fraction around its rest position on a jittered cadence,
+ * so a flagged point breathes its neighborhood without leaving the dead-space it was
+ * anchored in. Stepped inside `stepField` (no second rAF) via a closed-form
+ * easeInOutQuad over `now` — no integrator. Absent (`undefined`) → `stepField` skips
+ * the block (byte-identical to HEAD).
+ */
+export interface ConstellationPinnedDrift {
+    /** The anchor (the pinned node's rest position) the drift eases around (px). */
+    anchorX: number;
+    anchorY: number;
+    /** ms timestamp of the next leg; -1 until armed on the first stepped frame. */
+    nextAt: number;
+    /** ms timestamp the current leg started; -1 between legs (resting at the anchor). */
+    legStart: number;
+    /** the current leg's from/to (px) — the eased segment endpoints. */
+    fromX: number;
+    fromY: number;
+    toX: number;
+    toY: number;
+    /** the ± fraction of the canvas the drift wanders around the anchor. */
+    wanderFrac: number;
+    /** the per-leg easeInOutQuad duration (ms). */
+    durMs: number;
+    /** the minimum rest (ms) between legs. */
+    minIdle: number;
+    /** the random extra rest (ms) per leg (so the rhythm is not metronomic). */
+    jitter: number;
+}
+/**
+ * The warp-spring tuning the integrator reads (AY.W-CON2). Tokenised numeric (the
+ * `--constellation-warp-*` cohort) so a consumer retunes the warp WITHOUT editing
+ * src — read ONCE on mount via `parseFloat`, threaded onto the field.
+ *
+ * `response` is the keyframes.js `(response, dampingFraction)` model's ANGULAR
+ * PERIOD (the SwiftUI `.spring(response:)` axis): `ω₀ = 2π/response`. It is NOT a
+ * settle-duration — at ζ=1 the 2%-settle lands at `t₂ ≈ 5.83/ω₀ ≈ 0.93·response`
+ * (the `(1 + ω₀t)e^(−ω₀t)` critically-damped envelope). Documented here + in the
+ * `--constellation-warp-response` token comment so the token semantics are honest
+ * at ANY ζ (the AY.W-CON2 ω-reconcile; the engine keeps the keyframes.js convention,
+ * mints NO second ω formula).
+ */
+export interface ConstellationWarpConfig {
+    /** keyframes.js angular period (s) — `ω₀ = 2π/response`, NOT a settle-duration. */
+    response: number;
+    /** damping ratio ζ — 1 critically damped (a focal mark must NOT ring). */
+    zeta: number;
+}
+/**
+ * The gravity-well tuning (AY.W-CON2). The held-pointer pull is an inverse-square
+ * force composed into `stepField` (no new rAF). Tokenised numeric (the
+ * `--constellation-well-*` cohort) so a consumer retunes the well WITHOUT editing
+ * src. All distances are base-width px (`k`-scaled at step time).
+ */
+export interface ConstellationWellConfig {
+    /** the inverse-square pull gain (the force scale at unit distance). */
+    gain: number;
+    /** the reach (base-width px) — nodes beyond it are untouched (the O(within-reach) cost floor). */
+    reach: number;
+    /**
+     * the ARM ramp rate (1/s) — `strength` eases toward `target = 1` at this rate
+     * while HELD (the gentle bloom the token tunes). The RELEASE is NOT this rate:
+     * it is the fixed brisk {@link WELL_RELEASE_RAMP} (the field-cools invariant —
+     * not consumer-tunable, F8.2). A consumer slowing this token slows the ARM
+     * bloom only; the release stays brisk so the cool gate holds.
+     */
+    ramp: number;
+    /** the per-node speed cap (base-width px/frame) — the no-slingshot clamp. */
+    maxSpeed: number;
+    /** the singularity floor (px) — a node AT the cursor gets a bounded pull, never `∞`. */
+    soften: number;
+    /** ms the pointer is held before the well arms. */
+    holdMs: number;
+}
+/**
+ * The gravity-well live STATE (AY.W-CON2). `(x, y)` is the held pointer in
+ * canvas-local px (`-1` = inactive); `strength` is the eased pull 0→1 (ramps to
+ * `target` at `cfg.ramp`/s); `target` is the strength the ramp eases toward (1
+ * while held, 0 on release). A transient force — the field renormalises back to
+ * `speed` after release (the field-cools invariant).
+ */
+export interface ConstellationWell {
+    /** canvas-local px of the held pointer; `-1` = inactive. */
+    x: number;
+    y: number;
+    /** the eased pull strength 0→1 (ramps to `target` at `cfg.ramp`/s). */
+    strength: number;
+    /** the strength the ramp is easing toward: 1 while held, 0 on release. */
+    target: number;
+    /** the well tuning (gain/reach/ramp/maxSpeed/soften). */
+    cfg: ConstellationWellConfig;
+}
+/**
+ * The field state the component exposes to its `drawOverlay` consumer so a
+ * skin can pin itself to a real field node. `k` is the `width / BASE_WIDTH`
+ * scale, `dpr` the device-pixel ratio applied by the substrate.
+ *
+ * The focal node (AX.W17) is a FIRST-CLASS library concept: `focalIndex` names
+ * which node is focal (consumer-owned via `warpTo`), and the engine OWNS its
+ * position via the `warp` spring stepped inside `stepField`. A `drawOverlay`
+ * paints the focal mark at `field.warp.{x,y}` (the spring-eased position) —
+ * node-position mutation `drawOverlay` structurally cannot express, resolved by
+ * ONE first-class concept (warp + drift unify; no second parallel hook).
+ */
+export interface ConstellationField {
+    nodes: ConstellationNode[];
+    /** The host canvas — for `getComputedStyle` token reads in an overlay. */
+    canvas: HTMLCanvasElement | null;
+    w: number;
+    h: number;
+    k: number;
+    dpr: number;
+    /** R5-8 — SIZES draw at `kVisOf(field)`; TRUE `k` keeps positions/reach. */
+    kFloor?: number;
+    /**
+     * The designated focal node's INDEX, or `-1` when none is pinned. Re-points
+     * on each `warpTo`; node count is conserved (it is a designation, not a new
+     * node). A `drawOverlay` reads `field.warp.{x,y}` for the spring-eased mark.
+     */
+    focalIndex: number;
+    /** The per-axis warp spring the engine steps inside `stepField` (AX.W17). */
+    warp: ConstellationWarp;
+    /**
+     * The warp-spring tuning `warpStep` reads (AY.W-CON2). Optional — absent
+     * falls back to the shipped `{ response: 0.55, zeta: 1.0 }` defaults (the
+     * byte-identical HEAD spring). A tokenised override (read on mount) reaches
+     * the integrator through this member.
+     */
+    warpCfg?: ConstellationWarpConfig;
+    /**
+     * The optional auto-DRIFT cadence (AY.W-CON1). When set, `stepField`
+     * periodically re-points the warp to a random node (the wander source on the
+     * SAME spring). Absent (`undefined`) leaves the field BYTE-IDENTICAL to the
+     * pre-wander HEAD — `stepField` skips the cadence block entirely.
+     */
+    wander?: ConstellationWander;
+    /**
+     * The optional gravity-well (AY.W-CON2). When set, `stepField` composes a
+     * held-pointer inverse-square pull force (no new rAF) — `well.target → 1`
+     * while held, `→ 0` on release, the field renormalising back to `speed` once
+     * the well cools. Absent (`undefined`) leaves the field BYTE-IDENTICAL to the
+     * pre-well HEAD — `stepField` skips the force pass entirely.
+     */
+    well?: ConstellationWell;
+    /**
+     * The PINNED node designation (AZ.W-CON-GEN G1) — the index of a node `stepField`
+     * does NOT drift/bounce/steer/pull, so it HOLDS its seeded position (the flagged
+     * flagged node the consumer pins). `-1` (the default) = no pin → every node drifts
+     * (byte-identical to HEAD). A designation, NOT a new node — node count is
+     * conserved. The optional `pinnedDrift` gently wanders it around its anchor; the
+     * optional `drawEdges(…, accentIndex)` tints its incident edges.
+     */
+    pinnedIndex: number;
+    /**
+     * The optional autonomous PINNED-ANCHOR drift (AZ.W-CON-GEN G5). When set AND a
+     * node is pinned, `stepField` gently eases the pinned node around its anchor on a
+     * jittered cadence (a closed-form easeInOutQuad — no second rAF). Absent
+     * (`undefined`) → the pinned node holds dead-still at its anchor (byte-identical).
+     */
+    pinnedDrift?: ConstellationPinnedDrift;
+    /**
+     * Warp AUTO-RELEASE (AZ.W-CON-GEN G6). When `true`, `stepField` clears the warp's
+     * `targetIdx` (→ -1) once the spring has SETTLED on its target — the focal node
+     * releases the spring and rides its node's RAW drift (the identity-ride), freeing
+     * the spring for the next warp. Default `false`/undefined keeps the held-target
+     * behaviour (the warp chases its node forever — byte-identical to HEAD).
+     */
+    warpAutoRelease?: boolean;
+}
+/**
+ * The `<Constellation>` consumer prop surface (the public type a consumer types
+ * a wrapper against). The `drawOverlay` seam is the branded-skin injection — it
+ * runs AFTER the neutral passes with the live field.
+ */
+export interface ConstellationProps {
+    /** Node count. Default 64. */
+    count?: number;
+    /** Link distance in px (the falloff reach). Default 132. */
+    link?: number;
+    /** Drift speed. Default 0.16. */
+    speed?: number;
+    /**
+     * BC.W-VIZ-CONSTELLATION (§6) — the pointer-PARALLAX depth. Each node carries a seeded
+     * depth `z ∈ [0,1]`; the pointer offsets node screen positions by `parallax · z ·
+     * (pointer − center)` so the flat lattice reads as having depth (the Awwwards "living
+     * network" register). Additive default-on at a SUB-PERCEPTUAL 0.08 (a hair of depth, not
+     * a behavior break); 0 = the flat lattice. GPU-only (perturbs the node-position write,
+     * never a layout property). Frozen under reduced-motion / `freeze`.
+     */
+    parallax?: number;
+    /**
+     * AY.W-COHERE E3 — the per-instance outer-envelope RECESSION knob (the aurora
+     * `opacityCeiling` / fourier `intensity` sibling — ONE recession vocabulary
+     * across the four live substrates). Scales the painted edge/node/web/ripple
+     * alpha OVER the mode-tuned `--constellation-alpha` base so the lattice can
+     * RECEDE behind content (0.4–0.6 in a hero). Default `1` is byte-identical to
+     * HEAD.
+     */
+    opacityCeiling?: number;
+    /** Seed for a reproducible field (number or hashed string); omit for `Math.random`. */
+    seed?: number | string;
+    /** Steer-toward-cursor + tap ripples. Default true; auto-off under reduced-motion. */
+    pointerReactive?: boolean;
+    /**
+     * Click-to-warp (AX.W17): a click warps the focal node to the nearest
+     * drifting node + springs it there. INDEPENDENT of `pointerReactive` (warp
+     * works on a non-ripple lattice). Default false; auto-off under
+     * reduced-motion (the focal mark stays put — the stated PRM policy).
+     */
+    warpOnClick?: boolean;
+    /**
+     * Auto-DRIFT (AY.W-CON1): a periodic auto-pick re-points the focal node to a
+     * random node on a jittered cadence — the wander source on the SAME warp
+     * spring (no second mechanic). `true` uses the default cadence (8–16s, the
+     * slides rhythm); `{ minIdle, jitter }` tunes it. Default OFF (absent →
+     * byte-identical to HEAD). PRM-gated by the WARP precedent (the cadence never
+     * advances under reduced-motion — the focal stays at its seed).
+     */
+    wander?: boolean | {
+        minIdle?: number;
+        jitter?: number;
+    };
+    /**
+     * Pointer-held GRAVITY-WELL (AY.W-CON2): hold the pointer and the lattice is
+     * pulled toward it (an inverse-square force on the same engine, no new rAF);
+     * release and the field cools back to `speed`. INDEPENDENT of `warpOnClick`
+     * and `pointerReactive` (a consumer can hold-to-pull on a non-ripple,
+     * non-warp lattice). `true` uses the tokenised defaults; an object tunes the
+     * gains. Default OFF (absent → byte-identical to HEAD). PRM-gated by the WARP
+     * precedent (the held-timer is not registered under reduced-motion).
+     */
+    gravityWell?: boolean | {
+        holdMs?: number;
+        gain?: number;
+        reach?: number;
+        ramp?: number;
+        maxSpeed?: number;
+        soften?: number;
+    };
+    /**
+     * PINNED node designation (AZ.W-CON-GEN G1): a node held by every step pass (it
+     * does not drift / bounce / steer / feel the well). `false`/absent → no pin;
+     * `true` → node 0; a number → that index. The flagged-node pin the consumer holds.
+     */
+    pinned?: boolean | number;
+    /**
+     * ACCENT-edge skin (AZ.W-CON-GEN G2): edges incident on the pinned (else focal)
+     * node stroke the `--constellation-accent` tint — the flagged-node tether. Default
+     * OFF (the neutral single-color pass).
+     */
+    accentEdges?: boolean;
+    /**
+     * Autonomous PINNED-ANCHOR drift (AZ.W-CON-GEN G5): the pinned node gently wanders
+     * its seeded anchor on a jittered cadence (DISTINCT from `wander`, which re-targets
+     * the warp). Default OFF (the pin holds dead-still). PRM-gated.
+     */
+    pinnedDrift?: boolean | {
+        wanderFrac?: number;
+        durMs?: number;
+        minIdle?: number;
+        jitter?: number;
+    };
+    /**
+     * Warp AUTO-RELEASE (AZ.W-CON-GEN G6): a settled warp clears its target so the
+     * focal rides its node's raw drift (the identity-ride). Default OFF (the warp holds
+     * its target forever). Read the settled signal via the `warpSettled()` expose.
+     */
+    warpAutoRelease?: boolean;
+    /**
+     * Deterministic-capture freeze (AY.W-CON3): when `true`, lays out ONE
+     * reproducible STATIC frame (no `stepField`, no ripple / warp / wander / well
+     * advance) and hands `drawOverlay` a FROZEN `now` so a phase-driven skin
+     * resolves to a fixed value. Omit to AUTO-DERIVE from `location.search`
+     * matching `export | print | freeze` (the deploy-pipeline contract); an
+     * explicit `false` forces live even under a capture URL. Set `seed` for a
+     * field stable ACROSS runs. Unifies with the reduced-motion one-static-frame
+     * path (`freeze || reducedMotion` is the single static-frame predicate).
+     */
+    freeze?: boolean;
+    /**
+     * The interactive-BACKGROUND feed (BI.W-CONSTELLATION-DEDUPE). A full-bleed
+     * `pointer-events:none` background constellation cannot listen for its own
+     * pointer, so it reads the route chassis's ONE window pointer broadcaster
+     * (`useRoutePointer`, provided by the route chassis) and feeds a SUBTLE pointer
+     * WELL — the attractor/engagement over the shared field, projected by
+     * `constellationWellMapping` and applied by the KEPT per-node well integrator
+     * (`constellationWell.ts`, byte-frozen — the pointer feeds it, it does not
+     * replace it). The background influence is subtle (~2–6%, longer half-life);
+     * the canvas STAYS `pointer-events:none` (the broadcaster is the source). Default
+     * OFF — a foreground demo owns its own host listeners; only a background sets this.
+     */
+    backgroundInteractive?: boolean;
+    class?: string;
+    /** The skin seam — paints the consumer's focal mark on the live field. */
+    drawOverlay?: (ctx: CanvasRenderingContext2D, field: ConstellationField, now: number) => void;
+}