@oasys/oecs 0.4.0 → 0.5.0

package/dist/core/ecs/event_registry.d.ts

@@ -0,0 +1,22 @@
+import { EmptyEventSchema, EventDef, EventReader, EventShape } from './event.js';
+export declare class EventRegistry {
+    private readonly channels;
+    private readonly dirtyChannels;
+    private count;
+    private readonly keyMap;
+    registerEvent<S extends EventShape<S>>(fields: readonly (keyof S & string)[]): EventDef<S>;
+    emitEvent(def: EventDef<any>, values: Record<string, number>): void;
+    emitSignal(def: EventDef<EmptyEventSchema>): void;
+    getEventReader<S extends EventShape<S>>(def: EventDef<S>): EventReader<S>;
+    clearEvents(): void;
+    /** `DEV`-only: total events currently buffered across the dirty channels.
+     * `ECS.update` samples this either side of `dispatchSet` to assert an onSet
+     * observer emitted nothing — its emissions would be wiped by the tick-tail
+     * `clearEvents` and break the empty-channel-at-boundary invariant snapshot /
+     * restore relies on (#586). Walks only the dirty list, never the hot emit path. */
+    devBufferedEventCount(): number;
+    registerEventByKey<S extends EventShape<S>>(key: symbol, fields: readonly (keyof S & string)[]): EventDef<S>;
+    getEventDefByKey(key: symbol): EventDef<any>;
+    hasEventKey(key: symbol): boolean;
+}
+//# sourceMappingURL=event_registry.d.ts.map

package/dist/core/ecs/event_registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event_registry.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/event_registry.ts"],"names":[],"mappings":"AAAA;;;;;;;KAOK;AAGL,OAAO,EAGN,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,MAAM,SAAS,CAAC;AAGjB,qBAAa,aAAa;IAEzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAK/C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,KAAK,CAAK;IAIlB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAEzD,aAAa,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAC3C,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,GACnC,QAAQ,CAAC,CAAC,CAAC;IAOP,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAYnE,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAQjD,cAAc,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;IAIzE,WAAW,IAAI,IAAI;IAS1B;;;;uFAImF;IAC5E,qBAAqB,IAAI,MAAM;IAQ/B,kBAAkB,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAChD,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,GACnC,QAAQ,CAAC,CAAC,CAAC;IAcP,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC;IAY5C,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAGxC"}

package/dist/core/ecs/facades.d.cts

@@ -0,0 +1,158 @@
+import { Store } from './store.cjs';
+import { EntityID } from './entity.cjs';
+import { OnDeleteTarget, RelationDef, RelationOptions } from './relation.cjs';
+import { ResourceKey } from './resource.cjs';
+import { EventFieldsCover, EventKey, EventReader, EventShape, SignalKey } from './event.cjs';
+/** Relations — sparse `(relation, target)` pairs and hierarchy traversal
+ * (#471 / #474, ADR-0011). Add/remove/re-target cause no archetype
+ * transition; ops are immediate and safe mid-tick. Traversal and wildcard
+ * reads are cold-path. */
+export declare class ECSRelations {
+    private readonly store;
+    /** @internal constructed by `ECS`. */
+    constructor(store: Store);
+    /** Register a relation kind. Exclusive (default) stores one target per
+     * source; `{ multi: true }` stores a target set per source.
+     * `{ onDeleteTarget: "delete" | "clear" | "orphan" }` selects target-death
+     * cleanup (default `orphan`, #473).
+     *
+     * The overloads stamp the CARDINALITY into the handle type (typestate
+     * a173382 / POLISH_AUDIT #7), exactly like the flat `registerRelation`:
+     * the exclusive-only surfaces (`targetOf`, `ancestorsOf`/`rootOf`/
+     * `cascadeOf`, `Query.hierarchy`) accept only `RelationDef<"exclusive">`,
+     * so passing a `{ multi: true }` relation is a compile error. A
+     * dynamically-built options value falls to the erased overload and keeps
+     * the runtime check as its only guard. */
+    register(opts?: {
+        readonly exclusive?: true;
+        readonly multi?: false;
+        readonly onDeleteTarget?: OnDeleteTarget;
+    }): RelationDef<"exclusive">;
+    register(opts: {
+        readonly multi: true;
+        readonly exclusive?: false;
+        readonly onDeleteTarget?: OnDeleteTarget;
+    }): RelationDef<"multi">;
+    register(opts?: RelationOptions): RelationDef;
+    /** Count of registered relations. */
+    get count(): number;
+    /** Add a `(R, tgt)` pair to `src`. Exclusive replaces the existing target;
+     * multi adds to the set. No archetype transition. */
+    add(src: EntityID, def: RelationDef, tgt: EntityID): this;
+    /** Remove a `(R, tgt)` pair from `src`. For multi, omitting `tgt` removes
+     * all of `src`'s targets. No archetype transition. */
+    remove(src: EntityID, def: RelationDef, tgt?: EntityID): this;
+    /** Whether `src` holds any pair under `R`. */
+    has(src: EntityID, def: RelationDef): boolean;
+    /** The single target of `src` under an exclusive relation, or `undefined`. */
+    targetOf(src: EntityID, def: RelationDef<"exclusive">): EntityID | undefined;
+    /** All targets of `src` under `R`, ascending by id. */
+    targetsOf(src: EntityID, def: RelationDef): EntityID[];
+    /** Sources pointing at `tgt` under `R` (the reverse index), ascending by id.
+     * `(entity, def)` order, matching `targetOf` / `targetsOf`. */
+    sourcesOf(tgt: EntityID, def: RelationDef): EntityID[];
+    /** All `(source, target)` pairs of relation `R` — the `(R, *)` wildcard
+     * (#472). Sources in canonical entity-index order. Cold path. */
+    pairsOf(def: RelationDef): readonly (readonly [EntityID, EntityID])[];
+    /** Every `(relation, source)` pointing at `tgt`, across all relation kinds —
+     * the `(*, T)` wildcard (#472). Ordered by relation id then source id. */
+    sourcesOfAny(tgt: EntityID): readonly (readonly [RelationDef, EntityID])[];
+    /** Walk relation `R` up from `src` to its chain root, returning
+     * `[src, parent, …, root]` (nearest-ancestor-first). Exclusive only. */
+    ancestorsOf(src: EntityID, def: RelationDef<"exclusive">): EntityID[];
+    /** The root of `src`'s `R`-chain (`src` itself when it has no target).
+     * Exclusive only. */
+    rootOf(src: EntityID, def: RelationDef<"exclusive">): EntityID;
+    /** Walk relation `R` down from `root` over the reverse index, returning the
+     * subtree (including `root`) breadth-first — parents before children (the
+     * `cascade` order). Exclusive only. */
+    cascadeOf(root: EntityID, def: RelationDef<"exclusive">): EntityID[];
+    /** Reclaim relation reverse-index memory: drop every reverse entry whose
+     * target has been destroyed, returning the total dropped (#491). Purely
+     * cold-path, no observable state change — call at scene/snapshot
+     * boundaries. */
+    compact(): number;
+}
+/** Event channels and signals. Emit during one `update()`, visible to every
+ * later system in that call, cleared before the next. System-side reads and
+ * emits go through `ctx` — this facade is the HOST-side surface. */
+export declare class ECSEvents {
+    private readonly store;
+    /** @internal constructed by `ECS`. */
+    constructor(store: Store);
+    /** Register an event channel at world setup, before anything emits on it.
+     * `fields` must name EVERY schema key — an under-registered channel would
+     * silently drop the missing fields at emit (see `EventFieldsCover`).
+     *
+     * @example
+     * const Damaged = eventKey<{ target: EntityID; amount: number }>("Damaged");
+     * ecs.events.register(Damaged, ["target", "amount"]);
+     * ecs.events.emit(Damaged, { target: e, amount: 10 }); // or ctx.emit inside a system
+     */
+    register<S extends EventShape<S>, const F extends readonly (keyof S & string)[]>(key: EventKey<S>, fields: F & EventFieldsCover<S, F>): void;
+    /** Register a signal (empty-payload event channel). */
+    registerSignal(key: SignalKey): void;
+    emit(key: SignalKey): void;
+    emit<S extends EventShape<S>>(key: EventKey<S>, values: NoInfer<S>): void;
+    read<S extends EventShape<S>>(key: EventKey<S>): EventReader<S>;
+}
+/** World resources — singleton values keyed by `ResourceKey<T>`. Runtime
+ * mutations (`set` / `remove`) are access-checked as resource writes inside
+ * a system span; `register` is a one-time world-setup op. */
+export declare class ECSResources {
+    private readonly store;
+    /** @internal constructed by `ECS`. */
+    constructor(store: Store);
+    /** Register a resource at world setup. Reading/writing an unregistered
+     * key throws (fail-closed) — registration is the explicit "this world has
+     * this singleton" declaration, not a lazy default.
+     *
+     * @example
+     * const GameTime = resourceKey<{ elapsed: number }>("GameTime");
+     * ecs.resources.register(GameTime, { elapsed: 0 });
+     * ecs.resources.get(GameTime).elapsed; // or ctx.resource(GameTime) inside a system
+     */
+    register<T>(key: ResourceKey<T>, value: NoInfer<T>): void;
+    get<T>(key: ResourceKey<T>): T;
+    set<T>(key: ResourceKey<T>, value: NoInfer<T>): void;
+    /** Drop a resource from the world (#798). Access-checked as a *write*;
+     * fails closed on a missing key. Afterwards the key is free to `register`
+     * again — the present → absent → present lifecycle. */
+    remove<T>(key: ResourceKey<T>): void;
+    has<T>(key: ResourceKey<T>): boolean;
+}
+/** The determinism surface (#626 / ADR-0020): world snapshot/resume and the
+ * canonical state digest. Every member except `deterministic` throws
+ * `DETERMINISM_DISABLED` unless the world was constructed with
+ * `{ deterministic: true }`. All cold-path — take captures at tick
+ * boundaries (between `update()`s). */
+export declare class ECSSnapshots {
+    private readonly store;
+    /** @internal constructed by `ECS`. */
+    constructor(store: Store);
+    /** Whether the determinism surface is enabled. */
+    get deterministic(): boolean;
+    /** FNV-1a 32 digest over every archetype's live rows in id order — the
+     * canonical "live ECS state digest". Per-call cost scales with live
+     * entity count, not SAB capacity. */
+    stateHash(): number;
+    /** Capture the full live world (dense + sparse/relations + host-side
+     * bookkeeping) to one self-contained byte buffer that `restore` can mount
+     * back onto a live, ticking world (#789). v1 does NOT capture resources,
+     * events, or change-detection baselines (ADR-0031). */
+    capture(): Uint8Array;
+    /** Mount a `capture()` buffer onto this live world and keep ticking.
+     * Fails closed on a malformed frame or registration mismatch BEFORE
+     * mutating any live state. Requires a matching archetype set + column
+     * layout (prewarm so the set is stable). */
+    restore(bytes: Uint8Array): void;
+    /** Serialize the sparse stores + relations to a self-contained buffer —
+     * the sparse half of a world snapshot, canonical entity-index order
+     * (#470). Pairs with `restoreSparse`. */
+    captureSparse(): Uint8Array;
+    /** Repopulate the sparse stores + relation indices from `captureSparse`
+     * bytes. Sparse components must already be registered in the same order;
+     * throws `SparseRestoreError` on a shape or identity mismatch. */
+    restoreSparse(bytes: Uint8Array): void;
+}
+//# sourceMappingURL=facades.d.ts.map

package/dist/core/ecs/facades.d.ts

@@ -0,0 +1,158 @@
+import { Store } from './store.js';
+import { EntityID } from './entity.js';
+import { OnDeleteTarget, RelationDef, RelationOptions } from './relation.js';
+import { ResourceKey } from './resource.js';
+import { EventFieldsCover, EventKey, EventReader, EventShape, SignalKey } from './event.js';
+/** Relations — sparse `(relation, target)` pairs and hierarchy traversal
+ * (#471 / #474, ADR-0011). Add/remove/re-target cause no archetype
+ * transition; ops are immediate and safe mid-tick. Traversal and wildcard
+ * reads are cold-path. */
+export declare class ECSRelations {
+    private readonly store;
+    /** @internal constructed by `ECS`. */
+    constructor(store: Store);
+    /** Register a relation kind. Exclusive (default) stores one target per
+     * source; `{ multi: true }` stores a target set per source.
+     * `{ onDeleteTarget: "delete" | "clear" | "orphan" }` selects target-death
+     * cleanup (default `orphan`, #473).
+     *
+     * The overloads stamp the CARDINALITY into the handle type (typestate
+     * a173382 / POLISH_AUDIT #7), exactly like the flat `registerRelation`:
+     * the exclusive-only surfaces (`targetOf`, `ancestorsOf`/`rootOf`/
+     * `cascadeOf`, `Query.hierarchy`) accept only `RelationDef<"exclusive">`,
+     * so passing a `{ multi: true }` relation is a compile error. A
+     * dynamically-built options value falls to the erased overload and keeps
+     * the runtime check as its only guard. */
+    register(opts?: {
+        readonly exclusive?: true;
+        readonly multi?: false;
+        readonly onDeleteTarget?: OnDeleteTarget;
+    }): RelationDef<"exclusive">;
+    register(opts: {
+        readonly multi: true;
+        readonly exclusive?: false;
+        readonly onDeleteTarget?: OnDeleteTarget;
+    }): RelationDef<"multi">;
+    register(opts?: RelationOptions): RelationDef;
+    /** Count of registered relations. */
+    get count(): number;
+    /** Add a `(R, tgt)` pair to `src`. Exclusive replaces the existing target;
+     * multi adds to the set. No archetype transition. */
+    add(src: EntityID, def: RelationDef, tgt: EntityID): this;
+    /** Remove a `(R, tgt)` pair from `src`. For multi, omitting `tgt` removes
+     * all of `src`'s targets. No archetype transition. */
+    remove(src: EntityID, def: RelationDef, tgt?: EntityID): this;
+    /** Whether `src` holds any pair under `R`. */
+    has(src: EntityID, def: RelationDef): boolean;
+    /** The single target of `src` under an exclusive relation, or `undefined`. */
+    targetOf(src: EntityID, def: RelationDef<"exclusive">): EntityID | undefined;
+    /** All targets of `src` under `R`, ascending by id. */
+    targetsOf(src: EntityID, def: RelationDef): EntityID[];
+    /** Sources pointing at `tgt` under `R` (the reverse index), ascending by id.
+     * `(entity, def)` order, matching `targetOf` / `targetsOf`. */
+    sourcesOf(tgt: EntityID, def: RelationDef): EntityID[];
+    /** All `(source, target)` pairs of relation `R` — the `(R, *)` wildcard
+     * (#472). Sources in canonical entity-index order. Cold path. */
+    pairsOf(def: RelationDef): readonly (readonly [EntityID, EntityID])[];
+    /** Every `(relation, source)` pointing at `tgt`, across all relation kinds —
+     * the `(*, T)` wildcard (#472). Ordered by relation id then source id. */
+    sourcesOfAny(tgt: EntityID): readonly (readonly [RelationDef, EntityID])[];
+    /** Walk relation `R` up from `src` to its chain root, returning
+     * `[src, parent, …, root]` (nearest-ancestor-first). Exclusive only. */
+    ancestorsOf(src: EntityID, def: RelationDef<"exclusive">): EntityID[];
+    /** The root of `src`'s `R`-chain (`src` itself when it has no target).
+     * Exclusive only. */
+    rootOf(src: EntityID, def: RelationDef<"exclusive">): EntityID;
+    /** Walk relation `R` down from `root` over the reverse index, returning the
+     * subtree (including `root`) breadth-first — parents before children (the
+     * `cascade` order). Exclusive only. */
+    cascadeOf(root: EntityID, def: RelationDef<"exclusive">): EntityID[];
+    /** Reclaim relation reverse-index memory: drop every reverse entry whose
+     * target has been destroyed, returning the total dropped (#491). Purely
+     * cold-path, no observable state change — call at scene/snapshot
+     * boundaries. */
+    compact(): number;
+}
+/** Event channels and signals. Emit during one `update()`, visible to every
+ * later system in that call, cleared before the next. System-side reads and
+ * emits go through `ctx` — this facade is the HOST-side surface. */
+export declare class ECSEvents {
+    private readonly store;
+    /** @internal constructed by `ECS`. */
+    constructor(store: Store);
+    /** Register an event channel at world setup, before anything emits on it.
+     * `fields` must name EVERY schema key — an under-registered channel would
+     * silently drop the missing fields at emit (see `EventFieldsCover`).
+     *
+     * @example
+     * const Damaged = eventKey<{ target: EntityID; amount: number }>("Damaged");
+     * ecs.events.register(Damaged, ["target", "amount"]);
+     * ecs.events.emit(Damaged, { target: e, amount: 10 }); // or ctx.emit inside a system
+     */
+    register<S extends EventShape<S>, const F extends readonly (keyof S & string)[]>(key: EventKey<S>, fields: F & EventFieldsCover<S, F>): void;
+    /** Register a signal (empty-payload event channel). */
+    registerSignal(key: SignalKey): void;
+    emit(key: SignalKey): void;
+    emit<S extends EventShape<S>>(key: EventKey<S>, values: NoInfer<S>): void;
+    read<S extends EventShape<S>>(key: EventKey<S>): EventReader<S>;
+}
+/** World resources — singleton values keyed by `ResourceKey<T>`. Runtime
+ * mutations (`set` / `remove`) are access-checked as resource writes inside
+ * a system span; `register` is a one-time world-setup op. */
+export declare class ECSResources {
+    private readonly store;
+    /** @internal constructed by `ECS`. */
+    constructor(store: Store);
+    /** Register a resource at world setup. Reading/writing an unregistered
+     * key throws (fail-closed) — registration is the explicit "this world has
+     * this singleton" declaration, not a lazy default.
+     *
+     * @example
+     * const GameTime = resourceKey<{ elapsed: number }>("GameTime");
+     * ecs.resources.register(GameTime, { elapsed: 0 });
+     * ecs.resources.get(GameTime).elapsed; // or ctx.resource(GameTime) inside a system
+     */
+    register<T>(key: ResourceKey<T>, value: NoInfer<T>): void;
+    get<T>(key: ResourceKey<T>): T;
+    set<T>(key: ResourceKey<T>, value: NoInfer<T>): void;
+    /** Drop a resource from the world (#798). Access-checked as a *write*;
+     * fails closed on a missing key. Afterwards the key is free to `register`
+     * again — the present → absent → present lifecycle. */
+    remove<T>(key: ResourceKey<T>): void;
+    has<T>(key: ResourceKey<T>): boolean;
+}
+/** The determinism surface (#626 / ADR-0020): world snapshot/resume and the
+ * canonical state digest. Every member except `deterministic` throws
+ * `DETERMINISM_DISABLED` unless the world was constructed with
+ * `{ deterministic: true }`. All cold-path — take captures at tick
+ * boundaries (between `update()`s). */
+export declare class ECSSnapshots {
+    private readonly store;
+    /** @internal constructed by `ECS`. */
+    constructor(store: Store);
+    /** Whether the determinism surface is enabled. */
+    get deterministic(): boolean;
+    /** FNV-1a 32 digest over every archetype's live rows in id order — the
+     * canonical "live ECS state digest". Per-call cost scales with live
+     * entity count, not SAB capacity. */
+    stateHash(): number;
+    /** Capture the full live world (dense + sparse/relations + host-side
+     * bookkeeping) to one self-contained byte buffer that `restore` can mount
+     * back onto a live, ticking world (#789). v1 does NOT capture resources,
+     * events, or change-detection baselines (ADR-0031). */
+    capture(): Uint8Array;
+    /** Mount a `capture()` buffer onto this live world and keep ticking.
+     * Fails closed on a malformed frame or registration mismatch BEFORE
+     * mutating any live state. Requires a matching archetype set + column
+     * layout (prewarm so the set is stable). */
+    restore(bytes: Uint8Array): void;
+    /** Serialize the sparse stores + relations to a self-contained buffer —
+     * the sparse half of a world snapshot, canonical entity-index order
+     * (#470). Pairs with `restoreSparse`. */
+    captureSparse(): Uint8Array;
+    /** Repopulate the sparse stores + relation indices from `captureSparse`
+     * bytes. Sparse components must already be registered in the same order;
+     * throws `SparseRestoreError` on a shape or identity mismatch. */
+    restoreSparse(bytes: Uint8Array): void;
+}
+//# sourceMappingURL=facades.d.ts.map

package/dist/core/ecs/facades.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facades.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/facades.ts"],"names":[],"mappings":"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"}

package/dist/core/ecs/frame_stepper.d.cts

@@ -0,0 +1,58 @@
+import { ECS } from './ecs.cjs';
+type FrameCallback = (timestampMs: number) => void;
+type RequestFrame = (callback: FrameCallback) => number;
+type CancelFrame = (handle: number) => void;
+export interface FrameStepperOptions {
+    /** Delta used by `step()` when no dt is supplied, in seconds. Default 1/60. */
+    readonly fixedDt?: number;
+    /** Clamp browser-frame deltas before forwarding them to `ECS.update()`, in
+     * seconds. Default 0.25. A backgrounded tab suspends rAF; the first frame
+     * after it resumes carries the whole suspended interval as one delta, and
+     * without the clamp that lands in `update()`'s accumulator as a giant
+     * catch-up burst (bounded by `maxFixedSteps`, but still a burst). Manual
+     * `step()` deltas are deliberately not clamped — an explicit dt is trusted. */
+    readonly maxDt?: number;
+    /** Dependency injection for tests or non-browser hosts. Defaults to `requestAnimationFrame`. */
+    readonly requestFrame?: RequestFrame;
+    /** Dependency injection for tests or non-browser hosts. Defaults to `cancelAnimationFrame`. */
+    readonly cancelFrame?: CancelFrame;
+    /** Start the automatic frame loop immediately. */
+    readonly autoStart?: boolean;
+}
+/**
+ * Small host-side controller for manual ECS frame stepping.
+ *
+ * `ECS.update(dt)` is already the authoritative "run one frame" primitive.
+ * This class wraps it with pause/play controls for browser loops and an explicit
+ * `step()` method for debuggers, tests, editor tools, and rollback playback.
+ */
+export declare class FrameStepper {
+    private readonly ecs;
+    private readonly requestFrame?;
+    private readonly cancelFrame?;
+    private frameHandle;
+    private lastTimestampMs;
+    private running;
+    private _fixedDt;
+    private _maxDt;
+    constructor(ecs: ECS, options?: FrameStepperOptions);
+    get fixedDt(): number;
+    set fixedDt(value: number);
+    get maxDt(): number;
+    set maxDt(value: number);
+    get isRunning(): boolean;
+    /** Advance exactly one ECS frame. */
+    step(dt?: number): void;
+    /** Advance several fixed-size frames, useful for replaying a paused sim. */
+    stepFrames(count: number, dt?: number): void;
+    /** Start ticking with `requestAnimationFrame`; no-op when already running. */
+    play(): void;
+    /** Stop the automatic frame loop. Manual `step()` still works while paused. */
+    pause(): void;
+    toggle(): void;
+    dispose(): void;
+    private scheduleNextFrame;
+    private readonly onFrame;
+}
+export {};
+//# sourceMappingURL=frame_stepper.d.ts.map

package/dist/core/ecs/frame_stepper.d.ts

@@ -0,0 +1,58 @@
+import { ECS } from './ecs.js';
+type FrameCallback = (timestampMs: number) => void;
+type RequestFrame = (callback: FrameCallback) => number;
+type CancelFrame = (handle: number) => void;
+export interface FrameStepperOptions {
+    /** Delta used by `step()` when no dt is supplied, in seconds. Default 1/60. */
+    readonly fixedDt?: number;
+    /** Clamp browser-frame deltas before forwarding them to `ECS.update()`, in
+     * seconds. Default 0.25. A backgrounded tab suspends rAF; the first frame
+     * after it resumes carries the whole suspended interval as one delta, and
+     * without the clamp that lands in `update()`'s accumulator as a giant
+     * catch-up burst (bounded by `maxFixedSteps`, but still a burst). Manual
+     * `step()` deltas are deliberately not clamped — an explicit dt is trusted. */
+    readonly maxDt?: number;
+    /** Dependency injection for tests or non-browser hosts. Defaults to `requestAnimationFrame`. */
+    readonly requestFrame?: RequestFrame;
+    /** Dependency injection for tests or non-browser hosts. Defaults to `cancelAnimationFrame`. */
+    readonly cancelFrame?: CancelFrame;
+    /** Start the automatic frame loop immediately. */
+    readonly autoStart?: boolean;
+}
+/**
+ * Small host-side controller for manual ECS frame stepping.
+ *
+ * `ECS.update(dt)` is already the authoritative "run one frame" primitive.
+ * This class wraps it with pause/play controls for browser loops and an explicit
+ * `step()` method for debuggers, tests, editor tools, and rollback playback.
+ */
+export declare class FrameStepper {
+    private readonly ecs;
+    private readonly requestFrame?;
+    private readonly cancelFrame?;
+    private frameHandle;
+    private lastTimestampMs;
+    private running;
+    private _fixedDt;
+    private _maxDt;
+    constructor(ecs: ECS, options?: FrameStepperOptions);
+    get fixedDt(): number;
+    set fixedDt(value: number);
+    get maxDt(): number;
+    set maxDt(value: number);
+    get isRunning(): boolean;
+    /** Advance exactly one ECS frame. */
+    step(dt?: number): void;
+    /** Advance several fixed-size frames, useful for replaying a paused sim. */
+    stepFrames(count: number, dt?: number): void;
+    /** Start ticking with `requestAnimationFrame`; no-op when already running. */
+    play(): void;
+    /** Stop the automatic frame loop. Manual `step()` still works while paused. */
+    pause(): void;
+    toggle(): void;
+    dispose(): void;
+    private scheduleNextFrame;
+    private readonly onFrame;
+}
+export {};
+//# sourceMappingURL=frame_stepper.d.ts.map

package/dist/core/ecs/frame_stepper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame_stepper.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/frame_stepper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAGjC,KAAK,aAAa,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;AACnD,KAAK,YAAY,GAAG,CAAC,QAAQ,EAAE,aAAa,KAAK,MAAM,CAAC;AACxD,KAAK,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;AAM5C,MAAM,WAAW,mBAAmB;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;mFAK+E;IAC/E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,gGAAgG;IAChG,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,+FAA+F;IAC/F,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC7B;AAsBD;;;;;;GAMG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAc;IAC3C,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;gBAEJ,GAAG,EAAE,GAAG,EAAE,OAAO,GAAE,mBAAwB;IAW9D,IAAW,OAAO,IAAI,MAAM,CAE3B;IAED,IAAW,OAAO,CAAC,KAAK,EAAE,MAAM,EAE/B;IAED,IAAW,KAAK,IAAI,MAAM,CAEzB;IAED,IAAW,KAAK,CAAC,KAAK,EAAE,MAAM,EAE7B;IAED,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED,qCAAqC;IAC9B,IAAI,CAAC,EAAE,GAAE,MAAsB,GAAG,IAAI;IAI7C,4EAA4E;IACrE,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAE,MAAsB,GAAG,IAAI;IAMlE,8EAA8E;IACvE,IAAI,IAAI,IAAI;IAanB,+EAA+E;IACxE,KAAK,IAAI,IAAI;IASb,MAAM,IAAI,IAAI;IAKd,OAAO,IAAI,IAAI;IAItB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAQtB;CACF"}

package/dist/core/ecs/frame_trace.d.cts

@@ -0,0 +1,133 @@
+import { EntityID } from './entity.cjs';
+import { SystemDescriptor } from './system.cjs';
+import { SCHEDULE } from './schedule.cjs';
+/** A deferred structural command issued through `ctx.commands.*` (`query.ts`).
+ * `spawn`/`despawn`/`enable`/`disable` carry a `null` component; `add`/`remove`
+ * carry the affected component's id. */
+export type StructuralOp = "spawn" | "despawn" | "add" | "remove" | "enable" | "disable";
+/** An observer edge that fired at a flush (`add`/`remove`/`enable`/`disable`) or
+ * at the post-update onSet detection point (`set`). */
+export type ObserverOp = "add" | "remove" | "set" | "enable" | "disable";
+/**
+ * The push sink. All callers are `DEV`-gated, so the methods receive raw ids
+ * and descriptor references (no string-building on the hot path); the recorder
+ * decides what to retain. Implementations must be side-effect-free with respect
+ * to the ECS — they observe, never mutate.
+ */
+export interface FrameTraceSink {
+    /** Opens a frame. Fired first in `ecs.update`, before any phase runs. */
+    tickBegin(tick: number, dt: number): void;
+    /** Closes the frame opened by `tickBegin` (after onSet + `clearEvents`). */
+    tickEnd(tick: number): void;
+    /** A scheduled system is about to run, in the given phase. */
+    systemStart(system: SystemDescriptor, phase: SCHEDULE): void;
+    /** The system that last `systemStart`'d has returned. */
+    systemEnd(system: SystemDescriptor): void;
+    /** A deferred structural command was enqueued (applied at the next flush). */
+    commandQueued(op: StructuralOp, entity: EntityID, component: number | null): void;
+    /** The deferred command buffer is about to drain for this phase. */
+    flushBegin(phase: SCHEDULE): void;
+    /** The deferred command buffer (and any observer cascade) has settled. */
+    flushEnd(phase: SCHEDULE): void;
+    /**
+     * A schedule phase has fully settled — every system in `phase` ran and the
+     * deferred command buffer (plus any observer cascade) flushed — so the live
+     * world sits at a consistent, fingerprint-able point WITHIN the frame. Fired
+     * once per phase that runs (each startup phase, each fixed step, and each
+     * update phase), immediately after `flushEnd(phase)`.
+     *
+     * This is the blessed seam for a consumer to read `stateHash()` between the
+     * phases of one `update()` and bisect a divergence to the exact phase that
+     * introduced it (#797 / ADR-0032). `flushEnd` marks the same instant, but it
+     * is an observation of the flush *mechanism*, not a "safe to read consistent
+     * state" contract — so per-phase fingerprinting binds to this method, not to a
+     * flush-internal name. Like every sink method the call is read-only w.r.t. the
+     * ECS: reading `stateHash()` here cannot perturb the per-tick hash or ordering.
+     *
+     * Caveat: the POST_UPDATE boundary fires BEFORE the tick-tail onSet-observer
+     * dispatch + `clearEvents`, so for a world with onSet observers the final
+     * per-tick `stateHash` (after `update()` returns) may differ from the
+     * POST_UPDATE phase hash. A world with no onSet observers reconciles exactly.
+     */
+    phaseBoundary(phase: SCHEDULE): void;
+    /** An observer callback fired for one entity (`entity === -1` for an
+     * archetype-granular onSet, which has no per-entity id). */
+    observerFired(op: ObserverOp, component: number, entity: number, observer: SystemDescriptor): void;
+    /** A system emitted an event on `key` (the channel's symbol description). */
+    eventEmitted(key: string): void;
+    /** A system read an event channel; `count` is how many events it saw. */
+    eventRead(key: string, count: number): void;
+}
+/** One captured event, as plain JSON-serialisable data (string names + numeric
+ * ids), so a `FrameTrace[]` streams straight to a browser renderer. */
+export type FrameTraceEvent = {
+    readonly kind: "system_start";
+    readonly system: string;
+    readonly phase: SCHEDULE;
+} | {
+    readonly kind: "system_end";
+    readonly system: string;
+} | {
+    readonly kind: "command_queued";
+    readonly op: StructuralOp;
+    readonly entity: number;
+    readonly component: number | null;
+} | {
+    readonly kind: "flush_begin";
+    readonly phase: SCHEDULE;
+} | {
+    readonly kind: "flush_end";
+    readonly phase: SCHEDULE;
+} | {
+    readonly kind: "observer_fired";
+    readonly op: ObserverOp;
+    readonly component: number;
+    readonly entity: number;
+    readonly observer: string;
+} | {
+    readonly kind: "event_emitted";
+    readonly key: string;
+} | {
+    readonly kind: "event_read";
+    readonly key: string;
+    readonly count: number;
+};
+/** One frame's captured internals, in causal order. */
+export interface FrameTrace {
+    readonly tick: number;
+    readonly dt: number;
+    readonly events: FrameTraceEvent[];
+}
+/**
+ * The in-tree `FrameTraceSink`. Mirrors `command_log.ts`'s `openTick` /
+ * `RecordedTick` shape: `tickBegin` opens a fresh `FrameTrace`, every other
+ * method appends to it, `tickEnd` closes it. Events arriving with no open
+ * frame (e.g. a stray pre-`update` flush) are ignored rather than throwing —
+ * the recorder is a passive observer.
+ */
+export declare class FrameTraceRecorder implements FrameTraceSink {
+    private readonly _frames;
+    private _current;
+    tickBegin(tick: number, dt: number): void;
+    tickEnd(_tick: number): void;
+    systemStart(system: SystemDescriptor, phase: SCHEDULE): void;
+    systemEnd(system: SystemDescriptor): void;
+    commandQueued(op: StructuralOp, entity: EntityID, component: number | null): void;
+    flushBegin(phase: SCHEDULE): void;
+    flushEnd(phase: SCHEDULE): void;
+    /** No-op (#797 / ADR-0032). The recorder already marks this instant with
+     * `flushEnd`, and a per-phase fingerprint is a consumer concern — the recorder
+     * holds no world reference to hash. The seam exists so a consumer's OWN sink can
+     * run code (e.g. `stateHash()`) at the safe post-flush point; the in-tree
+     * event-stream recorder has nothing to add, so it stays a stream of causal
+     * events, not fingerprints. */
+    phaseBoundary(_phase: SCHEDULE): void;
+    observerFired(op: ObserverOp, component: number, entity: number, observer: SystemDescriptor): void;
+    eventEmitted(key: string): void;
+    eventRead(key: string, count: number): void;
+    /** The captured frames, in `update()` order. */
+    frames(): readonly FrameTrace[];
+    /** Drop all captured frames (reuse the recorder for a fresh run). */
+    reset(): void;
+}
+//# sourceMappingURL=frame_trace.d.ts.map

package/dist/core/ecs/frame_trace.d.ts

@@ -1,6 +1,6 @@
-import { EntityID } from './entity';
-import { SystemDescriptor } from './system';
-import { SCHEDULE } from './schedule';
+import { EntityID } from './entity.js';
+import { SystemDescriptor } from './system.js';
+import { SCHEDULE } from './schedule.js';
 /** A deferred structural command issued through `ctx.commands.*` (`query.ts`).
  * `spawn`/`despawn`/`enable`/`disable` carry a `null` component; `add`/`remove`
  * carry the affected component's id. */
@@ -9,13 +9,13 @@ export type StructuralOp = "spawn" | "despawn" | "add" | "remove" | "enable" | "
  * at the post-update onSet detection point (`set`). */
 export type ObserverOp = "add" | "remove" | "set" | "enable" | "disable";
 /**
- * The push sink. All callers are `__DEV__`-gated, so the methods receive raw ids
+ * The push sink. All callers are `DEV`-gated, so the methods receive raw ids
  * and descriptor references (no string-building on the hot path); the recorder
  * decides what to retain. Implementations must be side-effect-free with respect
  * to the ECS — they observe, never mutate.
  */
 export interface FrameTraceSink {
-    /** Opens a frame. Fired first in `world.update`, before any phase runs. */
+    /** Opens a frame. Fired first in `ecs.update`, before any phase runs. */
     tickBegin(tick: number, dt: number): void;
     /** Closes the frame opened by `tickBegin` (after onSet + `clearEvents`). */
     tickEnd(tick: number): void;