@sadhaka/loom-engine 0.12.0 → 0.14.0

package/README.md

@@ -146,7 +146,8 @@ public API surface will evolve until 1.0.
 | 11B.3 | shipped | MIT license + npm publish posture (this release) |
 | 12.4 | shipped | License pivot from MIT to BUSL 1.1 with $1M revenue cap |
 | 13.2 | shipped | Engine hardening: 12.6 audit lows L-08..L-12 closed |
-| 14.1 | shipped | WebGL2 instanced sprite batcher (this release) |
+| 14.1 | shipped | WebGL2 instanced sprite batcher |
+| 15.1 | shipped | Multiplayer presence: pluggable bridge (SSE / Mock), peer pool with per-peer linear interpolation, render system (this release) |
 
 See [LOOM-ENGINE-SPEC.md](../docker/LOOM-ENGINE-SPEC.md) Section 7
 for the full phase plan with effort estimates.
@@ -276,6 +277,14 @@ the browser without a build step on the consumer side.
   Demonstrates that the same ECS / resource model that runs the action
   demos also fits a UI-only game: custom `Resource`, custom `System`
   reading both `InputSnapshot` and DOM events, DOM as the primary UI.
+- **[Plaza Multiplayer](./demo/plaza-multiplayer/)** - walkable iso
+  plaza with three synthetic peers wandering randomly, driven by a
+  `MockMultiplayerBridge`. WASD to walk; the local player broadcasts
+  position at 10 Hz and the three peers (Alice / Bob / Carol) lerp
+  smoothly between presence updates. Demonstrates the pluggable
+  multiplayer bridge, `PeerPool` linear interpolation, and the
+  `PeerPresenceSystem` / `PeerRenderSystem` pipeline. See the
+  [Multiplayer](#multiplayer) section below for the wire protocol.
 
 The legacy reference demos (Phase 6 director, Phase 7 combat, Phase 8
 ARPG slice) stay accessible from the gallery index.
@@ -285,6 +294,109 @@ Controls in the legacy director demo (`demo/director.html`):
 - **Click**: burst 24 particles + play SFX chirp (after first click, AudioContext unlocks)
 - **Hover**: stats panel shows the iso tile under the cursor
 
+## Multiplayer
+
+Phase 15.1 adds a thin presence layer for showing other players in
+real time on the same world. The transport is pluggable: the engine
+ships an `SSEMultiplayerBridge` (server-sent events) and a
+`MockMultiplayerBridge` (in-process; tests + offline demos), and the
+`IMultiplayerBridge` interface is small enough to swap in WebSocket
+or WebRTC without touching anything above it. No CRDT - peers carry
+position only, and conflict resolution is "last write wins" at the
+server. Shared state beyond position is deferred to a later phase.
+
+### Wire protocol
+
+The bridge layer hides this from gameplay code, but for anyone
+implementing a server (or a custom transport) the contract is:
+
+**Server -> client (SSE event types):**
+- `presence.snapshot` `{ peers: [{ character_id, x, y, zone, ts_ms, name? }] }`
+  emitted once on connect with the full current peer roster. The
+  client treats this as authoritative and drops any peer not in the
+  snapshot.
+- `presence.update` `{ character_id, x, y, zone, ts_ms, name? }`
+  emitted as peers move.
+- `presence.depart` `{ character_id }`
+  emitted when a peer disconnects.
+
+**Client -> server (HTTP POST):**
+- `POST <broadcastUrl>` `{ character_id, x, y, zone, ts_ms }`
+  the engine rate-limits to **10 Hz** (`BROADCAST_HZ`); excess calls
+  to `broadcastPosition()` are silently dropped and counted in
+  `bridge.stats().rateLimitedDrops`. Calling once per frame is fine.
+
+`ts_ms` is the wall clock at which the position was true. The
+`PeerPool` uses it to interpolate between successive samples so peers
+don't jitter at the network rate. Acceptable lag is ~150 ms (one
+update interval at 10 Hz), imperceptible at walk speed.
+
+### Setup
+
+```ts
+import {
+  Engine,
+  // Multiplayer
+  MockMultiplayerBridge,        // or SSEMultiplayerBridge
+  PeerPool,
+  PeerSpritePool,
+  PeerPresenceSystem,
+  PeerRenderSystem,
+  POOL_PEER_SPRITE,
+  RESOURCE_MULTIPLAYER_BRIDGE,
+  RESOURCE_PEER_POOL,
+  SYSTEM_PHASE_INPUT,
+  SYSTEM_PHASE_RENDER,
+} from '@sadhaka/loom-engine';
+
+const engine = Engine.create({ canvas });
+
+// 1. Create a bridge. Production code uses SSEMultiplayerBridge:
+//
+//   const bridge = new SSEMultiplayerBridge({
+//     baseUrl: '/api/v1/loom/presence/events',
+//     characterId: 'me',
+//     zone: 'plaza',
+//   });
+//
+// Tests + offline dev use the in-process mock:
+const bridge = new MockMultiplayerBridge();
+bridge.connect();
+
+// 2. PeerPool stores all known peers + their interpolated positions.
+//    Self-filter: tell the pool which character_id is the local player
+//    so it isn't rendered as a ghost when the server echoes it back.
+const peerPool = new PeerPool();
+peerPool.setLocalCharacterId('me');
+
+// 3. PeerSpritePool maps character_id -> rendering hint. A default
+//    atlas + frame is enough for an undifferentiated demo; setOverride()
+//    lets you assign per-class sprites or cosmetic shards.
+const peerSprites = new PeerSpritePool({ defaultAtlas: peerAtlas });
+
+engine.world.resources.set(RESOURCE_MULTIPLAYER_BRIDGE, bridge);
+engine.world.resources.set(RESOURCE_PEER_POOL, peerPool);
+engine.world.registerPool(POOL_PEER_SPRITE, peerSprites);
+
+// 4. Wire the systems. PeerPresenceSystem drains the bridge each
+//    frame; PeerRenderSystem submits a drawSprite + name label per
+//    peer at their interpolated position.
+engine.world.addSystem(new PeerPresenceSystem(), SYSTEM_PHASE_INPUT);
+engine.world.addSystem(new PeerRenderSystem(),   SYSTEM_PHASE_RENDER);
+
+// 5. Inside your walk-system, call broadcastPosition() each frame.
+//    The bridge enforces the 10 Hz wire rate.
+bridge.broadcastPosition(playerX, playerY, 'plaza', Date.now());
+```
+
+### Swapping transports
+
+The bridge interface is just five methods (`connect`, `disconnect`,
+`status`, `pollMessages`, `broadcastPosition`, plus `stats`). To use
+WebSocket or WebRTC, implement `IMultiplayerBridge` with the same
+`PresenceMessage` shape (`update` / `depart` / `snapshot`); none of
+the systems above the bridge change.
+
 ## Layout
 
 ```

package/dist/components/peer-sprite.d.ts

@@ -0,0 +1,25 @@
+import type { AtlasHandle } from '../renderer/graphics-device.js';
+import type { ColorRGBA } from '../util/color.js';
+export interface PeerSpriteEntry {
+    atlas: AtlasHandle;
+    frame: number;
+    tint: Readonly<ColorRGBA> | null;
+}
+export interface PeerSpritePoolOptions {
+    defaultAtlas: AtlasHandle;
+    defaultFrame?: number;
+    defaultTint?: Readonly<ColorRGBA>;
+}
+export declare class PeerSpritePool {
+    private readonly defaultEntry;
+    private overrides;
+    constructor(opts: PeerSpritePoolOptions);
+    setOverride(characterId: string, entry: PeerSpriteEntry): void;
+    removeOverride(characterId: string): void;
+    resolve(characterId: string): Readonly<PeerSpriteEntry>;
+    getDefault(): Readonly<PeerSpriteEntry>;
+    hasOverride(characterId: string): boolean;
+    clear(): void;
+}
+export declare const POOL_PEER_SPRITE = "peer_sprite";
+//# sourceMappingURL=peer-sprite.d.ts.map

package/dist/components/peer-sprite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-sprite.d.ts","sourceRoot":"","sources":["../../src/components/peer-sprite.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IAEpC,YAAY,EAAE,WAAW,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;CACnC;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkB;IAC/C,OAAO,CAAC,SAAS,CAA2C;gBAEhD,IAAI,EAAE,qBAAqB;IAWvC,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI;IAI9D,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMzC,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC,eAAe,CAAC;IAIvD,UAAU,IAAI,QAAQ,CAAC,eAAe,CAAC;IAIvC,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIzC,KAAK,IAAI,IAAI;CAGd;AAED,eAAO,MAAM,gBAAgB,gBAAgB,CAAC"}

package/dist/components/peer-sprite.js

@@ -0,0 +1,48 @@
+// PeerSpritePool - per-peer rendering hints (atlas, frame, tint,
+// optional name label) keyed by character_id rather than by EntityId.
+//
+// Peers don't get a stable EntityId because they appear and disappear
+// based on network presence, not gameplay state. The PeerPresenceSystem
+// resolves a peer's interpolated (x, y) from PeerPool each frame and
+// draws via this pool's per-peer atlas/frame.
+//
+// Default style: unspecified peers render with a fallback atlas/frame
+// supplied at pool construction. That keeps single-line setup simple
+// for the demo while still allowing per-peer customization (cosmetic
+// shards, visible class, etc.) once the dev wants to differentiate.
+export class PeerSpritePool {
+    defaultEntry;
+    overrides = new Map();
+    constructor(opts) {
+        this.defaultEntry = {
+            atlas: opts.defaultAtlas,
+            frame: opts.defaultFrame ?? 0,
+            tint: opts.defaultTint ?? null,
+        };
+    }
+    // Per-peer override. Apply once on join (e.g. after a server-emitted
+    // class hint) and forget; the pool keeps it until clear() / removed
+    // explicitly.
+    setOverride(characterId, entry) {
+        this.overrides.set(characterId, entry);
+    }
+    removeOverride(characterId) {
+        this.overrides.delete(characterId);
+    }
+    // Resolve the rendering entry for a peer. Returns the override if
+    // one exists, otherwise the default. Never null for a known peer.
+    resolve(characterId) {
+        return this.overrides.get(characterId) ?? this.defaultEntry;
+    }
+    getDefault() {
+        return this.defaultEntry;
+    }
+    hasOverride(characterId) {
+        return this.overrides.has(characterId);
+    }
+    clear() {
+        this.overrides.clear();
+    }
+}
+export const POOL_PEER_SPRITE = 'peer_sprite';
+//# sourceMappingURL=peer-sprite.js.map

package/dist/components/peer-sprite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-sprite.js","sourceRoot":"","sources":["../../src/components/peer-sprite.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,sEAAsE;AACtE,EAAE;AACF,sEAAsE;AACtE,wEAAwE;AACxE,qEAAqE;AACrE,8CAA8C;AAC9C,EAAE;AACF,sEAAsE;AACtE,qEAAqE;AACrE,qEAAqE;AACrE,oEAAoE;AAkBpE,MAAM,OAAO,cAAc;IACR,YAAY,CAAkB;IACvC,SAAS,GAAiC,IAAI,GAAG,EAAE,CAAC;IAE5D,YAAY,IAA2B;QACrC,IAAI,CAAC,YAAY,GAAG;YAClB,KAAK,EAAE,IAAI,CAAC,YAAY;YACxB,KAAK,EAAE,IAAI,CAAC,YAAY,IAAI,CAAC;YAC7B,IAAI,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI;SAC/B,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,oEAAoE;IACpE,cAAc;IACd,WAAW,CAAC,WAAmB,EAAE,KAAsB;QACrD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,cAAc,CAAC,WAAmB;QAChC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACrC,CAAC;IAED,kEAAkE;IAClE,kEAAkE;IAClE,OAAO,CAAC,WAAmB;QACzB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC;IAC9D,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,WAAW,CAAC,WAAmB;QAC7B,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC"}

package/dist/director/ai/ai-plugin-registry.d.ts

@@ -0,0 +1,20 @@
+import type { IAIPlugin, EmittedEvents, PluginContext, PeerInfo, PlayerAction } from './plugin.js';
+export declare class AIPluginDuplicateError extends Error {
+    readonly pluginName: string;
+    constructor(pluginName: string);
+}
+export declare class AIPluginRegistry {
+    private plugins;
+    register(plugin: IAIPlugin): void;
+    unregister(name: string): Promise<boolean>;
+    list(): ReadonlyArray<IAIPlugin>;
+    get(name: string): IAIPlugin | undefined;
+    dispatchTick(ctx: PluginContext): Promise<EmittedEvents>;
+    dispatchPeerJoin(ctx: PluginContext, peer: PeerInfo): Promise<EmittedEvents>;
+    dispatchPeerLeave(ctx: PluginContext, peer: PeerInfo): Promise<EmittedEvents>;
+    dispatchZoneEnter(ctx: PluginContext, peer: PeerInfo, fromZone: string | null): Promise<EmittedEvents>;
+    dispatchPlayerAction(ctx: PluginContext, peer: PeerInfo, action: PlayerAction): Promise<EmittedEvents>;
+    private dispatch;
+    private errorMeta;
+}
+//# sourceMappingURL=ai-plugin-registry.d.ts.map

package/dist/director/ai/ai-plugin-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-plugin-registry.d.ts","sourceRoot":"","sources":["../../../src/director/ai/ai-plugin-registry.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EACb,aAAa,EACb,QAAQ,EACR,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,qBAAa,sBAAuB,SAAQ,KAAK;aACnB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAI/C;AAED,qBAAa,gBAAgB;IAK3B,OAAO,CAAC,OAAO,CAAmB;IAOlC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IA0B3B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BhD,IAAI,IAAI,aAAa,CAAC,SAAS,CAAC;IAMhC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAgBlC,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAMxD,gBAAgB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC;IAM5E,iBAAiB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC;IAM7E,iBAAiB,CACrB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,aAAa,CAAC;IAMnB,oBAAoB,CACxB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,aAAa,CAAC;YAYX,QAAQ;IAiEtB,OAAO,CAAC,SAAS;CAgBlB"}

package/dist/director/ai/ai-plugin-registry.js

@@ -0,0 +1,232 @@
+// AIPluginRegistry - dispatches lifecycle hooks across registered plugins.
+//
+// Per LOOM-DIRECTOR-PROTOCOL-V2 Section 5.3: the registry holds N
+// plugins, dispatches each hook in priority order (lower runs first),
+// and concatenates the EmittedEvents from every plugin into a single
+// merged result. The caller (the engine's emit path / TWT's loom_director
+// orchestrator) takes the merged events and routes them - character
+// events to the v1 stream, zone events to the v2 zone log + presence
+// fanout.
+//
+// Error isolation guarantee (open question 8.3): if a plugin's hook
+// throws synchronously OR the returned Promise rejects, the registry
+// logs the failure via that plugin's logger, drops that plugin's
+// contribution for THIS dispatch only, and continues with the next
+// plugin. The dispatch never throws to the caller. Plugin authors
+// remain responsible for their own internal try/catch; the registry
+// is the safety net of last resort.
+//
+// Implementation notes:
+//   - Plugins are kept in a sorted array; register/unregister keep
+//     it sorted so the dispatch hot path is a simple iteration.
+//   - The registry never instantiates a PluginContext; the caller
+//     supplies one per dispatch (or reuses one and refreshes views).
+//     This keeps the registry decoupled from world-state plumbing.
+//   - dispose() is awaited inside unregister() so plugins can flush
+//     pending work; if dispose throws we log and continue (drop
+//     guarantee extends to dispose so the caller never sees plugin
+//     errors leak).
+export class AIPluginDuplicateError extends Error {
+    pluginName;
+    constructor(pluginName) {
+        super('AIPluginDuplicateError: plugin already registered: ' + pluginName);
+        this.pluginName = pluginName;
+        this.name = 'AIPluginDuplicateError';
+    }
+}
+export class AIPluginRegistry {
+    // Sorted by priority ascending, then by registration order. The
+    // registration index is encoded by inserting at the right position
+    // on register() rather than re-sorting, which preserves stable
+    // ordering for equal priorities.
+    plugins = [];
+    // ----- Lifecycle -----
+    // Register a plugin. Throws AIPluginDuplicateError if a plugin with
+    // the same name is already registered (names are the registry key).
+    // Insertion is O(n) but n is small (typically 1-10 plugins).
+    register(plugin) {
+        for (var i = 0; i < this.plugins.length; i++) {
+            var existing = this.plugins[i];
+            if (existing && existing.name === plugin.name) {
+                throw new AIPluginDuplicateError(plugin.name);
+            }
+        }
+        // Find the first plugin with strictly higher priority and insert
+        // before it. This preserves stable ordering for equal priorities
+        // (a later-registered plugin runs after an earlier one with the
+        // same priority).
+        var insertAt = this.plugins.length;
+        for (var j = 0; j < this.plugins.length; j++) {
+            var p = this.plugins[j];
+            if (p && p.priority > plugin.priority) {
+                insertAt = j;
+                break;
+            }
+        }
+        this.plugins.splice(insertAt, 0, plugin);
+    }
+    // Unregister a plugin by name. Awaits the plugin's dispose() if
+    // present; logs and drops if dispose throws. Returns true if a
+    // plugin was removed, false if no plugin with that name was
+    // registered.
+    async unregister(name) {
+        var idx = -1;
+        for (var i = 0; i < this.plugins.length; i++) {
+            var p = this.plugins[i];
+            if (p && p.name === name) {
+                idx = i;
+                break;
+            }
+        }
+        if (idx === -1)
+            return false;
+        var plugin = this.plugins[idx];
+        this.plugins.splice(idx, 1);
+        if (plugin && typeof plugin.dispose === 'function') {
+            try {
+                await plugin.dispose();
+            }
+            catch (err) {
+                // Drop guarantee extends to dispose. We can't log via the
+                // plugin's logger because we have no PluginContext here;
+                // fall back to console with the plugin name tag.
+                console.error('[plugin: ' + plugin.name + '] dispose() threw', this.errorMeta(err));
+            }
+        }
+        return true;
+    }
+    // Read-only snapshot of the plugin list, in dispatch order. Returns
+    // a fresh array; mutating it does not affect the registry.
+    list() {
+        return this.plugins.slice();
+    }
+    // Look up a plugin by name. Returns undefined if no plugin with
+    // that name is registered.
+    get(name) {
+        for (var i = 0; i < this.plugins.length; i++) {
+            var p = this.plugins[i];
+            if (p && p.name === name)
+                return p;
+        }
+        return undefined;
+    }
+    // ----- Dispatchers -----
+    // All five dispatchers share the same shape: iterate plugins in
+    // priority order, call the hook if defined, await the result, merge
+    // into the running EmittedEvents. Errors are caught per-plugin and
+    // logged via the plugin's logger if reachable through ctx; never
+    // thrown to the caller.
+    async dispatchTick(ctx) {
+        return this.dispatch(ctx, 'onTick', function (plugin, ctx) {
+            return plugin.onTick(ctx);
+        });
+    }
+    async dispatchPeerJoin(ctx, peer) {
+        return this.dispatch(ctx, 'onPeerJoin', function (plugin, ctx) {
+            return plugin.onPeerJoin(ctx, peer);
+        });
+    }
+    async dispatchPeerLeave(ctx, peer) {
+        return this.dispatch(ctx, 'onPeerLeave', function (plugin, ctx) {
+            return plugin.onPeerLeave(ctx, peer);
+        });
+    }
+    async dispatchZoneEnter(ctx, peer, fromZone) {
+        return this.dispatch(ctx, 'onZoneEnter', function (plugin, ctx) {
+            return plugin.onZoneEnter(ctx, peer, fromZone);
+        });
+    }
+    async dispatchPlayerAction(ctx, peer, action) {
+        return this.dispatch(ctx, 'onPlayerAction', function (plugin, ctx) {
+            return plugin.onPlayerAction(ctx, peer, action);
+        });
+    }
+    // ----- Internals -----
+    // Generic dispatch helper. `hookName` is the property name we check
+    // for definition on each plugin; `invoke` calls the actual hook
+    // (the spread of args differs per dispatcher). Per-plugin try/catch
+    // around the await isolates failures.
+    async dispatch(ctx, hookName, invoke) {
+        var merged = {};
+        var characterEvents = undefined;
+        var zoneEvents = undefined;
+        // Snapshot the plugin list at dispatch start so a mutation during
+        // the dispatch (a hook calls registry.register/unregister) cannot
+        // change which plugins run for THIS dispatch. Spec doesn't forbid
+        // mutation but the predictable behavior is "this dispatch sees
+        // the registry as it was at start".
+        var snapshot = this.plugins.slice();
+        for (var i = 0; i < snapshot.length; i++) {
+            var plugin = snapshot[i];
+            if (!plugin)
+                continue;
+            // Hook not implemented by this plugin? Skip without allocating
+            // anything. Use bracket access so the keyof typing carries through.
+            var hook = plugin[hookName];
+            if (typeof hook !== 'function')
+                continue;
+            var emitted;
+            try {
+                emitted = await invoke(plugin, ctx);
+            }
+            catch (err) {
+                // Log via the plugin's logger so the failure is tagged with
+                // the plugin name. ctx.logger may itself throw; if so, fall
+                // back to console (cannot let logger errors break dispatch).
+                try {
+                    ctx.logger.error('plugin hook ' + String(hookName) + ' threw', this.errorMeta(err));
+                }
+                catch {
+                    console.error('[plugin: ' + plugin.name + '] hook ' + String(hookName) + ' threw', this.errorMeta(err));
+                }
+                // Drop this plugin's contribution for this dispatch.
+                continue;
+            }
+            if (!emitted)
+                continue;
+            if (emitted.characterEvents && emitted.characterEvents.length > 0) {
+                if (!characterEvents)
+                    characterEvents = [];
+                for (var ci = 0; ci < emitted.characterEvents.length; ci++) {
+                    var ce = emitted.characterEvents[ci];
+                    if (ce)
+                        characterEvents.push(ce);
+                }
+            }
+            if (emitted.zoneEvents && emitted.zoneEvents.length > 0) {
+                if (!zoneEvents)
+                    zoneEvents = [];
+                for (var zi = 0; zi < emitted.zoneEvents.length; zi++) {
+                    var ze = emitted.zoneEvents[zi];
+                    if (ze)
+                        zoneEvents.push(ze);
+                }
+            }
+        }
+        if (characterEvents)
+            merged.characterEvents = characterEvents;
+        if (zoneEvents)
+            merged.zoneEvents = zoneEvents;
+        return merged;
+    }
+    // Pull useful fields out of an unknown error for log meta. Avoids
+    // throwing on non-Error throws (strings, objects, undefined).
+    errorMeta(err) {
+        if (err instanceof Error) {
+            return {
+                error_name: err.name,
+                error_message: err.message,
+                error_stack: err.stack ?? null,
+            };
+        }
+        var safe;
+        try {
+            safe = JSON.stringify(err);
+        }
+        catch {
+            safe = String(err);
+        }
+        return { error: safe };
+    }
+}
+//# sourceMappingURL=ai-plugin-registry.js.map

package/dist/director/ai/ai-plugin-registry.js.map

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

package/dist/director/ai/mock-ai-plugin.d.ts

@@ -0,0 +1,24 @@
+import type { DirectorEvent } from '../event-envelope.js';
+import type { IAIPlugin, EmittedEvents, PluginContext, ZoneEvent } from './plugin.js';
+export interface MockAIPluginScriptEntry {
+    atTick: number;
+    characterEvents?: DirectorEvent[];
+    zoneEvents?: ZoneEvent[];
+}
+export interface MockAIPluginOptions {
+    name?: string;
+    script: ReadonlyArray<MockAIPluginScriptEntry>;
+    priority?: number;
+}
+export declare class MockAIPlugin implements IAIPlugin {
+    readonly name: string;
+    readonly version = "0.0.1";
+    readonly priority: number;
+    private readonly script;
+    private tick;
+    constructor(opts: MockAIPluginOptions);
+    onTick(_ctx: PluginContext): Promise<EmittedEvents>;
+    currentTick(): number;
+    resetTick(): void;
+}
+//# sourceMappingURL=mock-ai-plugin.d.ts.map

package/dist/director/ai/mock-ai-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-ai-plugin.d.ts","sourceRoot":"","sources":["../../../src/director/ai/mock-ai-plugin.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EACb,aAAa,EACb,SAAS,EACV,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,uBAAuB;IAGtC,MAAM,EAAE,MAAM,CAAC;IAEf,eAAe,CAAC,EAAE,aAAa,EAAE,CAAC;IAElC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAIlC,IAAI,CAAC,EAAE,MAAM,CAAC;IAId,MAAM,EAAE,aAAa,CAAC,uBAAuB,CAAC,CAAC;IAE/C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,YAAa,YAAW,SAAS;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAIhE,OAAO,CAAC,IAAI,CAAK;gBAEL,IAAI,EAAE,mBAAmB;IAM/B,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IA+BzD,WAAW,IAAI,MAAM;IAOrB,SAAS,IAAI,IAAI;CAGlB"}

package/dist/director/ai/mock-ai-plugin.js

@@ -0,0 +1,83 @@
+// MockAIPlugin - deterministic synthetic events for tests + offline demo.
+//
+// Per LOOM-DIRECTOR-PROTOCOL-V2 Section 5.4: replaces real LLM
+// dispatch with a scripted sequence of events keyed by tick number.
+// Engine tests can wire this in place of an Anthropic-backed plugin
+// to verify registry behavior, dispatch order, and downstream emit
+// paths without burning API budget. The offline demo can use it to
+// drive a showcase loop with predictable events.
+//
+// Determinism: the script is consulted on each onTick() call. The
+// plugin keeps an internal tick counter that increments every call;
+// the constructor's `tickKey` option lets the caller provide a
+// counter source instead (e.g. tying it to the engine's frame index
+// for cross-process consistency).
+//
+// Multiple instances: the constructor accepts an optional `name`
+// override so a test can register two MockAIPlugins with different
+// scripts. Without override, the name is 'mock' and registering two
+// instances throws AIPluginDuplicateError (intentional - the spec
+// keys plugins by name).
+export class MockAIPlugin {
+    name;
+    version = '0.0.1';
+    priority;
+    script;
+    // Current tick count; increments every onTick() call. The first
+    // tick observed is 1 (matches the typical engine convention where
+    // tick 0 is "before-first-update").
+    tick = 0;
+    constructor(opts) {
+        this.name = opts.name ?? 'mock';
+        this.priority = opts.priority ?? 999;
+        this.script = opts.script;
+    }
+    async onTick(_ctx) {
+        this.tick++;
+        var characterEvents;
+        var zoneEvents;
+        for (var i = 0; i < this.script.length; i++) {
+            var entry = this.script[i];
+            if (!entry)
+                continue;
+            if (entry.atTick !== this.tick)
+                continue;
+            if (entry.characterEvents && entry.characterEvents.length > 0) {
+                if (!characterEvents)
+                    characterEvents = [];
+                for (var ci = 0; ci < entry.characterEvents.length; ci++) {
+                    var ce = entry.characterEvents[ci];
+                    if (ce)
+                        characterEvents.push(ce);
+                }
+            }
+            if (entry.zoneEvents && entry.zoneEvents.length > 0) {
+                if (!zoneEvents)
+                    zoneEvents = [];
+                for (var zi = 0; zi < entry.zoneEvents.length; zi++) {
+                    var ze = entry.zoneEvents[zi];
+                    if (ze)
+                        zoneEvents.push(ze);
+                }
+            }
+        }
+        var emitted = {};
+        if (characterEvents)
+            emitted.characterEvents = characterEvents;
+        if (zoneEvents)
+            emitted.zoneEvents = zoneEvents;
+        return emitted;
+    }
+    // Inspect-only: current tick count. Useful in tests to assert the
+    // plugin saw the expected number of dispatches.
+    currentTick() {
+        return this.tick;
+    }
+    // Reset the tick counter to 0 so the script can replay from the
+    // start. Tests that re-use a single plugin across multiple cases
+    // call this between cases.
+    resetTick() {
+        this.tick = 0;
+    }
+}
+//# sourceMappingURL=mock-ai-plugin.js.map

package/dist/director/ai/mock-ai-plugin.js.map

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

package/dist/director/ai/plugin-context.d.ts

@@ -0,0 +1,27 @@
+import type { PluginContext, PluginLogger, PluginStorage, PeerInfo, CharacterState } from './plugin.js';
+export declare class MapPluginStorage {
+    private readonly store;
+    forPlugin(pluginName: string): PluginStorage;
+    clearPlugin(pluginName: string): void;
+    size(): number;
+    private composeKey;
+}
+export declare class ConsolePluginLogger implements PluginLogger {
+    private readonly pluginName;
+    constructor(pluginName: string);
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+    private write;
+}
+export interface BuildPluginContextOptions {
+    pluginName: string;
+    storage: MapPluginStorage;
+    logger?: PluginLogger;
+    getZonePeers?: (zoneId: string) => ReadonlyArray<PeerInfo>;
+    getCharacterState?: (characterId: string) => Readonly<CharacterState>;
+    getZoneState?: (zoneId: string) => ReadonlyMap<string, unknown>;
+    now?: () => number;
+}
+export declare function buildPluginContext(opts: BuildPluginContextOptions): PluginContext;
+//# sourceMappingURL=plugin-context.d.ts.map

package/dist/director/ai/plugin-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-context.d.ts","sourceRoot":"","sources":["../../../src/director/ai/plugin-context.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,cAAc,EACf,MAAM,aAAa,CAAC;AAQrB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IAKpD,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa;IAkB5C,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAsBrC,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,UAAU;CAGnB;AAQD,qBAAa,mBAAoB,YAAW,YAAY;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,MAAM;IAE/C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIvD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIvD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIxD,OAAO,CAAC,KAAK;CAwBd;AAYD,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,gBAAgB,CAAC;IAE1B,MAAM,CAAC,EAAE,YAAY,CAAC;IAGtB,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC3D,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,QAAQ,CAAC,cAAc,CAAC,CAAC;IACtE,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,aAAa,CAmCjF"}