@ai-rpg-engine/presentation 2.0.0 → 2.0.1

package/README.md

@@ -0,0 +1,66 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/ai-rpg-engine/readme.png" width="300" alt="AI RPG Engine">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@ai-rpg-engine/presentation"><img src="https://img.shields.io/npm/v/@ai-rpg-engine/presentation.svg" alt="npm"></a>
+  <a href="https://github.com/mcp-tool-shop-org/ai-rpg-engine/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/ai-rpg-engine/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/mcp-tool-shop-org/ai-rpg-engine/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+# @ai-rpg-engine/presentation
+
+Narration plan schema, render contracts, and presentation state types for the [AI RPG Engine](https://github.com/mcp-tool-shop-org/ai-rpg-engine).
+
+Part of the **Immersion Runtime** — the multi-modal presentation pipeline that transforms game state into structured audio-visual experiences.
+
+## Install
+
+```bash
+npm install @ai-rpg-engine/presentation
+```
+
+## What It Does
+
+Instead of outputting raw prose, the narrator produces a **NarrationPlan** — a structured recipe describing text, sound effects, ambient layers, music cues, UI effects, and voice synthesis parameters.
+
+Any frontend (terminal, web, Electron) implements the `PresentationRenderer` interface to receive and execute these plans.
+
+## Key Types
+
+| Type | Purpose |
+|------|---------|
+| `NarrationPlan` | Structured narration recipe (text + SFX + ambient + music + UI) |
+| `SpeakerCue` | Voice synthesis parameters (voice ID, emotion, speed) |
+| `SfxCue` | Sound effect trigger (effect ID, timing, intensity) |
+| `AmbientCue` | Ambient layer control (start, stop, crossfade) |
+| `MusicCue` | Background music control (play, stop, intensify, soften) |
+| `UiEffect` | Terminal/screen visual effects (flash, shake, fade) |
+| `VoiceProfile` | Voice configuration for speech synthesis |
+| `PresentationRenderer` | Render contract — any frontend implements this |
+
+## Usage
+
+```typescript
+import type { NarrationPlan, PresentationRenderer } from '@ai-rpg-engine/presentation';
+import { validateNarrationPlan, isValidNarrationPlan } from '@ai-rpg-engine/presentation';
+
+// Validate a plan from Claude's output
+const errors = validateNarrationPlan(planFromClaude);
+if (errors.length === 0) {
+  // Plan is valid, execute it
+}
+
+// Type guard
+if (isValidNarrationPlan(data)) {
+  console.log(data.sceneText);
+}
+```
+
+## Part of AI RPG Engine
+
+This package is part of the [AI RPG Engine](https://github.com/mcp-tool-shop-org/ai-rpg-engine) monorepo. See the root README for the full architecture.
+
+## License
+
+MIT

package/dist/validate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validate.test.d.ts.map

package/dist/validate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.test.d.ts","sourceRoot":"","sources":["../src/validate.test.ts"],"names":[],"mappings":""}

package/dist/validate.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { validateNarrationPlan, isValidNarrationPlan } from './validate.js';
+describe('validateNarrationPlan', () => {
+    const validPlan = {
+        sceneText: 'You step into a dimly lit chapel.',
+        tone: 'dread',
+        urgency: 'normal',
+        sfx: [{ effectId: 'ui_whoosh', timing: 'immediate', intensity: 0.5 }],
+        ambientLayers: [{ layerId: 'ambient_drone', action: 'start', volume: 0.3, fadeMs: 1000 }],
+        uiEffects: [],
+        interruptibility: 'free',
+    };
+    it('should accept a valid plan', () => {
+        const errors = validateNarrationPlan(validPlan);
+        expect(errors).toHaveLength(0);
+        expect(isValidNarrationPlan(validPlan)).toBe(true);
+    });
+    it('should reject non-object', () => {
+        expect(validateNarrationPlan(null)).toHaveLength(1);
+        expect(validateNarrationPlan('string')).toHaveLength(1);
+    });
+    it('should reject empty sceneText', () => {
+        const errors = validateNarrationPlan({ ...validPlan, sceneText: '' });
+        expect(errors.some((e) => e.field === 'sceneText')).toBe(true);
+    });
+    it('should reject invalid tone', () => {
+        const errors = validateNarrationPlan({ ...validPlan, tone: 'invalid' });
+        expect(errors.some((e) => e.field === 'tone')).toBe(true);
+    });
+    it('should reject invalid sfx timing', () => {
+        const errors = validateNarrationPlan({
+            ...validPlan,
+            sfx: [{ effectId: 'x', timing: 'invalid', intensity: 0.5 }],
+        });
+        expect(errors.some((e) => e.field.includes('timing'))).toBe(true);
+    });
+    it('should reject sfx intensity out of range', () => {
+        const errors = validateNarrationPlan({
+            ...validPlan,
+            sfx: [{ effectId: 'x', timing: 'immediate', intensity: 1.5 }],
+        });
+        expect(errors.some((e) => e.field.includes('intensity'))).toBe(true);
+    });
+});
+//# sourceMappingURL=validate.test.js.map

package/dist/validate.test.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-rpg-engine/presentation",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Narration plan schema, render contracts, and presentation state types for AI RPG Engine",
   "type": "module",
   "main": "./dist/index.js",