@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/world/buffer.ts

@@ -0,0 +1,176 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { viewsOf, type Layout, type Views } from '../../interface/registry/layout.js';
+import type { KernelCommands } from './kernel.js';
+import type { Positional, SpawnBatch } from './staging.js';
+
+export const spawnCommand = 0;
+export const despawnCommand = 1;
+export const addCommand = 2;
+export const removeCommand = 3;
+
+/** Rows `start` to `end` of a kernel's spawn batch, committed in its buffer's place in merge order. */
+export type Staged = { batch: SpawnBatch; start: number; end: number };
+
+/**
+ * Commands as parallel arrays with explicit counts, reused between runs, so issuing a command allocates nothing.
+ * Command `c` names components `ids[starts[c]]` up to the next command's start, with `values` alongside (unused for
+ * `remove`). A buffer drained from a worker's command ring keeps its structs' values as bytes in the ring, in their
+ * storages' layout, at `offsets` into `bytes`. A kernel's spawns are staged in batches instead, and its buffer lists
+ * their rows in `staged`, which the sync point commits before any command.
+ */
+export type CommandBuffer = {
+    count: number;
+    kinds: Uint8Array;
+    /** By command: the list of components a list add or remove names, by its index among the world's lists, or -1. */
+    shapes: Int32Array;
+    entities: Float64Array;
+    starts: Int32Array;
+    /** Components named so far, across commands. */
+    named: number;
+    ids: Int32Array;
+    readonly values: unknown[];
+    /** For a drained buffer, where its values' bytes are; null for a buffer of values alone. */
+    bytes: Views | null;
+    /** With `bytes`, by component named: its value's first byte there, or -1 for a value in `values`. */
+    offsets: Int32Array;
+    /** The first `stagedCount` entries are this buffer's; the rest are kept for reuse. */
+    readonly staged: Staged[];
+    stagedCount: number;
+};
+
+export const createBuffer = (capacity = 16): CommandBuffer => ({
+    count: 0,
+    kinds: new Uint8Array(capacity),
+    shapes: new Int32Array(capacity),
+    entities: new Float64Array(capacity),
+    starts: new Int32Array(capacity),
+    named: 0,
+    ids: new Int32Array(capacity * 4),
+    values: [],
+    bytes: null,
+    offsets: new Int32Array(0),
+    staged: [],
+    stagedCount: 0,
+});
+
+/** No commands; never written. */
+export const emptyBuffer: CommandBuffer = createBuffer(0);
+
+export const clearBuffer = (buffer: CommandBuffer): void => {
+    // Releases values for collection; the arrays keep their storage for the next run.
+    buffer.values.fill(undefined, 0, buffer.named);
+    buffer.bytes = null;
+    buffer.count = 0;
+    buffer.named = 0;
+    buffer.stagedCount = 0;
+};
+
+/** Adds rows `start` to `end` of a batch to the buffer's staged spawns. */
+export const stage = (buffer: CommandBuffer, batch: SpawnBatch, start: number, end: number): void => {
+    const entry = buffer.staged[buffer.stagedCount];
+    if (entry === undefined) buffer.staged.push({ batch, start, end });
+    else {
+        entry.batch = batch;
+        entry.start = start;
+        entry.end = end;
+    }
+    buffer.stagedCount++;
+};
+
+const grown = <T extends Uint8Array | Float64Array | Int32Array>(array: T, create: (length: number) => T): T => {
+    const larger = create(array.length * 2);
+    larger.set(array);
+    return larger;
+};
+
+/** Starts a command; name its components with `pushComponent` right after. */
+/** Room for more commands: outlined, so `pushCommand` stays small enough to inline into the systems issuing them. */
+const growCommands = (buffer: CommandBuffer): void => {
+    buffer.kinds = grown(buffer.kinds, length => new Uint8Array(length));
+    buffer.shapes = grown(buffer.shapes, length => new Int32Array(length));
+    buffer.entities = grown(buffer.entities, length => new Float64Array(length));
+    buffer.starts = grown(buffer.starts, length => new Int32Array(length));
+};
+
+export const pushCommand = (buffer: CommandBuffer, kind: number, entity: number): void => {
+    if (buffer.count === buffer.kinds.length) growCommands(buffer);
+    buffer.kinds[buffer.count] = kind;
+    buffer.shapes[buffer.count] = -1;
+    buffer.entities[buffer.count] = entity;
+    buffer.starts[buffer.count] = buffer.named;
+    buffer.count++;
+};
+
+/** Room for more component ids, outlined as `growCommands` is. */
+const growIds = (buffer: CommandBuffer): void => {
+    buffer.ids = grown(buffer.ids, length => new Int32Array(length));
+};
+
+export const pushComponent = (buffer: CommandBuffer, id: number, value: unknown): void => {
+    if (buffer.named === buffer.ids.length) growIds(buffer);
+    buffer.ids[buffer.named] = id;
+    buffer.values[buffer.named] = value;
+    buffer.named++;
+};
+
+/** A component value read out of bytes in a general layout, copied to row 0 here first; grown for larger layouts. */
+let scratch = viewsOf(new ArrayBuffer(256), 0, 256);
+
+/** Component `k`'s value: as given, or decoded from its bytes. */
+export const valueAt = (buffer: CommandBuffer, k: number, layouts: readonly Layout[]): unknown => {
+    const { bytes } = buffer;
+    if (bytes === null || buffer.offsets[k] < 0) return buffer.values[k];
+    const layout = layouts[buffer.ids[k]];
+    if (layout.kind !== "linear") return undefined;
+    const { stride } = layout;
+    if (stride > scratch.u8.length) scratch = viewsOf(new ArrayBuffer(stride * 2), 0, stride * 2);
+    const offset = buffer.offsets[k];
+    scratch.u8.set(bytes.u8.subarray(offset, offset + stride));
+    return layout.read(scratch, 0);
+};
+
+/** Component `k`'s value as a reference, an entity: one f64 in its bytes. */
+export const referenceAt = (buffer: CommandBuffer, k: number): number => {
+    const { bytes } = buffer;
+    return bytes === null || buffer.offsets[k] < 0 ? Number(buffer.values[k]) : bytes.f64[buffer.offsets[k] >> 3];
+};
+
+export const endOf = (buffer: CommandBuffer, command: number): number =>
+    command + 1 < buffer.count ? buffer.starts[command + 1] : buffer.named;
+
+/**
+ * Commands for a kernel, writing straight into a buffer: `ids` maps the kernel's key indexes to component ids, and
+ * `starts` to what each starts at, written for an `undefined` value. `target.buffer` may be replaced between calls.
+ * `spawners` stage the kernel's spawns, by spawn list.
+ */
+export const createKernelCommands = (target: { readonly buffer: CommandBuffer }, ids: readonly number[], starts: readonly unknown[], spawners: readonly Positional[]): KernelCommands => ({
+    spawners,
+    // Each writes the buffer itself rather than through pushCommand and pushComponent: a kernel's row loop inlines one
+    // call, and a second one left as a call boxes every entity, which ids past 2^32 make a double.
+    begin: (kind, entity) => {
+        const buffer = target.buffer;
+        const count = buffer.count;
+        if (count === buffer.kinds.length) growCommands(buffer);
+        buffer.kinds[count] = kind;
+        buffer.shapes[count] = -1;
+        buffer.entities[count] = entity;
+        buffer.starts[count] = buffer.named;
+        buffer.count = count + 1;
+    },
+    value: (key, value) => {
+        const buffer = target.buffer;
+        const named = buffer.named;
+        if (named === buffer.ids.length) growIds(buffer);
+        buffer.ids[named] = ids[key];
+        buffer.values[named] = value === undefined ? starts[key] : value;
+        buffer.named = named + 1;
+    },
+    component: key => {
+        const buffer = target.buffer;
+        const named = buffer.named;
+        if (named === buffer.ids.length) growIds(buffer);
+        buffer.ids[named] = ids[key];
+        buffer.values[named] = undefined;
+        buffer.named = named + 1;
+    },
+});

package/src/implementation/world/builtins.test.ts

@@ -0,0 +1,87 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Mat4x4, Quat, Vec3 } from "../../interface/math/index.js";
+import { System } from "../../interface/system/system.js";
+import { readEach, select } from "./reads.test-helper.js";
+import { createWorld } from "./create.js";
+import { workers } from "../../interface/resources/workers.js";
+
+const position = Symbol("builtinsTest/position");
+const velocity = Symbol("builtinsTest/velocity");
+const bits = Symbol("builtinsTest/bits");
+const counts = Symbol("builtinsTest/counts");
+const sums = Symbol("builtinsTest/sums");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: Vec3 };
+        [velocity]: { type: Vec3 };
+        [bits]: { type: Vec3.U32 };
+        [counts]: { type: Vec3.U32 };
+        [sums]: { type: Vec3.I32 };
+    }
+}
+
+
+const spawn = System.create({}, ({ commands }) => {
+    for (let i = 0; i < 64; i++) commands.spawn([position, velocity])({ [position]: [i, i % 5, -i], [velocity]: [1, 0.5 * (i % 3), 0.25] });
+});
+
+const rotation = Quat.fromAxisAngle([0, 1, 0], 0.5);
+const matrix = Mat4x4.multiply(Mat4x4.translation(1, 2, 3), Mat4x4.scaling(2, 2, 2));
+
+/** Rotates, transforms and offsets each position, with functions from three math namespaces inlined. */
+const transform = System.create({ kernel: true, 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]));
+});
+
+const expected = (p: Vec3, v: Vec3): Vec3 => Vec3.add(Mat4x4.multiplyVec3(matrix, Quat.rotateVec3(rotation, p)), Vec3.normalize(v));
+
+const bitsAt = (i: number): Vec3.U32 => [Math.imul(i + 1, 0x9E3779B9) >>> 0, (0xFFFFFFFF - i) >>> 0, i << 26 >>> 0];
+const sumsAt = (i: number): Vec3.I32 => [2 ** 31 - 1 - i, -(2 ** 31) + i, Math.imul(i, 65536)];
+
+const spawnBits = System.create({}, ({ commands }) => {
+    for (let i = 0; i < 64; i++) commands.spawn([bits, counts, sums])({ [bits]: bitsAt(i), [counts]: [0, 0, 0], [sums]: sumsAt(i) });
+});
+
+/** Integer functions that wrap, and bit functions without loops. */
+const integerResults = (b: Vec3.U32, s: Vec3.I32): { readonly counts: Vec3.U32; readonly sums: Vec3.I32 } => ({
+    counts: Vec3.U32.add(Vec3.U32.countOneBits(b), Vec3.U32.add(Vec3.U32.countTrailingZeros(b), Vec3.U32.multiply(Vec3.U32.reverseBits(b), b))),
+    sums: Vec3.I32.add(Vec3.I32.multiply(s, [65536, 3, 65536]), Vec3.I32.abs(Vec3.I32.negate(s))),
+});
+
+const integers = System.create({ kernel: true, components: { with: [bits, counts, sums] } }, row => {
+    const b = row[bits];
+    const s = row[sums];
+    row[counts] = Vec3.U32.add(Vec3.U32.countOneBits(b), Vec3.U32.add(Vec3.U32.countTrailingZeros(b), Vec3.U32.multiply(Vec3.U32.reverseBits(b), b)));
+    row[sums] = Vec3.I32.add(Vec3.I32.multiply(s, [65536, 3, 65536]), Vec3.I32.abs(Vec3.I32.negate(s)));
+});
+
+describe("math in kernels", () => {
+    for (const wasm of [false, true]) {
+        it(`matches the functions called directly (${wasm ? "WASM" : "JS"})`, async () => {
+            const world = createWorld({ [workers]: 0 }, { wasm });
+            await world.run(spawn);
+            await world.run(transform);
+            const read = await readEach(world, await select(world, { required: [position] }), position);
+            const want = Array.from({ length: 64 }, (_, i) => expected([i, i % 5, -i], [1, 0.5 * (i % 3), 0.25]));
+            // Stored as f32, so compared at f32 precision.
+            expect(read.map(value => value?.map(Math.fround))).toEqual(want.map(value => value.map(Math.fround)));
+            await world.dispose();
+        });
+    }
+    for (const wasm of [false, true]) {
+        it(`wraps integers and counts bits as the functions do (${wasm ? "WASM" : "JS"})`, async () => {
+            const world = createWorld({ [workers]: 0 }, { wasm });
+            await world.run(spawnBits);
+            await world.run(integers);
+            const entities = await select(world, { required: [bits] });
+            const want = Array.from({ length: 64 }, (_, i) => integerResults(bitsAt(i), sumsAt(i)));
+            expect(await readEach(world, entities, counts)).toEqual(want.map(value => value.counts));
+            expect(await readEach(world, entities, sums)).toEqual(want.map(value => value.sums));
+            await world.dispose();
+        });
+    }
+});

package/src/implementation/world/cascade.ts

@@ -0,0 +1,145 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Archetype } from './archetype.js';
+import { readCell } from './cells.js';
+import { indexOf, locate } from './entities.js';
+import { commandValue, isMissing } from './finalizers.js';
+import { createHolders, fitHolders, forEachHolder, linkHolder, unlinkHolder } from './holders.js';
+import { closureOf, owner } from './structure.js';
+import { archetypeOf, withoutComponent, type State } from './state.js';
+import type { Queued } from './synchronize.js';
+
+/**
+ * A reference value written in this sync point: by spawn or add commands, or a batch spawn. `holder`, `component`
+ * and `target` triples, checked once the plan's despawns are known.
+ */
+export type Written = number[];
+
+/** The entry for a live entity, added unchanged if it has none; -1 for one that isn't alive or planned. */
+export type EntryOf = (entity: number) => number;
+
+/** The value an entity holds for `component` once the plan applies, or undefined if it won't hold one. */
+const finalValue = (state: State, queued: readonly Queued[], holder: number, component: number): unknown => {
+    const { plan, entities, archetypes } = state;
+    const entry = plan.slots[indexOf(holder)] ?? -1;
+    if (entry >= 0 && plan.entity[entry] === holder) {
+        if (plan.despawned[entry] === 1 || archetypes[plan.to[entry]].storageById[component] === undefined) return undefined;
+        const value = commandValue(state, queued, entry, component);
+        if (!isMissing(value)) return value;
+    }
+    const index = locate(entities, holder);
+    if (index < 0) return undefined;
+    const storage = archetypes[entities.archetype[index]].storageById[component];
+    return storage === undefined ? undefined : readCell(storage, entities.row[index]);
+};
+
+/** Whether `target` is alive once the plan applies: live or spawned here, and not despawned. */
+const aliveAfter = (state: State, target: number): boolean => {
+    const { plan, entities } = state;
+    const index = indexOf(target);
+    const entry = index < plan.slots.length ? plan.slots[index] : -1;
+    if (entry >= 0 && plan.entity[entry] === target) return plan.despawned[entry] === 0;
+    return locate(entities, target) >= 0;
+};
+
+/**
+ * Despawns the holders that own a reference to an entity that is despawned or never lives, and removes `weak`
+ * references to one, transitively, before rules close the plan. A holder acts only if its value once the plan applies
+ * names the target, so a reference pointed elsewhere in the same sync point is left alone.
+ */
+export const cascadeReferences = (state: State, queued: readonly Queued[], written: Written, entryOf: EntryOf): void => {
+    const { plan, structure, archetypes } = state;
+    const despawned: number[] = [];
+    for (let entry = 0; entry < plan.count; entry++) if (plan.despawned[entry] === 1) despawned.push(plan.entity[entry]);
+    const act = (holder: number, component: number): void => {
+        const entry = entryOf(holder);
+        if (entry < 0 || plan.despawned[entry] === 1) return;
+        if (structure.references[component] === owner) {
+            plan.despawned[entry] = 1;
+            despawned.push(holder);
+            return;
+        }
+        const to = withoutComponent(state, archetypes[plan.to[entry]], component);
+        plan.to[entry] = closureOf(structure, state.derived, to, (components, shared) => archetypeOf(state, components, shared), archetypes).id;
+    };
+    let checked = 0;
+    for (let next = 0; next < despawned.length || checked < written.length;) {
+        for (; next < despawned.length; next++) {
+            const target = despawned[next];
+            for (const component of structure.referenceIds) {
+                const lists = structure.holders[component];
+                if (lists === undefined) continue;
+                forEachHolder(lists, target, holder => {
+                    if (finalValue(state, queued, holder, component) === target) act(holder, component);
+                });
+            }
+        }
+        // A reference written here to an entity that won't be alive is as dangling as one whose target despawns.
+        for (; checked < written.length; checked += 3) {
+            const holder = written[checked];
+            const component = written[checked + 1];
+            const target = written[checked + 2];
+            // `Entity.none` names no entity, so a reference to it isn't dangling.
+            if (target !== 0 && finalValue(state, queued, holder, component) === target && !aliveAfter(state, target)) act(holder, component);
+        }
+    }
+};
+
+/**
+ * The changes the plan makes to the holder index, read before it applies, while old and new values are both readable:
+ * `remove` and `add` as target, holder, component triples. A despawned target's holders each have a removal of their
+ * own, since every reference component despawns its holders or drops the reference.
+ */
+export type IndexChanges = { readonly remove: number[]; readonly add: number[] };
+
+export const indexChangesOf = (state: State, queued: readonly Queued[], fromOf: (entry: number) => Archetype | null, bornRows: readonly (readonly [Archetype, number])[]): IndexChanges => {
+    const { plan, structure, entities } = state;
+    const changes: IndexChanges = { remove: [], add: [] };
+    for (let entry = 0; entry < plan.count; entry++) {
+        const holder = plan.entity[entry];
+        const from = fromOf(entry);
+        for (const component of structure.referenceIds) {
+            const storage = from?.storageById[component];
+            const before = storage === undefined ? undefined : readCell(storage, entities.row[indexOf(holder)]);
+            const after = plan.despawned[entry] === 1 ? undefined : finalValue(state, queued, holder, component);
+            if (before === after) continue;
+            if (typeof before === "number" && before !== 0) changes.remove.push(before, holder, component);
+            if (typeof after === "number" && after !== 0) changes.add.push(after, holder, component);
+        }
+    }
+    // Batch spawns no command touched still hold the references they were spawned with. An entity is one f64.
+    const { slots } = plan;
+    for (const [archetype, first] of bornRows) {
+        for (const component of structure.referenceIds) {
+            const storage = archetype.storageById[component];
+            if (storage === undefined) continue;
+            const { unitStride, unitOffset } = storage;
+            const values = storage.views.f64;
+            const rows = archetype.entities;
+            for (let row = first; row < archetype.count; row++) {
+                const holder = rows[row];
+                const index = indexOf(holder);
+                if (index < slots.length && slots[index] >= 0) continue;
+                const value = values[row * unitStride + unitOffset];
+                if (value !== 0) changes.add.push(value, holder, component);
+            }
+        }
+    }
+    return changes;
+};
+
+/** Applies index changes after the plan applies. */
+export const applyIndexChanges = (state: State, changes: IndexChanges): void => {
+    const { holders } = state.structure;
+    const { remove, add } = changes;
+    for (let c = 0; c < remove.length; c += 3) {
+        const lists = holders[remove[c + 2]];
+        if (lists !== undefined) unlinkHolder(lists, remove[c], remove[c + 1]);
+    }
+    const length = state.entities.length;
+    for (let c = 0; c < add.length; c += 3) {
+        const component = add[c + 2];
+        const lists = holders[component] ??= createHolders();
+        fitHolders(lists, length);
+        linkHolder(lists, add[c], add[c + 1]);
+    }
+};

package/src/implementation/world/cells.ts

@@ -0,0 +1,25 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Storage } from './archetype.js';
+import { readString, writeString } from './strings.js';
+
+/** Where a value is: a storage, or a joined thread's view of one. */
+export type Cell = Pick<Storage, "layout" | "views" | "values" | "strings">;
+
+/** A component value, copied out of linear storage. */
+export const readCell = (storage: Cell, row: number): unknown => {
+    const { layout } = storage;
+    switch (layout.kind) {
+        case "linear": return layout.read(storage.views, row);
+        case "string": return readString(storage, row);
+        case "object": return storage.values[row];
+        default: return layout.value;
+    }
+};
+
+/** Replaces a component value. Doesn't touch ticks. */
+export const writeCell = (storage: Cell, row: number, value: unknown): void => {
+    const { layout } = storage;
+    if (layout.kind === "linear") layout.write(storage.views, row, value);
+    else if (layout.kind === "string") writeString(storage, row, value);
+    else if (layout.kind === "object") storage.values[row] = value;
+};

package/src/implementation/world/change-blocks.browser.test.ts

@@ -0,0 +1,76 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+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, join } from "./create.js";
+import type { F32, U32 } from "../../interface/math/index.js";
+import { gpu } from "./gpu.test-helper.js";
+
+// A GPU kernel stamps a whole column once; before a joined thread's systems filter on it, its rows, chunks and blocks
+// take the stamp, so the thread's change filters find every row, and then only rows written after.
+
+const value = Symbol("changeBlocksGpuTest/value");
+const at = Symbol("changeBlocksGpuTest/at");
+const note = Symbol("changeBlocksGpuTest/note");
+
+declare module "@adobe/ecs" {
+    interface Threads {
+        changeBlocksGpuTest: true;
+    }
+    interface Components {
+        [value]: { type: F32 };
+        [at]: { type: U32 };
+        [note]: { type: { readonly text: string } | null; thread: "changeBlocksGpuTest"; default: { text: "none" } };
+    }
+}
+const text = { type: "object", properties: { text: { type: "string" } } } as const;
+
+const rows = 4500;
+let entities: Entity[] = [];
+const seed = System.create({}, ({ commands }) => {
+    entities = [];
+    for (let i = 0; i < rows; i++) entities.push(commands.spawn([value, at, note])({ [value]: 0, [at]: i }));
+});
+const raise = System.create({ kernel: "gpu", components: { with: [value] } }, row => {
+    row[value] = row[value] + 1;
+});
+const setValue = System.create({ target: "entity", components: { with: [value] } }, (row, _context, input: { readonly entity: Entity }) => {
+    row[value] += 1;
+});
+let found: number[] = [];
+const there = System.create({ components: { with: [at, note], changed: [value] } }, row => { if (row[note] !== undefined) found.push(row[at]); });
+
+const device = async (): Promise<GPUDevice> => {
+    const adapter = await navigator.gpu.requestAdapter();
+    if (adapter === null) throw new Error("No WebGPU adapter.");
+    return adapter.requestDevice();
+};
+
+describe("chunk and block ticks after a GPU kernel's column stamp", () => {
+    it.runIf(gpu)("let a joined thread's filters find every row a GPU kernel wrote, then a row the CPU wrote", async () => {
+        const world = createWorld({ [workers]: 0, [gpuDevice]: await device() });
+        const channel = new MessageChannel();
+        const shared = world.share(channel.port1);
+        const remote = await join(channel.port2, { threads: ["changeBlocksGpuTest"] });
+        try {
+            await shared;
+            await world.run(seed);
+            await world.run(there);
+            await world.run(raise);
+            found = [];
+            await world.run(there);
+            expect(found.length).toBe(rows);
+            const row = 2 * 1024 + 5 * 64 + 9;
+            await world.run(setValue, { entity: entities[row] });
+            found = [];
+            await world.run(there);
+            expect(found).toEqual([row]);
+        }
+        finally {
+            await remote.dispose();
+            await world.dispose();
+        }
+    });
+});

package/src/implementation/world/change-blocks.cases.ts

@@ -0,0 +1,14 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./change-blocks.fixture.js";
+
+/** Chunk and block ticks on workers: the cases, over the fixture built for node or from source. */
+export const changeBlocksCases = (load: () => Promise<typeof Fixture>) => describe("chunk and block ticks on workers", () => {
+    for (const wasm of [false, true]) {
+        it(`let readers find the rows a kernel on workers wrote (${wasm ? "WASM" : "JS"} kernels)`, async () => {
+            const fixture = await load();
+            const expected = [5, 2048 + 5 * 64 + 9, 4499];
+            expect(await fixture.foundOnWorkers(wasm)).toEqual({ kernel: expected, main: expected });
+        });
+    }
+});

package/src/implementation/world/change-blocks.fixture.ts

@@ -0,0 +1,70 @@
+// © 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 { readEach, select } from "./reads.test-helper.js";
+import { createWorld } from "./create.js";
+import type { U32 } from "../../interface/math/index.js";
+
+/** Scenarios of chunk and block ticks on workers, run built in node and from source in chromium. */
+
+const value = Symbol("changeBlocksWorkersTest/value");
+const at = Symbol("changeBlocksWorkersTest/at");
+const seen = Symbol("changeBlocksWorkersTest/seen");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [value]: { type: number };
+        [at]: { type: U32 };
+        [seen]: { type: number };
+    }
+}
+
+
+const rows = 4500;
+
+const seed = System.create({}, ({ commands }) => {
+    for (let i = 0; i < rows; i++) commands.spawn([value, at, seen])({ [value]: 0, [at]: i, [seen]: 0 });
+});
+
+/** Writes the rows whose `at` is one of three, stamping row by row. */
+const writeSome = System.create({ kernel: true, components: { with: [at, value] } }, (row, _context, input: { readonly a: I32; readonly b: I32; readonly c: I32 }) => {
+    const here = row[at];
+    if (here === input.a || here === input.b || here === input.c) row[value] += 1;
+});
+
+/** Counts each run of the rows whose value changed. */
+const watch = System.create({ kernel: true, components: { with: [seen], changed: [value] } }, row => {
+    row[seen] += 1;
+});
+
+let found: number[] = [];
+const onMain = System.create({ components: { with: [at], changed: [value] } }, row => { found.push(row[at]); });
+
+/**
+ * The rows a kernel on workers and a system on the world's thread find after a kernel on workers wrote three rows far
+ * apart: in the first block, a middle block of a middle chunk, and the last row.
+ */
+export const foundOnWorkers = async (wasm: boolean): Promise<{ readonly kernel: readonly number[]; readonly main: readonly number[] }> => {
+    const world = createWorld({ [workers]: 2 }, { wasm, minimumChunk: 64 });
+    try {
+        await world.run(seed);
+        await world.run(watch);
+        await world.run(onMain);
+        const all = await select(world, { required: [seen] });
+        const before = await readEach(world, all, seen);
+        await world.run(writeSome, { a: 5, b: 2048 + 5 * 64 + 9, c: rows - 1 });
+        await world.run(watch);
+        found = [];
+        await world.run(onMain);
+        const after = await readEach(world, all, seen);
+        const ats = await readEach(world, all, at);
+        return {
+            kernel: all.flatMap((_, k) => after[k] !== before[k] ? [ats[k] ?? -1] : []).sort((a, b) => a - b),
+            main: [...found].sort((a, b) => a - b),
+        };
+    }
+    finally {
+        await world.dispose();
+    }
+};