@oasys/oecs 0.5.3 → 0.6.0

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

@@ -1,15 +1,15 @@
 import { ComponentDef, ComponentSchema, CompleteFieldValues, FieldValues } from './component.cjs';
 import { ECS } from './ecs.cjs';
 import { EntityID } from './entity.cjs';
-import { SystemContext } from './query.cjs';
-import { SCHEDULE } from './schedule.cjs';
+import { SystemContext } from './system_context.cjs';
+import { SchedulePhase } from './phase.cjs';
 import { PayloadCodec } from '../store/index.cjs';
 /** One component to attach to a freshly spawned entity. `values` are required
- * and complete as a *strictness* choice, not a runtime need: since #716 every
- * attach path (deferred included — `writeFields`'s `?? 0`) zero-fills omitted
+ * and complete as a *strictness* choice, not a runtime need: every
+ * attach path (deferred included, `writeFields`'s `?? 0`) zero-fills omitted
  * fields, same as templates. A host command is a reified, replayable record,
  * so it carries explicit intent for every field rather than relying on the
- * zero-fill; a tag component takes `{}`. Build type-safely with `spawnEntry`. */
+ * zero-fill. A tag component takes `{}`. Build type-safely with `spawnEntry`. */
 export interface SpawnEntry {
     readonly def: ComponentDef;
     readonly values: FieldValues<ComponentSchema>;
@@ -17,34 +17,34 @@ export interface SpawnEntry {
 /** Extracts the schema out of a `ComponentDef` handle. */
 type SchemaOf<D extends ComponentDef> = D extends ComponentDef<infer S> ? S : ComponentSchema;
 /** One schema-checked spawn entry: `values` is complete for its own def (see
- * the `SpawnEntry` doc — explicit intent per field, though the attach path
- * zero-fills since #716), and a tag takes exactly `{}`. */
+ * the `SpawnEntry` doc, explicit intent per field, though the attach path
+ * zero-fills), and a tag takes exactly `{}`. */
 export type SpawnEntryFor<D extends ComponentDef> = {
     readonly def: D;
     readonly values: CompleteFieldValues<SchemaOf<D>>;
 };
-/** The entries tuple for `HostCommandQueue.spawn` — each element's `values` is
+/** The entries tuple for `HostCommandQueue.spawn`, each element's `values` is
  * checked against its own `def`'s schema. Unlike the authoring-side bundle
- * varargs (`StrictBundles` — `Partial`, a template/attach zero-fills omitted
+ * varargs (`StrictBundles`, `Partial`, a template and attach zero-fills omitted
  * fields), a host command demands complete values: it is a reified, replayable
  * record, so every field is explicit even though the attach path would
- * zero-fill (#716). This is the one attach surface that stays on entry-objects
- * — it is transport (record/replay, editor undo), not authoring. */
+ * zero-fill. This is the one attach surface that stays on entry-objects.
+ * It is transport (record and replay, editor undo), not authoring. */
 export type SpawnEntries<Defs extends readonly ComponentDef[]> = readonly [
     ...{
         [K in keyof Defs]: SpawnEntryFor<Defs[K]>;
     }
 ];
-/** Type-checked `SpawnEntry` constructor — keeps `values` aligned to `def`'s
+/** Type-checked `SpawnEntry` constructor, keeps `values` aligned to `def`'s
  * schema at the call site even though the stored entry is schema-erased. */
 export declare function spawnEntry<S extends ComponentSchema>(def: ComponentDef<S>, values: CompleteFieldValues<S>): SpawnEntry;
 /**
  * A single world mutation, as plain data. Every transport (typed queue today, a
- * SAB ring codec tomorrow) and every consumer (editor undo, record/replay)
+ * SAB ring codec tomorrow) and every consumer (editor undo, record and replay)
  * speaks this one vocabulary, applied by the one `applyHostCommand` dispatch.
  *
- * Component fields are `string` / `def: ComponentDef` (schema-erased) so the
- * union stays flat; the typed `HostCommandQueue` methods preserve type-safety at
+ * Component fields are `string` and `def: ComponentDef` (schema-erased) so the
+ * union stays flat. The typed `HostCommandQueue` methods preserve type-safety at
  * the enqueue site. `applyHostCommand` re-applies them through `SystemContext`,
  * which type-checks because `ComponentDef` defaults its schema to
  * `ComponentSchema` (whose `keyof` is `string`).
@@ -53,7 +53,7 @@ export type HostCommand = {
     readonly kind: "spawn";
     readonly components: readonly SpawnEntry[];
     /** Fired with the new id once the spawn applies (the id only exists
-     * after the deferred create) — lets a producer/editor learn it. */
+     * after the deferred create), lets a producer or editor learn it. */
     readonly onSpawned?: (entityId: EntityID) => void;
 } | {
     readonly kind: "despawn";
@@ -81,163 +81,163 @@ export type HostCommand = {
     readonly eid: EntityID;
 };
 /**
- * THE ONE APPLY DISPATCH. Maps a `HostCommand` onto `SystemContext` ops. Only
+ * The one apply dispatch. Maps a `HostCommand` onto `SystemContext` ops. Only
  * ever called from inside the blessed apply system, which holds the `ctx` and is
- * `exclusive` (full access). Structural changes (`spawn`/`despawn`/component
- * add-remove) are deferred to the phase flush, exactly like a normal system's;
- * `setField` is immediate and bumps the change-tick. Returns the new entity for
- * `spawn`, otherwise `undefined`.
+ * `exclusive` (full access). A structural change (`spawn`, `despawn`, and a
+ * component add or remove) is deferred to the phase flush, exactly like a normal
+ * system's. `setField` is immediate and stamps the change tick. Returns the new
+ * entity for `spawn`, otherwise `undefined`.
  *
- * That immediate/deferred split is a sharp edge: a `setField` targeting a
- * component the entity does NOT yet have — because an `add`/`spawn`
- * enqueued in the SAME drain is still pending its flush — would otherwise fail
- * deep in `getColumn` with an opaque "component not registered". The `DEV`
+ * That immediate and deferred split is a sharp edge: a `setField` targeting a
+ * component the entity does not yet have, because an `add` or `spawn`
+ * enqueued in the same drain is still pending its flush, would otherwise fail
+ * deep in `getColumnMut` with an opaque "component not registered". The `DEV`
  * guard below turns that into an actionable message. The fix is structural, not a
- * retry: pass the value in `add`/`spawnEntry` (which carries complete
+ * retry: pass the value in `add` and `spawnEntry` (which carries complete
  * field values), or issue the `setField` on a later frame.
  */
 export declare function applyHostCommand(ctx: SystemContext, cmd: HostCommand): EntityID | undefined;
 /**
- * The host-facing write handle. Mutating methods ENQUEUE (off-schedule, pure);
- * nothing reaches the world until the apply system drains it at the next
+ * The host-facing write handle. A mutating method enqueues, off-schedule and
+ * pure. Nothing reaches the world until the apply system drains it at the next
  * schedule head. Mirrors Bevy's `Commands` ergonomics over the flat `HostCommand`
  * vocabulary. The returned-from-`installHostCommandSeam` instance is the
- * write counterpart to the reactive bridge's returned `reactiveMap`.
+ * write counterpart to a read view the Solid plugin returns.
  */
 export declare class HostCommandQueue {
-    private readonly queued;
+    private readonly _pending;
     /** Spawn an entity carrying `components`. `onSpawned` receives the new id
      * once the spawn applies. Each entry's `values` is checked against its own
-     * `def`'s schema (`SpawnEntries`); the stored command stays schema-erased. */
+     * `def`'s schema (`SpawnEntries`). The stored command stays schema-erased. */
     spawn<Defs extends readonly ComponentDef[]>(components: SpawnEntries<Defs>, onSpawned?: (entityId: EntityID) => void): this;
     despawn(entityId: EntityID): this;
     /** Attach `def` (with complete `values`) to `entityId` (deferred to the
-     * drain). The namespaced-handle grammar — the queue is a commands buffer, so
+     * drain). The namespaced-handle grammar, the queue is a commands buffer, so
      * it drops the noun (`add`, not `addComponent`), matching `ctx.commands.add`
-     * and the queue's own bare `spawn`/`despawn`/`disable`/`enable`. Values are
-     * complete (transport carries explicit intent per field; see `spawnEntry`),
+     * and the queue's own bare `spawn`, `despawn`, `disable` and `enable`. Values are
+     * complete (transport carries explicit intent per field, see `spawnEntry`),
      * unlike the authoring-side bundle sugar. */
     add<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, values: CompleteFieldValues<S>): this;
     /** Detach `def` from `entityId` (deferred to the drain). Bare `remove`
-     * matching `ctx.commands.remove` — see `add`. */
+     * matching `ctx.commands.remove`, see `add`. */
     remove(entityId: EntityID, def: ComponentDef): this;
-    /** Set `field` of `def` on `entityId`. Applied IMMEDIATELY at the drain, unlike
-     * the deferred structural ops — so `def` must already be on `entityId`. Do NOT
-     * `add`/`spawn` `def` and `setField` it in the same frame: the add is
+    /** Set `field` of `def` on `entityId`. Applied immediately at the drain, unlike
+     * the deferred structural ops, so `def` must already be on `entityId`. Do not
+     * `add` and `spawn` `def` and `setField` it in the same frame: the add is
      * still pending its flush when the immediate set runs (carry the value in
-     * `add`/`spawnEntry` instead). `applyHostCommand` throws an
+     * `add` or `spawnEntry` instead). `applyHostCommand` throws an
      * actionable error in `DEV` if you do. */
     setField<S extends ComponentSchema>(entityId: EntityID, def: ComponentDef<S>, field: string & keyof S, value: number): this;
     disable(entityId: EntityID): this;
     enable(entityId: EntityID): this;
     /** Enqueue a pre-built command. The path for a SAB-ring codec, an editor's
-     * reified inverse, or a replay log — all of which produce `HostCommand` data
+     * reified inverse, or a replay log, all of which produce `HostCommand` data
      * directly rather than calling the typed sugar above. */
     push(cmd: HostCommand): this;
     /** Commands buffered but not yet applied. */
-    get pending(): number;
-    /** Drop every buffered command without applying it (M15) — e.g. abandoning
+    get pendingCount(): number;
+    /** Drop every buffered command without applying it, e.g. abandoning
      * queued edits on a scene unload. Returns how many were dropped. Does not
      * touch commands already drained into the world. */
     clear(): number;
     /**
      * Apply and clear every buffered command. Called by the blessed apply system
-     * inside its schedule span; not part of the host-facing surface. Returns the
+     * inside its schedule span. Not part of the host-facing surface. Returns the
      * count applied.
      *
-     * `tap`, when present, is invoked with each command in apply order just before
-     * it is applied — the record/replay hook ({@link HostCommandRecorder}). It is
-     * an OPT-IN observer: the tap-free path keeps the original tight loop, so an
-     * un-recorded drain pays nothing (#702).
+     * `tap`, when present, is invoked with each command in apply order immediately before
+     * it is applied, the record and replay hook ({@link HostCommandRecorder}). It is
+     * an opt-in observer: the tap-free path keeps the original tight loop, so an
+     * un-recorded drain pays nothing.
      */
     drain(ctx: SystemContext, tap?: (cmd: HostCommand) => void): number;
 }
 /** Bytes of the payload region inside one `command_ring` slot (15). The slot's
- * leading byte is the opCode; `COMMAND_RING_SLOT_BYTES` (16) is the whole slot. */
+ * leading byte is the opCode. `COMMAND_RING_SLOT_BYTES` (16) is the whole slot. */
 export declare const HOST_COMMAND_PAYLOAD_BYTES: number;
 /**
- * Ring codec for a `setField` on a FIXED `(def, field)`. The component + field
- * are bound INTO the codec, not carried in the bytes — the consumer-owned-codec
+ * Ring codec for a `setField` on a fixed `(def, field)`. The component + field
+ * are bound into the codec, not carried in the bytes, the consumer-owned-codec
  * rule (mirroring `command_dispatch`): the engine ships the mechanism, a
  * consumer's codec knows which component+field an opcode means.
  *
  *   Payload (15 B): `[ eid: u32 LE @0 ][ value: f64 LE @4 ][ _reserved: 3 B @12 ]`
  *
- * `value` rides as `f64` (covers every numeric column type losslessly within
- * range); the trailing 3 bytes stay zero. Packing the id as `u32` is what makes
+ * `value` rides as `f64`, which covers every numeric column type losslessly
+ * within range. The trailing 3 bytes stay zero. Packing the id as `u32` makes
  * `setField` fit the 15-byte slot.
  */
 export declare function ringSetFieldCodec<S extends ComponentSchema>(def: ComponentDef<S>, field: string & keyof S): PayloadCodec<HostCommand>;
-/** Ring codec for `despawn` — `[ eid: u32 LE @0 ]`, trailing 11 B reserved-zero. */
+/** Ring codec for `despawn`, `[ eid: u32 LE @0 ]`, trailing 11 B reserved-zero. */
 export declare function ringDespawnCodec(): PayloadCodec<HostCommand>;
-/** Ring codec for `disable` — `[ eid: u32 LE @0 ]`, trailing 11 B reserved-zero. */
+/** Ring codec for `disable`, `[ eid: u32 LE @0 ]`, trailing 11 B reserved-zero. */
 export declare function ringDisableCodec(): PayloadCodec<HostCommand>;
-/** Ring codec for `enable` — `[ eid: u32 LE @0 ]`, trailing 11 B reserved-zero. */
+/** Ring codec for `enable`, `[ eid: u32 LE @0 ]`, trailing 11 B reserved-zero. */
 export declare function ringEnableCodec(): PayloadCodec<HostCommand>;
 /**
- * Ring codec for `removeComponent` of a FIXED `def` — `[ eid: u32 LE @0 ]`, the
- * component bound into the codec (consumer-owned-codec rule). `spawn` /
+ * Ring codec for `removeComponent` of a fixed `def`, `[ eid: u32 LE @0 ]`, the
+ * component bound into the codec (consumer-owned-codec rule). `spawn` and
  * `addComponent` are deliberately absent: they carry component field values
  * that don't fit the 15-byte slot generically, so they stay typed-transport-only
- * (the prototype's finding — the in-process queue has no width limit).
+ * (the prototype's finding, the in-process queue has no width limit).
  */
 export declare function ringRemoveComponentCodec(def: ComponentDef): PayloadCodec<HostCommand>;
 /** A ctx-aware applier for one ring opcode: runs on the system `ctx` (which the
  * apply system holds) with the raw 15-byte payload. `tap`, when present, is the
- * record/replay hook (#702) — a generic, `onCommand`-bound applier decodes the
+ * record and replay hook, a generic, `onCommand`-bound applier decodes the
  * slot to a `HostCommand` and feeds it to `tap` before applying, so ring-sourced
  * commands land in the same log as typed-queue ones. A raw `on` applier (a
  * consumer's own non-`HostCommand` op, e.g. the game's `spawn_unit`) has no
- * `HostCommand` to surface and simply ignores `tap`. */
+ * `HostCommand` to surface and ignores `tap`. */
 export type RingCommandApplier = (ctx: SystemContext, payload: Uint8Array, tap?: (cmd: HostCommand) => void) => void;
 /**
  * Drains the SAB `command_ring` as the second host-command transport, dispatching
  * each opcode to a bound applier. Two binding styles:
  *
- *   - `onCommand(op, codec)` — decode the slot to a `HostCommand` and run it
- *     through the ONE `applyHostCommand` (the same dispatch the typed queue
- *     uses). This is the generic cross-thread / wire host-write path.
- *   - `on(op, applier)` — a raw ctx-aware handler for a consumer's OWN ring ops
+ *   - `onCommand(op, codec)`, decode the slot to a `HostCommand` and run it
+ *     through the one `applyHostCommand` (the same dispatch the typed queue
+ *     uses). This is the generic cross-thread and wire host-write path.
+ *   - `on(op, applier)`, a raw ctx-aware handler for a consumer's own ring ops
  *     that aren't generic host commands (e.g. the game's `spawn_unit`, which runs
  *     a BFS placement + game spawn). Same drain, same ring: the "one bus".
  *
- * Opcodes + codecs are CONSUMER-supplied — the engine ships the mechanism and the
+ * Opcodes + codecs are consumer-supplied, the engine ships the mechanism and the
  * `ring_*_codec` factories, never the opcode numbers (mirrors `command_dispatch`).
  *
- * Exactly ONE dispatcher should drain a given ring — a second drain would consume
+ * Exactly one dispatcher should drain a given ring, a second drain would consume
  * the first's slots. The in-process apply system passes its dispatcher via
- * `installHostCommandSeam({ ring })`; a system that owns a timing-coupled drain
+ * `installHostCommandSeam({ ring })`. A system that owns a timing-coupled drain
  * point (e.g. `wave_spawn`, which must drain between the spatial-index build and
  * the flow-field rebuild) constructs one and calls `drain` itself.
  */
 export declare class HostCommandDispatcher {
-    private readonly appliers;
+    private readonly _appliers;
     /** Bind a raw ctx-aware applier to `opCode`. Re-binding replaces. */
     on(opCode: number, applier: RingCommandApplier): this;
-    /** Unbind `opCode` (M15). Returns whether a binding was removed; subsequent
+    /** Unbind `opCode`. Returns whether a binding was removed. Subsequent
      * slots carrying it hit the unknown-opcode path. */
     off(opCode: number): boolean;
     /** Bind a `HostCommand` codec to `opCode`: each matching slot is decoded and
-     * run through `applyHostCommand` — the SAME dispatch the typed queue uses.
-     * A drain-time `tap` (record/replay, #702) sees the decoded command before it
+     * run through `applyHostCommand`, the same dispatch the typed queue uses.
+     * A drain-time `tap` (record and replay) sees the decoded command before it
      * applies, so ring-sourced commands share one log with the typed transport. */
     onCommand(opCode: number, codec: PayloadCodec<HostCommand>): this;
     /** Drain every pending slot, dispatching each to its bound applier. Unbound
-     * opcodes are skipped (the read head still advances — matching
-     * `drainCommandRing` / `CommandDispatcher`). Returns slots drained. `tap`,
-     * when present, is forwarded to each applier as the record/replay hook (#702);
-     * only `onCommand`-bound (generic `HostCommand`) opcodes surface to it. */
+     * opcodes are skipped (the read head still advances, matching
+     * `drainCommandRing` and `CommandDispatcher`). Returns slots drained. `tap`,
+     * when present, is forwarded to each applier as the record and replay hook.
+     * Only an `onCommand`-bound (generic `HostCommand`) opcode surfaces to it. */
     drain(ctx: SystemContext, view: DataView, ringOff: number, tap?: (cmd: HostCommand) => void): number;
 }
 /**
- * A per-tick sink the apply system feeds drained commands into — the record side
- * of record/replay (#702). Declared structurally HERE (not imported from
+ * A per-tick sink the apply system feeds drained commands into, the record side
+ * of record and replay. Declared structurally here (not imported from
  * `command_log.ts`) so the seam needs no dependency on the recorder: the one-way
  * edge is `command_log` → `host_commands`, never back. {@link HostCommandRecorder}
  * is the in-tree implementation.
  *
- * The protocol the apply system follows: at each UPDATE-phase drain it calls
- * `openTick(tick, dt)` to open that tick's bucket; STARTUP-phase drains skip
+ * The protocol the apply system follows: at each `UPDATE`-phase drain it calls
+ * `openTick(tick, dt)` to open that tick's bucket. A `STARTUP`-phase drain skips
  * `openTick`, so seed-time commands land in the recorder's startup bucket. Then
  * every applied command (both transports) is handed to `record`.
  */
@@ -252,33 +252,51 @@ export interface HostCommandSink {
 /** Options for {@link installHostCommandSeam}. */
 export interface HostCommandSeamOptions {
     /** Schedule phases whose head drains the queue. Default
-     * `[PRE_STARTUP, PRE_UPDATE]` — seed-time edits plus every frame. */
-    readonly schedules?: readonly SCHEDULE[];
+     * `[PRE_STARTUP, PRE_UPDATE]`, seed-time edits plus every frame. Either
+     * spelling of a phase is accepted, so a plugin drains at the phase its own
+     * `addPhase` returned. A phase of the startup loop drains at seed time, and
+     * a recorder buckets it as startup rather than as a tick. */
+    readonly schedules?: readonly SchedulePhase[];
     /** Apply-system name (diagnostics). Default `"host_command_apply"`. */
     readonly name?: string;
-    /** When provided, the apply system ALSO drains the world's SAB `command_ring`
-     * through this dispatcher at each schedule head — the cross-thread / wire
+    /** When provided, the apply system also drains the world's SAB `command_ring`
+     * through this dispatcher at each schedule head, the cross-thread and wire
      * transport, resolving to the same `applyHostCommand` as the typed queue.
-     * The ECS `Store` always allocates a ring; if one is somehow absent
+     * The ECS `Store` always allocates a ring. If one is somehow absent
      * (`command_ring_off === 0`) the ring drain is a no-op. Bind opcodes with the
      * `ring_*_codec` factories, or `dispatcher.on` for a consumer's own ops. */
     readonly ring?: HostCommandDispatcher;
-    /** When provided, every command the apply system drains — from BOTH transports
-     * (typed queue + `onCommand`-bound ring ops) — is logged into this sink,
-     * tagged with the tick + `dt`, for record/replay (#702). Off by default: an
+    /** When provided, every command the apply system drains, from both transports
+     * (typed queue and `onCommand`-bound ring ops), is logged into this sink,
+     * tagged with the tick and the `dt`, for record and replay. Off by default: an
      * un-recorded seam keeps the original tap-free drain and pays nothing.
-     * {@link HostCommandRecorder} is the in-tree sink; replay it with
+     * {@link HostCommandRecorder} is the in-tree sink. Replay it with
      * `replayCommandLog`. */
     readonly recorder?: HostCommandSink;
 }
 /**
- * Tear down a seam installed by {@link installHostCommandSeam} (M15): removes
+ * Tear down a seam installed by {@link installHostCommandSeam}: removes
  * its apply systems from the world's schedule and clears any still-buffered
  * commands. The queue itself stays usable as a buffer, but nothing drains it
  * until a new seam is installed. No-op (returns `false`) if `queue` was not
  * produced by `installHostCommandSeam` on this world.
  */
 export declare function uninstallHostCommandSeam(ecs: ECS, queue: HostCommandQueue): boolean;
+/**
+ * Install the write seam on `world`: registers the blessed `exclusive`
+ * command-apply system at the head of the given schedules and returns the
+ * {@link HostCommandQueue} to enqueue into. Opt-in and explicit, the write
+ * counterpart to the Solid plugin's `solid()` read view.
+ *
+ * Call this before adding your own systems and before `ecs.startup()`: the
+ * apply system must be registered first so insertion order runs it at the head
+ * of its phase (a phase has no dedicated "first" slot), and the PRE_STARTUP
+ * drain only fires if it exists before startup.
+ *
+ * Lives in the world core, and not in a plugin: unlike the read side there is
+ * no framework dependency to quarantine. This is pure ECS plumbing over the
+ * deferred buffers and `SystemContext` the core already owns.
+ */
 export declare function installHostCommandSeam(ecs: ECS, opts?: HostCommandSeamOptions): HostCommandQueue;
 export {};
 //# sourceMappingURL=host_commands.d.ts.map