@godot-scene-web/canvas-effects 0.1.0

package/dist/webgpu.mjs

@@ -0,0 +1,1349 @@
+import { frameGridFor } from "@godot-scene-web/effects/particles";
+import { INSTANCE_STRIDE as INSTANCE_STRIDE$1 } from "@godot-scene-web/effects";
+//#region src/webgpu-pipeline.ts
+/** Normative WebGPU flags, stated locally so this module needs no browser host. */
+const BUFFER_USAGE = {
+	COPY_DST: 8,
+	UNIFORM: 64
+};
+const SHADER_STAGE = {
+	VERTEX: 1,
+	FRAGMENT: 2
+};
+/**
+* Bytes per per-cell uniform slot. 256 is the maximum `minUniformBufferOffsetAlignment` any WebGPU
+* implementation may report, so a buffer laid out at this pitch is bindable with a dynamic offset
+* everywhere; the real limit is read off the device and only ever rounds DOWN from here.
+*/
+const UNIFORM_SLOT_BYTES = 256;
+let lastError = null;
+/** The first error message from the most recent failed compile/validation (with WGSL line/col when
+*  the failure was a shader), for diagnostics. Null until something fails. */
+function lastPipelineError() {
+	return lastError;
+}
+function fail(message, onError) {
+	onError?.();
+	lastError = message;
+	console.warn("[gsw webgpu]", message);
+	return null;
+}
+/**
+* Compile a WGSL module, returning null when the source has an error-severity message.
+*
+* Reading `getCompilationInfo()` rather than waiting for pipeline creation is what makes the
+* message available at all: a module built from bad WGSL is a valid object that only fails later,
+* inside `createRenderPipeline`, with a generic validation error.
+*/
+async function compileModule(device, code, label, onError) {
+	let module;
+	try {
+		module = device.createShaderModule({
+			code,
+			label
+		});
+	} catch (error) {
+		return fail(`${label} WGSL module creation failed — ${describe(error)}`, onError);
+	}
+	try {
+		const errors = (await module.getCompilationInfo()).messages.filter((message) => message.type === "error");
+		if (errors.length > 0) {
+			const first = errors[0];
+			return fail(`${label} WGSL failed to compile — ${first.message} (line ${first.lineNum}, col ${first.linePos}); ${errors.length} error(s) total`, onError);
+		}
+	} catch (error) {
+		return fail(`${label} WGSL compilation info failed — ${describe(error)}`, onError);
+	}
+	return module;
+}
+/**
+* Create a render pipeline inside a validation error scope, so a layout/blend/vertex-buffer
+* mismatch comes back as a message and a null instead of as a surface that draws nothing.
+*/
+async function createPipeline(device, descriptor, label, onError) {
+	try {
+		device.pushErrorScope("validation");
+		const pipeline = device.createRenderPipeline(descriptor);
+		const error = await device.popErrorScope();
+		if (error) return fail(`${label} pipeline failed WebGPU validation — ${error.message}`, onError);
+		return pipeline;
+	} catch (error) {
+		return fail(`${label} pipeline creation threw — ${describe(error)}`, onError);
+	}
+}
+/** A uniform bind-group layout with binding 0 as a DYNAMIC-offset uniform buffer — the shape every
+*  ring in this package binds through. `minBindingSize` must not exceed the size the bind group
+*  actually binds (the slot, not the buffer), so callers that build their own bind group pass the
+*  same number to both. */
+function uniformBindGroupLayout(device, visibility = SHADER_STAGE.VERTEX | SHADER_STAGE.FRAGMENT, minBindingSize, label = "gsw-uniform") {
+	return device.createBindGroupLayout({
+		label,
+		entries: [{
+			binding: 0,
+			visibility,
+			buffer: minBindingSize === void 0 ? {
+				type: "uniform",
+				hasDynamicOffset: true
+			} : {
+				type: "uniform",
+				hasDynamicOffset: true,
+				minBindingSize
+			}
+		}]
+	});
+}
+function createUniformRing(device, cells, slotFloats = 256 / 4, options = {}) {
+	const label = options.label ?? "gsw-uniform-ring";
+	const count = Math.max(1, Math.floor(cells) || 0);
+	const slotBytes = Math.max(4, Math.ceil(slotFloats) * 4);
+	const alignment = Math.max(256, device.limits.minUniformBufferOffsetAlignment || 256, slotBytes);
+	const pitch = Math.ceil(alignment / 256) * 256;
+	const buffer = device.createBuffer({
+		label,
+		size: pitch * count,
+		usage: BUFFER_USAGE.UNIFORM | BUFFER_USAGE.COPY_DST
+	});
+	const layout = options.layout ?? uniformBindGroupLayout(device, options.visibility, slotBytes, label);
+	return {
+		buffer,
+		layout,
+		bindGroup: device.createBindGroup({
+			label,
+			layout,
+			entries: [{
+				binding: 0,
+				resource: {
+					buffer,
+					offset: 0,
+					size: slotBytes
+				}
+			}]
+		}),
+		pitch,
+		slotBytes,
+		stride: pitch / 4,
+		staging: new Float32Array(pitch / 4 * count),
+		destroy() {
+			buffer.destroy();
+		}
+	};
+}
+function describe(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** TEST-ONLY: clear the last recorded pipeline/shader error. */
+function __resetPipelineErrorForTest() {
+	lastError = null;
+}
+//#endregion
+//#region src/webgpu-readback.ts
+const BUFFER_USAGE$1 = {
+	MAP_READ: 1,
+	COPY_DST: 8
+};
+const MAP_MODE = { READ: 1 };
+/** `copyTextureToBuffer` requires every row to start on a 256-byte boundary, which is why the read
+*  is padded and then re-packed rather than mapped straight into the caller's hands. */
+const BYTES_PER_ROW_ALIGNMENT = 256;
+/**
+* Read `width`×`height` RGBA bytes out of `texture`, tightly packed (`width * 4` bytes per row,
+* top-down, PREMULTIPLIED alpha as stored — every fragment on this backend emits `vec4f(rgb*a, a)`
+* under `PREMULTIPLIED_BLEND`, so the bytes in the texture are already multiplied through. A
+* consumer that needs straight alpha (an encode into a 2D canvas) converts: see
+* `./still-capture`).
+*
+* `texture` must have been created with COPY_SRC usage — a texture that will be read back has to
+* declare it at creation, and there is no way to add it afterwards.
+*/
+async function readTexturePixels(shared, texture, width, height) {
+	const { device } = shared;
+	const w = Math.max(1, Math.floor(width));
+	const h = Math.max(1, Math.floor(height));
+	const bytesPerRow = Math.ceil(w * 4 / BYTES_PER_ROW_ALIGNMENT) * BYTES_PER_ROW_ALIGNMENT;
+	const buffer = device.createBuffer({
+		label: "gsw-readback",
+		size: bytesPerRow * h,
+		usage: BUFFER_USAGE$1.COPY_DST | BUFFER_USAGE$1.MAP_READ
+	});
+	try {
+		const encoder = device.createCommandEncoder({ label: "gsw-readback" });
+		encoder.copyTextureToBuffer({ texture }, {
+			buffer,
+			bytesPerRow,
+			rowsPerImage: h
+		}, [
+			w,
+			h,
+			1
+		]);
+		device.queue.submit([encoder.finish()]);
+		await buffer.mapAsync(MAP_MODE.READ);
+		const padded = new Uint8Array(buffer.getMappedRange());
+		const packed = new Uint8Array(w * h * 4);
+		for (let row = 0; row < h; row++) packed.set(padded.subarray(row * bytesPerRow, row * bytesPerRow + w * 4), row * w * 4);
+		buffer.unmap();
+		return packed;
+	} finally {
+		buffer.destroy();
+	}
+}
+//#endregion
+//#region src/particles-webgpu.ts
+const PARTICLE_BUFFER_USAGE = {
+	VERTEX: 32,
+	COPY_DST: 8
+};
+const PARTICLE_TEXTURE_USAGE = {
+	COPY_SRC: 1,
+	COPY_DST: 2,
+	TEXTURE_BINDING: 4,
+	RENDER_ATTACHMENT: 16
+};
+/** Bytes per packed instance record: the shipped `INSTANCE_STRIDE` (10 floats) × 4. Stated as a
+*  literal because it is what the vertex-buffer layout declares as its `arrayStride` and what every
+*  attribute offset below is measured in. */
+const INSTANCE_STRIDE_BYTES = 40;
+if (INSTANCE_STRIDE$1 * 4 !== 40) throw new Error(`gsw particle instance stride drift: INSTANCE_STRIDE (${INSTANCE_STRIDE$1}) * 4 !== 40. PARTICLE_VERTEX_BUFFERS in particles/render-webgpu.ts declares byte offsets into the packed record (center@0, scale@8, rotation@16, color@20, frame@36) and must be updated with it.`);
+/** Vertex entry point of `PARTICLE_WGSL`. Referenced by the pipeline descriptors, never spelled twice. */
+const PARTICLE_VS_ENTRY = "vs_particles";
+/** Fragment entry point for MIX (and every non-additive) blend: premultiplied colour out. */
+const PARTICLE_FS_ENTRY = "fs_particles";
+/** Fragment entry point for the ADDITIVE accumulate pass: raw light out, alpha 0. */
+const PARTICLE_FS_ADDITIVE_ENTRY = "fs_particles_additive";
+/** Vertex entry point of `ADDITIVE_RESOLVE_WGSL` (a full-target strip). */
+const RESOLVE_VS_ENTRY = "vs_resolve";
+/** Fragment entry point of `ADDITIVE_RESOLVE_WGSL`. */
+const RESOLVE_FS_ENTRY = "fs_resolve";
+/**
+* The blend state every non-additive draw uses, and the other half of the premultiply contract in
+* the module header.
+*
+* `one / one-minus-src-alpha` on colour AND alpha: the fragment already carries `rgb * a`, so the
+* source contributes its light unscaled and the destination is attenuated by the coverage the source
+* claims — `dst' = src.rgb*src.a + dst*(1-src.a)`, which is what `SRC_ALPHA / ONE_MINUS_SRC_ALPHA`
+* computes over a straight-alpha source (the GL path's blend). The alpha channel gets the same pair
+* so the canvas's own alpha accumulates the same way.
+*/
+const PREMULTIPLIED_BLEND = {
+	color: {
+		operation: "add",
+		srcFactor: "one",
+		dstFactor: "one-minus-src-alpha"
+	},
+	alpha: {
+		operation: "add",
+		srcFactor: "one",
+		dstFactor: "one-minus-src-alpha"
+	}
+};
+/** The ACCUMULATE pass's blend: `ONE, ONE` on both channels, i.e. `render-webgl`'s
+*  `blendFactorsFor(1)` — overlapping additive particles SUM their raw light (Godot
+*  `BLEND_MODE_ADD`) instead of compositing over one another. */
+const ADDITIVE_BLEND = {
+	color: {
+		operation: "add",
+		srcFactor: "one",
+		dstFactor: "one"
+	},
+	alpha: {
+		operation: "add",
+		srcFactor: "one",
+		dstFactor: "one"
+	}
+};
+/**
+* The vertex buffer layout: slot 0 is the static unit-quad corner (stepped per VERTEX), slot 1 is the
+* packed instance record (stepped per INSTANCE).
+*
+* The attribute offsets are the shipped float offsets × 4 — center@0, scale@8, rotation@16,
+* color@20, frame@36 — i.e. exactly `INSTANCE_ATTRS` in `render-webgl.ts`, in bytes. Exported so a
+* test can read the stride back without building a device.
+*/
+const PARTICLE_VERTEX_BUFFERS = [{
+	arrayStride: 8,
+	stepMode: "vertex",
+	attributes: [{
+		shaderLocation: 0,
+		offset: 0,
+		format: "float32x2"
+	}]
+}, {
+	arrayStride: 40,
+	stepMode: "instance",
+	attributes: [
+		{
+			shaderLocation: 1,
+			offset: 0,
+			format: "float32x2"
+		},
+		{
+			shaderLocation: 2,
+			offset: 8,
+			format: "float32x2"
+		},
+		{
+			shaderLocation: 3,
+			offset: 16,
+			format: "float32"
+		},
+		{
+			shaderLocation: 4,
+			offset: 20,
+			format: "float32x4"
+		},
+		{
+			shaderLocation: 5,
+			offset: 36,
+			format: "float32"
+		}
+	]
+}];
+/** Floats in the per-surface uniform slot (`Params` below): 6 f32 then 6 u32, all 4 bytes. */
+const PARAMS_FLOATS = 12;
+const PARAMS_BYTES = PARAMS_FLOATS * 4;
+/**
+* The instanced particle module — `render-webgl.ts`'s two shader stages, transcribed.
+*
+* PER-SYSTEM VALUES ARE UNIFORMS, NOT PIPELINE VARIANTS. `textured`/`lut`/`mask`/`uvPolar` etc. select
+* branches at runtime out of ONE pipeline, exactly as the GL program's `u_textured`/`u_lut` do — the
+* alternative (a pipeline per feature combination) is 64 pipelines for a fragment whose branches are
+* uniform-valued and therefore free of divergence. Sampling inside those branches is legal for two
+* independent reasons: a branch on a uniform value is UNIFORM CONTROL FLOW (so even
+* derivative-taking `textureSample` would be allowed), and the samples below use
+* `textureSampleLevel(..., 0.0)`, which needs no derivatives at all. Level 0 is not an approximation
+* here: every texture this backend binds is created with a single mip level (see `../webgpu/textures`).
+*/
+const PARTICLE_WGSL = `struct Params {
+  viewport: vec2f,       // canvas backing size, device px — REWRITTEN EVERY DRAW (canvases resize)
+  grid: vec2f,           // hframes, vframes
+  erodeFactors: vec2f,   // threshold, softness
+  textured: u32,
+  lut: u32,
+  alphaFromRed: u32,
+  erode: u32,
+  mask: u32,
+  uvPolar: u32,
+};
+
+@group(0) @binding(0) var<uniform> params: Params;
+@group(1) @binding(0) var sprite_tex: texture_2d<f32>;
+@group(1) @binding(1) var sprite_smp: sampler;
+@group(1) @binding(2) var lut_tex: texture_2d<f32>;
+@group(1) @binding(3) var lut_smp: sampler;
+@group(1) @binding(4) var mask_tex: texture_2d<f32>;
+@group(1) @binding(5) var mask_smp: sampler;
+
+// GLSL's \`mod\` is FLOOR-signed; WGSL's \`%\` is TRUNC-signed. The flipbook cell index and the polar
+// wrap are both written against GLSL semantics in the shader this ports, so re-derive them rather
+// than swap in an operator that agrees only for positive operands.
+fn godot_mod(x: f32, y: f32) -> f32 {
+  return x - y * floor(x / y);
+}
+
+struct VsOut {
+  @builtin(position) pos: vec4f,
+  @location(0) uv: vec2f,
+  @location(1) quad: vec2f,
+  @location(2) cell: vec2f,
+  @location(3) color: vec4f,
+};
+
+@vertex
+fn ${PARTICLE_VS_ENTRY}(
+  @location(0) corner: vec2f,
+  @location(1) center: vec2f,
+  @location(2) scale: vec2f,
+  @location(3) rotation: f32,
+  @location(4) color: vec4f,
+  @location(5) frame: f32,
+) -> VsOut {
+  let c = cos(rotation);
+  let s = sin(rotation);
+  let rotated = vec2f(corner.x * c - corner.y * s, corner.x * s + corner.y * c);
+  let px = center + rotated * scale;
+  var clip = (px / params.viewport) * 2.0 - 1.0;
+  clip.y = -clip.y;                       // canvas Y-down -> clip Y-up
+  var out: VsOut;
+  out.pos = vec4f(clip, 0.0, 1.0);
+  let uv01 = corner + 0.5;                // 0..1 across the SPRITE quad
+  let cell = vec2f(godot_mod(frame, params.grid.x), floor(frame / params.grid.x));
+  out.uv = (cell + uv01) / params.grid;
+  // The flipbook cell INDEX, so a fragment that re-derives its own sprite-local UV (the polar remap)
+  // can map it back into the same cell instead of over the whole sheet.
+  out.cell = cell;
+  // Quad-local 0..1, INDEPENDENT of the flipbook grid: the untextured dot and the coverage mask are
+  // both measured from this. Deriving them from the atlas-mapped uv put the dot's centre at the
+  // SHEET's centre, so any grid > 1x1 left it off-centre and clipped to a sliver of one cell.
+  out.quad = uv01;
+  out.color = color;
+  return out;
+}
+
+struct Shaded {
+  col: vec4f,
+  coverage: f32,
+};
+
+// The whole fragment feature set, shared by both entry points below so the mix and additive paths
+// can never disagree about it (in GL they are one shader and a branch).
+fn shade(in: VsOut) -> Shaded {
+  var uv = in.uv;
+  if (params.uvPolar == 1u) {
+    // Godot polar_coordinates(UV, vec2(0.5), 1, 1) (shaders/vfx/_util/polar_coordinates.gdshaderinc):
+    // x = radius from the sprite centre (0..1.41 at the corners), y = the angle mapped to 0..1, both
+    // wrapped — then RE-WRAPPED INTO THE SAME CELL through in.cell, so a flipbook stays a flipbook.
+    // A radial sheet (common_ring_polar_a) is a RING only through this; sampled flat it is a
+    // vertical BAR.
+    let dir = in.quad - vec2f(0.5);
+    let radius = length(dir) * 2.0;
+    let angle = atan2(dir.y, dir.x) * (1.0 / (3.1416 * 2.0));
+    uv = (in.cell + vec2f(godot_mod(radius, 1.0), godot_mod(angle, 1.0))) / params.grid;
+  }
+  var tex: vec4f;
+  if (params.textured == 1u) {
+    tex = textureSampleLevel(sprite_tex, sprite_smp, uv, 0.0);
+  } else {
+    // Soft round dot when the system has no texture — measured across the QUAD, not the atlas-mapped
+    // uv, so it stays centred whatever the (meaningless, textureless) grid is.
+    let r = length(in.quad - vec2f(0.5)) * 2.0;
+    tex = vec4f(1.0, 1.0, 1.0, 1.0 - smoothstep(0.7, 1.0, r));
+  }
+  // COVERAGE — taken PRE-LUT, because the LUT is a colour lookup INDEXED by that same red channel:
+  // reading it afterwards would sample the LUT's own (usually white) output instead of the sheet's
+  // shape. Grayscale VFX sheets are alpha-less PNGs, so tex.a is 1.0 everywhere and the alpha branch
+  // draws a SQUARE.
+  var coverage = select(tex.a, tex.r, params.alphaFromRed == 1u);
+  if (params.lut == 1u) {
+    // Godot's VFX particle-shader family: COLOR = vec4(texture(lut, texture_color.rr).rgb, alpha) *
+    // vertex_color. The sheet is a single-channel MASK, so its own RGB is meaningless; the LUT holds
+    // the real colours. Sampled AFTER the texture/dot resolve so both branches are recoloured, and
+    // the source ALPHA is preserved untouched — only RGB comes from the LUT.
+    tex = vec4f(textureSampleLevel(lut_tex, lut_smp, vec2f(tex.r, 0.5), 0.0).rgb, tex.a);
+  }
+  if (params.erode == 1u) {
+    // Godot erosion_from_factors(vec2(threshold, softness), coverage) — a CONSTANT erosion curve,
+    // i.e. the threshold does not sweep over the particle's life. AFTER the LUT, BEFORE the mask.
+    coverage = smoothstep(params.erodeFactors.x, params.erodeFactors.x + params.erodeFactors.y, coverage);
+  }
+  if (params.mask == 1u) {
+    // Godot's mask sampler reads the sprite's own UV, NOT the flipbook cell — it shapes the whole quad.
+    coverage = coverage * textureSampleLevel(mask_tex, mask_smp, in.quad, 0.0).r;
+  }
+  tex.a = coverage;
+  var out: Shaded;
+  out.col = tex * in.color;
+  out.coverage = coverage;
+  return out;
+}
+
+@fragment
+fn ${PARTICLE_FS_ENTRY}(in: VsOut) -> @location(0) vec4f {
+  let col = shade(in).col;
+  // PREMULTIPLIED — see the module header. Only correct under PREMULTIPLIED_BLEND.
+  return vec4f(col.rgb * col.a, col.a);
+}
+
+@fragment
+fn ${PARTICLE_FS_ADDITIVE_ENTRY}(in: VsOut) -> @location(0) vec4f {
+  // Additive sprites contribute light = colour x alpha (Godot BLEND_MODE_ADD adds src.rgb * src.a to
+  // the framebuffer, so an opaque-black glow background or an alpha-shaped sprite's transparent area
+  // both add nothing). Emit that light RAW and SUM it across particles (ADDITIVE_BLEND, into the
+  // accumulator); the resolve pass converts the per-pixel TOTAL to coverage ONCE. Normalizing per
+  // PARTICLE amplified every faint texel to full brightness and let overlaps clamp to white while
+  // stacking coverage — a subtle 5-particle fog rendered as an opaque white haze wall.
+  // ALPHA IS 0: the accumulator holds light, not coverage.
+  let shaded = shade(in);
+  return vec4f(shaded.col.rgb * shaded.coverage * in.color.a, 0.0);
+}
+`;
+/**
+* The additive RESOLVE pass: read the summed light out of the accumulator and present it.
+*
+* THE ALGEBRA. A premultiplied canvas wants the accumulated light itself: `(light, cov)` composites
+* to `light + dst*(1-cov)`, with no division at all — and therefore no `cov > 0` guard either, since
+* the division that would have needed one is gone (at cov = 0 the fragment is (0,0,0,0), which
+* composites to `dst` exactly). `RESOLVE_FRAGMENT_SRC` in `./render-webgl.ts` is now the same
+* expression, its canvas being premultiplied too; it used to divide by `cov` for a straight-alpha
+* canvas and rely on the blit into the node canvas to multiply it back.
+*
+* `textureLoad` at integer pixel coordinates, like GL's `texelFetch`: the accumulate pass renders
+* into the top-left w×h rect of a grow-only accumulator, and WebGPU framebuffer coordinates are
+* Y-DOWN in both passes, so texel (x, y) is fragment (x, y) with no flip arithmetic anywhere.
+*/
+const ADDITIVE_RESOLVE_WGSL = `@group(0) @binding(0) var accum_tex: texture_2d<f32>;
+
+@vertex
+fn ${RESOLVE_VS_ENTRY}(@builtin(vertex_index) index: u32) -> @builtin(position) vec4f {
+  // TRIANGLE_STRIP corner order, matching the particle quad's: (-1,-1) (1,-1) (-1,1) (1,1).
+  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)
+  );
+  return vec4f(corners[index], 0.0, 1.0);
+}
+
+@fragment
+fn ${RESOLVE_FS_ENTRY}(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+  let light = textureLoad(accum_tex, vec2i(pos.xy), 0).rgb;
+  let cov = max(light.r, max(light.g, light.b));
+  return vec4f(light, cov);
+}
+`;
+/** The accumulator's format. `rgba8unorm` rather than a float target ON PURPOSE: the GL path
+*  accumulates into an RGBA/UNSIGNED_BYTE FBO, so its sums CLAMP at 1.0 per channel, and matching
+*  that byte-clamping beats being more faithful than the renderer this must look identical to. */
+const ACCUM_FORMAT = "rgba8unorm";
+const TRANSPARENT$1 = {
+	r: 0,
+	g: 0,
+	b: 0,
+	a: 0
+};
+let programMemo;
+let programSettled;
+let programDevice = null;
+function acquireParticleProgram(options) {
+	if (programDevice !== options.device) {
+		programMemo = void 0;
+		programSettled = void 0;
+		programDevice = options.device;
+	}
+	if (programMemo) return programMemo;
+	programMemo = buildParticleProgram(options).then((program) => {
+		programSettled = program;
+		return program;
+	});
+	return programMemo;
+}
+function peekParticleProgram(options) {
+	return programDevice === options.device ? programSettled : void 0;
+}
+async function buildParticleProgram(options) {
+	const { device, format } = options;
+	const module = await compileModule(device, PARTICLE_WGSL, "gsw-particles");
+	if (!module) return null;
+	const resolveModule = await compileModule(device, ADDITIVE_RESOLVE_WGSL, "gsw-particle-resolve");
+	if (!resolveModule) return null;
+	const uniformLayout = uniformBindGroupLayout(device, SHADER_STAGE.VERTEX | SHADER_STAGE.FRAGMENT, PARAMS_BYTES, "gsw-particle-params");
+	const textureLayout = device.createBindGroupLayout({
+		label: "gsw-particle-textures",
+		entries: [
+			{
+				binding: 0,
+				visibility: SHADER_STAGE.FRAGMENT,
+				texture: {}
+			},
+			{
+				binding: 1,
+				visibility: SHADER_STAGE.FRAGMENT,
+				sampler: {}
+			},
+			{
+				binding: 2,
+				visibility: SHADER_STAGE.FRAGMENT,
+				texture: {}
+			},
+			{
+				binding: 3,
+				visibility: SHADER_STAGE.FRAGMENT,
+				sampler: {}
+			},
+			{
+				binding: 4,
+				visibility: SHADER_STAGE.FRAGMENT,
+				texture: {}
+			},
+			{
+				binding: 5,
+				visibility: SHADER_STAGE.FRAGMENT,
+				sampler: {}
+			}
+		]
+	});
+	const accumLayout = device.createBindGroupLayout({
+		label: "gsw-particle-accum",
+		entries: [{
+			binding: 0,
+			visibility: SHADER_STAGE.FRAGMENT,
+			texture: {}
+		}]
+	});
+	const particleLayout = device.createPipelineLayout({
+		label: "gsw-particles",
+		bindGroupLayouts: [uniformLayout, textureLayout]
+	});
+	const resolvePipelineLayout = device.createPipelineLayout({
+		label: "gsw-particle-resolve",
+		bindGroupLayouts: [accumLayout]
+	});
+	const normal = await createPipeline(device, particlePipelineDescriptor(module, particleLayout, format, false), "gsw-particles");
+	if (!normal) return null;
+	const accumulate = await createPipeline(device, particlePipelineDescriptor(module, particleLayout, ACCUM_FORMAT, true), "gsw-particles-additive");
+	if (!accumulate) return null;
+	const resolve = await createPipeline(device, resolvePipelineDescriptor(resolveModule, resolvePipelineLayout, format), "gsw-particle-resolve");
+	if (!resolve) return null;
+	const corners = device.createBuffer({
+		label: "gsw-particle-corners",
+		size: 32,
+		usage: PARTICLE_BUFFER_USAGE.VERTEX | PARTICLE_BUFFER_USAGE.COPY_DST
+	});
+	device.queue.writeBuffer(corners, 0, new Float32Array([
+		-.5,
+		-.5,
+		.5,
+		-.5,
+		-.5,
+		.5,
+		.5,
+		.5
+	]));
+	const placeholder = device.createTexture({
+		label: "gsw-particle-placeholder",
+		size: [
+			1,
+			1,
+			1
+		],
+		format: "rgba8unorm",
+		usage: PARTICLE_TEXTURE_USAGE.TEXTURE_BINDING | PARTICLE_TEXTURE_USAGE.COPY_DST
+	});
+	device.queue.writeTexture({ texture: placeholder }, new Uint8Array([
+		255,
+		255,
+		255,
+		255
+	]), {
+		bytesPerRow: 4,
+		rowsPerImage: 1
+	}, [
+		1,
+		1,
+		1
+	]);
+	return {
+		device,
+		format,
+		module,
+		resolveModule,
+		uniformLayout,
+		textureLayout,
+		accumLayout,
+		particleLayout,
+		resolvePipelineLayout,
+		normal,
+		accumulate,
+		resolve,
+		corners,
+		placeholderView: placeholder.createView(),
+		placeholderSampler: device.createSampler({
+			label: "gsw-particle-placeholder",
+			magFilter: "linear",
+			minFilter: "linear"
+		}),
+		accum: null,
+		capture: null
+	};
+}
+function particlePipelineDescriptor(module, layout, format, additive) {
+	return {
+		label: additive ? "gsw-particles-additive" : "gsw-particles",
+		layout,
+		vertex: {
+			module,
+			entryPoint: PARTICLE_VS_ENTRY,
+			buffers: PARTICLE_VERTEX_BUFFERS
+		},
+		fragment: {
+			module,
+			entryPoint: additive ? PARTICLE_FS_ADDITIVE_ENTRY : PARTICLE_FS_ENTRY,
+			targets: [{
+				format,
+				blend: additive ? ADDITIVE_BLEND : PREMULTIPLIED_BLEND
+			}]
+		},
+		primitive: { topology: "triangle-strip" }
+	};
+}
+function resolvePipelineDescriptor(module, layout, format) {
+	return {
+		label: "gsw-particle-resolve",
+		layout,
+		vertex: {
+			module,
+			entryPoint: RESOLVE_VS_ENTRY
+		},
+		fragment: {
+			module,
+			entryPoint: RESOLVE_FS_ENTRY,
+			targets: [{ format }]
+		},
+		primitive: { topology: "triangle-strip" }
+	};
+}
+/** Construct a renderer after its device program is compiled. Presentation contexts and texture handles stay host-owned. */
+async function createWebgpuParticleRenderer(options) {
+	const program = await acquireParticleProgram(options);
+	return program ? rendererOver(options, program) : null;
+}
+function peekWebgpuParticleRenderer(options) {
+	const program = peekParticleProgram(options);
+	return program === void 0 ? void 0 : program === null ? null : rendererOver(options, program);
+}
+function rendererOver(options, program) {
+	const { device } = options;
+	let encoder = null;
+	let recorded = false;
+	let implicit = false;
+	let submitCount = 0;
+	const ensureEncoder = () => {
+		if (!encoder) {
+			encoder = device.createCommandEncoder({ label: "gsw-particles" });
+			implicit = true;
+		}
+		return encoder;
+	};
+	const flush = () => {
+		if (encoder && recorded) {
+			device.queue.submit([encoder.finish()]);
+			submitCount++;
+		}
+		encoder = null;
+		recorded = false;
+		implicit = false;
+	};
+	const flushImplicit = () => {
+		if (implicit) flush();
+	};
+	return {
+		createSurface(surface) {
+			const ring = createUniformRing(device, 1, PARAMS_FLOATS, {
+				label: "gsw-particle-params",
+				layout: program.uniformLayout
+			});
+			const state = Object.assign(surface, {
+				ring,
+				words: new Uint32Array(ring.staging.buffer),
+				instances: null,
+				instanceBytes: 0,
+				bindGroup: null,
+				boundViews: [
+					null,
+					null,
+					null
+				],
+				bindGroupDirty: true,
+				disposeTextureListener: null
+			});
+			state.disposeTextureListener = surface.onTexturesChanged?.(() => {
+				state.bindGroupDirty = true;
+			}) ?? null;
+			return state;
+		},
+		disposeSurface(state) {
+			state.disposeTextureListener?.();
+			state.instances?.destroy();
+			state.ring.destroy();
+			state.bindGroup = null;
+		},
+		beginFrame() {
+			if (!encoder) {
+				encoder = device.createCommandEncoder({ label: "gsw-particles" });
+				recorded = false;
+				implicit = false;
+			}
+		},
+		endFrame: flush,
+		clear(state) {
+			const view = currentView(state);
+			if (view) {
+				ensureEncoder().beginRenderPass({
+					label: "gsw-particle-clear",
+					colorAttachments: [{
+						view,
+						clearValue: TRANSPARENT$1,
+						loadOp: "clear",
+						storeOp: "store"
+					}]
+				}).end();
+				recorded = true;
+			}
+			flushImplicit();
+		},
+		draw(state, buffer, opts) {
+			const view = currentView(state);
+			if (view) {
+				encodeSurface(program, ensureEncoder(), state, view, buffer, opts);
+				recorded = true;
+			}
+			flushImplicit();
+		},
+		submits: () => submitCount,
+		captureSurface: (state, buffer, opts) => captureSurfacePixels(program, options, state, buffer, opts)
+	};
+}
+/** The canvas's current swap-chain view, or null when it cannot be had (an unconfigured context, a
+*  zero-sized canvas, a lost device). A frame that cannot acquire its target is SKIPPED, not thrown
+*  out of: the runtime's next tick asks again. */
+function currentView(state) {
+	try {
+		return state.context.getCurrentTexture().createView();
+	} catch {
+		return null;
+	}
+}
+/** Record one system's draw into `encoder`, targeting `view` (the canvas's swap-chain image, or a
+*  capture texture). Additive systems record TWO passes; passes execute in the order they were
+*  recorded, so accumulate→resolve is safe inside the shared one-submit frame. */
+function encodeSurface(program, encoder, state, view, buffer, opts, capture = false) {
+	const w = Math.max(1, Math.floor(opts.width));
+	const h = Math.max(1, Math.floor(opts.height));
+	writeParams(program, state, w, h, opts);
+	uploadInstances(program, state, buffer);
+	const textures = ensureBindGroup(program, state);
+	const additive = opts.blendMode === 1;
+	const pipelines = capture ? captureOrThrow(program) : program;
+	if (additive) {
+		const accum = ensureAccum(program, w, h);
+		const accumPass = encoder.beginRenderPass({
+			label: "gsw-particle-accumulate",
+			colorAttachments: [{
+				view: accum.view,
+				clearValue: TRANSPARENT$1,
+				loadOp: "clear",
+				storeOp: "store"
+			}]
+		});
+		accumPass.setViewport(0, 0, w, h, 0, 1);
+		accumPass.setScissorRect(0, 0, w, h);
+		accumPass.setPipeline(program.accumulate);
+		accumPass.setBindGroup(0, state.ring.bindGroup, [0]);
+		accumPass.setBindGroup(1, textures);
+		accumPass.setVertexBuffer(0, program.corners);
+		accumPass.setVertexBuffer(1, state.instances);
+		accumPass.draw(4, buffer.count);
+		accumPass.end();
+		const resolvePass = encoder.beginRenderPass({
+			label: "gsw-particle-resolve",
+			colorAttachments: [{
+				view,
+				clearValue: TRANSPARENT$1,
+				loadOp: "clear",
+				storeOp: "store"
+			}]
+		});
+		resolvePass.setPipeline(pipelines.resolve);
+		resolvePass.setBindGroup(0, accum.bindGroup);
+		resolvePass.draw(4, 1);
+		resolvePass.end();
+		return;
+	}
+	const pass = encoder.beginRenderPass({
+		label: "gsw-particle-draw",
+		colorAttachments: [{
+			view,
+			clearValue: TRANSPARENT$1,
+			loadOp: "clear",
+			storeOp: "store"
+		}]
+	});
+	pass.setPipeline(pipelines.normal);
+	pass.setBindGroup(0, state.ring.bindGroup, [0]);
+	pass.setBindGroup(1, textures);
+	pass.setVertexBuffer(0, program.corners);
+	pass.setVertexBuffer(1, state.instances);
+	pass.draw(4, buffer.count);
+	pass.end();
+}
+/** The per-surface uniform slot. REWRITTEN EVERY DRAW rather than latched at create: a node canvas
+*  resizes (renderScale, a pin change, a rotation, a laid-out box moving), and a stale viewport maps
+*  every particle to the wrong clip position — silently, since nothing about it is an error. */
+function writeParams(program, state, w, h, opts) {
+	const textured = Boolean(opts.textured && state.textures.sprite);
+	const [hframes, vframes] = frameGridFor(textured, opts.hframes, opts.vframes);
+	const erode = opts.erode ?? null;
+	const floats = state.ring.staging;
+	const words = state.words;
+	floats[0] = w;
+	floats[1] = h;
+	floats[2] = hframes;
+	floats[3] = vframes;
+	floats[4] = erode ? erode.threshold : 0;
+	floats[5] = erode ? erode.softness : 0;
+	words[6] = textured ? 1 : 0;
+	words[7] = opts.lutTexture && state.textures.lut ? 1 : 0;
+	words[8] = opts.alphaFromRed ? 1 : 0;
+	words[9] = erode ? 1 : 0;
+	words[10] = opts.maskTexture && state.textures.mask ? 1 : 0;
+	words[11] = opts.uvPolar ? 1 : 0;
+	program.device.queue.writeBuffer(state.ring.buffer, 0, floats, 0, PARAMS_FLOATS);
+}
+/** The per-surface instance buffer: GROW-ONLY, like everything else in this pipeline, so a steady
+*  fleet allocates nothing per frame. */
+function uploadInstances(program, state, buffer) {
+	const bytes = Math.max(40, buffer.count * 40);
+	if (!state.instances || bytes > state.instanceBytes) {
+		state.instances?.destroy();
+		state.instances = program.device.createBuffer({
+			label: "gsw-particle-instances",
+			size: bytes,
+			usage: PARTICLE_BUFFER_USAGE.VERTEX | PARTICLE_BUFFER_USAGE.COPY_DST
+		});
+		state.instanceBytes = bytes;
+	}
+	if (buffer.count <= 0) return;
+	program.device.queue.writeBuffer(state.instances, 0, buffer.data.buffer, buffer.data.byteOffset, buffer.count * 40);
+}
+/** The surface's texture bind group, rebuilt when a decode replaced one of its views (see
+*  `WebgpuParticleSurfaceState.boundViews`) and otherwise reused. */
+function ensureBindGroup(program, state) {
+	const spriteView = state.textures.sprite?.view ?? program.placeholderView;
+	const lutView = state.textures.lut?.view ?? program.placeholderView;
+	const maskView = state.textures.mask?.view ?? program.placeholderView;
+	const stale = state.boundViews[0] !== spriteView || state.boundViews[1] !== lutView || state.boundViews[2] !== maskView;
+	if (state.bindGroup && !state.bindGroupDirty && !stale) return state.bindGroup;
+	state.bindGroup = program.device.createBindGroup({
+		label: "gsw-particle-textures",
+		layout: program.textureLayout,
+		entries: [
+			{
+				binding: 0,
+				resource: spriteView
+			},
+			{
+				binding: 1,
+				resource: state.textures.sprite?.sampler ?? program.placeholderSampler
+			},
+			{
+				binding: 2,
+				resource: lutView
+			},
+			{
+				binding: 3,
+				resource: state.textures.lut?.sampler ?? program.placeholderSampler
+			},
+			{
+				binding: 4,
+				resource: maskView
+			},
+			{
+				binding: 5,
+				resource: state.textures.mask?.sampler ?? program.placeholderSampler
+			}
+		]
+	});
+	state.boundViews = [
+		spriteView,
+		lutView,
+		maskView
+	];
+	state.bindGroupDirty = false;
+	return state.bindGroup;
+}
+/** Grow (never shrink) the device-scope light accumulator to cover w×h — the same policy, for the
+*  same realloc-cost reason, as the GL path's `ensureAccumTarget`. */
+function ensureAccum(program, w, h) {
+	const current = program.accum;
+	if (current && current.width >= w && current.height >= h) return current;
+	const width = Math.max(current?.width ?? 0, w);
+	const height = Math.max(current?.height ?? 0, h);
+	current?.texture.destroy();
+	const texture = program.device.createTexture({
+		label: "gsw-particle-accum",
+		size: [
+			width,
+			height,
+			1
+		],
+		format: ACCUM_FORMAT,
+		usage: PARTICLE_TEXTURE_USAGE.RENDER_ATTACHMENT | PARTICLE_TEXTURE_USAGE.TEXTURE_BINDING
+	});
+	const view = texture.createView();
+	const accum = {
+		texture,
+		view,
+		bindGroup: program.device.createBindGroup({
+			label: "gsw-particle-accum",
+			layout: program.accumLayout,
+			entries: [{
+				binding: 0,
+				resource: view
+			}]
+		}),
+		width,
+		height
+	};
+	program.accum = accum;
+	return accum;
+}
+function captureOrThrow(program) {
+	const capture = program.capture;
+	if (!capture) throw new Error("gsw: capture pipelines were not compiled");
+	return capture;
+}
+/**
+* Re-render this surface's CURRENT frame into an offscreen texture and read it back.
+*
+* NEVER `drawImage`/`toDataURL` FROM THE CANVAS. Both read a WebGPU canvas through its presentation
+* path, which is blank under headless SwiftShader and pathological on Android Chrome (S7 measured
+* 23 Hz against 87 for direct presentation). `copyTextureToBuffer` + `mapAsync` — what
+* `../webgpu/readback` does — is the one path verified to work fully headless, which is why this
+* hook exists at all rather than the parity harness simply reading the canvas.
+*
+* The pipelines are the live ones re-created against `rgba8unorm`: a pipeline's fragment target
+* format must match its attachment, and the canvas format is usually `bgra8unorm`. Everything else —
+* module, entry points, blend states, uniforms, bind groups — is shared with the live draw, so what
+* comes back is the frame the canvas is showing, not a second interpretation of it.
+*/
+async function captureSurfacePixels(program, options, state, buffer, opts) {
+	const w = Math.max(1, Math.floor(opts.width));
+	const h = Math.max(1, Math.floor(opts.height));
+	if (!program.capture) {
+		const normal = await createPipeline(program.device, particlePipelineDescriptor(program.module, program.particleLayout, ACCUM_FORMAT, false), "gsw-particles-capture");
+		const resolve = await createPipeline(program.device, resolvePipelineDescriptor(program.resolveModule, program.resolvePipelineLayout, ACCUM_FORMAT), "gsw-particle-resolve-capture");
+		if (!normal || !resolve) return null;
+		program.capture = {
+			normal,
+			resolve
+		};
+	}
+	const target = program.device.createTexture({
+		label: "gsw-particle-capture",
+		size: [
+			w,
+			h,
+			1
+		],
+		format: ACCUM_FORMAT,
+		usage: PARTICLE_TEXTURE_USAGE.RENDER_ATTACHMENT | PARTICLE_TEXTURE_USAGE.COPY_SRC
+	});
+	try {
+		const encoder = program.device.createCommandEncoder({ label: "gsw-particle-capture" });
+		encodeSurface(program, encoder, state, target.createView(), buffer, {
+			...opts,
+			width: w,
+			height: h
+		}, true);
+		program.device.queue.submit([encoder.finish()]);
+		return await (options.readTexturePixels ?? ((texture, width, height) => readTexturePixels({ device: options.device }, texture, width, height)))(target, w, h);
+	} catch {
+		options.onPipelineError?.();
+		return null;
+	} finally {
+		target.destroy();
+	}
+}
+/** TEST-ONLY: drop the device-scope pipelines so a suite can re-probe with a fresh stub device. */
+function __resetWebgpuParticleProgramForTest() {
+	programMemo = void 0;
+	programSettled = void 0;
+	programDevice = null;
+}
+//#endregion
+//#region src/shader-webgpu.ts
+/** Adapter-neutral WebGPU command executor for canvas shaders. Hosts own DOM, texture resolution and bind groups. */
+const TEXTURE_USAGE = {
+	COPY_SRC: 1,
+	RENDER_ATTACHMENT: 16
+};
+const TRANSPARENT = {
+	r: 0,
+	g: 0,
+	b: 0,
+	a: 0
+};
+function createWebgpuShaderBindGroupLayout(device, label, entries) {
+	return device.createBindGroupLayout({
+		label,
+		entries: Array.from(entries)
+	});
+}
+function createWebgpuShaderUniformBuffer(device, label, size) {
+	return device.createBuffer({
+		label,
+		size,
+		usage: 72
+	});
+}
+function createWebgpuShaderBindGroup(device, label, layout, entries) {
+	return device.createBindGroup({
+		label,
+		layout,
+		entries: Array.from(entries)
+	});
+}
+/** Owns one command encoder per host frame. It never creates contexts or texture handles. */
+var WebgpuShaderExecutor = class {
+	device;
+	encoder = null;
+	recorded = false;
+	implicit = false;
+	submitCount = 0;
+	constructor(device) {
+		this.device = device;
+	}
+	beginFrame() {
+		if (this.encoder) return;
+		this.encoder = this.device.createCommandEncoder({ label: "gsw-shaders" });
+		this.recorded = false;
+		this.implicit = false;
+	}
+	endFrame() {
+		this.flush();
+	}
+	submits() {
+		return this.submitCount;
+	}
+	draw(draw) {
+		const target = draw.target ?? this.currentView(draw.context);
+		if (!target) return false;
+		const encoder = this.ensureEncoder();
+		this.device.queue.writeBuffer(draw.uniformBuffer, 0, draw.uniformBytes, 0, draw.uniformBytes.byteLength);
+		const pass = encoder.beginRenderPass({
+			label: "gsw-shader-draw",
+			colorAttachments: [{
+				view: target,
+				clearValue: TRANSPARENT,
+				loadOp: "clear",
+				storeOp: "store"
+			}]
+		});
+		pass.setViewport(0, 0, draw.width, draw.height, 0, 1);
+		pass.setPipeline(draw.pipeline);
+		pass.setBindGroup(0, draw.bindGroup);
+		pass.draw(4, 1);
+		pass.end();
+		this.recorded = true;
+		if (this.implicit) this.flush();
+		return true;
+	}
+	async capture(draw) {
+		const target = this.device.createTexture({
+			label: "gsw-shader-capture",
+			size: [
+				draw.width,
+				draw.height,
+				1
+			],
+			format: "rgba8unorm",
+			usage: TEXTURE_USAGE.RENDER_ATTACHMENT | TEXTURE_USAGE.COPY_SRC
+		});
+		try {
+			const encoder = this.device.createCommandEncoder({ label: "gsw-shader-capture" });
+			this.device.queue.writeBuffer(draw.uniformBuffer, 0, draw.uniformBytes, 0, draw.uniformBytes.byteLength);
+			const pass = encoder.beginRenderPass({
+				label: "gsw-shader-draw",
+				colorAttachments: [{
+					view: target.createView(),
+					clearValue: TRANSPARENT,
+					loadOp: "clear",
+					storeOp: "store"
+				}]
+			});
+			pass.setViewport(0, 0, draw.width, draw.height, 0, 1);
+			pass.setPipeline(draw.pipeline);
+			pass.setBindGroup(0, draw.bindGroup);
+			pass.draw(4, 1);
+			pass.end();
+			this.device.queue.submit([encoder.finish()]);
+			return await draw.read(target, draw.width, draw.height);
+		} catch {
+			return null;
+		} finally {
+			target.destroy();
+		}
+	}
+	ensureEncoder() {
+		if (!this.encoder) {
+			this.encoder = this.device.createCommandEncoder({ label: "gsw-shaders" });
+			this.implicit = true;
+		}
+		return this.encoder;
+	}
+	currentView(context) {
+		try {
+			return context?.getCurrentTexture().createView() ?? null;
+		} catch {
+			return null;
+		}
+	}
+	flush() {
+		if (this.encoder && this.recorded) {
+			this.device.queue.submit([this.encoder.finish()]);
+			this.submitCount++;
+		}
+		this.encoder = null;
+		this.recorded = false;
+		this.implicit = false;
+	}
+};
+//#endregion
+//#region src/webgpu-pack-uniforms.ts
+/** A `PackedColorArray` arrives as RGBA quads even when the uniform is `vec3[]` — the same
+*  correction the WebGL path makes in `normalizeVec3ArrayUniformValues`. */
+const PACKED_COLOR_ARRAY = "PackedColorArray";
+/** Uniform-address-space arrays are strided to 16 bytes (4 floats) per element. */
+const ARRAY_STRIDE_FLOATS = 4;
+/** How many scalar components each WGSL member type holds. */
+const COMPONENTS = {
+	f32: 1,
+	i32: 1,
+	u32: 1,
+	vec2f: 2,
+	vec2i: 2,
+	vec3f: 3,
+	vec3i: 3,
+	vec4f: 4,
+	vec4i: 4
+};
+/** WGSL types written as signed INTEGERS rather than floats (an `int` uniform, and the `ivecN`s). */
+const INTEGER_TYPES = new Set([
+	"i32",
+	"vec2i",
+	"vec3i",
+	"vec4i"
+]);
+/** Allocate a staging block big enough for `sizeBytes` (rounded up to a whole float). */
+function createUniformStaging(sizeBytes) {
+	const size = Math.max(4, Math.ceil(sizeBytes / 4) * 4);
+	const bytes = new ArrayBuffer(size);
+	return {
+		bytes,
+		floats: new Float32Array(bytes),
+		ints: new Int32Array(bytes)
+	};
+}
+/**
+* Write `values` into `staging` at the byte offsets `layout` declares, and return it.
+*
+* ZEROED FIRST, deliberately: a uniform whose value disappeared between frames (a param attribute
+* dropped, a `MODULATE` that stopped applying) must read as 0, not as whatever the previous frame
+* left in that lane. The struct is small (tens of bytes) and this happens once per binding per
+* frame, so the clear is not worth optimising away for the class of bug it removes.
+*/
+function packShaderUniforms(layout, values, staging = createUniformStaging(layout.uniformStructSizeBytes)) {
+	staging.floats.fill(0);
+	const { builtinOffsets } = layout;
+	writeFloats(staging, builtinOffsets.uvFit, values.uvFit, 2);
+	writeFloats(staging, builtinOffsets.uvWindow, values.uvWindow, 4);
+	if (builtinOffsets.time !== void 0) staging.floats[builtinOffsets.time / 4] = values.time ?? 0;
+	writeFloats(staging, builtinOffsets.texturePixelSize, values.texturePixelSize, 2);
+	writeFloats(staging, builtinOffsets.modulate, values.modulate, 4);
+	writeFloats(staging, builtinOffsets.screenOrigin, values.screenOrigin, 2);
+	writeFloats(staging, builtinOffsets.screenSize, values.screenSize, 2);
+	const params = values.params ?? {};
+	for (const field of layout.uniforms) writeUniformField(staging, field, params[field.name] ?? field.default, values.paramKinds?.[field.name]);
+	return staging;
+}
+function writeUniformField(staging, field, raw, paramKind) {
+	const components = COMPONENTS[field.type];
+	if (components === void 0) return;
+	const target = INTEGER_TYPES.has(field.type) ? staging.ints : staging.floats;
+	const base = field.offsetBytes / 4;
+	if (field.arrayLength === void 0) {
+		if (components === 1) {
+			target[base] = scalarOf(raw, field.godotType);
+			return;
+		}
+		const list = Array.isArray(raw) ? raw : [];
+		for (let i = 0; i < components; i++) target[base + i] = list[i] ?? 0;
+		return;
+	}
+	const list = normalizeArrayValues(raw, field, paramKind);
+	for (let element = 0; element < field.arrayLength; element++) {
+		const slot = base + element * ARRAY_STRIDE_FLOATS;
+		for (let i = 0; i < components; i++) target[slot + i] = list[element * components + i] ?? 0;
+	}
+}
+function scalarOf(raw, godotType) {
+	const value = typeof raw === "number" ? raw : Array.isArray(raw) ? raw[0] ?? 0 : 0;
+	if (godotType === "bool") return value ? 1 : 0;
+	if (godotType === "int") return Math.round(value);
+	return value;
+}
+function normalizeArrayValues(raw, field, paramKind) {
+	const list = Array.isArray(raw) ? raw : typeof raw === "number" ? [raw] : [];
+	if (field.type === "vec3f" && paramKind === PACKED_COLOR_ARRAY && list.length % 4 === 0) {
+		const out = [];
+		for (let i = 0; i < list.length; i += 4) out.push(list[i] ?? 0, list[i + 1] ?? 0, list[i + 2] ?? 0);
+		return out;
+	}
+	return list;
+}
+function writeFloats(staging, offsetBytes, values, count) {
+	if (offsetBytes === void 0) return;
+	const base = offsetBytes / 4;
+	for (let i = 0; i < count; i++) staging.floats[base + i] = values?.[i] ?? 0;
+}
+//#endregion
+//#region src/webgpu-textures.ts
+/** Device-scoped texture allocation and upload primitives. Hosts own decoding and cache keys. */
+const WEBGPU_UPLOAD_TEXTURE_USAGE = 23;
+function createWebgpuRgbaTexture(device, width, height, label) {
+	const w = Math.max(1, Math.round(width));
+	const h = Math.max(1, Math.round(height));
+	return {
+		texture: device.createTexture({
+			label,
+			size: [
+				w,
+				h,
+				1
+			],
+			format: "rgba8unorm",
+			usage: 23
+		}),
+		width: w,
+		height: h
+	};
+}
+function uploadWebgpuRgba(device, target, pixels) {
+	device.queue.writeTexture({ texture: target.texture }, pixels, {
+		bytesPerRow: target.width * 4,
+		rowsPerImage: target.height
+	}, [target.width, target.height]);
+}
+/** Upload a host-decoded external image. The host decides its source and crop. */
+function uploadWebgpuExternalImage(device, target, source) {
+	device.queue.copyExternalImageToTexture(source, {
+		texture: target.texture,
+		premultipliedAlpha: false
+	}, [target.width, target.height]);
+}
+function createWebgpuSampler(device, opts) {
+	const filter = opts.nearest ? "nearest" : "linear";
+	const address = opts.repeat ? "repeat" : "clamp-to-edge";
+	return device.createSampler({
+		magFilter: filter,
+		minFilter: filter,
+		addressModeU: address,
+		addressModeV: address
+	});
+}
+function destroyWebgpuTexture(texture) {
+	try {
+		texture.destroy();
+	} catch {}
+}
+//#endregion
+//#region src/webgpu.ts
+/**
+* Explicit WebGPU execution entry point.
+*
+* Callers supply their device and presentation surface; this
+* package never creates a canvas, queries the DOM, fetches images, or schedules
+* animation frames.
+*/
+/** Configure a caller-supplied WebGPU presentation context for premultiplied output. */
+function configureWebgpuSurface(context, device, format) {
+	context.configure({
+		device,
+		format,
+		alphaMode: "premultiplied"
+	});
+}
+//#endregion
+export { ADDITIVE_BLEND, ADDITIVE_RESOLVE_WGSL, BUFFER_USAGE, INSTANCE_STRIDE_BYTES, PARTICLE_FS_ADDITIVE_ENTRY, PARTICLE_FS_ENTRY, PARTICLE_VERTEX_BUFFERS, PARTICLE_VS_ENTRY, PARTICLE_WGSL, PREMULTIPLIED_BLEND, RESOLVE_FS_ENTRY, RESOLVE_VS_ENTRY, SHADER_STAGE, UNIFORM_SLOT_BYTES, WEBGPU_UPLOAD_TEXTURE_USAGE, WebgpuShaderExecutor, __resetPipelineErrorForTest, __resetWebgpuParticleProgramForTest, compileModule, configureWebgpuSurface, createPipeline, createUniformRing, createUniformStaging, createWebgpuParticleRenderer, createWebgpuRgbaTexture, createWebgpuSampler, createWebgpuShaderBindGroup, createWebgpuShaderBindGroupLayout, createWebgpuShaderUniformBuffer, destroyWebgpuTexture, lastPipelineError, packShaderUniforms, peekWebgpuParticleRenderer, readTexturePixels, uniformBindGroupLayout, uploadWebgpuExternalImage, uploadWebgpuRgba };
+
+//# sourceMappingURL=webgpu.mjs.map