@adobe/ecs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,111 @@
+import { Component } from "../../interface/component/component.js";
+import { Entity } from "../../interface/entity/entity.js";
+import { Resource } from "../../interface/resource/resource.js";
+import { System } from "../../interface/system/system.js";
+
+// Keys and systems every thread of the transfer tests imports: systems on thread "transfersTest", which a joined thread
+// fills, and on the world's, taking Transferable values in their input, and `transfer` components holding them.
+// An input field's schema `{ allOf: [] }` takes any value, typed `unknown`, which each body narrows.
+
+export const anchor = Symbol("transfersTest/anchor");
+export const order = Symbol("transfersTest/order");
+export const port = Symbol("transfersTest/port");
+export const bitmap = Symbol("transfersTest/bitmap");
+export const portHere = Symbol("transfersTest/portHere");
+export const bitmapHere = Symbol("transfersTest/bitmapHere");
+export const parent = Symbol("transfersTest/parent");
+export const depth = Symbol("transfersTest/depth");
+declare module "@adobe/ecs" {
+    export interface Threads {
+        transfersTest: true;
+    }
+    export interface Components {
+        [port]: { type: MessagePort; thread: "transfersTest"; transfer: true };
+        [bitmap]: { type: ImageBitmap; thread: "transfersTest"; transfer: true };
+        [portHere]: { type: MessagePort; transfer: true };
+        [bitmapHere]: { type: ImageBitmap; transfer: true };
+        [parent]: { type: Entity; reference: "owner" };
+        [depth]: { type: number };
+    }
+    export interface Resources {
+        [anchor]: { type: { readonly text: string }; thread: "transfersTest" };
+        [order]: { type: number };
+    }
+}
+/** An object resource of "transfersTest", which places the systems reading it there. */
+Resource.register(anchor, { type: { type: "object", properties: { text: { type: "string" } }, default: { text: "anchor" } }, thread: "transfersTest" });
+/** Counts the runs that read it, in the order they ran. */
+Resource.register(order, { type: { type: "integer", default: 0 } });
+Component.register(port, { thread: "transfersTest", transfer: true });
+Component.register(bitmap, { thread: "transfersTest", transfer: true });
+Component.register(portHere, { transfer: true });
+Component.register(bitmapHere, { transfer: true });
+Component.register(parent, { type: Entity.schema, reference: "owner" });
+Component.register(depth, { type: { type: "number" } });
+
+const any = { allOf: [] } as const;
+
+/** What a system was given, on the thread it ran on: an ArrayBuffer's length and first byte, and the run's order. */
+export type Stored = { readonly bytes: number; readonly first: number; readonly order: number; readonly value: unknown };
+export const stored: Stored[] = [];
+/** The values systems gave components, on the thread they ran on. */
+export const kept: unknown[] = [];
+
+const store = (value: unknown, resources: { [order]: number }): void => {
+    const bytes = value instanceof ArrayBuffer ? value.byteLength : -1;
+    stored.push({ bytes, first: bytes > 0 && value instanceof ArrayBuffer ? new Uint8Array(value)[0] : -1, order: resources[order]++, value });
+};
+
+/** On "transfersTest": records the buffer it's given. */
+export const storeThere = System.create({ name: "transfersTest/storeThere", input: { type: "object", properties: { buffer: any } }, resources: { read: [anchor], write: [order] } }, ({ input, resources }) => {
+    if (resources[anchor].text === "anchor") store(input.buffer, resources);
+});
+/** On the world's thread: records the buffer it's given. */
+export const storeHere = System.create({ name: "transfersTest/storeHere", input: { type: "object", properties: { buffer: any } }, resources: { write: [order] } }, ({ input, resources }) => {
+    store(input.buffer, resources);
+});
+/** On the world's thread: what a run from a joined thread saw of the order, by its value. */
+export const marks: { readonly value: number; readonly order: number }[] = [];
+export const mark = System.create({ name: "transfersTest/mark", input: { type: "object", properties: { value: { type: "number" } } }, resources: { write: [order] } }, ({ input, resources }) => {
+    marks.push({ value: input.value, order: resources[order]++ });
+});
+/** On "transfersTest": gives an entity the port or bitmap it's given. */
+export const attachThere = System.create({
+    name: "transfersTest/attachThere", input: { type: "object", properties: { entity: Entity.schema, value: any } }, resources: { read: [anchor] },
+}, ({ input, resources, commands }) => {
+    if (resources[anchor].text !== "anchor") return;
+    kept.push(input.value);
+    if (input.value instanceof MessagePort) commands.add(input.entity, port, input.value);
+    else if (typeof ImageBitmap === "function" && input.value instanceof ImageBitmap) commands.add(input.entity, bitmap, input.value);
+});
+/** On the world's thread: gives an entity the port or bitmap it's given. */
+export const attachHere = System.create({ name: "transfersTest/attachHere", input: { type: "object", properties: { entity: Entity.schema, value: any } } }, ({ input, commands }) => {
+    kept.push(input.value);
+    if (input.value instanceof MessagePort) commands.add(input.entity, portHere, input.value);
+    else if (typeof ImageBitmap === "function" && input.value instanceof ImageBitmap) commands.add(input.entity, bitmapHere, input.value);
+});
+/** On "transfersTest": says hello through the port it's given, which only moving it there, not copying it, gives. */
+export const greetThere = System.create({ name: "transfersTest/greetThere", input: { type: "object", properties: { port: any } }, resources: { read: [anchor] } }, ({ input, resources }) => {
+    if (input.port instanceof MessagePort) input.port.postMessage(resources[anchor].text);
+});
+
+/** On the world's thread: spawns an entity holding the port it's given. */
+export const spawnHere = System.create({ name: "transfersTest/spawnHere", input: { type: "object", properties: { value: any } } }, ({ input, commands }) => {
+    if (input.value instanceof MessagePort) commands.spawn([portHere])({ [portHere]: input.value });
+});
+
+/**
+ * On "transfersTest", declaring `up`, which runs only on the world's thread: once a joined thread fills
+ * "transfersTest", it fails to register, so a run of it never runs.
+ */
+export const unregistered = System.create({
+    name: "transfersTest/unregistered", input: { type: "object", properties: { value: any } }, components: { read: [port], write: [depth] }, up: { through: parent, read: [depth] },
+}, (row, { input, up }) => {
+    row[depth] = (up === null ? 0 : up[depth]) + (row[port] === input.value ? 1 : 0);
+});
+
+/** On the world's thread: nothing, a run of its own. */
+export const idle = System.create({ name: "transfersTest/idle" }, () => {});
+
+/** Every system the joined threads run or place, which they import so the world can place them there. */
+export const transferSystems: readonly { readonly name: string }[] = [storeThere, storeHere, mark, attachThere, attachHere, spawnHere, greetThere, unregistered];

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

@@ -0,0 +1,157 @@
+import { describe, expect, it } from "vitest";
+import type { Observe } from "../../observe/index.js";
+import { workers } from "../../interface/resources/workers.js";
+import type { World } from "../../interface/world/world.js";
+import { createWorld, join, type CreatedWorld } from "./create.js";
+import { asEntity } from "./entities.js";
+import { peersOf } from "./join.js";
+import { attachHere, attachThere, greetThere, kept, mark, marks, spawnHere, storeHere, storeThere, stored, unregistered } from "./transfers.test-helper.js";
+import { reportOf, runReported } from "./reports.test-helper.js";
+
+// Transfers, with the world, the thread filling "transfersTest" and a thread filling none on this one, joined through
+// MessageChannels: a run's Transferable input moves to the thread its system runs on.
+
+const until = <T>(observe: Observe<T>, accept: (value: T) => boolean): Promise<T> => new Promise(resolve => {
+    let done = false;
+    const stop = observe(value => {
+        if (done || !accept(value)) return;
+        done = true;
+        queueMicrotask(() => stop());
+        resolve(value);
+    });
+});
+
+const later = (milliseconds = 0): Promise<void> => new Promise(resolve => setTimeout(resolve, milliseconds));
+
+/** Resolves once `remote` has a channel to another joined thread. */
+const peered = async (remote: World): Promise<void> => {
+    while ((peersOf.get(remote)?.() ?? 0) === 0) await later();
+};
+
+const sharedWith = (world: CreatedWorld, threads: readonly "transfersTest"[]): World => {
+    const channel = new MessageChannel();
+    world.share(channel.port1);
+    return join(channel.port2, { threads });
+};
+
+/** A world here, `filler` claiming "transfersTest", and `loader` claiming nothing, each with a channel to the other. */
+const joined = async (): Promise<{ readonly world: CreatedWorld; readonly filler: World; readonly loader: World }> => {
+    stored.length = marks.length = kept.length = 0;
+    const world = createWorld({ [workers]: 0 });
+    const loader = sharedWith(world, []);
+    const filler = sharedWith(world, ["transfersTest"]);
+    await until(world.threads, threads => threads.length === 2 && threads.every(thread => thread.status === "joined"));
+    await peered(loader);
+    await peered(filler);
+    return { world, filler, loader };
+};
+
+const bufferOf = (first: number, bytes = 1024): ArrayBuffer => {
+    const buffer = new ArrayBuffer(bytes);
+    new Uint8Array(buffer)[0] = first;
+    return buffer;
+};
+
+/** Resolves once a port's other end closed, or with false after `milliseconds`. */
+const closed = (port: MessagePort, milliseconds = 1000): Promise<boolean> => new Promise(resolve => {
+    port.addEventListener("close", () => resolve(true));
+    port.start();
+    setTimeout(() => resolve(false), milliseconds);
+});
+
+const clean = { failures: [], skipped: [], dropped: 0, warnings: [] };
+
+describe("transfers", () => {
+    it("move a run's Transferable input straight to the joined thread its system runs on, in call order with that thread's other runs", async () => {
+        const { world, filler, loader } = await joined();
+        const buffers = [bufferOf(1), bufferOf(2)];
+        const runs = [loader.run(storeThere, { buffer: buffers[0] }), loader.run(mark, { value: 1 }), loader.run(storeThere, { buffer: buffers[1] }), loader.run(mark, { value: 2 })];
+        // Moved, not copied: the loader's are detached as soon as it runs them.
+        expect(buffers.map(buffer => buffer.byteLength)).toEqual([0, 0]);
+        const reports = await Promise.all((await Promise.all(runs)).map(run => reportOf(world, run)));
+        expect(reports.map(report => report.warnings.map(warning => warning.kind))).toEqual([["blocking"], [], ["blocking"], []]);
+        expect(stored.map(({ bytes, first, order }) => [bytes, first, order])).toEqual([[1024, 1, 0], [1024, 2, 2]]);
+        expect(marks).toEqual([{ value: 1, order: 1 }, { value: 2, order: 3 }]);
+        await loader.dispose();
+        await filler.dispose();
+        await world.dispose();
+    });
+    it("move a MessagePort, which can't be copied, to the joined thread its system runs on, where it works", async () => {
+        const { world, filler, loader } = await joined();
+        const channel = new MessageChannel();
+        const greeted = new Promise<unknown>(resolve => {
+            channel.port2.onmessage = event => resolve(event.data);
+        });
+        expect((await reportOf(world, await loader.run(greetThere, { port: channel.port1 }))).failures).toEqual([]);
+        expect(await greeted).toBe("anchor");
+        channel.port2.close();
+        await loader.dispose();
+        await filler.dispose();
+        await world.dispose();
+    });
+    it("move one to the world's thread where its system runs there", async () => {
+        const { world, filler, loader } = await joined();
+        const buffer = bufferOf(3);
+        const ran = loader.run(storeHere, { buffer });
+        expect(buffer.byteLength).toBe(0);
+        expect(await reportOf(world, await ran)).toEqual(clean);
+        expect(stored.map(({ bytes, first }) => [bytes, first])).toEqual([[1024, 3]]);
+        await loader.dispose();
+        await filler.dispose();
+        await world.dispose();
+    });
+    it("keep one on the joined thread its system runs on, when it runs it", async () => {
+        const { world, filler, loader } = await joined();
+        const buffer = bufferOf(4);
+        await filler.run(storeThere, { buffer });
+        expect(stored.map(({ bytes, first, value }) => [bytes, first, value === buffer])).toEqual([[1024, 4, true]]);
+        await loader.dispose();
+        await filler.dispose();
+        await world.dispose();
+    });
+    it("reject a run whose input moved to a thread that left, the thread's later runs going on", async () => {
+        const { world, filler, loader } = await joined();
+        await filler.dispose();
+        const moved = loader.run(storeThere, { buffer: bufferOf(5) });
+        await expect(moved).rejects.toThrow("moved to a joined thread that's gone");
+        // Once the world has told it, its runs go to the world's thread, which runs the system now.
+        await later(10);
+        await loader.run(storeThere, { buffer: bufferOf(6) });
+        expect(stored.map(({ bytes, first }) => [bytes, first])).toEqual([[1024, 6]]);
+        await loader.dispose();
+        await world.dispose();
+    });
+    it("release a value whose command drops, on its thread", async () => {
+        const { world, filler, loader } = await joined();
+        const there = new MessageChannel();
+        const here = new MessageChannel();
+        const closes = [closed(there.port2), closed(here.port2)];
+        const dead = asEntity(123456);
+        expect((await reportOf(world, await loader.run(attachThere, { entity: dead, value: there.port1 }))).dropped).toBe(1);
+        expect((await reportOf(world, await loader.run(attachHere, { entity: dead, value: here.port1 }))).dropped).toBe(1);
+        expect(await Promise.all(closes)).toEqual([true, true]);
+        await loader.dispose();
+        await filler.dispose();
+        await world.dispose();
+    });
+    it("release what moved for a run that never ran there", async () => {
+        const { world, filler, loader } = await joined();
+        const channel = new MessageChannel();
+        const closing = closed(channel.port2);
+        await expect(loader.run(unregistered, { value: channel.port1 })).rejects.toThrow("declares up");
+        expect(await closing).toBe(true);
+        await loader.dispose();
+        await filler.dispose();
+        await world.dispose();
+    });
+    it("release a value whose command drops in a world no thread joined, and keep one whose command lands", async () => {
+        const world = createWorld({ [workers]: 0 });
+        const dropped = new MessageChannel();
+        const landed = new MessageChannel();
+        const closes = [closed(dropped.port2, 200), closed(landed.port2, 200)];
+        expect((await runReported(world, attachHere, { entity: asEntity(123456), value: dropped.port1 })).dropped).toBe(1);
+        expect((await runReported(world, spawnHere, { value: landed.port1 })).dropped).toBe(0);
+        expect(await Promise.all(closes)).toEqual([true, false]);
+        await world.dispose();
+    });
+});

package/src/implementation/world/transfers.ts

@@ -0,0 +1,104 @@
+import type { TaskChannel } from './remote-systems.js';
+
+// Transfers (threads.md, "Transfers"): a run's input holding Transferable values moves them to the thread its system
+// runs on, a value whose command drops is released there, and a run's input held on that thread until its task.
+
+/** Global constructors of Transferable values, where the platform has them. */
+const constructors: readonly string[] = [
+    "ArrayBuffer", "ImageBitmap", "OffscreenCanvas", "MessagePort", "VideoFrame", "AudioData",
+    "ReadableStream", "WritableStream", "TransformStream", "RTCDataChannel",
+];
+
+/** This platform's constructors of Transferable values, found once. */
+let found: readonly Function[] | null = null;
+const platformConstructors = (): readonly Function[] => found ??= constructors.flatMap(name => {
+    const constructor: unknown = Reflect.get(globalThis, name);
+    return typeof constructor === "function" ? [constructor] : [];
+});
+
+/** Whether `value` is Transferable on this platform: a `SharedArrayBuffer` isn't, as it's shared rather than moved. */
+export const isTransferable = (value: unknown): value is object => {
+    if (typeof value !== "object" || value === null) return false;
+    for (const constructor of platformConstructors()) if (value instanceof constructor) return true;
+    return false;
+};
+
+const collect = (value: unknown, into: object[] | null): object[] | null => {
+    if (!isTransferable(value) || into?.includes(value) === true) return into;
+    (into ??= []).push(value);
+    return into;
+};
+
+/**
+ * The Transferable values a run's input holds, each once: its fields', and the elements of fields that are arrays; null
+ * for none, which allocates nothing.
+ */
+export const transferablesOf = (input: unknown): object[] | null => {
+    if (typeof input !== "object" || input === null) return null;
+    let into: object[] | null = null;
+    for (const field of Object.keys(input)) {
+        const value: unknown = Reflect.get(input, field);
+        if (Array.isArray(value)) {
+            for (const element of value) if (typeof element === "object") into = collect(element, into);
+        }
+        else into = collect(value, into);
+    }
+    return into;
+};
+
+const ignore = (): void => {};
+
+/** Calls a method of `value` by name, if it has one, ignoring what it throws or rejects with. */
+const call = (value: object, method: string): void => {
+    const callable: unknown = Reflect.get(value, method);
+    if (typeof callable !== "function") return;
+    try {
+        const result: unknown = Reflect.apply(callable, value, []);
+        if (result instanceof Promise) result.catch(ignore);
+    }
+    catch {
+        // Released already, or locked: nothing more to release.
+    }
+};
+
+/**
+ * Releases a Transferable value no component will hold: closes an `ImageBitmap`, `VideoFrame`, `AudioData`,
+ * `MessagePort` or `RTCDataChannel`, cancels a `ReadableStream`, aborts a `WritableStream`, and both for a
+ * `TransformStream`'s sides. An `ArrayBuffer`'s and an `OffscreenCanvas`'s memory is the collector's.
+ */
+export const releaseValue = (value: unknown): void => {
+    if (!isTransferable(value)) return;
+    const name = value.constructor?.name;
+    if (name === "ReadableStream") call(value, "cancel");
+    else if (name === "WritableStream") call(value, "abort");
+    else if (name === "TransformStream") {
+        const readable: unknown = Reflect.get(value, "readable");
+        const writable: unknown = Reflect.get(value, "writable");
+        if (typeof readable === "object" && readable !== null) call(readable, "cancel");
+        if (typeof writable === "object" && writable !== null) call(writable, "abort");
+    }
+    else call(value, "close");
+};
+
+/** Releases every Transferable value a run's input holds. */
+export const releaseInput = (input: unknown): void => {
+    for (const value of transferablesOf(input) ?? []) releaseValue(value);
+};
+
+/**
+ * On the world's thread, a run's input held on the joined thread its system runs on, which moved it there: the joined
+ * thread that ran it, by number, the run's sequence there, the channel of the thread holding it, and whether a task
+ * there took it, so what none took is released once the run finishes.
+ */
+export type HeldInput = { readonly from: number; readonly sequence: number; readonly channel: TaskChannel; taken: boolean };
+
+const held = new WeakSet<object>();
+
+export const heldInput = (from: number, sequence: number, channel: TaskChannel): HeldInput => {
+    const input: HeldInput = { from, sequence, channel, taken: false };
+    held.add(input);
+    return input;
+};
+
+/** Whether a run's input is held on a joined thread. */
+export const isHeld = (input: unknown): input is HeldInput => typeof input === "object" && input !== null && held.has(input);

package/src/implementation/world/up-tree.test.ts

@@ -0,0 +1,152 @@
+import { expect, it } from "vitest";
+import { Component } from "../../interface/component/component.js";
+import { Entity } from "../../interface/entity/entity.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { readEach, select } from "./reads.test-helper.js";
+import { createWorld } from "./create.js";
+import { workers } from "../../interface/resources/workers.js";
+
+const local = Symbol("upTreeTest/local");
+const full = Symbol("upTreeTest/full");
+const filtered = Symbol("upTreeTest/filtered");
+const parent = Symbol("upTreeTest/parent");
+const hidden = Symbol("upTreeTest/hidden");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [local]: { type: number };
+        [full]: { type: number };
+        [filtered]: { type: number };
+        [parent]: { type: Entity; reference: "weak" };
+        [hidden]: { type: true };
+    }
+}
+
+Component.register(local, { type: { type: "number" } });
+Component.register(full, { type: { type: "number" } });
+Component.register(filtered, { type: { type: "number" } });
+Component.register(parent, { type: Entity.schema, reference: "weak" });
+Component.register(hidden, { type: { const: true } });
+
+const propagateFull = System.create({
+    name: "upTreeTest/propagateFull",
+    kernel: "cpu",
+    components: { read: [local], write: [full], not: [hidden] },
+    up: { through: parent, read: [full] },
+}, (row, { up }) => {
+    row[full] = (up === null ? 0 : up[full]) + row[local];
+});
+const propagateFiltered = System.create({
+    name: "upTreeTest/propagateFiltered",
+    kernel: "cpu",
+    components: { read: [local], write: [filtered], changed: [local], not: [hidden] },
+    up: { through: parent, read: [filtered] },
+}, (row, { up }) => {
+    row[filtered] = (up === null ? 0 : up[filtered]) + row[local];
+});
+
+type Operation =
+    | { readonly kind: "spawn"; readonly local: number; readonly parent: Entity | null }
+    | { readonly kind: "despawn" | "hide" | "show" | "orphan"; readonly entity: Entity }
+    | { readonly kind: "reparent"; readonly entity: Entity; readonly to: Entity }
+    | { readonly kind: "set"; readonly entity: Entity; readonly local: number };
+const operations: Operation[] = [];
+const apply = System.create({ name: "upTreeTest/apply" }, ({ commands }) => {
+    for (const operation of operations.splice(0)) {
+        switch (operation.kind) {
+            case "spawn":
+                if (operation.parent === null) commands.spawn([local, full, filtered])({ [local]: operation.local, [full]: 0, [filtered]: 0 });
+                else commands.spawn([local, full, filtered, parent])({ [local]: operation.local, [full]: 0, [filtered]: 0, [parent]: operation.parent });
+                break;
+            case "despawn": commands.despawn(operation.entity); break;
+            case "hide": commands.add(operation.entity, hidden, true); break;
+            case "show": commands.remove(operation.entity, hidden); break;
+            case "orphan": commands.remove(operation.entity, parent); break;
+            case "reparent": commands.add(operation.entity, parent, operation.to); break;
+            case "set": commands.add(operation.entity, local, operation.local); break;
+        }
+    }
+});
+
+/** A small deterministic generator, so a failure replays. */
+const generator = (seed: number) => {
+    let state = seed;
+    return (limit: number): number => {
+        state = (state * 1103515245 + 12345) % 2 ** 31;
+        // The high bits: a power-of-two modulus leaves the low ones short cycles.
+        return Math.floor((state / 2 ** 31) * limit);
+    };
+};
+
+/** What each matched row outside a cycle should hold, from the world's current tree and the values it stores. */
+const expected = async (ecs: World, key: typeof full | typeof filtered): Promise<Map<Entity, number>> => {
+    const entities = await select(ecs, { required: [local] });
+    const alive = new Set(entities);
+    const isHidden = new Set(await select(ecs, { required: [hidden] }));
+    // The walk reads only live entities, so one read of each component up front serves it.
+    const byEntity = <T>(values: readonly T[]): Map<Entity, T> => new Map(entities.map((entity, i) => [entity, values[i]]));
+    const parents = byEntity(await readEach(ecs, entities, parent));
+    const locals = byEntity(await readEach(ecs, entities, local));
+    const keys = byEntity(await readEach(ecs, entities, key));
+    const parentOf = (entity: Entity): Entity | null => {
+        const value = parents.get(entity);
+        return value !== undefined && value !== null && alive.has(value) ? value : null;
+    };
+    const matched = (entity: Entity): boolean => alive.has(entity) && !isHidden.has(entity);
+    const isCyclic = (entity: Entity): boolean => {
+        const seen = new Set<Entity>();
+        for (let current: Entity | null = entity; current !== null && matched(current); current = parentOf(current)) {
+            if (seen.has(current)) return true;
+            seen.add(current);
+        }
+        return false;
+    };
+    const values = new Map<Entity, number>();
+    const valueOf = (entity: Entity): number => {
+        if (!matched(entity) || isCyclic(entity)) return keys.get(entity) ?? 0;
+        const known = values.get(entity);
+        if (known !== undefined) return known;
+        const up = parentOf(entity);
+        const value = (up === null ? 0 : valueOf(up)) + (locals.get(entity) ?? 0);
+        values.set(entity, value);
+        return value;
+    };
+    const result = new Map<Entity, number>();
+    for (const entity of entities) if (matched(entity) && !isCyclic(entity)) result.set(entity, valueOf(entity));
+    return result;
+};
+
+const actual = async (ecs: World, key: typeof full | typeof filtered, rows: Iterable<Entity>): Promise<Map<Entity, number>> => {
+    const entities = [...rows];
+    const values = await readEach(ecs, entities, key);
+    return new Map(entities.map((entity, i) => [entity, values[i] ?? 0]));
+};
+
+it.each([true, false])("keeps its tree current across spawns, despawns, reparents, cycles and matching changes, with WASM %s", async wasm => {
+    await using ecs = createWorld({ [workers]: 0 }, { wasm });
+    const random = generator(7);
+    for (let k = 0; k < 30; k++) operations.push({ kind: "spawn", local: random(10), parent: null });
+    await ecs.run(apply);
+    for (let frame = 0; frame < 300; frame++) {
+        const entities = await select(ecs, { required: [local] });
+        const any = (): Entity => entities[random(entities.length)];
+        for (let k = 0; k < 4; k++) {
+            switch (random(8)) {
+                case 0: operations.push({ kind: "spawn", local: random(10), parent: random(4) === 0 ? null : any() }); break;
+                case 1: if (entities.length > 20) operations.push({ kind: "despawn", entity: any() }); break;
+                case 2: operations.push({ kind: random(2) === 0 ? "hide" : "show", entity: any() }); break;
+                case 3: operations.push({ kind: "orphan", entity: any() }); break;
+                case 4: case 5: operations.push({ kind: "reparent", entity: any(), to: any() }); break;
+                default: operations.push({ kind: "set", entity: any(), local: random(10) });
+            }
+        }
+        await ecs.run(apply);
+        await ecs.run(propagateFull);
+        await ecs.run(propagateFiltered);
+        for (const key of [full, filtered] as const) {
+            const want = await expected(ecs, key);
+            expect(await actual(ecs, key, want.keys()), `${String(key)}, frame ${frame}`).toEqual(want);
+        }
+    }
+});

package/src/implementation/world/up-workers.cases.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./up-workers.fixture.js";
+
+/** `up` runs depth by depth across workers: the cases, over the fixture built for node or from source. */
+export const upWorkersCases = (load: () => Promise<typeof Fixture>) => describe("up", () => {
+    it("runs depth by depth across workers, as on the main thread alone", async () => {
+        const fixture = await load();
+        const alone = await fixture.simulate(0, false);
+        const parallel = await fixture.simulate(2, true);
+        expect(parallel.values).toEqual(alone.values);
+        expect(parallel.windows).toBeGreaterThan(0);
+    });
+});

package/src/implementation/world/up-workers.fixture.ts

@@ -0,0 +1,67 @@
+import { Component } from "../../interface/component/component.js";
+import { Entity } from "../../interface/entity/entity.js";
+import { System } from "../../interface/system/system.js";
+import { workers } from "../../interface/resources/workers.js";
+import { readEach, select } from "./reads.test-helper.js";
+import { createWorld } from "./create.js";
+import { countingWorkers } from "./platforms.test-helper.js";
+
+/** Scenarios of `up` across workers, run built in node and from source in chromium. */
+
+const local = Symbol("upWorkersTest/local");
+const world = Symbol("upWorkersTest/world");
+const parent = Symbol("upWorkersTest/parent");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [local]: { type: number };
+        [world]: { type: number };
+        [parent]: { type: Entity; reference: "owner" };
+    }
+}
+
+Component.register(local, { type: { type: "number" } });
+Component.register(world, { type: { type: "number" } });
+Component.register(parent, { type: Entity.schema, reference: "owner" });
+
+const propagate = System.create({
+    name: "upWorkersTest/propagate",
+    kernel: "cpu",
+    components: { read: [local], write: [world], changed: [local] },
+    up: { through: parent, read: [world] },
+}, (row, { up }) => {
+    row[world] = (up === null ? 0 : up[world]) + row[local] * 2;
+});
+/** 100 trees, each a root with 40 levels of two children, ordered so storage order isn't depth order. */
+const grow = System.create({ name: "upWorkersTest/grow" }, ({ commands }) => {
+    for (let tree = 0; tree < 100; tree++) {
+        let level = [commands.spawn([local, world])({ [local]: tree, [world]: 0 })];
+        for (let depth = 1; depth < 40; depth++) {
+            const at = level[depth % level.length];
+            level = [commands.spawn([local, world, parent])({ [local]: depth, [world]: 0, [parent]: at }), commands.spawn([local, world, parent])({ [local]: -depth, [world]: 0, [parent]: at })];
+        }
+    }
+});
+const nudge = System.create({ name: "upWorkersTest/nudge", components: { write: [local] } }, row => {
+    if (row[local] === 7) row[local] = 70;
+});
+
+/** Values after `propagate` runs around a nudge, sorted, and the windows opened on workers meanwhile. */
+export const simulate = async (count: number, wasm: boolean): Promise<{ readonly values: readonly (number | null)[]; readonly windows: number }> => {
+    const counting = countingWorkers();
+    const ecs = createWorld({ [workers]: count }, { minimumChunk: 64, wasm, pool: counting.platform });
+    try {
+        await ecs.run(grow);
+        const before = counting.posted("window");
+        await ecs.run(propagate);
+        await ecs.run(nudge);
+        await ecs.run(propagate);
+        await ecs.run(propagate);
+        const windows = counting.posted("window") - before;
+        const values = (await readEach(ecs, await select(ecs, { required: [world] }), world)).sort((a, b) => (a ?? 0) - (b ?? 0));
+        return { values, windows };
+    }
+    finally {
+        await ecs.dispose();
+    }
+};