@sharpee/engine 0.9.111 → 1.0.0

package/prose-pipeline/decorations/resolver.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Class-name resolver — bare bracket name → final CSS class name.
+ *
+ * Public interface: `resolveClassName`. Used by the parser to settle
+ * the platform-vs-author distinction at parse time so the wire shape
+ * carries renderer-ready strings.
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * @see ADR-174 §Platform vs author classes
+ * @see ADR-174 §Internal interfaces
+ */
+/**
+ * Resolve a bracketed name to its final CSS class name.
+ *
+ * Platform names (those listed in `PLATFORM_VOCABULARY`) receive the
+ * `sharpee-` prefix. Author names — anything else — pass through
+ * verbatim. Empty input returns the empty string; the caller is
+ * responsible for the AC-12 no-op-wrapper behavior, since the
+ * resolver is a pure mapping.
+ *
+ * @param rawName Bare name as written between `[` and `:` in the
+ *                template, e.g., `em`, `thief-taunt`.
+ * @returns Final class name to place on the wire as
+ *          `IDecoration.className`.
+ */
+export declare function resolveClassName(rawName: string): string;
+//# sourceMappingURL=resolver.d.ts.map

package/prose-pipeline/decorations/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/decorations/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMxD"}

package/prose-pipeline/decorations/resolver.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Class-name resolver — bare bracket name → final CSS class name.
+ *
+ * Public interface: `resolveClassName`. Used by the parser to settle
+ * the platform-vs-author distinction at parse time so the wire shape
+ * carries renderer-ready strings.
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * @see ADR-174 §Platform vs author classes
+ * @see ADR-174 §Internal interfaces
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveClassName = resolveClassName;
+const platform_vocabulary_1 = require("./platform-vocabulary");
+/**
+ * Resolve a bracketed name to its final CSS class name.
+ *
+ * Platform names (those listed in `PLATFORM_VOCABULARY`) receive the
+ * `sharpee-` prefix. Author names — anything else — pass through
+ * verbatim. Empty input returns the empty string; the caller is
+ * responsible for the AC-12 no-op-wrapper behavior, since the
+ * resolver is a pure mapping.
+ *
+ * @param rawName Bare name as written between `[` and `:` in the
+ *                template, e.g., `em`, `thief-taunt`.
+ * @returns Final class name to place on the wire as
+ *          `IDecoration.className`.
+ */
+function resolveClassName(rawName) {
+    if (rawName === '')
+        return '';
+    if (platform_vocabulary_1.PLATFORM_VOCABULARY.has(rawName)) {
+        return `sharpee-${rawName}`;
+    }
+    return rawName;
+}
+//# sourceMappingURL=resolver.js.map

package/prose-pipeline/decorations/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/decorations/resolver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAkBH,4CAMC;AAtBD,+DAA4D;AAE5D;;;;;;;;;;;;;GAaG;AACH,SAAgB,gBAAgB,CAAC,OAAe;IAC9C,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IAC9B,IAAI,yCAAmB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACrC,OAAO,WAAW,OAAO,EAAE,CAAC;IAC9B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/prose-pipeline/decorations/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Type re-exports for the engine-internal prose pipeline's decoration
+ * primitives. Sub-phase 1.1 declared these locally; sub-phase 1.2
+ * lifted the shape change into `@sharpee/text-blocks`, so the
+ * engine-side module now re-exports the canonical types from there.
+ *
+ * Public interface: `IDecoration`, `TextContent`. Used internally by
+ * the parser, resolver, and (after sub-phase 1.5) by the pipeline
+ * class.
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * @see ADR-174 §Wire shape
+ */
+export type { IDecoration, TextContent } from "../../../text-blocks/index";
+//# sourceMappingURL=types.d.ts.map

package/prose-pipeline/decorations/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/decorations/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC"}

package/prose-pipeline/decorations/types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Type re-exports for the engine-internal prose pipeline's decoration
+ * primitives. Sub-phase 1.1 declared these locally; sub-phase 1.2
+ * lifted the shape change into `@sharpee/text-blocks`, so the
+ * engine-side module now re-exports the canonical types from there.
+ *
+ * Public interface: `IDecoration`, `TextContent`. Used internally by
+ * the parser, resolver, and (after sub-phase 1.5) by the pipeline
+ * class.
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * @see ADR-174 §Wire shape
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/prose-pipeline/decorations/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/decorations/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG"}

package/prose-pipeline/handlers/about.d.ts

@@ -0,0 +1,31 @@
+/**
+ * About event handler — `if.event.about_displayed`.
+ *
+ * Produces the same structured banner as `handleGameStarted`, via the
+ * shared `buildBannerBlocks` helper. The ABOUT action gives us a
+ * flat `params: Record<string, string>` that mirrors `event.data.story`
+ * — we project it into the `BannerStoryInfo` shape and reuse the
+ * builder.
+ *
+ * Public interface: `handleAboutDisplayed`. Used by the pipeline's
+ * event-type dispatch.
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * @see ADR-174 §Engine-internal prose pipeline (port from text-service)
+ */
+import type { ITextBlock } from "../../../text-blocks/index";
+import type { ISemanticEvent } from "../../../core/index";
+import type { HandlerContext } from './types';
+/**
+ * Handle `if.event.about_displayed` by showing the structured banner.
+ *
+ * Reads the about action's `params` payload (title, author, version,
+ * description, engineVersion, buildDate, portedBy). The ABOUT action
+ * does not currently pass `credits` directly; when present, the
+ * builder falls back to `By {author}` for a single author-list line.
+ * Stories that want richer ABOUT credit blocks should propagate
+ * `credits` through the about action's params.
+ */
+export declare function handleAboutDisplayed(event: ISemanticEvent, context: HandlerContext): ITextBlock[];
+//# sourceMappingURL=about.d.ts.map

package/prose-pipeline/handlers/about.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"about.d.ts","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/handlers/about.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,GACtB,UAAU,EAAE,CAoBd"}

package/prose-pipeline/handlers/about.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * About event handler — `if.event.about_displayed`.
+ *
+ * Produces the same structured banner as `handleGameStarted`, via the
+ * shared `buildBannerBlocks` helper. The ABOUT action gives us a
+ * flat `params: Record<string, string>` that mirrors `event.data.story`
+ * — we project it into the `BannerStoryInfo` shape and reuse the
+ * builder.
+ *
+ * Public interface: `handleAboutDisplayed`. Used by the pipeline's
+ * event-type dispatch.
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * @see ADR-174 §Engine-internal prose pipeline (port from text-service)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAboutDisplayed = handleAboutDisplayed;
+const banner_1 = require("./banner");
+/**
+ * Handle `if.event.about_displayed` by showing the structured banner.
+ *
+ * Reads the about action's `params` payload (title, author, version,
+ * description, engineVersion, buildDate, portedBy). The ABOUT action
+ * does not currently pass `credits` directly; when present, the
+ * builder falls back to `By {author}` for a single author-list line.
+ * Stories that want richer ABOUT credit blocks should propagate
+ * `credits` through the about action's params.
+ */
+function handleAboutDisplayed(event, context) {
+    const data = event.data;
+    const params = (data?.params ?? {});
+    const story = {
+        title: stringOrUndef(params.title),
+        version: stringOrUndef(params.version),
+        buildDate: stringOrUndef(params.buildDate),
+        description: stringOrUndef(params.description),
+        author: stringOrUndef(params.author),
+        credits: Array.isArray(params.credits)
+            ? params.credits.filter((s) => typeof s === 'string' && s.length > 0)
+            : undefined,
+    };
+    const engineVersion = stringOrUndef(params.engineVersion);
+    return (0, banner_1.buildBannerBlocks)('about.text', story, engineVersion, context);
+}
+function stringOrUndef(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+//# sourceMappingURL=about.js.map

package/prose-pipeline/handlers/about.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"about.js","sourceRoot":"","sources":["../../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/handlers/about.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;AAiBH,oDAuBC;AAnCD,qCAAmE;AAEnE;;;;;;;;;GASG;AACH,SAAgB,oBAAoB,CAClC,KAAqB,EACrB,OAAuB;IAEvB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAwD,CAAC;IAC5E,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,IAAI,EAAE,CAA4B,CAAC;IAE/D,MAAM,KAAK,GAAoB;QAC7B,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC;QAClC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC;QACtC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC;QAC1C,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC;QAC9C,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC;QACpC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;YACpC,CAAC,CAAE,MAAM,CAAC,OAAqB,CAAC,MAAM,CAClC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAC1D;YACH,CAAC,CAAC,SAAS;KACd,CAAC;IAEF,MAAM,aAAa,GAAG,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAE1D,OAAO,IAAA,0BAAiB,EAAC,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;AACxE,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3E,CAAC"}

package/prose-pipeline/handlers/audibility.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Audibility event handler — ADR-172 Phase 7a, ported to engine prose
+ * pipeline per ADR-174.
+ *
+ * Handles `sound.audibility.heard`. Converts each `IAudibilityEvent`
+ * (per-listener perception of a propagated sound, produced by the
+ * engine's sound dispatcher in Phase 6) into a single text block via
+ * the `sound.heard.<kind>.<tier>` template family registered in the
+ * active language pack (lang-en-us ships defaults; stories override
+ * per kind).
+ *
+ * Naming discipline:
+ *   - `audio`      — Web Audio playback (ADR-169 `AudioManager`).
+ *   - `sound`      — the media-cue channel id (`media.sound.play`,
+ *                    ADR-163).
+ *   - `audibility` — ADR-172 perception of propagated sound, this
+ *                    handler.
+ *
+ * Public interface: `handleAudibilityHeard`.
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * Listener filtering: in single-user scope today the player is the
+ * only entity carrying `ListenerTrait` automatically, so every
+ * audibility event delivered here is for the player. The dispatcher
+ * already writes the listener id into `event.entities.target`; when
+ * L2's NPC-listener work lands, this handler will need to filter
+ * `event.entities.target === playerId` before rendering.
+ *
+ * @see ADR-172 — Spatial Sound Propagation §Channel routing
+ * @see ADR-174 §Engine-internal prose pipeline (port from text-service)
+ */
+import type { ITextBlock } from "../../../text-blocks/index";
+import type { ISemanticEvent } from "../../../core/index";
+import type { HandlerContext } from './types';
+/**
+ * Handle a `sound.audibility.heard` event.
+ *
+ * Resolves `sound.heard.<kind>.<tier>` from the language provider,
+ * falling back to `sound.heard.default.<tier>` when the kind-specific
+ * template is not registered. Returns one `ITextBlock` per event, or
+ * `[]` when the event is malformed, the tier is `silent`, or no
+ * template resolves.
+ */
+export declare function handleAudibilityHeard(event: ISemanticEvent, context: HandlerContext): ITextBlock[];
+//# sourceMappingURL=audibility.d.ts.map

package/prose-pipeline/handlers/audibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audibility.d.ts","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/handlers/audibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAK9C;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,GACtB,UAAU,EAAE,CAiCd"}

package/prose-pipeline/handlers/audibility.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Audibility event handler — ADR-172 Phase 7a, ported to engine prose
+ * pipeline per ADR-174.
+ *
+ * Handles `sound.audibility.heard`. Converts each `IAudibilityEvent`
+ * (per-listener perception of a propagated sound, produced by the
+ * engine's sound dispatcher in Phase 6) into a single text block via
+ * the `sound.heard.<kind>.<tier>` template family registered in the
+ * active language pack (lang-en-us ships defaults; stories override
+ * per kind).
+ *
+ * Naming discipline:
+ *   - `audio`      — Web Audio playback (ADR-169 `AudioManager`).
+ *   - `sound`      — the media-cue channel id (`media.sound.play`,
+ *                    ADR-163).
+ *   - `audibility` — ADR-172 perception of propagated sound, this
+ *                    handler.
+ *
+ * Public interface: `handleAudibilityHeard`.
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * Listener filtering: in single-user scope today the player is the
+ * only entity carrying `ListenerTrait` automatically, so every
+ * audibility event delivered here is for the player. The dispatcher
+ * already writes the listener id into `event.entities.target`; when
+ * L2's NPC-listener work lands, this handler will need to filter
+ * `event.entities.target === playerId` before rendering.
+ *
+ * @see ADR-172 — Spatial Sound Propagation §Channel routing
+ * @see ADR-174 §Engine-internal prose pipeline (port from text-service)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAudibilityHeard = handleAudibilityHeard;
+const text_blocks_1 = require("../../../text-blocks/index.js");
+const assemble_1 = require("../assemble");
+const AUDIBILITY_TEMPLATE_PREFIX = 'sound.heard';
+/**
+ * Handle a `sound.audibility.heard` event.
+ *
+ * Resolves `sound.heard.<kind>.<tier>` from the language provider,
+ * falling back to `sound.heard.default.<tier>` when the kind-specific
+ * template is not registered. Returns one `ITextBlock` per event, or
+ * `[]` when the event is malformed, the tier is `silent`, or no
+ * template resolves.
+ */
+function handleAudibilityHeard(event, context) {
+    const provider = context.languageProvider;
+    if (!provider)
+        return [];
+    const data = event.data;
+    if (!data || typeof data !== 'object')
+        return [];
+    if (!data.kind || !data.audibilityTier)
+        return [];
+    // Defense-in-depth: the dispatcher already filters `silent`, but
+    // never render it if one slips through.
+    if (data.audibilityTier === 'silent')
+        return [];
+    const params = {
+        kind: data.kind,
+    };
+    if (data.content?.messageId) {
+        const innerParams = data.content.params;
+        params.content = provider.getMessage(data.content.messageId, innerParams);
+    }
+    const kindId = `${AUDIBILITY_TEMPLATE_PREFIX}.${data.kind}.${data.audibilityTier}`;
+    let message = provider.getMessage(kindId, params);
+    if (!message || message === kindId) {
+        const fallbackId = `${AUDIBILITY_TEMPLATE_PREFIX}.default.${data.audibilityTier}`;
+        message = provider.getMessage(fallbackId, params);
+        if (!message || message === fallbackId) {
+            return [];
+        }
+    }
+    return (0, assemble_1.createBlocks)(text_blocks_1.BLOCK_KEYS.ACTION_RESULT, message);
+}
+//# sourceMappingURL=audibility.js.map

package/prose-pipeline/handlers/audibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audibility.js","sourceRoot":"","sources":["../../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/handlers/audibility.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;AAoBH,sDAoCC;AArDD,sDAAkD;AAIlD,0CAA2C;AAE3C,MAAM,0BAA0B,GAAG,aAAa,CAAC;AAEjD;;;;;;;;GAQG;AACH,SAAgB,qBAAqB,CACnC,KAAqB,EACrB,OAAuB;IAEvB,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAC1C,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IAEzB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAoC,CAAC;IACxD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACjD,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,cAAc;QAAE,OAAO,EAAE,CAAC;IAElD,iEAAiE;IACjE,wCAAwC;IACxC,IAAK,IAAI,CAAC,cAAyB,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAE5D,MAAM,MAAM,GAA4B;QACtC,IAAI,EAAE,IAAI,CAAC,IAAI;KAChB,CAAC;IACF,IAAI,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC;QAC5B,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,MAEpB,CAAC;QACd,MAAM,CAAC,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,0BAA0B,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;IACnF,IAAI,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACnC,MAAM,UAAU,GAAG,GAAG,0BAA0B,YAAY,IAAI,CAAC,cAAc,EAAE,CAAC;QAClF,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;YACvC,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED,OAAO,IAAA,uBAAY,EAAC,wBAAU,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;AACzD,CAAC"}

package/prose-pipeline/handlers/banner.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared banner-block builder.
+ *
+ * Emits the opening banner as a sequence of semantically-classed
+ * blocks. Used by both `handleGameStarted` and `handleAboutDisplayed`
+ * so the banner shown at game-start and via the ABOUT command are
+ * structurally identical.
+ *
+ * Pieces (in order):
+ *
+ *  1. `game-title`         — title
+ *  2. `story-version`      — `Story v{version}` + optional build date
+ *  3. `platform-version`   — `Sharpee v{engineVersion}` (if provided)
+ *  4. `sub-title`          — description (if provided)
+ *  5. `author-list[]`      — `credits` if provided, else single
+ *                            `By {author}` line if `author` is set
+ *  6. `banner-spacer`      — empty `<p>` for visual separation
+ *  7. story-tail           — appended via `createBlocks` from
+ *                            `game.banner.story-tail` if the language
+ *                            provider has that template
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ */
+import type { ITextBlock } from "../../../text-blocks/index";
+import type { HandlerContext } from './types';
+/**
+ * Subset of story metadata used by the banner builder.
+ * Both `handleGameStarted` (`event.data.story`) and
+ * `handleAboutDisplayed` (`event.data.params`) project into this shape.
+ */
+export interface BannerStoryInfo {
+    title?: string;
+    version?: string;
+    buildDate?: string;
+    description?: string;
+    author?: string;
+    credits?: string[];
+}
+/**
+ * Build the structured banner blocks for a `key` (typically
+ * `'game.banner'` from `game.started` or `'about.text'` from ABOUT).
+ */
+export declare function buildBannerBlocks(key: string, story: BannerStoryInfo | undefined, engineVersion: string | undefined, context: HandlerContext): ITextBlock[];
+//# sourceMappingURL=banner.d.ts.map

package/prose-pipeline/handlers/banner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"banner.d.ts","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/handlers/banner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAI9C;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,eAAe,GAAG,SAAS,EAClC,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,OAAO,EAAE,cAAc,GACtB,UAAU,EAAE,CAmDd"}

package/prose-pipeline/handlers/banner.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Shared banner-block builder.
+ *
+ * Emits the opening banner as a sequence of semantically-classed
+ * blocks. Used by both `handleGameStarted` and `handleAboutDisplayed`
+ * so the banner shown at game-start and via the ABOUT command are
+ * structurally identical.
+ *
+ * Pieces (in order):
+ *
+ *  1. `game-title`         — title
+ *  2. `story-version`      — `Story v{version}` + optional build date
+ *  3. `platform-version`   — `Sharpee v{engineVersion}` (if provided)
+ *  4. `sub-title`          — description (if provided)
+ *  5. `author-list[]`      — `credits` if provided, else single
+ *                            `By {author}` line if `author` is set
+ *  6. `banner-spacer`      — empty `<p>` for visual separation
+ *  7. story-tail           — appended via `createBlocks` from
+ *                            `game.banner.story-tail` if the language
+ *                            provider has that template
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBannerBlocks = buildBannerBlocks;
+const assemble_1 = require("../assemble");
+const STORY_TAIL_MESSAGE_ID = 'game.banner.story-tail';
+/**
+ * Build the structured banner blocks for a `key` (typically
+ * `'game.banner'` from `game.started` or `'about.text'` from ABOUT).
+ */
+function buildBannerBlocks(key, story, engineVersion, context) {
+    if (!story)
+        return [];
+    const blocks = [];
+    if (story.title) {
+        blocks.push((0, assemble_1.createBlock)(key, story.title, { className: 'game-title' }));
+    }
+    if (story.version) {
+        const buildDate = formatBuildDate(story.buildDate);
+        const versionText = buildDate
+            ? `Story v${story.version} (built ${buildDate})`
+            : `Story v${story.version}`;
+        blocks.push((0, assemble_1.createBlock)(key, versionText, { className: 'story-version' }));
+    }
+    if (engineVersion) {
+        blocks.push((0, assemble_1.createBlock)(key, `Sharpee v${engineVersion}`, {
+            className: 'platform-version',
+        }));
+    }
+    if (story.description) {
+        blocks.push((0, assemble_1.createBlock)(key, story.description, { className: 'sub-title' }));
+    }
+    const creditLines = story.credits && story.credits.length > 0
+        ? story.credits
+        : story.author
+            ? [`By ${story.author}`]
+            : [];
+    for (const line of creditLines) {
+        blocks.push((0, assemble_1.createBlock)(key, line, { className: 'author-list' }));
+    }
+    if (blocks.length > 0) {
+        blocks.push((0, assemble_1.createBlock)(key, '', { className: 'banner-spacer' }));
+    }
+    const tail = context.languageProvider?.getMessage(STORY_TAIL_MESSAGE_ID, {});
+    if (tail && tail !== STORY_TAIL_MESSAGE_ID) {
+        blocks.push(...(0, assemble_1.createBlocks)(key, tail));
+    }
+    return blocks;
+}
+/**
+ * Format an ISO build date as `YYYY-MM-DD` for the version line.
+ * Returns the original string if it doesn't parse cleanly, or empty
+ * when missing.
+ */
+function formatBuildDate(buildDate) {
+    if (!buildDate)
+        return '';
+    try {
+        const iso = new Date(buildDate).toISOString();
+        return iso.split('T')[0];
+    }
+    catch {
+        return buildDate;
+    }
+}
+//# sourceMappingURL=banner.js.map

package/prose-pipeline/handlers/banner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"banner.js","sourceRoot":"","sources":["../../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/handlers/banner.ts"],"names":[],"mappings":"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"}

package/prose-pipeline/handlers/client-query.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Client-query handler — `client.query`.
+ *
+ * Today only the `disambiguation` source is rendered. The handler
+ * formats a candidate list as natural English ("the X or the Y" /
+ * "the X, the Y, or the Z") and resolves the
+ * `core.disambiguation_prompt` template with the resulting `options`
+ * string.
+ *
+ * Public interface: `handleClientQuery`. Used by the pipeline's
+ * event-type dispatch.
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * @see ADR-174 §Engine-internal prose pipeline (extracted from
+ *   text-service.ts inline)
+ */
+import type { ITextBlock } from "../../../text-blocks/index";
+import type { ISemanticEvent } from "../../../core/index";
+import type { HandlerContext } from './types';
+export declare function handleClientQuery(event: ISemanticEvent, context: HandlerContext): ITextBlock[];
+//# sourceMappingURL=client-query.d.ts.map

package/prose-pipeline/handlers/client-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-query.d.ts","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/handlers/client-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAU9C,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,GACtB,UAAU,EAAE,CAgBd"}

package/prose-pipeline/handlers/client-query.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Client-query handler — `client.query`.
+ *
+ * Today only the `disambiguation` source is rendered. The handler
+ * formats a candidate list as natural English ("the X or the Y" /
+ * "the X, the Y, or the Z") and resolves the
+ * `core.disambiguation_prompt` template with the resulting `options`
+ * string.
+ *
+ * Public interface: `handleClientQuery`. Used by the pipeline's
+ * event-type dispatch.
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * @see ADR-174 §Engine-internal prose pipeline (extracted from
+ *   text-service.ts inline)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleClientQuery = handleClientQuery;
+const text_blocks_1 = require("../../../text-blocks/index.js");
+const assemble_1 = require("../assemble");
+function handleClientQuery(event, context) {
+    const data = event.data;
+    if (data?.source !== 'disambiguation') {
+        return [];
+    }
+    const candidateNames = (data.candidates || []).map((c) => c.name);
+    const options = formatCandidateList(candidateNames);
+    const message = context.languageProvider?.getMessage('core.disambiguation_prompt', {
+        options,
+    }) ?? `Which do you mean: ${options}?`;
+    return (0, assemble_1.createBlocks)(text_blocks_1.BLOCK_KEYS.ERROR, message);
+}
+/**
+ * Format a list of candidate names as natural English.
+ *
+ * Examples:
+ *   ["red ball", "blue ball"]            → "the red ball or the blue ball"
+ *   ["sword", "axe", "knife"]            → "the sword, the axe, or the knife"
+ */
+function formatCandidateList(names) {
+    if (names.length === 0)
+        return '';
+    if (names.length === 1)
+        return `the ${names[0]}`;
+    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}`;
+}
+//# sourceMappingURL=client-query.js.map

package/prose-pipeline/handlers/client-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-query.js","sourceRoot":"","sources":["../../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/handlers/client-query.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;AAeH,8CAmBC;AA/BD,sDAAkD;AAGlD,0CAA2C;AAS3C,SAAgB,iBAAiB,CAC/B,KAAqB,EACrB,OAAuB;IAEvB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAuB,CAAC;IAE3C,IAAI,IAAI,EAAE,MAAM,KAAK,gBAAgB,EAAE,CAAC;QACtC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,cAAc,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAClE,MAAM,OAAO,GAAG,mBAAmB,CAAC,cAAc,CAAC,CAAC;IAEpD,MAAM,OAAO,GACX,OAAO,CAAC,gBAAgB,EAAE,UAAU,CAAC,4BAA4B,EAAE;QACjE,OAAO;KACR,CAAC,IAAI,sBAAsB,OAAO,GAAG,CAAC;IAEzC,OAAO,IAAA,uBAAY,EAAC,wBAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,mBAAmB,CAAC,KAAe;IAC1C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAEjD,MAAM,YAAY,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAElD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,CAAC;IAED,+CAA+C;IAC/C,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,EAAE,CAAC;IAChC,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;AAClD,CAAC"}

package/prose-pipeline/handlers/command-failed.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Command-failed handler — `command.failed`.
+ *
+ * Maps parser / entity-resolution failure reasons to user-facing
+ * error prose. Recognized reason fragments:
+ *   - `ENTITY_NOT_FOUND` / `modifiers_not_matched` →
+ *     `core.entity_not_found` (default: "I don't see that here.")
+ *   - `NO_MATCH` / `parse` →
+ *     `core.command_not_understood` (default: "I don't understand that.")
+ * Anything else → `core.command_failed` (same default).
+ *
+ * Public interface: `handleCommandFailed`. Used by the pipeline's
+ * event-type dispatch.
+ *
+ * Owner context: `@sharpee/engine` — internal prose pipeline.
+ *
+ * @see ADR-174 §Engine-internal prose pipeline (extracted from
+ *   text-service.ts inline)
+ */
+import type { ITextBlock } from "../../../text-blocks/index";
+import type { ISemanticEvent } from "../../../core/index";
+import type { HandlerContext } from './types';
+export declare function handleCommandFailed(event: ISemanticEvent, context: HandlerContext): ITextBlock[];
+//# sourceMappingURL=command-failed.d.ts.map

package/prose-pipeline/handlers/command-failed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-failed.d.ts","sourceRoot":"","sources":["../../../../../../../repos/sharpee/packages/engine/src/prose-pipeline/handlers/command-failed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAQ9C,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,GACtB,UAAU,EAAE,CA6Bd"}