@adobe/ecs 0.2.3 → 0.2.4

package/src/implementation/world/thread-systems.ts

@@ -280,6 +280,7 @@ export const createThreadSystems = (host: ThreadSystemsHost) => {
         },
         despawn: entity => beginCommand(writer, despawnCommand, entity),
         spawnTables: () => { throw new Error("commands.spawnTables runs on the world's thread: run the system there."); },
+        despawnWhere: () => { throw new Error("commands.despawnWhere runs on the world's thread: run the system there."); },
         add: (entity: number, components: symbol | readonly symbol[], values?: unknown) => {
             if (typeof components === "symbol") {
                 const key = givenKeyOf(components);
@@ -990,18 +991,19 @@ export const createThreadRunner = (host: RunnerHost, leaf: Leaf, records: Readon
         const row = bindRow(archetype);
         const subject = row.value;
         const input = runInput;
+        const { body } = system;
         const filters = filtersOf(archetype);
         if (since < 0 || filters.length === 0) {
             for (let index = 0; index < count; index++) {
                 row.index = index;
-                system.body(subject, value, input);
+                body(subject, value, input);
             }
             return;
         }
         forEachPassingRange(filters, since, 0, count, (start, end) => {
             for (let index = start; index < end; index++) {
                 row.index = index;
-                system.body(subject, value, input);
+                body(subject, value, input);
             }
         });
     };
@@ -1103,18 +1105,19 @@ export const createThreadRunner = (host: RunnerHost, leaf: Leaf, records: Readon
         const row = bindRow(archetype);
         const subject = row.value;
         const input = runInput;
+        const { body } = system;
         const filters = filtersOf(archetype);
         if (since < 0 || filters.length === 0) {
             for (let index = start; index < end && !halted; index++) {
                 row.index = index;
-                system.body(subject, tailValue, input);
+                body(subject, tailValue, input);
             }
             return;
         }
         forEachPassingRange(filters, since, start, end, (first, last) => {
             for (let index = first; index < last && !halted; index++) {
                 row.index = index;
-                system.body(subject, tailValue, input);
+                body(subject, tailValue, input);
             }
         });
     };
@@ -1233,6 +1236,7 @@ export const createThreadRunner = (host: RunnerHost, leaf: Leaf, records: Readon
         const copied = (storages: readonly (ThreadStorage | undefined)[]): ThreadArchetype =>
             ({ id: -1, entities, storageById: storages, record: -1, version: -1, mirrored: null, components: [], resource: false, reclaimed: false, generation: 0 });
         const ownedInput = runInput;
+        const { body } = system;
         try {
             if (optionalNumbers.length === 0 && sharedReads.length === 0) {
                 const row = bindRow(copied(storageById));
@@ -1240,7 +1244,7 @@ export const createThreadRunner = (host: RunnerHost, leaf: Leaf, records: Readon
                 for (let index = first; index < rows && !halted; index++) {
                     if (skipped !== null && skipped.has(archetypeIds[index])) continue;
                     row.index = index;
-                    system.body(subject, tailValue, ownedInput);
+                    body(subject, tailValue, ownedInput);
                 }
             }
             else {
@@ -1275,7 +1279,7 @@ export const createThreadRunner = (host: RunnerHost, leaf: Leaf, records: Readon
                     const subject = row.value;
                     for (; index < end && !halted; index++) {
                         row.index = index;
-                        system.body(subject, tailValue, ownedInput);
+                        body(subject, tailValue, ownedInput);
                     }
                 }
             }

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

@@ -190,7 +190,7 @@ describe("up", () => {
         expect(await read(ecs, entities.grandchild, world)).toBe(100);
     });
 
-    it("runs every row after a spawn outruns the journal, with change filters, then only the rows that changed", async () => {
+    it("runs every row after spawning more than a patch takes, with change filters, then only the rows that changed", async () => {
         await using ecs = createWorld({ [workers]: 0 });
         await ecs.run(spawn);
         await ecs.run(nest);
@@ -211,6 +211,18 @@ describe("up", () => {
         expect(ran).toEqual([]);
     });
 
+    it("runs only the rows spawned in bulk, which the journal holds once each, with change filters", async () => {
+        await using ecs = createWorld({ [workers]: 0 });
+        await ecs.run(spawn);
+        await ecs.run(nest);
+        await ecs.run(propagateChanged);
+        await ecs.run(bulkUnder, { count: 3000 });
+        ran.length = 0;
+        await ecs.run(propagateChanged);
+        expect(ran.length).toBe(3000);
+        expect(await readEach(ecs, bulk.slice(0, 3), world)).toEqual([112, 112, 112]);
+    });
+
     it("finds a cycle a reparent closes after the tree was built, and runs its rows again once it opens", async () => {
         await using ecs = createWorld({ [workers]: 0 });
         await ecs.run(spawn);

package/src/implementation/world/up.ts

@@ -22,6 +22,9 @@ const cyclic = -1;
 const denseShare = 1 / 8;
 /** Rows below this many are sorted rather than scanned. */
 const denseMinimum = 4096;
+/** Past this many journal entries, and past this share of the matched rows, the tree is built again rather than patched. */
+const patchMinimum = 4096;
+const patchShare = 1 / 8;
 /** Sort keys pack a row with its parent's archetype: `(parent + 1) * rowLimit + row`. */
 const rowLimit = 2 ** 27;
 
@@ -375,7 +378,9 @@ const createShared = (state: State, through: number, read: readonly number[], ma
         const { journal } = state;
         const end = journalEnd(journal);
         if (position === end) return;
-        if (position < journal.first) {
+        let matched = 0;
+        for (let k = 0; k < matches.length; k++) matched += matches[k].count;
+        if (position < journal.first || end - position > Math.max(patchMinimum, matched * patchShare)) {
             build(matches);
             position = end;
             rebuiltAll();

package/src/implementation/world/where.ts

@@ -115,22 +115,50 @@ const predicateOf = (given: unknown): ((value: unknown, context: object) => unkn
     typeof given === "function" ? (value, context) => Reflect.apply(given, undefined, [value, context]) : null;
 
 /**
- * A system's `where` in a world: its values interned there, by number, its predicates' context reading `reads`,
- * evaluated again once one of them changed since they last were.
+ * `where`'s conditions in a world, each value interned there, by number, and with `pinned`, pinned, so its number stays
+ * while no archetype holds it and one that comes to hold it again matches; or the key of a component that isn't shared.
+ * A value interned unpinned keeps its number to the end of the sync point.
  */
-export const createWhere = <A extends Valued>(state: State, where: { readonly [key: symbol]: unknown }, reads: readonly symbol[], leaf: Leaf): Where<A> => {
-    const conditions: Condition[] = Object.getOwnPropertySymbols(where).map(key => {
+const conditionsOf = (state: State, where: { readonly [key: symbol]: unknown }, pinned: boolean): Condition[] | symbol => {
+    const conditions: Condition[] = [];
+    for (const key of Object.getOwnPropertySymbols(where)) {
         const id = idOf(state, key);
         const given: unknown = Reflect.get(where, key);
         const predicate = predicateOf(given);
-        if (predicate !== null) return { id, number: -1, predicate };
+        if (predicate !== null) {
+            conditions.push({ id, number: -1, predicate });
+            continue;
+        }
         const values = state.shared[id];
-        if (values === undefined) throw new Error(`System "${leaf.name}": where names "${labelOf(key)}", which isn't a shared component.`);
+        if (values === undefined) return key;
         const number = internShared(values, given);
-        // Pinned, so its number stays while no archetype holds it: one that comes to hold it again matches.
-        if (number >= 0) holdShared(values, number);
-        return { id, number, predicate: null };
-    });
+        if (pinned && number >= 0) holdShared(values, number);
+        conditions.push({ id, number, predicate: null });
+    }
+    return conditions;
+};
+
+/**
+ * Whether an archetype holds each of `where`'s values, as a system's `where` of values passes it, for a `where` naming
+ * only shared components and giving no predicate; or the key of one that isn't shared. Its values are pinned with
+ * `pinned`, and otherwise only interned, for a `where` used before the sync point ends.
+ */
+export const holdsValuesOf = (state: State, where: { readonly [key: symbol]: unknown }, pinned: boolean): ((archetype: Valued) => boolean) | symbol => {
+    const conditions = conditionsOf(state, where, pinned);
+    if (typeof conditions === "symbol") return conditions;
+    return archetype => {
+        for (let c = 0; c < conditions.length; c++) if (archetype.shared[conditions[c].id] !== conditions[c].number) return false;
+        return true;
+    };
+};
+
+/**
+ * A system's `where` in a world: its values interned there, by number, its predicates' context reading `reads`,
+ * evaluated again once one of them changed since they last were.
+ */
+export const createWhere = <A extends Valued>(state: State, where: { readonly [key: symbol]: unknown }, reads: readonly symbol[], leaf: Leaf): Where<A> => {
+    const conditions = conditionsOf(state, where, true);
+    if (typeof conditions === "symbol") throw new Error(`System "${leaf.name}": where names "${labelOf(conditions)}", which isn't a shared component.`);
     const readIds = reads.map(key => idOf(state, key));
     // Its predicates' context: each resource read once per evaluation, since a struct's read copies it out.
     const cached: unknown[] = reads.map(() => undefined);

package/src/interface/finalizer/body.ts

@@ -7,6 +7,8 @@ import type { LookupFunction } from '../system/values.js';
 import type { WriteResources } from '../system/body.js';
 import type { ChangesDeclaration, Declaration } from './declaration.js';
 import type { Essential, ReadonlyType } from '../component/value.js';
+import type { Resource } from '../resource/resource.js';
+import type { ReadonlyType as ResourceType } from '../resource/value.js';
 import type { Elsewhere, ThreadsOf } from '../system/threads.js';
 
 /**
@@ -29,7 +31,10 @@ export type Context<D extends Declaration | ChangesDeclaration> =
     & (true extends Elsewhere<ThreadsOf<D>> ? {} : { readonly commands: Commands });
 
 /** The components a changes finalizer sees. */
-export type Watched<D extends ChangesDeclaration> = Property<D, "watch"> extends readonly Essential[] ? Listed<D, "watch"> & Essential : Essential;
+export type Watched<D extends ChangesDeclaration> = Property<D, "watch"> extends readonly unknown[] ? Listed<D, "watch"> & Essential : Essential;
+
+/** The resources a changes finalizer sees: those it watches. */
+export type WatchedResources<D extends ChangesDeclaration> = Listed<D, "watch"> & Resource.Key;
 
 /** Entities whose components changed the same way: `from` and `to` are null for those spawned and despawned. */
 export type Group<C extends Component.Key> = {
@@ -42,9 +47,14 @@ export type Group<C extends Component.Key> = {
     readonly entities: readonly Entity[];
 };
 
-/** A sync point's structural changes to the watched components, and the values adds replace, before they apply. */
-export type ChangeSet<C extends Component.Key> = {
+/**
+ * A sync point's structural changes to the watched components, and the values adds replace, before they apply; and each
+ * watched resource written since the last sync point's finalizers ran, to a value that isn't equal to its last one,
+ * leaf by leaf for data and by identity for objects, with its value before and after.
+ */
+export type ChangeSet<C extends Component.Key, R extends Resource.Key = never> = {
     readonly groups: readonly Group<C>[];
+    readonly resources: readonly { readonly [K in R]: { readonly key: K; readonly previous: ResourceType<K>; readonly next: ResourceType<K> } }[R][];
     /** The value before the sync point, or null if the entity didn't have it. */
     previous<K extends C>(entity: Entity, component: K): ReadonlyType<K> | null;
     /** The value after it, or null if the entity won't have it. */

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

@@ -75,7 +75,7 @@ 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: "resource", watch: [time] })).toThrow("which isn't a registered component");
+        expect(() => untyped(Finalizer.changes, { name: "unregistered", watch: [Symbol("typesFinalizerTest/unregistered")] })).toThrow("which isn't a registered component or resource");
         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);
@@ -93,6 +93,8 @@ describe("Finalizer.create and Finalizer.changes", () => {
             .toThrow('uses "typesFinalizerTest/tags" on "world" and "typesFinalizerTest/page" on "main"');
         expect(() => untyped(Finalizer.changes, {}, { resources: { read: [page] } }))
             .toThrow(`watches or reads values on thread "main"; a changes finalizer runs on the world's thread, in the sync point.`);
+        expect(() => untyped(Finalizer.changes, { name: "savePage", watch: [page] }))
+            .toThrow(`watches or reads values on thread "main"; a changes finalizer runs on the world's thread, in the sync point.`);
         // Reading another thread's values, without writing or looking up, it's created.
         const detach = Finalizer.create({ components: { with: [node] } }, row => { void row[node]; });
         expect(programFinalizers()).toHaveLength(8);

package/src/interface/finalizer/create.ts

@@ -8,9 +8,11 @@ import { checkWorldWritten } from '../registry/written.js';
 import { checkLookup } from '../registry/indexes.js';
 import type { Listed, Property } from '../system/property.js';
 import type { ThreadOfComponent } from '../component/value.js';
+import type { ThreadOfResource } from '../resource/value.js';
+import type { Resource } from '../resource/resource.js';
 import type { Component } from '../component/component.js';
 import type { Elsewhere, OneThread, ThreadedBy, ThreadsOf } from '../system/threads.js';
-import type { ChangeSet, Context, Row, Watched } from './body.js';
+import type { ChangeSet, Context, Row, Watched, WatchedResources } from './body.js';
 import type { Changes, Leaf } from './created.js';
 import type { ChangesDeclaration, Declaration, Resolved, ResolvedChanges } from './declaration.js';
 import { accessOf, compact, lookupsLists, resourceUses, type Access } from '../system/resolve.js';
@@ -26,7 +28,7 @@ type Remote<D> = true extends Elsewhere<ThreadsOf<D>>
     : {};
 
 /** A changes finalizer runs on the world's thread, in the sync point: it watches and reads no other thread's objects. */
-type OnWorld<D> = true extends Elsewhere<ThreadsOf<D> | ThreadOfComponent<Listed<D, "watch"> & Component.Key>>
+type OnWorld<D> = true extends Elsewhere<ThreadsOf<D> | ThreadOfComponent<Listed<D, "watch"> & Component.Key> | ThreadOfResource<Listed<D, "watch"> & Resource.Key>>
     ? { readonly "error: a changes finalizer watches and reads only the world's thread's objects": true }
     : {};
 
@@ -127,12 +129,12 @@ export const create = <const D extends Declaration>(
 
 /**
  * Declares a finalizer of each sync point's structural changes, which applies in every world, and returns it. It runs
- * on the world's thread. Throws as `create` does, for a watched component that isn't registered or is derived, and for
- * one watching or reading another thread's values.
+ * on the world's thread. Throws as `create` does, for a watched component that isn't registered or is derived, a
+ * watched key that's neither a component nor a resource, and for one watching or reading another thread's values.
  */
 export const changes = <const D extends ChangesDeclaration>(
     declared: D & Inferred & OnWorld<D>,
-    body: (changes: ChangeSet<Watched<D>>, context: Context<D>) => void,
+    body: (changes: ChangeSet<Watched<D>, WatchedResources<D>>, context: Context<D>) => void,
 ): Finalizer => {
     const id = takeIdOfDeclaration(declared);
     const name = nameOf(declared, id, "finalizer");
@@ -148,10 +150,13 @@ export const changes = <const D extends ChangesDeclaration>(
         for (const keys of [lookup.read, "has" in lookup ? lookup.has : undefined, "not" in lookup ? lookup.not : undefined]) requireRegistered("Finalizer", name, "component", keys);
     }
     for (const key of declaration.watch ?? []) {
-        if (kindOf(key) !== "component") throw new Error(`Finalizer "${name}" watches "${labelOf(key)}", which isn't a registered component: ${whyUnregistered(key)}.`);
+        const kind = kindOf(key);
+        if (kind !== "component" && kind !== "resource") throw new Error(`Finalizer "${name}" watches "${labelOf(key)}", which isn't a registered component or resource: ${whyUnregistered(key)}.`);
         if (declarationOf(key)?.derived === true) throw new Error(`Finalizer "${name}" watches "${labelOf(key)}", which is derived; it sees only components user code adds and removes.`);
     }
-    const thread = threadOf({ components: { read: declaration.watch }, resources: declaration.resources, lookup: declaration.lookup }, "Finalizer", name);
+    const watched = (kind: "component" | "resource"): readonly symbol[] => (declaration.watch ?? []).filter(key => kindOf(key) === kind);
+    const read = [...declaration.resources?.read ?? [], ...watched("resource")];
+    const thread = threadOf({ components: { read: watched("component") }, resources: { ...declaration.resources, read }, lookup: declaration.lookup }, "Finalizer", name);
     if (thread !== null && thread !== "world") throw new Error(`Finalizer "${name}" watches or reads values on thread "${thread}"; a changes finalizer runs on the world's thread, in the sync point.`);
     checkOrder(name, "world", declaration);
     return addFinalizer(finalizer, id);

package/src/interface/finalizer/declaration.ts

@@ -4,6 +4,7 @@ import type { SystemLookupLists, ResourceLists } from '../system/access.js';
 import type { Lookup } from '../system/access.js';
 import type { Finalizer } from './finalizer.js';
 import type { Essential } from '../component/value.js';
+import type { Resource } from '../resource/resource.js';
 
 /**
  * What every finalizer declares. What its body reads of its row and lookups, and reads and writes of resources, the
@@ -26,9 +27,10 @@ export type Declaration = Shared & {
 
 /**
  * A finalizer that sees each sync point's structural changes to the components it watches: by default, every one that
- * isn't derived or an object a joined thread fills.
+ * isn't derived or an object a joined thread fills; and the resources it watches, none by default, written since the
+ * last sync point's finalizers ran.
  */
-export type ChangesDeclaration = Shared & { readonly watch?: readonly Essential[] };
+export type ChangesDeclaration = Shared & { readonly watch?: readonly (Essential | Resource.Key)[] };
 
 type Key = symbol;
 

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

@@ -144,3 +144,13 @@ describe("systems ordering their rows by an index", () => {
         expect(() => untypedRender(Index.create({ key: [amount] }))).toThrow(/orders its rows by index "index #\d+", which isn't sorted/);
     });
 });
+
+describe("Index.declarationOf", () => {
+    it("gives an index's declaration as registered, its with and not as declared, and nothing for a value Index.create didn't return", () => {
+        const byName = Index.create({ key: [name], unique: true, components: { with: [shown], not: [parent] } });
+        expect(Index.declarationOf(byName)).toEqual({ key: [name], components: { with: [shown], not: [parent] }, unique: true });
+        const byCell = Index.create({ key: [cell, amount], sorted: true });
+        expect(Index.declarationOf(byCell)).toEqual({ key: [cell, amount], components: {}, sorted: true });
+        expect(Index.declarationOf({ name: "not an index" })).toBeUndefined();
+    });
+});

package/src/interface/indexes/declaration-of.ts

@@ -0,0 +1,34 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../component/component.js';
+import { indexDefinitionOf } from '../registry/indexes.js';
+import { kindOf } from '../registry/names.js';
+import type { Index } from './index-type.js';
+
+/**
+ * An index's declaration as `Index.create` registered it: its key, the components it holds by besides its key and those
+ * it excludes, and whether it's sorted or unique.
+ */
+export type Declared = {
+    readonly key: readonly Component.Key[];
+    readonly components: { readonly with?: readonly Component.Key[]; readonly not?: readonly Component.Key[] };
+    readonly sorted?: boolean;
+    readonly unique?: boolean;
+};
+
+/** Registration takes only components for a key part, `with` and `not`. */
+const isComponent = (key: symbol): key is Component.Key => kindOf(key) === "component";
+
+/** The declaration `index` was created from, as registered, or undefined for a value `Index.create` didn't return. */
+export const declarationOf = <D extends object>(index: Index<D>): Declared | undefined => {
+    const created = indexDefinitionOf(index);
+    if (created === undefined) return undefined;
+    const { key, components, sorted, unique } = created.declaration;
+    const held = components?.has?.filter(isComponent);
+    const excluded = components?.not?.filter(isComponent);
+    return {
+        key: key.filter(isComponent),
+        components: { ...held === undefined ? {} : { with: held }, ...excluded === undefined ? {} : { not: excluded } },
+        ...sorted === undefined ? {} : { sorted },
+        ...unique === undefined ? {} : { unique },
+    };
+};

package/src/interface/indexes/index.ts

@@ -1,2 +1,3 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 export * from './create.js';
+export { declarationOf, type Declared } from './declaration-of.js';