@adobe/ecs 0.0.0-stage → 0.1.0

package/src/interface/registry/indexes.ts

@@ -0,0 +1,73 @@
+import type { Created } from '../indexes/created.js';
+import { labelOfItem, recordItem, registeredAs } from './items.js';
+import { firstKeyOf, labelOf, sameDeclaration } from './names.js';
+
+/**
+ * Records an index under the id the plugin gave its declaration and returns it; declared again under that id the same,
+ * as a module evaluated again declares it, it's the index already recorded. Throws for that id with another kind or
+ * declaration.
+ */
+export const addIndex = (index: Created, id: string | undefined): Created => {
+    const existing = registeredAs(index, id, sameDeclaration);
+    const found = existing === undefined ? undefined : indexDefinitionOf(existing);
+    if (found !== undefined) return found;
+    recordItem(index, id, undefined);
+    return index;
+};
+
+/** Only `Index.create` makes values of kind `"index"` with a declaration. */
+const isIndex = (value: object): value is Created =>
+    "kind" in value && value.kind === "index" && "declaration" in value && typeof value.declaration === "object" && value.declaration !== null;
+
+/** What `Index.create` recorded for a value, or undefined for any other value. */
+export const indexDefinitionOf = (value: unknown): Created | undefined => typeof value === "object" && value !== null && isIndex(value) ? value : undefined;
+
+type Key = symbol;
+
+/** A lookup as a declaration holds it: by entity, or through an index. */
+type AnyLookup = { readonly index?: unknown; readonly read?: readonly Key[]; readonly has?: readonly Key[]; readonly changed?: readonly Key[] | true };
+
+const noKeys: readonly never[] = [];
+
+/** The components whose changes a lookup's rows or lists report: none for an index lookup's `changed: true`. */
+export const watchedBy = <K extends PropertyKey>(lookup: { readonly changed?: readonly K[] | true }): readonly K[] => lookup.changed === true ? noKeys : lookup.changed ?? noKeys;
+
+/** Whether a lookup's `changed` is true: its index's entries changing is a change filter of its system. */
+export const watchesEntries = (lookup: AnyLookup): boolean => lookup.changed === true;
+
+/** The index a lookup goes through, or undefined for a lookup by entity. */
+export const indexOfLookup = (lookup: AnyLookup): Created | undefined => lookup.index === undefined ? undefined : indexDefinitionOf(lookup.index);
+
+/** The key parts a lookup reads to find rows: its index's, or none for a lookup by entity. */
+export const lookupKeysOf = (lookup: AnyLookup): readonly Key[] => indexOfLookup(lookup)?.declaration.key ?? [];
+
+/**
+ * Throws for a lookup by entity whose `changed` names a component it neither reads nor has, for an index lookup whose
+ * `index` isn't a value `Index.create` returned, or whose `read` or `changed` names a component that not every entity
+ * the index holds has, and for a `changed: true` but on a system's index lookup.
+ */
+export const checkLookup = (what: "System" | "Finalizer", name: string, lookupName: string, lookup: AnyLookup): void => {
+    if (lookup.changed === true) {
+        if (what === "Finalizer") throw new Error(`Finalizer "${name}": lookup "${lookupName}"'s changed is true, which only a system's index lookup takes; a finalizer runs on each entity that stops matching.`);
+        if (lookup.index === undefined) throw new Error(`System "${name}": lookup "${lookupName}"'s changed is true, which only an index lookup takes; name the components it watches.`);
+    }
+    if (lookup.index === undefined) {
+        for (const key of watchedBy(lookup)) {
+            if (!(lookup.read ?? []).includes(key) && !(lookup.has ?? []).includes(key)) throw new Error(`${what} "${name}": lookup "${lookupName}" watches "${labelOf(key)}", which it neither reads nor has; name it in its read or has.`);
+        }
+        return;
+    }
+    const index = indexDefinitionOf(lookup.index);
+    if (index === undefined) throw new Error(`${what} "${name}": lookup "${lookupName}" goes through a value Index.create didn't return.`);
+    const held = new Set<Key>([...index.declaration.key, ...index.declaration.components?.has ?? []].map(firstKeyOf));
+    const check = (verb: string, keys: readonly Key[] | undefined): void => {
+        for (const key of keys ?? []) {
+            if (!held.has(firstKeyOf(key))) throw new Error(`${what} "${name}": lookup "${lookupName}" ${verb} "${labelOf(key)}", which not every entity index "${labelOfItem(index)}" holds has; name its key parts or its has.`);
+        }
+    };
+    check("reads", lookup.read);
+    check("watches", watchedBy(lookup));
+};
+
+/** The key parts a system's rows are ordered by: its `order` index's, or none. */
+export const orderKeysOf = (declaration: { readonly order?: unknown }): readonly Key[] => indexDefinitionOf(declaration.order)?.declaration.key ?? [];

package/src/interface/registry/items.ts

@@ -0,0 +1,125 @@
+/** A registered system, rule or finalizer: what each constructor records, told apart by `kind`. */
+type Registered = { readonly kind: string; readonly name: string; readonly declaration: object };
+
+/**
+ * A registered item: its kind and declaration, those of the first value registered under its id, its name, its id if
+ * the plugin gave one, and the label it has without one, numbered when another item had its name; shared by every
+ * value registered under its id. `first` is the value registered first, which stands for it wherever items compare.
+ */
+type Entry = {
+    readonly kind: string;
+    readonly declaration: object;
+    readonly name: string;
+    readonly id: string | undefined;
+    readonly numbered: string;
+    readonly first: Registered;
+};
+
+/** Every system, rule and finalizer, by value: values of one id share an entry. */
+const entries = new WeakMap<object, Entry>();
+
+/** Entries by the ids the plugin gave their declarations. */
+const identified = new Map<string, Entry>();
+
+/** Numbered labels given, so each item's is unique. */
+const labels = new Set<string>();
+
+/** How many registered items have each name. */
+const named = new Map<string, number>();
+
+/** Whether two values are one item: the same value, or values registered under one id. */
+export const sameItem = (a: object, b: object): boolean => {
+    if (a === b) return true;
+    const entry = entries.get(a);
+    return entry !== undefined && entry === entries.get(b);
+};
+
+/** The value first registered as this item, which stands for it wherever items compare; any other value as it is. */
+export const firstItemOf = (item: object): object => entries.get(item)?.first ?? item;
+
+/**
+ * How errors and reports name a system, rule or finalizer: its name while no other registered item has it, else its
+ * name with its id when the plugin gave one, and without one its name numbered by registration order. An item not
+ * registered is named by its name.
+ */
+export const labelOfItem = (item: { readonly name: string }): string => {
+    const entry = entries.get(item);
+    if (entry === undefined || (named.get(entry.name) ?? 0) <= 1) return item.name;
+    return entry.id === undefined ? entry.numbered : `${entry.name} (${entry.id})`;
+};
+
+/**
+ * The item already registered under `id` that `item` is: one of its kind with the same declaration, as a module
+ * evaluated again declares it; undefined without an id or for an id not registered. Throws for an id registered as
+ * another kind or with another declaration. `same` compares declarations.
+ */
+export const registeredAs = <T extends Registered>(item: T, id: string | undefined, same: (a: unknown, b: unknown) => boolean): object | undefined => {
+    if (id === undefined) return undefined;
+    const entry = identified.get(id);
+    if (entry === undefined) return undefined;
+    if (entry.kind !== item.kind) throw new Error(`Cannot declare "${item.name}" (${id}): its id is a ${entry.kind}'s.`);
+    if (!same(entry.declaration, item.declaration)) {
+        throw new Error(`Cannot declare "${item.name}" (${id}): its id is another item's, with another declaration; if a module was evaluated again with a changed declaration, reload the page.`);
+    }
+    return entry.first;
+};
+
+/** A label for an item registered now without an id, its name numbered when another item's has it. */
+const numberedFor = (name: string): string => {
+    let label = name;
+    for (let n = 2; labels.has(label); n++) label = `${name}#${n}`;
+    labels.add(label);
+    return label;
+};
+
+/** An item without an id is forgotten once collected: its name's count and numbered label go with it. */
+const forgotten = new FinalizationRegistry<{ readonly name: string; readonly numbered: string }>(({ name, numbered }) => {
+    labels.delete(numbered);
+    const count = (named.get(name) ?? 0) - 1;
+    if (count > 0) named.set(name, count);
+    else named.delete(name);
+});
+
+/**
+ * Records an item under its id: a value of an item `registeredAs` found shares its entry, and any other is a new item.
+ */
+export const recordItem = (item: Registered, id: string | undefined, existing: object | undefined): void => {
+    const shared = existing === undefined ? undefined : entries.get(existing);
+    if (shared !== undefined) {
+        entries.set(item, shared);
+        return;
+    }
+    const entry: Entry = { kind: item.kind, declaration: item.declaration, name: item.name, id, numbered: numberedFor(item.name), first: item };
+    named.set(item.name, (named.get(item.name) ?? 0) + 1);
+    if (id !== undefined) identified.set(id, entry);
+    else forgotten.register(item, { name: item.name, numbered: entry.numbered });
+    entries.set(item, entry);
+};
+
+/** How many items of each kind were declared without a name or an id, to number their labels. */
+const anonymous = new Map<string, number>();
+
+/**
+ * An item's name: the one its declaration gives; without one, its binding with the id the plugin gave it
+ * (`spawn (src/setup.ts#spawn)`), and without an id, its kind numbered by creation (`system #3`).
+ */
+export const nameOf = (name: string | undefined, id: string | undefined, kind: "system" | "rule" | "finalizer" | "index"): string => {
+    if (name !== undefined) return name;
+    if (id !== undefined) return `${id.slice(id.lastIndexOf("#") + 1)} (${id})`;
+    const count = (anonymous.get(kind) ?? 0) + 1;
+    anonymous.set(kind, count);
+    return `${kind} #${count}`;
+};
+
+/** The id the plugin gave a system, rule or finalizer, by which other threads name it, if it gave one. */
+export const idOfItem = (item: object): string | undefined => entries.get(item)?.id;
+
+/** The item first registered under an id, or undefined where no module declaring it was imported. */
+export const itemOfId = (id: string): { readonly kind: string; readonly name: string } | undefined => identified.get(id)?.first;
+
+/** The ids of every system, rule and finalizer of `kind` registered with one, as a joined thread tells the world what it imported. */
+export const identifiedItems = (kind: string): readonly string[] => {
+    const found: string[] = [];
+    for (const [id, entry] of identified) if (entry.kind === kind) found.push(id);
+    return found;
+};

package/src/interface/registry/layout.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import type { Schema } from "../schema/schema.js";
+import { threadOfDeclaration } from "./declarations.js";
+import { layoutOf } from "./layout.js";
+import { allowsNull, conditional, hasBoolean, isStruct } from "./schemas.js";
+
+const f32: Schema = { type: "number", precision: 1 };
+const vec = (length: number, layout?: "storage" | "vertex"): Schema => ({ type: "array", items: f32, minItems: length, maxItems: length, ...layout === undefined ? {} : { layout } });
+
+/** Byte offsets of each leaf, and the element stride. */
+const placement = (schema: Schema): { readonly stride: number; readonly offsets: readonly number[] } => {
+    const layout = layoutOf(schema);
+    if (layout.kind !== "linear") throw new Error("not linear");
+    return { stride: layout.stride, offsets: layout.leaves.map(leaf => leaf.offset) };
+};
+
+describe("layoutOf", () => {
+    it("follows WGSL storage rules: vec3 aligned to 16 but 12 bytes, so a scalar packs after it", () => {
+        expect(placement(vec(3, "storage"))).toEqual({ stride: 16, offsets: [0, 4, 8] });
+        expect(placement(vec(2, "storage"))).toEqual({ stride: 8, offsets: [0, 4] });
+        expect(placement({ type: "object", layout: "storage", properties: { position: vec(3), mass: f32 } })).toEqual({ stride: 16, offsets: [0, 4, 8, 12] });
+        expect(placement({ type: "object", layout: "storage", properties: { mass: f32, position: vec(3) } })).toEqual({ stride: 32, offsets: [0, 16, 20, 24] });
+        // array<vec3<f32>, 2>: elements at a 16-byte stride.
+        expect(placement({ type: "array", layout: "storage", items: vec(3), minItems: 2, maxItems: 2 })).toEqual({ stride: 32, offsets: [0, 4, 8, 16, 20, 24] });
+    });
+
+    it("packs vertex layouts tightly at 4 bytes", () => {
+        expect(placement(vec(3, "vertex"))).toEqual({ stride: 12, offsets: [0, 4, 8] });
+        expect(placement({ type: "object", layout: "vertex", properties: { mass: f32, position: vec(3), flag: { type: "boolean" } } })).toEqual({ stride: 20, offsets: [0, 4, 8, 12, 16] });
+    });
+
+    it("packs CPU layouts tightly with natural alignment", () => {
+        expect(placement(vec(3))).toEqual({ stride: 12, offsets: [0, 4, 8] });
+        expect(placement({ type: "object", properties: { flag: { type: "boolean" }, weight: { type: "number" }, mass: f32 } })).toEqual({ stride: 24, offsets: [0, 8, 16] });
+    });
+
+    it("stores sets and maps as objects, even of numbers, and nothing in them as a struct", () => {
+        const set: Schema = { type: "set", items: { type: "number" } };
+        const map: Schema = { type: "map", keys: { type: "integer", minimum: 0, maximum: 9 }, values: { type: "boolean" } };
+        expect([layoutOf(set).kind, layoutOf(map).kind]).toEqual(["object", "object"]);
+        expect(layoutOf({ type: "object", properties: { at: f32, marks: set } }).kind).toBe("object");
+        expect([isStruct(set), isStruct(map), hasBoolean(map), allowsNull(set), conditional(map)]).toEqual([false, false, false, false, false]);
+        expect(threadOfDeclaration({ type: map })).toBe("world");
+        expect(() => layoutOf({ type: "array", layout: "storage", items: set, minItems: 2, maxItems: 2 })).toThrow("storage layout needs");
+    });
+
+    it("rejects GPU layouts the GPU can't share, naming the leaf", () => {
+        expect(() => layoutOf({ type: "object", layout: "storage", properties: { mass: { type: "number" } } })).toThrow('["mass"] is f64');
+        expect(() => layoutOf({ type: "array", layout: "vertex", items: { type: "string" }, minItems: 2, maxItems: 2 })).toThrow("vertex layout needs");
+    });
+
+    it("reads and writes interleaved values, leaving padding untouched", () => {
+        const layout = layoutOf(vec(3, "storage"));
+        if (layout.kind !== "linear") throw new Error("not linear");
+        const buffer = new ArrayBuffer(64);
+        const views = { f32: new Float32Array(buffer), f64: new Float64Array(buffer), i32: new Int32Array(buffer), u32: new Uint32Array(buffer), u8: new Uint8Array(buffer) };
+        views.f32.fill(-1);
+        layout.write(views, 1, [1, 2, 3]);
+        expect(layout.read(views, 1)).toEqual([1, 2, 3]);
+        expect([...views.f32.subarray(0, 8)]).toEqual([-1, -1, -1, -1, 1, 2, 3, -1]);
+    });
+
+    it("reads and writes structs of every leaf kind, nested and with any member name", () => {
+        const integer: Schema = { type: "integer", minimum: 0, maximum: 255 };
+        const layout = layoutOf({
+            type: "object",
+            properties: {
+                ["__proto__"]: f32,
+                flag: { type: "boolean" },
+                count: integer,
+                at: vec(2),
+                inner: { type: "object", properties: { x: { type: "number" }, pairs: { type: "array", items: vec(2), minItems: 2, maxItems: 2 } } },
+            },
+        });
+        if (layout.kind !== "linear") throw new Error("not linear");
+        const buffer = new ArrayBuffer(256);
+        const views = { f32: new Float32Array(buffer), f64: new Float64Array(buffer), i32: new Int32Array(buffer), u32: new Uint32Array(buffer), u8: new Uint8Array(buffer) };
+        const value = JSON.parse('{ "__proto__": 0.5, "flag": true, "count": 7, "at": [1, 2], "inner": { "x": 0.25, "pairs": [[3, 4], [5, 6]] } }');
+        layout.write(views, 1, value);
+        const read = layout.read(views, 1);
+        expect(read).toEqual(value);
+        expect(Object.getPrototypeOf(read)).toBe(Object.prototype);
+        layout.write(views, 1, { flag: false, count: 1, at: [0, 0] });
+        expect(layout.read(views, 1)).toEqual(JSON.parse('{ "__proto__": null, "flag": false, "count": 1, "at": [0, 0], "inner": { "x": null, "pairs": [[null, null], [null, null]] } }', (_, leaf: unknown) => leaf === null ? NaN : leaf));
+    });
+});

package/src/interface/registry/layout.ts

@@ -0,0 +1,364 @@
+import type { Schema } from '../schema/schema.js';
+import { isString } from './schemas.js';
+
+/** A path from a value to one scalar leaf: `[]` for a scalar, `[1]` for a tuple element, `["x"]` for a struct field. */
+export type Path = readonly (number | string)[];
+
+/** A leaf's logical type. */
+export type Scalar = "f32" | "f64" | "i32" | "u32" | "boolean";
+
+/** The typed array a leaf is stored through: booleans are `u8` on the CPU and `u32` in GPU layouts. */
+export type View = "f32" | "f64" | "i32" | "u32" | "u8";
+
+/** Views of one component's bytes; a leaf reads the one its `view` names. */
+export type Views = {
+    readonly f32: Float32Array;
+    readonly f64: Float64Array;
+    readonly i32: Int32Array;
+    readonly u32: Uint32Array;
+    readonly u8: Uint8Array;
+};
+
+export type TypedArray = Views[keyof Views];
+
+/** A scalar leaf at byte `offset` within each element. In elements of its view, a row's value is at `row * unitStride + unitOffset`. */
+export type Leaf = {
+    readonly path: Path;
+    readonly scalar: Scalar;
+    readonly view: View;
+    readonly offset: number;
+    readonly unitStride: number;
+    readonly unitOffset: number;
+};
+
+/**
+ * How a component's values are stored.
+ * - `constant`: a `const` schema; no storage, every value is `value`.
+ * - `linear`: interleaved elements of `stride` bytes in one column. `read` copies a value out; `write` replaces it.
+ * - `string`: the world's thread's values, as `object`'s, and a 4-byte handle per row, in one column, to each one's
+ *   record in shared memory, which other threads read; only the world's thread writes them.
+ * - `object`: a JS array of values, on its logical thread only.
+ */
+export type Layout =
+    | { readonly kind: "constant"; readonly value: unknown }
+    | {
+        readonly kind: "linear";
+        readonly leaves: readonly Leaf[];
+        readonly stride: number;
+        readonly read: (views: Views, row: number) => unknown;
+        readonly write: (views: Views, row: number, value: unknown) => void;
+    }
+    | { readonly kind: "string"; readonly stride: 4 }
+    | { readonly kind: "object" };
+
+/** The layout of every string. */
+const stringLayout: Layout = { kind: "string", stride: 4 };
+
+/** The layout of values stored as they are. */
+export const objectLayout: Layout = { kind: "object" };
+
+export const bytesOf = (view: View): number => view === "f64" ? 8 : view === "u8" ? 1 : 4;
+
+export const viewsOf = (buffer: ArrayBufferLike, byteOffset: number, byteLength: number): Views => ({
+    f32: new Float32Array(buffer, byteOffset, byteLength >> 2),
+    f64: new Float64Array(buffer, byteOffset, Math.floor(byteLength / 8)),
+    i32: new Int32Array(buffer, byteOffset, byteLength >> 2),
+    u32: new Uint32Array(buffer, byteOffset, byteLength >> 2),
+    u8: new Uint8Array(buffer, byteOffset, byteLength),
+});
+
+/** A value's shape, before placement. */
+type Shape =
+    | { readonly kind: "scalar"; readonly scalar: Scalar }
+    | { readonly kind: "tuple"; readonly items: readonly Shape[] }
+    | { readonly kind: "struct"; readonly names: readonly string[]; readonly items: readonly Shape[] };
+
+const integerScalar = ({ minimum, maximum }: { readonly minimum?: number; readonly maximum?: number }): Scalar => {
+    if (minimum === undefined || maximum === undefined) return "f64";
+    if (minimum >= 0 && maximum <= 0xFFFFFFFF) return "u32";
+    if (minimum >= -0x80000000 && maximum <= 0x7FFFFFFF) return "i32";
+    return "f64";
+};
+
+/** `null` if the schema isn't linear: numbers, booleans, fixed-length tuples and structs of those. */
+const shapeOf = (schema: Schema): Shape | null => {
+    if (!("type" in schema)) return null;
+    switch (schema.type) {
+        case "number": return { kind: "scalar", scalar: schema.precision === 1 ? "f32" : "f64" };
+        case "integer": return { kind: "scalar", scalar: "format" in schema ? "f64" : integerScalar(schema) };
+        case "boolean": return { kind: "scalar", scalar: "boolean" };
+        case "array": {
+            const length = schema.minItems;
+            if (length === undefined || length !== schema.maxItems) return null;
+            const item = shapeOf(schema.items);
+            return item === null ? null : { kind: "tuple", items: new Array<Shape>(length).fill(item) };
+        }
+        case "object": {
+            const names = Object.keys(schema.properties);
+            const { required } = schema;
+            if (required !== undefined && names.some(name => !required.includes(name))) return null;
+            const items: Shape[] = [];
+            for (const name of names) {
+                const item = shapeOf(schema.properties[name]);
+                if (item === null) return null;
+                items.push(item);
+            }
+            return { kind: "struct", names, items };
+        }
+        default: return null;
+    }
+};
+
+const roundUp = (value: number, alignment: number): number => Math.ceil(value / alignment) * alignment;
+
+/** A shape's placement: leaves at offsets relative to the shape's start. */
+type Placed = { readonly size: number; readonly align: number; readonly leaves: readonly { readonly path: Path; readonly scalar: Scalar; readonly view: View; readonly offset: number }[] };
+
+type Rules = "cpu" | "storage" | "vertex";
+
+const describe = (path: Path): string => path.length === 0 ? "the value" : `[${path.map(key => JSON.stringify(key)).join("][")}]`;
+
+const gpuScalar = (scalar: Scalar, path: Path): View => {
+    if (scalar === "f64") throw new Error(`${describe(path)} is f64, which isn't GPU compatible: use a number with precision: 1, or an integer with minimum and maximum within i32 or u32.`);
+    return scalar === "boolean" ? "u32" : scalar;
+};
+
+const sameScalar = (items: readonly Shape[]): Scalar | null => {
+    const first = items[0];
+    if (first?.kind !== "scalar") return null;
+    return items.every(item => item.kind === "scalar" && item.scalar === first.scalar) ? first.scalar : null;
+};
+
+const place = (shape: Shape, path: Path, rules: Rules): Placed => {
+    if (shape.kind === "scalar") {
+        const view: View = rules === "cpu" ? (shape.scalar === "boolean" ? "u8" : shape.scalar) : gpuScalar(shape.scalar, path);
+        const size = bytesOf(view);
+        return { size, align: size, leaves: [{ path, scalar: shape.scalar, view, offset: 0 }] };
+    }
+    const keys: readonly (number | string)[] = shape.kind === "struct" ? shape.names : shape.items.map((_, i) => i);
+    const items = shape.items.map((item, i) => place(item, [...path, keys[i]], rules));
+    if (rules === "storage" && shape.kind === "tuple") {
+        const scalar = sameScalar(shape.items);
+        const length = shape.items.length;
+        // WGSL vec2/vec3/vec4: 4-byte components, aligned to 8, 16, 16; a vec3 is 12 bytes, so a scalar can follow it.
+        if (scalar !== null && length >= 2 && length <= 4) {
+            return { size: 4 * length, align: length === 2 ? 8 : 16, leaves: items.map((item, i) => ({ ...item.leaves[0], offset: 4 * i })) };
+        }
+        if (!shape.items.every(item => JSON.stringify(item) === JSON.stringify(shape.items[0]))) {
+            throw new Error(`${describe(path)} mixes element types, which a WGSL array can't: use a struct.`);
+        }
+        // WGSL array<T, N>: elements at a stride of T's size rounded up to its alignment.
+        const element = items[0];
+        const stride = roundUp(element.size, element.align);
+        return {
+            size: stride * length,
+            align: element.align,
+            leaves: items.flatMap((item, i) => item.leaves.map(leaf => ({ ...leaf, offset: leaf.offset + i * stride }))),
+        };
+    }
+    const align = rules === "vertex" ? 4 : Math.max(...items.map(item => item.align));
+    return pack(items, align, rules === "vertex" ? 4 : 0);
+};
+
+/** Members in order, each at its alignment (or `memberAlign` when set), padded to the aggregate's alignment. */
+const pack = (items: readonly Placed[], align: number, memberAlign: number): Placed => {
+    let offset = 0;
+    const leaves: Placed["leaves"][number][] = [];
+    for (const item of items) {
+        offset = roundUp(offset, memberAlign === 0 ? item.align : Math.min(memberAlign, item.align));
+        for (const leaf of item.leaves) leaves.push({ ...leaf, offset: offset + leaf.offset });
+        offset += item.size;
+    }
+    return { size: roundUp(offset, align), align, leaves };
+};
+
+type Node = {
+    readonly read: (views: Views, row: number) => unknown;
+    readonly write: (views: Views, row: number, value: unknown) => void;
+};
+
+const element = (value: unknown, key: number | string): unknown =>
+    typeof value === "object" && value !== null ? Reflect.get(value, key) : undefined;
+
+/** A tuple of 2 to 4 same-typed scalars in consecutive elements of one view. */
+const lanesNode = (view: View, unitStride: number, unitOffset: number, length: number): Node => {
+    const write = (views: Views, row: number, value: unknown): void => {
+        const target = views[view];
+        const index = row * unitStride + unitOffset;
+        if (Array.isArray(value)) for (let i = 0; i < length; i++) target[index + i] = Number(value[i]);
+        else for (let i = 0; i < length; i++) target[index + i] = Number(element(value, i));
+    };
+    if (length === 2) return {
+        read: (views, row) => {
+            const target = views[view];
+            const index = row * unitStride + unitOffset;
+            return [target[index], target[index + 1]];
+        },
+        write,
+    };
+    if (length === 3) return {
+        read: (views, row) => {
+            const target = views[view];
+            const index = row * unitStride + unitOffset;
+            return [target[index], target[index + 1], target[index + 2]];
+        },
+        write,
+    };
+    return {
+        read: (views, row) => {
+            const target = views[view];
+            const index = row * unitStride + unitOffset;
+            return [target[index], target[index + 1], target[index + 2], target[index + 3]];
+        },
+        write,
+    };
+};
+
+/** Builds read/write closures over placed leaves, consuming them in shape order. */
+const nodeOf = (shape: Shape, leaves: readonly Leaf[], next: { index: number }): Node => {
+    if (shape.kind === "scalar") {
+        const { view, unitStride, unitOffset } = leaves[next.index++];
+        return shape.scalar === "boolean"
+            ? { read: (views, row) => views[view][row * unitStride + unitOffset] !== 0, write: (views, row, value) => { views[view][row * unitStride + unitOffset] = Number(value); } }
+            : { read: (views, row) => views[view][row * unitStride + unitOffset], write: (views, row, value) => { views[view][row * unitStride + unitOffset] = Number(value); } };
+    }
+    const first = next.index;
+    const items = shape.items.map(item => nodeOf(item, leaves, next));
+    const tupleLeaves = leaves.slice(first, next.index);
+    // A tuple of same-typed non-boolean scalars, like a vec3: one loop over its leaves.
+    if (shape.kind === "tuple" && shape.items.every(item => item.kind === "scalar" && item.scalar !== "boolean") && tupleLeaves.every(leaf => leaf.view === tupleLeaves[0].view)) {
+        const view = tupleLeaves[0].view;
+        const strides = tupleLeaves.map(leaf => leaf.unitStride);
+        const offsets = tupleLeaves.map(leaf => leaf.unitOffset);
+        const length = tupleLeaves.length;
+        const [{ unitStride, unitOffset }] = tupleLeaves;
+        // Lanes next to each other, as in a vec2, vec3 or vec4: array literals and straight-line stores.
+        if (length >= 2 && length <= 4 && tupleLeaves.every((leaf, i) => leaf.unitStride === unitStride && leaf.unitOffset === unitOffset + i)) return lanesNode(view, unitStride, unitOffset, length);
+        return {
+            read: (views, row) => {
+                const target = views[view];
+                const value = new Array<number>(length);
+                for (let i = 0; i < length; i++) value[i] = target[row * strides[i] + offsets[i]];
+                return value;
+            },
+            write: (views, row, value) => {
+                const target = views[view];
+                if (Array.isArray(value)) for (let i = 0; i < length; i++) target[row * strides[i] + offsets[i]] = Number(value[i]);
+                else for (let i = 0; i < length; i++) target[row * strides[i] + offsets[i]] = Number(element(value, i));
+            },
+        };
+    }
+    if (shape.kind === "tuple") {
+        return {
+            read: (views, row) => {
+                const value = new Array<unknown>(items.length);
+                for (let i = 0; i < items.length; i++) value[i] = items[i].read(views, row);
+                return value;
+            },
+            write: (views, row, value) => {
+                if (Array.isArray(value)) for (let i = 0; i < items.length; i++) items[i].write(views, row, value[i]);
+                else for (let i = 0; i < items.length; i++) items[i].write(views, row, element(value, i));
+            },
+        };
+    }
+    const { names } = shape;
+    return {
+        read: (views, row) => {
+            const value: { [name: string]: unknown } = {};
+            for (let i = 0; i < names.length; i++) value[names[i]] = items[i].read(views, row);
+            return value;
+        },
+        write: (views, row, value) => {
+            for (let i = 0; i < names.length; i++) items[i].write(views, row, element(value, names[i]));
+        },
+    };
+};
+
+/** Whether code can be generated here; a content security policy without `'unsafe-eval'` forbids it. */
+let generating = true;
+
+/** A struct member's name as an object literal's key: quoted, and computed for `__proto__`, which a plain key would make the prototype. */
+const propertyOf = (name: string): string => name === "__proto__" ? `[${JSON.stringify(name)}]` : JSON.stringify(name);
+
+/**
+ * A struct's or nested tuple's read and write as straight-line code: one literal of its leaves' loads, and one store per
+ * leaf, rather than a call per leaf and properties added one at a time. Only numbers, view names and quoted member
+ * names are written into the code. A value that isn't an object is written through `fallback`. Null where code can't
+ * be generated.
+ */
+const generatedNode = (shape: Shape, leaves: readonly Leaf[], fallback: Node): Node | null => {
+    if (!generating) return null;
+    const at = (leaf: Leaf): string => `views.${leaf.view}[row * ${leaf.unitStride} + ${leaf.unitOffset}]`;
+    let next = 0;
+    const literal = (node: Shape): string => {
+        if (node.kind === "scalar") {
+            const leaf = leaves[next++];
+            return leaf.scalar === "boolean" ? `${at(leaf)} !== 0` : at(leaf);
+        }
+        if (node.kind === "tuple") return `[${node.items.map(literal).join(", ")}]`;
+        return `{ ${node.items.map((item, i) => `${propertyOf(node.names[i])}: ${literal(item)}`).join(", ")} }`;
+    };
+    const read = literal(shape);
+    next = 0;
+    let temporaries = 0;
+    // A member of `value` is read directly when `value` is known to be an object, and through `element` otherwise.
+    const stores = (node: Shape, value: string, object: boolean): string[] => {
+        if (node.kind === "scalar") return [`${at(leaves[next++])} = Number(${value});`];
+        const keys = node.kind === "struct" ? node.names.map(name => JSON.stringify(name)) : node.items.map((_, i) => String(i));
+        return node.items.flatMap((item, i) => {
+            const member = object ? `${value}[${keys[i]}]` : `element(${value}, ${keys[i]})`;
+            if (item.kind === "scalar") return stores(item, member, false);
+            const temporary = `t${temporaries++}`;
+            return [`const ${temporary} = ${member};`, ...stores(item, temporary, false)];
+        });
+    };
+    const body = [
+        `return { read: (views, row) => (${read}), write: (views, row, value) => {`,
+        `if (typeof value !== "object" || value === null) { fallback.write(views, row, value); return; }`,
+        ...stores(shape, "value", true),
+        "} };",
+    ].join("\n");
+    try {
+        // The factory returns the node its body above makes.
+        const node: Node = new Function("element", "fallback", body)(element, fallback);
+        return node;
+    }
+    catch {
+        generating = false;
+        return null;
+    }
+};
+
+const gpuLayoutOf = (schema: Schema): "storage" | "vertex" | undefined =>
+    "type" in schema && (schema.type === "object" || schema.type === "array") ? schema.layout : undefined;
+
+/**
+ * How a schema's values are stored. Throws when a schema declares a GPU `layout` it can't meet,
+ * naming the leaf and the fix, so registration fails rather than the GPU upload.
+ */
+/** A value without a schema isn't data, so it's stored as it is. */
+export const layoutOf = (schema: Schema | undefined): Layout => {
+    if (schema === undefined) return objectLayout;
+    if ("const" in schema) return { kind: "constant", value: schema.const };
+    if (isString(schema)) return stringLayout;
+    const rules: Rules = gpuLayoutOf(schema) ?? "cpu";
+    const shape = shapeOf(schema);
+    if (shape === null) {
+        if (rules !== "cpu") throw new Error(`A ${rules} layout needs numbers, integers, booleans, fixed-length tuples and structs with every property required.`);
+        return objectLayout;
+    }
+    const placed = place(shape, [], rules);
+    // An array of elements: each is padded to its alignment.
+    const stride = roundUp(placed.size, placed.align);
+    const leaves: Leaf[] = placed.leaves.map(leaf => ({
+        ...leaf,
+        unitStride: stride / bytesOf(leaf.view),
+        unitOffset: leaf.offset / bytesOf(leaf.view),
+    }));
+    const built = nodeOf(shape, leaves, { index: 0 });
+    // Scalars and tuples of scalars are already straight-line.
+    const node = shape.kind === "struct" || (shape.kind === "tuple" && shape.items.some(item => item.kind !== "scalar")) ? generatedNode(shape, leaves, built) ?? built : built;
+    return { kind: "linear", leaves, stride, read: node.read, write: node.write };
+};
+
+export const samePath = (a: Path, b: Path): boolean => a.length === b.length && a.every((key, i) => key === b[i]);