fancy-ui-react 0.2.0

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

@@ -0,0 +1,4 @@
+export { FireworksHdr } from "./FireworksHdr.js";
+export type { FireworksHdrProps } from "./FireworksHdr.js";
+export { heartOutline, starOutline, polygonOutline, outlineBurst } from "./fireworks-shared.js";
+export type { FireworksHandle, LaunchOptions, LaunchResult, FireworksRenderLevel, ShellKind, QualityTier, Outline, BurstDir, Vec2, } from "./fireworks-shared.js";

package/dist/components/fireworks-hdr/webgl2-renderer.d.ts

@@ -0,0 +1,20 @@
+import { STRETCH } from "./fireworks-shared.js";
+import { type FireworksEngineHandle } from "./webgpu-renderer.js";
+export interface WebGl2FireworksOptions {
+    /** Max instances the buffer must hold (the resolved tier's capacity). */
+    maxInstances: number;
+    /** Accumulation resolution scale relative to the canvas (default 1). */
+    renderScale?: number;
+    /** Initial display exposure — accepted for parity; SDR pins it to 1.0. */
+    exposure?: number;
+    /** Attempt a `display-p3` drawing buffer (wide-gamut fallback). Default true. */
+    hdr?: boolean;
+}
+/**
+ * Build the WebGL2 fallback renderer, or `null` when WebGL2 is unavailable (no
+ * context, missing programs) — the caller then gives up silently (no onReady).
+ * Synchronous: WebGL has no async init, but the shape matches the WebGPU seam so
+ * the component treats `await startWebGpu…` and `startWebGl2…` uniformly.
+ */
+export declare function startWebGl2Fireworks(canvas: HTMLCanvasElement, opts: WebGl2FireworksOptions): FireworksEngineHandle | null;
+export { STRETCH };

package/dist/components/fireworks-hdr/webgl2-renderer.js

@@ -0,0 +1,517 @@
+"use client";
+import { SDR_CORE_SCALE, SDR_KNEE_START, SDR_SAT_BOOST } from "./fireworks-shared.js";
+import { STRETCH } from "./fireworks-shared.js";
+import { TRAIL_FADE_RATE } from "./webgpu-renderer.js";
+import { isDev } from "./dev.js";
+const MAX_DPR = 2;
+const INSTANCE_FLOATS = 8;
+const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
+function scaleByPixelRatio(input) {
+  const dpr = Math.min(typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1, MAX_DPR);
+  return Math.floor(input * dpr);
+}
+function probeFloatAccum() {
+  if (typeof document === "undefined") return false;
+  try {
+    const probe = document.createElement("canvas").getContext("webgl2");
+    if (!probe) return false;
+    const has = !!probe.getExtension("EXT_color_buffer_float");
+    probe.getExtension("WEBGL_lose_context")?.loseContext();
+    return has;
+  } catch {
+    return false;
+  }
+}
+const FULLSCREEN_VS = (
+  /* glsl */
+  `#version 300 es
+// Fullscreen triangle from gl_VertexID; uv round-trips y consistently with the
+// particle pass (clip.y = 1 - 2·posY there, uv = clip·0.5+0.5 here), so nothing
+// is flipped and rockets rise upward.
+const vec2 P[3] = vec2[3](vec2(-1.0, -3.0), vec2(-1.0, 1.0), vec2(3.0, 1.0));
+out vec2 vUv;
+void main() {
+	vec2 p = P[gl_VertexID];
+	gl_Position = vec4(p, 0.0, 1.0);
+	vUv = p * 0.5 + 0.5;
+}`
+);
+const DECAY_FS = (
+  /* glsl */
+  `#version 300 es
+precision highp float;
+in vec2 vUv;
+uniform sampler2D uAccum;
+uniform float uFade;
+out vec4 frag;
+void main() {
+	frag = texture(uAccum, vUv) * uFade;
+}`
+);
+const SOFT_KNEE_GLSL = (
+  /* glsl */
+  `
+float softKnee(float x, float knee) {
+	if (x <= knee) return x;
+	float over = x - knee;
+	float span = max(1.0 - knee, 1e-3);
+	return knee + span * (1.0 - exp(-over / span));
+}
+vec3 sdrLadder(vec3 c, float knee, float sat) {
+	vec3 k = vec3(softKnee(c.r, knee), softKnee(c.g, knee), softKnee(c.b, knee));
+	float luma = dot(k, vec3(0.2126, 0.7152, 0.0722));
+	return mix(vec3(luma), k, 1.0 + sat);
+}`
+);
+const DISPLAY_FS = (
+  /* glsl */
+  `#version 300 es
+precision highp float;
+in vec2 vUv;
+uniform sampler2D uAccum;
+uniform float uKnee;
+uniform float uSat;
+out vec4 frag;
+${SOFT_KNEE_GLSL}
+void main() {
+	// SDR always: exposure pinned to 1.0, soft-knee on the accumulated sum,
+	// saturation lift, alpha clamped for premultiplied compositing.
+	vec3 c = max(texture(uAccum, vUv).rgb, vec3(0.0));
+	vec3 k = sdrLadder(c, uKnee, uSat);
+	float a = min(max(k.r, max(k.g, k.b)), 1.0);
+	frag = vec4(clamp(k, vec3(0.0), vec3(1.0)), a);
+}`
+);
+const PARTICLE_VS = (
+  /* glsl */
+  `#version 300 es
+layout(location = 0) in vec2 iPos;    // normalized [0,1], top-left origin
+layout(location = 1) in float iSize;  // half-size in screen-heights
+layout(location = 2) in vec3 iColor;  // linear RGB · brightness
+layout(location = 3) in vec2 iVel;    // velocity · STRETCH (screen-height displacement)
+uniform float uAspect;
+uniform float uCoreScale; // SDR trades headroom for size (§7.4); always on in WebGL
+out vec2 vLocal;
+out vec3 vColor;
+const vec2 C[4] = vec2[4](vec2(-1.0, -1.0), vec2(1.0, -1.0), vec2(-1.0, 1.0), vec2(1.0, 1.0));
+// Quad oversize so the halo can fall to zero before the geometry ends.
+const float QUAD_PAD = 1.35;
+void main() {
+	vec2 c = C[gl_VertexID];
+	float size = iSize * uCoreScale;
+	float velLen = length(iVel);
+	vec2 dir = velLen > 1e-6 ? iVel / velLen : vec2(1.0, 0.0);
+	vec2 perp = vec2(-dir.y, dir.x);
+	float minorHalf = size * QUAD_PAD;
+	float majorHalf = clamp(size + velLen, size, size * 2.5) * QUAD_PAD;
+	vec2 off = dir * (majorHalf * c.x) + perp * (minorHalf * c.y);
+	vec2 p01 = iPos + vec2(off.x / uAspect, off.y);
+	vec2 ndc = vec2(p01.x * 2.0 - 1.0, 1.0 - p01.y * 2.0);
+	gl_Position = vec4(ndc, 0.0, 1.0);
+	vLocal = c * QUAD_PAD;
+	vColor = iColor;
+}`
+);
+const PARTICLE_LOBE_GLSL = (
+  /* glsl */
+  `
+	const float QUAD_PAD = 1.35;
+	float r2 = dot(vLocal, vLocal);
+	float core = exp(-r2 * 6.0);
+	float halo = exp(-r2 * 1.6) * 0.35;
+	float win = smoothstep(QUAD_PAD, QUAD_PAD * 0.6, sqrt(r2));
+	float intensity = (core + halo) * win;`
+);
+const PARTICLE_FS_ACCUM = (
+  /* glsl */
+  `#version 300 es
+precision highp float;
+in vec2 vLocal;
+in vec3 vColor;
+out vec4 frag;
+void main() {
+${PARTICLE_LOBE_GLSL}
+	frag = vec4(vColor * intensity, intensity);
+}`
+);
+const PARTICLE_FS_DIRECT = (
+  /* glsl */
+  `#version 300 es
+precision highp float;
+in vec2 vLocal;
+in vec3 vColor;
+uniform float uKnee;
+uniform float uSat;
+out vec4 frag;
+${SOFT_KNEE_GLSL}
+void main() {
+${PARTICLE_LOBE_GLSL}
+	vec3 c = sdrLadder(vColor * intensity, uKnee, uSat);
+	float a = min(max(c.r, max(c.g, c.b)), 1.0);
+	frag = vec4(clamp(c, vec3(0.0), vec3(1.0)), a);
+}`
+);
+const FADE_FS = (
+  /* glsl */
+  `#version 300 es
+precision highp float;
+uniform float uAlpha;
+out vec4 frag;
+void main() {
+	frag = vec4(0.0, 0.0, 0.0, uAlpha);
+}`
+);
+function compileShader(gl, type, source) {
+  const shader = gl.createShader(type);
+  if (!shader) return null;
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    if (isDev()) {
+      console.warn("[FireworksHdr] WebGL2 shader compile failed:", gl.getShaderInfoLog(shader));
+    }
+    gl.deleteShader(shader);
+    return null;
+  }
+  return shader;
+}
+function linkProgram(gl, vsSrc, fsSrc) {
+  const vs = compileShader(gl, gl.VERTEX_SHADER, vsSrc);
+  const fs = compileShader(gl, gl.FRAGMENT_SHADER, fsSrc);
+  if (!vs || !fs) {
+    if (vs) gl.deleteShader(vs);
+    if (fs) gl.deleteShader(fs);
+    return null;
+  }
+  const program = gl.createProgram();
+  if (!program) {
+    gl.deleteShader(vs);
+    gl.deleteShader(fs);
+    return null;
+  }
+  gl.attachShader(program, vs);
+  gl.attachShader(program, fs);
+  gl.linkProgram(program);
+  gl.deleteShader(vs);
+  gl.deleteShader(fs);
+  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+    if (isDev()) {
+      console.warn("[FireworksHdr] WebGL2 program link failed:", gl.getProgramInfoLog(program));
+    }
+    gl.deleteProgram(program);
+    return null;
+  }
+  return program;
+}
+function startWebGl2Fireworks(canvas, opts) {
+  const wantFloatAccum = probeFloatAccum();
+  let gl;
+  try {
+    gl = canvas.getContext("webgl2", {
+      alpha: true,
+      antialias: false,
+      depth: false,
+      stencil: false,
+      premultipliedAlpha: true,
+      // False on Path A (the common HDR-float fallback) — a real fill-rate/
+      // memory saving; true only where Path B's frame-to-frame readback needs it.
+      preserveDrawingBuffer: !wantFloatAccum
+    });
+  } catch {
+    gl = null;
+  }
+  if (!gl) return null;
+  const glc = gl;
+  let renderLevel = "webgl-sdr";
+  if ("drawingBufferColorSpace" in glc) {
+    try {
+      glc.drawingBufferColorSpace = "display-p3";
+      if (glc.drawingBufferColorSpace === "display-p3") {
+        renderLevel = "webgl-p3";
+      }
+    } catch {
+    }
+  }
+  if (isDev()) {
+    console.info(
+      renderLevel === "webgl-p3" ? "[FireworksHdr] WebGL2 fallback: webgl-p3 (wide-gamut drawing buffer)" : "[FireworksHdr] WebGL2 fallback: webgl-sdr"
+    );
+  }
+  const floatAccum = !!glc.getExtension("EXT_color_buffer_float");
+  if (wantFloatAccum && !floatAccum) {
+    if (isDev()) {
+      console.warn(
+        "[FireworksHdr] WebGL2 float-accum probe/context mismatch; bailing to static fallback"
+      );
+    }
+    return null;
+  }
+  let renderScale = opts.renderScale ?? 1;
+  const instanceCapacity = Math.max(1, opts.maxInstances);
+  let destroyed = false;
+  let lost = false;
+  function onContextLost(e) {
+    e.preventDefault();
+    lost = true;
+    if (isDev()) console.warn("[FireworksHdr] WebGL2 context lost");
+  }
+  canvas.addEventListener("webglcontextlost", onContextLost, false);
+  let accum = null;
+  let particleProgram = null;
+  let decayProgram = null;
+  let displayProgram = null;
+  let fadeProgram = null;
+  let instanceBuffer = null;
+  let particleVao = null;
+  let fullscreenVao = null;
+  function cleanupPartial() {
+    canvas.removeEventListener("webglcontextlost", onContextLost, false);
+    if (particleProgram) glc.deleteProgram(particleProgram);
+    if (decayProgram) glc.deleteProgram(decayProgram);
+    if (displayProgram) glc.deleteProgram(displayProgram);
+    if (fadeProgram) glc.deleteProgram(fadeProgram);
+    if (instanceBuffer) glc.deleteBuffer(instanceBuffer);
+    if (particleVao) glc.deleteVertexArray(particleVao);
+    if (fullscreenVao) glc.deleteVertexArray(fullscreenVao);
+    destroyAccum();
+  }
+  particleProgram = linkProgram(
+    glc,
+    PARTICLE_VS,
+    floatAccum ? PARTICLE_FS_ACCUM : PARTICLE_FS_DIRECT
+  );
+  decayProgram = floatAccum ? linkProgram(glc, FULLSCREEN_VS, DECAY_FS) : null;
+  displayProgram = floatAccum ? linkProgram(glc, FULLSCREEN_VS, DISPLAY_FS) : null;
+  fadeProgram = floatAccum ? null : linkProgram(glc, FULLSCREEN_VS, FADE_FS);
+  const programsOk = floatAccum ? particleProgram && decayProgram && displayProgram : particleProgram && fadeProgram;
+  if (!programsOk) {
+    if (isDev()) console.warn("[FireworksHdr] WebGL2 program setup failed");
+    cleanupPartial();
+    return null;
+  }
+  const uAspect = glc.getUniformLocation(particleProgram, "uAspect");
+  const uCoreScale = glc.getUniformLocation(particleProgram, "uCoreScale");
+  const uPartKnee = floatAccum ? null : glc.getUniformLocation(particleProgram, "uKnee");
+  const uPartSat = floatAccum ? null : glc.getUniformLocation(particleProgram, "uSat");
+  const uDecayFade = decayProgram ? glc.getUniformLocation(decayProgram, "uFade") : null;
+  const uDecayAccum = decayProgram ? glc.getUniformLocation(decayProgram, "uAccum") : null;
+  const uDispAccum = displayProgram ? glc.getUniformLocation(displayProgram, "uAccum") : null;
+  const uDispKnee = displayProgram ? glc.getUniformLocation(displayProgram, "uKnee") : null;
+  const uDispSat = displayProgram ? glc.getUniformLocation(displayProgram, "uSat") : null;
+  const uFadeAlpha = fadeProgram ? glc.getUniformLocation(fadeProgram, "uAlpha") : null;
+  instanceBuffer = glc.createBuffer();
+  particleVao = glc.createVertexArray();
+  fullscreenVao = glc.createVertexArray();
+  if (!instanceBuffer || !particleVao || !fullscreenVao) {
+    cleanupPartial();
+    return null;
+  }
+  glc.bindVertexArray(particleVao);
+  glc.bindBuffer(glc.ARRAY_BUFFER, instanceBuffer);
+  glc.bufferData(glc.ARRAY_BUFFER, instanceCapacity * INSTANCE_STRIDE, glc.DYNAMIC_DRAW);
+  glc.enableVertexAttribArray(0);
+  glc.vertexAttribPointer(0, 2, glc.FLOAT, false, INSTANCE_STRIDE, 0);
+  glc.vertexAttribDivisor(0, 1);
+  glc.enableVertexAttribArray(1);
+  glc.vertexAttribPointer(1, 1, glc.FLOAT, false, INSTANCE_STRIDE, 8);
+  glc.vertexAttribDivisor(1, 1);
+  glc.enableVertexAttribArray(2);
+  glc.vertexAttribPointer(2, 3, glc.FLOAT, false, INSTANCE_STRIDE, 12);
+  glc.vertexAttribDivisor(2, 1);
+  glc.enableVertexAttribArray(3);
+  glc.vertexAttribPointer(3, 2, glc.FLOAT, false, INSTANCE_STRIDE, 24);
+  glc.vertexAttribDivisor(3, 1);
+  glc.bindVertexArray(null);
+  function makeAccumTex(w, h) {
+    const tex = glc.createTexture();
+    if (!tex) return null;
+    glc.bindTexture(glc.TEXTURE_2D, tex);
+    glc.texImage2D(glc.TEXTURE_2D, 0, glc.RGBA16F, w, h, 0, glc.RGBA, glc.HALF_FLOAT, null);
+    glc.texParameteri(glc.TEXTURE_2D, glc.TEXTURE_MIN_FILTER, glc.LINEAR);
+    glc.texParameteri(glc.TEXTURE_2D, glc.TEXTURE_MAG_FILTER, glc.LINEAR);
+    glc.texParameteri(glc.TEXTURE_2D, glc.TEXTURE_WRAP_S, glc.CLAMP_TO_EDGE);
+    glc.texParameteri(glc.TEXTURE_2D, glc.TEXTURE_WRAP_T, glc.CLAMP_TO_EDGE);
+    return tex;
+  }
+  function makeFbo(tex) {
+    const fbo = glc.createFramebuffer();
+    if (!fbo) return null;
+    glc.bindFramebuffer(glc.FRAMEBUFFER, fbo);
+    glc.framebufferTexture2D(glc.FRAMEBUFFER, glc.COLOR_ATTACHMENT0, glc.TEXTURE_2D, tex, 0);
+    glc.clearColor(0, 0, 0, 0);
+    glc.clear(glc.COLOR_BUFFER_BIT);
+    if (glc.checkFramebufferStatus(glc.FRAMEBUFFER) !== glc.FRAMEBUFFER_COMPLETE) {
+      glc.deleteFramebuffer(fbo);
+      return null;
+    }
+    return fbo;
+  }
+  function destroyAccum() {
+    if (!accum) return;
+    glc.deleteTexture(accum.readTex);
+    glc.deleteTexture(accum.writeTex);
+    glc.deleteFramebuffer(accum.readFbo);
+    glc.deleteFramebuffer(accum.writeFbo);
+    accum = null;
+  }
+  function initAccum(w, h) {
+    if (!floatAccum) return true;
+    const aw = Math.max(1, Math.round(w * renderScale));
+    const ah = Math.max(1, Math.round(h * renderScale));
+    if (accum && accum.width === aw && accum.height === ah) return true;
+    destroyAccum();
+    const rt = makeAccumTex(aw, ah);
+    const wt = makeAccumTex(aw, ah);
+    if (!rt || !wt) {
+      if (rt) glc.deleteTexture(rt);
+      if (wt) glc.deleteTexture(wt);
+      return false;
+    }
+    const rf = makeFbo(rt);
+    const wf = makeFbo(wt);
+    if (!rf || !wf) {
+      glc.deleteTexture(rt);
+      glc.deleteTexture(wt);
+      if (rf) glc.deleteFramebuffer(rf);
+      if (wf) glc.deleteFramebuffer(wf);
+      return false;
+    }
+    accum = {
+      readTex: rt,
+      writeTex: wt,
+      readFbo: rf,
+      writeFbo: wf,
+      width: aw,
+      height: ah,
+      swap() {
+        let t = this.readTex;
+        this.readTex = this.writeTex;
+        this.writeTex = t;
+        t = this.readFbo;
+        this.readFbo = this.writeFbo;
+        this.writeFbo = t;
+      }
+    };
+    return true;
+  }
+  function resizeIfNeeded() {
+    if (destroyed || lost) return;
+    const w = scaleByPixelRatio(canvas.clientWidth);
+    const h = scaleByPixelRatio(canvas.clientHeight);
+    if (w > 0 && h > 0 && (canvas.width !== w || canvas.height !== h)) {
+      canvas.width = w;
+      canvas.height = h;
+      initAccum(w, h);
+    }
+  }
+  function setRenderScale(scale) {
+    if (destroyed || lost) return;
+    const next = Number.isFinite(scale) ? Math.max(0.25, Math.min(1, scale)) : 1;
+    if (next === renderScale) return;
+    renderScale = next;
+    if (floatAccum && canvas.width > 0 && canvas.height > 0) initAccum(canvas.width, canvas.height);
+  }
+  function frame(dt, instanceData, liveCount, uniforms) {
+    if (destroyed || lost) return;
+    clampExposure(uniforms.exposure);
+    const count = Math.max(0, Math.min(liveCount, instanceCapacity));
+    const fade = Math.exp(-TRAIL_FADE_RATE * Math.max(0, dt));
+    const aspect = canvas.width / Math.max(1, canvas.height);
+    if (count > 0) {
+      glc.bindBuffer(glc.ARRAY_BUFFER, instanceBuffer);
+      glc.bufferData(glc.ARRAY_BUFFER, instanceCapacity * INSTANCE_STRIDE, glc.DYNAMIC_DRAW);
+      glc.bufferSubData(glc.ARRAY_BUFFER, 0, instanceData, 0, count * INSTANCE_FLOATS);
+    }
+    if (floatAccum) {
+      if (!accum) return;
+      glc.bindFramebuffer(glc.FRAMEBUFFER, accum.writeFbo);
+      glc.viewport(0, 0, accum.width, accum.height);
+      glc.disable(glc.BLEND);
+      glc.useProgram(decayProgram);
+      glc.uniform1f(uDecayFade, fade);
+      glc.activeTexture(glc.TEXTURE0);
+      glc.bindTexture(glc.TEXTURE_2D, accum.readTex);
+      glc.uniform1i(uDecayAccum, 0);
+      glc.bindVertexArray(fullscreenVao);
+      glc.drawArrays(glc.TRIANGLES, 0, 3);
+      if (count > 0) {
+        glc.useProgram(particleProgram);
+        glc.uniform1f(uAspect, aspect);
+        glc.uniform1f(uCoreScale, SDR_CORE_SCALE);
+        glc.enable(glc.BLEND);
+        glc.blendEquation(glc.FUNC_ADD);
+        glc.blendFunc(glc.ONE, glc.ONE);
+        glc.bindVertexArray(particleVao);
+        glc.drawArraysInstanced(glc.TRIANGLE_STRIP, 0, 4, count);
+      }
+      accum.swap();
+      glc.bindFramebuffer(glc.FRAMEBUFFER, null);
+      glc.viewport(0, 0, canvas.width, canvas.height);
+      glc.disable(glc.BLEND);
+      glc.useProgram(displayProgram);
+      glc.uniform1f(uDispKnee, SDR_KNEE_START);
+      glc.uniform1f(uDispSat, SDR_SAT_BOOST);
+      glc.activeTexture(glc.TEXTURE0);
+      glc.bindTexture(glc.TEXTURE_2D, accum.readTex);
+      glc.uniform1i(uDispAccum, 0);
+      glc.bindVertexArray(fullscreenVao);
+      glc.drawArrays(glc.TRIANGLES, 0, 3);
+      glc.bindVertexArray(null);
+      return;
+    }
+    glc.bindFramebuffer(glc.FRAMEBUFFER, null);
+    glc.viewport(0, 0, canvas.width, canvas.height);
+    glc.useProgram(fadeProgram);
+    glc.uniform1f(uFadeAlpha, 1 - fade);
+    glc.enable(glc.BLEND);
+    glc.blendEquation(glc.FUNC_ADD);
+    glc.blendFuncSeparate(glc.ZERO, glc.ONE_MINUS_SRC_ALPHA, glc.ZERO, glc.ONE_MINUS_SRC_ALPHA);
+    glc.bindVertexArray(fullscreenVao);
+    glc.drawArrays(glc.TRIANGLES, 0, 3);
+    if (count > 0) {
+      glc.useProgram(particleProgram);
+      glc.uniform1f(uAspect, aspect);
+      glc.uniform1f(uCoreScale, SDR_CORE_SCALE);
+      glc.uniform1f(uPartKnee, SDR_KNEE_START);
+      glc.uniform1f(uPartSat, SDR_SAT_BOOST);
+      glc.blendFunc(glc.ONE, glc.ONE);
+      glc.bindVertexArray(particleVao);
+      glc.drawArraysInstanced(glc.TRIANGLE_STRIP, 0, 4, count);
+    }
+    glc.bindVertexArray(null);
+  }
+  {
+    const w = scaleByPixelRatio(canvas.clientWidth) || 1;
+    const h = scaleByPixelRatio(canvas.clientHeight) || 1;
+    canvas.width = w;
+    canvas.height = h;
+    if (!initAccum(w, h)) {
+      cleanupPartial();
+      return null;
+    }
+  }
+  return {
+    frame,
+    resizeIfNeeded,
+    setRenderScale,
+    extendedToneMapping: false,
+    // WebGL has no extended tone mapping — always SDR
+    renderLevel,
+    get lost() {
+      return lost;
+    },
+    instanceCapacity,
+    destroy() {
+      destroyed = true;
+      cleanupPartial();
+    }
+  };
+}
+function clampExposure(v) {
+  if (!Number.isFinite(v)) return 1;
+  return Math.max(1, Math.min(4, v));
+}
+export {
+  STRETCH,
+  startWebGl2Fireworks
+};

package/dist/components/fireworks-hdr/webgpu-renderer.d.ts

@@ -0,0 +1,51 @@
+import { STRETCH, type FireworksRenderLevel } from "./fireworks-shared.js";
+/**
+ * Single global accumulation fade rate (1/s). Per-frame factor is
+ * exp(-TRAIL_FADE_RATE·dt); at 60 fps that is ≈0.889, fading a trail to 10% in
+ * ~330 ms (AD §3.3 ascent range 350–500 ms). Held deliberately short: the
+ * accumulation buffer is what smears a moving particle into a line, so a slower
+ * fade turns falling debris into long straight filaments instead of sparks.
+ */
+export declare const TRAIL_FADE_RATE = 7;
+export interface WebGpuFireworksOptions {
+    /** Max instances the buffer must hold (the Sim's capacity). */
+    maxInstances: number;
+    /** Accumulation resolution scale relative to the canvas (default 1). */
+    renderScale?: number;
+    /** Initial display exposure multiplier (clamped [1,4]). */
+    exposure?: number;
+}
+export interface FrameUniforms {
+    /** Display exposure multiplier (clamped [1,4] internally). */
+    exposure: number;
+}
+/**
+ * Renderer control surface owned by the component. The rAF loop lives in the
+ * component; it calls `frame` once per tick with the live instance data.
+ */
+export interface FireworksEngineHandle {
+    /** Render one frame: decay, additive particles, display. */
+    frame(dt: number, instanceData: Float32Array<ArrayBuffer>, liveCount: number, uniforms: FrameUniforms): void;
+    /** Reconcile the drawing buffer + accumulation textures with the CSS size. */
+    resizeIfNeeded(): void;
+    /**
+     * Set the accumulation-buffer resolution scale (relative to the canvas) and
+     * rebuild the accumulation textures at the new scale. Used by the component's
+     * adaptive downgrade to shed GPU fill-rate. No-op where there is no separate
+     * accumulation buffer (WebGL2 Path B).
+     */
+    setRenderScale(scale: number): void;
+    /** Whether the browser actually kept extended tone mapping (true HDR path). */
+    readonly extendedToneMapping: boolean;
+    /** "webgpu-hdr" or "webgpu-sdr" (never a webgl-* / none level here). */
+    readonly renderLevel: FireworksRenderLevel;
+    readonly lost: boolean;
+    readonly instanceCapacity: number;
+    destroy(): void;
+}
+/**
+ * Build the WebGPU renderer, or `null` when WebGPU is unavailable / rejected
+ * (the caller then tries the WebGL2 path, or gives up silently).
+ */
+export declare function startWebGpuFireworks(canvas: HTMLCanvasElement, opts: WebGpuFireworksOptions): Promise<FireworksEngineHandle | null>;
+export { STRETCH };