@oasys/oecs 0.4.0 → 0.5.0

package/dist/extensions/editor/index.js

@@ -1,72 +1,68 @@
-function o(i, t, n) {
-  return `${i}:${t.id}:${n}`;
+function a(r, t, e) {
+  return `${r}:${t.id}:${e}`;
 }
-class d {
-  /** @internal */
-  constructor(t, n) {
-    this.readField = t, this.shadow = n;
-  }
+const d = /* @__PURE__ */ new WeakMap();
+class h {
   /** @internal */
-  _txn = { forward: [], inverse: [] };
-  /**
-   * 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(t, n) {
-    const e = {
+  constructor(t, e) {
+    this.readField = t, this.shadow = e, d.set(this, { forward: [], inverse: [] });
+  }
+  /** 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`. */
+  staged = /* @__PURE__ */ new Map();
+  get _txn() {
+    return d.get(this);
+  }
+  spawn(t, e) {
+    const n = {
       kind: "despawn",
       eid: 0
     };
-    return this._txn.inverse.push(e), this._txn.forward.push({
+    return this._txn.inverse.push(n), this._txn.forward.push({
       kind: "spawn",
       components: t,
       onSpawned: (s) => {
-        e.eid = s, n?.(s);
+        n.eid = s, e?.(s);
       }
     }), 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(t, n) {
-    const e = { kind: "despawn", eid: t };
-    return this._txn.forward.push(e), this._txn.inverse.push({
+  despawn(t, e) {
+    const n = { kind: "despawn", eid: t };
+    return this._txn.forward.push(n), this._txn.inverse.push({
       kind: "spawn",
-      components: n,
+      components: e,
       onSpawned: (s) => {
-        e.eid = s;
+        n.eid = s;
       }
     }), this;
   }
   /**
    * Set `field` of `def` on `eid` to `value`. Inverse: set it back to the value
-   * this edit replaced — read from the shadow (so stacked edits before a commit
-   * invert correctly) or, failing that, the read channel (`0` if unknown).
+   * 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(t, n, e, s) {
-    const r = o(t, n, e), a = this.shadow.get(r) ?? this.readField(t, n, e) ?? 0;
-    return this.shadow.set(r, s), this._txn.forward.push({ kind: "set_field", eid: t, def: n, field: e, value: s }), this._txn.inverse.push({ kind: "set_field", eid: t, def: n, field: e, value: a }), this;
+  setField(t, e, n, s) {
+    const i = a(t, e, n), o = this.staged.get(i) ?? this.shadow.get(i) ?? this.readField(t, e, n) ?? 0;
+    return this.staged.set(i, s), this._txn.forward.push({ kind: "set_field", eid: t, def: e, field: n, value: s }), this._txn.inverse.push({ kind: "set_field", eid: t, def: e, field: n, value: o }), this;
   }
   /** Add `def` (with complete `values`) to `eid`. Inverse: remove it. */
-  addComponent(t, n, e) {
-    return this._txn.forward.push({ kind: "add_component", eid: t, def: n, values: e }), this._txn.inverse.push({ kind: "remove_component", eid: t, def: n }), this;
+  addComponent(t, e, n) {
+    return this._txn.forward.push({ kind: "add_component", eid: t, def: e, values: n }), this._txn.inverse.push({ kind: "remove_component", eid: t, def: e }), this;
   }
   /**
    * Remove `def` from `eid`. Inverse: re-add it from `restore` (the field values
    * to recreate — read them from the channel before removing).
    */
-  removeComponent(t, n, e) {
-    return this._txn.forward.push({ kind: "remove_component", eid: t, def: n }), this._txn.inverse.push({
+  removeComponent(t, e, n) {
+    return this._txn.forward.push({ kind: "remove_component", eid: t, def: e }), this._txn.inverse.push({
       kind: "add_component",
       eid: t,
-      def: n,
-      values: e
+      def: e,
+      values: n
     }), this;
   }
   /** Disable `eid`. Inverse: enable it. */
@@ -78,12 +74,14 @@ class d {
     return this._txn.forward.push({ kind: "enable", eid: t }), this._txn.inverse.push({ kind: "disable", eid: t }), this;
   }
 }
-class h {
-  constructor(t, n) {
-    this.queue = t, this.readField = n;
+class u {
+  constructor(t, e) {
+    this.queue = t, this.readField = e;
   }
   undoStack = [];
   redoStack = [];
+  /** onChange subscribers — see {@link onChange}. */
+  listeners = [];
   /** Per-`(entity, component, field)` shadow of edited values, for inverse correctness. */
   shadow = /* @__PURE__ */ new Map();
   /**
@@ -92,36 +90,34 @@ class h {
    * commands) and lands on the undo stack atomically, clearing the redo stack.
    */
   transaction(t) {
-    const n = new d(this.readField, this.shadow);
-    return t(n), this.commit(n._txn);
+    const e = new h(this.readField, this.shadow);
+    return t(e), this.commit(d.get(e));
   }
-  /** Spawn `components` as its own undo entry. `onSpawned` reports the new id. */
-  spawn(t, n) {
-    return this.transaction((e) => e.spawn(t, n));
+  spawn(t, e) {
+    return this.transaction((n) => n.spawn(t, e));
   }
-  /** Despawn `eid` as its own undo entry; `restore` recreates it on undo. */
-  despawn(t, n) {
-    return this.transaction((e) => e.despawn(t, n));
+  despawn(t, e) {
+    return this.transaction((n) => n.despawn(t, e));
   }
   /** Set one field as its own undo entry. */
-  setField(t, n, e, s) {
-    return this.transaction((r) => r.setField(t, n, e, s));
+  setField(t, e, n, s) {
+    return this.transaction((i) => i.setField(t, e, n, s));
   }
   /** Add a component as its own undo entry. */
-  addComponent(t, n, e) {
-    return this.transaction((s) => s.addComponent(t, n, e));
+  addComponent(t, e, n) {
+    return this.transaction((s) => s.addComponent(t, e, n));
   }
   /** Remove a component as its own undo entry; `restore` re-adds it on undo. */
-  removeComponent(t, n, e) {
-    return this.transaction((s) => s.removeComponent(t, n, e));
+  removeComponent(t, e, n) {
+    return this.transaction((s) => s.removeComponent(t, e, n));
   }
   /** Disable `eid` as its own undo entry. */
   disable(t) {
-    return this.transaction((n) => n.disable(t));
+    return this.transaction((e) => e.disable(t));
   }
   /** Enable `eid` as its own undo entry. */
   enable(t) {
-    return this.transaction((n) => n.enable(t));
+    return this.transaction((e) => e.enable(t));
   }
   /**
    * Undo the most recent transaction: enqueue its inverse commands (in reverse
@@ -131,9 +127,9 @@ class h {
   undo() {
     const t = this.undoStack.pop();
     if (t === void 0) return !1;
-    const n = t.inverse.slice().reverse();
-    for (const e of n) this.queue.push(e);
-    return this.applyShadow(n), this.redoStack.push(t), !0;
+    const e = t.inverse.slice().reverse();
+    for (const n of e) this.queue.push(n);
+    return this.applyShadow(e), this.redoStack.push(t), this.notify(), !0;
   }
   /**
    * Redo the most recently undone transaction: re-enqueue its forward commands on
@@ -143,67 +139,99 @@ class h {
   redo() {
     const t = this.redoStack.pop();
     if (t === void 0) return !1;
-    for (const n of t.forward) this.queue.push(n);
-    return this.applyShadow(t.forward), this.undoStack.push(t), !0;
+    for (const e of t.forward) this.queue.push(e);
+    return this.applyShadow(t.forward), this.undoStack.push(t), this.notify(), !0;
   }
   /** Drop both stacks (e.g. on load). Does not touch the world. */
   clear() {
-    this.undoStack.length = 0, this.redoStack.length = 0, this.shadow.clear();
+    this.undoStack.length = 0, this.redoStack.length = 0, this.shadow.clear(), this.notify();
   }
   /** Current stack depths — for an "Undo (3)" / "Redo" affordance. */
   depths() {
     return { undo: this.undoStack.length, redo: this.redoStack.length };
   }
+  /** `true` when `undo()` would do something — allocation-free (M10). */
+  get canUndo() {
+    return this.undoStack.length > 0;
+  }
+  /** `true` when `redo()` would do something — allocation-free (M10). */
+  get canRedo() {
+    return this.redoStack.length > 0;
+  }
+  /**
+   * 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(t) {
+    return this.listeners.push(t), () => {
+      const e = this.listeners.indexOf(t);
+      e !== -1 && this.listeners.splice(e, 1);
+    };
+  }
+  notify() {
+    for (const t of this.listeners.slice()) t();
+  }
+  /** 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(t, e, n) {
+    return this.readField(t, e, n);
+  }
   /**
    * 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), the entry is dropped and this returns `undefined` — so `pending` does
-   * not outlive its set→commit window and shadow a later external write. The one
+   * 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(t, n, e) {
-    const s = o(t, n, e), r = this.shadow.get(s);
-    if (r !== void 0) {
-      if (this.readField(t, n, e) === r) {
-        this.shadow.delete(s);
-        return;
-      }
-      return r;
+  pendingField(t, e, n) {
+    const s = a(t, e, n), i = this.shadow.get(s);
+    if (i === void 0) return;
+    const o = this.readField(t, e, n);
+    if (o === i || o === void 0) {
+      this.shadow.delete(s);
+      return;
     }
+    return i;
   }
   /** Enqueue forward commands, record the transaction, clear redo, sync shadow. */
   commit(t) {
     if (t.forward.length === 0) return t;
-    for (const n of t.forward) this.queue.push(n);
-    return this.applyShadow(t.forward), this.undoStack.push(t), this.redoStack.length = 0, t;
+    for (const e of t.forward) this.queue.push(e);
+    return this.applyShadow(t.forward), this.undoStack.push(t), this.redoStack.length = 0, this.notify(), t;
   }
   /** Keep the setField shadow in step with the commands just enqueued. */
   applyShadow(t) {
-    for (const n of t)
-      n.kind === "set_field" && this.shadow.set(o(n.eid, n.def, n.field), n.value);
+    for (const e of t)
+      e.kind === "set_field" && this.shadow.set(a(e.eid, e.def, e.field), e.value);
   }
 }
-function u(i, t, n, e, s) {
+function c(r, t, e, n, s) {
   return {
     get value() {
-      return s();
+      return s !== void 0 ? s() : r.committedField(t, e, n);
     },
-    set(r) {
-      i.setField(t, n, e, r);
+    set(i) {
+      r.setField(t, e, n, i);
     },
     get pending() {
-      return i.pendingField(t, n, e);
+      return r.pendingField(t, e, n);
     }
   };
 }
 export {
-  h as Editor,
-  d as TransactionBuilder,
-  u as fieldHandle
+  u as Editor,
+  h as TransactionBuilder,
+  c as fieldHandle
 };

package/dist/extensions/reactive/ecs_sync.d.cts

@@ -0,0 +1,214 @@
+import { ReactiveArray, ReactiveMap, StructSetters, StructEq } from '../../reactive/index.cjs';
+import { ComponentDef, ComponentSchema, ECS, EntityID, SystemAccessDeclaration } from '../../core/ecs/index.cjs';
+import { shallow } from '../../reactive/shallow.cjs';
+export { shallow };
+/**
+ * A read cursor over one entity's single-component state, handed to a single-
+ * component `Projection`. `field` is column-backed under "column" grain
+ * (sequential), random-access (`getField`) under "entity" grain.
+ *
+ * Lifetime: the cursor is a reused, mutable singleton valid ONLY during the
+ * synchronous `project` call for the current row. Read what you need and return —
+ * never capture `row` (or stash its `field` reads keyed off a later closure): the
+ * next row/tick mutates it in place, so a captured cursor reads stale data.
+ */
+export interface RowReader<S extends ComponentSchema> {
+    /** The current entity (the row being projected). */
+    readonly eid: EntityID;
+    /** Read a field of the synced component for the current row. */
+    field<K extends string & keyof S>(name: K): number;
+}
+/**
+ * A read cursor over a JOINED entity (it carries every component in the join), for
+ * a `JoinProjection`. `field(def, name)` reads any field of any joined component
+ * for the current entity (random-access; the join subscribes to all of them so the
+ * read can never go stale).
+ *
+ * Lifetime: like `RowReader`, a reused mutable singleton valid ONLY during the
+ * synchronous `project` call — never capture it; the next dispatch mutates it.
+ */
+export interface JoinReader<Schemas extends readonly ComponentSchema[] = readonly ComponentSchema[]> {
+    /** The current entity (it has all joined components). */
+    readonly eid: EntityID;
+    /** Read a field of one joined component for the current entity. `def` is
+     * constrained to the join's own component set — reading a def outside the
+     * join is the stale-read footgun the module header warns about (its changes
+     * aren't subscribed), so it's a compile error. */
+    field<S extends Schemas[number], K extends string & keyof S>(def: ComponentDef<S>, name: K): number;
+}
+/** Map one single-component row to the value a UI cell reads. */
+export type Projection<S extends ComponentSchema, V> = (row: RowReader<S>) => V;
+/** Map one joined entity to the value a UI cell reads. */
+export type JoinProjection<V, Schemas extends readonly ComponentSchema[] = readonly ComponentSchema[]> = (row: JoinReader<Schemas>) => V;
+/** Per-component dirty grain. See the module header for the measured crossover. */
+export type SyncGrain = "entity" | "column";
+export interface EcsMapSyncOptions<V> {
+    /** Dirty grain (default `"entity"`). Use `"column"` for high-churn components. */
+    grain?: SyncGrain;
+    /**
+     * Value equality for the map's per-key no-op skip (default `Object.is`). Pass
+     * `shallow` for object projections, or a content comparator. A fresh object
+     * every tick under the default reference eq wakes the row every frame.
+     */
+    eq?: (a: V, b: V) => boolean;
+    /**
+     * Access surface the projection touches, merged over the synced components'
+     * `reads`. `DEV` access-checks the observer callbacks exactly like a system.
+     */
+    access?: Partial<SystemAccessDeclaration>;
+    /**
+     * Replay current matches on registration (default `true`), so a bridge attached
+     * to an already-populated world seeds the map with present state instead of
+     * waking only on the next change. flecs `yieldExisting`.
+     */
+    seedExisting?: boolean;
+}
+export interface EcsMapSync<V> {
+    /** The live channel: a reader of key `eid` subscribes to that entity alone. */
+    readonly map: ReactiveMap<EntityID, V>;
+    /** Unregister the observer(s) and stop publishing. Safe to call more than once. */
+    dispose(): void;
+}
+/**
+ * Sync ONE component's change detection into a `reactiveMap`, keyed by `EntityID`.
+ * A value change publishes the changed rows; a spawn inserts a row and a despawn
+ * deletes it. Returns the map + a disposer. Drive with `batchedUpdate(world, dt)`.
+ *
+ * To read more than one component per row, use `syncJoinToMap` — reading a second
+ * component here goes stale (its changes aren't subscribed).
+ */
+export declare function syncComponentToMap<S extends ComponentSchema, V>(ecs: ECS, def: ComponentDef<S>, project: Projection<S, V>, opts?: EcsMapSyncOptions<V>): EcsMapSync<V>;
+/**
+ * Sugar over `syncComponentToMap`: project a fixed FIELD LIST into a `{ field:
+ * value }` snapshot, with an automatic `shallow` eq so an unchanged row wakes
+ * nobody. The declarative-field-list model from WatermelonDB `observeWithColumns` /
+ * TanStack `select` — the common "mirror these fields" case without hand-writing
+ * the projection + comparator.
+ *
+ * Allocation note: this builds a fresh object per dirty row and `shallow` does two
+ * `Object.keys` per compare — fine for low-churn. For a HIGH-churn component (the
+ * case you'd pick `grain:"column"` for), prefer `syncComponentToMap` with a scalar
+ * or hand-written-`eq` projection, so the hot path doesn't allocate exactly where
+ * the column grain is meant to keep it cheap.
+ */
+export declare function syncFieldsToMap<S extends ComponentSchema, const F extends readonly (string & keyof S)[]>(ecs: ECS, def: ComponentDef<S>, fields: F, opts?: Omit<EcsMapSyncOptions<{
+    [K in F[number]]: number;
+}>, "eq">): EcsMapSync<{
+    [K in F[number]]: number;
+}>;
+/**
+ * Sync a multi-component JOIN into a `reactiveMap`. An entity is a member iff it
+ * has EVERY component in `defs`; the projection reads any of them via
+ * `row.field(def, name)`. Change detection subscribes to ALL joined components, so
+ * a write to ANY of them republishes the row — the join can never go stale (the
+ * bug a single-component sync + manual secondary read would have). Spawns/removes
+ * of any joined component re-evaluate membership.
+ *
+ * Entity grain only: a join spans archetypes, so there is no single column to
+ * sweep. Drive with `batchedUpdate(world, dt)`.
+ */
+export declare function syncJoinToMap<Schemas extends readonly ComponentSchema[], V>(ecs: ECS, defs: readonly [...{
+    [I in keyof Schemas]: ComponentDef<Schemas[I]>;
+}], project: JoinProjection<V, Schemas>, opts?: Omit<EcsMapSyncOptions<V>, "grain">): EcsMapSync<V>;
+export interface SingletonStructSync<V extends object> {
+    /** The live per-field channel: reading `struct.field` in a tracked scope
+     * subscribes to that field alone (pair with `fromKernelStruct` to render). */
+    readonly struct: V;
+    /** Unregister the observer and stop publishing. Safe to call more than once. */
+    dispose(): void;
+}
+export interface SingletonSyncOptions<V extends object = Record<string, number>> {
+    /**
+     * Access surface the publish touches, merged over the synced def's read.
+     * `DEV` access-checks the observer callbacks exactly like a system.
+     */
+    access?: Partial<SystemAccessDeclaration>;
+    /** Replay current state on registration (default `true`). flecs `yieldExisting`. */
+    seedExisting?: boolean;
+    /**
+     * Drive a PRE-CREATED `reactiveStruct` (its `[proxy, set]` pair) instead of
+     * creating a fresh one. Lets the consumer keep the struct at module scope as a
+     * stable "channel" with initial values present before the sync attaches (the
+     * client UI seam: panels import the eager proxy; the sync, set up at world build,
+     * republishes into it via the observer). The seed (`yieldExisting`) overwrites
+     * the eager initials with the entity's current values on registration.
+     */
+    into?: readonly [V, StructSetters<V>];
+    /** Per-field equality overrides for the created struct (parity with
+     * `SingletonArraySyncOptions.eq`). Ignored when `into` supplies a
+     * pre-created struct — that struct already carries its own `eq`. */
+    eq?: StructEq<V>;
+}
+/**
+ * Sync ONE singleton entity's single-component state into a `reactiveStruct`,
+ * keyless — the singleton/resource shape (ADR-0024). This is how heterogeneous
+ * ephemeral UI state (net status + latency, FPS/mem, wave timer, hovered hex) joins
+ * the same reactive view as per-entity components: model it as components on a
+ * reserved singleton entity (the flecs / Unity-DOTS "singleton-as-entity" model)
+ * and read it through per-field channels — NOT a separate reactive-resource
+ * subsystem. Resources stay non-reactive internal singletons.
+ *
+ * It reuses the entity-grain ADR-0013 component observer verbatim, filtered to the
+ * one target eid: an `onSet` (or seed `onAdd`) republishes the entity's field values
+ * into the struct via per-field setters. The per-field `Object.is` eq means an
+ * unchanged field writes nothing — "equal write → 0 renders" — and per-field signals
+ * give "1-of-N FIELD → 1 re-render"; drive with `batchedUpdate` for "one tick → one
+ * commit". Because the component change-detection fires on `ctx.setField`, the
+ * in-place write pattern that defeats a `setResource`-keyed resource observer is
+ * handled for free.
+ *
+ * `fields` is explicit: a `ComponentDef` is a branded number at runtime (its schema
+ * is a phantom type), so the field names must be passed — same contract as
+ * `syncFieldsToMap`. Project a subset to channel only what the UI reads.
+ *
+ * A `reactiveStruct` has a fixed field set and no `delete`, so the map adapter's
+ * delete-on-disable (#677 / ADR-0023) has no struct analog: `onRemove`/`onDisable`
+ * **reset the fields to the channel's declared initial values** (`onSet` skips
+ * disabled entities), `onEnable` republishes. The defaults are the channel's own
+ * initials — the eager `into` struct's declared values (e.g. `NetStats.latency = -1`),
+ * or the zeros of a freshly-created one — captured (untracked) at registration, NOT a
+ * blind 0. A singleton is rarely despawned; this keeps the channel well-defined if it is.
+ */
+export declare function syncSingletonToStruct<S extends ComponentSchema, const F extends readonly (string & keyof S)[]>(ecs: ECS, def: ComponentDef<S>, eid: EntityID, fields: F, opts?: SingletonSyncOptions<{
+    [K in F[number]]: number;
+}>): SingletonStructSync<{
+    [K in F[number]]: number;
+}>;
+export interface SingletonArraySync<T> {
+    /** The live ordered channel: a reader of slot `i` subscribes to that slot alone. */
+    readonly array: ReactiveArray<T>;
+    /** Unregister the observer and stop publishing. Safe to call more than once. */
+    dispose(): void;
+}
+export interface SingletonArraySyncOptions<T> {
+    access?: Partial<SystemAccessDeclaration>;
+    seedExisting?: boolean;
+    /** Drive a PRE-CREATED `reactiveArray` (the module-scope channel) instead of a fresh one. */
+    into?: ReactiveArray<T>;
+    /** Per-slot equality for the array's no-op skip (default `Object.is`). */
+    eq?: (a: T, b: T) => boolean;
+}
+/**
+ * Sync ONE singleton entity's component into a `reactiveArray`, one slot per field
+ * in `fields` order (#685 / ADR-0024) — the ORDERED sibling of `syncSingletonToStruct`,
+ * for positional UI state (the army slots). On every change to the component it
+ * `reconcile`s the array from the field values: a slot whose value is unchanged keeps
+ * its reference (structural sharing), only changed slots wake. `onRemove`/`onDisable`
+ * reset the slots to the channel's DECLARED initial slots (a reactiveArray has no row
+ * delete) — captured (untracked) at registration, so the army channel resets to its
+ * empty sentinel (`EMPTY_SLOT`), NOT a blind 0 that would read as unit type 0.
+ *
+ * `fields` is explicit (a `ComponentDef` is a branded number at runtime). Pair with
+ * `@oasys/oecs/solid`'s `fromKernelArray` + a Solid `<Index>`.
+ */
+export declare function syncSingletonToArray<S extends ComponentSchema>(ecs: ECS, def: ComponentDef<S>, eid: EntityID, fields: readonly (string & keyof S)[], opts?: SingletonArraySyncOptions<number>): SingletonArraySync<number>;
+/**
+ * Advance the world one tick with every bridge publish coalesced into a single UI
+ * flush. onAdd/onRemove fire mid-tick at flush boundaries and onSet fires at the
+ * tick tail; wrapping the whole update in `batch` defers the effect flush until the
+ * tick completes, so a frame that touched K entities (across any number of syncs on
+ * this world) wakes its readers once, not once per observer dispatch point.
+ * Equivalent to `batch(() => ecs.update(dt))`.
+ */
+export declare function batchedUpdate(ecs: ECS, dt: number): void;
+//# sourceMappingURL=ecs_sync.d.ts.map

package/dist/extensions/reactive/ecs_sync.d.ts

@@ -1,12 +1,7 @@
-import { ReactiveArray, ReactiveMap, StructSetters } from '../../core/reactive';
-import { ComponentDef, ComponentSchema, ECS, EntityID, SystemAccessDeclaration } from '../../core/ecs';
-/**
- * Shallow (one-level) value equality — the recommended `eq` for object-valued
- * projections. Mirrors zustand `useShallow` / MobX `comparer.shallow`: two objects
- * are equal iff they have the same own keys with `Object.is`-equal values. Restores
- * "equal write wakes nobody" for projections that build a fresh object each tick.
- */
-export declare function shallow(a: object, b: object): boolean;
+import { ReactiveArray, ReactiveMap, StructSetters, StructEq } from '../../reactive/index.js';
+import { ComponentDef, ComponentSchema, ECS, EntityID, SystemAccessDeclaration } from '../../core/ecs/index.js';
+import { shallow } from '../../reactive/shallow.js';
+export { shallow };
 /**
  * A read cursor over one entity's single-component state, handed to a single-
  * component `Projection`. `field` is column-backed under "column" grain
@@ -32,16 +27,19 @@ export interface RowReader<S extends ComponentSchema> {
  * Lifetime: like `RowReader`, a reused mutable singleton valid ONLY during the
  * synchronous `project` call — never capture it; the next dispatch mutates it.
  */
-export interface JoinReader {
+export interface JoinReader<Schemas extends readonly ComponentSchema[] = readonly ComponentSchema[]> {
     /** The current entity (it has all joined components). */
     readonly eid: EntityID;
-    /** Read a field of one joined component for the current entity. */
-    field<S extends ComponentSchema, K extends string & keyof S>(def: ComponentDef<S>, name: K): number;
+    /** Read a field of one joined component for the current entity. `def` is
+     * constrained to the join's own component set — reading a def outside the
+     * join is the stale-read footgun the module header warns about (its changes
+     * aren't subscribed), so it's a compile error. */
+    field<S extends Schemas[number], K extends string & keyof S>(def: ComponentDef<S>, name: K): number;
 }
 /** Map one single-component row to the value a UI cell reads. */
 export type Projection<S extends ComponentSchema, V> = (row: RowReader<S>) => V;
 /** Map one joined entity to the value a UI cell reads. */
-export type JoinProjection<V> = (row: JoinReader) => V;
+export type JoinProjection<V, Schemas extends readonly ComponentSchema[] = readonly ComponentSchema[]> = (row: JoinReader<Schemas>) => V;
 /** Per-component dirty grain. See the module header for the measured crossover. */
 export type SyncGrain = "entity" | "column";
 export interface EcsMapSyncOptions<V> {
@@ -55,7 +53,7 @@ export interface EcsMapSyncOptions<V> {
     eq?: (a: V, b: V) => boolean;
     /**
      * Access surface the projection touches, merged over the synced components'
-     * `reads`. `__DEV__` access-checks the observer callbacks exactly like a system.
+     * `reads`. `DEV` access-checks the observer callbacks exactly like a system.
      */
     access?: Partial<SystemAccessDeclaration>;
     /**
@@ -79,7 +77,7 @@ export interface EcsMapSync<V> {
  * To read more than one component per row, use `syncJoinToMap` — reading a second
  * component here goes stale (its changes aren't subscribed).
  */
-export declare function syncComponentToMap<S extends ComponentSchema, V>(world: ECS, def: ComponentDef<S>, project: Projection<S, V>, opts?: EcsMapSyncOptions<V>): EcsMapSync<V>;
+export declare function syncComponentToMap<S extends ComponentSchema, V>(ecs: ECS, def: ComponentDef<S>, project: Projection<S, V>, opts?: EcsMapSyncOptions<V>): EcsMapSync<V>;
 /**
  * Sugar over `syncComponentToMap`: project a fixed FIELD LIST into a `{ field:
  * value }` snapshot, with an automatic `shallow` eq so an unchanged row wakes
@@ -93,7 +91,7 @@ export declare function syncComponentToMap<S extends ComponentSchema, V>(world:
  * or hand-written-`eq` projection, so the hot path doesn't allocate exactly where
  * the column grain is meant to keep it cheap.
  */
-export declare function syncFieldsToMap<S extends ComponentSchema, const F extends readonly (string & keyof S)[]>(world: ECS, def: ComponentDef<S>, fields: F, opts?: Omit<EcsMapSyncOptions<{
+export declare function syncFieldsToMap<S extends ComponentSchema, const F extends readonly (string & keyof S)[]>(ecs: ECS, def: ComponentDef<S>, fields: F, opts?: Omit<EcsMapSyncOptions<{
     [K in F[number]]: number;
 }>, "eq">): EcsMapSync<{
     [K in F[number]]: number;
@@ -109,7 +107,9 @@ export declare function syncFieldsToMap<S extends ComponentSchema, const F exten
  * Entity grain only: a join spans archetypes, so there is no single column to
  * sweep. Drive with `batchedUpdate(world, dt)`.
  */
-export declare function syncJoinToMap<V>(world: ECS, defs: readonly ComponentDef[], project: JoinProjection<V>, opts?: Omit<EcsMapSyncOptions<V>, "grain">): EcsMapSync<V>;
+export declare function syncJoinToMap<Schemas extends readonly ComponentSchema[], V>(ecs: ECS, defs: readonly [...{
+    [I in keyof Schemas]: ComponentDef<Schemas[I]>;
+}], project: JoinProjection<V, Schemas>, opts?: Omit<EcsMapSyncOptions<V>, "grain">): EcsMapSync<V>;
 export interface SingletonStructSync<V extends object> {
     /** The live per-field channel: reading `struct.field` in a tracked scope
      * subscribes to that field alone (pair with `fromKernelStruct` to render). */
@@ -120,7 +120,7 @@ export interface SingletonStructSync<V extends object> {
 export interface SingletonSyncOptions<V extends object = Record<string, number>> {
     /**
      * Access surface the publish touches, merged over the synced def's read.
-     * `__DEV__` access-checks the observer callbacks exactly like a system.
+     * `DEV` access-checks the observer callbacks exactly like a system.
      */
     access?: Partial<SystemAccessDeclaration>;
     /** Replay current state on registration (default `true`). flecs `yieldExisting`. */
@@ -134,6 +134,10 @@ export interface SingletonSyncOptions<V extends object = Record<string, number>>
      * the eager initials with the entity's current values on registration.
      */
     into?: readonly [V, StructSetters<V>];
+    /** Per-field equality overrides for the created struct (parity with
+     * `SingletonArraySyncOptions.eq`). Ignored when `into` supplies a
+     * pre-created struct — that struct already carries its own `eq`. */
+    eq?: StructEq<V>;
 }
 /**
  * Sync ONE singleton entity's single-component state into a `reactiveStruct`,
@@ -165,7 +169,7 @@ export interface SingletonSyncOptions<V extends object = Record<string, number>>
  * or the zeros of a freshly-created one — captured (untracked) at registration, NOT a
  * blind 0. A singleton is rarely despawned; this keeps the channel well-defined if it is.
  */
-export declare function syncSingletonToStruct<S extends ComponentSchema, const F extends readonly (string & keyof S)[]>(world: ECS, def: ComponentDef<S>, eid: EntityID, fields: F, opts?: SingletonSyncOptions<{
+export declare function syncSingletonToStruct<S extends ComponentSchema, const F extends readonly (string & keyof S)[]>(ecs: ECS, def: ComponentDef<S>, eid: EntityID, fields: F, opts?: SingletonSyncOptions<{
     [K in F[number]]: number;
 }>): SingletonStructSync<{
     [K in F[number]]: number;
@@ -197,14 +201,14 @@ export interface SingletonArraySyncOptions<T> {
  * `fields` is explicit (a `ComponentDef` is a branded number at runtime). Pair with
  * `@oasys/oecs/solid`'s `fromKernelArray` + a Solid `<Index>`.
  */
-export declare function syncSingletonToArray<S extends ComponentSchema>(world: ECS, def: ComponentDef<S>, eid: EntityID, fields: readonly (string & keyof S)[], opts?: SingletonArraySyncOptions<number>): SingletonArraySync<number>;
+export declare function syncSingletonToArray<S extends ComponentSchema>(ecs: ECS, def: ComponentDef<S>, eid: EntityID, fields: readonly (string & keyof S)[], opts?: SingletonArraySyncOptions<number>): SingletonArraySync<number>;
 /**
  * Advance the world one tick with every bridge publish coalesced into a single UI
  * flush. onAdd/onRemove fire mid-tick at flush boundaries and onSet fires at the
  * tick tail; wrapping the whole update in `batch` defers the effect flush until the
  * tick completes, so a frame that touched K entities (across any number of syncs on
  * this world) wakes its readers once, not once per observer dispatch point.
- * Equivalent to `batch(() => world.update(dt))`.
+ * Equivalent to `batch(() => ecs.update(dt))`.
  */
-export declare function batchedUpdate(world: ECS, dt: number): void;
+export declare function batchedUpdate(ecs: ECS, dt: number): void;
 //# sourceMappingURL=ecs_sync.d.ts.map