@adobe/ecs 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,53 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Component } from '../component/component.js';
+import { Entity, Index, System } from "@adobe/ecs";
+
+const position = Symbol("listsTypeTest/position");
+const velocity = Symbol("listsTypeTest/velocity");
+const scale = Symbol("listsTypeTest/scale");
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: number };
+        [velocity]: { type: number };
+    }
+    interface Resources {
+        [scale]: { type: number };
+    }
+}
+
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+const expectType = <T extends true>(): T | undefined => undefined;
+
+// A list of components declared `as const` is a tuple, an archetype wherever component lists go.
+export const Particle = [position, velocity] as const;
+expectType<Equal<typeof Particle, readonly [typeof position, typeof velocity]>>();
+export const one: readonly Component.Key[] = Particle;
+export const move = System.create({ components: { with: [...Particle] } }, row => { row[position] += row[velocity]; });
+export const read = System.create({ observer: true, components: { with: [...Particle] } }, row => { void row[velocity]; });
+
+// Declared without `as const`, a list's keys widen to `symbol`, which no list of components takes.
+const loose = [position, velocity];
+expectType<Equal<typeof loose, symbol[]>>();
+// @ts-expect-error so it's never a list of components
+export const looseList: readonly Component.Key[] = loose;
+// @ts-expect-error nor an index's
+export const byLoose = Index.create({ key: [position], components: { with: loose } });
+
+/** A list whose components are known only at runtime says so by its type. */
+const runtime: readonly (typeof position | typeof velocity)[] = Particle;
+
+export const spawn = System.create(({ commands }) => {
+    commands.spawn(Particle)({ [position]: 1, [velocity]: 2 });
+    // @ts-expect-error a tuple's values are required
+    commands.spawn(Particle)({ [position]: 1 });
+    commands.spawn([position, velocity])({ [position]: 1, [velocity]: 2 });
+    // @ts-expect-error a list declared without `as const` can't be spawned
+    commands.spawn(loose);
+    // @ts-expect-error nor added
+    commands.add(Entity.none, loose, {});
+    // A runtime list takes any of its values.
+    commands.spawn(runtime)({ [position]: 1 });
+    commands.add(Entity.none, Particle, { [position]: 1, [velocity]: 2 });
+    // @ts-expect-error a resource is never in a list of components
+    commands.spawn([position, scale]);
+});

package/src/interface/system/name.ts

@@ -0,0 +1,7 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * The label errors give it, for display: its binding, from the id the plugin gave it; for one made in a
+ * function, the binding or function the plugin found it in; else its kind numbered. The value its constructor returns
+ * is its identity, so labels needn't be unique.
+ */
+export type Name = string;

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

@@ -0,0 +1,51 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity } from '../entity/entity.js';
+import { System } from './system.js';
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+const position = Symbol("optionalTest/position");
+const velocity = Symbol("optionalTest/velocity");
+const pilot = Symbol("optionalTest/pilot");
+
+declare module '@adobe/ecs' {
+    export interface Components {
+        [position]: { type: number };
+        [velocity]: { type: number };
+        [pilot]: { type: Entity; reference: "owner" };
+    }
+}
+
+// An optional component is its value, or undefined where an entity lacks it.
+System.create({ components: { with: [position], optional: [velocity, pilot] } }, row => {
+    check<Equal<typeof row[typeof velocity], number | undefined>>();
+    const speed = row[velocity];
+    if (speed !== undefined) row[position] += speed;
+    row[velocity] = 2;
+    // @ts-expect-error a reference is read-only in a row, optional or not
+    row[pilot] = Entity.none;
+});
+
+// A CPU kernel reads them as a body run as written does; GPU kernels don't read components an archetype may lack yet.
+System.create({ kernel: true, components: { with: [position], optional: [velocity] } }, row => { void row[velocity]; });
+System.create({
+    // @ts-expect-error a GPU kernel can't have optional components yet
+    kernel: "gpu",
+    components: { with: [position], optional: [velocity] },
+}, row => { void row[velocity]; });
+
+// An observer system reads its optional components and writes nothing.
+System.create({ observer: true, components: { with: [position], optional: [velocity] } }, row => {
+    void row[velocity];
+    // @ts-expect-error an observer system's row is read-only
+    row[velocity] = 1;
+});
+
+// A lookup by entity's optional component is its value, or undefined where the entity lacks it.
+System.create({ components: { with: [pilot] }, lookup: { pilots: { with: [position], optional: [velocity] } } }, (row, { lookup }) => {
+    const found = lookup.pilots(row[pilot]);
+    if (found === null) return;
+    check<Equal<typeof found[typeof position], number>>();
+    check<Equal<typeof found[typeof velocity], number | undefined>>();
+});

package/src/interface/system/property.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export type Property<T, K extends PropertyKey> = T extends { readonly [P in K]?: infer V } ? V : undefined;
+
+export type Listed<T, K extends PropertyKey> = Property<T, K> extends readonly (infer E)[] ? E : never;

package/src/interface/system/render.ts

@@ -0,0 +1,106 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../component/component.js';
+import type { Index } from '../indexes/index-type.js';
+import { takeIdOfDeclaration } from '../registry/ids.js';
+import { nameOf } from '../registry/items.js';
+import { claimSystem } from '../registry/program.js';
+import type { Condition } from '../resource/condition.js';
+import type { ThreadOfResource } from '../resource/value.js';
+import { gpuDevice } from '../resources/gpu-device.js';
+import type { Body } from './body.js';
+import type { ReturnsNoPromise } from './input.js';
+import { accessorsOf } from '../gpu/accessors.js';
+import { checkLeaf } from './check.js';
+import { accessOf, compact, resourceUses } from './resolve.js';
+import type { Leaf } from './leaf.js';
+import type { StructComponent } from './struct.js';
+import type { Shared } from '../component/value.js';
+import type { System } from './system.js';
+import type { OneThread, ThreadedBy, ThreadsOf } from './threads.js';
+
+/**
+ * How a render system's shaders reach its components: `accessors` names a WGSL function for each component it reads,
+ * generated by `Gpu.wgsl` at bind group `group` (0 by default). A shared component has no column for one to read.
+ */
+export type Shader = { readonly group?: number; readonly accessors: { readonly [name: string]: Exclude<StructComponent, Shared> } };
+
+/**
+ * One group of matching rows, `0` to `count`: an archetype's, or with `order` every matching row in its order. `bind`
+ * sets the world's bind group for it on a pass.
+ */
+export type RenderTable = {
+    readonly count: number;
+    readonly bind: (pass: GPURenderPassEncoder | GPUComputePassEncoder) => void;
+};
+
+/**
+ * What a render body records with. `encoder` is the run's: the world submits it, after the run's GPU kernels and
+ * uploads, when the run ends. Acquire canvas textures inside the body.
+ */
+export type RenderContext = {
+    readonly device: GPUDevice;
+    readonly encoder: GPUCommandEncoder;
+    readonly tables: readonly RenderTable[];
+};
+
+type RenderDeclaration = {
+    /** It matches the components its accessors name, and those in `with`, and none in `not`. */
+    readonly components?: { readonly with?: readonly Component.Key[]; readonly not?: readonly Component.Key[] };
+    /** It runs only while `gpuDevice` is set, as if `is` listed it. What its body reads of resources the build infers. */
+    readonly resources?: { readonly is?: readonly Condition[]; readonly not?: readonly Condition[] };
+    /**
+     * Draws every matching row as one table, in this sorted index's order: key order, then entity order. Its shaders'
+     * accessors then take a row's position in that order.
+     */
+    readonly order?: Index<{ readonly sorted: true; readonly key: readonly Component.Key[] }>;
+    readonly shader: Shader;
+    readonly before?: readonly System<unknown>[];
+    readonly after?: readonly System<unknown>[];
+    readonly during?: readonly System<unknown>[];
+};
+
+/** What a render body reads of resources is inferred, and what it reads of components its accessors name. */
+type Inferred = {
+    readonly components?: { readonly read?: never; readonly has?: never };
+    readonly resources?: { readonly read?: never };
+};
+
+/**
+ * Declares a render system: it runs once per run on `gpuDevice`'s thread, in schedule order, and records GPU work over
+ * the GPU copy of the components its accessors name, which the world uploads first as needed. It runs only while the
+ * world has a `gpuDevice`. Its body's `tables` hold one table per matching archetype, each in row order; with `order`,
+ * exactly one table of every matching row, across archetypes, in the index's order, so instance `i` is the i-th: a
+ * shader's accessors take that position as their `row`, with the same names and signatures. Throws as `create` does,
+ * for an `order` that isn't a sorted index, and for an accessor its shader can't read on the GPU. A system with `order`
+ * fails its run when a matching archetype holds more rows than 32 bits name beside its slot: 2^31 with up to two
+ * matching archetypes, 2^30 with up to four, and so on.
+ */
+export const render = <const D extends RenderDeclaration, B extends Body<D>>(
+    declaration: D & Inferred & OneThread<ThreadsOf<D> | ThreadOfResource<typeof gpuDevice>, ThreadedBy<D>>,
+    body: B & ReturnsNoPromise<B>,
+): System => {
+    const id = takeIdOfDeclaration(declaration);
+    const name = nameOf(declaration, id, "system");
+    const what = `System "${name}"`;
+    const read = [...new Set<symbol>(Object.values(declaration.shader.accessors))];
+    const is = [...new Set<symbol>([...declaration.resources?.is ?? [], gpuDevice])];
+    const uses = resourceUses(what, accessOf(what, declaration), is);
+    const { components, resources, ...rest } = declaration;
+    const system: Leaf & System = {
+        kind: "render",
+        name,
+        declaration: {
+            ...rest,
+            components: compact({ read, has: (components?.with ?? []).filter(key => !read.includes(key)), not: components?.not }),
+            resources: compact({ read: uses.read, is, not: resources?.not }),
+        },
+        input: undefined,
+        body,
+    };
+    if (uses.write.length > 0 || uses.reduce.length > 0) throw new Error(`${what} writes or reduces into resources; a render system only reads.`);
+    checkLeaf(system);
+    const accessors = accessorsOf(declaration.shader);
+    if (typeof accessors === "string") throw new Error(`System "${name}" can't render: ${accessors}.`);
+    claimSystem(system, id);
+    return system;
+};

package/src/interface/system/resolve.test.ts

@@ -0,0 +1,49 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import "../registry/declarations.js";
+import { componentLists, lookupsLists, resourceUses, type Access } from "./resolve.js";
+
+const mass = Symbol("resolveTest/mass");
+const pool = Symbol("resolveTest/pool");
+const position = Symbol("resolveTest/position");
+declare module "@adobe/ecs" {
+    interface Components {
+        [mass]: { type: number };
+        [position]: { type: number };
+        [pool]: { type: ReadonlyMap<string, number>; derived: true };
+    }
+}
+const access = (lookup: Access["lookup"]): Access => ({ components: null, resources: null, lookup, up: null, at: "a test" });
+
+describe("lookupsLists", () => {
+    it("takes a lookup whose rows the build didn't follow as reading everything it requires", () => {
+        expect(lookupsLists({ others: { with: [mass, position] } }, access({ others: null }))).toEqual({ others: { read: [mass, position] } });
+    });
+    it("takes a lookup the body never used as reading nothing, and one it followed as reading what it read", () => {
+        expect(lookupsLists({ others: { with: [mass, position] } }, access({}))).toEqual({ others: { has: [mass, position] } });
+        expect(lookupsLists({ others: { with: [mass, position] } }, access({ others: [position] }))).toEqual({ others: { read: [position], has: [mass] } });
+    });
+});
+
+describe("componentLists", () => {
+    it("takes a row the build didn't follow as writing every member, its added and changed filters' included", () => {
+        expect(componentLists({ with: [mass], changed: [position] }, null, false)).toEqual({ write: [mass, position], changed: [position] });
+    });
+    it("takes an observer's row the build didn't follow as reading every member, writing none", () => {
+        expect(componentLists({ with: [mass], changed: [position] }, null, true)).toEqual({ read: [mass, position], changed: [position] });
+    });
+    it("lists optional components apart, reading and writing them as the body does, or as members when unfollowed", () => {
+        const used = { read: [position], write: [mass] };
+        expect(componentLists({ with: [mass], optional: [position] }, used, false)).toEqual({ read: [position], write: [mass], optional: [position] });
+        expect(componentLists({ with: [mass], optional: [position] }, null, false)).toEqual({ write: [mass, position], optional: [position] });
+        expect(componentLists({ with: [mass], optional: [mass, position] }, used, false)).toEqual({ read: [position], write: [mass], optional: [position] });
+    });
+});
+
+describe("resourceUses", () => {
+    const changing = (key: symbol): Access => ({ components: { read: [key], write: [], mutate: [key] }, resources: { read: [], write: [], reduce: [] }, lookup: null, up: null, at: "a test" });
+    it("rejects a change inside a data value, given as a copy, and takes one inside an object as a read", () => {
+        expect(() => resourceUses("System \"s\"", changing(mass), undefined)).toThrow(`changes something inside its row's "resolveTest/mass", a value given as a copy`);
+        expect(() => resourceUses("System \"s\"", changing(pool), undefined)).not.toThrow();
+    });
+});

package/src/interface/system/resolve.ts

@@ -0,0 +1,165 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { takeAccessOf } from '../registry/ids.js';
+import { indexDefinitionOf } from '../registry/indexes.js';
+import { declarationOf, labelOf } from '../registry/names.js';
+import { isString, isStruct } from '../registry/schemas.js';
+import type { ComponentAccess, ComponentLists, Lookup, SystemLookup, SystemLookupLists } from './access.js';
+
+type Key = symbol;
+
+/** What a body reads and writes of a group of keys, and those it changes inside their values, read as well. */
+type Used = { readonly read: readonly Key[]; readonly write: readonly Key[]; readonly mutate?: readonly Key[] };
+
+/**
+ * What the build infers a body uses, which the plugin gives the declaration or body a constructor is called with: what
+ * it reads and writes of its row, and of resources with what it reduces into; what it reads of each lookup's rows,
+ * and of its parent's values with `up`. Each is null where the build couldn't follow the body's uses, and `at` names
+ * where the body is, for errors.
+ */
+export type Access = {
+    readonly components: Used | null;
+    readonly resources: (Used & { readonly reduce: readonly Key[] }) | null;
+    readonly lookup: { readonly [name: string]: readonly Key[] | null } | null;
+    readonly up: readonly Key[] | null;
+    /** The resources the predicates of its declaration's `where` read; absent without predicates. */
+    readonly where?: readonly Key[] | null;
+    readonly at: string;
+};
+
+const isKeys = (value: unknown): value is readonly Key[] => Array.isArray(value) && value.every(key => typeof key === "symbol");
+
+const isUsed = (value: unknown): value is Used => typeof value === "object" && value !== null
+    && isKeys(Reflect.get(value, "read")) && isKeys(Reflect.get(value, "write"))
+    && (Reflect.get(value, "mutate") === undefined || isKeys(Reflect.get(value, "mutate")));
+
+const isAccess = (value: unknown): value is Access => {
+    if (typeof value !== "object" || value === null) return false;
+    const components: unknown = Reflect.get(value, "components");
+    const resources: unknown = Reflect.get(value, "resources");
+    const lookup: unknown = Reflect.get(value, "lookup");
+    const up: unknown = Reflect.get(value, "up");
+    return (components === null || isUsed(components))
+        && (resources === null || (isUsed(resources) && isKeys(Reflect.get(resources, "reduce"))))
+        && (lookup === null || (typeof lookup === "object" && Object.values(lookup).every(reads => reads === null || isKeys(reads))))
+        && (up === null || isKeys(up)) && typeof Reflect.get(value, "at") === "string"
+        && (Reflect.get(value, "where") === undefined || Reflect.get(value, "where") === null || isKeys(Reflect.get(value, "where")));
+};
+
+/**
+ * What the build inferred the body a constructor is called with uses: given to its declaration, or for a system
+ * declaring nothing to its body. Throws when there's none, as when a module isn't built with the plugin.
+ */
+export const accessOf = (what: string, made: object): Access => {
+    const access = takeAccessOf(made);
+    if (!isAccess(access)) throw new Error(`${what} has no access the build inferred from its body: the build reads what a body uses where the constructor is called with its declaration written in place, as an object literal, and its body as a function, in a module built with Compiler.plugin().`);
+    return access;
+};
+
+/**
+ * Throws for a body changing something inside a data value, a struct or a string, which a row or the resources give
+ * as a copy and take only whole, so the change would be lost. An object, changed in place, is read.
+ */
+const checkChanges = (what: string, access: Access): void => {
+    for (const [group, keys] of [["its row's", access.components?.mutate], ["resources'", access.resources?.mutate]] as const) {
+        for (const key of keys ?? []) {
+            const type = declarationOf(key)?.type;
+            if (type !== undefined && (isStruct(type) || isString(type))) {
+                throw new Error(`${what}'s body (${access.at}) changes something inside ${group} "${labelOf(key)}", a value given as a copy and taken only whole: assign it a new value instead.`);
+            }
+        }
+    }
+};
+
+/** Throws for a group the build couldn't follow, naming what the body did instead. */
+const followed = <T>(what: string, used: T | null, group: string, access: Access): T => {
+    if (used !== null) return used;
+    throw new Error(`${what}'s body (${access.at}) uses ${group} in a way the build can't follow, so it can't tell what it reads and writes of them: index them by key directly, or destructure them by key, rather than passing them on, aliasing or spreading them.`);
+};
+
+const without = (keys: readonly Key[], ...others: (readonly Key[] | undefined)[]): Key[] =>
+    keys.filter(key => others.every(other => !other?.includes(key)));
+
+/** `lists` without its empty lists. */
+export const compact = <T extends object>(lists: T): T => {
+    const result: { [name: string]: unknown } = {};
+    for (const [name, value] of Object.entries(lists)) if (value !== undefined && !(Array.isArray(value) && value.length === 0)) result[name] = value;
+    // Every field is one of `lists`', with its own value.
+    return result as T;
+};
+
+/**
+ * A row's lists: what the body reads and writes of its members, the others only required. Without the body's uses,
+ * conservatively every member is written but references and shared components, which change only through commands,
+ * or read where it only reads.
+ */
+export const componentLists = (components: ComponentAccess, used: Used | null, reading: boolean, whereReads: readonly Key[] = []): ComponentLists => {
+    // A row holds what its added and changed filters name too, and its optional components where an entity has them.
+    const members = [...new Set([...components.with ?? [], ...components.added ?? [], ...components.changed ?? []])];
+    // Its `where` names shared components it requires, as `with` does.
+    const where = components.where === undefined ? undefined : components.where;
+    const named: readonly Key[] = members;
+    const filtered = where === undefined ? [] : Object.getOwnPropertySymbols(where).filter(key => !named.includes(key));
+    const optional = without(components.optional ?? [], members);
+    const held = [...members, ...optional];
+    const write = used === null
+        ? reading ? [] : held.filter(key => declarationOf(key)?.reference === undefined && declarationOf(key)?.shared !== true)
+        : used.write;
+    const read = used === null ? without(held, write) : without(used.read, write);
+    const has = [...without(members, read, write), ...without(filtered, read, write)];
+    return compact({ read, write, has, optional, not: components.not, added: components.added, changed: components.changed, where, whereReads });
+};
+
+/**
+ * A lookup's lists: what the body reads of its rows, the rest of its `with` only required. Without the body's uses,
+ * conservatively everything its rows hold is read: its `with`, or every component its index holds.
+ */
+export const lookupLists = (lookup: SystemLookup | Lookup, reads: readonly Key[] | null): SystemLookupLists => {
+    if (lookup.index !== undefined) {
+        const index = indexDefinitionOf(lookup.index)?.declaration;
+        const read = reads ?? [...index?.key ?? [], ...index?.components?.has ?? []];
+        const { changed } = lookup;
+        return changed === true ? { index: lookup.index, read, changed } : compact({ index: lookup.index, read, changed });
+    }
+    // Its optional components are read where an entity has them and never required.
+    const optional = without(lookup.optional ?? [], lookup.with ?? []);
+    const read = reads ?? [...lookup.with ?? [], ...optional];
+    return compact({ read, has: without(lookup.with ?? [], read), optional, not: lookup.not, changed: lookup.changed });
+};
+
+/** Each lookup's lists, by name. */
+export const lookupsLists = <L extends SystemLookup | Lookup>(lookups: { readonly [name: string]: L } | undefined, access: Access): { readonly [name: string]: SystemLookupLists } | undefined => {
+    if (lookups === undefined) return undefined;
+    const lists: { [name: string]: SystemLookupLists } = {};
+    for (const name in lookups) {
+        const lookup = lookups[name];
+        // A lookup whose rows the build didn't follow is null; one it saw unused has no entry.
+        const reads = access.lookup === null ? null : name in access.lookup ? access.lookup[name] ?? null : [];
+        if (lookup !== undefined) lists[name] = lookupLists(lookup, reads);
+    }
+    return lists;
+};
+
+/**
+ * What a body reads, writes and reduces into of resources, conditions in `is` read already. A read of what it reduces
+ * into stays, for registration to reject.
+ */
+export const resourceUses = (what: string, access: Access, is: readonly Key[] | undefined): { readonly read: Key[]; readonly write: readonly Key[]; readonly reduce: readonly Key[] } => {
+    checkChanges(what, access);
+    const used = followed(what, access.resources, "its resources", access);
+    return { read: without(used.read, used.write, is), write: used.write, reduce: used.reduce };
+};
+
+/**
+ * The resources a declaration's `where` predicates read: none without predicates; throws when the build couldn't follow
+ * them, since the world couldn't tell when to evaluate them again.
+ */
+export const whereReadsOf = (what: string, components: ComponentAccess | undefined, access: Access): readonly Key[] => {
+    const where = components?.where;
+    if (where === undefined || !Object.getOwnPropertySymbols(where).some(key => typeof Reflect.get(where, key) === "function")) return [];
+    const reads = access.where;
+    if (reads === undefined || reads === null) throw new Error(`${what}'s where predicates (${access.at}) read resources in a way the build can't follow, so it can't tell when to evaluate them again: index them by key directly, or destructure them by key, in a predicate written in place in a module built with Compiler.plugin().`);
+    return reads;
+};
+
+/** What a body reads of its parent's values. */
+export const upReads = (what: string, access: Access): readonly Key[] => followed(what, access.up, "its parent's values", access);

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

@@ -0,0 +1,205 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Component } from '../component/component.js';
+import { Entity } from '../entity/entity.js';
+import type { Vec2 } from '../math/index.js';
+import type { Traits } from '../trait/types.js';
+import { System } from './system.js';
+import { Index } from '../indexes/index-type.js';
+import type { Commands } from './commands.js';
+import type { InvalidDeclarations } from '../world/declarations.js';
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+/** Whether two types take the same values, however they're written. */
+type Same<X, Y> = [X] extends [Y] ? [Y] extends [X] ? true : false : false;
+
+const team = Symbol("sharedTypeTest/team");
+const cell = Symbol("sharedTypeTest/cell");
+const level = Symbol("sharedTypeTest/level");
+const health = Symbol("sharedTypeTest/health");
+const position = Symbol("sharedTypeTest/position");
+const camera = Symbol("sharedTypeTest/camera");
+const owner = Symbol("sharedTypeTest/owner");
+const tags = Symbol("sharedTypeTest/tags");
+const style = Symbol("sharedTypeTest/style");
+const scores = Symbol("sharedTypeTest/scores");
+const tool = Symbol("sharedTypeTest/tool");
+const maybe = Symbol("sharedTypeTest/maybe");
+
+declare module '@adobe/ecs' {
+    export interface Components {
+        // A shared component's value is its archetype's, once for every entity holding it: comparable data.
+        [team]: { type: "red" | "blue"; shared: true };
+        [cell]: { type: Vec2.I32; shared: true };
+        [level]: { type: number; shared: true };
+        [tags]: { type: readonly string[]; shared: true };
+        [style]: { type: { readonly color: string; readonly weight: number }; shared: true };
+        [health]: { type: number };
+        [position]: { type: Vec2 };
+        [owner]: { type: Entity; reference: "owner" };
+        [scores]: { type: ReadonlyMap<string, number> };
+        [tool]: { type: { readonly name: string; readonly use: () => void } };
+        [maybe]: { type: number | null };
+    }
+    export interface Resources {
+        [camera]: { type: { readonly x: number; readonly y: number; readonly radius: number } };
+    }
+}
+
+// Shared components are those declaring the trait.
+type Ours = typeof team | typeof cell | typeof level | typeof tags | typeof style | typeof health | typeof position | typeof owner | typeof scores | typeof tool | typeof maybe;
+check<Equal<Extract<Component.With<"shared">, Ours>, typeof team | typeof cell | typeof level | typeof tags | typeof style>>();
+
+// The trait takes comparable data only: numbers, booleans, strings, arrays and plain objects of those.
+check<Equal<Traits<typeof team>["shared"], true>>();
+check<Equal<Traits<typeof style>["shared"], true>>();
+check<Equal<Traits<typeof tags>["shared"], true>>();
+check<Equal<Traits<typeof health>["shared"], true>>();
+// Maps, objects with methods and null aren't.
+check<Equal<Traits<typeof scores>["shared"], never>>();
+check<Equal<Traits<typeof tool>["shared"], never>>();
+check<Equal<Traits<typeof maybe>["shared"], never>>();
+// A reference isn't shared: its target despawning acts on each holder.
+check<Equal<Traits<typeof owner>["shared"], never>>();
+// A shared value lives in shared memory, so it has no thread.
+check<Equal<Traits<typeof team>["thread"], never>>();
+check<Equal<Traits<typeof tags>["thread"], never>>();
+// Rules derive only what has no value of its own to choose an archetype by.
+check<Equal<Traits<typeof team>["derived"], never>>();
+check<Equal<Traits<typeof camera>["shared"], never>>();
+// Every declaration above holds.
+check<Equal<Extract<InvalidDeclarations, { readonly key: Ours }>, never>>();
+
+// A spawner of shared components takes their values first, constant for the spawner, then the rest of each entity's.
+export const spawn = (commands: Commands): Entity => {
+    const recruit = commands.spawn([team, health, position], { [team]: "red" });
+    check<Same<Parameters<typeof recruit>[0], { readonly [health]: number; readonly [position]: Vec2 }>>();
+    recruit({ [health]: 10, [position]: [0, 0] });
+    // Non-shared components may be given first too, constant for every entity it spawns.
+    const veteran = commands.spawn([team, health, position], { [team]: "blue", [health]: 100 });
+    veteran({ [position]: [1, 1] });
+    check<Same<Parameters<typeof veteran>[0], { readonly [position]: Vec2 }>>();
+    // @ts-expect-error a component comes from one of the calls, never both
+    veteran({ [position]: [1, 1], [health]: 3 });
+    // Constants giving every component: the call gives nothing, or an empty object, and never one of them again.
+    const whole = commands.spawn([team, health], { [team]: "red", [health]: 1 });
+    whole();
+    whole({});
+    // @ts-expect-error a component its constants gave
+    whole({ [health]: 2 });
+    // @ts-expect-error a component outside its list
+    whole({ [position]: [0, 0] });
+    // @ts-expect-error every shared component is given first, since its value chooses the archetype
+    commands.spawn([team, health]);
+    // @ts-expect-error and given a value of its type
+    commands.spawn([team, health], { [team]: "green" });
+    // @ts-expect-error each shared component, not only some
+    commands.spawn([team, cell], { [team]: "red" });
+    // @ts-expect-error a constant names only components of the spawn
+    commands.spawn([team], { [team]: "red", [health]: 1 });
+    // A spawner without shared components takes no constants, or any of its components'.
+    commands.spawn([health, position])({ [health]: 1, [position]: [0, 0] });
+    const placed = commands.spawn([health, position], { [position]: [2, 2] });
+    check<Same<Parameters<typeof placed>[0], { readonly [health]: number }>>();
+    return placed({ [health]: 1 });
+};
+
+// A row reads a shared component as its archetype's value, and never assigns it: commands.add moves the entity.
+export const read = System.create({ components: { with: [team, health] } }, (row, { commands }) => {
+    const value: "red" | "blue" = row[team];
+    // Its plain value type, read-only.
+    check<Equal<typeof row[typeof team], "red" | "blue">>();
+    row[health] = value === "red" ? 1 : 2;
+    // @ts-expect-error a shared component's value is its archetype's, read-only: change it with commands.add
+    row[team] = "blue";
+    commands.add(row.entity, team, "blue");
+    commands.remove(row.entity, team);
+});
+System.create({ components: { with: [cell, position] } }, row => {
+    const [x, y] = row[cell];
+    row[position] = [x, y];
+});
+System.create({ components: { with: [health], optional: [team] } }, row => {
+    const value: "red" | "blue" | undefined = row[team];
+    check<Equal<typeof row[typeof team], "red" | "blue" | undefined>>();
+    void value;
+    // @ts-expect-error nor an optional one
+    row[team] = "red";
+});
+System.create({ observer: true, components: { with: [team] } }, row => {
+    check<Equal<typeof row[typeof team], "red" | "blue">>();
+});
+
+// where keeps a system to the archetypes whose shared values pass: by value, or by a predicate of the value and the
+// world's resources.
+export const visible = System.create({
+    components: {
+        with: [position],
+        where: {
+            [cell]: ([x, y], { resources }) => Math.abs(x - resources[camera].x) + Math.abs(y - resources[camera].y) <= resources[camera].radius,
+            [team]: "red",
+        },
+    },
+}, row => {
+    void row[position];
+});
+System.create({ components: { with: [health], where: { [level]: value => value > 1 } } }, () => {});
+System.create({
+    components: {
+        with: [health],
+        // @ts-expect-error where names only shared components
+        where: { [health]: 1 },
+    },
+}, () => {});
+System.create({
+    components: {
+        with: [health],
+        // @ts-expect-error a value is of the component's type
+        where: { [team]: "green" },
+    },
+}, () => {});
+System.create({
+    components: {
+        with: [health],
+        // @ts-expect-error a predicate returns whether the value passes
+        where: { [level]: value => value },
+    },
+}, () => {});
+System.create({
+    components: {
+        with: [health],
+        // @ts-expect-error a predicate reads resources only
+        where: { [level]: (value, { commands }) => value > 0 && commands !== undefined },
+    },
+}, () => {});
+
+// A shared component has no column: no index keys by it, and no render system's accessor reads it.
+Index.create({ key: [health], components: { with: [team] } });
+// @ts-expect-error a key part is a value each entity holds; filter by a shared component with where
+Index.create({ key: [level] });
+System.render({
+    shader: {
+        accessors: {
+            // @ts-expect-error a render accessor reads a column
+            tint: level,
+        },
+    },
+}, () => {});
+
+// where keeps rows unordered across archetypes.
+System.create({
+    components: {
+        with: [health],
+        // @ts-expect-error not with up, order or a target
+        where: { [team]: "red" },
+    },
+    up: { through: owner },
+}, () => {});
+System.create({
+    components: {
+        with: [health],
+        // @ts-expect-error not with up, order or a target
+        where: { [team]: "red" },
+    },
+    target: "entity",
+}, (_row, _context, _input: { readonly entity: Entity }) => {});

package/src/interface/system/struct.ts

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../component/component.js';
+import type { Resource } from '../resource/resource.js';
+import type { IsStruct } from '../schema/is-struct.js';
+
+/** Components whose values are structs, which kernels read and write. */
+export type StructComponent = { [K in Component.Key]: IsStruct<Component.Value<K>> extends true ? K : never }[Component.Key];
+
+/** Resources whose values are structs, which kernels read. */
+export type StructResource = { [K in Resource.Key]: IsStruct<Resource.Value<K>> extends true ? K : never }[Resource.Key];