@ai-rpg-engine/presentation 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { NarrationPlan, NarrationTone, Urgency, Interruptibility, SpeakerCue, SfxCue, SfxTiming, AmbientCue, MusicCue, UiEffect, UiEffectType, VoiceProfile, VoicePreset, PresentationState, PresentationRenderer, } from './types.js';
+export { validateNarrationPlan, isValidNarrationPlan, type ValidationError, } from './validate.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,aAAa,EACb,aAAa,EACb,OAAO,EACP,gBAAgB,EAChB,UAAU,EACV,MAAM,EACN,SAAS,EACT,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { validateNarrationPlan, isValidNarrationPlan, } from './validate.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GAErB,MAAM,eAAe,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+/** Structured narration recipe for multi-modal presentation. */
+export type NarrationPlan = {
+    sceneText: string;
+    tone: NarrationTone;
+    urgency: Urgency;
+    speaker?: SpeakerCue;
+    musicCue?: MusicCue;
+    sfx: SfxCue[];
+    ambientLayers: AmbientCue[];
+    uiEffects: UiEffect[];
+    interruptibility: Interruptibility;
+    voiceProfile?: VoiceProfile;
+};
+export type NarrationTone = 'tense' | 'calm' | 'wonder' | 'dread' | 'combat' | 'triumph' | 'sorrow';
+export type Urgency = 'idle' | 'normal' | 'elevated' | 'critical';
+export type Interruptibility = 'free' | 'locked' | 'soft-lock';
+/** Voice synthesis cue for a speaker (narrator or NPC). */
+export type SpeakerCue = {
+    entityId: string;
+    voiceId: string;
+    emotion: string;
+    speed: number;
+    text: string;
+};
+/** Sound effect trigger. */
+export type SfxCue = {
+    effectId: string;
+    timing: SfxTiming;
+    intensity: number;
+};
+export type SfxTiming = 'immediate' | 'with-text' | 'after-text';
+/** Ambient audio layer control. */
+export type AmbientCue = {
+    layerId: string;
+    action: 'start' | 'stop' | 'crossfade';
+    volume: number;
+    fadeMs: number;
+};
+/** Background music control. */
+export type MusicCue = {
+    action: 'play' | 'stop' | 'crossfade' | 'intensify' | 'soften';
+    trackId?: string;
+    fadeMs: number;
+};
+/** Terminal/screen visual effect. */
+export type UiEffect = {
+    type: UiEffectType;
+    durationMs: number;
+    color?: string;
+};
+export type UiEffectType = 'flash' | 'shake' | 'fade-in' | 'fade-out' | 'border-pulse';
+/** Voice configuration for speech synthesis. */
+export type VoiceProfile = {
+    voiceId: string;
+    preset: VoicePreset;
+    emotion: string;
+    speed: number;
+};
+export type VoicePreset = 'narrator' | 'storyteller' | 'announcer' | 'whisper' | 'assistant';
+/** Presentation state for the game session. */
+export type PresentationState = 'exploration' | 'dialogue' | 'tension' | 'combat' | 'aftermath' | 'menu' | 'dream' | 'director';
+/** Render contract — any frontend implements this to receive presentation commands. */
+export interface PresentationRenderer {
+    renderText(text: string): Promise<void>;
+    playVoice(cue: SpeakerCue): Promise<void>;
+    playSfx(cue: SfxCue): Promise<void>;
+    setAmbient(cue: AmbientCue): Promise<void>;
+    setMusic(cue: MusicCue): Promise<void>;
+    applyUiEffect(effect: UiEffect): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,3 @@
+// Narration plan schema and presentation types
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,+CAA+C"}

package/dist/validate.d.ts

@@ -0,0 +1,10 @@
+import type { NarrationPlan } from './types.js';
+export type ValidationError = {
+    field: string;
+    message: string;
+};
+/** Validate a NarrationPlan, returning errors if any. */
+export declare function validateNarrationPlan(plan: unknown): ValidationError[];
+/** Returns true if the plan is valid. */
+export declare function isValidNarrationPlan(plan: unknown): plan is NarrationPlan;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAA4C,MAAM,YAAY,CAAC;AAQ1F,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,yDAAyD;AACzD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,EAAE,CAsDtE;AAED,yCAAyC;AACzC,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,aAAa,CAEzE"}

package/dist/validate.js

@@ -0,0 +1,58 @@
+// Validate a NarrationPlan against expected shape
+const VALID_TONES = [
+    'tense', 'calm', 'wonder', 'dread', 'combat', 'triumph', 'sorrow',
+];
+const VALID_URGENCIES = ['idle', 'normal', 'elevated', 'critical'];
+const VALID_INTERRUPTIBILITIES = ['free', 'locked', 'soft-lock'];
+/** Validate a NarrationPlan, returning errors if any. */
+export function validateNarrationPlan(plan) {
+    const errors = [];
+    if (!plan || typeof plan !== 'object') {
+        return [{ field: 'root', message: 'NarrationPlan must be an object' }];
+    }
+    const p = plan;
+    if (typeof p.sceneText !== 'string' || p.sceneText.length === 0) {
+        errors.push({ field: 'sceneText', message: 'sceneText must be a non-empty string' });
+    }
+    if (!VALID_TONES.includes(p.tone)) {
+        errors.push({ field: 'tone', message: `tone must be one of: ${VALID_TONES.join(', ')}` });
+    }
+    if (!VALID_URGENCIES.includes(p.urgency)) {
+        errors.push({ field: 'urgency', message: `urgency must be one of: ${VALID_URGENCIES.join(', ')}` });
+    }
+    if (!VALID_INTERRUPTIBILITIES.includes(p.interruptibility)) {
+        errors.push({
+            field: 'interruptibility',
+            message: `interruptibility must be one of: ${VALID_INTERRUPTIBILITIES.join(', ')}`,
+        });
+    }
+    if (!Array.isArray(p.sfx)) {
+        errors.push({ field: 'sfx', message: 'sfx must be an array' });
+    }
+    else {
+        for (let i = 0; i < p.sfx.length; i++) {
+            const sfx = p.sfx[i];
+            if (typeof sfx.effectId !== 'string') {
+                errors.push({ field: `sfx[${i}].effectId`, message: 'effectId must be a string' });
+            }
+            if (!['immediate', 'with-text', 'after-text'].includes(sfx.timing)) {
+                errors.push({ field: `sfx[${i}].timing`, message: 'timing must be immediate, with-text, or after-text' });
+            }
+            if (typeof sfx.intensity !== 'number' || sfx.intensity < 0 || sfx.intensity > 1) {
+                errors.push({ field: `sfx[${i}].intensity`, message: 'intensity must be a number between 0 and 1' });
+            }
+        }
+    }
+    if (!Array.isArray(p.ambientLayers)) {
+        errors.push({ field: 'ambientLayers', message: 'ambientLayers must be an array' });
+    }
+    if (!Array.isArray(p.uiEffects)) {
+        errors.push({ field: 'uiEffects', message: 'uiEffects must be an array' });
+    }
+    return errors;
+}
+/** Returns true if the plan is valid. */
+export function isValidNarrationPlan(plan) {
+    return validateNarrationPlan(plan).length === 0;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

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

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@ai-rpg-engine/presentation",
+  "version": "2.0.0",
+  "description": "Narration plan schema, render contracts, and presentation state types for AI RPG Engine",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "license": "MIT",
+  "author": "mcp-tool-shop",
+  "homepage": "https://mcp-tool-shop-org.github.io/ai-rpg-engine/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mcp-tool-shop-org/ai-rpg-engine.git",
+    "directory": "packages/presentation"
+  },
+  "keywords": ["rpg", "narration", "presentation", "audio", "immersion", "game-engine"],
+  "bugs": {
+    "url": "https://github.com/mcp-tool-shop-org/ai-rpg-engine/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}