@oasys/oecs 0.3.1 → 0.5.0

package/dist/core/store/state_hash.d.ts

@@ -0,0 +1,38 @@
+import { ColumnStore } from './column_store.js';
+/** FNV-1a 32-bit offset basis (Fowler/Noll/Vo). */
+export declare const FNV1A_OFFSET_BASIS = 2166136261;
+/** FNV-1a 32-bit prime. */
+export declare const FNV1A_PRIME = 16777619;
+/** One FNV-1a round folding a single **byte** (the low 8 bits of `b`) into the
+ * running `hash`: `hash = imul((hash ^ (b & 0xff)) >>> 0, PRIME) >>> 0`. The
+ * single canonical definition of the byte step (#498) — reused by `fnv1a32`
+ * here, by the sparse-store `schemaFingerprint`, and by the server determinism
+ * byte/u32 folds, so the constants and the round live in exactly one place.
+ *
+ * Trivially inlinable (monomorphic, no allocation); the intermediate `>>> 0`s
+ * never change a later round (xor/imul see the same 32-bit pattern signed or
+ * unsigned), they just keep the value unsigned for readers. */
+export declare function fnv1aStep(hash: number, b: number): number;
+/** One FNV-1a round folding a full 32-bit **word** into `hash` — the whole word
+ * xored at once, not four byte rounds. A coarser fold than per-byte FNV-1a, but
+ * equally deterministic and ~4× cheaper, which is why `Store.stateHash` folds
+ * its columns this way (#326). This is the canonical word-step definition its
+ * cold sparse/relation folds call; its hot dense-column inner loop inlines this
+ * exact step for speed and must stay in sync. Same `>>> 0` reasoning as
+ * `fnv1aStep`. */
+export declare function fnv1aStepWord(hash: number, word: number): number;
+/** FNV-1a 32-bit hash of a byte buffer. Returned as an unsigned 32-bit
+ * `number` (i.e. always in `[0, 2^32)`).
+ *
+ * Standalone export so callers that already have a `Uint8Array` (a sliced
+ * snapshot, bytes off disk, a hot subrange) can hash without round-tripping
+ * through `ColumnStore`. */
+export declare function fnv1a32(bytes: Uint8Array): number;
+/** FNV-1a 32-bit hash of the entire SAB region — header + descriptors +
+ * column bytes. The canonical state identifier for cross-replay determinism
+ * checks (#171 plan exit criterion §6.1.7).
+ *
+ * The snapshot view is zero-copy (`snapshotColumnStore` is a view, not a
+ * copy), so this is one scan over the live SAB with no allocation. */
+export declare function columnStoreStateHash(store: ColumnStore): number;
+//# sourceMappingURL=state_hash.d.ts.map

package/dist/core/store/state_hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state_hash.d.ts","sourceRoot":"","sources":["../../../src/core/store/state_hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAC7C,2BAA2B;AAC3B,eAAO,MAAM,WAAW,WAAa,CAAC;AAEtC;;;;;;;;+DAQ+D;AAC/D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED;;;;;;kBAMkB;AAClB,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhE;AAED;;;;;4BAK4B;AAC5B,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIjD;AAED;;;;;sEAKsE;AACtE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAE/D"}

package/dist/core/store/store_regions.d.cts

@@ -0,0 +1,38 @@
+import { CreateColumnStoreOptions } from './column_store.cjs';
+/** The `StoreHeader` fields that hold a MECHANISM region's byte offset (0 ⇒
+ * region absent). Exactly the four fields a `MechanismRegionSpec` can own; the
+ * always-present `bindings_off` / `layout_descriptor_off` and the generic
+ * `region_table_off` / `region_table_count` pair are not mechanism regions in
+ * this sense and are computed directly outside the loop. */
+export type StoreRegionOffsetField = "command_ring_off" | "entity_index_off" | "event_ring_off" | "action_ring_off";
+/** Mutable accumulator for building `CreateColumnStoreOptions` field by field as
+ * each region reads itself back out of an existing SAB (`readOptions`). */
+export type MutableColumnStoreOptions = {
+    -readonly [K in keyof CreateColumnStoreOptions]: CreateColumnStoreOptions[K];
+};
+/** One engine MECHANISM region. The four closures are the per-region half of
+ * each generic pass; see the module doc for which consumer drives which.
+ *
+ * (Consumer/game regions use the separate self-contained `StoreRegionSpec` in
+ * `region_table.ts` — they carry a precomputed `bytes` + `init` and are
+ * addressed by an opaque `region_id`, not a named header field.) */
+export interface MechanismRegionSpec {
+    /** Stable name — reads in diagnostics and keeps the array self-documenting. */
+    readonly name: string;
+    /** `StoreHeader` field this region's byte offset is written to. */
+    readonly headerOff: StoreRegionOffsetField;
+    /** Byte size implied by `options` (0 ⇒ region absent, so no offset/init). */
+    readonly sizeFromOptions: (options: CreateColumnStoreOptions) => number;
+    /** Initialise the region's header at `off`. Called by `createColumnStore`
+     * only when the region is present (`off !== 0`). */
+    readonly init: (view: DataView, off: number, options: CreateColumnStoreOptions) => void;
+    /** Byte length of an already-allocated region, read from its own header.
+     * Used to snapshot exactly the live bytes before a realloc. */
+    readonly regionBytes: (view: DataView, off: number) => number;
+    /** Re-derive the `CreateColumnStoreOptions` knobs that recreate this region
+     * from an existing SAB, so a realloc lays it out identically. */
+    readonly readOptions: (view: DataView, off: number, out: MutableColumnStoreOptions) => void;
+}
+/** The engine mechanism prefix regions, in SAB byte order (see module doc). */
+export declare const STORE_PREFIX_REGIONS: readonly MechanismRegionSpec[];
+//# sourceMappingURL=store_regions.d.ts.map

package/dist/core/store/store_regions.d.ts

@@ -0,0 +1,38 @@
+import { CreateColumnStoreOptions } from './column_store.js';
+/** The `StoreHeader` fields that hold a MECHANISM region's byte offset (0 ⇒
+ * region absent). Exactly the four fields a `MechanismRegionSpec` can own; the
+ * always-present `bindings_off` / `layout_descriptor_off` and the generic
+ * `region_table_off` / `region_table_count` pair are not mechanism regions in
+ * this sense and are computed directly outside the loop. */
+export type StoreRegionOffsetField = "command_ring_off" | "entity_index_off" | "event_ring_off" | "action_ring_off";
+/** Mutable accumulator for building `CreateColumnStoreOptions` field by field as
+ * each region reads itself back out of an existing SAB (`readOptions`). */
+export type MutableColumnStoreOptions = {
+    -readonly [K in keyof CreateColumnStoreOptions]: CreateColumnStoreOptions[K];
+};
+/** One engine MECHANISM region. The four closures are the per-region half of
+ * each generic pass; see the module doc for which consumer drives which.
+ *
+ * (Consumer/game regions use the separate self-contained `StoreRegionSpec` in
+ * `region_table.ts` — they carry a precomputed `bytes` + `init` and are
+ * addressed by an opaque `region_id`, not a named header field.) */
+export interface MechanismRegionSpec {
+    /** Stable name — reads in diagnostics and keeps the array self-documenting. */
+    readonly name: string;
+    /** `StoreHeader` field this region's byte offset is written to. */
+    readonly headerOff: StoreRegionOffsetField;
+    /** Byte size implied by `options` (0 ⇒ region absent, so no offset/init). */
+    readonly sizeFromOptions: (options: CreateColumnStoreOptions) => number;
+    /** Initialise the region's header at `off`. Called by `createColumnStore`
+     * only when the region is present (`off !== 0`). */
+    readonly init: (view: DataView, off: number, options: CreateColumnStoreOptions) => void;
+    /** Byte length of an already-allocated region, read from its own header.
+     * Used to snapshot exactly the live bytes before a realloc. */
+    readonly regionBytes: (view: DataView, off: number) => number;
+    /** Re-derive the `CreateColumnStoreOptions` knobs that recreate this region
+     * from an existing SAB, so a realloc lays it out identically. */
+    readonly readOptions: (view: DataView, off: number, out: MutableColumnStoreOptions) => void;
+}
+/** The engine mechanism prefix regions, in SAB byte order (see module doc). */
+export declare const STORE_PREFIX_REGIONS: readonly MechanismRegionSpec[];
+//# sourceMappingURL=store_regions.d.ts.map

package/dist/core/store/store_regions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store_regions.d.ts","sourceRoot":"","sources":["../../../src/core/store/store_regions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAUH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE/D;;;;4DAI4D;AAC5D,MAAM,MAAM,sBAAsB,GAC/B,kBAAkB,GAClB,kBAAkB,GAClB,gBAAgB,GAChB,iBAAiB,CAAC;AAErB;2EAC2E;AAC3E,MAAM,MAAM,yBAAyB,GAAG;IACvC,CAAC,UAAU,CAAC,IAAI,MAAM,wBAAwB,GAAG,wBAAwB,CAAC,CAAC,CAAC;CAC5E,CAAC;AAEF;;;;;oEAKoE;AACpE,MAAM,WAAW,mBAAmB;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;IAC3C,6EAA6E;IAC7E,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,MAAM,CAAC;IACxE;wDACoD;IACpD,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,KAAK,IAAI,CAAC;IACxF;mEAC+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9D;qEACiE;IACjE,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,yBAAyB,KAAK,IAAI,CAAC;CAC5F;AAED,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,EAAE,SAAS,mBAAmB,EAgE9D,CAAC"}

package/dist/core/store/vendored_abi/abi.d.cts

@@ -0,0 +1,43 @@
+export declare const STORE_MAGIC = 827148627;
+export declare const SIM_ABI_VERSION = 0;
+export declare const COMPONENT_MASK_WORDS = 4;
+export declare const STORE_HEADER_BYTES = 52;
+export declare const STORE_HEADER_OFFSETS: {
+    readonly magic: 0;
+    readonly sim_abi_version: 4;
+    readonly view_stamp: 8;
+    readonly capacity: 12;
+    readonly archetype_count: 16;
+    readonly layout_descriptor_off: 20;
+    readonly command_ring_off: 24;
+    readonly action_ring_off: 28;
+    readonly entity_index_off: 32;
+    readonly event_ring_off: 36;
+    readonly region_table_off: 40;
+    readonly region_table_count: 44;
+    readonly bindings_off: 48;
+};
+export declare const REGION_TABLE_ENTRY_BYTES = 12;
+export declare const REGION_TABLE_ENTRY_OFFSETS: {
+    readonly region_id: 0;
+    readonly byte_offset: 4;
+    readonly byte_length: 8;
+};
+export declare const COLUMN_DESCRIPTOR_BYTES = 16;
+export declare const COLUMN_DESCRIPTOR_OFFSETS: {
+    readonly component_id: 0;
+    readonly field_id: 2;
+    readonly type_tag: 4;
+    readonly byte_off: 8;
+    readonly stride: 12;
+};
+export declare const ARCHETYPE_DESCRIPTOR_HEADER_BYTES = 36;
+export declare const ARCHETYPE_DESCRIPTOR_OFFSETS: {
+    readonly archetype_id: 0;
+    readonly component_mask: 4;
+    readonly row_count: 20;
+    readonly row_capacity: 24;
+    readonly column_count: 28;
+    readonly enabled_count: 32;
+};
+//# sourceMappingURL=abi.d.ts.map

package/dist/core/store/vendored_abi/abi.d.ts

@@ -0,0 +1,43 @@
+export declare const STORE_MAGIC = 827148627;
+export declare const SIM_ABI_VERSION = 0;
+export declare const COMPONENT_MASK_WORDS = 4;
+export declare const STORE_HEADER_BYTES = 52;
+export declare const STORE_HEADER_OFFSETS: {
+    readonly magic: 0;
+    readonly sim_abi_version: 4;
+    readonly view_stamp: 8;
+    readonly capacity: 12;
+    readonly archetype_count: 16;
+    readonly layout_descriptor_off: 20;
+    readonly command_ring_off: 24;
+    readonly action_ring_off: 28;
+    readonly entity_index_off: 32;
+    readonly event_ring_off: 36;
+    readonly region_table_off: 40;
+    readonly region_table_count: 44;
+    readonly bindings_off: 48;
+};
+export declare const REGION_TABLE_ENTRY_BYTES = 12;
+export declare const REGION_TABLE_ENTRY_OFFSETS: {
+    readonly region_id: 0;
+    readonly byte_offset: 4;
+    readonly byte_length: 8;
+};
+export declare const COLUMN_DESCRIPTOR_BYTES = 16;
+export declare const COLUMN_DESCRIPTOR_OFFSETS: {
+    readonly component_id: 0;
+    readonly field_id: 2;
+    readonly type_tag: 4;
+    readonly byte_off: 8;
+    readonly stride: 12;
+};
+export declare const ARCHETYPE_DESCRIPTOR_HEADER_BYTES = 36;
+export declare const ARCHETYPE_DESCRIPTOR_OFFSETS: {
+    readonly archetype_id: 0;
+    readonly component_mask: 4;
+    readonly row_count: 20;
+    readonly row_capacity: 24;
+    readonly column_count: 28;
+    readonly enabled_count: 32;
+};
+//# sourceMappingURL=abi.d.ts.map

package/dist/core/store/vendored_abi/abi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi.d.ts","sourceRoot":"","sources":["../../../../src/core/store/vendored_abi/abi.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,WAAW,YAAa,CAAC;AACtC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;CAcvB,CAAC;AAEX,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C,eAAO,MAAM,0BAA0B;;;;CAI7B,CAAC;AAEX,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,eAAO,MAAM,yBAAyB;;;;;;CAM5B,CAAC;AAEX,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,eAAO,MAAM,4BAA4B;;;;;;;CAO/B,CAAC"}

package/dist/dev_flag.d.cts

@@ -0,0 +1,17 @@
+/**
+ * The dev-mode flag, resolved once at module load.
+ *
+ * Bundled (npm) builds: Vite's `define` replaces the bare `__DEV__` global
+ * below with a literal (`false` for `vite build`, `true` for dev/test), so
+ * `DEV` constant-folds and dev-only branches are eliminated.
+ *
+ * Raw-source (JSR/Deno) consumers: no bundler defines `__DEV__`, the `typeof`
+ * probe falls through, and `DEV` defaults to `true` (all dev checks on). To
+ * opt out, set `globalThis.__DEV__ = false` before the first import of this
+ * package.
+ */
+declare global {
+    var __DEV__: boolean;
+}
+export declare const DEV: boolean;
+//# sourceMappingURL=dev_flag.d.ts.map

package/dist/dev_flag.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The dev-mode flag, resolved once at module load.
+ *
+ * Bundled (npm) builds: Vite's `define` replaces the bare `__DEV__` global
+ * below with a literal (`false` for `vite build`, `true` for dev/test), so
+ * `DEV` constant-folds and dev-only branches are eliminated.
+ *
+ * Raw-source (JSR/Deno) consumers: no bundler defines `__DEV__`, the `typeof`
+ * probe falls through, and `DEV` defaults to `true` (all dev checks on). To
+ * opt out, set `globalThis.__DEV__ = false` before the first import of this
+ * package.
+ */
+declare global {
+    var __DEV__: boolean;
+}
+export declare const DEV: boolean;
+//# sourceMappingURL=dev_flag.d.ts.map

package/dist/dev_flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev_flag.d.ts","sourceRoot":"","sources":["../src/dev_flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,CAAC,MAAM,CAAC;IAEd,IAAI,OAAO,EAAE,OAAO,CAAC;CACrB;AAED,eAAO,MAAM,GAAG,EAAE,OAAyD,CAAC"}

package/dist/extensions/editor/editor.d.cts

@@ -0,0 +1,170 @@
+import { ComponentDef, ComponentHandle, ComponentSchema, EntityID, CompleteFieldValues, HostCommand, HostCommandQueue, SpawnEntries } from '../../core/ecs/index.cjs';
+/**
+ * Reads the committed value of one `(entity, component, field)` slot — the editor
+ * uses it to seed a `setField` inverse with the value the edit replaced. Wire it
+ * to the reactive read channel (e.g. a `reactiveMap`/`reactiveStruct` projection)
+ * or to `ecs.getField`; `undefined` for an unknown slot falls back to `0`.
+ */
+export type FieldReader = (eid: EntityID, def: ComponentDef, field: string) => number | undefined;
+/**
+ * A reified, undoable unit of editor work: the `forward` commands and their
+ * `inverse`, both plain `HostCommand` data on the one bus. The arrays are mutable
+ * internally (the spawn/despawn id finalizers patch a slot at apply time) but the
+ * type handed back from {@link Editor.transaction} is read-only.
+ */
+export interface EditorTransaction {
+    readonly forward: readonly HostCommand[];
+    readonly inverse: readonly HostCommand[];
+}
+/**
+ * Accumulates the `forward`/`inverse` commands for ONE transaction. Each method
+ * appends a forward command and its inverse, computing the inverse from the
+ * shadow / read channel where needed. Spawn and despawn install id-finalizers
+ * (via `HostCommand.onSpawned`) that patch the apply-time id into the right slot.
+ *
+ * Obtained from {@link Editor.transaction}; not constructed directly.
+ */
+export declare class TransactionBuilder {
+    private readonly readField;
+    private readonly shadow;
+    /** Values staged by THIS build, layered over the editor's shared shadow. Kept
+     * transaction-local so an aborted build (the callback throws before commit)
+     * leaves the shared shadow untouched — a phantom staged value would poison
+     * `pendingField` and seed the NEXT edit's inverse with a value the world never
+     * held. The one merge point into the shared shadow is commit's `applyShadow`. */
+    private readonly staged;
+    /** @internal */
+    constructor(readField: FieldReader, shadow: Map<string, number>);
+    private get _txn();
+    /**
+     * Spawn an entity carrying `components`. Inverse: despawn the created entity,
+     * finalized once the spawn applies (the id only exists post-flush). `onSpawned`
+     * also forwards the new id to the caller. The finalizer re-fires on redo, so the
+     * inverse tracks the current id.
+     */
+    spawn<Defs extends readonly ComponentDef[]>(components: SpawnEntries<Defs>, onSpawned?: (eid: EntityID) => void): this;
+    /**
+     * Despawn `eid`. Inverse: respawn from `restore` (the components+values to
+     * recreate — read them from the channel before despawning). Undo respawns the
+     * DATA, not the identity: the new entity gets a fresh id, and the respawn's
+     * `onSpawned` rewrites this despawn's target so redo removes the respawned
+     * entity rather than the dead original.
+     */
+    despawn<Defs extends readonly ComponentDef[]>(eid: EntityID, restore: SpawnEntries<Defs>): this;
+    /**
+     * Set `field` of `def` on `eid` to `value`. Inverse: set it back to the value
+     * this edit replaced — read from the staged overlay / shadow (so stacked edits,
+     * within one build or before a commit, invert correctly) or, failing that, the
+     * read channel (`0` if unknown).
+     */
+    setField<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, field: string & keyof S, value: number): this;
+    /** Add `def` (with complete `values`) to `eid`. Inverse: remove it. */
+    addComponent<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, values: CompleteFieldValues<S>): this;
+    /**
+     * Remove `def` from `eid`. Inverse: re-add it from `restore` (the field values
+     * to recreate — read them from the channel before removing).
+     */
+    removeComponent<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, restore: CompleteFieldValues<S>): this;
+    /** Disable `eid`. Inverse: enable it. */
+    disable(eid: EntityID): this;
+    /** Enable `eid`. Inverse: disable it. */
+    enable(eid: EntityID): this;
+}
+/**
+ * The editor's undo/redo manager over a {@link HostCommandQueue}. Each action is a
+ * reified {@link EditorTransaction} pushed onto the undo stack; `undo()`/`redo()`
+ * enqueue its inverse/forward on the SAME bus. The single-action methods
+ * (`spawn`, `setField`, …) are sugar for one-command transactions; `transaction`
+ * groups several into one undo entry.
+ *
+ * Construct with the queue and a {@link FieldReader} for the committed read
+ * channel (used to seed `setField` inverses).
+ */
+export declare class Editor {
+    private readonly queue;
+    private readonly readField;
+    private readonly undoStack;
+    private readonly redoStack;
+    /** onChange subscribers — see {@link onChange}. */
+    private readonly listeners;
+    /** Per-`(entity, component, field)` shadow of edited values, for inverse correctness. */
+    private readonly shadow;
+    constructor(queue: HostCommandQueue, readField: FieldReader);
+    /**
+     * Group several actions into ONE undo entry. Build them on the passed
+     * {@link TransactionBuilder}; the whole group commits (enqueues its forward
+     * commands) and lands on the undo stack atomically, clearing the redo stack.
+     */
+    transaction(build: (tx: TransactionBuilder) => void): EditorTransaction;
+    /** Spawn `components` as its own undo entry. `onSpawned` reports the new id. */
+    spawn<Defs extends readonly ComponentDef[]>(components: SpawnEntries<Defs>, onSpawned?: (eid: EntityID) => void): EditorTransaction;
+    /** Despawn `eid` as its own undo entry; `restore` recreates it on undo. */
+    despawn<Defs extends readonly ComponentDef[]>(eid: EntityID, restore: SpawnEntries<Defs>): EditorTransaction;
+    /** Set one field as its own undo entry. */
+    setField<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, field: string & keyof S, value: number): EditorTransaction;
+    /** Add a component as its own undo entry. */
+    addComponent<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, values: CompleteFieldValues<S>): EditorTransaction;
+    /** Remove a component as its own undo entry; `restore` re-adds it on undo. */
+    removeComponent<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, restore: CompleteFieldValues<S>): EditorTransaction;
+    /** Disable `eid` as its own undo entry. */
+    disable(eid: EntityID): EditorTransaction;
+    /** Enable `eid` as its own undo entry. */
+    enable(eid: EntityID): EditorTransaction;
+    /**
+     * Undo the most recent transaction: enqueue its inverse commands (in reverse
+     * order — a group unwinds last-action-first) on the bus and move it to the redo
+     * stack. Returns `false` if the undo stack is empty.
+     */
+    undo(): boolean;
+    /**
+     * Redo the most recently undone transaction: re-enqueue its forward commands on
+     * the bus and move it back to the undo stack. Returns `false` if the redo stack
+     * is empty.
+     */
+    redo(): boolean;
+    /** Drop both stacks (e.g. on load). Does not touch the world. */
+    clear(): void;
+    /** Current stack depths — for an "Undo (3)" / "Redo" affordance. */
+    depths(): {
+        undo: number;
+        redo: number;
+    };
+    /** `true` when `undo()` would do something — allocation-free (M10). */
+    get canUndo(): boolean;
+    /** `true` when `redo()` would do something — allocation-free (M10). */
+    get canRedo(): boolean;
+    /**
+     * Subscribe to undo/redo-stack changes: fires after every commit, undo,
+     * redo, and clear — the push signal an "Undo (3)" affordance needs instead
+     * of polling `depths()` per frame (M10). Returns an unsubscribe function.
+     * Callbacks run synchronously in subscription order; read `canUndo` /
+     * `canRedo` / `depths()` inside.
+     */
+    onChange(cb: () => void): () => void;
+    private notify;
+    /** Read one committed `(entity, component, field)` slot through the reader
+     * this editor was constructed with — the default read for `fieldHandle`
+     * when no channel thunk is supplied (M11). */
+    committedField(eid: EntityID, def: ComponentDef, field: string): number | undefined;
+    /**
+     * The pending value the editor believes for a field that the committed read
+     * channel has NOT caught up to yet (the shadow), or `undefined` if none. Lets an
+     * inspector echo an edit between the `set` and the tick that commits it.
+     *
+     * Self-resolving: once the read channel reports the shadowed value (the edit
+     * landed) — or reports `undefined` (the slot is gone: entity despawned or
+     * component removed) — the entry is dropped and this returns `undefined`, so
+     * `pending` does not outlive its set→commit window and shadow a later external
+     * write, nor a dead slot's lifetime. The one
+     * residual: if an external write changes the field to a *different* value within
+     * the same window before this is next consulted, `pending` can read stale until
+     * the next edit to the slot. `value` (the read channel) is always the source of
+     * truth; `pending` is only the optimistic bridge.
+     */
+    pendingField(eid: EntityID, def: ComponentHandle, field: string): number | undefined;
+    /** Enqueue forward commands, record the transaction, clear redo, sync shadow. */
+    private commit;
+    /** Keep the setField shadow in step with the commands just enqueued. */
+    private applyShadow;
+}
+//# sourceMappingURL=editor.d.ts.map

package/dist/extensions/editor/editor.d.ts

@@ -0,0 +1,170 @@
+import { ComponentDef, ComponentHandle, ComponentSchema, EntityID, CompleteFieldValues, HostCommand, HostCommandQueue, SpawnEntries } from '../../core/ecs/index.js';
+/**
+ * Reads the committed value of one `(entity, component, field)` slot — the editor
+ * uses it to seed a `setField` inverse with the value the edit replaced. Wire it
+ * to the reactive read channel (e.g. a `reactiveMap`/`reactiveStruct` projection)
+ * or to `ecs.getField`; `undefined` for an unknown slot falls back to `0`.
+ */
+export type FieldReader = (eid: EntityID, def: ComponentDef, field: string) => number | undefined;
+/**
+ * A reified, undoable unit of editor work: the `forward` commands and their
+ * `inverse`, both plain `HostCommand` data on the one bus. The arrays are mutable
+ * internally (the spawn/despawn id finalizers patch a slot at apply time) but the
+ * type handed back from {@link Editor.transaction} is read-only.
+ */
+export interface EditorTransaction {
+    readonly forward: readonly HostCommand[];
+    readonly inverse: readonly HostCommand[];
+}
+/**
+ * Accumulates the `forward`/`inverse` commands for ONE transaction. Each method
+ * appends a forward command and its inverse, computing the inverse from the
+ * shadow / read channel where needed. Spawn and despawn install id-finalizers
+ * (via `HostCommand.onSpawned`) that patch the apply-time id into the right slot.
+ *
+ * Obtained from {@link Editor.transaction}; not constructed directly.
+ */
+export declare class TransactionBuilder {
+    private readonly readField;
+    private readonly shadow;
+    /** Values staged by THIS build, layered over the editor's shared shadow. Kept
+     * transaction-local so an aborted build (the callback throws before commit)
+     * leaves the shared shadow untouched — a phantom staged value would poison
+     * `pendingField` and seed the NEXT edit's inverse with a value the world never
+     * held. The one merge point into the shared shadow is commit's `applyShadow`. */
+    private readonly staged;
+    /** @internal */
+    constructor(readField: FieldReader, shadow: Map<string, number>);
+    private get _txn();
+    /**
+     * Spawn an entity carrying `components`. Inverse: despawn the created entity,
+     * finalized once the spawn applies (the id only exists post-flush). `onSpawned`
+     * also forwards the new id to the caller. The finalizer re-fires on redo, so the
+     * inverse tracks the current id.
+     */
+    spawn<Defs extends readonly ComponentDef[]>(components: SpawnEntries<Defs>, onSpawned?: (eid: EntityID) => void): this;
+    /**
+     * Despawn `eid`. Inverse: respawn from `restore` (the components+values to
+     * recreate — read them from the channel before despawning). Undo respawns the
+     * DATA, not the identity: the new entity gets a fresh id, and the respawn's
+     * `onSpawned` rewrites this despawn's target so redo removes the respawned
+     * entity rather than the dead original.
+     */
+    despawn<Defs extends readonly ComponentDef[]>(eid: EntityID, restore: SpawnEntries<Defs>): this;
+    /**
+     * Set `field` of `def` on `eid` to `value`. Inverse: set it back to the value
+     * this edit replaced — read from the staged overlay / shadow (so stacked edits,
+     * within one build or before a commit, invert correctly) or, failing that, the
+     * read channel (`0` if unknown).
+     */
+    setField<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, field: string & keyof S, value: number): this;
+    /** Add `def` (with complete `values`) to `eid`. Inverse: remove it. */
+    addComponent<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, values: CompleteFieldValues<S>): this;
+    /**
+     * Remove `def` from `eid`. Inverse: re-add it from `restore` (the field values
+     * to recreate — read them from the channel before removing).
+     */
+    removeComponent<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, restore: CompleteFieldValues<S>): this;
+    /** Disable `eid`. Inverse: enable it. */
+    disable(eid: EntityID): this;
+    /** Enable `eid`. Inverse: disable it. */
+    enable(eid: EntityID): this;
+}
+/**
+ * The editor's undo/redo manager over a {@link HostCommandQueue}. Each action is a
+ * reified {@link EditorTransaction} pushed onto the undo stack; `undo()`/`redo()`
+ * enqueue its inverse/forward on the SAME bus. The single-action methods
+ * (`spawn`, `setField`, …) are sugar for one-command transactions; `transaction`
+ * groups several into one undo entry.
+ *
+ * Construct with the queue and a {@link FieldReader} for the committed read
+ * channel (used to seed `setField` inverses).
+ */
+export declare class Editor {
+    private readonly queue;
+    private readonly readField;
+    private readonly undoStack;
+    private readonly redoStack;
+    /** onChange subscribers — see {@link onChange}. */
+    private readonly listeners;
+    /** Per-`(entity, component, field)` shadow of edited values, for inverse correctness. */
+    private readonly shadow;
+    constructor(queue: HostCommandQueue, readField: FieldReader);
+    /**
+     * Group several actions into ONE undo entry. Build them on the passed
+     * {@link TransactionBuilder}; the whole group commits (enqueues its forward
+     * commands) and lands on the undo stack atomically, clearing the redo stack.
+     */
+    transaction(build: (tx: TransactionBuilder) => void): EditorTransaction;
+    /** Spawn `components` as its own undo entry. `onSpawned` reports the new id. */
+    spawn<Defs extends readonly ComponentDef[]>(components: SpawnEntries<Defs>, onSpawned?: (eid: EntityID) => void): EditorTransaction;
+    /** Despawn `eid` as its own undo entry; `restore` recreates it on undo. */
+    despawn<Defs extends readonly ComponentDef[]>(eid: EntityID, restore: SpawnEntries<Defs>): EditorTransaction;
+    /** Set one field as its own undo entry. */
+    setField<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, field: string & keyof S, value: number): EditorTransaction;
+    /** Add a component as its own undo entry. */
+    addComponent<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, values: CompleteFieldValues<S>): EditorTransaction;
+    /** Remove a component as its own undo entry; `restore` re-adds it on undo. */
+    removeComponent<S extends ComponentSchema>(eid: EntityID, def: ComponentDef<S>, restore: CompleteFieldValues<S>): EditorTransaction;
+    /** Disable `eid` as its own undo entry. */
+    disable(eid: EntityID): EditorTransaction;
+    /** Enable `eid` as its own undo entry. */
+    enable(eid: EntityID): EditorTransaction;
+    /**
+     * Undo the most recent transaction: enqueue its inverse commands (in reverse
+     * order — a group unwinds last-action-first) on the bus and move it to the redo
+     * stack. Returns `false` if the undo stack is empty.
+     */
+    undo(): boolean;
+    /**
+     * Redo the most recently undone transaction: re-enqueue its forward commands on
+     * the bus and move it back to the undo stack. Returns `false` if the redo stack
+     * is empty.
+     */
+    redo(): boolean;
+    /** Drop both stacks (e.g. on load). Does not touch the world. */
+    clear(): void;
+    /** Current stack depths — for an "Undo (3)" / "Redo" affordance. */
+    depths(): {
+        undo: number;
+        redo: number;
+    };
+    /** `true` when `undo()` would do something — allocation-free (M10). */
+    get canUndo(): boolean;
+    /** `true` when `redo()` would do something — allocation-free (M10). */
+    get canRedo(): boolean;
+    /**
+     * Subscribe to undo/redo-stack changes: fires after every commit, undo,
+     * redo, and clear — the push signal an "Undo (3)" affordance needs instead
+     * of polling `depths()` per frame (M10). Returns an unsubscribe function.
+     * Callbacks run synchronously in subscription order; read `canUndo` /
+     * `canRedo` / `depths()` inside.
+     */
+    onChange(cb: () => void): () => void;
+    private notify;
+    /** Read one committed `(entity, component, field)` slot through the reader
+     * this editor was constructed with — the default read for `fieldHandle`
+     * when no channel thunk is supplied (M11). */
+    committedField(eid: EntityID, def: ComponentDef, field: string): number | undefined;
+    /**
+     * The pending value the editor believes for a field that the committed read
+     * channel has NOT caught up to yet (the shadow), or `undefined` if none. Lets an
+     * inspector echo an edit between the `set` and the tick that commits it.
+     *
+     * Self-resolving: once the read channel reports the shadowed value (the edit
+     * landed) — or reports `undefined` (the slot is gone: entity despawned or
+     * component removed) — the entry is dropped and this returns `undefined`, so
+     * `pending` does not outlive its set→commit window and shadow a later external
+     * write, nor a dead slot's lifetime. The one
+     * residual: if an external write changes the field to a *different* value within
+     * the same window before this is next consulted, `pending` can read stale until
+     * the next edit to the slot. `value` (the read channel) is always the source of
+     * truth; `pending` is only the optimistic bridge.
+     */
+    pendingField(eid: EntityID, def: ComponentHandle, field: string): number | undefined;
+    /** Enqueue forward commands, record the transaction, clear redo, sync shadow. */
+    private commit;
+    /** Keep the setField shadow in step with the commands just enqueued. */
+    private applyShadow;
+}
+//# sourceMappingURL=editor.d.ts.map

package/dist/extensions/editor/editor.d.ts.map

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

package/dist/extensions/editor/field_handle.d.cts

@@ -0,0 +1,40 @@
+import { ComponentDef, ComponentSchema, EntityID } from '../../core/ecs/index.cjs';
+import { Editor } from './editor.cjs';
+/**
+ * A two-way handle on one `(entity, component, field)` slot. `value` reads the
+ * reactive channel (tracked, if read in a tracking scope); `set` enqueues an
+ * undoable `setField` command via the editor.
+ */
+export interface FieldHandle {
+    /**
+     * The field's current value through the reactive read channel — `undefined`
+     * until the channel has it (e.g. before the spawn's first commit). Read inside
+     * a tracking scope to subscribe to the channel; the value reflects the last
+     * COMMITTED tick, so a fresh `set` shows up on the next tick.
+     */
+    readonly value: number | undefined;
+    /** Enqueue an undoable `setField` for this slot; applied at the next tick. */
+    set(value: number): void;
+    /**
+     * The editor's pending (not-yet-committed) value for this slot, or `undefined`
+     * if none — a NON-reactive read of the editor shadow, for an optimistic echo
+     * between the `set` and its commit. Self-resolves to `undefined` once the read
+     * channel catches up, so it does not outlive the edit. Not a substitute for
+     * `value` in a tracking scope (it does not subscribe); `value` is the source of
+     * truth.
+     */
+    readonly pending: number | undefined;
+}
+/**
+ * Build a {@link FieldHandle} for one `(eid, def, field)` slot. `read` is the
+ * tracked read of the reactive channel for this field (e.g.
+ * `() => sync.map.get(eid)?.x`); `set` routes through `editor.setField`, so the
+ * edit is queued, batched, and undoable.
+ *
+ * `read` is optional (M11): omitted, the handle reads through the editor's own
+ * committed-channel reader (`editor.committedField`). That default is correct
+ * but NOT reactive — supply the channel thunk when the handle's `value` must
+ * subscribe inside a tracking scope.
+ */
+export declare function fieldHandle<S extends ComponentSchema>(editor: Editor, eid: EntityID, def: ComponentDef<S>, field: string & keyof S, read?: () => number | undefined): FieldHandle;
+//# sourceMappingURL=field_handle.d.ts.map