@adobe/ecs 0.2.1 → 0.2.3

package/src/interface/system/tables.ts

@@ -0,0 +1,21 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../component/component.js';
+import type { Resource } from '../resource/resource.js';
+import type { Table } from '../world/table/table.js';
+
+/**
+ * What a readonly system's `tables` reads: of every archetype matching `with` and `not` that holds any of
+ * `components`, a table of those it holds; and, with `resources`, each resource's value.
+ */
+export type TablesDeclaration = {
+    readonly components: readonly Component.Key[];
+    readonly with?: readonly Component.Key[];
+    readonly not?: readonly Component.Key[];
+    readonly resources?: readonly Resource.Key[];
+};
+
+/** A readonly system's `tables`: a table of each archetype its declaration reads, and the values of the resources it reads. */
+export type Tables = {
+    readonly archetypes: readonly Table[];
+    readonly resources: { readonly [K in Resource.Key]?: Resource<K> };
+};

package/src/interface/system/up.type-test.ts

@@ -62,6 +62,6 @@ System.create({
     up: { through: parent },
 }, () => {});
 
-// An observer system reads what a sync point left, in no order.
-// @ts-expect-error an observer system has no up
-System.create({ observer: true, components: { with: [local] }, up: { through: parent } }, () => {});
+// A readonly system reads what a sync point left, in no order.
+// @ts-expect-error a readonly system has no up
+System.create({ readonly: true, components: { with: [local] }, up: { through: parent } }, () => {});

package/src/interface/world/index.ts

@@ -1,3 +1,3 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
-// The `World` namespace's members: none, since a consumer declares nothing more with it.
-export {};
+// The `World` namespace's types.
+export type { Table } from './table/table.js';

package/src/interface/world/run.type-test.ts

@@ -19,7 +19,7 @@ declare module '@adobe/ecs' {
 }
 
 // A run resolves to its per-run body's value: a one-off read is an observer system returning it.
-const count = System.create({ observer: true }, ({ resources }) => resources[frames]);
+const count = System.create({ readonly: true }, ({ resources }) => resources[frames]);
 check<Equal<typeof count, System<undefined, number>>>();
 const counted: Promise<number> = world.run(count);
 // @ts-expect-error a run of it resolves to a number
@@ -32,7 +32,7 @@ const scaled = System.create({}, ({ resources }, input: { readonly by: number })
 const scaledValue: Promise<{ scaled: number }> = world.run(scaled, { by: 2 });
 
 // A body that may be skipped, as one whose conditions or resource change filters can fail, may give undefined.
-const changedFrames = System.create({ observer: true, resources: { changed: [frames] } }, ({ resources }) => resources[frames]);
+const changedFrames = System.create({ readonly: true, resources: { changed: [frames] } }, ({ resources }) => resources[frames]);
 check<Equal<typeof changedFrames, System<undefined, number | undefined>>>();
 const whileDevice = System.create({ resources: { is: [gpuDevice] } }, () => "drawn");
 const drawn: Promise<string | undefined> = world.run(whileDevice);
@@ -68,7 +68,7 @@ void [counted, notText, nextValue, scaledValue, drawn, rows, composite, input, n
 // @ts-expect-error a body returns no promise
 System.create(() => Promise.resolve(1));
 // @ts-expect-error a body returns no promise
-System.create({ observer: true }, () => Promise.resolve(1));
+System.create({ readonly: true }, () => Promise.resolve(1));
 // @ts-expect-error a body returns no promise, a row system's neither
 System.create({ components: { with: [position] } }, () => Promise.resolve());
 // @ts-expect-error a body returns no promise, a render system's neither

package/src/interface/world/table/index.ts

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/**
+ * One component's values in a table, copies taken as a readonly system reads `tables`:
+ * - `bytes`: a struct's or number's, `stride` bytes per row in the world's layout for it, which is a function of the
+ *   component's schema alone;
+ * - `values`: a string's or an object's, one per row;
+ * - `value`: one value every row holds, for a shared component or one whose schema is a constant.
+ */
+export type Column =
+    | { readonly kind: "bytes"; readonly bytes: Uint8Array; readonly stride: number }
+    | { readonly kind: "values"; readonly values: readonly unknown[] }
+    | { readonly kind: "value"; readonly value: unknown };
+
+/**
+ * What `commands.spawnTables` spawned: each table's new entities in its row order, `Entity.none` for a row it didn't
+ * spawn, and how many rows it didn't, those owned by an entity outside the tables.
+ */
+export type Spawned = { readonly entities: readonly Float64Array[]; readonly dropped: number };

package/src/interface/world/table/table.ts

@@ -0,0 +1,12 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../../component/component.js';
+import type { Column } from './index.js';
+
+/** The rows of one archetype: their entities in row order, and a column for each component asked for that it holds. */
+export type Table = {
+    readonly count: number;
+    readonly entities: Float64Array;
+    readonly columns: { readonly [K in Component.Key]?: Column };
+};
+
+export type * as Table from './index.js';

package/src/interface/world/world.ts

@@ -3,23 +3,23 @@ import type { Input } from '../system/input.js';
 import type { System } from '../system/system.js';
 
 /**
- * A world. Systems read and change it; observer systems read it after each run's and tick's sync point. Every member's
+ * A world. Systems read and change it; readonly systems read it after each run's and tick's sync point. Every member's
  * type is named from the package root, so declarations a consumer emits for its results name no internal module.
  */
 export type World = {
     /**
      * The one way to change state. Runs are sequential in call order; physically, any that don't conflict overlap. Each
-     * runs a system or composite, ending in a sync point, then observer systems, the run's and those added, and
+     * runs a system or composite, ending in a sync point, then readonly systems, the run's and those added, and
      * resolves to what a per-run body returns: a system without components resolves to its body's value, or
      * `undefined` when its body was skipped, and any other system or composite to nothing. So a one-off read is a run
-     * of an observer system returning what it read; one that runs on a joined thread, as it reads objects there, runs
-     * there before the run resolves, to its value as structured clone. A run of observer systems alone runs them once
+     * of a readonly system returning what it read; one that runs on a joined thread, as it reads objects there, runs
+     * there before the run resolves, to its value as structured clone. A run of readonly systems alone runs them once
      * after an empty sync point, and doesn't wake the loop.
      *
      * When a system or finalizer of the run fails, later tiers are skipped, the sync point still applies what was done,
-     * and once its observer systems ran the run rejects with an `Error` naming each failure, its system's label and id,
+     * and once its readonly systems ran the run rejects with an `Error` naming each failure, its system's label and id,
      * message and cause. It rejects too when the run can't happen or finish: registration fails, the world is disposed,
-     * its GPU device is lost, or its sync point can't apply a command's value. What fails after it, an observer system
+     * its GPU device is lost, or its sync point can't apply a command's value. What fails after it, a readonly system
      * added or GPU work, is reported out of band, as ticks' failures are (see `add`).
      */
     run<I, R>(system: System<I, R>, ...input: Input<NoInfer<I>>): Promise<R>;
@@ -27,9 +27,9 @@ export type World = {
      * Adds a system to every tick, from the next one on, ordered with those already added by its constraints, as a
      * composite's members are. A tick runs on a beat of the `cadence` resource where `always` is set, `wake` is due or
      * a run arrived since the last tick, and only while some system is added. Throws for a system with no ordering path
-     * to one already added that conflicts with it. An observer system runs after every run's and tick's sync point
+     * to one already added that conflicts with it. A readonly system runs after every run's and tick's sync point
      * instead. It never conflicts and doesn't count as an added system for ticking. On a joined thread `add` takes only
-     * observer systems, whose keys need ids: each runs on that thread after the world's sync points, once for the
+     * readonly systems, whose keys need ids: each runs on that thread after the world's sync points, once for the
      * newest when the thread fell behind, reading structs and the objects of the threads it fills as of one sync point.
      *
      * What added systems throw, and what fails in ticks, is reported out of band on the world's thread, as an `Error`
@@ -43,14 +43,14 @@ export type World = {
      * released. A system added both alone and within an added composite stays until both are removed; constraints
      * naming a removed system are ignored. Removing a value that isn't added does nothing. Throws, removing nothing,
      * when the systems left would conflict with no ordering path between them, as `add` does. On a joined thread it
-     * takes only observer systems.
+     * takes only readonly systems.
      */
     remove(system: System<void>): void;
     /**
      * Lets another thread join this world through `port`, one end of a channel to it, of the browser or node: a
      * `MessagePort`, a `Worker`, or a worker's own scope, `self` or node's `parentPort`. That thread joins through the
      * other end, claiming the logical threads it fills. Resolves once it has joined: the threads it claims are its own,
-     * and the observer systems it added as its join resolved, before awaiting anything else, are added, so a run
+     * and the readonly systems it added as its join resolved, before awaiting anything else, are added, so a run
      * started afterwards runs on it and reaches them; one it adds later reaches the runs after its add arrived.
      * Rejects with an `Error` saying why it didn't join: the world refused its claim, as of a thread claimed twice, the
      * world was disposed, the port is shared already, or that thread ended first, as the platform reports it: a

package/src/observe/entity.ts

@@ -129,14 +129,14 @@ const createShape = (state: WorldState, byShape: Map<string, EntityShape>, id: s
     let finders: Finders | null = null;
     let source: object | null = null;
     const system = optional.length === 0
-        ? System.create(labelled({ observer: true, lookup: { presence: { with: required, changed: required }, values: { with: required }, members: { index: membersOf(required), changed: required } } }, name, { lookup: { values: required } }), ({ lookup }) => {
+        ? System.create(labelled({ readonly: true, lookup: { presence: { with: required, changed: required }, values: { with: required }, members: { index: membersOf(required), changed: required } } }, name, { lookup: { values: required } }), ({ lookup }) => {
             if (source !== lookup || finders === null) {
                 source = lookup;
                 finders = { presence: lookup.presence, values: lookup.values, optional: noOptional };
             }
             pass(lookup.members().changed, finders);
         })
-        : System.create(labelled({ observer: true, lookup: optionalLookups(required, optional) }, name, { lookup: optionalReads(required, optional) }), ({ lookup }) => {
+        : System.create(labelled({ readonly: true, lookup: optionalLookups(required, optional) }, name, { lookup: optionalReads(required, optional) }), ({ lookup }) => {
             if (source !== lookup || finders === null) {
                 source = lookup;
                 finders = { presence: lookup.presence, values: lookup.values, optional: (index, entity) => lookup[index](entity) };

package/src/observe/resource.ts

@@ -31,14 +31,14 @@ const createShape = (state: WorldState, byKey: Map<Resource.Key, ResourceShape>,
     const label = `Observe.resource(${key.description ?? "?"})`;
     // On a joined thread, first values come once a run of this system resolved, never in its pass: none to skip.
     const { joined } = state;
-    const notifier = System.create(labelled({ observer: true, resources: { changed: [key] } }, label, { resources: [key] }), ({ resources }) => {
+    const notifier = System.create(labelled({ readonly: true, resources: { changed: [key] } }, label, { resources: [key] }), ({ resources }) => {
         passed(state);
         entry.value = resources[key];
         entry.valid = true;
         if (entry.stopped > 0) sweepSubscribers(entry);
         throwFailed(give(entry, 0, true, state.pass, joined ? -1 : state.pass, none));
     });
-    const reader = System.create(labelled({ observer: true }, label, { resources: [key] }), ({ resources }) => {
+    const reader = System.create(labelled({ readonly: true }, label, { resources: [key] }), ({ resources }) => {
         const through = shape.called.shift() ?? 0;
         entry.value = resources[key];
         entry.valid = true;

package/src/observe/select.ts

@@ -403,16 +403,16 @@ const createShape = (state: WorldState, byShape: Map<string, QueryShape>, id: st
     };
 
     const tracker = ordered !== null
-        ? System.create(labelled({ observer: true, lookup: { list: { index: ordered, changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
+        ? System.create(labelled({ readonly: true, lookup: { list: { index: ordered, changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
             track(lookup.list(), null, fromSorted);
         })
         : byRange !== null
-            ? System.create(labelled({ observer: true, lookup: { list: { index: byRange, changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
+            ? System.create(labelled({ readonly: true, lookup: { list: { index: byRange, changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
                 // A range is of a `where` condition on the index's key, which the query's type checked against its
                 // values.
                 track(null, entry => ownRange(entry, range => lookup.list(range as Parameters<typeof lookup.list>[0]), () => lookup.list()), fromSorted);
             })
-            : System.create(labelled({ observer: true, lookup: { list: { index: keylessOf(has, not), changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
+            : System.create(labelled({ readonly: true, lookup: { list: { index: keylessOf(has, not), changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
                 track(lookup.list(), null, fromKeyless);
             });
 
@@ -466,7 +466,7 @@ const createShape = (state: WorldState, byShape: Map<string, QueryShape>, id: st
         for (const entry of scan.entries) entry.gather.start();
         accept = acceptOf(scan.entries);
     };
-    const scanner = System.create(labelled({ observer: true, components: { with: [...reads, ...required.filter(key => !reads.includes(key))], not } }, name, { components: reads }), row => {
+    const scanner = System.create(labelled({ readonly: true, components: { with: [...reads, ...required.filter(key => !reads.includes(key))], not } }, name, { components: reads }), row => {
         if (accept === null) start();
         if (direct === 0) {
             accept?.(row);

package/src/observe/world-state.ts

@@ -116,7 +116,7 @@ const ignore = (): void => {
 };
 
 /** Runs nothing: a run of it resolves while its world lives. */
-const alive = System.create(labelled({ observer: true }, "Observe/alive"), () => {});
+const alive = System.create(labelled({ readonly: true }, "Observe/alive"), () => {});
 
 /**
  * What a rejected run of the factories' own does: nothing for a disposed world, whose first values never come, and for
@@ -232,7 +232,7 @@ export const stateOf = (world: World): WorldState => {
         deliveries: [],
         idle: [],
         rejected: rejectedOf(world),
-        deliver: System.create(labelled({ observer: true }, "Observe/deliver"), () => {
+        deliver: System.create(labelled({ readonly: true }, "Observe/deliver"), () => {
             const delivery = created.deliveries.shift();
             if (delivery === undefined) return;
             created.delivered = delivery.batch;
@@ -243,7 +243,7 @@ export const stateOf = (world: World): WorldState => {
     states.set(world, created);
     if (joined) return created;
     // Added before any shape's system, so in each pass it counts the pass before they run.
-    world.add(System.create(labelled({ observer: true }, "Observe/maintain"), () => {
+    world.add(System.create(labelled({ readonly: true }, "Observe/maintain"), () => {
         created.pass++;
         if (created.idle.length > 0) sweepShapes(created);
     }));

package/src/perftest/benchmarks.ts

@@ -505,7 +505,7 @@ export const benchmarks: readonly Benchmark[] = [
         run: async () => {
             const { world, roots } = await filteredForest();
             const found: { child: Entity | null } = { child: null };
-            await world.run(System.create({ observer: true, components: { with: [hierarchyParent] } }, row => {
+            await world.run(System.create({ readonly: true, components: { with: [hierarchyParent] } }, row => {
                 if (found.child === null && row[hierarchyParent] === roots[0]) found.child = row.entity;
             }));
             const { child } = found;

package/src/perftest/indexes.ts

@@ -307,13 +307,13 @@ const seedFlags = System.create({}, ({ commands }) => {
     for (let i = 0; i < flagged; i++) commands.spawn([flag])({ [flag]: i % 2 === 0 });
 });
 /** A run of observer systems alone, which passes every one added. */
-const pass = System.create({ observer: true }, () => {});
+const pass = System.create({ readonly: true }, () => {});
 /** A count of each bucket, written only when the index's entries changed: by `changed: true`, or by its lists' `changed`. */
 const countsWhenChanged = (filtered: boolean): System => filtered
-    ? System.create({ observer: true, lookup: { byFlag: { index: byFlag, changed: true } } }, ({ lookup }) => {
+    ? System.create({ readonly: true, lookup: { byFlag: { index: byFlag, changed: true } } }, ({ lookup }) => {
         found += lookup.byFlag(false).length + lookup.byFlag(true).length;
     })
-    : System.create({ observer: true, lookup: { byFlag: { index: byFlag } } }, ({ lookup }) => {
+    : System.create({ readonly: true, lookup: { byFlag: { index: byFlag } } }, ({ lookup }) => {
         const off = lookup.byFlag(false);
         const on = lookup.byFlag(true);
         if (!off.changed && !on.changed) return;

package/src/perftest/loop.ts

@@ -12,7 +12,7 @@ export const loopTicks = 10_000;
 export const observerIdles = 100;
 
 /** Observer systems no entity matches, each run after every tick. */
-const idleObserver = Array.from({ length: observerIdles }, (_, i) => System.create({ observer: true, components: { with: [unused] } }, () => {}));
+const idleObserver = Array.from({ length: observerIdles }, (_, i) => System.create({ readonly: true, components: { with: [unused] } }, () => {}));
 
 /**
  * The fastest of `stretches` stretches of `loopTicks` ticks with nothing changed, after one to warm up: a world with

package/src/perftest/observer.ts

@@ -14,14 +14,14 @@ import type { World } from "../interface/world/world.js";
  * first call only starts the stretch that warms up.
  */
 export const eachTick = (world: World, notify: () => void): (() => void) => {
-    const counter = System.create({ observer: true, resources: { changed: [clock] } }, () => { notify(); });
+    const counter = System.create({ readonly: true, resources: { changed: [clock] } }, () => { notify(); });
     world.add(counter);
     return () => world.remove(counter);
 };
 
 /** The clock as an observer run last read it. */
 const read = { tick: 0, now: 0 };
-const readClock = System.create({ observer: true }, ({ resources }) => {
+const readClock = System.create({ readonly: true }, ({ resources }) => {
     read.tick = resources[clock].tick;
     read.now = resources[clock].now;
 });
@@ -36,7 +36,7 @@ export const ticksAfter = async (world: World, count: number): Promise<void> =>
     let { tick, now } = read;
     let seen = 0;
     await new Promise<void>(resolve => {
-        const counter = System.create({ observer: true }, ({ resources }) => {
+        const counter = System.create({ readonly: true }, ({ resources }) => {
             const current = resources[clock];
             if (current.tick === tick && current.now === now) return;
             tick = current.tick;
@@ -52,7 +52,7 @@ export const ticksAfter = async (world: World, count: number): Promise<void> =>
 /** The entities with every component of `has` and none of `not`, in storage order, read by an observer run. */
 export const entitiesWith = async (world: World, has: readonly Component.Key[], not: readonly Component.Key[] = []): Promise<Entity[]> => {
     const found: Entity[] = [];
-    await world.run(System.create({ observer: true, components: { with: [...has], not } }, row => { found.push(row.entity); }));
+    await world.run(System.create({ readonly: true, components: { with: [...has], not } }, row => { found.push(row.entity); }));
     return found;
 };
 

package/src/perftest/reads.ts

@@ -78,7 +78,7 @@ const lookups = async (system: System): Promise<{ readonly best: number; readonl
 /** Every entity a seeded world holds. */
 const entitiesOf = async (world: World): Promise<readonly Entity[]> => {
     const found: Entity[] = [];
-    await world.run(System.create({ observer: true, components: { with: [value] } }, row => { found.push(row.entity); }));
+    await world.run(System.create({ readonly: true, components: { with: [value] } }, row => { found.push(row.entity); }));
     return found;
 };
 
@@ -124,7 +124,7 @@ export const readBenchmarks: readonly Benchmark[] = [
         run: async () => {
             const world = await seeded(10_000);
             copied = 0;
-            const best = await fastest(() => world.run(System.create({ observer: true }, ({ resources }) => { copied = resources[level]; })), 300);
+            const best = await fastest(() => world.run(System.create({ readonly: true }, ({ resources }) => { copied = resources[level]; })), 300);
             check(copied === 3, "read run observer: wrong value");
             await world.dispose();
             return best;

package/src/perftest/remote.ts

@@ -49,7 +49,7 @@ export const reorder = System.create([flip, reverse]);
 export const observerSeen = { last: 0, notified: 0 };
 
 /** On a joined thread, after each sync point that changed it: the observed resource. */
-export const observerCounter = System.create({ observer: true, resources: { changed: [counter] } }, ({ resources }) => {
+export const observerCounter = System.create({ readonly: true, resources: { changed: [counter] } }, ({ resources }) => {
     observerSeen.last = resources[counter];
     observerSeen.notified++;
 });
@@ -61,7 +61,7 @@ const sortedKeys = { keys: new Float64Array(0), entities: new Float64Array(0), p
  * On a joined thread, after each sync point: the entities in `order`, sorted from a scan of the index of every ranked
  * entity into reused arrays.
  */
-export const observerSelect = System.create({ observer: true, lookup: { all: { index: ranked } } }, ({ lookup }) => {
+export const observerSelect = System.create({ readonly: true, lookup: { all: { index: ranked } } }, ({ lookup }) => {
     const list = lookup.all();
     const count = list.length;
     if (sortedKeys.keys.length < count) {
@@ -99,12 +99,12 @@ export const retext = System.create([count, recaption]);
 export const reamounted = System.create([count, reamount]);
 
 /** On a joined thread, after each sync point: every row's caption, out of its record. */
-export const observerCaptions = System.create({ observer: true, components: { with: [caption] } }, row => {
+export const observerCaptions = System.create({ readonly: true, components: { with: [caption] } }, row => {
     observerSeen.last += row[caption].length;
     observerSeen.notified++;
 });
 /** On a joined thread, after each sync point: every row's amount. */
-export const observerAmounts = System.create({ observer: true, components: { with: [amount] } }, row => {
+export const observerAmounts = System.create({ readonly: true, components: { with: [amount] } }, row => {
     observerSeen.last += row[amount];
     observerSeen.notified++;
 });
@@ -129,7 +129,7 @@ const joinedFile = "./joined.js";
 /** The observed resource, read by an observer run. */
 const counterOf = async (world: World): Promise<number> => {
     let value = 0;
-    await world.run(System.create({ observer: true }, ({ resources }) => { value = resources[counter]; }));
+    await world.run(System.create({ readonly: true }, ({ resources }) => { value = resources[counter]; }));
     return value;
 };
 

package/src/perftest/strings.ts

@@ -80,7 +80,7 @@ const read = (system: System, name: string) => measure(system, async world => {
 /** Each row's text, as the last write left it. */
 const written = (name: string) => async (world: World): Promise<void> => {
     let wrong = 0;
-    await world.run(System.create({ observer: true, components: { with: [text, boxed] } }, row => {
+    await world.run(System.create({ readonly: true, components: { with: [text, boxed] } }, row => {
         if (row[text] !== row[boxed].text && row[text] !== labelOf(row.entity, round) && row[boxed].text !== labelOf(row.entity, round)) wrong++;
     }));
     check(wrong === 0, `${name}: wrong text`);

package/src/perftest/suite.ts

@@ -196,7 +196,7 @@ export const idle = System.create({ components: { with: [unused] } }, () => {});
 /** A system that throws, so each run of it rejects. */
 export const failing = System.create({}, () => { throw new Error("suite: failing"); });
 /** An observer system no entity matches: a run of it alone has no tiers. */
-export const idleObserver = System.create({ observer: true, components: { with: [unused] } }, () => {});
+export const idleObserver = System.create({ readonly: true, components: { with: [unused] } }, () => {});
 
 /** Fifty systems no entity matches, in one tier. */
 export const idles = System.create({

package/src/world.test.ts

@@ -23,7 +23,7 @@ describe("World.create", () => {
         await world.run(spawn);
         await world.run(add);
         let seen = 0;
-        await world.run(System.create({ observer: true, components: { with: [count] } }, row => { seen = row[count]; }));
+        await world.run(System.create({ readonly: true, components: { with: [count] } }, row => { seen = row[count]; }));
         expect(seen).toBe(2);
     });
     it("rejects a key that isn't a resource, as worlds the implementation creates do", () => {
@@ -40,7 +40,7 @@ describe("World.join", () => {
         await shared;
         await joined.run(raise);
         let seen = 0;
-        await world.run(System.create({ observer: true }, ({ resources }) => { seen = resources[total]; }));
+        await world.run(System.create({ readonly: true }, ({ resources }) => { seen = resources[total]; }));
         expect(seen).toBe(7);
     });
 });

package/src/world.ts

@@ -0,0 +1,32 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { create as createWorld, join as joinWorld } from './implementation/index.js';
+import type { Create } from './interface/world/create.js';
+import type { Join } from './interface/world/join.js';
+
+export type { Table } from './interface/world/table/table.js';
+
+/**
+ * Creates a world on this thread, synchronously, with resources starting at the given values in place of their
+ * defaults. This thread is its `"world"` thread for the world's life: it runs the sync points, the ticks and the GPU
+ * device, and fills every logical thread no joined thread claims. Keys are the resources' symbols, built-in ones
+ * included (`{ [workers]: 0 }`); string keys are never a resource's, so they're ignored. Throws for a symbol that isn't
+ * a resource, or is one only the world writes. While a declaration's trait or default doesn't hold, each call fails to
+ * compile, once, naming each such key, its members and what's wrong with them.
+ * @function
+ */
+export const create: Create = createWorld;
+
+/**
+ * Joins, from another thread, a world that `share` let join through the other end of `port`, claiming the logical
+ * `threads` this thread fills: their objects live here, and the systems and finalizers reading them run here. Resolves,
+ * once the world accepted the claim, to the same world: its `run` runs systems there, and its `add` and `remove` take
+ * readonly systems, which run here after the world's sync points. Add them before awaiting anything else, so the
+ * world's `share` resolves with them in place. Its `dispose` disconnects this thread. Rejects with an `Error` saying
+ * why it didn't join: the world refused the claim, was disposed, or its thread ended first, as the platform reports it:
+ * the world's `Worker` failing to start or throwing first, a port closed, as in node, or, in a browser, the world's
+ * thread ending once it was shared through a port this thread listened on. A browser world's worker that the page ended
+ * before this thread heard from it isn't reported, so the join stays pending. Rejects too where memory can't be shared,
+ * as without cross-origin isolation.
+ * @function
+ */
+export const join: Join = joinWorld;