@adobe/ecs 0.1.0 → 0.2.1

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

@@ -0,0 +1,348 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Entity, Finalizer, Index, Rule, System, workers } from "../../index.js";
+import type { F32, Vec2 } from "../../interface/math/index.js";
+import { registerComponent } from "../../interface/registry/declarations.js";
+import type { Commands } from "../../interface/system/commands.js";
+import { createWorld, join } from "./create.js";
+import { runReported } from "./outcomes.test-helper.js";
+
+const team = Symbol("sharedTest/team");
+const cell = Symbol("sharedTest/cell");
+const weight = Symbol("sharedTest/weight");
+const style = Symbol("sharedTest/style");
+const health = Symbol("sharedTest/health");
+const armed = Symbol("sharedTest/armed");
+const banner = Symbol("sharedTest/banner");
+const marker = Symbol("sharedTest/marker");
+const place = Symbol("sharedTest/place");
+declare module "@adobe/ecs" {
+    interface Threads {
+        sharedTest: true;
+    }
+    interface Components {
+        [team]: { type: "red" | "blue"; shared: true };
+        [cell]: { type: Vec2.I32; shared: true };
+        [weight]: { type: F32; shared: true };
+        [style]: { type: { readonly color: string; readonly sizes: readonly number[] }; shared: true };
+        [health]: { type: number };
+        [armed]: { type: true; derived: true };
+        [banner]: { type: { readonly text: string } | null; thread: "sharedTest" };
+        [marker]: { type: number };
+        [place]: { type: readonly [number, number] };
+    }
+}
+
+export const arming = Rule.create({ components: { with: [team, health] }, derive: [armed] });
+
+const inline = () => createWorld({ [workers]: 0 });
+
+// Systems a joined thread runs, which it names by the ids the build gives them at the top level.
+const heard: string[] = [];
+export const listen = System.create({ observer: true, components: { with: [team, health] } }, row => { heard.push(`${row[team]} ${row[health]}`); });
+export const spawnBanners = System.create(({ commands }) => {
+    commands.spawn([team, health, banner], { [team]: "red" })({ [health]: 1 });
+    commands.spawn([team, health, banner], { [team]: "blue" })({ [health]: 2 });
+});
+// Placed there by writing its objects.
+export const writeBanners = System.create({ components: { with: [team, health, banner] } }, row => {
+    row[banner] = { text: `${row[team]} ${row[health]}` };
+});
+const banners: string[] = [];
+// A finalizer reading the joined thread's objects runs there, reading each stop's shared value as of before it applied.
+const finalized: string[] = [];
+export const finalizeBanners = Finalizer.create({ components: { with: [team, health, banner] } }, row => { finalized.push(`${row[team]} ${row[health]} ${row[banner]?.text ?? "none"}`); });
+export const despawnBanners = System.create({ components: { with: [banner] } }, (row, { commands }) => { commands.despawn(row.entity); });
+// On the joined thread: two lists spawned with one constants object, each spawner its own list's.
+const base = { [health]: 7 } as const;
+export const spawnThere = System.create({ components: { with: [banner] } }, (row, { commands }) => {
+    if (row[banner] === null) return;
+    commands.spawn([health, marker], base)({ [marker]: 1 });
+    commands.spawn([health], base)({});
+});
+export const readBanners = System.create({ observer: true, components: { with: [banner] } }, row => { banners.push(row[banner]?.text ?? "none"); });
+
+/** Every entity's team and health, and whether it's armed, sorted by health. */
+const rowsOf = async (world: ReturnType<typeof inline>): Promise<readonly string[]> => {
+    const read = System.create({ observer: true, components: { with: [team, health], optional: [armed] } }, (row) => {
+        found.push(`${row[team]} ${row[health]}${row[armed] === true ? " armed" : ""}`);
+    });
+    const found: string[] = [];
+    await world.run(read);
+    return found.sort((a, b) => Number(a.split(" ")[1]) - Number(b.split(" ")[1]));
+};
+
+describe("a shared component", () => {
+    it("is registered only on comparable data, never with a thread, as derived or as a reference", () => {
+        expect(() => registerComponent(Symbol("sharedTest/map"), { type: { type: "map", keys: { type: "string" }, values: { type: "number" } }, shared: true }))
+            .toThrow("a shared component's value is comparable data: numbers, booleans, strings, and arrays and objects of those");
+        expect(() => registerComponent(Symbol("sharedTest/nullable"), { type: { anyOf: [{ type: "number" }, { type: "null" }] }, shared: true }))
+            .toThrow("a shared component's value is comparable data");
+        expect(() => registerComponent(Symbol("sharedTest/opaque"), { shared: true })).toThrow("a shared component's value is comparable data");
+        expect(() => registerComponent(Symbol("sharedTest/placed"), { type: { type: "array", items: { type: "string" } }, shared: true, thread: "main" }))
+            .toThrow("a shared value lives in shared memory, so it has no thread");
+        expect(() => registerComponent(Symbol("sharedTest/derived"), { type: { type: "number" }, default: 0, derived: true, shared: true }))
+            .toThrow("a derived component isn't shared: its rule adds it with its default");
+        expect(() => registerComponent(Symbol("sharedTest/reference"), { type: Entity.schema, reference: "owner", shared: true }))
+            .toThrow("a reference isn't shared");
+        expect(() => registerComponent(Symbol("sharedTest/flag"), { type: { type: "number" }, shared: false })).toThrow("shared is true");
+        expect(() => registerComponent(Symbol("sharedTest/tags"), { type: { type: "array", items: { type: "string" } }, shared: true })).not.toThrow();
+    });
+
+    it("keeps no index key part: where filters by it", () => {
+        // Typed, a shared key part is an error already.
+        expect(() => Reflect.apply(Index.create, undefined, [{ key: [weight] }])).toThrow(`has key part "sharedTest/weight", a shared component: filter by it with where`);
+    });
+
+    it("chooses the archetype by its value, interned by structure, each value read as stored", async () => {
+        await using world = inline();
+        const spawned = new Map<string, Entity>();
+        await world.run(System.create(({ commands }) => { commands.spawn([health])({ [health]: 0 }); }));
+        const before = (await world.tables()).archetypes;
+        await world.run(System.create(({ commands }) => {
+            spawned.set("a", commands.spawn([cell, health], { [cell]: [1, 2] })({ [health]: 1 }));
+            spawned.set("b", commands.spawn([cell, health], { [cell]: [1, 2] })({ [health]: 2 }));
+            spawned.set("c", commands.spawn([cell, health], { [cell]: [2, 1] })({ [health]: 3 }));
+            // Leaves compare as stored: f32, -0 as 0.
+            commands.spawn([weight, health], { [weight]: 0.1 })({ [health]: 4 });
+            commands.spawn([weight, health], { [weight]: Math.fround(0.1) })({ [health]: 5 });
+            commands.spawn([weight, health], { [weight]: -0 })({ [health]: 6 });
+            commands.spawn([weight, health], { [weight]: 0 })({ [health]: 7 });
+            commands.spawn([weight, health], { [weight]: NaN })({ [health]: 8 });
+            commands.spawn([weight, health], { [weight]: NaN })({ [health]: 9 });
+            commands.spawn([style, health], { [style]: { sizes: [1, 2], color: "red" } })({ [health]: 10 });
+            commands.spawn([style, health], { [style]: { color: "red", sizes: [1, 2] } })({ [health]: 11 });
+        }));
+        // Three cells' worth of [1, 2] and [2, 1], three weights and one style.
+        expect((await world.tables()).archetypes - before).toBe(2 + 3 + 1);
+        const read: string[] = [];
+        await world.run(System.create({ observer: true, components: { with: [health], optional: [cell, weight, style] } }, row => {
+            if (row[health] === 0) return;
+            read.push(`${row[health]}: ${JSON.stringify(row[cell] ?? row[style] ?? null)} ${String(row[weight])}`);
+        }));
+        expect(read.sort((a, b) => Number.parseInt(a) - Number.parseInt(b))).toEqual([
+            "1: [1,2] undefined", "2: [1,2] undefined", "3: [2,1] undefined",
+            `4: null ${Math.fround(0.1)}`, `5: null ${Math.fround(0.1)}`, "6: null 0", "7: null 0", "8: null NaN", "9: null NaN",
+            `10: {"color":"red","sizes":[1,2]} undefined`, `11: {"color":"red","sizes":[1,2]} undefined`,
+        ]);
+    });
+
+    it("gives the same spawner for a world, list and constants, and a constant non-shared value to every entity spawned", async () => {
+        await using world = inline();
+        const spawners: unknown[] = [];
+        const Unit = [team, health] as const;
+        await world.run(System.create(({ commands }) => {
+            spawners.push(commands.spawn(Unit, { [team]: "red" }), commands.spawn(Unit, { [team]: "red" }), commands.spawn(Unit, { [team]: "blue" }));
+            spawners.push(commands.spawn(Unit, { [team]: "red", [health]: 5 }), commands.spawn(Unit, { [team]: "red", [health]: 5 }), commands.spawn(Unit, { [team]: "red", [health]: 6 }));
+            commands.spawn(Unit, { [team]: "blue", [health]: 7 })({});
+            commands.spawn(Unit, { [team]: "blue", [health]: 7 })({});
+        }));
+        expect(spawners[0]).toBe(spawners[1]);
+        expect(spawners[0]).not.toBe(spawners[2]);
+        expect(spawners[3]).toBe(spawners[4]);
+        expect(spawners[3]).not.toBe(spawners[5]);
+        expect(await rowsOf(world)).toEqual(["blue 7 armed", "blue 7 armed"]);
+    });
+
+    it("keeps -0 and 0 apart in constants not shared, whole or in a tuple", async () => {
+        await using world = inline();
+        const spawned: string[] = [];
+        await world.run(System.create(({ commands }) => {
+            commands.spawn([team, health], { [team]: "red", [health]: 0 })({});
+            commands.spawn([team, health], { [team]: "red", [health]: -0 })({});
+            commands.spawn([team, place], { [team]: "red", [place]: [0, 1] })({});
+            commands.spawn([team, place], { [team]: "red", [place]: [-0, 1] })({});
+        }));
+        await world.run(System.create({ components: { with: [team, health] } }, row => { spawned.push(`health ${Object.is(row[health], -0) ? "-0" : row[health]}`); }));
+        await world.run(System.create({ components: { with: [team, place] } }, row => { spawned.push(`place ${Object.is(row[place][0], -0) ? "-0" : row[place][0]}`); }));
+        expect(spawned).toEqual(["health 0", "health -0", "place 0", "place -0"]);
+    });
+
+    it("fails a spawn without its value, or with one not of its type, at the spawner", async () => {
+        await using world = inline();
+        const untyped = (commands: Commands, ...parameters: unknown[]): unknown => Reflect.apply(commands.spawn, commands, parameters);
+        expect((await runReported(world, System.create(({ commands }) => { untyped(commands, [team, health]); }))).failures.map(failure => failure.message)).toEqual([
+            expect.stringContaining(`A spawn of "sharedTest/team", a shared component, takes its value first: commands.spawn(components, { [key]: value })`),
+        ]);
+        expect((await runReported(world, System.create(({ commands }) => { untyped(commands, [team, health], { [team]: { name: "green" } }); }))).failures.map(failure => failure.message)).toEqual([
+            expect.stringContaining(`"sharedTest/team" isn't given one of its type's values`),
+        ]);
+    });
+
+    it("fails a spawn giving a component its constants gave, shared or not, spawning nothing", async () => {
+        await using world = inline();
+        const untyped = (spawner: unknown, values: object): unknown => Reflect.apply(Function.prototype.call, spawner, [undefined, values]);
+        for (const values of [{ [team]: "blue", [health]: 1 }, { [health]: 1 }]) {
+            const report = await runReported(world, System.create(({ commands }) => {
+                const spawner = commands.spawn([team, health, place], { [team]: "red", [place]: [0, 0] });
+                untyped(spawner, { ...values, [place]: [1, 1] });
+            }));
+            expect(report.failures.map(failure => failure.message)).toEqual([expect.stringMatching(/A spawn gives "sharedTest\/(team|place)" in both its calls: each component's value comes from one/)]);
+        }
+        expect(await rowsOf(world)).toEqual([]);
+    });
+
+    it("reads as its archetype's value in rows, lookups and finalizers, and fails a body assigning it", async () => {
+        await using world = inline();
+        let red = Entity.none;
+        await world.run(System.create(({ commands }) => {
+            red = commands.spawn([team, health], { [team]: "red" })({ [health]: 1 });
+            commands.spawn([team, health], { [team]: "blue" })({ [health]: 2 });
+        }));
+        const looked: string[] = [];
+        await world.run(System.create({ components: { with: [health] }, lookup: { other: { with: [team] } } }, (row, { lookup }) => {
+            looked.push(`${row[health]} sees ${lookup.other(red)?.[team] ?? "none"}`);
+        }));
+        expect(looked.sort()).toEqual(["1 sees red", "2 sees red"]);
+        const assign: (row: object) => void = row => { Reflect.set(row, team, "blue"); };
+        const assigning = System.create({ kernel: false, components: { with: [team, health] } }, row => {
+            if (row[health] === 1) assign(row);
+        });
+        // The build takes the row as written whole, since it can't follow it: every member but shared ones and references.
+        expect((await runReported(world, assigning)).failures.map(failure => failure.message)).toEqual([
+            expect.stringContaining(`"sharedTest/team" is shared: its value is its archetype's, so give it another with commands.add rather than assigning it`),
+        ]);
+        expect(() => System.create({ components: { with: [team, health] } }, row => {
+            // @ts-expect-error a shared component's value is its archetype's
+            row[team] = "blue";
+        })).toThrow(`writes "sharedTest/team", a shared component, whose value is its archetype's: give it another with commands.add`);
+    });
+
+    it("moves its entity on commands.add of another value, marking it changed but not added, and leaves on remove", async () => {
+        await using world = inline();
+        let entity = Entity.none;
+        await world.run(System.create(({ commands }) => {
+            entity = commands.spawn([team, health], { [team]: "red" })({ [health]: 1 });
+            commands.spawn([team, health], { [team]: "red" })({ [health]: 2 });
+        }));
+        const changes: string[] = [];
+        const watch = System.create({ observer: true, components: { with: [health], changed: [team] } }, row => { changes.push(`changed ${row[health]}`); });
+        const adds = System.create({ observer: true, components: { with: [health], added: [team] } }, row => { changes.push(`added ${row[health]}`); });
+        world.add(watch);
+        world.add(adds);
+        await world.run(System.create(() => {}));
+        changes.length = 0;
+        await world.run(System.create(({ commands }) => { commands.add(entity, team, "blue"); }));
+        expect(changes.sort()).toEqual(["changed 1"]);
+        expect(await rowsOf(world)).toEqual(["blue 1 armed", "red 2 armed"]);
+        changes.length = 0;
+        // The same value again stays, and is changed as any add is.
+        await world.run(System.create(({ commands }) => { commands.add(entity, team, "blue"); }));
+        expect(changes).toEqual(["changed 1"]);
+        await world.run(System.create(({ commands }) => { commands.remove(entity, team); }));
+        expect(await rowsOf(world)).toEqual(["red 2 armed"]);
+        changes.length = 0;
+        await world.run(System.create(({ commands }) => { commands.add(entity, [team, health], { [team]: "red", [health]: 3 }); }));
+        expect(changes.sort()).toEqual(["added 3", "changed 3"]);
+        expect(await rowsOf(world)).toEqual(["red 2 armed", "red 3 armed"]);
+    });
+
+    it("gives a change's previous and next values, its archetypes told apart by value", async () => {
+        await using world = inline();
+        const seen: string[] = [];
+        const changes = Finalizer.changes({ watch: [team, health] }, (changed) => {
+            for (const change of changed.groups) {
+                for (const entity of change.entities) {
+                    if (change.replaced.includes(team)) seen.push(`${String(changed.previous(entity, team))} to ${String(changed.next(entity, team))}`);
+                }
+            }
+        });
+        const stops: string[] = [];
+        const stopped = Finalizer.create({ components: { with: [team, health] } }, row => { stops.push(`${row[team]} ${row[health]}`); });
+        let entity = Entity.none;
+        await world.run(System.create(({ commands }) => { entity = commands.spawn([team, health], { [team]: "red" })({ [health]: 1 }); }));
+        await world.run(System.create(({ commands }) => { commands.add(entity, team, "blue"); }));
+        expect(seen).toEqual(["red to blue"]);
+        await world.run(System.create(({ commands }) => { commands.despawn(entity); }));
+        // A change of value moves the entity, and stops nothing: it holds every component it did.
+        expect(stops).toEqual(["blue 1"]);
+        void changes;
+        void stopped;
+    });
+
+    it("is read on a joined thread, by the systems placed there and the observer systems added there", async () => {
+        const channel = new MessageChannel();
+        await using world = createWorld({ [workers]: 0 });
+        const [joined] = await Promise.all([
+            join(channel.port2, { threads: ["sharedTest"] }).then(thread => {
+                thread.add(listen);
+                return thread;
+            }),
+            world.share(channel.port1),
+        ]);
+        await using thread = joined;
+        heard.length = 0;
+        banners.length = 0;
+        await world.run(spawnBanners);
+        await world.run(writeBanners);
+        await thread.run(readBanners);
+        expect(banners.sort()).toEqual(["blue 2", "red 1"]);
+        const end = performance.now() + 2000;
+        while (heard.length < 2 && performance.now() < end) await new Promise(resolve => setTimeout(resolve, 1));
+        expect(heard.sort().slice(0, 2)).toEqual(["blue 2", "red 1"]);
+        await world.run(despawnBanners);
+        const finalizing = performance.now() + 2000;
+        while (finalized.length < 2 && performance.now() < finalizing) await new Promise(resolve => setTimeout(resolve, 1));
+        expect(finalized.sort()).toEqual(["blue 2 blue 2", "red 1 red 1"]);
+    });
+
+    it("runs a body a kernel would read it in as written, reading its archetype's value", async () => {
+        await using world = inline();
+        await world.run(System.create(({ commands }) => {
+            commands.spawn([weight, health], { [weight]: 2 })({ [health]: 1 });
+            commands.spawn([weight, health], { [weight]: 3 })({ [health]: 1 });
+        }));
+        await world.run(System.create({ components: { with: [weight, health] } }, row => { row[health] *= row[weight]; }));
+        const read: number[] = [];
+        await world.run(System.create({ observer: true, components: { with: [health] } }, row => { read.push(row[health]); }));
+        expect(read.sort()).toEqual([2, 3]);
+    });
+
+    it("fails a system adding a value not of its type, queuing nothing of that add, and leaves the run's other commands", async () => {
+        await using world = inline();
+        let entity = Entity.none;
+        await world.run(System.create(({ commands }) => { entity = commands.spawn([team, health], { [team]: "red" })({ [health]: 1 }); }));
+        const untyped = (commands: Commands, ...parameters: unknown[]): unknown => Reflect.apply(commands.add, commands, parameters);
+        const others = System.create(({ commands }) => { commands.spawn([team, health], { [team]: "blue" })({ [health]: 2 }); });
+        const wrong = System.create(({ commands }) => {
+            commands.add(entity, health, 5);
+            untyped(commands, entity, team, "green");
+        });
+        const wrongList = System.create(({ commands }) => { untyped(commands, entity, [team, health], { [team]: { name: "green" }, [health]: 9 }); });
+        const report = await runReported(world, System.create([others, wrong, wrongList]));
+        expect(report.failures.map(failure => [failure.name, failure.message])).toEqual([
+            ["wrong", `"sharedTest/team", a shared component, isn't given one of its type's values: green.`],
+            ["wrongList", expect.stringContaining(`"sharedTest/team", a shared component, isn't given one of its type's values`)],
+        ]);
+        expect(await rowsOf(world)).toEqual(["blue 2 armed", "red 5 armed"]);
+    });
+
+    it("checks a tuple's every leaf against its type, whatever was interned before", async () => {
+        for (const order of [[[1, 2], [1.5, 2], [2 ** 32 + 7, 7], [7, 7]], [[1.5, 2], [2 ** 32 + 7, 7], [1, 2], [7, 7]]]) {
+            await using world = inline();
+            const untyped = (commands: Commands, ...parameters: unknown[]): unknown => Reflect.apply(commands.spawn, commands, parameters);
+            const outcomes: string[] = [];
+            for (const at of order) {
+                const report = await runReported(world, System.create(({ commands }) => { untyped(commands, [cell, health], { [cell]: at }); }));
+                outcomes.push(`${JSON.stringify(at)} ${report.failures.length === 0 ? "ok" : "refused"}`);
+            }
+            expect(outcomes.sort()).toEqual(["[1,2] ok", "[1.5,2] refused", "[4294967303,7] refused", "[7,7] ok"]);
+        }
+    });
+    it("gives a joined thread's spawners with constants by their list and constants", async () => {
+        const channel = new MessageChannel();
+        await using world = createWorld({ [workers]: 0 });
+        const [joined] = await Promise.all([join(channel.port2, { threads: ["sharedTest"] }), world.share(channel.port1)]);
+        await using thread = joined;
+        await world.run(spawnBanners);
+        await world.run(writeBanners);
+        await world.run(spawnThere);
+        const found: string[] = [];
+        await world.run(System.create({ observer: true, components: { with: [health], optional: [marker, team] } }, row => {
+            if (row[team] === undefined) found.push(`${row[health]} ${row[marker] ?? "none"}`);
+        }));
+        expect(found.sort()).toEqual(["7 1", "7 1", "7 none", "7 none"]);
+        void thread;
+    });
+});
+

package/src/implementation/world/shared.ts

@@ -0,0 +1,316 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from '../../interface/schema/schema.js';
+import { matchesSchema } from '../../interface/registry/schemas.js';
+import { layoutOf, type Scalar } from '../../interface/registry/layout.js';
+
+// A shared component's values, which choose archetypes: each world interns them per component by structure, so equal
+// values, compared leaf by leaf as index keys are, are one number, and an archetype holds the number of each.
+
+/**
+ * One shared component's values in a world: each distinct one once, as stored, by number. Numbers are kept at the
+ * precision its schema stores them at, -0 as 0, so a row reads what a column would hold.
+ */
+export type SharedValues = {
+    readonly schema: Schema | undefined;
+    /** By number, the value as rows read it. */
+    readonly values: unknown[];
+    /** By number, its canonical text, which equal values share and the layout directory carries to joined threads. */
+    readonly texts: string[];
+    readonly byText: Map<string, number>;
+    /** Primitives given before and the stored values, by identity, so finding them again builds no text. */
+    readonly byValue: Map<unknown, number>;
+    /**
+     * For a tuple of numbers, each leaf's scalar, and the values found so far by their leaves as stored, a level a leaf:
+     * a tuple given again, as a cell is, is found without building its text.
+     */
+    readonly lanes: readonly Scalar[] | null;
+    readonly byLanes: Map<number, unknown>;
+    /**
+     * By number, what holds it: the archetypes holding it and its pins, a `where`'s value each. One no longer held is
+     * dropped (`releaseShared`), its number reused.
+     */
+    readonly refs: number[];
+    /** Numbers dropped, reused before new ones. */
+    readonly free: number[];
+    /** Numbers interned since the last sweep, dropped then if nothing holds them (`sweepShared`). */
+    readonly fresh: number[];
+    /** By number, its keys in `byValue` besides the stored value: primitives given that are stored as it. */
+    readonly keys: unknown[][];
+    /** By number, what caches it, each let go of as it's dropped: spawners and their batches. */
+    readonly cached: (Set<() => void> | undefined)[];
+};
+
+/** The scalars of a schema's leaves when it's a tuple of numbers, each its own leaf; null for any other. */
+const lanesOf = (schema: Schema | undefined): readonly Scalar[] | null => {
+    if (schema === undefined) return null;
+    let layout;
+    try {
+        layout = layoutOf(schema);
+    }
+    catch {
+        return null;
+    }
+    if (layout.kind !== "linear" || !("type" in schema) || schema.type !== "array") return null;
+    const { leaves } = layout;
+    // Only leaves whose every value a lane holds exactly is of their type: a number without a range, or a 32-bit integer.
+    const exact = (item: Schema, scalar: Scalar): boolean => "type" in item && (
+        (item.type === "number" && item.minimum === undefined && item.maximum === undefined && scalar !== "boolean")
+        || (item.type === "integer" && !("format" in item) && ((scalar === "i32" && item.minimum === -0x80000000 && item.maximum === 0x7FFFFFFF) || (scalar === "u32" && item.minimum === 0 && item.maximum === 0xFFFFFFFF))));
+    return leaves.every((leaf, k) => leaf.path.length === 1 && leaf.path[0] === k && exact(schema.items, leaf.scalar)) ? leaves.map(leaf => leaf.scalar) : null;
+};
+
+export const createSharedValues = (schema: Schema | undefined): SharedValues =>
+    ({ schema, values: [], texts: [], byText: new Map(), byValue: new Map(), lanes: lanesOf(schema), byLanes: new Map(), refs: [], free: [], fresh: [], keys: [], cached: [] });
+
+/** A leaf as a column of `scalar` would hold it, -0 as 0. */
+const storedLane = (scalar: Scalar, value: number): number => {
+    const stored = scalar === "f32" ? Math.fround(value) : scalar === "u32" ? value >>> 0 : scalar === "i32" ? value | 0 : value;
+    return Object.is(stored, -0) ? 0 : stored;
+};
+
+/** A tuple of numbers' number, found by its leaves as stored; -1 for a value of another shape, which `internShared` reads whole. */
+const internLanes = (shared: SharedValues, lanes: readonly Scalar[], given: unknown): number => {
+    if (!Array.isArray(given) || given.length !== lanes.length) return -1;
+    let level: Map<number, unknown> = shared.byLanes;
+    for (let k = 0; k < lanes.length; k++) {
+        const item: unknown = given[k];
+        if (typeof item !== "number") return -1;
+        const lane = storedLane(lanes[k], item);
+        // An integer leaf its type can't hold, a fraction or out of range, is checked whole, and refused.
+        if (lane !== item && lanes[k] !== "f32" && lanes[k] !== "f64") return -1;
+        const next = level.get(lane);
+        if (k === lanes.length - 1) {
+            if (typeof next === "number") return next;
+            const number = internWhole(shared, given);
+            if (number >= 0) level.set(lane, number);
+            return number;
+        }
+        if (next instanceof Map) level = next;
+        else {
+            const made = new Map<number, unknown>();
+            level.set(lane, made);
+            level = made;
+        }
+    }
+    return -1;
+};
+
+/** A number as its schema stores it: f32 or a 32-bit integer where the schema says, -0 as 0. */
+const storedNumber = (schema: Schema | undefined, value: number): number => {
+    let stored = value;
+    if (schema !== undefined && "type" in schema) {
+        if (schema.type === "number" && schema.precision === 1) stored = Math.fround(value);
+        else if (schema.type === "integer" && !("format" in schema) && schema.minimum !== undefined && schema.maximum !== undefined) {
+            if (schema.minimum >= 0 && schema.maximum <= 0xFFFFFFFF) stored = value >>> 0;
+            else if (schema.minimum >= -0x80000000 && schema.maximum <= 0x7FFFFFFF) stored = value | 0;
+        }
+    }
+    return Object.is(stored, -0) ? 0 : stored;
+};
+
+/** The member of a union a value is one of, which says how it's stored. */
+const memberOf = (schema: Schema | undefined, value: unknown): Schema | undefined => {
+    if (schema === undefined || !("anyOf" in schema)) return schema;
+    return schema.anyOf.find(member => matchesSchema(member, value)) ?? undefined;
+};
+
+/** A comparable value as stored, with its canonical text; null for a value that isn't comparable data. */
+const canonical = (schema: Schema | undefined, given: unknown, exact = false): { readonly value: unknown; readonly text: string } | null => {
+    const member = memberOf(schema, given);
+    if (typeof given === "number") {
+        if (exact && Object.is(given, -0)) return { value: given, text: "#-0" };
+        const value = storedNumber(member, given);
+        return { value, text: `#${String(value)}` };
+    }
+    if (typeof given === "string") return { value: given, text: JSON.stringify(given) };
+    if (typeof given === "boolean") return { value: given, text: given ? "t" : "f" };
+    if (Array.isArray(given)) {
+        const items = member !== undefined && "type" in member && member.type === "array" ? member.items : undefined;
+        const value: unknown[] = [];
+        const texts: string[] = [];
+        for (const item of given) {
+            const found = canonical(items, item, exact);
+            if (found === null) return null;
+            value.push(found.value);
+            texts.push(found.text);
+        }
+        return { value, text: `[${texts.join(",")}]` };
+    }
+    if (typeof given !== "object" || given === null) return null;
+    const prototype: unknown = Object.getPrototypeOf(given);
+    if (prototype !== Object.prototype && prototype !== null) return null;
+    const properties = member !== undefined && "type" in member && member.type === "object" ? member.properties : undefined;
+    const value: { [field: string]: unknown } = {};
+    const fields: string[] = [];
+    for (const field of Object.keys(given).sort()) {
+        const item: unknown = Reflect.get(given, field);
+        if (item === undefined) continue;
+        const found = canonical(properties?.[field], item, exact);
+        if (found === null) return null;
+        value[field] = found.value;
+        fields.push(`${JSON.stringify(field)}:${found.text}`);
+    }
+    return { value, text: `{${fields.join(",")}}` };
+};
+
+/**
+ * The number of a value among a shared component's, interned the first time an equal one is given; -1 for one that
+ * isn't one of its type's values.
+ */
+export const internShared = (shared: SharedValues, given: unknown): number => {
+    const known = shared.byValue.get(given);
+    if (known !== undefined) return known;
+    if (shared.lanes !== null) {
+        const found = internLanes(shared, shared.lanes, given);
+        if (found >= 0) return found;
+    }
+    return internWhole(shared, given);
+};
+
+/** As `internShared`, by the value's canonical text. */
+const internWhole = (shared: SharedValues, given: unknown): number => {
+    if (shared.schema !== undefined && !matchesSchema(shared.schema, given)) return -1;
+    const found = canonical(shared.schema, given);
+    if (found === null) return -1;
+    let number = shared.byText.get(found.text);
+    if (number === undefined) {
+        number = shared.free.pop() ?? shared.values.length;
+        shared.values[number] = found.value;
+        shared.texts[number] = found.text;
+        shared.refs[number] = 0;
+        shared.keys[number] = [];
+        shared.byText.set(found.text, number);
+        shared.byValue.set(found.value, number);
+        shared.fresh.push(number);
+    }
+    // Primitives are their own identity; objects given are found again by their text, so none is held.
+    if ((typeof given !== "object" || given === null) && !Object.is(given, found.value) && !shared.byValue.has(given)) {
+        shared.byValue.set(given, number);
+        shared.keys[number].push(given);
+    }
+    return number;
+};
+
+/** One more holder of value `number`: an archetype holding it, or a pin. */
+export const holdShared = (shared: SharedValues, number: number): void => {
+    shared.refs[number]++;
+};
+
+/** One fewer holder of value `number`, which is dropped once none is left. */
+export const releaseShared = (shared: SharedValues, number: number): void => {
+    if (--shared.refs[number] === 0) dropShared(shared, number);
+};
+
+/** Registers what to let go of once value `number` is dropped; returns a function unregistering it. */
+export const cacheShared = (shared: SharedValues, number: number, letGo: () => void): (() => void) => {
+    const held = shared.cached[number] ??= new Set();
+    held.add(letGo);
+    return () => { held.delete(letGo); };
+};
+
+/** Drops the values interned since the last sweep that nothing holds: given once, as a spawner's constant never spawned. */
+export const sweepShared = (shared: SharedValues): void => {
+    const { fresh } = shared;
+    for (let k = 0; k < fresh.length; k++) {
+        const number = fresh[k];
+        if (shared.refs[number] === 0 && shared.texts[number] !== undefined) dropShared(shared, number);
+    }
+    fresh.length = 0;
+};
+
+/** Forgets value `number`: every way it's found, and what caches it, its number then reused. */
+const dropShared = (shared: SharedValues, number: number): void => {
+    const text = shared.texts[number];
+    const value = shared.values[number];
+    if (text === undefined) return;
+    shared.byText.delete(text);
+    if (shared.byValue.get(value) === number) shared.byValue.delete(value);
+    for (const key of shared.keys[number]) if (shared.byValue.get(key) === number) shared.byValue.delete(key);
+    if (shared.lanes !== null && Array.isArray(value)) forgetLanes(shared.byLanes, shared.lanes, value, number);
+    const cached = shared.cached[number];
+    shared.cached[number] = undefined;
+    if (cached !== undefined) for (const letGo of cached) letGo();
+    shared.values[number] = undefined;
+    // Undefined while dropped, so a sweep or a drop finds it gone.
+    Reflect.deleteProperty(shared.texts, number);
+    shared.keys[number] = [];
+    shared.free.push(number);
+};
+
+/** Removes a tuple's leaves from the levels that find it, and each level it left empty. */
+const forgetLanes = (byLanes: Map<number, unknown>, lanes: readonly Scalar[], value: readonly unknown[], number: number): void => {
+    const path: Map<number, unknown>[] = [];
+    let level: Map<number, unknown> = byLanes;
+    for (let k = 0; k < lanes.length; k++) {
+        const item = value[k];
+        if (typeof item !== "number") return;
+        path.push(level);
+        const next = level.get(item);
+        if (k === lanes.length - 1) {
+            if (next === number) level.delete(item);
+            break;
+        }
+        if (!(next instanceof Map)) return;
+        level = next;
+    }
+    for (let k = path.length - 1; k > 0; k--) {
+        if (path[k].size > 0) break;
+        const item = value[k - 1];
+        if (typeof item === "number") path[k - 1].delete(item);
+    }
+};
+
+/** A value from its canonical text, as a joined thread reads it from the layout directory. */
+export const parseShared = (text: string): unknown => {
+    let at = 0;
+    const value = (): unknown => {
+        const first = text[at];
+        if (first === "#") {
+            const start = ++at;
+            while (at < text.length && text[at] !== "," && text[at] !== "]" && text[at] !== "}") at++;
+            return Number(text.slice(start, at));
+        }
+        if (first === "t" || first === "f") {
+            at++;
+            return first === "t";
+        }
+        if (first === "\"") return string();
+        if (first === "[") {
+            at++;
+            const items: unknown[] = [];
+            while (text[at] !== "]") {
+                items.push(value());
+                if (text[at] === ",") at++;
+            }
+            at++;
+            return items;
+        }
+        if (first === "{") {
+            at++;
+            const fields: { [field: string]: unknown } = {};
+            while (text[at] !== "}") {
+                const field = string();
+                at++;
+                fields[field] = value();
+                if (text[at] === ",") at++;
+            }
+            at++;
+            return fields;
+        }
+        throw new Error(`A shared value's text is malformed at ${at}: ${text}`);
+    };
+    const string = (): string => {
+        const start = at++;
+        while (text[at] !== "\"") at += text[at] === "\\" ? 2 : 1;
+        at++;
+        const parsed: unknown = JSON.parse(text.slice(start, at));
+        return typeof parsed === "string" ? parsed : "";
+    };
+    return value();
+};
+
+/** The canonical text of comparable data as given, compared without a schema; null for any other value. */
+export const textOf = (value: unknown): string | null => canonical(undefined, value)?.text ?? null;
+
+/** As `textOf`, telling -0 from 0, as a constant not shared is copied into each spawn as given. */
+export const exactTextOf = (value: unknown): string | null => canonical(undefined, value, true)?.text ?? null;