@oasys/oecs 0.5.3 → 0.6.0

package/dist/plugins/events/facade.d.cts

@@ -0,0 +1,26 @@
+import { EventFieldsCover, EventKey, EventReader, EventShape, SignalKey } from '../../core/ecs/event.cjs';
+import { EventRegistry } from './event_registry.cjs';
+/** 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 _registry;
+    /** @internal constructed by the events plugin. */
+    constructor(registry: EventRegistry);
+    /** 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>;
+}
+//# sourceMappingURL=facade.d.ts.map

package/dist/plugins/events/facade.d.ts

@@ -0,0 +1,26 @@
+import { EventFieldsCover, EventKey, EventReader, EventShape, SignalKey } from '../../core/ecs/event.js';
+import { EventRegistry } from './event_registry.js';
+/** 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 _registry;
+    /** @internal constructed by the events plugin. */
+    constructor(registry: EventRegistry);
+    /** 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>;
+}
+//# sourceMappingURL=facade.d.ts.map

package/dist/plugins/events/facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["../../../src/plugins/events/facade.ts"],"names":[],"mappings":"AAAA;;;;;;;KAOK;AAEL,OAAO,KAAK,EAGX,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,UAAU,EACV,SAAS,EACT,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;mEAEmE;AACnE,qBAAa,SAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,kDAAkD;gBACtC,QAAQ,EAAE,aAAa;IAInC;;;;;;;;OAQG;IACI,QAAQ,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,EACrF,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,EAChB,MAAM,EAAE,CAAC,GAAG,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,GAChC,IAAI;IAIP,uDAAuD;IAChD,cAAc,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI;IAIpC,IAAI,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI;IAC1B,IAAI,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAgBzE,IAAI,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;CAOtE"}

package/dist/plugins/events/index.d.cts

@@ -0,0 +1,10 @@
+import { ECSEvents } from './facade.cjs';
+import { Plugin } from '../../core/ecs/plugin.cjs';
+export { ECSEvents } from './facade.cjs';
+/** The world surface this plugin adds. */
+export interface EventsPlugin {
+    readonly events: ECSEvents;
+}
+/** The events plugin, for `ECS.create({ plugins: [events()] })`. */
+export declare function events(): Plugin<EventsPlugin>;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/events/index.d.ts

@@ -0,0 +1,10 @@
+import { ECSEvents } from './facade.js';
+import { Plugin } from '../../core/ecs/plugin.js';
+export { ECSEvents } from './facade.js';
+/** The world surface this plugin adds. */
+export interface EventsPlugin {
+    readonly events: ECSEvents;
+}
+/** The events plugin, for `ECS.create({ plugins: [events()] })`. */
+export declare function events(): Plugin<EventsPlugin>;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/events/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;KAaK;AAGL,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,uBAAuB,CAAC;AAEhE,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;CAC3B;AAED,oEAAoE;AACpE,wBAAgB,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,CAS7C"}

package/dist/plugins/events.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("../index.cjs"),h=require("./assertions-z5GQd_bB.cjs");require("../internal.cjs");class c{fieldNames;columns;reader;_readerLen;constructor(e){this.fieldNames=e,this.columns=[];for(let n=0;n<e.length;n++)this.columns.push([]);const t={};for(let n=0;n<e.length;n++)t[e[n]]=this.columns[n];const s={length:0,...t};this._readerLen=s,this.reader=s}emit(e){const t=this.fieldNames,s=this.columns;for(let n=0;n<t.length;n++)s[n].push(e[t[n]]);this._readerLen.length++}emitSignal(){this._readerLen.length++}clear(){this._readerLen.length=0;const e=this.columns;for(let t=0;t<e.length;t++)e[t].length=0}}const o=r=>h.unsafeCast(r);class d{_channels=[];_dirtyChannels=[];_nextEventId=0;_defsByKey=new Map;register(e){const t=o(this._nextEventId++),s=new c(e);return this._channels.push(s),h.unsafeCast(t)}emit(e,t){const s=e,n=this._channels[s],a=n.reader.length===0;n.emit(t),a&&this._dirtyChannels.push(s)}emitSignal(e){const t=e,s=this._channels[t],n=s.reader.length===0;s.emitSignal(),n&&this._dirtyChannels.push(t)}reader(e){return this._channels[e].reader}clear(){const e=this._dirtyChannels;if(e.length===0)return;const t=this._channels;for(let s=0;s<e.length;s++)t[e[s]].clear();e.length=0}devBufferedCount(){const e=this._dirtyChannels,t=this._channels;let s=0;for(let n=0;n<e.length;n++)s+=t[e[n]].reader.length;return s}registerByKey(e,t){if(this._defsByKey.has(e))throw new i.ECSError(i.ECS_ERROR.EVENT_ALREADY_REGISTERED,`event '${e.description??"<unnamed>"}' is already registered`,{event:e.description});const s=this.register(t);return this._defsByKey.set(e,s),s}defByKey(e){const t=this._defsByKey.get(e);if(t===void 0)throw new i.ECSError(i.ECS_ERROR.EVENT_NOT_REGISTERED,`event '${e.description??"<unnamed>"}' is not registered, call ecs.events.register(key, fields) at world setup`,{event:e.description});return t}hasKey(e){return this._defsByKey.has(e)}}class l{_registry;constructor(e){this._registry=e}register(e,t){this._registry.registerByKey(e,t)}registerSignal(e){this._registry.registerByKey(e,[])}emit(e,t){const s=this._registry.defByKey(e);t===void 0?this._registry.emitSignal(s):this._registry.emit(s,t)}read(e){const t=this._registry.defByKey(e);return this._registry.reader(t)}}function g(){return{name:"events",install(r){const e=new d;return r.store.installEvents(e),{events:new l(e)}}}}exports.ECSEvents=l;exports.events=g;

package/dist/plugins/events.d.cts

@@ -0,0 +1 @@
+export * from "./events/index.cjs";

package/dist/plugins/events.d.ts

@@ -0,0 +1 @@
+export * from "./events/index.js";

package/dist/plugins/events.development.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("../index.development.cjs"),c=require("./assertions-z5GQd_bB.cjs"),h=require("../internal.development.cjs");class l{fieldNames;columns;reader;_readerLen;constructor(e){this.fieldNames=e,this.columns=[];for(let s=0;s<e.length;s++)this.columns.push([]);const t={};for(let s=0;s<e.length;s++)t[e[s]]=this.columns[s];const n={length:0,...t};this._readerLen=n,this.reader=n}emit(e){const t=this.fieldNames,n=this.columns;for(let s=0;s<t.length;s++)if(!(t[s]in e))throw new i.ECSError(i.ECS_ERROR.FIELD_NOT_REGISTERED,`emit: event field "${t[s]}" missing from values`);for(let s=0;s<t.length;s++)n[s].push(e[t[s]]);this._readerLen.length++}emitSignal(){this._readerLen.length++}clear(){this._readerLen.length=0;const e=this.columns;for(let t=0;t<e.length;t++)e[t].length=0}}const d=r=>{if(!(Number.isInteger(r)&&r>=0))throw new i.ECSError(i.ECS_ERROR.INVALID_EVENT_ID,`event id must be an integer >= 0, got ${r}`);return c.unsafeCast(r)};class g{_channels=[];_dirtyChannels=[];_nextEventId=0;_defsByKey=new Map;register(e){const t=d(this._nextEventId++),n=new l(e);return this._channels.push(n),c.unsafeCast(t)}emit(e,t){const n=e,s=this._channels[n],a=s.reader.length===0;s.emit(t),a&&this._dirtyChannels.push(n)}emitSignal(e){const t=e,n=this._channels[t],s=n.reader.length===0;n.emitSignal(),s&&this._dirtyChannels.push(t)}reader(e){return this._channels[e].reader}clear(){const e=this._dirtyChannels;if(e.length===0)return;const t=this._channels;for(let n=0;n<e.length;n++)t[e[n]].clear();e.length=0}devBufferedCount(){const e=this._dirtyChannels,t=this._channels;let n=0;for(let s=0;s<e.length;s++)n+=t[e[s]].reader.length;return n}registerByKey(e,t){if(this._defsByKey.has(e))throw new i.ECSError(i.ECS_ERROR.EVENT_ALREADY_REGISTERED,`event '${e.description??"<unnamed>"}' is already registered`,{event:e.description});const n=this.register(t);return this._defsByKey.set(e,n),n}defByKey(e){const t=this._defsByKey.get(e);if(t===void 0)throw new i.ECSError(i.ECS_ERROR.EVENT_NOT_REGISTERED,`event '${e.description??"<unnamed>"}' is not registered, call ecs.events.register(key, fields) at world setup`,{event:e.description});return t}hasKey(e){return this._defsByKey.has(e)}}class o{_registry;constructor(e){this._registry=e}register(e,t){this._registry.registerByKey(e,t)}registerSignal(e){this._registry.registerByKey(e,[])}emit(e,t){h.dispatchTrace.isActive()&&h.dispatchTrace.recordEventEmit(e.description??"");const n=this._registry.defByKey(e);t===void 0?this._registry.emitSignal(n):this._registry.emit(n,t)}read(e){h.dispatchTrace.isActive()&&h.dispatchTrace.recordEventRead(e.description??"");const t=this._registry.defByKey(e);return this._registry.reader(t)}}function E(){return{name:"events",install(r){const e=new g;return r.store.installEvents(e),{events:new o(e)}}}}exports.ECSEvents=o;exports.events=E;

package/dist/plugins/events.development.js

@@ -0,0 +1,174 @@
+import { ECSError as h, ECS_ERROR as o } from "../index.development.js";
+import { u as l } from "./assertions-gtDVfbnQ.js";
+import { dispatchTrace as i } from "../internal.development.js";
+class a {
+  fieldNames;
+  columns;
+  // any: type-erased storage, channel is stored in Map<number, EventChannel>, S is lost
+  reader;
+  // The one mutable view of the reader's `length`. The public `EventReader`
+  // type declares it readonly (a consumer writing `reader.length = 0` on the
+  // live shared object would permanently desync every other system's view),
+  // so the channel keeps this private alias to the same
+  // object for emit and clear bookkeeping.
+  _readerLen;
+  constructor(e) {
+    this.fieldNames = e, this.columns = [];
+    for (let n = 0; n < e.length; n++)
+      this.columns.push([]);
+    const t = {};
+    for (let n = 0; n < e.length; n++)
+      t[e[n]] = this.columns[n];
+    const s = { length: 0, ...t };
+    this._readerLen = s, this.reader = s;
+  }
+  emit(e) {
+    const t = this.fieldNames, s = this.columns;
+    for (let n = 0; n < t.length; n++)
+      if (!(t[n] in e))
+        throw new h(
+          o.FIELD_NOT_REGISTERED,
+          `emit: event field "${t[n]}" missing from values`
+        );
+    for (let n = 0; n < t.length; n++) s[n].push(e[t[n]]);
+    this._readerLen.length++;
+  }
+  /** Emit a signal (zero-field event). */
+  emitSignal() {
+    this._readerLen.length++;
+  }
+  clear() {
+    this._readerLen.length = 0;
+    const e = this.columns;
+    for (let t = 0; t < e.length; t++)
+      e[t].length = 0;
+  }
+}
+const d = (r) => {
+  if (!(Number.isInteger(r) && r >= 0))
+    throw new h(
+      o.INVALID_EVENT_ID,
+      `event id must be an integer >= 0, got ${r}`
+    );
+  return l(r);
+};
+class g {
+  // Parallel array indexed by EventID: each channel holds SoA columns + reader.
+  _channels = [];
+  // IDs of channels emitted to since the last `clear()`. An `emit*`
+  // only pushes when the channel was empty (`reader.length === 0`), so each
+  // dirty channel appears at most once per tick, `clear` then walks
+  // only these instead of every registered channel.
+  _dirtyChannels = [];
+  _nextEventId = 0;
+  // any: type-erased. EventDef<F> phantom is lost in the map, recovered by
+  // callers via EventKey<F>
+  _defsByKey = /* @__PURE__ */ new Map();
+  register(e) {
+    const t = d(this._nextEventId++), s = new a(e);
+    return this._channels.push(s), l(t);
+  }
+  emit(e, t) {
+    const s = e, n = this._channels[s], c = n.reader.length === 0;
+    n.emit(t), c && this._dirtyChannels.push(s);
+  }
+  emitSignal(e) {
+    const t = e, s = this._channels[t], n = s.reader.length === 0;
+    s.emitSignal(), n && this._dirtyChannels.push(t);
+  }
+  reader(e) {
+    return this._channels[e].reader;
+  }
+  clear() {
+    const e = this._dirtyChannels;
+    if (e.length === 0) return;
+    const t = this._channels;
+    for (let s = 0; s < e.length; s++)
+      t[e[s]].clear();
+    e.length = 0;
+  }
+  /** `DEV`-only: total events currently buffered across the dirty channels.
+   * `ECS.update` samples this either side of the settle hooks to assert an
+   * onSet observer emitted nothing, its emissions would be wiped by the
+   * tick-tail `clear` and break the empty-channel-at-boundary invariant that
+   * snapshot and restore rely on. Walks only the dirty list, never the hot emit path. */
+  devBufferedCount() {
+    const e = this._dirtyChannels, t = this._channels;
+    let s = 0;
+    for (let n = 0; n < e.length; n++) s += t[e[n]].reader.length;
+    return s;
+  }
+  registerByKey(e, t) {
+    if (this._defsByKey.has(e))
+      throw new h(
+        o.EVENT_ALREADY_REGISTERED,
+        `event '${e.description ?? "<unnamed>"}' is already registered`,
+        { event: e.description }
+      );
+    const s = this.register(t);
+    return this._defsByKey.set(e, s), s;
+  }
+  // any: type-erased, caller recovers F from EventKey<F>
+  defByKey(e) {
+    const t = this._defsByKey.get(e);
+    if (t === void 0)
+      throw new h(
+        o.EVENT_NOT_REGISTERED,
+        `event '${e.description ?? "<unnamed>"}' is not registered, call ecs.events.register(key, fields) at world setup`,
+        { event: e.description }
+      );
+    return t;
+  }
+  hasKey(e) {
+    return this._defsByKey.has(e);
+  }
+}
+class _ {
+  _registry;
+  /** @internal constructed by the events plugin. */
+  constructor(e) {
+    this._registry = e;
+  }
+  /** 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(e, t) {
+    this._registry.registerByKey(e, t);
+  }
+  /** Register a signal (empty-payload event channel). */
+  registerSignal(e) {
+    this._registry.registerByKey(e, []);
+  }
+  // Erased implementation position spells `<any>`, not the bare/`unknown`
+  // form, `EventKey` is invariant under the typestate seams (function-typed
+  // phantom), so only `<any>` erases (see project typestate constraints).
+  emit(e, t) {
+    i.isActive() && i.recordEventEmit(e.description ?? "");
+    const s = this._registry.defByKey(e);
+    t === void 0 ? this._registry.emitSignal(s) : this._registry.emit(s, t);
+  }
+  read(e) {
+    i.isActive() && i.recordEventRead(e.description ?? "");
+    const t = this._registry.defByKey(e);
+    return this._registry.reader(t);
+  }
+}
+function E() {
+  return {
+    name: "events",
+    install(r) {
+      const e = new g();
+      return r.store.installEvents(e), { events: new _(e) };
+    }
+  };
+}
+export {
+  _ as ECSEvents,
+  E as events
+};

package/dist/plugins/events.js

@@ -0,0 +1,159 @@
+import { ECSError as i, ECS_ERROR as h } from "../index.js";
+import { u as l } from "./assertions-gtDVfbnQ.js";
+import "../internal.js";
+class o {
+  fieldNames;
+  columns;
+  // any: type-erased storage, channel is stored in Map<number, EventChannel>, S is lost
+  reader;
+  // The one mutable view of the reader's `length`. The public `EventReader`
+  // type declares it readonly (a consumer writing `reader.length = 0` on the
+  // live shared object would permanently desync every other system's view),
+  // so the channel keeps this private alias to the same
+  // object for emit and clear bookkeeping.
+  _readerLen;
+  constructor(e) {
+    this.fieldNames = e, this.columns = [];
+    for (let n = 0; n < e.length; n++)
+      this.columns.push([]);
+    const t = {};
+    for (let n = 0; n < e.length; n++)
+      t[e[n]] = this.columns[n];
+    const s = { length: 0, ...t };
+    this._readerLen = s, this.reader = s;
+  }
+  emit(e) {
+    const t = this.fieldNames, s = this.columns;
+    for (let n = 0; n < t.length; n++) s[n].push(e[t[n]]);
+    this._readerLen.length++;
+  }
+  /** Emit a signal (zero-field event). */
+  emitSignal() {
+    this._readerLen.length++;
+  }
+  clear() {
+    this._readerLen.length = 0;
+    const e = this.columns;
+    for (let t = 0; t < e.length; t++)
+      e[t].length = 0;
+  }
+}
+const c = (r) => l(r);
+class d {
+  // Parallel array indexed by EventID: each channel holds SoA columns + reader.
+  _channels = [];
+  // IDs of channels emitted to since the last `clear()`. An `emit*`
+  // only pushes when the channel was empty (`reader.length === 0`), so each
+  // dirty channel appears at most once per tick, `clear` then walks
+  // only these instead of every registered channel.
+  _dirtyChannels = [];
+  _nextEventId = 0;
+  // any: type-erased. EventDef<F> phantom is lost in the map, recovered by
+  // callers via EventKey<F>
+  _defsByKey = /* @__PURE__ */ new Map();
+  register(e) {
+    const t = c(this._nextEventId++), s = new o(e);
+    return this._channels.push(s), l(t);
+  }
+  emit(e, t) {
+    const s = e, n = this._channels[s], a = n.reader.length === 0;
+    n.emit(t), a && this._dirtyChannels.push(s);
+  }
+  emitSignal(e) {
+    const t = e, s = this._channels[t], n = s.reader.length === 0;
+    s.emitSignal(), n && this._dirtyChannels.push(t);
+  }
+  reader(e) {
+    return this._channels[e].reader;
+  }
+  clear() {
+    const e = this._dirtyChannels;
+    if (e.length === 0) return;
+    const t = this._channels;
+    for (let s = 0; s < e.length; s++)
+      t[e[s]].clear();
+    e.length = 0;
+  }
+  /** `DEV`-only: total events currently buffered across the dirty channels.
+   * `ECS.update` samples this either side of the settle hooks to assert an
+   * onSet observer emitted nothing, its emissions would be wiped by the
+   * tick-tail `clear` and break the empty-channel-at-boundary invariant that
+   * snapshot and restore rely on. Walks only the dirty list, never the hot emit path. */
+  devBufferedCount() {
+    const e = this._dirtyChannels, t = this._channels;
+    let s = 0;
+    for (let n = 0; n < e.length; n++) s += t[e[n]].reader.length;
+    return s;
+  }
+  registerByKey(e, t) {
+    if (this._defsByKey.has(e))
+      throw new i(
+        h.EVENT_ALREADY_REGISTERED,
+        `event '${e.description ?? "<unnamed>"}' is already registered`,
+        { event: e.description }
+      );
+    const s = this.register(t);
+    return this._defsByKey.set(e, s), s;
+  }
+  // any: type-erased, caller recovers F from EventKey<F>
+  defByKey(e) {
+    const t = this._defsByKey.get(e);
+    if (t === void 0)
+      throw new i(
+        h.EVENT_NOT_REGISTERED,
+        `event '${e.description ?? "<unnamed>"}' is not registered, call ecs.events.register(key, fields) at world setup`,
+        { event: e.description }
+      );
+    return t;
+  }
+  hasKey(e) {
+    return this._defsByKey.has(e);
+  }
+}
+class g {
+  _registry;
+  /** @internal constructed by the events plugin. */
+  constructor(e) {
+    this._registry = e;
+  }
+  /** 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(e, t) {
+    this._registry.registerByKey(e, t);
+  }
+  /** Register a signal (empty-payload event channel). */
+  registerSignal(e) {
+    this._registry.registerByKey(e, []);
+  }
+  // Erased implementation position spells `<any>`, not the bare/`unknown`
+  // form, `EventKey` is invariant under the typestate seams (function-typed
+  // phantom), so only `<any>` erases (see project typestate constraints).
+  emit(e, t) {
+    const s = this._registry.defByKey(e);
+    t === void 0 ? this._registry.emitSignal(s) : this._registry.emit(s, t);
+  }
+  read(e) {
+    const t = this._registry.defByKey(e);
+    return this._registry.reader(t);
+  }
+}
+function f() {
+  return {
+    name: "events",
+    install(r) {
+      const e = new d();
+      return r.store.installEvents(e), { events: new g(e) };
+    }
+  };
+}
+export {
+  g as ECSEvents,
+  f as events
+};

package/dist/plugins/observers/index.d.cts

@@ -0,0 +1,23 @@
+import { Plugin } from '../../core/ecs/plugin.cjs';
+import { ArchetypeSetObserverConfig, EntitySetObserverConfig, ObserverHandle, StructuralObserverConfig } from '../../core/ecs/observer.cjs';
+import { ComponentHandle } from '../../core/ecs/component.cjs';
+import { SparseComponentDef } from '../../core/ecs/sparse_store.cjs';
+export { ObserverRegistry } from './observer_registry.cjs';
+/** The world surface this plugin adds. The overloads match the ones `ECS`
+ * carried before the split, so a call site does not change.
+ *
+ * `observe` registers the callbacks in `config` against `def`. `onAdd`,
+ * `onRemove`, `onDisable` and `onEnable` fire at the structural flush, after
+ * the batch commits, in canonical order (access-topological across
+ * observers, entity id order within), and the flush loops to a fixed point
+ * so a cascade settles. `onSet` fires at the settle of `update()`. Register
+ * before `startup()`. The handle's `dispose()` unregisters. Cold path. */
+export interface ObserversPlugin {
+    observe(def: ComponentHandle, config: StructuralObserverConfig): ObserverHandle;
+    observe(def: ComponentHandle, config: EntitySetObserverConfig): ObserverHandle;
+    observe(def: ComponentHandle, config: ArchetypeSetObserverConfig): ObserverHandle;
+    observe(def: SparseComponentDef, config: EntitySetObserverConfig): ObserverHandle;
+}
+/** The observers plugin, for `ECS.create({ plugins: [observers()] })`. */
+export declare function observers(): Plugin<ObserversPlugin>;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/observers/index.d.ts

@@ -0,0 +1,23 @@
+import { Plugin } from '../../core/ecs/plugin.js';
+import { ArchetypeSetObserverConfig, EntitySetObserverConfig, ObserverHandle, StructuralObserverConfig } from '../../core/ecs/observer.js';
+import { ComponentHandle } from '../../core/ecs/component.js';
+import { SparseComponentDef } from '../../core/ecs/sparse_store.js';
+export { ObserverRegistry } from './observer_registry.js';
+/** The world surface this plugin adds. The overloads match the ones `ECS`
+ * carried before the split, so a call site does not change.
+ *
+ * `observe` registers the callbacks in `config` against `def`. `onAdd`,
+ * `onRemove`, `onDisable` and `onEnable` fire at the structural flush, after
+ * the batch commits, in canonical order (access-topological across
+ * observers, entity id order within), and the flush loops to a fixed point
+ * so a cascade settles. `onSet` fires at the settle of `update()`. Register
+ * before `startup()`. The handle's `dispose()` unregisters. Cold path. */
+export interface ObserversPlugin {
+    observe(def: ComponentHandle, config: StructuralObserverConfig): ObserverHandle;
+    observe(def: ComponentHandle, config: EntitySetObserverConfig): ObserverHandle;
+    observe(def: ComponentHandle, config: ArchetypeSetObserverConfig): ObserverHandle;
+    observe(def: SparseComponentDef, config: EntitySetObserverConfig): ObserverHandle;
+}
+/** The observers plugin, for `ECS.create({ plugins: [observers()] })`. */
+export declare function observers(): Plugin<ObserversPlugin>;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/observers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/observers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;KAiBK;AAGL,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EACX,0BAA0B,EAC1B,uBAAuB,EAEvB,cAAc,EACd,wBAAwB,EACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;;0EAQ0E;AAC1E,MAAM,WAAW,eAAe;IAC/B,OAAO,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,wBAAwB,GAAG,cAAc,CAAC;IAChF,OAAO,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,uBAAuB,GAAG,cAAc,CAAC;IAC/E,OAAO,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,0BAA0B,GAAG,cAAc,CAAC;IAClF,OAAO,CAAC,GAAG,EAAE,kBAAkB,EAAE,MAAM,EAAE,uBAAuB,GAAG,cAAc,CAAC;CAClF;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,IAAI,MAAM,CAAC,eAAe,CAAC,CAoBnD"}

package/dist/plugins/observers/observer_registry.d.cts

@@ -0,0 +1,101 @@
+import { ComponentHandle } from '../../core/ecs/component.cjs';
+import { SparseComponentDef } from '../../core/ecs/sparse_store.cjs';
+import { SystemContext } from '../../core/ecs/system_context.cjs';
+import { StructuralObserverEvents } from '../../core/ecs/store.cjs';
+import { SystemDescriptor } from '../../core/ecs/system.cjs';
+import { ObserverConfig, ObserverHandle, ObserverHooks, ObserverHost } from '../../core/ecs/observer.cjs';
+/**
+ * Registry of component observers. Owned by the observers plugin, which builds
+ * it at install. The store calls `dispatchStructural` through its structural
+ * hook between fixed-point rounds of `flushStructural`, and the world calls
+ * `dispatchSet` through the plugin's settle hook at the post-update detection
+ * point.
+ */
+export declare class ObserverRegistry implements ObserverHooks {
+    private readonly _store;
+    private readonly _ctx;
+    private readonly _entries;
+    /** ComponentID → its observers (structural + onSet). */
+    private readonly _byCid;
+    /** The entity-level onSet observers on sparse components, in registration
+     * order. */
+    private readonly _sparseEntries;
+    /** Per-`dispatchSet` cache of each sparse component's drain, so two
+     * observers on one sparse component fire over one snapshot. */
+    private readonly _sparseDrainCache;
+    /** Cached access-topological order. A register or a dispose invalidates it. */
+    private _topo;
+    private readonly _addBuckets;
+    private readonly _remBuckets;
+    private readonly _disBuckets;
+    private readonly _enaBuckets;
+    private _radixOut;
+    private readonly _radixC0;
+    private readonly _radixC1;
+    private readonly _setDrainCache;
+    constructor(_store: ObserverHost, _ctx: SystemContext);
+    get count(): number;
+    /** The synthesized `SystemDescriptor`s of every registered observer, in
+     * registration order (`dispose()` splices entries out, so none are stale).
+     * Fed into the `startup()` archetype-prewarm closure so an observer's declared
+     * `spawns` and `transitions` create their target archetypes eagerly, exactly as a
+     * system's do. Without this an archetype an observer spawns into or transitions to
+     * first-touches lazily mid-tick, the one asymmetry left in the otherwise
+     * uniform "no lazy archetypes" prewarm. */
+    descriptors(): SystemDescriptor[];
+    register(def: ComponentHandle | SparseComponentDef, config: ObserverConfig): ObserverHandle;
+    /** The sparse arm of `register`: an entity-level onSet, and nothing else.
+     * A sparse add and remove are immediate and touch no archetype, so there
+     * is no flush boundary to fire a structural observer at, and no archetype
+     * column for the archetype grain. */
+    private _registerSparse;
+    private _dispose;
+    /** Recompute the component's hot-path observation flags from its live
+     * observers and push them to the store (which owns the flags + fast-path
+     * counters). */
+    private _reconfigureComponent;
+    private _getTopo;
+    /**
+     * Fire onAdd, onRemove, onDisable and onEnable for one fixed-point round's
+     * effective events, in canonical order: access-topological across observers,
+     * entity-id order (radix) within each observer. Called through the store's
+     * structural hook after the batch commits. Observer callbacks may
+     * enqueue further structural ops (or toggles) onto the deferred buffers (the
+     * store loops until quiescent).
+     *
+     * The events arrive as flat `(comp, eid)` parallel arrays collected during the
+     * flush. This dispatch buckets by component once (O(K)), then walks observers
+     * in topo order so a producer's writes are visible to a consumer
+     * (glitch-free). A round
+     * carries either structural (add, remove) or toggle (disable, enable) events, never both,
+     * toggles drain only once add, remove and destroy are quiescent (`flushStructural`),
+     * but all four bucket uniformly. The empty pairs are no-ops. Within an
+     * observer the fire order is remove, add, disable, enable (the "leaving" edges
+     * before the "entering" edges).
+     */
+    dispatchStructural(ev: StructuralObserverEvents): void;
+    /** Radix-sort `eids` by entity index (canonical within-observer order), then
+     * fire `fn` per entity under the observer's access scope. */
+    private _fireEach;
+    private _bucket;
+    private _clearBuckets;
+    /**
+     * Fire onSet observers for the current frame, in canonical order. Per-entity
+     * onSet drains the opt-in dirty list, once for each changed entity.
+     * Archetype-granular onSet scans the change tick, once for each changed
+     * archetype column.
+     * Called through the plugin's settle hook, after every phase of the frame.
+     * `run` is the change tick advanced
+     * for this dispatch: above every system run of the frame, and the baseline
+     * each archetype-granular observer keeps for its next dispatch.
+     */
+    dispatchSet(run: number): void;
+    /** Fire one sparse observer over the members recorded since the last
+     * drain. The store's walk gives alive, member and enabled entities, so no
+     * check remains here. Canonical order by entity index, through the radix. */
+    private _dispatchSparseSet;
+    private _dispatchSetEntity;
+    private _dispatchSetArch;
+    private _yieldExisting;
+}
+//# sourceMappingURL=observer_registry.d.ts.map