vireuikit 0.1.0 → 0.2.0

package/dist/{dynamics-BqBoj03x.d.ts → dynamics-DelasYER.d.ts}

@@ -59,8 +59,83 @@ type VireUIKitMediumParams = {
     baseColor: VireUIKitMediumChannel;
     /** Background weight in the Oklab mix: keeps the platform tone visible even where the smoke is dense. */
     baseWeight: number;
+    /** Field-sample scale for the far depth plane, k ≥ 1 (see `MEDIUM_COMPOSITE_SHADER`): the far
+     *  plane reads the SAME vapor/condensate field as the near plane, at `src * k + offset` instead
+     *  of `src`. A larger k folds more of the field into the same screen area, so the identical
+     *  evolving field reads as both finer-grained structure (features occupy fewer screen-px) and,
+     *  because the field's own motion maps to screen motion as v/k, slower apparent motion — parallax
+     *  and scale-of-structure from one number, with no second simulation. Measured against
+     *  `check-medium.mjs`'s parallax gate (a cross-correlation best-shift, not a centroid — see the
+     *  gate's own comment on why): 1.6 puts the far/near screen-speed ratio at 0.630, matching the
+     *  naive prediction 1/1.6 = 0.625 almost exactly, comfortably inside a band that reads as depth
+     *  without the far plane looking frozen. */
+    depthFarScale: number;
+    /** Offset into the shared field for the far plane, as a FRACTION of the grid's own width/height
+     *  (per axis) rather than a fixed grid-px value — the field wraps (`gl.REPEAT`), so a fixed
+     *  grid-px offset's EFFECTIVE (wrapped) distance from zero depends on whatever grid size it
+     *  happens to run at, and can land close to zero by accident at a size nobody tested against.
+     *  (This shipped once as `[41, 67]` grid-px: harmless at the 96px grid the depth gates tested
+     *  against, but 67 wraps to just 5px at the 72px grid height this package's own README uses as
+     *  its example — the far plane nearly re-read the near one, exactly the echo depth exists to
+     *  avoid.) A fraction keeps the wrapped distance proportional to the grid at any size — see
+     *  `depthFarOffsetPx` below and `check-medium.mjs`'s decorrelation gate, which measures this
+     *  directly at the README's own 128x72. */
+    depthFarOffsetFrac: readonly [number, number];
+    /** Grid-px tap radius for the far plane's 4-tap box blur. A spatial average cannot raise local
+     *  variance, so the same blur that softens the far plane's edges also, by construction, lowers
+     *  its measured contrast — one mechanism for both aerial-perspective cues (no separate contrast
+     *  knob exists). 0 disables it (the near plane stays sharp). Measured: reading the far plane's
+     *  own scale/offset with no blur already drops contrast ~6% (a fixed offset can land on a
+     *  locally denser or sparser patch of a field that isn't spatially uniform); this radius takes
+     *  the total to 24% — see the aerial-perspective gate, whose two thresholds isolate blur's own
+     *  share from that baseline. */
+    depthFarBlurRadius: number;
+    /** The far plane's share of the mix, relative to the near plane's implicit 1 — aerial
+     *  perspective's other half: even at equal density the far plane must not compete with the near
+     *  one for attention. */
+    depthFarWeight: number;
+    /** grid-px/s — a small downward drift added to VAPOR's own velocity, on top of the shared
+     *  curl-noise field (condensate already settles faster via `condensateSettleSpeed`). An order of
+     *  magnitude below it so the gas reads as "barely noticeable" drift rather than visibly falling.
+     *  ADDS NO DENSITY: on this periodic (`gl.REPEAT`) grid a uniform drift only ever translates the
+     *  field and wraps it back in at the top — it cannot accumulate mass anywhere, the way a real
+     *  floor would. It is a motion cue (which way is down), not a source of "denser at the bottom" —
+     *  that reading comes entirely from `gravityBottomBoost` below. See
+     *  `check-medium.mjs`'s vapor-drift gate, which checks DIRECTION over a short window rather than
+     *  a density ratio, for exactly this reason. */
+    gravityVaporDrift: number;
+    /** Density boost at the very bottom of the frame, added on top of 1 — a COMPOSITING-only effect:
+     *  it scales how the already-conserved vapor/condensate density is DISPLAYED, never the
+     *  simulated buffers themselves, so it cannot threaten the water-conservation invariant by
+     *  construction, and — unlike `gravityVaporDrift` above — this is the mechanism that actually
+     *  produces "denser at the bottom": it is a steady-state property of the compositing math, true
+     *  from the very first frame, independent of any warmup or mixing time (see
+     *  `check-medium.mjs`'s boost gate, which measures it with zero simulated steps for exactly that
+     *  reason). Large in absolute terms because `baseWeight` (0.9) dominates the Oklab mix wherever
+     *  gas density is thin — a small boost gets diluted into an invisible change in the final color;
+     *  measured this large to register as a real, visible band against that dilution. */
+    gravityBottomBoost: number;
+    /** Fraction of frame height (0 top, 1 bottom) where the bottom boost starts ramping in via
+     *  `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;
 };
 declare const MEDIUM_DEFAULTS: VireUIKitMediumParams;
+/**
+ * Resolves the far plane's fractional offset (`depthFarOffsetFrac`) into grid-px for a GIVEN grid
+ * size — pure and exported so the wrap-safety it exists for is directly testable (see
+ * `medium-depth-offset.test.ts`) without spinning up a WebGL2 context. Per-axis: `gridWidth` and
+ * `gridHeight` are independent, and a non-square grid (the README's own 128x72 example) shouldn't
+ * distort one axis relative to the other.
+ */
+declare function depthFarOffsetPx(offsetFrac: readonly [number, number], gridWidth: number, gridHeight: number): readonly [number, number];
+/**
+ * How far a value lands from the nearest wrap boundary (0 or `period`) on a periodic axis of the
+ * given `period` — the quantity that actually matters for decorrelation, not the raw offset value
+ * itself (a raw offset near the period is effectively a tiny one once the field wraps). Exported
+ * for the same reason as `depthFarOffsetPx`: a plain number, testable without a GPU.
+ */
+declare function wrappedDistanceFromZero(value: number, period: number): number;
 /** The material probe can't see texture finer than this: there is no gain in a denser simulation
  *  grid than the probe's own floor. */
 declare const MEDIUM_PROBE_FLOOR_PX = 22;
@@ -115,6 +190,18 @@ declare const MEDIUM_NATURAL_JITTER = 35;
  *  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;
+/** 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. */
+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];
 
 type VireUIKitMediumPlaybackState = 'idle' | 'playing' | 'paused' | 'stopped';
 type VireUIKitMediumTrackPresetName = keyof typeof MEDIUM_TRACK_PRESETS;
@@ -129,6 +216,11 @@ type VireUIKitMediumEmission = VireUIKitMediumTrackPreset & {
     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;
 };
 type VireUIKitMediumDynamicsInput = {
     state: VireUIKitMediumPlaybackState;
@@ -150,6 +242,13 @@ type VireUIKitMediumDynamicsFrame = {
 type VireUIKitMediumDynamics = {
     step(input: VireUIKitMediumDynamicsInput): VireUIKitMediumDynamicsFrame;
 };
+/**
+ * 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).
+ */
+declare function applyTrackDepth(preset: VireUIKitMediumTrackPreset, depth: number): VireUIKitMediumTrackPreset;
 /**
  * Stateful "playback dynamics" model: turbulence and emission scheduling per frame. Platform
  * neutral — the caller supplies the clock and the playback position (in a bench, that would be
@@ -157,4 +256,4 @@ type VireUIKitMediumDynamics = {
  */
 declare function createMediumDynamics(): VireUIKitMediumDynamics;
 
-export { 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_PRESETS as l, MEDIUM_TURBULENCE_TAU as m, type VireUIKitMediumDynamics as n, type VireUIKitMediumDynamicsFrame as o, type VireUIKitMediumDynamicsInput as p, type VireUIKitMediumEmission as q, type VireUIKitMediumParams as r, type VireUIKitMediumPlaybackState as s, type VireUIKitMediumTrackPreset as t, type VireUIKitMediumTrackPresetName as u, createMediumDynamics as v };
+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 };

package/dist/index.cjs

@@ -291,8 +291,22 @@ var MEDIUM_DEFAULTS = {
   condensateColor: [0.94, 0.95, 0.97],
   channelColors: neutralSpecies(BASE_COLOR),
   baseColor: BASE_COLOR,
-  baseWeight: 0.9
+  baseWeight: 0.9,
+  depthFarScale: 1.6,
+  depthFarOffsetFrac: [0.47, 0.53],
+  depthFarBlurRadius: 5,
+  depthFarWeight: 0.5,
+  gravityVaporDrift: 0.6,
+  gravityBottomBoost: 2,
+  gravityBottomBoostStart: 0.75
 };
+function depthFarOffsetPx(offsetFrac, gridWidth, gridHeight) {
+  return [offsetFrac[0] * gridWidth, offsetFrac[1] * gridHeight];
+}
+function wrappedDistanceFromZero(value, period) {
+  const wrapped = (value % period + period) % period;
+  return Math.min(wrapped, period - wrapped);
+}
 var MEDIUM_PROBE_FLOOR_PX = 22;
 var MEDIUM_DEFAULT_CELL_PX = 26;
 var MEDIUM_TRACK_PRESETS = {
@@ -337,6 +351,8 @@ var MEDIUM_NATURAL_INTERVAL = 25;
 var MEDIUM_NATURAL_JITTER = 35;
 var MEDIUM_SENSITIVE_TOP = 0.55;
 var MEDIUM_SENSITIVE_BOTTOM = 0.95;
+var MEDIUM_TRACK_DEPTH_WIDTH_RANGE = [0.55, 1];
+var MEDIUM_TRACK_DEPTH_INTENSITY_RANGE = [0.4, 1];
 
 // src/medium/noise.ts
 var VG_VALUE_NOISE = `
@@ -521,11 +537,16 @@ var MEDIUM_ADVECT_VELOCITY_SETTLE = `
 ${MEDIUM_ADVECT_VELOCITY}
   vel.y += u_settleSpeed;
 `;
+var MEDIUM_ADVECT_VELOCITY_VAPOR = `
+${MEDIUM_ADVECT_VELOCITY}
+  vel.y += u_vaporDrift;
+`;
 var MEDIUM_VAPOR_FORWARD_SHADER = `
 ${MEDIUM_ADVECT_UNIFORMS}
+uniform float u_vaporDrift;
 
 half4 main(float2 xy) {
-${MEDIUM_ADVECT_VELOCITY}
+${MEDIUM_ADVECT_VELOCITY_VAPOR}
   float2 src = xy - vel * u_dt;
   return u_dye.eval(float2(src.x, u_dyeSize.y - src.y));
 }
@@ -561,9 +582,10 @@ var MEDIUM_MACCORMACK_CORRECT = `
 var MEDIUM_VAPOR_CORRECT_SHADER = `
 ${MEDIUM_ADVECT_UNIFORMS}
 uniform shader u_forward;
+uniform float u_vaporDrift;
 
 half4 main(float2 xy) {
-${MEDIUM_ADVECT_VELOCITY}
+${MEDIUM_ADVECT_VELOCITY_VAPOR}
 ${MEDIUM_MACCORMACK_CORRECT}
   return limited;
 }
@@ -683,17 +705,52 @@ uniform float3 u_labCondensate;
 uniform float  u_baseWeight;
 uniform float  u_condensateTint;
 uniform float  u_condensateGain;
+uniform float  u_farScale;
+uniform float2 u_farOffset;
+uniform float  u_farBlurRadius;
+uniform float  u_farWeight;
+uniform float  u_gravityBoost;
+uniform float  u_gravityBoostStart;
 
 ${VG_OKLAB_TO_SRGB}
 
 half4 main(float2 xy) {
-  float2 src = xy * u_dyeScale;
-  half4 vapor = u_vapor.eval(src);
-  half4 condensate = u_condensate.eval(src);
-  half4 track = u_track.eval(src);
-  float w0 = float(vapor.r) + float(track.r);
-  float w1 = float(vapor.g) + float(track.g);
-  float w2 = float(vapor.b) + float(track.b);
+  float2 baseSrc = xy * u_dyeScale;
+
+  // Near plane \u2014 sampled exactly as before the depth work; the calibrated look lives here.
+  half4 vapor = u_vapor.eval(baseSrc);
+  half4 condensate = u_condensate.eval(baseSrc);
+  half4 track = u_track.eval(baseSrc);
+
+  // Far plane \u2014 the identical field, scaled and offset (see the file header). A 4-tap box blur
+  // (no separate center sample, the cheapest isotropic blur available) supplies aerial perspective's
+  // blur and, as a side effect of averaging, its lower contrast too.
+  float2 farSrc = baseSrc * u_farScale + u_farOffset;
+  float2 blurX = float2(u_farBlurRadius, 0.0);
+  float2 blurY = float2(0.0, u_farBlurRadius);
+  half4 vaporFar = (u_vapor.eval(farSrc + blurX) + u_vapor.eval(farSrc - blurX) +
+                     u_vapor.eval(farSrc + blurY) + u_vapor.eval(farSrc - blurY)) * half4(0.25);
+  half4 condensateFar = (u_condensate.eval(farSrc + blurX) + u_condensate.eval(farSrc - blurX) +
+                          u_condensate.eval(farSrc + blurY) + u_condensate.eval(farSrc - blurY)) * half4(0.25);
+
+  // Gravity's "denser layer at the bottom of the chamber" \u2014 a compositing-only boost (see
+  // MEDIUM_DEFAULTS.gravityBottomBoost): it scales how density already in the conserved buffers is
+  // DISPLAYED, never the buffers themselves, so it can't threaten water conservation. Shared by
+  // both planes: the chamber's floor is denser everywhere along its depth, not just up close.
+  //
+  // Verified with a headless render, not assumed: ramping this with xy.y directly lit up the TOP
+  // of the frame, not the bottom (contentTexture's own orientation contract flips y once more
+  // between this pass and the final scene \u2014 see the file header) \u2014 hence the 1.0 - below.
+  float bottomFrac = 1.0 - xy.y / u_resolution.y;
+  float bottomT = smoothstep(u_gravityBoostStart, 1.0, bottomFrac);
+  float bottomBoost = 1.0 + u_gravityBoost * bottomT;
+
+  float gasR = (float(vapor.r) + float(vaporFar.r) * u_farWeight) * bottomBoost;
+  float gasG = (float(vapor.g) + float(vaporFar.g) * u_farWeight) * bottomBoost;
+  float gasB = (float(vapor.b) + float(vaporFar.b) * u_farWeight) * bottomBoost;
+  float w0 = gasR + float(track.r);
+  float w1 = gasG + float(track.g);
+  float w2 = gasB + float(track.b);
   float wBg = u_baseWeight;
 
   // A faint condensate hint from the LOCAL vapor, not its own color (droplets scatter light
@@ -701,7 +758,8 @@ half4 main(float2 xy) {
   float vaporLocal = max(w0 + w1 + w2, 1e-4);
   float3 vaporHue = (u_lab0 * w0 + u_lab1 * w1 + u_lab2 * w2) / vaporLocal;
   float3 condensateLab = mix(u_labCondensate, vaporHue, u_condensateTint);
-  float wCondensate = float(condensate.r) * u_condensateGain;
+  float wCondensate =
+    (float(condensate.r) + float(condensateFar.r) * u_farWeight) * u_condensateGain * bottomBoost;
 
   float total = max(w0 + w1 + w2 + wBg + wCondensate, 1e-4);
   float3 mixLab =
@@ -761,15 +819,31 @@ function channelFromSeed(seed) {
   const idx = Math.floor(hash01(seed * 1.37) * 3) % 3;
   return idx === 0 ? [1, 0, 0] : idx === 1 ? [0, 1, 0] : [0, 0, 1];
 }
+function lerp(range, t) {
+  return range[0] + (range[1] - range[0]) * t;
+}
+function applyTrackDepth(preset, depth) {
+  const widthScale = lerp(MEDIUM_TRACK_DEPTH_WIDTH_RANGE, depth);
+  const intensityScale = lerp(MEDIUM_TRACK_DEPTH_INTENSITY_RANGE, depth);
+  return {
+    ...preset,
+    headWidthFrac: preset.headWidthFrac * widthScale,
+    tailWidthFrac: preset.tailWidthFrac * widthScale,
+    intensity: preset.intensity * intensityScale
+  };
+}
 function buildEmission(presetName, source, seed, intensityScale) {
   const preset = MEDIUM_TRACK_PRESETS[presetName];
+  const depth = hash01(seed * 4.63);
+  const depthApplied = applyTrackDepth(preset, depth);
   return {
-    ...preset,
-    intensity: preset.intensity * intensityScale,
+    ...depthApplied,
+    intensity: depthApplied.intensity * intensityScale,
     source,
     angle: hash01(seed * 7.31) * Math.PI * 2,
     seed,
-    channel: channelFromSeed(seed)
+    channel: channelFromSeed(seed),
+    depth
   };
 }
 function createMediumDynamics() {
@@ -845,6 +919,8 @@ exports.MEDIUM_SPECIES_HUE_SPREAD = MEDIUM_SPECIES_HUE_SPREAD;
 exports.MEDIUM_SPECIES_LIGHTNESS = MEDIUM_SPECIES_LIGHTNESS;
 exports.MEDIUM_TIME_PERIOD = MEDIUM_TIME_PERIOD;
 exports.MEDIUM_TRACK_ADVECT_SHADER = MEDIUM_TRACK_ADVECT_SHADER;
+exports.MEDIUM_TRACK_DEPTH_INTENSITY_RANGE = MEDIUM_TRACK_DEPTH_INTENSITY_RANGE;
+exports.MEDIUM_TRACK_DEPTH_WIDTH_RANGE = MEDIUM_TRACK_DEPTH_WIDTH_RANGE;
 exports.MEDIUM_TRACK_PRESETS = MEDIUM_TRACK_PRESETS;
 exports.MEDIUM_TURBULENCE_TAU = MEDIUM_TURBULENCE_TAU;
 exports.MEDIUM_VAPOR_CORRECT_SHADER = MEDIUM_VAPOR_CORRECT_SHADER;
@@ -854,12 +930,14 @@ exports.OKLAB_TO_LMS = OKLAB_TO_LMS;
 exports.VG_CURL_NOISE = VG_CURL_NOISE;
 exports.VG_OKLAB_TO_SRGB = VG_OKLAB_TO_SRGB;
 exports.VG_VALUE_NOISE = VG_VALUE_NOISE;
+exports.applyTrackDepth = applyTrackDepth;
 exports.atomAtRest = atomAtRest;
 exports.atomLift = atomLift;
 exports.atomMaterial = atomMaterial;
 exports.characterOf = characterOf;
 exports.createGrowthState = createGrowthState;
 exports.createMediumDynamics = createMediumDynamics;
+exports.depthFarOffsetPx = depthFarOffsetPx;
 exports.growthFrame = growthFrame;
 exports.growthInk = growthInk;
 exports.growthPhase = growthPhase;
@@ -870,5 +948,6 @@ exports.speciesFamily = speciesFamily;
 exports.srgbToOklab = srgbToOklab;
 exports.stepGrowth = stepGrowth;
 exports.stepSpring = stepSpring;
+exports.wrappedDistanceFromZero = wrappedDistanceFromZero;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map