@adobe/ecs 0.1.0 → 0.2.0

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

@@ -1,4 +1,4 @@
-import type { IsData } from "./is-data.js";
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { IsStruct } from "./is-struct.js";
 import type { Schema } from "./schema.js";
 
@@ -134,20 +134,22 @@ const badSetForm: Schema = { type: 'set', keys: { type: 'string' }, values: { ty
 const badMapForm: Schema = { type: 'map', items: { type: 'string' } };
 void [okSet, okMap, badSet, badMap, badSetForm, badMapForm];
 
-// A ReadonlySet or ReadonlyMap of data is data; a Set or Map, which changes in place, isn't, nor one holding functions.
-check<Equal<IsData<ReadonlySet<string>>, true>>();
-check<Equal<IsData<ReadonlyMap<string, { readonly x: number }>>, true>>();
-check<Equal<IsData<ReadonlySet<() => void>>, false>>();
-check<Equal<IsData<Set<string>>, false>>();
-check<Equal<IsData<Map<string, number>>, false>>();
-// An object is data only when every member is: a record of handles isn't, however deep they are.
-check<Equal<IsData<{ readonly context: GPUCanvasContext; readonly canvas: HTMLCanvasElement }>, false>>();
-check<Equal<IsData<{ readonly pipelines: { readonly fill: GPURenderPipeline } }>, false>>();
-check<Equal<IsData<{ readonly items: readonly { readonly blob: Blob }[] }>, false>>();
-check<Equal<IsData<{ readonly at: readonly [number, number]; readonly label?: string; readonly nested: { readonly x: number } }>, true>>();
-// A recursive data type is still data.
-type Tree = { readonly value: number; readonly children: readonly Tree[] };
-check<Equal<IsData<Tree>, true>>();
-// Neither is a struct: neither lives in shared memory.
+// A set or map isn't a struct: neither lives in shared memory.
 check<Equal<IsStruct<ReadonlySet<number>>, false>>();
 check<Equal<IsStruct<ReadonlyMap<number, number>>, false>>();
+
+// Schema.Type is the plain type a schema describes, so a type named by it is that type: a number or a tuple, unbranded.
+type Level = Schema.Type<{ type: "integer"; minimum: 0; maximum: 9 }>;
+check<Equal<Level, number>>();
+check<Equal<Schema.Type<{ type: "array"; items: { type: "number"; precision: 1 }; minItems: 3; maxItems: 3 }>, readonly [number, number, number]>>();
+// @ts-expect-error its argument is a schema
+type NotSchema = Schema.Type<{ type: "integer"; minimum: "zero" }>;
+
+// A schema holds no default, anywhere: a value's start comes from its declaration or its type's namespace.
+// @ts-expect-error a default isn't part of a schema
+const badDefault: Schema = { type: 'number', default: 0 };
+// @ts-expect-error nor of a field's schema
+const badFieldDefault: Schema = { type: 'object', properties: { x: { type: 'number', default: 0 } } };
+// @ts-expect-error Schema.Type takes a schema, so a default fails there too
+type BadType = Schema.Type<{ type: 'integer'; minimum: 1; default: 5 }>;
+void [badDefault, badFieldDefault];

package/src/interface/schema/schemas.type-test.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Schema } from "./schema.js";
 
 const ok: Schema.ForType<true> = { const: true };

package/src/interface/system/access.ts

@@ -1,37 +1,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component } from '../component/component.js';
 import type { Resource } from '../resource/resource.js';
-import type { Writable } from '../component/value.js';
 import type { Condition } from '../resource/condition.js';
-import type { Reduced } from '../resource/reduction.js';
-import type { WorldWritten } from '../resource/written.js';
 import type { Index } from '../indexes/index-type.js';
+import type { Shared } from '../component/value.js';
+import type { ReadResources } from './body.js';
 
 /**
- * Matches every component in `read`, `write`, `has`, `added` and `changed`, and excludes `not`. A component in `write`
- * is also readable, so it's never listed in `read` as well.
+ * The entities a system runs over: those with every component in `with`, `added` and `changed`, and none in `not`.
+ * What its body reads and writes of them the build infers from the body.
  */
 export type ComponentAccess = {
-    readonly read?: readonly Component.Key[];
-    /** A component holding a `reference` changes only through commands, so it can't be written here. */
-    readonly write?: readonly Writable[];
-    readonly has?: readonly Component.Key[];
+    readonly with?: readonly Component.Key[];
+    /** Components its rows hold where an entity has them, `undefined` where it doesn't; they never narrow what it matches. */
+    readonly optional?: readonly Component.Key[];
     readonly not?: readonly Component.Key[];
     /** Passes rows where any of these were added since the system last ran. */
     readonly added?: readonly Component.Key[];
     /** Passes rows where any of these may have changed since the system last ran. */
     readonly changed?: readonly Component.Key[];
+    /**
+     * Keeps the system to the archetypes whose shared components' values pass, each one required as `with` requires
+     * it: a value passes the archetypes holding an equal one, a predicate those it returns true for. A predicate reads
+     * its value and the world's resources, never anything else that may change, and runs as written on the thread
+     * that runs the system, once per archetype as it appears and again whenever a resource it reads changed. With
+     * change filters, an archetype it skipped keeps its rows unseen until it passes again.
+     */
+    readonly where?: { readonly [K in Shared]?: Component.Value<K> | ((value: Component.Value<K>, context: { readonly resources: ReadResources }) => boolean) };
 };
 
 /**
- * Read-only access to other entities: by entity, matching `read`, `has` and `not`, or through an index by key. A lookup
- * by entity's `changed` names components it reads or has, whose changes its row's `changed` reports. An index lookup's
- * `read` names components every entity the index holds has, its key parts or its `has`, and its `changed` the ones
- * whose changes its lists' `changed` reports. Both report as a system's `changed` filter does; its system can't write a
- * key part or what it reads.
+ * Read-only access to other entities: by entity, matching `with` and `not`, its `optional` components read where an
+ * entity has them, or through an index by key, whose rows hold what every entity the index holds has. What the body reads of them the build infers. A lookup by entity's
+ * `changed` names components in `with`, whose changes its row's `changed` reports, and an index lookup's those of its
+ * rows. Both report as a system's `changed` filter does; its system can't write a key part or what it reads.
  */
 export type Lookup =
-    | Pick<ComponentAccess, "read" | "has" | "not"> & { readonly changed?: readonly Component.Key[] }
-    | { readonly index: Index; readonly read?: readonly Component.Key[]; readonly changed?: readonly Component.Key[] };
+    | { readonly with?: readonly Component.Key[]; readonly optional?: readonly Component.Key[]; readonly not?: readonly Component.Key[]; readonly changed?: readonly Component.Key[]; readonly index?: never }
+    | { readonly index: Index; readonly changed?: readonly Component.Key[]; readonly with?: never; readonly optional?: never; readonly not?: never };
 
 /**
  * A system's lookup. An index lookup's `changed: true` makes the index a change filter, as a resource in `changed` is:
@@ -40,24 +46,17 @@ export type Lookup =
  * when a condition fails, keeping its `lastRun`. Its lists' `changed` then reports those changes alone. Only on the
  * world's thread.
  */
-export type SystemLookup =
-    | Lookup
-    | { readonly index: Index; readonly read?: readonly Component.Key[]; readonly changed: true };
+export type SystemLookup = Lookup | { readonly index: Index; readonly changed: true };
 
 /**
  * The parent each row's values flow down from: the entity its `through` reference names, read before the row. Rows
- * run parent first, so a parent's value is the one written earlier in the same run, and `read` may name components the
- * system writes.
+ * run parent first, so a parent's value is the one written earlier in the same run. The context's `up` holds the
+ * parent's values the body reads, or null for a row without a parent or whose parent lacks one of them.
  */
-export type Up = { readonly through: Component.With<"reference">; readonly read?: readonly Component.Key[] };
+export type Up = { readonly through: Component.With<"reference"> };
 
-/**
- * A resource in `write` is also readable, so it's never listed in `read` as well. Reduced resources are never written,
- * nor are those only the world writes.
- */
+/** The resources a system filters and is conditioned on; what its body reads, writes and reduces the build infers. */
 export type ResourceAccess = {
-    readonly read?: readonly Resource.Key[];
-    readonly write?: readonly Exclude<Resource.Key, Reduced | WorldWritten>[];
     /** Passes every row when any of these changed since the system last ran. */
     readonly changed?: readonly Resource.Key[];
     /** Runs only while each of these is neither `null` nor `false`, and reads it as such. Otherwise it's skipped, successfully. */
@@ -65,3 +64,44 @@ export type ResourceAccess = {
     /** Runs only while each of these is `null` or `false`. Otherwise it's skipped, successfully. */
     readonly not?: readonly Condition[];
 };
+
+/** A key, as the world takes declarations: their lists come from the build, untyped. */
+type Key = symbol;
+
+/**
+ * What a system reads and writes, as the world takes it: the build's inferred access joined with its declaration.
+ * Matches every component in `read`, `write`, `has`, `added` and `changed` but those in `optional`, and excludes `not`.
+ */
+export type ComponentLists = {
+    /** Members its rows hold only where an entity has them; those it uses are in `read` or `write` too. */
+    readonly optional?: readonly Key[];
+    readonly read?: readonly Key[];
+    readonly write?: readonly Key[];
+    readonly has?: readonly Key[];
+    readonly not?: readonly Key[];
+    readonly added?: readonly Key[];
+    readonly changed?: readonly Key[];
+    /** Its `where`, by shared component: a value, or a predicate of it and the resources. Its keys are in `has` or `read`. */
+    readonly where?: { readonly [key: symbol]: unknown };
+    /** The resources its `where`'s predicates read, which the build infers: when one changed, they're evaluated again. */
+    readonly whereReads?: readonly Key[];
+};
+
+/** A lookup as the world takes it, with what its body reads of its rows in `read`. */
+export type LookupLists =
+    | { readonly read?: readonly Key[]; readonly has?: readonly Key[]; readonly optional?: readonly Key[]; readonly not?: readonly Key[]; readonly changed?: readonly Key[] }
+    | { readonly index: Index; readonly read?: readonly Key[]; readonly changed?: readonly Key[] };
+
+export type SystemLookupLists = LookupLists | { readonly index: Index; readonly read?: readonly Key[]; readonly changed: true };
+
+export type UpLists = { readonly through: Key; readonly read?: readonly Key[] };
+
+/** A system's resources as the world takes them. */
+export type ResourceLists = {
+    readonly read?: readonly Key[];
+    readonly write?: readonly Key[];
+    readonly reduce?: readonly Key[];
+    readonly changed?: readonly Key[];
+    readonly is?: readonly Key[];
+    readonly not?: readonly Key[];
+};

package/src/interface/system/body.ts

@@ -1,49 +1,79 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component } from '../component/component.js';
+import type { Writable } from '../component/value.js';
 import type { Entity } from '../entity/entity.js';
 import type { Resource } from '../resource/resource.js';
 import type { Holding } from '../resource/condition.js';
-import type { Schema } from '../schema/schema.js';
+import type { Reduced } from '../resource/reduction.js';
+import type { WorldWritten } from '../resource/written.js';
 import type { Commands } from './commands.js';
 import type { Declaration } from './declaration.js';
 import type { Listed, Property } from './property.js';
 import type { RenderContext } from './render.js';
 import type { ComponentValues, LookupFunction, ResourceValues, Values } from './values.js';
 
-/** `read` values are read-only, `write` values readable and writable. */
+/** The components every entity a declaration matches has: those in `with`, `added` and `changed`. */
+export type Members<D> =
+    | Listed<Property<D, "components">, "with"> | Listed<Property<D, "components">, "added"> | Listed<Property<D, "components">, "changed">;
+
+/** Whether a declaration only reads: an observer or a render system. */
+type Reading<D> = D extends { readonly observer: true } | { readonly shader: object } ? true : false;
+
+/** The components a declaration's rows hold only where an entity has them. */
+export type Optional<D> = Exclude<Listed<Property<D, "components">, "optional">, Members<D>>;
+
+/** Each optional component's value or `undefined`, as `ComponentValues` gives members'. */
+type OptionalValues = { readonly [K in Component.Key]: Component.Value<K> | undefined };
+
+/**
+ * Its members' values, writable but for references and shared components, and in a system that only reads; its
+ * optional components' too, or `undefined` where an entity lacks one, which assigning to fails the system. A shared
+ * component reads as its archetype's value, which only `commands.add` changes, by moving the entity.
+ */
 export type Row<D extends Declaration> =
     { readonly entity: Entity }
-    & Values<Listed<Property<D, "components">, "read">, Listed<Property<D, "components">, "write">, Component.Key, ComponentValues>;
+    & Values<Members<D>, Reading<D> extends true ? never : Members<D> & Writable, Component.Key, ComponentValues>
+    & Values<Optional<D>, Reading<D> extends true ? never : Optional<D> & Writable, Component.Key, OptionalValues>;
+
+/** Resources systems write: every one but those reduced, which only their contributors' fold sets, and those only the world writes. */
+type Writes = Exclude<Resource.Key, Reduced | WorldWritten>;
+
+/** Every resource, read-only. */
+export type ReadResources = Values<Resource.Key, never, Resource.Key, ResourceValues>;
+
+/** Every resource, writable as `Writes` says. */
+export type WriteResources = Values<Resource.Key, Writes, Resource.Key, ResourceValues>;
+
+/** Each reduced resource, as a function contributing a value to the run's fold. */
+type Reductions = { readonly [K in Reduced]: (value: Resource.Value<K>) => void };
 
-type Resources<D> = Listed<Property<D, "resources">, "read"> | Listed<Property<D, "resources">, "write"> | Is<D>;
 type Is<D> = Listed<Property<D, "resources">, "is">;
-type Reduced<D> = keyof Property<D, "reduce"> & Resource.Key;
 
 /**
- * What a body uses besides its row, by kind, under the declaration's own keys: each is present only when the
- * declaration declares something of its kind. `commands` is there for every system but a GPU kernel, a render system
- * and an observer system.
+ * What a body uses besides its row: every resource, its lookups by name, the resources it may reduce into, its
+ * parent's values with `up`, and its commands, there for every system but a GPU kernel, a render system and an
+ * observer system. The build infers which of them the body reads and writes.
  */
 export type Context<D extends Declaration> =
-    ([Resources<D>] extends [never] ? {} : {
-        readonly resources: Values<Listed<Property<D, "resources">, "read">, Listed<Property<D, "resources">, "write">, Resource.Key, ResourceValues>
-            & { readonly [K in Is<D> & Resource.Key]: Holding<K> };
-    })
+    {
+        readonly resources: (Reading<D> extends true ? ReadResources : WriteResources) & { readonly [K in Is<D> & Resource.Key]: Holding<K> };
+    }
     & ([keyof Property<D, "lookup">] extends [never] ? {} : {
         readonly lookup: { readonly [K in keyof Property<D, "lookup">]: LookupFunction<Property<D, "lookup">[K]> };
     })
-    & ([Reduced<D>] extends [never] ? {} : {
-        /** Each resource it reduces into, as a function contributing a value to the run's fold. */
-        readonly reduce: { readonly [K in Reduced<D>]: (value: Resource.Value<K>) => void };
-    })
-    & (Property<D, "input"> extends Schema ? { readonly input: Schema.ToType<Property<D, "input">> } : {})
+    & (Reading<D> extends true ? {} : { readonly reduce: Reductions })
     & (Property<D, "up"> extends object ? {
-        /** The parent's `up.read` values, or null for a row without a parent. */
-        readonly up: { readonly [K in Listed<Property<D, "up">, "read"> & Component.Key]: Component.Value<K> } | null;
+        /** The parent's values the body reads, or null for a row without a parent or whose parent lacks one of them. */
+        readonly up: ComponentValues | null;
     } : {})
     & (D extends { readonly kernel: "gpu" } | { readonly shader: object } | { readonly observer: true } ? {} : { readonly commands: Commands });
 
-/** `(row, context)` for a system with `components`, `(context)` for one without, and `(gpu, context)` for a render system. */
-export type Body<D extends Declaration> =
+/**
+ * `(row, context, input)` for a system with `components`, `(context, input)` for one without, and `(gpu, context)` for
+ * a render system. `input` is the value each run passes, of the type the body gives its parameter; a body without one
+ * takes none.
+ */
+export type Body<D extends Declaration, I = undefined> =
     D extends { readonly shader: object } ? (gpu: RenderContext, context: Context<D>) => void :
-    Property<D, "components"> extends undefined ? (context: Context<D>) => void :
-    (row: Row<D>, context: Context<D>) => void;
+    D extends { readonly components: object } ? (row: Row<D>, context: Context<D>, input: I) => void :
+    (context: Context<D>, input: I) => void;

package/src/interface/system/check.ts

@@ -1,16 +1,16 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { layoutOf } from '../registry/layout.js';
-import { declarationOf, kindOf, labelOf } from '../registry/names.js';
+import { declarationOf, kindOf, labelOf, whyUnregistered } from '../registry/names.js';
 import { definitionOf } from '../registry/program.js';
 import { reducedBy, scheduleOf } from '../registry/schedule.js';
-import { conditional } from '../registry/schemas.js';
+import { conditional, matchesSchema } from '../registry/schemas.js';
 import { requireRegistered, threadOf } from '../registry/threads.js';
 import { checkWorldWritten } from '../registry/written.js';
 import { checkLookup, indexDefinitionOf, lookupKeysOf, orderKeysOf } from '../registry/indexes.js';
-import { labelOfItem } from '../registry/items.js';
 import type { Schema } from '../schema/schema.js';
 import type { Composite } from './composite.js';
 import type { Definition } from './definition.js';
-import type { Leaf } from './leaf.js';
+import type { InputSchema, Leaf } from './leaf.js';
 
 type Key = symbol;
 
@@ -22,18 +22,15 @@ const checkLists = (name: string, what: string, lists: { readonly read?: readonl
 };
 
 /**
- * Throws if a leaf reduces into a resource with an operator its `reduce` trait doesn't declare, or also reads, writes
- * or filters on it, or writes a resource that's reduced, which only its contributors' fold sets.
+ * Throws if a leaf reduces into a resource without a `reduce` trait, which gives the operator it folds with, or also
+ * reads, writes or filters on it, or writes a resource that's reduced, which only its contributors' fold sets.
  */
 const checkReductions = (leaf: Leaf): void => {
     const { name } = leaf;
-    const { reduce, resources } = leaf.declaration;
+    const { resources } = leaf.declaration;
     const others = new Set<Key>([...resources?.read ?? [], ...resources?.write ?? [], ...resources?.changed ?? []]);
     for (const key of reducedBy(leaf)) {
-        const declared = declarationOf(key)?.reduce;
-        const operator: unknown = Reflect.get(reduce ?? {}, key);
-        if (declared === undefined) throw new Error(`System "${name}" reduces "${labelOf(key)}", which has no reduce trait.`);
-        if (declared !== operator) throw new Error(`System "${name}" reduces "${labelOf(key)}" with "${labelOf(operator)}", but it's declared reduce: "${labelOf(declared)}".`);
+        if (declarationOf(key)?.reduce === undefined) throw new Error(`System "${name}" reduces "${labelOf(key)}", which has no reduce trait.`);
         if (others.has(key)) throw new Error(`System "${name}" reduces "${labelOf(key)}", so it can't also read, write or filter on it.`);
     }
     for (const key of resources?.write ?? []) {
@@ -53,7 +50,7 @@ const checkConditions = (leaf: Leaf): void => {
     const listed = new Set<Key>([...resources?.read ?? [], ...resources?.write ?? []]);
     for (const key of [...is, ...not]) {
         const declaration = declarationOf(key);
-        if (kindOf(key) !== "resource" || declaration === undefined) throw new Error(`System "${name}" runs on the condition of "${labelOf(key)}", which isn't a registered resource.`);
+        if (kindOf(key) !== "resource" || declaration === undefined) throw new Error(`System "${name}" runs on the condition of "${labelOf(key)}", which isn't a registered resource: ${whyUnregistered(key)}.`);
         const { type } = declaration;
         if (type !== undefined && !conditional(type)) throw new Error(`System "${name}" runs on the condition of "${labelOf(key)}", which is never null or false.`);
     }
@@ -69,6 +66,30 @@ const unreadByKernels = (key: symbol): string | null => {
     return kind === "object" ? "which isn't stored in linear memory" : kind === "string" ? "a string, which kernels don't read yet" : null;
 };
 
+/**
+ * What of a leaf's ordering index and lookups a kernel can't read, or null: workers read them from shared memory, so
+ * their values must be linear there too.
+ */
+export const unreadByKernel = (leaf: Leaf): string | null => {
+    const { lookup, order } = leaf.declaration;
+    if (order !== undefined) {
+        for (const key of orderKeysOf(leaf.declaration)) {
+            const unread = unreadByKernels(key);
+            if (unread !== null) return `its rows are ordered by an index keyed by "${labelOf(key)}", ${unread}`;
+        }
+    }
+    const lookups = Object.values(lookup ?? {});
+    for (const key of lookups.flatMap(found => found.read ?? [])) {
+        const unread = unreadByKernels(key);
+        if (unread !== null) return `a lookup reads "${labelOf(key)}", ${unread}`;
+    }
+    for (const key of lookups.flatMap(lookupKeysOf)) {
+        const unread = unreadByKernels(key);
+        if (unread !== null) return `a lookup goes through an index keyed by "${labelOf(key)}", ${unread}`;
+    }
+    return null;
+};
+
 /**
  * Throws for what a leaf's kind and placement rule out: `up` without components or through a key that isn't a reference
  * component, `order` by anything but a sorted index, without components, with `up` or on the GPU, a kernel's lookup of
@@ -82,16 +103,10 @@ const checkPlacement = (leaf: Leaf): void => {
     if (order !== undefined) {
         const index = indexDefinitionOf(order);
         if (index === undefined) fail("orders its rows by a value Index.create didn't return");
-        else if (index.declaration.sorted !== true) fail(`orders its rows by index "${labelOfItem(index)}", which isn't sorted`);
+        else if (index.declaration.sorted !== true) fail(`orders its rows by index "${index.name}", which isn't sorted`);
         if (components === undefined) fail("orders its rows without components, so it runs once");
         if (up !== undefined) fail("uses both up and order, which both decide the order of its rows");
         if (kernel === "gpu") fail("can't run on the GPU: GPU kernels have no order yet");
-        if (kernel !== undefined) {
-            for (const key of orderKeysOf(leaf.declaration)) {
-                const unread = unreadByKernels(key);
-                if (unread !== null) throw new Error(`Kernel "${name}": its rows are ordered by an index keyed by "${labelOf(key)}", ${unread}.`);
-            }
-        }
     }
     if (up !== undefined) {
         if (components === undefined) fail("uses up, which orders rows, without components");
@@ -100,16 +115,9 @@ const checkPlacement = (leaf: Leaf): void => {
         }
     }
     const lookups = Object.values(lookup ?? {});
-    if (kernel !== undefined) {
-        // Workers read lookups from shared memory, so their values must be linear there too.
-        for (const key of lookups.flatMap(found => found.read ?? [])) {
-            const unread = unreadByKernels(key);
-            if (unread !== null) throw new Error(`Kernel "${name}": a lookup reads "${labelOf(key)}", ${unread}.`);
-        }
-        for (const key of lookups.flatMap(lookupKeysOf)) {
-            const unread = unreadByKernels(key);
-            if (unread !== null) throw new Error(`Kernel "${name}": a lookup goes through an index keyed by "${labelOf(key)}", ${unread}.`);
-        }
+    if (kernel === true || kernel === "gpu") {
+        const unread = unreadByKernel(leaf);
+        if (unread !== null) throw new Error(`Kernel "${name}": ${unread}.`);
     }
     const reduces = reducedBy(leaf).length > 0;
     if (kernel === "gpu") {
@@ -121,6 +129,23 @@ const checkPlacement = (leaf: Leaf): void => {
     if ((leaf.declaration.shader !== undefined) !== (leaf.kind === "render")) fail("has a shader only when System.render makes it");
 };
 
+/**
+ * Throws for a `where` naming what isn't a shared component, giving one a value not of its type, or with `up`, `order`
+ * or a target, which run rows across archetypes.
+ */
+const checkWhere = (leaf: Leaf): void => {
+    const { name, declaration } = leaf;
+    const where = declaration.components?.where;
+    if (where === undefined) return;
+    if (declaration.up !== undefined || declaration.order !== undefined || declaration.target !== undefined) throw new Error(`System "${name}" uses where with up, order or a target, which run rows across archetypes.`);
+    for (const key of Object.getOwnPropertySymbols(where)) {
+        const found = declarationOf(key);
+        if (kindOf(key) !== "component" || found?.shared !== true) throw new Error(`System "${name}": where names "${labelOf(key)}", which isn't a shared component: where keeps a system to archetypes by their shared values.`);
+        const value: unknown = Reflect.get(where, key);
+        if (typeof value !== "function" && found.type !== undefined && !matchesSchema(found.type, value)) throw new Error(`System "${name}": where gives "${labelOf(key)}" ${labelOf(value)}, which isn't one of its type's values.`);
+    }
+};
+
 /**
  * Throws for what an observer system can't declare: it only reads, after a sync point, so it writes and reduces into
  * nothing, takes no input, isn't a kernel or a render system, has no `up`, and is ordered with nothing.
@@ -132,23 +157,22 @@ const checkObserver = (leaf: Leaf): void => {
     const fail = (message: string): never => { throw new Error(`System "${name}" is an observer, so it ${message}.`); };
     if (observer !== true) throw new Error(`System "${name}": observer is true or left out.`);
     if (leaf.kind === "render") fail("records no GPU work");
-    if (declaration.kernel !== undefined) fail("isn't a kernel");
+    if (declaration.kernel === true || declaration.kernel === "gpu") fail("isn't a kernel");
     if ((declaration.components?.write?.length ?? 0) + (declaration.resources?.write?.length ?? 0) > 0) fail("writes nothing");
     if (reducedBy(leaf).length > 0) fail("reduces into nothing");
-    if (declaration.input !== undefined) fail("takes no input");
+    if (leaf.input !== undefined) fail("takes no input");
     if (declaration.up !== undefined) fail("has no up");
     if ((declaration.before?.length ?? 0) + (declaration.after?.length ?? 0) + (declaration.during?.length ?? 0) > 0) fail("is ordered with nothing");
 };
 
 /**
  * Throws for a leaf that names a component or resource that isn't registered as one, lists a key in both `read` and
- * `write`, writes a reference, has a lookup reading a component it writes, takes input that isn't an object schema,
- * uses object components and resources of different threads, declares what an observer system can't, or whose
+ * `write`, writes a reference, has a lookup reading a component it writes, uses object components and resources of different threads, declares what an observer system can't, or whose
  * reductions, conditions, `up` or placement can't hold.
  */
 export const checkLeaf = (leaf: Leaf): void => {
     const { name, declaration } = leaf;
-    const { components, resources, lookup, input } = declaration;
+    const { components, resources, lookup } = declaration;
     checkLists(name, "components", components);
     checkLists(name, "resources", resources);
     checkWorldWritten(`System "${name}"`, resources?.write);
@@ -165,12 +189,6 @@ export const checkLeaf = (leaf: Leaf): void => {
     for (const key of orderKeysOf(declaration)) {
         if (writes.has(key)) throw new Error(`System "${name}": its rows are ordered by an index keyed by "${labelOf(key)}", which the system writes.`);
     }
-    if (input !== undefined) {
-        const schema: Schema = input;
-        if (!("type" in schema) || schema.type !== "object" || typeof schema.properties !== "object" || schema.properties === null) {
-            throw new Error(`System "${name}": input is an object schema of named fields.`);
-        }
-    }
     checkTarget(leaf);
     threadOf(declaration, "System", name);
     requireRegistered("System", name, "component", components?.has);
@@ -182,28 +200,48 @@ export const checkLeaf = (leaf: Leaf): void => {
     }
     for (const key of components?.write ?? []) {
         if (declarationOf(key)?.reference !== undefined) throw new Error(`System "${name}" writes "${labelOf(key)}", a reference, which changes only through commands.`);
+        if (declarationOf(key)?.shared === true) throw new Error(`System "${name}" writes "${labelOf(key)}", a shared component, whose value is its archetype's: give it another with commands.add.`);
     }
     checkObserver(leaf);
+    checkWhere(leaf);
     checkReductions(leaf);
     checkConditions(leaf);
     checkPlacement(leaf);
 };
 
+const isInputSchema = (value: unknown): value is InputSchema =>
+    typeof value === "object" && value !== null && Reflect.get(value, "type") === "object"
+    && typeof Reflect.get(value, "properties") === "object" && Reflect.get(value, "properties") !== null;
+
+/**
+ * The schema of a body's input, which the plugin passes from the type of its parameter after the `before` before it.
+ * Throws for a body taking input without one, as one not built with the plugin does, and for a schema that isn't an
+ * object of named fields.
+ */
+export const inputSchemaOf = (name: string, body: (...parameters: never[]) => void, before: number, input: unknown): InputSchema | undefined => {
+    if (input === undefined) {
+        if (body.length > before) throw new Error(`System "${name}" takes input, whose schema the plugin gives from the type of its body's parameter: write its body in place and build it with Compiler.plugin().`);
+        return undefined;
+    }
+    if (!isInputSchema(input)) throw new Error(`System "${name}": input is an object schema of named fields.`);
+    return input;
+};
+
 /**
  * Throws if a system on one entity takes it from what isn't an entity field of its input, has no components, or is a
  * kernel, has `up` or `order`, or reduces.
  */
 const checkTarget = (leaf: Leaf): void => {
-    const { name, declaration } = leaf;
-    const { target, input, components, kernel, up, order, reduce } = declaration;
+    const { name, declaration, input } = leaf;
+    const { target, components, kernel, up, order, resources } = declaration;
     if (target === undefined) return;
     const fail = (message: string): never => { throw new Error(`System "${name}" runs on one entity, so it ${message}.`); };
     const field: Schema | undefined = input !== undefined && "properties" in input ? Reflect.get(input.properties, target) : undefined;
     if (field === undefined || !("format" in field) || field.format !== "entity") fail(`takes it from an input field "${target}" holding an entity`);
     if (components === undefined) fail("needs components");
-    if (kernel !== undefined) fail("isn't a kernel");
+    if (kernel === true || kernel === "gpu") fail("isn't a kernel");
     if (up !== undefined || order !== undefined) fail("has no up or order");
-    if (reduce !== undefined) fail("reduces into nothing");
+    if ((resources?.reduce?.length ?? 0) > 0) fail("reduces into nothing");
 };
 
 /** Every leaf under a system, each once. Throws for a member no System constructor returned. */

package/src/interface/system/commands.ts

@@ -1,21 +1,66 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component } from '../component/component.js';
 import type { Entity } from '../entity/entity.js';
-import type { Essential } from '../component/value.js';
-import type { ValuesOf } from '../archetype/values-of.js';
+import type { Essential, Shared } from '../component/value.js';
+import type { ValuesOf } from './values-of.js';
 
 /** The value an `add` of one component takes: none for a tag. */
 type ValueArgument<K extends Essential> = Component.Value<K> extends true ? [value?: true] : [value: Component.Value<K>];
 
+/** Values of components of `C` a spawner's first call may give, constant for every entity it spawns. */
+type Preset<C extends readonly Essential[]> = { readonly [K in C[number]]?: Component.Value<K> };
+
+/** The value of each shared component of `C`, which a spawner's first call must give, since they choose the archetype. */
+type SharedPreset<C extends readonly Essential[]> = { readonly [K in C[number] & Shared]: Component.Value<K> };
+
+/**
+ * Whether `C` names a shared component, so a spawner of it takes its constants: a list that isn't a tuple, whose
+ * components aren't known until it runs, may take them or not.
+ */
+type RequiresPreset<C extends readonly Essential[]> = number extends C["length"] ? false : [C[number] & Shared] extends [never] ? false : true;
+
+/** A preset naming only components of `C`: any other key's value is a message naming it. Written in place, so keys print. */
+type Named<C extends readonly Essential[], P> = { readonly [K in Exclude<keyof P, C[number]>]: { readonly "error: a constant names a component of the spawn's list": { readonly [Q in K]: "isn't one" } } };
+
+/**
+ * The list of a spawn, which, when it names a shared component and no constants are given, is a message naming them:
+ * the spawn takes their values first.
+ */
+type Spawned<C extends readonly Essential[], P> = RequiresPreset<C> extends true
+    ? [keyof P] extends [never] ? C & { readonly "error: a spawn of a shared component takes its value first, in its constants": { readonly [K in C[number] & Shared]: Component.Value<K> } } : C
+    : C;
+
+/** Each component of `C` the constants `P` gave, whose value a spawn's values give again as a message naming it. */
+type Again<C extends readonly Essential[], P> = { readonly [K in keyof P & C[number]]?: { readonly "error: a spawn gives each component's value in one of its calls, this one in its constants": { readonly [Q in K]: "given" } } };
+
+/**
+ * What a spawner with constants `P` of the components `C` takes: the rest of each entity's values, exactly, or nothing
+ * once none of them is required.
+ */
+type SpawnValues<C extends readonly Essential[], P> = number extends C["length"]
+    ? [values: ValuesOf<C, keyof P>]
+    : {} extends ValuesOf<C, keyof P> ? [values?: Rest<C, P>] : [values: Rest<C, P>];
+
+/** The values a spawner's call gives: the rest, and with constants, each component they gave as a message. */
+type Rest<C extends readonly Essential[], P> = [keyof P & C[number]] extends [never] ? ValuesOf<C, keyof P> : ValuesOf<C, keyof P> & Again<C, P>;
+
 /**
  * Structural changes and writes to other entities, applied in issue order at the next sync point. They take only the
  * components commands may add: every one but those rules derive.
  */
 export type Commands = {
     /**
-     * The spawner of entities of exactly `components`: the same function for a world and list each time, so calling
-     * it allocates nothing. It returns a real entity immediately, alive at the sync point.
+     * The spawner of entities of exactly `components`: on the world's thread, the same function for a world, list and
+     * equal constants each time while an archetype holds each shared value among them, so calling it allocates
+     * nothing; on a joined thread, the same for a list and one constants object, found by its identity. `constant` gives values every entity it spawns starts with: each shared
+     * component's, which the spawner must be given, since they choose the archetype, and any other's. Its call takes the
+     * rest, or nothing once none of them is required, each component's value from one of the two, never both, which
+     * fails the system; it returns a real entity immediately, alive at the sync point.
      */
-    spawn<const C extends readonly Essential[]>(components: C): (values: ValuesOf<C>) => Entity;
+    spawn<const C extends readonly Essential[], const P extends Preset<C> = {}>(
+        components: Spawned<C, P>,
+        ...constant: RequiresPreset<C> extends true ? [constant?: P & SharedPreset<C> & Named<C, P>] : [constant?: P & Named<C, P>]
+    ): (...values: SpawnValues<C, P>) => Entity;
     despawn(entity: Entity): void;
     /** Adds or replaces one component's value, marking it changed. */
     add<K extends Essential>(entity: Entity, component: K, ...value: ValueArgument<K>): void;

package/src/interface/system/commands.type-test.ts

@@ -1,6 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { Resource } from '../resource/resource.js';
 import { Component } from '../component/component.js';
-import { Archetype } from '../archetype/archetype.js';
 import type { Entity } from '../entity/entity.js';
 import type { Commands } from './commands.js';
 
@@ -25,14 +25,8 @@ declare module '@adobe/ecs' {
         [time]: { type: number };
     }
 }
-Component.register(position, { type: { type: "number" } });
-Component.register(velocity, { type: { type: "number" } });
-Component.register(label, { type: { anyOf: [{ type: "string" }, { type: "null" }] } });
-Component.register(player, { type: { const: true } });
-Component.register(slot, { type: { type: "number", default: 0 }, derived: true });
-Resource.register(time, { type: { type: "number", default: 0 } });
 
-const particle = Archetype.create([position, velocity, label, player]);
+const particle = [position, velocity, label, player] as const;
 
 export const issue = (commands: Commands, entity: Entity): void => {
     // `spawn` is curried: the components first, then their values, giving an entity.