zeus-api-types 1.0.0 → 1.0.1

package/dist/game-state.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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;
+    day: number;
+    hour: number;
+    minute: number;
+}
+/**
+ * Base interface for world entities (NPCs, Locations, etc.)
+ * All world entities share this common structure
+ */
+export interface WorldEntity {
+    id: string;
+    name?: string;
+    description?: string;
+    discovered?: boolean;
+    image?: string;
+    [key: string]: unknown;
+}
+/**
+ * Player character
+ */
+export interface Player extends WorldEntity {
+    name: string;
+    motivation?: string;
+    role?: string;
+    backstory?: string;
+    tone?: string;
+}
+/**
+ * Non-Player Character
+ * Inherits base entity structure, all other properties are genre-specific
+ */
+export interface NPC extends WorldEntity {
+    name: string;
+    discovered: boolean;
+    playable?: boolean;
+    motivation?: string;
+    role?: string;
+    backstory?: string;
+    tone?: string;
+}
+/**
+ * Location in the game world
+ * Requires name and description, maintains custom properties for tracking
+ */
+export interface Location extends WorldEntity {
+    name: string;
+    description: string;
+    discovered: boolean;
+    atmosphere: string;
+    accessible: boolean;
+}
+/**
+ * World container - reduced version without events (for frontend)
+ */
+export interface World {
+    locations: Record<string, Location>;
+    npcs: Record<string, NPC>;
+}
+export interface DialogMessage {
+    speaker: string;
+    message: string;
+    timestamp?: string;
+    tone?: string;
+}
+export interface HistoryEntry {
+    turn_number: number;
+    timestamp: string;
+    game_time?: string;
+    location: string;
+    narrative_summary: string;
+    choice: {
+        id?: string;
+        label: string;
+        meta?: unknown;
+    };
+    charactersPresent?: string[];
+}
+export interface PresentationCache {
+    turn: number;
+    narrative: string;
+    charactersPresent?: string[];
+    storyArcProgression?: number;
+    dialogHistory?: DialogMessage[];
+    generatedAt?: string;
+    source?: string;
+}
+export interface Session {
+    history: HistoryEntry[];
+    storySoFar?: HistoryEntry[];
+    key_themes?: string[];
+    narrative_momentum?: string;
+    presentationCache?: PresentationCache;
+    prologue?: string;
+}
+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;
+}

package/dist/game-state.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Game State Types
+ *
+ * Core game state interfaces shared between middle-layer and frontend.
+ * Extracted from middle-layer/src/core/GameState.ts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -1,2 +1,4 @@
-export { ApiError, ApiErrorResponse } from './errors';
-export { NarrativeStartEventPayload, NarrativeChunkEventPayload, NarrativeCompleteEventPayload, NarrativeMetadataEventPayload, MetadataEventPayload, DoneEventPayload, ErrorEventPayload, NarrativeSSEEventPayload, } from './sse/narrative';
+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, World, DialogMessage, HistoryEntry, PresentationCache, Session, StoryArc, } from './game-state';
+export type { NarrativeFontPreferences, SoundPreferences, ModelStackPreset, ModelEntry, ModelStack, ModelStackPreferences, SystemModelPresets, AIPreferences, UserPreferences, UserMetadata, } from './user-preferences';

package/dist/user-preferences.d.ts

@@ -0,0 +1,131 @@
+/**
+ * User Preferences Types
+ *
+ * User preference interfaces shared between middle-layer and frontend.
+ * Extracted from middle-layer/src/core/GameState.ts
+ */
+/**
+ * Narrative font preferences for display customization
+ * Supports preset font stacks, custom fonts, and Google Fonts
+ */
+export interface NarrativeFontPreferences {
+    /**
+     * Font family - can be:
+     * - Preset name: 'serif', 'sans', 'mono', 'literary', 'modern', 'typewriter'
+     * - Custom CSS font-family string: 'Lora, Georgia, serif'
+     */
+    family: string;
+    /** Font size in pixels (12-48) */
+    sizePx: number;
+    /** Line height multiplier (1.0-3.0), default 1.7 */
+    lineHeight?: number;
+    /** Letter spacing in pixels (0-5), default 0 */
+    letterSpacing?: number;
+    /** Optional Google Fonts URL for custom font loading */
+    googleFontsUrl?: string;
+}
+/**
+ * Sound notification preferences
+ */
+export interface SoundPreferences {
+    /** Sound to play when narrative starts streaming */
+    onNarrativeStart: string;
+    /** Volume for narrative start sound (0.0-1.0) */
+    onNarrativeStartVolume: number;
+    /** Sound to play when narrative finishes streaming */
+    onNarrativeEnd: string;
+    /** Volume for narrative end sound (0.0-1.0) */
+    onNarrativeEndVolume: number;
+    /** Enable haptic feedback (vibration) when narrative ends */
+    hapticsOnNarrativeEnd?: boolean;
+}
+/**
+ * Preset identifiers for model stacks
+ */
+export type ModelStackPreset = 'fast' | 'balanced' | 'detailed' | 'custom';
+/**
+ * A single model entry in a stack with configuration
+ * Extensible for future OpenRouter parameters
+ */
+export interface ModelEntry {
+    /** OpenRouter model identifier (e.g., "anthropic/claude-3.5-sonnet") */
+    model: string;
+    /** Temperature for generation (0.0-2.0) */
+    temperature: number;
+    /** Optional max tokens override */
+    maxTokens?: number;
+    /** Optional top_p parameter */
+    topP?: number;
+}
+/**
+ * A stack of models to try in order (with deduplication against env fallbacks)
+ */
+export type ModelStack = ModelEntry[];
+/**
+ * User's model stack preferences
+ */
+export interface ModelStackPreferences {
+    /** Selected preset for narrative generation */
+    narrativePreset: ModelStackPreset;
+    /** Selected preset for dialog generation */
+    dialogPreset: ModelStackPreset;
+    /** Custom stack for narrative (used when narrativePreset === 'custom') */
+    narrativeCustom?: ModelStack;
+    /** Custom stack for dialog (used when dialogPreset === 'custom') */
+    dialogCustom?: ModelStack;
+}
+/**
+ * System-level model stack presets (stored in TEMPLATE/preferences.json)
+ */
+export interface SystemModelPresets {
+    narrative: {
+        fast: ModelStack;
+        balanced: ModelStack;
+        detailed: ModelStack;
+    };
+    dialog: {
+        fast: ModelStack;
+        balanced: ModelStack;
+        detailed: ModelStack;
+    };
+    /** Extraction presets (backend-only, no user selection - only 'balanced') */
+    extraction?: {
+        balanced: ModelStack;
+    };
+    /** Genre init presets (backend-only, no user selection - only 'balanced') */
+    genre?: {
+        balanced: ModelStack;
+    };
+}
+/**
+ * AI behavior preferences
+ */
+export interface AIPreferences {
+    /**
+     * Words/phrases the AI should avoid using in narrative generation.
+     * These are aggregated with system, genre, and narrative style blacklists.
+     */
+    blacklist: string[];
+    /**
+     * Model stack preferences for narrative and dialog generation
+     */
+    modelPrefs?: ModelStackPreferences;
+}
+/**
+ * User preferences stored in preferences.json
+ */
+export interface UserPreferences {
+    version: number;
+    updatedAt?: string;
+    /** Display name for the user (1-50 chars, free-text Unicode) */
+    userName?: string;
+    narrativeFont: NarrativeFontPreferences;
+    sound?: SoundPreferences;
+    ai?: AIPreferences;
+}
+/**
+ * User-specific metadata injected into game state responses
+ */
+export interface UserMetadata {
+    preferences: UserPreferences;
+}

package/dist/user-preferences.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * User Preferences Types
+ *
+ * User preference interfaces shared between middle-layer and frontend.
+ * Extracted from middle-layer/src/core/GameState.ts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeus-api-types",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Shared API types for Wagtales - SSE payloads, error types, and common interfaces",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -44,4 +44,3 @@
     "typescript": "^5.0.0"
   }
 }
-