@adobe/ecs 0.1.0 → 0.2.0

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { Resource } from '../resource/resource.js';
 import { Component } from '../component/component.js';
 import { Finalizer } from '../finalizer/finalizer.js';
@@ -33,82 +34,50 @@ declare module '@adobe/ecs' {
         [time]: { type: number };
     }
 }
-Resource.register(settings, { type: { anyOf: [{ type: "object", properties: { name: { type: "string" } } }, { type: "null" }], default: null } });
-Component.register(node, { thread: "main" });
-Component.register(label, { type: { type: "string" } });
-Component.register(audio, { thread: "threadsTypeTest" });
-Component.register(position, { type: { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2 } });
-Component.register(tags, { type: { type: "array", items: { type: "string" } } });
-Resource.register(document, { thread: "main" });
-Resource.register(time, { type: { type: "number", default: 0 } });
 
-// A system runs on the thread of the object components and resources it uses; strings and structs go with any.
-System.create({ name: "threadsTypeTest/render", components: { read: [position], write: [node] }, resources: { read: [time, document] } }, () => {});
-System.create({ name: "threadsTypeTest/play", components: { read: [audio, position] } }, () => {});
-System.create({ name: "threadsTypeTest/label", components: { write: [label] }, resources: { is: [settings] } }, () => {});
-// Presence-only lists don't place a system.
-System.create({ name: "threadsTypeTest/count", components: { read: [label], has: [node], not: [audio] }, resources: { read: [time] } }, () => {});
-System.create({ name: "threadsTypeTest/paused", components: { read: [node] }, resources: { not: [settings] } }, () => {});
-System.create({ name: "threadsTypeTest/caption", components: { read: [label], write: [node] } }, () => {});
-System.create({ name: "threadsTypeTest/captionChanged", components: { read: [node], changed: [label] }, lookup: { labels: { read: [label] } } }, () => {});
+// A system runs on the thread of the object components and resources it uses; strings and structs go with any. Its
+// type places it by what it filters on, conditions and lookup keys; what its body uses places it at registration.
+System.create({ components: { with: [position, node] } }, () => {});
+System.create({ components: { with: [audio, position] } }, () => {});
+System.create({ components: { with: [label] }, resources: { is: [settings] } }, () => {});
+System.create({ components: { with: [label, node], not: [audio] } }, () => {});
+System.create({ components: { with: [node] }, resources: { not: [settings] } }, () => {});
+System.create({ components: { with: [node], changed: [label] }, lookup: { labels: { with: [label] } } }, () => {});
+System.create({ components: { with: [tags, node] } }, () => {});
 
-// @ts-expect-error a system's object components live on one thread
-System.create({ name: "threadsTypeTest/both", components: { read: [node, tags] } }, () => {});
-// @ts-expect-error writes and change filters place it too
-System.create({ name: "threadsTypeTest/changed", components: { write: [tags], changed: [audio] } }, () => {});
-// @ts-expect-error a lookup's reads place it too
-System.create({ name: "threadsTypeTest/lookup", components: { read: [tags] }, lookup: { nodes: { read: [node] } } }, () => {});
+// @ts-expect-error change filters and conditions place it
+System.create({ components: { changed: [tags, audio] } }, () => {});
 // @ts-expect-error resources and components live on one thread
-System.create({ name: "threadsTypeTest/mixed", components: { read: [audio] }, resources: { read: [document] } }, () => {});
-// @ts-expect-error a condition it reads places it
-System.create({ name: "threadsTypeTest/condition", components: { read: [node] }, resources: { is: [settings] } }, () => {});
+System.create({ components: { changed: [audio] }, resources: { is: [document] } }, () => {});
 
 // Render systems run on gpuDevice's thread, "world".
-System.render({ name: "threadsTypeTest/draw", resources: { read: [settings] }, shader: { accessors: { place: position } } }, () => {});
+System.render({ shader: { accessors: { place: position } } }, () => {});
 // @ts-expect-error a render system's resources live with gpuDevice
-System.render({ name: "threadsTypeTest/drawNode", resources: { read: [document] }, shader: { accessors: { place: position } } }, () => {});
+System.render({ resources: { is: [document] }, shader: { accessors: { place: position } } }, () => {});
 
 // A composite's members may live on different threads.
-const render = System.create({ name: "threadsTypeTest/renderMember", components: { write: [node] } }, () => {});
-const play = System.create({ name: "threadsTypeTest/playMember", components: { write: [audio] } }, () => {});
-export const frame = System.create({ name: "threadsTypeTest/frame", systems: [render, play] });
+const render = System.create({ components: { with: [node] } }, () => {});
+const play = System.create({ components: { with: [audio] } }, () => {});
+export const frame = System.create({ systems: [render, play] });
 
-// Finalizers too run on one thread.
-Finalizer.create({ name: "threadsTypeTest/release", components: { read: [node] }, resources: { read: [document] } }, () => {});
-// @ts-expect-error a finalizer's object components and resources live on one thread
-Finalizer.create({ name: "threadsTypeTest/releaseBoth", components: { read: [node, audio] } }, () => {});
-Finalizer.create({ name: "threadsTypeTest/releaseCaption", components: { read: [node, label] } }, () => {});
-
-// A finalizer on another thread than the world's, which a joined thread may fill, runs there after the sync point: it
-// issues no commands, writes no resources and looks up nothing.
-Finalizer.create({ name: "threadsTypeTest/detach", components: { read: [node, position] }, resources: { read: [document, time] } }, (row, context) => {
+// Finalizers too run on one thread, which registration finds from what their bodies use. One on another thread than
+// the world's, which a joined thread may fill, runs there after the sync point: it issues no commands, writes no
+// resources and looks up nothing.
+Finalizer.create({ components: { with: [node] } }, () => {});
+Finalizer.create({ components: { with: [node, label] } }, () => {});
+Finalizer.create({ components: { with: [node, position] } }, (row, context) => {
     row[node].remove();
     void [row[position], context.resources[document], context.resources[time]];
-    // @ts-expect-error a finalizer on another thread issues no commands
-    void context.commands;
-});
-Finalizer.create({ name: "threadsTypeTest/silence", components: { read: [audio] } }, (row, context) => {
-    void row[audio];
-    // @ts-expect-error a finalizer on another thread issues no commands
-    void context.commands;
 });
-// @ts-expect-error a finalizer on another thread writes no resources
-Finalizer.create({ name: "threadsTypeTest/detachWriting", components: { read: [node] }, resources: { write: [time] } }, () => {});
-// @ts-expect-error a finalizer writing another thread's resource is on that thread
-Finalizer.create({ name: "threadsTypeTest/documentWriting", components: { read: [position] }, resources: { write: [document] } }, () => {});
-// @ts-expect-error a finalizer on another thread looks up nothing
-Finalizer.create({ name: "threadsTypeTest/detachLooking", components: { read: [node] }, lookup: { places: { read: [position] } } }, () => {});
 // On the world's thread, structs and its objects alike, it does.
-Finalizer.create({ name: "threadsTypeTest/forget", components: { read: [label, position] }, resources: { write: [time] }, lookup: { labels: { read: [label] } } }, (row, { commands, resources, lookup }) => {
+Finalizer.create({ components: { with: [label, position] }, lookup: { labels: { with: [label] } } }, (row, { commands, resources, lookup }) => {
     resources[time] = lookup.labels(row.entity)?.[label].length ?? 0;
     commands.despawn(row.entity);
 });
-// A changes finalizer runs on the world's thread: watching another thread's objects, or reading its resources, doesn't compile.
-Finalizer.changes({ name: "threadsTypeTest/save", watch: [label, position], resources: { read: [time] } }, (_, { commands }) => { void commands; });
+// A changes finalizer runs on the world's thread: watching another thread's objects doesn't compile.
+Finalizer.changes({ watch: [label, position] }, (_, { commands }) => { void commands; });
 // @ts-expect-error a changes finalizer watches no other thread's objects
-Finalizer.changes({ name: "threadsTypeTest/saveNodes", watch: [node] }, () => {});
-// @ts-expect-error a changes finalizer reads no other thread's resources
-Finalizer.changes({ name: "threadsTypeTest/saveDocument", resources: { read: [document] } }, () => {});
+Finalizer.changes({ watch: [node] }, () => {});
 
 // The error names each object component and resource with its thread; data places nothing.
-check<Equal<ThreadedBy<{ readonly components: { readonly read: [typeof audio, typeof position] }; readonly resources: { readonly read: [typeof document, typeof time] } }>, { readonly [audio]: "threadsTypeTest"; readonly [document]: "main" }>>();
+check<Equal<ThreadedBy<{ readonly components: { readonly changed: [typeof audio, typeof position] }; readonly resources: { readonly is: [typeof document, typeof time] } }>, { readonly [audio]: "threadsTypeTest"; readonly [document]: "main" }>>();

package/src/interface/system/up.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 { System } from './system.js';
@@ -18,63 +19,49 @@ declare module '@adobe/ecs' {
         [name]: { type: string };
     }
 }
-Component.register(local, { type: { type: "number" } });
-Component.register(world, { type: { type: "number" } });
-Component.register(parent, { type: Entity.schema, reference: "owner" });
-Component.register(name, { type: { type: "string" } });
 
-// `up` reads what `read` lists of the entity `through` names, or null for a row without one; it may read what the
-// system writes.
+// `up` holds the values of the entity `through` names, or null for a row without one; it may read what the system
+// writes. What the body reads of it the build infers.
 System.create({
-    name: "upTypeTest/propagate",
-    kernel: "cpu",
-    components: { read: [local], write: [world] },
-    up: { through: parent, read: [world] },
+    kernel: true,
+    components: { with: [local, world] },
+    up: { through: parent },
 }, (row, { up }) => {
-    check<Equal<typeof up, { readonly [world]: number } | null>>();
+    if (up !== null) check<Equal<typeof up[typeof world], number>>();
     row[world] = up === null ? row[local] : up[world] + row[local];
     // @ts-expect-error up's values are read-only
     if (up !== null) up[world] = 0;
 });
 
 // Without `up`, the context has none.
-System.create({ name: "upTypeTest/none", components: { read: [local] } }, (row, context) => {
+System.create({ components: { with: [local] } }, (row, context) => {
     void row[local];
     // @ts-expect-error no up declared
     void context.up;
 });
 
 System.create({
-    name: "upTypeTest/unreferenced",
-    components: { write: [world] },
+    components: { with: [world] },
     // @ts-expect-error through is a reference component
-    up: { through: local, read: [world] },
+    up: { through: local },
 }, () => {});
 
-System.create({
-    name: "upTypeTest/text",
-    kernel: "cpu",
-    components: { write: [world] },
-    // @ts-expect-error a kernel's up reads linear values
-    up: { through: parent, read: [name] },
-}, () => {});
+
 
 // A GPU kernel reads up too.
 System.create({
-    name: "upTypeTest/gpu",
     kernel: "gpu",
-    components: { read: [local], write: [world] },
-    up: { through: parent, read: [world] },
+    components: { with: [local, world] },
+    up: { through: parent },
 }, (row, { up }) => {
     row[world] = up === null ? row[local] : up[world] + row[local];
 });
 
 System.create({
-    name: "upTypeTest/rowless",
     // @ts-expect-error up orders rows, so it needs components
-    up: { through: parent, read: [world] },
+    up: { through: parent },
 }, () => {});
 
 // An observer system reads what a sync point left, in no order.
 // @ts-expect-error an observer system has no up
-System.create({ observer: true, components: { read: [local] }, up: { through: parent, read: [local] } }, () => {});
+System.create({ observer: true, components: { with: [local] }, up: { through: parent } }, () => {});

package/src/interface/system/values-of.ts

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../component/component.js';
+
+/** Components a spawn or add may leave out: a tag, whose value is `true`, and one whose type allows `null`, its start. */
+type Omissible<K extends Component.Key> = Component.Value<K> extends true ? K : null extends Component.Value<K> ? K : never;
+
+/**
+ * The values a spawn or add of the components `C` takes, keyed by component and exact against `C`, but those `Given`
+ * already: a tag needs no value, a component whose type allows `null` may be left out to start at `null`, and every
+ * other one is required. Leaving one out, or giving `undefined`, never leaves the component out. A list that isn't a
+ * tuple takes any of its components' values.
+ */
+export type ValuesOf<C extends readonly Component.Key[], Given extends PropertyKey = never> = number extends C["length"]
+    // A list whose components aren't known until it runs, so any of them may be given.
+    ? { readonly [K in Exclude<C[number], Given>]?: Component.Value<K> }
+    : { readonly [K in Exclude<C[number], Given> as K extends Omissible<K> ? never : K]: Component.Value<K> }
+        & { readonly [K in Exclude<C[number], Given> as K extends Omissible<K> ? K : never]?: Component.Value<K> };

package/src/interface/system/values.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component } from '../component/component.js';
 import type { Entity } from '../entity/entity.js';
 import type { Index } from '../indexes/index-type.js';
@@ -16,8 +17,8 @@ export type Values<Read, Write, Keys extends PropertyKey, Types> =
 /** An index declaration's key. */
 export type KeyOf<D> = D extends { readonly key: infer K extends readonly Component.Key[] } ? K : readonly Component.Key[];
 
-/** The components every entity an index holds has: its key parts and its `has`. */
-export type HeldBy<D> = KeyOf<D>[number] | Listed<Property<D, "components">, "has">;
+/** The components every entity an index holds has: its key parts and its `with`. */
+export type HeldBy<D> = KeyOf<D>[number] | Listed<Property<D, "components">, "with">;
 
 /** The key's values, in key order. */
 type KeyValues<K extends readonly Component.Key[]> = { readonly [I in keyof K]: Component.Value<K[I] & Component.Key> };
@@ -27,8 +28,8 @@ type Prefix<V extends readonly unknown[]> = V extends readonly [infer First, ...
     ? readonly [] | readonly [First | Comparison<First>] | readonly [First, ...Prefix<Rest>]
     : readonly [];
 
-/** A row an index lookup gives: its entity and the lookup's `read` values, read-only. */
-type IndexRow<L> = { readonly entity: Entity } & { readonly [K in Listed<L, "read"> & Component.Key]: Component.Value<K> };
+/** A row an index lookup gives: its entity and the values of what every entity the index holds has, read-only. */
+type IndexRow<D> = { readonly entity: Entity } & { readonly [K in HeldBy<D> & Component.Key]: Component.Value<K> };
 
 /**
  * The rows a lookup found, in the index's order: by entity for a hash index, by key and then entity for a sorted one.
@@ -47,24 +48,26 @@ type Rows<R> = {
 };
 
 /** A lookup through an index, by its declaration `D`: by key, a prefix of it for a sorted index. */
-type IndexLookup<D, L> =
+type IndexLookup<D> =
     D extends { readonly unique: true }
         ? D extends { readonly sorted: true }
-            ? ((...key: KeyValues<KeyOf<D>>) => IndexRow<L> | null) & ((...key: Prefix<KeyValues<KeyOf<D>>>) => Rows<IndexRow<L>>)
-            : (...key: KeyValues<KeyOf<D>>) => IndexRow<L> | null
+            ? ((...key: KeyValues<KeyOf<D>>) => IndexRow<D> | null) & ((...key: Prefix<KeyValues<KeyOf<D>>>) => Rows<IndexRow<D>>)
+            : (...key: KeyValues<KeyOf<D>>) => IndexRow<D> | null
         : D extends { readonly sorted: true }
-            ? (...key: Prefix<KeyValues<KeyOf<D>>>) => Rows<IndexRow<L>>
-            : (...key: KeyValues<KeyOf<D>>) => Rows<IndexRow<L>>;
+            ? (...key: Prefix<KeyValues<KeyOf<D>>>) => Rows<IndexRow<D>>
+            : (...key: KeyValues<KeyOf<D>>) => Rows<IndexRow<D>>;
 
 /**
- * The row a lookup by entity gives: the lookup's `read` values, read-only, and with `changed` declared, whether a
+ * The row a lookup by entity gives: the values of its `with`, read-only, and with `changed` declared, whether a
  * component it names may have changed in the entity since its system last ran: conservative, as `changed` filters are,
  * and true on a system's first run and in finalizers. With `changed`, valid until the lookup is called again.
  */
 type EntityRow<L> = {
-    readonly [K in (Listed<L, "read"> & Component.Key) | (L extends { readonly changed: readonly Component.Key[] } ? "changed" : never)]: K extends Component.Key ? Component.Value<K> : boolean
+    readonly [K in (Listed<L, "with"> & Component.Key) | (Exclude<Listed<L, "optional">, Listed<L, "with">> & Component.Key) | (L extends { readonly changed: readonly Component.Key[] } ? "changed" : never)]:
+        // Its `optional` components are their values where the entity has them, `undefined` where it doesn't.
+        K extends Component.Key ? K extends Listed<L, "with"> ? Component.Value<K> : Component.Value<K> | undefined : boolean
 };
 
 export type LookupFunction<L> = L extends { readonly index: Index<infer D> }
-    ? IndexLookup<D, L>
+    ? IndexLookup<D>
     : (entity: Entity) => EntityRow<L> | null;

package/src/interface/thread/of.ts

@@ -1,8 +1,9 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { IsShared } from '../schema/is-struct.js';
 import type { Thread } from './thread.js';
 
 /**
- * The thread a value of type `T` declared with traits `Entry` lives on: none for a struct or a string, else its `thread`
- * or `"world"`.
+ * The thread a value of type `T` declared with traits `Entry` lives on: none for a struct, a string or a shared
+ * component's value, which every thread reads, else its `thread` or `"world"`.
  */
-export type ThreadOf<Entry, T> = IsShared<T> extends true ? never : Entry extends { readonly thread: infer H extends Thread } ? H : "world";
+export type ThreadOf<Entry, T> = IsShared<T> extends true ? never : Entry extends { readonly shared: true } ? never : Entry extends { readonly thread: infer H extends Thread } ? H : "world";

package/src/interface/thread/thread.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /**
  * The logical threads, by augmentation: `interface Threads { audio: true }`. A logical thread is where object values
  * live and where the code touching them runs. A worker can fill several; one that no thread claims is filled by `world`.

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { Component } from '../component/component.js';
 import type { IsNode, IsTransferable } from '../platform/platform.js';
 import { Resource } from '../resource/resource.js';
@@ -21,105 +22,39 @@ void undeclared;
 const label = Symbol("threadTypeTest/label");
 const path = Symbol("threadTypeTest/path");
 const handle = Symbol("threadTypeTest/handle");
-const placedLabel = Symbol("threadTypeTest/placedLabel");
-const unknownThread = Symbol("threadTypeTest/unknownThread");
 const position = Symbol("threadTypeTest/position");
-const placedPosition = Symbol("threadTypeTest/placedPosition");
-const placedTag = Symbol("threadTypeTest/placedTag");
 const element = Symbol("threadTypeTest/element");
-const unplacedElement = Symbol("threadTypeTest/unplacedElement");
-const workerElement = Symbol("threadTypeTest/workerElement");
 const maybeElement = Symbol("threadTypeTest/maybeElement");
 const bitmap = Symbol("threadTypeTest/bitmap");
 const buffer = Symbol("threadTypeTest/buffer");
-const notTransferable = Symbol("threadTypeTest/notTransferable");
 const canvas = Symbol("threadTypeTest/canvas");
 const cache = Symbol("threadTypeTest/cache");
-const count = Symbol("threadTypeTest/count");
 const port = Symbol("threadTypeTest/port");
-const text = Symbol("threadTypeTest/text");
 const names = Symbol("threadTypeTest/names");
-const mode = Symbol("threadTypeTest/mode");
-const caption = Symbol("threadTypeTest/caption");
 
 declare module '@adobe/ecs' {
     export interface Components {
         // Objects: on "world" without `thread`, or on the thread they name.
         [path]: { type: readonly number[]; thread: "threadTypeTest" };
         [handle]: { type: Map<string, number>; thread: "world" };
-        [unknownThread]: { type: readonly number[]; thread: "elsewhere" };
-        // Strings and structs live in shared memory, so they have no thread.
+        // Strings and structs live in shared memory, so they have no thread; World.create rejects one with it.
         [label]: { type: string };
-        [placedLabel]: { type: string; thread: "main" };
         [position]: { type: readonly [number, number, number] };
-        [placedPosition]: { type: readonly [number, number, number]; thread: "main" };
-        [placedTag]: { type: true; thread: "world" };
-        // A DOM Node lives on "main", and says so.
+        // A DOM Node lives on "main", and says so; the build rejects one without it.
         [element]: { type: HTMLElement; thread: "main" };
-        [unplacedElement]: { type: HTMLElement };
-        [workerElement]: { type: HTMLElement; thread: "threadTypeTest" };
         [maybeElement]: { type: HTMLCanvasElement | null; thread: "main" };
         // Transferable values may be moved, never copied, to their thread.
         [bitmap]: { type: ImageBitmap; thread: "threadTypeTest"; transfer: true };
         [buffer]: { type: ArrayBuffer; transfer: true };
-        [notTransferable]: { type: Map<string, number>; transfer: true };
     }
     export interface Resources {
         [canvas]: { type: OffscreenCanvas | null; thread: "threadTypeTest"; transfer: true };
         [cache]: { type: Map<string, number> | null; thread: "main" };
-        [count]: { type: number; thread: "main" };
         [port]: { type: MessagePort | null; transfer: true };
-        [text]: { type: string; transfer: true };
         [names]: { type: Map<string, number>; thread: "main" };
-        [mode]: { type: "edit" | "view"; thread: "main" };
-        [caption]: { type: string | null; thread: "main" };
     }
 }
 
-Component.register(label, { type: { type: "string" } });
-Component.register(path, { type: { type: "array", items: { type: "number" } }, thread: "threadTypeTest" });
-Component.register(handle, { thread: "world" });
-Component.register(position, { type: { type: "array", items: { type: "number" }, minItems: 3, maxItems: 3 } });
-Component.register(element, { thread: "main" });
-Component.register(maybeElement, { thread: "main" });
-Component.register(bitmap, { thread: "threadTypeTest", transfer: true });
-Component.register(buffer, { transfer: true });
-Resource.register(canvas, { thread: "threadTypeTest", transfer: true });
-Resource.register(cache, { thread: "main" });
-Resource.register(port, { transfer: true });
-
-// @ts-expect-error a thread is a declared one
-Component.register(unknownThread, { type: { type: "array", items: { type: "number" } }, thread: "elsewhere" });
-// @ts-expect-error a string lives in shared memory, so it has no thread
-Component.register(placedLabel, { type: { type: "string" }, thread: "main" });
-// @ts-expect-error a union of string literals is a string too
-Resource.register(mode, { type: { anyOf: [{ const: "edit" }, { const: "view" }], default: "view" }, thread: "main" });
-// @ts-expect-error and so is a string or null
-Resource.register(caption, { type: { anyOf: [{ type: "string" }, { type: "null" }], default: null }, thread: "main" });
-// @ts-expect-error a struct lives in shared memory, so it has no thread
-Component.register(placedPosition, { type: { type: "array", items: { type: "number" }, minItems: 3, maxItems: 3 }, thread: "main" });
-// @ts-expect-error a tag is a struct too
-Component.register(placedTag, { type: { const: true }, thread: "world" });
-// @ts-expect-error a struct resource has no thread either
-Resource.register(count, { type: { type: "number", default: 0 }, thread: "main" });
-// @ts-expect-error a DOM Node declares thread: "main"
-Component.register(unplacedElement, {});
-// @ts-expect-error a DOM Node lives on "main", not another thread
-Component.register(workerElement, { thread: "threadTypeTest" });
-// @ts-expect-error only a Transferable value is moved
-Component.register(notTransferable, { transfer: true });
-// @ts-expect-error a string is data, copied, never moved
-Resource.register(text, { type: { type: "string", default: "" }, transfer: true });
-// @ts-expect-error a value that's data is registered with its schema
-Component.register(label, {});
-// @ts-expect-error a component's object has no default: its value comes from commands
-Component.register(handle, { default: new Map(), thread: "world" });
-// @ts-expect-error a resource without null starts at a default
-Resource.register(names, { thread: "main" });
-// @ts-expect-error a default is a value of the type
-Resource.register(names, { default: "map", thread: "main" });
-Resource.register(names, { default: new Map(), thread: "main" });
-
 check<Equal<Component.Value<typeof path>, readonly number[]>>();
 check<Equal<ThreadOf<{ readonly thread: "main" }, string>, never>>();
 check<Equal<ThreadOf<{ readonly thread: "main" }, "edit" | "view">, never>>();

package/src/interface/trait/key.ts

@@ -1,6 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Traits } from './types.js';
 
 export type Key = keyof Traits<never>;
 
 /** The core's traits, the only ones named by strings. */
-export type BuiltIn = "type" | "derived" | "within" | "reference" | "reduce" | "thread" | "transfer";
+export type BuiltIn = "type" | "derived" | "within" | "reference" | "reduce" | "thread" | "transfer" | "shared";

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

@@ -1,10 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { Component } from '../component/component.js';
 import { Entity } from '../entity/entity.js';
 import { Resource } from '../resource/resource.js';
 import type { Commands } from '../system/commands.js';
 import type { IsStruct } from '../schema/is-struct.js';
 import type { Components } from '../component/types.js';
-import { Trait } from './trait.js';
 import type { Derived, Essential } from '../component/value.js';
 import type { Reduced } from '../resource/reduction.js';
 
@@ -20,10 +20,6 @@ declare module '@adobe/ecs' {
         readonly [nonPersistent]: N extends Component.Key ? (Components[N] extends { readonly derived: true } ? never : true) : true;
     }
 }
-Trait.register(gpuOnly);
-Trait.register(nonPersistent);
-// @ts-expect-error string trait names are the core's built-in traits
-Trait.register("derived");
 
 const parent = Symbol("traitTest/parent");
 const follows = Symbol("traitTest/follows");
@@ -33,90 +29,27 @@ const score = Symbol("traitTest/score");
 const link = Symbol("traitTest/link");
 const pair = Symbol("traitTest/pair");
 const cache = Symbol("traitTest/cache");
-const badReference = Symbol("traitTest/badReference");
-const selfWithin = Symbol("traitTest/selfWithin");
-const derivedWithin = Symbol("traitTest/derivedWithin");
-const derivedReference = Symbol("traitTest/derivedReference");
-const gpuString = Symbol("traitTest/gpuString");
-const derivedNonPersistent = Symbol("traitTest/derivedNonPersistent");
 const time = Symbol("traitTest/time");
-const derivedResource = Symbol("traitTest/derivedResource");
 const sum = Symbol("traitTest/sum");
-const anyFlag = Symbol("traitTest/anyFlag");
-const named = Symbol("traitTest/named");
-const reducedComponent = Symbol("traitTest/reducedComponent");
 
 declare module '@adobe/ecs' {
     export interface Components {
         [parent]: { type: Entity; reference: "owner" };
         [follows]: { type: Entity; reference: "weak" };
-        [slot]: { type: number; derived: true };
+        [slot]: { type: number; derived: true; default: 0 };
         [ready]: { type: true; within: typeof slot };
         [score]: { type: number };
         [link]: { type: { readonly to: Entity; readonly weight: number } };
         [pair]: { type: readonly [number, number]; [gpuOnly]: true };
         [cache]: { type: number; [nonPersistent]: true };
-        [badReference]: { type: number; reference: "owner" };
-        [selfWithin]: { type: true; within: typeof selfWithin };
-        [derivedWithin]: { type: number; derived: true; within: typeof score };
-        [derivedReference]: { type: Entity; derived: true; reference: "owner" };
-        [gpuString]: { type: string; [gpuOnly]: true };
-        [derivedNonPersistent]: { type: number; derived: true; [nonPersistent]: true };
-        [reducedComponent]: { type: number; reduce: "+" };
     }
     export interface Resources {
-        [time]: { type: number };
-        [derivedResource]: { type: number; derived: true };
+        [time]: { type: number; default: 0 };
         [sum]: { type: number; reduce: "+" };
-        [anyFlag]: { type: boolean; reduce: "+" };
-        [named]: { type: string; reduce: "max" };
     }
 }
 
-// Registration takes exactly the declared traits, `type` as a schema for the declared type.
-Component.register(parent, { type: Entity.schema, reference: "owner" });
-Component.register(follows, { type: Entity.schema, reference: "weak" });
-Component.register(slot, { type: { type: "number", default: 0 }, derived: true });
-Component.register(ready, { type: { const: true }, within: slot });
-Component.register(score, { type: { type: "number" } });
-Component.register(link, { type: { type: "object", properties: { to: Entity.schema, weight: { type: "number" } } } });
-Component.register(pair, { type: { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2 }, [gpuOnly]: true });
-Component.register(cache, { type: { type: "number" }, [nonPersistent]: true });
-Resource.register(time, { type: { type: "number", default: 0 } });
-Resource.register(sum, { type: { type: "number", default: 0 }, reduce: "+" });
-
-// @ts-expect-error a derived component's type has a default, which it starts at
-Component.register(slot, { type: { type: "number" }, derived: true });
-// @ts-expect-error a reference's value is an entity
-Component.register(badReference, { type: { type: "number" }, reference: "owner" });
-// @ts-expect-error a component can't live within itself
-Component.register(selfWithin, { type: { const: true }, within: selfWithin });
-// @ts-expect-error a derived component's rule covers within
-Component.register(derivedWithin, { type: { type: "number", default: 0 }, derived: true, within: score });
-// @ts-expect-error a rule can't set a derived component's target
-Component.register(derivedReference, { type: { ...Entity.schema, default: Entity.none }, derived: true, reference: "owner" });
-// @ts-expect-error gpuOnly takes only linear components
-Component.register(gpuString, { type: { type: "string" }, [gpuOnly]: true });
-// @ts-expect-error nonPersistent is redundant on a derived component
-Component.register(derivedNonPersistent, { type: { type: "number", default: 0 }, derived: true, [nonPersistent]: true });
-// @ts-expect-error a declared trait is missing
-Component.register(parent, { type: Entity.schema });
-// @ts-expect-error an undeclared trait is given
-Component.register(score, { type: { type: "number" }, derived: true });
-// @ts-expect-error a trait's value differs from the declared one
-Component.register(follows, { type: Entity.schema, reference: "owner" });
-// @ts-expect-error an unknown trait
-Component.register(score, { type: { type: "number" }, unknown: true });
-// @ts-expect-error an entity's schema is Entity.schema
-Component.register(parent, { type: { type: "integer" }, reference: "owner" });
-// @ts-expect-error a number's schema isn't Entity.schema
-Component.register(score, { type: Entity.schema });
-// @ts-expect-error an entity field's schema is Entity.schema too
-Component.register(link, { type: { type: "object", properties: { to: { type: "integer" }, weight: { type: "number" } } } });
-// @ts-expect-error a resource's schema has a default
-Resource.register(time, { type: { type: "number" } });
-// @ts-expect-error derived is a component trait
-Resource.register(derivedResource, { type: { type: "number", default: 0 }, derived: true });
+// The build registers each as declared; the registry checks the built-in traits when it does.
 
 // Types filter components by their traits and value types.
 type Ours = typeof parent | typeof follows | typeof slot | typeof ready | typeof score | typeof link | typeof pair | typeof cache;
@@ -148,11 +81,5 @@ const raw: number = Entity.none;
 const forged: Entity = 3;
 void raw;
 void forged;
-// @ts-expect-error booleans reduce bitwise
-Resource.register(anyFlag, { type: { type: "boolean", default: false }, reduce: "+" });
-// @ts-expect-error only numbers and booleans, and tuples and structs of them, are reduced
-Resource.register(named, { type: { type: "string", default: "" }, reduce: "max" });
-// @ts-expect-error reduce is a resource trait
-Component.register(reducedComponent, { type: { type: "number" }, reduce: "+" });
 check<Equal<Reduced & typeof sum, typeof sum>>();
 check<Equal<Reduced & typeof time, never>>();

package/src/interface/trait/types.ts

@@ -1,10 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component } from '../component/component.js';
 import type { Components } from '../component/types.js';
 import type { Entity } from '../entity/entity.js';
 import type { IsNode, IsTransferable } from '../platform/platform.js';
 import type { Resource } from '../resource/resource.js';
 import type { Reduction } from '../resource/reduction.js';
-import type { IsString, IsStruct } from '../schema/is-struct.js';
+import type { IsComparable, IsString, IsStruct } from '../schema/is-struct.js';
 import type { Thread } from '../thread/thread.js';
 
 /** The value type of the component or resource `N`. */
@@ -19,15 +20,16 @@ type Structs = { readonly [K in Component.Key | Resource.Key as K]: IsString<Val
 
 /**
  * The value each trait allows on the component or resource `N`. Augment it, with this exact type parameter, to
- * define a trait, and register its name with `Trait.register`. A trait that doesn't apply to `N` resolves to `never`.
+ * define a trait, keyed by a `Symbol()` constant of the same module, which the build registers. A trait that doesn't
+ * apply to `N` resolves to `never`.
  * An allowed value may look at `N`'s own traits and at the one component a declared value names, never map over
  * every component, or checking grows with the square of the component count.
  */
 export interface Traits<N extends Component.Key | Resource.Key> {
     /** The value type: declared as a TypeScript type, registered as a schema for it when it's data. */
     readonly type: unknown;
-    /** Present only while a rule deriving it matches, so commands never add or remove it. */
-    readonly derived: N extends Component.Key ? true : never;
+    /** Present only while a rule deriving it matches, so commands never add or remove it. Not on a shared component. */
+    readonly derived: N extends Component.Key ? Components[N] extends { readonly shared: true } ? never : true : never;
     /** Exists only while its host component does, and is removed with it. Not on a derived component, which its rule covers. */
     readonly within: N extends Component.Key
         ? Components[N] extends { readonly derived: true } | { readonly within: N } ? never : Component.Key
@@ -37,7 +39,7 @@ export interface Traits<N extends Component.Key | Resource.Key> {
      * component. Not on a derived component, whose target only a command could set.
      */
     readonly reference: N extends Component.Key
-        ? Components[N] extends { readonly derived: true } ? never : [Component.Value<N>] extends [Entity] ? "owner" | "weak" : never
+        ? Components[N] extends { readonly derived: true } | { readonly shared: true } ? never : [Component.Value<N>] extends [Entity] ? "owner" | "weak" : never
         : never;
     /**
      * On a resource, the operator systems reduce into it with: each run that a contributor runs in starts it at the
@@ -50,7 +52,18 @@ export interface Traits<N extends Component.Key | Resource.Key> {
      * The logical thread an object lives on, `"world"` without it. Not on a struct or a string, which live in shared
      * memory. A DOM `Node` lives on `"main"`, and says so.
      */
-    readonly thread: Structs[N] extends true | "string" ? never : IsNode<ValueOf<N>> extends true ? "main" : Thread;
+    readonly thread: Structs[N] extends true | "string" ? never
+        : N extends Component.Key ? Components[N] extends { readonly shared: true } ? never : IsNode<ValueOf<N>> extends true ? "main" : Thread
+        : IsNode<ValueOf<N>> extends true ? "main" : Thread;
     /** The value may be moved, never copied, to its thread: only a Transferable value. */
     readonly transfer: IsTransferable<ValueOf<N>> extends true ? true : never;
+    /**
+     * On a component of comparable data (numbers, booleans, strings, arrays and plain objects of those): each archetype
+     * holds one value of it for every entity it holds, so entities of equal values share an archetype. Rows read it as
+     * their archetype's value; `commands.add` with another value moves the entity. Not on a derived component or a
+     * reference, and it has no thread: every thread reads it.
+     */
+    readonly shared: N extends Component.Key
+        ? Components[N] extends { readonly derived: true } | { readonly reference: unknown } ? never : IsComparable<Component.Value<N>> extends true ? true : never
+        : never;
 }

package/src/interface/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../data/tsconfig-base.json",
+  "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "rootDir": ".",
     "outDir": "../../dist/interface",