feat(engine): loader for narrator JSON

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

package-lock.json

@@ -770,6 +770,17 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/node": {
+      "version": "25.6.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.6.0.tgz",
+      "integrity": "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "undici-types": "~7.19.0"
+      }
+    },
     "node_modules/@vitest/expect": {
       "version": "2.1.9",
       "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-2.1.9.tgz",
@@ -1273,12 +1284,20 @@
         "node": ">=14.17"
       }
     },
+    "node_modules/undici-types": {
+      "version": "7.19.2",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.19.2.tgz",
+      "integrity": "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/vite": {
       "version": "5.4.21",
       "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
       "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",
@@ -1442,6 +1461,7 @@
     "packages/story-engine": {
       "version": "0.1.0",
       "devDependencies": {
+        "@types/node": "^25.6.0",
         "vitest": "^2.1.0"
       }
     }

packages/story-engine/package.json

@@ -12,6 +12,7 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
+    "@types/node": "^25.6.0",
     "vitest": "^2.1.0"
   }
 }

packages/story-engine/src/loader.ts

@@ -0,0 +1,34 @@
+import type { Narrator } from "./types.js";
+
+interface RawNarrator {
+  name: string;
+  description: string;
+  introduction: string;
+  background: string;
+  goal: string;
+  voice: string;
+  voice_tone: string;
+  // legacy fields ignored: picture, tools, etc.
+}
+
+export function loadNarrator(raw: unknown): Narrator {
+  const r = raw as RawNarrator;
+  if (!r || typeof r !== "object") {
+    throw new Error("Narrator JSON must be an object");
+  }
+  for (const field of ["name", "description", "introduction", "background", "goal", "voice", "voice_tone"] as const) {
+    if (typeof r[field] !== "string" || !r[field]) {
+      throw new Error(`Narrator missing required string field: ${field}`);
+    }
+  }
+  return {
+    id: "narrator",
+    name: r.name,
+    description: r.description,
+    introduction: r.introduction,
+    background: r.background,
+    goal: r.goal,
+    voice: r.voice,
+    voiceTone: r.voice_tone,
+  };
+}

packages/story-engine/tests/fixtures/narrator/narrator.json

@@ -0,0 +1,9 @@
+{
+  "name": "The Narrator",
+  "description": "A cheerful storyteller",
+  "introduction": "Welcome adventurer!",
+  "background": "An entity who guides players through stories.",
+  "goal": "Help the player pick a story.",
+  "voice": "cedar",
+  "voice_tone": "Warm, enthusiastic, brief."
+}

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

@@ -0,0 +1,18 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadNarrator } from "../src/loader.js";
+
+const narratorJson = JSON.parse(
+  readFileSync(resolve(__dirname, "fixtures/narrator/narrator.json"), "utf-8"),
+);
+
+describe("loadNarrator", () => {
+  it("normalizes a narrator JSON into the Narrator type", () => {
+    const narrator = loadNarrator(narratorJson);
+    expect(narrator.id).toBe("narrator");
+    expect(narrator.name).toBe("The Narrator");
+    expect(narrator.voice).toBe("cedar");
+    expect(narrator.voiceTone).toBe("Warm, enthusiastic, brief.");
+  });
+});

packages/story-engine/tsconfig.json

@@ -1,4 +1,7 @@
 {
   "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["node"]
+  },
   "include": ["src/**/*", "tests/**/*"]
 }