@adobe/ecs 0.1.0 → 0.2.1

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

@@ -1,13 +1,16 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
-import { Component } from "../component/component.js";
+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, labelOfItem, requireDefinition } from "../registry/index.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");
@@ -23,7 +26,7 @@ const view = Symbol("indexCreateTest/view");
 
 declare module "@adobe/ecs" {
     export interface Components {
-        [cell]: { type: readonly [number, number] };
+        [cell]: { type: Vec2.I32 };
         [point]: { type: { readonly x: number; readonly y: number } };
         [amount]: { type: number };
         [name]: { type: string };
@@ -35,38 +38,28 @@ declare module "@adobe/ecs" {
         [view]: { type: { readonly label: string }; thread: "main" };
     }
 }
-Component.register(cell, { type: { type: "array", items: { type: "integer", minimum: -1000, maximum: 1000 }, minItems: 2, maxItems: 2 } });
-Component.register(point, { type: { type: "object", properties: { x: { type: "number" }, y: { type: "number" } }, required: ["x", "y"] } });
-Component.register(amount, { type: { type: "number" } });
-Component.register(name, { type: { type: "string" } });
-Component.register(node, { type: { type: "object", properties: { label: { type: "string" } } } });
-Component.register(tags, { type: { type: "set", items: { type: "string" } } });
-Component.register(shown, { type: { const: true } });
-Component.register(parent, { type: Entity.schema, reference: "owner" });
-Component.register(handle, {});
-Component.register(view, { type: { type: "object", properties: { label: { type: "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({ name: "indexCreateTest/named", key: [amount] });
-        expect(named.name).toBe("indexCreateTest/named");
+        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 (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({ name: "indexCreateTest/again", key: [cell], components: { has: [shown] } }, "i.ts#again"));
-        expect(Index.create(identify({ name: "indexCreateTest/again", key: [cell], components: { has: [shown] } }, "i.ts#again"))).toBe(first);
-        expect(() => Index.create(identify({ name: "indexCreateTest/again", key: [amount] }, "i.ts#again"))).toThrow("reload the page");
+        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({ name: "indexCreateTest/again", key: [cell], components: { has: [shown] } })).not.toBe(first);
+        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(`Index "bad" needs a key`);
-        expect(() => untyped({ name: "bad", key: amount })).toThrow(`Index "bad" needs a key`);
+        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`);
@@ -74,10 +67,10 @@ describe("Index.create", () => {
     });
     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: { has: [amount], not: [shown] } })).not.toThrow();
-        expect(() => untyped({ name: "bad", key: [], unique: true })).toThrow(`Index "bad" is unique without a key`);
-        expect(() => untyped({ name: "bad", key: [], components: { has: [shown], not: [shown] } })).toThrow("which it holds by");
-        expect(() => untyped({ name: "bad", key: [], components: { has: [unregistered] } })).toThrow("isn't a registered component");
+        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();
@@ -89,21 +82,22 @@ describe("Index.create", () => {
     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: { has: [unregistered] } })).toThrow("isn't a registered component");
+        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: { has: [shown], not: [shown] } })).toThrow("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({ name: "indexCreateTest/grid", key: [cell], components: { has: [amount] } });
-    const untypedSystem = (declaration: object): unknown => Reflect.apply(System.create, undefined, [declaration, () => {}]);
+    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({ name: "indexCreateTest/reader", lookup: { near: { index: grid, read: [amount] } } }, ({ lookup }) => { void lookup.near([0, 0]).at(0)[amount]; });
+        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({ name: "indexCreateTest/writer", components: { write: [cell] } }, row => { row[cell] = [0, 0]; });
+        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] });
@@ -111,35 +105,42 @@ describe("systems and finalizers looking up through an index", () => {
     });
     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 "indexCreateTest/grid" holds has`);
+        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: "cpu", components: { write: [amount] }, lookup: { near: { index: Index.create({ key: [name] }) } } })).toThrow(`keyed by "indexCreateTest/name", a string, which kernels don't read yet`);
-        expect(() => Reflect.apply(Finalizer.create, undefined, [{ name: "bad", components: { read: [amount] }, lookup: { near: { index: grid, read: [name] } } }, () => {}])).toThrow(`Finalizer "bad": lookup "near" reads`);
-        expect(labelOfItem(grid)).toBe("indexCreateTest/grid");
+        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({ name: "indexCreateTest/ranked", key: [amount], sorted: true, components: { has: [cell] } });
-    const untypedSystem = (declaration: object): unknown => Reflect.apply(System.create, undefined, [declaration, () => {}]);
+    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({ name: "indexCreateTest/ordered", components: { read: [cell] }, order: ranked }, row => { void row[cell]; });
+        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({ name: "indexCreateTest/rankWriter", components: { write: [amount] } }, row => { row[amount] = 0; });
+        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(`System "bad" orders its rows by a value Index.create didn't return`);
-        expect(() => untypedSystem({ name: "bad", components: { read: [cell] }, order: Index.create({ name: "indexCreateTest/hashed", key: [amount] }) })).toThrow(`orders its rows by index "indexCreateTest/hashed", which isn't sorted`);
+        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: "cpu", 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`);
+        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

@@ -1,20 +1,26 @@
+// © 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 } from '../registry/names.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 `has`. An index without a key isn't unique. */
+/**
+ * `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">, "has">>[] };
-} & (D["key"] extends readonly [] ? { readonly unique?: false } : unknown);
+    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 => {
@@ -28,25 +34,26 @@ const collection = (schema: Schema): boolean => "type" in schema && (schema.type
 
 /**
  * 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 `has`, and none in `not`, keyed by the values
+ * 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 `has` and `not` are
+ * 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 run that found them reports an `"index"` failure.
+ *   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 or is a set or map, a sorted part has no
+ * 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 `has` or `not` names a key that isn't a registered component
- * or `not` names a key part or a `has` component.
+ * 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.name, id, "index");
+    const name = nameOf(declaration, id, "index");
     const fail = (message: string): never => { throw new Error(`Index "${name}" ${message}.`); };
-    const { key, components, sorted } = declaration;
+    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>();
@@ -54,11 +61,12 @@ export const create = <const D extends Declaration>(declaration: D & Validate<D>
     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`);
+        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);
@@ -68,13 +76,13 @@ export const create = <const D extends Declaration>(declaration: D & Validate<D>
     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`);
+        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`);
+        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 };
+    const index: Created = { kind: "index", name, declaration: { ...declaration, ...components === undefined ? {} : { components } } };
     return addIndex(index, id);
 };

package/src/interface/indexes/created.ts

@@ -1,4 +1,5 @@
-import type { Declaration } from './declaration.js';
+// © 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: Declaration };
+export type Created = { readonly kind: "index"; readonly name: string; readonly declaration: Stored };

package/src/interface/indexes/declaration.ts

@@ -1,11 +1,15 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component } from '../component/component.js';
-import type { Name } from './name.js';
 
 /** What `Index.create` takes, its fields documented there; not exported from the package. */
 export type Declaration = {
-    readonly name?: Name;
     readonly key: readonly Component.Key[];
-    readonly components?: { readonly has?: readonly Component.Key[]; readonly not?: 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

@@ -1,11 +1,12 @@
+// © 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 its name. `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 }>`.
+ * 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 };
 

package/src/interface/indexes/index.ts

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

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

@@ -1,3 +1,4 @@
+// © 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';
@@ -37,39 +38,27 @@ declare module '@adobe/ecs' {
         [label]: { type: string };
     }
 }
-Component.register(cell, { type: Vec3.I32.schema });
-Component.register(position, { type: Vec3.schema });
-Component.register(velocity, { type: Vec3.schema });
-Component.register(serverId, { type: { type: "number" } });
-Component.register(health, { type: { type: "number" } });
-Component.register(track, { type: Entity.schema });
-Component.register(start, { type: { type: "number" } });
-Component.register(clip, { type: { type: "number" } });
-Component.register(playhead, { type: { type: "number" } });
-Component.register(owner, { type: Entity.schema, reference: "owner" });
-Component.register(archived, { type: { const: true } });
-Component.register(label, { type: { type: "string" } });
 
 // An index is typed by its declaration, as written.
-const grid = Index.create({ name: "indexTest/grid", key: [cell], components: { has: [position] } });
-check<Equal<typeof grid, Index<{ readonly name: "indexTest/grid"; readonly key: readonly [typeof cell]; readonly components: { readonly has: readonly [typeof position] } }>>>();
-const byServerId = Index.create({ key: [serverId], unique: true, components: { has: [health] } });
-const clips = Index.create({ key: [track, start], sorted: true, components: { has: [clip] } });
+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 `has` component and no `not` one; with neither, every entity.
-const living = Index.create({ key: [], components: { has: [health], not: [archived] } });
-check<Equal<typeof living, Index<{ readonly key: readonly []; readonly components: { readonly has: readonly [typeof health]; readonly not: readonly [typeof archived] } }>>>();
+// 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: { has: [start] } });
+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: { has: [archived], not: [archived] } });
+Index.create({ key: [], components: { with: [archived], not: [archived] } });
 // @ts-expect-error `not` excludes neither key parts nor `has`
-Index.create({ key: [owner], components: { has: [archived], not: [owner] } });
+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;
@@ -83,8 +72,8 @@ 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: { read: [position, cell], write: [velocity] },
-    lookup: { near: { index: grid, read: [position] } },
+    components: { with: [position, cell, velocity] },
+    lookup: { near: { index: grid } },
 }, (row, { lookup }) => {
     const near = lookup.near(row[cell]);
     check<Equal<typeof near.length, number>>();
@@ -96,8 +85,9 @@ export const separate = System.create({
     void entity;
     // @ts-expect-error rows are read-only
     other[position] = [0, 0, 0];
-    // @ts-expect-error rows hold only the lookup's read
     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
@@ -106,19 +96,18 @@ export const separate = System.create({
 
 // A unique lookup gives the row or null.
 export const applyDelta = System.create({
-    input: { type: "object", properties: { id: { type: "number" }, hp: { type: "number" } } },
-    lookup: { known: { index: byServerId, read: [health] } },
-}, ({ input, lookup, commands }) => {
+    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 [health]: number }) | null>>();
+    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: { read: [track, playhead] },
-    lookup: { due: { index: clips, read: [clip, start], changed: [clip] } },
+    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 });
@@ -131,9 +120,9 @@ export const cue = System.create({
 });
 
 // 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, read: [label] } } }, ({ lookup }) => {
+System.create({ lookup: { names: { index: named } } }, ({ lookup }) => {
     const one = lookup.names("a", 1);
-    check<Equal<typeof one, ({ readonly entity: Entity } & { readonly [label]: string }) | null>>();
+    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();
@@ -142,7 +131,7 @@ System.create({ lookup: { names: { index: named, read: [label] } } }, ({ lookup
 
 // 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, read: [health], changed: [health] }, all: { index: everything }, ordered: { index: inOrder, read: [start] } },
+    lookup: { living: { index: living, changed: [health] }, all: { index: everything }, ordered: { index: inOrder } },
 }, ({ lookup }) => {
     const rows = lookup.living();
     check<Equal<typeof rows.length, number>>();
@@ -156,115 +145,77 @@ export const census = System.create({
     void lookup.all().at(0)[health];
 });
 System.create({
-    kernel: "cpu",
-    components: { write: [velocity] },
-    lookup: { living: { index: living, read: [health] } },
+    kernel: true,
+    components: { with: [velocity] },
+    lookup: { living: { index: living } },
 }, () => {});
-System.create({
-    components: { write: [health] },
-    // @ts-expect-error a system doesn't write what it reads through an index
-    lookup: { living: { index: living, read: [health] } },
-}, () => {});
-System.create({ components: { read: [start], write: [playhead] }, order: inOrder }, row => {
+System.create({ components: { with: [start, playhead] }, order: inOrder }, row => {
     row[playhead] = row[start];
 });
 
 // Finalizers look up through indexes too.
-Finalizer.create({ components: { read: [owner] }, lookup: { tasks: { index: tasksOf } } }, (row, { lookup }) => {
+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: { read: [cell] },
-    // @ts-expect-error an index lookup reads only what every entity the index holds has
-    lookup: { near: { index: grid, read: [velocity] } },
-}, () => {});
 
 System.create({
-    components: { read: [cell] },
+    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({
-    components: { write: [cell] },
-    // @ts-expect-error a system doesn't write what it finds rows by
-    lookup: { near: { index: grid } },
-}, () => {});
-
-System.create({
-    components: { write: [position] },
-    // @ts-expect-error a system doesn't write what it reads through an index
-    lookup: { near: { index: grid, read: [position] } },
-}, () => {});
 
 System.create({
-    kernel: "cpu",
-    components: { read: [cell], write: [velocity] },
-    lookup: { near: { index: grid, read: [position] } },
+    kernel: true,
+    components: { with: [cell, velocity] },
+    lookup: { near: { index: grid } },
 }, () => {});
 
 System.create({
-    kernel: "cpu",
-    components: { read: [cell], write: [velocity] },
+    kernel: true,
+    components: { with: [cell, velocity] },
     lookup: { near: { index: grid, changed: [position] } },
 }, () => {});
 
-System.create({
-    kernel: "cpu",
-    components: { write: [velocity] },
-    // @ts-expect-error kernels look up only through indexes of struct keys
-    lookup: { names: { index: named } },
-}, () => {});
 
 System.create({
     kernel: "gpu",
-    components: { write: [velocity] },
+    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: { read: [start], write: [playhead] }, order: clips }, row => {
+System.create({ components: { with: [start, playhead] }, order: clips }, row => {
     row[playhead] = row[start];
 });
-System.create({ kernel: "cpu", components: { read: [start], write: [playhead] }, order: clips }, row => {
+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: { write: [velocity] }, order: grid }, () => {});
+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: { read: [clip], write: [playhead] },
+    components: { with: [clip, playhead] },
     up: { through: owner },
     // @ts-expect-error `up` orders rows too
     order: clips,
 }, () => {});
-System.create({
-    components: { write: [start] },
-    // @ts-expect-error a system doesn't write what its rows are ordered by
-    order: clips,
-}, () => {});
 System.create({
     kernel: "gpu",
-    components: { write: [velocity] },
+    components: { with: [velocity] },
     // @ts-expect-error GPU kernels have no order yet
     order: clips,
 }, () => {});
-System.create({
-    kernel: "cpu",
-    components: { write: [velocity] },
-    // @ts-expect-error kernels are ordered only by indexes of struct keys
-    order: named,
-}, () => {});
 
 // 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.
@@ -273,21 +224,21 @@ System.create({ observer: true, lookup: { living: { index: living, changed: true
     check<Equal<typeof rows.changed, boolean>>();
     check<Equal<typeof rows.length, number>>();
 });
-System.create({ components: { read: [cell] }, lookup: { near: { index: grid, read: [position], changed: true } } }, (row, { lookup }) => {
+System.create({ components: { with: [cell] }, lookup: { near: { index: grid, changed: true } } }, (row, { lookup }) => {
     void lookup.near(row[cell]).at(0)[position];
 });
 System.create({
-    kernel: "cpu",
-    components: { read: [cell], write: [velocity] },
+    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: { read: [health], changed: 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: { read: [owner] }, lookup: { tasks: { index: tasksOf, changed: 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 };