@adobe/ecs 0.1.0 → 0.2.0

package/src/implementation/world/lists.ts

@@ -1,15 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Entity } from '../../interface/entity/entity.js';
-import { archetypeIndexOf, labelOf } from '../../interface/registry/index.js';
+import { archetypeIndexKey, internArchetype, labelOf, type Interned } from '../../interface/registry/index.js';
 import { batchOf } from './batches.js';
 import { reserve } from './entities.js';
-import { claim, generated, openRow, writerOf, type Column, type Positional, type SpawnBatch, type Writer } from './staging.js';
+import { claim, encodedIn, generated, noValues, openRow, writerOf, type Column, type Positional, type SpawnBatch, type Writer } from './staging.js';
+import { cacheShared, exactTextOf, internShared, type SharedValues } from './shared.js';
 import { commandIdOf, type State } from './state.js';
 
 /** Values by key, as spawns and adds read them. */
 export type Values = { readonly [key: symbol]: unknown };
 
 /** Spawns one entity of a list's components, writing its values into the list's batch. */
-export type Spawner = (values: Values) => Entity;
+export type Spawner = (values?: Values) => Entity;
 
 /** Where a shape's spawns go: its batch, and the components holding values, each with its key, column and writer. */
 export type Written = {
@@ -32,12 +34,23 @@ export type ListShape = {
     readonly keys: readonly symbol[];
     readonly ids: readonly number[];
     readonly starts: readonly unknown[];
+    /** The positions of its shared components, whose values a spawner of it takes first. */
+    readonly shared: readonly number[];
     written: Written | null;
     spawner: Spawner | null;
+    /** Its spawners with constants, by their values (`presetSpawnerOf`). */
+    presets: PresetNode | null;
 };
 
-/** A plain list named recently, found by its keys, copied, since it may change. */
-export type Recent = { readonly keys: readonly unknown[]; readonly shape: ListShape };
+/**
+ * A level of a shape's spawners with constants: by the constant of the next component in the shape's order, the next
+ * level, the last one holding the spawner. A shared value is keyed by its number, a primitive by itself, other data
+ * by its text, and anything else by identity.
+ */
+type PresetNode = { readonly next: Map<unknown, PresetNode>; spawner: Spawner | null; letGo: (() => void) | null };
+
+/** A plain list named recently, found by its keys, copied once for its shape, since it may change. */
+export type Recent = { keys: readonly unknown[]; shape: ListShape };
 
 const recentCount = 8;
 
@@ -53,24 +66,34 @@ const resolve = (state: State, list: readonly unknown[]): ListShape => {
     const shapes = state.lists.get(name) ?? [];
     const found = shapes.find(shape => keys.every(key => shape.keys.includes(key)));
     if (found !== undefined) return found;
-    const shape: ListShape = { index: state.shapes.length, adding: [], removing: [], keys, ids, starts: ids.map(id => state.starts[id]), written: null, spawner: null };
+    const shared = ids.flatMap((id, k) => state.shared[id] === undefined ? [] : [k]);
+    const shape: ListShape = { index: state.shapes.length, adding: [], removing: [], keys, ids, starts: ids.map(id => state.starts[id]), shared, written: null, spawner: null, presets: null };
     state.lists.set(name, [...shapes, shape]);
     state.shapes.push(shape);
     return shape;
 };
 
 /**
- * The shape of a list of components: an archetype `Archetype.create` indexed, which never changes, by its index; any
- * other list by its keys among the recent plain lists, else resolved and made recent. Lists of the same components in
- * any order share a shape.
+ * The index a list has: the program-wide one the plugin gave it, which never changes; for one made at runtime, the
+ * one it keeps while its keys are those it was resolved with; else -1. Both are read from one property, so a list of
+ * either kind is one lookup.
+ */
+export const listIndexOf = (list: readonly unknown[]): number => {
+    const index: unknown = Reflect.get(list, archetypeIndexKey);
+    return typeof index === "number" ? index : isKept(index) && sameKeys(index.keys, list) ? index.index : -1;
+};
+
+/**
+ * The shape of a list of components, by its index (`listIndexOf`); for a list made at runtime without one, by its keys
+ * among the recent ones, else resolved, given an index it keeps and made recent. Lists of the same components in any
+ * order share a shape.
  */
 export const listShapeOf = (state: State, list: readonly unknown[]): ListShape => {
-    const index = archetypeIndexOf(list);
-    // Kept small, so it inlines into the systems spawning and adding: the rest is outlined.
+    const index = listIndexOf(list);
     return (index >= 0 ? state.byIndex[index] : undefined) ?? shapeOfList(state, list, index);
 };
 
-/** A list's shape, other than an archetype's already resolved. */
+/** A list's shape, other than one already resolved by its index. */
 const shapeOfList = (state: State, list: readonly unknown[], index: number): ListShape => {
     if (index >= 0) {
         const shape = resolve(state, list);
@@ -78,36 +101,65 @@ const shapeOfList = (state: State, list: readonly unknown[], index: number): Lis
         return shape;
     }
     const { recent } = state;
-    const length = list.length;
-    for (let r = 0; r < recent.length; r++) {
-        const { keys } = recent[r];
-        if (keys.length !== length) continue;
-        let same = true;
-        for (let k = 0; k < length && same; k++) same = keys[k] === list[k];
-        if (same) return recent[r].shape;
+    for (let r = 0; r < recent.length; r++) if (sameKeys(recent[r].keys, list)) return recent[r].shape;
+    // Lists of these keys made on every call share one index, so a shape seen before allocates nothing here.
+    const interned = internArchetype(list);
+    const shape = state.byIndex[interned.index] ?? (state.byIndex[interned.index] = resolve(state, list));
+    if (recent.length < recentCount) recent.push({ keys: interned.keys, shape });
+    else {
+        const slot = recent[state.nextRecent = (state.nextRecent + 1) % recentCount];
+        slot.keys = interned.keys;
+        slot.shape = shape;
+    }
+    // A list keeps the record of its keys' index, so naming it again is one lookup while it holds them.
+    const kept: unknown = Reflect.get(list, archetypeIndexKey);
+    if (kept === undefined && Object.isExtensible(list)) {
+        record.value = interned;
+        Object.defineProperty(list, archetypeIndexKey, record);
     }
-    const shape = resolve(state, list);
-    const entry: Recent = { keys: [...list], shape };
-    if (recent.length < recentCount) recent.push(entry);
-    else recent[state.nextRecent = (state.nextRecent + 1) % recentCount] = entry;
+    else if (isKept(kept)) Reflect.set(list, archetypeIndexKey, interned);
     return shape;
 };
 
+/** The descriptor a list's record is defined by, its value set for each: writable, since the list may change. */
+const record: PropertyDescriptor = { value: null, writable: true };
+
+/** Whether an index property holds a list's record: only this module puts an object there, and indexes are numbers. */
+const isKept = (value: unknown): value is Interned => typeof value === "object" && value !== null;
+
+/** Whether a list holds exactly the keys copied from one before. */
+const sameKeys = (keys: readonly unknown[], list: readonly unknown[]): boolean => {
+    const length = list.length;
+    if (keys.length !== length) return false;
+    for (let k = 0; k < length; k++) if (keys[k] !== list[k]) return false;
+    return true;
+};
+
 /** Where a shape's spawns go, resolved once. A constant's column holds nothing, so nothing is written or read for it. */
 export const writtenOf = (state: State, shape: ListShape): Written => {
     if (shape.written !== null) return shape.written;
-    const batch = batchOf(state, shape.ids);
+    shape.written = writtenInto(state, shape, batchOf(state, shape.ids));
+    return shape.written;
+};
+
+/** Where a shape's spawns into `batch` go: its columns holding values, each with its key and writer. */
+const writtenInto = (state: State, shape: ListShape, batch: SpawnBatch): Written => {
     const held = shape.ids.flatMap((id, k) => state.layouts[id].kind === "constant" ? [] : [k]);
     const columns = held.map(k => batch.columns[batch.ids.indexOf(shape.ids[k])]);
-    shape.written = { batch, keys: held.map(k => shape.keys[k]), columns, writers: held.map((k, c) => writerOf(columns[c], shape.starts[k])) };
-    return shape.written;
+    return { batch, keys: held.map(k => shape.keys[k]), columns, writers: held.map((k, c) => writerOf(columns[c], shape.starts[k])) };
+};
+
+/** Throws for a spawner without constants of a shape with shared components, whose values choose the archetype. */
+const refuseShared = (shape: ListShape): void => {
+    const first = shape.shared[0];
+    if (first !== undefined) throw new Error(`A spawn of "${labelOf(shape.keys[first])}", a shared component, takes its value first: commands.spawn(components, { [key]: value }).`);
 };
 
 /** Spawns by reading each value by key in a loop: where code can't be generated. */
 const loopSpawner = (state: State, { batch, keys, writers }: Written): Spawner => {
     const { entities } = state;
     const count = keys.length;
-    return values => {
+    return (values = noValues) => {
         const row = openRow(batch);
         for (let k = 0; k < count; k++) writers[k](row, values[keys[k]]);
         const entity = reserve(entities);
@@ -123,6 +175,7 @@ export type { Positional };
  * writers. A key the shape doesn't name is ignored.
  */
 export const positionalOf = (state: State, shape: ListShape, order: readonly unknown[]): Positional => {
+    refuseShared(shape);
     const { batch, keys, columns, writers } = writtenOf(state, shape);
     const at = keys.map(key => order.indexOf(key));
     const made = generated<Positional>(state.entities, reserve, batch, order.map((_, k) => `v${k}`), keys, columns, writers, k => at[k] < 0 ? "undefined" : `v${at[k]}`);
@@ -145,8 +198,106 @@ export const spawnerOf = (state: State, shape: ListShape): Spawner => shape.spaw
 
 /** Makes a shape's spawner, the first time it spawns. */
 const makeSpawner = (state: State, shape: ListShape): Spawner => {
+    refuseShared(shape);
     const written = writtenOf(state, shape);
     const { batch, keys, columns, writers } = written;
-    shape.spawner = generated<Spawner>(state.entities, reserve, batch, ["values"], keys, columns, writers, k => `values[k${k}]`) ?? loopSpawner(state, written);
+    shape.spawner = generated<Spawner>(state.entities, reserve, batch, ["values = none"], keys, columns, writers, k => `values[k${k}]`) ?? loopSpawner(state, written);
     return shape.spawner;
 };
+
+/** For tests of what a world holds: the levels of a shape's spawners with constants. */
+export const presetLevelsOf = (shape: ListShape): number => {
+    const count = (node: PresetNode): number => {
+        let levels = 0;
+        for (const child of node.next.values()) levels += 1 + count(child);
+        return levels;
+    };
+    return shape.presets === null ? 0 : count(shape.presets);
+};
+
+/** What keys a component given no constant at its level of a shape's spawners. */
+const absent = Symbol("absent");
+/** What keys a constant of -0, which a map's keys don't tell from 0. */
+const negativeZero = Symbol("negativeZero");
+
+/**
+ * The spawner of a shape with constants `preset`: the same function for a world, list and equal constants each time,
+ * found by each constant in turn, a level of the shape's spawners each (`PresetNode`). Its batch is the one of the
+ * shape's components and shared values, so its archetype, found by them, is resolved when the spawner is made, and
+ * made with the first sync point that commits a spawn of it. Every shared component is given a value of its type here,
+ * or the spawner throws. Other constants are encoded once and copied into each spawn; its call reads only the rest.
+ */
+export const presetSpawnerOf = (state: State, shape: ListShape, preset: object): Spawner => {
+    let node = shape.presets ??= { next: new Map(), spawner: null, letGo: null };
+    const { keys, ids } = shape;
+    for (let k = 0; k < keys.length; k++) {
+        const given: unknown = Reflect.get(preset, keys[k]);
+        const values = state.shared[ids[k]];
+        let part: unknown;
+        if (values !== undefined) {
+            if (given === undefined) throw new Error(`A spawn of "${labelOf(keys[k])}", a shared component, takes its value first: commands.spawn(components, { [key]: value }).`);
+            part = internShared(values, given);
+            if (part === -1) throw new Error(`"${labelOf(keys[k])}" isn't given one of its type's values: ${labelOf(given)}.`);
+        }
+        else part = given === undefined ? absent : Object.is(given, -0) ? negativeZero : typeof given === "object" && given !== null ? exactTextOf(given) ?? given : given;
+        let next = node.next.get(part);
+        if (next === undefined) {
+            next = { next: new Map(), spawner: null, letGo: null };
+            node.next.set(part, next);
+            if (values !== undefined && typeof part === "number") letGoWith(values, part, node, next);
+        }
+        node = next;
+    }
+    return node.spawner ??= makePresetSpawner(state, shape, preset);
+};
+
+/** Throws for a spawn giving a component its constants gave. */
+const refuseGiven = (key: unknown): never => {
+    throw new Error(`A spawn gives "${labelOf(key)}" in both its calls: each component's value comes from one.`);
+};
+
+/**
+ * Lets go of a level of a shape's spawners found by shared value `number`, under `parent`, once that value is dropped,
+ * so levels don't pile up as values come and go: the levels below it let go of what they registered too.
+ */
+const letGoWith = (values: SharedValues, number: number, parent: PresetNode, node: PresetNode): void => {
+    node.letGo = cacheShared(values, number, () => {
+        if (parent.next.get(number) === node) parent.next.delete(number);
+        unregisterBelow(node);
+    });
+};
+
+/** Unregisters every level below `node` from the values that would drop it, as `node` is dropped itself. */
+const unregisterBelow = (node: PresetNode): void => {
+    for (const child of node.next.values()) {
+        child.letGo?.();
+        unregisterBelow(child);
+    }
+};
+
+/** Makes the spawner of a shape with constants, the first time those constants are given. */
+const makePresetSpawner = (state: State, shape: ListShape, preset: object): Spawner => {
+    const shared: (number | undefined)[] = [];
+    for (const k of shape.shared) {
+        const values = state.shared[shape.ids[k]];
+        if (values !== undefined) shared[shape.ids[k]] = internShared(values, Reflect.get(preset, shape.keys[k]));
+    }
+    const written = writtenInto(state, shape, batchOf(state, shape.ids, shared));
+    const { batch, keys, columns, writers } = written;
+    const constants = keys.map(key => Reflect.get(preset, key));
+    const encoded = columns.map((column, c) => constants[c] === undefined ? null : encodedIn(column, constants[c]));
+    // Every key the constants give, shared ones included, which a spawn's values mustn't give again.
+    const given = shape.keys.filter(key => Reflect.get(preset, key) !== undefined);
+    const guarded = { keys: given, refuse: refuseGiven };
+    const made = generated<Spawner>(state.entities, reserve, batch, ["values = none"], keys.map((key, c) => constants[c] === undefined ? key : constants[c]), columns, writers, k => constants[k] === undefined ? `values[k${k}]` : `k${k}`, encoded, guarded);
+    if (made !== null) return made;
+    const { entities } = state;
+    return (values = noValues) => {
+        for (const key of given) if (values[key] !== undefined) refuseGiven(key);
+        const row = openRow(batch);
+        for (let k = 0; k < keys.length; k++) writers[k](row, constants[k] === undefined ? values[keys[k]] : constants[k]);
+        const entity = reserve(entities);
+        claim(batch, entity);
+        return entity;
+    };
+};

package/src/implementation/world/lookup-keys.ts

@@ -1,24 +1,25 @@
-import type { SystemLookup } from '../../interface/system/access.js';
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { SystemLookupLists } from '../../interface/system/access.js';
 import { indexDefinitionOf, indexOfLookup, watchedBy } from '../../interface/registry/index.js';
-import type { Component } from '../../interface/component/component.js';
+type Key = symbol;
 
 /** Every component a lookup names: what it reads, matches on and watches, and for an index lookup the index's own. */
-export const lookupComponentsOf = (lookup: SystemLookup): readonly Component.Key[] => {
+export const lookupComponentsOf = (lookup: SystemLookupLists): readonly Key[] => {
     const index = indexOfLookup(lookup);
     if (index === undefined) return [...lookup.read ?? [], ..."has" in lookup ? lookup.has ?? [] : [], ..."not" in lookup ? lookup.not ?? [] : []];
     const { key, components } = index.declaration;
     return [...lookup.read ?? [], ...watchedBy(lookup), ...key, ...components?.has ?? [], ...components?.not ?? []];
 };
 
-const none: readonly Component.Key[] = [];
+const none: readonly Key[] = [];
 
 /**
  * The components whose changes the indexes of a declaration's lookups follow, which keep ticks and kernels' stamps
  * while it lives: each index's key parts, and what its lookups watch.
  */
-export const indexWatchesOf = (lookup: { readonly [name: string]: SystemLookup } | undefined): readonly Component.Key[] => {
+export const indexWatchesOf = (lookup: { readonly [name: string]: SystemLookupLists } | undefined): readonly Key[] => {
     if (lookup === undefined) return none;
-    const keys: Component.Key[] = [];
+    const keys: Key[] = [];
     for (const name in lookup) {
         const declared = lookup[name];
         const index = indexOfLookup(declared);
@@ -29,9 +30,9 @@ export const indexWatchesOf = (lookup: { readonly [name: string]: SystemLookup }
 };
 
 /** The components a declaration's lookups by entity watch: their `changed`, which keep ticks and kernels' stamps while it lives. */
-export const entityWatchesOf = (lookup: { readonly [name: string]: SystemLookup } | undefined): readonly Component.Key[] => {
+export const entityWatchesOf = (lookup: { readonly [name: string]: SystemLookupLists } | undefined): readonly Key[] => {
     if (lookup === undefined) return none;
-    const keys: Component.Key[] = [];
+    const keys: Key[] = [];
     for (const name in lookup) {
         const declared = lookup[name];
         if (indexOfLookup(declared) === undefined) keys.push(...watchedBy(declared));
@@ -40,7 +41,7 @@ export const entityWatchesOf = (lookup: { readonly [name: string]: SystemLookup
 };
 
 /** Every component the index a declaration orders its rows by names: its key parts, `has` and `not`. */
-export const orderComponentsOf = (declaration: { readonly order?: unknown }): readonly Component.Key[] => {
+export const orderComponentsOf = (declaration: { readonly order?: unknown }): readonly Key[] => {
     const index = indexDefinitionOf(declaration.order);
     if (index === undefined) return none;
     const { key, components } = index.declaration;

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

@@ -1,5 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
-import { Component, System } from "../../index.js";
+import { System } from "../../index.js";
 import { requireDefinition, type Composite } from "../../interface/registry/index.js";
 import type { Cadence } from "../../interface/resources/cadence.js";
 import { backToBack, createLoop, type Clock, type LoopSettings } from "./loop.js";
@@ -14,12 +15,11 @@ declare module "@adobe/ecs" {
         [count]: { type: number };
     }
 }
-Component.register(count, { type: { type: "number" } });
 
-const increment = requireDefinition(System.create({ name: "loopTest/increment", components: { write: [count] } }, row => { row[count] += 1; }));
-const reader = requireDefinition(System.create({ name: "loopTest/reader", components: { read: [count] } }, row => { void row[count]; }));
-const ordered = requireDefinition(System.create({ name: "loopTest/ordered", components: { read: [count] }, after: [System.create({ name: "loopTest/phase" }, () => {})] }, row => { void row[count]; }));
-const takesInput = requireDefinition(System.create({ name: "loopTest/input", input: { type: "object", properties: { by: { type: "number" } } } }, () => {}));
+const increment = requireDefinition(System.create({ components: { with: [count] } }, row => { row[count] += 1; }));
+const reader = requireDefinition(System.create({ components: { with: [count] } }, row => { void row[count]; }));
+const ordered = requireDefinition(System.create({ components: { with: [count] }, after: [System.create({}, () => {})] }, row => { void row[count]; }));
+const takesInput = requireDefinition(System.create({}, (_context, input: { readonly by: number }) => {}));
 
 /** A host whose frames and timers run only when the test says, at the times it gives. */
 const createHost = (settings: { cadence: Cadence; always: boolean; wake: number }) => {
@@ -112,6 +112,17 @@ describe("the loop", () => {
         expect(ticks).toHaveLength(1);
     });
 
+    it("under a fixed cadence ticks once when a wake time comes, without waiting for a frame, and not again for the same wake", async () => {
+        const { host, ticks, advance } = createHost({ cadence: { kind: "fixed", step: 10 }, always: false, wake: 50 });
+        createLoop(host).add(increment);
+        await advance(40, false);
+        expect(ticks).toEqual([]);
+        await advance(20, false);
+        expect(ticks).toEqual([{ now: 60, delta: 10, tick: 0 }]);
+        await advance(100, false);
+        expect(ticks).toHaveLength(1);
+    });
+
     it("under a fixed cadence ticks by step, at most maxSteps per beat, and builds no debt while quiet", async () => {
         const settings = { cadence: { kind: "fixed", step: 10, maxSteps: 2 } as Cadence, always: true, wake: Infinity };
         const { host, ticks, advance } = createHost(settings);
@@ -143,7 +154,7 @@ describe("the loop", () => {
         const { host } = createHost({ cadence: { kind: "frame" }, always: false, wake: Infinity });
         const loop = createLoop(host);
         loop.add(increment);
-        expect(() => loop.add(reader)).toThrow('Systems "loopTest/increment" and "loopTest/reader" both access "loopTest/count" and one writes it');
+        expect(() => loop.add(reader)).toThrow('Systems "increment" and "reader" both access "loopTest/count" and one writes it');
         expect(() => loop.add(takesInput)).toThrow("takes input, which ticks don't pass");
         loop.add(increment);
         expect(() => loop.add(ordered)).toThrow("both access");
@@ -164,7 +175,7 @@ describe("a world's loop platform", () => {
     it("can be given, so a back-to-back driver ticks as fast as tasks run", async () => {
         const driver = backToBack();
         const world = createWorld({ [always]: true }, { loop: driver });
-        world.add(System.create({ name: "loopTest/idle", components: { has: [count] } }, () => {}));
+        world.add(System.create({ components: { with: [count] } }, () => {}));
         const start = performance.now();
         // At 60 frames a second, a timer's frames would take 1.6 s.
         await new Promise<void>(resolve => {

package/src/implementation/world/loop.ts

@@ -1,6 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Cadence } from '../../interface/resources/cadence.js';
 import type { Composite, Definition } from '../../interface/registry/index.js';
-import { labelOfItem } from '../../interface/registry/index.js';
 import { requireDefinition } from '../../interface/registry/program.js';
 import { isLeaf, isObserver, scheduleOf } from '../../interface/registry/schedule.js';
 import type { Leaf } from '../../interface/system/leaf.js';
@@ -104,7 +104,7 @@ const checkNoInput = (system: Definition, seen: Set<Definition> = new Set()): vo
     if (seen.has(system)) return;
     seen.add(system);
     if (isLeaf(system)) {
-        if (system.declaration.input !== undefined) throw new Error(`System "${labelOfItem(system)}" takes input, which ticks don't pass; run it instead.`);
+        if (system.input !== undefined) throw new Error(`System "${system.name}" takes input, which ticks don't pass; run it instead.`);
         return;
     }
     for (const member of system.declaration.systems) checkNoInput(requireDefinition(member), seen);
@@ -247,7 +247,7 @@ export const createLoop = (host: LoopHost): Loop => {
             }
             if (systems.includes(system)) return;
             const next = [...systems, system];
-            const candidate: Composite = { kind: "composite", name: "tick", declaration: { name: "tick", systems: next } };
+            const candidate: Composite = { kind: "composite", name: "tick", declaration: { systems: next } };
             // Throws for members ordered in a cycle, or conflicting with no order between them.
             scheduleOf(candidate);
             systems.push(system);
@@ -265,7 +265,7 @@ export const createLoop = (host: LoopHost): Loop => {
             const at = systems.indexOf(system);
             if (at < 0 || composite === null) return null;
             const left = systems.filter((_, k) => k !== at);
-            const next: Composite | null = left.length === 0 ? null : { kind: "composite", name: "tick", declaration: { name: "tick", systems: left } };
+            const next: Composite | null = left.length === 0 ? null : { kind: "composite", name: "tick", declaration: { systems: left } };
             // Throws for members that conflict with no ordering path left between them.
             if (next !== null) scheduleOf(next);
             const previous = composite;

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
 import { coveringBuffer, createMemory, pageBytes } from "./memory.js";
 

package/src/implementation/world/memory.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /** Bytes per WebAssembly page. */
 export const pageBytes = 65536;
 /** 4 GiB, the wasm32 limit. Shared memory reserves address space up front, not physical memory. */

package/src/implementation/world/mirror.ts

@@ -1,7 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { indexOf } from './entities.js';
 import {
     cursorField, entitiesWord, recordCount, recordEntities, recordStorages, recordWords,
-    remoteFlag, storageAdded, storageChanged, storageColumn, storageComponent, storageFlags, storageWords, structureWaitersWord,
+    remoteFlag, resourceEntityWord, storageAdded, storageChanged, storageColumn, storageComponent, storageFlags, storageWords, structureWaitersWord,
     structureWord, tableLengthWord, tableOffsetWord, threadShift, tickedFlag,
 } from './layout-directory.js';
 import {
@@ -38,6 +39,12 @@ type Staged = { readonly slot: number; readonly entity: number; readonly compone
 /** Whether replaying is done, waits for a component's key to be named, or found the log lapped or replaced. */
 export type Replayed = "current" | "held" | "lapped";
 
+/**
+ * Whether rebuilding is done; found a sync point applying before or during it, so it can rebuild once the structure
+ * epoch is even; or waits for a component's key to be named or a finalizer to be set up.
+ */
+export type Rebuilt = "rebuilt" | "moved" | "held";
+
 /** A joined thread's mirror of the world's rows holding its objects. */
 export type Mirror = {
     readonly memory: WebAssembly.Memory;
@@ -73,6 +80,8 @@ export type Mirror = {
     nextSlot: number;
     /** Times it rebuilt, for tests. */
     rebuilds: number;
+    /** The archetype last found holding the resource entity, or -1. */
+    resourceArchetype: number;
     /**
      * How many values of components declared `transfer` are staged and not yet settled, so the thread replays to
      * release those whose commands dropped once it's woken.
@@ -96,7 +105,7 @@ export const createMirror = (memory: WebAssembly.Memory, block: number, thread:
         memory, thread, block, buffer: memory.buffer, words: new Uint32Array(0), signed: new Int32Array(0), header: new Int32Array(0),
         ring: new Uint32Array(0), ringEntities: new Float64Array(0), version: -1, mask: 0, position: 0, through: 0, tick: 0,
         keys: new Map(), starts: new Map(), archetypes: [], scratch: new Uint32Array(1024), scratchEntities: new Float64Array(0),
-        staged: [], head: 0, nextSlot: 0, rebuilds: 0, stagedTransfers: 0, finalize: null,
+        staged: [], head: 0, nextSlot: 0, rebuilds: 0, resourceArchetype: -1, stagedTransfers: 0, finalize: null,
     };
     refresh(mirror);
     return mirror;
@@ -477,14 +486,14 @@ const previousValue = (old: readonly (Mirrored | null | undefined)[], entity: nu
 /**
  * Rebuilds every column from the layout directory, as of the last published sync, under the structure epoch: rows
  * from each archetype's `entities` and count, values by the tag each row's storage holds, a staged slot's taken, any
- * other the thread's own kept by entity, and ticks from the world's. Returns false while a sync point applies, or a
- * component it holds has no key named yet, having changed nothing.
+ * other the thread's own kept by entity, and ticks from the world's. Short of `"rebuilt"`, its columns are as they
+ * were, though the finalizers of stops through the sync it read may have run first.
  */
-export const rebuild = (mirror: Mirror): boolean => {
+export const rebuild = (mirror: Mirror): Rebuilt => {
     refresh(mirror);
     const { words, signed, header, buffer } = mirror;
     const epoch = Atomics.load(signed, structureWord);
-    if ((epoch & 1) === 1) return false;
+    if ((epoch & 1) === 1) return "moved";
     const version = Atomics.load(header, logVersionWord);
     const sync = Atomics.load(header, logSyncWord) >>> 0;
     const published = Atomics.load(header, logPublishedWord) >>> 0;
@@ -499,7 +508,7 @@ export const rebuild = (mirror: Mirror): boolean => {
             indexed = true;
         }
         return previousValue(old, entity, component, start);
-    })) return false;
+    })) return "held";
     const archetypes: (Mirrored | null)[] = [];
     /** Staged slots the rebuild takes, settled only once it's complete. */
     const taken: number[] = [];
@@ -511,7 +520,7 @@ export const rebuild = (mirror: Mirror): boolean => {
             continue;
         }
         const columns = columnsOf(mirror, record);
-        if (columns === undefined) return false;
+        if (columns === undefined) return "held";
         if (columns === null) {
             archetypes.push(null);
             continue;
@@ -550,7 +559,7 @@ export const rebuild = (mirror: Mirror): boolean => {
         archetypes.push(archetype);
     }
     // An exchange, so every read above completes before it.
-    if (Atomics.add(signed, structureWord, 0) !== epoch) return false;
+    if (Atomics.add(signed, structureWord, 0) !== epoch) return "moved";
     for (const slot of taken) {
         const staged = stagedOf(mirror, slot);
         if (staged !== undefined) staged.live = false;
@@ -563,7 +572,7 @@ export const rebuild = (mirror: Mirror): boolean => {
     viewRing(mirror);
     settle(mirror);
     mirror.rebuilds++;
-    return true;
+    return "rebuilt";
 };
 
 /** A storage's first word in a record, by its component. */
@@ -575,6 +584,32 @@ const storageOf = (words: Uint32Array, record: number, component: number): numbe
     return -1;
 };
 
+/**
+ * The value this thread holds for its object resource `component`, as replayed so far, which may be behind the entity
+ * table; its start while no row holds it. The resource entity is alone in its archetype, so at row 0, and never
+ * despawned, so its index, which the directory's header holds, names no other entity.
+ */
+export const resourceValueOf = (mirror: Mirror, component: number, start: unknown): unknown => {
+    const word = Atomics.load(mirror.words, resourceEntityWord);
+    if (word === 0) return start;
+    const index = word - 1;
+    const { archetypes } = mirror;
+    let archetype = mirror.resourceArchetype < 0 ? undefined : archetypes[mirror.resourceArchetype];
+    if (archetype === null || archetype === undefined || archetype.count === 0 || indexOf(archetype.entities[0]) !== index) {
+        archetype = undefined;
+        mirror.resourceArchetype = -1;
+        for (let id = 0; id < archetypes.length; id++) {
+            const candidate = archetypes[id];
+            if (candidate === null || candidate === undefined || candidate.count === 0 || indexOf(candidate.entities[0]) !== index) continue;
+            archetype = candidate;
+            mirror.resourceArchetype = id;
+            break;
+        }
+    }
+    const column = archetype?.byComponent[component];
+    return column === undefined ? start : column.values[0];
+};
+
 /** A staged slot's value while no sync applied it, else `settled`. */
 export const stagedValue = (mirror: Mirror, slot: number, settled: unknown): unknown => {
     const staged = stagedOf(mirror, slot);