vireuikit 0.3.0 → 0.4.0

package/dist/{dynamics-7Bq3LLds.d.ts → dynamics-DqGk_f1n.d.ts}

@@ -1,4 +1,39 @@
 type VireUIKitMediumChannel = readonly [number, number, number];
+/**
+ * A static light source, as data — the chamber's illumination is a separate entity from the gas it
+ * lights (see `MEDIUM_COMPOSITE_SHADER`): the medium itself is dark, and everything visible is
+ * light scattered by mist, condensate and tracks inside a light's reach.
+ */
+type VireUIKitMediumLight = {
+    /** Fraction of the frame, 0…1 both axes. `y=0` is the chamber's visual BOTTOM edge, `y=1` the
+     *  top — the same convention `gravityBottomBoost` already uses in `MEDIUM_COMPOSITE_SHADER`. */
+    position: readonly [number, number];
+    /** Unit direction (any nonzero vector is normalized before upload) the light points into the
+     *  chamber, in the SAME up-is-positive-y convention as `position`. Kept off the exact
+     *  vertical/horizontal axes by default: an on-axis beam edge is itself axis-aligned, which is
+     *  exactly the straight-line artifact `check:medium`'s isotropy gate polices, and an angled shaft
+     *  also reads more like a real illuminated volume than a spotlight aimed straight down a wall. */
+    direction: readonly [number, number];
+    /** Half-angle of the light's cone, radians. Wide (close to a right angle or beyond) for an edge
+     *  strip that washes the whole chamber width — there the shaping comes from distance falloff, not
+     *  a cone edge — narrow for a spotlight, where the cone edge IS the visible beam. */
+    coneAngle: number;
+    /** 1/(fraction of frame height) — how fast illumination drops off with distance from the light.
+     *  Distance is normalized by frame HEIGHT (not a raw fraction of each axis) so a circular pool of
+     *  light stays circular on screen regardless of the frame's aspect ratio. */
+    falloff: number;
+    /** sRGB 0…1. Defaults to a cool neutral; a caller deriving a light rig from cover art applies
+     *  `speciesFamily`/`characterOf` (`species.ts`) to THESE colors now, not to `channelColors` —
+     *  see the comment on `channelColors` below. */
+    color: VireUIKitMediumChannel;
+    /** ≥0 multiplier on this light's contribution. 0 turns it off without removing it from the array. */
+    intensity: number;
+};
+/** How many lights `MEDIUM_COMPOSITE_SHADER` reads — a fixed, small count of flat uniforms
+ *  (`u_light0*`/`u_light1*`/`u_light2*`), the same pattern `u_lab0/1/2` already uses for species:
+ *  `setUniform` (vireglass/web) has no array form, only scalars up to vec4. A `lights` array
+ *  shorter than this is padded with intensity-0 entries; a longer one is truncated. */
+declare const MEDIUM_MAX_LIGHTS = 3;
 type VireUIKitMediumParams = {
     /** 1/s — how fast the TRACK density decays per second. Water (vapor+condensate) does not decay:
      *  it is a conserved volume, only moving between phases and being transported. */
@@ -63,9 +98,16 @@ type VireUIKitMediumParams = {
     /** Near-white sRGB tone of droplets with no hue seeding (`condensateTint=0`) — droplets scatter
      *  light rather than color it. */
     condensateColor: VireUIKitMediumChannel;
-    /** Each vapor species' hue, sRGB 0…1. Derived as a family around one tone (`speciesFamily`),
-     *  not picked as three separate colors — see `species.ts`. */
+    /** Each vapor species' hue, sRGB 0…1, folded into the dark ambient mix underneath the lit layer
+     *  (see `MEDIUM_COMPOSITE_SHADER`) — a minor, near-neutral hint by default. Colour now lives on
+     *  `lights`, not here: a real chamber's gas is invisible, only what scatters light reads at all
+     *  (see `channelScatter`). Kept for callers that still want a tinted ambient base, and because the
+     *  isotropy/contrast/depth gates in `check-medium.mjs` measure structure through it directly. */
     channelColors: readonly [VireUIKitMediumChannel, VireUIKitMediumChannel, VireUIKitMediumChannel];
+    /** How strongly each vapor species scatters light, relative to the others — what a species IS,
+     *  now that colour lives on `lights` (see `channelColors`). `[1, 1, 1]` (equal) by default; a
+     *  caller can make one species read as denser mist than another without touching its hue. */
+    channelScatter: VireUIKitMediumChannel;
     /** The platform's neutral tone — what the medium is, alone, with no source playing. */
     baseColor: VireUIKitMediumChannel;
     /** Background weight in the Oklab mix: keeps the platform tone visible even where the smoke is dense. */
@@ -131,7 +173,30 @@ type VireUIKitMediumParams = {
      *  `smoothstep`. The brief asks for a denser LAYER at the floor of the chamber, not a boost that
      *  reaches halfway up the frame — kept in the bottom quarter. */
     gravityBottomBoostStart: number;
+    /** Static lights — the chamber's illumination, entirely separate from the gas (see
+     *  `VireUIKitMediumLight`). Padded/truncated to `MEDIUM_MAX_LIGHTS` by the web runtime. */
+    lights: readonly VireUIKitMediumLight[];
+    /** How strongly the gas between a spotlight and a point dims it, per frame height of dense gas. */
+    shadowExtinction: number;
+    /** 0…1 — a track's minimum visibility regardless of local illumination, added to the light
+     *  reaching it. Tracks are lit the same way as mist, but a fresh ionization trail is bright enough
+     *  in a real chamber to read even where the ambient light is weak — this is that floor, not a
+     *  second light source. */
+    trackLightFloor: number;
+    /** ≥0 — master strength of the crisp, screen-space track layer (`web/track-layer.ts`): a grid
+     *  cell cannot carry a thin sharp line (see that module's own header), so the grid stamp this
+     *  file's `decay`/`trackLightFloor` govern stays the soft, gas-carried residue, and THIS is the
+     *  bright, sharp geometry drawn over it in content pixels. 0 disables it outright — the canary
+     *  `check:medium` uses to prove its "sharp at birth" gate is actually sensitive to the layer,
+     *  not to the residue underneath it. */
+    trackLayerAmount: number;
 };
+/**
+ * An edge strip along the chamber floor plus two spotlights above the frame, aimed down across it
+ * toward the source point. The lamps stay off screen, so a beam never shows its apex, and the two
+ * differ slightly in position, angle and strength: an exact mirror reads as staged.
+ */
+declare const MEDIUM_DEFAULT_LIGHTS: readonly VireUIKitMediumLight[];
 declare const MEDIUM_DEFAULTS: VireUIKitMediumParams;
 /**
  * Resolves the far plane's fractional offset (`depthFarOffsetFrac`) into grid-px for a GIVEN grid
@@ -157,9 +222,11 @@ declare const MEDIUM_PROBE_FLOOR_PX = 22;
 declare const MEDIUM_DEFAULT_CELL_PX = 26;
 /**
  * The geometry of one track stamp (`emit-shader.ts`), in FRACTIONS of `min(gridW, gridH)` rather
- * than pixels — so a preset doesn't depend on the simulation grid's resolution. Two presets:
- * alpha is a thick, short, straight track; beta is a thin, long, ragged one. The third, natural,
- * is dim and short, for the occasional background track at rest (not tied to cover art).
+ * than pixels — so a preset doesn't depend on the simulation grid's resolution. Three presets, the
+ * reference's three visible kinds: `alpha` is a thick, short, straight ray — `createMediumDynamics`
+ * stamps a dozen or so of these at once per event, radiating from one point, so a single ray is
+ * short on purpose. `electron` is thin, long-ish and ragged (wiggly, granular). `muon` is long,
+ * straight and thin — a cosmic ray crossing the whole chamber, unrelated to any source.
  */
 type VireUIKitMediumTrackPreset = {
     lengthFrac: number;
@@ -174,7 +241,7 @@ type VireUIKitMediumTrackPreset = {
     tailDim: number;
     intensity: number;
 };
-declare const MEDIUM_TRACK_PRESETS: Readonly<Record<'alpha' | 'beta' | 'natural', VireUIKitMediumTrackPreset>>;
+declare const MEDIUM_TRACK_PRESETS: Readonly<Record<'alpha' | 'electron' | 'muon', VireUIKitMediumTrackPreset>>;
 /** Turbulence at rest/paused/with no active track — the "slow drift" baseline shared by all three
  *  neutral states (they differ from each other in other ways, not in this number). */
 declare const MEDIUM_DRIFT_TURBULENCE = 0.045;
@@ -196,30 +263,100 @@ declare const MEDIUM_EMISSION_PROBABILITY = 0.55;
 declare const MEDIUM_MIN_EMISSION_INTERVAL = 1.2;
 /** Average interval between solitary "background emission" tracks at rest, seconds, plus a random
  *  `MEDIUM_NATURAL_JITTER` on top — rare, with no discernible rhythm. */
-declare const MEDIUM_NATURAL_INTERVAL = 25;
-declare const MEDIUM_NATURAL_JITTER = 35;
+declare const MEDIUM_NATURAL_INTERVAL = 8;
+declare const MEDIUM_NATURAL_JITTER = 12;
 /** The sensitive layer — fractions of height, top to bottom. Above it there isn't enough
  *  supersaturation for a track to appear at all, so background emission is only ever visible here. */
 declare const MEDIUM_SENSITIVE_TOP = 0.55;
 declare const MEDIUM_SENSITIVE_BOTTOM = 0.95;
+/** How many alpha rays a single decay event stamps at once, radiating from the same source point —
+ *  the reference's starburst, not a lone track (`MEDIUM_TRACK_PRESETS.alpha` is the shape of ONE
+ *  ray). Randomized per event within this range. */
+declare const MEDIUM_ALPHA_BURST_RAYS: readonly [number, number];
+/** Per-ray length multiplier within a burst, so the rays read as an organic spray rather than a
+ *  wheel of identical spokes — the reference's rays visibly differ in reach. */
+declare const MEDIUM_ALPHA_RAY_LENGTH_SCALE: readonly [number, number];
 /** Per-emission depth range applied to a track's width (`headWidthFrac`/`tailWidthFrac`), far…near.
  *  The same knob reads as both "thin" and "soft": a Gaussian stamp's edge steepness scales with its
  *  own width (`emit-shader.ts`'s only extent parameter), so shrinking it for a far track thins and
  *  softens it in the same stroke — there is no second knob to hang an independent softness number
  *  on. Floored at 0.55: below that a far `alpha` track's head narrows past what MacCormack's own
- *  numerical smoothing already blurs it to, and the depth cue disappears into that noise floor. */
+ *  numerical smoothing already blurs it to, and the depth cue disappears into that noise floor.
+ *  The near end now runs past 1 (1.2, not 1): depth of field needs the NEAREST tracks a little
+ *  LARGER than the base preset too, not just full-size — the reference shows near tracks blurring
+ *  into big soft shapes rather than merely reading "as sharp as it gets". The same knob does both
+ *  jobs again: a wider-than-base stamp is also a softer-edged one. */
 declare const MEDIUM_TRACK_DEPTH_WIDTH_RANGE: readonly [number, number];
 /** Per-emission depth range applied to a track's intensity, far…near — "dim". Floored at 0.4, not
  *  lower: a far track still has to clear `MEDIUM_DEFAULTS.condensationFloor`'s excess threshold
  *  often enough to read as a track, or depth would look like tracks randomly failing to spawn
  *  rather than fading into the distance. */
 declare const MEDIUM_TRACK_DEPTH_INTENSITY_RANGE: readonly [number, number];
+/**
+ * How long a live track stays in the crisp screen-space layer (`web/track-layer.ts`), seconds, by
+ * preset — tuned by eye against the reference's own "roughly one to two seconds"
+ * (`docs`/the brief's own reference frames): `alpha` is the shortest, thickest burst ray; `muon`,
+ * a cosmic ray crossing the whole chamber, lingers longest. Independent of `MEDIUM_DEFAULTS.decay`,
+ * which times the SOFT gas-carried residue left behind in the grid, not this layer.
+ */
+declare const MEDIUM_TRACK_LAYER_LIFE_SECONDS: Readonly<Record<keyof typeof MEDIUM_TRACK_PRESETS, number>>;
+/** Oldest-out cap on the live-track list (`web/track-layer.ts`) — a burst of a dozen-plus alpha
+ *  rays every few seconds would otherwise grow the instanced draw without bound over a long
+ *  session; 64 is comfortably above what a few overlapping bursts plus background radiation ever
+ *  need alive at once. */
+declare const MEDIUM_TRACK_LAYER_MAX_TRACKS = 64;
+/**
+ * How a track looks in the crisp layer, per kind. Lengths are fractions of
+ * `min(contentWidth, contentHeight)`: the grid presets' widths are sized for a 26 px cell and
+ * would be tens of pixels wide here.
+ */
+type VireUIKitTrackLayerLook = {
+    /** Core Gaussian sigma at birth, at the source end. */
+    sigmaFrac: number;
+    /** Sigma multiplier at the far end: an alpha thickens toward the end of its range. */
+    endSigmaMul: number;
+    /** Diffusion: sigma(age) = sigma * sqrt(1 + broaden * age). */
+    broaden: number;
+    /** Sideways wiggle amplitude, for kinds whose preset has a ragged path. */
+    wiggleFrac: number;
+    /** Period of the brightness beads along the track. */
+    beadFrac: number;
+    /** Mean spacing of stray droplets along the track, and the share of slots that hold one. */
+    dropletFrac: number;
+    dropletChance: number;
+    /** Gap between the source point and where the track starts. */
+    startFrac: number;
+    /** Brightness at birth, before depth and fade. */
+    gain: number;
+};
+declare const MEDIUM_TRACK_LAYER_LOOK: Readonly<Record<keyof typeof MEDIUM_TRACK_PRESETS, VireUIKitTrackLayerLook>>;
+/** Seconds over which one alpha burst's rays are born: a strong source sprays rays one after
+ *  another, not all at the same instant. The first `MEDIUM_TRACK_LAYER_BURST_ACCENT` rays land on
+ *  the beat itself. */
+declare const MEDIUM_TRACK_LAYER_BURST_SPREAD = 1.6;
+declare const MEDIUM_TRACK_LAYER_BURST_ACCENT = 3;
+/** Shapes the brightness-vs-age curve as `(1 - age/life) ** gamma`: reaches exactly 0 at removal
+ *  (no pop when a track leaves the list) while staying close to full brightness for the first part
+ *  of its life (>1 skews the fade toward the end rather than a flat linear ramp down). */
+declare const MEDIUM_TRACK_LAYER_FADE_GAMMA = 1.6;
+/** Downward drift, as a fraction of `min(contentWidth, contentHeight)` per second — droplets that
+ *  formed along a track keep settling after the stamp itself, the same physical idea as
+ *  `MEDIUM_DEFAULTS.condensateSettleSpeed` but for this layer's own screen-space geometry rather
+ *  than the simulation grid. Small: over a track's longest life (muon, 2.2s) this alone moves it
+ *  well under a tenth of the frame. */
+declare const MEDIUM_TRACK_LAYER_GRAVITY_SAG = 0.018;
+/** Scales the curl field's push on a live track (see `web/track-layer.ts`'s `curlVelocityJS`),
+ *  units of `min(contentWidth, contentHeight)` per second per unit of curl velocity — small enough
+ *  to read as "nudged", not carried the way the gas itself is by `MEDIUM_DEFAULTS.advectSpeed`. */
+declare const MEDIUM_TRACK_LAYER_CURL_PUSH = 0.05;
 
 type VireUIKitMediumPlaybackState = 'idle' | 'playing' | 'paused' | 'stopped';
 type VireUIKitMediumTrackPresetName = keyof typeof MEDIUM_TRACK_PRESETS;
 /** The fully resolved geometry of one track stamp — the platform layer (`web/medium.ts`)
  *  translates fractions into simulation-grid pixels and binds the uniforms, deciding nothing else:
- *  which preset, where, and how bright is entirely this model's call. */
+ *  which preset, where, and how bright is entirely this model's call. Carries no color of its own
+ *  (there is no `channel` field): a track is lit the same way as the mist around it
+ *  (`MEDIUM_COMPOSITE_SHADER`), not tinted by which track it happens to be. */
 type VireUIKitMediumEmission = VireUIKitMediumTrackPreset & {
     /** 0…1, a fraction of the grid on both axes — the source point (cover art while playing;
      *  wherever it happens to land at rest). */
@@ -227,12 +364,16 @@ type VireUIKitMediumEmission = VireUIKitMediumTrackPreset & {
     /** Radians, direction from the source to the head. */
     angle: number;
     seed: number;
-    channel: readonly [number, number, number];
     /** 0 (farthest) … 1 (nearest), random within the full range and deterministic from `seed` — which
      *  plane the track reads as living on. Already folded into this emission's own `headWidthFrac`/
      *  `tailWidthFrac`/`intensity` below (see `buildEmission`); carried here too so a caller inspecting
      *  an emission can see why. */
     depth: number;
+    /** Which preset this emission was built from — `applyTrackDepth` already folds depth into the
+     *  numeric fields above, but the crisp screen-space track layer (`web/track-layer.ts`) still needs
+     *  the NAME: droplet density/size and per-kind lifetime are keyed off it, not off any numeric
+     *  field here (a depth-scaled `headWidthFrac` alone can't tell an alpha from an electron). */
+    kind: VireUIKitMediumTrackPresetName;
 };
 type VireUIKitMediumDynamicsInput = {
     state: VireUIKitMediumPlaybackState;
@@ -258,7 +399,10 @@ type VireUIKitMediumDynamics = {
  * Scales a track preset's width and intensity by depth (0 far … 1 near) — separated from
  * `buildEmission` below and exported so depth's effect on a preset is directly testable with two
  * plain numbers, independent of how a specific emission's depth got hashed from its seed. At
- * depth=1 this returns the preset's own numbers unchanged (both ranges' upper bound is 1).
+ * depth=1 this returns the preset's OWN intensity unchanged but its width scaled by the width
+ * range's own near end (`MEDIUM_TRACK_DEPTH_WIDTH_RANGE[1]`, now slightly above 1 — the nearest
+ * tracks read a little larger and softer than the base preset, not merely "as sharp as it gets";
+ * see that constant's own comment).
  */
 declare function applyTrackDepth(preset: VireUIKitMediumTrackPreset, depth: number): VireUIKitMediumTrackPreset;
 /**
@@ -268,4 +412,4 @@ declare function applyTrackDepth(preset: VireUIKitMediumTrackPreset, depth: numb
  */
 declare function createMediumDynamics(): VireUIKitMediumDynamics;
 
-export { wrappedDistanceFromZero as A, MEDIUM_DEFAULTS as M, type VireUIKitMediumChannel as V, MEDIUM_DEFAULT_CELL_PX as a, MEDIUM_DRIFT_TURBULENCE as b, MEDIUM_EMISSION_BEATS as c, MEDIUM_EMISSION_PROBABILITY as d, MEDIUM_MIN_EMISSION_INTERVAL as e, MEDIUM_NATURAL_INTERVAL as f, MEDIUM_NATURAL_JITTER as g, MEDIUM_PLAYING_TURBULENCE_RANGE as h, MEDIUM_PROBE_FLOOR_PX as i, MEDIUM_SENSITIVE_BOTTOM as j, MEDIUM_SENSITIVE_TOP as k, MEDIUM_TRACK_DEPTH_INTENSITY_RANGE as l, MEDIUM_TRACK_DEPTH_WIDTH_RANGE as m, MEDIUM_TRACK_PRESETS as n, MEDIUM_TURBULENCE_TAU as o, type VireUIKitMediumDynamics as p, type VireUIKitMediumDynamicsFrame as q, type VireUIKitMediumDynamicsInput as r, type VireUIKitMediumEmission as s, type VireUIKitMediumParams as t, type VireUIKitMediumPlaybackState as u, type VireUIKitMediumTrackPreset as v, type VireUIKitMediumTrackPresetName as w, applyTrackDepth as x, createMediumDynamics as y, depthFarOffsetPx as z };
+export { MEDIUM_TRACK_PRESETS as A, MEDIUM_TURBULENCE_TAU as B, type VireUIKitMediumDynamics as C, type VireUIKitMediumDynamicsFrame as D, type VireUIKitMediumDynamicsInput as E, type VireUIKitMediumEmission as F, type VireUIKitMediumParams as G, type VireUIKitMediumPlaybackState as H, type VireUIKitMediumTrackPreset as I, type VireUIKitMediumTrackPresetName as J, type VireUIKitTrackLayerLook as K, applyTrackDepth as L, MEDIUM_ALPHA_BURST_RAYS as M, createMediumDynamics as N, depthFarOffsetPx as O, wrappedDistanceFromZero as P, type VireUIKitMediumChannel as V, type VireUIKitMediumLight as a, MEDIUM_ALPHA_RAY_LENGTH_SCALE as b, MEDIUM_DEFAULTS as c, MEDIUM_DEFAULT_CELL_PX as d, MEDIUM_DEFAULT_LIGHTS as e, MEDIUM_DRIFT_TURBULENCE as f, MEDIUM_EMISSION_BEATS as g, MEDIUM_EMISSION_PROBABILITY as h, MEDIUM_MAX_LIGHTS as i, MEDIUM_MIN_EMISSION_INTERVAL as j, MEDIUM_NATURAL_INTERVAL as k, MEDIUM_NATURAL_JITTER as l, MEDIUM_PLAYING_TURBULENCE_RANGE as m, MEDIUM_PROBE_FLOOR_PX as n, MEDIUM_SENSITIVE_BOTTOM as o, MEDIUM_SENSITIVE_TOP as p, MEDIUM_TRACK_DEPTH_INTENSITY_RANGE as q, MEDIUM_TRACK_DEPTH_WIDTH_RANGE as r, MEDIUM_TRACK_LAYER_BURST_ACCENT as s, MEDIUM_TRACK_LAYER_BURST_SPREAD as t, MEDIUM_TRACK_LAYER_CURL_PUSH as u, MEDIUM_TRACK_LAYER_FADE_GAMMA as v, MEDIUM_TRACK_LAYER_GRAVITY_SAG as w, MEDIUM_TRACK_LAYER_LIFE_SECONDS as x, MEDIUM_TRACK_LAYER_LOOK as y, MEDIUM_TRACK_LAYER_MAX_TRACKS as z };