@driftengine/core 3.61.0

package/src/render/backend/webgpu/lightVolumePass.ts

@@ -0,0 +1,203 @@
+import { DEPTH_COMPARE } from '../../depthConvention.ts';
+import {
+  LIGHTVOLUME_BINDINGS,
+  LIGHT_VOLUME_FRAG_WGSL,
+  LIGHT_VOLUME_VERT_WGSL,
+} from '../../shaders/generated/lightVolume.wgsl.ts';
+import { vertexBufferLayouts } from './buffers.ts';
+import { DEPTH_FORMAT, type StageBindings } from './flatPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * The light-volume pass: a closed hull, and a march down the view ray inside it.
+ *
+ * The geometry decides which pixels run and nothing else, so this is an ordinary indexed mesh
+ * draw with an unusual pipeline: **additive, depth tested, depth never written, and culling
+ * chosen per draw** rather than fixed.
+ *
+ * Culling is the part that is not boilerplate. A volume seen from outside is entered at its
+ * front faces and a volume seen from inside is entered at its back ones, so which face survives
+ * is a property of where the camera stands — `resolveLightVolume` answers it, and this file
+ * turns the answer into one of two pipelines.
+ */
+
+/** Which permutation of the fragment stage: the sun-shadow lookup compiled in, or not. */
+export type LightVolumeVariant = 'none' | 'directionalShadows';
+
+export const LIGHT_VOLUME_VERT_FIELDS = LIGHTVOLUME_BINDINGS.LIGHT_VOLUME_VERT.fields;
+export const LIGHT_VOLUME_VERT_SIZE = LIGHTVOLUME_BINDINGS.LIGHT_VOLUME_VERT.uniformSize;
+
+const VERT_BINDING = LIGHTVOLUME_BINDINGS.LIGHT_VOLUME_VERT.uniforms;
+
+/*
+ * The generated file is `as const`, so indexing it by a computed key is an error until the
+ * shape is declared once. Checked against the real object rather than asserted about it, which
+ * is what `flatPass.ts` does with the sixteen flat permutations and for the same reason.
+ */
+const FRAGMENT_BINDINGS = LIGHTVOLUME_BINDINGS.lightVolumeFrag as unknown as Readonly<
+  Record<string, StageBindings>
+>;
+
+/** Everything the generator recorded about one permutation of the fragment stage. */
+export function lightVolumeFragmentBindings(variant: LightVolumeVariant): StageBindings {
+  const found = FRAGMENT_BINDINGS[variant];
+  if (found === undefined) throw new Error(`lightVolumePass: no bindings for variant "${variant}"`);
+  return found;
+}
+
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+
+/**
+ * The layout this variant binds against. **Both blocks are dynamic.**
+ *
+ * Unlike the flat pass, where the fragment block holds the lights and the fog and is settled
+ * once a frame, every field here belongs to one volume: its strength, its reach, its aperture,
+ * its own placement and the camera expressed in its own space. Two beams in a frame have
+ * nothing in common to hoist, so both blocks come out of a ring a slot at a time — see
+ * `UniformRing` for what a single buffer does to a second draw.
+ */
+export function createLightVolumeBindGroupLayout(
+  device: GPUDevice,
+  variant: LightVolumeVariant,
+): GPUBindGroupLayout {
+  const fragment = lightVolumeFragmentBindings(variant);
+  const entries: GPUBindGroupLayoutEntry[] = [
+    {
+      binding: VERT_BINDING,
+      visibility: VISIBILITY_VERTEX,
+      buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: LIGHT_VOLUME_VERT_SIZE },
+    },
+    {
+      binding: fragment.uniforms,
+      visibility: VISIBILITY_FRAGMENT,
+      buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: fragment.uniformSize },
+    },
+  ];
+
+  /*
+   * Three depth textures, declared `unfilterable-float` beside a `non-filtering` sampler, for
+   * the reason `flatPass.ts` gives: a depth format's supported sample types are
+   * `UnfilterableFloat | Depth` and never plain `Float`, so an empty `texture: {}` is rejected
+   * at bind time. It is also what this shader wants — `sunReach` takes one explicit-level tap
+   * per map and asks the hardware to blend nothing.
+   */
+  for (const texture of Object.values(fragment.textures)) {
+    entries.push({
+      binding: texture.texture,
+      visibility: VISIBILITY_FRAGMENT,
+      texture: { sampleType: 'unfilterable-float' },
+    });
+    entries.push({
+      binding: texture.sampler,
+      visibility: VISIBILITY_FRAGMENT,
+      sampler: { type: 'non-filtering' },
+    });
+  }
+  return device.createBindGroupLayout({ label: `lightVolume.layout:${variant}`, entries });
+}
+
+/**
+ * Bind the two rings and one view per declared map.
+ *
+ * `resolve` is asked by the shader's own name for each map, so the caller supplies what it has
+ * and a stand-in for the rest. **The stand-in has to read as unoccluded, not as absent**: the
+ * dynamic layer is sampled unconditionally, and `occlusion()` calls any stored depth below the
+ * receiver's a blocker — so a stand-in of zero would put the whole beam in shadow, which is a
+ * picture rather than an error. A white one-pixel texture is depth 1, the far plane, nothing in
+ * the way. `emptyTexture.ts` is the same value on the other backend for the same reason.
+ */
+export function createLightVolumeBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  variant: LightVolumeVariant,
+  vertices: GPUBuffer,
+  fragments: GPUBuffer,
+  resolve: (name: string) => { view: GPUTextureView; sampler: GPUSampler },
+): GPUBindGroup {
+  const fragment = lightVolumeFragmentBindings(variant);
+  const entries: GPUBindGroupEntry[] = [
+    { binding: VERT_BINDING, resource: { buffer: vertices, size: LIGHT_VOLUME_VERT_SIZE } },
+    {
+      binding: fragment.uniforms,
+      resource: { buffer: fragments, size: fragment.uniformSize },
+    },
+  ];
+  for (const [name, texture] of Object.entries(fragment.textures)) {
+    const supplied = resolve(name);
+    entries.push({ binding: texture.texture, resource: supplied.view });
+    entries.push({ binding: texture.sampler, resource: supplied.sampler });
+  }
+  return device.createBindGroup({
+    label: `lightVolume.bindGroup:${variant}`,
+    layout,
+    entries,
+  });
+}
+
+/**
+ * The pipeline for one variant and one side of the hull.
+ *
+ * **`src-alpha, one`, which is `gl.blendFunc(SRC_ALPHA, ONE)` and the whole reason this pass
+ * exists.** Alpha blending moves what is behind a surface *toward* it, so an unlit beam drawn
+ * that way comes out darker than the sky and sweeps a solid dark wedge across the frame; see
+ * the history at the top of `shaders/lightVolume.ts`. The shader puts its energy in the colour
+ * and leaves alpha at 1, because a blend that multiplies by alpha squares anything written to
+ * both.
+ *
+ * The alpha channel is left as it was rather than accumulated, which differs from the GL call
+ * — `blendFunc` sets both channels — and is invisible here because the swap chain is
+ * configured `alphaMode: 'opaque'` and the composited alpha is discarded. It would stop being
+ * invisible the day a consumer wants the canvas composited against the page behind it, and
+ * that is the line to change.
+ *
+ * **Depth tested, never written.** A beam passes behind whatever stands in front of it, and
+ * occludes nothing itself: a volume of light is not a surface.
+ */
+export function lightVolumePipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  variant: LightVolumeVariant,
+  cullMode: GPUCullMode,
+  present: Readonly<Record<string, boolean>>,
+  key: string,
+): GPURenderPipeline {
+  return cache.get(key, () => ({
+    label: key,
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: {
+      module: shaderModule(device, {
+        label: 'lightVolume.vert',
+        code: LIGHT_VOLUME_VERT_WGSL,
+      }),
+      entryPoint: 'main',
+      /*
+       * The mesh's own interleaved layout, not a four-attribute one. This shader reads
+       * locations 0 to 3, and the pipeline still has to describe every buffer the draw sets —
+       * the depth pass has the same shape with one attribute.
+       */
+      buffers: vertexBufferLayouts(present),
+    },
+    fragment: {
+      module: shaderModule(device, {
+        label: `lightVolume.frag:${variant}`,
+        code: LIGHT_VOLUME_FRAG_WGSL[variant] ?? '',
+      }),
+      entryPoint: 'main',
+      targets: [
+        {
+          format: cache.format,
+          blend: {
+            color: { srcFactor: 'src-alpha', dstFactor: 'one', operation: 'add' },
+            alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+          },
+        },
+      ],
+    },
+    primitive: { topology: 'triangle-list', cullMode },
+    multisample: { count: cache.sampleCount },
+    depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+  }));
+}

package/src/render/backend/webgpu/linePass.ts

@@ -0,0 +1,270 @@
+import { DEPTH_COMPARE } from '../../depthConvention.ts';
+import {
+  LINE_BINDINGS,
+  LINE_FRAG_WGSL,
+  LINE_VERT_WGSL,
+} from '../../shaders/generated/line.wgsl.ts';
+import { buildSegmentQuads } from '../../segmentQuads.ts';
+import type { LineSegments } from '../../linePoints.ts';
+import type { UniformFields } from './scatterPass.ts';
+import { DEPTH_FORMAT } from './flatPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * The line pass: a polyline with a real width, four vertices a segment.
+ *
+ * **The plain sibling of `boltPass.ts`, sharing its quad and nothing after that.** Both turn a
+ * segment into a camera-facing quad from `segmentQuads.ts`, because neither filament has a
+ * thickness to see around; a bolt is additive light with no model transform and a line is a
+ * fogged, alpha-blended thing in the world that moves with whatever it is attached to, hence
+ * the extra `uModel` field `LINE_VERT` carries and `BOLT_VERT` does not.
+ *
+ * The per-frame streams are two positions, not bolt's five — no `along`/`fade`/`seed`/
+ * `brightness` to carry, because a line has no envelope. `expandLineSegments` is written here
+ * rather than folded into `expandBoltSegments` in `segmentQuads.ts`, for the reason
+ * `lineBatch.ts` gives on the WebGL2 side: teaching that function a `LineSegments` shape too
+ * would grow a union coupling two renderers that share only a quad.
+ *
+ * **Uniforms are a `UniformRing`, one slot a draw, not a single block like `boltPass.ts`'s.**
+ * A bolt pool is drawn once a frame in every scene that has shipped so far, so a single block
+ * happened to be safe there; a polyline is exactly the shape `uniformRing.ts`'s own comment
+ * warns about — a waveform, several trails, a plotted curve, all in one frame — and
+ * `queue.writeBuffer` does not interleave with recorded draw commands, so a single block
+ * written more than once in a frame gives *every* draw that frame the last write. Found on
+ * this page's own demo, which draws seven polylines a frame: every stroke rendered at the last
+ * one's transform, colour and width, which on WebGPU alone put every shape at the last draw's
+ * position and looked exactly like nothing had rendered rather than like a transform bug — see
+ * `drawLines` in `webgpu/renderer.ts`.
+ */
+
+export const LINE_VERT_FIELDS: UniformFields = LINE_BINDINGS.LINE_VERT.fields;
+export const LINE_VERT_SIZE = LINE_BINDINGS.LINE_VERT.uniformSize;
+export const LINE_FRAG_FIELDS: UniformFields = LINE_BINDINGS.LINE_FRAG.fields;
+export const LINE_FRAG_SIZE = LINE_BINDINGS.LINE_FRAG.uniformSize;
+
+const VERT_BINDING = LINE_BINDINGS.LINE_VERT.uniforms;
+const FRAG_BINDING = LINE_BINDINGS.LINE_FRAG.uniforms;
+
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008; // VERTEX | COPY_DST
+const USAGE_INDEX = 0x0010 | 0x0008; // INDEX | COPY_DST
+
+/** A polyline batch on the device, behind the surface's opaque handle. */
+export interface GpuLines {
+  readonly fromBuffer: GPUBuffer;
+  readonly toBuffer: GPUBuffer;
+  readonly corners: GPUBuffer;
+  readonly indices: GPUBuffer;
+  readonly capacity: number;
+  /** Staging, expanded from the segment list's per-segment arrays to per-vertex ones. */
+  readonly from: Float32Array;
+  readonly to: Float32Array;
+  dispose(): void;
+}
+
+export function createGpuLines(device: GPUDevice, capacity: number, label: string): GpuLines {
+  const verts = capacity * 4;
+  const geometry = buildSegmentQuads(capacity);
+
+  const dynamic = (floats: number, name: string): GPUBuffer =>
+    device.createBuffer({
+      label: `${label}.${name}`,
+      size: Math.max(4, floats * 4),
+      usage: USAGE_VERTEX,
+    });
+
+  const fromBuffer = dynamic(verts * 3, 'from');
+  const toBuffer = dynamic(verts * 3, 'to');
+
+  const corners = device.createBuffer({
+    label: `${label}.corners`,
+    size: Math.max(4, geometry.corners.byteLength),
+    usage: USAGE_VERTEX,
+  });
+  device.queue.writeBuffer(corners, 0, geometry.corners);
+
+  const indices = device.createBuffer({
+    label: `${label}.indices`,
+    size: Math.max(4, geometry.indices.byteLength),
+    usage: USAGE_INDEX,
+  });
+  device.queue.writeBuffer(indices, 0, geometry.indices);
+
+  return {
+    fromBuffer,
+    toBuffer,
+    corners,
+    indices,
+    capacity,
+    from: new Float32Array(verts * 3),
+    to: new Float32Array(verts * 3),
+    dispose(): void {
+      fromBuffer.destroy();
+      toBuffer.destroy();
+      corners.destroy();
+      indices.destroy();
+    },
+  };
+}
+
+/**
+ * Expand this frame's segments to their four vertices each, into arrays the caller owns.
+ *
+ * Returns how many segments were written, which is the list's count clamped to the batch's
+ * capacity — a caller that overruns loses its tail rather than its frame, the same rule
+ * `expandBoltSegments` follows. Reads only `LineSegments.from`/`.to`, the same walk `lineBatch.ts`
+ * writes inline in `upload()` on the WebGL2 side.
+ */
+export function expandLineSegments(
+  data: LineSegments,
+  capacity: number,
+  from: Float32Array,
+  to: Float32Array,
+): number {
+  const count = Math.min(data.count, capacity);
+  for (let s = 0; s < count; s++) {
+    const fx = data.from[s * 3] as number;
+    const fy = data.from[s * 3 + 1] as number;
+    const fz = data.from[s * 3 + 2] as number;
+    const tx = data.to[s * 3] as number;
+    const ty = data.to[s * 3 + 1] as number;
+    const tz = data.to[s * 3 + 2] as number;
+    for (let c = 0; c < 4; c++) {
+      const v = s * 4 + c;
+      from[v * 3] = fx;
+      from[v * 3 + 1] = fy;
+      from[v * 3 + 2] = fz;
+      to[v * 3] = tx;
+      to[v * 3 + 1] = ty;
+      to[v * 3 + 2] = tz;
+    }
+  }
+  return count;
+}
+
+/** `aFrom`, `aTo`, `aCorner` — one buffer each, at the locations `line.ts` declares. No fourth
+ * dynamic attribute: unlike a bolt, a line carries no envelope. */
+export function lineVertexLayouts(): GPUVertexBufferLayout[] {
+  return [
+    {
+      arrayStride: 12,
+      attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' as GPUVertexFormat }],
+    },
+    {
+      arrayStride: 12,
+      attributes: [{ shaderLocation: 1, offset: 0, format: 'float32x3' as GPUVertexFormat }],
+    },
+    {
+      arrayStride: 8,
+      attributes: [{ shaderLocation: 2, offset: 0, format: 'float32x2' as GPUVertexFormat }],
+    },
+  ];
+}
+
+/**
+ * `hasDynamicOffset: true` on both bindings, which the ring needs for the reason this file's own
+ * top comment gives.
+ *
+ * **This used to say "unlike `boltPass.ts`", and that stopped being true on 2026-09-02** when
+ * bolts, caustics, the flock and the wind streaks all gained rings of their own. A comment naming
+ * a neighbour's shortcoming is a comment that goes stale when the neighbour is fixed.
+ */
+export function createLineBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+  return device.createBindGroupLayout({
+    label: 'line.layout',
+    entries: [
+      {
+        binding: VERT_BINDING,
+        visibility: VISIBILITY_VERTEX,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: LINE_VERT_SIZE },
+      },
+      {
+        binding: FRAG_BINDING,
+        visibility: VISIBILITY_FRAGMENT,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: LINE_FRAG_SIZE },
+      },
+    ],
+  });
+}
+
+/** Bound once against the ring's two buffers; every draw supplies its own dynamic offset. */
+export function createLineBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  vertices: GPUBuffer,
+  fragments: GPUBuffer,
+): GPUBindGroup {
+  return device.createBindGroup({
+    label: 'line.bindGroup',
+    layout,
+    entries: [
+      { binding: VERT_BINDING, resource: { buffer: vertices, size: LINE_VERT_SIZE } },
+      { binding: FRAG_BINDING, resource: { buffer: fragments, size: LINE_FRAG_SIZE } },
+    ],
+  });
+}
+
+/**
+ * The pipeline.
+ *
+ * **Alpha blended, depth tested, depth not written, nothing culled.** Alpha rather than
+ * `boltPipeline`'s additive, matching `LineBatch.drawTo`'s WebGL2 state exactly: a line occludes
+ * in colour but must not punch a hole in the depth buffer from its own soft antialiased edge,
+ * the same discipline the SDF text pass follows. Nothing culled for the reason `lineBatch.ts`
+ * gives: the quad billboards toward the view the same way a bolt's does, so its winding can flip
+ * with the camera angle.
+ */
+export function linePipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  /**
+   * Whether this stroke is *light arriving* rather than a thing in the world.
+   *
+   * **A second pipeline rather than a second verb, and it does not make a line a bolt.** Blending
+   * is pipeline state on this backend, so an additive stroke is a variant with its own cache key —
+   * the same arrangement `depthWrite` already has for a translucent mesh. What it is not is a mode
+   * flag turning `drawLines` into `drawBolts`: a bolt jitters along its own path because it is
+   * lightning, which is a fact about geometry that nothing here touches.
+   */
+  additive = false,
+): GPURenderPipeline {
+  return cache.get(additive ? 'line:additive' : 'line', () => ({
+    label: additive ? 'line.additive' : 'line',
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: {
+      module: shaderModule(device, { label: 'line.vert', code: LINE_VERT_WGSL }),
+      entryPoint: 'main',
+      buffers: lineVertexLayouts(),
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'line.frag', code: LINE_FRAG_WGSL }),
+      entryPoint: 'main',
+      targets: [
+        {
+          format: cache.format,
+          /* The additive arm is `boltPass`'s exactly, because it is the same statement about the
+             same kind of thing: light adds to what is behind it and never covers it. */
+          blend: additive
+            ? {
+                color: { srcFactor: 'src-alpha', dstFactor: 'one', operation: 'add' },
+                alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+              }
+            : {
+                color: {
+                  srcFactor: 'src-alpha',
+                  dstFactor: 'one-minus-src-alpha',
+                  operation: 'add',
+                },
+                alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+              },
+        },
+      ],
+    },
+    primitive: { topology: 'triangle-list', cullMode: 'none' },
+    multisample: { count: cache.sampleCount },
+    depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+  }));
+}

package/src/render/backend/webgpu/morphTexture.ts

@@ -0,0 +1,61 @@
+import { morphTextureRows, morphTextureWidth } from '../../skinPalette.ts';
+
+/**
+ * A mesh's morph deltas as an `rgba32float` texture, on WebGPU.
+ *
+ * The twin of the WebGL2 module of this name, and **`rgba` where that one is `rgb`**: WebGPU has
+ * no three-channel float format at all, so the fourth channel is padding the shader ignores. That
+ * is a quarter of the texture holding nothing, and it is the format list rather than a choice —
+ * naming it here so the difference between the two files is not read as an oversight.
+ */
+export class MorphTexture {
+  private texture: GPUTexture | null = null;
+  private cachedView: GPUTextureView | null = null;
+  readonly width: number;
+  readonly rows: number;
+  readonly targetCount: number;
+
+  constructor(device: GPUDevice, deltas: Float32Array, vertices: number, targets: number) {
+    this.targetCount = targets;
+    this.width = morphTextureWidth(vertices, targets);
+    this.rows = morphTextureRows(vertices, targets);
+
+    this.texture = device.createTexture({
+      label: `morph.deltas:${targets}x${vertices}`,
+      size: { width: this.width, height: this.rows },
+      format: 'rgba32float',
+      usage: TEXTURE_USAGE.TEXTURE_BINDING | TEXTURE_USAGE.COPY_DST,
+    });
+
+    /* Three floats a delta widened to four, and padded to the full rectangle for the reason the
+       WebGL2 twin gives: a short last row is what an upload walks off the end of. */
+    const padded = new Float32Array(this.width * this.rows * 4);
+    const count = Math.min(deltas.length / 3, this.width * this.rows);
+    for (let i = 0; i < count; i++) {
+      padded[i * 4] = deltas[i * 3] as number;
+      padded[i * 4 + 1] = deltas[i * 3 + 1] as number;
+      padded[i * 4 + 2] = deltas[i * 3 + 2] as number;
+    }
+    device.queue.writeTexture(
+      { texture: this.texture },
+      padded,
+      { bytesPerRow: this.width * 16, rowsPerImage: this.rows },
+      { width: this.width, height: this.rows },
+    );
+  }
+
+  view(): GPUTextureView | null {
+    if (this.texture === null) return null;
+    if (this.cachedView === null) this.cachedView = this.texture.createView();
+    return this.cachedView;
+  }
+
+  dispose(): void {
+    this.texture?.destroy();
+    this.texture = null;
+    this.cachedView = null;
+  }
+}
+
+/* Spelled out, because the global is not in the TypeScript lib this package compiles against. */
+const TEXTURE_USAGE = { COPY_DST: 0x02, TEXTURE_BINDING: 0x04 } as const;

package/src/render/backend/webgpu/panelPass.ts

@@ -0,0 +1,138 @@
+import {
+  PANEL_BINDINGS,
+  PANEL_FRAG_WGSL,
+  PANEL_VERT_WGSL,
+} from '../../shaders/generated/panel.wgsl.ts';
+import type { UniformFields } from './scatterPass.ts';
+import { DEPTH_FORMAT } from './flatPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * The panel pass: two triangles in screen space, one colour, one alpha.
+ *
+ * The plain surface an overlay is read against — what `renderer.ts` says about `fillPanel`
+ * applies here unchanged, including why neither `beginInset` nor a plate of glyph cubes can
+ * stand in for it.
+ *
+ * **The corners are a vertex buffer rather than `vertex_index` arithmetic**, because the GLSL
+ * is the source of truth and it declares `aCorner`. Six vertices, uploaded once.
+ */
+
+export const PANEL_VERT_FIELDS: UniformFields = PANEL_BINDINGS.PANEL_VERT.fields;
+export const PANEL_VERT_SIZE = PANEL_BINDINGS.PANEL_VERT.uniformSize;
+export const PANEL_FRAG_FIELDS: UniformFields = PANEL_BINDINGS.PANEL_FRAG.fields;
+export const PANEL_FRAG_SIZE = PANEL_BINDINGS.PANEL_FRAG.uniformSize;
+
+const VERT_BINDING = PANEL_BINDINGS.PANEL_VERT.uniforms;
+const FRAG_BINDING = PANEL_BINDINGS.PANEL_FRAG.uniforms;
+
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008; // VERTEX | COPY_DST
+
+/** The unit quad, as two triangles. The rect and the viewport turn it into pixels. */
+const CORNERS = new Float32Array([0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1]);
+export const PANEL_VERTEX_COUNT = CORNERS.length / 2;
+
+export function createPanelCorners(device: GPUDevice): GPUBuffer {
+  const buffer = device.createBuffer({
+    label: 'panel.corners',
+    size: CORNERS.byteLength,
+    usage: USAGE_VERTEX,
+  });
+  device.queue.writeBuffer(buffer, 0, CORNERS);
+  return buffer;
+}
+
+export function createPanelBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+  return device.createBindGroupLayout({
+    label: 'panel.layout',
+    entries: [
+      {
+        binding: VERT_BINDING,
+        visibility: VISIBILITY_VERTEX,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: PANEL_VERT_SIZE },
+      },
+      {
+        binding: FRAG_BINDING,
+        visibility: VISIBILITY_FRAGMENT,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: PANEL_FRAG_SIZE },
+      },
+    ],
+  });
+}
+
+/**
+ * Bound once against both rings, and addressed by dynamic offset per panel.
+ *
+ * **A ring rather than one buffer, because a frame draws more than one.** The loader alone
+ * draws a track and a fill, and `queue.writeBuffer` does not interleave with recorded commands
+ * — so a single block written twice would give both panels the second colour. That is the bug
+ * that left a flame leaning forty degrees in still air, one pass higher up.
+ */
+export function createPanelBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  vertices: GPUBuffer,
+  fragments: GPUBuffer,
+): GPUBindGroup {
+  return device.createBindGroup({
+    label: 'panel.bindGroup',
+    layout,
+    entries: [
+      { binding: VERT_BINDING, resource: { buffer: vertices, size: PANEL_VERT_SIZE } },
+      { binding: FRAG_BINDING, resource: { buffer: fragments, size: PANEL_FRAG_SIZE } },
+    ],
+  });
+}
+
+/**
+ * The pipeline.
+ *
+ * **Nothing culled, nothing depth-tested, nothing written to depth.** This is furniture drawn
+ * over a finished frame: it must neither be occluded by the scene nor occlude what comes after
+ * it. `renderer.ts` disables all three by hand for the same draw, and records that leaving
+ * culling on drew nothing at all, silently — a screen-space quad has no meaningful facing.
+ */
+export function panelPipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+): GPURenderPipeline {
+  return cache.get('panel', () => ({
+    label: 'panel',
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: {
+      module: shaderModule(device, { label: 'panel.vert', code: PANEL_VERT_WGSL }),
+      entryPoint: 'main',
+      buffers: [
+        {
+          arrayStride: 8,
+          attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x2' as GPUVertexFormat }],
+        },
+      ],
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'panel.frag', code: PANEL_FRAG_WGSL }),
+      entryPoint: 'main',
+      targets: [
+        {
+          format: cache.format,
+          blend: {
+            color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+          },
+        },
+      ],
+    },
+    primitive: { topology: 'triangle-list', cullMode: 'none' },
+    multisample: { count: cache.sampleCount },
+    /*
+     * `always` is how a WebGPU pipeline says what `gl.disable(DEPTH_TEST)` says. The attachment
+     * is still declared because the frame's pass has one, and a pipeline that omits it cannot
+     * be used in a pass that has one.
+     */
+    depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: 'always' },
+  }));
+}