@adobe/ecs 0.1.0 → 0.2.0

package/src/interface/finalizer/declaration.ts

@@ -1,25 +1,27 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component } from '../component/component.js';
-import type { Resource } from '../resource/resource.js';
+import type { SystemLookupLists, ResourceLists } from '../system/access.js';
 import type { Lookup } from '../system/access.js';
 import type { Finalizer } from './finalizer.js';
-import type { Name } from './name.js';
 import type { Essential } from '../component/value.js';
-import type { Reduced } from '../resource/reduction.js';
-import type { WorldWritten } from '../resource/written.js';
 
+/**
+ * What every finalizer declares. What its body reads of its row and lookups, and reads and writes of resources, the
+ * build infers; resource writes take the sync point's tick, so each system sees them once.
+ */
 type Shared = {
-    readonly name?: Name;
     /** Read-only access to other entities, as they are before the sync point applies. */
     readonly lookup?: { readonly [name: string]: Lookup };
-    /** Writes take the sync point's tick, so each system sees them once. A resource in `write` is also readable. */
-    readonly resources?: { readonly read?: readonly Resource.Key[]; readonly write?: readonly Exclude<Resource.Key, Reduced | WorldWritten>[] };
     readonly before?: readonly Finalizer[];
     readonly after?: readonly Finalizer[];
 };
 
-/** A finalizer that runs for each entity that stops matching its components. */
+/**
+ * A finalizer that runs for each entity that stops matching its components: those with every one in `with` and none in
+ * `not`. Its `optional` components, which never decide a stop, its row reads where the entity had them.
+ */
 export type Declaration = Shared & {
-    readonly components: { readonly read?: readonly Component.Key[]; readonly has?: readonly Component.Key[]; readonly not?: readonly Component.Key[] };
+    readonly components: { readonly with?: readonly Component.Key[]; readonly optional?: readonly Component.Key[]; readonly not?: readonly Component.Key[] };
 };
 
 /**
@@ -27,3 +29,20 @@ export type Declaration = Shared & {
  * isn't derived or an object a joined thread fills.
  */
 export type ChangesDeclaration = Shared & { readonly watch?: readonly Essential[] };
+
+type Key = symbol;
+
+/** What every finalizer's declaration holds as the world takes it, with what the build inferred its body uses. */
+type ResolvedShared = {
+    readonly lookup?: { readonly [name: string]: SystemLookupLists };
+    readonly resources?: Pick<ResourceLists, "read" | "write">;
+    readonly before?: readonly Finalizer[];
+    readonly after?: readonly Finalizer[];
+};
+
+/** A finalizer's declaration as the world takes it: what its body reads of its row in `read`, the rest of `with` in `has`. */
+export type Resolved = ResolvedShared & {
+    readonly components: { readonly read?: readonly Key[]; readonly has?: readonly Key[]; readonly optional?: readonly Key[]; readonly not?: readonly Key[] };
+};
+
+export type ResolvedChanges = ResolvedShared & { readonly watch?: readonly Key[] };

package/src/interface/finalizer/finalizer.ts

@@ -1,6 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /**
- * A finalizer, the value `Finalizer.create` or `Finalizer.changes` returned: identified by that value, labeled by its
- * name, and listed in other finalizers' `before` and `after`.
+ * A finalizer, the value `Finalizer.create` or `Finalizer.changes` returned: identified by that value, labeled by
+ * `name`, the binding it's declared at, and listed in other finalizers' `before` and `after`.
  */
 export type Finalizer = { readonly name: string };
 

package/src/interface/finalizer/index.ts

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

package/src/interface/gpu/accessors.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { layoutOf, type Leaf } from '../registry/layout.js';
 import { declarationOf } from '../registry/index.js';
 import type { Shader } from '../system/render.js';
@@ -27,18 +28,20 @@ const reserved = new Set(("alias break case const const_assert continue continui
 
 /**
  * Accessors for a render system's shader, in `accessors` order, or the reason one can't be read on the GPU: scalars
- * and tuples of two to four scalars of one type, laid out in 4-byte words.
+ * and tuples of two to four scalars of one type, laid out in 4-byte words. An `ordered` system's accessors take a
+ * row's position in its order, which `ecs_address` resolves to a table's column.
  */
-export const accessorsOf = (shader: Shader): readonly Accessor[] | string => {
+export const accessorsOf = (shader: Shader, ordered = false): readonly Accessor[] | string => {
     const accessors: Accessor[] = [];
     const entries = Object.entries(shader.accessors);
     // A table record is a row count, then a word address per accessor.
     if (entries.length > 63) return "it names more than 63 accessors";
-    for (const [name, key] of entries) {
+    for (const [column, [name, key]] of entries.entries()) {
         const component = labelOf(key);
         if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(name) || name.startsWith("ecs_") || reserved.has(name)) return `"${name}" isn't usable as a WGSL function name`;
         const declaration = declarationOf(key);
         if (declaration === undefined) return `"${component}" has no registered schema`;
+        if (declaration.shared === true) return `"${component}" is shared, so it has no column: its value is its archetype's`;
         const layout = layoutOf(declaration.type);
         if (layout.kind !== "linear") return `"${component}" isn't stored in linear memory`;
         const { leaves, stride } = layout;
@@ -47,26 +50,41 @@ export const accessorsOf = (shader: Shader): readonly Accessor[] | string => {
             return `"${component}" isn't laid out in 4-byte words of f32, i32, u32 or booleans; give it a "storage" or "vertex" layout or 4-byte scalars`;
         }
         const words = stride / 4;
-        const word = (leaf: Leaf): string => `ecs_table.ecs_${name} + row * ${words}u + ${leaf.offset / 4}u`;
+        const word = ordered
+            ? (leaf: Leaf): string => `ecs_base + ${leaf.offset / 4}u`
+            : (leaf: Leaf): string => `ecs_table.ecs_${name} + row * ${words}u + ${leaf.offset / 4}u`;
+        const base = ordered ? `let ecs_base = ecs_address(row, ${column}u, ${words}u); ` : "";
         const [first] = leaves;
         if (leaves.length === 1 && first.path.length === 0) {
-            accessors.push({ name, component: key, code: `fn ${name}(row: u32) -> ${types[0]} { return ${readOf(first, word(first))}; }` });
+            accessors.push({ name, component: key, code: `fn ${name}(row: u32) -> ${types[0]} { ${base}return ${readOf(first, word(first))}; }` });
             continue;
         }
         const tuple = leaves.length >= 2 && leaves.length <= 4 && leaves.every((leaf, i) => leaf.path.length === 1 && leaf.path[0] === i && types[i] === types[0]);
         if (!tuple) return `"${component}" isn't a scalar or a tuple of two to four scalars of one type`;
         const items = leaves.map(leaf => readOf(leaf, word(leaf))).join(", ");
-        accessors.push({ name, component: key, code: `fn ${name}(row: u32) -> vec${leaves.length}<${types[0]}> { return vec${leaves.length}<${types[0]}>(${items}); }` });
+        accessors.push({ name, component: key, code: `fn ${name}(row: u32) -> vec${leaves.length}<${types[0]}> { ${base}return vec${leaves.length}<${types[0]}>(${items}); }` });
     }
     return accessors;
 };
 
 /** The WGSL declarations of a render system's bind group and accessors. */
-export const declarationsOf = (group: number, accessors: readonly Accessor[]): string => [
+export const declarationsOf = (group: number, accessors: readonly Accessor[], ordered = false): string => [
     `@group(${group}) @binding(0) var<storage, read> ecs_heap: array<u32>;`,
-    `struct EcsTable { ecs_rows: u32, ${accessors.map(accessor => `ecs_${accessor.name}: u32`).join(", ")} }`,
+    ordered
+        ? "struct EcsTable { ecs_rows: u32, ecs_order: u32, ecs_tables: u32, ecs_shift: u32 }"
+        : `struct EcsTable { ecs_rows: u32, ${accessors.map(accessor => `ecs_${accessor.name}: u32`).join(", ")} }`,
     `@group(${group}) @binding(1) var<uniform> ecs_table: EcsTable;`,
     `fn ecs_count() -> u32 { return ecs_table.ecs_rows; }`,
+    ...ordered ? [orderedAddress(accessors.length)] : [],
     ...accessors.map(accessor => accessor.code),
     "",
 ].join("\n");
+
+/**
+ * The word address of a column's value at a position of an ordered system's order. The order block holds, by position,
+ * a table's slot above `ecs_shift` bits and its row below them; the tables block holds, by slot, a word address per
+ * accessor.
+ */
+const orderedAddress = (columns: number): string =>
+    "fn ecs_address(row: u32, column: u32, words: u32) -> u32 { let ecs_entry = ecs_heap[ecs_table.ecs_order + row]; "
+    + `return ecs_heap[ecs_table.ecs_tables + (ecs_entry >> ecs_table.ecs_shift) * ${columns}u + column] + (ecs_entry & ((1u << ecs_table.ecs_shift) - 1u)) * words; }`;

package/src/interface/gpu/gpu.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /** `Gpu.wgsl` and `Gpu.layout` give render systems' shaders and pipelines what they need from schemas alone. */
 export type Gpu = never;
 

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { Component } from '../component/component.js';
 import type { Gpu } from '../index.js';
 import { System } from '../system/system.js';
@@ -11,7 +12,6 @@ declare module '@adobe/ecs' {
         [tint]: { type: number };
     }
 }
-Component.register(tint, { type: { type: "number" } });
 
 declare const wgsl: typeof Gpu.wgsl;
 declare const layout: typeof Gpu.layout;
@@ -21,7 +21,7 @@ export type Wgsl = Gpu.Wgsl;
 export type Layout = Gpu.Layout;
 check<Equal<typeof Gpu.wgsl, (system: System<unknown>) => string>>();
 declare const device: GPUDevice;
-const draw = System.render({ name: "gpuTypeTest/draw", shader: { accessors: { tint } } }, () => {});
+const draw = System.render({ shader: { accessors: { tint } } }, () => {});
 const code: string = wgsl(draw);
 check<Equal<typeof Gpu.layout, (device: GPUDevice) => GPUBindGroupLayout>>();
 export const used = [code, layout(device)];

package/src/interface/gpu/index.ts

@@ -1,2 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 export { layout } from './layout.js';
 export { wgsl } from './wgsl.js';

package/src/interface/gpu/layout.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { recordBytes } from './record.js';
 
 const layouts = new WeakMap<GPUDevice, GPUBindGroupLayout>();

package/src/interface/gpu/record.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /**
  * Bytes per parameter or table record, the dynamic offset alignment WebGPU guarantees. A record is `u32` words: a
  * row count, then a word address in the heap per column, then, for kernels, scalars as f32 bits.

package/src/interface/gpu/wgsl.ts

@@ -1,20 +1,23 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { definitionOf } from '../registry/index.js';
-import type { Name } from '../system/name.js';
 import type { System } from '../system/system.js';
 import { accessorsOf, declarationsOf } from './accessors.js';
 
 /**
  * The WGSL a render system's shaders include: its bind group at `shader.group` (the heap and its table record), and a
  * function per accessor returning that component of a row, such as `fn position(row: u32) -> vec3<f32>`, plus
- * `ecs_count()`. Depends only on registered schemas, so pipelines can be built before any world exists.
+ * `ecs_count()`. For a system with `order`, `row` is an instance's position in its order and `ecs_count()` the number
+ * of instances. Depends only on registered schemas, so pipelines can be built before any world exists.
  * Throws if the system isn't a render system or a component can't be read on the GPU.
  */
 export const wgsl = (system: System<unknown>): string => {
     const definition = definitionOf(system);
-    const shader = definition?.kind === "render" ? definition.declaration.shader : undefined;
-    if (shader === undefined) throw new Error(`System "${system.name}" isn't a render system.`);
+    const declaration = definition?.kind === "render" ? definition.declaration : undefined;
+    const shader = declaration?.shader;
+    if (declaration === undefined || shader === undefined) throw new Error(`System "${system.name}" isn't a render system.`);
     const { name } = system;
-    const accessors = accessorsOf(shader);
+    const ordered = declaration.order !== undefined;
+    const accessors = accessorsOf(shader, ordered);
     if (typeof accessors === "string") throw new Error(`Render system "${name}": ${accessors}.`);
-    return declarationsOf(shader.group ?? 0, accessors);
+    return declarationsOf(shader.group ?? 0, accessors, ordered);
 };

package/src/interface/index.ts

@@ -1,4 +1,4 @@
-export { Archetype } from './archetype/archetype.js';
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 export { Component } from './component/component.js';
 export { Entity } from './entity/entity.js';
 export { Finalizer } from './finalizer/finalizer.js';
@@ -6,12 +6,10 @@ export { Gpu } from './gpu/gpu.js';
 export { Index } from './indexes/index-type.js';
 export * from './math/index.js';
 export * from './resources/index.js';
-export { Report } from './report/report.js';
 export { Resource } from './resource/resource.js';
 export { Rule } from './rule/rule.js';
 export type { Schema } from './schema/schema.js';
 export { System } from './system/system.js';
-export { Trait } from './trait/trait.js';
 export type { World } from './world/world.js';
 export type { Components } from './component/types.js';
 export type { Resources } from './resource/types.js';

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

@@ -1,3 +1,4 @@
+// © 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";
@@ -17,21 +18,17 @@ declare module "@adobe/ecs" {
         [scale]: { type: number };
     }
 }
-Component.register(position, { type: { type: "number" } });
-Component.register(slot, { type: { type: "number", default: 0 }, derived: true });
-Component.register(element, { thread: "main" });
-Resource.register(scale, { type: { type: "number", default: 1 } });
-export const move = System.create({ name: "indexTypeTest/move", components: { write: [position] }, resources: { read: [scale] } }, (row, { resources }) => { row[position] += resources[scale]; });
-export const show = System.create({ name: "indexTypeTest/show", components: { read: [position], write: [element] } }, row => { row[element].textContent = String(row[position]); });
-export const all = System.create({ name: "indexTypeTest/all", systems: [move, show] });
-export const draw = System.render({ name: "indexTypeTest/draw", shader: { accessors: { place: position } } }, () => {});
-export const release = Finalizer.create({ name: "indexTypeTest/release", components: { read: [element] } }, row => { row[element].remove(); });
-Rule.create({ name: "indexTypeTest/slots", components: { has: [position] }, derive: [slot] });
+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({ name: "indexTypeTest/read", observer: true, components: { read: [position, slot] }, resources: { read: [gpuDevice, workers] } }, () => {});
-export const readOne = System.create({ observer: true, lookup: { at: { read: [position], has: [slot] } } }, () => {});
+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);
@@ -42,8 +39,8 @@ 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: { has: [position] }, derive: [slot] });
-// @ts-expect-error an archetype is a readonly list of components
+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;

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[] };
+};