docs(content): authoritative SCHEMA + playthrough integration test

content/SCHEMA.md

@@ -0,0 +1,105 @@
+# Story Content Schema (Reachy Tales)
+
+This file documents the **actual** schema the `story-engine` reads.
+It supersedes the legacy `STORIES_DOCUMENTATION.md` from the original AI_game project.
+
+## Layout
+
+```
+content/
+├── narrator/
+│   └── narrator.json
+└── <story_id>/
+    ├── manifest.json
+    ├── map.json
+    ├── flags.json
+    ├── story_state_template.json
+    ├── characters/<id>.json
+    ├── scenes/<id>.json
+    └── storylines/chapter<n>/<node_id>.json
+```
+
+## File formats
+
+(Brief schema description — kept minimal to avoid drift; engine code is the source of truth.)
+
+### narrator.json / characters/<id>.json
+```json
+{
+  "name": "string",
+  "description": "string",
+  "introduction": "string",
+  "background": "string",
+  "goal": "string",
+  "voice": "string (OpenAI Realtime voice preset name, e.g. \"cedar\", \"ash\")",
+  "voice_tone": "string"
+}
+```
+
+### manifest.json
+```json
+{
+  "id": "string (matches folder name)",
+  "title": "string",
+  "description": "string",
+  "languages": ["en"],
+  "entry_point": "storylines/chapter1/<node_id>.json",
+  "narrator": { /* same shape as a character */ }
+}
+```
+
+### scenes/<id>.json
+```json
+{
+  "name": "string",
+  "description": "string",
+  "actions": [ { "id": "string", "description": "string", "effects": "string" } ],
+  "characters_present": ["character_id_or_name"]
+}
+```
+
+### storylines/chapter<n>/<node_id>.json
+```json
+{
+  "id": "string",
+  "scene": "scene_id",
+  "type": "dialogue | narration | character_interaction",
+  "speaker": "character_id_or_name | narrator | \"\"",
+  "text": "string",
+  "actions": [
+    {
+      "id": "string",
+      "description": "string",
+      "next": "node_id (optional, end-node if omitted)",
+      "effects": { "set_flags": { "flag_name": true } }
+    }
+  ]
+}
+```
+
+### map.json
+```json
+[
+  {
+    "from": "scene_id",
+    "to": "scene_id",
+    "description": "string",
+    "conditions": [
+      {
+        "type": "requires_flag",
+        "flag": "flag_name",
+        "condition_failed": "string (player-facing explanation)"
+      }
+    ]
+  }
+]
+```
+
+### flags.json
+```json
+["flag_name_1", "flag_name_2"]
+```
+
+## Notes
+- All strings are English. Bilingual `{ "en": "...", "fr": "..." }` envelopes from the legacy schema are NOT supported.
+- Image fields (`picture`, `cover_image`) are ignored by the engine.

packages/story-engine/tests/playthrough.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import { StoryEngine } from "../src/engine.js";
+import { loadNarrator, loadStory } from "../src/loader.js";
+import { readFileSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import type { LoadedContent } from "../src/types.js";
+
+const CONTENT = resolve(__dirname, "../../../content");
+function readJsonFile(p: string): unknown { return JSON.parse(readFileSync(p, "utf-8")); }
+function readJsonDir(dir: string): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const f of readdirSync(dir)) if (f.endsWith(".json")) out[f.replace(/\.json$/, "")] = readJsonFile(resolve(dir, f));
+  return out;
+}
+
+function loadRealContent(): LoadedContent {
+  const narrator = loadNarrator(readJsonFile(resolve(CONTENT, "narrator/narrator.json")));
+  const pirates = loadStory({
+    manifest: readJsonFile(resolve(CONTENT, "story_pirates/manifest.json")),
+    map: readJsonFile(resolve(CONTENT, "story_pirates/map.json")),
+    flags: readJsonFile(resolve(CONTENT, "story_pirates/flags.json")),
+    characters: readJsonDir(resolve(CONTENT, "story_pirates/characters")),
+    scenes: readJsonDir(resolve(CONTENT, "story_pirates/scenes")),
+    storylines: readJsonDir(resolve(CONTENT, "story_pirates/storylines/chapter1")),
+  });
+  return { narrator, stories: { story_pirates: pirates } };
+}
+
+describe("story_pirates playthrough", () => {
+  it("loads cleanly and reports the expected starting state", () => {
+    const engine = new StoryEngine(loadRealContent());
+    const r = engine.enterStoryMode("story_pirates");
+    expect(r.events.find((e) => e.type === "blocked")).toBeUndefined();
+    expect(r.state.currentNodeId).toBe("meet_sparrow");
+    expect(r.state.currentSceneId).toBe("tavern");
+  });
+
+  it("happy-path traversal: respect Sparrow → ask treasure → ... reaches an end", () => {
+    const engine = new StoryEngine(loadRealContent());
+    engine.enterStoryMode("story_pirates");
+    // Walk the friendly branch as far as the data allows
+    const visited: string[] = [];
+    const walk = (actionId: string, maxSteps = 20): void => {
+      for (let step = 0; step < maxSteps; step++) {
+        const r = engine.advanceStoryline(actionId);
+        if (r.events.some((e) => e.type === "blocked")) break;
+        const node = engine.getCurrentNode();
+        if (!node || node.actions.length === 0) break;
+        visited.push(node.id);
+        actionId = node.actions[0]!.id;
+      }
+    };
+    walk("greet_respectfully");
+    expect(visited.length).toBeGreaterThan(0);
+  });
+});