@adobe/ecs 0.2.4 → 0.3.0

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

@@ -0,0 +1,61 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { System } from "../../interface/system/system.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld } from "./create.js";
+import { runRan, runReported } from "./outcomes.test-helper.js";
+
+const seed = Symbol("passesTest/seed");
+const event = Symbol("passesTest/event");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [seed]: { type: number };
+        [event]: { type: number };
+    }
+}
+
+/** What the systems below ran, in order. */
+const order: string[] = [];
+let firing = false;
+
+const plant = System.create(({ commands }) => { commands.spawn([seed])({ [seed]: 1 }); });
+const emit = System.create({ components: { with: [seed] } }, (row, { commands }) => {
+    order.push("emit");
+    if (firing) commands.spawn([event])({ [event]: row[seed] });
+});
+const handle = System.create({ components: { with: [event] }, after: [emit] }, row => { order.push(`handle ${row[event]}`); });
+const finish = System.create({ after: [handle] }, () => { order.push("finish"); });
+const chain = System.create([emit, handle, finish]);
+
+const fail = System.create({ components: { with: [seed] }, after: [emit] }, () => {
+    order.push("fail");
+    throw new Error("passesTest: fail");
+});
+const afterFail = System.create({ after: [fail] }, () => { order.push("after fail"); });
+const failing = System.create([emit, fail, afterFail]);
+
+describe("tiers on the world's thread", () => {
+    it("run one after another past sync points that apply nothing, and apply one with commands before the tier after it", async () => {
+        expect(System.describe(chain).tiers.map(tier => tier.sync === null)).toEqual([false, true, true]);
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(plant);
+        order.length = 0;
+        firing = false;
+        expect((await runRan(world, chain)).systems).toBe(3);
+        firing = true;
+        expect((await runRan(world, chain)).systems).toBe(3);
+        expect(order).toEqual(["emit", "finish", "emit", "handle 1", "finish"]);
+    });
+
+    it("stop at a tier whose system fails, skipping those after it", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(plant);
+        order.length = 0;
+        firing = false;
+        const reported = await runReported(world, failing);
+        expect([reported.failures.map(failure => failure.message), reported.skipped]).toEqual([["passesTest: fail"], [afterFail.name]]);
+        expect(order).toEqual(["emit", "fail"]);
+        expect((await runRan(world, failing)).systems).toBe(2);
+    });
+});

package/src/implementation/world/perf.md

@@ -229,6 +229,15 @@ Review fixes to shared components and `where`, node, alternating against the com
 - **A spawner's guard** against a component given in both calls, one check of each constant's key a spawn: `spawn singles shared` 323 → 323 ns, `spawn bulk shared` 18.0 → 18.1 ns.
 - **Reclaiming** (`reclaim.ts`): an entity walking one cell a run made an archetype, an interned value, a batch and spawner levels per cell, for good: after 20K cells 20,002 archetypes, 185 MB of heap and 9.1 MB of arena, and `one row after 100K cells walked`, a system over one row, 2.76 ms a run against 250 ns before the walk. Reclaimed and reused, after 100K cells: 11 archetypes, 9 values, 9 batches, 18 spawner levels, heap 29.7–29.9 MB from 1K cells on, arena 71,616 B throughout; `one row after 100K cells walked` 250 ns; `walk to a new cell` 10.3 → 2.8 µs a run. Waiting out empty sync points (`emptyFor`), `circle 8 cells`, round 8 cells, each emptied 7 sync points: 2.67–2.69 µs a run at 1, 2 and 4, reclaiming and reusing one archetype a run, 1.00 at 8 and 16, reclaiming nothing; `walk to a new cell` 2.69–2.73 µs at 1 to 4, 2.81 at 8, 3.06 at 16, scanning more candidates; `flicker between 2 cells` 958 ns at all, against 916 before reclaiming, the sync point's scan of its emptied archetypes. 8, so a cell left for up to 7 sync points keeps its archetype. Edges cached to an archetype of shared values are kept on it to clear, but a batch's archetype is checked by its generation instead: an edge object per spawned archetype, allocated between archetypes and their storages, made `where 1K cells moving` 10% slower, its 1K predicates walking archetypes spread over more memory; checked, +1.8%. Worlds without shared components, five rounds against the commit before: within noise (`run idle` 208 → 208 ns, `run observer` 125 → 125, `loop tick idle`, `move 1K`, `main thread 1K`, `sync point one spawn` 708 → 708, `create` +0.5%, `create flat`, `spawn bulk`, `despawn one`, `churn`, `add value`, `remote run`, `joined observer resource`, `joined observer 10K`, `handoff`, `tail prompt` +0.5% over eight rounds, `log replay`, `read run`); `run 50 idle` was +5% a system until the run's check for reclaimed archetypes kept the scan for new ones apart, out of what its runner inlines: 71.2 → 71.2 ns.
 
+Sync points and tiers that apply nothing (adobe/data#245), node, alternating eight rounds against `244f952` with the
+new benchmarks added there: eight systems over rows no entity has, each with a command it never issues. `chained
+unordered`, one tier, 538 → 538 ns a run; `chained quiet`, eight tiers by `after` with no commands, 717 → 636;
+`chained noting`, eight tiers whose commands no later system depends on, 723 → 636; `chained commanding`, eight tiers
+and seven sync points, 859 → 713. A tier boundary on the world's thread costs about 14 ns, from 26, the tiers running
+as one pass; a sync point between them with nothing to apply about 11 ns, from 20, its check of what's pending standing
+for its activation, rewinds and publishing. The other node benchmarks are within noise of `244f952` over three
+rounds, and `read run` (+3.7%) and `loop tick add remove again` (+3.9%), which make a schedule each run, over ten.
+
 ## Where the gains came from
 
 Step figures marked (vitest) are from the node vitest lane: read them as relative.

package/src/implementation/world/program.ts

@@ -10,5 +10,8 @@ import type { Key } from './state.js';
 export const triggersOf = (item: Rule | Finalizer): { readonly keys: readonly Key[]; readonly any: boolean } => {
     if (item.kind === "rule") return { keys: item.declaration.components.has ?? [], any: false };
     if (item.kind === "finalizer") return { keys: [...item.declaration.components.read ?? [], ...item.declaration.components.has ?? []], any: false };
-    return { keys: item.declaration.watch ?? [], any: true };
+    const { watch } = item.declaration;
+    // Every component, or those declaring a trait, may be met at any sync point.
+    if (watch.components === true || watch.componentTraits.length + watch.resourceTraits.length > 0) return { keys: [], any: true };
+    return { keys: [...watch.components, ...watch.resources], any: true };
 };

package/src/implementation/world/run-results.test.ts

@@ -354,6 +354,23 @@ describe("what a run gathers for tests", () => {
         expect(await runRan(world, System.create([nothing, raise]))).toEqual({ systems: 2, workers: 0, joined: 0, main: true, gpu: false });
         expect(await runRan(world, readLevel)).toEqual({ systems: 0, workers: 0, joined: 0, main: false, gpu: false });
     });
+
+    it("counts each system of a chain once, run whole or entered after a sync point that applies something", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        /** Systems each after the one before, the first after `first`. */
+        const chainOf = (length: number, first: readonly System<unknown>[]): System<unknown>[] => {
+            const links: System<unknown>[] = [];
+            for (let k = 0; k < length; k++) links.push(System.create({ after: links.length === 0 ? first : links.slice(-1) }, ({ resources }) => {
+                resources[frames] = k;
+            }));
+            return links;
+        };
+        expect(await runRan(world, System.create(chainOf(64, [])))).toEqual({ systems: 64, workers: 0, joined: 0, main: true, gpu: false });
+        const reads = System.create({ after: [spawn], components: { with: [amount] } }, row => {
+            counted += row[amount];
+        });
+        expect(await runRan(world, System.create([spawn, reads, ...chainOf(8, [reads])]))).toEqual({ systems: 10, workers: 0, joined: 0, main: true, gpu: false });
+    });
 });
 
 describe("a value a body returned", () => {

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

@@ -8,17 +8,25 @@ import { scheduleOf } from "../../interface/registry/schedule.js";
 
 const value = Symbol("scheduleTest/value");
 const other = Symbol("scheduleTest/other");
+const voxel = Symbol("scheduleTest/voxel");
+const mark = Symbol("scheduleTest/mark");
+const size = Symbol("scheduleTest/size");
 
 declare module "@adobe/ecs" {
     export interface Components {
         [value]: { type: number };
         [other]: { type: number };
+        [voxel]: { type: true };
+        [mark]: { type: true };
+    }
+    export interface Resources {
+        [size]: { type: number };
     }
 }
 
 
 /** Systems built as values, not registered, so each test's are its own. */
-const leaf = (declaration: Resolved & { readonly name: string }): Leaf => ({ kind: "system", name: declaration.name, declaration, input: undefined, body: () => {} });
+const leaf = (declaration: Resolved & { readonly name: string }): Leaf => ({ kind: "system", name: declaration.name, declaration, input: undefined, body: () => {}, commands: () => undefined });
 const composite = (declaration: Composite["declaration"] & { readonly name: string }): Composite => ({ kind: "composite", name: declaration.name, declaration });
 
 const names = (system: Definition): string[][] => scheduleOf(system).tiers.map(tier => tier.map(leaf => leaf.name));
@@ -113,6 +121,39 @@ describe("scheduleOf", () => {
             .toEqual([["a", "c"], ["b"]]);
     });
 
+    it("doesn't order two systems on a key both reach through rows that never match one entity", () => {
+        const voxels = leaf({ name: "voxels", components: { write: [value], has: [voxel], not: [mark] } });
+        const marks = leaf({ name: "marks", components: { write: [value], has: [mark] } });
+        const watching = leaf({ name: "watching", components: { read: [value], changed: [value], has: [mark] } });
+        expect(names(composite({ name: "root", systems: [voxels, marks] }))).toEqual([["voxels", "marks"]]);
+        expect(names(composite({ name: "root", systems: [voxels, watching] }))).toEqual([["voxels", "watching"]]);
+    });
+    it("orders two systems whose rows may match one entity, or that reach the key other than through their rows", () => {
+        const voxels = leaf({ name: "voxels", components: { write: [value], has: [voxel] } });
+        const marks = leaf({ name: "marks", components: { write: [value], has: [mark] } });
+        expect(() => scheduleOf(composite({ name: "root", systems: [voxels, marks] })))
+            .toThrow(`Systems "voxels" and "marks" both access "scheduleTest/value" and one writes it; order them with before or after, or, if they never match one entity, add a component of one to the other's not.`);
+        const apart = leaf({ name: "apart", components: { write: [value], has: [voxel], not: [mark] } });
+        const looking = leaf({ name: "looking", components: { has: [mark] }, lookup: { others: { read: [value] } } });
+        expect(() => scheduleOf(composite({ name: "root", systems: [apart, looking] })))
+            .toThrow(`Systems "apart" and "looking" both access "scheduleTest/value" and one writes it; order them with before or after.`);
+        // An optional component is read where an entity has it, so it excludes nothing it doesn't require.
+        const optional = leaf({ name: "optional", components: { read: [value, mark], optional: [mark] } });
+        expect(() => scheduleOf(composite({ name: "root", systems: [apart, optional] }))).toThrow('"apart" and "optional"');
+    });
+
+    it("orders a system before or after every other that uses a resource it lists, but those already ordered and those listing it too", () => {
+        const resize = leaf({ name: "resize", resources: { write: [size] }, before: [size] });
+        const frame = leaf({ name: "frame", resources: { read: [size] } });
+        const pick = leaf({ name: "pick", components: { read: [value] }, resources: { is: [size] } });
+        const old = leaf({ name: "old", resources: { read: [size] }, before: [resize] });
+        expect(names(composite({ name: "root", systems: [frame, pick, resize, old] }))).toEqual([["old"], ["resize"], ["frame", "pick"]]);
+        const last = leaf({ name: "last", resources: { read: [size] }, after: [size] });
+        expect(names(composite({ name: "root", systems: [last, frame, resize] }))).toEqual([["resize"], ["frame"], ["last"]]);
+        const again = leaf({ name: "again", resources: { write: [size] }, before: [size] });
+        expect(() => scheduleOf(composite({ name: "root", systems: [resize, again, frame] }))).toThrow(`Systems "resize" and "again" both access "scheduleTest/size"`);
+    });
+
     it("schedules two systems of one name as two, and one listed twice as one", () => {
         const a = leaf({ name: "a", components: { write: [value] } });
         const copy = leaf({ name: "a", components: { write: [value] }, after: [a] });

package/src/implementation/world/state.ts

@@ -78,6 +78,14 @@ export const countRan = (state: State, runners: readonly RanRunner[]): void => {
     for (let k = 0; k < tier.logs.length; k++) ran.joined.add(tier.logs[k]);
 };
 
+/** Counts runners into `ran` that all ran here, none on a joined thread: on `main` unless a joined thread claims it. */
+export const countRanHere = (state: State, systems: number, gpu: boolean): void => {
+    const { ran } = state;
+    ran.systems += systems;
+    if (systems !== 0 && state.claims.get("main") === undefined) ran.main = true;
+    if (gpu) ran.gpu = true;
+};
+
 /** Starts gathering what a run ran. */
 export const startRan = (ran: Ran): void => {
     ran.systems = 0;

package/src/implementation/world/sync-points.test.ts

@@ -79,6 +79,11 @@ const tally = System.create({ components: { with: [grown] }, after: [sprout] },
 const garden = System.create([plant, sprout, tally]);
 const readChildren = System.create({ readonly: true }, ({ resources }) => resources[children]);
 
+const spawnSeedlings = System.create(({ commands }) => { commands.spawn(Seedling)({ [seed]: 1, [grown]: 2 }); });
+const countSeedlings = System.create({ components: { with: [seed, grown] }, after: [spawnSeedlings] }, (row, { resources }) => { resources[children] += row[grown]; });
+/** Declared below the systems whose commands name it. */
+const Seedling = [seed, grown] as const;
+
 describe("sync points within a run", () => {
     it("apply commands before a later system that depends on what they change, which then sees them in the same run", async () => {
         const world = createWorld({ [workers]: 0 });
@@ -122,6 +127,13 @@ describe("sync points within a run", () => {
         }
     });
 
+    it("follow commands naming an archetype declared below their system", async () => {
+        expect(System.describe(System.create([spawnSeedlings, countSeedlings])).tiers.map(tier => tier.sync?.map(reason => reason.keys) ?? null)).toEqual([[[seed, grown]], null]);
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(System.create([spawnSeedlings, countSeedlings]));
+        expect(await world.run(readChildren)).toBe(2);
+    });
+
     it("commit a kernel's staged spawns at a sync point within the run, for a later tier", async () => {
         expect(System.describe(garden).tiers.map(tier => tier.sync === null)).toEqual([false, false, true]);
         await using world = createWorld({ [workers]: 0 });

package/src/implementation/world/synchronize.ts

@@ -147,10 +147,11 @@ const closedOf = (state: State, archetype: Archetype): Archetype => {
 };
 
 /**
- * Despawns each entity a `despawnWhere` command selects given the plan so far: those planned, by where they're going,
- * then the rest, by the archetype they're in. Never the resource entity.
+ * Despawns each entity alive before the sync point that a `despawnWhere` command selects given the plan so far: those
+ * planned, by where they're going, then the rest, by the archetype they're in. Never the resource entity, nor an
+ * entity the sync point spawns: `born` holds the first row each archetype gained at it.
  */
-const despawnWhere = (state: State, buffer: CommandBuffer, command: number, within: boolean): void => {
+const despawnWhere = (state: State, buffer: CommandBuffer, command: number, within: boolean, born: ReadonlyMap<number, number>): void => {
     const { plan, archetypes } = state;
     const { ids } = buffer;
     const start = buffer.starts[command];
@@ -159,8 +160,12 @@ const despawnWhere = (state: State, buffer: CommandBuffer, command: number, with
     const where = ids[last - 1] === despawnWhereHolds ? buffer.values[last - 1] : null;
     const holds = typeof where === "function" ? where : null;
     const end = holds === null ? last : last - 1;
+    const { row } = state.entities;
     for (let entry = 0; entry < plan.count; entry++) {
-        if (plan.despawned[entry] === 1 || plan.entity[entry] === state.resourceEntity) continue;
+        const from = plan.from[entry];
+        if (plan.despawned[entry] === 1 || plan.entity[entry] === state.resourceEntity || from < 0) continue;
+        const first = born.get(from);
+        if (first !== undefined && row[indexOf(plan.entity[entry])] >= first) continue;
         const to = archetypes[plan.to[entry]];
         if (matches(within && plan.to[entry] !== plan.from[entry] ? closedOf(state, to) : to, ids, start, middle, end, holds)) plan.despawned[entry] = 1;
     }
@@ -171,8 +176,9 @@ const despawnWhere = (state: State, buffer: CommandBuffer, command: number, with
         if (archetype.resource || archetype.count === 0 || !matches(archetype, ids, start, middle, end, holds)) continue;
         ensurePlanCapacity(state, plan.count + archetype.count);
         const { entities } = archetype;
-        for (let row = 0; row < archetype.count; row++) {
-            const entity = entities[row];
+        const alive = born.get(id) ?? archetype.count;
+        for (let at = 0; at < alive; at++) {
+            const entity = entities[at];
             const index = indexOf(entity);
             if (slots[index] < 0) plan.despawned[addPlanned(state, entity, index, id, id)] = 1;
         }
@@ -183,7 +189,7 @@ const despawnWhere = (state: State, buffer: CommandBuffer, command: number, with
  * Plan: the net change for each entity, in issue order. Commands against dead entities do nothing. Reference values
  * written by commands go to `written`, to check once despawns are known.
  */
-const planOf = (state: State, queued: readonly Queued[], written: Written): void => {
+const planOf = (state: State, queued: readonly Queued[], written: Written, born: ReadonlyMap<number, number>): void => {
     const { plan, structure } = state;
     if (plan.slots.length < state.entities.length) plan.slots = new Int32Array(Math.max(state.entities.length, plan.slots.length * 2)).fill(-1);
     const { slots } = plan;
@@ -199,7 +205,7 @@ const planOf = (state: State, queued: readonly Queued[], written: Written): void
         for (let command = 0; command < buffer.count; command++) {
             const kind = kinds[command];
             if (kind === despawnWhereCommand) {
-                despawnWhere(state, buffer, command, within);
+                despawnWhere(state, buffer, command, within, born);
                 ensurePlanCapacity(state, plan.count + buffer.count - command);
                 continue;
             }
@@ -742,7 +748,7 @@ const preparePending = (state: State, queued: readonly Queued[], isolated: boole
         if (!isolated) plan.spawned += commitBatches(state, tick, born, deriving ? close : null);
         plan.spawned += commitStaged(state, queued, tick, born, deriving ? close : null);
         const written: Written = [];
-        planOf(state, queued, written);
+        planOf(state, queued, written, born);
         if (structure.rederive && !isolated) rederive(state);
         if (deriving) for (let entry = 0; entry < plan.count; entry++) if (plan.despawned[entry] === 0) plan.to[entry] = close(state.archetypes[plan.to[entry]]).id;
         let index: IndexChanges | null = null;

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

@@ -46,18 +46,20 @@ const tablesOf = (components: readonly Component.Key[], resources: readonly Reso
     System.create({ readonly: true, tables: { components, resources, not } }, ({ tables }): Tables => tables);
 
 const spawnedBy: { spawned: Table.Spawned } = { spawned: { entities: [], dropped: 0 } };
-const given: { tables: readonly Table[]; resources?: { readonly [key: symbol]: unknown }; existing?: ReadonlyMap<Entity, Entity> } = { tables: [] };
+const given: { tables: readonly Table[]; resources?: { readonly [key: symbol]: unknown }; existing?: ReadonlyMap<Entity, Entity>; update?: boolean } = { tables: [] };
 const spawnGiven = System.create(({ commands }) => {
-    spawnedBy.spawned = commands.spawnTables(given.tables, { resources: given.resources, existing: given.existing });
+    spawnedBy.spawned = commands.spawnTables(given.tables, { resources: given.resources, existing: given.existing, update: given.update });
 });
-const spawnTables = async (world: ReturnType<typeof inline>, tables: readonly Table[], existing?: ReadonlyMap<Entity, Entity>): Promise<Table.Spawned> => {
+const spawnTables = async (world: ReturnType<typeof inline>, tables: readonly Table[], existing?: ReadonlyMap<Entity, Entity>, update?: boolean): Promise<Table.Spawned> => {
     given.tables = tables;
     given.existing = existing;
+    given.update = update;
     try {
         await world.run(spawnGiven);
     }
     finally {
         given.existing = undefined;
+        given.update = undefined;
     }
     return spawnedBy.spawned;
 };
@@ -247,6 +249,37 @@ describe("tables", () => {
         expect((await readAll(other)).find(entry => entry.label === "owned")).toMatchObject({ parent: existingSteel, target: existingSteel });
     });
 
+    it("write a row existing maps onto its entity with update, as an add would, entity values rewritten as a spawned row's", async () => {
+        await using world = inline();
+        let steel = Entity.none;
+        await world.run(System.create(({ commands }) => {
+            const inside = commands.spawn([label])({ [label]: "inside" });
+            const outside = commands.spawn([pinned])();
+            steel = commands.spawn([label, position, buddy, target, link, team], { [team]: "red" })({ [label]: "steel", [position]: [1, 2, 3], [buddy]: inside, [target]: outside, [link]: { to: inside, weight: 4 } });
+        }));
+        const { archetypes } = await world.run(tablesOf([label, position, buddy, target, link, team]));
+        await using other = inline();
+        let mine = Entity.none, kept = Entity.none;
+        await other.run(System.create(({ commands }) => {
+            kept = commands.spawn([label])({ [label]: "kept" });
+            mine = commands.spawn([label, hidden, target, team], { [team]: "blue" })({ [label]: "mine", [target]: kept });
+        }));
+        const changed: string[] = [];
+        const watch = System.create({ components: { with: [label], changed: [label] } }, row => { changed.push(row[label]); });
+        await other.run(watch);
+        changed.length = 0;
+        const { entities, dropped } = await spawnTables(other, archetypes, new Map([[steel, mine]]), true);
+        expect([dropped, entities.flatMap(list => [...list]).includes(mine)]).toEqual([0, true]);
+        const read = await readAll(other);
+        const inside = read.find(entry => entry.label === "inside")?.entity;
+        // The weak reference to an entity outside the tables is left out, so the entity's own stands.
+        expect(read.find(entry => entry.entity === mine)).toMatchObject({ label: "steel", position: [1, 2, 3], buddy: inside, target: kept, link: { to: inside, weight: 4 } });
+        const teams = await other.run(System.create({ readonly: true, tables: { components: [team, hidden] } }, ({ tables }) => tables.archetypes.map(table => [table.columns[team], table.columns[hidden] !== undefined])));
+        expect(teams).toEqual([[{ kind: "value", value: "red" }, true]]);
+        await other.run(watch);
+        expect(changed.sort()).toEqual(["inside", "steel"]);
+    });
+
     it("refuse existing mapping to an entity that isn't alive, spawning nothing", async () => {
         await using world = inline();
         const gone = (await spawnLabels(world, ["gone"])).get("gone") ?? Entity.none;

package/src/implementation/world/tables.ts

@@ -1,5 +1,5 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
-import type { Layout, Path } from '../../interface/registry/layout.js';
+import { viewsOf, type Layout, type Path } from '../../interface/registry/layout.js';
 import { declarationOf, labelOf } from '../../interface/registry/names.js';
 import { isEntity } from '../../interface/registry/schemas.js';
 import type { Schema } from '../../interface/schema/schema.js';
@@ -8,7 +8,8 @@ import { batchOf } from './batches.js';
 import { indexOf, locate, reserveRun } from './entities.js';
 import { internShared } from './shared.js';
 import { claimRows, openRows, writerOf, type Column as BatchColumn } from './staging.js';
-import { commandIdOf, type Key, type State } from './state.js';
+import { commandIdOf, storedShared, type Key, type State } from './state.js';
+import { addCommand, pushCommand, pushComponent, type CommandBuffer } from './buffer.js';
 
 /** Whether a value of `schema` may hold an entity anywhere in it. */
 const holdsEntity = (schema: Schema): boolean => {
@@ -209,6 +210,45 @@ const spawnRows = (state: State, { table, keys, ids, shared }: Planned, rows: re
     claimRows(batch, entities);
 };
 
+/** A linear value read out of a table's bytes, copied to row 0 here first; grown for larger layouts. */
+let scratch = viewsOf(new ArrayBuffer(256), 0, 256);
+
+/** A table's value of a component in a row: its column's one value, its value there, or one read out of its bytes. */
+const valueIn = (layout: Layout, column: Table.Column, row: number): unknown => {
+    if (column.kind === "value") return column.value;
+    if (column.kind === "values") return column.values[row];
+    if (layout.kind !== "linear") return undefined;
+    const { stride } = layout;
+    if (stride > scratch.u8.length) scratch = viewsOf(new ArrayBuffer(stride * 2), 0, stride * 2);
+    scratch.u8.set(column.bytes.subarray(row * stride, (row + 1) * stride));
+    return layout.read(scratch, 0);
+};
+
+/**
+ * Queues an add of each of its table's components onto the entity standing for a row `existing` maps, its entity
+ * values remapped, but a reference whose target isn't there.
+ */
+const updateRows = (state: State, { table, keys, ids }: Planned, rows: readonly number[], standing: Float64Array, buffer: CommandBuffer, remap: Remap): void => {
+    const columns: Table.Column[] = keys.map(key => Reflect.get(table.columns, key));
+    const schemas = keys.map(key => declarationOf(key)?.type);
+    const references = keys.map(key => declarationOf(key)?.reference !== undefined);
+    for (const row of rows) {
+        pushCommand(buffer, addCommand, standing[row]);
+        for (let k = 0; k < keys.length; k++) {
+            const id = ids[k];
+            const schema = schemas[k];
+            let value = valueIn(state.layouts[id], columns[k], row);
+            if (references[k]) {
+                const to = remap(Number(value));
+                if (to === 0 && value !== 0) continue;
+                value = to;
+            }
+            else if (schema !== undefined && holdsEntity(schema)) value = remapValue(schema, value, remap);
+            pushComponent(buffer, id, state.shared[id] === undefined ? value : storedShared(state, id, value));
+        }
+    }
+};
+
 /** Throws for an entity `existing` maps to that isn't alive in this world. */
 const checkExisting = (state: State, existing: ReadonlyMap<number, number>): void => {
     for (const [source, target] of existing) {
@@ -223,7 +263,7 @@ const checkExisting = (state: State, existing: ReadonlyMap<number, number>): voi
  * value naming an entity spawned names the one spawned for it. A row whose entity `existing` maps isn't spawned: the
  * entity it maps to stands for it, as it does for an entity outside the tables that `existing` maps.
  */
-export const spawnTables = (state: State, tables: readonly Table[], existing: ReadonlyMap<number, number> = new Map()): Table.Spawned => {
+export const spawnTables = (state: State, tables: readonly Table[], existing: ReadonlyMap<number, number> = new Map(), updates: CommandBuffer | null = null): Table.Spawned => {
     const plans = tables.map(table => planOf(state, table));
     checkExisting(state, existing);
     // Entities are mapped only where a value of the tables may hold one, or a row is one that exists.
@@ -342,6 +382,11 @@ export const spawnTables = (state: State, tables: readonly Table[], existing: Re
             const target = targetAt(row);
             return target !== 0 && !isSpawned(target);
         });
+        if (updates !== null && !wholly[t]) {
+            const mapped: number[] = [];
+            for (let row = 0; row < table.count; row++) if (existingAt[first + row] !== 0) mapped.push(row);
+            if (mapped.length > 0) updateRows(state, plan, mapped, entities[t], updates, remap);
+        }
         let whole = wholly[t];
         if (weak.length > 0) for (let row = 0; row < table.count && whole; row++) if (loses(row)) whole = false;
         if (whole) return spawnRows(state, plan, null, none, entities[t], remap);

package/src/implementation/world/watch-traits-late.test-helper.ts

@@ -0,0 +1,14 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { System } from "../../interface/system/system.js";
+import { inDocument } from "./watch-traits.test-helper.js";
+
+/** A resource of the document's, registered once this module is imported. */
+export const margin = Symbol("watchTraits/margin");
+
+declare module "@adobe/ecs" {
+    export interface Resources {
+        [margin]: { type: number; [inDocument]: true };
+    }
+}
+
+export const widen = System.create(({ resources }) => { resources[margin] = 5; });

package/src/implementation/world/watch-traits.test-helper.ts

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/** A trait of the document's: what changes finalizers watching it see. */
+export const inDocument = Symbol("watchTraits/inDocument");
+
+declare module "@adobe/ecs" {
+    export interface Traits<N> {
+        readonly [inDocument]: N extends unknown ? true : never;
+    }
+}

package/src/implementation/world/watch-traits.test.ts

@@ -0,0 +1,62 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { expect, it } from "vitest";
+import { Finalizer } from "../../interface/finalizer/finalizer.js";
+import { System } from "../../interface/system/system.js";
+import { createWorld } from "../index.js";
+import { readResource } from "./reads.test-helper.js";
+import { inDocument } from "./watch-traits.test-helper.js";
+
+const title = Symbol("watchTraits/title");
+const cursor = Symbol("watchTraits/cursor");
+const zoom = Symbol("watchTraits/zoom");
+const theme = Symbol("watchTraits/theme");
+const saved = Symbol("watchTraits/saved");
+const recorded = Symbol("watchTraits/recorded");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [title]: { type: string; [inDocument]: true };
+        [cursor]: { type: number };
+    }
+    interface Resources {
+        [zoom]: { type: number; default: 1; [inDocument]: true };
+        [theme]: { type: string };
+        [saved]: { type: readonly string[]; default: [] };
+        [recorded]: { type: readonly string[]; default: [] };
+    }
+}
+
+/** What a change set holds, as lines: each group's components added and removed, and each resource written. */
+const linesOf = (changes: { readonly groups: readonly { readonly added: readonly symbol[]; readonly removed: readonly symbol[] }[]; readonly resources: readonly { readonly key: symbol; readonly previous: unknown; readonly next: unknown }[] }): string[] => [
+    ...changes.groups.map(group => [...group.added.map(key => `+${key.description}`), ...group.removed.map(key => `-${key.description}`)].join(" ")),
+    ...changes.resources.map(change => `${change.key.description} ${String(change.previous)} → ${String(change.next)}`),
+];
+
+Finalizer.changes({ watch: [inDocument] }, (changes, { resources }) => {
+    resources[saved] = [...resources[saved], ...linesOf(changes)];
+});
+Finalizer.changes({ watch: { components: true, resources: [theme] } }, (changes, { resources }) => {
+    resources[recorded] = [...resources[recorded], ...linesOf(changes)];
+});
+
+const spawn = System.create(({ commands }) => { commands.spawn([title, cursor])({ [title]: "notes", [cursor]: 0 }); });
+const edit = System.create(({ resources }) => {
+    resources[zoom] = 2;
+    resources[theme] = "dark";
+});
+
+it("watches each component and resource declaring a trait, and every component with the resources chosen", async () => {
+    await using world = createWorld();
+    await world.run(spawn);
+    await world.run(edit);
+    expect(await readResource(world, saved)).toEqual(["+watchTraits/title", "watchTraits/zoom 1 → 2"]);
+    expect(await readResource(world, recorded)).toEqual(["+watchTraits/title +watchTraits/cursor", "watchTraits/theme  → dark"]);
+});
+
+it("watches a resource declaring a trait it watches that registers after the world started", async () => {
+    await using world = createWorld();
+    await world.run(spawn);
+    const { widen } = await import("./watch-traits-late.test-helper.js");
+    await world.run(widen);
+    expect(await readResource(world, saved)).toEqual(["+watchTraits/title", "watchTraits/margin 0 → 5"]);
+});

package/src/interface/finalizer/body.ts

@@ -5,9 +5,11 @@ import type { Commands } from '../system/commands.js';
 import type { Listed, Property } from '../system/property.js';
 import type { LookupFunction } from '../system/values.js';
 import type { WriteResources } from '../system/body.js';
-import type { ChangesDeclaration, Declaration } from './declaration.js';
+import type { ChangesDeclaration, Declaration, OwnTrait } from './declaration.js';
 import type { Essential, ReadonlyType } from '../component/value.js';
 import type { Resource } from '../resource/resource.js';
+import type { Resources } from '../resource/types.js';
+import type { Components } from '../component/types.js';
 import type { ReadonlyType as ResourceType } from '../resource/value.js';
 import type { Elsewhere, ThreadsOf } from '../system/threads.js';
 
@@ -30,11 +32,28 @@ export type Context<D extends Declaration | ChangesDeclaration> =
     })
     & (true extends Elsewhere<ThreadsOf<D>> ? {} : { readonly commands: Commands });
 
+/** The components declaring any of the traits `T`. */
+type ComponentsDeclaring<T> = { [K in Component.Key]: [Extract<keyof Components[K], T>] extends [never] ? never : K }[Component.Key];
+
+/** The resources declaring any of the traits `T`. */
+type ResourcesDeclaring<T> = { [K in Resource.Key]: [Extract<keyof Resources[K], T>] extends [never] ? never : K }[Resource.Key];
+
+/** The components keys `L` name: each, and each declaring a trait among them. */
+type ComponentsOf<L> = Extract<L, Essential> | Extract<ComponentsDeclaring<Extract<L, OwnTrait>>, Essential>;
+
+/** The resources keys `L` name: each, and each declaring a trait among them. */
+type ResourcesOf<L> = Extract<L, Resource.Key> | ResourcesDeclaring<Extract<L, OwnTrait>>;
+
+/** The keys a changes finalizer's `watch` lists, by kind: those of its list, or of its object's lists. */
+export type WatchListed<D extends ChangesDeclaration, Of extends "components" | "resources"> = Property<D, "watch"> extends readonly (infer E)[] ? E
+    : Property<D, "watch"> extends { readonly [P in Of]: readonly (infer E)[] } ? E : never;
+
 /** The components a changes finalizer sees. */
-export type Watched<D extends ChangesDeclaration> = Property<D, "watch"> extends readonly unknown[] ? Listed<D, "watch"> & Essential : Essential;
+export type Watched<D extends ChangesDeclaration> = Property<D, "watch"> extends readonly unknown[] | { readonly components: readonly unknown[] }
+    ? ComponentsOf<WatchListed<D, "components">> : Essential;
 
 /** The resources a changes finalizer sees: those it watches. */
-export type WatchedResources<D extends ChangesDeclaration> = Listed<D, "watch"> & Resource.Key;
+export type WatchedResources<D extends ChangesDeclaration> = ResourcesOf<WatchListed<D, "resources">>;
 
 /** Entities whose components changed the same way: `from` and `to` are null for those spawned and despawned. */
 export type Group<C extends Component.Key> = {

package/src/interface/finalizer/create.test.ts

@@ -75,7 +75,10 @@ describe("Finalizer.create and Finalizer.changes", () => {
         expect(() => untyped(Finalizer.create, { components: {} }, { resources: { reduce: [total] } })).toThrow("only systems contribute to a reduction");
         expect(() => untyped(Finalizer.create, { components: { with: [node, tags] } }, { read: [node, tags] })).toThrow('uses "typesFinalizerTest/node" on "main" and "typesFinalizerTest/tags" on "world"');
         expect(() => untyped(Finalizer.changes, { name: "derived", watch: [slot] })).toThrow("which is derived");
-        expect(() => untyped(Finalizer.changes, { name: "unregistered", watch: [Symbol("typesFinalizerTest/unregistered")] })).toThrow("which isn't a registered component or resource");
+        expect(() => untyped(Finalizer.changes, { name: "unregistered", watch: [Symbol("typesFinalizerTest/unregistered")] })).toThrow("which isn't a registered component, resource or trait");
+        expect(() => untyped(Finalizer.changes, { watch: { components: [time], resources: [] } })).toThrow(`watches "typesFinalizerTest/time" among its components, which isn't a registered component or trait`);
+        expect(() => untyped(Finalizer.changes, { watch: { components: true, resources: [label] } })).toThrow(`watches "typesFinalizerTest/label" among its resources, which isn't a registered resource or trait`);
+        expect(() => untyped(Finalizer.changes, { watch: { components: [slot], resources: [] } })).toThrow("which is derived");
         expect(() => untyped(Finalizer.create, { components: { with: [time] } })).toThrow(`uses component "typesFinalizerTest/time", which isn't a registered component`);
         expect(() => untyped(Finalizer.create, { components: { with: [label] }, lookup: { others: { not: [Symbol("typesFinalizerTest/unregistered")] } } }, { read: [label] })).toThrow("which isn't a registered component");
         expect(programFinalizers()).toHaveLength(7);