@sadhaka/loom-engine 0.10.0

package/dist/components/sprite.js

@@ -0,0 +1,122 @@
+// SpritePool - per-entity sprite appearance data.
+//
+// Companion to TransformPool: an entity that has both Transform
+// (position) and Sprite (atlas + frame + tint) gets rendered by
+// the SpriteRenderSystem.
+//
+// Stored as parallel arrays indexed by entity index, mirroring
+// TransformPool's structure-of-arrays layout. Atlas + frame are
+// tightly packed. Tint is split into rgba arrays so iteration
+// stays cache-friendly.
+import { growF32, growI32, growU8, nextPow2 } from '../util/typed-arrays.js';
+import { entityIndex } from '../entity.js';
+export const SPRITE_FLAG_ACTIVE = 1 << 0;
+export const SPRITE_FLAG_TINTED = 1 << 1;
+export class SpritePool {
+    // Hot data
+    atlas; // -1 = no sprite assigned (pair with flags ACTIVE bit)
+    frame;
+    tintR;
+    tintG;
+    tintB;
+    tintA;
+    // Cold data
+    flags;
+    highWaterMark = 0;
+    capacity = 0;
+    constructor(initialCapacity = 64) {
+        this.capacity = nextPow2(initialCapacity);
+        this.atlas = new Int32Array(this.capacity).fill(-1);
+        this.frame = new Int32Array(this.capacity);
+        this.tintR = new Float32Array(this.capacity);
+        this.tintG = new Float32Array(this.capacity);
+        this.tintB = new Float32Array(this.capacity);
+        this.tintA = new Float32Array(this.capacity);
+        this.flags = new Uint8Array(this.capacity);
+    }
+    ensureCapacity(neededIndex) {
+        if (neededIndex < this.capacity)
+            return;
+        const next = nextPow2(neededIndex + 1);
+        const newAtlas = new Int32Array(next).fill(-1);
+        newAtlas.set(this.atlas);
+        this.atlas = newAtlas;
+        this.frame = growI32(this.frame, next);
+        this.tintR = growF32(this.tintR, next);
+        this.tintG = growF32(this.tintG, next);
+        this.tintB = growF32(this.tintB, next);
+        this.tintA = growF32(this.tintA, next);
+        this.flags = growU8(this.flags, next);
+        this.capacity = next;
+    }
+    attach(e, atlas, frame = 0, tint) {
+        const i = entityIndex(e);
+        this.ensureCapacity(i);
+        this.atlas[i] = atlas;
+        this.frame[i] = frame;
+        if (tint) {
+            this.tintR[i] = tint.r;
+            this.tintG[i] = tint.g;
+            this.tintB[i] = tint.b;
+            this.tintA[i] = tint.a;
+            this.flags[i] = SPRITE_FLAG_ACTIVE | SPRITE_FLAG_TINTED;
+        }
+        else {
+            this.tintR[i] = 1;
+            this.tintG[i] = 1;
+            this.tintB[i] = 1;
+            this.tintA[i] = 1;
+            this.flags[i] = SPRITE_FLAG_ACTIVE;
+        }
+        if (i >= this.highWaterMark)
+            this.highWaterMark = i + 1;
+    }
+    detach(e) {
+        const i = entityIndex(e);
+        if (i >= this.capacity)
+            return;
+        this.atlas[i] = -1;
+        this.flags[i] = 0;
+    }
+    setFrame(e, frame) {
+        const i = entityIndex(e);
+        if (i >= this.capacity)
+            return;
+        this.frame[i] = frame;
+    }
+    setTint(e, tint) {
+        const i = entityIndex(e);
+        if (i >= this.capacity)
+            return;
+        this.tintR[i] = tint.r;
+        this.tintG[i] = tint.g;
+        this.tintB[i] = tint.b;
+        this.tintA[i] = tint.a;
+        const f = this.flags[i] ?? 0;
+        this.flags[i] = f | SPRITE_FLAG_TINTED;
+    }
+    clearTint(e) {
+        const i = entityIndex(e);
+        if (i >= this.capacity)
+            return;
+        this.tintR[i] = 1;
+        this.tintG[i] = 1;
+        this.tintB[i] = 1;
+        this.tintA[i] = 1;
+        const f = this.flags[i] ?? 0;
+        this.flags[i] = f & ~SPRITE_FLAG_TINTED;
+    }
+    isActive(e) {
+        const i = entityIndex(e);
+        if (i >= this.capacity)
+            return false;
+        return ((this.flags[i] ?? 0) & SPRITE_FLAG_ACTIVE) !== 0;
+    }
+    getHighWaterMark() {
+        return this.highWaterMark;
+    }
+    getCapacity() {
+        return this.capacity;
+    }
+}
+//# sourceMappingURL=sprite.js.map

package/dist/components/sprite.js.map

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

package/dist/components/transform.d.ts

@@ -0,0 +1,30 @@
+import { type EntityId } from '../entity.js';
+export declare const TRANSFORM_FLAG_DIRTY: number;
+export declare const TRANSFORM_FLAG_VISIBLE: number;
+export declare const TRANSFORM_FLAG_STATIC: number;
+export declare const TRANSFORM_FLAG_HAS_PARENT: number;
+export declare class TransformPool {
+    x: Float32Array;
+    y: Float32Array;
+    z: Float32Array;
+    rotation: Float32Array;
+    scaleX: Float32Array;
+    scaleY: Float32Array;
+    parent: Int32Array;
+    flags: Uint8Array;
+    private highWaterMark;
+    private capacity;
+    constructor(initialCapacity?: number);
+    ensureCapacity(neededIndex: number): void;
+    attach(e: EntityId, x?: number, y?: number, z?: number): void;
+    detach(e: EntityId): void;
+    setPosition(e: EntityId, x: number, y: number, z?: number): void;
+    setScale(e: EntityId, sx: number, sy: number): void;
+    setRotation(e: EntityId, radians: number): void;
+    isVisible(e: EntityId): boolean;
+    setVisible(e: EntityId, visible: boolean): void;
+    getHighWaterMark(): number;
+    getCapacity(): number;
+    clearDirtyAt(index: number): void;
+}
+//# sourceMappingURL=transform.d.ts.map

package/dist/components/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/components/transform.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,QAAQ,EAAe,MAAM,cAAc,CAAC;AAG1D,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAC7C,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAC5C,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD,qBAAa,aAAa;IAExB,CAAC,EAAE,YAAY,CAAC;IAChB,CAAC,EAAE,YAAY,CAAC;IAChB,CAAC,EAAE,YAAY,CAAC;IAChB,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;IAGrB,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,UAAU,CAAC;IAKlB,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAa;gBAEjB,eAAe,GAAE,MAAW;IAYxC,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAsBzC,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAE,MAAU,EAAE,CAAC,GAAE,MAAU,EAAE,CAAC,GAAE,MAAU,GAAG,IAAI;IActE,MAAM,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI;IASzB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAE,MAAU,GAAG,IAAI;IAUnE,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IASnD,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAQ/C,SAAS,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO;IAM/B,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAO/C,gBAAgB,IAAI,MAAM;IAI1B,WAAW,IAAI,MAAM;IAOrB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAKlC"}

package/dist/components/transform.js

@@ -0,0 +1,150 @@
+// TransformPool - the hot component for the Loom Engine ECS.
+//
+// Structure-of-arrays storage: x, y, z, rotation, scaleX, scaleY in
+// separate Float32Arrays so iteration sweeps a contiguous block.
+// Cold metadata (parent, flags) in their own arrays.
+//
+// Inspired by Mike Acton's CppCon 2014 "Data-Oriented Design" talk
+// (see PRIOR-ART.md). The premise: a 10k-entity sort step iterates
+// through ~80kB of contiguous Float32Array memory rather than
+// chasing 10k object pointers.
+//
+// Capacity grows by 2x on demand. Initial capacity is small to
+// keep startup cost tiny; first scene with > 64 entities pays for
+// one grow, after that pow-2 sizing absorbs further growth cheaply.
+import { growF32, growU8, nextPow2 } from '../util/typed-arrays.js';
+import { entityIndex } from '../entity.js';
+// Bitflags packed into the cold flags array.
+export const TRANSFORM_FLAG_DIRTY = 1 << 0; // world matrix needs recompute
+export const TRANSFORM_FLAG_VISIBLE = 1 << 1; // skip render if cleared
+export const TRANSFORM_FLAG_STATIC = 1 << 2; // never moves; cache aggressively
+export const TRANSFORM_FLAG_HAS_PARENT = 1 << 3; // parent slot is meaningful
+export class TransformPool {
+    // Hot data - touched every frame by render + sort systems.
+    x;
+    y;
+    z;
+    rotation;
+    scaleX;
+    scaleY;
+    // Cold data - rarely touched per-frame.
+    parent; // -1 for root, otherwise parent entity index
+    flags;
+    // High-water mark of active indices. Iteration goes up to this,
+    // not capacity, so a sparsely-populated pool doesn't waste cycles
+    // on empty slots above the live set.
+    highWaterMark = 0;
+    capacity = 0;
+    constructor(initialCapacity = 64) {
+        this.capacity = nextPow2(initialCapacity);
+        this.x = new Float32Array(this.capacity);
+        this.y = new Float32Array(this.capacity);
+        this.z = new Float32Array(this.capacity);
+        this.rotation = new Float32Array(this.capacity);
+        this.scaleX = new Float32Array(this.capacity);
+        this.scaleY = new Float32Array(this.capacity);
+        this.parent = new Int32Array(this.capacity).fill(-1);
+        this.flags = new Uint8Array(this.capacity);
+    }
+    ensureCapacity(neededIndex) {
+        if (neededIndex < this.capacity)
+            return;
+        const next = nextPow2(neededIndex + 1);
+        this.x = growF32(this.x, next);
+        this.y = growF32(this.y, next);
+        this.z = growF32(this.z, next);
+        this.rotation = growF32(this.rotation, next);
+        this.scaleX = growF32(this.scaleX, next);
+        this.scaleY = growF32(this.scaleY, next);
+        // -1 is the parent sentinel for "no parent" - new slots default
+        // to that.
+        const oldParent = this.parent;
+        const newParent = new Int32Array(next).fill(-1);
+        newParent.set(oldParent);
+        this.parent = newParent;
+        this.flags = growU8(this.flags, next);
+        this.capacity = next;
+    }
+    // Attach a transform to an entity. Sets sane defaults: scale = 1,
+    // visible = true, dirty = true. The dirty flag tells the transform
+    // system to recompute any cached world matrix on the next commit.
+    attach(e, x = 0, y = 0, z = 0) {
+        const i = entityIndex(e);
+        this.ensureCapacity(i);
+        this.x[i] = x;
+        this.y[i] = y;
+        this.z[i] = z;
+        this.rotation[i] = 0;
+        this.scaleX[i] = 1;
+        this.scaleY[i] = 1;
+        this.parent[i] = -1;
+        this.flags[i] = TRANSFORM_FLAG_DIRTY | TRANSFORM_FLAG_VISIBLE;
+        if (i >= this.highWaterMark)
+            this.highWaterMark = i + 1;
+    }
+    detach(e) {
+        const i = entityIndex(e);
+        if (i >= this.capacity)
+            return;
+        this.flags[i] = 0;
+        // We don't shrink highWaterMark on detach - the slot is just
+        // marked invisible. A future tighten() pass could compact, but
+        // v1 keeps it simple.
+    }
+    setPosition(e, x, y, z = 0) {
+        const i = entityIndex(e);
+        if (i >= this.capacity)
+            return;
+        this.x[i] = x;
+        this.y[i] = y;
+        this.z[i] = z;
+        const f = this.flags[i] ?? 0;
+        this.flags[i] = f | TRANSFORM_FLAG_DIRTY;
+    }
+    setScale(e, sx, sy) {
+        const i = entityIndex(e);
+        if (i >= this.capacity)
+            return;
+        this.scaleX[i] = sx;
+        this.scaleY[i] = sy;
+        const f = this.flags[i] ?? 0;
+        this.flags[i] = f | TRANSFORM_FLAG_DIRTY;
+    }
+    setRotation(e, radians) {
+        const i = entityIndex(e);
+        if (i >= this.capacity)
+            return;
+        this.rotation[i] = radians;
+        const f = this.flags[i] ?? 0;
+        this.flags[i] = f | TRANSFORM_FLAG_DIRTY;
+    }
+    isVisible(e) {
+        const i = entityIndex(e);
+        if (i >= this.capacity)
+            return false;
+        return ((this.flags[i] ?? 0) & TRANSFORM_FLAG_VISIBLE) !== 0;
+    }
+    setVisible(e, visible) {
+        const i = entityIndex(e);
+        if (i >= this.capacity)
+            return;
+        const f = this.flags[i] ?? 0;
+        this.flags[i] = visible ? f | TRANSFORM_FLAG_VISIBLE : f & ~TRANSFORM_FLAG_VISIBLE;
+    }
+    getHighWaterMark() {
+        return this.highWaterMark;
+    }
+    getCapacity() {
+        return this.capacity;
+    }
+    // Clear the dirty bit after the transform-system commit pass. The
+    // commit pass walks all dirty entries, recomputes derived state,
+    // then calls this.
+    clearDirtyAt(index) {
+        if (index >= this.capacity)
+            return;
+        const f = this.flags[index] ?? 0;
+        this.flags[index] = f & ~TRANSFORM_FLAG_DIRTY;
+    }
+}
+//# sourceMappingURL=transform.js.map

package/dist/components/transform.js.map

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

package/dist/director/director-bridge.d.ts

@@ -0,0 +1,22 @@
+import type { DirectorEvent } from './event-envelope.js';
+export type DirectorBridgeStatus = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'snapshot-required' | 'closed';
+export interface DirectorBridgeStats {
+    eventsReceived: number;
+    reconnects: number;
+    lastEventId: number;
+    outOfOrderEvents: number;
+    serverDropsP1: number;
+    serverDropsP2: number;
+}
+export interface IDirectorBridge {
+    start(): void;
+    stop(): void;
+    status(): DirectorBridgeStatus;
+    isConnected(): boolean;
+    getLastEventId(): number;
+    pollEvents(): DirectorEvent[];
+    stats(): Readonly<DirectorBridgeStats>;
+}
+export declare const RESOURCE_DIRECTOR_BRIDGE = "director_bridge";
+export declare const RESOURCE_KNOT_CONTEXT = "knot_context";
+//# sourceMappingURL=director-bridge.d.ts.map

package/dist/director/director-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-bridge.d.ts","sourceRoot":"","sources":["../../src/director/director-bridge.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,oBAAoB,GAC5B,MAAM,GACN,YAAY,GACZ,WAAW,GACX,cAAc,GACd,mBAAmB,GACnB,QAAQ,CAAC;AAEb,MAAM,WAAW,mBAAmB;IAElC,cAAc,EAAE,MAAM,CAAC;IAEvB,UAAU,EAAE,MAAM,CAAC;IAEnB,WAAW,EAAE,MAAM,CAAC;IAEpB,gBAAgB,EAAE,MAAM,CAAC;IAEzB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,MAAM,IAAI,oBAAoB,CAAC;IAC/B,WAAW,IAAI,OAAO,CAAC;IACvB,cAAc,IAAI,MAAM,CAAC;IACzB,UAAU,IAAI,aAAa,EAAE,CAAC;IAC9B,KAAK,IAAI,QAAQ,CAAC,mBAAmB,CAAC,CAAC;CACxC;AAGD,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAC1D,eAAO,MAAM,qBAAqB,iBAAiB,CAAC"}

package/dist/director/director-bridge.js

@@ -0,0 +1,23 @@
+// IDirectorBridge - abstraction over the event source.
+//
+// Concrete implementations:
+//   MockDirectorBridge  - synthetic event injection. Used in tests +
+//                         offline demo. Does not touch the network.
+//   SSEDirectorBridge   - real EventSource subscription against the
+//                         backend's /api/v1/loom/director/events route.
+//                         Browser-only; throws in Node test runs.
+//
+// The DirectorSystem (PHASE_INPUT) calls pollEvents() once per tick
+// to drain queued events. Bridges buffer events between polls so the
+// system's per-tick read is bounded.
+//
+// Connection lifecycle:
+//   start()            - begin subscription / open EventSource
+//   stop()             - close and stop reconnecting
+//   isConnected()      - true when the underlying transport is open
+//   getLastEventId()   - highest id observed; used for reconnect Last-Event-ID
+//   pollEvents()       - drain and return all queued events since last poll
+// Resource keys.
+export const RESOURCE_DIRECTOR_BRIDGE = 'director_bridge';
+export const RESOURCE_KNOT_CONTEXT = 'knot_context';
+//# sourceMappingURL=director-bridge.js.map

package/dist/director/director-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-bridge.js","sourceRoot":"","sources":["../../src/director/director-bridge.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,4BAA4B;AAC5B,qEAAqE;AACrE,oEAAoE;AACpE,oEAAoE;AACpE,wEAAwE;AACxE,kEAAkE;AAClE,EAAE;AACF,oEAAoE;AACpE,qEAAqE;AACrE,qCAAqC;AACrC,EAAE;AACF,wBAAwB;AACxB,+DAA+D;AAC/D,qDAAqD;AACrD,oEAAoE;AACpE,+EAA+E;AAC/E,4EAA4E;AAoC5E,iBAAiB;AACjB,MAAM,CAAC,MAAM,wBAAwB,GAAG,iBAAiB,CAAC;AAC1D,MAAM,CAAC,MAAM,qBAAqB,GAAG,cAAc,CAAC"}

package/dist/director/director-encounter-system.d.ts

@@ -0,0 +1,21 @@
+import type { System } from '../system.js';
+import type { World } from '../world.js';
+import type { AtlasHandle } from '../renderer/graphics-device.js';
+import type { EntityId } from '../entity.js';
+export interface DirectorEncounterSystemOptions {
+    player: EntityId;
+    mobAtlas: AtlasHandle;
+    onEncounterStarted?: (encounterId: string, mobCount: number, narratorLine: string | null) => void;
+}
+export declare class DirectorEncounterSystem implements System {
+    readonly name: string;
+    private handled;
+    private opts;
+    constructor(opts: DirectorEncounterSystemOptions);
+    update(world: World, _dt: number): void;
+    private spawnEncounter;
+    private spawnOne;
+    clearHandled(): void;
+    hasHandled(encounterId: string): boolean;
+}
+//# sourceMappingURL=director-encounter-system.d.ts.map

package/dist/director/director-encounter-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-encounter-system.d.ts","sourceRoot":"","sources":["../../src/director/director-encounter-system.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAWzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAsB7C,MAAM,WAAW,8BAA8B;IAE7C,MAAM,EAAE,QAAQ,CAAC;IAKjB,QAAQ,EAAE,WAAW,CAAC;IAItB,kBAAkB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CACnG;AAED,qBAAa,uBAAwB,YAAW,MAAM;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAwB;IAI7C,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,IAAI,CAAiC;gBAEjC,IAAI,EAAE,8BAA8B;IAIhD,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IA2BvC,OAAO,CAAC,cAAc;IA6BtB,OAAO,CAAC,QAAQ;IAyBhB,YAAY,IAAI,IAAI;IAIpB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;CAGzC"}

package/dist/director/director-encounter-system.js

@@ -0,0 +1,128 @@
+// DirectorEncounterSystem - subscribes to encounter.spawn events
+// from the DirectorEventLog and spawns mobs into the world.
+//
+// Works in tandem with DirectorSystem:
+//   1. DirectorSystem (PHASE_INPUT) drains the bridge and applies
+//      events to KnotContext / VeilBudget / DirectorEventLog
+//   2. DirectorEncounterSystem (PHASE_LOGIC) re-reads the most
+//      recent events from the log, spawns mobs from any new
+//      encounter.spawn event, and tracks handled encounter ids so
+//      replay / duplicate events don't double-spawn
+//
+// Per spec §3.1 the encounter.spawn payload includes:
+//   - mobs: ReadonlyArray<MobSpec> with type, position_hint, etc.
+//   - boss: BossSpec | null
+//   - knot, level, zone_id, narrator_line
+//
+// The renderer never decides composition (spec §5.1, §6.5). It just
+// applies what the Director said.
+//
+// Mob type mapping: the spec's `type` field is a string the Director
+// chose. We map known strings to MobArchetype values; unknown strings
+// fall back to 'skel_warrior' so the encounter still produces
+// something visible.
+import { RESOURCE_DIRECTOR_LOG, } from './director-system.js';
+import { spawnMob, MOB_CATALOG, } from '../combat/mob-catalog.js';
+// String -> MobArchetype map. The Director can emit any string in
+// the type field (spec doesn't enumerate); the engine validates +
+// falls back. New mob types added in subsequent phases just extend
+// this map.
+const TYPE_MAP = {
+    skel_warrior: 'skel_warrior',
+    skel_archer: 'skel_archer',
+    skel_caster: 'skel_caster',
+    // Aliases / legacy names from the existing Survivor that map to
+    // catalog archetypes.
+    skeleton_iron: 'skel_warrior',
+    skeleton_warrior: 'skel_warrior',
+    skeleton_archer: 'skel_archer',
+    skeleton_caster: 'skel_caster',
+};
+function resolveMobArchetype(typeStr) {
+    return TYPE_MAP[typeStr] ?? 'skel_warrior';
+}
+export class DirectorEncounterSystem {
+    name = 'director-encounter';
+    // Set of encounter_ids we've already spawned. Prevents duplicate
+    // spawn on event replay (spec §9.3 dual-delivery dedupe).
+    handled = new Set();
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    update(world, _dt) {
+        const log = world.resources.get(RESOURCE_DIRECTOR_LOG);
+        if (!log)
+            return;
+        // Walk recent events from the log. recent is newest-first and
+        // capped at 32 (per DirectorSystem ring buffer). Iterate from
+        // oldest-to-newest so multi-encounter ticks spawn in order.
+        for (let i = log.recent.length - 1; i >= 0; i--) {
+            const ev = log.recent[i];
+            if (!ev || ev.type !== 'encounter.spawn')
+                continue;
+            const spawn = ev;
+            const id = spawn.data.encounter_id;
+            if (!id || this.handled.has(id))
+                continue;
+            this.spawnEncounter(world, spawn.data);
+            this.handled.add(id);
+        }
+        // On encounter.end events, free up the encounter id so a future
+        // re-emission (e.g. retry) can spawn again.
+        for (let i = log.recent.length - 1; i >= 0; i--) {
+            const ev = log.recent[i];
+            if (!ev || ev.type !== 'encounter.end')
+                continue;
+            const id = ev.encounter_id;
+            if (id)
+                this.handled.delete(id);
+        }
+    }
+    spawnEncounter(world, data) {
+        let totalSpawned = 0;
+        for (const mob of data.mobs) {
+            totalSpawned += this.spawnOne(world, mob);
+        }
+        // Boss spawn (if present).
+        if (data.boss) {
+            // Bosses use the same spawnMob factory in v1; future work
+            // adds a spawnBoss with bigger HP / unique behaviour.
+            const archetype = resolveMobArchetype(data.boss.type);
+            // Verify the catalog has the entry before spawning - prevents
+            // a typo on the Director side from crashing the renderer.
+            if (MOB_CATALOG[archetype]) {
+                spawnMob(world, archetype, data.boss.position_hint.x, data.boss.position_hint.y, this.opts.player, this.opts.mobAtlas);
+                totalSpawned++;
+            }
+        }
+        if (this.opts.onEncounterStarted) {
+            this.opts.onEncounterStarted(data.encounter_id, totalSpawned, data.narrator_line);
+        }
+    }
+    spawnOne(world, mob) {
+        const archetype = resolveMobArchetype(mob.type);
+        if (!MOB_CATALOG[archetype])
+            return 0;
+        const baseX = mob.position_hint.x;
+        const baseY = mob.position_hint.y;
+        // count > 1 spawns multiple instances at slightly varied
+        // positions (small radius around the position_hint).
+        for (let i = 0; i < mob.count; i++) {
+            const angle = (i / Math.max(1, mob.count)) * Math.PI * 2;
+            const spread = mob.count > 1 ? 0.5 : 0;
+            spawnMob(world, archetype, baseX + Math.cos(angle) * spread, baseY + Math.sin(angle) * spread, this.opts.player, this.opts.mobAtlas);
+        }
+        return mob.count;
+    }
+    // Test / debug helper: clear the handled-id cache. Used by demo
+    // code when transitioning zones so a fresh encounter.spawn for a
+    // re-entered zone re-spawns mobs.
+    clearHandled() {
+        this.handled.clear();
+    }
+    hasHandled(encounterId) {
+        return this.handled.has(encounterId);
+    }
+}
+//# sourceMappingURL=director-encounter-system.js.map

package/dist/director/director-encounter-system.js.map

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

package/dist/director/director-system.d.ts

@@ -0,0 +1,19 @@
+import type { System } from '../system.js';
+import type { World } from '../world.js';
+import type { DirectorEvent, VeilTier } from './event-envelope.js';
+export interface DirectorEventLog {
+    recent: DirectorEvent[];
+    lastNarratorLine: string | null;
+    lastNarratorTtlMs: number;
+    lastKnot: string | null;
+    activeEncounterId: string | null;
+    lastTier: VeilTier;
+    eventsApplied: number;
+}
+export declare const RESOURCE_DIRECTOR_LOG = "director_log";
+export declare function createDirectorEventLog(): DirectorEventLog;
+export declare class DirectorSystem implements System {
+    readonly name: string;
+    update(world: World, _dt: number): void;
+}
+//# sourceMappingURL=director-system.d.ts.map

package/dist/director/director-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-system.d.ts","sourceRoot":"","sources":["../../src/director/director-system.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAazC,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACT,MAAM,qBAAqB,CAAC;AAG7B,MAAM,WAAW,gBAAgB;IAE/B,MAAM,EAAE,aAAa,EAAE,CAAC;IAExB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAG1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjC,QAAQ,EAAE,QAAQ,CAAC;IAEnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,qBAAqB,iBAAiB,CAAC;AAIpD,wBAAgB,sBAAsB,IAAI,gBAAgB,CAUzD;AAwBD,qBAAa,cAAe,YAAW,MAAM;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAc;IAEnC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;CAwBxC"}