@adobe/ecs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,71 @@
+import type { Index } from '../indexes/index-type.js';
+import type { Schema } from '../schema/schema.js';
+import type { ComponentAccess, ResourceAccess, SystemLookup, Up } from './access.js';
+import type { Name } from './name.js';
+import type { Shader } from './render.js';
+import type { System } from './system.js';
+import type { OperatorOf, Reduced } from '../resource/reduction.js';
+/**
+ * A system never declares its thread: it runs on the one its object components and resources live on, those it
+ * reads, writes or filters on by change, through `components`, `lookup`, `up` and `resources` but `has` and `not`.
+ * Without them, a kernel runs on the kernel pool and any other system on `"world"`.
+ */
+export type Declaration = {
+    readonly name?: Name;
+    /**
+     * Compiled to a kernel, which the build rejects if the body leaves the kernel subset. Values in `components` and
+     * `lookup` must be structs and resources read-only. Without it, the system runs as written, on its thread.
+     * - `"cpu"`: runs on the kernel pool. - `"gpu"`: also has no lookups, change filters, commands or loops, and only
+     *   4-byte scalar values, its `up` included. It runs as a   compute shader in a world with a GPU, and as a `"cpu"`
+     *   kernel in one without. Every matched row counts as   changed in what it writes.
+     */
+    readonly kernel?: "cpu" | "gpu";
+    /** The entities it runs over, and what it reads and writes of theirs. Omitted for a system that runs once per run. */
+    readonly components?: ComponentAccess;
+    readonly lookup?: {
+        readonly [name: string]: SystemLookup;
+    };
+    /**
+     * Runs rows in depth order through `through`, so each reads its parent's `read` values after the parent ran, as
+     * the context's `up`, or null for a row without a parent. With change filters, a row also passes when its parent,
+     * or what it reads of its parent, changed since the system last ran, or it moved to another archetype, as removing
+     * its parent moves it. Rows on or under a parent cycle don't run.
+     */
+    readonly up?: Up;
+    /**
+     * Runs the rows it matches that this sorted index holds, in key order and then entity order; with change filters,
+     * the rows that pass, in that order. Commands, reductions and side effects follow it. Like a lookup through the
+     * index, it reads the index's key parts and doesn't write them. Not with `up`.
+     */
+    readonly order?: Index<{
+        readonly sorted: true;
+    }>;
+    readonly resources?: ResourceAccess;
+    /** The resources its body contributes to, each with the operator its `reduce` trait declares. */
+    readonly reduce?: {
+        readonly [K in Reduced]?: OperatorOf<K>;
+    };
+    /** The object of named fields passed to each run. A system with input can't use `added` or `changed`. */
+    readonly input?: Extract<Schema, {
+        readonly type: "object";
+    }>;
+    /**
+     * The input field naming the one entity it runs on: its body runs once, on that entity's row, when the entity is
+     * alive and matches `components`, and not at all otherwise. Needs `components`; not with `kernel`, `up`, `order`
+     * or `reduce`.
+     */
+    readonly target?: string;
+    /** Makes this a render system (see `render`): its body records GPU work over the GPU copy of the components it names. */
+    readonly shader?: Shader;
+    /** Hard constraint. */
+    readonly before?: readonly System<unknown>[];
+    /** Hard constraint. */
+    readonly after?: readonly System<unknown>[];
+    /** Runs inside the span of the systems listed: after what they follow and before what follows them. */
+    readonly during?: readonly System<unknown>[];
+    /**
+     * Runs after the last sync point of each run and tick (a tick is a run of the added composite), reading the settled
+     * state; changes nothing; never ordered; doesn't keep the loop ticking.
+     */
+    readonly observer?: true;
+};

package/dist/interface/system/declaration.js

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

package/dist/interface/system/declaration.js.map

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

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

@@ -0,0 +1,4 @@
+import type { Composite } from './composite.js';
+import type { Leaf } from './leaf.js';
+/** What the implementation knows of a system: the value a constructor returned, with its kind, declaration and body. */
+export type Definition = Leaf | Composite;

package/dist/interface/system/definition.js

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

package/dist/interface/system/definition.js.map

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

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

@@ -0,0 +1,3 @@
+export type { Commands } from './commands.js';
+export * from './create.js';
+export { render, type RenderContext, type RenderTable } from './render.js';

package/dist/interface/system/index.js

@@ -0,0 +1,3 @@
+export * from './create.js';
+export { render } from './render.js';
+//# sourceMappingURL=index.js.map

package/dist/interface/system/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/interface/system/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAwC,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,28 @@
+import type { Schema } from '../schema/schema.js';
+import type { System } from './system.js';
+/**
+ * The input a system declares: a value of its `input` schema, or `undefined` without one; `unknown` for `any`, as an
+ * overload's declaration erases to, since every schema's value type is too deep to compute.
+ */
+export type InputOf<D> = 0 extends 1 & D ? unknown : D extends {
+    readonly input: infer A extends Schema;
+} ? Schema.ToType<A> : undefined;
+/** What `run` takes after a system: nothing, or one value. */
+export type Input<I> = [I] extends [undefined] ? [] : [input: I];
+/** A member's input fields, or `unknown` without input. */
+type Fields<S> = S extends System<infer I> ? [Exclude<I, undefined>] extends [never] ? unknown : Exclude<I, undefined> : unknown;
+type Merged<T, A = unknown> = T extends readonly [infer S, ...infer R] ? Merged<R, A & Fields<S>> : A;
+/** The input a composite of `T` takes: every field of its members' inputs, or `undefined` when none has input. */
+export type CompositeInputOf<T> = unknown extends Merged<T> ? undefined : {
+    [K in keyof Merged<T>]: Merged<T>[K];
+};
+/** The fields of `M` whose type differs from the one the composite's input `I` gives them. */
+type Conflicts<M, I> = {
+    [K in keyof M]-?: [Exclude<M[K], undefined>] extends [Exclude<I[K & keyof I], undefined>] ? never : K;
+}[keyof M];
+type Checked<S, I> = [Conflicts<Fields<S>, I>] extends [never] ? S : `Input field "${Extract<Conflicts<Fields<S>, I>, string>}" has a different type in another member of this composite.`;
+/** Members whose input has a field of a different type than another member's. */
+export type CheckMembers<T> = {
+    readonly [P in keyof T]: Checked<T[P], Merged<T>>;
+};
+export {};

package/dist/interface/system/input.js

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

package/dist/interface/system/input.js.map

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

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

@@ -0,0 +1,12 @@
+import type { Declaration } from './declaration.js';
+import type { Name } from './name.js';
+/**
+ * A system that runs a body: `"render"` for one made by `render`, `"system"` otherwise. Its body's parameters are
+ * checked where it's created, so a leaf holds any body.
+ */
+export type Leaf = {
+    readonly kind: "system" | "render";
+    readonly name: Name;
+    readonly declaration: Declaration;
+    readonly body: (...parameters: never[]) => void;
+};

package/dist/interface/system/leaf.js

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

package/dist/interface/system/leaf.js.map

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

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

@@ -0,0 +1,6 @@
+/**
+ * The label reports and errors give it, which needn't be unique: the value its constructor returns is its identity, so
+ * separately written code can't collide by name. Namespacing it (`"physics/integrate"`) keeps labels short. Without
+ * one, it's labeled by its binding and the id the plugin gave it, or else by its kind numbered.
+ */
+export type Name = string;

package/dist/interface/system/name.js

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

package/dist/interface/system/name.js.map

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

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

@@ -0,0 +1,4 @@
+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/dist/interface/system/property.js

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

package/dist/interface/system/property.js.map

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

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

@@ -0,0 +1,65 @@
+import type { Component } from '../component/component.js';
+import type { Condition } from '../resource/condition.js';
+import type { Resource } from '../resource/resource.js';
+import type { ThreadOfResource } from '../resource/value.js';
+import { gpuDevice } from '../resources/gpu-device.js';
+import type { Body } from './body.js';
+import type { Name } from './name.js';
+import type { StructComponent } from './struct.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).
+ */
+export type Shader = {
+    readonly group?: number;
+    readonly accessors: {
+        readonly [name: string]: StructComponent;
+    };
+};
+/** One group of matching rows, `0` to `count`. `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 = {
+    readonly name?: Name;
+    /** It reads the components its accessors name. */
+    readonly components?: {
+        readonly has?: readonly Component.Key[];
+        readonly not?: readonly Component.Key[];
+    };
+    /** It runs only while `gpuDevice` is set, as if `is` listed it. */
+    readonly resources?: {
+        readonly read?: readonly Resource.Key[];
+        readonly is?: readonly Condition[];
+        readonly not?: readonly Condition[];
+    };
+    readonly shader: Shader;
+    readonly before?: readonly System<unknown>[];
+    readonly after?: readonly System<unknown>[];
+    readonly during?: readonly System<unknown>[];
+};
+/** A render declaration with the components its accessors name as `components.read`. */
+type Rendered<D extends RenderDeclaration> = D & {
+    readonly components: {
+        readonly read: readonly StructComponent[];
+    };
+};
+/**
+ * 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`. Throws as `create` does, and for an accessor its shader can't read on the GPU.
+ */
+export declare const render: <const D extends RenderDeclaration>(declaration: D & OneThread<ThreadsOf<D> | ThreadOfResource<typeof gpuDevice>, ThreadedBy<D>>, body: Body<Rendered<D>>) => System;
+export {};

package/dist/interface/system/render.js

@@ -0,0 +1,32 @@
+import { takeIdOfDeclaration } from '../registry/ids.js';
+import { nameOf } from '../registry/items.js';
+import { claimSystem } from '../registry/program.js';
+import { gpuDevice } from '../resources/gpu-device.js';
+import { accessorsOf } from '../gpu/accessors.js';
+import { checkLeaf } from './check.js';
+/**
+ * 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`. Throws as `create` does, and for an accessor its shader can't read on the GPU.
+ */
+export const render = (declaration, body) => {
+    const id = takeIdOfDeclaration(declaration);
+    const name = nameOf(declaration.name, id, "system");
+    const system = {
+        kind: "render",
+        name,
+        declaration: {
+            ...declaration,
+            components: { ...declaration.components, read: [...new Set(Object.values(declaration.shader.accessors))] },
+            resources: { ...declaration.resources, is: [...new Set([...declaration.resources?.is ?? [], gpuDevice])] },
+        },
+        body,
+    };
+    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;
+};
+//# sourceMappingURL=render.js.map

package/dist/interface/system/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/interface/system/render.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAIrD,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAEvD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA4CvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAClB,WAA4F,EAC5F,IAAuB,EACjB,EAAE;IACR,MAAM,EAAE,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;IACpD,MAAM,MAAM,GAAkB;QAC1B,IAAI,EAAE,QAAQ;QACd,IAAI;QACJ,WAAW,EAAE;YACT,GAAG,WAAW;YACd,UAAU,EAAE,EAAE,GAAG,WAAW,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;YAC1G,SAAS,EAAE,EAAE,GAAG,WAAW,CAAC,SAAS,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,CAAY,CAAC,GAAG,WAAW,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE;SACxH;QACD,IAAI;KACP,CAAC;IACF,SAAS,CAAC,MAAM,CAAC,CAAC;IAClB,MAAM,SAAS,GAAG,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAClD,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,mBAAmB,SAAS,GAAG,CAAC,CAAC;IACnG,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC;AAClB,CAAC,CAAC"}

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

@@ -0,0 +1,11 @@
+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];

package/dist/interface/system/struct.js

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

package/dist/interface/system/struct.js.map

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

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

@@ -0,0 +1,10 @@
+declare const input: unique symbol;
+/**
+ * A system, the value a System constructor returned: identified by that value and labeled by its name. `run` takes it
+ * with a value of type `I`, or with nothing when `I` is `undefined`.
+ */
+export type System<I = undefined> = {
+    readonly name: string;
+    readonly [input]?: I;
+};
+export * as System from './index.js';

package/dist/interface/system/system.js

@@ -0,0 +1,2 @@
+export * as System from './index.js';
+//# sourceMappingURL=system.js.map

package/dist/interface/system/system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.js","sourceRoot":"","sources":["../../../src/interface/system/system.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,MAAM,MAAM,YAAY,CAAC"}

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

@@ -0,0 +1,46 @@
+import type { Component } from '../component/component.js';
+import type { ThreadOfComponent } from '../component/value.js';
+import type { Resource } from '../resource/resource.js';
+import type { ThreadOfResource } from '../resource/value.js';
+import type { Index } from '../indexes/index-type.js';
+import type { Listed, Property } from './property.js';
+import type { KeyOf } from './values.js';
+type Lookups<D> = Property<D, "lookup">;
+type LookupReads<D> = {
+    [L in keyof Lookups<D>]: Listed<Lookups<D>[L], "read">;
+}[keyof Lookups<D>];
+type LookupKeys<D> = {
+    [L in keyof Lookups<D>]: Lookups<D>[L] extends {
+        readonly index: Index<infer I>;
+    } ? KeyOf<I>[number] : never;
+}[keyof Lookups<D>];
+type OrderKeys<D> = Property<D, "order"> extends Index<infer I> ? KeyOf<I>[number] : never;
+type Components<D> = Property<D, "components">;
+type Resources<D> = Property<D, "resources">;
+/** The components that place a declaration: those it reads, writes or filters on by change, and the keys it looks up and orders by. */
+type Placing<D> = Listed<Components<D>, "read"> | Listed<Components<D>, "write"> | Listed<Components<D>, "added"> | Listed<Components<D>, "changed"> | LookupReads<D> | LookupKeys<D> | Listed<Property<D, "up">, "read"> | OrderKeys<D>;
+/** The resources that place a declaration: those it reads, writes, filters on by change, or reads as a condition. */
+type PlacingResources<D> = Listed<Resources<D>, "read"> | Listed<Resources<D>, "write"> | Listed<Resources<D>, "changed"> | Listed<Resources<D>, "is">;
+/** The threads of the object components and resources a declaration uses. */
+export type ThreadsOf<D> = ThreadOfComponent<Placing<D> & Component.Key> | ThreadOfResource<PlacingResources<D> & Resource.Key>;
+/** Each object component and resource a declaration uses, by key, with the thread it lives on. */
+export type ThreadedBy<D> = {
+    readonly [K in (Placing<D> & Component.Key) | (PlacingResources<D> & Resource.Key) as [Thread<K>] extends [never] ? never : K]: Thread<K>;
+};
+type Thread<K> = K extends Component.Key ? ThreadOfComponent<K> : K extends Resource.Key ? ThreadOfResource<K> : never;
+type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
+/**
+ * Requires a property no declaration has when `T` holds more than one thread, so the declaration fails to compile; its
+ * value names each key with its thread, `ThreadedBy` of the declaration.
+ */
+export type OneThread<T, Keys = T> = true extends IsUnion<T> ? {
+    readonly "error: its object components and resources live on different threads": {
+        readonly [K in keyof Keys]: Keys[K];
+    };
+} : {};
+/**
+ * Whether `T`, the thread a declaration's objects live on, is another than the world's, which a joined thread may fill;
+ * false for the threads of every declaration, which hold the world's.
+ */
+export type Elsewhere<T> = [T] extends [never] ? false : "world" extends T ? false : true;
+export {};

package/dist/interface/system/threads.js

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

package/dist/interface/system/threads.js.map

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

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

@@ -0,0 +1,73 @@
+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 `has`. */
+export type HeldBy<D> = KeyOf<D>[number] | Listed<Property<D, "components">, "has">;
+/** 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 lookup's `read` values, read-only. */
+type IndexRow<L> = {
+    readonly entity: Entity;
+} & {
+    readonly [K in Listed<L, "read"> & 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, L> = 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 {
+    readonly sorted: true;
+} ? (...key: Prefix<KeyValues<KeyOf<D>>>) => Rows<IndexRow<L>> : (...key: KeyValues<KeyOf<D>>) => Rows<IndexRow<L>>;
+/**
+ * The row a lookup by entity gives: the lookup's `read` values, read-only, and with `changed` declared, whether a
+ * component it names may have changed in the entity since its system last ran: conservative, as `changed` filters are,
+ * and true on a system's first run and in finalizers. With `changed`, valid until the lookup is called again.
+ */
+type EntityRow<L> = {
+    readonly [K in (Listed<L, "read"> & Component.Key) | (L extends {
+        readonly changed: readonly Component.Key[];
+    } ? "changed" : never)]: K extends Component.Key ? Component.Value<K> : boolean;
+};
+export type LookupFunction<L> = L extends {
+    readonly index: Index<infer D>;
+} ? IndexLookup<D, L> : (entity: Entity) => EntityRow<L> | null;
+export {};

package/dist/interface/system/values.js

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

package/dist/interface/system/values.js.map

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

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

@@ -0,0 +1,9 @@
+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"`.
+ */
+export type ThreadOf<Entry, T> = IsShared<T> extends true ? never : Entry extends {
+    readonly thread: infer H extends Thread;
+} ? H : "world";

package/dist/interface/thread/of.js

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

package/dist/interface/thread/of.js.map

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

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

@@ -0,0 +1,12 @@
+/**
+ * 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/dist/interface/thread/thread.js

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

package/dist/interface/thread/thread.js.map

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

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

@@ -0,0 +1 @@
+export { register } from './register.js';

package/dist/interface/trait/index.js

@@ -0,0 +1,2 @@
+export { register } from './register.js';
+//# sourceMappingURL=index.js.map

package/dist/interface/trait/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/interface/trait/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

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

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

package/dist/interface/trait/key.js

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

package/dist/interface/trait/key.js.map

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

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

@@ -0,0 +1,7 @@
+import type { BuiltIn, Key } from './key.js';
+/**
+ * Registers a trait under `key`, a plain `Symbol(...)`: string trait names are the core's built-in traits. The same
+ * trait again is accepted, and so is a new symbol with a trait's id, as a module evaluated again makes it. Throws for a key that isn't a plain symbol, or
+ * one registered as a component or resource.
+ */
+export declare const register: (key: Exclude<Key, BuiltIn> & symbol) => void;

package/dist/interface/trait/register.js

@@ -0,0 +1,8 @@
+import { addTrait } from '../registry/traits.js';
+/**
+ * Registers a trait under `key`, a plain `Symbol(...)`: string trait names are the core's built-in traits. The same
+ * trait again is accepted, and so is a new symbol with a trait's id, as a module evaluated again makes it. Throws for a key that isn't a plain symbol, or
+ * one registered as a component or resource.
+ */
+export const register = (key) => addTrait(key);
+//# sourceMappingURL=register.js.map

package/dist/interface/trait/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/interface/trait/register.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAmC,EAAQ,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC"}

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

@@ -0,0 +1,10 @@
+import type { IsNode } from '../platform/platform.js';
+/**
+ * The traits a declaration must have beyond those it lists: a DOM `Node` lives on `"main"`, so a declaration of one
+ * without `thread` can't be registered. Where the DOM library isn't loaded, nothing is required.
+ */
+export type Required<Entry, T> = IsNode<T> extends true ? (Entry extends {
+    readonly thread: unknown;
+} ? {} : {
+    readonly thread: "main";
+}) : {};

package/dist/interface/trait/required.js

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

package/dist/interface/trait/required.js.map

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

package/dist/interface/trait/symbol-keys.d.ts

@@ -0,0 +1,16 @@
+import type { Components } from '../component/types.js';
+import type { Resources } from '../resource/types.js';
+import type { BuiltIn } from './key.js';
+import type { Traits } from './types.js';
+/** A required property naming `problem` and the keys that cause it, or nothing without such keys. */
+type Problem<Keys, Text extends string> = [Keys] extends [never] ? {} : {
+    readonly [P in Text]: Keys;
+};
+/**
+ * What every declaration also requires while `C`, `R` or `T` has a key that isn't a symbol, besides the built-in
+ * traits: a property named for the problem, holding the keys, so registration fails to compile and says why.
+ */
+export type KeysMustBeSymbols<C, R, T> = Problem<Exclude<keyof C, symbol>, "component keys must be symbols"> & Problem<Exclude<keyof R, symbol>, "resource keys must be symbols"> & Problem<Exclude<keyof T, symbol | BuiltIn>, "trait keys must be symbols">;
+/** `KeysMustBeSymbols` of the program's components, resources and traits, computed once. */
+export type SymbolKeys = KeysMustBeSymbols<Components, Resources, Traits<never>>;
+export {};

package/dist/interface/trait/symbol-keys.js

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

package/dist/interface/trait/symbol-keys.js.map

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

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

@@ -0,0 +1,2 @@
+export type Trait = never;
+export * as Trait from './index.js';

package/dist/interface/trait/trait.js

@@ -0,0 +1,2 @@
+export * as Trait from './index.js';
+//# sourceMappingURL=trait.js.map