@mkbabb/glass-ui 3.12.0 → 3.13.0

package/dist/components/custom/constellation/composables/useConstellationPointer.d.ts

@@ -0,0 +1,35 @@
+import type { Ref } from "vue";
+import type { ConstellationField, ConstellationPointer, ConstellationRipple } from "../constellationField";
+/** The substrate handle the wiring reads (`wake` re-arms a parked surface). */
+interface CanvasHandle {
+    wake: () => void;
+    reducedMotion: boolean;
+}
+export interface UseConstellationPointerOptions {
+    host: HTMLElement | null;
+    canvas: HTMLCanvasElement;
+    field: ConstellationField;
+    pointer: ConstellationPointer;
+    ripples: ConstellationRipple[];
+    handle: CanvasHandle;
+    /** The hoisted client→canvas-local mapper ref the exposed `warpTo(clientX,clientY)` reads. */
+    toLocalRef: Ref<((e: {
+        clientX: number;
+        clientY: number;
+    }) => ConstellationPointer | null) | null>;
+    pointerReactive: boolean;
+    warpOnClick: boolean;
+    gravityWell: boolean;
+    /** The deterministic-capture predicate — a frozen capture registers NO listeners. */
+    isFrozen: boolean;
+}
+/**
+ * Wire the constellation pointer listeners on the host. Sets the hoisted
+ * `toLocal` mapper (the deck-scale invariant — BOTH the ripple path AND the warp
+ * path read this ONE mapper), then registers the three independent listener
+ * blocks gated by their respective prop flags (each PRM-gated + capture-gated).
+ * No teardown is returned: the listeners ride the component's lifetime (the host
+ * element is torn down with the component), matching the prior inline behaviour.
+ */
+export declare function useConstellationPointer(opts: UseConstellationPointerOptions): void;
+export {};

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

@@ -0,0 +1,61 @@
+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;

package/dist/components/custom/constellation/constellationDraw.d.ts

@@ -0,0 +1,30 @@
+import type { ConstellationField, ConstellationPalette, ConstellationPointer, ConstellationRipple } from "./constellationField";
+import { DEFAULT_PALETTE } from "./constants";
+/** R5-8 — the visual-SIZE draw scale: `max(k, kFloor)`. The four neutral passes
+ *  size on this; positions/reach stay on TRUE `field.k`. Exported so a
+ *  `drawOverlay` skin floors its own marks/labels on the same axis. */
+export declare function kVisOf(field: ConstellationField): number;
+export { DEFAULT_PALETTE };
+/**
+ * Resolve the FULL neutral palette + legibility weights off a canvas's resolved
+ * custom properties (AX.W17). The colors AND the alpha multipliers route through
+ * the same `getComputedStyle` probe, so a dark-mode flip re-resolves BOTH the
+ * `:root`/`.dark` color arms AND the per-mode alpha defaults in one read.
+ */
+export declare function readPalette(canvas: HTMLCanvasElement): ConstellationPalette;
+/**
+ * Pass 1 — hairline edges between any two nodes within `link` px (alpha falls off with
+ * distance). The optional `accentIndex` (AZ.W-CON-GEN G2; default `-1` = OFF,
+ * byte-identical to the prior single-color pass) is the flagged-node ACCENT-edge skin:
+ * an edge incident on that node strokes `palette.accent` at `palette.edgeAccentAlpha`
+ * with a slightly heavier line (the flagged-node tether), while every other edge keeps
+ * the neutral register. The neutral edges carry a `palette.edgeFloor` minimum so a
+ * distance-faded hairline clears the perceptual floor on a bright ground (G3).
+ */
+export declare function drawEdges(ctx: CanvasRenderingContext2D, field: ConstellationField, link: number, palette: ConstellationPalette, opacityCeiling?: number, accentIndex?: number): void;
+/** Pass 2 — ambient node dots. */
+export declare function drawNodes(ctx: CanvasRenderingContext2D, field: ConstellationField, palette: ConstellationPalette, opacityCeiling?: number): void;
+/** Pass 3 — the cursor joins the web: faint links to nodes within reach + a soft cursor node. */
+export declare function drawPointerWeb(ctx: CanvasRenderingContext2D, field: ConstellationField, link: number, palette: ConstellationPalette, pointer: ConstellationPointer | null, opacityCeiling?: number): void;
+/** Pass 4 — tap ripples: expanding rings that fade over ~0.9s; consumed entries are spliced. */
+export declare function drawRipples(ctx: CanvasRenderingContext2D, field: ConstellationField, now: number, ripples: ConstellationRipple[], palette: ConstellationPalette, opacityCeiling?: number): void;

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

@@ -1,5 +1,4 @@
-/** Reference width the `k` scale factor is keyed to (CSS px). */
-export declare const BASE_WIDTH = 1280;
+export { BASE_WIDTH } from "./constants";
 export interface ConstellationNode {
     x: number;
     y: number;
@@ -35,6 +34,27 @@ export interface ConstellationPalette {
     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
@@ -72,14 +92,37 @@ export interface ConstellationWander {
     jitter: number;
 }
 /**
- * Auto-DRIFT cadence DEFAULTS (AY.W-CON1 source; tokenised in AY.W-CON2). The
- * `--constellation-wander-idle`/`-wander-jitter` tokens override these on mount via
- * `readInteractionConfig` (the SAME numeric `--constellation-*` cohort as the warp
- * spring + the well gains); 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).
+ * 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 declare const DEFAULT_WANDER_IDLE = 8000;
-export declare const DEFAULT_WANDER_JITTER = 8000;
+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
@@ -163,6 +206,8 @@ export interface ConstellationField {
     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
@@ -193,6 +238,30 @@ export interface ConstellationField {
      * 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
@@ -206,6 +275,15 @@ export interface ConstellationProps {
     link?: number;
     /** Drift speed. Default 0.16. */
     speed?: 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. */
@@ -246,6 +324,35 @@ export interface ConstellationProps {
         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
@@ -261,31 +368,6 @@ export interface ConstellationProps {
     /** The skin seam — paints the consumer's focal mark on the live field. */
     drawOverlay?: (ctx: CanvasRenderingContext2D, field: ConstellationField, now: number) => void;
 }
-export declare const DEFAULT_PALETTE: ConstellationPalette;
-/**
- * Resolve the FULL neutral palette + legibility weights off a canvas's resolved
- * custom properties (AX.W17). The colors AND the alpha multipliers route through
- * the same `getComputedStyle` probe, so a dark-mode flip re-resolves BOTH the
- * `:root`/`.dark` color arms AND the per-mode alpha defaults in one read.
- */
-export declare function readPalette(canvas: HTMLCanvasElement): ConstellationPalette;
-/**
- * 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;
-    };
-};
 /**
  * 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
@@ -325,118 +407,3 @@ export declare function refitField(field: ConstellationField, prevW: number, pre
  * (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): void;
-/**
- * Advance the gravity-well one `dt` (AY.W-CON2). A transient held-pointer force
- * composed inside `stepField` (NO new rAF): ease `well.strength` toward
- * `well.target` (1 held / 0 released) at `cfg.ramp`/s; while active, add an
- * inverse-square pull toward the held point onto each node within `cfg.reach`
- * (the `max(d, soften)` no-singularity floor + the `cfg.maxSpeed` no-slingshot
- * clamp); ALWAYS ease every node's |v| back toward `speed` (the field-cools
- * invariant — so a released well re-settles). No-ops (entirely skipped) when
- * `field.well` is undefined → the default render is byte-identical to HEAD.
- *
- * `dt` is clamped to {@link WARP_DT_CLAMP} (the same park-resume guard the warp
- * uses) so a tab-throttle gap cannot slingshot the field in one giant step.
- */
-export declare function stepWell(field: ConstellationField, k: number, speed: number, dt: number): void;
-/**
- * Warp spring tuning DEFAULTS — gentle critically-damped (no overshoot on a focal
- * mark). The `--constellation-warp-response`/`-zeta` tokens override these on mount
- * via `field.warpCfg` (AY.W-CON2); these stay the byte-identical fallback.
- *
- * `WARP_RESPONSE` is the keyframes.js `(response, dampingFraction)` model's ANGULAR
- * PERIOD (the SwiftUI `.spring(response:)` axis), `ω₀ = 2π/response` — 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); the shipped 0.55 settles
- * at ≈0.51s. This is the AY.W-CON2 ω-reconcile: the engine keeps the keyframes.js
- * `ω₀ = 2π/response` convention (the shared house model — `regen-spring-tokens.mjs`,
- * `keyframes.d.ts:860-882`) and mints NO second ω formula; the SEMANTIC honesty
- * (period, not settle) lives in this doc + the token comment + the settle-time unit
- * assertion, so a consumer setting the token gets the documented behaviour at ANY ζ.
- */
-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;
-/**
- * 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;
-/** Pass 1 — hairline edges between any two nodes within `link` px (alpha falls off with distance). */
-export declare function drawEdges(ctx: CanvasRenderingContext2D, field: ConstellationField, link: number, palette: ConstellationPalette): void;
-/** Pass 2 — ambient node dots. */
-export declare function drawNodes(ctx: CanvasRenderingContext2D, field: ConstellationField, palette: ConstellationPalette): void;
-/** Pass 3 — the cursor joins the web: faint links to nodes within reach + a soft cursor node. */
-export declare function drawPointerWeb(ctx: CanvasRenderingContext2D, field: ConstellationField, link: number, palette: ConstellationPalette, pointer: ConstellationPointer | null): void;
-/** Pass 4 — tap ripples: expanding rings that fade over ~0.9s; consumed entries are spliced. */
-export declare function drawRipples(ctx: CanvasRenderingContext2D, field: ConstellationField, now: number, ripples: ConstellationRipple[], palette: ConstellationPalette): void;

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

@@ -0,0 +1,132 @@
+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;
+    };
+};
+/**
+ * Advance the gravity-well one `dt` (AY.W-CON2). A transient held-pointer force
+ * composed inside `stepField` (NO new rAF): ease `well.strength` toward
+ * `well.target` (1 held / 0 released) at `cfg.ramp`/s; while active, add an
+ * inverse-square pull toward the held point onto each node within `cfg.reach`
+ * (the `max(d, soften)` no-singularity floor + the `cfg.maxSpeed` no-slingshot
+ * clamp); ALWAYS ease every node's |v| back toward `speed` (the field-cools
+ * invariant — so a released well re-settles). No-ops (entirely skipped) when
+ * `field.well` is undefined → the default render is byte-identical to HEAD.
+ *
+ * `dt` is clamped to {@link WARP_DT_CLAMP} (the same park-resume guard the warp
+ * uses) so a tab-throttle gap cannot slingshot the field in one giant step.
+ */
+export declare function stepWell(field: ConstellationField, k: number, speed: number, dt: number): void;
+/**
+ * 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;

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

@@ -1,3 +1,6 @@
 export { default as Constellation } from "./Constellation.vue";
-export { seedField, stepField, stepWell, refitField, readPalette, drawEdges, drawNodes, drawPointerWeb, drawRipples, nearestNode, readInteractionConfig, warpStep, warpTo, setWarpTarget, warpSettled, pickWanderTarget, BASE_WIDTH, DEFAULT_PALETTE, DEFAULT_WELL_CONFIG, DEFAULT_WANDER_IDLE, DEFAULT_WANDER_JITTER, WARP_RESPONSE, WARP_ZETA, } from "./constellationField";
-export type { ConstellationNode, ConstellationRipple, ConstellationPointer, ConstellationPalette, ConstellationField, ConstellationWarp, ConstellationWarpConfig, ConstellationWander, ConstellationWell, ConstellationWellConfig, ConstellationProps, } from "./constellationField";
+export { seedField, stepField, refitField, BASE_WIDTH, } from "./constellationField";
+export { DEFAULT_K_FLOOR } from "./constants";
+export { stepWell, nearestNode, readInteractionConfig, warpStep, warpTo, setWarpTarget, warpSettled, pickWanderTarget, stepPinnedDrift, makePinnedDrift, DEFAULT_WELL_CONFIG, DEFAULT_WANDER_IDLE, DEFAULT_WANDER_JITTER, DEFAULT_PINNED_DRIFT_FRAC, DEFAULT_PINNED_DRIFT_DUR, DEFAULT_PINNED_DRIFT_IDLE, DEFAULT_PINNED_DRIFT_JITTER, WARP_RESPONSE, WARP_ZETA, } from "./constellationInteraction";
+export { kVisOf, readPalette, drawEdges, drawNodes, drawPointerWeb, drawRipples, DEFAULT_PALETTE, } from "./constellationDraw";
+export type { ConstellationNode, ConstellationRipple, ConstellationPointer, ConstellationPalette, ConstellationField, ConstellationWarp, ConstellationWarpConfig, ConstellationWander, ConstellationWell, ConstellationWellConfig, ConstellationPinnedDrift, ConstellationProps, } from "./constellationField";

package/dist/components/custom/controls/DarkModeToggle.vue.d.ts

@@ -13,11 +13,22 @@ type __VLS_Props = {
      * @default false
      */
     disableTransitions?: boolean;
+    /**
+     * Opt-in slow-ECLIPSE register: a LONG-PRESS (vs the normal click) flips
+     * the mode through an indulgent, stretched sun↔moon cross-fade — the
+     * `--toggle-eclipse-duration` (≈1600ms) over the default 750ms. The bare
+     * `@click` flip is UNCHANGED (the default-path canary). Under
+     * `prefers-reduced-motion: reduce` the long-press flips INSTANTLY (no
+     * eclipse). Default false — the toggle behaves exactly as before.
+     * @default false
+     */
+    eclipse?: boolean;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
     size: DarkModeToggleSize;
     passive: boolean;
     disableTransitions: boolean;
+    eclipse: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;