@adobe/ecs 0.1.0 → 0.2.1

package/dist/interface/system/values.d.ts

@@ -5,10 +5,10 @@ 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>;
+    readonly [K in Component.Key]: Component<K>;
 };
 export type ResourceValues = {
-    readonly [K in Resource.Key]: Resource.Value<K>;
+    readonly [K in Resource.Key]: Resource<K>;
 };
 /** `Read` values are read-only, `Write` values writable. */
 export type Values<Read, Write, Keys extends PropertyKey, Types> = {
@@ -20,19 +20,19 @@ export type Values<Read, Write, Keys extends PropertyKey, Types> = {
 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>;
+    readonly [I in keyof K]: Component<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 lookup's `read` values, read-only. */
-type IndexRow<L> = {
+/** 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 Listed<L, "read"> & Component.Key]: Component.Value<K>;
+    readonly [K in HeldBy<D> & Component.Key]: Component<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.
@@ -50,24 +50,24 @@ type Rows<R> = {
     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, L> = D extends {
+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 : D extends {
+} ? ((...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 [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)]: K extends Component.Key ? Component.Value<K> : boolean;
+    } ? "changed" : never)]: K extends Component.Key ? K extends Listed<L, "with"> ? Component<K> : Component<K> | undefined : boolean;
 };
 export type LookupFunction<L> = L extends {
     readonly index: Index<infer D>;
-} ? IndexLookup<D, L> : (entity: Entity) => EntityRow<L> | null;
+} ? IndexLookup<D> : (entity: Entity) => EntityRow<L> | null;
 export {};

package/dist/interface/thread/of.d.ts

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

package/dist/interface/trait/key.d.ts

@@ -1,4 +1,4 @@
 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/dist/interface/trait/types.d.ts

@@ -4,10 +4,10 @@ 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`. */
-type ValueOf<N> = N extends Component.Key ? Component.Value<N> : N extends Resource.Key ? Resource.Value<N> : never;
+type ValueOf<N> = N extends Component.Key ? Component<N> : N extends Resource.Key ? Resource<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,
@@ -18,15 +18,18 @@ type Structs = {
 };
 /**
  * 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;
@@ -39,18 +42,33 @@ export interface Traits<N extends Component.Key | Resource.Key> {
      */
     readonly reference: N extends Component.Key ? Components[N] extends {
         readonly derived: true;
-    } ? never : [Component.Value<N>] extends [Entity] ? "owner" | "weak" : never : never;
+    } | {
+        readonly shared: true;
+    } ? never : [Component<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;
+    readonly reduce: N extends Resource.Key ? [Resource<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 : 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<N>> extends true ? true : never : never;
 }
 export {};

package/dist/interface/world/create.d.ts

@@ -1,15 +1,17 @@
 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>;
+    readonly [K in Exclude<Resource.Key, WorldWritten>]?: Resource<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.
+ * The type of `World.create`.
+ * @inline
  */
-export type Create = (resources?: InitialResources) => World;
+export type Create = (this: [InvalidDeclarations] extends [never] ? unknown : {
+    readonly "declarations don't hold": {
+        readonly [D in InvalidDeclarations as D["key"]]: D["members"];
+    };
+}, resources?: InitialResources) => World;

package/dist/interface/world/declarations.d.ts

@@ -0,0 +1,37 @@
+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<K>>>;
+}[Component.Key] | {
+    readonly [K in Resource.Key]: Reported<K, Invalid<K, Resources[K], Resource<K>>>;
+}[Resource.Key];
+export {};

package/dist/interface/world/declarations.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=declarations.js.map

package/dist/interface/world/declarations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declarations.js","sourceRoot":"","sources":["../../../src/interface/world/declarations.ts"],"names":[],"mappings":""}

package/dist/interface/world/filter.js

@@ -1,2 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 export {};
 //# sourceMappingURL=filter.js.map

package/dist/interface/world/filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../../src/interface/world/filter.ts"],"names":[],"mappings":""}
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../../src/interface/world/filter.ts"],"names":[],"mappings":"AAAA,uDAAuD"}

package/dist/interface/world/join.d.ts

@@ -1,11 +1,9 @@
 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. The world
- * it returns is the same one: its `run` runs systems there, and its `add` and `remove` take observer systems, which run
- * here after the world's sync points. Its `dispose` disconnects this thread.
+ * The type of `World.join`.
+ * @inline
  */
 export type Join = (port: Parameters<World["share"]>[0], options?: {
     readonly threads?: readonly Exclude<Thread, "world">[];
-}) => World;
+}) => Promise<World>;

package/dist/interface/world/world.d.ts

@@ -7,25 +7,33 @@ import type { System } from '../system/system.js';
 export type World = {
     /**
      * The one way to change state. Runs are sequential in call order; physically, any that don't conflict overlap. Each
-     * runs a system or composite, ending in a sync point, and resolves to its number: every run and tick takes the
-     * next, in the order they run. What went wrong, if anything, is a report the world spawns for that number (see
-     * `Report`): systems, finalizers and GPU work that failed, systems skipped after a failed tier, commands that did
-     * nothing, and warnings. Rejects only when the run can't happen or finish: registration fails, the world is
-     * disposed, its GPU device is lost, or its sync point can't apply a command's value. Observer systems, the run's and
-     * those added, run after its sync point and its report, before it resolves; their throws are `"system"` failures
-     * in the next run's report, since each report's errors are written once. A run of observer systems alone runs them
-     * once after an empty sync point, and doesn't wake the loop.
+     * runs a system or composite, ending in a sync point, then observer systems, the run's and those added, and
+     * resolves to what a per-run body returns: a system without components resolves to its body's value, or
+     * `undefined` when its body was skipped, and any other system or composite to nothing. So a one-off read is a run
+     * of an observer system returning what it read; one that runs on a joined thread, as it reads objects there, runs
+     * there before the run resolves, to its value as structured clone. A run of observer systems alone runs them once
+     * after an empty sync point, and doesn't wake the loop.
+     *
+     * When a system or finalizer of the run fails, later tiers are skipped, the sync point still applies what was done,
+     * and once its observer systems ran the run rejects with an `Error` naming each failure, its system's label and id,
+     * message and cause. It rejects too when the run can't happen or finish: registration fails, the world is disposed,
+     * its GPU device is lost, or its sync point can't apply a command's value. What fails after it, an observer system
+     * added or GPU work, is reported out of band, as ticks' failures are (see `add`).
      */
-    run<I>(system: System<I>, ...input: Input<NoInfer<I>>): Promise<number>;
+    run<I, R>(system: System<I, R>, ...input: Input<NoInfer<I>>): Promise<R>;
     /**
      * Adds a system to every tick, from the next one on, ordered with those already added by its constraints, as a
      * composite's members are. A tick runs on a beat of the `cadence` resource where `always` is set, `wake` is due or
      * a run arrived since the last tick, and only while some system is added. Throws for a system with no ordering path
-     * to one already added that conflicts with it; failures are in the tick's report. An observer system runs after
-     * every run's and tick's sync point instead. It never conflicts and doesn't count as an added system for ticking.
-     * On a joined thread `add` takes only observer systems, whose keys need ids: each runs on that thread after the
-     * world's sync points, once for the newest when the thread fell behind, reading structs and the objects of the
-     * threads it fills as of one sync point; its failures are in a later run's report.
+     * to one already added that conflicts with it. An observer system runs after every run's and tick's sync point
+     * instead. It never conflicts and doesn't count as an added system for ticking. On a joined thread `add` takes only
+     * observer systems, whose keys need ids: each runs on that thread after the world's sync points, once for the
+     * newest when the thread fell behind, reading structs and the objects of the threads it fills as of one sync point.
+     *
+     * What added systems throw, and what fails in ticks, is reported out of band on the world's thread, as an `Error`
+     * naming what failed with what it threw as its cause: through `reportError` where the platform has it, as browsers
+     * and their workers do, and otherwise thrown from a task of its own, an uncaught exception, as in node. A system is
+     * reported once while it keeps failing, and again once it has run without failing since.
      */
     add(system: System<void>): void;
     /**
@@ -39,8 +47,14 @@ export type World = {
     /**
      * Lets another thread join this world through `port`, one end of a channel to it, of the browser or node: a
      * `MessagePort`, a `Worker`, or a worker's own scope, `self` or node's `parentPort`. That thread joins through the
-     * other end, claiming the logical threads it fills; a thread claimed twice can't join. Throws on a joined thread,
-     * and where memory can't be shared, as without cross-origin isolation.
+     * other end, claiming the logical threads it fills. Resolves once it has joined: the threads it claims are its own,
+     * and the observer systems it added as its join resolved, before awaiting anything else, are added, so a run
+     * started afterwards runs on it and reaches them; one it adds later reaches the runs after its add arrived.
+     * Rejects with an `Error` saying why it didn't join: the world refused its claim, as of a thread claimed twice, the
+     * world was disposed, the port is shared already, or that thread ended first, as the platform reports it: a
+     * `Worker` failing to start or throwing first, a node worker exiting, a port closed, or, once that thread asked to
+     * join, its end however it came. A browser worker ended before it asked to join isn't reported, so its share stays
+     * pending. Rejects too on a joined thread, and where memory can't be shared, as without cross-origin isolation.
      */
     share(port: {
         readonly postMessage: (message: never, transfer: never) => void;
@@ -48,7 +62,7 @@ export type World = {
         readonly addEventListener: (type: "message", listener: (event: unknown) => void) => void;
     } | {
         readonly on: (event: "message", listener: (value: unknown) => void) => unknown;
-    })): void;
+    })): Promise<void>;
     /**
      * Waits for pending runs, then stops ticking and releases memory, and joined threads' runs reject; the world is
      * unusable afterwards. On a joined thread, it disconnects this thread.

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "@adobe/ecs",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Adobe ECS",
+  "license": "MIT",
   "type": "module",
   "sideEffects": false,
   "private": false,
+  "pages": [
+    {
+      "from": "docs",
+      "to": "ecs"
+    }
+  ],
   "independentVersion": true,
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -21,21 +28,25 @@
     "!dist/guide",
     "!dist/perf",
     "!dist/perftest",
-    "!dist/samples",
     "!dist/observe",
     "!dist/**/*.tsbuildinfo",
     "src",
     "LICENSE"
   ],
   "devDependencies": {
-    "@types/estree": "^1.0.5",
+    "@oxc-parser/binding-wasm32-wasip1": "0.155.0",
+    "@oxc-transform/binding-wasm32-wasip1": "0.155.0",
+    "@types/estree": "^1.0.9",
     "@types/node": "^25.6.0",
     "@vitest/browser-playwright": "^5.0.5",
+    "@vitest/coverage-v8": "^5.0.5",
     "@webgpu/types": "^0.1.61",
     "playwright": "^1.64.1",
+    "typedoc": "^0.28.9",
     "typescript": "^5.8.3",
     "vite": "^8.3.4",
-    "vitest": "^5.0.5"
+    "vitest": "^5.0.5",
+    "wabt": "1.0.39"
   },
   "peerDependencies": {
     "vite": "^8.0.0"
@@ -60,10 +71,12 @@
     "dev": "tsc -b -w --preserveWatchOutput",
     "typecheck": "tsc -b",
     "test": "pnpm exec playwright install chromium && vitest --run",
+    "test:coverage": "pnpm exec playwright install chromium && vitest --run --coverage",
+    "test:coverage:without-guide": "pnpm exec playwright install chromium && ECS_WITHOUT_GUIDE=1 vitest --run --coverage",
     "test:perf": "pnpm exec playwright install chromium && vitest --run --config vitest.perf.config.ts",
     "perf": "node scripts/perf.mjs",
     "perf:browser": "node scripts/perf.mjs --browser",
     "perf:report": "node scripts/perf.mjs --report",
-    "sample": "vite --config vite.sample.config.ts"
+    "docs": "typedoc"
   }
 }