fancy-ui-react 0.2.0

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

@@ -0,0 +1,461 @@
+"use client";
+import { EXPOSURE_AMBIENT } from "./fireworks-shared.js";
+import { STRETCH } from "./fireworks-shared.js";
+import { isDev } from "./dev.js";
+const TRAIL_FADE_RATE = 7;
+const MAX_DPR = 2;
+const ACCUM_FORMAT = "rgba16float";
+const INSTANCE_FLOATS = 8;
+const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
+const WGSL = (
+  /* wgsl */
+  `
+// ---- shared fullscreen-triangle vertex ------------------------------------
+struct FSOut {
+	@builtin(position) pos: vec4f,
+	@location(0) uv: vec2f,
+}
+
+@vertex
+fn vs_fullscreen(@builtin(vertex_index) i: u32) -> FSOut {
+	var p = array<vec2f, 3>(vec2f(-1.0, -3.0), vec2f(-1.0, 1.0), vec2f(3.0, 1.0));
+	var out: FSOut;
+	out.pos = vec4f(p[i], 0.0, 1.0);
+	// v=0 is the top texel row (top-left origin, matching normalized positions).
+	out.uv = vec2f(p[i].x, -p[i].y) * 0.5 + 0.5;
+	return out;
+}
+
+// ---- (a) decay ------------------------------------------------------------
+struct DecayU { fade: f32, _pad0: f32, _pad1: f32, _pad2: f32 }
+@group(0) @binding(0) var<uniform> du: DecayU;
+@group(0) @binding(1) var accumSmp: sampler;
+@group(0) @binding(2) var accumTex: texture_2d<f32>;
+
+@fragment
+fn fs_decay(in: FSOut) -> @location(0) vec4f {
+	return textureSample(accumTex, accumSmp, in.uv) * du.fade;
+}
+
+// ---- (b) particles --------------------------------------------------------
+struct ParticleU { aspect: f32, sdr: f32, coreScale: f32, _pad: f32 }
+@group(0) @binding(0) var<uniform> pu: ParticleU;
+
+// Quad oversize so the halo can fall to zero before the geometry ends.
+const QUAD_PAD: f32 = 1.35;
+
+struct PVOut {
+	@builtin(position) pos: vec4f,
+	@location(0) local: vec2f,  // quad-local coords in [-1,1]
+	@location(1) color: vec3f,
+}
+
+@vertex
+fn vs_particle(
+	@builtin(vertex_index) vi: u32,
+	@location(0) iPos: vec2f,     // normalized [0,1], top-left origin
+	@location(1) iSize: f32,      // half-size in screen-heights
+	@location(2) iColor: vec3f,   // linear RGB · brightness
+	@location(3) iVel: vec2f,     // velocity · STRETCH (screen-height displacement)
+) -> PVOut {
+	// 4-vertex triangle strip corners.
+	var corners = array<vec2f, 4>(
+		vec2f(-1.0, -1.0), vec2f(1.0, -1.0), vec2f(-1.0, 1.0), vec2f(1.0, 1.0)
+	);
+	let c = corners[vi];
+
+	// SDR trades brightness headroom for size — bigger, not brighter (§7.4).
+	let size = iSize * select(1.0, pu.coreScale, pu.sdr > 0.5);
+
+	// Velocity-stretch: major axis along velocity, clamped 1–2.5× the minor.
+	let velLen = length(iVel);
+	var dir = vec2f(1.0, 0.0);
+	if (velLen > 1e-6) { dir = iVel / velLen; }
+	let perp = vec2f(-dir.y, dir.x);
+	// QUAD_PAD gives the halo room to reach zero INSIDE the quad; the fragment
+	// keeps the gaussian in un-padded units so the visible size is unchanged.
+	let minorHalf = size * QUAD_PAD;
+	let majorHalf = clamp(size + velLen, size, size * 2.5) * QUAD_PAD;
+
+	// Offset in isotropic screen-height units, then map to [0,1] (x compressed
+	// by aspect) and to NDC (flip y for the top-left origin).
+	let off = dir * (majorHalf * c.x) + perp * (minorHalf * c.y);
+	let p01 = iPos + vec2f(off.x / pu.aspect, off.y);
+	let ndc = vec2f(p01.x * 2.0 - 1.0, 1.0 - p01.y * 2.0);
+
+	var out: PVOut;
+	out.pos = vec4f(ndc, 0.0, 1.0);
+	out.local = c * QUAD_PAD;
+	out.color = iColor;
+	return out;
+}
+
+@fragment
+fn fs_particle(in: PVOut) -> @location(0) vec4f {
+	// Two-lobe gaussian: tight hot core + soft wide halo.
+	let r2 = dot(in.local, in.local);
+	let core = exp(-r2 * 6.0);
+	let halo = exp(-r2 * 1.6) * 0.35;
+	// Window it to exactly zero at the quad edge. The halo alone still carries
+	// ~7% of its peak there, and additive blending turns that step into a
+	// hard-edged square around anything bright (a flash reads as a lit box).
+	let win = smoothstep(QUAD_PAD, QUAD_PAD * 0.6, sqrt(r2));
+	let intensity = (core + halo) * win;
+	// Additive (one/one): premultiplied contribution.
+	return vec4f(in.color * intensity, intensity);
+}
+
+// ---- (c) display ----------------------------------------------------------
+struct DisplayU { exposure: f32, sdr: f32, knee: f32, satBoost: f32 }
+@group(0) @binding(0) var<uniform> disp: DisplayU;
+@group(0) @binding(1) var dispSmp: sampler;
+@group(0) @binding(2) var dispTex: texture_2d<f32>;
+
+fn softKnee(x: f32, knee: f32) -> f32 {
+	// Below the knee: identity. Above: asymptotic approach to 1.0 (§7.2).
+	if (x <= knee) { return x; }
+	let over = x - knee;
+	let span = max(1.0 - knee, 1e-3);
+	return knee + span * (1.0 - exp(-over / span));
+}
+
+@fragment
+fn fs_display(in: FSOut) -> @location(0) vec4f {
+	let c = max(textureSample(dispTex, dispSmp, in.uv).rgb, vec3f(0.0));
+
+	if (disp.sdr > 0.5) {
+		// SDR: exposure pinned to 1.0, soft-knee compression, saturation lift.
+		var k = vec3f(softKnee(c.r, disp.knee), softKnee(c.g, disp.knee), softKnee(c.b, disp.knee));
+		let luma = dot(k, vec3f(0.2126, 0.7152, 0.0722));
+		k = mix(vec3f(luma), k, 1.0 + disp.satBoost);
+		let a = min(max(k.r, max(k.g, k.b)), 1.0);
+		return vec4f(clamp(k, vec3f(0.0), vec3f(1.0)), a);
+	}
+
+	// HDR: encoded values above 1.0 render brighter than SDR white. Alpha stays
+	// clamped for premultiplied compositing; color intentionally exceeds it.
+	let a = min(max(c.r, max(c.g, c.b)), 1.0);
+	return vec4f(c * disp.exposure, a);
+}
+`
+);
+function scaleByPixelRatio(input) {
+  const dpr = Math.min(typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1, MAX_DPR);
+  return Math.floor(input * dpr);
+}
+async function startWebGpuFireworks(canvas, opts) {
+  try {
+    let makeTexture = function(w, h) {
+      return device.createTexture({
+        size: { width: w, height: h },
+        format: ACCUM_FORMAT,
+        usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
+      });
+    }, makeDoubleTex = function(w, h) {
+      const a = makeTexture(w, h);
+      const b = makeTexture(w, h);
+      return {
+        read: a,
+        write: b,
+        readView: a.createView(),
+        writeView: b.createView(),
+        width: w,
+        height: h,
+        swap() {
+          const t = this.read;
+          const tv = this.readView;
+          this.read = this.write;
+          this.readView = this.writeView;
+          this.write = t;
+          this.writeView = tv;
+        }
+      };
+    }, bindGroupFor = function(uniform, texView) {
+      return device.createBindGroup({
+        layout: fsLayout,
+        entries: [
+          { binding: 0, resource: { buffer: uniform } },
+          { binding: 1, resource: sampler },
+          { binding: 2, resource: texView }
+        ]
+      });
+    }, initTextures = function(w, h) {
+      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;
+      accum?.read.destroy();
+      accum?.write.destroy();
+      accum = makeDoubleTex(aw, ah);
+      accumViewA = accum.readView;
+      bgDecayA = bindGroupFor(decayU, accum.readView);
+      bgDecayB = bindGroupFor(decayU, accum.writeView);
+      bgDisplayA = bindGroupFor(displayU, accum.readView);
+      bgDisplayB = bindGroupFor(displayU, accum.writeView);
+    }, resizeIfNeeded = function() {
+      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;
+        initTextures(w, h);
+      }
+    }, setRenderScale = function(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 (canvas.width > 0 && canvas.height > 0) initTextures(canvas.width, canvas.height);
+    }, frame = function(dt, instanceData, liveCount, uniforms) {
+      if (destroyed || lost || !accum) return;
+      exposure = clampExposure(uniforms.exposure);
+      const sdr = hdrOutput ? 0 : 1;
+      const count = Math.max(0, Math.min(liveCount, instanceCapacity));
+      if (count > 0) {
+        device.queue.writeBuffer(instanceBuffer, 0, instanceData, 0, count * INSTANCE_FLOATS);
+      }
+      scratch4.fill(0);
+      scratch4[0] = Math.exp(-TRAIL_FADE_RATE * Math.max(0, dt));
+      device.queue.writeBuffer(decayU, 0, scratch4);
+      scratch4.fill(0);
+      scratch4[0] = canvas.width / Math.max(1, canvas.height);
+      scratch4[1] = sdr;
+      scratch4[2] = 1.4;
+      device.queue.writeBuffer(particleU, 0, scratch4);
+      scratch4.fill(0);
+      scratch4[0] = exposure;
+      scratch4[1] = sdr;
+      scratch4[2] = 0.8;
+      scratch4[3] = 0.12;
+      device.queue.writeBuffer(displayU, 0, scratch4);
+      const encoder = device.createCommandEncoder();
+      const readIsA = accum.readView === accumViewA;
+      const decayBindGroup = readIsA ? bgDecayA : bgDecayB;
+      runFullscreen(encoder, decayPipeline, decayBindGroup, accum.writeView, "clear");
+      if (count > 0) {
+        const pass = encoder.beginRenderPass({
+          colorAttachments: [{ view: accum.writeView, loadOp: "load", storeOp: "store" }]
+        });
+        pass.setPipeline(particlePipeline);
+        pass.setBindGroup(0, particleBindGroup);
+        pass.setVertexBuffer(0, instanceBuffer);
+        pass.draw(4, count);
+        pass.end();
+      }
+      accum.swap();
+      const displayBindGroup = readIsA ? bgDisplayB : bgDisplayA;
+      runFullscreen(
+        encoder,
+        displayPipeline,
+        displayBindGroup,
+        context.getCurrentTexture().createView(),
+        "clear"
+      );
+      device.queue.submit([encoder.finish()]);
+    }, runFullscreen = function(encoder, pipeline, bindGroup, target, loadOp) {
+      const pass = encoder.beginRenderPass({
+        colorAttachments: [
+          { view: target, loadOp, storeOp: "store", clearValue: { r: 0, g: 0, b: 0, a: 0 } }
+        ]
+      });
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, bindGroup);
+      pass.draw(3);
+      pass.end();
+    };
+    const gpu = navigator.gpu;
+    if (!gpu) return null;
+    const adapter = await gpu.requestAdapter();
+    if (!adapter) return null;
+    const device = await adapter.requestDevice();
+    const { GPUShaderStage, GPUBufferUsage, GPUTextureUsage } = globalThis;
+    const configuration = {
+      device,
+      format: ACCUM_FORMAT,
+      alphaMode: "premultiplied",
+      colorSpace: "display-p3",
+      toneMapping: { mode: "extended" }
+    };
+    try {
+      const probe = document.createElement("canvas").getContext("webgpu");
+      if (!probe) {
+        device.destroy();
+        return null;
+      }
+      probe.configure(configuration);
+      probe.unconfigure();
+    } catch (error) {
+      device.destroy();
+      if (isDev()) {
+        console.warn("[FireworksHdr] WebGPU canvas configuration rejected:", error);
+      }
+      return null;
+    }
+    const maybeContext = canvas.getContext("webgpu");
+    if (!maybeContext) {
+      device.destroy();
+      return null;
+    }
+    const context = maybeContext;
+    context.configure(configuration);
+    let extendedToneMapping = false;
+    try {
+      const applied = context.getConfiguration?.();
+      extendedToneMapping = applied?.toneMapping?.mode === "extended";
+    } catch {
+    }
+    const hdrDisplay = typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia("(dynamic-range: high)").matches : false;
+    const hdrOutput = extendedToneMapping && hdrDisplay;
+    let destroyed = false;
+    let lost = false;
+    device.lost.then((info) => {
+      lost = true;
+      if (!destroyed && isDev()) {
+        console.warn(`[FireworksHdr] WebGPU device lost (${info.reason}): ${info.message}`);
+      }
+    });
+    if (isDev()) {
+      device.addEventListener("uncapturederror", (event) => {
+        console.error(
+          "[FireworksHdr] WebGPU uncaptured error:",
+          event.error.message
+        );
+      });
+    }
+    const module = device.createShaderModule({ code: WGSL });
+    let renderScale = opts.renderScale ?? 1;
+    const instanceCapacity = Math.max(1, opts.maxInstances);
+    let exposure = clampExposure(opts.exposure ?? EXPOSURE_AMBIENT);
+    const fsLayout = device.createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+        { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+        { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } }
+      ]
+    });
+    const particleLayout = device.createBindGroupLayout({
+      entries: [{ binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } }]
+    });
+    const decayPipeline = device.createRenderPipeline({
+      layout: device.createPipelineLayout({ bindGroupLayouts: [fsLayout] }),
+      vertex: { module, entryPoint: "vs_fullscreen" },
+      fragment: { module, entryPoint: "fs_decay", targets: [{ format: ACCUM_FORMAT }] },
+      primitive: { topology: "triangle-list" }
+    });
+    const particlePipeline = device.createRenderPipeline({
+      layout: device.createPipelineLayout({ bindGroupLayouts: [particleLayout] }),
+      vertex: {
+        module,
+        entryPoint: "vs_particle",
+        buffers: [
+          {
+            arrayStride: INSTANCE_STRIDE,
+            stepMode: "instance",
+            attributes: [
+              { shaderLocation: 0, offset: 0, format: "float32x2" },
+              // pos
+              { shaderLocation: 1, offset: 8, format: "float32" },
+              // size
+              { shaderLocation: 2, offset: 12, format: "float32x3" },
+              // color
+              { shaderLocation: 3, offset: 24, format: "float32x2" }
+              // vel
+            ]
+          }
+        ]
+      },
+      fragment: {
+        module,
+        entryPoint: "fs_particle",
+        targets: [
+          {
+            format: ACCUM_FORMAT,
+            blend: {
+              color: { srcFactor: "one", dstFactor: "one", operation: "add" },
+              alpha: { srcFactor: "one", dstFactor: "one", operation: "add" }
+            }
+          }
+        ]
+      },
+      primitive: { topology: "triangle-strip" }
+    });
+    const displayPipeline = device.createRenderPipeline({
+      layout: device.createPipelineLayout({ bindGroupLayouts: [fsLayout] }),
+      vertex: { module, entryPoint: "vs_fullscreen" },
+      fragment: { module, entryPoint: "fs_display", targets: [{ format: ACCUM_FORMAT }] },
+      primitive: { topology: "triangle-list" }
+    });
+    const sampler = device.createSampler({
+      magFilter: "linear",
+      minFilter: "linear",
+      addressModeU: "clamp-to-edge",
+      addressModeV: "clamp-to-edge"
+    });
+    const decayU = device.createBuffer({
+      size: 16,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+    });
+    const particleU = device.createBuffer({
+      size: 16,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+    });
+    const displayU = device.createBuffer({
+      size: 16,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+    });
+    const instanceBuffer = device.createBuffer({
+      size: instanceCapacity * INSTANCE_STRIDE,
+      usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST
+    });
+    const particleBindGroup = device.createBindGroup({
+      layout: particleLayout,
+      entries: [{ binding: 0, resource: { buffer: particleU } }]
+    });
+    const scratch4 = new Float32Array(4);
+    let accum = null;
+    let accumViewA = null;
+    let bgDecayA = null;
+    let bgDecayB = null;
+    let bgDisplayA = null;
+    let bgDisplayB = null;
+    const renderLevel = hdrOutput ? "webgpu-hdr" : "webgpu-sdr";
+    {
+      const w = scaleByPixelRatio(canvas.clientWidth) || 1;
+      const h = scaleByPixelRatio(canvas.clientHeight) || 1;
+      canvas.width = w;
+      canvas.height = h;
+      initTextures(w, h);
+    }
+    return {
+      frame,
+      resizeIfNeeded,
+      setRenderScale,
+      extendedToneMapping,
+      renderLevel,
+      get lost() {
+        return lost;
+      },
+      instanceCapacity,
+      destroy() {
+        destroyed = true;
+        accum?.read.destroy();
+        accum?.write.destroy();
+        device.destroy();
+      }
+    };
+  } catch (error) {
+    if (isDev()) {
+      console.warn("[FireworksHdr] WebGPU init failed:", error);
+    }
+    return null;
+  }
+}
+function clampExposure(v) {
+  if (!Number.isFinite(v)) return 1;
+  return Math.max(1, Math.min(4, v));
+}
+export {
+  STRETCH,
+  TRAIL_FADE_RATE,
+  startWebGpuFireworks
+};

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

@@ -0,0 +1,159 @@
+/** Texture format string (`"rgba16float"` is the only one used here). */
+export type GPUTextureFormat = string;
+/** Render-pass load operation. */
+export type GPULoadOp = "load" | "clear";
+export interface GPUTextureView {
+    readonly __brand?: "GPUTextureView";
+}
+export interface GPUTexture {
+    createView(): GPUTextureView;
+    destroy(): void;
+}
+export interface GPUBuffer {
+    destroy?(): void;
+}
+export interface GPUSampler {
+    readonly __brand?: "GPUSampler";
+}
+export interface GPUShaderModule {
+    readonly __brand?: "GPUShaderModule";
+}
+export interface GPUBindGroup {
+    readonly __brand?: "GPUBindGroup";
+}
+export interface GPUBindGroupLayout {
+    readonly __brand?: "GPUBindGroupLayout";
+}
+export interface GPUPipelineLayout {
+    readonly __brand?: "GPUPipelineLayout";
+}
+export interface GPURenderPipeline {
+    readonly __brand?: "GPURenderPipeline";
+}
+export interface GPUCommandBuffer {
+    readonly __brand?: "GPUCommandBuffer";
+}
+export interface GPURenderPassEncoder {
+    setPipeline(pipeline: GPURenderPipeline): void;
+    setBindGroup(index: number, bindGroup: GPUBindGroup): void;
+    setVertexBuffer(slot: number, buffer: GPUBuffer): void;
+    draw(vertexCount: number, instanceCount?: number): void;
+    end(): void;
+}
+export interface GPUColorAttachment {
+    view: GPUTextureView;
+    loadOp: GPULoadOp;
+    storeOp: "store" | "discard";
+    clearValue?: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+}
+export interface GPUCommandEncoder {
+    beginRenderPass(descriptor: {
+        colorAttachments: GPUColorAttachment[];
+    }): GPURenderPassEncoder;
+    finish(): GPUCommandBuffer;
+}
+export interface GPUQueue {
+    writeBuffer(buffer: GPUBuffer, bufferOffset: number, data: ArrayBufferView | ArrayBufferLike, dataOffset?: number, size?: number): void;
+    submit(commandBuffers: GPUCommandBuffer[]): void;
+}
+export interface GPUDeviceLostInfo {
+    readonly reason: string;
+    readonly message: string;
+}
+export interface GPUUncapturedErrorEvent {
+    readonly error: {
+        readonly message: string;
+    };
+}
+/** Descriptor bags are typed loosely on purpose — they are write-only literals. */
+export interface GPUDevice {
+    readonly lost: Promise<GPUDeviceLostInfo>;
+    readonly queue: GPUQueue;
+    addEventListener(type: string, listener: (event: unknown) => void): void;
+    createShaderModule(descriptor: {
+        code: string;
+    }): GPUShaderModule;
+    createBindGroupLayout(descriptor: {
+        entries: unknown[];
+    }): GPUBindGroupLayout;
+    createPipelineLayout(descriptor: {
+        bindGroupLayouts: GPUBindGroupLayout[];
+    }): GPUPipelineLayout;
+    createRenderPipeline(descriptor: {
+        layout: GPUPipelineLayout;
+        vertex: unknown;
+        fragment: unknown;
+        primitive: unknown;
+    }): GPURenderPipeline;
+    createSampler(descriptor: {
+        magFilter?: string;
+        minFilter?: string;
+        addressModeU?: string;
+        addressModeV?: string;
+    }): GPUSampler;
+    createBuffer(descriptor: {
+        size: number;
+        usage: number;
+    }): GPUBuffer;
+    createBindGroup(descriptor: {
+        layout: GPUBindGroupLayout;
+        entries: unknown[];
+    }): GPUBindGroup;
+    createTexture(descriptor: {
+        size: {
+            width: number;
+            height: number;
+        };
+        format: GPUTextureFormat;
+        usage: number;
+    }): GPUTexture;
+    createCommandEncoder(): GPUCommandEncoder;
+    destroy(): void;
+}
+export interface GPUAdapter {
+    requestDevice(): Promise<GPUDevice>;
+}
+export interface GPU {
+    requestAdapter(): Promise<GPUAdapter | null>;
+}
+export interface GPUCanvasConfiguration {
+    device: GPUDevice;
+    format: GPUTextureFormat;
+    alphaMode?: string;
+    colorSpace?: string;
+    toneMapping?: {
+        mode?: string;
+    };
+}
+export interface GPUCanvasContext {
+    configure(configuration: GPUCanvasConfiguration): void;
+    unconfigure(): void;
+    getConfiguration?(): GPUCanvasConfiguration | null;
+    getCurrentTexture(): GPUTexture;
+}
+/**
+ * The three WebGPU flag namespaces are runtime globals rather than types. They
+ * are read off `globalThis` at the one call site that needs them, after the
+ * adapter has already been obtained — so a browser without WebGPU never touches
+ * them.
+ */
+export interface WebGpuGlobals {
+    GPUShaderStage: {
+        VERTEX: number;
+        FRAGMENT: number;
+    };
+    GPUBufferUsage: {
+        UNIFORM: number;
+        COPY_DST: number;
+        VERTEX: number;
+    };
+    GPUTextureUsage: {
+        RENDER_ATTACHMENT: number;
+        TEXTURE_BINDING: number;
+    };
+}

package/dist/components/flickering-grid/FlickeringGrid.d.ts

@@ -0,0 +1,33 @@
+/**
+ * FlickeringGrid - Canvas-based grid with flickering opacity squares
+ *
+ * Uses ResizeObserver, IntersectionObserver, and requestAnimationFrame
+ * for performant rendering with automatic pause when off-screen.
+ */
+export interface FlickeringGridProps {
+    /** Size of each grid square in pixels */
+    squareSize?: number;
+    /** Gap between squares in pixels */
+    gridGap?: number;
+    /** Probability of a square changing opacity each second (0-1) */
+    flickerChance?: number;
+    /** Color of the squares (hex format) */
+    color?: string;
+    /** Maximum opacity of squares (0-1) */
+    maxOpacity?: number;
+    /** Fixed width in pixels (defaults to container width) */
+    width?: number;
+    /** Fixed height in pixels (defaults to container height) */
+    height?: number;
+    /** Additional CSS classes */
+    className?: string;
+    /**
+     * Seed for the flicker stream. The same seed always produces the same
+     * sequence of opacities, which is what makes the effect reproducible in a
+     * test and identical across two mounts of the same instance. Change it to
+     * give two grids on one page different flicker — the default is shared, so
+     * two `<FlickeringGrid />` with no seed light up alike.
+     */
+    seed?: number;
+}
+export declare function FlickeringGrid({ squareSize, gridGap, flickerChance, color, maxOpacity, width, height, className, seed, }: FlickeringGridProps): import("react").JSX.Element;