fancy-ui-react 0.2.0

package/dist/components/fireworks-hdr/fireworks-shared.d.ts

@@ -0,0 +1,444 @@
+/** Floats per particle in the interleaved pool. */
+export declare const STRIDE = 17;
+/** Field offsets inside one particle's STRIDE-float slot. */
+export declare const F: {
+    readonly posX: 0;
+    readonly posY: 1;
+    readonly velX: 2;
+    readonly velY: 3;
+    readonly age: 4;
+    readonly ttl: 5;
+    readonly size: 6;
+    readonly r: 7;
+    readonly g: 8;
+    readonly b: 9;
+    readonly brightness: 10;
+    readonly type: 11;
+    readonly seed: 12;
+    readonly targetX: 13;
+    readonly targetY: 14;
+    readonly dragScale: 15;
+    /**
+     * Per-particle depth dim in (0,1] — the launch's `depth` folded into a
+     * single multiplier applied to the resolved brightness every frame (§3.6).
+     * Defaults to 1 for every spawn (see `appendParticle`), so only depth-aware
+     * spawns need to write it.
+     */
+    readonly depthDim: 16;
+};
+export declare const TYPE: {
+    readonly ROCKET: 0;
+    readonly SPARK: 1;
+    readonly EMBER: 2;
+    readonly SMOKE: 3;
+    readonly FLASH: 4;
+    readonly SEEKER: 5;
+};
+export type ParticleType = (typeof TYPE)[keyof typeof TYPE];
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+/** Linear RGB; channels may exceed 1.0 (HDR headroom). */
+export interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+export type ShellKind = "peony" | "willow" | "ring" | "glyph" | "heart" | "star" | "shape";
+export type Intensity = "intro" | "ambient";
+export type QualityTier = "high" | "mid" | "low";
+export interface LaunchOptions {
+    apex: Vec2;
+    from?: Vec2;
+    /** @default 'peony' */
+    shell?: ShellKind;
+    /** Single hue or an adjacent duo; omitted → palette ping-pong sweep. */
+    color?: Rgb | Rgb[];
+    /** REQUIRED when `shell === 'glyph'`: normalized target points. */
+    glyphPoints?: Vec2[];
+    /**
+     * REQUIRED when `shell === 'shape'`: the closed figure the burst is cut
+     * from, as y-UP points around the origin. Scale is free — the outline is
+     * normalized to the unit circle, then drawn at the shell's radius. Points are
+     * walked in order and the figure is closed automatically, so a hand-written
+     * polygon works as well as a sampled curve.
+     */
+    shapePoints?: Vec2[];
+    scale?: number;
+    flightMs?: number;
+    /** @default 'ambient' */
+    intensity?: Intensity;
+    /** [0,1] — far shells render dimmer, smaller, less saturated. */
+    depth?: number;
+    seed?: number;
+    /** Glyph only: sim self-triggers seeker release at this time (ms after launch). */
+    releaseAtMs?: number;
+}
+export interface LaunchResult {
+    flightMs: number;
+    /** flightMs + fuse-hang; when the shell detonates. */
+    breakMs: number;
+}
+/**
+ * How the fireworks are actually being rendered (sampled once at handle
+ * creation; does not follow the window to another display):
+ * - "webgpu-hdr": WebGPU with extended tone mapping active AND a display
+ *   reporting `(dynamic-range: high)` — true brighter-than-white output.
+ * - "webgpu-sdr": WebGPU float16 + P3, but the browser clamped tone mapping or
+ *   the display is SDR.
+ * - "webgl-p3":  WebGL2 fallback with a display-p3 drawing buffer.
+ * - "webgl-sdr": WebGL2 fallback, plain sRGB.
+ * - "none":      no GPU rendering available; the component never fires onReady.
+ */
+export type FireworksRenderLevel = "webgpu-hdr" | "webgpu-sdr" | "webgl-p3" | "webgl-sdr" | "none";
+/**
+ * Imperative control surface handed to `FireworksHdr`'s `onReady` callback
+ * (§1). Coordinates are normalized [0,1], top-left origin.
+ */
+export interface FireworksHandle {
+    /** Fire a shell; returns the resolved flight/break timing. */
+    launch(opts: LaunchOptions): LaunchResult;
+    /** Toggle the ambient auto-scheduler; optionally set its intensity [0,1]. */
+    setAmbient(on: boolean, intensity?: number): void;
+    /** Set (or clear) the keep-clear rect ambient apexes must avoid. */
+    setKeepClear(rect: Rect | null): void;
+    /** Set the display exposure multiplier (clamped [1,4] by the renderer). */
+    setExposure(v: number): void;
+    readonly renderLevel: FireworksRenderLevel;
+    /** Stop the loop, remove listeners, and release GPU resources. */
+    cleanup(): void;
+}
+export interface Zone {
+    rect: Rect;
+    weight: number;
+}
+export interface Rect {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+export interface TierSpec {
+    maxParticles: number;
+    trailRate: number;
+}
+export interface ShellRecipe {
+    counts: Record<QualityTier, number>;
+    emberFrac: number;
+    smoke: number;
+    radius: [number, number];
+    builder: BurstBuilderKind;
+    /**
+     * Pattern shells only: the unit outline the burst is cut from, sampled at
+     * `t ∈ [0,1)`. Points are y-UP and bounded by the unit circle; the burst
+     * converts to the sim's y-down convention.
+     */
+    outline?: Outline;
+    /**
+     * Pattern shells hold a readable figure, so they suppress the break
+     * asymmetry, the stragglers and most of the embers that would smear it.
+     */
+    crisp?: boolean;
+}
+type BurstBuilderKind = "sphere" | "willow" | "ring" | "glyph" | "outline";
+/** A closed unit figure: `t ∈ [0,1)` → point, y-up, `|p| ≤ 1`. */
+export type Outline = (t: number) => Vec2;
+export interface Sim {
+    launch(opts: LaunchOptions): LaunchResult;
+    spawnFlash(pos: Vec2, brightness: number, sizeNorm: number, hue: Rgb): void;
+    /** Advances the simulation; `dt` is clamped to DT_MAX internally. */
+    step(dtSeconds: number, wind?: Vec2): void;
+    /** Writes 8-float instances into `out`; returns the live instance count. */
+    writeInstances(out: Float32Array): number;
+    setAspect(aspect: number): void;
+    /**
+     * Set (or clear) the keep-clear rect. Detonation apexes are the scheduler's
+     * job to steer away; here it only soft-dims stray particles (§4.5) that drift
+     * inside so the area behind the card stays calm.
+     */
+    setKeepClear(rect: Rect | null): void;
+    /**
+     * Scale new burst particle counts (spawn density) in [0,1]. The adaptive
+     * downgrade uses this as its pop-free CPU lever; glyph seekers are driven by
+     * explicit points and are never scaled. Default 1 (no change).
+     */
+    setSpawnScale(scale: number): void;
+    reset(): void;
+    readonly count: number;
+    readonly capacity: number;
+    readonly droppedSpawns: number;
+    /** Interleaved pool, read-only view (first `count · STRIDE` floats live). */
+    readonly data: Float32Array;
+}
+export interface SimOptions {
+    quality: QualityTier;
+    aspect: number;
+    hdr: boolean;
+    /** Injectable spawn/schedule randomness; defaults to Math.random. */
+    rng?: () => number;
+    wind?: Vec2;
+    /** Linear-RGB palette (ping-pong order); defaults to PALETTE. */
+    palette?: Rgb[];
+}
+export declare const G = 3.6;
+export declare const DT_MAX = 0.033;
+export declare const LAUNCH_Y: [number, number];
+export declare const LAUNCH_X: [number, number];
+export declare const EXPOSURE_AMBIENT = 2.2;
+export declare const EXPOSURE_INTRO = 2.6;
+export declare const SDR_KNEE_START = 0.8;
+export declare const SDR_CORE_SCALE = 1.4;
+export declare const SDR_SAT_BOOST = 0.12;
+export declare const STRETCH = 0.01;
+export declare const B_FLASH_INTRO = 3.4;
+export declare const B_FLASH_AMBIENT = 2.1;
+export declare const B_SPARK_FRESH = 2.2;
+export declare const B_SPARK_STEADY = 0.9;
+export declare const B_SPARK_TERMINAL = 0.15;
+export declare const B_ASCENT_HEAD = 2.8;
+export declare const B_ASCENT_TAIL = 0.45;
+export declare const B_BURST_STREAK = 0.5;
+export declare const B_EMBER_MEAN = 0.35;
+export declare const B_SMOKE_MIN = 0.05;
+export declare const B_SMOKE_MAX = 0.12;
+export declare const B_GLYPH_HOLD = 1.3;
+export declare const B_GLYPH_RELEASE = 2.6;
+export declare const B_HAZE_CEIL = 0.18;
+export declare const CRACKLE_HZ = 24;
+export declare const PALETTE_HEX: readonly ["#42cfff", "#3d5bff", "#a142ff", "#ff2fd6"];
+export declare const COOL_END_HEX = "#ffcf9c";
+export declare const MAGNESIUM_HEX = "#f4f8ff";
+export declare const COMET_HEAD_HEX = "#fff2e0";
+export declare const SMOKE_HEX = "#0a0b10";
+export declare const SHELL_JITTER_DEG = 7;
+export declare const SPARK_JITTER_DEG = 3;
+export declare const ROCKET_WOBBLE_AMP = 0.045;
+export declare const ROCKET_WOBBLE_HZ = 11;
+export declare const HUE_ARRIVES_AT = 0.34;
+export declare const COOL_START = 0.72;
+export declare const CRACKLE_FRAC = 0.06;
+export declare const DEPTH_DIM = 0.45;
+export declare const DEPTH_SIZE = 0.5;
+export declare const DEPTH_CHROMA = 0.35;
+export declare const DEPTH_RADIUS = 0.25;
+export declare const QUALITY: Record<QualityTier, TierSpec>;
+export declare const SHELL: Record<ShellKind, ShellRecipe>;
+export declare const AMBIENT_RADIUS_MAX = 0.2;
+export declare const AMBIENT_ZONES: Zone[];
+export declare const KEEP_CLEAR_DESKTOP: Rect;
+export declare const KEEP_CLEAR_MOBILE: Rect;
+export declare const KEEP_CLEAR_DIM = 0.35;
+/** hash11(x) = fract(sin(x·127.1)·43758.5453) — deterministic scalar hash. */
+export declare function hash11(x: number): number;
+/**
+ * 1-D value noise in [0,1). Smooth-interpolated hash lattice sampled at
+ * `age·freq`, offset by `seed`. Deterministic per (seed, age, freq).
+ */
+export declare function flickerNoise(seed: number, ageSec: number, freqHz: number): number;
+/** smoothstep with edge0 possibly > edge1 (used by the death gate). */
+export declare function smoothstep(edge0: number, edge1: number, x: number): number;
+/**
+ * Last-10%-of-life brightness gate (§2.1 / §3.6). Equals 1 up to lifeT 0.9,
+ * eases to 0 at lifeT 1.0 — so a particle's brightness reaches 0 exactly when
+ * it is removed, honoring "nothing removed at nonzero brightness".
+ */
+export declare function deathGate(lifeT: number): number;
+/** Parse `#rrggbb` to linear RGB. Falls back to white on malformed input. */
+export declare function hexToLinearRgb(hex: string): Rgb;
+interface Oklab {
+    L: number;
+    a: number;
+    b: number;
+}
+/** Linear RGB → oklab. */
+export declare function linearToOklab(c: Rgb): Oklab;
+/** oklab → linear RGB (may return negative channels for out-of-gamut hues). */
+export declare function oklabToLinear(o: Oklab): Rgb;
+/** Rotate a linear-RGB color's oklab hue by `deg` degrees (chroma preserved). */
+export declare function hueRotate(c: Rgb, deg: number): Rgb;
+/** Perceptual mix of two linear-RGB colors in oklab. */
+export declare function mixOklab(a: Rgb, b: Rgb, t: number): Rgb;
+export declare const PALETTE: Rgb[];
+export declare const COMET_TRAIL_MIX = 0.25;
+/**
+ * The medium a solved launch actually flies through. Omit it (or pass zeroed
+ * fields) for the textbook undamped, square-canvas trajectory; pass the sim's
+ * own numbers and the solve inverts the SAME model `integrate` applies, so the
+ * shell really peaks at `apex` instead of undershooting by the drag it was
+ * never told about.
+ */
+export interface LaunchMedium {
+    /** Linear drag on the rocket (1/s) — `DRAG[TYPE.ROCKET]`. 0 → ballistic. */
+    drag?: number;
+    /** Canvas aspect W/H; x integrates as `pos.x += (vel.x / A) · dt`. */
+    aspect?: number;
+    /** Horizontal wind accel, already scaled by the rocket's windScale. */
+    windX?: number;
+    /** Vertical wind accel (+y down), already scaled by the rocket's windScale. */
+    windY?: number;
+}
+/**
+ * Solve a rocket's launch velocity (§4). With `flightMs` the timing wins
+ * (vy = 0 exactly at flight, apex.y only targets x); without it the flight is
+ * derived so the trajectory peaks at apex.y.
+ *
+ * `medium` makes the solve match the integrator: with drag `k` the vertical
+ * motion is `vu(t) = (vu0 + g/k)·e^(−kt) − g/k` (apex where that hits 0) and
+ * the horizontal one integrates to `(vx0 − ax/k)(1 − e^(−kt))/k + (ax/k)·t`,
+ * divided by the aspect. Without it both collapse to the undamped forms.
+ */
+export declare function solveLaunch(from: Vec2, apex: Vec2, g: number, flightMs?: number, medium?: LaunchMedium): {
+    v0: Vec2;
+    flightMs: number;
+};
+/** Gravity that makes a launch from `from` peak at `apex.y` in `flightSec`. */
+export declare function solveGravity(from: Vec2, apex: Vec2, flightSec: number): number;
+export interface BurstDir {
+    dir: Vec2;
+    z: number;
+}
+/** Fibonacci-sphere burst (peony). `dir` is the in-plane projection, `z` depth. */
+export declare function sphereBurst(n: number, seed: number): BurstDir[];
+/** Even ring of unit in-plane directions with a slight per-seed tilt (ring shell). */
+export declare function ringBurst(n: number, seed: number): BurstDir[];
+/**
+ * Classic heart curve, normalized into the unit circle and y-up.
+ * `x = 16sin³t`, `y = 13cos t − 5cos 2t − 2cos 3t − cos 4t` — the 17 divisor is
+ * the curve's own extent, so the figure fills the shell radius without clipping.
+ */
+export declare function heartOutline(t: number): Vec2;
+/**
+ * A `points`-pointed star walked along its edges (not just its vertices), so a
+ * sparse particle count still draws the figure rather than a scatter of tips.
+ * `inner` is the valley radius as a fraction of the tip radius.
+ */
+export declare function starOutline(points?: number, inner?: number): Outline;
+/**
+ * Cut a burst from a closed unit figure (§3.7). Each direction keeps the
+ * outline point's own magnitude, so the spawn speed is proportional to its
+ * distance from the centre — under linear drag every spark coasts `v0/drag`,
+ * which is what redraws the figure in the sky at `radius` scale.
+ *
+ * Points are y-up going in and y-down coming out, matching the sim.
+ */
+export declare function outlineBurst(n: number, seed: number, outline: Outline, jitter?: number): BurstDir[];
+/**
+ * Turn caller points into an {@link Outline}: normalized to the unit circle
+ * about their own centroid and walked as a closed polygon, so both a sampled
+ * curve and a hand-written polygon draw correctly.
+ */
+export declare function polygonOutline(points: Vec2[]): Outline;
+/** Upward-biased, vertically compressed sphere (willow droop before gravity). */
+export declare function willowBurst(n: number, seed: number): BurstDir[];
+/**
+ * One semi-implicit Euler step of a damped spring toward `target`.
+ * a = −ω²(p−target) − 2ζω·v (§5.2). Stable for the seeker's ω=6, ζ=0.9 at
+ * dt up to 33 ms.
+ */
+export declare function springStep(pos: number, vel: number, target: number, dt: number, omega: number, zeta: number): {
+    pos: number;
+    vel: number;
+};
+/**
+ * Ping-pong index over 0..3 (§1). Returns the current index, then advances,
+ * reflecting at the ends: 0,1,2,3,2,1,0,1,…
+ */
+export declare function nextShellHue(state: {
+    i: number;
+    dir: 1 | -1;
+}): number;
+/** Palette color at a ping-pong index, jittered ±`jitterDeg` in oklab hue. */
+export declare function shellHueColor(hueIndex: number, palette: Rgb[], jitterDeg: number, rng: () => number): Rgb;
+/**
+ * Spark color at life fraction (§1.3 / §3.1): pure white → hue crossfade →
+ * full hue → cool warm-white. `whiteHold` is the life fraction the white core
+ * holds before crossfading; `seed` adds a small deterministic hue jitter.
+ */
+export declare function sparkColorAtLife(shellHue: Rgb, lifeT: number, whiteHold: number, seed: number): Rgb;
+/**
+ * Poisson (exponential) inter-arrival time in ms, clamped to [min,max]. The
+ * clamp (rather than truncation) keeps the sampled mean near `meanMs`.
+ */
+export declare function poissonIntervalMs(meanMs: number, rng: () => number, clampMin: number, clampMax: number): number;
+/** Margin the keep-clear rect is grown by before rejecting an apex (§6). */
+export declare const KEEP_CLEAR_MARGIN = 0.02;
+/**
+ * Whether `(x, y)` falls inside `rect` grown by `margin`. Exported so callers
+ * that derive an apex from a sampled one (e.g. a mirrored double) can re-run
+ * the same rejection test rather than assume the transform preserved it.
+ */
+export declare function rectExpandedContains(rect: Rect, x: number, y: number, margin?: number): boolean;
+/**
+ * Sample an apex from weighted zones (§6). Rejects points inside the expanded
+ * keep-clear rect (resampling up to `maxTries`), edge-biases x by depth, and
+ * falls back to the zone farthest from the keep-clear center.
+ */
+export declare function sampleZone(zones: Zone[], rng: () => number, keepClear: Rect | null, maxTries?: number): {
+    apex: Vec2;
+    depth: number;
+};
+/**
+ * SDR soft-knee tone map (§7.2): identity below `knee`, then an asymptotic
+ * approach to 1.0 so over-white energy compresses instead of hard-clipping.
+ * Shared by the renderers (WGSL / GLSL inline the same formula) and unit-tested
+ * here so the ladder has one canonical definition.
+ */
+export declare function softKnee(x: number, knee: number): number;
+/**
+ * Resolve the effective quality tier for `quality="auto"` (or pass a fixed tier
+ * through unchanged). Extracted from the component so the ladder is testable:
+ *
+ * - an explicit tier ("high"/"mid"/"low") always wins;
+ * - a small viewport (min-dim < 480 px) → "low" (covers phones);
+ * - a low-power device on the WebGL2 fallback → "low" (weak GPU + modest
+ *   CPU/RAM; only ever downgrades the fallback path, never WebGPU);
+ * - "webgpu-hdr" → "high"; "webgpu-sdr" → "high" on a retina DPR, else "mid";
+ * - the WebGL2 levels ("webgl-p3"/"webgl-sdr") → "mid" (the fallback renderer is
+ *   fill-rate bound; "none" is unreachable here — no sim is built without an
+ *   engine — but maps to "mid" for completeness).
+ */
+export declare function resolveQualityTier(requested: "auto" | QualityTier, level: FireworksRenderLevel, dpr: number, minDim: number, lowPower?: boolean): QualityTier;
+/** One rung of the adaptive quality ladder. */
+export interface AdaptiveLevel {
+    /** Accumulation-buffer resolution scale relative to the canvas. */
+    renderScale: number;
+    /** Multiplier on new burst particle counts (spawn density). */
+    spawnScale: number;
+}
+/** The fixed ladder. Index 0 is full quality; each step sheds more. */
+export declare const ADAPTIVE_LADDER: AdaptiveLevel[];
+export interface AdaptiveTuning {
+    /** EMA smoothing factor (higher = more reactive). */
+    alpha: number;
+    /** Frame-time (ms) above which frames count toward a downgrade. */
+    thresholdMs: number;
+    /** Consecutive over-threshold frames required to drop a notch. */
+    sustainFrames: number;
+}
+/** Defaults: EMA α=0.1, downgrade when the average frame holds > 24 ms (~<42 fps) for ~60 frames (~1 s). */
+export declare const ADAPTIVE_DEFAULTS: AdaptiveTuning;
+export interface AdaptiveState {
+    /** EMA of frame time (ms). */
+    emaMs: number;
+    /** Consecutive frames the EMA has been over threshold. */
+    overCount: number;
+    /** Current ladder index (only ever increases). */
+    step: number;
+    /** Whether the EMA has been seeded (avoids a ramp-up from 0). */
+    started: boolean;
+}
+export declare function createAdaptiveState(): AdaptiveState;
+/**
+ * Fold one ACTIVE frame's wall time into the adaptive controller. The caller
+ * must invoke this only for frames that actually did work (particles present,
+ * not reduced-motion-idle, not `document.hidden`) so paused/quiet frames don't
+ * skew the average. Mutates `state` (EMA, counter, step) and returns `true` on
+ * the frame a downgrade fires — the caller then applies `adaptiveLevel(state)`.
+ * Session-sticky: never upgrades; a no-op once at the ladder floor.
+ */
+export declare function adaptiveDowngradeStep(state: AdaptiveState, frameMs: number, tuning?: AdaptiveTuning): boolean;
+/** The current ladder rung for `state.step`. */
+export declare function adaptiveLevel(state: AdaptiveState): AdaptiveLevel;
+export declare function createSim(opts: SimOptions): Sim;
+export {};