@adobe/ecs 0.0.0-stage → 0.1.0

package/dist/interface/archetype/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/interface/archetype/create.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAA2C,UAAa,EAAK,EAAE;IACjF,cAAc,CAAC,UAAU,CAAC,CAAC;IAC3B,OAAO,UAAU,CAAC;AACtB,CAAC,CAAC"}

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

@@ -0,0 +1 @@
+export * from './create.js';

package/dist/interface/archetype/index.js

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/interface/archetype/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/interface/archetype/values-of.d.ts

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

package/dist/interface/archetype/values-of.js

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

package/dist/interface/archetype/values-of.js.map

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

package/dist/interface/component/component.d.ts

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

package/dist/interface/component/component.js

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

package/dist/interface/component/component.js.map

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

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

@@ -0,0 +1,74 @@
+import type { IsData } from "../schema/is-data.js";
+import type { Schema } from "../schema/schema.js";
+import type { Key as TraitKey } from "../trait/key.js";
+import type { Required } from "../trait/required.js";
+import type { Traits } from "../trait/types.js";
+import type { SymbolKeys } from "../trait/symbol-keys.js";
+import type { Key } from "./key.js";
+import type { Components } from "./types.js";
+/** A value starts at `default`, which a type that allows `null` may leave out: it's `null` then. */
+export type Starting<T> = null extends T ? {
+    readonly default?: T;
+} : {
+    readonly default: T;
+};
+type Same<A, B> = (<X>() => X extends A ? 1 : 2) extends (<X>() => X extends B ? 1 : 2) ? true : false;
+/** How deep `Flattened` goes: deeper values are compared as they are, so recursive types stay finite. */
+type Depth = [never, 0, 1, 2, 3, 4, 5, 6, 7];
+/** `T` with every object, at any depth up to eight, as one object type, so `A & B` compares equal to the object it is. */
+type Flattened<T, D extends number = 8> = [
+    D
+] extends [never] ? T : T extends string | number | boolean | bigint | symbol | null | undefined | ((...parameters: never[]) => unknown) ? T : T extends ReadonlyMap<infer K, infer V> ? (T extends Map<K, V> ? T : ReadonlyMap<Flattened<K, Depth[D]>, Flattened<V, Depth[D]>>) : T extends ReadonlySet<infer E> ? (T extends Set<E> ? T : ReadonlySet<Flattened<E, Depth[D]>>) : {
+    [K in keyof T]: Flattened<T[K], Depth[D]>;
+};
+/** Whether `A` and `B` are the same type, flattened only when they aren't identical. */
+type Equivalent<A, B> = Same<A, B> extends true ? true : Same<Flattened<A>, Flattened<B>>;
+/**
+ * Nothing when schema `S` describes exactly the declared type `T` and its `default`, if any, is a `T`; else a required
+ * property naming the problem, so registration fails to compile and says why. A check rather than `type`'s own type,
+ * so `type` is inferred from the schema alone.
+ */
+export type Describing<S, T> = ((S extends Schema ? Equivalent<Schema.ToType<S>, T> : false) extends true ? {} : {
+    readonly "the schema describes another type than the declared one": T;
+}) & (S extends {
+    readonly default: infer V;
+} ? ([V] extends [T] ? {} : {
+    readonly "the schema's default isn't of the declared type": T;
+}) : {});
+/** A derived component starts at its schema's `default`, at its `const`, or at `null` when its type allows it. */
+type DerivedStart<S, T> = S extends {
+    readonly const: unknown;
+} | {
+    readonly default: unknown;
+} ? {} : null extends T ? {} : {
+    readonly "a derived component's schema has a default, which it starts at": T;
+};
+/**
+ * The value type's part of a declaration: `type`, schema `S`, describing exactly the declared type `T` when it's data.
+ * A type that isn't data has no `type`, and a derived one starts at the declaration's `default`.
+ */
+type TypePart<S, T, Derived> = IsData<T> extends true ? [S] extends [never] ? {
+    readonly type: Schema;
+} : Describing<S, T> & {
+    readonly default?: never;
+} & (Derived extends true ? DerivedStart<S, T> : {}) : {
+    readonly type?: never;
+} & (Derived extends true ? Starting<T> : {
+    readonly default?: never;
+});
+/**
+ * What `register(K, ...)` takes: exactly the traits `Components[K]` declares, `type` as schema `S` for the declared
+ * type. A trait whose declared value its definition doesn't allow on `K`, or one a value of its type must declare and
+ * doesn't, becomes `never`, so registration fails to compile, as every registration does while a component, resource
+ * or trait is keyed by a string (`SymbolKeys`).
+ */
+export type Declaration<K extends Key, S> = {
+    readonly type?: S;
+} & TypePart<S, Components[K]["type"], Components[K] extends {
+    readonly derived: true;
+} ? true : false> & {
+    readonly [T in Exclude<keyof Components[K], "type">]: T extends TraitKey ? (Components[K][T] extends Traits<K>[T] ? Components[K][T] : never) : never;
+} & {
+    readonly [T in Exclude<TraitKey, keyof Components[K]>]?: never;
+} & Required<Components[K], Components[K]["type"]> & SymbolKeys;
+export {};

package/dist/interface/component/declaration.js

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

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

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

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

@@ -0,0 +1,3 @@
+export * from './register.js';
+export type { Key } from './key.js';
+export type { Value, With } from './value.js';

package/dist/interface/component/index.js

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

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

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

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

@@ -0,0 +1,2 @@
+import type { Components } from './types.js';
+export type Key = keyof Components;

package/dist/interface/component/key.js

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

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

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

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

@@ -0,0 +1,23 @@
+import type { Resource } from "../resource/resource.js";
+import type { Schema } from "../schema/schema.js";
+import type { Key as TraitKey } from "../trait/key.js";
+import type { Declaration } from "./declaration.js";
+import type { Key } from "./key.js";
+/**
+ * Registers the component `key`, a plain `Symbol(...)` whose traits `Components` declares, with exactly those traits:
+ * `type` as a schema that describes the declared type, left out only for a type that isn't data, which is stored as
+ * it is.
+ * ```ts
+ * declare module "@adobe/ecs" { interface Components { [position]: { type: Vec3 } } }
+ * Component.register(position, { type: Vec3.schema });
+ * ```
+ * The declaration is fixed from then on. The same declaration again is accepted, and so is a new symbol with the id
+ * of a component, as a module evaluated again makes it, which is then that key. A key also declared as a resource or
+ * a trait can't be registered: names are unique across the three. Throws for a key that isn't a plain symbol (a
+ * `Symbol.for` or well-known symbol isn't), one registered, or whose id is registered, as another kind or with another
+ * declaration, a trait that isn't registered, a trait's value that can't hold for the declaration, or a schema asking
+ * for a GPU layout it can't meet.
+ */
+export declare function register<K extends Exclude<Key, Resource.Key | TraitKey> & symbol, const S extends Schema & {
+    readonly default?: unknown;
+} = never>(key: K, declaration: Declaration<K, S>): void;

package/dist/interface/component/register.js

@@ -0,0 +1,6 @@
+import { createRegistry } from "../registry/declarations.js";
+const registry = createRegistry("component");
+export function register(key, declaration) {
+    registry(key, declaration);
+}
+//# sourceMappingURL=register.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/interface/component/register.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAuB,MAAM,6BAA6B,CAAC;AAOlF,MAAM,QAAQ,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;AAkB7C,MAAM,UAAU,QAAQ,CAAC,GAAY,EAAE,WAA2B;IAC9D,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;AAC/B,CAAC"}

package/dist/interface/component/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Each component's traits, `type` included, by augmentation: `[position]: { type: Vec3 }`,
+ * `[slot]: { type: Slot; derived: true }`. Registration must give exactly these.
+ */
+export interface Components {
+}

package/dist/interface/component/types.js

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

package/dist/interface/component/types.js.map

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

package/dist/interface/component/value.d.ts

@@ -0,0 +1,34 @@
+import type { ThreadOf } from '../thread/of.js';
+import type { Key as TraitKey } from "../trait/key.js";
+import type { Key } from "./key.js";
+import type { Components } from "./types.js";
+/** Every component's value type, computed once so `Value` is a lookup. */
+type ValueTypes = {
+    readonly [K in Key]: Components[K] extends {
+        readonly type: infer T;
+    } ? T : never;
+};
+/** The value type of component `K`. */
+export type Value<K extends Key> = ValueTypes[K];
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+/** Component `K`'s value as reads return it: read-only, with branded primitives such as `Entity` as they are. */
+export type ReadonlyValue<K extends Key> = Value<K> extends Primitive ? Value<K> : Readonly<Value<K>>;
+/** Components that declare trait `T`, with a value assignable to `V`. */
+export type With<T extends TraitKey, V = unknown> = {
+    [K in Key]: Components[K] extends {
+        readonly [P in T]: V;
+    } ? K : never;
+}[Key];
+/** Components only rules add and remove. */
+export type Derived = With<"derived">;
+/** Components user code adds and removes: the only ones commands take. */
+export type Essential = Exclude<Key, Derived>;
+/** Components systems may write: every one but references, which change only through commands. */
+export type Writable = Exclude<Key, With<"reference">>;
+/** Every component's thread, computed once so `ThreadOf` is a lookup. */
+type Threads = {
+    readonly [K in Key]: ThreadOf<Components[K], Value<K>>;
+};
+/** The thread component `K` lives on, or `never` for a struct, which lives in shared memory. */
+export type ThreadOfComponent<K extends Key> = Threads[K];
+export {};

package/dist/interface/component/value.js

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

package/dist/interface/component/value.js.map

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

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

@@ -0,0 +1,6 @@
+import type { Key } from "./key.js";
+import type { Value } from './value.js';
+/** Values for any subset of components, keyed by component. */
+export type Values = {
+    readonly [K in Key]?: Value<K>;
+};

package/dist/interface/component/values.js

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

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

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

package/dist/interface/entity/entity.d.ts

@@ -0,0 +1,9 @@
+declare const entityBrand: unique symbol;
+/**
+ * An entity id, live or not: a branded number; 0 is none. The brand makes entity-valued components and fields visible
+ * to types and schemas, and costs nothing at runtime.
+ */
+export type Entity = number & {
+    readonly [entityBrand]: true;
+};
+export * as Entity from './index.js';

package/dist/interface/entity/entity.js

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

package/dist/interface/entity/entity.js.map

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

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

@@ -0,0 +1,8 @@
+import type { Entity } from './entity.js';
+/** The schema of every entity-typed value. */
+export declare const schema: {
+    readonly type: "integer";
+    readonly format: "entity";
+};
+/** No entity: index 0 is never one, so zeroed memory and an entity-valued default mean none, and a lookup of it returns null. */
+export declare const none: Entity;

package/dist/interface/entity/index.js

@@ -0,0 +1,5 @@
+/** The schema of every entity-typed value. */
+export const schema = { type: "integer", format: "entity" };
+/** No entity: index 0 is never one, so zeroed memory and an entity-valued default mean none, and a lookup of it returns null. */
+export const none = 0;
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/interface/entity/index.ts"],"names":[],"mappings":"AAGA,8CAA8C;AAC9C,MAAM,CAAC,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAA4B,CAAC;AAEtF,iIAAiI;AACjI,MAAM,CAAC,MAAM,IAAI,GAAG,CAAW,CAAC"}

package/dist/interface/finalizer/body.d.ts

@@ -0,0 +1,50 @@
+import type { Component } from '../component/component.js';
+import type { Entity } from '../entity/entity.js';
+import type { Resource } from '../resource/resource.js';
+import type { Commands } from '../system/commands.js';
+import type { Listed, Property } from '../system/property.js';
+import type { LookupFunction, ResourceValues, Values } from '../system/values.js';
+import type { ChangesDeclaration, Declaration } from './declaration.js';
+import type { Essential, ReadonlyValue } from '../component/value.js';
+import type { Elsewhere, ThreadsOf } from '../system/threads.js';
+/** The entity that stopped matching, with its `read` values as they are before the sync point applies. */
+export type Row<D extends Declaration> = {
+    readonly entity: Entity;
+} & {
+    readonly [K in Listed<Property<D, "components">, "read"> & Component.Key]: Component.Value<K>;
+};
+type Resources<D> = Listed<Property<D, "resources">, "read"> | Listed<Property<D, "resources">, "write">;
+/**
+ * Resources and lookups, each present only when declared, and the commands it issues for the next sync point: none on
+ * another thread than the world's, which runs after the sync point.
+ */
+export type Context<D extends Declaration | ChangesDeclaration> = ([Resources<D>] extends [never] ? {} : {
+    readonly resources: Values<Listed<Property<D, "resources">, "read">, Listed<Property<D, "resources">, "write">, Resource.Key, ResourceValues>;
+}) & ([keyof Property<D, "lookup">] extends [never] ? {} : {
+    readonly lookup: {
+        readonly [K in keyof Property<D, "lookup">]: LookupFunction<Property<D, "lookup">[K]>;
+    };
+}) & (true extends Elsewhere<ThreadsOf<D>> ? {} : {
+    readonly commands: Commands;
+});
+/** The components a changes finalizer sees. */
+export type Watched<D extends ChangesDeclaration> = Property<D, "watch"> extends readonly Essential[] ? Listed<D, "watch"> & Essential : Essential;
+/** Entities whose components changed the same way: `from` and `to` are null for those spawned and despawned. */
+export type Group<C extends Component.Key> = {
+    readonly from: readonly C[] | null;
+    readonly to: readonly C[] | null;
+    readonly added: readonly C[];
+    readonly removed: readonly C[];
+    /** Given a value by an add while the entity has it before and after, removed and added again meanwhile or not. */
+    readonly replaced: readonly C[];
+    readonly entities: readonly Entity[];
+};
+/** A sync point's structural changes to the watched components, and the values adds replace, before they apply. */
+export type ChangeSet<C extends Component.Key> = {
+    readonly groups: readonly Group<C>[];
+    /** The value before the sync point, or null if the entity didn't have it. */
+    previous<K extends C>(entity: Entity, component: K): ReadonlyValue<K> | null;
+    /** The value after it, or null if the entity won't have it. */
+    next<K extends C>(entity: Entity, component: K): ReadonlyValue<K> | null;
+};
+export {};

package/dist/interface/finalizer/body.js

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

package/dist/interface/finalizer/body.js.map

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

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

@@ -0,0 +1,43 @@
+import type { Resource } from '../resource/resource.js';
+import type { Listed, Property } from '../system/property.js';
+import type { ThreadOfComponent } from '../component/value.js';
+import type { Component } from '../component/component.js';
+import type { Elsewhere, OneThread, ThreadedBy, ThreadsOf } from '../system/threads.js';
+import type { ChangeSet, Context, Row, Watched } from './body.js';
+import type { ChangesDeclaration, Declaration } from './declaration.js';
+import type { Finalizer } from './finalizer.js';
+/** A resource in `write` is readable too, so it isn't also in `read`. */
+type Validate<D extends Declaration | ChangesDeclaration> = {
+    readonly resources?: {
+        readonly read?: readonly Exclude<Resource.Key, Listed<Property<D, "resources">, "write">>[];
+    };
+};
+/**
+ * A finalizer on another thread than the world's runs there after the sync point, which doesn't wait for it: it writes
+ * no resources and looks up nothing.
+ */
+type Remote<D> = true extends Elsewhere<ThreadsOf<D>> ? ([Listed<Property<D, "resources">, "write">] extends [never] ? {} : {
+    readonly "error: a finalizer on another thread than the world's writes no resources": true;
+}) & ([keyof Property<D, "lookup">] extends [never] ? {} : {
+    readonly "error: a finalizer on another thread than the world's looks up nothing": true;
+}) : {};
+/** A changes finalizer runs on the world's thread, in the sync point: it watches and reads no other thread's objects. */
+type OnWorld<D> = true extends Elsewhere<ThreadsOf<D> | ThreadOfComponent<Listed<D, "watch"> & Component.Key>> ? {
+    readonly "error: a changes finalizer watches and reads only the world's thread's objects": true;
+} : {};
+/**
+ * Declares a finalizer for each entity that stops matching its components, which applies in every world, and returns
+ * it. It runs on the thread its object components and resources live on: on another than the world's, after the sync
+ * point, issuing no commands. Throws if it names a component or resource that isn't registered as one, lists a
+ * resource in both `read` and `write`, writes a reduced one, uses object values of different threads, writes resources
+ * or looks up entities on another thread than the world's, or is ordered with a finalizer on another thread, in a cycle
+ * or with a resource conflict.
+ */
+export declare const create: <const D extends Declaration>(declaration: D & Validate<D> & OneThread<ThreadsOf<D>, ThreadedBy<D>> & Remote<D>, body: (row: Row<D>, context: Context<D>) => void) => Finalizer;
+/**
+ * Declares a finalizer of each sync point's structural changes, which applies in every world, and returns it. It runs
+ * on the world's thread. Throws as `create` does, for a watched component that isn't registered or is derived, and for
+ * one watching or reading another thread's values.
+ */
+export declare const changes: <const D extends ChangesDeclaration>(declaration: D & Validate<D> & OnWorld<D>, body: (changes: ChangeSet<Watched<D>>, context: Context<D>) => void) => Finalizer;
+export {};

package/dist/interface/finalizer/create.js

@@ -0,0 +1,97 @@
+import { declarationOf, kindOf, labelOf } from '../registry/names.js';
+import { takeIdOfDeclaration } from '../registry/ids.js';
+import { firstItemOf, labelOfItem, nameOf } from '../registry/items.js';
+import { addFinalizer, programFinalizers } from '../registry/program.js';
+import { requireRegistered, threadOf } from '../registry/threads.js';
+import { checkWorldWritten } from '../registry/written.js';
+import { checkLookup } from '../registry/indexes.js';
+/** Throws if a resource is in both `read` and `write`, or a reduced one is written. */
+const checkResources = (name, resources) => {
+    const writes = new Set(resources?.write);
+    const both = (resources?.read ?? []).find(key => writes.has(key));
+    if (both !== undefined)
+        throw new Error(`Finalizer "${name}" lists "${labelOf(both)}" in both resources read and write; write already makes it readable.`);
+    checkWorldWritten(`Finalizer "${name}"`, resources?.write);
+    for (const key of writes) {
+        if (declarationOf(key)?.reduce !== undefined)
+            throw new Error(`Finalizer "${name}" writes "${labelOf(key)}", which is reduced; only its contributors' fold sets it.`);
+    }
+};
+/** The thread a registered finalizer runs on: a changes finalizer, and one using no objects, on the world's. */
+const runsOn = (finalizer) => finalizer.kind === "finalizer" ? threadOf(finalizer.declaration, "Finalizer", finalizer.name) ?? "world" : "world";
+/** Throws for a finalizer ordered with one on another thread: they run at different times. */
+const checkOrder = (name, thread, declaration) => {
+    for (const other of [...declaration.before ?? [], ...declaration.after ?? []]) {
+        const first = firstItemOf(other);
+        const found = programFinalizers().find(finalizer => firstItemOf(finalizer) === first);
+        if (found === undefined)
+            continue;
+        const theirs = runsOn(found);
+        if (theirs !== thread) {
+            throw new Error(`Finalizer "${name}" runs on thread "${thread}" and is ordered with "${labelOfItem(found)}", which runs on thread "${theirs}"; finalizers on different threads run at different times, so neither is ordered before the other.`);
+        }
+    }
+};
+/**
+ * Declares a finalizer for each entity that stops matching its components, which applies in every world, and returns
+ * it. It runs on the thread its object components and resources live on: on another than the world's, after the sync
+ * point, issuing no commands. Throws if it names a component or resource that isn't registered as one, lists a
+ * resource in both `read` and `write`, writes a reduced one, uses object values of different threads, writes resources
+ * or looks up entities on another thread than the world's, or is ordered with a finalizer on another thread, in a cycle
+ * or with a resource conflict.
+ */
+export const create = (declaration, body) => {
+    const id = takeIdOfDeclaration(declaration);
+    const name = nameOf(declaration.name, id, "finalizer");
+    const finalizer = { kind: "finalizer", name, declaration, body };
+    checkResources(name, declaration.resources);
+    const thread = threadOf(declaration, "Finalizer", name);
+    if (thread !== null && thread !== "world") {
+        const elsewhere = `one on another thread than the world's runs after the sync point, so it`;
+        if ((declaration.resources?.write?.length ?? 0) > 0)
+            throw new Error(`Finalizer "${name}" runs on thread "${thread}" and writes resources; ${elsewhere} writes none.`);
+        if (Object.keys(declaration.lookup ?? {}).length > 0)
+            throw new Error(`Finalizer "${name}" runs on thread "${thread}" and looks up other entities; ${elsewhere} looks up none.`);
+    }
+    checkOrder(name, thread ?? "world", declaration);
+    requireRegistered("Finalizer", name, "component", declaration.components.has);
+    requireRegistered("Finalizer", name, "component", declaration.components.not);
+    for (const lookupName in declaration.lookup) {
+        checkLookup("Finalizer", name, lookupName, declaration.lookup[lookupName]);
+        const lookup = declaration.lookup[lookupName];
+        requireRegistered("Finalizer", name, "component", "has" in lookup ? lookup.has : undefined);
+        requireRegistered("Finalizer", name, "component", "not" in lookup ? lookup.not : undefined);
+    }
+    return addFinalizer(finalizer, id);
+};
+/**
+ * Declares a finalizer of each sync point's structural changes, which applies in every world, and returns it. It runs
+ * on the world's thread. Throws as `create` does, for a watched component that isn't registered or is derived, and for
+ * one watching or reading another thread's values.
+ */
+export const changes = (declaration, body) => {
+    const id = takeIdOfDeclaration(declaration);
+    const name = nameOf(declaration.name, id, "finalizer");
+    const finalizer = { kind: "changes", name, declaration, body };
+    checkResources(name, declaration.resources);
+    requireRegistered("Finalizer", name, "resource", declaration.resources?.read);
+    requireRegistered("Finalizer", name, "resource", declaration.resources?.write);
+    for (const lookupName in declaration.lookup) {
+        const lookup = declaration.lookup[lookupName];
+        checkLookup("Finalizer", name, lookupName, lookup);
+        for (const keys of [lookup.read, "has" in lookup ? lookup.has : undefined, "not" in lookup ? lookup.not : undefined])
+            requireRegistered("Finalizer", name, "component", keys);
+    }
+    for (const key of declaration.watch ?? []) {
+        if (kindOf(key) !== "component")
+            throw new Error(`Finalizer "${name}" watches "${labelOf(key)}", which isn't a registered component.`);
+        if (declarationOf(key)?.derived === true)
+            throw new Error(`Finalizer "${name}" watches "${labelOf(key)}", which is derived; it sees only components user code adds and removes.`);
+    }
+    const thread = threadOf({ components: { read: declaration.watch }, resources: declaration.resources, lookup: declaration.lookup }, "Finalizer", name);
+    if (thread !== null && thread !== "world")
+        throw new Error(`Finalizer "${name}" watches or reads values on thread "${thread}"; a changes finalizer runs on the world's thread, in the sync point.`);
+    checkOrder(name, "world", declaration);
+    return addFinalizer(finalizer, id);
+};
+//# sourceMappingURL=create.js.map

package/dist/interface/finalizer/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../../src/interface/finalizer/create.ts"],"names":[],"mappings":"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"}

package/dist/interface/finalizer/created.d.ts

@@ -0,0 +1,16 @@
+import type { ChangesDeclaration, Declaration } from './declaration.js';
+/** Runs, inside a sync point, for each entity that stops matching its components. */
+export type Leaf<D extends Declaration = Declaration> = {
+    readonly kind: "finalizer";
+    readonly name: string;
+    readonly declaration: D;
+    body: (...parameters: never[]) => void;
+};
+/** Runs, inside a sync point, with all its structural changes to the components it watches. */
+export type Changes<D extends ChangesDeclaration = ChangesDeclaration> = {
+    readonly kind: "changes";
+    readonly name: string;
+    readonly declaration: D;
+    body: (...parameters: never[]) => void;
+};
+export type Finalizer = Leaf | Changes;

package/dist/interface/finalizer/created.js

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

package/dist/interface/finalizer/created.js.map

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

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

@@ -0,0 +1,38 @@
+import type { Component } from '../component/component.js';
+import type { Resource } from '../resource/resource.js';
+import type { Lookup } from '../system/access.js';
+import type { Finalizer } from './finalizer.js';
+import type { Name } from './name.js';
+import type { Essential } from '../component/value.js';
+import type { Reduced } from '../resource/reduction.js';
+import type { WorldWritten } from '../resource/written.js';
+type Shared = {
+    readonly name?: Name;
+    /** Read-only access to other entities, as they are before the sync point applies. */
+    readonly lookup?: {
+        readonly [name: string]: Lookup;
+    };
+    /** Writes take the sync point's tick, so each system sees them once. A resource in `write` is also readable. */
+    readonly resources?: {
+        readonly read?: readonly Resource.Key[];
+        readonly write?: readonly Exclude<Resource.Key, Reduced | WorldWritten>[];
+    };
+    readonly before?: readonly Finalizer[];
+    readonly after?: readonly Finalizer[];
+};
+/** A finalizer that runs for each entity that stops matching its components. */
+export type Declaration = Shared & {
+    readonly components: {
+        readonly read?: readonly Component.Key[];
+        readonly has?: readonly Component.Key[];
+        readonly not?: readonly Component.Key[];
+    };
+};
+/**
+ * A finalizer that sees each sync point's structural changes to the components it watches: by default, every one that
+ * isn't derived or an object a joined thread fills.
+ */
+export type ChangesDeclaration = Shared & {
+    readonly watch?: readonly Essential[];
+};
+export {};

package/dist/interface/finalizer/declaration.js

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

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

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

package/dist/interface/finalizer/finalizer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A finalizer, the value `Finalizer.create` or `Finalizer.changes` returned: identified by that value, labeled by its
+ * name, and listed in other finalizers' `before` and `after`.
+ */
+export type Finalizer = {
+    readonly name: string;
+};
+export * as Finalizer from './index.js';

package/dist/interface/finalizer/finalizer.js

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

package/dist/interface/finalizer/finalizer.js.map

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