feat(engine): define core types for story data and game state

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

packages/story-engine/src/types.ts

@@ -0,0 +1,135 @@
+// ─── Loaded data (immutable after load) ──────────────────────────────────
+
+export interface Narrator {
+  id: "narrator";              // sentinel id for the global narrator
+  name: string;
+  description: string;
+  introduction: string;
+  background: string;
+  goal: string;
+  voice: string;               // OpenAI Realtime voice preset name
+  voiceTone: string;
+}
+
+export interface Character {
+  id: string;                  // derived from filename stem (e.g. "sparrow")
+  name: string;
+  description: string;
+  introduction: string;
+  background: string;
+  goal: string;
+  voice: string;               // OpenAI Realtime voice preset name
+  voiceTone: string;
+}
+
+export interface SceneAction {
+  id: string;
+  description: string;
+  effects: string;             // narrative description, no flag effects
+}
+
+export interface Scene {
+  id: string;                  // derived from filename stem
+  name: string;
+  description: string;
+  actions: SceneAction[];      // atmospheric actions
+  charactersPresent: string[]; // character ids
+}
+
+export interface StorylineActionEffects {
+  setFlags?: Record<string, boolean>;
+}
+
+export interface StorylineAction {
+  id: string;
+  description: string;
+  next?: string;               // next storyline node id
+  effects?: StorylineActionEffects;
+}
+
+export type StorylineType = "dialogue" | "narration" | "character_interaction";
+
+export interface StorylineNode {
+  id: string;
+  scene: string;               // scene id
+  type: StorylineType;
+  speaker: string;             // character id, "narrator", or empty string
+  text: string;
+  actions: StorylineAction[];
+}
+
+export interface FlagCondition {
+  type: "requires_flag";
+  flag: string;
+  conditionFailed: string;     // explanation if blocked
+}
+
+export interface MapEdge {
+  from: string;                // scene id
+  to: string;                  // scene id
+  description: string;
+  conditions?: FlagCondition[];
+}
+
+export interface Story {
+  id: string;
+  title: string;
+  description: string;
+  languages: string[];
+  entryPoint: string;          // path relative to story root, e.g. "storylines/chapter1/meet_sparrow.json"
+  narrator: Character | Narrator;  // story-specific or global
+  characters: Record<string, Character>;
+  scenes: Record<string, Scene>;
+  storylines: Record<string, StorylineNode>;
+  map: MapEdge[];
+  flags: string[];             // declared flag names (flat array)
+}
+
+export interface LoadedContent {
+  narrator: Narrator;          // global menu narrator
+  stories: Record<string, Story>;
+}
+
+// ─── Mutable state ────────────────────────────────────────────────────────
+
+export type AppMode = "menu" | "story";
+
+export interface GameState {
+  mode: AppMode;
+  storyId?: string;
+  currentSceneId?: string;
+  currentNodeId?: string;
+  currentSpeaker?: string;     // character id, or "narrator"
+  flags: Record<string, boolean>;
+  discoveredScenes: string[];
+  metCharacters: string[];
+  recentTransitions: TransitionEvent[];  // bounded log for summary builder
+}
+
+// ─── Transition events ────────────────────────────────────────────────────
+
+export type TransitionEvent =
+  | { type: "speakerChanged"; from?: string; to: string;
+      newCharacter: Character | Narrator }
+  | { type: "sceneChanged"; from?: string; to: string }
+  | { type: "storyEntered"; storyId: string }
+  | { type: "storyExited" }
+  | { type: "flagSet"; name: string; value: boolean }
+  | { type: "blocked"; reason: string };
+
+export interface TransitionResult {
+  state: Readonly<GameState>;
+  events: TransitionEvent[];
+}
+
+// ─── Tool definitions for OpenAI Realtime ─────────────────────────────────
+
+export interface ToolDef {
+  name: string;
+  description: string;
+  parameters: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required: string[];
+  };
+}