vireuikit 0.1.0 → 0.3.0

package/dist/dynamics-7Bq3LLds.d.ts

@@ -0,0 +1,271 @@
+type VireUIKitMediumChannel = readonly [number, number, number];
+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. */
+    decay: number;
+    /** Spatial frequency of the curl-noise potential, 1/px of the simulation grid. */
+    curlFreq: number;
+    /** Drift speed of the noise domain over time, 1/s. */
+    curlSpeed: number;
+    /** Velocity field scale, grid-px/s — how far the smoke can be carried in a second. */
+    advectSpeed: number;
+    /** Turbulence gate, 0…1 (playback drives it: playing is alive, paused cools down). The
+     *  per-frame value is computed by `createMediumDynamics` (`dynamics.ts`) — it arrives here
+     *  already resolved. */
+    turbulence: number;
+    /** 1/s — the fraction of vapor EXCESS above `condensationFloor` that turns into condensate every
+     *  second from background seeding: weak, everywhere, all the time — the chamber is never
+     *  perfectly clean. */
+    condensationRate: number;
+    /** Vapor density (in seed-density units, a spot's peak ≈1) below which condensation does not
+     *  happen at all — only the excess above it condenses. Without a floor, the condensate would
+     *  exactly retrace the vapor spot's shape (the same outline, or softer from growth blur), and
+     *  the two phases would have nowhere to visually diverge: vapor is already soft, so the floor
+     *  concentrates condensate in dense turbulence cores, leaving the sparse vapor around it
+     *  uncondensed. Keep it NOTICEABLY below the settled mean vapor level (turbulence stirs spots
+     *  into a nearly flat background of ~0.3 over a few minutes — a known limit of the numerical
+     *  advection): a floor above that mean eventually stops finding any excess at all, and
+     *  condensation dies out for good. */
+    condensationFloor: number;
+    /** 1/s — the fraction of condensate evaporating back into vapor. Larger than the condensation
+     *  rate: at equilibrium most of the water stays vapor, which is the "supersaturated" one. */
+    evaporationRate: number;
+    /** grid-px/s — condensate drift downward, on top of the shared velocity field: gravity touches
+     *  droplets and leaves vapor alone. */
+    condensateSettleSpeed: number;
+    /** Multiplier on the ambient curl field's OWN x-component, added to settling UNCONDITIONALLY
+     *  (not gated by `turbulence` the way the shared velocity field is) — see
+     *  MEDIUM_ADVECT_VELOCITY_SETTLE in advect-shader.ts. Without it, a droplet falling at a constant
+     *  `condensateSettleSpeed` with only a turbulence-gated sideways push traces a near-straight
+     *  vertical line whenever turbulence is low (rest/paused: 0.045, over 20x below the gated push
+     *  needed to bend the fall) — many droplets in nearby columns then read as parallel vertical
+     *  streaks, one of the axis-aligned artifacts `check-medium.mjs`'s isotropy gate measures. Reuses
+     *  the SAME seamless curl field `vel` already reads rather than a second noise system, so it adds
+     *  no new seam of its own. Calibrated against that gate at the product's default grid (1920x952,
+     *  74x37) — see the gate's own report for the measured ratio at this value. */
+    condensateSettleWiggle: number;
+    /** 1/s — the rate at which a droplet blends with its grid neighbors. There is no separate age
+     *  counter: the blend repeats every frame, and whatever has survived more frames ends up more
+     *  blended with its neighbors on its own — that IS "growth". Keep it NOTICEABLY below
+     *  `evaporationRate`: over a droplet's average lifetime (1/evaporationRate) only a small
+     *  fraction should get to blend — otherwise the blur outruns evaporation and the whole grid
+     *  levels into flat fog before a droplet gets a chance to return to vapor (visible by eye: the
+     *  contrast between "a patch of droplets" and the vapor background disappears within seconds). */
+    condensateSpreadRate: number;
+    /** 0…1 — how much of the local vapor hue shows through in the condensate. Droplets carry no
+     *  color of their own (droplets scatter light rather than tint it) — this is only a faint hint
+     *  of the surroundings. */
+    condensateTint: number;
+    /** Condensate's visibility multiplier in the Oklab mix relative to vapor at equal density —
+     *  droplets hold a small share of the water's mass, but they are mostly what's visible (as in a
+     *  real cloud: vapor is transparent, droplets create the visibility). */
+    condensateGain: number;
+    /** 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`. */
+    channelColors: readonly [VireUIKitMediumChannel, VireUIKitMediumChannel, 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. */
+    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 radius of the far plane's 8-tap ring blur, rotated so no tap pair lies on a grid
+     *  axis. 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;
+/** Device-px per simulation grid cell by default — noticeably coarser than the probe floor;
+ *  sharpening the detail visible right next to the glass is a later increment (emission and
+ *  palette). */
+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).
+ */
+type VireUIKitMediumTrackPreset = {
+    lengthFrac: number;
+    headWidthFrac: number;
+    tailWidthFrac: number;
+    /** Amplitude of the path's sideways noise, as a fraction of `min(gridW, gridH)`; 0 = a straight thread. */
+    raggedFrac: number;
+    raggedFreq: number;
+    /** How far the tail has settled downward, as a fraction of `min(gridW, gridH)`. */
+    settleFrac: number;
+    /** How much dimmer the tail is than the head, 0…1. */
+    tailDim: number;
+    intensity: number;
+};
+declare const MEDIUM_TRACK_PRESETS: Readonly<Record<'alpha' | 'beta' | 'natural', 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;
+/** Turbulence range during playback: the low end is a quiet stretch of the track, the high end is
+ *  peak amplitude. */
+declare const MEDIUM_PLAYING_TURBULENCE_RANGE: readonly [number, number];
+/** Turbulence smoothing time constant, seconds: both ramping up on play and cooling down on pause
+ *  go through this filter — smooth, never a jump. */
+declare const MEDIUM_TURBULENCE_TAU = 2.5;
+/** Emission cadence — once every this many beats, not on every beat: at 120–180 BPM that is
+ *  0.5–0.75 Hz, an order of magnitude below the WCAG 2.3.1 photosensitivity ceiling (3 Hz). */
+declare const MEDIUM_EMISSION_BEATS = 4;
+/** Fraction of the beats that actually get an emission — breaks up the exact periodicity (a
+ *  metronome-perfect pulse reads as mechanical) without moving the average rate. */
+declare const MEDIUM_EMISSION_PROBABILITY = 0.55;
+/** Emergency floor between two emissions, seconds — a safeguard for the same WCAG 2.3.1
+ *  requirement, independent of `MEDIUM_EMISSION_BEATS`/BPM: even a mistake in the other constants
+ *  can't flash faster than this. */
+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;
+/** 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;
+/** 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;
+/** 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. */
+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). */
+    source: readonly [number, number];
+    /** 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;
+};
+type VireUIKitMediumDynamicsInput = {
+    state: VireUIKitMediumPlaybackState;
+    /** Beats per minute of the active track; unread in states with no track. */
+    bpm: number;
+    /** 0…1 — a continuous volume envelope (e.g. from precomputed waveform peaks), NOT the beat itself. */
+    amplitude: number;
+    /** Seconds, a deterministic playback position (not wall-clock time) — the emission cadence has
+     *  to be derived from it rather than accumulating its own phase. */
+    positionSeconds: number;
+    /** 0…1 — the area of the active track's cover art that emission comes from while playing. */
+    sourcePoint: readonly [number, number];
+    dt: number;
+};
+type VireUIKitMediumDynamicsFrame = {
+    turbulence: number;
+    emissions: readonly VireUIKitMediumEmission[];
+};
+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
+ * its own render loop); it never reads `performance.now()` or the DOM itself.
+ */
+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 };

package/dist/index.cjs

@@ -285,14 +285,29 @@ var MEDIUM_DEFAULTS = {
   condensationFloor: 0.12,
   evaporationRate: 0.2,
   condensateSettleSpeed: 8,
+  condensateSettleWiggle: 0.4,
   condensateSpreadRate: 0.08,
   condensateTint: 0.2,
   condensateGain: 5,
   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 +352,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 = `
@@ -468,6 +485,71 @@ float2 vgCurlVelocity(float2 p, float phase) {
   float py0 = vgPotential(p - float2(0.0, e), phase);
   return float2(py1 - py0, -(px1 - px0)) / (2.0 * e);
 }
+
+// vgPotential above is periodic in TIME only: the simulation domain is a torus (gl.REPEAT), but
+// the lattice itself never wraps in x/y, so velocity jumps at the domain seam and dye on either
+// side of it is transported differently \u2014 a straight seam, made worse wherever something re-reads
+// the field at a different scale (the far depth plane's tile boundary). vgValueNoise3Seamless
+// wraps ALL THREE lattice axes: xyPeriod/zPeriod fold BOTH neighbors of a cell into their own
+// period before hashing, so the field is EXACTLY the same one period over, in space exactly as it
+// already was in time.
+//
+// The period has to be an integer number of lattice cells, or the wrap would jump instead of
+// closing seamlessly (the same requirement MEDIUM_TIME_OCTAVES/mediumOctavePeriod enforces for
+// time) \u2014 but unlike time, the spatial period depends on the GRID SIZE, which this shader has no
+// notion of. So xyPeriod travels together with a per-octave spatial frequency the CPU computes to
+// make gridSize * frequency land on that exact integer (see computeMediumSpatialPeriods below);
+// both arrive together as one uniform per octave (u_spatialN.xy = frequency, .zw = period),
+// recomputed by web/medium.ts whenever the grid resizes.
+float vgValueNoise3Seamless(float3 p, float2 xyPeriod, float zPeriod) {
+  float3 i = floor(p);
+  float3 f = fract(p);
+  float3 u = f * f * (3.0 - 2.0 * f);
+  float x0 = mod(i.x, xyPeriod.x);
+  float x1 = mod(i.x + 1.0, xyPeriod.x);
+  float y0 = mod(i.y, xyPeriod.y);
+  float y1 = mod(i.y + 1.0, xyPeriod.y);
+  float z0 = mod(i.z, zPeriod);
+  float z1 = mod(i.z + 1.0, zPeriod);
+  float n000 = vgHash31(float3(x0, y0, z0));
+  float n100 = vgHash31(float3(x1, y0, z0));
+  float n010 = vgHash31(float3(x0, y1, z0));
+  float n110 = vgHash31(float3(x1, y1, z0));
+  float n001 = vgHash31(float3(x0, y0, z1));
+  float n101 = vgHash31(float3(x1, y0, z1));
+  float n011 = vgHash31(float3(x0, y1, z1));
+  float n111 = vgHash31(float3(x1, y1, z1));
+  float nx00 = mix(n000, n100, u.x);
+  float nx10 = mix(n010, n110, u.x);
+  float nx01 = mix(n001, n101, u.x);
+  float nx11 = mix(n011, n111, u.x);
+  float nxy0 = mix(nx00, nx10, u.y);
+  float nxy1 = mix(nx01, nx11, u.y);
+  return mix(nxy0, nxy1, u.z) * 2.0 - 1.0;
+}
+
+// Same four-octave fbm as vgPotential, but every octave reads the seamless lattice above at its
+// OWN (frequency, period) pair \u2014 sN.xy replaces that octave's compile-time \`scale\` constant (it
+// has to be a uniform now: the adjustment depends on the live grid size), sN.zw is the matching
+// integer period. \`p\` is still curlFreq-scaled exactly as vgPotential's caller scales it \u2014 only
+// the per-octave multiplier changed from a constant to a grid-dependent uniform, so the finite
+// difference in vgCurlVelocitySeamless below needs no epsilon change of its own.
+float vgPotentialSeamless(float2 p, float phase, float4 s0, float4 s1, float4 s2, float4 s3) {
+  float v = vgValueNoise3Seamless(float3(p * s0.xy, phase * ${VG_OCT0.rate} + ${VG_OCT0.offset}), s0.zw, ${VG_OCT0.period}) * 0.5;
+  v += vgValueNoise3Seamless(float3(p * s1.xy, phase * ${VG_OCT1.rate} + ${VG_OCT1.offset}), s1.zw, ${VG_OCT1.period}) * 0.25;
+  v += vgValueNoise3Seamless(float3(p * s2.xy, phase * ${VG_OCT2.rate} + ${VG_OCT2.offset}), s2.zw, ${VG_OCT2.period}) * 0.125;
+  float macro = vgValueNoise3Seamless(float3(p * s3.xy, phase * ${VG_OCT3.rate} + ${VG_OCT3.offset}), s3.zw, ${VG_OCT3.period});
+  return v * (0.7 + 0.3 * macro);
+}
+
+float2 vgCurlVelocitySeamless(float2 p, float phase, float4 s0, float4 s1, float4 s2, float4 s3) {
+  float e = 0.6;
+  float px1 = vgPotentialSeamless(p + float2(e, 0.0), phase, s0, s1, s2, s3);
+  float px0 = vgPotentialSeamless(p - float2(e, 0.0), phase, s0, s1, s2, s3);
+  float py1 = vgPotentialSeamless(p + float2(0.0, e), phase, s0, s1, s2, s3);
+  float py0 = vgPotentialSeamless(p - float2(0.0, e), phase, s0, s1, s2, s3);
+  return float2(py1 - py0, -(px1 - px0)) / (2.0 * e);
+}
 `;
 
 // src/medium/seed-shader.ts
@@ -511,21 +593,36 @@ uniform float  u_phase;
 uniform float  u_curlFreq;
 uniform float  u_advectSpeed;
 uniform float  u_turbulence;
+// One float4 per MEDIUM_TIME_OCTAVES entry: xy is that octave's seamless spatial frequency, zw its
+// matching integer lattice period \u2014 both grid-size-dependent, so they can't be compile-time
+// constants (see vgPotentialSeamless/computeMediumSpatialPeriods in noise.ts). Recomputed by
+// web/medium.ts's bindVelocityUniforms every frame from the live grid dimensions.
+uniform float4 u_spatial0;
+uniform float4 u_spatial1;
+uniform float4 u_spatial2;
+uniform float4 u_spatial3;
 
 ${VG_CURL_NOISE}
 `;
 var MEDIUM_ADVECT_VELOCITY = `
-  float2 vel = vgCurlVelocity(xy * u_curlFreq, u_phase) * u_advectSpeed * u_turbulence;
+  float2 curl = vgCurlVelocitySeamless(xy * u_curlFreq, u_phase, u_spatial0, u_spatial1, u_spatial2, u_spatial3);
+  float2 vel = curl * u_advectSpeed * u_turbulence;
 `;
 var MEDIUM_ADVECT_VELOCITY_SETTLE = `
 ${MEDIUM_ADVECT_VELOCITY}
   vel.y += u_settleSpeed;
+  vel.x += curl.x * u_advectSpeed * u_settleWiggle;
+`;
+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));
 }
@@ -533,6 +630,7 @@ ${MEDIUM_ADVECT_VELOCITY}
 var MEDIUM_CONDENSATE_FORWARD_SHADER = `
 ${MEDIUM_ADVECT_UNIFORMS}
 uniform float u_settleSpeed;
+uniform float u_settleWiggle;
 
 half4 main(float2 xy) {
 ${MEDIUM_ADVECT_VELOCITY_SETTLE}
@@ -561,9 +659,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;
 }
@@ -571,6 +670,7 @@ ${MEDIUM_MACCORMACK_CORRECT}
 var MEDIUM_CONDENSATE_CORRECT_SHADER = `
 ${MEDIUM_ADVECT_UNIFORMS}
 uniform float u_settleSpeed;
+uniform float u_settleWiggle;
 uniform shader u_forward;
 
 half4 main(float2 xy) {
@@ -670,6 +770,39 @@ ${MEDIUM_ADVECT_VELOCITY}
 `;
 
 // src/medium/composite-shader.ts
+var VG_CUBIC_WEIGHTS = `
+float4 vgCubicWeights(float v) {
+  float4 n = float4(1.0, 2.0, 3.0, 4.0) - v;
+  float4 s = n * n * n;
+  float x = s.x;
+  float y = s.y - 4.0 * s.x;
+  float z = s.z - 4.0 * s.y + 6.0 * s.x;
+  float w = 6.0 - x - y - z;
+  return float4(x, y, z, w) * (1.0 / 6.0);
+}
+`;
+function vgBicubicSampler(fnName, textureName) {
+  return `
+half4 ${fnName}(float2 px) {
+  float2 shifted = px - 0.5;
+  float2 fxy = fract(shifted);
+  float2 base = shifted - fxy;
+  float4 xw = vgCubicWeights(fxy.x);
+  float4 yw = vgCubicWeights(fxy.y);
+  float2 sx = float2(xw.x + xw.y, xw.z + xw.w);
+  float2 sy = float2(yw.x + yw.y, yw.z + yw.w);
+  float2 offsetX = float2(base.x - 0.5 + xw.y / sx.x, base.x + 1.5 + xw.w / sx.y);
+  float2 offsetY = float2(base.y - 0.5 + yw.y / sy.x, base.y + 1.5 + yw.w / sy.y);
+  half4 s00 = ${textureName}.eval(float2(offsetX.x, offsetY.x));
+  half4 s10 = ${textureName}.eval(float2(offsetX.y, offsetY.x));
+  half4 s01 = ${textureName}.eval(float2(offsetX.x, offsetY.y));
+  half4 s11 = ${textureName}.eval(float2(offsetX.y, offsetY.y));
+  float wx = sx.x / (sx.x + sx.y);
+  float wy = sy.x / (sy.x + sy.y);
+  return mix(mix(s11, s01, wx), mix(s10, s00, wx), wy);
+}
+`;
+}
 var MEDIUM_COMPOSITE_SHADER = `
 uniform shader u_vapor;
 uniform shader u_condensate;
@@ -683,17 +816,71 @@ 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}
+${VG_CUBIC_WEIGHTS}
+${vgBicubicSampler("vgBicubicVapor", "u_vapor")}
+${vgBicubicSampler("vgBicubicCondensate", "u_condensate")}
 
 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 the calibrated look lives here. Bicubic (see the file header) on vapor and
+  // condensate; track stays a plain bilinear read.
+  half4 vapor = vgBicubicVapor(baseSrc);
+  half4 condensate = vgBicubicCondensate(baseSrc);
+  half4 track = u_track.eval(baseSrc);
+
+  // Far plane \u2014 the identical field, scaled and offset (see the file header). An 8-tap ring, not
+  // the near plane's \xB1x/\xB1y box: axis-aligned taps read the SAME column/row on both sides of any
+  // residual axis-aligned structure (a seam, a resize artifact), which is exactly how a straight
+  // line gets doubled into four parallel copies instead of softened away \u2014 measured directly via
+  // check-medium.mjs's isotropy gate (see its report). The ring is rotated a half-step (22.5\xB0) off
+  // the axes so no tap direction ever coincides with a grid row or column. Radius stays in the same
+  // far-plane texture-space unit as before (u_farBlurRadius, grid-px) \u2014 only the tap PATTERN
+  // changed, not what it measures in.
+  float2 farSrc = baseSrc * u_farScale + u_farOffset;
+  float2 ring0 = float2( 0.9238795,  0.3826834) * u_farBlurRadius;
+  float2 ring1 = float2( 0.3826834,  0.9238795) * u_farBlurRadius;
+  float2 ring2 = float2(-0.3826834,  0.9238795) * u_farBlurRadius;
+  float2 ring3 = float2(-0.9238795,  0.3826834) * u_farBlurRadius;
+  float2 ring4 = float2(-0.9238795, -0.3826834) * u_farBlurRadius;
+  float2 ring5 = float2(-0.3826834, -0.9238795) * u_farBlurRadius;
+  float2 ring6 = float2( 0.3826834, -0.9238795) * u_farBlurRadius;
+  float2 ring7 = float2( 0.9238795, -0.3826834) * u_farBlurRadius;
+  half4 vaporFar = (u_vapor.eval(farSrc + ring0) + u_vapor.eval(farSrc + ring1) +
+                     u_vapor.eval(farSrc + ring2) + u_vapor.eval(farSrc + ring3) +
+                     u_vapor.eval(farSrc + ring4) + u_vapor.eval(farSrc + ring5) +
+                     u_vapor.eval(farSrc + ring6) + u_vapor.eval(farSrc + ring7)) * half4(0.125);
+  half4 condensateFar = (u_condensate.eval(farSrc + ring0) + u_condensate.eval(farSrc + ring1) +
+                          u_condensate.eval(farSrc + ring2) + u_condensate.eval(farSrc + ring3) +
+                          u_condensate.eval(farSrc + ring4) + u_condensate.eval(farSrc + ring5) +
+                          u_condensate.eval(farSrc + ring6) + u_condensate.eval(farSrc + ring7)) * half4(0.125);
+
+  // 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 +888,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 +949,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 +1049,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 +1060,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 +1078,6 @@ exports.speciesFamily = speciesFamily;
 exports.srgbToOklab = srgbToOklab;
 exports.stepGrowth = stepGrowth;
 exports.stepSpring = stepSpring;
+exports.wrappedDistanceFromZero = wrappedDistanceFromZero;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map