Genarrative/packages/shared/src/contracts/visualNovel.ts

export type VisualNovelSourceMode = 'idea' | 'document' | 'blank';

export type VisualNovelCharacterRole =
  | 'protagonist'
  | 'main'
  | 'supporting'
  | 'antagonist'
  | 'background';

export type VisualNovelAssetSource =
  | 'platform_asset'
  | 'generated'
  | 'external';

export type VisualNovelAudioGenerationKind =
  | 'background_music'
  | 'sound_effect';

export type VisualNovelSceneAvailability =
  | 'opening'
  | 'always'
  | 'phase_locked';

export type VisualNovelAttributePanelMode =
  | 'off'
  | 'platform_whitelist'
  | 'template_config';

export type VisualNovelValidationSeverity = 'error' | 'warning';

export type VisualNovelAgentStatus =
  | 'collecting'
  | 'drafting'
  | 'ready'
  | 'failed';

export type VisualNovelAgentMessageRole = 'user' | 'assistant' | 'system';

export type VisualNovelAgentMessageKind =
  | 'chat'
  | 'summary'
  | 'action_result'
  | 'warning';

export type VisualNovelAgentActionKind =
  | 'generate_draft'
  | 'patch_world'
  | 'patch_character'
  | 'patch_scene'
  | 'patch_story_phase'
  | 'generate_scene_image'
  | 'generate_character_image'
  | 'compile_work_profile';

export type VisualNovelAgentPhase =
  | 'perception'
  | 'reasoning'
  | 'drafting'
  | 'reflection'
  | 'finalizing';

export type VisualNovelRunMode = 'test' | 'play';

export type VisualNovelRunStatus = 'active' | 'completed' | 'failed';

export type VisualNovelRuntimeActionKind = 'choice' | 'free_text' | 'continue';

export type VisualNovelTransitionKind = 'fade' | 'cut' | 'flash' | 'none';

export type VisualNovelHistorySource = 'player' | 'assistant' | 'system';

export type VisualNovelFlagValue = string | number | boolean;

export interface VisualNovelDraftPatch {
  path: string;
  op: 'add' | 'replace' | 'remove';
  value?: unknown;
}

export interface VisualNovelValidationIssue {
  issueId: string;
  code: string;
  severity: VisualNovelValidationSeverity;
  path: string;
  message: string;
}

export interface VisualNovelChoiceDraft {
  choiceId: string;
  text: string;
  actionHint?: string | null;
}

export interface VisualNovelCharacterImageAsset {
  assetId: string;
  imageSrc: string;
  expression?: string | null;
  source: VisualNovelAssetSource;
}

export interface VisualNovelWorldDraft {
  title: string;
  summary: string;
  background: string;
  premise: string;
  literaryStyle: string;
  playerRole: string;
  defaultTone: string;
}

export interface VisualNovelCharacterDraft {
  characterId: string;
  name: string;
  gender: string | null;
  role: VisualNovelCharacterRole;
  appearance: string;
  personality: string;
  tone: string;
  background: string;
  relationshipToPlayer: string;
  imageAssets: VisualNovelCharacterImageAsset[];
  defaultExpression: string | null;
  isPlayerVisible: boolean;
}

export interface VisualNovelSceneDraft {
  sceneId: string;
  name: string;
  description: string;
  backgroundImageSrc: string | null;
  musicSrc: string | null;
  ambientSoundSrc: string | null;
  availability: VisualNovelSceneAvailability;
  phaseIds: string[];
}

export interface VisualNovelStoryPhaseDraft {
  phaseId: string;
  title: string;
  goal: string;
  summary: string;
  entryCondition: string;
  exitCondition: string;
  sceneIds: string[];
  characterIds: string[];
  suggestedChoices: string[];
}

export interface VisualNovelOpeningDraft {
  sceneId: string | null;
  narration: string;
  speakerCharacterId: string | null;
  firstDialogue: string | null;
  initialChoices: VisualNovelChoiceDraft[];
}

export interface VisualNovelRuntimeConfigDraft {
  textModeEnabled: boolean;
  defaultTextMode: boolean;
  maxHistoryEntries: number;
  maxAssistantStepCountPerTurn: number;
  allowFreeTextAction: boolean;
  allowHistoryRegeneration: boolean;
  attributePanelMode: VisualNovelAttributePanelMode;
  saveArchiveEnabled: boolean;
}

export interface VisualNovelResultDraft {
  profileId: string | null;
  workTitle: string;
  workDescription: string;
  workTags: string[];
  coverImageSrc: string | null;
  sourceMode: VisualNovelSourceMode;
  sourceAssetIds: string[];
  world: VisualNovelWorldDraft;
  characters: VisualNovelCharacterDraft[];
  scenes: VisualNovelSceneDraft[];
  storyPhases: VisualNovelStoryPhaseDraft[];
  opening: VisualNovelOpeningDraft;
  runtimeConfig: VisualNovelRuntimeConfigDraft;
  publishReady: boolean;
  validationIssues: VisualNovelValidationIssue[];
  updatedAt: string;
}

export interface VisualNovelAgentMessage {
  id: string;
  role: VisualNovelAgentMessageRole;
  kind: VisualNovelAgentMessageKind;
  text: string;
  createdAt: string;
}

export interface VisualNovelAgentPendingAction {
  actionId: string;
  kind: VisualNovelAgentActionKind;
  label: string;
  targetId?: string | null;
  payload?: unknown;
}

export interface VisualNovelAgentSessionSnapshot {
  sessionId: string;
  ownerUserId: string;
  sourceMode: VisualNovelSourceMode;
  status: VisualNovelAgentStatus;
  messages: VisualNovelAgentMessage[];
  draft: VisualNovelResultDraft | null;
  pendingAction: VisualNovelAgentPendingAction | null;
  createdAt: string;
  updatedAt: string;
}

export interface CreateVisualNovelSessionRequest {
  sourceMode: VisualNovelSourceMode;
  seedText?: string | null;
  sourceAssetIds?: string[];
}

export interface VisualNovelSessionResponse {
  session: VisualNovelAgentSessionSnapshot;
}

export interface VisualNovelWorkSummary {
  runtimeKind: 'visual-novel';
  profileId: string;
  ownerUserId: string;
  title: string;
  description: string;
  coverImageSrc: string | null;
  tags: string[];
  publishStatus: string;
  publishReady: boolean;
  playCount: number;
  updatedAt: string;
  publishedAt: string | null;
}

export interface VisualNovelWorkDetail {
  workId: string;
  summary: VisualNovelWorkSummary;
  sourceSessionId: string | null;
  authorDisplayName: string;
  sourceAssetIds: string[];
  draft: VisualNovelResultDraft;
  createdAt: string;
}

export interface VisualNovelWorksResponse {
  works: VisualNovelWorkSummary[];
}

export interface VisualNovelWorkResponse {
  work: VisualNovelWorkDetail;
}

export interface UpdateVisualNovelWorkRequest {
  draft: VisualNovelResultDraft;
}

export interface VisualNovelCompileResponse {
  session: VisualNovelAgentSessionSnapshot;
  work: VisualNovelWorkDetail;
}

export interface CreateVisualNovelBackgroundMusicRequest {
  prompt: string;
  title: string;
  tags?: string | null;
  model?: string | null;
}

export interface CreateVisualNovelSoundEffectRequest {
  prompt: string;
  duration?: number | null;
  seed?: number | null;
}

export interface VisualNovelAudioGenerationTaskResponse {
  kind: VisualNovelAudioGenerationKind;
  taskId: string;
  provider: string;
  status: string;
}

export interface PublishVisualNovelGeneratedAudioAssetRequest {
  sceneId: string;
  profileId?: string | null;
}

export interface VisualNovelGeneratedAudioAssetResponse {
  kind: VisualNovelAudioGenerationKind;
  taskId: string;
  provider: string;
  status: string;
  assetObjectId?: string | null;
  assetKind?: string | null;
  audioSrc?: string | null;
}

export interface SendVisualNovelMessageRequest {
  clientMessageId: string;
  text: string;
}

export interface ExecuteVisualNovelAgentActionRequest {
  actionId?: string | null;
  kind: VisualNovelAgentActionKind;
  targetId?: string | null;
  payload?: unknown;
}

export interface CompileVisualNovelWorkProfileRequest {
  draft: VisualNovelResultDraft;
}

export type VisualNovelAgentStreamEvent =
  | { type: 'start'; sessionId: string }
  | { type: 'phase'; phase: VisualNovelAgentPhase }
  | { type: 'text_delta'; text: string }
  | { type: 'draft_patch'; patch: VisualNovelDraftPatch }
  | { type: 'action_required'; action: VisualNovelAgentPendingAction }
  | { type: 'complete'; session: VisualNovelAgentSessionSnapshot }
  | { type: 'error'; message: string; retryable: boolean }
  | { type: 'done' };

export interface VisualNovelSceneChangeStep {
  type: 'scene_change';
  sceneId: string;
  backgroundImageSrc: string | null;
  musicSrc: string | null;
}

export interface VisualNovelNarrationStep {
  type: 'narration';
  text: string;
}

export interface VisualNovelDialogueStep {
  type: 'dialogue';
  characterId: string;
  characterName: string;
  expression: string | null;
  text: string;
}

export interface VisualNovelTransitionStep {
  type: 'transition';
  transitionKind: VisualNovelTransitionKind;
  text: string | null;
}

export interface VisualNovelChoiceStep {
  type: 'choice';
  choices: VisualNovelChoiceDraft[];
}

export interface VisualNovelFlagStep {
  type: 'flag';
  key: string;
  value: VisualNovelFlagValue;
}

export interface VisualNovelMetricStep {
  type: 'metric';
  key: string;
  delta: number;
}

export type VisualNovelRuntimeStep =
  | VisualNovelSceneChangeStep
  | VisualNovelNarrationStep
  | VisualNovelDialogueStep
  | VisualNovelTransitionStep
  | VisualNovelChoiceStep
  | VisualNovelFlagStep
  | VisualNovelMetricStep;

export interface VisualNovelHistoryEntry {
  entryId: string;
  runId: string;
  turnIndex: number;
  source: VisualNovelHistorySource;
  actionText: string | null;
  steps: VisualNovelRuntimeStep[];
  snapshotBeforeHash: string | null;
  snapshotAfterHash: string | null;
  createdAt: string;
}

export interface VisualNovelRunSnapshot {
  runId: string;
  ownerUserId: string;
  profileId: string;
  mode: VisualNovelRunMode;
  status: VisualNovelRunStatus;
  currentSceneId: string | null;
  currentPhaseId: string | null;
  visibleCharacterIds: string[];
  flags: Record<string, VisualNovelFlagValue>;
  metrics: Record<string, number>;
  history: VisualNovelHistoryEntry[];
  availableChoices: VisualNovelChoiceDraft[];
  textModeEnabled: boolean;
  createdAt: string;
  updatedAt: string;
}

export interface VisualNovelRuntimeActionRequest {
  actionKind: VisualNovelRuntimeActionKind;
  choiceId?: string;
  text?: string;
  clientEventId: string;
}

export interface VisualNovelStartRunRequest {
  profileId: string;
  mode: VisualNovelRunMode;
}

export interface VisualNovelRunResponse {
  run: VisualNovelRunSnapshot;
}

export interface VisualNovelHistoryResponse {
  history: VisualNovelHistoryEntry[];
}

export interface VisualNovelRegenerateRequest {
  historyEntryId: string;
  clientEventId: string;
}

export interface VisualNovelSaveArchiveState {
  runtimeKind: 'visual-novel';
  profileId: string;
  runId: string;
  currentSceneId: string | null;
  currentPhaseId: string | null;
  historyCursor: number;
  snapshotHash: string | null;
}

export type VisualNovelRuntimeStreamEvent =
  | { type: 'start'; runId: string }
  | { type: 'raw_text'; text: string }
  | { type: 'step'; step: VisualNovelRuntimeStep }
  | { type: 'snapshot'; run: VisualNovelRunSnapshot }
  | { type: 'complete'; run: VisualNovelRunSnapshot }
  | { type: 'error'; message: string; retryable: boolean }
  | { type: 'done' };