@sharpee/text-service 0.9.60-beta

package/dist/stages/filter.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Event filtering stage
+ *
+ * Filters out events that should not produce text output:
+ * - System events (system.*)
+ *
+ * @see ADR-096 Text Service Architecture
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterEvents = filterEvents;
+/**
+ * Filter events that should produce text output
+ */
+function filterEvents(events) {
+    return events.filter((event) => {
+        // Skip system events
+        if (event.type.startsWith('system.')) {
+            return false;
+        }
+        // Skip platform events (save/restore/quit/restart requests and completions)
+        if (event.type.startsWith('platform.')) {
+            return false;
+        }
+        return true;
+    });
+}
+//# sourceMappingURL=filter.js.map

package/dist/stages/filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../src/stages/filter.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAOH,oCAcC;AAjBD;;GAEG;AACH,SAAgB,YAAY,CAAC,MAAwB;IACnD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAC7B,qBAAqB;QACrB,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACrC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,4EAA4E;QAC5E,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACvC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/stages/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Pipeline stages for TextService
+ *
+ * @see ADR-096 Text Service Architecture
+ */
+export { filterEvents } from './filter.js';
+export { sortEventsForProse, getChainMetadata } from './sort.js';
+export { createBlock, extractValue } from './assemble.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/stages/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/stages/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/stages/index.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Pipeline stages for TextService
+ *
+ * @see ADR-096 Text Service Architecture
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractValue = exports.createBlock = exports.getChainMetadata = exports.sortEventsForProse = exports.filterEvents = void 0;
+var filter_js_1 = require("./filter.js");
+Object.defineProperty(exports, "filterEvents", { enumerable: true, get: function () { return filter_js_1.filterEvents; } });
+var sort_js_1 = require("./sort.js");
+Object.defineProperty(exports, "sortEventsForProse", { enumerable: true, get: function () { return sort_js_1.sortEventsForProse; } });
+Object.defineProperty(exports, "getChainMetadata", { enumerable: true, get: function () { return sort_js_1.getChainMetadata; } });
+var assemble_js_1 = require("./assemble.js");
+Object.defineProperty(exports, "createBlock", { enumerable: true, get: function () { return assemble_js_1.createBlock; } });
+Object.defineProperty(exports, "extractValue", { enumerable: true, get: function () { return assemble_js_1.extractValue; } });
+//# sourceMappingURL=index.js.map

package/dist/stages/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/stages/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,yCAA2C;AAAlC,yGAAA,YAAY,OAAA;AACrB,qCAAiE;AAAxD,6GAAA,kBAAkB,OAAA;AAAE,2GAAA,gBAAgB,OAAA;AAC7C,6CAA0D;AAAjD,0GAAA,WAAW,OAAA;AAAE,2GAAA,YAAY,OAAA"}

package/dist/stages/sort.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Event sorting stage
+ *
+ * Sorts events within each transaction for correct prose order:
+ * 1. action.* events first (the main action result)
+ * 2. Then by chainDepth (lower depth first)
+ *
+ * Events arrive from Engine in emission order, but prose requires:
+ * - Action result first ("You open the chest.")
+ * - Then consequences ("Inside you see...")
+ *
+ * @see ADR-094 Event Chaining
+ * @see ADR-096 Text Service Architecture
+ */
+import type { ISemanticEvent } from '@sharpee/core';
+/**
+ * Event data with chain metadata (ADR-094)
+ */
+interface ChainMetadata {
+    _transactionId?: string;
+    _chainDepth?: number;
+    _chainedFrom?: string;
+    _chainSourceId?: string;
+}
+/**
+ * Sort events for correct prose order within transactions
+ *
+ * Uses stable sort to preserve order across different transactions.
+ */
+export declare function sortEventsForProse(events: ISemanticEvent[]): ISemanticEvent[];
+/**
+ * Extract chain metadata from event data
+ */
+export declare function getChainMetadata(event: ISemanticEvent): ChainMetadata;
+export {};
+//# sourceMappingURL=sort.d.ts.map

package/dist/stages/sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort.d.ts","sourceRoot":"","sources":["../../src/stages/sort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;GAEG;AACH,UAAU,aAAa;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CA6C7E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,aAAa,CAQrE"}

package/dist/stages/sort.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Event sorting stage
+ *
+ * Sorts events within each transaction for correct prose order:
+ * 1. action.* events first (the main action result)
+ * 2. Then by chainDepth (lower depth first)
+ *
+ * Events arrive from Engine in emission order, but prose requires:
+ * - Action result first ("You open the chest.")
+ * - Then consequences ("Inside you see...")
+ *
+ * @see ADR-094 Event Chaining
+ * @see ADR-096 Text Service Architecture
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortEventsForProse = sortEventsForProse;
+exports.getChainMetadata = getChainMetadata;
+/**
+ * Sort events for correct prose order within transactions
+ *
+ * Uses stable sort to preserve order across different transactions.
+ */
+function sortEventsForProse(events) {
+    return [...events].sort((a, b) => {
+        const aData = a.data;
+        const bData = b.data;
+        const aTxnId = aData?._transactionId;
+        const bTxnId = bData?._transactionId;
+        // Game lifecycle events come first, before everything
+        // This ensures the banner displays before the first room description
+        // Note: Only match specific lifecycle events, NOT game.message (which is handled elsewhere)
+        const LIFECYCLE_EVENTS = ['game.started', 'game.starting', 'game.loading', 'game.loaded', 'game.initialized'];
+        const aIsGameLifecycle = LIFECYCLE_EVENTS.includes(a.type);
+        const bIsGameLifecycle = LIFECYCLE_EVENTS.includes(b.type);
+        if (aIsGameLifecycle && !bIsGameLifecycle)
+            return -1;
+        if (!aIsGameLifecycle && bIsGameLifecycle)
+            return 1;
+        // Different transactions or no transaction: maintain original order
+        if (aTxnId !== bTxnId)
+            return 0;
+        // Implicit take events should come first (before the main action result)
+        // "first taking the X" should appear before "X reads:..."
+        const aIsImplicitTake = a.type === 'if.event.implicit_take';
+        const bIsImplicitTake = b.type === 'if.event.implicit_take';
+        if (aIsImplicitTake && !bIsImplicitTake)
+            return -1;
+        if (!aIsImplicitTake && bIsImplicitTake)
+            return 1;
+        // Room description should come before action.success (for contents list)
+        // This ensures "Room Name\nDescription" appears before "You see X here."
+        const aIsRoomDesc = a.type === 'if.event.room.description' || a.type === 'if.event.room_description';
+        const bIsRoomDesc = b.type === 'if.event.room.description' || b.type === 'if.event.room_description';
+        if (aIsRoomDesc && !bIsRoomDesc)
+            return -1;
+        if (!aIsRoomDesc && bIsRoomDesc)
+            return 1;
+        // Same transaction: action.* first (after room description)
+        const aIsAction = a.type.startsWith('action.');
+        const bIsAction = b.type.startsWith('action.');
+        if (aIsAction && !bIsAction)
+            return -1;
+        if (!aIsAction && bIsAction)
+            return 1;
+        // Then by chain depth (lower depth first)
+        const aDepth = aData?._chainDepth ?? 0;
+        const bDepth = bData?._chainDepth ?? 0;
+        return aDepth - bDepth;
+    });
+}
+/**
+ * Extract chain metadata from event data
+ */
+function getChainMetadata(event) {
+    const data = event.data;
+    return {
+        _transactionId: data?._transactionId,
+        _chainDepth: data?._chainDepth,
+        _chainedFrom: data?._chainedFrom,
+        _chainSourceId: data?._chainSourceId,
+    };
+}
+//# sourceMappingURL=sort.js.map

package/dist/stages/sort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort.js","sourceRoot":"","sources":["../../src/stages/sort.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;AAmBH,gDA6CC;AAKD,4CAQC;AA/DD;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,MAAwB;IACzD,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC/B,MAAM,KAAK,GAAG,CAAC,CAAC,IAAiC,CAAC;QAClD,MAAM,KAAK,GAAG,CAAC,CAAC,IAAiC,CAAC;QAElD,MAAM,MAAM,GAAG,KAAK,EAAE,cAAc,CAAC;QACrC,MAAM,MAAM,GAAG,KAAK,EAAE,cAAc,CAAC;QAErC,sDAAsD;QACtD,qEAAqE;QACrE,4FAA4F;QAC5F,MAAM,gBAAgB,GAAG,CAAC,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,kBAAkB,CAAC,CAAC;QAC9G,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,gBAAgB,IAAI,CAAC,gBAAgB;YAAE,OAAO,CAAC,CAAC,CAAC;QACrD,IAAI,CAAC,gBAAgB,IAAI,gBAAgB;YAAE,OAAO,CAAC,CAAC;QAEpD,oEAAoE;QACpE,IAAI,MAAM,KAAK,MAAM;YAAE,OAAO,CAAC,CAAC;QAEhC,yEAAyE;QACzE,0DAA0D;QAC1D,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,KAAK,wBAAwB,CAAC;QAC5D,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,KAAK,wBAAwB,CAAC;QAC5D,IAAI,eAAe,IAAI,CAAC,eAAe;YAAE,OAAO,CAAC,CAAC,CAAC;QACnD,IAAI,CAAC,eAAe,IAAI,eAAe;YAAE,OAAO,CAAC,CAAC;QAElD,yEAAyE;QACzE,yEAAyE;QACzE,MAAM,WAAW,GAAG,CAAC,CAAC,IAAI,KAAK,2BAA2B,IAAI,CAAC,CAAC,IAAI,KAAK,2BAA2B,CAAC;QACrG,MAAM,WAAW,GAAG,CAAC,CAAC,IAAI,KAAK,2BAA2B,IAAI,CAAC,CAAC,IAAI,KAAK,2BAA2B,CAAC;QACrG,IAAI,WAAW,IAAI,CAAC,WAAW;YAAE,OAAO,CAAC,CAAC,CAAC;QAC3C,IAAI,CAAC,WAAW,IAAI,WAAW;YAAE,OAAO,CAAC,CAAC;QAE1C,4DAA4D;QAC5D,MAAM,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,SAAS,IAAI,CAAC,SAAS;YAAE,OAAO,CAAC,CAAC,CAAC;QACvC,IAAI,CAAC,SAAS,IAAI,SAAS;YAAE,OAAO,CAAC,CAAC;QAEtC,0CAA0C;QAC1C,MAAM,MAAM,GAAG,KAAK,EAAE,WAAW,IAAI,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,KAAK,EAAE,WAAW,IAAI,CAAC,CAAC;QACvC,OAAO,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAAC,KAAqB;IACpD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAiC,CAAC;IACrD,OAAO;QACL,cAAc,EAAE,IAAI,EAAE,cAAc;QACpC,WAAW,EAAE,IAAI,EAAE,WAAW;QAC9B,YAAY,EAAE,IAAI,EAAE,YAAY;QAChC,cAAc,EAAE,IAAI,EAAE,cAAc;KACrC,CAAC;AACJ,CAAC"}

package/dist/text-service.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Text Service
+ *
+ * Orchestrates the text output pipeline:
+ * 1. Filter - remove system events
+ * 2. Sort - order events for prose (ADR-094)
+ * 3. Process - route to handlers
+ * 4. Assemble - create ITextBlock with decorations
+ *
+ * Stateless transformer: events in, TextBlocks out.
+ * Inspired by FyreVM channel I/O (2009).
+ *
+ * @see ADR-096 Text Service Architecture
+ */
+import type { ITextBlock } from '@sharpee/text-blocks';
+import type { LanguageProvider } from '@sharpee/if-domain';
+import type { ISemanticEvent } from '@sharpee/core';
+/**
+ * Text service interface (ADR-096)
+ *
+ * Stateless transformer: takes events, returns TextBlocks.
+ * Engine calls processTurn() after each turn completes.
+ */
+export interface ITextService {
+    /**
+     * Process turn events and produce TextBlocks.
+     * Called by Engine after turn completes.
+     *
+     * @param events - All events from this turn (including chained events)
+     * @returns TextBlocks for client rendering
+     */
+    processTurn(events: ISemanticEvent[]): ITextBlock[];
+}
+/**
+ * TextService implementation
+ *
+ * Orchestrates the pipeline: filter → sort → process → assemble
+ */
+export declare class TextService implements ITextService {
+    private readonly languageProvider;
+    constructor(languageProvider: LanguageProvider);
+    processTurn(events: ISemanticEvent[]): ITextBlock[];
+    /**
+     * Route event to appropriate handler
+     */
+    private routeToHandler;
+    /**
+     * NEW PATTERN (ADR-097): Process domain events that carry messageId directly.
+     *
+     * Returns text blocks if event has messageId and message was found.
+     * Returns null to fall through to legacy handling.
+     *
+     * This allows gradual migration: actions can be updated one at a time
+     * to emit domain events with messageId instead of separate action.success.
+     */
+    private tryProcessDomainEventMessage;
+    /**
+     * Handle if.event.implicit_take events
+     * Produces "(first taking the X)" message
+     */
+    private handleImplicitTake;
+    /**
+     * Handle command.failed events
+     * These occur when parsing or entity resolution fails
+     */
+    private handleCommandFailed;
+    /**
+     * Handle client.query events (disambiguation, confirmations, etc.)
+     */
+    private handleClientQuery;
+    /**
+     * Format a list of candidate names as natural English
+     * e.g., "the red ball or the blue ball" or "the sword, the axe, or the knife"
+     */
+    private formatCandidateList;
+}
+/**
+ * Create a TextService with the given LanguageProvider.
+ * LanguageProvider supplies templates (standard + story-registered).
+ *
+ * @param languageProvider - Provider for template resolution
+ * @returns Configured TextService instance
+ */
+export declare function createTextService(languageProvider: LanguageProvider): ITextService;
+//# sourceMappingURL=text-service.d.ts.map

package/dist/text-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-service.d.ts","sourceRoot":"","sources":["../src/text-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAepD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,UAAU,EAAE,CAAC;CACrD;AAyBD;;;;GAIG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;gBAExC,gBAAgB,EAAE,gBAAgB;IAI9C,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,UAAU,EAAE;IAmBnD;;OAEG;IACH,OAAO,CAAC,cAAc;IAgDtB;;;;;;;;OAQG;IACH,OAAO,CAAC,4BAA4B;IAqCpC;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA4B3B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAwBzB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;CAe5B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,YAAY,CAElF"}

package/dist/text-service.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * Text Service
+ *
+ * Orchestrates the text output pipeline:
+ * 1. Filter - remove system events
+ * 2. Sort - order events for prose (ADR-094)
+ * 3. Process - route to handlers
+ * 4. Assemble - create ITextBlock with decorations
+ *
+ * Stateless transformer: events in, TextBlocks out.
+ * Inspired by FyreVM channel I/O (2009).
+ *
+ * @see ADR-096 Text Service Architecture
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TextService = void 0;
+exports.createTextService = createTextService;
+const text_blocks_1 = require("@sharpee/text-blocks");
+// Pipeline stages
+const filter_js_1 = require("./stages/filter.js");
+const sort_js_1 = require("./stages/sort.js");
+const assemble_js_1 = require("./stages/assemble.js");
+const room_js_1 = require("./handlers/room.js");
+const action_js_1 = require("./handlers/action.js");
+const revealed_js_1 = require("./handlers/revealed.js");
+const generic_js_1 = require("./handlers/generic.js");
+const game_js_1 = require("./handlers/game.js");
+/**
+ * State change events that don't produce text output (LEGACY pattern).
+ * The corresponding action.success event provides the message.
+ *
+ * NOTE: With the simplified event pattern (ADR-097), domain events can carry
+ * messageId directly. When they do, we process them and skip action.success.
+ * This set is only checked when events DON'T have messageId (backward compat).
+ *
+ * @deprecated Will be removed once all actions migrate to simplified pattern
+ */
+const STATE_CHANGE_EVENTS = new Set([
+    'if.event.opened',
+    'if.event.closed',
+    'if.event.locked',
+    'if.event.unlocked',
+    'if.event.switched_on',
+    'if.event.switched_off',
+    'if.event.taken', // State change - action.success provides message
+    'if.event.dropped', // State change - action.success provides message
+    'if.event.read', // State change - action.success provides message
+    // Note: if.event.room.description removed - specialized handler handles it
+]);
+/**
+ * TextService implementation
+ *
+ * Orchestrates the pipeline: filter → sort → process → assemble
+ */
+class TextService {
+    languageProvider;
+    constructor(languageProvider) {
+        this.languageProvider = languageProvider;
+    }
+    processTurn(events) {
+        // Pipeline: filter → sort → process
+        const filtered = (0, filter_js_1.filterEvents)(events);
+        const sorted = (0, sort_js_1.sortEventsForProse)(filtered);
+        // Process each event through handlers
+        const handlerContext = {
+            languageProvider: this.languageProvider,
+        };
+        const blocks = [];
+        for (const event of sorted) {
+            const eventBlocks = this.routeToHandler(event, handlerContext);
+            blocks.push(...eventBlocks);
+        }
+        return blocks;
+    }
+    /**
+     * Route event to appropriate handler
+     */
+    routeToHandler(event, context) {
+        // NEW PATTERN (ADR-097): Domain events can carry messageId directly.
+        // If present, look up message and return block - no action.success needed.
+        const result = this.tryProcessDomainEventMessage(event, context);
+        if (result) {
+            return result;
+        }
+        // LEGACY PATTERN: Skip state change events (action.success provides message)
+        if (STATE_CHANGE_EVENTS.has(event.type)) {
+            return [];
+        }
+        switch (event.type) {
+            case 'game.started':
+                return (0, game_js_1.handleGameStarted)(event, context);
+            case 'if.event.room_description':
+            case 'if.event.room.description':
+                return (0, room_js_1.handleRoomDescription)(event, context);
+            case 'action.success':
+                return (0, action_js_1.handleActionSuccess)(event, context);
+            case 'action.failure':
+            case 'action.blocked':
+                return (0, action_js_1.handleActionFailure)(event, context);
+            case 'game.message':
+                return (0, generic_js_1.handleGameMessage)(event, context);
+            case 'if.event.revealed':
+                return (0, revealed_js_1.handleRevealed)(event, context);
+            case 'if.event.implicit_take':
+                return this.handleImplicitTake(event, context);
+            case 'command.failed':
+                return this.handleCommandFailed(event, context);
+            case 'client.query':
+                return this.handleClientQuery(event, context);
+            default:
+                return (0, generic_js_1.handleGenericEvent)(event, context);
+        }
+    }
+    /**
+     * NEW PATTERN (ADR-097): Process domain events that carry messageId directly.
+     *
+     * Returns text blocks if event has messageId and message was found.
+     * Returns null to fall through to legacy handling.
+     *
+     * This allows gradual migration: actions can be updated one at a time
+     * to emit domain events with messageId instead of separate action.success.
+     */
+    tryProcessDomainEventMessage(event, context) {
+        const data = event.data;
+        // No messageId = fall through to legacy handling
+        if (!data?.messageId) {
+            return null;
+        }
+        // Skip action.success/failure/blocked - they use legacy handler
+        // (prevents double processing during migration)
+        if (event.type.startsWith('action.')) {
+            return null;
+        }
+        // Look up message via language provider
+        if (!context.languageProvider) {
+            return null;
+        }
+        const message = context.languageProvider.getMessage(data.messageId, data.params);
+        // If message wasn't found (returns the messageId), fall through to legacy
+        if (message === data.messageId) {
+            return null;
+        }
+        // Determine block key based on event type
+        const blockKey = event.type.includes('blocked') || event.type.includes('failure')
+            ? text_blocks_1.BLOCK_KEYS.ACTION_BLOCKED
+            : text_blocks_1.BLOCK_KEYS.ACTION_RESULT;
+        return [(0, assemble_js_1.createBlock)(blockKey, message)];
+    }
+    /**
+     * Handle if.event.implicit_take events
+     * Produces "(first taking the X)" message
+     */
+    handleImplicitTake(event, _context) {
+        const data = event.data;
+        const itemName = data.itemName || 'something';
+        return [(0, assemble_js_1.createBlock)(text_blocks_1.BLOCK_KEYS.ACTION_RESULT, `(first taking the ${itemName})`)];
+    }
+    /**
+     * Handle command.failed events
+     * These occur when parsing or entity resolution fails
+     */
+    handleCommandFailed(event, context) {
+        const data = event.data;
+        // Try to get a user-friendly message based on the reason
+        if (data.reason) {
+            // Check for specific failure reasons
+            if (data.reason.includes('ENTITY_NOT_FOUND') || data.reason.includes('modifiers_not_matched')) {
+                // Entity resolution failed - player referred to something that doesn't exist or can't be found
+                const message = context.languageProvider?.getMessage('core.entity_not_found')
+                    ?? "I don't see that here.";
+                return [(0, assemble_js_1.createBlock)(text_blocks_1.BLOCK_KEYS.ERROR, message)];
+            }
+            // Note: AMBIGUOUS_ENTITY now uses client.query event, not command.failed
+            if (data.reason.includes('NO_MATCH') || data.reason.includes('parse')) {
+                const message = context.languageProvider?.getMessage('core.command_not_understood')
+                    ?? "I don't understand that.";
+                return [(0, assemble_js_1.createBlock)(text_blocks_1.BLOCK_KEYS.ERROR, message)];
+            }
+        }
+        // Generic fallback
+        const message = context.languageProvider?.getMessage('core.command_failed')
+            ?? "I don't understand that.";
+        return [(0, assemble_js_1.createBlock)(text_blocks_1.BLOCK_KEYS.ERROR, message)];
+    }
+    /**
+     * Handle client.query events (disambiguation, confirmations, etc.)
+     */
+    handleClientQuery(event, context) {
+        const data = event.data;
+        // Only handle disambiguation queries here
+        if (data.source !== 'disambiguation') {
+            return [];
+        }
+        // Format candidates as natural list
+        const candidateNames = (data.candidates || []).map(c => c.name);
+        const options = this.formatCandidateList(candidateNames);
+        // Get message template with options
+        const message = context.languageProvider?.getMessage('core.disambiguation_prompt', { options })
+            ?? `Which do you mean: ${options}?`;
+        return [(0, assemble_js_1.createBlock)(text_blocks_1.BLOCK_KEYS.ERROR, message)];
+    }
+    /**
+     * Format a list of candidate names as natural English
+     * e.g., "the red ball or the blue ball" or "the sword, the axe, or the knife"
+     */
+    formatCandidateList(names) {
+        if (names.length === 0)
+            return '';
+        if (names.length === 1)
+            return `the ${names[0]}`;
+        // Add "the" article to each name
+        const withArticles = names.map(n => `the ${n}`);
+        if (withArticles.length === 2) {
+            return `${withArticles[0]} or ${withArticles[1]}`;
+        }
+        // Oxford comma style: "the X, the Y, or the Z"
+        const last = withArticles.pop();
+        return `${withArticles.join(', ')}, or ${last}`;
+    }
+}
+exports.TextService = TextService;
+/**
+ * Create a TextService with the given LanguageProvider.
+ * LanguageProvider supplies templates (standard + story-registered).
+ *
+ * @param languageProvider - Provider for template resolution
+ * @returns Configured TextService instance
+ */
+function createTextService(languageProvider) {
+    return new TextService(languageProvider);
+}
+//# sourceMappingURL=text-service.js.map

package/dist/text-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-service.js","sourceRoot":"","sources":["../src/text-service.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AA6RH,8CAEC;AA5RD,sDAAkD;AAIlD,kBAAkB;AAClB,kDAAkD;AAClD,8CAAsD;AACtD,sDAAmD;AAInD,gDAA2D;AAC3D,oDAAgF;AAChF,wDAAwD;AACxD,sDAA8E;AAC9E,gDAAuD;AAmBvD;;;;;;;;;GASG;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC;IAClC,iBAAiB;IACjB,iBAAiB;IACjB,iBAAiB;IACjB,mBAAmB;IACnB,sBAAsB;IACtB,uBAAuB;IACvB,gBAAgB,EAAQ,iDAAiD;IACzE,kBAAkB,EAAM,iDAAiD;IACzE,eAAe,EAAS,iDAAiD;IACzE,2EAA2E;CAC5E,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAa,WAAW;IACL,gBAAgB,CAAmB;IAEpD,YAAY,gBAAkC;QAC5C,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;IAC3C,CAAC;IAED,WAAW,CAAC,MAAwB;QAClC,oCAAoC;QACpC,MAAM,QAAQ,GAAG,IAAA,wBAAY,EAAC,MAAM,CAAC,CAAC;QACtC,MAAM,MAAM,GAAG,IAAA,4BAAkB,EAAC,QAAQ,CAAC,CAAC;QAE5C,sCAAsC;QACtC,MAAM,cAAc,GAAmB;YACrC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;SACxC,CAAC;QAEF,MAAM,MAAM,GAAiB,EAAE,CAAC;QAChC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;YAC/D,MAAM,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC;QAC9B,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACK,cAAc,CAAC,KAAqB,EAAE,OAAuB;QACnE,qEAAqE;QACrE,2EAA2E;QAC3E,MAAM,MAAM,GAAG,IAAI,CAAC,4BAA4B,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACjE,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,6EAA6E;QAC7E,IAAI,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACxC,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,cAAc;gBACjB,OAAO,IAAA,2BAAiB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAE3C,KAAK,2BAA2B,CAAC;YACjC,KAAK,2BAA2B;gBAC9B,OAAO,IAAA,+BAAqB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAE/C,KAAK,gBAAgB;gBACnB,OAAO,IAAA,+BAAmB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAE7C,KAAK,gBAAgB,CAAC;YACtB,KAAK,gBAAgB;gBACnB,OAAO,IAAA,+BAAmB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAE7C,KAAK,cAAc;gBACjB,OAAO,IAAA,8BAAiB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAE3C,KAAK,mBAAmB;gBACtB,OAAO,IAAA,4BAAc,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAExC,KAAK,wBAAwB;gBAC3B,OAAO,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAEjD,KAAK,gBAAgB;gBACnB,OAAO,IAAI,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAElD,KAAK,cAAc;gBACjB,OAAO,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAEhD;gBACE,OAAO,IAAA,+BAAkB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACK,4BAA4B,CAClC,KAAqB,EACrB,OAAuB;QAEvB,MAAM,IAAI,GAAG,KAAK,CAAC,IAA4E,CAAC;QAEhG,iDAAiD;QACjD,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,gEAAgE;QAChE,gDAAgD;QAChD,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,wCAAwC;QACxC,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAEjF,0EAA0E;QAC1E,IAAI,OAAO,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,0CAA0C;QAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;YAC/E,CAAC,CAAC,wBAAU,CAAC,cAAc;YAC3B,CAAC,CAAC,wBAAU,CAAC,aAAa,CAAC;QAE7B,OAAO,CAAC,IAAA,yBAAW,EAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACK,kBAAkB,CAAC,KAAqB,EAAE,QAAwB;QACxE,MAAM,IAAI,GAAG,KAAK,CAAC,IAA6B,CAAC;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,WAAW,CAAC;QAC9C,OAAO,CAAC,IAAA,yBAAW,EAAC,wBAAU,CAAC,aAAa,EAAE,qBAAqB,QAAQ,GAAG,CAAC,CAAC,CAAC;IACnF,CAAC;IAED;;;OAGG;IACK,mBAAmB,CAAC,KAAqB,EAAE,OAAuB;QACxE,MAAM,IAAI,GAAG,KAAK,CAAC,IAA2C,CAAC;QAE/D,yDAAyD;QACzD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,qCAAqC;YACrC,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,CAAC;gBAC9F,+FAA+F;gBAC/F,MAAM,OAAO,GAAG,OAAO,CAAC,gBAAgB,EAAE,UAAU,CAAC,uBAAuB,CAAC;uBACxE,wBAAwB,CAAC;gBAC9B,OAAO,CAAC,IAAA,yBAAW,EAAC,wBAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;YAClD,CAAC;YAED,yEAAyE;YAEzE,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBACtE,MAAM,OAAO,GAAG,OAAO,CAAC,gBAAgB,EAAE,UAAU,CAAC,6BAA6B,CAAC;uBAC9E,0BAA0B,CAAC;gBAChC,OAAO,CAAC,IAAA,yBAAW,EAAC,wBAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;YAClD,CAAC;QACH,CAAC;QAED,mBAAmB;QACnB,MAAM,OAAO,GAAG,OAAO,CAAC,gBAAgB,EAAE,UAAU,CAAC,qBAAqB,CAAC;eACtE,0BAA0B,CAAC;QAChC,OAAO,CAAC,IAAA,yBAAW,EAAC,wBAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,KAAqB,EAAE,OAAuB;QACtE,MAAM,IAAI,GAAG,KAAK,CAAC,IAKlB,CAAC;QAEF,0CAA0C;QAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,gBAAgB,EAAE,CAAC;YACrC,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,oCAAoC;QACpC,MAAM,cAAc,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAChE,MAAM,OAAO,GAAG,IAAI,CAAC,mBAAmB,CAAC,cAAc,CAAC,CAAC;QAEzD,oCAAoC;QACpC,MAAM,OAAO,GAAG,OAAO,CAAC,gBAAgB,EAAE,UAAU,CAAC,4BAA4B,EAAE,EAAE,OAAO,EAAE,CAAC;eAC1F,sBAAsB,OAAO,GAAG,CAAC;QAEtC,OAAO,CAAC,IAAA,yBAAW,EAAC,wBAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,CAAC;IAED;;;OAGG;IACK,mBAAmB,CAAC,KAAe;QACzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAEjD,iCAAiC;QACjC,MAAM,YAAY,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAEhD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,CAAC;QAED,+CAA+C;QAC/C,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,EAAE,CAAC;QAChC,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IAClD,CAAC;CACF;AAnND,kCAmNC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,gBAAkC;IAClE,OAAO,IAAI,WAAW,CAAC,gBAAgB,CAAC,CAAC;AAC3C,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@sharpee/text-service",
+  "version": "0.9.60-beta",
+  "description": "Text service for Sharpee - resolves templates and produces ITextBlock output",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@sharpee/text-blocks": "0.9.60-beta",
+    "@sharpee/core": "0.9.60-beta",
+    "@sharpee/if-services": "0.9.60-beta",
+    "@sharpee/if-domain": "0.9.60-beta"
+  },
+  "devDependencies": {
+    "@types/node": "^18.0.0",
+    "@typescript-eslint/eslint-plugin": "^5.59.0",
+    "@typescript-eslint/parser": "^5.59.0",
+    "eslint": "^8.38.0",
+    "rimraf": "^5.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.6.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "interactive-fiction",
+    "if",
+    "text-adventure",
+    "sharpee",
+    "text-service",
+    "fyrevm"
+  ],
+  "author": "Sharpee Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ChicagoDave/sharpee.git",
+    "directory": "packages/text-service"
+  },
+  "homepage": "https://github.com/ChicagoDave/sharpee#readme",
+  "bugs": {
+    "url": "https://github.com/ChicagoDave/sharpee/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "test:ci": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "clean": "rimraf dist"
+  }
+}