@adobe/ecs 0.2.3 → 0.3.0

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/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/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

@@ -5,8 +5,12 @@ 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';
 
 /**
@@ -28,8 +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 Essential[] ? 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> = 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> = {
@@ -42,9 +66,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,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: "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, 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);
@@ -93,6 +96,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

@@ -6,11 +6,13 @@ import { addFinalizer, programFinalizers } from '../registry/program.js';
 import { requireRegistered, threadOf } from '../registry/threads.js';
 import { checkWorldWritten } from '../registry/written.js';
 import { checkLookup } from '../registry/indexes.js';
-import type { Listed, Property } from '../system/property.js';
+import type { 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, WatchListed } 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 extends ChangesDeclaration> = true extends Elsewhere<ThreadsOf<D> | ThreadOfComponent<Extract<WatchListed<D, "components">, Component.Key>> | ThreadOfResource<Extract<WatchListed<D, "resources">, Resource.Key>>>
     ? { readonly "error: a changes finalizer watches and reads only the world's thread's objects": true }
     : {};
 
@@ -125,19 +127,52 @@ export const create = <const D extends Declaration>(
     return addFinalizer(finalizer, id);
 };
 
+const isList = (watch: NonNullable<ChangesDeclaration["watch"]>): watch is Extract<ChangesDeclaration["watch"], readonly unknown[]> => Array.isArray(watch);
+
+/** What a changes finalizer watches, sorted by kind. Throws for a key that's neither of the kinds it's listed as, or derived. */
+const watchOf = (name: string, watch: ChangesDeclaration["watch"]): ResolvedChanges["watch"] => {
+    const components: symbol[] = [];
+    const componentTraits: symbol[] = [];
+    const resources: symbol[] = [];
+    const resourceTraits: symbol[] = [];
+    const sort = (key: unknown, kinds: readonly ("component" | "resource")[]): void => {
+        const kind = kindOf(key);
+        if (typeof key !== "symbol" || kind === undefined || (kind !== "trait" && !kinds.includes(kind))) {
+            const among = kinds.length === 2 ? "" : ` among its ${kinds[0]}s`;
+            throw new Error(`Finalizer "${name}" watches "${labelOf(key)}"${among}, which isn't a registered ${kinds.length === 2 ? "component, resource" : kinds[0]} or trait: ${whyUnregistered(key)}.`);
+        }
+        if (kind === "trait") {
+            if (kinds.includes("component")) componentTraits.push(key);
+            if (kinds.includes("resource")) resourceTraits.push(key);
+            return;
+        }
+        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.`);
+        (kind === "component" ? components : resources).push(key);
+    };
+    if (watch === undefined) return { components: true, componentTraits, resources, resourceTraits };
+    if (isList(watch)) {
+        for (const key of watch) sort(key, ["component", "resource"]);
+        return { components, componentTraits, resources, resourceTraits };
+    }
+    const every = watch.components === true;
+    if (!every) for (const key of watch.components) sort(key, ["component"]);
+    for (const key of watch.resources) sort(key, ["resource"]);
+    return { components: every ? true : components, componentTraits: every ? [] : componentTraits, resources, resourceTraits };
+};
+
 /**
  * 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");
     const what = `Finalizer "${name}"`;
-    const declaration: ResolvedChanges = { ...resolveShared(what, declared, accessOf(what, declared)), ...declared.watch === undefined ? {} : { watch: declared.watch } };
+    const declaration: ResolvedChanges = { ...resolveShared(what, declared, accessOf(what, declared)), watch: watchOf(name, declared.watch) };
     const finalizer: Changes = { kind: "changes", name, declaration, body };
     checkResources(name, declaration.resources);
     requireRegistered("Finalizer", name, "resource", declaration.resources?.read);
@@ -147,11 +182,9 @@ export const changes = <const D extends ChangesDeclaration>(
         checkLookup("Finalizer", name, lookupName, lookup);
         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)}.`);
-        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 { watch } = declaration;
+    const read = [...declaration.resources?.read ?? [], ...watch.resources];
+    const thread = threadOf({ components: { read: watch.components === true ? [] : watch.components }, 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,9 @@ 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';
+import type { Traits } from '../trait/types.js';
+import type { BuiltIn } from '../trait/key.js';
 
 /**
  * What every finalizer declares. What its body reads of its row and lookups, and reads and writes of resources, the
@@ -24,11 +27,23 @@ export type Declaration = Shared & {
     readonly components: { readonly with?: readonly Component.Key[]; readonly optional?: readonly Component.Key[]; readonly not?: readonly Component.Key[] };
 };
 
+/** A trait of your own, which watches every component and resource declaring it. */
+export type OwnTrait = Exclude<keyof Traits<never>, BuiltIn>;
+
 /**
- * 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.
+ * A finalizer that sees each sync point's structural changes to the components it watches, and the resources it
+ * watches written since the last sync point's finalizers ran. By default it watches every component that isn't derived
+ * or an object a joined thread fills, and no resource. `watch` lists components, resources and traits of your own, or,
+ * as an object, every component (`components: true`) or those listed, beside the resources listed. A trait watches each
+ * component and resource declaring it, as each registers, but those the default leaves out and resources on another
+ * thread.
  */
-export type ChangesDeclaration = Shared & { readonly watch?: readonly Essential[] };
+export type ChangesDeclaration = Shared & {
+    readonly watch?: readonly (Essential | Resource.Key | OwnTrait)[] | {
+        readonly components: true | readonly (Essential | OwnTrait)[];
+        readonly resources: readonly (Resource.Key | OwnTrait)[];
+    };
+};
 
 type Key = symbol;
 
@@ -45,4 +60,16 @@ export type Resolved = ResolvedShared & {
     readonly components: { readonly read?: readonly Key[]; readonly has?: readonly Key[]; readonly optional?: readonly Key[]; readonly not?: readonly Key[] };
 };
 
-export type ResolvedChanges = ResolvedShared & { readonly watch?: readonly Key[] };
+/**
+ * A changes finalizer's declaration as the world takes it. It watches the components listed, or every one (`true`),
+ * and those declaring a trait of `componentTraits`; the resources listed, and those declaring a trait of
+ * `resourceTraits`.
+ */
+export type ResolvedChanges = ResolvedShared & {
+    readonly watch: {
+        readonly components: true | readonly Key[];
+        readonly componentTraits: readonly Key[];
+        readonly resources: readonly Key[];
+        readonly resourceTraits: readonly Key[];
+    };
+};

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';

package/src/interface/registry/index.ts

@@ -3,7 +3,7 @@
 export type { AnyDeclaration } from './declarations.js';
 export { schemaOf, threadOfDeclaration } from './declarations.js';
 export type { Kind } from './names.js';
-export { declarationOf, firstKeyOf, keyOfId, kindOf, labelOf, newestKeyOf, whyUnregistered } from './names.js';
+export { declarationOf, declaresTrait, declaredOf, firstKeyOf, keyOfId, keysVersion, kindOf, labelOf, newestKeyOf, whyUnregistered } from './names.js';
 export type { Item } from './program.js';
 export { definitionOf, programFinalizers, programRules, programVersion, requireDefinition } from './program.js';
 export type { Schedule } from './schedule.js';

package/src/interface/registry/names.ts

@@ -22,6 +22,9 @@ type Entry = {
 /** Every component, resource and user trait, by symbol identity: symbols of one id share an entry. */
 const entries = new Map<symbol, Entry>();
 
+/** How many keys were registered, counting a symbol registered under another's id. */
+let registered = 0;
+
 /** Entries by the ids the plugin gave their keys. */
 const identified = new Map<string, Entry>();
 
@@ -155,12 +158,28 @@ export const claimKey = (key: unknown, kind: Kind, declaration?: AnyDeclaration)
         }
         named.newest = symbol;
         entries.set(symbol, named);
+        registered++;
         return;
     }
     const description = descriptionOf(symbol);
     const entry: Entry = { kind, declaration, description, id, first: symbol, newest: symbol };
     if (id !== undefined) identified.set(id, entry);
     entries.set(symbol, entry);
+    registered++;
+};
+
+/** How many keys are registered so far, so a world can tell when one registered since it last looked. */
+export const keysVersion = (): number => {
+    catchUp();
+    return registered;
+};
+
+/** Whether a component's or resource's declaration declares one of `traits`, keys of traits of your own. */
+export const declaresTrait = (key: unknown, traits: readonly symbol[]): boolean => {
+    const declaration = declarationOf(key);
+    if (declaration === undefined) return false;
+    for (const declared of Object.getOwnPropertySymbols(declaration)) for (const trait of traits) if (sameKey(declared, trait)) return true;
+    return false;
 };
 
 /** The symbol last registered under an id, by which a world gives values, or undefined where none was. */