zeus-api-types 1.0.48 → 1.0.51

package/dist/ai.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Operation types for AI metadata tracking
+ */
+export type AIOperationType = 'narrative' | 'dialog' | 'updateScript' | 'choiceMetadata' | 'gameInit' | 'genreInit';
+export interface AIOperationTokens {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    count: number;
+}
+export interface AIMetadata {
+    tokensUsed: {
+        total: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+        };
+        byOperation: {
+            narrative?: AIOperationTokens;
+            dialog?: AIOperationTokens;
+            updateScript?: AIOperationTokens;
+            choiceMetadata?: AIOperationTokens;
+            gameInit?: AIOperationTokens;
+            genreInit?: AIOperationTokens;
+        };
+    };
+    modelsUsed: string[];
+    operationCount: number;
+    operationsByType: Record<string, number>;
+    firstOperationAt?: string;
+    lastOperationAt?: string;
+}

package/dist/ai.js

@@ -0,0 +1,5 @@
+"use strict";
+// ============================================================================
+// AI METADATA TRACKING
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/deck.d.ts

@@ -0,0 +1,81 @@
+import type { GameState } from "./game-state";
+export interface StoryArc {
+    id?: string;
+    theme?: string;
+    title?: string;
+    description?: string;
+    narrative_hooks?: string[];
+    atmosphere_modifiers?: Record<string, number>;
+    /**
+     * Arc pattern representing emotional trajectory
+     * 11 values (0-100) at 0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100% progress
+     */
+    arc_pattern?: number[];
+    /**
+     * Tone pattern representing emotional tone trajectory throughout the story
+     * 11 tone values in compact notation at progress intervals
+     */
+    tone_pattern?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Base card interface - shared properties across all card types
+ */
+export interface BaseDeckCard {
+    id: string;
+    theme?: string;
+    title?: string;
+    description?: string;
+    emoji?: string;
+    [key: string]: unknown;
+}
+/**
+ * Story Arc card - used for narrative trajectory
+ */
+export interface StoryArcCard extends BaseDeckCard {
+    narrative_hooks?: string[];
+    /**
+     * Arc pattern representing emotional trajectory
+     * 11 values (0-100) at 0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100% progress
+     * 0 = darkest/worst, 100 = brightest/best
+     * Based on Kurt Vonnegut's story shapes
+     */
+    arc_pattern?: number[];
+    /**
+     * Tone pattern representing emotional tone trajectory throughout the story
+     * 11 tone values in compact notation at 0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100% progress
+     * Each tone is in format "HHH:SSS:LLL" (hue:saturation:lightness)
+     * Interpolated between values to get tone at any progression point
+     */
+    tone_pattern?: string[];
+}
+/**
+ * Narrative Style card - used for writing style and voice
+ */
+export interface NarrativeStyleCard extends BaseDeckCard {
+    representative_authors?: string[];
+    technical_guide?: string;
+    example?: string;
+}
+export interface DeckDefinition {
+    deckId: string;
+    name?: string;
+    description?: string;
+    version?: string;
+    genre?: string;
+    cards: BaseDeckCard[];
+    draw_rules?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Multi-deck format - contains multiple named decks
+ * Example: { story_arc: {...}, mood: {...}, etc. }
+ */
+export interface MultiDeckDefinition {
+    story_arc: DeckDefinition;
+    [deckName: string]: DeckDefinition;
+}
+export interface FixtureSet {
+    state: GameState;
+    deck: DeckDefinition;
+}

package/dist/deck.js

@@ -0,0 +1,5 @@
+"use strict";
+// ============================================================================
+// STORY ARC & CARD SYSTEM
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/events.d.ts

@@ -0,0 +1,43 @@
+import type { WorldEntity } from "./game-state";
+export interface EventPropagation {
+    to: string;
+    effect: Record<string, unknown>;
+    decay?: number;
+}
+export interface BaseEvent extends WorldEntity {
+    id: string;
+    name?: string;
+    description?: string;
+    location?: string;
+    conditions?: Record<string, unknown>;
+    effects?: Record<string, unknown>;
+    propagation?: EventPropagation[];
+    cooldown?: number;
+    cooldown_remaining?: number;
+}
+export interface DeterministicEvent extends BaseEvent {
+}
+export interface ScheduledEvent extends BaseEvent {
+    timestamp: string;
+    interrupts?: boolean;
+    severity?: string;
+}
+export interface ProbabilisticEvent extends BaseEvent {
+    base_probability: number;
+    current_probability: number;
+    modifiers?: Record<string, unknown>;
+    last_triggered_turn?: number;
+}
+export interface EventHistoryEntry {
+    event_id: string;
+    type: 'deterministic' | 'scheduled' | 'probabilistic';
+    turn: number;
+    timestamp?: string;
+    outcome?: string;
+}
+export interface WorldEvents {
+    deterministic: DeterministicEvent[];
+    scheduled: ScheduledEvent[];
+    probabilistic: ProbabilisticEvent[];
+    history: EventHistoryEntry[];
+}

package/dist/events.js

@@ -0,0 +1,5 @@
+"use strict";
+// ============================================================================
+// WORLD EVENT SYSTEM
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/game-state.d.ts

@@ -1,31 +1,8 @@
-export interface AIOperationTokens {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-    count: number;
-}
-export interface AIMetadata {
-    tokensUsed: {
-        total: {
-            prompt_tokens: number;
-            completion_tokens: number;
-            total_tokens: number;
-        };
-        byOperation: {
-            narrative?: AIOperationTokens;
-            dialog?: AIOperationTokens;
-            updateScript?: AIOperationTokens;
-            choiceMetadata?: AIOperationTokens;
-            gameInit?: AIOperationTokens;
-            genreInit?: AIOperationTokens;
-        };
-    };
-    modelsUsed: string[];
-    operationCount: number;
-    operationsByType: Record<string, number>;
-    firstOperationAt?: string;
-    lastOperationAt?: string;
-}
+import { ToneCompact } from "tonelib";
+import type { AIMetadata } from "./ai";
+import type { NarrativeStyleCard, StoryArc } from "./deck";
+import type { WorldEvents } from "./events";
+import { UserMetadata } from "./user-preferences";
 /**
  * Tag structure for both system-level and author-defined metadata
  * - System tags (in immutable): managed by backend, hidden from UI
@@ -81,7 +58,6 @@ export interface WorldReduced {
  * Game State Types
  *
  * Core game state interfaces shared between middle-layer and frontend.
- * Extracted from middle-layer/src/core/GameState.ts
  */
 export interface TimeState {
     current: string;
@@ -142,6 +118,13 @@ export interface Location extends WorldEntity {
     name: string;
     description: string;
 }
+export interface PresentationChoiceMeta {
+    timeCost?: string;
+    vectors?: Record<string, string>;
+    expectedNPCs?: string[];
+    tone?: ToneCompact;
+    [key: string]: unknown;
+}
 export interface DialogMessage {
     speaker: string;
     message: string;
@@ -171,6 +154,8 @@ export interface PresentationCache {
     dialogHistory?: DialogMessage[];
     generatedAt?: string;
     source?: string;
+    choiceMetadata?: PresentationChoiceMeta[];
+    presentationCache?: PresentationCache;
 }
 export interface Session {
     history: HistoryEntry[];
@@ -180,22 +165,110 @@ export interface Session {
     presentationCache?: PresentationCache;
     prologue?: string;
 }
-export interface StoryArc {
-    id?: string;
-    theme?: string;
+export interface World extends WorldReduced {
+    events: WorldEvents;
+}
+export interface DialogContext {
+    context: Record<string, unknown>;
+    last_updated_turn?: number;
+    history: DialogMessage[];
+}
+/**
+ * Metadata for game state
+ * NOTE: genre moved to immutable block (pre-MVP, no backward compatibility)
+ */
+export interface Metadata {
+    genreTitle?: string;
+    expectedTurns: number;
+    storyArcCutoff: number;
+    storyArcProgression?: number;
+    version?: string;
+    tags?: Tag[];
     title?: string;
     description?: string;
-    narrative_hooks?: string[];
-    atmosphere_modifiers?: Record<string, number>;
-    /**
-     * Arc pattern representing emotional trajectory
-     * 11 values (0-100) at 0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100% progress
-     */
-    arc_pattern?: number[];
-    /**
-     * Tone pattern representing emotional tone trajectory throughout the story
-     * 11 tone values in compact notation at progress intervals
-     */
-    tone_pattern?: string[];
+    image?: string;
+    blacklist?: string[];
+    dialog?: DialogContext;
+    totalActs?: number;
+    nextActPrologue?: string;
+    nextActTime?: string;
+    nextActLocation?: string;
+    user?: UserMetadata;
     [key: string]: unknown;
 }
+export interface GameState {
+    immutable: ImmutableState;
+    currentTurn: number;
+    time: TimeState;
+    location: string;
+    player: Player;
+    world: World;
+    session: Session;
+    metadata: Metadata;
+    storyArc?: StoryArc;
+    narrativeStyle?: NarrativeStyleCard;
+}
+export interface GameStateReduced {
+    immutable: ImmutableState;
+    currentTurn: number;
+    time: TimeState;
+    location: string;
+    player: Player;
+    world: WorldReduced;
+    metadata: Metadata;
+    storyArc?: StoryArc;
+    narrativeStyle?: NarrativeStyleCard;
+}
+export interface StateSnapshot {
+    state: GameState;
+    timestamp: string;
+    turn: number;
+}
+export interface PromptVariables {
+    [key: string]: string | number | boolean | object | undefined;
+}
+/**
+ * Lightweight game metadata for efficient game listing
+ * Stored separately from full game state in metadata.json
+ * Updated on every save, read by listGamesWithMetadata()
+ */
+export interface GameMetadata {
+    /** Schema version for future evolution */
+    version: 1;
+    /** Unique game identifier */
+    gameId: string;
+    /** User who owns this game */
+    userId: string;
+    /** Genre this game is based on */
+    genreId: string;
+    /** Current turn number */
+    turn: number;
+    /** Current location ID */
+    location: string;
+    /** Human-readable location name */
+    locationName?: string;
+    /** Location image filename (not full URL) */
+    locationImage?: string;
+    /** Genre ID (duplicate for convenience) */
+    genre: string;
+    /** Game/Genre title */
+    title?: string;
+    /** Player character name */
+    playerName?: string;
+    /** Player image filename (not full URL) */
+    playerImage?: string;
+    /** Current act number (for multi-act games) */
+    act?: number;
+    /** Total number of acts planned */
+    totalActs?: number;
+    /** Saga ID (links acts together) */
+    sagaId?: string;
+    /** Previous act's game ID */
+    previousActId?: string;
+    /** Next act's game ID (if created) */
+    nextActId?: string;
+    /** ISO 8601 timestamp of last modification */
+    lastModified: string;
+    /** File size in bytes (of game.json) */
+    sizeBytes: number;
+}

package/dist/game-state.js

@@ -1,5 +1,2 @@
 "use strict";
-// ============================================================================
-// AI METADATA TRACKING
-// ============================================================================
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export type { ApiError, ApiErrorResponse } from './errors';
-export type { NarrativeStartEventPayload, NarrativeChunkEventPayload, NarrativeCompleteEventPayload, NarrativeMetadataEventPayload, MetadataEventPayload, DoneEventPayload, ErrorEventPayload, NarrativeSSEEventPayload, } from './sse/narrative';
-export type { TimeState, WorldEntity, Player, NPC, Location, WorldReduced, DialogMessage, HistoryEntry, PresentationCache, Session, StoryArc, AIOperationTokens, AIMetadata, Tag, BaseImmutableState, ImmutableState, GenreImmutableState, } from './game-state';
-export type { NarrativeFontPreferences, SoundPreferences, ModelStackPreset, ModelEntry, ModelStack, ModelStackPreferences, SystemModelPresets, AIPreferences, UserPreferences, UserMetadata, } from './user-preferences';
+export type { DoneEventPayload, ErrorEventPayload, MetadataEventPayload, NarrativeChunkEventPayload, NarrativeCompleteEventPayload, NarrativeMetadataEventPayload, NarrativeSSEEventPayload, NarrativeStartEventPayload } from './sse/narrative';
+export type { AIMetadata, AIOperationTokens, AIOperationType } from './ai';
+export type { BaseDeckCard, DeckDefinition, FixtureSet, MultiDeckDefinition, NarrativeStyleCard, StoryArc, StoryArcCard } from './deck';
+export type { BaseEvent, DeterministicEvent, EventHistoryEntry, EventPropagation, ProbabilisticEvent, ScheduledEvent, WorldEvents } from './events';
+export type { BaseImmutableState, DialogContext, DialogMessage, GameMetadata, GameState, GameStateReduced, GenreImmutableState, HistoryEntry, ImmutableState, Location, Metadata, NPC, NpcExistingOrNewOp, Player, PresentationCache, PresentationChoiceMeta, PromptVariables, Session, StateSnapshot, Tag, TimeState, World, WorldEntity, WorldReduced } from './game-state';
+export type { AIPreferences, ModelEntry, ModelStack, ModelStackPreferences, ModelStackPreset, NarrativeFontPreferences, SoundPreferences, SystemModelPresets, UserMetadata, UserPreferences } from './user-preferences';
+export type { CreatePresetRequest, CreatePresetResponse, DeletePresetResponse, ListPresetsResponse, PaginatedPresetsResponse, PaginationMetadata, PresetIndex, PresetMetadata, UpdatePresetRequest, UpdatePresetResponse } from './preset';

package/dist/preset.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Preset Types
+ *
+ * Presets are portable game state snapshots that can be cloned
+ * to create new games with identical initial conditions.
+ */
+/**
+ * Lightweight metadata for a single preset (stored in index.json)
+ */
+export interface PresetMetadata {
+    /** Unique identifier for this preset */
+    presetId: string;
+    /** Display name for the preset */
+    name: string;
+    /** Brief description of the opening scene */
+    description: string;
+    /** Original Act 1 gameId this preset was created from (for reference/debugging) */
+    sourceGameId: string;
+    /** ISO 8601 timestamp when preset was created */
+    createdAt: string;
+}
+/**
+ * Index file structure for genre presets
+ * Stored at: fixtures/genres/{genreId}/presets/index.json
+ */
+export interface PresetIndex {
+    /** Schema version for future evolution */
+    version: number;
+    /** Array of preset metadata entries */
+    presets: PresetMetadata[];
+}
+/**
+ * Response from GET /genres/{genreId}/presets (non-paginated, deprecated)
+ */
+export interface ListPresetsResponse {
+    /** Genre identifier */
+    genreId: string;
+    /** Array of available presets */
+    presets: PresetMetadata[];
+}
+/**
+ * Pagination metadata for list responses
+ */
+export interface PaginationMetadata {
+    /** Total number of items across all pages */
+    total: number;
+    /** Number of items per page */
+    limit: number;
+    /** Current offset (number of items skipped) */
+    offset: number;
+    /** Whether there are more items after this page */
+    hasMore: boolean;
+}
+/**
+ * Paginated response from GET /genres/{genreId}/presets
+ */
+export interface PaginatedPresetsResponse {
+    /** Genre identifier */
+    genreId: string;
+    /** Array of presets for this page */
+    presets: PresetMetadata[];
+    /** Pagination metadata */
+    pagination: PaginationMetadata;
+}
+/**
+ * Request body for POST /genres/{genreId}/presets
+ */
+export interface CreatePresetRequest {
+    /** Game ID to create preset from (can be any act - will resolve to Act 1 Turn 0) */
+    sourceGameId: string;
+    /** Display name for the new preset */
+    name: string;
+    /** Brief description of the opening scene */
+    description: string;
+}
+/**
+ * Response from POST /genres/{genreId}/presets
+ */
+export interface CreatePresetResponse extends PresetMetadata {
+    /** Genre this preset belongs to */
+    genreId: string;
+}
+/**
+ * Request body for PUT /genres/{genreId}/presets/{presetId}
+ */
+export interface UpdatePresetRequest {
+    /** Updated display name for the preset */
+    name: string;
+    /** Updated description of the opening scene */
+    description: string;
+}
+/**
+ * Response from PUT /genres/{genreId}/presets/{presetId}
+ */
+export interface UpdatePresetResponse extends PresetMetadata {
+    /** Genre this preset belongs to */
+    genreId: string;
+}
+/**
+ * Response from DELETE /genres/{genreId}/presets/{presetId}
+ */
+export interface DeletePresetResponse {
+    /** ID of the deleted preset */
+    presetId: string;
+    /** Genre the preset was deleted from */
+    genreId: string;
+    /** Confirmation message */
+    message: string;
+}

package/dist/preset.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Preset Types
+ *
+ * Presets are portable game state snapshots that can be cloned
+ * to create new games with identical initial conditions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeus-api-types",
-  "version": "1.0.48",
+  "version": "1.0.51",
   "description": "Shared API types for Wagtales - SSE payloads, error types, and common interfaces",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,6 +40,9 @@
     "url": "https://github.com/lovebowls/zeus-api-types/issues"
   },
   "sideEffects": false,
+  "dependencies": {
+    "tonelib": "file:../tonelib"
+  },
   "devDependencies": {
     "rimraf": "^5.0.0",
     "typescript": "^5.0.0"