@oasys/oecs 0.3.0 → 0.4.0

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

@@ -0,0 +1,265 @@
+import { StoreHeader } from './header';
+import { ArchetypeDescriptor, TypeTagValue } from './descriptor';
+import { BufferAllocator } from './allocator';
+import { COMMAND_RING_DEFAULT_CAPACITY_SLOTS } from './command_ring';
+import { ENTITY_INDEX_DEFAULT_CAPACITY } from './entity_index';
+import { EVENT_RING_DEFAULT_CAPACITY_SLOTS } from './event_ring';
+import { StoreRegionSpec } from './region_table';
+/** Caller-facing column spec — no `byte_off` yet, the store computes it. */
+export interface ColumnSpec {
+    readonly componentId: number;
+    readonly fieldId: number;
+    readonly typeTag: TypeTagValue;
+}
+/** Caller-facing archetype spec — no `column_count` (derived) and no
+ * `byte_off`s in the columns; both are computed during sizing. */
+export interface ArchetypeSpec {
+    readonly archetypeId: number;
+    /** Component bitmask, `COMPONENT_MASK_WORDS` little-endian u32 words. */
+    readonly componentMask: readonly number[];
+    readonly rowCapacity: number;
+    readonly columns: readonly ColumnSpec[];
+}
+/** A single column's view after allocation. The `byte_off` matches what
+ * was recorded in the layout descriptor; `view` is a TypedArray of the
+ * right element type, length `row_capacity`, backed by the SAB. */
+export interface ColumnView {
+    readonly componentId: number;
+    readonly fieldId: number;
+    readonly typeTag: TypeTagValue;
+    readonly byteOff: number;
+    readonly stride: number;
+    readonly view: AnyTypedArray;
+}
+/** Views for all columns in a single archetype, indexed by a numeric
+ * key encoding `(component_id, field_id)` so a (cid, fid) pair maps to
+ * its column in O(1). The encoding (see `columnKey`) is dense over
+ * (cid: 0..65535, fid: 0..65535), letting V8 keep this as a
+ * Number-keyed `Map` — meaningfully faster than the previous string
+ * keys (no per-lookup template-string allocation, no string hashing).
+ * The row order matches `ArchetypeSpec.columns`. The
+ * `component_mask` words mirror what's in the SAB layout descriptor so
+ * `growColumnStore` (and any other carry-forward path) doesn't have to
+ * re-parse the descriptor region. */
+export interface ArchetypeViews {
+    readonly archetypeId: number;
+    /** Component bitmask, `COMPONENT_MASK_WORDS` little-endian u32 words. */
+    readonly componentMask: readonly number[];
+    readonly rowCapacity: number;
+    readonly columns: ReadonlyMap<number, ColumnView>;
+    readonly columnsInOrder: readonly ColumnView[];
+}
+export interface ColumnStore {
+    /** The backing buffer. `ArrayBufferLike` because the store is backing-agnostic:
+     * a `SharedArrayBuffer` for the SAB/WASM/worker profile, or a plain resizable
+     * `ArrayBuffer` for the pure-TS heap profile (`heapArraybufferAllocator`).
+     * Consumers that genuinely require sharing (worker transfer, WASM memory)
+     * narrow back to `SharedArrayBuffer` at their boundary. */
+    readonly buffer: ArrayBufferLike;
+    readonly view: DataView;
+    readonly header: StoreHeader;
+    /** Indexed by `archetype_id`. */
+    readonly archetypes: ReadonlyMap<number, ArchetypeViews>;
+}
+export type AnyTypedArray = Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array;
+/** Pack `(component_id, field_id)` into a single non-negative integer so
+ * `ArchetypeViews.columns` can be a `Map<number, ColumnView>` instead of
+ * `Map<string, ColumnView>`. V8's number-keyed `Map` skips the
+ * string-hash + string-equality every lookup pays, and template-string
+ * keys (`"${cid}:${fid}"`) allocated a fresh string on every call. On
+ * the lazy-registration ramp-up the per-extend `refreshViews`
+ * walks `N` × `cols` of these lookups for `N` archetypes, so the saving
+ * compounds quadratically.
+ *
+ * Encoding: `(component_id << 16) | field_id`. `component_id` is bounded
+ * by `STORE_DESCRIPTOR_COMPONENT_LIMIT` (the registration cap, 128), well
+ * below 65536. `field_id` is bounded by the component's schema width,
+ * single digits in practice. */
+export declare function columnKey(componentId: number, fieldId: number): number;
+/** First byte offset the SAB layout math cannot represent: 2³¹.
+ *
+ * `alignUp` rounds with `& ~(align-1)`, and JS bitwise operators coerce
+ * their operands to **signed** 32-bit integers (`ToInt32`). Once an offset
+ * reaches 2³¹ the result wraps to a negative number (or, for some inputs, a
+ * misaligned positive one), which then flows straight into
+ * `new Uint8Array(buffer, byte_off, …)` — either a thrown `RangeError` deep in
+ * the TypedArray ctor or, worse, a silently wrong view overlapping another
+ * column. The 256 MiB default allocator cap (`growableSabAllocator`) keeps
+ * real matches three orders of magnitude below this, but the cap is tunable
+ * and callers are invited to raise it for bigger worlds — so the layout step
+ * guards the hard 2³¹ ceiling explicitly rather than relying on the policy
+ * cap to stay in front of it (#382). */
+export declare const STORE_MAX_BYTE_OFFSET: number;
+/** Thrown when a SAB column layout would place an offset at or beyond
+ * {@link STORE_MAX_BYTE_OFFSET} (2³¹), past which the signed-32-bit bitwise
+ * `alignUp` can no longer produce correct offsets. This is a hard ceiling,
+ * not the (tunable, much lower) 256 MiB allocator cap — see #382. */
+export declare class StoreLayoutOverflowError extends Error {
+    constructor(byteOff: number);
+}
+/** Round `off` up to the next multiple of `align`. `align` must be a power
+ * of two (1/2/4/8 here, all `TYPE_TAG_STRIDE` values).
+ *
+ * Throws {@link StoreLayoutOverflowError} when the rounded offset would reach
+ * {@link STORE_MAX_BYTE_OFFSET}, because the `& ~(align-1)` step coerces to a
+ * signed 32-bit int and wraps past 2³¹ (#382). The guard fires before the
+ * bitwise op so any returned offset is always a correct, in-range value.
+ * Shared by `extend.ts` and `grow.ts`, whose in-place paths compute tail
+ * byte_offs without going through `planLayout`. */
+export declare function alignUp(off: number, align: number): number;
+/** Build the layout-descriptor-region descriptors (with `byte_off` and
+ * `stride` filled in) and return both them and the byte offset just past
+ * the last column — i.e. the total SAB size.
+ *
+ * `headroomBytes` reserves slack at the end of the descriptor region — ON
+ * TOP OF the natural size for `specs` — so future extends can append new
+ * descriptor entries without shifting existing column byte_offs. Used by
+ * the growable-SAB path (#237 Option A) — column views stay valid across
+ * `extendColumnStore` because their byte_offs don't move.
+ *
+ * Additive, not a floor (#541): `regionSize = natural + headroom`, NOT
+ * `max(natural, headroom)`. A floor only yields slack while `natural` is
+ * below it; the moment the descriptor region outgrows the floor (the #237
+ * headroom exhausts and a realloc re-plans the merged spec set), a floor
+ * would size the region to exactly `natural` — zero slack — and every
+ * subsequent extend would take the slow realloc path forever after. The
+ * additive form re-creates the same `headroom` margin on every realloc.
+ * For the engine's empty-seed store (`createColumnStore([], …)`, where
+ * `natural === 0`) the two forms coincide, so this is behaviour-identical
+ * for the only production caller. */
+declare function planLayout(specs: readonly ArchetypeSpec[], regionOff: number, headroomBytes?: number): {
+    descriptors: ArchetypeDescriptor[];
+    totalBytes: number;
+    regionBytes: number;
+};
+/** Exposed for use by `extendColumnStore`'s in-place fast path so it can
+ * compute new column byte_offs without re-running `planLayout`. */
+export { planLayout as _planLayout };
+/** Optional configuration for `createColumnStore`. */
+export interface CreateColumnStoreOptions {
+    /** Extra slack to reserve at the end of the layout descriptor region,
+     * ON TOP OF the natural size for `specs` (#541 — additive, not a floor).
+     * The descriptor region is padded with this many unused bytes so future
+     * `extendColumnStore` calls can append new archetype descriptors into the
+     * slack without shifting existing column byte_offs. Pairs with
+     * `growableSabAllocator` to give the #237 Option A fast path: existing
+     * TypedArray column views stay valid across extends because their offsets
+     * and the underlying buffer both stay put.
+     *
+     * Carried forward as a policy across the realloc-and-republish path: the
+     * value lives on `ColumnStoreInternal._reservedDescriptorBytes` and
+     * `optionsFromOld` re-applies it, so a store that exhausts its headroom
+     * and reallocs gets a fresh margin rather than dropping to zero slack and
+     * going permanently slow (#541). */
+    readonly reservedDescriptorBytes?: number;
+    /** When provided, allocates a command ring (#171 §7.5, Phase 4) inside
+     * the SAB at a stable offset right after the 48-byte header. Slot
+     * count MUST be a power of two; `COMMAND_RING_DEFAULT_CAPACITY_SLOTS`
+     * (256) is the canonical value. Omitted ⇒ no ring; `command_ring_off`
+     * stays at 0 ("absent"); existing test fixtures with hand-rolled SABs
+     * see the legacy layout (descriptor region immediately after header).
+     *
+     * Sizing the ring this way — between header and descriptor region —
+     * keeps `command_ring_off` stable across `extendColumnStore` /
+     * `growColumnStore` calls, since those grow the descriptor region and
+     * the column tail but never the bytes between header and descriptor. */
+    readonly commandRingCapacitySlots?: number;
+    /** When provided, allocates the entity-index region (#245 / Phase 4
+     * PR 4B) inside the SAB at a stable offset between the command ring
+     * (or header) and the descriptor region. Holds `(generations,
+     * archetypes, rows)` triples indexed by entity slot; the engine's
+     * `Store` populates them as entities are created/moved/destroyed,
+     * and Zig systems read them to resolve cross-entity targets without
+     * a callback. Capacity is in *slots* (entities), not bytes; each
+     * slot is 12 bytes. Omitted ⇒ no region; `entity_index_off` stays
+     * at 0 ("absent"). The engine's Store always sets it to
+     * `ENTITY_INDEX_DEFAULT_CAPACITY`; bare-SAB tests can leave it
+     * absent. */
+    readonly entityIndexCapacity?: number;
+    /** When provided, allocates the event ring (#247 / Phase 4 PR 4C)
+     * inside the SAB at a stable offset between the entity-index region
+     * and the descriptor region. Same SPSC shape as the command ring;
+     * carries ECS signal payloads so Zig systems can emit and consume
+     * them during `tick()` without callbacks into TS.
+     *
+     * Slot count MUST be a power of two; `EVENT_RING_DEFAULT_CAPACITY_SLOTS`
+     * (256) is the canonical value. Omitted ⇒ no ring; `event_ring_off`
+     * stays at 0 ("absent"); existing test fixtures with hand-rolled
+     * SABs see the pre-#247 layout. */
+    readonly eventRingCapacitySlots?: number;
+    /** When provided, allocates the action ring (#291 / Phase 5 PR 5L)
+     * inside the SAB at a stable offset between the entity-index/event-ring
+     * and the region-table directory. Main writes encoded actions to it;
+     * the sim worker drains them on each apply.
+     *
+     * Slot count MUST be a power of two; `ACTION_RING_DEFAULT_CAPACITY_SLOTS`
+     * (256) is the canonical value. Omitted ⇒ no ring; `action_ring_off`
+     * stays at 0 ("absent"); bare-SAB tests skip it. (Engine mechanism — the
+     * `Store` allocates one always-on; it is no longer a public ECS option.) */
+    readonly actionRingCapacitySlots?: number;
+    /** Consumer-declared SAB regions (#623). Each `StoreRegionSpec` carries an
+     * opaque `region_id`, a precomputed byte size, and an `init` closure; the
+     * engine lays them out after the mechanism regions, writes a generic
+     * region-table directory (`region_table.ts`) keyed by `region_id`, and
+     * snapshots/restores them across a grow/extend. The engine never
+     * interprets `region_id` — a game (e.g. `@internal/sim`'s region specs)
+     * owns it. Omitted ⇒ no consumer regions; `region_table_off` stays 0. */
+    readonly regions?: readonly StoreRegionSpec[];
+    /** Byte size of the always-before-descriptor sim-bindings region (v5 /
+     * "SAB-is-the-interface"). A consumer that opts into a WASM backend supplies
+     * its own size here — `@internal/sim`'s `SIM_BINDINGS_BYTES`, computed from
+     * the game's binding manifest. The engine treats the region as opaque bytes:
+     * it reserves the block at `bindings_off` (right before the descriptor
+     * region, so the offset is stable across grow/extend) and the host writes the
+     * `(component_id, field_id)` IDs into it via `write_sim_bindings`.
+     *
+     * Omitted / 0 ⇒ NO bindings region (`bindings_off` stays 0, "absent") — the
+     * default for a pure-TS game that pays nothing for the WASM seam. This used
+     * to be the engine-baked `SIM_BINDINGS_BYTES` ABI constant reflected from the
+     * game's Zig struct; #625 de-welded it so a manifest edit no longer dirties
+     * the engine ABI golden. Re-derived across realloc by `optionsFromOld`
+     * (= `layout_descriptor_off - bindings_off`), so it survives grow/extend
+     * without a carried policy field. */
+    readonly bindingsRegionBytes?: number;
+}
+/** Internal `ColumnStore` extension carrying the descriptor-region byte
+ * size. Used by the in-place extend path to know where the next
+ * descriptor entry should be written (= `regionOff + region_bytes_used`,
+ * tracked separately) and how much headroom remains. */
+export interface ColumnStoreInternal extends ColumnStore {
+    readonly _regionBytes: number;
+    readonly _allocator: BufferAllocator;
+    /** The `reservedDescriptorBytes` policy this store was created with
+     * (the additive descriptor-region headroom margin; 0 when none). Carried
+     * with the store — NOT re-derivable from the SAB bytes, since `_regionBytes`
+     * holds the absolute region size (natural + this), and once `natural`
+     * outgrows the margin the two are indistinguishable. The realloc slow path
+     * reads it via `optionsFromOld` and re-reserves the same margin, so a
+     * store that exhausts its headroom and reallocs keeps taking the #237
+     * in-place fast path instead of going permanently slow (#541). The
+     * `*_in_place` paths carry it forward verbatim. */
+    readonly _reservedDescriptorBytes: number;
+}
+/** Allocate a SAB sized for `specs`, write the header + layout descriptor,
+ * and construct one TypedArray view per column.
+ *
+ * The returned `ColumnStore` is the source of truth for "where every column
+ * lives in this SAB". `view_stamp` is initialised to 0 — a Phase 4 SAB
+ * grow flow will bump it. (#171 §6.1.4 / §8.1) */
+export declare function createColumnStore(specs: readonly ArchetypeSpec[], allocator?: BufferAllocator, options?: CreateColumnStoreOptions): ColumnStore;
+/** Default command-ring slot count used by `ECS.Store` when constructing
+ * its SAB. Re-exported here so the Store doesn't reach across modules. */
+export { COMMAND_RING_DEFAULT_CAPACITY_SLOTS };
+/** Default entity-index capacity used by `ECS.Store` when constructing
+ * its SAB. Re-exported alongside `COMMAND_RING_DEFAULT_CAPACITY_SLOTS`. */
+export { ENTITY_INDEX_DEFAULT_CAPACITY };
+/** Default event-ring slot count used by `ECS.Store` when constructing
+ * its SAB. Re-exported alongside the other defaults. */
+export { EVENT_RING_DEFAULT_CAPACITY_SLOTS };
+/** Build the `ArchetypeViews` map from a SAB and its parsed descriptors.
+ * Shared by `createColumnStore` (fresh allocation, byte_offs just computed)
+ * and `restoreColumnStore` (existing allocation, byte_offs read out of the
+ * snapshot). Either way the views land at the byte_offs the descriptors
+ * already carry — this helper does not plan layout. */
+export declare function buildArchetypeViews(buffer: ArrayBufferLike, descriptors: readonly ArchetypeDescriptor[]): Map<number, ArchetypeViews>;
+//# sourceMappingURL=column_store.d.ts.map

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

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

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

@@ -0,0 +1,52 @@
+/**
+ * Command dispatch — the generic drain surface a consumer registers against
+ * (#624, game-agnostic ECS / epic #616).
+ *
+ * The command ring (`command_ring.ts`) carries opaque `(opCode, payload)`
+ * slots; the engine never interprets a code. This module is the thin,
+ * game-free glue that lets a consumer bind a payload codec + typed handler to
+ * each opcode and drain the ring in one call. The opcode enum and the codecs
+ * themselves stay consumer-owned — for our game they live in
+ * `@internal/sim`'s `command_payloads.ts` (`COMMAND_OP`, `SpawnUnitFields`,
+ * `encode/decode_spawn_unit_payload`); the engine knows none of those names.
+ *
+ * Usage:
+ *
+ *   const dispatcher = new CommandDispatcher()
+ *     .on(COMMAND_OP.spawn_unit, spawn_unit_codec, (fields) => spawn(fields));
+ *   dispatcher.drain(view, ringOff); // runs after wasm.tick() returns
+ *
+ * Unregistered opcodes are skipped (the same forward-compatible stance as the
+ * raw `drainCommandRing` handler that ignores codes it doesn't know).
+ */
+/** Decode (and, symmetrically, encode) the 15-byte payload region of a
+ * command slot into a typed value. A consumer supplies one per opcode it
+ * cares about; the engine only ever calls `decode` during a drain, but the
+ * `encode` half keeps the codec a single round-trippable unit (and is what
+ * test/host producers use to push). */
+export interface PayloadCodec<T> {
+    /** Encode `value` into a fresh `COMMAND_RING_SLOT_BYTES - 1` (15) byte
+     * payload, ready for `pushCommand(view, off, op, payload)`. */
+    encode(value: T): Uint8Array;
+    /** Decode a 15-byte payload back into the typed value. */
+    decode(payload: Uint8Array): T;
+}
+/**
+ * Registry mapping command opcodes to a payload codec + handler. Generic over
+ * the consumer's opcodes — the engine ships the mechanism; the game supplies
+ * the codes and codecs.
+ */
+export declare class CommandDispatcher {
+    private readonly bindings;
+    /** Register `handler` for `opCode`, decoding each slot with `codec`.
+     * Re-registering an opcode replaces its binding. `opCode` must be a u8 in
+     * `[1, 255]` — `0` is the reserved empty-slot marker and can never carry a
+     * command. Returns `this` for chaining. */
+    on<T>(opCode: number, codec: PayloadCodec<T>, handler: (value: T) => void): this;
+    /** Drain every pending command, decoding + dispatching each to its
+     * registered handler. Commands with no registered opcode are skipped.
+     * Returns the number of slots drained (including skipped ones — the ring is
+     * advanced regardless, matching `drainCommandRing`). */
+    drain(view: DataView, ringOff: number): number;
+}
+//# sourceMappingURL=command_dispatch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command_dispatch.d.ts","sourceRoot":"","sources":["../../../src/core/store/command_dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;;uCAIuC;AACvC,MAAM,WAAW,YAAY,CAAC,CAAC;IAC9B;mEAC+D;IAC/D,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC;IAC7B,0DAA0D;IAC1D,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,CAAC,CAAC;CAC/B;AAWD;;;;GAIG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAE7D;;;+CAG2C;IAC3C,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,IAAI;IAgBhF;;;4DAGwD;IACxD,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;CAO9C"}

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

@@ -0,0 +1,107 @@
+/**
+ * Command ring — WASM-side producer / TS-side consumer SPSC ring buffer
+ * for structural-change intents emitted during `sim.tick()`. Plan §7.5
+ * (`docs/ideas/buffer-wasm-sim-plan-2026-05-14T1600.md`).
+ *
+ * Layout:
+ *
+ *   [ write_head:   u32 ]   slot 0..N-1, monotonic (NOT slot-modulo)
+ *   [ read_head:    u32 ]   slot 0..N-1, monotonic
+ *   [ capacity:     u32 ]   slot count, power-of-two
+ *   [ overflow:     u32 ]   0 = OK; 1 = WASM exhausted the ring this tick
+ *   [ slot 0:       16 B ]  opCode: u8, payload: [15]u8
+ *   [ slot 1:       16 B ]  ...
+ *   ...
+ *
+ * SPSC contract (Phase 4 scope):
+ *   - Producer: WASM `sim.tick()`. Pushes 0..N commands during one tick;
+ *     bumps `write_head` after each.
+ *   - Consumer: TS host, immediately after `wasm.tick()` returns. Drains
+ *     0..N pending commands; bumps `read_head` after each.
+ *   - The two never run concurrently in Phase 4 (single host thread
+ *     orchestrates both). Phase 5's worker offload promotes the head
+ *     bumps to `Atomics.store`; that's an additive change without
+ *     altering the layout.
+ *
+ * Overflow:
+ *   - If WASM would write a slot when (`write_head - read_head == capacity`),
+ *     it sets `overflow = 1` and drops the command. TS treats overflow as
+ *     a hard error in dev builds; production logs and continues (a command
+ *     might be lost rather than crash the host).
+ *
+ * Slot format (plan §7.5):
+ *   byte 0:       opCode (u8). 0 is reserved as the empty-slot marker
+ *                 (`COMMAND_OP_EMPTY`); all other codes are consumer-defined.
+ *                 The engine never interprets a code — it drains
+ *                 `(opCode, payload)` and hands them to the attached
+ *                 consumer, which owns the opcode enum + payload codecs (the
+ *                 game's live in `@internal/sim`'s `command_payloads.ts`).
+ *   bytes 1..15:  payload, op-specific. Multi-byte fields may be
+ *                 unaligned within the payload; readers must use byte-
+ *                 oriented helpers (DataView in TS, `mem.readInt` in Zig).
+ *
+ * The ring lives BEFORE the layout-descriptor region in the SAB (right
+ * after the 32-byte header) so its offset is stable across descriptor /
+ * column-region growth. The host writes `header.command_ring_off` to
+ * point at it during `createColumnStore`; absent ring is signalled by
+ * `command_ring_off === 0`.
+ */
+/** Total bytes for the ring header. */
+export declare const COMMAND_RING_HEADER_BYTES = 16;
+/** Fixed slot size — 1-byte opCode + 15-byte payload. */
+export declare const COMMAND_RING_SLOT_BYTES = 16;
+/** Default ring capacity in slots. 256 × 16 B = 4 KiB of ring data plus
+ * 16 B header. Sized for the worst-case burst (peak spawn intents per
+ * tick) × small safety margin. Tune up if a Phase 4 burst pushes past it
+ * in the bench harness. */
+export declare const COMMAND_RING_DEFAULT_CAPACITY_SLOTS = 256;
+/** Byte offsets within the ring header. Mirrored on the Zig side in
+ * `packages/sim/src/command_ring.zig` — keep in sync. */
+export declare const COMMAND_RING_HEADER_OFFSETS: {
+    readonly write_head: 0;
+    readonly read_head: 4;
+    readonly capacity_slots: 8;
+    readonly overflow_flag: 12;
+};
+/** Op-code `0` is reserved across the SAB layer as the empty-slot marker
+ * so a zero-initialised SAB doesn't appear to hold a valid command (mirror
+ * of `EVENT_OP_EMPTY`). All non-zero codes are opaque to the engine —
+ * the attached consumer owns the opcode enum + payload codecs (the game's
+ * `COMMAND_OP` + `SpawnUnitFields` live in `@internal/sim`). */
+export declare const COMMAND_OP_EMPTY = 0;
+/** Total bytes the ring occupies for `capacity_slots` slots. */
+export declare function commandRingBytes(capacitySlots: number): number;
+export declare class CommandRingError extends Error {
+    constructor(message: string);
+}
+/** Initialise the ring header at `ringOff` in the SAB. Zeroes
+ * `write_head`, `read_head`, and `overflow_flag`; sets `capacity_slots`.
+ * Slot bytes are left as-is (callers normally allocate the ring on a
+ * fresh, zero-initialised SAB). */
+export declare function initCommandRing(view: DataView, ringOff: number, capacitySlots: number): void;
+/** Read live ring-header field. */
+export declare function ringWriteHead(view: DataView, ringOff: number): number;
+export declare function ringReadHead(view: DataView, ringOff: number): number;
+export declare function ringCapacitySlots(view: DataView, ringOff: number): number;
+export declare function ringOverflow(view: DataView, ringOff: number): boolean;
+/** Pending command count = `(write_head - read_head) mod 2^32`. The
+ * `>>> 0` keeps the result a u32 in the wrap-around case (rings live for
+ * the host's lifetime; 2^32 commands at 50 Hz ≈ 2 years, but the
+ * arithmetic should be correct regardless). */
+export declare function pendingCommandCount(view: DataView, ringOff: number): number;
+/** Push a command into the ring from the TS side. Production producer is
+ * WASM (via `command_ring.zig`); this is for host-side tests and for
+ * symmetric tests across the two sides. Returns `false` on overflow and
+ * sets the overflow flag. Payload must be exactly 15 bytes. */
+export declare function pushCommand(view: DataView, ringOff: number, opCode: number, payload: Uint8Array): boolean;
+/** Read one command from the ring. Returns opCode (0 = empty/no
+ * command) and fills `outPayload` (15 bytes) with the slot's payload.
+ * When 0 is returned, `outPayload` is untouched. */
+export declare function popCommand(view: DataView, ringOff: number, outPayload: Uint8Array): number;
+/** Visit every pending command and bump `read_head` past them. Yields
+ * `{ opCode, payload }` per slot where `payload` is a freshly-copied
+ * 15-byte Uint8Array (so the handler can hold it past the next pop
+ * without aliasing the ring). Stops when the ring is empty. Used by the
+ * TS host drain that runs right after `wasm.tick()` returns. */
+export declare function drainCommandRing(view: DataView, ringOff: number, handler: (opCode: number, payload: Uint8Array) => void): number;
+//# sourceMappingURL=command_ring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command_ring.d.ts","sourceRoot":"","sources":["../../../src/core/store/command_ring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,uCAAuC;AACvC,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,yDAAyD;AACzD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;;;2BAG2B;AAC3B,eAAO,MAAM,mCAAmC,MAAM,CAAC;AAEvD;yDACyD;AACzD,eAAO,MAAM,2BAA2B;;;;;CAK9B,CAAC;AAEX;;;;gEAIgE;AAChE,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9D;AASD,qBAAa,gBAAiB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI3B;AAED;;;mCAGmC;AACnC,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAU5F;AAED,mCAAmC;AACnC,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAErE;AACD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpE;AACD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE;AACD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAErE;AAED;;;+CAG+C;AAC/C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;+DAG+D;AAC/D,wBAAgB,WAAW,CAC1B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,UAAU,GACjB,OAAO,CAmCT;AAED;;oDAEoD;AACpD,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAiB1F;AAED;;;;gEAIgE;AAChE,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,KAAK,IAAI,GACpD,MAAM,CAWR"}

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

@@ -0,0 +1,80 @@
+import { COLUMN_DESCRIPTOR_BYTES, COLUMN_DESCRIPTOR_OFFSETS, ARCHETYPE_DESCRIPTOR_HEADER_BYTES, ARCHETYPE_DESCRIPTOR_OFFSETS, COMPONENT_MASK_WORDS } from './__generated__/abi';
+export { COLUMN_DESCRIPTOR_BYTES, COLUMN_DESCRIPTOR_OFFSETS, ARCHETYPE_DESCRIPTOR_HEADER_BYTES, ARCHETYPE_DESCRIPTOR_OFFSETS, COMPONENT_MASK_WORDS };
+/** type_tag values for `ColumnDescriptor.type_tag`. The order matches the
+ * TypedArrayTag union in `packages/std/type_primitives` so a tag's element
+ * width is `TYPE_TAG_STRIDE[tag]`. */
+export declare const TYPE_TAG: {
+    readonly u8: 0;
+    readonly i8: 1;
+    readonly u16: 2;
+    readonly i16: 3;
+    readonly u32: 4;
+    readonly i32: 5;
+    readonly f32: 6;
+    readonly f64: 7;
+};
+export type TypeTagValue = (typeof TYPE_TAG)[keyof typeof TYPE_TAG];
+/** Element width in bytes for each `TYPE_TAG`. Indexed by tag value so a
+ * `stride = TYPE_TAG_STRIDE[tag]` lookup is O(1) array access. */
+export declare const TYPE_TAG_STRIDE: Readonly<Record<TypeTagValue, number>>;
+/** String-tag → numeric-tag bridge. `TypedArrayTag` ("u8", "f32", …) is the
+ * vocabulary the TS-side component registry speaks; `TypeTagValue` is the
+ * numeric enum the SAB descriptors carry on the wire. Bridging happens at
+ * the ECS↔SAB seam — Archetype layouts come in as strings, ColumnSpecs go
+ * out as integers. */
+export declare const TYPED_ARRAY_TAG_TO_TYPE_TAG: {
+    readonly u8: 0;
+    readonly i8: 1;
+    readonly u16: 2;
+    readonly i16: 3;
+    readonly u32: 4;
+    readonly i32: 5;
+    readonly f32: 6;
+    readonly f64: 7;
+};
+export interface ColumnDescriptor {
+    readonly componentId: number;
+    readonly fieldId: number;
+    readonly typeTag: TypeTagValue;
+    /** Byte offset of the column's first row, measured from SAB byte 0. */
+    readonly byteOff: number;
+    /** Element width in bytes; should always equal `TYPE_TAG_STRIDE[type_tag]`. */
+    readonly stride: number;
+}
+export declare function writeColumnDescriptor(view: DataView, off: number, c: ColumnDescriptor): void;
+export declare function readColumnDescriptor(view: DataView, off: number): ColumnDescriptor;
+/** Number of distinct components the cross-language ECS supports:
+ * `COMPONENT_MASK_WORDS × 32` bits in the SAB archetype descriptor mask. The
+ * Zig side matches archetypes purely on this mask, so a component whose ID is
+ * ≥ this limit would be invisible there while the heap-side `BitSet` stayed
+ * correct — silently conflating archetypes that differ only in such a
+ * component. `Store.registerComponent` enforces this as a hard registration
+ * ceiling so the overflow fails loudly instead (#381). The mask is sized to
+ * the `BitSet`'s `INITIAL_WORD_COUNT`, so a registry within the limit never
+ * grows a component mask past its initial words. */
+export declare const STORE_DESCRIPTOR_COMPONENT_LIMIT: number;
+export interface ArchetypeDescriptor {
+    readonly archetypeId: number;
+    /** Component bitmask, `COMPONENT_MASK_WORDS` little-endian u32 words. Word
+     * `w` holds component IDs in `[w*32, w*32+32)`. */
+    readonly componentMask: readonly number[];
+    readonly rowCount: number;
+    readonly rowCapacity: number;
+    /** Enabled-row count `≤ row_count` (#577 / #599). Per-row entity-scan loops in
+     * the WASM sim bound on this so disabled entities (swapped to the tail
+     * `[enabled_count, row_count)`) are not simulated; row-indexed cross-entity
+     * reads still use `row_count`. */
+    readonly enabledCount: number;
+    readonly columns: readonly ColumnDescriptor[];
+}
+/** Total bytes a descriptor will occupy, given its column count. Useful for
+ * planning the layout descriptor region size up front. */
+export declare function archetypeDescriptorBytes(columnCount: number): number;
+export declare function writeArchetypeDescriptor(view: DataView, off: number, d: ArchetypeDescriptor): number;
+export declare function readArchetypeDescriptor(view: DataView, off: number): ArchetypeDescriptor;
+export declare function writeLayoutDescriptorRegion(view: DataView, regionOff: number, descriptors: readonly ArchetypeDescriptor[]): number;
+export declare function readLayoutDescriptorRegion(view: DataView, regionOff: number, archetypeCount: number): readonly ArchetypeDescriptor[];
+/** Total bytes needed for a layout descriptor region holding these archetypes.
+ * Use to size the SAB region between header end and the first column. */
+export declare function layoutDescriptorRegionBytes(descriptors: readonly ArchetypeDescriptor[]): number;
+//# sourceMappingURL=descriptor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../../src/core/store/descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAeH,OAAO,EACN,uBAAuB,EACvB,yBAAyB,EACzB,iCAAiC,EACjC,4BAA4B,EAC5B,oBAAoB,EACpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACN,uBAAuB,EACvB,yBAAyB,EACzB,iCAAiC,EACjC,4BAA4B,EAC5B,oBAAoB,EACpB,CAAC;AAEF;;sCAEsC;AACtC,eAAO,MAAM,QAAQ;;;;;;;;;CASX,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AAEpE;kEACkE;AAClE,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CASjE,CAAC;AAEH;;;;sBAIsB;AACtB,eAAO,MAAM,2BAA2B;;;;;;;;;CAS9B,CAAC;AAUX,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAS5F;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAQlF;AAeD;;;;;;;;oDAQoD;AACpD,eAAO,MAAM,gCAAgC,QAA4B,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;uDACmD;IACnD,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;sCAGkC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC9C;AAED;0DAC0D;AAC1D,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wBAAgB,wBAAwB,CACvC,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,MAAM,EACX,CAAC,EAAE,mBAAmB,GACpB,MAAM,CAoBR;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAuBxF;AAcD,wBAAgB,2BAA2B,CAC1C,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,SAAS,mBAAmB,EAAE,GACzC,MAAM,CAMR;AAED,wBAAgB,0BAA0B,CACzC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACpB,SAAS,mBAAmB,EAAE,CAShC;AAED;yEACyE;AACzE,wBAAgB,2BAA2B,CAC1C,WAAW,EAAE,SAAS,mBAAmB,EAAE,GACzC,MAAM,CAMR"}

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

@@ -0,0 +1,108 @@
+/**
+ * Entity-index SAB region — `EntityID` → `(archetype_id, row, generation)`
+ * lookup table shared with the Zig sim. (#245 / Phase 4 PR 4B)
+ *
+ * Every hot fixed-update system that needs to resolve an `EntityID`
+ * held in a column (e.g. a component field that points at another
+ * entity → that entity's columns) has to do
+ * `entityId → archetype + row` translation. The plan forbids
+ * WASM-into-TS callbacks during `tick()` (§4 / §5.2), so the lookup
+ * tables must live in shared memory.
+ *
+ * Layout:
+ *
+ *   [ length:    u32 ]   high-water index (count of slots ever issued)
+ *   [ capacity:  u32 ]   backing-array length (slots × 1; not bytes)
+ *   [ _pad0:     u32 ]   alignment pad to 16 bytes
+ *   [ _pad1:     u32 ]   ───
+ *   [ generations[capacity]: i32 ]
+ *   [ archetypes[capacity]:  i32 ]
+ *   [ rows[capacity]:        i32 ]
+ *
+ * Sentinels:
+ *   - `generations[i] = 0` (INITIAL_GENERATION) for never-used slots.
+ *     Generation grows by 1 on every destroy; an `EntityID`'s generation
+ *     field matches `generations[index]` iff it's still alive.
+ *   - `archetypes[i] = -1` (UNASSIGNED) when the slot hasn't been placed
+ *     into an archetype, OR when the entity is destroyed.
+ *   - `rows[i]      = -1` (UNASSIGNED) on destroy / not-placed.
+ *
+ * Field width: i32 (signed) on the TS side so `-1` round-trips through
+ * `Int32Array` without unsigned coercion. Zig reads as i32 too — bit
+ * pattern is identical to u32 `0xFFFFFFFF` for the UNASSIGNED case, and
+ * for valid archetype_ids (bounded by `MAX_INDEX = 2^20`) the sign bit
+ * is never set, so signed/unsigned interpretation agrees.
+ *
+ * Region placement: between command ring and descriptor region so the
+ * offset is stable across descriptor / column-region growth (same
+ * property the command ring gets). Grow path (when entityHighWater
+ * exceeds `capacity`) uses `growColumnStore` — slow path, same as
+ * descriptor-region overflow.
+ *
+ * Reading from Zig: see `packages/sim/src/entity_index.zig` for the
+ * symmetric reader.
+ */
+/** Fixed bytes of the region header (length, capacity, two pad u32s for
+ * 16-byte alignment of the i32 arrays that follow). */
+export declare const ENTITY_INDEX_HEADER_BYTES = 16;
+/** Bytes per slot: three i32 columns. */
+export declare const ENTITY_INDEX_BYTES_PER_SLOT = 12;
+/** Byte offsets within the region header. Locked by the
+ * `entity_index.test.ts` golden bytes; any change here is a
+ * `SIM_ABI_VERSION` bump. */
+export declare const ENTITY_INDEX_HEADER_OFFSETS: {
+    readonly length: 0;
+    readonly capacity: 4;
+};
+/** Default initial slot count when the engine creates a Store. Matches
+ * `MAX_INDEX = (1 << 20) - 1 + 1 = 1_048_576` (the EntityID 20-bit index
+ * range, see `entity.ts`), so the region pre-sizes to the entire
+ * addressable entity space and `createEntity` can never run out under
+ * the default. 1M × 12 B ≈ 12 MiB SAB region — virtual memory only;
+ * physical pages allocate lazily via OS page-fault on first touch, so
+ * the typical 1000-entity workload pays for ~12 KiB physical even though the
+ * virtual reservation is 12 MiB.
+ *
+ * Tests / benches can pass a smaller `StoreOptions.entityIndexCapacity`
+ * to bench tighter reservations. A future PR will replace this with
+ * on-demand growth via `growColumnStore` so the default can drop. */
+export declare const ENTITY_INDEX_DEFAULT_CAPACITY: number;
+/** Total region bytes for `capacity` slots: header + 3 i32 columns. */
+export declare function entityIndexRegionBytes(capacity: number): number;
+/** Byte offset of the generations column within the region. */
+export declare function entityIndexGenerationsOff(regionOff: number): number;
+/** Byte offset of the archetype-id column. */
+export declare function entityIndexArchetypesOff(regionOff: number, capacity: number): number;
+/** Byte offset of the row column. */
+export declare function entityIndexRowsOff(regionOff: number, capacity: number): number;
+export declare class EntityIndexError extends Error {
+    constructor(message: string);
+}
+/** Initialise the region header at `regionOff`. Sets `length=0` and
+ * `capacity=<arg>`. The i32 arrays past the header are left untouched
+ * (callers normally allocate the region on a fresh, zero-initialised
+ * SAB; generation 0 is the INITIAL_GENERATION sentinel, archetype/row
+ * sentinels of 0 are caught by `length=0` so no read reaches them). */
+export declare function initEntityIndexRegion(view: DataView, regionOff: number, capacity: number): void;
+/** Read the region's current length (high-water index, ≤ capacity). */
+export declare function entityIndexLength(view: DataView, regionOff: number): number;
+/** Read the region's current capacity (backing-array length). */
+export declare function entityIndexCapacity(view: DataView, regionOff: number): number;
+/** Update the region's length (called from the engine's Store on every
+ * entity allocation that pushes `entityHighWater` past its previous
+ * value). */
+export declare function setEntityIndexLength(view: DataView, regionOff: number, length: number): void;
+/** Materialise the three Int32Array views over the region's column data
+ * for use by the engine's Store. The views live as long as the
+ * SharedArrayBuffer hasn't been reallocated — refresh on `view_stamp`
+ * bump (the engine's `_onBufferResized` callback).
+ *
+ * Three separate views (not a single struct-of-arrays object) because
+ * the engine's hot paths benefit from each being a direct typed-array
+ * read; V8 specialises `arr[i] = v` aggressively for typed arrays. */
+export declare function buildEntityIndexViews(buffer: ArrayBufferLike, regionOff: number, capacity: number): {
+    readonly generations: Int32Array;
+    readonly archetypes: Int32Array;
+    readonly rows: Int32Array;
+};
+//# sourceMappingURL=entity_index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity_index.d.ts","sourceRoot":"","sources":["../../../src/core/store/entity_index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH;uDACuD;AACvD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,yCAAyC;AACzC,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;6BAE6B;AAC7B,eAAO,MAAM,2BAA2B;;;CAI9B,CAAC;AAEX;;;;;;;;;;;qEAWqE;AACrE,eAAO,MAAM,6BAA6B,QAAU,CAAC;AAErD,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO/D;AAED,+DAA+D;AAC/D,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,8CAA8C;AAC9C,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,qCAAqC;AACrC,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI3B;AAED;;;;uEAIuE;AACvE,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACd,IAAI,CASN;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;aAEa;AACb,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAE5F;AAED;;;;;;;sEAOsE;AACtE,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACd;IACF,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC1B,CAQA"}