@adobe/ecs 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,31 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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 channel: MessageChannel;
+declare const worker: Worker;
+
+// Sharing lets another thread join through a port: a MessagePort, a Worker or a worker's own scope. It resolves once
+// that thread has joined, to nothing.
+const shared: Promise<void> = world.share(channel.port1);
+check<Equal<ReturnType<World["share"]>, Promise<void>>>();
+world.share(worker);
+world.share(self);
+// A port is share's parameter, inferred where a consumer names it.
+const port: Parameters<World["share"]>[0] = channel.port2;
+// @ts-expect-error a port posts messages to another thread
+world.share({});
+// @ts-expect-error a thread is shared through one port
+world.share();
+
+// The package root's World.join joins; World names no type for it, its options or its port.
+// @ts-expect-error no World.Join
+export type Joining = World.Join;
+// @ts-expect-error no World.JoinOptions
+export type Options = World.JoinOptions;
+// @ts-expect-error no World.Port
+export type Ported = World.Port;
+void [shared, port];

package/src/interface/world/world.ts

@@ -0,0 +1,73 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Input } from '../system/input.js';
+import type { System } from '../system/system.js';
+
+/**
+ * A world. Systems read and change it; observer systems read it after each run's and tick's sync point. Every member's
+ * type is named from the package root, so declarations a consumer emits for its results name no internal module.
+ */
+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, 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, 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. 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;
+    /**
+     * Takes a value passed to `add`. Once it returns, that system's body is never called again, and its memory is
+     * released. A system added both alone and within an added composite stays until both are removed; constraints
+     * naming a removed system are ignored. Removing a value that isn't added does nothing. Throws, removing nothing,
+     * when the systems left would conflict with no ordering path between them, as `add` does. On a joined thread it
+     * takes only observer systems.
+     */
+    remove(system: System<void>): void;
+    /**
+     * 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. 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 } & (
+        | { readonly addEventListener: (type: "message", listener: (event: unknown) => void) => void }
+        | { readonly on: (event: "message", listener: (value: unknown) => void) => unknown }
+    )): 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.
+     */
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+};
+
+export type * as World from './index.js';

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

@@ -0,0 +1,77 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Component } from '../component/component.js';
+import type { Entity } from '../entity/entity.js';
+import { System } from '../system/system.js';
+import { main, move, position, time, total, watchTime } from '../system/system.type-test.js';
+import type { Create } from './create.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 entity: Entity;
+declare const create: Create;
+
+const point = Symbol("worldTypeTest/point");
+const persistent = Symbol("worldTypeTest/persistent");
+const shared = Symbol("worldTypeTest/shared");
+declare module '@adobe/ecs' {
+    export interface Components {
+        [point]: { type: { readonly x: number } };
+        [persistent]: { type: true };
+        [shared]: { type: true };
+    }
+}
+// Reading goes through observer systems: a world has no observers, and no synchronous reads.
+// @ts-expect-error no observe: observer systems read a world
+void world.observe;
+// @ts-expect-error no synchronous reads
+void world.query;
+// @ts-expect-error no synchronous reads
+void world.read;
+// @ts-expect-error GPU writes are read back for observer systems, without synchronize
+void world.synchronize;
+// @ts-expect-error no World.Query: observer systems declare what they read
+export type NoQuery = World.Query<[typeof persistent]>;
+
+// A run resolves to its per-run body's value, here nothing (see `run.type-test.ts`), and rejects when a system failed.
+const ran: Promise<void> = world.run(main);
+const moved: Promise<void> = world.run(move, { distance: 1 });
+// @ts-expect-error a system with input needs it
+world.run(move);
+// @ts-expect-error input must match its schema
+world.run(move, { distance: "far" });
+// @ts-expect-error a system without input takes none
+world.run(main, {});
+
+const created: World = create();
+const withResources: World = create({ [time]: 1, [total]: 0 });
+// @ts-expect-error a resource's initial value has its type
+create({ [time]: "now" });
+// @ts-expect-error resources takes only resource keys
+create({ [position]: 0 });
+// @ts-expect-error a key is its symbol, never its description
+create({ "systemTest/time": 1 });
+// @ts-expect-error systems register on their first run
+void world.systems;
+const disposed: Promise<void> = world.dispose();
+const usingDispose = async () => {
+    await using scoped = create();
+    await scoped.run(main);
+};
+void [disposed, usingDispose, ran, moved, created, withResources];
+
+// How a world is created is the implementation's: World names no Create or InitialResources.
+check<Equal<ReturnType<Create>, World>>();
+// @ts-expect-error no World.Create
+export type Created = World.Create;
+// @ts-expect-error no World.InitialResources: Parameters<typeof createWorld>[0]
+export type Initial = World.InitialResources;
+// @ts-expect-error no World.Failure: a failed run rejects with an Error
+export type Failed = World.Failure;
+
+// An observer system is added to every run and tick, or run once after an empty sync point.
+const addedObserver: void = world.add(watchTime);
+const ranObserver: Promise<void> = world.run(watchTime);
+void [addedObserver, ranObserver];

package/src/observe/compare.ts

@@ -0,0 +1,87 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// Comparing and testing component values for queries: equality, order, and `where` conditions compiled once.
+
+/** Whether two values are equal: primitives by identity, objects and arrays by their own keys, recursively. */
+export const equals = (a: unknown, b: unknown): boolean => {
+    if (a === b) return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+    const keys = Reflect.ownKeys(a);
+    if (keys.length !== Reflect.ownKeys(b).length) return false;
+    for (let i = 0; i < keys.length; i++) if (!equals(Reflect.get(a, keys[i]), Reflect.get(b, keys[i]))) return false;
+    return true;
+};
+
+/** Code points of two strings compared, never by locale, as sorted indexes order them. */
+const compareStrings = (a: string, b: string): number => {
+    const length = Math.min(a.length, b.length);
+    for (let k = 0; k < length; k++) {
+        const x = a.charCodeAt(k);
+        const y = b.charCodeAt(k);
+        if (x === y) continue;
+        // A surrogate encodes a code point above every unit that isn't one.
+        const xs = x >= 0xD800 && x <= 0xDFFF;
+        const ys = y >= 0xD800 && y <= 0xDFFF;
+        if (xs !== ys) return xs ? 1 : -1;
+        return x < y ? -1 : 1;
+    }
+    return a.length - b.length;
+};
+
+/**
+ * Orders values as sorted indexes do: numbers numerically with NaN after every number, booleans false first, strings
+ * by code point, tuples element by element; anything else is equal.
+ */
+export const compare = (a: unknown, b: unknown): number => {
+    if (typeof a === "number" && typeof b === "number") return compareNumbers(a, b);
+    if (Array.isArray(a) && Array.isArray(b)) {
+        const length = Math.min(a.length, b.length);
+        for (let i = 0; i < length; i++) {
+            const order = compare(a[i], b[i]);
+            if (order !== 0) return order;
+        }
+        return a.length - b.length;
+    }
+    if (typeof a === "boolean" && typeof b === "boolean") return a === b ? 0 : a ? 1 : -1;
+    if (typeof a === "string" && typeof b === "string") return compareStrings(a, b);
+    return 0;
+};
+
+/** Numbers in order, NaN after every other, -0 equal to 0. */
+export const compareNumbers = (a: number, b: number): number => {
+    if (a < b) return -1;
+    if (a > b) return 1;
+    if (a === b) return 0;
+    const nanA = a !== a;
+    return nanA === (b !== b) ? 0 : nanA ? 1 : -1;
+};
+
+const operators = new Set(["==", "!=", "<", ">", "<=", ">="]);
+
+/** A `where` condition compiled once: a plain value is equality, an object of comparison operators is a comparison. */
+export const predicateOf = (condition: unknown): ((value: unknown) => boolean) => {
+    if (typeof condition !== "object" || condition === null || Array.isArray(condition)) {
+        if (typeof condition === "number" || typeof condition === "string" || typeof condition === "boolean") return value => value === condition;
+        return value => equals(value, condition);
+    }
+    const entries = Object.entries(condition);
+    if (entries.length === 0 || !entries.every(([operator]) => operators.has(operator))) return value => equals(value, condition);
+    const tests = entries.map(([operator, operand]): ((value: unknown) => boolean) => {
+        switch (operator) {
+            case "==": return value => equals(value, operand);
+            case "!=": return value => !equals(value, operand);
+            case "<": return typeof operand === "number" ? value => typeof value === "number" ? value < operand : compare(value, operand) < 0 : value => compare(value, operand) < 0;
+            case ">": return typeof operand === "number" ? value => typeof value === "number" ? value > operand : compare(value, operand) > 0 : value => compare(value, operand) > 0;
+            case "<=": return typeof operand === "number" ? value => typeof value === "number" ? value <= operand : compare(value, operand) <= 0 : value => compare(value, operand) <= 0;
+            default: return typeof operand === "number" ? value => typeof value === "number" ? value >= operand : compare(value, operand) >= 0 : value => compare(value, operand) >= 0;
+        }
+    });
+    if (tests.length === 1) return tests[0];
+    if (tests.length === 2) {
+        const [first, second] = tests;
+        return value => first(value) && second(value);
+    }
+    return value => {
+        for (let i = 0; i < tests.length; i++) if (!tests[i](value)) return false;
+        return true;
+    };
+};

package/src/observe/entity.ts

@@ -0,0 +1,232 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Index, System, type Component, type Entity, type World } from '../interface/index.js';
+import type { Observe } from './observe.js';
+import { createEntry, give, giveFirst, keysId, labelOf, labelled, none, noDelivery, passed, scheduleDelivery, scheduleRead, stateOf, subscribe, sweepSubscribers, throwFailed, type Entry, type Read, type Shape, type WorldState } from './world-state.js';
+
+/** An observed entity's value, shared by its observers, and by optional component whether it had it last. */
+type EntityEntry = Entry<object | null> & { readonly entity: Entity; readonly present: boolean[] };
+
+/**
+ * The entities observed with one list of required and optional components, read by one observer system that looks each
+ * up by entity; with no optional components, it skips them while an index of what has the required ones reports no
+ * change. `swept` is false while an entry may have no subscribers.
+ */
+type EntityShape = Shape & {
+    readonly system: System;
+    /** On a joined thread, a run of its system, once resolved giving first values its pass read. */
+    readonly read: Read;
+    /** Whether its system is added: it's removed once the shape has been idle for a pass, and added again on use. */
+    attached: boolean;
+    readonly entries: EntityEntry[];
+    readonly byEntity: Map<Entity, EntityEntry>;
+    waiting: boolean;
+    swept: boolean;
+};
+
+/** By world, its entity observers' shapes, kept for its life, so their systems register in it once. */
+const shapes = new WeakMap<WorldState, Map<string, EntityShape>>();
+
+/** Indexes of the entities with every component of a list, by its id: one per list in the program. */
+const memberIndexes = new Map<string, Index<{ readonly key: readonly []; readonly components: { readonly with: readonly Component.Key[] } }>>();
+
+const membersOf = (required: readonly Component.Key[]) => {
+    const id = keysId(required);
+    let index = memberIndexes.get(id);
+    if (index === undefined) memberIndexes.set(id, index = Index.create(labelled({ key: [], components: { with: [...required] } }, `Observe.entity(${labelOf(required)})`)));
+    return index;
+};
+
+/** A by-entity lookup's row: whether a component it watches changed since its system last ran. */
+type PresenceRow = { readonly changed: boolean };
+
+/** A by-entity lookup's row of the components it reads, and whether one changed since its system last ran. */
+type LookupRow = { readonly changed: boolean } & { readonly [K in Component.Key]: unknown };
+
+/** What a pass finds an entity by: whether it has the required components and they changed, their values, and an optional one's. */
+type Finders = {
+    readonly presence: (entity: Entity) => PresenceRow | null;
+    readonly values: (entity: Entity) => { readonly [K in Component.Key]?: unknown } | null;
+    readonly optional: (index: number, entity: Entity) => LookupRow | null;
+};
+
+const createShape = (state: WorldState, byShape: Map<string, EntityShape>, id: string, required: readonly Component.Key[], optional: readonly Component.Key[]): EntityShape => {
+    const name = `Observe.entity(${labelOf(required)}${optional.length === 0 ? "" : `; ${labelOf(optional)}`})`;
+    const rows: (LookupRow | null)[] = optional.map(() => null);
+    /**
+     * Reads an entry's entity, giving its value if it changed and first values to subscribers waiting up to `through`:
+     * its required values only once they changed, a new object each time.
+     */
+    const evaluate = (entry: EntityEntry, finders: Finders, through: number, failed: unknown): unknown => {
+        const found = finders.presence(entry.entity);
+        let changed: boolean;
+        if (found === null) changed = !entry.valid || entry.value !== null;
+        else {
+            changed = !entry.valid || entry.value === null || found.changed;
+            for (let i = 0; i < optional.length; i++) {
+                const row = rows[i] = finders.optional(i, entry.entity);
+                const present = row !== null;
+                if (present !== entry.present[i] || (present && row.changed)) changed = true;
+            }
+        }
+        if (changed) {
+            if (found === null) entry.value = null;
+            else if (optional.length === 0) entry.value = finders.values(entry.entity);
+            else {
+                const value: { [key: symbol]: unknown } = {};
+                const values = required.length === 0 ? null : finders.values(entry.entity);
+                for (let i = 0; i < required.length; i++) value[required[i]] = values?.[required[i]];
+                for (let i = 0; i < optional.length; i++) {
+                    const row = rows[i];
+                    entry.present[i] = row !== null;
+                    if (row !== null) value[optional[i]] = row[optional[i]];
+                }
+                entry.value = value;
+            }
+            entry.valid = true;
+        }
+        if (!changed && entry.waiting === 0) return failed;
+        return give(entry, through, changed, state.pass, -1, failed);
+    };
+    /** Drops entries found without subscribers in three passes, as shapes are; returns whether any is left without them. */
+    const sweep = (): boolean => {
+        const { entries } = shape;
+        let kept = 0;
+        let idle = false;
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            if (entry.stopped > 0) sweepSubscribers(entry);
+            if (entry.live === 0) {
+                if (++entry.idle > 2) {
+                    shape.byEntity.delete(entry.entity);
+                    continue;
+                }
+                idle = true;
+            }
+            entries[kept++] = entry;
+        }
+        entries.length = kept;
+        return idle;
+    };
+    /** Evaluates every entry, or with nothing changed, those whose subscribers wait for a first value. */
+    const pass = (changed: boolean, finders: Finders): void => {
+        passed(state);
+        if (!shape.swept) shape.swept = !sweep();
+        if (!changed && !shape.waiting) return;
+        const through = state.delivered;
+        const { entries } = shape;
+        let failed: unknown = none;
+        let waiting = false;
+        for (let i = 0, count = entries.length; i < count; i++) {
+            const entry = entries[i];
+            if (changed || (entry.waiting > 0 && !entry.valid)) failed = evaluate(entry, finders, through, failed);
+            else if (entry.waiting > 0) failed = give(entry, through, false, state.pass, -1, failed);
+            if (entry.waiting > 0) waiting = true;
+        }
+        shape.waiting = waiting;
+        throwFailed(failed);
+    };
+    /** The finders of the runner whose lookups they are: another, once its system is added again. */
+    let finders: Finders | null = null;
+    let source: object | null = null;
+    const system = optional.length === 0
+        ? System.create(labelled({ observer: true, lookup: { presence: { with: required, changed: required }, values: { with: required }, members: { index: membersOf(required), changed: required } } }, name, { lookup: { values: required } }), ({ lookup }) => {
+            if (source !== lookup || finders === null) {
+                source = lookup;
+                finders = { presence: lookup.presence, values: lookup.values, optional: noOptional };
+            }
+            pass(lookup.members().changed, finders);
+        })
+        : System.create(labelled({ observer: true, lookup: optionalLookups(required, optional) }, name, { lookup: optionalReads(required, optional) }), ({ lookup }) => {
+            if (source !== lookup || finders === null) {
+                source = lookup;
+                finders = { presence: lookup.presence, values: lookup.values, optional: (index, entity) => lookup[index](entity) };
+            }
+            pass(true, finders);
+        });
+    const shape: EntityShape = {
+        live: 0,
+        idle: 0,
+        system,
+        read: {
+            system,
+            flushed: noDelivery,
+            delivered: batch => {
+                const { entries } = shape;
+                for (let i = 0; i < entries.length; i++) giveFirst(state, entries[i], batch);
+            },
+        },
+        attached: false,
+        entries: [],
+        byEntity: new Map(),
+        waiting: false,
+        swept: true,
+        remove: () => {
+            shape.attached = false;
+            shape.entries.length = 0;
+            shape.byEntity.clear();
+            state.world.remove(system);
+        },
+    };
+    byShape.set(id, shape);
+    return shape;
+};
+
+const noOptional = (): null => null;
+
+type Watched = { readonly with: readonly Component.Key[]; readonly changed: readonly Component.Key[] };
+
+/** Lookups of an entity's required components, whether and what, and one of each optional one, by its position. */
+const optionalLookups = (required: readonly Component.Key[], optional: readonly Component.Key[]): {
+    readonly presence: { readonly with: readonly Component.Key[]; readonly changed: readonly Component.Key[] };
+    readonly values: { readonly with: readonly Component.Key[] };
+    readonly [index: number]: Watched;
+} => {
+    const lookups: { presence: { readonly with: readonly Component.Key[]; readonly changed: readonly Component.Key[] }; values: { readonly with: readonly Component.Key[] }; [index: number]: Watched } = {
+        presence: { with: required, changed: required },
+        values: { with: required },
+    };
+    for (let i = 0; i < optional.length; i++) lookups[i] = { with: [optional[i]], changed: [optional[i]] };
+    return lookups;
+};
+
+/** What the optional shape's body reads of its lookups' rows: the required values, and each optional one. */
+const optionalReads = (required: readonly Component.Key[], optional: readonly Component.Key[]): { readonly [name: string]: readonly Component.Key[] } => {
+    const reads: { [name: string]: readonly Component.Key[] } = { values: required };
+    for (let i = 0; i < optional.length; i++) reads[i] = [optional[i]];
+    return reads;
+};
+
+export const observeEntity = <T>(world: World, entity: Entity, components: { readonly required?: readonly Component.Key[]; readonly optional?: readonly Component.Key[] }): Observe<T | null> => {
+    const required = [...components.required ?? []];
+    const optional = [...components.optional ?? []];
+    const id = `${keysId(required)};${keysId(optional)}`;
+    return notify => {
+        const state = stateOf(world);
+        let byShape = shapes.get(state);
+        if (byShape === undefined) shapes.set(state, byShape = new Map());
+        const shape = byShape.get(id) ?? createShape(state, byShape, id, required, optional);
+        if (!shape.attached) {
+            // Throws on a joined thread for components it can't read, adding nothing.
+            world.add(shape.system);
+            shape.attached = true;
+        }
+        let entry = shape.byEntity.get(entity);
+        if (entry === undefined) {
+            entry = { ...createEntry<object | null>(null), entity, present: optional.map(() => false) };
+            shape.byEntity.set(entity, entry);
+            shape.entries.push(entry);
+        }
+        const observed = entry;
+        // An entity observer's values have the listed components' types, which `members.ts` gives `T` by the lists.
+        const typed = observed as Entry<T | null>;
+        const stop = subscribe(state, shape, typed, notify, () => {
+            shape.waiting = true;
+            if (state.joined) scheduleRead(state, shape.read);
+            else scheduleDelivery(state);
+        });
+        return () => {
+            if (observed.live > 0) shape.swept = false;
+            stop();
+        };
+    };
+};

package/src/observe/index.ts

@@ -0,0 +1,2 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export { Observe } from './observe.js';

package/src/observe/members.ts

@@ -0,0 +1,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component, Components, Entity, Resource, World } from '../interface/index.js';
+import { observeEntity } from './entity.js';
+import type { Observe } from './observe.js';
+import { observeCount, observeSelect } from './select.js';
+import type { Query } from './query.js';
+import { observeResource } from './resource.js';
+import type { ReadonlyResourceValue, ReadonlyValue } from './values.js';
+
+export { toPromise } from './to-promise.js';
+export type { Query } from './query.js';
+
+/**
+ * A resource's value, then a new one after each run or tick that changed it: one whose sync point stamped it, even with
+ * the same value, a reduced resource when its fold differs.
+ */
+export const resource = <R extends Resource.Key>(world: World, resource: R): Observe<ReadonlyResourceValue<R>> =>
+    observeResource(world, resource);
+
+/**
+ * An entity's required components and those optional ones it has, or `null` while it's dead or lacks a required one;
+ * then a new value after each run or tick that wrote a listed component of it, added or removed one, or despawned it.
+ * Other components' changes don't notify, nor does anything while it stays `null`. Values map over
+ * `Pick<Components, ...>`, so their symbol keys keep the declarations a consumer's emitted types name them by.
+ */
+export const entity = <const R extends readonly Component.Key[] = [], const O extends readonly Component.Key[] = []>(
+    world: World,
+    entity: Entity,
+    components: { readonly required?: R; readonly optional?: O },
+): Observe<({ readonly [K in keyof Pick<Components, R[number]>]: ReadonlyValue<K> } & { readonly [K in keyof Pick<Components, O[number]>]?: ReadonlyValue<K> }) | null> =>
+    observeEntity(world, entity, components);
+
+/**
+ * The entities a query matches, sorted by `order` if given, and with a `page`, at most `limit` of them from `offset`;
+ * then a new value after each run or tick whose result differs. Nothing when it's the same, even if matching entities
+ * were written. Throws for a page whose offset or limit isn't a non-negative integer.
+ */
+export const select = <const R extends readonly Component.Key[] = []>(world: World, query: Query<R>): Observe<readonly Entity[]> =>
+    observeSelect(world, query);
+
+/** The number of entities a query matches; then a new one after each run or tick that changed it. */
+export const count = <const R extends readonly Component.Key[] = []>(world: World, query: Omit<Query<R>, "order" | "page">): Observe<number> =>
+    observeCount(world, query);

package/src/observe/observe.ts

@@ -0,0 +1,25 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * Observes a sequence of values: `notify` is called zero or more times, possibly during the call that subscribes,
+ * possibly later; an observer mustn't depend on either. Returns the function that stops it.
+ */
+export type Observe<T> = (notify: (value: T) => void) => Unobserve;
+
+/** Stops notifications; calling it again does nothing. */
+type Unobserve = () => void;
+
+/**
+ * Observers of a world, built on observer systems: one per resource and per shape of observer, shared by every
+ * subscriber of it, notifying once per run or tick whose sync point changed what it gives, and only then. - A first
+ * value already held for that resource, entity or query, while others observe it, comes during the subscribing   call,
+ * as of the last sync point. Any other comes later, from a run after every run called before the subscribing   call, so
+ * it reflects them; first values of one task come in that order, from one batch of runs. A first value   whose notify
+ * throws is thrown out of band, as an uncaught error, and stops that observer; a later value's is a   `"system"`
+ * failure of the run or tick, named by the observer's system.
+ * - Selections without `order`, and ties under one, come in entity order. Under `order`, NaN comes after every number.
+ * - Values are kept warm for subscribers to come while their observers are used, and released once the world's
+ *   passes found them unused in three; a query is kept current through an index only once a subscriber outlives its
+ *   first value, so a first value alone is one scan.
+ * - A disposed world runs nothing, so a first value that comes later never comes.
+ */
+export * as Observe from './members.js';