@adobe/ecs 0.1.0 → 0.2.0

package/src/implementation/world/gpu.browser.test.ts

@@ -1,8 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
-import { Component } from "../../interface/component/component.js";
 import { Entity } from "../../interface/entity/entity.js";
 import { Gpu } from "../../interface/gpu/gpu.js";
-import { Mat4x4, Quat, Vec3 } from "../../interface/math/index.js";
+import { type F32, Mat4x4, Quat, type U32, Vec3 } from "../../interface/math/index.js";
 import type { Schema } from "../../interface/schema/schema.js";
 import { gpuDevice } from "../../interface/resources/gpu-device.js";
 import { System } from "../../interface/system/system.js";
@@ -12,7 +12,8 @@ import { workers } from "../../interface/resources/workers.js";
 import { always } from "../../interface/resources/always.js";
 import { clock } from "../../interface/resources/clock.js";
 import { Observe } from "../../observe/index.js";
-import { runReported } from "./reports.test-helper.js";
+import { catchOutOfBand, runReported } from "./outcomes.test-helper.js";
+import { gpu } from "./gpu.test-helper.js";
 
 const vec3 = { type: "array", items: { type: "number", precision: 1 }, minItems: 3, maxItems: 3 } as const satisfies Schema;
 const position = Symbol("gpuTest/position");
@@ -29,12 +30,12 @@ const ownedBy = Symbol("gpuTest/ownedBy");
 
 declare module "@adobe/ecs" {
     export interface Components {
-        [position]: { type: readonly [number, number, number] };
-        [velocity]: { type: readonly [number, number, number] };
-        [score]: { type: number };
+        [position]: { type: Vec3 };
+        [velocity]: { type: Vec3 };
+        [score]: { type: F32 };
         [tag]: { type: true };
-        [code]: { type: number };
-        [amount]: { type: number };
+        [code]: { type: U32 };
+        [amount]: { type: F32 };
         [flag]: { type: boolean };
         [followed]: { type: Entity };
         [bits]: { type: Vec3.U32 };
@@ -43,60 +44,51 @@ declare module "@adobe/ecs" {
     }
 }
 
-Component.register(position, { type: vec3 });
-Component.register(velocity, { type: vec3 });
-Component.register(score, { type: { type: "number", precision: 1 } });
-Component.register(tag, { type: { const: true } });
-Component.register(code, { type: { type: "integer", minimum: 0, maximum: 0xFFFFFFFF } });
-Component.register(amount, { type: { type: "number", precision: 1 } });
-Component.register(flag, { type: { type: "boolean" } });
-Component.register(followed, { type: Entity.schema });
-Component.register(ownedBy, { type: Entity.schema, reference: "owner" });
 
 const count = 5000;
 
-const spawn = System.create({ name: "gpuTest/spawn" }, ({ commands }) => {
+const spawn = System.create({}, ({ commands }) => {
     for (let i = 0; i < count; i++) {
         if (i % 2 === 0) commands.spawn([position, velocity])({ [position]: [i, 0, -i], [velocity]: [1, i % 7, 0.5] });
         else commands.spawn([position, velocity, tag])({ [position]: [i, 0, -i], [velocity]: [1, i % 7, 0.5], [tag]: true });
     }
 });
 
-const move = System.create({ name: "gpuTest/move", kernel: "gpu", components: { read: [velocity], write: [position] } }, row => {
+const move = System.create({ kernel: "gpu", components: { with: [velocity, position] } }, row => {
     const [px, py, pz] = row[position];
     const [vx, vy, vz] = row[velocity];
     row[position] = [px + vx, py + vy * 2, pz + vz];
 });
 
 /** Between two GPU kernels: reads what the first wrote, and changes what both read. */
-const reset = System.create({ name: "gpuTest/reset", components: { write: [position, velocity] }, after: [move] }, row => {
+const reset = System.create({ components: { with: [position, velocity] }, after: [move] }, row => {
     const [px, py, pz] = row[position];
     const [vx, vy, vz] = row[velocity];
     row[position] = [px * 2, py, pz + 100];
     row[velocity] = [vz, vx, vy];
 });
 
-const moveAgain = System.create({ name: "gpuTest/moveAgain", kernel: "gpu", components: { read: [velocity], write: [position] }, after: [reset] }, row => {
+const moveAgain = System.create({ kernel: "gpu", components: { with: [velocity, position] }, after: [reset] }, row => {
     const [px, py, pz] = row[position];
     const [vx, vy, vz] = row[velocity];
     row[position] = [px + vx, py + vy, pz + vz];
 });
 
 /** Between two GPU kernels: changes only what they read, so nothing needs reading back first. */
-const turn = System.create({ name: "gpuTest/turn", components: { write: [velocity] }, after: [move] }, row => {
+const turn = System.create({ components: { with: [velocity] }, after: [move] }, row => {
     const [vx, vy, vz] = row[velocity];
     row[velocity] = [vz * 3, vx, vy];
 });
 
-const moveLater = System.create({ name: "gpuTest/moveLater", kernel: "gpu", components: { read: [velocity], write: [position] }, after: [turn] }, row => {
+const moveLater = System.create({ kernel: "gpu", components: { with: [velocity, position] }, after: [turn] }, row => {
     const [px, py, pz] = row[position];
     const [vx, vy, vz] = row[velocity];
     row[position] = [px + vx, py + vy, pz + vz];
 });
 
-const turning = System.create({ name: "gpuTest/turning", systems: [move, turn, moveLater] });
+const turning = System.create({ systems: [move, turn, moveLater] });
 
-const spawnNumbers = System.create({ name: "gpuTest/spawnNumbers" }, ({ commands }) => {
+const spawnNumbers = System.create({}, ({ commands }) => {
     for (const [c, a] of [[0, 0], [3, -2.5], [0xff00ff00, 2.5], [0xffffff00, 7], [0x80000000, -0.25]]) commands.spawn([code, amount])({ [code]: c, [amount]: a });
 });
 
@@ -104,7 +96,7 @@ const spawnNumbers = System.create({ name: "gpuTest/spawnNumbers" }, ({ commands
  * JS semantics the GPU keeps: u32 values past 2^31, integer and bitwise chains bit for bit, infinities, rounding.
  * Arithmetic is f32, so only results f32 holds exactly are compared; WGSL lets implementations assume no value is NaN.
  */
-const numbers = System.create({ name: "gpuTest/numbers", kernel: "gpu", components: { write: [code, amount] } }, row => {
+const numbers = System.create({ kernel: "gpu", components: { with: [code, amount] } }, row => {
     const c = row[code];
     const a = row[amount];
     const mixed = (c ^ 0x0f0f0f0f) >>> 0;
@@ -113,29 +105,28 @@ const numbers = System.create({ name: "gpuTest/numbers", kernel: "gpu", componen
         + (c | 0) / 0x1000000 + Math.clz32(c) + (c > 0x80000000 ? 10000 : 0) + Math.max(a, -1) * 100 + (a % 1.5) * 10000;
 });
 
-const flagScore = System.create({ name: "gpuTest/flagScore", kernel: "gpu", components: { read: [flag], write: [score] } }, row => {
+const flagScore = System.create({ kernel: "gpu", components: { with: [flag, score] } }, row => {
     row[score] = row[flag] ? 1 : 0;
 });
 
-const spawnFollower = System.create({ name: "gpuTest/spawnFollower" }, ({ commands }) => {
+const spawnFollower = System.create({}, ({ commands }) => {
     const leader = commands.spawn([position, velocity])({ [position]: [10, 0, 0], [velocity]: [5, 0, 0] });
     commands.spawn([followed, score])({ [followed]: leader, [score]: 0 });
 });
 
 /** On the CPU, reads through a lookup what a GPU kernel wrote. */
 const follow = System.create({
-    name: "gpuTest/follow",
-    components: { read: [followed], write: [score] },
-    lookup: { leader: { read: [position] } },
+    components: { with: [followed, score] },
+    lookup: { leader: { with: [position] } },
     after: [move],
 }, (row, { lookup: { leader } }) => {
     row[score] = leader(row[followed])?.[position][0] ?? -1;
 });
 
-const following = System.create({ name: "gpuTest/following", systems: [move, follow] });
+const following = System.create({ systems: [move, follow] });
 
 /** Despawns the first entity, moving the last into its row, then makes the sync point throw. */
-const poison = System.create({ name: "gpuTest/poison", components: { read: [position] } }, (row, { commands }) => {
+const poison = System.create({ components: { with: [position] } }, (row, { commands }) => {
     if (row[position][0] === 2) commands.despawn(row.entity);
     if (row[position][0] === 4) commands.add(row.entity, score, Symbol("poison") as unknown as number);
 });
@@ -144,38 +135,36 @@ let frameNumber = 0;
 const spawnedNow: Entity[] = [];
 
 /** Spawns a few particles each frame, through growth of their archetypes; nothing on the CPU reads their positions. */
-const spawnFew = System.create({ name: "gpuTest/churn" }, ({ commands }) => {
+const spawnFew = System.create({}, ({ commands }) => {
     for (let i = 0; i < 37; i++) spawnedNow.push(commands.spawn([position, velocity])({ [position]: [frameNumber, i, 0], [velocity]: [1, i % 3, 0.25] }));
     // Every fifth frame, a despawn moves another particle into a row the GPU wrote.
     if (frameNumber % 5 === 4) commands.despawn(spawnedNow[frameNumber * 3]);
 });
 
 /** A render body that fails after starting its pass. */
-const fail = System.render({ name: "gpuTest/fail", shader: { accessors: { place: position } }, after: [move] }, ({ encoder }) => {
+const fail = System.render({ shader: { accessors: { place: position } }, after: [move] }, ({ encoder }) => {
     encoder.beginComputePass();
     throw new Error("draw failed");
 });
 
-const failing = System.create({ name: "gpuTest/failing", systems: [move, fail] });
+const failing = System.create({ systems: [move, fail] });
 
 /** Math from three namespaces, inlined into a compute shader. */
-const transform = System.create({ name: "gpuTest/transform", kernel: "gpu", components: { read: [velocity], write: [position] } }, row => {
+const transform = System.create({ kernel: "gpu", components: { with: [velocity, position] } }, row => {
     const q = Quat.fromAxisAngle([0, 1, 0], 0.5);
     const m = Mat4x4.multiply(Mat4x4.translation(1, 2, 3), Mat4x4.scaling(2, 2, 2));
     row[position] = Vec3.add(Mat4x4.multiplyVec3(m, Quat.rotateVec3(q, row[position])), Vec3.normalize(row[velocity]));
 });
 
-Component.register(bits, { type: Vec3.U32.schema });
-Component.register(sums, { type: Vec3.I32.schema });
 
-const spawnIntegers = System.create({ name: "gpuTest/spawnIntegers" }, ({ commands }) => {
+const spawnIntegers = System.create({}, ({ commands }) => {
     for (let i = 0; i < 100; i++) {
         commands.spawn([bits, sums])({ [bits]: [Math.imul(i + 1, 0x9E3779B9) >>> 0, (0xFFFFFFFF - i) >>> 0, (i << 26) >>> 0], [sums]: [2 ** 31 - 1 - i, -(2 ** 31) + i, Math.imul(i, 65536)] });
     }
 });
 
 /** Integer builtins, which wrap and count bits as the functions do. */
-const integers = System.create({ name: "gpuTest/integers", kernel: "gpu", components: { write: [bits, sums] } }, row => {
+const integers = System.create({ kernel: "gpu", components: { with: [bits, sums] } }, row => {
     const b = row[bits];
     const s = row[sums];
     row[bits] = Vec3.U32.add(Vec3.U32.countOneBits(b), Vec3.U32.add(Vec3.U32.countTrailingZeros(b), Vec3.U32.multiply(Vec3.U32.reverseBits(b), Vec3.U32.bitwiseXor(b, [7, 7, 7]))));
@@ -183,7 +172,7 @@ const integers = System.create({ name: "gpuTest/integers", kernel: "gpu", compon
 });
 
 /** Float builtins across vectors, quaternions and matrices, on in-domain inputs. */
-const shading = System.create({ name: "gpuTest/shading", kernel: "gpu", components: { read: [velocity], write: [position] } }, row => {
+const shading = System.create({ kernel: "gpu", components: { with: [velocity, position] } }, row => {
     const p = row[position];
     const v = Vec3.add(row[velocity], [0.25, 0.5, 0.75]);
     const n = Vec3.normalize(v);
@@ -199,17 +188,17 @@ const shading = System.create({ name: "gpuTest/shading", kernel: "gpu", componen
 });
 
 /** Reads the entity, an f64. */
-const entityScore = System.create({ name: "gpuTest/entityScore", kernel: "gpu", components: { write: [score] } }, row => {
+const entityScore = System.create({ kernel: "gpu", components: { with: [score] } }, row => {
     row[score] = row.entity;
 });
 
 let watched = 0;
-const watch = System.create({ name: "gpuTest/watch", components: { changed: [position] } }, () => { watched++; });
+const watch = System.create({ components: { changed: [position] } }, () => { watched++; });
 
-const frame = System.create({ name: "gpuTest/frame", systems: [move, reset, moveAgain] });
+const frame = System.create({ systems: [move, reset, moveAgain] });
 
 /** Added while others come and go, so ticks go on. */
-const steady = System.create({ name: "gpuTest/steady" }, () => {});
+const steady = System.create({}, () => {});
 
 const device = async (): Promise<GPUDevice> => {
     const adapter = await navigator.gpu.requestAdapter();
@@ -221,14 +210,14 @@ const positions = async (world: ReturnType<typeof createWorld>): Promise<Vec3[]>
     (await readEach(world, await select(world, { required: [position] }), position)).map(value => value ?? [NaN, NaN, NaN]);
 
 let nextDevice: GPUDevice | null = null;
-const setDevice = System.create({ name: "gpuTest/setDevice", resources: { write: [gpuDevice] } }, ({ resources }) => { resources[gpuDevice] = nextDevice; });
+const setDevice = System.create({}, ({ resources }) => { resources[gpuDevice] = nextDevice; });
 
 describe("removing GPU systems", () => {
-    it("releases the GPU records of a render system and a GPU kernel once they're removed", async () => {
+    it.runIf(gpu)("releases the GPU records of a render system and a GPU kernel once they're removed", async () => {
         const world = createWorld({ [workers]: 0, [always]: true, [gpuDevice]: await device() });
         await world.run(spawn);
         let drawn = 0;
-        const draw = System.render({ name: "gpuTest/drawUntilRemoved", shader: { accessors: { place: position } }, after: [move] }, () => { drawn++; });
+        const draw = System.render({ shader: { accessors: { place: position } }, after: [move] }, () => { drawn++; });
         const ticks = async (count: number): Promise<void> => {
             const from = (await Observe.toPromise(Observe.resource(world, clock))).tick;
             await new Promise<void>(resolve => {
@@ -257,7 +246,7 @@ describe("removing GPU systems", () => {
 });
 
 describe("the gpuDevice resource", () => {
-    it("moves GPU kernels onto the device once a system sets it", async () => {
+    it.runIf(gpu)("moves GPU kernels onto the device once a system sets it", async () => {
         const world = createWorld({ [workers]: 0 });
         await world.run(spawn);
         await world.run(move);
@@ -271,17 +260,17 @@ describe("the gpuDevice resource", () => {
         await world.dispose();
     });
 
-    it("sets itself to null once the device is lost, so the world goes on without it until a new one is set", async () => {
+    it.runIf(gpu)("sets itself to null once the device is lost, so the world goes on without it until a new one is set", async () => {
         const lost = await device();
         const world = createWorld({ [workers]: 0, [gpuDevice]: lost });
         const cpuWorld = createWorld({ [workers]: 0 });
         let changes = 0;
-        const watchDevice = System.create({ name: "gpuTest/watchDevice", resources: { read: [gpuDevice], changed: [gpuDevice] } }, ({ resources }) => {
+        const watchDevice = System.create({ resources: { changed: [gpuDevice] } }, ({ resources }) => {
             void resources[gpuDevice];
             changes++;
         });
         let drawn = 0;
-        const draw = System.render({ name: "gpuTest/drawWhileLost", shader: { accessors: { place: position } } }, () => { drawn++; });
+        const draw = System.render({ shader: { accessors: { place: position } } }, () => { drawn++; });
         for (const each of [world, cpuWorld]) await each.run(spawn);
         await world.run(watchDevice);
         // This move stays on the lost device, so it's lost with it.
@@ -306,7 +295,7 @@ describe("the gpuDevice resource", () => {
         await cpuWorld.dispose();
     });
 
-    it("moves to another device, reading back what's ahead on the one it leaves", async () => {
+    it.runIf(gpu)("moves to another device, reading back what's ahead on the one it leaves", async () => {
         const world = createWorld({ [workers]: 0, [gpuDevice]: await device() });
         const cpuWorld = createWorld({ [workers]: 0 });
         for (const each of [world, cpuWorld]) await each.run(spawn);
@@ -320,11 +309,11 @@ describe("the gpuDevice resource", () => {
         await cpuWorld.dispose();
     });
 
-    it("runs GPU kernels on the CPU again when set to null, and skips render systems", async () => {
+    it.runIf(gpu)("runs GPU kernels on the CPU again when set to null, and skips render systems", async () => {
         const world = createWorld({ [workers]: 2, [gpuDevice]: await device() }, { minimumChunk: 1 });
         const cpuWorld = createWorld({ [workers]: 0 });
         let drawn = 0;
-        const draw = System.render({ name: "gpuTest/drawUntilNull", shader: { accessors: { place: position } } }, () => { drawn++; });
+        const draw = System.render({ shader: { accessors: { place: position } } }, () => { drawn++; });
         for (const each of [world, cpuWorld]) await each.run(spawn);
         await world.run(draw);
         await world.run(move);
@@ -343,7 +332,7 @@ describe("the gpuDevice resource", () => {
 
 describe("GPU kernels", () => {
     // Each comparison runs the same GPU kernels in a world without a GPU, where they run on the CPU.
-    it("write values reads see, as the CPU kernel's do", async () => {
+    it.runIf(gpu)("write values reads see, as the CPU kernel's do", async () => {
         const gpuWorld = createWorld({ [gpuDevice]: await device() });
         const cpuWorld = createWorld({ [workers]: 0 });
         for (const world of [gpuWorld, cpuWorld]) {
@@ -357,7 +346,7 @@ describe("GPU kernels", () => {
         await cpuWorld.dispose();
     });
 
-    it("see main-thread writes made between them in the same run, and the main thread sees theirs", async () => {
+    it.runIf(gpu)("see main-thread writes made between them in the same run, and the main thread sees theirs", async () => {
         const gpuWorld = createWorld({ [gpuDevice]: await device() });
         const cpuWorld = createWorld({ [workers]: 0 });
         for (const world of [gpuWorld, cpuWorld]) {
@@ -370,7 +359,7 @@ describe("GPU kernels", () => {
         await cpuWorld.dispose();
     });
 
-    it("see main-thread writes to what they only read, made between them in the same run", async () => {
+    it.runIf(gpu)("see main-thread writes to what they only read, made between them in the same run", async () => {
         const gpuWorld = createWorld({ [gpuDevice]: await device() });
         const cpuWorld = createWorld({ [workers]: 0 });
         for (const world of [gpuWorld, cpuWorld]) {
@@ -382,8 +371,8 @@ describe("GPU kernels", () => {
         await cpuWorld.dispose();
     });
 
-    it("keep their writes when the sync point moves rows of their archetypes", async () => {
-        const spawnOne = System.create({ name: "gpuTest/spawnOne" }, ({ commands }) => {
+    it.runIf(gpu)("keep their writes when the sync point moves rows of their archetypes", async () => {
+        const spawnOne = System.create({}, ({ commands }) => {
             commands.spawn([position, velocity])({ [position]: [-1, -1, -1], [velocity]: [0, 0, 0] });
         });
         const world = createWorld({ [gpuDevice]: await device() });
@@ -399,14 +388,14 @@ describe("GPU kernels", () => {
         await world.dispose();
     });
 
-    it("keep their writes when a cascade moves rows of their archetypes", async () => {
+    it.runIf(gpu)("keep their writes when a cascade moves rows of their archetypes", async () => {
         const owners: Entity[] = [];
-        const spawnOwned = System.create({ name: "gpuTest/spawnOwned" }, ({ commands }) => {
+        const spawnOwned = System.create({}, ({ commands }) => {
             owners.push(commands.spawn([score])({ [score]: 0 }), commands.spawn([score])({ [score]: 1 }));
             for (let i = 0; i < 64; i++) commands.spawn([position, velocity, ownedBy])({ [position]: [i, 0, 0], [velocity]: [1, 0, 0], [ownedBy]: owners[i === 0 ? 0 : 1] });
         });
         // No command touches the owned rows: despawning their owner removes them.
-        const despawnOwner = System.create({ name: "gpuTest/despawnOwner" }, ({ commands }) => {
+        const despawnOwner = System.create({}, ({ commands }) => {
             const [owner] = owners;
             if (owner !== undefined) commands.despawn(owner);
         });
@@ -419,7 +408,7 @@ describe("GPU kernels", () => {
         await world.dispose();
     });
 
-    it("keep JS semantics for u32 values, bitwise operators and infinities", async () => {
+    it.runIf(gpu)("keep JS semantics for u32 values, bitwise operators and infinities", async () => {
         const gpuWorld = createWorld({ [gpuDevice]: await device() });
         const cpuWorld = createWorld({ [workers]: 0 });
         const values = async (world: ReturnType<typeof createWorld>): Promise<unknown[]> =>
@@ -433,7 +422,7 @@ describe("GPU kernels", () => {
         await cpuWorld.dispose();
     });
 
-    it("are read back for CPU systems that look them up", async () => {
+    it.runIf(gpu)("are read back for CPU systems that look them up", async () => {
         const world = createWorld({ [gpuDevice]: await device() });
         await world.run(spawnFollower);
         await world.run(following);
@@ -443,7 +432,7 @@ describe("GPU kernels", () => {
         await world.dispose();
     });
 
-    it("keep their copies current when a sync point fails partway", async () => {
+    it.runIf(gpu)("keep their copies current when a sync point fails partway", async () => {
         const gpuWorld = createWorld({ [gpuDevice]: await device() });
         const cpuWorld = createWorld({ [workers]: 0 });
         for (const world of [gpuWorld, cpuWorld]) {
@@ -457,7 +446,7 @@ describe("GPU kernels", () => {
         await cpuWorld.dispose();
     });
 
-    it("keep their writes as spawns grow their archetypes and despawns move rows", async () => {
+    it.runIf(gpu)("keep their writes as spawns grow their archetypes and despawns move rows", async () => {
         const gpuWorld = createWorld({ [gpuDevice]: await device() });
         const cpuWorld = createWorld({ [workers]: 0 });
         for (const world of [gpuWorld, cpuWorld]) {
@@ -473,7 +462,7 @@ describe("GPU kernels", () => {
         await cpuWorld.dispose();
     });
 
-    it("pass change filters on what they write, once per write", async () => {
+    it.runIf(gpu)("pass change filters on what they write, once per write", async () => {
         const counts: number[][] = [];
         for (const world of [createWorld({ [gpuDevice]: await device() }), createWorld({ [workers]: 0 })]) {
             watched = 0;
@@ -490,7 +479,7 @@ describe("GPU kernels", () => {
         expect(counts[0]).toEqual([count, count, count, 2 * count, 2 * count, 2 * count, 2 * count, 3 * count]);
     });
 
-    it("inline math functions as the CPU does, at f32 precision", async () => {
+    it.runIf(gpu)("inline math functions as the CPU does, at f32 precision", async () => {
         const gpuWorld = createWorld({ [gpuDevice]: await device() });
         const cpuWorld = createWorld({ [workers]: 0 });
         for (const world of [gpuWorld, cpuWorld]) {
@@ -506,7 +495,7 @@ describe("GPU kernels", () => {
         await cpuWorld.dispose();
     });
 
-    it("emit WGSL builtins for integer math, which wraps and counts bits as the CPU does", async () => {
+    it.runIf(gpu)("emit WGSL builtins for integer math, which wraps and counts bits as the CPU does", async () => {
         const gpuWorld = createWorld({ [gpuDevice]: await device() });
         const cpuWorld = createWorld({ [workers]: 0 });
         for (const world of [gpuWorld, cpuWorld]) {
@@ -520,7 +509,7 @@ describe("GPU kernels", () => {
         await cpuWorld.dispose();
     });
 
-    it("emit WGSL builtins for float math, within f32 precision of the CPU", async () => {
+    it.runIf(gpu)("emit WGSL builtins for float math, within f32 precision of the CPU", async () => {
         const gpuWorld = createWorld({ [gpuDevice]: await device() });
         const cpuWorld = createWorld({ [workers]: 0 });
         for (const world of [gpuWorld, cpuWorld]) {
@@ -536,7 +525,7 @@ describe("GPU kernels", () => {
         await cpuWorld.dispose();
     });
 
-    it("refuse what they can't run, with the reason", async () => {
+    it.runIf(gpu)("refuse what they can't run, with the reason", async () => {
         const world = createWorld({ [gpuDevice]: await device() });
         await expect(world.run(entityScore)).rejects.toThrow(/can't run on the GPU: it reads an f64 value/);
         await expect(world.run(flagScore)).rejects.toThrow(/reads a byte value/);
@@ -549,7 +538,7 @@ describe("GPU kernels", () => {
 });
 
 describe("render systems", () => {
-    it("that fail lose only their own work", async () => {
+    it.runIf(gpu)("that fail lose only their own work", async () => {
         const world = createWorld({ [gpuDevice]: await device() });
         await world.run(spawn);
         expect((await runReported(world, failing)).failures.map(failure => failure.message)).toEqual(["draw failed"]);
@@ -557,40 +546,59 @@ describe("render systems", () => {
         await world.dispose();
     });
 
-    it("that record invalid work make the next run report the GPU's error, under the run that submitted it", async () => {
+    it.runIf(gpu)("that record invalid work have the GPU's error reported out of band, under the run that submitted it, once while it keeps failing", async () => {
         // A dispatch without a pipeline is a validation error when the encoder finishes.
-        const invalid = System.render({ name: "gpuTest/invalid", shader: { accessors: { place: position } } }, ({ encoder }) => {
+        const invalid = System.render({ shader: { accessors: { place: position } } }, ({ encoder }) => {
             const pass = encoder.beginComputePass();
             pass.dispatchWorkgroups(1);
             pass.end();
         });
+        using reported = catchOutOfBand();
         const own = await device();
         const world = createWorld({ [gpuDevice]: own });
         await world.run(spawn);
+        // The run resolves: the device gives the error once it has processed the run's work.
+        await world.run(invalid);
+        const error = await reported.until(() => true);
+        expect(error.message).toMatch(/^GPU work of system "invalid" .*failed: validation: /);
         await world.run(invalid);
-        // The device reports the error once it has processed the run's work.
         await own.queue.onSubmittedWorkDone();
-        const [failure] = (await runReported(world, spawn)).failures;
-        expect([failure.kind, failure.name]).toEqual(["gpu", "gpuTest/invalid"]);
-        expect(failure.message).toMatch(/^validation: /);
-        expect((await runReported(world, spawn)).failures).toEqual([]);
+        await world.run(spawn);
+        expect(reported.errors).toHaveLength(1);
+        await world.dispose();
+    });
+
+    it.runIf(gpu)("that record invalid work report nothing once the world is disposed", async () => {
+        // A dispatch without a pipeline is a validation error when the encoder finishes.
+        const invalidThenDisposed = System.render({ shader: { accessors: { place: position } } }, ({ encoder }) => {
+            const pass = encoder.beginComputePass();
+            pass.dispatchWorkgroups(1);
+            pass.end();
+        });
+        using reported = catchOutOfBand();
+        const own = await device();
+        const world = createWorld({ [gpuDevice]: own });
+        await world.run(spawn);
+        await world.run(invalidThenDisposed);
         await world.dispose();
+        await own.queue.onSubmittedWorkDone();
+        await new Promise(resolve => setTimeout(resolve, 50));
+        expect(reported.errors).toEqual([]);
     });
 
-    it("name accessors anything WGSL allows, and only that", async () => {
+    it.runIf(gpu)("name accessors anything WGSL allows, and only that", async () => {
         const own = await device();
-        const named = (name: "gpuTest/count" | "gpuTest/target", accessor: string) => System.render({ name, shader: { accessors: { [accessor]: position } } }, () => {});
-        const module = own.createShaderModule({ code: `${Gpu.wgsl(named("gpuTest/count", "count"))}\n@compute @workgroup_size(1) fn main() { _ = count(0u); }` });
+        const named = (accessor: string) => System.render({ shader: { accessors: { [accessor]: position } } }, () => {});
+        const module = own.createShaderModule({ code: `${Gpu.wgsl(named("count"))}\n@compute @workgroup_size(1) fn main() { _ = count(0u); }` });
         expect((await module.getCompilationInfo()).messages.filter(message => message.type === "error")).toEqual([]);
-        expect(() => Gpu.wgsl(named("gpuTest/target", "target"))).toThrow(/isn't usable as a WGSL function name/);
+        expect(() => Gpu.wgsl(named("target"))).toThrow(/isn't usable as a WGSL function name/);
     });
 
-    it("read their components on the GPU through the generated accessors", async () => {
+    it.runIf(gpu)("read their components on the GPU through the generated accessors", async () => {
         const own = await device();
         const output = own.createBuffer({ size: count * 16, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC });
         const copy = System.render({
-            name: "gpuTest/copy/2",
-            components: { has: [tag] },
+            components: { with: [tag] },
             shader: { group: 0, accessors: { place: position } },
             after: [move],
         }, ({ encoder, tables }) => {
@@ -615,7 +623,7 @@ describe("render systems", () => {
 }`,
         });
         const pipeline = own.createComputePipeline({ layout: own.createPipelineLayout({ bindGroupLayouts: [Gpu.layout(own), outputLayout] }), compute: { module, entryPoint: "main" } });
-        const frameWithCopy = System.create({ name: "gpuTest/frame/2", systems: [move, copy] });
+        const frameWithCopy = System.create({ systems: [move, copy] });
         await world.run(spawn);
         await world.run(frameWithCopy);
         const staging = own.createBuffer({ size: output.size, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
@@ -637,12 +645,12 @@ describe("render systems", () => {
 /** The x a spawned position reaches after one `move`, of the one row the nudges below write. */
 const nudged = 3000;
 
-const nudgeRow = System.create({ name: "gpuTest/nudgeRow", components: { write: [position] } }, row => {
+const nudgeRow = System.create({ components: { with: [position] } }, row => {
     const [px, py, pz] = row[position];
     if (px === nudged) row[position] = [px, py + 1, pz];
 });
 
-const nudgeKernel = System.create({ name: "gpuTest/nudgeKernel", kernel: "cpu", components: { write: [position] } }, row => {
+const nudgeKernel = System.create({ kernel: true, components: { with: [position] } }, row => {
     const [px, py, pz] = row[position];
     if (px === nudged) row[position] = [px, py + 1, pz];
 });
@@ -667,7 +675,7 @@ describe("CPU writes to GPU copies", () => {
         { name: "a WASM kernel on workers", nudge: nudgeKernel, threads: 2, wasm: true },
         { name: "a JS kernel on workers", nudge: nudgeKernel, threads: 2, wasm: false },
     ];
-    it.each(cases)("upload only the chunks they changed: $name", async ({ nudge, threads, wasm }) => {
+    it.runIf(gpu).each(cases)("upload only the chunks they changed: $name", async ({ nudge, threads, wasm }) => {
         const own = await device();
         const sizes = uploadSizes(own);
         const gpuWorld = createWorld({ [workers]: threads, [gpuDevice]: own }, { minimumChunk: 64, wasm });

package/src/implementation/world/gpu.test-helper.ts

@@ -0,0 +1,12 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { inject } from "vitest";
+
+declare module "vitest" {
+    interface ProvidedContext {
+        /** Whether this run has a GPU: tests that need one skip without it, as on CI's runners (`vitest.config.ts`). */
+        readonly gpu: boolean;
+    }
+}
+
+/** Whether this run has a GPU, for `it.runIf(gpu)`. */
+export const gpu = inject("gpu");

package/src/implementation/world/gpu.ts

@@ -1,4 +1,6 @@
-import { labelOfItem } from '../../interface/registry/index.js';
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { failureOf } from './failures.js';
+import type { OutOfBand } from './out-of-band.js';
 import { layout } from '../../interface/gpu/layout.js';
 import { recordBytes } from '../../interface/gpu/record.js';
 import type { Archetype, Storage } from './archetype.js';
@@ -62,6 +64,8 @@ export type GpuEngine = {
     readonly release: (prefix: string) => void;
     /** For tests of what a world holds: how many records and index blocks it keeps. */
     readonly records: () => number;
+    /** Lets go of the GPU copies of a reclaimed archetype's storages (`reclaim.ts`): it has no rows, and starts again empty. */
+    readonly forget: (archetype: Archetype) => void;
     /** Marks every row of a storage changed on the CPU, for writes that may not stamp its chunks. */
     readonly markCpuWrites: (archetype: Archetype, storage: Storage) => void;
     readonly markGpuWrites: (archetype: Archetype, storage: Storage) => void;
@@ -78,17 +82,17 @@ export type GpuEngine = {
     readonly touched: (archetypes: Iterable<Archetype>) => void;
     /** Set once the device is lost; later runs that use the GPU reject with it, and readbacks keep the CPU's copies. */
     readonly lost: () => string | null;
-    /** Records the first error a run's scopes report, for the next run to reject with. */
-    /** Keeps the first error of a run's GPU work, with the label of the system whose run submitted it. */
+    /**
+     * Reports a run's GPU work out of band once its scopes give their errors, as a `"gpu"` failure of the system whose
+     * run submitted it; a run whose scopes give none takes that system as recovered.
+     */
     readonly reportErrors: (system: { readonly name: string }, validation: Promise<GPUError | null>, memory: Promise<GPUError | null>) => void;
-    /** The recorded error, cleared. */
-    readonly takeError: () => { readonly name: string; readonly message: string } | null;
     readonly destroy: () => void;
 };
 
 const sizeClass = (bytes: number): number => Math.max(0, Math.ceil(Math.log2(Math.max(bytes, minimumBlockBytes) / minimumBlockBytes)));
 
-export const createGpu = (device: GPUDevice): GpuEngine => {
+export const createGpu = (device: GPUDevice, outOfBand: OutOfBand): GpuEngine => {
     const renderLayout = layout(device);
     const computeLayout = device.createBindGroupLayout({
         entries: [
@@ -109,7 +113,6 @@ export const createGpu = (device: GPUDevice): GpuEngine => {
     let groups: { render: GPUBindGroup; compute: GPUBindGroup } | null = null;
     let encoder: GPUCommandEncoder | null = null;
     let lostReason: string | null = null;
-    let recorded: { readonly name: string; readonly message: string } | null = null;
     const residents = new Map<Storage, Resident>();
     const ahead = new Set<Resident>();
     void device.lost.then(info => { lostReason = info.message === "" ? info.reason : info.message; });
@@ -190,6 +193,16 @@ export const createGpu = (device: GPUDevice): GpuEngine => {
         return resident;
     };
 
+    const forget = (archetype: Archetype): void => {
+        for (const storage of archetype.storages) {
+            const resident = residents.get(storage);
+            if (resident === undefined) continue;
+            if (resident.bytes > 0) (freeBlocks[sizeClass(resident.bytes)] ??= []).push(resident.offset);
+            residents.delete(storage);
+            ahead.delete(resident);
+        }
+    };
+
     /** Writes rows `low` to `high` of a storage into its GPU copy. */
     const write = (resident: Resident, low: number, high: number): void => {
         // A queue write lands before work recorded but not yet submitted, which may read these rows.
@@ -359,6 +372,7 @@ export const createGpu = (device: GPUDevice): GpuEngine => {
         uploadIndexes,
         record,
         release,
+        forget,
         records: () => slots.size + indexBlocks.size,
         markCpuWrites,
         markGpuWrites,
@@ -375,15 +389,13 @@ export const createGpu = (device: GPUDevice): GpuEngine => {
         reportErrors: (system, validation, memory) => {
             void (async () => {
                 const [invalid, exhausted] = await Promise.all([validation, memory]);
-                if (invalid !== null) recorded ??= { name: labelOfItem(system), message: `validation: ${invalid.message}` };
-                else if (exhausted !== null) recorded ??= { name: labelOfItem(system), message: `out of memory: ${exhausted.message}` };
+                if (invalid === null && exhausted === null) outOfBand.recovered(system);
+                else {
+                    const error = invalid !== null ? new Error(`validation: ${invalid.message}`, { cause: invalid }) : new Error(`out of memory: ${exhausted?.message}`, { cause: exhausted });
+                    outOfBand.report(failureOf("gpu", system, error));
+                }
             })();
         },
-        takeError: () => {
-            const error = recorded;
-            recorded = null;
-            return error;
-        },
         destroy: () => {
             submit();
             heap.destroy();