@woosh/meep-engine 3.14.2 → 3.14.4

package/src/shade/playground/skinned_mesh_soup/verify_clone_vertices.js

@@ -0,0 +1,409 @@
+/**
+ * Read a clone's deformed vertex region back and hold it against an answer the CPU knows.
+ *
+ * The page can be looked at, and soup is not subtle. What looking at it cannot say is *which*
+ * vertices went wrong and in what pattern, and that is the whole difference between "skinning is
+ * broken" and a bug you can name: every vertex past the 64th of its meshlet is the workgroup stride
+ * loop, every vertex of some meshlets and none of others is the per-meshlet addressing, a scatter
+ * with no pattern is the joint palette.
+ *
+ * This runs in the **bind pose** — `?skin=bind`, no clip registered — because that is the one pose
+ * whose answer needs no GPU. At bind, `joint.global × inverse_bind` is the identity for every joint
+ * (verified on the CPU for Michelle: every one of her 19 106 vertices lands back on its rest
+ * position to the bit), so the blend collapses whatever the weights are and the shader's output is
+ * just its input under the mesh-local fold:
+ *
+ * ```
+ * clone_position = inverse(mesh.transform_global) × source_position
+ * ```
+ *
+ * — the leftmost factor of the glTF skinning formula, which `chunk_skin_blend_mesh_local` folds
+ * into each joint matrix so the rasterizer can re-apply `mesh.global` afterwards. Nothing about
+ * that expression involves the pose, so a disagreement here is the skinning *machinery* — the
+ * addressing, the layout, the matrix range — and not the animation.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+import { assert } from "../../../core/assert.js";
+import {
+    MESHLET_METADATA_STRUCT
+} from "../../renderer/geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import {
+    GEOMETRY_METADATA_STRUCT
+} from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
+
+/**
+ * Copy a slice of a GPU buffer back to the CPU.
+ *
+ * @param {GPUDevice} device
+ * @param {GPUBuffer} buffer
+ * @param {number} offset in bytes, a multiple of 4
+ * @param {number} size in bytes, a multiple of 4
+ * @returns {Promise<ArrayBuffer>}
+ */
+async function read_back(device, buffer, offset, size) {
+    const staging = device.createBuffer({
+        label: 'soup/readback',
+        size,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+
+    const encoder = device.createCommandEncoder({ label: 'soup/readback' });
+
+    encoder.copyBufferToBuffer(buffer, offset, staging, 0, size);
+
+    device.queue.submit([encoder.finish()]);
+
+    await staging.mapAsync(GPUMapMode.READ);
+
+    const copy = staging.getMappedRange().slice(0);
+
+    staging.unmap();
+    staging.destroy();
+
+    return copy;
+}
+
+/**
+ * Transform a point by a column-major 4×4.
+ *
+ * @param {ArrayLike<number>} m
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number[]}
+ */
+function transform_point(m, x, y, z) {
+    return [
+        m[0] * x + m[4] * y + m[8] * z + m[12],
+        m[1] * x + m[5] * y + m[9] * z + m[13],
+        m[2] * x + m[6] * y + m[10] * z + m[14],
+    ];
+}
+
+/**
+ * Invert a column-major 4×4 that is an affine transform — which every node transform in this engine
+ * is. General enough for a `T · R · S` with non-uniform scale, and not for a projection.
+ *
+ * @param {ArrayLike<number>} m
+ * @returns {Float64Array}
+ */
+function affine_inverse(m) {
+    const a = m[0], b = m[4], c = m[8];
+    const d = m[1], e = m[5], f = m[9];
+    const g = m[2], h = m[6], i = m[10];
+
+    const det = a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g);
+
+    assert.notEqual(det, 0, 'transform is singular');
+
+    const s = 1 / det;
+
+    const r = new Float64Array(16);
+
+    r[0] = (e * i - f * h) * s;
+    r[1] = (f * g - d * i) * s;
+    r[2] = (d * h - e * g) * s;
+
+    r[4] = (c * h - b * i) * s;
+    r[5] = (a * i - c * g) * s;
+    r[6] = (b * g - a * h) * s;
+
+    r[8] = (b * f - c * e) * s;
+    r[9] = (c * d - a * f) * s;
+    r[10] = (a * e - b * d) * s;
+
+    const tx = m[12], ty = m[13], tz = m[14];
+
+    r[12] = -(r[0] * tx + r[4] * ty + r[8] * tz);
+    r[13] = -(r[1] * tx + r[5] * ty + r[9] * tz);
+    r[14] = -(r[2] * tx + r[6] * ty + r[10] * tz);
+
+    r[15] = 1;
+
+    return r;
+}
+
+/**
+ * Contiguous runs of a sorted list of integers, as `[first, last]` pairs.
+ *
+ * @param {number[]} values
+ * @returns {number[][]}
+ */
+function runs_of(values) {
+    const runs = [];
+
+    for (const value of values) {
+        const last = runs[runs.length - 1];
+
+        if (last !== undefined && last[1] === value - 1) {
+            last[1] = value;
+        } else {
+            runs.push([value, value]);
+        }
+    }
+
+    return runs;
+}
+
+/**
+ * The clone's deformed vertices, against `inverse(mesh.global) × rest`.
+ *
+ * Reads the GPU's own answer to "where does this geometry id's data live" rather than reconstructing
+ * it from the host records: the geometry metadata row, then the clone's meshlet metadata rows, then
+ * the data those rows address. That is the same chain the rasterizer and the intersector walk, so a
+ * clone whose *addressing* is wrong is caught here rather than being read around.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {Scene} options.scene
+ * @param {SkinnedMesh} options.mesh
+ * @param {number} [options.tolerance] in mesh-local units — the space the clone is written in,
+ *        which for a glTF character carrying a centimetre scale is a hundred times its world size
+ * @returns {Promise<object>}
+ */
+export async function verify_clone_vertices({ renderer, scene, mesh, tolerance = 1e-3 }) {
+    assert.defined(mesh, 'mesh');
+    assert.equal(mesh.isSkinnedMesh, true, 'mesh.isSkinnedMesh !== true');
+
+    const graphics = renderer.graphics;
+    const device = graphics.device;
+    const geometries = graphics.geometries;
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    const geometry_index = scene_context.skinning.obtain_geometry_index(mesh);
+
+    // ---- where the clone's meshlets are, as the GPU has it -------------------------------------
+
+    const geometry_row = new DataView(await read_back(
+        device,
+        geometries.buffer_metadata,
+        geometry_index * GEOMETRY_METADATA_STRUCT.size,
+        GEOMETRY_METADATA_STRUCT.size
+    ));
+
+    const meshlets_address = geometry_row.getUint32(
+        GEOMETRY_METADATA_STRUCT.get('meshlets_address').offset, true
+    );
+    const meshlets_count = geometry_row.getUint32(
+        GEOMETRY_METADATA_STRUCT.get('meshlets_count').offset, true
+    );
+
+    const source_batch = mesh.geometry.meshlets;
+
+    if (meshlets_count !== source_batch.count) {
+        return {
+            geometry_index,
+            verdict: `FAIL — the clone's geometry row claims ${meshlets_count} meshlets, `
+                + `its source has ${source_batch.count}`,
+        };
+    }
+
+    const meshlet_stride = MESHLET_METADATA_STRUCT.aligned_size;
+
+    const clone_metadata = new DataView(await read_back(
+        device,
+        geometries.meshlets.buffer_metadata,
+        meshlets_address * meshlet_stride,
+        meshlets_count * meshlet_stride
+    ));
+
+    const ADDRESS_OFFSET = MESHLET_METADATA_STRUCT.get('address').offset;
+    const VERTEX_COUNT_OFFSET = MESHLET_METADATA_STRUCT.get('vertex_count').offset;
+    const PRIMITIVE_COUNT_OFFSET = MESHLET_METADATA_STRUCT.get('primitive_count').offset;
+
+    // ---- and where the source's are, to say the clone is somewhere else --------------------------
+
+    /*
+     A clone is a fresh vertex region plus a patch pass that adds `clone.data.offset -
+     source.data.offset` to every one of its meshlet records. If that patch does not land, the
+     clone's records still address the *source's* data: the skinning pass then deforms the shared
+     rest-pose vertices in place, every instance of the model deforms on top of every other, and the
+     source no rasterizer ever wanted deformed goes with them. The addresses differing by one
+     constant is the whole contract, and it is checkable before a single vertex is compared.
+    */
+    const source_record = geometries.get_metadata(mesh.geometry);
+
+    const source_metadata = new DataView(await read_back(
+        device,
+        geometries.meshlets.buffer_metadata,
+        source_record.meshlets.metadata.offset * meshlet_stride,
+        meshlets_count * meshlet_stride
+    ));
+
+    // ---- the clone's vertex data, in one read ---------------------------------------------------
+
+    /*
+     Position is the first attribute of the section and is never collapsed to a shared slot (see
+     ENCODED_ORDERED_ATTRIBUTES and MESHLET_ATTRIBUTE_COMPRESSION_FLAGS), so a meshlet's positions
+     start where its attribute section does and the furthest word this needs is the last position
+     word of the furthest meshlet. That is a span, not a set of holes, so it comes back in one copy
+     rather than in `meshlets_count` of them — two hundred round trips through `mapAsync` is a
+     diagnostic nobody runs twice.
+    */
+    const position_word_of = new Uint32Array(meshlets_count);
+
+    let data_low = Infinity;
+    let data_high = 0;
+
+    /** every distinct `clone address − source address`; one entry is the contract */
+    const address_deltas = new Set();
+
+    for (let m = 0; m < meshlets_count; m++) {
+        const row = m * meshlet_stride;
+
+        const address = clone_metadata.getUint32(row + ADDRESS_OFFSET, true);
+        const primitive_count = clone_metadata.getUint32(row + PRIMITIVE_COUNT_OFFSET, true);
+        const vertex_count = clone_metadata.getUint32(row + VERTEX_COUNT_OFFSET, true);
+
+        address_deltas.add(address - source_metadata.getUint32(row + ADDRESS_OFFSET, true));
+
+        const position_word = address + ((primitive_count * 3 + 3) >> 2);
+
+        position_word_of[m] = position_word;
+
+        data_low = Math.min(data_low, position_word);
+        data_high = Math.max(data_high, position_word + vertex_count * 3);
+    }
+
+    if (address_deltas.size !== 1 || address_deltas.has(0)) {
+        return {
+            geometry_index,
+            address_deltas: [...address_deltas].slice(0, 8),
+            verdict: address_deltas.has(0) && address_deltas.size === 1
+                ? `FAIL — every one of the clone's ${meshlets_count} meshlet records addresses the `
+                    + `source's vertex data. The address patch did not run, so the skinning pass is `
+                    + `deforming the shared rest-pose region in place.`
+                : `FAIL — the clone's meshlet records sit at ${address_deltas.size} different `
+                    + `offsets from the source's; a clone is one contiguous region and its patch is `
+                    + `one delta.`,
+        };
+    }
+
+    const data = new Float32Array(await read_back(
+        device,
+        geometries.meshlets.buffer_data,
+        data_low * 4,
+        (data_high - data_low) * 4
+    ));
+
+    // ---- the answer the CPU knows ---------------------------------------------------------------
+
+    const to_mesh_local = affine_inverse(mesh.transform_global.matrix);
+
+    // ---- and the comparison ---------------------------------------------------------------------
+
+    let vertices = 0;
+    let wrong = 0;
+    let worst = 0;
+    let worst_where = null;
+
+    /** meshlets with at least one wrong vertex */
+    const wrong_meshlets = [];
+
+    /** per-vertex-slot tally: how many meshlets got slot `v` wrong */
+    const wrong_by_slot = new Map();
+
+    const examples = [];
+
+    for (let m = 0; m < meshlets_count; m++) {
+        const source_header = source_batch.read_header(m);
+        const source = source_batch.read_meshlet(m);
+
+        const row = m * meshlet_stride;
+
+        const clone_vertex_count = clone_metadata.getUint32(row + VERTEX_COUNT_OFFSET, true);
+        const clone_primitive_count = clone_metadata.getUint32(row + PRIMITIVE_COUNT_OFFSET, true);
+
+        if (clone_vertex_count !== source_header.vertex_count
+            || clone_primitive_count !== source_header.primitive_count) {
+            return {
+                geometry_index,
+                verdict: `FAIL — clone meshlet ${m} says `
+                    + `${clone_vertex_count} vertices / ${clone_primitive_count} triangles, `
+                    + `its source says ${source_header.vertex_count} / ${source_header.primitive_count}. `
+                    + `The metadata copy or its address patch is wrong, before any skinning ran.`,
+            };
+        }
+
+        const positions = data.subarray(
+            position_word_of[m] - data_low,
+            position_word_of[m] - data_low + clone_vertex_count * 3
+        );
+
+        let meshlet_wrong = 0;
+
+        for (let v = 0; v < clone_vertex_count; v++) {
+            vertices++;
+
+            const expected = transform_point(
+                to_mesh_local,
+                source.attribute_position[v * 3],
+                source.attribute_position[v * 3 + 1],
+                source.attribute_position[v * 3 + 2],
+            );
+
+            const error = Math.max(
+                Math.abs(positions[v * 3] - expected[0]),
+                Math.abs(positions[v * 3 + 1] - expected[1]),
+                Math.abs(positions[v * 3 + 2] - expected[2]),
+            );
+
+            if (error > worst) {
+                worst = error;
+                worst_where = { meshlet: m, vertex: v };
+            }
+
+            if (error > tolerance) {
+                wrong++;
+                meshlet_wrong++;
+
+                wrong_by_slot.set(v, (wrong_by_slot.get(v) ?? 0) + 1);
+
+                if (examples.length < 8) {
+                    examples.push({
+                        meshlet: m,
+                        vertex: v,
+                        got: [positions[v * 3], positions[v * 3 + 1], positions[v * 3 + 2]],
+                        expected,
+                    });
+                }
+            }
+        }
+
+        if (meshlet_wrong > 0) {
+            wrong_meshlets.push(m);
+        }
+    }
+
+    // The two shapes worth telling apart, named rather than left to be read out of the runs: a
+    // stride-loop bug wrongs every slot at or past the workgroup size and nothing below it, and an
+    // addressing bug wrongs whole meshlets.
+    const slots = [...wrong_by_slot.keys()].sort((a, b) => a - b);
+
+    const lowest_wrong_slot = slots.length > 0 ? slots[0] : null;
+
+    return {
+        geometry_index,
+        meshlets: meshlets_count,
+        address_delta: [...address_deltas][0],
+        vertices,
+        wrong,
+        worst,
+        worst_where,
+        wrong_meshlets: wrong_meshlets.length,
+        wrong_meshlet_runs: runs_of(wrong_meshlets).slice(0, 20),
+        lowest_wrong_slot,
+        highest_correct_slot: slots.length > 0 ? lowest_wrong_slot - 1 : null,
+        wrong_slot_runs: runs_of(slots).slice(0, 20),
+        examples,
+        verdict: wrong === 0
+            ? `pass — all ${vertices} of the clone's vertices are the bind pose, worst error ${worst}`
+            : `FAIL — ${wrong} of ${vertices} vertices in ${wrong_meshlets.length} of `
+                + `${meshlets_count} meshlets are not the bind pose (worst ${worst}); `
+                + `lowest wrong vertex slot ${lowest_wrong_slot}`,
+    };
+}

package/src/shade/playground/texture_encode/README.md

@@ -0,0 +1,109 @@
+# GPU block encoder
+
+A sampleable texture in, a block-compressed texture out, on the device — the runtime compression of
+the compressed-texture plan's §4.5, driven here on real hardware.
+
+This is tier 8 of the plan's testing ladder for the encoder, and the only tier with a GPU in it.
+Everything below runs device-free: the encoder chunk in the WGSL emulator against an exhaustive
+optimum, the whole kernel in the emulator against the chunk, the orchestration on the software
+device with its copies executing over host-written bytes. What none of that can answer is whether a
+real device takes the format and the padded rows, whether the texture ends up holding the blocks the
+shader wrote, and whether the hardware's own BC decoder agrees with the test decoder every number
+below is judged with.
+
+## Running it
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+Then open `/src/shade/playground/texture_encode/index.html`, pick a target and press **Encode**. The
+synthetic source is the three spec fixtures — smooth, rough, mask — in the red, green and blue
+channels at 512x512 with a CPU-built mip chain, so the numbers here can be held against the ones the
+specs pin. Any image file can be dropped in through the file input instead.
+
+The page does not use the renderer: the renderer's frame loop needs immediate data, which not every
+browser build offers, and the encoder needs no frame. A `GraphicsContext` and a command context over
+a bare device are enough to record the encode, and everything else is readback.
+
+## What it checks
+
+1. **The device accepts the work.** `createTexture` with the block format, one dispatch, one
+   `copyBufferToTexture` per level with rows padded to 256 bytes — inside a validation error scope,
+   so a refusal is a message rather than a black texture.
+2. **The texture holds the buffer.** Every level is copied back out with `copyTextureToBuffer` and
+   compared byte for byte with the block buffer the shader wrote.
+3. **The hardware decodes what the CPU decoder predicts.** Every level is read back through a
+   `textureLoad` pass — the GPU's own decoder — and compared texel for texel with the test
+   decoder. The specification writes BC4's interpolation in real arithmetic and leaves the
+   precision to the hardware, which the probe below found up to seven levels from the test decoder
+   on the widest six-value spans, so the verdict is the picture rather than a texel count: a level
+   whose hardware decode is decibels under the CPU decoder's reading of the same bytes, one
+   rounding forgiven, holds a wrong block. BC7 and BC6H decoders are bit-exact by specification and
+   matched on every sample.
+4. **The device against the emulator.** Level 0 is encoded a second time by the same chunk in the
+   WGSL emulator, in f64, and the blocks are compared. A block that differs is not wrong: the f32
+   arithmetic rounds a tie the other way, and the page says whether the device's choice decoded
+   better, worse or the same.
+
+And the numbers the specs already pin, on the same fixtures: PSNR and worst texel against the source,
+per level — once against the CPU decoder's reading of the blocks and once against the hardware's.
+
+The third panel is **FLIP** — the tree's own `sampler2d_flip_ldr`, the renderer's regression gate —
+of the hardware's picture against the source at level 0, drawn through the magma map: black where
+a viewer flipping between the two would see nothing, yellow where they certainly would. Its pooled
+mean and weighted median are in the report. It compares the displayed bytes, which for BC6H is the
+tone-mapped picture and for a signed format the mid-grey-centred one, because FLIP judges what is
+seen. It runs whatever the size: it is a CPU pass on the page's own thread, half a second at
+512x512 and twenty-two seconds at 2048x2048 here, the status says so while it runs, and the report
+line carries how long it took.
+
+The three panels share one view — the wheel zooms about the pointer, a drag pans, a double click
+refits — and one cursor: the open circle is the same texel on all three, and the line under the
+panels is what each holds there, in the format's own units, with the FLIP value beside them.
+
+**Probe hardware decoder** does the fourth check on its own, exhaustively: a 1024x1024 BC4 texture
+holding every pair of endpoints, read back at full precision, from which the interpolation weight at
+every index is fitted and the difference from the CPU decoder tabulated.
+
+## What it measured
+
+NVIDIA Lovelace through Dawn, 2026-09-02:
+
+| target | source | blocks | PSNR, CPU / hardware decode | wall, record to done | first run, with pipeline compile |
+|---|---|---|---|---|---|
+| `bc4-r-unorm` | 512x512, 10 levels | 21,847 | 53.15 / 52.59 dB | 5.3 ms | 212 ms |
+| `bc4-r-unorm` | 2048x2048, 12 levels | 349,527 | 53.23 / 52.66 dB | 8.6 ms (650 MP/s) | 21 ms |
+| `bc5-rg-unorm` | 512x512, 10 levels | 21,847 | 45.24 / 44.69 dB | 4.1 ms | 504 ms |
+| `bc1-rgba-unorm` | 512x512 correlated colour | 21,847 | 41.53 / 41.51 dB | 7.2 ms | 526 ms |
+| `bc1-rgba-unorm` | 512x512 unrelated channels | 21,847 | 31.55 / 31.53 dB | 4.3 ms | 316 ms |
+| `bc7-rgba-unorm` | 512x512 correlated colour, cut out | 21,847 | 46.04 / 46.04 dB | 3.6 ms | 257 ms |
+| `bc7-rgba-unorm` | 2048x2048 unrelated channels | 349,527 | 33.41 / 33.41 dB | 8.2 ms (682 MP/s) | 20 ms |
+| `bc5-rg-unorm` | 512x512 normal map | 21,847 | 37.40 / 37.01 dB | 4.3 ms | 397 ms |
+| `bc5-rg-snorm` | 512x512 normal map, signed bytes | 21,847 | 31.43 / 30.96 dB (peak 127) | 3.9 ms | 453 ms |
+| `bc6h-rgb-ufloat` | 512x512 HDR, fourteen stops and a sun | 21,847 | 47.05 / 47.05 dB (over half bits) | 3.6 ms | 364 ms |
+
+BC6H's hardware decode, like BC7's, matched the CPU decoder on every sample: the format requires a
+bit-accurate decoder.
+
+`astc-4x4-unorm` is on the list and refused by this device before a texture is created — it
+samples no ASTC format. An ASTC device is the first thing to point the page at.
+
+BC7's hardware decode matched the CPU decoder on every sample of every level: its interpolation is
+fully specified, where BC4's is left to the implementation.
+
+Validation clean. Every level's blocks read back from the texture byte-identical to the block
+buffer, the tails included. Against the source at 2048², level 0: 53.23 dB by the CPU decoder,
+52.66 dB as the hardware decodes it. The device and the f64 emulator chose the same block for 13,675
+of the 16,384 level-0 blocks of the 512² source; of the rest, 2,428 decode to the same error, 120
+better on the device, 161 worse.
+
+The hardware's BC4 decoder is `A + (B − A) · c / 257` over 16-bit endpoints, with c = 36, 72, 113,
+144, 185, 221 for the eight-value mode and 48, 96, 161, 209 for the six-value one. Rounded to eight
+bits it agrees with the CPU decoder on 62.6% of palette entries, is one level off on 22.9%, and up
+to seven off on 0.04% — the widest six-value spans.
+
+Two things this page found that no device-free tier had, both about the same rule: a copy of a
+compressed level is sized in whole blocks against the level's *physical* extent, so a 2x2 mip is
+copied as 4x4 and a 2x2 copy is refused. The encoder's copies were wrong that way for one run, and
+`texture_write_level` had been wrong that way for every BC chain's tail since it was written.

package/src/shade/playground/texture_encode/index.html

@@ -0,0 +1,133 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — GPU block encoder</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --line: #2b3038;
+            --text: #d6dae0;
+            --muted: #8b939f;
+            --pass: #55c46a;
+            --fail: #ff6b6b;
+            --warn: #e5b54a;
+        }
+
+        html, body { margin: 0; background: #0d0f12; color: var(--text); font: 13px/1.5 system-ui, -apple-system, Segoe UI, sans-serif; }
+
+        main { padding: 16px 20px; max-width: 1400px; }
+
+        h1 { font-size: 15px; margin: 0 0 4px; }
+
+        p.note { color: var(--muted); margin: 0 0 12px; max-width: 90ch; }
+
+        .row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin: 8px 0; }
+
+        button, select, input {
+            font: inherit;
+            padding: 5px 11px;
+            border-radius: 6px;
+            border: 1px solid var(--line);
+            background: #1c1f25;
+            color: var(--text);
+        }
+
+        button { cursor: pointer; }
+
+        #status { font-size: 12px; color: var(--muted); }
+        #status.pass { color: var(--pass); }
+        #status.fail { color: var(--fail); }
+        #status.warn { color: var(--warn); }
+
+        #report {
+            margin: 8px 0 0;
+            white-space: pre;
+            font: 11.5px/1.45 ui-monospace, SFMono-Regular, Consolas, monospace;
+        }
+
+        .panels { display: flex; gap: 12px; flex-wrap: wrap; margin-top: 12px; }
+
+        .panel { display: flex; flex-direction: column; gap: 4px; }
+
+        .panel span { font-size: 11.5px; color: var(--muted); }
+
+        canvas { border: 1px solid var(--line); background: #000; cursor: crosshair; touch-action: none; }
+
+        #readout {
+            min-height: 1.5em;
+            margin: 6px 0 0;
+            white-space: pre;
+            font: 11.5px/1.45 ui-monospace, SFMono-Regular, Consolas, monospace;
+        }
+    </style>
+</head>
+<body>
+<main>
+    <h1>GPU block encoder — tier 8, a real device</h1>
+
+    <p class="note">
+        A texture goes in, a block-compressed texture comes out, on the device: one compute dispatch
+        over every level, one <code>copyBufferToTexture</code> per level. This page proves the parts
+        no device-free tier can: that <code>createTexture</code> takes the format, that the copies
+        take the padded rows, that the blocks the shader wrote are the blocks the texture holds, and
+        — by reading the texture back through the hardware's own decoder — that the picture is the
+        picture.
+    </p>
+
+    <div class="row">
+        <label>Target <select id="format">
+            <option value="bc4-r-unorm">bc4-r-unorm — red</option>
+            <option value="bc5-rg-unorm">bc5-rg-unorm — red and green</option>
+            <option value="bc1-rgba-unorm">bc1-rgba-unorm — RGB</option>
+            <option value="bc7-rgba-unorm">bc7-rgba-unorm — RGBA, mode 6</option>
+            <option value="bc6h-rgb-ufloat">bc6h-rgb-ufloat — HDR RGB, mode 11</option>
+            <option value="astc-4x4-unorm">astc-4x4-unorm — RGB, one partition (needs an ASTC device)</option>
+            <option value="bc4-r-snorm">bc4-r-snorm — red, signed</option>
+            <option value="bc5-rg-snorm">bc5-rg-snorm — red and green, signed</option>
+        </select></label>
+        <label>Source <select id="source">
+            <option value="512">synthetic 512x512 (smooth / rough / mask in R, G, B — channels unrelated)</option>
+            <option value="correlated512">synthetic 512x512, correlated colour (a photograph's case)</option>
+            <option value="normal512">synthetic 512x512, a normal map in red and green (signed bytes for a signed target)</option>
+            <option value="hdr512">synthetic 512x512, HDR: the correlated colour over fourteen stops with a sun (for BC6H)</option>
+            <option value="2048">synthetic 2048x2048 — for timing</option>
+        </select></label>
+        <input id="file" type="file" accept="image/*">
+        <button id="run">Encode</button>
+        <button id="probe">Probe hardware decoder</button>
+    </div>
+
+    <div id="device" class="note">…</div>
+    <div id="status">waiting for a device</div>
+    <pre id="report"></pre>
+
+    <div class="panels">
+        <div class="panel"><span>source, the channels the format carries</span><canvas id="source_view"></canvas></div>
+        <div class="panel"><span>hardware decode of the encoded texture</span><canvas id="decoded_view"></canvas></div>
+        <div class="panel"><span>FLIP, hardware decode against the source (magma: black is unseen, yellow is certain)</span><canvas id="difference_view"></canvas></div>
+    </div>
+
+    <div id="readout"></div>
+
+    <p class="note">
+        The three panels share one view: the wheel zooms about the pointer, a drag pans, a double
+        click refits. The circle is the same texel on all three, and the line above is what each
+        panel holds there.
+    </p>
+</main>
+
+<script type="module">
+    import { start } from './main.js';
+
+    start().catch(error => {
+        const status = document.getElementById('status');
+
+        status.className = 'fail';
+        status.textContent = String(error?.message ?? error);
+
+        console.error(error);
+    });
+</script>
+</body>
+</html>

package/src/shade/playground/texture_encode/main.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Stand the page up.
+ *
+ * @returns {Promise<void>}
+ */
+export function start(): Promise<void>;
+/**
+ * One level of a source image, as bytes and as the sampler the harness compares with.
+ */
+export type SourceLevel = {
+    width: number;
+    height: number;
+    /**
+     * `width * height * 4` bytes of the texel format — `rgba8unorm`,
+     * `rgba8snorm`, or the half floats of `rgba16float` for an HDR level, in which case it is
+     * `width * height * 8` bytes
+     */
+    rgba: Uint8Array;
+    /**
+     * `width * height * 3` linear RGB floats, present for an HDR level
+     */
+    hdr?: Float32Array;
+};
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/texture_encode/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/texture_encode/main.js"],"names":[],"mappings":"AA+xBA;;;;GAIG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAmnBzB;;;;;WAhyCa,MAAM;YACN,MAAM;;;;;;UACN,UAAU;;;;UAGV,YAAY"}