@adobe/ecs 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,52 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Component, Finalizer, Resource, Rule, System, gpuDevice, workers, type Gpu } from "@adobe/ecs";
+import type * as Ecs from "@adobe/ecs";
+import type { Create } from "./world/create.js";
+
+// A consumer emits declarations for the values it makes from the public interface, naming no internal module.
+export const position = Symbol("indexTypeTest/position");
+export const slot = Symbol("indexTypeTest/slot");
+export const element = Symbol("indexTypeTest/element");
+export const scale = Symbol("indexTypeTest/scale");
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: number };
+        [slot]: { type: number; derived: true };
+        [element]: { type: HTMLElement; thread: "main" };
+    }
+    interface Resources {
+        [scale]: { type: number };
+    }
+}
+export const move = System.create({ components: { with: [position] } }, (row, { resources }) => { row[position] += resources[scale]; });
+export const show = System.create({ components: { with: [position, element] } }, row => { row[element].textContent = String(row[position]); });
+export const all = System.create({ systems: [move, show] });
+export const draw = System.render({ shader: { accessors: { place: position } } }, () => {});
+export const release = Finalizer.create({ components: { with: [element] } }, row => { row[element].remove(); });
+Rule.create({ components: { with: [position] }, derive: [slot] });
+declare const create: Create;
+declare const wgsl: typeof Gpu.wgsl;
+export const world = create({ [workers]: 4, [gpuDevice]: null });
+export const read = System.create({ observer: true, components: { with: [position, slot] } }, () => {});
+export const readOne = System.create({ observer: true, lookup: { at: { with: [position, slot] } } }, () => {});
+export const report = world.run(all);
+export const shader = wgsl(draw);
+export const added = world.add(read);
+
+// Only types a consumer declares with are named; the rest are inferred where wanted.
+// @ts-expect-error a thread's name is keyof Threads
+export type NoThread = Ecs.Thread;
+// @ts-expect-error the cadence's value is Resource.Value<typeof cadence>
+export type NoCadence = Ecs.Cadence;
+// @ts-expect-error a rule is the value Rule.create returns: ReturnType<typeof Rule.create>
+export const noRule: Rule = Rule.create({ components: { with: [position] }, derive: [slot] });
+// @ts-expect-error an archetype is a list of components declared as const
+export const noArchetype: Ecs.Archetype = [position];
+// @ts-expect-error a trait's key is keyof Traits<never, never>
+export type NoTraitKey = Ecs.Trait.Key;
+// @ts-expect-error observer systems read a world: no Observe
+export type NoObserve = Ecs.Observe<number>;
+// @ts-expect-error nor its helpers
+export type NoToPromise = typeof Ecs.Observe.toPromise;
+// @ts-expect-error nor what world.observe held
+export type NoObservers = Ecs.Observers;

package/src/interface/indexes/create.test.ts

@@ -0,0 +1,146 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { createResolved } from "../system/create-resolved.js";
+import { giveAccess } from "../registry/ids.test-helper.js";
+import { Entity } from "../entity/entity.js";
+import { Finalizer } from "../finalizer/finalizer.js";
+import { identify } from "../registry/ids.test-helper.js";
+import { isLeaf, requireDefinition } from "../registry/index.js";
+import { accessOf } from "../registry/schedule.js";
+import { threadOf } from "../registry/threads.js";
+import { System } from "../system/system.js";
+import { Index } from "./index-type.js";
+import type { Vec2 } from "../math/index.js";
+
+const cell = Symbol("indexCreateTest/cell");
+const point = Symbol("indexCreateTest/point");
+const amount = Symbol("indexCreateTest/amount");
+const name = Symbol("indexCreateTest/name");
+const node = Symbol("indexCreateTest/node");
+const tags = Symbol("indexCreateTest/tags");
+const shown = Symbol("indexCreateTest/shown");
+const parent = Symbol("indexCreateTest/parent");
+const unregistered = Symbol("indexCreateTest/unregistered");
+const handle = Symbol("indexCreateTest/handle");
+const view = Symbol("indexCreateTest/view");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [cell]: { type: Vec2.I32 };
+        [point]: { type: { readonly x: number; readonly y: number } };
+        [amount]: { type: number };
+        [name]: { type: string };
+        [node]: { type: { readonly label: string } };
+        [tags]: { type: ReadonlySet<string> };
+        [shown]: { type: true };
+        [parent]: { type: Entity; reference: "owner" };
+        [handle]: { type: () => void };
+        [view]: { type: { readonly label: string }; thread: "main" };
+    }
+}
+
+/** Declares as an untyped caller would, bypassing the types' checks. */
+const untyped = (declaration: object): unknown => Reflect.apply(Index.create, undefined, [declaration]);
+
+describe("Index.create", () => {
+    it("returns an index labeled by its name, its binding and id, or its kind numbered", () => {
+        const named = Index.create({ key: [amount] });
+        expect(named.name).toBe("named");
+        const bound = Index.create(identify({ key: [amount], sorted: true }, "i.ts#bound"));
+        expect(bound.name).toBe("bound");
+        expect(Index.create({ key: [amount] }).name).toMatch(/^index #\d+$/);
+    });
+    it("is the index already recorded when declared again under its id the same, and throws for another declaration", () => {
+        const first = Index.create(identify({ key: [cell], components: { with: [shown] } }, "i.ts#again"));
+        expect(Index.create(identify({ key: [cell], components: { with: [shown] } }, "i.ts#again"))).toBe(first);
+        expect(() => Index.create(identify({ key: [amount] }, "i.ts#again"))).toThrow("reload the page");
+        // Another value is another index.
+        expect(Index.create({ key: [cell], components: { with: [shown] } })).not.toBe(first);
+    });
+    it("throws for key parts that aren't components of data, are listed twice, or are sets", () => {
+        expect(() => untyped({ name: "bad" })).toThrow(`needs a key`);
+        expect(() => untyped({ name: "bad", key: amount })).toThrow(`needs a key`);
+        expect(() => untyped({ name: "bad", key: [unregistered] })).toThrow(`key part "indexCreateTest/unregistered", which isn't a registered component of data`);
+        expect(() => untyped({ name: "bad", key: [handle] })).toThrow("isn't a registered component of data");
+        expect(() => untyped({ name: "bad", key: [amount, amount] })).toThrow(`lists key part "indexCreateTest/amount" twice`);
+        expect(() => untyped({ name: "bad", key: [tags] })).toThrow("a set or map");
+    });
+    it("takes an empty key, holding the entities with its has and not, and isn't unique then", () => {
+        expect(() => Index.create({ key: [] })).not.toThrow();
+        expect(() => Index.create({ key: [], sorted: true, components: { with: [amount], not: [shown] } })).not.toThrow();
+        expect(() => untyped({ name: "bad", key: [], unique: true })).toThrow(`is unique without a key`);
+        expect(() => untyped({ name: "bad", key: [], components: { with: [shown], not: [shown] } })).toThrow("which it holds by");
+        expect(() => untyped({ name: "bad", key: [], components: { with: [unregistered] } })).toThrow("isn't a registered component");
+    });
+    it("orders sorted parts that have an order: numbers, booleans, entities, strings and tuples of them", () => {
+        expect(() => Index.create({ key: [cell, amount, name, parent], sorted: true })).not.toThrow();
+        expect(() => untyped({ name: "bad", key: [point], sorted: true })).toThrow(`sorted by "indexCreateTest/point", whose values have no order`);
+        expect(() => untyped({ name: "bad", key: [node], sorted: true })).toThrow("whose values have no order");
+        // A hash part may be any data.
+        expect(() => Index.create({ key: [point, node] })).not.toThrow();
+    });
+    it("throws for object parts on two threads and for has and not naming what they can't", () => {
+        expect(() => untyped({ name: "bad", key: [node, view] })).toThrow(`key parts on threads "world" and "main"`);
+        expect(() => untyped({ name: "bad", key: [name, view] })).toThrow(`key parts on threads "world" and "main"; its object parts live on one thread, the world's beside a string`);
+        expect(() => untyped({ name: "bad", key: [amount], components: { with: [unregistered] } })).toThrow("isn't a registered component");
+        expect(() => untyped({ name: "bad", key: [amount], components: { not: [unregistered] } })).toThrow("isn't a registered component");
+        expect(() => untyped({ name: "bad", key: [amount], components: { not: [amount] } })).toThrow(`excludes "indexCreateTest/amount", which it holds by`);
+        expect(() => untyped({ name: "bad", key: [amount], components: { with: [shown], not: [shown] } })).toThrow("which it holds by");
+    });
+});
+
+describe("systems and finalizers looking up through an index", () => {
+    const grid = Index.create({ key: [cell], components: { with: [amount] } });
+    /** A system of a declaration as the world takes it, what its body reads and writes listed, bypassing the types' checks. */
+    const untypedSystem = (declaration: object): unknown => Reflect.apply(createResolved, undefined, [declaration, () => {}]);
+    it("read the index's key parts, for ordering and conflicts, and are placed by them", () => {
+        const reader = System.create({ lookup: { near: { index: grid } } }, ({ lookup }) => { void lookup.near([0, 0]).at(0)[amount]; });
+        const leaf = requireDefinition(reader);
+        expect(isLeaf(leaf) ? [...accessOf(leaf).reads] : null).toEqual([amount, cell]);
+        const writer = System.create({ components: { with: [cell] } }, row => { row[cell] = [0, 0]; });
+        expect(() => System.create([reader, writer])).toThrow(`both access "indexCreateTest/cell" and one writes it`);
+        expect(() => System.create({ systems: [reader, writer], before: [] })).toThrow("order them");
+        const names = Index.create({ key: [view] });
+        expect(threadOf({ lookup: { shown: { index: names } } }, "System", "placed")).toBe("main");
+    });
+    it("throw for a lookup through what isn't an index, reading or watching what not every entity it holds has, or a system writing its key or reads", () => {
+        expect(() => untypedSystem({ name: "bad", lookup: { near: { index: { name: "fake" } } } })).toThrow(`lookup "near" goes through a value Index.create didn't return`);
+        expect(() => untypedSystem({ name: "bad", lookup: { near: { index: grid, read: [name] } } })).toThrow(`lookup "near" reads "indexCreateTest/name", which not every entity index "grid" holds has`);
+        expect(() => untypedSystem({ name: "bad", lookup: { near: { index: grid, changed: [name] } } })).toThrow(`lookup "near" watches "indexCreateTest/name"`);
+        expect(() => untypedSystem({ name: "bad", components: { write: [cell] }, lookup: { near: { index: grid } } })).toThrow(`goes through an index keyed by "indexCreateTest/cell", which the system writes`);
+        expect(() => untypedSystem({ name: "bad", components: { write: [amount] }, lookup: { near: { index: grid, read: [amount] } } })).toThrow(`reads "indexCreateTest/amount", which the system writes`);
+        expect(() => untypedSystem({ name: "bad", kernel: true, components: { write: [amount] }, lookup: { near: { index: Index.create({ key: [name] }) } } })).toThrow(`keyed by "indexCreateTest/name", a string, which kernels don't read yet`);
+        const reading = giveAccess({ components: { with: [amount] }, lookup: { near: { index: grid } } }, { read: [amount], lookup: { near: [name] } });
+        expect(() => Reflect.apply(Finalizer.create, undefined, [reading, () => {}])).toThrow(`lookup "near" reads`);
+        expect(grid.name).toBe("grid");
+    });
+});
+
+describe("systems ordering their rows by an index", () => {
+    const ranked = Index.create({ key: [amount], sorted: true, components: { with: [cell] } });
+    /** A system of a declaration as the world takes it, what its body reads and writes listed, bypassing the types' checks. */
+    const untypedSystem = (declaration: object): unknown => Reflect.apply(createResolved, undefined, [declaration, () => {}]);
+    it("read the index's key parts, for ordering and conflicts, and are placed by them", () => {
+        const ordered = System.create({ components: { with: [cell] }, order: ranked }, row => { void row[cell]; });
+        const leaf = requireDefinition(ordered);
+        expect(isLeaf(leaf) ? [...accessOf(leaf).reads] : null).toEqual([cell, amount]);
+        const writer = System.create({ components: { with: [amount] } }, row => { row[amount] = 0; });
+        expect(() => System.create([ordered, writer])).toThrow(`both access "indexCreateTest/amount" and one writes it`);
+        // Every value a sorted index orders lives in shared memory, strings included, so its key places nothing.
+        expect(threadOf({ order: Index.create({ key: [name], sorted: true }) }, "System", "unplaced")).toBe(null);
+    });
+    it("throw for an order by what isn't a sorted index, without components, with up, on the GPU, or writing its key", () => {
+        expect(() => untypedSystem({ name: "bad", components: { read: [cell] }, order: { name: "fake" } })).toThrow(`orders its rows by a value Index.create didn't return`);
+        expect(() => untypedSystem({ name: "bad", components: { read: [cell] }, order: Index.create({ key: [amount] }) })).toThrow(`orders its rows by index "order", which isn't sorted`);
+        expect(() => untypedSystem({ name: "bad", order: ranked })).toThrow("orders its rows without components");
+        expect(() => untypedSystem({ name: "bad", components: { read: [cell] }, up: { through: parent }, order: ranked })).toThrow("uses both up and order");
+        expect(() => untypedSystem({ name: "bad", kernel: "gpu", components: { write: [cell] }, order: ranked })).toThrow("GPU kernels have no order yet");
+        expect(() => untypedSystem({ name: "bad", components: { write: [amount] }, order: ranked })).toThrow(`its rows are ordered by an index keyed by "indexCreateTest/amount", which the system writes`);
+        expect(() => untypedSystem({ name: "bad", kernel: true, components: { write: [amount] }, order: Index.create({ key: [name], sorted: true }) })).toThrow(`ordered by an index keyed by "indexCreateTest/name", a string, which kernels don't read yet`);
+    });
+    it("throw for a render system's order by what isn't a sorted index", () => {
+        const untypedRender = (order: object): unknown => Reflect.apply(System.render, undefined, [giveAccess({ order, shader: { accessors: { amount } } }), () => {}]);
+        expect(() => untypedRender({ name: "fake" })).toThrow(`orders its rows by a value Index.create didn't return`);
+        expect(() => untypedRender(Index.create({ key: [amount] }))).toThrow(/orders its rows by index "index #\d+", which isn't sorted/);
+    });
+});

package/src/interface/indexes/create.ts

@@ -0,0 +1,88 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../component/component.js';
+import type { Shared } from '../component/value.js';
+import { threadOfDeclaration } from '../registry/declarations.js';
+import { takeIdOfDeclaration } from '../registry/ids.js';
+import { addIndex } from '../registry/indexes.js';
+import { nameOf } from '../registry/items.js';
+import { layoutOf } from '../registry/layout.js';
+import { declarationOf, firstKeyOf, kindOf, labelOf, whyUnregistered } from '../registry/names.js';
+import type { Schema } from '../schema/schema.js';
+import type { Listed, Property } from '../system/property.js';
+import type { Created } from './created.js';
+import type { Declaration } from './declaration.js';
+import type { Index } from './index-type.js';
+
+/**
+ * `not` excludes what the index holds by: its key parts and `with`. An index without a key isn't unique. A key part is
+ * a value each entity holds, never a shared component's, which systems filter by with `where`.
+ */
+type Validate<D extends Declaration> = {
+    readonly components?: { readonly not?: readonly Exclude<Component.Key, D["key"][number] | Listed<Property<D, "components">, "with">>[]; readonly has?: never };
+} & (D["key"] extends readonly [] ? { readonly unique?: false } : unknown)
+    & ([D["key"][number] & Shared] extends [never] ? unknown : { readonly key: { readonly "error: a key part is a value each entity holds; filter by a shared component with where": D["key"][number] & Shared } });
+
+/** Whether a schema's values have an order: numbers, booleans, entities and fixed-length tuples of them, and strings. */
+const ordered = (schema: Schema): boolean => {
+    if ("type" in schema && schema.type === "string") return true;
+    const layout = layoutOf(schema);
+    return layout.kind === "linear" && layout.leaves.every(leaf => leaf.path.every(step => typeof step === "number"));
+};
+
+/** Whether a schema's values are sets or maps, which a key part can't be yet. */
+const collection = (schema: Schema): boolean => "type" in schema && (schema.type === "set" || schema.type === "map");
+
+/**
+ * Declares an index over components' values and returns it; nothing is built until a world's system or finalizer uses
+ * it. It holds the entities with every key part and every component in `with`, and none in `not`, keyed by the values
+ * of `key`, compared part by part: numbers and tuples by value, an entity with its generation, so a stale one finds
+ * nothing. With an empty key it holds those entities, every entity but the resource entity when `with` and `not` are
+ * empty too, and its lookup takes no key and gives them all, in entity order.
+ * - `sorted`: keeps key order, numbers numerically, NaN last, booleans false first, strings by code point, tuples
+ *   element by element, then entity order, so a lookup takes a prefix of the key whose last part may be a comparison.
+ * - `unique`: at most one entity per key: a lookup by a whole key returns its row or null. When two entities share a
+ *   key, the one with the lower entity index is kept, and the index fails the run or tick that found them.
+ *
+ * Throws if a key part isn't a registered component of data, is listed twice, is a set or map or shared, a sorted part has no
+ * order, its object parts live on different threads, or on another than the world's beside a string, which the world
+ * keeps its keys of, it's unique without a key, or `with` or `not` names a key that isn't a registered component
+ * or `not` names a key part or a `with` component.
+ */
+export const create = <const D extends Declaration>(declaration: D & Validate<D>): Index<D> => {
+    const id = takeIdOfDeclaration(declaration);
+    const name = nameOf(declaration, id, "index");
+    const fail = (message: string): never => { throw new Error(`Index "${name}" ${message}.`); };
+    const { key, sorted } = declaration;
+    const components = declaration.components === undefined ? undefined : { has: declaration.components.with, not: declaration.components.not };
+    if (!Array.isArray(key)) fail("needs a key: a list of components");
+    if (key.length === 0 && declaration.unique === true) fail("is unique without a key: it holds at most one entity per key");
+    const threads = new Set<string>();
+    const parts = new Set<symbol>();
+    for (const part of key) {
+        const found = declarationOf(part);
+        const type = found?.type;
+        if (kindOf(part) !== "component" || type === undefined) fail(`has key part "${labelOf(part)}", which isn't a registered component of data: ${whyUnregistered(part)}`);
+        else {
+            if (parts.has(firstKeyOf(part))) fail(`lists key part "${labelOf(part)}" twice`);
+            parts.add(firstKeyOf(part));
+            if (collection(type)) fail(`has key part "${labelOf(part)}", a set or map, which a key part can't be yet`);
+            if (found?.shared === true) fail(`has key part "${labelOf(part)}", a shared component: filter by it with where`);
+            if (sorted === true && !ordered(type)) fail(`is sorted by "${labelOf(part)}", whose values have no order: a sorted part is a number, boolean, entity, string or fixed-length tuple of them`);
+            // The world's thread keeps keys of strings, so they hold the index there with its objects.
+            const thread = found === undefined ? null : threadOfDeclaration(found) ?? (layoutOf(type).kind === "string" ? "world" : null);
+            if (thread !== null) threads.add(thread);
+        }
+    }
+    if (threads.size > 1) fail(`has key parts on threads ${[...threads].map(thread => `"${thread}"`).join(" and ")}; its object parts live on one thread, the world's beside a string`);
+    const held = new Set<symbol>(parts);
+    for (const component of components?.has ?? []) {
+        if (kindOf(component) !== "component") fail(`has "${labelOf(component)}", which isn't a registered component: ${whyUnregistered(component)}`);
+        held.add(firstKeyOf(component));
+    }
+    for (const component of components?.not ?? []) {
+        if (kindOf(component) !== "component") fail(`excludes "${labelOf(component)}", which isn't a registered component: ${whyUnregistered(component)}`);
+        if (held.has(firstKeyOf(component))) fail(`excludes "${labelOf(component)}", which it holds by`);
+    }
+    const index: Created = { kind: "index", name, declaration: { ...declaration, ...components === undefined ? {} : { components } } };
+    return addIndex(index, id);
+};

package/src/interface/indexes/created.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Stored } from './declaration.js';
+
+/** What `Index.create` records: its kind, its label and its declaration. */
+export type Created = { readonly kind: "index"; readonly name: string; readonly declaration: Stored };

package/src/interface/indexes/declaration.ts

@@ -0,0 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../component/component.js';
+
+/** What `Index.create` takes, its fields documented there; not exported from the package. */
+export type Declaration = {
+    readonly key: readonly Component.Key[];
+    readonly components?: { readonly with?: readonly Component.Key[]; readonly not?: readonly Component.Key[] };
+    readonly sorted?: boolean;
+    readonly unique?: boolean;
+};
+
+/** An index's declaration as the world takes it: what it requires in `has`. */
+export type Stored = Omit<Declaration, "components"> & {
+    readonly components?: { readonly has?: readonly symbol[]; readonly not?: readonly symbol[] };
+};

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

@@ -0,0 +1,13 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Declaration } from './declaration.js';
+
+declare const declared: unique symbol;
+
+/**
+ * An index, the value `Index.create` returned: identified by that value, labeled by the binding it's declared at. `D`
+ * is the type of the declaration it was created from, which its lookups take their key and rows from; code accepting
+ * any sorted index takes `Index<{ readonly sorted: true }>`.
+ */
+export type Index<D extends object = Declaration> = { readonly name: string; readonly [declared]?: D };
+
+export * as Index from './index.js';

package/src/interface/indexes/index.ts

@@ -0,0 +1,2 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export * from './create.js';

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

@@ -0,0 +1,244 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Component } from '../component/component.js';
+import { Entity } from '../entity/entity.js';
+import { Finalizer } from '../finalizer/finalizer.js';
+import { Vec3 } from '../math/index.js';
+import { System } from '../system/system.js';
+import { Index } from './index-type.js';
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+const cell = Symbol("indexTest/cell");
+const position = Symbol("indexTest/position");
+const velocity = Symbol("indexTest/velocity");
+const serverId = Symbol("indexTest/serverId");
+const health = Symbol("indexTest/health");
+const track = Symbol("indexTest/track");
+const start = Symbol("indexTest/start");
+const clip = Symbol("indexTest/clip");
+const playhead = Symbol("indexTest/playhead");
+const owner = Symbol("indexTest/owner");
+const archived = Symbol("indexTest/archived");
+const label = Symbol("indexTest/label");
+
+declare module '@adobe/ecs' {
+    export interface Components {
+        [cell]: { type: Vec3.I32 };
+        [position]: { type: Vec3 };
+        [velocity]: { type: Vec3 };
+        [serverId]: { type: number };
+        [health]: { type: number };
+        [track]: { type: Entity };
+        [start]: { type: number };
+        [clip]: { type: number };
+        [playhead]: { type: number };
+        [owner]: { type: Entity; reference: "owner" };
+        [archived]: { type: true };
+        [label]: { type: string };
+    }
+}
+
+// An index is typed by its declaration, as written.
+const grid = Index.create({ key: [cell], components: { with: [position] } });
+check<Equal<typeof grid, Index<{ readonly key: readonly [typeof cell]; readonly components: { readonly with: readonly [typeof position] } }>>>();
+const byServerId = Index.create({ key: [serverId], unique: true, components: { with: [health] } });
+const clips = Index.create({ key: [track, start], sorted: true, components: { with: [clip] } });
+const tasksOf = Index.create({ key: [owner], components: { not: [archived] } });
+const named = Index.create({ key: [label, serverId], sorted: true, unique: true });
+// With an empty key, an index holds the entities with every `with` component and no `not` one; with neither, every entity.
+const living = Index.create({ key: [], components: { with: [health], not: [archived] } });
+check<Equal<typeof living, Index<{ readonly key: readonly []; readonly components: { readonly with: readonly [typeof health]; readonly not: readonly [typeof archived] } }>>>();
+const everything = Index.create({ key: [] });
+const inOrder = Index.create({ key: [], sorted: true, components: { with: [start] } });
+// @ts-expect-error a key is a list of components
+Index.create({ key: [health, 3] });
+// @ts-expect-error an index without a key holds no key once
+Index.create({ key: [], unique: true });
+// @ts-expect-error `not` excludes `has`
+Index.create({ key: [], components: { with: [archived], not: [archived] } });
+// @ts-expect-error `not` excludes neither key parts nor `has`
+Index.create({ key: [owner], components: { with: [archived], not: [owner] } });
+
+// Code accepting any sorted index takes `Index<{ readonly sorted: true }>`.
+const sortedOnly = (index: Index<{ readonly sorted: true }>): string => index.name;
+sortedOnly(clips);
+sortedOnly(named);
+// @ts-expect-error a hash index isn't sorted
+sortedOnly(grid);
+const anyIndex: Index = tasksOf;
+// @ts-expect-error an index whose declaration isn't known isn't known to be sorted
+sortedOnly(anyIndex);
+
+// A hash lookup takes the whole key and gives the bucket's rows, with `length`, `changed` and `at`.
+export const separate = System.create({
+    components: { with: [position, cell, velocity] },
+    lookup: { near: { index: grid } },
+}, (row, { lookup }) => {
+    const near = lookup.near(row[cell]);
+    check<Equal<typeof near.length, number>>();
+    check<Equal<typeof near.changed, boolean>>();
+    const other = near.at(0);
+    const value: Vec3 = other[position];
+    const entity: Entity = other.entity;
+    row[velocity] = value;
+    void entity;
+    // @ts-expect-error rows are read-only
+    other[position] = [0, 0, 0];
+    void other[cell];
+    // @ts-expect-error rows hold only what every entity the index holds has
+    void other[velocity];
+    // @ts-expect-error a hash lookup takes the whole key
+    lookup.near();
+    // @ts-expect-error a key part's value has its type
+    lookup.near([0, 0]);
+});
+
+// A unique lookup gives the row or null.
+export const applyDelta = System.create({
+    lookup: { known: { index: byServerId } },
+}, ({ lookup, commands }, input: { readonly id: number; readonly hp: number }) => {
+    const known = lookup.known(input.id);
+    check<Equal<typeof known, ({ readonly entity: Entity } & { readonly [serverId]: number; readonly [health]: number }) | null>>();
+    if (known === null) commands.spawn([serverId, health])({ [serverId]: input.id, [health]: input.hp });
+    else commands.add(known.entity, health, known[health] + input.hp);
+});
+
+// A sorted lookup takes a prefix of the key, whose last part may be a comparison.
+export const cue = System.create({
+    components: { with: [track, playhead] },
+    lookup: { due: { index: clips, changed: [clip] } },
+}, (row, { lookup }) => {
+    const t = row[playhead];
+    const due = lookup.due(row[track], { ">=": t, "<": t + 1 });
+    for (let i = 0; i < due.length; i++) void [due.at(i)[clip], due.at(i)[start]];
+    void lookup.due();
+    void lookup.due({ ">": row[track] });
+    void lookup.due(row[track], t);
+    // @ts-expect-error only the last part given may be a comparison
+    lookup.due({ "==": row[track] }, t);
+});
+
+// A unique sorted lookup gives a row by a whole key of plain values, and rows by anything else.
+System.create({ lookup: { names: { index: named } } }, ({ lookup }) => {
+    const one = lookup.names("a", 1);
+    check<Equal<typeof one, ({ readonly entity: Entity } & { readonly [label]: string; readonly [serverId]: number }) | null>>();
+    const some = lookup.names("a", { ">": 1 });
+    check<Equal<typeof some.length, number>>();
+    const all = lookup.names();
+    void all.at(0)[label];
+});
+
+// A lookup through an index without a key takes none and gives every row it holds, in entity order.
+export const census = System.create({
+    lookup: { living: { index: living, changed: [health] }, all: { index: everything }, ordered: { index: inOrder } },
+}, ({ lookup }) => {
+    const rows = lookup.living();
+    check<Equal<typeof rows.length, number>>();
+    check<Equal<typeof rows.changed, boolean>>();
+    check<Equal<ReturnType<typeof rows.at>, { readonly entity: Entity } & { readonly [health]: number }>>();
+    void lookup.all().at(0).entity;
+    void lookup.ordered().at(0)[start];
+    // @ts-expect-error a lookup without a key takes none
+    lookup.living(1);
+    // @ts-expect-error rows hold only what every entity the index holds has
+    void lookup.all().at(0)[health];
+});
+System.create({
+    kernel: true,
+    components: { with: [velocity] },
+    lookup: { living: { index: living } },
+}, () => {});
+System.create({ components: { with: [start, playhead] }, order: inOrder }, row => {
+    row[playhead] = row[start];
+});
+
+// Finalizers look up through indexes too.
+Finalizer.create({ components: { with: [owner] }, lookup: { tasks: { index: tasksOf } } }, (row, { lookup }) => {
+    const tasks = lookup.tasks(row[owner]);
+    void tasks.at(0).entity;
+});
+
+
+System.create({
+    components: { with: [cell] },
+    // @ts-expect-error an index lookup watches only what every entity the index holds has
+    lookup: { near: { index: grid, changed: [velocity] } },
+}, () => {});
+
+
+System.create({
+    kernel: true,
+    components: { with: [cell, velocity] },
+    lookup: { near: { index: grid } },
+}, () => {});
+
+System.create({
+    kernel: true,
+    components: { with: [cell, velocity] },
+    lookup: { near: { index: grid, changed: [position] } },
+}, () => {});
+
+
+System.create({
+    kernel: "gpu",
+    components: { with: [velocity] },
+    // @ts-expect-error GPU kernels can't use lookups
+    lookup: { near: { index: grid } },
+}, () => {});
+
+// `order` runs a system's rows in a sorted index's order.
+System.create({ components: { with: [start, playhead] }, order: clips }, row => {
+    row[playhead] = row[start];
+});
+System.create({ kernel: true, components: { with: [start, playhead] }, order: clips }, row => {
+    row[playhead] = row[start];
+});
+// A sorted index typed by its declaration is one of `Index<{ readonly sorted: true }>`.
+const ordering: Index<{ readonly sorted: true }> = clips;
+void ordering;
+// @ts-expect-error a hash index has no order
+System.create({ components: { with: [velocity] }, order: grid }, () => {});
+// @ts-expect-error a hash index isn't one of `Index<{ readonly sorted: true }>`
+const unordered: Index<{ readonly sorted: true }> = grid;
+void unordered;
+// @ts-expect-error a system without components runs once, in no order
+System.create({ order: clips }, () => {});
+System.create({
+    components: { with: [clip, playhead] },
+    up: { through: owner },
+    // @ts-expect-error `up` orders rows too
+    order: clips,
+}, () => {});
+System.create({
+    kernel: "gpu",
+    components: { with: [velocity] },
+    // @ts-expect-error GPU kernels have no order yet
+    order: clips,
+}, () => {});
+
+// An index lookup's `changed: true` runs its system only when the index's entries changed since it last ran: its
+// lists' `changed` then reports entries alone. Observer systems and CPU kernels take it; it's not a list of components.
+System.create({ observer: true, lookup: { living: { index: living, changed: true } } }, ({ lookup }) => {
+    const rows = lookup.living();
+    check<Equal<typeof rows.changed, boolean>>();
+    check<Equal<typeof rows.length, number>>();
+});
+System.create({ components: { with: [cell] }, lookup: { near: { index: grid, changed: true } } }, (row, { lookup }) => {
+    void lookup.near(row[cell]).at(0)[position];
+});
+System.create({
+    kernel: true,
+    components: { with: [cell, velocity] },
+    lookup: { near: { index: grid, changed: true } },
+}, () => {});
+System.create({
+    // @ts-expect-error only an index lookup's `changed` may be true
+    lookup: { player: { with: [health], changed: true } },
+}, () => {});
+System.create({
+    // @ts-expect-error `changed` is true or a list of components
+    lookup: { living: { index: living, changed: false } },
+}, () => {});
+// @ts-expect-error a finalizer runs on each entity that stops matching, so its lookups' `changed` is never true
+Finalizer.create({ components: { with: [owner] }, lookup: { tasks: { index: tasksOf, changed: true } } }, () => {});

package/src/interface/math/f32/default.ts

@@ -0,0 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { F32 } from "./index.js";
+
+/** What a value of this type starts at. */
+const start: F32 = 0;
+export { start as default };

package/src/interface/math/f32/index.ts

@@ -0,0 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from "../../schema/schema.js";
+import type { schema } from "./schema.js";
+
+export type F32 = Schema.Type<typeof schema>;
+
+export * as F32 from "./public.js";

package/src/interface/math/f32/public.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export * from "./schema.js";
+export { default } from "./default.js";

package/src/interface/math/f32/round-half-even.ts

@@ -0,0 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/** Rounds to the nearest integer, and halfway values to the even one, as WGSL's `round` does. */
+export const roundHalfEven = (x: number): number => {
+    const rounded = Math.round(x);
+    return rounded - x === 0.5 && Math.floor(rounded * 0.5) * 2 !== rounded ? rounded - 1 : rounded;
+};

package/src/interface/math/f32/schema.ts

@@ -0,0 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from "../../schema/schema.js";
+
+export const schema = { type: "number", precision: 1 } as const satisfies Schema;

package/src/interface/math/i32/default.ts

@@ -0,0 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { I32 } from "./index.js";
+
+/** What a value of this type starts at. */
+const start: I32 = 0;
+export { start as default };

package/src/interface/math/i32/index.ts

@@ -0,0 +1,8 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from "../../schema/schema.js";
+import type { schema } from "./schema.js";
+
+/** Integers in [-2^31, 2^31). Functions wrap as WGSL's i32 does; for other values their results are indeterminate. */
+export type I32 = Schema.Type<typeof schema>;
+
+export * as I32 from "./public.js";

package/src/interface/math/i32/public.ts

@@ -0,0 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export { schema } from "./schema.js";
+export { shiftRight } from "./shift-right.js";
+export { default } from "./default.js";

package/src/interface/math/i32/schema.ts

@@ -0,0 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from "../../schema/schema.js";
+
+export const schema = { type: "integer", minimum: -2147483648, maximum: 2147483647 } as const satisfies Schema;