@adobe/ecs 0.0.0-stage → 0.2.0

package/src/perftest/tails.ts

@@ -0,0 +1,298 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <reference types="node" />
+import { always } from "../interface/resources/always.js";
+import { eachTick, ticksAfter } from "./observer.js";
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import type { World } from "../interface/world/world.js";
+import { backToBack, createWorld, type CreatedWorld } from "../implementation/index.js";
+import { tailWriters } from "../implementation/world/tails.js";
+import type { Benchmark } from "./benchmark.js";
+import { runReported } from "../implementation/world/outcomes.test-helper.js";
+import type { Mat4x4, U32, Vec3 } from "../interface/math/index.js";
+import type { Schema } from "../interface/schema/schema.js";
+
+// Tails: terminal systems on a joined worker, which claims "tailsBenchmark", running after their tick's sync point
+// while the world goes on. The joined thread is `joined.ts`.
+
+const place = Symbol("tails/place");
+const pose = Symbol("tails/pose");
+const surface = Symbol("tails/surface");
+const poked = Symbol("tails/poked");
+const rowWork = Symbol("tails/rowWork");
+const worldWork = Symbol("tails/worldWork");
+declare module "@adobe/ecs" {
+    export interface Threads {
+        tailsBenchmark: true;
+    }
+    export interface Components {
+        [place]: { type: Vec3 };
+        [pose]: { type: Mat4x4 };
+    }
+    export interface Resources {
+        [surface]: { type: Surface; thread: "tailsBenchmark" };
+        [poked]: { type: Schema.Type<{ type: "integer" }>; default: 0 };
+        [rowWork]: { type: U32 };
+        [worldWork]: { type: number };
+    }
+}
+/** An object of the joined thread, as a canvas or the DOM is, which places the systems reading it there. */
+const surfaceStart = { name: "surface" } as const;
+/** The surface tails draw to, which starts as `surfaceStart`, so they can tell it apart by identity. */
+type Surface = { readonly name: string };
+const Surface = { default: surfaceStart };
+
+/** What the tails read, so their reads aren't dead. */
+export const drawn = { sum: 0 };
+
+/** Rows of the prompt tail, and of the late one's snapshot. */
+export const promptRows = 1_000;
+export const lateRows = 10_000;
+/** Ticks in each timed stretch of the prompt tail. */
+export const tailTicks = 1_000;
+
+const spawnPlaces = System.create({}, ({ commands }) => {
+    for (let k = 0; k < promptRows; k++) commands.spawn([place])({ [place]: [k, 0, 0] });
+});
+const spawnPoses = System.create({}, ({ commands }) => {
+    for (let k = 0; k < lateRows; k++) commands.spawn([place, pose])({ [place]: [k, 0, 0], [pose]: [k, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1] });
+});
+
+const here = System.create({}, () => {});
+/** On the joined thread, terminal: reads every row's place, as a DOM-writing system reads positions. */
+const draw = System.create({ components: { with: [place] } }, (row, { resources }) => {
+    if (resources[surface] === surfaceStart) drawn.sum += row[place][0];
+});
+/** A tick of a world system and a 1,000-row tail that finishes before the next tick needs it. */
+export const promptTick = System.create({ systems: [here, draw] });
+
+/** On the joined thread, ahead of the late tail: busy for a while, as a main thread is with layout. */
+const busy = System.create({}, ({ resources }) => {
+    const until = performance.now() + 4;
+    while (performance.now() < until && resources[surface] === surfaceStart);
+});
+/** On the joined thread, terminal, after `busy`: reads every row's place and pose, and the resource `poke` writes. */
+const copied = System.create({ components: { with: [place, pose] }, after: [busy] }, (row, { resources }) => {
+    if (resources[surface] === surfaceStart) drawn.sum += row[place][0] + row[pose][15] + resources[poked];
+});
+export const lateTick = System.create({ systems: [busy, copied] });
+/** On the world's thread: writes what the late tail reads, so it copies the rest of the tail's reads first. */
+const poke = System.create({}, ({ resources }) => {
+    resources[poked] += 1;
+});
+const nothing = System.create({}, () => {});
+
+/** Steps of work each row of the overlapping tail does, about 2.5 ms over 10,000 rows; the world's work after its writer. */
+export const overlapWork = 40;
+export const overlapWorldMilliseconds = 2;
+/** Ticks in each timed stretch of the overlapping tail. */
+export const overlapTicks = 100;
+
+/** On the world's thread: writes every row's place, which the last tick's tail still reads. */
+const overlapWrite = System.create({ kernel: false, components: { with: [place] } }, row => {
+    row[place] = [row[place][0], 1, 0];
+});
+/** On the world's thread, after the writer: the rest of the tick's work, as systems reading what it wrote do. */
+const overlapSimulate = System.create({ after: [overlapWrite] }, ({ resources }) => {
+    const until = performance.now() + resources[worldWork];
+    while (performance.now() < until);
+});
+/** On the joined thread, terminal: works on every row's place and pose, as a DOM-writing system on main does. */
+const overlapDraw = System.create({ components: { with: [place, pose] }, after: [overlapWrite] }, (row, { resources }) => {
+    if (resources[surface] !== surfaceStart) return;
+    let sum = row[place][0] + row[pose][15];
+    for (let k = resources[rowWork]; k > 0; k--) sum = Math.sqrt(sum + k);
+    drawn.sum += sum;
+});
+export const overlapTick = System.create({ systems: [overlapWrite, overlapSimulate, overlapDraw] });
+const setOverlap = System.create({}, ({ resources }) => {
+    resources[rowWork] = overlapWork;
+    resources[worldWork] = overlapWorldMilliseconds;
+});
+
+/** Every system the joined thread runs, which it imports so the world can place them there. */
+export const tailSystems: readonly System<void>[] = [promptTick, lateTick, overlapTick];
+
+const joinedFile = "./joined.js";
+
+/** Starts `joined.ts` on a worker, joined to `world` and claiming the benchmark's thread, once it joined. */
+const startClaiming = async (world: CreatedWorld): Promise<{ readonly terminate: () => Promise<void> }> => {
+    const message = (port: unknown) => ({ kind: "port", port, threads: ["tailsBenchmark"] });
+    let terminate: () => Promise<void>;
+    let shared: Promise<void>;
+    if (typeof globalThis.Worker === "function") {
+        const { port1, port2 } = new MessageChannel();
+        shared = world.share(port1);
+        const worker = new globalThis.Worker(new URL("./joined.js", import.meta.url), { type: "module" });
+        await new Promise(resolve => {
+            worker.onmessage = resolve;
+            worker.postMessage(message(port2), [port2]);
+        });
+        terminate = async () => worker.terminate();
+    }
+    else {
+        const threads = globalThis.process.getBuiltinModule("node:worker_threads");
+        const { port1, port2 } = new threads.MessageChannel();
+        shared = world.share(port1);
+        const worker = new threads.Worker(new URL(joinedFile, import.meta.url));
+        await new Promise(resolve => {
+            worker.once("message", resolve);
+            worker.postMessage(message(port2), [port2]);
+        });
+        terminate = async () => { await worker.terminate(); };
+    }
+    await shared;
+    return { terminate };
+};
+
+/** The fastest of `stretches` stretches of `tailTicks` ticks with the prompt tail, driven back to back. */
+const prompt = async (stretches = 5): Promise<number> => {
+    const driver = backToBack();
+    const world = createWorld({ [workers]: 0, [always]: true }, { loop: driver });
+    const joined = await startClaiming(world);
+    let best = Infinity;
+    try {
+        await world.run(spawnPlaces);
+        const report = await runReported(world, promptTick);
+        if (report.failures.length > 0 || report.warnings.length > 0) throw new Error(`tail prompt: the tail didn't run as one: ${report.failures[0]?.message ?? report.warnings[0]?.message}.`);
+        await new Promise<void>(resolve => {
+            let ticks = 0;
+            let stretch = 0;
+            let start = 0;
+            const unobserve = eachTick(world, () => {
+                if (ticks++ % tailTicks !== 0) return;
+                const now = performance.now();
+                if (stretch > 1) best = Math.min(best, now - start);
+                start = now;
+                if (stretch++ <= stretches) return;
+                unobserve();
+                resolve();
+            });
+            world.add(promptTick);
+        });
+    }
+    finally {
+        // Disposed first: ticks after the thread ended would fail its systems, reported out of band.
+        await world.dispose();
+        await joined.terminate();
+        driver.close();
+    }
+    return best;
+};
+
+/**
+ * The fastest of `rounds` runs writing what a late tail of 10,000 rows reads, each right after a tick posted it behind
+ * a busy system on its thread, so the run copies the tail's reads first.
+ */
+const late = async (rounds = 30): Promise<number> => {
+    const driver = backToBack();
+    const world = createWorld({ [workers]: 0 }, { loop: driver });
+    const joined = await startClaiming(world);
+    let best = Infinity;
+    try {
+        await world.run(spawnPoses);
+        world.add(lateTick);
+        for (let round = 0; round < rounds; round++) {
+            // Each run makes the next beat tick, which posts the tail behind `busy`.
+            const ticked = ticksAfter(world, 1);
+            await world.run(nothing);
+            await ticked;
+            const start = performance.now();
+            // A run whose tail failed rejects.
+            await world.run(poke);
+            const time = performance.now() - start;
+            if (round > 1) best = Math.min(best, time);
+            // The tail and the tick the run made finish.
+            await new Promise(resolve => setTimeout(resolve, 12));
+        }
+    }
+    finally {
+        // Disposed first: ticks after the thread ended would fail its systems, reported out of band.
+        await world.dispose();
+        await joined.terminate();
+        driver.close();
+    }
+    return best;
+};
+
+/**
+ * The fastest of `stretches` stretches of `overlapTicks` ticks writing what the last tick's tail reads, driven back to
+ * back: with snapshots, or with the writer waiting for the tail to finish.
+ */
+const overlap = async (waiting: boolean, stretches = 5): Promise<number> => {
+    const driver = backToBack();
+    const world = createWorld({ [workers]: 0, [always]: true }, { loop: driver });
+    const joined = await startClaiming(world);
+    let best = Infinity;
+    tailWriters.wait = waiting;
+    try {
+        await world.run(spawnPoses);
+        await world.run(setOverlap);
+        const report = await runReported(world, overlapTick);
+        if (report.failures.length > 0 || report.warnings.length > 0) throw new Error(`tail overlap: the tail didn't run as one: ${report.failures[0]?.message ?? report.warnings[0]?.message}.`);
+        await new Promise<void>(resolve => {
+            let ticks = 0;
+            let stretch = 0;
+            let start = 0;
+            const unobserve = eachTick(world, () => {
+                if (ticks++ % overlapTicks !== 0) return;
+                const now = performance.now();
+                if (stretch > 1) best = Math.min(best, now - start);
+                start = now;
+                if (stretch++ <= stretches) return;
+                unobserve();
+                resolve();
+            });
+            world.add(overlapTick);
+        });
+    }
+    finally {
+        tailWriters.wait = false;
+        // Disposed first: ticks after the thread ended would fail its systems, reported out of band.
+        await world.dispose();
+        await joined.terminate();
+        driver.close();
+    }
+    return best;
+};
+
+const overlapOperation = "Ticks writing every row's place, which the last tick's tail on a joined worker still reads, then working 2 ms, while the tail works about 2.5 ms over 10,000 rows of a place and a pose: main's DOM work and the world's work after its writer that together outlast a frame or a fixed step, though each fits.";
+
+export const tailBenchmarks: readonly Benchmark[] = [
+    {
+        name: "tail prompt",
+        operation: "Ticks of a world system and a terminal system on a joined worker over 1,000 rows, which runs after the sync point and finishes before the next tick needs it: a DOM-writing system on main that keeps up.",
+        per: "ticks",
+        n: tailTicks,
+        typical: [1, 1],
+        best: { bytes: 256 + promptRows * 12, basis: "One task moves its posted, done, payload and completion lines between cores, and the tail reads each row's 12-byte vec3." },
+        run: () => prompt(),
+    },
+    {
+        name: "tail late snapshot 10K",
+        operation: "A run writing what a late tail on a joined worker reads, 10,000 passing rows of a vec3 and a mat4: the copy of the tail's reads it makes first, as when main is busy when the next tick writes positions.",
+        per: "rows copied",
+        n: lateRows,
+        typical: [100, 10_000],
+        best: { bytes: 2 * (12 + 64) + 20, basis: "Each row's 12-byte vec3 and 64-byte mat4 are read and written, and its position, archetype, row and entity, 20 bytes, written." },
+        run: () => late(),
+    },
+    {
+        name: "tail overlap",
+        operation: `${overlapOperation} The writer copies the rows the tail hasn't read, so the tick and the tail overlap.`,
+        per: "ticks",
+        n: overlapTicks,
+        typical: [1, 1],
+        best: { bytes: 2 * lateRows * (12 + 64), basis: "The world copies each row's 12-byte vec3 and 64-byte mat4 the tail hasn't read, and the tail reads them, beyond the work each side does." },
+        run: () => overlap(false),
+    },
+    {
+        name: "tail overlap waiting",
+        operation: `${overlapOperation} The writer waits for the tail to finish instead, the alternative \`tail overlap\` is measured against.`,
+        per: "ticks",
+        n: overlapTicks,
+        typical: [1, 1],
+        best: { bytes: lateRows * (12 + 64), basis: "The tail reads each row's 12-byte vec3 and 64-byte mat4, beyond the work each side does." },
+        run: () => overlap(true),
+    },
+];

package/src/perftest/transfers.ts

@@ -0,0 +1,98 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import { createWorld, type CreatedWorld } from "../implementation/index.js";
+import type { Benchmark } from "./benchmark.js";
+
+// A benchmark of transfers, in a browser: a loader on a joined worker moving decoded assets to the joined worker that
+// claims "transfersBenchmark", whose system takes them, through runs. Both workers are `joined.ts`.
+
+export const sink = Symbol("transfers/sink");
+declare module "@adobe/ecs" {
+    export interface Threads {
+        transfersBenchmark: true;
+    }
+    export interface Resources {
+        [sink]: { type: { readonly read: () => number } | null; thread: "transfersBenchmark" };
+    }
+}
+/** An object of the claimed thread, which places the system reading it there. */
+
+/** Bytes `take` took, on the claimed thread. */
+export const taken = { bytes: 0 };
+
+/** On the claimed thread: takes a buffer and a bitmap, as an upload would, closing the bitmap. */
+export const take = System.create({}, ({ resources }, input: { readonly buffer: ArrayBuffer; readonly bitmap: ImageBitmap }) => {
+    if (resources[sink] !== null) return;
+    taken.bytes += input.buffer.byteLength + input.bitmap.width * input.bitmap.height * 4;
+    input.bitmap.close();
+});
+
+/** Every system the joined threads run, which they import so the world can place them there. */
+export const transferSystems: readonly { readonly name: string }[] = [take];
+
+/** Transfers timed, in stretches of `transferBatch`, each made untimed first. */
+export const transferCount = 100;
+export const transferBatch = 10;
+/** Each transfer's buffer bytes, and its bitmap's side in pixels. */
+export const transferBytes = 1 << 20;
+export const transferSide = 1024;
+
+type Joined = { readonly ask: (message: unknown) => Promise<unknown>; readonly terminate: () => void };
+
+/** Starts `joined.ts` on a browser worker, joining `world` through a channel it's given and claiming `threads`. */
+const startJoined = async (world: CreatedWorld, threads: readonly string[]): Promise<Joined> => {
+    const { port1, port2 } = new MessageChannel();
+    const shared = world.share(port1);
+    const worker = new Worker(new URL("./joined.js", import.meta.url), { type: "module" });
+    const ask = (message: unknown, transfer: Transferable[] = []): Promise<unknown> => new Promise(resolve => {
+        worker.onmessage = event => resolve(event.data);
+        worker.postMessage(message, transfer);
+    });
+    await ask({ kind: "port", port: port2, threads }, [port2]);
+    await shared;
+    return { ask, terminate: () => worker.terminate() };
+};
+
+/**
+ * Milliseconds the loader took for `transferCount` transfers to the claimed thread of bitmaps `side` pixels square, each
+ * run posted back to back in batches: every batch's time, or with `fastestOf`, the fastest of that many batches'.
+ */
+const transfers = async (side: number, fastestOf: number): Promise<number> => {
+    const world = createWorld({ [workers]: 0 });
+    const filler = await startJoined(world, ["transfersBenchmark"]);
+    const loader = await startJoined(world, []);
+    try {
+        const reply = await loader.ask({ kind: "transfers", side, fastestOf });
+        if (typeof reply !== "object" || reply === null || Reflect.get(reply, "kind") !== "transferred") throw new Error("transfer: the loader didn't transfer.");
+        const milliseconds: unknown = Reflect.get(reply, "milliseconds");
+        return typeof milliseconds === "number" ? milliseconds : NaN;
+    }
+    finally {
+        loader.terminate();
+        // Disposed first: ticks after the thread ended would fail its systems, reported out of band.
+        await world.dispose();
+        filler.terminate();
+    }
+};
+
+export const transferBenchmarks: readonly Benchmark[] = [
+    {
+        name: "transfer",
+        operation: "Runs from a loader on a joined worker, each moving a 1 MB ArrayBuffer and a 1024 by 1024 ImageBitmap to the joined worker whose system takes them, which acknowledges each to the world: decoded textures or audio reaching the thread that uses them.",
+        per: "transfers",
+        n: transferCount,
+        typical: [1, 100],
+        best: { bytes: 256, basis: "A transfer moves its values' handles in one message, the bytes staying where they are, and the run's slot and completion lines between cores." },
+        run: () => transfers(transferSide, 0),
+    },
+    {
+        name: "transfer small bitmaps",
+        operation: "`transfer` with 1 by 1 bitmaps, the fastest of 40 batches of 10: the ECS's path for a transfer, without the browser's moving of large bitmaps, which varies twofold from batch to batch.",
+        per: "transfers",
+        n: transferCount,
+        typical: [1, 100],
+        best: { bytes: 256, basis: "As `transfer`." },
+        run: () => transfers(1, 40),
+    },
+];

package/src/perftest/uploads.ts

@@ -0,0 +1,80 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity } from "../interface/entity/entity.js";
+import { gpuDevice } from "../interface/resources/gpu-device.js";
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import { createWorld } from "../implementation/world/create.js";
+import type { Benchmark } from "./benchmark.js";
+import type { Vec3 } from "../interface/math/index.js";
+
+// A drag: the CPU writes one row of a column a render system holds on the GPU, which uploads what changed.
+
+const place = Symbol("uploads/place");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [place]: { type: Vec3 };
+    }
+}
+
+const shapes = 100_000;
+let spawned: Entity[] = [];
+const spawn = System.create({}, ({ commands }) => {
+    spawned = [];
+    for (let i = 0; i < shapes; i++) spawned.push(commands.spawn([place])({ [place]: [i, 0, 0] }));
+});
+const drag = System.create({
+    components: { with: [place] },
+    target: "shape",
+}, (row, _context, input: { readonly shape: Entity; readonly x: number }) => {
+    row[place] = [input.x, 1, 0];
+});
+/** Draws nothing: its run uploads what it reads. */
+const draw = System.render({ shader: { accessors: { place } }, after: [drag] }, () => {});
+const frame = System.create({ systems: [drag, draw] });
+const slide = System.create({ kernel: true, components: { with: [place] } }, row => {
+    const [x, y, z] = row[place];
+    row[place] = [x + 1, y, z];
+});
+const drawAfterSlide = System.render({ shader: { accessors: { place } }, after: [slide] }, () => {});
+const slideFrame = System.create({ systems: [slide, drawAfterSlide] });
+
+/** Timed per run by `timed`, which waits for the GPU. */
+export const uploadBenchmarks = (device: GPUDevice, timed: (run: () => Promise<unknown>) => Promise<number>): readonly Benchmark[] => [{
+    name: "gpu upload one row 100K",
+    operation: "A target system writing one row of 100K 12-byte positions a render system draws, as a drag does, then the render system's run, which uploads what the CPU changed.",
+    per: "runs",
+    n: 1,
+    typical: [1, 1],
+    best: { bytes: 12, basis: "The upload writes the one 12-byte position changed.", on: "gpu" },
+    run: async () => {
+        const world = createWorld({ [workers]: 0, [gpuDevice]: device });
+        try {
+            await world.run(spawn);
+            const shape = spawned[shapes / 2];
+            let x = 0;
+            await world.run(frame, { shape, x });
+            return await timed(() => world.run(frame, { shape, x: ++x }));
+        }
+        finally {
+            await world.dispose();
+        }
+    },
+}, {
+    name: "gpu upload all rows 100K",
+    operation: "A CPU kernel on the main thread writing every row of 100K 12-byte positions a render system draws, then the render system's run, which uploads them.",
+    per: "rows",
+    n: shapes,
+    typical: [1_000, 100_000],
+    best: { bytes: 36, basis: "The kernel reads and writes each 12-byte position, and the upload writes it.", on: "gpu" },
+    run: async () => {
+        const world = createWorld({ [workers]: 0, [gpuDevice]: device });
+        try {
+            await world.run(spawn);
+            await world.run(slideFrame);
+            return await timed(() => world.run(slideFrame));
+        }
+        finally {
+            await world.dispose();
+        }
+    },
+}];

package/src/perftest/values.ts

@@ -0,0 +1,107 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Finalizer } from "../interface/finalizer/finalizer.js";
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import type { World } from "../interface/world/world.js";
+import { createWorld } from "../implementation/index.js";
+import type { Benchmark, Best } from "./benchmark.js";
+import { fastest } from "./suite.js";
+import type { Vec2 } from "../interface/math/index.js";
+
+// Benchmarks of struct values, which a row reads into an object and writes back field by field: a 2D transform's five
+// numbers, as an editor's nodes hold, beside a vec2 size.
+
+const pose = Symbol("values/pose");
+const shown = Symbol("values/shown");
+const extent = Symbol("values/extent");
+const order = Symbol("values/order");
+type Pose = { readonly tx: number; readonly ty: number; readonly rotation: number; readonly sx: number; readonly sy: number };
+declare module "@adobe/ecs" {
+    export interface Components {
+        [pose]: { type: Pose };
+        [shown]: { type: Pose };
+        [extent]: { type: Vec2 };
+        [order]: { type: number };
+    }
+}
+const number = { type: "number" } as const;
+const poseSchema = { type: "object", properties: { tx: number, ty: number, rotation: number, sx: number, sy: number }, required: ["tx", "ty", "rotation", "sx", "sy"] } as const;
+
+const Node = [pose, shown, extent, order] as const;
+
+const rows = 100_000;
+
+const seed = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    for (let i = 0; i < input.count; i++) commands.spawn(Node)({ [pose]: { tx: i, ty: 0, rotation: 0, sx: 1, sy: 1 }, [shown]: { tx: 0, ty: 0, rotation: 0, sx: 1, sy: 1 }, [extent]: [1, 1], [order]: i });
+});
+
+/** Shows each row's pose: a struct read and written whole per row. */
+const showPose = System.create({ kernel: false, components: { with: [pose, shown] } }, row => { row[shown] = row[pose]; });
+
+/** Commits a pose and an extent per row as commands, values every row already has. */
+const commitPose = System.create({ kernel: true, components: { with: [order] } }, (row, { commands }) => {
+    commands.add(row.entity, pose, { tx: row[order], ty: 1, rotation: 0, sx: 1, sy: 1 });
+    commands.add(row.entity, extent, [2, 2]);
+});
+
+const seeded = async (pool: number): Promise<World> => {
+    const world = createWorld({ [workers]: pool });
+    await world.run(seed, { count: rows });
+    return world;
+};
+
+/** Entities the watching finalizer saw replace a pose, its last sync point. */
+let replacedPoses = 0;
+
+export const valueBenchmarks: readonly Benchmark[] = [
+    {
+        name: "struct copy 100K",
+        operation: "A main-thread row system reading a five-number struct and writing it to another component: a transform shown, copied or edited per row.",
+        per: "rows",
+        n: rows,
+        typical: [1_000, 100_000],
+        best: { bytes: 80, basis: "Each row reads 40 bytes and writes 40." },
+        run: async () => {
+            const world = await seeded(0);
+            const best = await fastest(() => world.run(showPose));
+            await world.dispose();
+            return best;
+        },
+    },
+    {
+        name: "struct replace kernel watched",
+        operation: "As `struct replace kernel main`, with a changes finalizer watching both components: an edit history recording each commit's replaced values.",
+        per: "commands",
+        n: 2 * rows,
+        typical: [1_000, 100_000],
+        best: { bytes: 32, basis: "Each command writes its 40-byte struct or 8-byte vec2 and reads its entity's 8-byte location." },
+        run: async () => {
+            // Program-wide, so made here, in this benchmark's own process.
+            Finalizer.changes({ watch: [pose, extent] }, ({ groups }) => {
+                replacedPoses = 0;
+                for (const group of groups) if (group.replaced.includes(pose)) replacedPoses += group.entities.length;
+            });
+            const world = await seeded(0);
+            const best = await fastest(() => world.run(commitPose));
+            await world.dispose();
+            if (replacedPoses !== rows) throw new Error("struct replace kernel watched: wrong count");
+            return best;
+        },
+    },
+];
+
+/** `struct replace kernel` on the world's thread alone, or on a pool of `pool` workers. */
+export const structReplace = (label: string, pool: number, on?: Best["on"]): Benchmark => ({
+    name: `struct replace kernel ${label}`,
+    operation: "A kernel adding a five-number struct and a vec2 every row already has: a gesture committing its rows' values as commands, so change sets see them.",
+    per: "commands",
+    n: 2 * rows,
+    typical: [1_000, 100_000],
+    best: { bytes: 32, basis: "Each command writes its 40-byte struct or 8-byte vec2 and reads its entity's 8-byte location.", ...on === undefined ? {} : { on } },
+    run: async () => {
+        const world = await seeded(pool);
+        const best = await fastest(() => world.run(commitPose));
+        await world.dispose();
+        return best;
+    },
+});

package/src/perftest/wake.ts

@@ -0,0 +1,41 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { createMemory } from "../implementation/world/memory.js";
+import { createPool, type FastTask } from "../implementation/world/pool.js";
+import { idleKernel } from "../implementation/world/protocol.js";
+import { platformWorkers } from "../implementation/world/worker-platform.js";
+import type { Benchmark } from "./benchmark.js";
+
+/** Round trips in each timed stretch of `wake`. */
+export const wakes = 10_000;
+
+const idle: FastTask = { kernel: idleKernel, archetype: -1, start: 0, end: 0, tick: 0, lastRun: 0, scalars: [], partials: -1, partialBytes: 0 };
+
+/** The fastest of `stretches` stretches of `wakes` round trips to one pool worker waiting in its window, after one to warm up. */
+const wakeRoundTrips = async (stretches = 5): Promise<number> => {
+    const platform = platformWorkers();
+    const port = platform?.start() ?? null;
+    if (port === null) throw new Error("This platform has no workers.");
+    const pool = createPool([port], createMemory(true));
+    let best = Infinity;
+    try {
+        for (let stretch = 0; stretch <= stretches; stretch++) {
+            const start = performance.now();
+            for (let k = 0; k < wakes; k++) await pool.claimed(0, 1, idle, 1)[0];
+            if (stretch > 0) best = Math.min(best, performance.now() - start);
+        }
+    }
+    finally {
+        await pool.terminate();
+    }
+    return best;
+};
+
+export const wake: Benchmark = {
+    name: "wake",
+    operation: "A task posted to a pool worker waiting in its window, which wakes, marks it done and wakes the world's thread: the fixed cost of every tier on workers.",
+    per: "round trips",
+    n: wakes,
+    typical: [1, 100],
+    best: { bytes: 128, basis: "A round trip moves at least the two cache lines of the ring's posted and done words between cores." },
+    run: () => wakeRoundTrips(),
+};

package/src/world.test.ts

@@ -0,0 +1,46 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { System, World, workers } from "./index.js";
+
+const count = Symbol("worldTest/count");
+const total = Symbol("worldTest/total");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [count]: { type: number };
+    }
+    export interface Resources {
+        [total]: { type: number };
+    }
+}
+
+const spawn = System.create({}, ({ commands }) => { commands.spawn([count])({ [count]: 1 }); });
+const raise = System.create({}, ({ resources }) => { resources[total] = 7; });
+const add = System.create({ components: { with: [count] } }, row => { row[count] += 1; });
+
+describe("World.create", () => {
+    it("creates a world from the package root, the one import that names everything else", async () => {
+        await using world = World.create({ [workers]: 0 });
+        await world.run(spawn);
+        await world.run(add);
+        let seen = 0;
+        await world.run(System.create({ observer: true, components: { with: [count] } }, row => { seen = row[count]; }));
+        expect(seen).toBe(2);
+    });
+    it("rejects a key that isn't a resource, as worlds the implementation creates do", () => {
+        expect(() => Reflect.apply(World.create, undefined, [{ [count]: 1 }])).toThrow("isn't a registered resource");
+    });
+});
+
+describe("World.join", () => {
+    it("joins a world another thread shared, from the package root, and runs there", async () => {
+        await using world = World.create({ [workers]: 0 });
+        const channel = new MessageChannel();
+        const shared = world.share(channel.port1);
+        await using joined = await World.join(channel.port2);
+        await shared;
+        await joined.run(raise);
+        let seen = 0;
+        await world.run(System.create({ observer: true }, ({ resources }) => { seen = resources[total]; }));
+        expect(seen).toBe(7);
+    });
+});