zeus-api-types 1.0.47 → 1.0.50

package/dist/game-state.d.ts

@@ -1,3 +1,81 @@
+import { ToneCompact } from "tonelib";
+import { UserMetadata } from "./user-preferences";
+/**
+ * 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;
+}
+/**
+ * Tag structure for both system-level and author-defined metadata
+ * - System tags (in immutable): managed by backend, hidden from UI
+ * - Author tags (in metadata): user-editable via genre editor
+ */
+export interface Tag {
+    /** Unique key identifier (max 64 chars) */
+    key: string;
+    /** Value as string or array of strings (max 64 chars per item) */
+    value: string | string[];
+}
+/**
+ * Base interface for all immutable blocks
+ */
+export interface BaseImmutableState {
+    id: string;
+    hash?: string;
+}
+/**
+ * Game-specific immutable state
+ */
+export interface ImmutableState extends BaseImmutableState {
+    userId: string;
+    genre: string;
+    author: string;
+    ai?: {
+        metadata: AIMetadata;
+    };
+    act?: number;
+    sagaId?: string;
+    previousActId?: string;
+    nextActId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Genre-specific immutable state (for genre authoring)
+ */
+export interface GenreImmutableState extends BaseImmutableState {
+    genre: string;
+    author: string;
+    published: boolean;
+    createdAt: string;
+    tags?: Tag[];
+}
 /**
  * World container - reduced version without events (for frontend)
  */
@@ -9,7 +87,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;
@@ -70,6 +147,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;
@@ -99,6 +183,8 @@ export interface PresentationCache {
     dialogHistory?: DialogMessage[];
     generatedAt?: string;
     source?: string;
+    choiceMetadata?: PresentationChoiceMeta[];
+    presentationCache?: PresentationCache;
 }
 export interface Session {
     history: HistoryEntry[];
@@ -127,3 +213,218 @@ export interface StoryArc {
     tone_pattern?: string[];
     [key: string]: unknown;
 }
+/**
+ * Deck Definitions
+ *
+ * Describes the structure of deck.json fixtures for each genre.
+ */
+/**
+ * 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;
+}
+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[];
+}
+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;
+    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,2 +1,5 @@
 "use strict";
+// ============================================================================
+// AI METADATA TRACKING
+// ============================================================================
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 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, } 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, BaseDeckCard, BaseImmutableState, DeckDefinition, DialogContext, DialogMessage, FixtureSet, GameState, GameStateReduced, GenreImmutableState, HistoryEntry, ImmutableState, Location, Metadata, MultiDeckDefinition, NarrativeStyleCard, NPC, Player, PresentationCache, Session, StoryArc, StoryArcCard, Tag, TimeState, WorldEntity, WorldReduced, EventPropagation, BaseEvent, DeterministicEvent, ScheduledEvent, ProbabilisticEvent, EventHistoryEntry, WorldEvents, World, StateSnapshot, PromptVariables, GameMetadata, AIOperationType, NpcExistingOrNewOp, PresentationChoiceMeta } from './game-state';
+export type { AIPreferences, ModelEntry, ModelStack, ModelStackPreferences, ModelStackPreset, NarrativeFontPreferences, SoundPreferences, SystemModelPresets, UserMetadata, UserPreferences } from './user-preferences';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeus-api-types",
-  "version": "1.0.47",
+  "version": "1.0.50",
   "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"