@adobe/ecs 0.2.0 → 0.2.3

package/src/implementation/world/tables.ts

@@ -0,0 +1,330 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Layout, Path } from '../../interface/registry/layout.js';
+import { declarationOf, labelOf } from '../../interface/registry/names.js';
+import { isEntity } from '../../interface/registry/schemas.js';
+import type { Schema } from '../../interface/schema/schema.js';
+import type { Table } from '../../interface/world/table/table.js';
+import { batchOf } from './batches.js';
+import { indexOf, reserveRun } from './entities.js';
+import { internShared } from './shared.js';
+import { claimRows, openRows, writerOf, type Column as BatchColumn } from './staging.js';
+import { commandIdOf, type Key, type State } from './state.js';
+
+/** Whether a value of `schema` may hold an entity anywhere in it. */
+const holdsEntity = (schema: Schema): boolean => {
+    if (isEntity(schema)) return true;
+    if ("anyOf" in schema) return schema.anyOf.some(holdsEntity);
+    if ("allOf" in schema) return schema.allOf.some(holdsEntity);
+    if (!("type" in schema)) return false;
+    switch (schema.type) {
+        case "array": case "set": return holdsEntity(schema.items);
+        case "map": return holdsEntity(schema.keys) || holdsEntity(schema.values);
+        case "object": return Object.values(schema.properties).some(holdsEntity);
+        default: return false;
+    }
+};
+
+/** The schema at `path` inside `schema`, through struct fields and tuple items. */
+const schemaAt = (schema: Schema, path: Path): Schema | undefined => {
+    let at: Schema | undefined = schema;
+    for (const step of path) {
+        if (at === undefined || !("type" in at)) return undefined;
+        if (at.type === "object" && typeof step === "string") at = at.properties[step];
+        else if (at.type === "array" && typeof step === "number") at = at.items;
+        else return undefined;
+    }
+    return at;
+};
+
+/** The f64 leaves of a linear layout holding entities: where, in f64 elements, each row's is. */
+const entityLeavesOf = (layout: Layout, schema: Schema | undefined): readonly { readonly unitStride: number; readonly unitOffset: number }[] => {
+    if (layout.kind !== "linear" || schema === undefined) return [];
+    return layout.leaves.filter(leaf => {
+        const leafSchema = schemaAt(schema, leaf.path);
+        return leaf.view === "f64" && leafSchema !== undefined && isEntity(leafSchema);
+    });
+};
+
+/** The entity each entity of the tables given is spawned as, and what a value naming none of them becomes. */
+type Remap = (entity: number) => number;
+
+/** `value` of `schema` with each entity in it replaced by `remap`'s. */
+const remapValue = (schema: Schema, value: unknown, remap: Remap): unknown => {
+    if (isEntity(schema)) return typeof value === "number" ? remap(value) : value;
+    if (!holdsEntity(schema)) return value;
+    if ("anyOf" in schema) {
+        for (const member of schema.anyOf) {
+            if (isEntity(member) && typeof value === "number") return remap(value);
+            if (!("type" in member) || !holdsEntity(member)) continue;
+            if ((member.type === "array" && Array.isArray(value)) || (member.type === "set" && value instanceof Set) || (member.type === "map" && value instanceof Map)
+                || (member.type === "object" && typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Set) && !(value instanceof Map))) return remapValue(member, value, remap);
+        }
+        return value;
+    }
+    if ("allOf" in schema) return schema.allOf.reduce<unknown>((next, member) => remapValue(member, next, remap), value);
+    if (!("type" in schema)) return value;
+    switch (schema.type) {
+        case "array": return Array.isArray(value) ? value.map(item => remapValue(schema.items, item, remap)) : value;
+        case "set": return value instanceof Set ? new Set(Array.from(value, item => remapValue(schema.items, item, remap))) : value;
+        case "map": return value instanceof Map ? new Map(Array.from(value, ([key, item]) => [remapValue(schema.keys, key, remap), remapValue(schema.values, item, remap)])) : value;
+        case "object": {
+            if (typeof value !== "object" || value === null) return value;
+            const copy: { [name: string]: unknown } = {};
+            for (const name of Object.keys(value)) {
+                const field = schema.properties[name];
+                const item: unknown = Reflect.get(value, name);
+                copy[name] = field === undefined ? item : remapValue(field, item, remap);
+            }
+            return copy;
+        }
+        default: return value;
+    }
+};
+
+/** A table's components with their ids, the columns given for them, and their layouts. */
+type Planned = {
+    readonly table: Table;
+    readonly keys: readonly Key[];
+    readonly ids: readonly number[];
+    readonly shared: (number | undefined)[];
+};
+
+/** Throws, naming the component, for a column that doesn't fit its component's layout or its table's count. */
+const checkColumn = (state: State, key: Key, id: number, column: Table.Column, count: number): void => {
+    const layout = state.layouts[id];
+    const fail = (message: string): never => { throw new Error(`commands.spawnTables: "${labelOf(key)}" ${message}.`); };
+    if (state.shared[id] !== undefined) {
+        if (column.kind !== "value") fail("is a shared component, so its column is one value");
+        return;
+    }
+    if (layout.kind === "constant" || column.kind === "value") return;
+    if (layout.kind === "linear") {
+        if (column.kind !== "bytes") fail("is stored as bytes, so its column gives bytes");
+        else if (column.stride !== layout.stride) fail(`has a stride of ${layout.stride} bytes in this world, not ${column.stride}`);
+        else if (column.bytes.length !== count * layout.stride) fail(`gives ${column.bytes.length} bytes for ${count} rows of ${layout.stride}`);
+        return;
+    }
+    if (column.kind !== "values") fail("is stored as values, so its column gives values");
+    else if (column.values.length !== count) fail(`gives ${column.values.length} values for ${count} rows`);
+};
+
+/** The plan of each table: its keys, their command ids, and the numbers of its shared values. Throws for one that won't spawn. */
+const planOf = (state: State, table: Table): Planned => {
+    const { count, entities, columns } = table;
+    if (!Number.isInteger(count) || count < 0 || entities.length !== count) throw new Error(`commands.spawnTables: a table of ${count} rows gives ${entities.length} entities.`);
+    const keys = Object.getOwnPropertySymbols(columns).filter(key => Reflect.get(columns, key) !== undefined);
+    const ids = keys.map(key => commandIdOf(state, key));
+    const shared: (number | undefined)[] = [];
+    keys.forEach((key, k) => {
+        const column: Table.Column = Reflect.get(columns, key);
+        checkColumn(state, key, ids[k], column, count);
+        const values = state.shared[ids[k]];
+        if (values !== undefined && column.kind === "value") {
+            const number = internShared(values, column.value);
+            if (number < 0) throw new Error(`commands.spawnTables: "${labelOf(key)}", a shared component, isn't given one of its type's values: ${labelOf(column.value)}.`);
+            shared[ids[k]] = number;
+        }
+    });
+    return { table, keys, ids, shared };
+};
+
+/**
+ * Where each entity of the tables is, by its index: the entity itself, to tell it from another of that index, and its
+ * position among all the tables' rows. Throws for an entity two rows name.
+ */
+const placesOf = (plans: readonly Planned[]): { readonly entities: Float64Array; readonly positions: Int32Array } => {
+    let largest = 0;
+    for (const { table } of plans) for (let row = 0; row < table.count; row++) largest = Math.max(largest, indexOf(table.entities[row]));
+    const entities = new Float64Array(largest + 1).fill(-1);
+    const positions = new Int32Array(largest + 1);
+    let position = 0;
+    for (const { table } of plans) {
+        for (let row = 0; row < table.count; row++) {
+            const entity = table.entities[row];
+            const index = indexOf(entity);
+            if (entities[index] === entity) throw new Error(`commands.spawnTables: entity ${entity} is in two rows.`);
+            entities[index] = entity;
+            positions[index] = position++;
+        }
+    }
+    return { entities, positions };
+};
+
+/** A reference column's entity value in each row: the f64 at the row's start, a reference's whole value. */
+const referencesOf = (column: Table.Column): ((row: number) => number) => {
+    if (column.kind !== "bytes") return () => 0;
+    const view = new DataView(column.bytes.buffer, column.bytes.byteOffset, column.bytes.byteLength);
+    const { stride } = column;
+    return row => view.getFloat64(row * stride, true);
+};
+
+/** Copies a table's `rows`, or all of them, of one column into rows `start` on of a batch's column, remapping entities. */
+const copyColumn = (target: BatchColumn, column: Table.Column, schema: Schema | undefined, rows: readonly number[] | null, count: number, start: number, remap: Remap | null): void => {
+    const rowAt = (i: number): number => rows === null ? i : rows[i];
+    const remapped = remap !== null && schema !== undefined && holdsEntity(schema);
+    if (column.kind === "value") {
+        const write = writerOf(target, column.value);
+        const value = remapped ? remapValue(schema, column.value, remap) : column.value;
+        for (let i = 0; i < count; i++) write(start + i, value);
+        return;
+    }
+    if (column.kind === "bytes") {
+        const { stride } = target;
+        if (rows === null) target.views.u8.set(column.bytes, start * stride);
+        else for (let i = 0; i < count; i++) target.views.u8.set(column.bytes.subarray(rows[i] * stride, (rows[i] + 1) * stride), (start + i) * stride);
+        if (!remapped) return;
+        const { f64 } = target.views;
+        for (const leaf of entityLeavesOf(target.layout, schema)) {
+            for (let row = start, end = start + count; row < end; row++) {
+                const index = row * leaf.unitStride + leaf.unitOffset;
+                f64[index] = remap(f64[index]);
+            }
+        }
+        return;
+    }
+    if (target.remote !== null && column.values.some(value => value !== undefined && value !== null)) throw new Error(target.remote);
+    for (let i = 0; i < count; i++) {
+        const value = column.values[rowAt(i)];
+        target.values[start + i] = remapped ? remapValue(schema, value, remap) : value;
+    }
+};
+
+/** Spawns `rows` of a plan's table, or all of them, with the components it holds but `removed`, as `entities`. */
+const spawnRows = (state: State, { table, keys, ids, shared }: Planned, rows: readonly number[] | null, removed: ReadonlySet<Key>, entities: Float64Array, remap: Remap | null): void => {
+    const kept = keys.flatMap((key, k) => removed.has(key) ? [] : [k]);
+    const batch = batchOf(state, kept.map(k => ids[k]), shared.length === 0 ? undefined : shared);
+    const start = openRows(batch, entities.length);
+    for (const k of kept) {
+        const target = batch.columns.find(column => column.id === ids[k]);
+        if (target === undefined || target.layout.kind === "constant") continue;
+        const column: Table.Column = Reflect.get(table.columns, keys[k]);
+        copyColumn(target, column, declarationOf(keys[k])?.type, rows, entities.length, start, remap);
+    }
+    claimRows(batch, entities);
+};
+
+/**
+ * Spawns an entity for each row of `tables` into the batches of their components, as references would leave them had
+ * the entities outside the tables despawned: a row owned, directly or through others, by an entity outside them isn't
+ * spawned; a weak reference to one is removed; and any other entity value naming one is `Entity.none`. Every entity
+ * value naming an entity spawned names the one spawned for it.
+ */
+export const spawnTables = (state: State, tables: readonly Table[]): Table.Spawned => {
+    const plans = tables.map(table => planOf(state, table));
+    // Entities are mapped only where a value of the tables may hold one.
+    const remapping = plans.some(({ keys }) => keys.some(key => {
+        const schema = declarationOf(key)?.type;
+        return schema !== undefined && holdsEntity(schema);
+    }));
+    const none: ReadonlySet<Key> = new Set();
+    if (!remapping) {
+        const entities = plans.map(({ table }) => {
+            const spawned = new Float64Array(table.count);
+            reserveRun(state.entities, spawned);
+            return spawned;
+        });
+        plans.forEach((plan, t) => spawnRows(state, plan, null, none, entities[t], null));
+        return { entities, dropped: 0 };
+    }
+    const places = placesOf(plans);
+    const positionOf = (entity: number): number => {
+        const index = indexOf(entity);
+        return entity !== 0 && index < places.entities.length && places.entities[index] === entity ? places.positions[index] : -1;
+    };
+    const firsts: number[] = [];
+    let total = 0;
+    for (const { table } of plans) {
+        firsts.push(total);
+        total += table.count;
+    }
+    // A row owned by an entity outside the tables isn't spawned, nor anything it owns, as despawning its owner would.
+    const dropped = new Uint8Array(total);
+    /** Each owner reference between rows of the tables: the owned row's position, and its owner's. */
+    const ownedRows: number[] = [];
+    const ownerRows: number[] = [];
+    const waiting: number[] = [];
+    plans.forEach(({ table, keys }, t) => {
+        for (const key of keys) {
+            if (declarationOf(key)?.reference !== "owner") continue;
+            const ownerAt = referencesOf(Reflect.get(table.columns, key));
+            for (let row = 0; row < table.count; row++) {
+                const owner = ownerAt(row);
+                if (owner === 0) continue;
+                const at = positionOf(owner);
+                const position = firsts[t] + row;
+                if (at >= 0) {
+                    ownedRows.push(position);
+                    ownerRows.push(at);
+                }
+                else if (dropped[position] === 0) {
+                    dropped[position] = 1;
+                    waiting.push(position);
+                }
+            }
+        }
+    });
+    if (waiting.length > 0) {
+        const owned = new Map<number, number[]>();
+        for (let i = 0; i < ownedRows.length; i++) {
+            const list = owned.get(ownerRows[i]);
+            if (list === undefined) owned.set(ownerRows[i], [ownedRows[i]]);
+            else list.push(ownedRows[i]);
+        }
+        for (let next = waiting.pop(); next !== undefined; next = waiting.pop()) {
+            for (const child of owned.get(next) ?? []) {
+                if (dropped[child] !== 0) continue;
+                dropped[child] = 1;
+                waiting.push(child);
+            }
+        }
+    }
+    const spawnedAt = new Float64Array(total);
+    const entities = plans.map(({ table }, t) => {
+        const alive = [];
+        for (let row = 0; row < table.count; row++) if (dropped[firsts[t] + row] === 0) alive.push(row);
+        const reserved = new Float64Array(alive.length);
+        reserveRun(state.entities, reserved);
+        const spawned = new Float64Array(table.count);
+        alive.forEach((row, i) => {
+            spawned[row] = reserved[i];
+            spawnedAt[firsts[t] + row] = reserved[i];
+        });
+        return spawned;
+    });
+    const isSpawned = (entity: number): boolean => {
+        const at = positionOf(entity);
+        return at >= 0 && dropped[at] === 0;
+    };
+    const remap: Remap = entity => isSpawned(entity) ? spawnedAt[positionOf(entity)] : 0;
+    let droppedCount = 0;
+    plans.forEach((plan, t) => {
+        const { table, keys } = plan;
+        const first = firsts[t];
+        const weak = keys.filter(key => declarationOf(key)?.reference === "weak").map(key => ({ key, targetAt: referencesOf(Reflect.get(table.columns, key)) }));
+        const loses = (row: number): boolean => weak.some(({ targetAt }) => {
+            const target = targetAt(row);
+            return target !== 0 && !isSpawned(target);
+        });
+        let whole = true;
+        for (let row = 0; row < table.count && whole; row++) if (dropped[first + row] !== 0 || loses(row)) whole = false;
+        if (whole) return spawnRows(state, plan, null, none, entities[t], remap);
+        // Rows by the weak references they lose, whose targets aren't spawned: each set of components a batch of its own.
+        const groups = new Map<string, { readonly removed: Set<Key>; readonly rows: number[] }>();
+        for (let row = 0; row < table.count; row++) {
+            if (dropped[first + row] !== 0) {
+                droppedCount++;
+                continue;
+            }
+            const removed = weak.filter(({ targetAt }) => {
+                const target = targetAt(row);
+                return target !== 0 && !isSpawned(target);
+            }).map(({ key }) => key);
+            const signature = removed.map(key => weak.findIndex(entry => entry.key === key)).join(",");
+            let group = groups.get(signature);
+            if (group === undefined) groups.set(signature, group = { removed: new Set(removed), rows: [] });
+            group.rows.push(row);
+        }
+        for (const { removed, rows } of groups.values()) spawnRows(state, plan, rows, removed, Float64Array.from(rows, row => entities[t][row]), remap);
+    });
+    return { entities, dropped: droppedCount };
+};

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

@@ -75,7 +75,7 @@ describe("tails", () => {
         const { world, remote } = await joined({ loop: driver }, { [always]: true });
         await world.run(seed, { count: 10 });
         const counters: number[] = [];
-        const values = System.create({ observer: true }, ({ resources }) => { counters.push(resources[counter]); });
+        const values = System.create({ readonly: true }, ({ resources }) => { counters.push(resources[counter]); });
         world.add(ticked);
         world.add(values);
         await until(Observe.resource(world, counter), value => value >= 5);

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

@@ -24,8 +24,8 @@ const remove = System.create({ target: "entity", components: { with: [tagged] }
 });
 let amounts: number[] = [];
 let changed: number[] = [];
-const readAmounts = System.create({ observer: true, components: { with: [amount] } }, row => { amounts.push(row[amount]); });
-const watchChanged = System.create({ observer: true, components: { with: [amount], changed: [amount] } }, row => { changed.push(row[amount]); });
+const readAmounts = System.create({ readonly: true, components: { with: [amount] } }, row => { amounts.push(row[amount]); });
+const watchChanged = System.create({ readonly: true, components: { with: [amount], changed: [amount] } }, row => { changed.push(row[amount]); });
 
 const inline = () => createWorld({ [workers]: 0 });
 const amountsOf = async (world: ReturnType<typeof inline>): Promise<number[]> => {

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

@@ -69,7 +69,7 @@ const errorOf = (error: unknown): WorkerError =>
 
 const refuse = (): never => { throw new Error("An observer system issues no commands."); };
 /** An observer system's context has no commands, so these are never called. */
-const noCommands: Commands = { spawn: refuse, despawn: refuse, add: refuse, remove: refuse };
+const noCommands: Commands = { spawn: refuse, despawn: refuse, add: refuse, remove: refuse, spawnTables: refuse };
 const noStamps: number[] = [];
 
 export const createThreadObserver = (host: ThreadObserverHost) => {

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

@@ -172,7 +172,7 @@ const reading: { entities: readonly Entity[]; objects: readonly { readonly [name
 
 /** Each entity's objects of the thread, as data, a note by its text: none for an entity that's dead or has no uid. */
 const readObjects = System.create({
-    observer: true,
+    readonly: true,
     lookup: { ids: { with: [uid] }, captions: { with: [caption] }, notes: { with: [note] } },
 }, ({ lookup }) => {
     reading.objects = reading.entities.map(entity => {
@@ -322,9 +322,9 @@ export const paintReader = System.create(({ resources }) => () => resources[pain
 /** A composite of systems on the thread returning values, which no run resolves to. */
 export const paintsTogether = System.create([paintReader, paintLengthThere]);
 /** An observer system on the thread, as it reads the thread's paint: what a run of it resolves to. */
-export const paintObserved = System.create({ observer: true }, ({ resources }) => resources[paint].text);
+export const paintObserved = System.create({ readonly: true }, ({ resources }) => resources[paint].text);
 /** An observer system on the thread, throwing there. */
-export const paintObservedFails = System.create({ observer: true }, ({ resources }) => {
+export const paintObservedFails = System.create({ readonly: true }, ({ resources }) => {
     if (resources[paint].text !== "never") throw new Error("threadSystemsTest observer failure there");
     return 0;
 });

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

@@ -279,6 +279,7 @@ export const createThreadSystems = (host: ThreadSystemsHost) => {
             return typeof preset === "object" && preset !== null ? presetSpawnerOf(components, preset) : spawnerOf(components);
         },
         despawn: entity => beginCommand(writer, despawnCommand, entity),
+        spawnTables: () => { throw new Error("commands.spawnTables 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);

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

@@ -62,10 +62,10 @@ export const noteInView = System.create({ components: { with: [position, note],
     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]); });
+export const hearInView = System.create({ readonly: 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]); });
+export const signalInView = System.create({ readonly: 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 }) => {
@@ -79,7 +79,7 @@ export const noteChanged = System.create({ components: { with: [position, note],
     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 readNotes = System.create({ readonly: 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. */
@@ -91,7 +91,7 @@ const until = async (done: () => boolean): Promise<void> => {
 /** 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]}`]); }));
+    await world.run(System.create({ readonly: 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"));
 };
 

package/src/implementation/world/workers.fixture.ts

@@ -149,8 +149,8 @@ const emitted = { seen: 0 };
 const countEmitted = System.create({ components: { added: [position], with: [spawned] } }, () => { emitted.seen++; });
 
 const gathered: Entity[] = [];
-const gatherPositioned = System.create({ observer: true, components: { with: [position] } }, row => { gathered.push(row.entity); });
-const gatherSpawned = System.create({ observer: true, components: { with: [spawned] } }, row => { gathered.push(row.entity); });
+const gatherPositioned = System.create({ readonly: true, components: { with: [position] } }, row => { gathered.push(row.entity); });
+const gatherSpawned = System.create({ readonly: true, components: { with: [spawned] } }, row => { gathered.push(row.entity); });
 
 /** The entities an observer row system passes, in storage order. */
 const storageOrder = async (world: World, gather: System<void>): Promise<Entity[]> => {

package/src/index.ts

@@ -3,9 +3,6 @@
  * A high-performance, multithreaded Entity Component System.
  * @module @adobe/ecs
  */
-import { create, join } from './implementation/index.js';
-import type { Create } from './interface/world/create.js';
-import type { Join } from './interface/world/join.js';
 import type { World as Created } from './interface/world/world.js';
 
 export * from './interface/index.js';
@@ -15,7 +12,8 @@ export type World = Created;
 
 /**
  * How a world is made, `World.create(resources?)`, on the thread that will run it, with resources starting at the given
- * values in place of their defaults; and how another thread joins one that shared itself with it,
- * `World.join(port, { threads })`.
+ * values in place of their defaults; how another thread joins one that shared itself with it,
+ * `World.join(port, { threads })`; and `World.Table`, an archetype's rows as a readonly system's `tables` copies them
+ * and `commands.spawnTables` spawns them.
  */
-export const World: { readonly create: Create; readonly join: Join } = { create, join };
+export * as World from './world.js';

package/src/interface/component/component.ts

@@ -1,5 +1,11 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Key } from './key.js';
+import type { Type } from './value.js';
 
-export type Component = never;
+/**
+ * The type of component `K`'s value, as its record in `Components` declares it: `Component<typeof position>`. The
+ * namespace's `Key` and `With` name components' keys.
+ */
+export type Component<K extends Key> = Type<K>;
 
 export * as Component from './index.js';

package/src/interface/component/declarations.ts

@@ -0,0 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Declared } from './declared.js';
+import { declaredOf } from '../registry/names.js';
+import type { Key } from './key.js';
+
+/** Every component its modules registered so far, with its declaration. */
+export const declarations = (): ReadonlyMap<Key, Declared> => {
+    // Registration takes only keys declared in `Components`, so each symbol registered as a component is one of its keys.
+    const found = declaredOf("component") as ReadonlyMap<Key, Declared>;
+    return found;
+};

package/src/interface/component/declared.ts

@@ -0,0 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from '../schema/schema.js';
+import type { Key as TraitKey } from '../trait/key.js';
+
+/**
+ * A component's or resource's declaration as registered: its schema as `type` where its value is data, what it
+ * starts at as `default`, and its other traits, the built-in ones by name and those of your own by their keys.
+ */
+export type Declared = { readonly type?: Schema; readonly default?: unknown } & { readonly [T in TraitKey]?: unknown };

package/src/interface/component/index.ts

@@ -1,3 +1,5 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 export type { Key } from './key.js';
-export type { Value, With } from './value.js';
+export type { With } from './value.js';
+export { declarations } from './declarations.js';
+export type { Declared } from './declared.js';

package/src/interface/component/value.ts

@@ -4,16 +4,16 @@ import type { Key as TraitKey } from "../trait/key.js";
 import type { Key } from "./key.js";
 import type { Components } from "./types.js";
 
-/** Every component's value type, computed once so `Value` is a lookup. */
-type ValueTypes = { readonly [K in Key]: Components[K] extends { readonly type: infer T } ? T : never };
+/** Every component's value type, computed once so `Type` is a lookup. */
+type Types = { readonly [K in Key]: Components[K] extends { readonly type: infer T } ? T : never };
 
 /** The value type of component `K`. */
-export type Value<K extends Key> = ValueTypes[K];
+export type Type<K extends Key> = Types[K];
 
 type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 
 /** Component `K`'s value as reads return it: read-only, with branded primitives such as `Entity` as they are. */
-export type ReadonlyValue<K extends Key> = Value<K> extends Primitive ? Value<K> : Readonly<Value<K>>;
+export type ReadonlyType<K extends Key> = Type<K> extends Primitive ? Type<K> : Readonly<Type<K>>;
 
 /** Components that declare trait `T`, with a value assignable to `V`. */
 export type With<T extends TraitKey, V = unknown> = { [K in Key]: Components[K] extends { readonly [P in T]: V } ? K : never }[Key];
@@ -35,7 +35,7 @@ export type Shared = With<"shared">;
 export type Writable = Exclude<Key, With<"reference"> | Shared>;
 
 /** Every component's thread, computed once so `ThreadOf` is a lookup. */
-type Threads = { readonly [K in Key]: ThreadOf<Components[K], Value<K>> };
+type Threads = { readonly [K in Key]: ThreadOf<Components[K], Type<K>> };
 
 /** The thread component `K` lives on, or `never` for a struct, which lives in shared memory. */
 export type ThreadOfComponent<K extends Key> = Threads[K];

package/src/interface/component/values.ts

@@ -1,6 +1,6 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Key } from "./key.js";
-import type { Value } from './value.js';
+import type { Type } from './value.js';
 
 /** Values for any subset of components, keyed by component. */
-export type Values = { readonly [K in Key]?: Value<K> };
+export type Values = { readonly [K in Key]?: Type<K> };

package/src/interface/finalizer/body.ts

@@ -6,7 +6,7 @@ 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 { Essential, ReadonlyValue } from '../component/value.js';
+import type { Essential, ReadonlyType } from '../component/value.js';
 import type { Elsewhere, ThreadsOf } from '../system/threads.js';
 
 /**
@@ -14,8 +14,8 @@ import type { Elsewhere, ThreadsOf } from '../system/threads.js';
  * its `optional` where it had them, `undefined` where it didn't.
  */
 export type Row<D extends Declaration> =
-    { readonly entity: Entity } & { readonly [K in Listed<Property<D, "components">, "with"> & Component.Key]: Component.Value<K> }
-    & { readonly [K in Exclude<Listed<Property<D, "components">, "optional">, Listed<Property<D, "components">, "with">> & Component.Key]: Component.Value<K> | undefined };
+    { readonly entity: Entity } & { readonly [K in Listed<Property<D, "components">, "with"> & Component.Key]: Component<K> }
+    & { readonly [K in Exclude<Listed<Property<D, "components">, "optional">, Listed<Property<D, "components">, "with">> & Component.Key]: Component<K> | undefined };
 
 /**
  * Every resource, its lookups when declared, and the commands it issues for the next sync point: none on another
@@ -46,7 +46,7 @@ export type Group<C extends Component.Key> = {
 export type ChangeSet<C extends Component.Key> = {
     readonly groups: readonly Group<C>[];
     /** The value before the sync point, or null if the entity didn't have it. */
-    previous<K extends C>(entity: Entity, component: K): ReadonlyValue<K> | null;
+    previous<K extends C>(entity: Entity, component: K): ReadonlyType<K> | null;
     /** The value after it, or null if the entity won't have it. */
-    next<K extends C>(entity: Entity, component: K): ReadonlyValue<K> | null;
+    next<K extends C>(entity: Entity, component: K): ReadonlyType<K> | null;
 };

package/src/interface/index.type-test.ts

@@ -27,8 +27,8 @@ Rule.create({ components: { with: [position] }, derive: [slot] });
 declare const create: Create;
 declare const wgsl: typeof Gpu.wgsl;
 export const world = create({ [workers]: 4, [gpuDevice]: null });
-export const read = System.create({ observer: true, components: { with: [position, slot] } }, () => {});
-export const readOne = System.create({ observer: true, lookup: { at: { with: [position, slot] } } }, () => {});
+export const read = System.create({ readonly: true, components: { with: [position, slot] } }, () => {});
+export const readOne = System.create({ readonly: true, lookup: { at: { with: [position, slot] } } }, () => {});
 export const report = world.run(all);
 export const shader = wgsl(draw);
 export const added = world.add(read);
@@ -36,7 +36,7 @@ export const added = world.add(read);
 // Only types a consumer declares with are named; the rest are inferred where wanted.
 // @ts-expect-error a thread's name is keyof Threads
 export type NoThread = Ecs.Thread;
-// @ts-expect-error the cadence's value is Resource.Value<typeof cadence>
+// @ts-expect-error the cadence's value is Resource<typeof cadence>
 export type NoCadence = Ecs.Cadence;
 // @ts-expect-error a rule is the value Rule.create returns: ReturnType<typeof Rule.create>
 export const noRule: Rule = Rule.create({ components: { with: [position] }, derive: [slot] });

package/src/interface/indexes/index.type-test.ts

@@ -219,7 +219,7 @@ System.create({
 
 // An index lookup's `changed: true` runs its system only when the index's entries changed since it last ran: its
 // lists' `changed` then reports entries alone. Observer systems and CPU kernels take it; it's not a list of components.
-System.create({ observer: true, lookup: { living: { index: living, changed: true } } }, ({ lookup }) => {
+System.create({ readonly: true, lookup: { living: { index: living, changed: true } } }, ({ lookup }) => {
     const rows = lookup.living();
     check<Equal<typeof rows.changed, boolean>>();
     check<Equal<typeof rows.length, number>>();

package/src/interface/registry/names.ts

@@ -61,6 +61,14 @@ const entryOf = (key: symbol): Entry | undefined => {
     return entries.get(key);
 };
 
+/** Every key registered as `kind`, each by the symbol a world gives its values by, with its declaration. */
+export const declaredOf = (kind: "component" | "resource"): ReadonlyMap<symbol, AnyDeclaration> => {
+    catchUp();
+    const found = new Map<symbol, AnyDeclaration>();
+    for (const entry of entries.values()) if (entry.kind === kind && entry.declaration !== undefined) found.set(entry.newest, entry.declaration);
+    return found;
+};
+
 /** Whether a key is a component, a resource or a trait. */
 export const kindOf = (key: unknown): Kind | undefined => typeof key === "symbol" ? entryOf(key)?.kind : undefined;