1

packages/shared/src/contracts/visualNovel.ts

@@ -0,0 +1,410 @@
+export type VisualNovelSourceMode = 'idea' | 'document' | 'blank';
+
+export type VisualNovelCharacterRole =
+  | 'protagonist'
+  | 'main'
+  | 'supporting'
+  | 'antagonist'
+  | 'background';
+
+export type VisualNovelAssetSource = 'platform_asset' | 'generated' | 'external';
+
+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 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' };