@adobe/ecs 0.0.0-stage → 0.2.0

package/src/perftest/editor.ts

@@ -0,0 +1,126 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity } from "../interface/entity/entity.js";
+import { Index } from "../interface/indexes/index-type.js";
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import { createWorld } from "../implementation/index.js";
+import type { Benchmark } from "./benchmark.js";
+
+// A 2D editor loading a document: a tree of groups and leaves, a sorted paint-order index, a hash index of children
+// by parent, and `up` systems with change filters propagating transforms and opacity down the tree.
+
+const localX = Symbol("editor/localX");
+const localY = Symbol("editor/localY");
+const worldX = Symbol("editor/worldX");
+const worldY = Symbol("editor/worldY");
+const opacity = Symbol("editor/opacity");
+const worldOpacity = Symbol("editor/worldOpacity");
+const paintDepth = Symbol("editor/paintDepth");
+const parent = Symbol("editor/parent");
+const group = Symbol("editor/group");
+const shape = Symbol("editor/shape");
+const image = Symbol("editor/image");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [localX]: { type: number };
+        [localY]: { type: number };
+        [worldX]: { type: number };
+        [worldY]: { type: number };
+        [opacity]: { type: number };
+        [worldOpacity]: { type: number };
+        [paintDepth]: { type: number };
+        [parent]: { type: Entity; reference: "owner" };
+        [group]: { type: true };
+        [shape]: { type: true };
+        [image]: { type: true };
+    }
+}
+
+const node = [localX, localY, worldX, worldY, opacity, worldOpacity, paintDepth] as const;
+const Document = [...node, group] as const;
+const Group = [...node, parent, group] as const;
+const Shape = [...node, parent, shape] as const;
+const Image = [...node, parent, image] as const;
+
+const byPaintDepth = Index.create({ key: [paintDepth], sorted: true });
+const childrenOf = Index.create({ key: [parent] });
+
+/** Groups under the document, subgroups in each, and leaves in each subgroup: 50,201 nodes. */
+const groups = 200;
+const subgroups = 2;
+const leaves = 124;
+const nodes = 1 + groups * (1 + subgroups * (1 + leaves));
+
+/** Spawns the document depth first, as a file lists it, its paint depth its place in that order. */
+const load = System.create({}, ({ commands }) => {
+    let depth = 0;
+    const values = (x: number) => ({ [localX]: x, [localY]: 1, [worldX]: 0, [worldY]: 0, [opacity]: 0.99, [worldOpacity]: 1, [paintDepth]: depth++ });
+    const document = commands.spawn(Document)(values(0));
+    for (let g = 0; g < groups; g++) {
+        const outer = commands.spawn(Group)({ ...values(g), [parent]: document, [group]: true });
+        for (let s = 0; s < subgroups; s++) {
+            const inner = commands.spawn(Group)({ ...values(s), [parent]: outer, [group]: true });
+            for (let l = 0; l < leaves; l++) {
+                if (l % 2 === 0) commands.spawn(Shape)({ ...values(l), [parent]: inner, [shape]: true });
+                else commands.spawn(Image)({ ...values(l), [parent]: inner, [image]: true });
+            }
+        }
+    }
+});
+
+/** Each node's world position is its parent's plus its own. */
+const place = System.create({
+    kernel: false,
+    components: { with: [localX, localY, worldX, worldY], changed: [localX, localY] },
+    up: { through: parent },
+}, (row, { up }) => {
+    row[worldX] = (up === null ? 0 : up[worldX]) + row[localX];
+    row[worldY] = (up === null ? 0 : up[worldY]) + row[localY];
+});
+/** Each node's world opacity is its parent's times its own. */
+const fade = System.create({
+    kernel: false,
+    components: { with: [opacity, worldOpacity], changed: [opacity] },
+    up: { through: parent },
+}, (row, { up }) => {
+    row[worldOpacity] = (up === null ? 1 : up[worldOpacity]) * row[opacity];
+});
+let checksum = 0;
+/** Each group counts its children, as a layout does. */
+const layout = System.create({ components: { with: [group] }, lookup: { children: { index: childrenOf } } }, (row, { lookup }) => {
+    checksum += lookup.children(row.entity).length;
+});
+/** Visits every node in paint order, as drawing does. */
+const paint = System.create({ components: { with: [worldX, worldOpacity] }, order: byPaintDepth, after: [place, fade] }, row => {
+    checksum = (checksum * 31 + row[worldX] * row[worldOpacity]) % 1000003;
+});
+const frame = System.create({ systems: [place, fade, layout, paint] });
+
+const check = (condition: boolean, message: string): void => {
+    if (!condition) throw new Error(message);
+};
+
+export const editorBenchmarks: readonly Benchmark[] = [{
+    name: "editor load tick 50K",
+    operation: "A 2D editor's first tick after loading a 50K-node document of groups and leaves: two `up` systems with change filters propagate transforms and opacity down the tree, a layout looks up children through a hash index on the parent, and painting runs in a sorted index's order, so every `up` order and index is built from scratch.",
+    per: "nodes",
+    n: nodes,
+    typical: [1_000, 100_000],
+    best: { bytes: 100, basis: "Each node reads its parent link, its 7 values and its parent's 3, writes 3, and enters two indexes and two orders." },
+    run: async () => {
+        let best = Infinity;
+        for (let i = 0; i < 8; i++) {
+            const world = createWorld({ [workers]: 0 });
+            await world.run(frame);
+            await world.run(load);
+            checksum = 0;
+            const start = performance.now();
+            await world.run(frame);
+            best = Math.min(best, performance.now() - start);
+            check(checksum !== 0, "editor load tick: nothing ran");
+            await world.dispose();
+        }
+        return best;
+    },
+}];
+

package/src/perftest/filters.ts

@@ -0,0 +1,124 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { I32 } from "../interface/math/i32/index.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 } from "./benchmark.js";
+import type { U32 } from "../interface/math/index.js";
+
+// Change filters over one archetype of 100K rows after a writer changed one row, a few, or every one: what finding the
+// rows that pass costs each system that filters, apart from running them.
+
+const value = Symbol("filters/value");
+const other = Symbol("filters/other");
+const at = Symbol("filters/at");
+const out0 = Symbol("filters/out0");
+const out1 = Symbol("filters/out1");
+const out2 = Symbol("filters/out2");
+const out3 = Symbol("filters/out3");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [value]: { type: number };
+        [other]: { type: number };
+        [at]: { type: U32 };
+        [out0]: { type: number };
+        [out1]: { type: number };
+        [out2]: { type: number };
+        [out3]: { type: number };
+    }
+}
+
+const rows = 100_000;
+const filtered = [value, other, at, out0, out1, out2, out3] as const;
+
+const seed = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    for (let i = 0; i < input.count; i++) commands.spawn(filtered)({ [value]: 0, [other]: 0, [at]: i, [out0]: 0, [out1]: 0, [out2]: 0, [out3]: 0 });
+});
+
+/** Writes the value of the rows whose `at` is `first` plus a multiple of `stride`. */
+const write = System.create({
+    kernel: true,
+    components: { with: [at, value] },
+}, (row, _context, input: { readonly first: I32; readonly stride: I32 }) => {
+    const offset = row[at] - input.first;
+    if (offset >= 0 && offset % input.stride === 0) row[value] += 1;
+});
+
+let seen = 0;
+/** Main-thread systems each filtering on `value`'s changes. */
+const readers = System.create({
+    systems: Array.from({ length: 8 }, (_, i) => System.create({ components: { with: [value], changed: [value] } }, row => {
+        seen += row[value];
+    })),
+});
+/** The same filtering on `value`'s or `other`'s changes, of which only `value` is written. */
+const readersOfTwo = System.create({
+    systems: Array.from({ length: 8 }, (_, i) => System.create({ components: { with: [value], changed: [value, other] } }, row => {
+        seen += row[value];
+    })),
+});
+/** Kernels each filtering on `value`'s changes, writing an output of its own. */
+const kernels = System.create({
+    systems: [
+        System.create({ kernel: true, components: { with: [value, out0], changed: [value] } }, row => { row[out0] = row[value] * 2; }),
+        System.create({ kernel: true, components: { with: [value, out1], changed: [value] } }, row => { row[out1] = row[value] * 3; }),
+        System.create({ kernel: true, components: { with: [value, out2], changed: [value] } }, row => { row[out2] = row[value] * 4; }),
+        System.create({ kernel: true, components: { with: [value, out3], changed: [value] } }, row => { row[out3] = row[value] * 5; }),
+    ],
+});
+
+/** The fastest run of `measured` right after a write of every `stride`th row from a moving first row. */
+const afterWrites = async (measured: System, stride: number): Promise<number> => {
+    const world: World = createWorld({ [workers]: 0 });
+    await world.run(seed, { count: rows });
+    await world.run(measured);
+    let best = Infinity;
+    const warm = 20;
+    for (let i = 0; i < warm + 200; i++) {
+        await world.run(write, { first: (i * 7919) % Math.min(stride, rows), stride });
+        const start = performance.now();
+        await world.run(measured);
+        if (i >= warm) best = Math.min(best, performance.now() - start);
+    }
+    await world.dispose();
+    return best;
+};
+
+const cases = [
+    { name: "one", stride: rows * 2, said: "one row changed" },
+    { name: "few", stride: 10_000, said: "ten rows changed, 10,000 apart" },
+    { name: "all", stride: 1, said: "every row changed" },
+] as const;
+
+export const filterBenchmarks: readonly Benchmark[] = [
+    ...cases.map(({ name, stride, said }): Benchmark => ({
+        name: `changed ${name} 100K`,
+        operation: `Eight main-thread systems filtering on \`changed\` over 100K rows after ${said}: views and derived values reacting to edits.`,
+        per: "systems",
+        n: 8,
+        typical: [1, 100],
+        best: { bytes: 0, basis: "Finding the changed rows could cost nothing beyond running them." },
+        run: () => afterWrites(readers, stride),
+    })),
+    {
+        name: "changed one 100K two filters",
+        operation: "Eight main-thread systems filtering on `changed` of two components over 100K rows after one row's first component changed.",
+        per: "systems",
+        n: 8,
+        typical: [1, 100],
+        best: { bytes: 0, basis: "Finding the changed row could cost nothing beyond running it." },
+        run: () => afterWrites(readersOfTwo, rows * 2),
+    },
+    ...cases.map(({ name, stride, said }): Benchmark => ({
+        name: `changed ${name} 100K kernels`,
+        operation: `Four kernels filtering on \`changed\` over 100K rows after ${said}, on the world's thread: derived columns kept current.`,
+        per: "systems",
+        n: 4,
+        typical: [1, 100],
+        best: { bytes: 0, basis: "Finding the changed rows could cost nothing beyond running them." },
+        run: () => afterWrites(kernels, stride),
+    })),
+];
+
+export const seenTotal = (): number => seen;

package/src/perftest/finalized.ts

@@ -0,0 +1,170 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <reference types="node" />
+import { Finalizer } from "../interface/finalizer/finalizer.js";
+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";
+import { runReported } from "../implementation/world/outcomes.test-helper.js";
+import type { Vec3 } from "../interface/math/index.js";
+
+// Despawning entities whose objects a joined thread fills, with a finalizer on that thread: the world's thread writes
+// each stop's declared struct reads into the thread's stop list and doesn't wait for it. The joined thread is
+// `joined.ts`, which imports this module, so it runs the finalizers. A second finalizer, over other entities, reads a
+// string resource too, and a third two linear resources, which each sync point's stop list holds copies of.
+
+const spot = Symbol("finalized/spot");
+const handle = Symbol("finalized/handle");
+const noted = Symbol("finalized/noted");
+const note = Symbol("finalized/note");
+const measured = Symbol("finalized/measured");
+const scale = Symbol("finalized/scale");
+const offset = Symbol("finalized/offset");
+declare module "@adobe/ecs" {
+    export interface Threads {
+        finalizedBenchmark: true;
+    }
+    export interface Components {
+        [spot]: { type: Vec3 };
+        [handle]: { type: { readonly release: () => void } | null; thread: "finalizedBenchmark" };
+        [noted]: { type: { readonly release: () => void } | null; thread: "finalizedBenchmark" };
+        [measured]: { type: { readonly release: () => void } | null; thread: "finalizedBenchmark" };
+    }
+    export interface Resources {
+        [note]: { type: string; default: "released" };
+        [scale]: { type: number; default: 1 };
+        [offset]: { type: Vec3 };
+    }
+}
+/** An object of the joined thread, as a DOM node or a GPU handle is. */
+
+/** Entities each timed sync point despawns. */
+export const despawnedObjects = 10_000;
+
+/** On the joined thread: what the finalizer released. */
+export const releases = { count: 0 };
+export const release = Finalizer.create({ components: { with: [handle, spot] } }, row => {
+    row[handle]?.release();
+    if (row[spot][0] >= 0) releases.count++;
+});
+
+/** On the joined thread: the same, reading the world's string resource too. */
+export const releaseNoted = Finalizer.create({ components: { with: [noted, spot] } }, (row, { resources }) => {
+    row[noted]?.release();
+    if (row[spot][0] >= 0 && resources[note].length > 0) releases.count++;
+});
+
+/** On the joined thread: the same, reading two linear resources of the world's too. */
+export const releaseMeasured = Finalizer.create({ components: { with: [measured, spot] } }, (row, { resources }) => {
+    row[measured]?.release();
+    if (row[spot][0] * resources[scale] + resources[offset][0] >= 0) releases.count++;
+});
+
+const spawn = System.create({}, ({ commands }) => {
+    for (let k = 0; k < despawnedObjects; k++) commands.spawn([spot, handle])({ [spot]: [k, 0, 0], [handle]: null });
+});
+const despawn = System.create({ kernel: false, components: { with: [handle, spot] } }, (row, { commands }) => {
+    commands.despawn(row.entity);
+});
+const spawnNoted = System.create({}, ({ commands }) => {
+    for (let k = 0; k < despawnedObjects; k++) commands.spawn([spot, noted])({ [spot]: [k, 0, 0], [noted]: null });
+});
+const spawnMeasured = System.create({}, ({ commands }) => {
+    for (let k = 0; k < despawnedObjects; k++) commands.spawn([spot, measured])({ [spot]: [k, 0, 0], [measured]: null });
+});
+const despawnMeasured = System.create({ kernel: false, components: { with: [measured, spot] } }, (row, { commands }) => {
+    commands.despawn(row.entity);
+});
+const despawnNoted = System.create({ kernel: false, components: { with: [noted, spot] } }, (row, { commands }) => {
+    commands.despawn(row.entity);
+});
+
+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: ["finalizedBenchmark"] });
+    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 `rounds` sync points despawning `despawnedObjects` entities holding the joined thread's objects,
+ * timed on the world's thread, each after a spawn and a pause in which the thread finalizes the last.
+ */
+const despawnObjects = async (spawning: typeof spawn = spawn, despawning: typeof despawn = despawn, rounds = 30): Promise<number> => {
+    const world = createWorld({ [workers]: 0 });
+    const joined = await startClaiming(world);
+    let best = Infinity;
+    try {
+        for (let round = 0; round < rounds; round++) {
+            await world.run(spawning);
+            const start = performance.now();
+            const report = await runReported(world, despawning);
+            const time = performance.now() - start;
+            if (report.failures.length > 0) throw new Error(`despawn objects: ${report.failures[0].message}`);
+            if (round > 1) best = Math.min(best, time);
+            // The thread finalizes them and acknowledges, so the next sync point returns their indexes.
+            await new Promise(resolve => setTimeout(resolve, 5));
+        }
+    }
+    finally {
+        // Disposed first: ticks after the thread ended would fail its systems, reported out of band.
+        await world.dispose();
+        await joined.terminate();
+    }
+    return best;
+};
+
+export const finalizedBenchmarks: readonly Benchmark[] = [
+    {
+        name: "despawn objects 10K",
+        operation: "A sync point despawning 10K entities whose objects a joined worker fills, with a finalizer there reading the object and a vec3: releasing DOM nodes or GPU handles, which the world's thread doesn't wait for.",
+        per: "despawns",
+        n: despawnedObjects,
+        typical: [1, 10_000],
+        best: { bytes: 56, basis: "Each despawn frees its 8-byte location and entity, and writes its stop: its entity, archetype, row and tag, 20 bytes, and its 12-byte vec3, read and written." },
+        run: () => despawnObjects(),
+    },
+    {
+        name: "despawn objects 10K string resource",
+        operation: "`despawn objects 10K` with the finalizer reading a string resource too, whose record the sync point's stop list holds a copy of, so the thread reads it as it was before apply.",
+        per: "despawns",
+        n: despawnedObjects,
+        typical: [1, 10_000],
+        best: { bytes: 56, basis: "As `despawn objects 10K`: the resource's copy is once per sync point." },
+        run: () => despawnObjects(spawnNoted, despawnNoted),
+    },
+    {
+        name: "despawn objects 10K linear resource",
+        operation: "`despawn objects 10K` with the finalizer reading a number and a vec3 resource too, which the sync point's stop list holds copies of, so the thread reads them as they were before apply.",
+        per: "despawns",
+        n: despawnedObjects,
+        typical: [1, 10_000],
+        best: { bytes: 56, basis: "As `despawn objects 10K`: the resources' copies are once per sync point." },
+        run: () => despawnObjects(spawnMeasured, despawnMeasured),
+    },
+];

package/src/perftest/flat.ts

@@ -0,0 +1,57 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System } from "../interface/system/system.js";
+import type { F32, U32 } from '../interface/math/index.js';
+
+// Mirrors adobe/data's ecs2 `create` perftest (packages/data/src/perftest/ecs2-perf.ts): 1M particles of eight scalar
+// components, interleaved over four archetypes by visible/enabled, each with its own values.
+
+const color = Symbol("flat/color");
+const mass = Symbol("flat/mass");
+const positionX = Symbol("flat/positionX");
+const positionY = Symbol("flat/positionY");
+const positionZ = Symbol("flat/positionZ");
+const velocityX = Symbol("flat/velocityX");
+const velocityY = Symbol("flat/velocityY");
+const velocityZ = Symbol("flat/velocityZ");
+export const visible = Symbol("flat/visible");
+export const enabled = Symbol("flat/enabled");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [color]: { type: U32 };
+        [mass]: { type: F32 };
+        [positionX]: { type: F32 };
+        [positionY]: { type: F32 };
+        [positionZ]: { type: F32 };
+        [velocityX]: { type: F32 };
+        [velocityY]: { type: F32 };
+        [velocityZ]: { type: F32 };
+        [visible]: { type: true };
+        [enabled]: { type: true };
+    }
+}
+
+
+const scalars = [color, mass, positionX, positionY, positionZ, velocityX, velocityY, velocityZ] as const;
+/** Entity i goes to archetype i % 4, like ecs2's seedSingle. */
+const archetypes = [
+    [...scalars, visible, enabled] as const,
+    [...scalars, visible] as const,
+    [...scalars, enabled] as const,
+    scalars,
+] as const;
+
+/** Spawns with values passed inline. */
+export const spawnFlat = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    for (let i = 0; i < input.count; i++) {
+        commands.spawn(archetypes[i % 4])({ [color]: 0xff00ff, [mass]: 10, [positionX]: i + 1, [positionY]: i + 1, [positionZ]: i + 1, [velocityX]: -i, [velocityY]: -i, [velocityZ]: -i });
+    }
+});
+
+/** The same spawns with each value object built first, as values from data or from another system's results are. */
+export const spawnFlatDynamic = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    for (let i = 0; i < input.count; i++) {
+        const values = { [color]: 0xff00ff, [mass]: 10, [positionX]: i + 1, [positionY]: i + 1, [positionZ]: i + 1, [velocityX]: -i, [velocityY]: -i, [velocityZ]: -i };
+        commands.spawn(archetypes[i % 4])(values);
+    }
+});

package/src/perftest/growth.ts

@@ -0,0 +1,47 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System } from "../interface/system/system.js";
+import type { F32 } from "../interface/math/index.js";
+
+// A hundred archetypes, each grown at once: what a sync point costs where every archetype it touches grows.
+
+const value = Symbol("growth/value");
+const g0 = Symbol("growth/g0");
+const g1 = Symbol("growth/g1");
+const g2 = Symbol("growth/g2");
+const g3 = Symbol("growth/g3");
+const g4 = Symbol("growth/g4");
+const g5 = Symbol("growth/g5");
+const g6 = Symbol("growth/g6");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [value]: { type: F32 };
+        [g0]: { type: true };
+        [g1]: { type: true };
+        [g2]: { type: true };
+        [g3]: { type: true };
+        [g4]: { type: true };
+        [g5]: { type: true };
+        [g6]: { type: true };
+    }
+}
+
+
+const tags = [g0, g1, g2, g3, g4, g5, g6] as const;
+/** `value` with each of the first 100 sets of the seven tags, by their bits. */
+const hundred = Array.from({ length: 100 }, (_, bits) => [value, ...tags.filter((_, bit) => (bits & (1 << bit)) !== 0)] as const);
+
+/** Spawns `count` entities into each of the hundred archetypes. */
+export const fillEach = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    for (const archetype of hundred) for (let i = 0; i < input.count; i++) commands.spawn(archetype)({ [value]: i });
+});
+
+/** One spawn into each of the hundred archetypes. */
+export const spawnEach = System.create({}, ({ commands }) => {
+    for (const archetype of hundred) commands.spawn(archetype)({ [value]: 0 });
+});
+
+/** A kernel over every row of the hundred archetypes. */
+export const bumpEach = System.create({ kernel: true, components: { with: [value] } }, row => {
+    row[value] = row[value] + 1;
+});

package/src/perftest/handoff.ts

@@ -0,0 +1,147 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <reference types="node" />
+import { always } from "../interface/resources/always.js";
+import { eachTick } from "./observer.js";
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import { backToBack, createWorld, type CreatedWorld } from "../implementation/index.js";
+import type { Benchmark } from "./benchmark.js";
+import { runReported } from "../implementation/world/outcomes.test-helper.js";
+
+// Benchmarks of systems on a joined thread, which claims "handoffBenchmark": tiers handing off between the world's
+// thread and the joined one, and consecutive tiers on the joined one, which run as one task. Their systems reach their
+// commands, so they block their tiers rather than run as tails. The joined thread is `joined.ts`.
+
+export const token = Symbol("handoff/token");
+declare module "@adobe/ecs" {
+    export interface Threads {
+        handoffBenchmark: true;
+    }
+    export interface Resources {
+        [token]: { type: { readonly read: () => number } | null; thread: "handoffBenchmark" };
+    }
+}
+/** An object of the joined thread, which places the systems reading it there. */
+
+const here0 = System.create({}, () => {});
+const there0 = System.create({ after: [here0] }, ({ resources, commands }) => { void resources[token]; void commands; });
+const here1 = System.create({ after: [there0] }, () => {});
+const there1 = System.create({ after: [here1] }, ({ resources, commands }) => { void resources[token]; void commands; });
+const here2 = System.create({ after: [there1] }, () => {});
+const there2 = System.create({ after: [here2] }, ({ resources, commands }) => { void resources[token]; void commands; });
+const here3 = System.create({ after: [there2] }, () => {});
+const there3 = System.create({ after: [here3] }, ({ resources, commands }) => { void resources[token]; void commands; });
+const here4 = System.create({ after: [there3] }, () => {});
+const there4 = System.create({ after: [here4] }, ({ resources, commands }) => { void resources[token]; void commands; });
+/** Ten tiers alternating the world's thread and the joined one, empty systems. */
+export const handoff = System.create({ systems: [here0, there0, here1, there1, here2, there2, here3, there3, here4, there4] });
+
+const fused0 = System.create({}, ({ resources, commands }) => { void resources[token]; void commands; });
+const fused1 = System.create({ after: [fused0] }, ({ resources, commands }) => { void resources[token]; void commands; });
+const fused2 = System.create({ after: [fused1] }, ({ resources, commands }) => { void resources[token]; void commands; });
+const fused3 = System.create({ after: [fused2] }, ({ resources, commands }) => { void resources[token]; void commands; });
+const fused4 = System.create({ after: [fused3] }, ({ resources, commands }) => { void resources[token]; void commands; });
+const fused5 = System.create({ after: [fused4] }, ({ resources, commands }) => { void resources[token]; void commands; });
+const fused6 = System.create({ after: [fused5] }, ({ resources, commands }) => { void resources[token]; void commands; });
+const fused7 = System.create({ after: [fused6] }, ({ resources, commands }) => { void resources[token]; void commands; });
+const fused8 = System.create({ after: [fused7] }, ({ resources, commands }) => { void resources[token]; void commands; });
+const fused9 = System.create({ after: [fused8] }, ({ resources, commands }) => { void resources[token]; void commands; });
+/** Ten consecutive tiers on the joined thread, empty systems. */
+export const fused = System.create({ systems: [fused0, fused1, fused2, fused3, fused4, fused5, fused6, fused7, fused8, fused9] });
+
+/** Every system the joined thread runs, which it imports so the world can place them there. */
+export const handoffSystems: readonly System<void>[] = [handoff, fused];
+
+/** Ticks in each timed stretch. */
+export const handoffTicks = 1_000;
+
+/** The joined thread, `joined.ts` on a worker, asked to join through a port and claim "handoffBenchmark". */
+type Joined = { readonly terminate: () => Promise<void> };
+
+const joinedFile = "./joined.js";
+
+/** Starts `joined.ts` on a worker, joining `world` through a channel it's given and claiming the benchmark's thread. */
+const startClaiming = async (world: CreatedWorld): Promise<Joined> => {
+    const message = (port: unknown) => ({ kind: "port", port, threads: ["handoffBenchmark"] });
+    let joined: Joined;
+    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]);
+        });
+        joined = { 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]);
+        });
+        joined = { terminate: async () => { await worker.terminate(); } };
+    }
+    // Its claims are active once it joined, so the systems run there from the first tick.
+    await shared;
+    return joined;
+};
+
+/** The fastest of `stretches` stretches of `handoffTicks` ticks of `system`, driven back to back, after one to warm up. */
+const ticksBest = async (system: System<void>, 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 new Promise<void>(resolve => {
+            let ticks = 0;
+            let stretch = 0;
+            let start = 0;
+            const unobserve = eachTick(world, () => {
+                if (ticks++ % handoffTicks !== 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(system);
+        });
+        const report = await runReported(world, system);
+        if (report.failures.length > 0 || report.warnings.length === 0) throw new Error(`handoff: the joined thread didn't run its systems: ${report.failures[0]?.message ?? "none placed there"}.`);
+    }
+    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;
+};
+
+export const handoffBenchmarks: readonly Benchmark[] = [
+    {
+        name: "handoff",
+        operation: "Ticks of ten tiers alternating the world's thread and a joined worker, empty systems: five tasks posted and waited for each tick, as when systems that write a worker's objects sit between the world's.",
+        per: "ticks",
+        n: handoffTicks,
+        typical: [1, 1],
+        best: { bytes: 5 * 256, basis: "Each of five handoffs moves at least the task's posted, done, payload and completion lines between cores." },
+        run: () => ticksBest(handoff),
+    },
+    {
+        name: "fused tiers",
+        operation: "Ticks of ten consecutive tiers on a joined worker, empty systems, which run as one task: a worker filling objects whose systems follow one another.",
+        per: "ticks",
+        n: handoffTicks,
+        typical: [1, 1],
+        best: { bytes: 256, basis: "One task moves at least its posted, done, payload and completion lines between cores." },
+        run: () => ticksBest(fused),
+    },
+];