@adobe/ecs 0.2.3 → 0.3.0

package/src/implementation/world/cascade.ts

@@ -1,7 +1,7 @@
 // © 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 { generationOf, 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';
@@ -9,8 +9,8 @@ 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.
+ * A reference value written in this sync point to check: by spawn or add commands, or of a row spawned that `linkBorn`
+ * leaves to the cascade. `holder`, `component` and `target` triples, checked once the plan's despawns are known.
  */
 export type Written = number[];
 
@@ -41,6 +41,48 @@ const aliveAfter = (state: State, target: number): boolean => {
     return locate(entities, target) >= 0;
 };
 
+/**
+ * Links each reference the rows spawned in this sync point hold to its target, before the cascade, so a target it
+ * despawns finds them as it finds any holder. One naming an entity that won't be alive isn't linked, and goes to
+ * `written` to cascade, as does every reference of a row a command touched, which the command may point elsewhere.
+ * The rows spawned into an archetype are those from `first`, by archetype id; an entity is one f64.
+ */
+export const linkBorn = (state: State, born: ReadonlyMap<number, number>, written: Written, tick: number): void => {
+    const { plan, structure, archetypes, entities, referencesWritten } = state;
+    const { slots } = plan;
+    for (const [id, first] of born) {
+        const archetype = archetypes[id];
+        const { count } = archetype;
+        if (first >= count) continue;
+        const rows = archetype.entities;
+        for (const component of structure.referenceIds) {
+            const storage = archetype.storageById[component];
+            if (storage === undefined) continue;
+            referencesWritten[component] = tick;
+            const lists = structure.holders[component] ??= createHolders();
+            fitHolders(lists, entities.length);
+            const { unitStride, unitOffset } = storage;
+            const values = storage.views.f64;
+            // `aliveAfter`, through locals, since it runs for each row spawned.
+            const { archetype: archetypeOfIndex, generation, length } = entities;
+            const { entity: planned, despawned } = plan;
+            for (let row = first; row < count; row++) {
+                const target = values[row * unitStride + unitOffset];
+                if (target === 0) continue;
+                const holder = rows[row];
+                const index = indexOf(holder);
+                const commanded = index < slots.length && slots[index] >= 0;
+                const into = indexOf(target);
+                const entry = into < slots.length ? slots[into] : -1;
+                const alive = entry >= 0 && planned[entry] === target ? despawned[entry] === 0
+                    : into < length && archetypeOfIndex[into] >= 0 && generation[into] === generationOf(target);
+                if (alive) linkHolder(lists, target, holder);
+                if (commanded || !alive) written.push(holder, component, target);
+            }
+        }
+    }
+};
+
 /**
  * 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
@@ -91,7 +133,7 @@ export const cascadeReferences = (state: State, queued: readonly Queued[], writt
  */
 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 => {
+export const indexChangesOf = (state: State, queued: readonly Queued[], fromOf: (entry: number) => Archetype | null): IndexChanges => {
     const { plan, structure, entities } = state;
     const changes: IndexChanges = { remove: [], add: [] };
     for (let entry = 0; entry < plan.count; entry++) {
@@ -106,24 +148,6 @@ export const indexChangesOf = (state: State, queued: readonly Queued[], fromOf:
             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;
 };
 

package/src/implementation/world/commands.ts

@@ -1,10 +1,13 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Commands } from '../../interface/system/commands.js';
-import { addCommand, createBuffer, despawnCommand, pushCommand, pushComponent, removeCommand, spawnCommand, type CommandBuffer } from './buffer.js';
+import { addCommand, createBuffer, despawnCommand, despawnWhereCommand, despawnWhereHolds, pushCommand, pushComponent, removeCommand, spawnCommand, type CommandBuffer } from './buffer.js';
+import type { Archetype } from './archetype.js';
 import { reserve } from './entities.js';
 import { listShapeOf, presetSpawnerOf, spawnerOf, type ListShape } from './lists.js';
-import { commandIdOf, idOf, storedShared, type Key, type State } from './state.js';
+import { commandIdOf, idOf, queryIdOf, storedShared, type Key, type State } from './state.js';
 import { spawnTables } from './tables.js';
+import { holdsValuesOf } from './where.js';
+import { checkWhereValues } from '../../interface/system/check.js';
 import { declarationOf, isWorldWritten, kindOf, labelOf, threadOfDeclaration, whyUnregistered } from '../../interface/registry/index.js';
 import { matchesSchema } from '../../interface/registry/schemas.js';
 
@@ -83,6 +86,32 @@ const queueResources = (state: State, resources: object): void => {
 /** Values of a list add given none, which only an untyped caller does. */
 const empty = {};
 
+const noKeys: readonly unknown[] = [];
+
+/**
+ * Queues a `despawnWhere`, its ids resolved and its `where` checked first, so a key that isn't a component, or a `where`
+ * that isn't of shared values, queues nothing.
+ */
+const pushDespawnWhere = (state: State, buffer: CommandBuffer, query: Parameters<Commands["despawnWhere"]>[0]): void => {
+    const including: readonly unknown[] = query.with;
+    const excluding: readonly unknown[] = query.not ?? noKeys;
+    const { where } = query;
+    if (including.length === 0) throw new Error("commands.despawnWhere's `with` names at least one component.");
+    for (let k = 0; k < including.length; k++) queryIdOf(state, including[k]);
+    for (let k = 0; k < excluding.length; k++) queryIdOf(state, excluding[k]);
+    let holds: ((archetype: Archetype) => boolean) | null = null;
+    if (where !== undefined && Object.getOwnPropertySymbols(where).length > 0) {
+        checkWhereValues("commands.despawnWhere", "where", "a despawn", where, false);
+        const found = holdsValuesOf(state, where, false);
+        if (typeof found === "symbol") throw new Error(`commands.despawnWhere: where names "${labelOf(found)}", which isn't a shared component.`);
+        holds = found;
+    }
+    pushCommand(buffer, despawnWhereCommand, including.length);
+    for (let k = 0; k < including.length; k++) pushComponent(buffer, queryIdOf(state, including[k]), undefined);
+    for (let k = 0; k < excluding.length; k++) pushComponent(buffer, queryIdOf(state, excluding[k]), undefined);
+    if (holds !== null) pushComponent(buffer, despawnWhereHolds, holds);
+};
+
 /**
  * Commands that queue for the next sync point. A key that isn't a component commands may name throws here, inside the
  * issuing system, before anything is queued. Values are immutable by convention, so they aren't copied.
@@ -97,6 +126,7 @@ export const createCommands = (state: State, target: { readonly buffer: CommandB
     despawn: entity => {
         pushCommand(target.buffer, despawnCommand, entity);
     },
+    despawnWhere: query => pushDespawnWhere(state, target.buffer, query),
     add: (entity: number, components: symbol | readonly symbol[], values?: unknown) => {
         const { buffer } = target;
         if (typeof components === "symbol") {
@@ -119,10 +149,12 @@ export const createCommands = (state: State, target: { readonly buffer: CommandB
             pushComponent(buffer, ids[k], value === undefined ? starts[k] : value);
         }
     },
-    spawnTables: (tables, resources) => {
-        if (resources === undefined) return spawnTables(state, tables);
+    spawnTables: (tables, options) => {
+        const resources = options?.resources;
+        const updates = options?.update === true ? target.buffer : null;
+        if (resources === undefined) return spawnTables(state, tables, options?.existing, updates);
         checkResources(resources);
-        const spawned = spawnTables(state, tables);
+        const spawned = spawnTables(state, tables, options?.existing, updates);
         queueResources(state, resources);
         return spawned;
     },

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

@@ -71,28 +71,28 @@ const positions = async (world: World): Promise<Vec2[]> =>
     (await readEach(world, await select(world, { required: [position], order: { [position]: true } }), position)).map(value => value ?? [NaN, NaN]);
 
 describe("World.create", () => {
-    it("spawns once from a changed resource, then integrates", async () => {
+    it("spawns once from a changed resource, then integrates, from the run that spawns", async () => {
         const world = createWorld();
         await world.run(main);
-        expect(await positions(world)).toEqual([[0, 0], [1, 0], [2, 0]]);
-        await world.run(main);
         expect(await positions(world)).toEqual([[0, 1], [1, 1], [2, 1]]);
+        await world.run(main);
+        expect(await positions(world)).toEqual([[0, 2], [1, 2], [2, 2]]);
         expect(await readResource(world, spawnCount)).toBe(3);
     });
 
     it("reports each change to a system exactly once", async () => {
         const world = createWorld();
         await world.run(main);
-        // Spawned at the sync point, after watch ran: seen on the next run.
-        expect(await readResource(world, seen)).toBe(0);
-        await world.run(main);
+        // Spawned at the sync point before move, which watch follows: seen in the same run.
         expect(await readResource(world, seen)).toBe(3);
+        await world.run(main);
+        expect(await readResource(world, seen)).toBe(6);
         // Moved before watch in the last run, so already reported.
         await world.run(watch);
-        expect(await readResource(world, seen)).toBe(3);
+        expect(await readResource(world, seen)).toBe(6);
         await world.run(move);
         await world.run(watch);
-        expect(await readResource(world, seen)).toBe(6);
+        expect(await readResource(world, seen)).toBe(9);
     });
 
     it("applies the net structural change of a sync point", async () => {

package/src/implementation/world/create.ts

@@ -1,7 +1,7 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Finalizer } from '../../interface/finalizer/created.js';
 import type { Rule } from '../../interface/rule/created.js';
-import { requireDefinition, type Definition } from '../../interface/registry/index.js';
+import { definitionOf, requireDefinition, type Definition } from '../../interface/registry/index.js';
 import type { World } from '../../interface/world/world.js';
 import type { Input } from '../../interface/system/input.js';
 import type { System } from '../../interface/system/system.js';
@@ -33,8 +33,8 @@ import { refreshDirectories } from './directories.js';
 import { createRegistrar, type Registration } from './register.js';
 import type { Schedule } from '../../interface/registry/schedule.js';
 import { ensureResources, findResource, initialOf, setResource } from './resources.js';
-import { ensureProgramResources, activate, finalizerCrossing, placeFinalizers } from './activate.js';
-import { isObserver, isWorldWritten, kindOf, programVersion, scheduleOf, type Composite } from '../../interface/registry/index.js';
+import { ensureProgramResources, activate, finalizerCrossing, placeFinalizers, programResourcesChanged, type Ensured } from './activate.js';
+import { isObserver, isWorldWritten, kindOf, scheduleOf, type Composite } from '../../interface/registry/index.js';
 import { always } from '../../interface/resources/always.js';
 import { cadence, type Cadence } from '../../interface/resources/cadence.js';
 import { clock } from '../../interface/resources/clock.js';
@@ -43,6 +43,10 @@ import { stampChanged } from './archetype.js';
 import { createLoop, platformFrame, platformTimer, type Clock, type LoopPlatform } from './loop.js';
 import { presetLevelsOf } from './lists.js';
 import { createState, defaultOf, idOf, reside, startTicking, type Key } from './state.js';
+import { asksForChanges, changesOf, resourcesWrittenBy, startRecording, takesInput } from './run-changes.js';
+import type { ChangeSet } from '../../interface/finalizer/body.js';
+import type { Essential } from '../../interface/component/value.js';
+import type { Resource } from '../../interface/resource/resource.js';
 import { indexOf } from './entities.js';
 import { touchedHeld } from './up.js';
 import { isHeld } from './transfers.js';
@@ -53,6 +57,9 @@ type Queue = <T>(task: () => T | Promise<T>) => Promise<T>;
 
 /** A task's failure as the queue's own chain carries it, which never rejects: made only when a task fails. */
 type Carried = { readonly thrown: unknown };
+/** A schedule of nothing, whose run is its sync point alone. */
+const noTiers: Schedule = { tiers: [], reductions: new Map(), observer: [], syncs: [] };
+
 const thrownValues = new WeakSet<object>();
 const thrownOf = (error: unknown): Carried => {
     const wrapped = { thrown: error };
@@ -277,7 +284,7 @@ export const createWorld = (resources: InitialResources = {}, options: WorldOpti
         if (state.observer.posts.length !== 0) await settlePosts(state, true);
     };
     let disposed = false;
-    const ensured = { version: -1 };
+    const ensured: Ensured = { version: -1, keys: -1, traits: false };
 
     const minimumChunk = options.minimumChunk ?? defaultMinimumChunk;
 
@@ -538,7 +545,7 @@ export const createWorld = (resources: InitialResources = {}, options: WorldOpti
     /** Follows what changed since the last run: program resources, change watches, workers and the device; null when nothing did. */
     const prepareRun = (): Promise<void> | null => {
         // Resources added between runs move the resource entity, whose structs a tail may still read.
-        if (ensured.version !== programVersion() && (state.channels.length > 0 || state.observer.posts.length > 0)) return drainThenPrepare();
+        if (programResourcesChanged(ensured) && (state.channels.length > 0 || state.observer.posts.length > 0)) return drainThenPrepare();
         ensureProgramResources(state, ensured);
         if (startWatches(state)) return followChanges(true, false);
         if (workersChanged()) return followChanges(false, true);
@@ -956,9 +963,57 @@ export const createWorld = (resources: InitialResources = {}, options: WorldOpti
         },
     });
 
+    /**
+     * Runs a system or composite, recording its own changes, which it resolves to: what earlier finalizers queued
+     * applies first, at a sync point of its own, and the recording covers the run's sync points alone.
+     */
+    const runChanging = (definition: Definition, value: unknown): Promise<unknown> => {
+        const started = enqueue(() => startChanges(definition));
+        const ran = runWith(definition, value);
+        const taken = enqueue(takeChanges);
+        return Promise.all([started, ran, taken]).then(([, , changes]) => changes);
+    };
+    const startChanges = (definition: Definition): unknown => {
+        checkLive();
+        const flushed = execution(definition, undefined, noTiers);
+        if (flushed instanceof Promise) return flushed.then(report => startRecordingOf(definition, report));
+        startRecordingOf(definition, flushed);
+        return undefined;
+    };
+    const startRecordingOf = (definition: Definition, flushed: RunReport): void => {
+        outOfBand.reportAll(flushed.failures);
+        state.recording = startRecording(state, resourcesWrittenBy(definition));
+    };
+    const takeChanges = (): unknown => {
+        const { recording } = state;
+        state.recording = null;
+        if (recording === null) throw new Error("The run's changes weren't recorded.");
+        return changesOf(state, recording);
+    };
+
+    function run<I, R>(system: System<I, R>, ...input: Input<NoInfer<I>>): Promise<R>;
+    function run<I, R>(system: System<I, R>, ...input: [...Input<NoInfer<I>>, options: { readonly changes: true }]): Promise<ChangeSet<Essential, Resource.Key>>;
+    function run(system: System<unknown, unknown>, ...args: readonly unknown[]): Promise<unknown> {
+        // Options come last, so a run not asking for changes reads one value more.
+        const { length } = args;
+        if (length === 0 || !asksForChanges(args[length - 1])) return runWith(system, args[0]);
+        const definition = definitionOf(system);
+        let input = false;
+        try {
+            input = definition !== undefined && takesInput(definition);
+        }
+        catch {
+            // A composite whose schedule can't be made fails its run, as `runWith` finds.
+            return runWith(system, args[0]);
+        }
+        // A system taking input whose input is all it was given runs with it.
+        if (definition === undefined || (input && args.length < 2)) return runWith(system, args[0]);
+        return runChanging(definition, input ? args[0] : undefined);
+    }
+
     const world: CreatedWorld = {
         // A run gives what its system's body returned, `R` by the system's type.
-        run: <I, R>(system: System<I, R>, ...input: Input<NoInfer<I>>) => runWith(system, input[0]) as Promise<R>,
+        run,
         share: port => {
             if (disposed) return Promise.reject(new Error("The world is disposed."));
             if (!state.memory.shared) return Promise.reject(new Error("Without cross-origin isolation memory can't be shared, so no thread can join."));

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

@@ -4,7 +4,7 @@ import { Rule } from "../../interface/rule/rule.js";
 import { System } from "../../interface/system/system.js";
 import { createWorld } from "../index.js";
 import { readResource } from "./reads.test-helper.js";
-import { Entity, F32, I32, Mat4x4, Quat, U32, Vec2, Vec3, Vec4 } from "../../index.js";
+import { Entity, F32, I32, Mat4x4, Quat, U32, Vec2, Vec3, Vec4, type Resource } from "../../index.js";
 
 const pool = Symbol();
 const names = Symbol();
@@ -14,6 +14,8 @@ const index = Symbol();
 const turn = Symbol();
 const least = Symbol();
 const all = Symbol();
+const written = Symbol();
+const keys = Symbol();
 
 /** A pool declared through an alias of ReadonlyMap. */
 type Pool = ReadonlyMap<string, number>;
@@ -30,6 +32,8 @@ declare module "@adobe/ecs" {
         [turn]: { type: Quat };
         [least]: { type: F32; reduce: "min" };
         [all]: { type: boolean; reduce: "&" };
+        [written]: { type: ReadonlyMap<Resource.Key, unknown> };
+        [keys]: { type: ReadonlySet<symbol> };
     }
 }
 
@@ -49,6 +53,25 @@ describe("a resource declared without a default", () => {
     });
 });
 
+describe("a ReadonlyMap or ReadonlySet of what isn't data", () => {
+    it("starts at an empty one of each world's own, which a system replaces whole, keys and values kept as they are", async () => {
+        await using first = createWorld();
+        await using second = createWorld();
+        const [firstWritten, secondWritten] = [await readResource(first, written), await readResource(second, written)];
+        expect([firstWritten, secondWritten, await readResource(first, keys)]).toEqual([new Map(), new Map(), new Set()]);
+        expect(firstWritten).not.toBe(secondWritten);
+        const value = { at: 1 };
+        await first.run(System.create(({ resources }) => {
+            resources[written] = new Map([[count, value]]);
+            resources[keys] = new Set([count]);
+        }));
+        const read = await readResource(first, written);
+        expect([read.get(count), await readResource(first, keys)]).toEqual([value, new Set([count])]);
+        expect(read.get(count)).toBe(value);
+        expect(await readResource(second, written)).toBe(secondWritten);
+    });
+});
+
 describe("a derived component declared without a default", () => {
     it("starts every row of a world at one empty Map of its own, since values are replaced whole", async () => {
         const spawn = System.create(({ commands }) => {