vireuikit 0.3.0 → 0.5.0

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

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