@adobe/ecs 0.1.0 → 0.2.1

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, test } from "vitest";
 import type { Program } from "./kernel.js";
 import { generateWgsl } from "./wgsl.js";

package/src/implementation/world/wgsl.ts

@@ -1,6 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { laneCount } from './intrinsics.js';
 import type { Program } from './kernel.js';
-import type { WasmColumn, WasmScalar } from './wasm.js';
+import { scalarOfExpression, type WasmColumn, type WasmScalar } from './wasm.js';
 
 type Expression = Program.Expression;
 type Statement = Program.Statement;
@@ -165,7 +166,10 @@ fn roundHalfUp(x: f32) -> f32 { let down = floor(x); return select(down, down +
  * Generates a compute shader for a kernel program, or the reason it can't run on the GPU: lookups, loops, f64 or
  * entity columns, or byte stores.
  */
-export const generateWgsl = (program: Program, columns: readonly WasmColumn[], scalarTypes: (scalar: WasmScalar) => unknown, upColumns: readonly WasmColumn[] = []): WgslKernel | string => {
+/** How a scalar parameter is written into a dispatch's record, and read there: f32 bits, an integer's or a boolean's. */
+export type ScalarKind = "f32" | "i32" | "u32" | "bool" | "f64";
+
+export const generateWgsl = (program: Program, columns: readonly WasmColumn[], scalarTypes: (scalar: WasmScalar) => unknown, upColumns: readonly WasmColumn[] = [], scalarKinds: (scalar: WasmScalar) => ScalarKind = () => "f32"): WgslKernel | string => {
     /**
      * Reading `up`, a dispatch's record has, after the columns, the word addresses of its rows and their parents' rows,
      * whether they have a parent, and each parent column's address; the scalars follow.
@@ -241,6 +245,10 @@ export const generateWgsl = (program: Program, columns: readonly WasmColumn[], s
                 return column === undefined ? "f32" : column.boolean ? "bool" : column.view === "u32" ? "u32" : column.view === "i32" ? "i32" : "f32";
             }
             case "upFound": return "bool";
+            case "shared": {
+                const kind = scalarKinds(scalarOfExpression(expression));
+                return kind === "f64" ? "f32" : kind;
+            }
             case "local": return localKinds[expression.local];
             case "unary": return expression.operator === "!" ? "bool" : expression.operator === "~" ? "i32" : "f32";
             case "binary":
@@ -310,9 +318,18 @@ export const generateWgsl = (program: Program, columns: readonly WasmColumn[], s
             case "column": return read(expression.column);
             case "upLeaf": return readUp(expression.column);
             case "upFound": return bool(`(${upWord(2)} != 0u)`);
-            case "resource": case "args": {
-                const scalar: WasmScalar = expression.kind === "args" ? { source: "args", path: expression.path } : { source: "resource", index: expression.index, path: expression.path };
-                return f32(`bitcast<f32>(parameters[${1 + columns.length + upWords + scalarOf(scalar)}])`);
+            case "resource": case "args": case "shared": {
+                const scalar = scalarOfExpression(expression);
+                const word = `parameters[${1 + columns.length + upWords + scalarOf(scalar)}]`;
+                // A shared value's leaf keeps its type, as its column would: resources and the input are f32.
+                switch (scalarKinds(scalar)) {
+                    case "i32": return i32(`bitcast<i32>(${word})`);
+                    case "u32": return u32(word);
+                    case "bool": return bool(`${word} != 0u`);
+                    // As an f64 column read: the GPU has no f64, and rounding it would change what the body reads.
+                    case "f64": return fail("it reads an f64 value, such as an entity or a precision-2 number");
+                    default: return f32(`bitcast<f32>(${word})`);
+                }
             }
             case "local": return { code: localName(expression.local), type: localKinds[expression.local] };
             case "unary": {

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

@@ -0,0 +1,342 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Entity, System, workers } from "../../index.js";
+import type { F32, Vec2 } from "../../interface/math/index.js";
+import { createWorld, join, startTicksAt } from "./create.js";
+import { whereOf } from "./where.js";
+
+const team = Symbol("whereTest/team");
+const note = Symbol("whereTest/note");
+const cell = Symbol("whereTest/cell");
+const position = Symbol("whereTest/position");
+const seen = Symbol("whereTest/seen");
+const camera = Symbol("whereTest/camera");
+const other = Symbol("whereTest/other");
+declare module "@adobe/ecs" {
+    interface Components {
+        [team]: { type: "red" | "blue"; shared: true };
+        [cell]: { type: Vec2.I32; shared: true };
+        [position]: { type: F32 };
+        [seen]: { type: F32 };
+        [note]: { type: { readonly text: string } | null; thread: "whereTest" };
+    }
+    interface Threads {
+        whereTest: true;
+    }
+    interface Resources {
+        [camera]: { type: { readonly x: number; readonly radius: number }; default: { x: 0; radius: 1 } };
+        [other]: { type: number; default: 0 };
+    }
+}
+
+/** Whether a cell is within the camera's radius of its center, along x. */
+const visible = (at: Vec2.I32, x: number, radius: number): boolean => Math.abs(at[0] - x) <= radius;
+
+const spawn = System.create(({ commands }) => {
+    for (let x = -3; x <= 3; x++) {
+        for (let k = 0; k < 4; k++) commands.spawn([cell, team, position, seen], { [cell]: [x, 0], [team]: k % 2 === 0 ? "red" : "blue" })({ [position]: x * 10 + k, [seen]: 0 });
+    }
+});
+
+// By value: only the red archetypes.
+export const reds = System.create({ components: { with: [position, seen], where: { [team]: "red" } } }, row => { row[seen] += 1; });
+
+// By a predicate of the value and a resource.
+export const inView = System.create({ kernel: false, components: { with: [position, seen], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } } }, row => { row[seen] += 100; });
+// The same, as a kernel.
+export const inViewKernel = System.create({ kernel: true, components: { with: [position, seen], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } } }, row => { row[seen] += 100; });
+
+// With a change filter: each archetype counts as changed since this system last saw it.
+const caught: number[] = [];
+export const catchUp = System.create({ kernel: false, components: { with: [position], changed: [position], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } } }, row => { caught.push(row[position]); });
+
+export const look = System.create({}, ({ resources }, input: { readonly x: number; readonly radius: number }) => { resources[camera] = { x: input.x, radius: input.radius }; });
+export const touch = System.create(({ resources }) => { resources[other] += 1; });
+export const nudge = System.create({ components: { with: [position, cell] } }, row => { row[position] += 0.5; });
+
+// On a joined thread: a system placed there by writing its objects, and an observer system added there.
+export const spawnNoted = System.create(({ commands }) => {
+    for (let x = -3; x <= 3; x++) commands.spawn([cell, position, note], { [cell]: [x, 0] })({ [position]: x });
+});
+export const noteInView = System.create({ components: { with: [position, note], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } } }, row => {
+    row[note] = { text: `${row[position]}` };
+});
+const heard: number[] = [];
+export const hearInView = System.create({ observer: true, components: { with: [position], changed: [position], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } } }, row => { heard.push(row[position]); });
+// Filtered by a resource the predicate doesn't read: a culled archetype coming into view catches up on its change.
+const signalled: number[] = [];
+export const signalInView = System.create({ observer: true, components: { with: [position], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } }, resources: { changed: [other] } }, row => { signalled.push(row[position]); });
+// A system moving the camera its own predicate reads: its next run sees the new view.
+const followed: number[] = [];
+export const follow = System.create({ components: { with: [position], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } } }, (row, { resources }) => {
+    followed.push(row[position]);
+    resources[camera] = { x: 3, radius: 0 };
+});
+// Placed on the joined thread by writing its objects, with a change filter: what it saw changed, by position.
+const notedChanged: number[] = [];
+export const noteChanged = System.create({ components: { with: [position, note], changed: [position], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } } }, row => {
+    notedChanged.push(row[position]);
+    row[note] = { text: `${row[position]}` };
+});
+const notes: string[] = [];
+export const readNotes = System.create({ observer: true, components: { with: [note] } }, row => { if (row[note] !== null) notes.push(row[note].text); });
+export const nudgeNoted = System.create({ components: { with: [position, note] } }, row => { row[position] += 0.5; });
+
+/** Waits a turn at a time until `done`, for two seconds at most. */
+const until = async (done: () => boolean): Promise<void> => {
+    const end = performance.now() + 2000;
+    while (!done() && performance.now() < end) await new Promise(resolve => setTimeout(resolve, 1));
+};
+
+/** Every row's position and how often it was seen, by position. */
+const seenOf = async (world: ReturnType<typeof createWorld>): Promise<readonly string[]> => {
+    const read: [number, string][] = [];
+    await world.run(System.create({ observer: true, components: { with: [position, seen] } }, row => { read.push([row[position], `${row[position]}:${row[seen]}`]); }));
+    return read.sort((a, b) => a[0] - b[0]).map(([, text]) => text).filter(text => !text.endsWith(":0"));
+};
+
+describe("where", () => {
+    it("runs a system over the archetypes holding an equal shared value", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(spawn);
+        await world.run(reds);
+        expect(await seenOf(world)).toEqual([-30, -28, -20, -18, -10, -8, 0, 2, 10, 12, 20, 22, 30, 32].map(position => `${position}:1`));
+    });
+    for (const system of [inView, inViewKernel]) {
+        it(`runs ${system === inView ? "a body" : "a kernel"} over the archetypes a predicate passes, as resources it reads change`, async () => {
+            await using world = createWorld({ [workers]: 0 });
+            await world.run(spawn);
+            await world.run(system);
+            expect(await seenOf(world)).toEqual([-10, -9, -8, -7, 0, 1, 2, 3, 10, 11, 12, 13].map(position => `${position}:100`));
+            await world.run(look, { x: 3, radius: 0 });
+            await world.run(system);
+            expect((await seenOf(world)).filter(text => Number.parseFloat(text) >= 30)).toEqual(["30:100", "31:100", "32:100", "33:100"]);
+        });
+    }
+    it("evaluates a predicate once per archetype as it appears, and again for every one only when a resource it reads changed", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(spawn);
+        await world.run(inView);
+        const where = whereOf(inView);
+        expect(where?.evaluations).toBe(14);
+        const passing = where?.passing;
+        for (let k = 0; k < 5; k++) await world.run(inView);
+        await world.run(touch);
+        await world.run(inView);
+        expect(where?.evaluations).toBe(14);
+        // The run's list of archetypes is one buffer, reused.
+        expect(where?.passing).toBe(passing);
+        expect(where?.count).toBe(6);
+        await world.run(look, { x: 2, radius: 1 });
+        await world.run(inView);
+        expect(where?.evaluations).toBe(28);
+        expect(where?.passing).toBe(passing);
+        // A new archetype is evaluated as it appears.
+        await world.run(System.create(({ commands }) => { commands.spawn([cell, team, position, seen], { [cell]: [9, 0], [team]: "red" })({ [position]: 90, [seen]: 0 }); }));
+        await world.run(inView);
+        expect(where?.evaluations).toBe(29);
+    });
+    it("keeps each archetype's last run, so one a predicate skipped catches up on its changes when it passes again", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(spawn);
+        await world.run(catchUp);
+        caught.length = 0;
+        // Every row changes; only those in view are visited.
+        await world.run(nudge);
+        await world.run(catchUp);
+        expect(caught.sort((a, b) => a - b)).toEqual([-9.5, -8.5, -7.5, -6.5, 0.5, 1.5, 2.5, 3.5, 10.5, 11.5, 12.5, 13.5]);
+        caught.length = 0;
+        // Nothing changed since: nothing in view is visited, and cells coming into view catch up.
+        await world.run(look, { x: 2, radius: 1 });
+        await world.run(catchUp);
+        expect(caught.sort((a, b) => a - b)).toEqual([20.5, 21.5, 22.5, 23.5, 30.5, 31.5, 32.5, 33.5]);
+        caught.length = 0;
+        await world.run(catchUp);
+        expect(caught).toEqual([]);
+    });
+    it("counts a row moved from a skipped archetype into a passing one as changed since the system last saw it", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        let far = Entity.none;
+        await world.run(System.create(({ commands }) => {
+            far = commands.spawn([cell, position], { [cell]: [5, 0] })({ [position]: 50 });
+            commands.spawn([cell, position], { [cell]: [1, 0] })({ [position]: 1 });
+        }));
+        await world.run(catchUp);
+        // Both change; only the one in view is visited, and its archetype's point moves on.
+        await world.run(nudge);
+        caught.length = 0;
+        await world.run(catchUp);
+        expect(caught).toEqual([1.5]);
+        // The other moves into that archetype, holding a change its system never saw.
+        await world.run(System.create(({ commands }) => { commands.add(far, cell, [1, 0]); }));
+        caught.length = 0;
+        await world.run(catchUp);
+        expect(caught).toContain(50.5);
+    });
+    it("counts a moved row as changed by its old archetype's point before the run, whichever runs first", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        let far = Entity.none;
+        await world.run(System.create(({ commands }) => {
+            // Its archetype is the first, so a run reaches it before the one its row moves into.
+            far = commands.spawn([cell, position], { [cell]: [2, 0] })({ [position]: 20 });
+            commands.spawn([cell, position], { [cell]: [0, 0] })({ [position]: 0 });
+        }));
+        await world.run(look, { x: 1, radius: 1 });
+        await world.run(catchUp);
+        await world.run(look, { x: 0, radius: 1 });
+        await world.run(nudge);
+        caught.length = 0;
+        await world.run(catchUp);
+        expect(caught).toEqual([0.5]);
+        await world.run(System.create(({ commands }) => { commands.add(far, cell, [0, 0]); }));
+        await world.run(look, { x: 1, radius: 1 });
+        caught.length = 0;
+        await world.run(catchUp);
+        expect(caught).toContain(20.5);
+    });
+    it("counts a moved row as changed after its old archetype comes into view and its new one only later", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        let far = Entity.none;
+        await world.run(System.create(({ commands }) => {
+            far = commands.spawn([cell, position], { [cell]: [2, 0] })({ [position]: 20 });
+            commands.spawn([cell, position], { [cell]: [0, 0] })({ [position]: 0 });
+        }));
+        await world.run(catchUp);
+        await world.run(nudge);
+        caught.length = 0;
+        await world.run(catchUp);
+        expect(caught).toEqual([0.5]);
+        await world.run(System.create(({ commands }) => { commands.add(far, cell, [0, 0]); }));
+        // Its old archetype, empty now, is run over while its new one is out of view.
+        await world.run(look, { x: 2, radius: 0 });
+        await world.run(catchUp);
+        await world.run(look, { x: 0, radius: 1 });
+        caught.length = 0;
+        await world.run(catchUp);
+        expect(caught).toContain(20.5);
+    });
+    it("counts a row moved between archetypes it saw as unchanged, however long ago it saw another", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        let moving = Entity.none;
+        await world.run(System.create(({ commands }) => {
+            commands.spawn([cell, position], { [cell]: [5, 0] })({ [position]: 50 });
+            moving = commands.spawn([cell, position], { [cell]: [0, 0] })({ [position]: 0 });
+            commands.spawn([cell, position], { [cell]: [1, 0] })({ [position]: 10 });
+        }));
+        await world.run(catchUp);
+        await world.run(nudge);
+        caught.length = 0;
+        await world.run(catchUp);
+        expect(caught.sort((a, b) => a - b)).toEqual([0.5, 10.5]);
+        // Out of view from the start, its archetype's point is the oldest; the move is between two seen since.
+        await world.run(System.create(({ commands }) => { commands.add(moving, cell, [1, 0]); }));
+        caught.length = 0;
+        await world.run(catchUp);
+        expect(caught).toEqual([]);
+    });
+    it("runs on a joined thread for the systems placed there and the observer systems added there, catching up there too", async () => {
+        const channel = new MessageChannel();
+        await using world = createWorld({ [workers]: 0 });
+        heard.length = notes.length = 0;
+        const [joined] = await Promise.all([
+            join(channel.port2, { threads: ["whereTest"] }).then(thread => {
+                thread.add(hearInView);
+                return thread;
+            }),
+            world.share(channel.port1),
+        ]);
+        await using thread = joined;
+        await world.run(spawnNoted);
+        await world.run(noteInView);
+        await thread.run(readNotes);
+        expect(notes.sort()).toEqual(["-1", "0", "1"]);
+        await until(() => heard.length >= 3);
+        expect(heard.sort((a, b) => a - b)).toEqual([-1, 0, 1]);
+        heard.length = 0;
+        // Every row changes; the observer hears those in view, and those coming into view when they do.
+        await world.run(nudgeNoted);
+        await until(() => heard.length >= 3);
+        expect(heard.sort((a, b) => a - b)).toEqual([-0.5, 0.5, 1.5]);
+        heard.length = 0;
+        await world.run(look, { x: 3, radius: 1 });
+        // A pass while its last post still runs skips it; later passes post it, as ticks would.
+        const idle = System.create(() => {});
+        const end = performance.now() + 2000;
+        while (heard.length < 2 && performance.now() < end) await world.run(idle);
+        expect(heard.sort((a, b) => a - b)).toEqual([2.5, 3.5]);
+    });
+    // From a tick past 2^32 too, the moves crossing it.
+    for (const start of [0, 2 ** 32 - 8]) it(`counts a moved row as changed by its old archetype's point on a joined thread, from tick ${start}`, async () => {
+        const channel = new MessageChannel();
+        await using world = createWorld({ [workers]: 0 });
+        startTicksAt(world, start);
+        const [joined] = await Promise.all([join(channel.port2, { threads: ["whereTest"] }), world.share(channel.port1)]);
+        await using thread = joined;
+        let far = Entity.none;
+        let moving = Entity.none;
+        await world.run(System.create(({ commands }) => {
+            far = commands.spawn([cell, position, note], { [cell]: [2, 0] })({ [position]: 20 });
+            commands.spawn([cell, position, note], { [cell]: [0, 0] })({ [position]: 0 });
+            moving = commands.spawn([cell, position, note], { [cell]: [-1, 0] })({ [position]: -10 });
+            commands.spawn([cell, position, note], { [cell]: [1, 0] })({ [position]: 10 });
+            commands.spawn([cell, position, note], { [cell]: [9, 0] })({ [position]: 90 });
+        }));
+        await world.run(look, { x: 1, radius: 1 });
+        await world.run(noteChanged);
+        await world.run(look, { x: 0, radius: 1 });
+        await world.run(nudgeNoted);
+        notedChanged.length = 0;
+        await world.run(noteChanged);
+        expect(notedChanged.sort((a, b) => a - b)).toEqual([-9.5, 0.5, 10.5]);
+        // One moves in from an archetype out of view since the change, one between archetypes in view.
+        await world.run(System.create(({ commands }) => {
+            commands.add(far, cell, [0, 0]);
+            commands.add(moving, cell, [1, 0]);
+        }));
+        await world.run(look, { x: 1, radius: 1 });
+        notedChanged.length = 0;
+        await world.run(noteChanged);
+        expect(notedChanged).toContain(20.5);
+        expect(notedChanged).not.toContain(-9.5);
+        expect(notedChanged).not.toContain(10.5);
+        void thread;
+    });
+    it("catches up a culled archetype on a resource filter's change on a joined thread", async () => {
+        const channel = new MessageChannel();
+        await using world = createWorld({ [workers]: 0 });
+        signalled.length = 0;
+        const [joined] = await Promise.all([
+            join(channel.port2, { threads: ["whereTest"] }).then(thread => {
+                thread.add(signalInView);
+                return thread;
+            }),
+            world.share(channel.port1),
+        ]);
+        await using thread = joined;
+        const idle = System.create(() => {});
+        /** Runs until what the observer system signalled settles. */
+        const settled = async (count: number): Promise<number[]> => {
+            const end = performance.now() + 2000;
+            while (signalled.length < count && performance.now() < end) await world.run(idle);
+            return signalled.splice(0).sort((a, b) => a - b);
+        };
+        await world.run(spawnNoted);
+        expect(await settled(3)).toEqual([-1, 0, 1]);
+        await world.run(touch);
+        expect(await settled(3)).toEqual([-1, 0, 1]);
+        await world.run(look, { x: 3, radius: 1 });
+        expect(await settled(2)).toEqual([2, 3]);
+        void thread;
+    });
+    it("evaluates a predicate again after its own system wrote what it reads", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(spawnNoted);
+        followed.length = 0;
+        await world.run(follow);
+        expect(followed.sort((a, b) => a - b)).toEqual([-1, 0, 1]);
+        followed.length = 0;
+        await world.run(follow);
+        expect(followed).toEqual([3]);
+    });
+});
+

package/src/implementation/world/where.ts

@@ -0,0 +1,236 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Leaf } from '../../interface/system/leaf.js';
+import { declarationOf, labelOf } from '../../interface/registry/index.js';
+import { indexOf } from './entities.js';
+import { readCell } from './cells.js';
+import type { RowStorage } from './rows.js';
+import { resourceCell } from './resources.js';
+import { createSharedValues, holdShared, internShared, textOf } from './shared.js';
+import { idOf, type State } from './state.js';
+
+// A system's `where`: which of its matched archetypes its runs go over, by their shared values. A value passes the
+// archetypes holding an equal one, by number; a predicate those it returns true for, evaluated as written, here, once per
+// archetype as it appears and again for every one whenever a resource it reads changed since it last was.
+
+/** What an archetype `where` looks at: its values of shared components, by component id. */
+type Valued = { readonly shared: readonly (number | undefined)[]; readonly storageById: readonly ({ readonly layout: { readonly kind: string; readonly value?: unknown } } | undefined)[] };
+
+/** One shared component's condition: a value's number, or a predicate. */
+type Condition = { readonly id: number; readonly number: number; readonly predicate: ((value: unknown, context: object) => unknown) | null };
+
+/**
+ * The archetypes a run goes over, of those matched: the first `count` of `passing`, each with its position among the
+ * matches in `indices`, kept in buffers that only grow, so a run allocates nothing.
+ */
+export type Where<A> = {
+    readonly passing: A[];
+    readonly indices: number[];
+    count: number;
+    /** How many times a predicate's archetype was evaluated, for tests. */
+    evaluations: number;
+    /** Evaluates what it must of `matches`, and lists those that pass. */
+    readonly refresh: (matches: readonly A[]) => void;
+    /** How many of the matches, from the first, it evaluated: those after are evaluated by the next refresh. */
+    evaluated: number;
+    /**
+     * As matches move, removed or reused for other values (`reclaim.ts`): match `from`'s result now `to`'s; matches `a`
+     * and `b` swapped; and the last evaluated left to the next refresh to evaluate.
+     */
+    readonly move: (from: number, to: number) => void;
+    readonly swapped: (a: number, b: number) => void;
+    readonly forgetLast: () => void;
+};
+
+/** What tests read of a `where`. */
+type Observed = { readonly passing: readonly unknown[]; readonly count: number; readonly evaluations: number; readonly evaluated: number };
+
+/** For tests: by system, its `where` in the last world that registered it. */
+const wheres = new WeakMap<object, Observed>();
+
+/** For tests: a system's `where` in the last world that registered it, or undefined without one. */
+export const whereOf = (system: object): Observed | undefined => wheres.get(system);
+
+/**
+ * The core of a `where` over matches of type `M`: `passes` evaluates one, counting what a predicate evaluated, and
+ * `readsChanged(since)` tells whether a resource a predicate reads changed after tick `since`; `now` is the tick an
+ * evaluation is as of. `predicated` without predicates, so only new matches are ever evaluated.
+ */
+const whereOver = <M>(predicated: boolean, passes: (match: M) => boolean, readsChanged: (since: number) => boolean, now: () => number, bind: () => void): Where<M> => {
+    /** The tick it last evaluated every match at: a resource changed after it evaluates them again. */
+    let evaluatedAt = -1;
+    /** By match, whether it passes. */
+    const results: boolean[] = [];
+    /** Whether matches moved since it last listed those that pass. */
+    let moved = false;
+    const result: Where<M> = {
+        passing: [],
+        indices: [],
+        count: 0,
+        evaluations: 0,
+        evaluated: 0,
+        move: (from, to) => {
+            results[to] = results[from];
+            moved = true;
+        },
+        swapped: (a, b) => {
+            const kept = results[a];
+            results[a] = results[b];
+            results[b] = kept;
+            moved = true;
+        },
+        forgetLast: () => {
+            result.evaluated--;
+            moved = true;
+        },
+        refresh: matches => {
+            const { evaluated } = result;
+            const again = predicated && evaluated > 0 && readsChanged(evaluatedAt);
+            if (!again && evaluated === matches.length && !moved) return;
+            if (predicated) bind();
+            let changed = moved;
+            moved = false;
+            for (let m = again ? 0 : evaluated; m < matches.length; m++) {
+                const passed = passes(matches[m]);
+                if (m >= evaluated || results[m] !== passed) changed = true;
+                results[m] = passed;
+            }
+            result.evaluated = matches.length;
+            evaluatedAt = now();
+            if (!changed) return;
+            let count = 0;
+            for (let m = 0; m < matches.length; m++) {
+                if (!results[m]) continue;
+                result.passing[count] = matches[m];
+                result.indices[count] = m;
+                count++;
+            }
+            result.count = count;
+        },
+    };
+    return result;
+};
+
+/** A predicate as the world calls it, with what its declaration gave. */
+const predicateOf = (given: unknown): ((value: unknown, context: object) => unknown) | null =>
+    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.
+ */
+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 id = idOf(state, key);
+        const given: unknown = Reflect.get(where, key);
+        const predicate = predicateOf(given);
+        if (predicate !== null) return { id, number: -1, predicate };
+        const values = state.shared[id];
+        if (values === undefined) throw new Error(`System "${leaf.name}": where names "${labelOf(key)}", which isn't a shared component.`);
+        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 };
+    });
+    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);
+    const values: object = Object.create({});
+    reads.forEach((key, k) => Object.defineProperty(values, key, { get: () => cached[k], enumerable: true }));
+    const context = { value: { resources: values }, bind: (): void => {
+        for (let k = 0; k < reads.length; k++) {
+            const { storage, row } = resourceCell(state, reads[k]);
+            cached[k] = readCell(storage, row);
+        }
+    } };
+    const passes = (archetype: A): boolean => {
+        for (let c = 0; c < conditions.length; c++) {
+            const { id, number, predicate } = conditions[c];
+            if (predicate === null) {
+                if (archetype.shared[id] !== number) return false;
+                continue;
+            }
+            const layout = archetype.storageById[id]?.layout;
+            if (layout === undefined || layout.kind !== "constant") return false;
+            found.evaluations++;
+            if (predicate(layout.value, context.value) !== true) return false;
+        }
+        return true;
+    };
+    const readsChanged = (since: number): boolean => {
+        if (readIds.length === 0 || state.resourceEntity < 0) return false;
+        const index = indexOf(state.resourceEntity);
+        const archetype = state.archetypes[state.entities.archetype[index]];
+        const row = state.entities.row[index];
+        for (let k = 0; k < readIds.length; k++) {
+            const storage = archetype?.storageById[readIds[k]];
+            if (storage !== undefined && storage.changed[row] > since) return true;
+        }
+        return false;
+    };
+    // Evaluated as of before its run's own tick, so what its own body writes after counts as changed.
+    const found = whereOver(conditions.some(condition => condition.predicate !== null), passes, readsChanged, () => state.tick - 1, context.bind);
+    wheres.set(leaf, found);
+    return found;
+};
+
+/** What a joined thread's `where` reads of its world: archetypes' views by id, its numbers for keys and its resource row. */
+type ThreadWhereHost<A> = {
+    readonly archetypeAt: (id: number) => A | undefined;
+    readonly numberOf: (key: symbol) => number;
+    readonly resourceRow: () => { readonly archetype: { readonly storageById: readonly (RowStorage | undefined)[] }; readonly row: number } | null;
+    readonly tick: () => number;
+};
+
+/**
+ * A system's `where` on a joined thread, over its matches by archetype id: a value compared by its canonical text with
+ * each archetype's, which the layout directory gives it, and its predicates run here, reading this thread's view of the
+ * resources.
+ */
+export const createThreadWhere = <A extends { readonly storageById: readonly (RowStorage | undefined)[] }>(host: ThreadWhereHost<A>, where: { readonly [key: symbol]: unknown }, reads: readonly symbol[]): Where<number> => {
+    const conditions = Object.getOwnPropertySymbols(where).map(key => {
+        const given: unknown = Reflect.get(where, key);
+        const predicate = predicateOf(given);
+        const values = createSharedValues(declarationOf(key)?.type);
+        const number = predicate === null ? internShared(values, given) : -1;
+        return { number: host.numberOf(key), text: number < 0 ? null : values.texts[number] ?? null, predicate };
+    });
+    const readNumbers = reads.map(host.numberOf);
+    const values: object = Object.create({});
+    reads.forEach((key, k) => {
+        Object.defineProperty(values, key, {
+            get: () => {
+                const found = host.resourceRow();
+                const storage = found?.archetype.storageById[readNumbers[k]];
+                return storage === undefined || found === null ? undefined : readCell(storage, found.row);
+            },
+            enumerable: true,
+        });
+    });
+    const context: object = { resources: values };
+    const passes = (id: number): boolean => {
+        const archetype = host.archetypeAt(id);
+        if (archetype === undefined) return false;
+        for (const { number, text, predicate } of conditions) {
+            const layout = archetype.storageById[number]?.layout;
+            if (layout === undefined || layout.kind !== "constant") return false;
+            if (predicate === null) {
+                if (text === null || textOf(layout.value) !== text) return false;
+                continue;
+            }
+            found.evaluations++;
+            if (predicate(layout.value, context) !== true) return false;
+        }
+        return true;
+    };
+    const readsChanged = (since: number): boolean => {
+        const row = readNumbers.length === 0 ? null : host.resourceRow();
+        if (row === null) return false;
+        for (const number of readNumbers) {
+            const storage = row.archetype.storageById[number];
+            if (storage !== undefined && storage.changed[row.row] > since) return true;
+        }
+        return false;
+    };
+    const found = whereOver(conditions.some(condition => condition.predicate !== null), passes, readsChanged, host.tick, () => {});
+    return found;
+};

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /// <reference types="node" />
 import type { MessagePort as NodeMessagePort, Worker as NodeWorker } from 'node:worker_threads';
 import type { FromWorker, ToWorker } from './protocol.js';