@adobe/ecs 0.0.0-stage → 0.2.0

package/src/interface/system/values.ts

@@ -0,0 +1,73 @@
+// © 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';
+import type { Resource } from '../resource/resource.js';
+import type { Comparison } from '../world/filter.js';
+import type { Listed, Property } from './property.js';
+
+export type ComponentValues = { readonly [K in Component.Key]: Component.Value<K> };
+export type ResourceValues = { readonly [K in Resource.Key]: Resource.Value<K> };
+
+/** `Read` values are read-only, `Write` values writable. */
+export type Values<Read, Write, Keys extends PropertyKey, Types> =
+    { readonly [K in Exclude<Read, Write> & Keys]: Types[K & keyof Types] }
+    & { -readonly [K in Write & Keys]: Types[K & keyof 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 `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> };
+
+/** A prefix of the key, possibly empty, whose last part may be a comparison. */
+type Prefix<V extends readonly unknown[]> = V extends readonly [infer First, ...infer Rest]
+    ? readonly [] | readonly [First | Comparison<First>] | readonly [First, ...Prefix<Rest>]
+    : readonly [];
+
+/** 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.
+ * Valid until its call site runs again, and each row until the list is.
+ */
+type Rows<R> = {
+    readonly length: number;
+    /**
+     * Whether, since its system last ran, an entity entered or left it or moved within it, or a component in the
+     * lookup's `changed` may have changed in one of its rows: conservative, as `changed` filters are, and true on a
+     * system's first run and in finalizers.
+     */
+    readonly changed: boolean;
+    /** The row at `index`, from 0 to `length - 1`. */
+    at(index: number): R;
+};
+
+/** A lookup through an index, by its declaration `D`: by key, a prefix of it for a sorted index. */
+type IndexLookup<D> =
+    D extends { readonly unique: true }
+        ? D extends { readonly sorted: true }
+            ? ((...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<D>>
+            : (...key: KeyValues<KeyOf<D>>) => Rows<IndexRow<D>>;
+
+/**
+ * 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, "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>
+    : (entity: Entity) => EntityRow<L> | null;

package/src/interface/thread/of.ts

@@ -0,0 +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, 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 shared: true } ? never : Entry extends { readonly thread: infer H extends Thread } ? H : "world";

package/src/interface/thread/thread.ts

@@ -0,0 +1,14 @@
+// © 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`.
+ */
+export interface Threads {
+    /** The thread that created the world. */
+    world: true;
+    /** The window's thread, where the DOM is. */
+    main: true;
+}
+
+/** A logical thread's name. */
+export type Thread = keyof Threads & string;

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

@@ -0,0 +1,75 @@
+// © 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';
+import type { ThreadOf } from './of.js';
+import type { Thread } from './thread.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>() => { };
+
+// Threads are augmentable; `world` and `main` are built in.
+declare module '@adobe/ecs' {
+    export interface Threads {
+        threadTypeTest: true;
+    }
+}
+check<Equal<Extract<Thread, "world" | "main" | "threadTypeTest">, "world" | "main" | "threadTypeTest">>();
+// @ts-expect-error a thread is a declared one
+const undeclared: Thread = "elsewhere";
+void undeclared;
+
+const label = Symbol("threadTypeTest/label");
+const path = Symbol("threadTypeTest/path");
+const handle = Symbol("threadTypeTest/handle");
+const position = Symbol("threadTypeTest/position");
+const element = Symbol("threadTypeTest/element");
+const maybeElement = Symbol("threadTypeTest/maybeElement");
+const bitmap = Symbol("threadTypeTest/bitmap");
+const buffer = Symbol("threadTypeTest/buffer");
+const canvas = Symbol("threadTypeTest/canvas");
+const cache = Symbol("threadTypeTest/cache");
+const port = Symbol("threadTypeTest/port");
+const names = Symbol("threadTypeTest/names");
+
+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" };
+        // Strings and structs live in shared memory, so they have no thread; World.create rejects one with it.
+        [label]: { type: string };
+        [position]: { type: readonly [number, number, number] };
+        // A DOM Node lives on "main", and says so; the build rejects one without it.
+        [element]: { type: HTMLElement; thread: "main" };
+        [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 };
+    }
+    export interface Resources {
+        [canvas]: { type: OffscreenCanvas | null; thread: "threadTypeTest"; transfer: true };
+        [cache]: { type: Map<string, number> | null; thread: "main" };
+        [port]: { type: MessagePort | null; transfer: true };
+        [names]: { type: Map<string, number>; 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>>();
+check<Equal<ThreadOf<{ readonly thread: "main" }, readonly string[]>, "main">>();
+check<Equal<ThreadOf<{ readonly thread: "main" }, string | null>, never>>();
+check<Equal<ThreadOf<{}, null>, "world">>();
+
+// The checks resolve to no check where the DOM library isn't loaded: a scope without `Node` has no DOM Node type.
+type NoDom = { readonly ArrayBuffer: { readonly prototype: ArrayBuffer } };
+check<Equal<IsNode<HTMLElement>, true>>();
+check<Equal<IsNode<HTMLElement | null>, true>>();
+check<Equal<IsNode<HTMLElement, NoDom>, false>>();
+check<Equal<IsNode<string>, false>>();
+check<Equal<IsTransferable<ImageBitmap | null>, true>>();
+check<Equal<IsTransferable<ImageBitmap, NoDom>, false>>();
+check<Equal<IsTransferable<ArrayBuffer, NoDom>, true>>();
+check<Equal<IsTransferable<SharedArrayBuffer>, false>>();
+check<Equal<IsTransferable<null>, false>>();

package/src/interface/trait/key.ts

@@ -0,0 +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" | "shared";

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

@@ -0,0 +1,85 @@
+// © 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 type { Derived, Essential } from '../component/value.js';
+import type { Reduced } from '../resource/reduction.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>() => { };
+
+// Traits other packages define: one only linear components take, one derived components don't need.
+const gpuOnly = Symbol("traitTest/gpuOnly");
+const nonPersistent = Symbol("traitTest/nonPersistent");
+declare module '@adobe/ecs' {
+    export interface Traits<N> {
+        readonly [gpuOnly]: N extends Component.Key ? (IsStruct<Component.Value<N>> extends true ? true : never) : never;
+        readonly [nonPersistent]: N extends Component.Key ? (Components[N] extends { readonly derived: true } ? never : true) : true;
+    }
+}
+
+const parent = Symbol("traitTest/parent");
+const follows = Symbol("traitTest/follows");
+const slot = Symbol("traitTest/slot");
+const ready = Symbol("traitTest/ready");
+const score = Symbol("traitTest/score");
+const link = Symbol("traitTest/link");
+const pair = Symbol("traitTest/pair");
+const cache = Symbol("traitTest/cache");
+const time = Symbol("traitTest/time");
+const sum = Symbol("traitTest/sum");
+
+declare module '@adobe/ecs' {
+    export interface Components {
+        [parent]: { type: Entity; reference: "owner" };
+        [follows]: { type: Entity; reference: "weak" };
+        [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 };
+    }
+    export interface Resources {
+        [time]: { type: number; default: 0 };
+        [sum]: { type: number; reduce: "+" };
+    }
+}
+
+// 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;
+check<Equal<Component.Value<typeof parent>, Entity>>();
+check<Equal<Component.Value<typeof link>, { readonly to: Entity; readonly weight: number }>>();
+check<Equal<Extract<Component.With<"reference">, Ours>, typeof parent | typeof follows>>();
+check<Equal<Extract<Component.With<"reference", "owner">, Ours>, typeof parent>>();
+check<Equal<Extract<Derived, Ours>, typeof slot>>();
+check<Equal<Extract<Component.With<typeof gpuOnly>, Ours>, typeof pair>>();
+type Persisted = Exclude<Essential, Component.With<typeof nonPersistent>>;
+check<Equal<Extract<Persisted, Ours>, Exclude<Ours, typeof slot | typeof cache>>>();
+check<Equal<Resource.Value<typeof time>, number>>();
+
+// Commands add and remove only essential components.
+export const issue = (commands: Commands, entity: Entity): void => {
+    commands.add(entity, [score, parent], { [score]: 1, [parent]: entity });
+    commands.remove(entity, score);
+    // @ts-expect-error derived components are added only by rules
+    commands.spawn([slot])({ [slot]: 1 });
+    // @ts-expect-error derived components are added only by rules
+    commands.add(entity, slot, 1);
+    // @ts-expect-error derived components are removed only by rules
+    commands.remove(entity, slot);
+};
+
+// Entities are branded numbers.
+const raw: number = Entity.none;
+// @ts-expect-error a number isn't an entity
+const forged: Entity = 3;
+void raw;
+void forged;
+check<Equal<Reduced & typeof sum, typeof sum>>();
+check<Equal<Reduced & typeof time, never>>();

package/src/interface/trait/types.ts

@@ -0,0 +1,69 @@
+// © 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 { IsComparable, IsString, IsStruct } from '../schema/is-struct.js';
+import type { Thread } from '../thread/thread.js';
+
+/** The value type of the component or resource `N`. */
+type ValueOf<N> = N extends Component.Key ? Component.Value<N> : N extends Resource.Key ? Resource.Value<N> : never;
+
+/**
+ * Whether each component's and resource's value is a struct, `"string"` for a string, computed once so a check is a
+ * lookup. Its keys are remapped (`as K`) so a generic key's lookup stays one: resolved as `IsStruct` of a generic value,
+ * as a registration resolves its contextual type, it recurses without end.
+ */
+type Structs = { readonly [K in Component.Key | Resource.Key as K]: IsString<ValueOf<K>> extends true ? "string" : IsStruct<ValueOf<K>> };
+
+/**
+ * The value each trait allows on the component or resource `N`. Augment it, with this exact type parameter, to
+ * 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. 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
+        : never;
+    /**
+     * On an entity-valued component: when its target despawns, `owner` despawns the holder and `weak` removes the
+     * 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 } | { 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
+     * operator's identity and leaves it holding the fold of every contribution. Booleans fold bitwise.
+     */
+    readonly reduce: N extends Resource.Key
+        ? [Resource.Value<N>] extends [boolean] ? "&" | "|" | "^" : Structs[N] extends true ? Reduction : never
+        : never;
+    /**
+     * 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
+        : 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

@@ -0,0 +1,28 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "../../dist/interface",
+    "composite": true,
+    "types": [
+      "@webgpu/types"
+    ],
+    "paths": {
+      "@adobe/ecs": [
+        "./index.ts"
+      ],
+      "@adobe/ecs/*": [
+        "./index.ts"
+      ]
+    },
+    "lib": [
+      "ES2024",
+      "ESNext.Disposable",
+      "DOM",
+      "DOM.Iterable"
+    ]
+  },
+  "include": [
+    "**/*"
+  ]
+}

package/src/interface/world/create.ts

@@ -0,0 +1,22 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Resource } from '../resource/resource.js';
+import type { WorldWritten } from '../resource/written.js';
+import type { InvalidDeclarations } from './declarations.js';
+import type { World } from './world.js';
+
+/** Values resources start at in place of their defaults: any but those only the world writes. */
+export type InitialResources = { readonly [K in Exclude<Resource.Key, WorldWritten>]?: Resource.Value<K> };
+
+/**
+ * Creates a world on this thread, synchronously, with resources starting at the given values in place of their
+ * defaults. This thread is its `"world"` thread for the world's life: it runs the sync points, the ticks and the GPU
+ * device, and fills every logical thread no joined thread claims. Keys are the resources' symbols, built-in ones
+ * included (`{ [workers]: 0 }`); string keys are never a resource's, so they're ignored. Throws for a symbol that isn't
+ * a resource, or is one only the world writes. While a declaration's trait or default doesn't hold, each call fails to
+ * compile, once, naming each such key, its members and what's wrong with them.
+ */
+export type Create = (
+    // Unknown while every declaration holds; else what a call's `this` can't be, so the call reports it, printed whole.
+    this: [InvalidDeclarations] extends [never] ? unknown : { readonly "declarations don't hold": { readonly [D in InvalidDeclarations as D["key"]]: D["members"] } },
+    resources?: InitialResources,
+) => World;

package/src/interface/world/declarations.ts

@@ -0,0 +1,34 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../component/component.js';
+import type { Components } from '../component/types.js';
+import type { Resource } from '../resource/resource.js';
+import type { Resources } from '../resource/types.js';
+import type { Key as TraitKey } from '../trait/key.js';
+import type { Traits } from '../trait/types.js';
+
+/**
+ * The members of key `K`'s declaration `Entry` that don't hold: a trait whose value `Traits<K>` doesn't allow, a name
+ * that isn't a trait, and a `default` that isn't of the declared type. Checks only `K`'s own traits, so the whole check
+ * is linear in the declarations.
+ */
+type Invalid<K extends Component.Key | Resource.Key, Entry, Value> =
+    | { readonly [T in Exclude<keyof Entry, "type" | "default">]-?: T extends TraitKey ? ([Entry[T]] extends [Traits<K>[T]] ? never : T) : T }[Exclude<keyof Entry, "type" | "default">]
+    | (Entry extends { readonly default: infer D } ? ([D] extends [Value] ? never : "default") : never);
+
+/**
+ * Key `K` with what's wrong with each member that doesn't hold, keyed by member so an error prints a trait by its
+ * key's binding; written in place, as an alias would print by its name.
+ */
+type Reported<K, Members extends PropertyKey> = [Members] extends [never] ? never : {
+    readonly key: K;
+    readonly members: { readonly [M in Members]: M extends "default" ? "isn't of the declared type" : M extends TraitKey ? "isn't allowed on this key" : "isn't a trait" };
+};
+
+/**
+ * Every declaration in `Components` and `Resources` with members that don't hold, each as its key and what's wrong
+ * with those members; `never` when all hold. The build registers declarations without a type checker, so
+ * `World.create` reports these.
+ */
+export type InvalidDeclarations =
+    | { readonly [K in Component.Key]: Reported<K, Invalid<K, Components[K], Component.Value<K>>> }[Component.Key]
+    | { readonly [K in Resource.Key]: Reported<K, Invalid<K, Resources[K], Resource.Value<K>>> }[Resource.Key];

package/src/interface/world/filter.ts

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+export type Comparison<T> = {
+    readonly "=="?: T;
+    readonly "!="?: T;
+    readonly "<"?: T;
+    readonly ">"?: T;
+    readonly "<="?: T;
+    readonly ">="?: T;
+};

package/src/interface/world/index.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// The `World` namespace's members: none, since a consumer declares nothing more with it.
+export {};

package/src/interface/world/join.ts

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Thread } from '../thread/thread.js';
+import type { World } from './world.js';
+
+/**
+ * Joins, from another thread, a world that `share` let join through the other end of `port`, claiming the logical
+ * `threads` this thread fills: their objects live here, and the systems and finalizers reading them run here. Resolves,
+ * once the world accepted the claim, to the same world: its `run` runs systems there, and its `add` and `remove` take
+ * observer systems, which run here after the world's sync points. Add them before awaiting anything else, so the
+ * world's `share` resolves with them in place. Its `dispose` disconnects this thread. Rejects with an `Error` saying
+ * why it didn't join: the world refused the claim, was disposed, or its thread ended first, as the platform reports it:
+ * the world's `Worker` failing to start or throwing first, a port closed, as in node, or, in a browser, the world's
+ * thread ending once it was shared through a port this thread listened on. A browser world's worker that the page ended
+ * before this thread heard from it isn't reported, so the join stays pending. Rejects too where memory can't be shared,
+ * as without cross-origin isolation.
+ */
+export type Join = (port: Parameters<World["share"]>[0], options?: { readonly threads?: readonly Exclude<Thread, "world">[] }) => Promise<World>;

package/src/interface/world/loop.type-test.ts

@@ -0,0 +1,72 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import {
+    Finalizer, System, always, cadence, clock, gpuDevice, wake, workers,
+    type Component, type Resource, type World,
+} from '../index.js';
+import type { Create } from './create.js';
+import type * as Ecs from '../index.js';
+import { main, move } from '../system/system.type-test.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>() => { };
+
+declare const world: World;
+declare const create: Create;
+
+// Systems added to every tick take no input.
+const added: void = world.add(main);
+// @ts-expect-error a system with input can't be added, since ticks pass none
+world.add(move);
+void added;
+// Removing takes a value passed to add, which takes no input.
+const removed: void = world.remove(main);
+// @ts-expect-error a system with input was never added
+world.remove(move);
+void removed;
+
+// Built-in resources.
+check<Equal<Resource.Value<typeof gpuDevice>, GPUDevice | null>>();
+check<Equal<Resource.Value<typeof workers>, number | null>>();
+// null is the platform's choice of pool size.
+export const platformPool: World = create({ [workers]: null });
+check<Equal<Resource.Value<typeof always>, boolean>>();
+check<Equal<Resource.Value<typeof wake>, number>>();
+check<Equal<Resource.Value<typeof clock>, { readonly now: number; readonly delta: number; readonly tick: number }>>();
+check<Equal<Resource.Value<typeof cadence>, { readonly kind: "frame" } | { readonly kind: "fixed"; readonly step: number; readonly maxSteps?: number }>>();
+// Built-in resources are symbols, so worlds start them at other values through their imported keys.
+check<Equal<[typeof gpuDevice, typeof workers, typeof cadence, typeof always, typeof wake, typeof clock] extends readonly symbol[] ? true : false, true>>();
+// @ts-expect-error a resource key is its imported symbol, never its description
+create({ workers: 2 });
+
+// There are no built-in components: a joined thread's progress is the implementation's.
+type Removed = "component" | "persistent" | "shared" | "threadPort" | "threadStatus" | "threadClaims";
+check<Equal<Extract<Removed, keyof typeof Ecs | Component.Key>, never>>();
+
+// Systems read the loop's state, ask for a wake time and change its cadence.
+System.create({}, ({ resources }) => {
+    const now: number = resources[clock].now;
+    void now;
+});
+System.create({}, ({ resources }) => {
+    resources[cadence] = { kind: "fixed", step: 1000 / 60, maxSteps: 2 };
+    resources[always] = true;
+});
+System.create({}, ({ reduce }) => { reduce[wake](1000); });
+System.create({}, ({ resources }) => {
+    // @ts-expect-error clock is written only by the world
+    resources[clock] = resources[clock];
+    // @ts-expect-error wake is reduced, never written
+    resources[wake] = 0;
+});
+Finalizer.create({ components: {} }, (_row, { resources }) => {
+    // @ts-expect-error a finalizer doesn't write clock either
+    resources[clock] = resources[clock];
+});
+// @ts-expect-error a cadence is a frame or a fixed step
+System.create({}, ({ resources }) => { resources[cadence] = { kind: "fixed" }; });
+
+// Worlds start the loop's settings at other values; clock is the world's own.
+const paced: World = create({ [cadence]: { kind: "fixed", step: 10 }, [always]: true, [workers]: 2 });
+// @ts-expect-error clock is written only by the world
+create({ [clock]: { now: 0, delta: 0, tick: 0 } });
+void paced;

package/src/interface/world/run.type-test.ts

@@ -0,0 +1,87 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type * as Ecs from '../index.js';
+import { gpuDevice } from '../resources/gpu-device.js';
+import { System } from '../system/system.js';
+import { integrate, main, move, position, time, watchTime } from '../system/system.type-test.js';
+import type { World } from './world.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>() => { };
+
+declare const world: World;
+declare const ecs: typeof Ecs;
+
+const frames = Symbol("runTypeTest/frames");
+declare module '@adobe/ecs' {
+    export interface Resources {
+        [frames]: { type: number };
+    }
+}
+
+// A run resolves to its per-run body's value: a one-off read is an observer system returning it.
+const count = System.create({ observer: true }, ({ resources }) => resources[frames]);
+check<Equal<typeof count, System<undefined, number>>>();
+const counted: Promise<number> = world.run(count);
+// @ts-expect-error a run of it resolves to a number
+const notText: Promise<string> = world.run(count);
+
+// A system that declares nothing, and one taking input, resolve to what their bodies return.
+const next = System.create(({ resources }) => resources[frames] + 1);
+const nextValue: Promise<number> = world.run(next);
+const scaled = System.create({}, ({ resources }, input: { readonly by: number }) => ({ scaled: resources[frames] * input.by }));
+const scaledValue: Promise<{ scaled: number }> = world.run(scaled, { by: 2 });
+
+// A body that may be skipped, as one whose conditions or resource change filters can fail, may give undefined.
+const changedFrames = System.create({ observer: true, resources: { changed: [frames] } }, ({ resources }) => resources[frames]);
+check<Equal<typeof changedFrames, System<undefined, number | undefined>>>();
+const whileDevice = System.create({ resources: { is: [gpuDevice] } }, () => "drawn");
+const drawn: Promise<string | undefined> = world.run(whileDevice);
+
+// Row systems, composites, render systems and bodies returning nothing resolve to nothing.
+const rows: Promise<void> = world.run(integrate);
+const composite: Promise<void> = world.run(main);
+const input: Promise<void> = world.run(move, { distance: 1 });
+const nothing: Promise<void> = world.run(watchTime);
+const valuedRows = System.create({ components: { with: [position] } }, row => row[position]);
+check<Equal<typeof valuedRows, System>>();
+check<Equal<typeof main, System>>();
+check<Equal<typeof watchTime, System>>();
+const drawing = System.render({ shader: { accessors: { place: position } } }, () => {});
+check<Equal<typeof drawing, System>>();
+
+// What a body returns doesn't change where a system goes: composites and constraints take it, and so do ticks.
+const reads = System.create([count, integrate]);
+check<Equal<typeof reads, System>>();
+System.create({ after: [count] }, () => {});
+world.add(count);
+world.add(next);
+
+// A run that fails rejects with an Error naming what failed; nothing else describes a run, so there's no Report.
+// @ts-expect-error runs give their body's value and reject with what failed: no Report
+void ecs.Report;
+// @ts-expect-error no run numbers
+const numbered: Promise<number> = world.run(main);
+
+void [counted, notText, nextValue, scaledValue, drawn, rows, composite, input, nothing, numbered, time];
+
+// A body returns no promise: it starts the work, and a later run finishes it.
+// @ts-expect-error a body returns no promise
+System.create(() => Promise.resolve(1));
+// @ts-expect-error a body returns no promise
+System.create({ observer: true }, () => Promise.resolve(1));
+// @ts-expect-error a body returns no promise, a row system's neither
+System.create({ components: { with: [position] } }, () => Promise.resolve());
+// @ts-expect-error a body returns no promise, a render system's neither
+System.render({ shader: { accessors: { place: position } } }, () => Promise.resolve());
+const thenable: PromiseLike<number> = Promise.resolve(1);
+// @ts-expect-error nor any PromiseLike
+System.create(() => thenable);
+// @ts-expect-error nor a return type wide enough to hide one, unknown
+System.create((): unknown => Promise.resolve(1));
+// @ts-expect-error or object
+System.create((): object => Promise.resolve(1));
+// @ts-expect-error a row body's neither
+System.create({ components: { with: [position] } }, (): unknown => Promise.resolve());
+// Values of other types are a body's to return.
+System.create(() => ({}));
+System.create((): { readonly then?: never } => ({}));