@adobe/ecs 0.1.0 → 0.2.1

package/src/implementation/world/worker-window.test.ts

@@ -0,0 +1,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { controlWords, done, epoch, posted, ringSize, taskWords } from "./protocol.js";
+import { runWindow } from "./worker-window.js";
+
+describe("a pool worker's window", () => {
+    it("runs a task the pool posted just before closing it, after the worker last looked for tasks", () => {
+        const control = new Int32Array(new SharedArrayBuffer(controlWords * 4));
+        const statuses = new Int32Array(new SharedArrayBuffer(ringSize * 4));
+        const payloads = new Float64Array(new SharedArrayBuffer(ringSize * taskWords * 8));
+        const windowEpoch = 2;
+        control[epoch] = windowEpoch;
+        // The pool, between the worker's look at `posted` and its look at the epoch: it posts a task of this window,
+        // then closes it.
+        const load = Atomics.load;
+        let lookedForTasks = false;
+        let played = false;
+        const playPool = (array: Int32Array, index: number): number => {
+            const value = load(array, index);
+            if (array !== control) return value;
+            if (index === posted) lookedForTasks = true;
+            else if (index === epoch && lookedForTasks && !played) {
+                played = true;
+                payloads[6] = windowEpoch;
+                Atomics.store(control, posted, 1);
+                return Atomics.add(control, epoch, 1) + 1;
+            }
+            return value;
+        };
+        const original = Object.getOwnPropertyDescriptor(Atomics, "load");
+        let ran = 0;
+        try {
+            Object.defineProperty(Atomics, "load", { value: playPool, configurable: true, writable: true });
+            runWindow(control, statuses, payloads, windowEpoch, () => { ran++; });
+        }
+        finally {
+            if (original !== undefined) Object.defineProperty(Atomics, "load", original);
+        }
+        expect(played).toBe(true);
+        expect(ran).toBe(1);
+        expect(Atomics.load(control, done)).toBe(1);
+    });
+});

package/src/implementation/world/worker-window.ts

@@ -0,0 +1,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { done, epoch, posted, ringSize, signal, taskWords } from './protocol.js';
+
+/**
+ * A pool worker's window (`pool.ts`): runs the tasks of its ring, each by `runTask` with its payload's base, which
+ * throws when the task fails, blocking between them, until the pool closes the window or posts a task of a later one;
+ * then it returns, so the worker handles its messages. `control`, `statuses` and `payloads` are the worker's views of
+ * the pool's state; `windowEpoch` is the epoch the window opened in.
+ */
+export const runWindow = (control: Int32Array, statuses: Int32Array, payloads: Float64Array, windowEpoch: number, runTask: (base: number) => void): void => {
+    let next = Atomics.load(control, done);
+    for (;;) {
+        const seen = Atomics.load(control, signal);
+        if (next < Atomics.load(control, posted)) {
+            const ring = next % ringSize;
+            const base = ring * taskWords;
+            // A task from a later window waits until this worker has handled the messages sent before it.
+            if (payloads[base + 6] !== windowEpoch) return;
+            let status = next + 1;
+            try {
+                runTask(base);
+            }
+            catch {
+                status = -status;
+            }
+            Atomics.store(statuses, ring, status);
+            next++;
+            Atomics.store(control, done, next);
+            Atomics.notify(control, done);
+            continue;
+        }
+        // Closed, it leaves once it ran this window's tasks: the pool posts a task before it closes the window, so a task
+        // posted since the check above is seen now, and runs above if it's this window's.
+        if (Atomics.load(control, epoch) !== windowEpoch) {
+            if (next < Atomics.load(control, posted)) continue;
+            return;
+        }
+        // Tiers follow each other closely, so spin briefly before paying for a blocking wait's wake-up.
+        const deadline = performance.now() + 0.05;
+        while (Atomics.load(control, signal) === seen && performance.now() < deadline);
+        if (Atomics.load(control, signal) === seen) Atomics.wait(control, signal, seen);
+    }
+};

package/src/implementation/world/worker.ts

@@ -1,12 +1,14 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { buildKernel, buildViews, phases, readPlan, runBuildStep } from './index-build.js';
 import type { Entity } from '../../interface/entity/entity.js';
 import { createBlock, endBlock, locate, reserveFrom, tableLength, type Block } from './entities.js';
 import { createBatch, positionalSpawner, type Positional, type SpawnBatch } from './staging.js';
-import type { Kernel, KernelCommands, KernelModule } from './kernel.js';
+import { blockShift, chunkShift, type Kernel, type KernelCommands, type KernelModule } from './kernel.js';
 import { layoutOf, viewsOf, type Layout, type TypedArray, type Views } from '../../interface/registry/layout.js';
-import { emptyViews } from './arrays.js';
+import { absentColumn, emptyViews } from './arrays.js';
 import { claimPiece } from './claims.js';
-import { controlWords, done, epoch, idleKernel, lineWords, posted, ringBase, ringCapacity, ringCursor, ringNeeded, ringSize, signal, taskFields, taskWords, type FromWorker, type KernelSetup, type LookupSetup, type ToWorker, type WorkerError } from './protocol.js';
+import { controlWords, idleKernel, lineWords, ringBase, ringCapacity, ringCursor, ringNeeded, ringSize, taskFields, taskWords, type FromWorker, type KernelSetup, type LookupSetup, type ToWorker, type WorkerError } from './protocol.js';
+import { runWindow } from './worker-window.js';
 import { beginCommand, createRingWriter, encoderOf, endSegment, noExtent, objectStart, putComponent, putStart, putValue, startSegment, type Encoder, type Extent } from './command-ring.js';
 import { forEachPassingRange, type Filter } from './ranges.js';
 import { indexParameterCount, instantiateWasm, scalarValues, type WasmRun } from './wasm.js';
@@ -15,7 +17,7 @@ import { coveringBuffer, pageBytes, pagesWord } from './memory.js';
 import { endpointChannel, scopeChannel } from './port.js';
 import {
     archetypeField, capacityField, cursorField, entitiesVersionField, entitiesWord, freeCapacityField, freeField, generationField, linearFlag,
-    recordCapacity, recordEntities, recordStorages, recordVersion, recordWords, rowField, storageAdded, storageChanged, storageChunkAdded,
+    recordCapacity, recordEntities, recordStorages, recordVersion, recordWords, rowField, storageAdded, storageBlockAdded, storageBlockChanged, storageChanged, storageChunkAdded,
     storageChunkChanged, storageChunks, storageColumn, storageComponent, storageFlags, storageWords, tableLengthWord, tableOffsetWord, tickedFlag,
 } from './layout-directory.js';
 
@@ -26,6 +28,8 @@ type StorageViews = {
     readonly changed: Float64Array;
     readonly chunkAdded: Float64Array;
     readonly chunkChanged: Float64Array;
+    readonly blockAdded: Float64Array;
+    readonly blockChanged: Float64Array;
 };
 
 /** A worker's views of one archetype's columns, as of its record's `version`. */
@@ -160,6 +164,8 @@ const viewArchetype = (record: number, version: number): ArchetypeViews => {
             changed: ticked ? new Float64Array(memoryBuffer, words[base + storageChanged], capacity) : noTicks,
             chunkAdded: ticked ? new Float64Array(memoryBuffer, words[base + storageChunkAdded], words[base + storageChunks]) : noTicks,
             chunkChanged: ticked ? new Float64Array(memoryBuffer, words[base + storageChunkChanged], words[base + storageChunks]) : noTicks,
+            blockAdded: ticked ? new Float64Array(memoryBuffer, words[base + storageBlockAdded], words[base + storageChunks] << (chunkShift - blockShift)) : noTicks,
+            blockChanged: ticked ? new Float64Array(memoryBuffer, words[base + storageBlockChanged], words[base + storageChunks] << (chunkShift - blockShift)) : noTicks,
         });
     }
     return { version, entities: new Float64Array(memoryBuffer, words[record + recordEntities], capacity), storages };
@@ -201,7 +207,7 @@ const createChangedLookup = (lookup: LookupSetup, watched: readonly number[], si
         if (index < 0) return null;
         const archetype = archetypeAt(table.archetype[index]);
         if (archetype === undefined) return null;
-        for (const id of lookup.read) if (!archetype.storages.has(id)) return null;
+        for (const id of lookup.read) if (!archetype.storages.has(id) && !lookup.optional.includes(id)) return null;
         for (const id of lookup.has) if (!archetype.storages.has(id)) return null;
         for (const id of lookup.not) if (archetype.storages.has(id)) return null;
         const row = table.row[index];
@@ -209,7 +215,7 @@ const createChangedLookup = (lookup: LookupSetup, watched: readonly number[], si
         for (let i = 0; i < read.length; i++) {
             const layout = layouts[read[i]];
             const storage = archetype.storages.get(read[i]);
-            values[i] = layout.kind === "linear" && storage !== undefined ? layout.read(storage.views, row) : layout.kind === "constant" ? layout.value : undefined;
+            values[i] = storage === undefined && !archetype.storages.has(read[i]) ? undefined : layout.kind === "linear" && storage !== undefined ? layout.read(storage.views, row) : layout.kind === "constant" ? layout.value : undefined;
         }
         let changed = since.value < 0;
         for (let i = 0; i < watched.length && !changed; i++) {
@@ -227,14 +233,15 @@ const createLookup = (lookup: LookupSetup) => (entity: Entity): readonly unknown
     if (index < 0) return null;
     const archetype = archetypeAt(table.archetype[index]);
     if (archetype === undefined) return null;
-    for (const id of lookup.read) if (!archetype.storages.has(id)) return null;
+    for (const id of lookup.read) if (!archetype.storages.has(id) && !lookup.optional.includes(id)) return null;
     for (const id of lookup.has) if (!archetype.storages.has(id)) return null;
     for (const id of lookup.not) if (archetype.storages.has(id)) return null;
     const row = table.row[index];
     return lookup.read.map(id => {
         const layout = layouts[id];
         const storage = archetype.storages.get(id);
-        return layout.kind === "linear" && storage !== undefined ? layout.read(storage.views, row) : layout.kind === "constant" ? layout.value : undefined;
+        // An optional component the entity lacks reads undefined.
+        return storage === undefined && !archetype.storages.has(id) ? undefined : layout.kind === "linear" && storage !== undefined ? layout.read(storage.views, row) : layout.kind === "constant" ? layout.value : undefined;
     });
 };
 
@@ -247,15 +254,15 @@ const readerArchetype = (id: number) => {
 /** The one element a muted tick column's stores land on. */
 const mutedColumn = new Float64Array(1);
 
-/** A kernel's change filters in an archetype: `added` then `changed`, rows and chunks. */
+/** A kernel's change filters in an archetype: `added` then `changed`, rows, chunks and blocks. */
 const filtersOf = (loaded: LoadedKernel, archetype: ArchetypeViews): Filter[] => [
     ...loaded.setup.added.flatMap(id => {
         const storage = archetype.storages.get(id);
-        return storage === undefined ? [] : [{ ticks: storage.added, chunks: storage.chunkAdded }];
+        return storage === undefined ? [] : [{ ticks: storage.added, chunks: storage.chunkAdded, blocks: storage.blockAdded }];
     }),
     ...loaded.setup.changed.flatMap(id => {
         const storage = archetype.storages.get(id);
-        return storage === undefined ? [] : [{ ticks: storage.changed, chunks: storage.chunkChanged }];
+        return storage === undefined ? [] : [{ ticks: storage.changed, chunks: storage.chunkChanged, blocks: storage.blockChanged }];
     }),
 ];
 
@@ -263,16 +270,20 @@ const bind = (loaded: LoadedKernel, archetypeId: number, archetype: ArchetypeVie
     const columns = loaded.setup.sources.map((source, k) => {
         if (loaded.setup.muted[k]) return mutedColumn;
         if (source.kind === "entity") return archetype.entities;
+        if (source.kind === "present") return archetype.storages.has(source.id) ? archetype.entities : emptyViews.f64;
         const storage = archetype.storages.get(source.id);
+        // An optional component's columns are empty where the archetype lacks it: reads give undefined.
+        if (storage === undefined && loaded.setup.optional.includes(source.id)) return absentColumn(layouts[source.id], source);
         if (storage === undefined) throw new Error(`Archetype ${archetypeId} lacks component ${source.id}.`);
         if (source.kind === "changed") return storage.changed;
         if (source.kind === "chunks") return storage.chunkChanged;
+        if (source.kind === "blocks") return storage.blockChanged;
         const layout = layouts[source.id];
         if (layout.kind !== "linear") throw new Error(`Component ${source.id} isn't linear.`);
         return storage.views[layout.leaves[source.leaf].view];
     });
     const filters = filtersOf(loaded, archetype);
-    const addresses = [...columns.map(column => column.byteOffset), ...filters.map(filter => filter.ticks.byteOffset), ...filters.map(filter => filter.chunks.byteOffset)];
+    const addresses = [...columns.map(column => column.byteOffset), ...filters.map(filter => filter.ticks.byteOffset), ...filters.map(filter => filter.chunks.byteOffset), ...filters.map(filter => filter.blocks.byteOffset)];
     return { views: archetype, columns, filters, addresses };
 };
 
@@ -336,9 +347,10 @@ const run = (message: RunMessage): void => {
     const { columns, filters, addresses } = boundOf(loaded, message.archetype);
     const { commands } = stagingOf(loaded);
     const { wasm } = loaded;
-    if (wasm !== null && loaded.setup.wasm !== null) {
+    // WASM runs only archetypes with every optional component; the JS kernel runs the rest.
+    if (wasm !== null && loaded.setup.wasm !== null && loaded.setup.optional.every(id => boundOf(loaded, message.archetype).views.storages.has(id))) {
         wasm(message.start, message.end, message.tick, message.lastRun, ...addresses, ...message.lookups, ...message.indexes,
-            ...scalarValues(loaded.setup.wasm.scalars, message.resources, message.args),
+            ...scalarValues(loaded.setup.wasm.scalars, message.resources, message.args, message.shared),
             ...message.partials < 0 ? [] : [message.partials]);
         return;
     }
@@ -352,7 +364,7 @@ const run = (message: RunMessage): void => {
         at += count;
     }
     forEachPassingRange(filters, message.lastRun, message.start, message.end, (start, end) =>
-        loaded.kernel(columns, start, end, message.resources, loaded.lookups, loaded.setup.keys, message.args, commands, message.tick, partials, 0));
+        loaded.kernel(columns, start, end, message.resources, loaded.lookups, loaded.setup.keys, message.args, commands, message.tick, partials, 0, undefined, undefined, undefined, undefined, message.shared));
 };
 
 const load = async (setups: readonly KernelSetup[]): Promise<void> => {
@@ -373,7 +385,7 @@ const load = async (setups: readonly KernelSetup[]): Promise<void> => {
         const since: Since | null = setup.lookups.some(lookup => lookup.changed !== null) ? { value: 0 } : null;
         const lookups = setup.lookups.map((lookup, k): unknown => readers.find(found => found.lookup === k)?.reader
             ?? (lookup.changed === null || since === null ? createLookup(lookup) : createChangedLookup(lookup, lookup.changed, since)));
-        kernels.set(setup.index, { since, setup, kernel: loaded[i].module.create(setup.booleans, setup.strides.map((stride, k) => setup.muted[k] ? 0 : stride), setup.offsets.map((offset, k) => setup.muted[k] ? 0 : offset), setup.up.booleans, setup.up.strides, setup.up.offsets), wasm: loaded[i].wasm, lookups, readers, staging: null, bound: [] });
+        kernels.set(setup.index, { since, setup, kernel: loaded[i].module.create(setup.booleans, setup.strides.map((stride, k) => setup.muted[k] ? 0 : stride), setup.offsets.map((offset, k) => setup.muted[k] ? 0 : offset), setup.up.booleans, setup.up.strides, setup.up.offsets, setup.labels), wasm: loaded[i].wasm, lookups, readers, staging: null, bound: [] });
     });
 };
 
@@ -423,54 +435,30 @@ const runBuildTask = (payloads: Float64Array, base: number, buffer: ArrayBufferL
  * Runs tasks from this worker's ring in shared memory, blocking between them, until the main thread asks it to leave;
  * then it returns to handling messages.
  */
-const runWindow = (message: Extract<ToWorker, { kind: "window" }>): void => {
+const openWindow = (message: Extract<ToWorker, { kind: "window" }>): void => {
     const buffer = required(memory, "memory").buffer;
     // The pool's control state never moves, so these views last the window.
     const control = new Int32Array(buffer, message.control + message.worker * controlWords * 4, controlWords);
     const statuses = new Int32Array(buffer, message.statuses + message.worker * ringSize * 4, ringSize);
     const payloads = new Float64Array(buffer, message.payloads + message.worker * ringSize * taskWords * 8, ringSize * taskWords);
-    let next = Atomics.load(control, done);
-    for (;;) {
-        const seen = Atomics.load(control, signal);
-        if (next < Atomics.load(control, posted)) {
-            const ring = next % ringSize;
-            const base = ring * taskWords;
-            // A task from a later window waits until this worker has handled the messages sent before it.
-            if (payloads[base + 6] !== message.epoch) return;
-            let status = next + 1;
-            try {
-                refreshMemory();
-                const kernel = payloads[base];
-                if (kernel === buildKernel) runBuildTask(payloads, base, buffer, message);
-                else if (kernel !== idleKernel) {
-                    const loaded = kernels.get(kernel);
-                    if (loaded === undefined) throw new Error("Worker can't run this task.");
-                    const line = payloads[base + 8];
-                    const participants = payloads[base + 11];
-                    const scalarCount = payloads[base + 7];
-                    const partials = loaded.setup.reduces ? payloads[base + taskFields + scalarCount] : -1;
-                    const partialBytes = loaded.setup.reduces ? payloads[base + taskFields + scalarCount + 1] : 0;
-                    runWasm(loaded, payloads[base + 1], payloads[base + 2], payloads[base + 3], payloads[base + 4], payloads[base + 5],
-                        Array.from(payloads.subarray(base + taskFields, base + taskFields + scalarCount)),
-                        line < 0 ? null : { words: new Int32Array(buffer, message.claims + line * lineWords * 4, participants * lineWords), self: payloads[base + 10], participants },
-                        payloads[base + 9], partials ?? -1, partialBytes ?? 0);
-                }
-            }
-            catch {
-                status = -status;
-            }
-            Atomics.store(statuses, ring, status);
-            next++;
-            Atomics.store(control, done, next);
-            Atomics.notify(control, done);
-            continue;
+    runWindow(control, statuses, payloads, message.epoch, base => {
+        refreshMemory();
+        const kernel = payloads[base];
+        if (kernel === buildKernel) runBuildTask(payloads, base, buffer, message);
+        else if (kernel !== idleKernel) {
+            const loaded = kernels.get(kernel);
+            if (loaded === undefined) throw new Error("Worker can't run this task.");
+            const line = payloads[base + 8];
+            const participants = payloads[base + 11];
+            const scalarCount = payloads[base + 7];
+            const partials = loaded.setup.reduces ? payloads[base + taskFields + scalarCount] : -1;
+            const partialBytes = loaded.setup.reduces ? payloads[base + taskFields + scalarCount + 1] : 0;
+            runWasm(loaded, payloads[base + 1], payloads[base + 2], payloads[base + 3], payloads[base + 4], payloads[base + 5],
+                Array.from(payloads.subarray(base + taskFields, base + taskFields + scalarCount)),
+                line < 0 ? null : { words: new Int32Array(buffer, message.claims + line * lineWords * 4, participants * lineWords), self: payloads[base + 10], participants },
+                payloads[base + 9], partials ?? -1, partialBytes ?? 0);
         }
-        if (Atomics.load(control, epoch) !== message.epoch) return;
-        // Tiers follow each other closely, so spin briefly before paying for a blocking wait's wake-up.
-        const deadline = performance.now() + 0.05;
-        while (Atomics.load(control, signal) === seen && performance.now() < deadline);
-        if (Atomics.load(control, signal) === seen) Atomics.wait(control, signal, seen);
-    }
+    });
 };
 
 /** Where messages come from and replies go: this worker's own scope, until a lent worker's owner gives it a port. */
@@ -492,7 +480,7 @@ const handle = async (message: ToWorker): Promise<void> => {
         return;
     }
     if (message.kind === "window") {
-        runWindow(message);
+        openWindow(message);
         return;
     }
     if (message.kind === "layout") {

package/src/implementation/world/workers-follow.test.ts

@@ -0,0 +1,51 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { expect, it } from "vitest";
+import { System } from "../../interface/system/system.js";
+import { Finalizer } from "../../interface/finalizer/finalizer.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld, join } from "./create.js";
+import type { WorkerPlatform } from "./worker-platform.js";
+
+const heat = Symbol("workersFollowTest/heat");
+const other = Symbol("workersFollowTest/other");
+declare module "@adobe/ecs" {
+    interface Components {
+        [heat]: { type: number };
+        [other]: { type: number };
+    }
+}
+
+const spawnRows = System.create({}, ({ commands }) => {
+    for (let i = 0; i < 64; i++) commands.spawn([heat])({ [heat]: i });
+});
+const cool = System.create({ kernel: true, components: { with: [heat] } }, row => {
+    row[heat] = row[heat] * 0.5;
+});
+const setWorkers = System.create({}, ({ resources }) => {
+    resources[workers] = 2;
+});
+
+it("follows a change of the workers resource at the next run, though the program changed while a thread is joined", async () => {
+    let starts = 0;
+    // A platform with no workers to give: each start the world tries is counted.
+    const platform: WorkerPlatform = { count: 3, start: () => { starts++; return null; } };
+    const world = createWorld({ [workers]: 0 }, { pool: platform, minimumChunk: 2 });
+    const channel = new MessageChannel();
+    const shared = world.share(channel.port1);
+    const remote = await join(channel.port2, { threads: ["main"] });
+    try {
+        await shared;
+        await world.run(spawnRows);
+        await world.run(cool);
+        await world.run(setWorkers);
+        expect(starts).toBe(0);
+        // A finalizer created between runs changes the program, so the next run drains the joined thread first.
+        Finalizer.create({ components: { with: [other] } }, () => {});
+        await world.run(cool);
+        expect(starts).toBe(1);
+    }
+    finally {
+        await remote.dispose();
+        await world.dispose();
+    }
+});

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
 import type * as Fixture from "./workers.fixture.js";
 

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

@@ -1,6 +1,5 @@
-import { Component } from "../../interface/component/component.js";
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { Entity } from "../../interface/entity/entity.js";
-import { Resource } from "../../interface/resource/resource.js";
 import type { Schema } from "../../interface/schema/schema.js";
 import { System } from "../../interface/system/system.js";
 import type { World } from "../../interface/world/world.js";
@@ -9,6 +8,7 @@ import { createWorld } from "./create.js";
 import { workers } from "../../interface/resources/workers.js";
 import { countingWorkers } from "./platforms.test-helper.js";
 import type { WorkerPlatform } from "./worker-platform.js";
+import type { F32 } from "../../interface/math/index.js";
 
 /** Scenarios of kernels on workers against the main thread alone, run built in node and from source in chromium. */
 
@@ -34,10 +34,10 @@ const seconds = Symbol("workersTest/seconds");
 
 declare module "@adobe/ecs" {
     export interface Components {
-        [position]: { type: readonly [number, number] };
-        [velocity]: { type: readonly [number, number] };
+        [position]: { type: Schema.Type<{ type: "array"; items: { type: "number"; precision: 1 }; minItems: 2; maxItems: 2 }> };
+        [velocity]: { type: Schema.Type<{ type: "array"; items: { type: "number"; precision: 1 }; minItems: 2; maxItems: 2 }> };
         [target]: { type: Entity };
-        [offset]: { type: number };
+        [offset]: { type: F32 };
         [spawned]: { type: true };
         [tagA]: { type: true };
         [tagB]: { type: true };
@@ -50,37 +50,22 @@ declare module "@adobe/ecs" {
         [tagI]: { type: true };
     }
     export interface Resources {
-        [seconds]: { type: number };
+        [seconds]: { type: number; default: 0.25 };
     }
 }
 
-Component.register(position, { type: vec2 });
-Component.register(velocity, { type: vec2 });
-Component.register(target, { type: Entity.schema });
-Component.register(offset, { type: { type: "number", precision: 1 } });
-Component.register(spawned, { type: { const: true } });
-Component.register(tagA, { type: { const: true } });
-Component.register(tagB, { type: { const: true } });
-Component.register(tagC, { type: { const: true } });
-Component.register(tagD, { type: { const: true } });
-Component.register(tagE, { type: { const: true } });
-Component.register(tagF, { type: { const: true } });
-Component.register(tagG, { type: { const: true } });
-Component.register(tagH, { type: { const: true } });
-Component.register(tagI, { type: { const: true } });
 
 /** 64 entities in each of the 512 archetypes the tags combine into. */
-const scatter = System.create({ name: "workersTest/scatter" }, ({ commands }) => {
+const scatter = System.create({}, ({ commands }) => {
     for (let i = 0; i < 512 * 64; i++) {
         const components: (typeof position | typeof velocity | (typeof tags)[number])[] = [position, velocity];
         tags.forEach((tag, bit) => { if (((i >> 6) & (1 << bit)) !== 0) components.push(tag); });
         commands.spawn(components)({ [position]: [i, 0], [velocity]: [1, i % 5] });
     }
 });
-Resource.register(seconds, { type: { type: "number", default: 0.25 } });
 
 /** Spawns `count` moving entities, each following the one before it. */
-const seed = System.create({ name: "workersTest/seed", input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input, commands }) => {
+const seed = System.create({}, ({ commands }, input: { readonly count: number }) => {
     let previous = commands.spawn([position, velocity])({ [position]: [0, 0], [velocity]: [1, 0] });
     for (let i = 1; i < input.count; i++) {
         previous = commands.spawn([position, velocity, target])({ [position]: [i, 0], [velocity]: [1, i % 7], [target]: previous });
@@ -88,10 +73,8 @@ const seed = System.create({ name: "workersTest/seed", input: { type: "object",
 });
 
 const integrate = System.create({
-    name: "workersTest/integrate",
-    kernel: "cpu",
-    components: { read: [velocity], write: [position] },
-    resources: { read: [seconds] },
+    kernel: true,
+    components: { with: [velocity, position] },
 }, (row, { resources }) => {
     const [x, y] = row[position];
     const [vx, vy] = row[velocity];
@@ -100,9 +83,8 @@ const integrate = System.create({
 
 /** Structural commands from workers: rows past a threshold spawn a marker and lose their velocity. */
 const split = System.create({
-    name: "workersTest/split",
-    kernel: "cpu",
-    components: { read: [position], has: [velocity] },
+    kernel: true,
+    components: { with: [position, velocity] },
     after: [integrate],
 }, (row, { commands }) => {
     const [x, y] = row[position];
@@ -114,10 +96,9 @@ const split = System.create({
 
 /** Lookups from workers: offset by the distance to the target. */
 const follow = System.create({
-    name: "workersTest/follow",
-    kernel: "cpu",
-    components: { read: [position, target], write: [offset] },
-    lookup: { targets: { read: [position] } },
+    kernel: true,
+    components: { with: [position, target, offset] },
+    lookup: { targets: { with: [position] } },
     after: [split],
 }, (row, { lookup: { targets } }) => {
     const other = targets(row[target]);
@@ -125,31 +106,28 @@ const follow = System.create({
     row[offset] = other === null ? -1 : x - other[position][0];
 }, );
 
-const main = System.create({ name: "workersTest/main", systems: [integrate, split, follow] });
+const main = System.create({ systems: [integrate, split, follow] });
 
 /** Every row writes the same entity, so only merge order decides which value survives. */
 const stamp = System.create({
-    name: "workersTest/stamp",
-    kernel: "cpu",
-    input: { type: "object", properties: { entity: Entity.schema } },
-    components: { read: [position] },
-}, (row, { input, commands }) => {
+    kernel: true,
+    components: { with: [position] },
+}, (row, { commands }, input: { readonly entity: Entity }) => {
     const [x, y] = row[position];
     commands.add(input.entity, offset, x * 1000 + y);
 });
 
 /** Despawns entity 1, the resource entity, since index 0 is never an entity and registration reserves the next first. */
 const unlink = System.create({
-    name: "workersTest/unlink",
-    kernel: "cpu",
-    components: { has: [target] },
+    kernel: true,
+    components: { with: [target] },
 }, (_, { commands }) => {
     // @ts-expect-error an untyped caller can pass any number
     commands.despawn(1);
 });
 
 /** Archetypes in this order: 5 rows the main thread runs, 1,000 that workers run, then 10 more on the main thread. */
-const sources = System.create({ name: "workersTest/sources" }, ({ commands }) => {
+const sources = System.create({}, ({ commands }) => {
     for (let i = 0; i < 5; i++) commands.spawn([offset, tagD])({ [offset]: i });
     for (let i = 5; i < 1_005; i++) commands.spawn([offset, tagA])({ [offset]: i });
     for (let i = 1_005; i < 1_015; i++) commands.spawn([offset, tagB])({ [offset]: i });
@@ -157,11 +135,9 @@ const sources = System.create({ name: "workersTest/sources" }, ({ commands }) =>
 
 /** A spawn per row, from wherever its chunk runs; with `edit`, each spawn is also added to and removed from. */
 const emit = System.create({
-    name: "workersTest/emit",
-    kernel: "cpu",
-    input: { type: "object", properties: { edit: { type: "boolean" } } },
-    components: { read: [offset], not: [spawned] },
-}, (row, { input, commands }) => {
+    kernel: true,
+    components: { with: [offset], not: [spawned] },
+}, (row, { commands }, input: { readonly edit: boolean }) => {
     const entity = commands.spawn([position, spawned, tagC])({ [position]: [row[offset], -row[offset]] });
     if (input.edit) {
         commands.add(entity, velocity, [row[offset], 1]);
@@ -170,11 +146,11 @@ const emit = System.create({
 });
 
 const emitted = { seen: 0 };
-const countEmitted = System.create({ name: "workersTest/countEmitted", components: { added: [position], has: [spawned] } }, () => { emitted.seen++; });
+const countEmitted = System.create({ components: { added: [position], with: [spawned] } }, () => { emitted.seen++; });
 
 const gathered: Entity[] = [];
-const gatherPositioned = System.create({ name: "workersTest/gatherPositioned", observer: true, components: { has: [position] } }, row => { gathered.push(row.entity); });
-const gatherSpawned = System.create({ name: "workersTest/gatherSpawned", observer: true, components: { has: [spawned] } }, row => { gathered.push(row.entity); });
+const gatherPositioned = System.create({ observer: true, components: { with: [position] } }, row => { gathered.push(row.entity); });
+const gatherSpawned = System.create({ observer: true, components: { with: [spawned] } }, row => { gathered.push(row.entity); });
 
 /** The entities an observer row system passes, in storage order. */
 const storageOrder = async (world: World, gather: System<void>): Promise<Entity[]> => {
@@ -252,8 +228,9 @@ export const unlinked = (): Promise<number> => using(createWorld({ [workers]: 2
 /** Workers ended by `dispose`, and what a run after it rejects with. */
 export const disposed = async (): Promise<{ readonly started: number; readonly terminated: number; readonly after: string }> => {
     const counting = countingWorkers();
-    const world = createWorld({ [workers]: 2 }, { pool: counting.platform });
-    // Workers start with the first kernel.
+    const world = createWorld({ [workers]: 2 }, { minimumChunk: 64, pool: counting.platform });
+    // Workers start with the first kernel run over rows enough for them.
+    await world.run(seed, { count: 64 });
     await world.run(main);
     await world.dispose();
     const after = await world.run(main).then(() => "resolved", (error: unknown) => String(error));

package/src/implementation/world/world-host.fixture.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { scopeChannel } from "./port.js";
 import { lentWorkers } from "./worker-platform.js";
 import { simulate } from "./workers.fixture.js";

package/src/index.ts

@@ -1,3 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * A high-performance, multithreaded Entity Component System.
+ * @module @adobe/ecs
+ */
 import { create, join } from './implementation/index.js';
 import type { Create } from './interface/world/create.js';
 import type { Join } from './interface/world/join.js';
@@ -13,4 +18,27 @@ export type World = Created;
  * values in place of their defaults; and how another thread joins one that shared itself with it,
  * `World.join(port, { threads })`.
  */
-export const World: { readonly create: Create; readonly join: Join } = { create, join };
+export const World: {
+    /**
+     * Creates a world on this thread, synchronously, with resources starting at the given values in place of their
+     * defaults. This thread is its `"world"` thread for the world's life: it runs the sync points, the ticks and the GPU
+     * device, and fills every logical thread no joined thread claims. Keys are the resources' symbols, built-in ones
+     * included (`{ [workers]: 0 }`); string keys are never a resource's, so they're ignored. Throws for a symbol that isn't
+     * a resource, or is one only the world writes. While a declaration's trait or default doesn't hold, each call fails to
+     * compile, once, naming each such key, its members and what's wrong with them.
+     */
+    readonly create: Create;
+    /**
+     * Joins, from another thread, a world that `share` let join through the other end of `port`, claiming the logical
+     * `threads` this thread fills: their objects live here, and the systems and finalizers reading them run here. Resolves,
+     * once the world accepted the claim, to the same world: its `run` runs systems there, and its `add` and `remove` take
+     * observer systems, which run here after the world's sync points. Add them before awaiting anything else, so the
+     * world's `share` resolves with them in place. Its `dispose` disconnects this thread. Rejects with an `Error` saying
+     * why it didn't join: the world refused the claim, was disposed, or its thread ended first, as the platform reports it:
+     * the world's `Worker` failing to start or throwing first, a port closed, as in node, or, in a browser, the world's
+     * thread ending once it was shared through a port this thread listened on. A browser world's worker that the page ended
+     * before this thread heard from it isn't reported, so the join stays pending. Rejects too where memory can't be shared,
+     * as without cross-origin isolation.
+     */
+    readonly join: Join;
+} = { create, join };

package/src/interface/CLAUDE.md

@@ -17,7 +17,7 @@ own. That includes:
 
 - exported types, values and functions;
 - fields, options, parameters and return types;
-- union members, failure kinds and report fields;
+- union members, failure kinds and what a run resolves or rejects with;
 - built-in components and resources;
 - the documented behaviour of an existing call.
 

package/src/interface/component/component.ts

@@ -1,4 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Key } from './key.js';
+import type { Type } from './value.js';
 
-export type Component = never;
+/**
+ * The type of component `K`'s value, as its record in `Components` declares it: `Component<typeof position>`. The
+ * namespace's `Key` and `With` name components' keys.
+ */
+export type Component<K extends Key> = Type<K>;
 
 export * as Component from './index.js';