1

server-rs/crates/shared-contracts/src/big_fish.rs

@@ -0,0 +1,238 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct CreateBigFishSessionRequest {
+    #[serde(default)]
+    pub seed_text: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct SendBigFishMessageRequest {
+    pub client_message_id: String,
+    pub text: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct ExecuteBigFishActionRequest {
+    pub action: String,
+    #[serde(default)]
+    pub level: Option<u32>,
+    #[serde(default)]
+    pub motion_key: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct SubmitBigFishInputRequest {
+    pub x: f32,
+    pub y: f32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishAnchorItemResponse {
+    pub key: String,
+    pub label: String,
+    pub value: String,
+    pub status: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishAnchorPackResponse {
+    pub gameplay_promise: BigFishAnchorItemResponse,
+    pub ecology_visual_theme: BigFishAnchorItemResponse,
+    pub growth_ladder: BigFishAnchorItemResponse,
+    pub risk_tempo: BigFishAnchorItemResponse,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishLevelBlueprintResponse {
+    pub level: u32,
+    pub name: String,
+    pub one_line_fantasy: String,
+    pub silhouette_direction: String,
+    pub size_ratio: f32,
+    pub visual_prompt_seed: String,
+    pub motion_prompt_seed: String,
+    pub merge_source_level: Option<u32>,
+    pub prey_window: Vec<u32>,
+    pub threat_window: Vec<u32>,
+    pub is_final_level: bool,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishBackgroundBlueprintResponse {
+    pub theme: String,
+    pub color_mood: String,
+    pub foreground_hints: String,
+    pub midground_composition: String,
+    pub background_depth: String,
+    pub safe_play_area_hint: String,
+    pub spawn_edge_hint: String,
+    pub background_prompt_seed: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishRuntimeParamsResponse {
+    pub level_count: u32,
+    pub merge_count_per_upgrade: u32,
+    pub spawn_target_count: u32,
+    pub leader_move_speed: f32,
+    pub follower_catch_up_speed: f32,
+    pub offscreen_cull_seconds: f32,
+    pub prey_spawn_delta_levels: Vec<u32>,
+    pub threat_spawn_delta_levels: Vec<u32>,
+    pub win_level: u32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishGameDraftResponse {
+    pub title: String,
+    pub subtitle: String,
+    pub core_fun: String,
+    pub ecology_theme: String,
+    pub levels: Vec<BigFishLevelBlueprintResponse>,
+    pub background: BigFishBackgroundBlueprintResponse,
+    pub runtime_params: BigFishRuntimeParamsResponse,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishAgentMessageResponse {
+    pub id: String,
+    pub role: String,
+    pub kind: String,
+    pub text: String,
+    pub created_at: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishAssetSlotResponse {
+    pub slot_id: String,
+    pub asset_kind: String,
+    pub level: Option<u32>,
+    pub motion_key: Option<String>,
+    pub status: String,
+    pub asset_url: Option<String>,
+    pub prompt_snapshot: String,
+    pub updated_at: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishAssetCoverageResponse {
+    pub level_main_image_ready_count: u32,
+    pub level_motion_ready_count: u32,
+    pub background_ready: bool,
+    pub required_level_count: u32,
+    pub publish_ready: bool,
+    pub blockers: Vec<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishSessionSnapshotResponse {
+    pub session_id: String,
+    pub current_turn: u32,
+    pub progress_percent: u32,
+    pub stage: String,
+    pub anchor_pack: BigFishAnchorPackResponse,
+    pub draft: Option<BigFishGameDraftResponse>,
+    pub asset_slots: Vec<BigFishAssetSlotResponse>,
+    pub asset_coverage: BigFishAssetCoverageResponse,
+    pub messages: Vec<BigFishAgentMessageResponse>,
+    pub last_assistant_reply: Option<String>,
+    pub publish_ready: bool,
+    pub updated_at: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishSessionResponse {
+    pub session: BigFishSessionSnapshotResponse,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishActionResponse {
+    pub session: BigFishSessionSnapshotResponse,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishVector2Response {
+    pub x: f32,
+    pub y: f32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishRuntimeEntityResponse {
+    pub entity_id: String,
+    pub level: u32,
+    pub position: BigFishVector2Response,
+    pub radius: f32,
+    pub offscreen_seconds: f32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishRuntimeSnapshotResponse {
+    pub run_id: String,
+    pub session_id: String,
+    pub status: String,
+    pub tick: u64,
+    pub player_level: u32,
+    pub win_level: u32,
+    pub leader_entity_id: Option<String>,
+    pub owned_entities: Vec<BigFishRuntimeEntityResponse>,
+    pub wild_entities: Vec<BigFishRuntimeEntityResponse>,
+    pub camera_center: BigFishVector2Response,
+    pub last_input: BigFishVector2Response,
+    pub event_log: Vec<String>,
+    pub updated_at: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct BigFishRunResponse {
+    pub run: BigFishRuntimeSnapshotResponse,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn big_fish_session_request_uses_camel_case() {
+        let payload = serde_json::to_value(CreateBigFishSessionRequest {
+            seed_text: Some("深海机械鱼".to_string()),
+        })
+        .expect("payload should serialize");
+
+        assert_eq!(payload, json!({ "seedText": "深海机械鱼" }));
+    }
+
+    #[test]
+    fn big_fish_action_request_uses_camel_case() {
+        let payload = serde_json::to_value(ExecuteBigFishActionRequest {
+            action: "big_fish_generate_level_motion".to_string(),
+            level: Some(3),
+            motion_key: Some("move_swim".to_string()),
+        })
+        .expect("payload should serialize");
+
+        assert_eq!(payload["motionKey"], json!("move_swim"));
+        assert_eq!(payload["level"], json!(3));
+    }
+}

server-rs/crates/shared-contracts/src/lib.rs

@@ -2,7 +2,12 @@ pub mod ai;
 pub mod api;
 pub mod assets;
 pub mod auth;
+pub mod big_fish;
 pub mod llm;
+pub mod puzzle_agent;
+pub mod puzzle_gallery;
+pub mod puzzle_runtime;
+pub mod puzzle_works;
 pub mod runtime;
 pub mod runtime_story;
 pub mod story;

server-rs/crates/shared-contracts/src/puzzle_agent.rs

@@ -0,0 +1,188 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct CreatePuzzleAgentSessionRequest {
+    #[serde(default)]
+    pub seed_text: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct SendPuzzleAgentMessageRequest {
+    pub client_message_id: String,
+    pub text: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct ExecutePuzzleAgentActionRequest {
+    pub action: String,
+    #[serde(default)]
+    pub prompt_text: Option<String>,
+    #[serde(default)]
+    pub candidate_count: Option<u32>,
+    #[serde(default)]
+    pub candidate_id: Option<String>,
+    #[serde(default)]
+    pub level_name: Option<String>,
+    #[serde(default)]
+    pub summary: Option<String>,
+    #[serde(default)]
+    pub theme_tags: Option<Vec<String>>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleAnchorItemResponse {
+    pub key: String,
+    pub label: String,
+    pub value: String,
+    pub status: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleAnchorPackResponse {
+    pub theme_promise: PuzzleAnchorItemResponse,
+    pub visual_subject: PuzzleAnchorItemResponse,
+    pub visual_mood: PuzzleAnchorItemResponse,
+    pub composition_hooks: PuzzleAnchorItemResponse,
+    pub tags_and_forbidden: PuzzleAnchorItemResponse,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleGeneratedImageCandidateResponse {
+    pub candidate_id: String,
+    pub image_src: String,
+    pub asset_id: String,
+    pub prompt: String,
+    #[serde(default)]
+    pub actual_prompt: Option<String>,
+    pub source_type: String,
+    pub selected: bool,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleCreatorIntentResponse {
+    pub source_mode: String,
+    pub raw_messages_summary: String,
+    pub theme_promise: String,
+    pub visual_subject: String,
+    pub visual_mood: Vec<String>,
+    pub composition_hooks: Vec<String>,
+    pub theme_tags: Vec<String>,
+    pub forbidden_directives: Vec<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleResultDraftResponse {
+    pub level_name: String,
+    pub summary: String,
+    pub theme_tags: Vec<String>,
+    pub forbidden_directives: Vec<String>,
+    #[serde(default)]
+    pub creator_intent: Option<PuzzleCreatorIntentResponse>,
+    pub anchor_pack: PuzzleAnchorPackResponse,
+    pub candidates: Vec<PuzzleGeneratedImageCandidateResponse>,
+    #[serde(default)]
+    pub selected_candidate_id: Option<String>,
+    #[serde(default)]
+    pub cover_image_src: Option<String>,
+    #[serde(default)]
+    pub cover_asset_id: Option<String>,
+    pub generation_status: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleAgentMessageResponse {
+    pub id: String,
+    pub role: String,
+    pub kind: String,
+    pub text: String,
+    pub created_at: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleAgentSuggestedActionResponse {
+    pub id: String,
+    pub action_type: String,
+    pub label: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleResultPreviewBlockerResponse {
+    pub id: String,
+    pub code: String,
+    pub message: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleResultPreviewFindingResponse {
+    pub id: String,
+    pub severity: String,
+    pub code: String,
+    pub message: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleResultPreviewEnvelopeResponse {
+    pub draft: PuzzleResultDraftResponse,
+    pub blockers: Vec<PuzzleResultPreviewBlockerResponse>,
+    pub quality_findings: Vec<PuzzleResultPreviewFindingResponse>,
+    pub publish_ready: bool,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleAgentSessionSnapshotResponse {
+    pub session_id: String,
+    pub current_turn: u32,
+    pub progress_percent: u32,
+    pub stage: String,
+    pub anchor_pack: PuzzleAnchorPackResponse,
+    #[serde(default)]
+    pub draft: Option<PuzzleResultDraftResponse>,
+    pub messages: Vec<PuzzleAgentMessageResponse>,
+    #[serde(default)]
+    pub last_assistant_reply: Option<String>,
+    #[serde(default)]
+    pub published_profile_id: Option<String>,
+    pub suggested_actions: Vec<PuzzleAgentSuggestedActionResponse>,
+    #[serde(default)]
+    pub result_preview: Option<PuzzleResultPreviewEnvelopeResponse>,
+    pub updated_at: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleAgentSessionResponse {
+    pub session: PuzzleAgentSessionSnapshotResponse,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleAgentOperationResponse {
+    pub operation_id: String,
+    pub operation_type: String,
+    pub status: String,
+    pub phase_label: String,
+    pub phase_detail: String,
+    pub progress: u32,
+    #[serde(default)]
+    pub error: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleAgentActionResponse {
+    pub operation: PuzzleAgentOperationResponse,
+}

server-rs/crates/shared-contracts/src/puzzle_gallery.rs

@@ -0,0 +1,15 @@
+use serde::{Deserialize, Serialize};
+
+use crate::puzzle_works::PuzzleWorkSummaryResponse;
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleGalleryResponse {
+    pub items: Vec<PuzzleWorkSummaryResponse>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleGalleryDetailResponse {
+    pub item: PuzzleWorkSummaryResponse,
+}

server-rs/crates/shared-contracts/src/puzzle_runtime.rs

@@ -0,0 +1,99 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct StartPuzzleRunRequest {
+    pub profile_id: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct SwapPuzzlePiecesRequest {
+    pub first_piece_id: String,
+    pub second_piece_id: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct DragPuzzlePieceRequest {
+    pub piece_id: String,
+    pub target_row: u32,
+    pub target_col: u32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleCellPositionResponse {
+    pub row: u32,
+    pub col: u32,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzlePieceStateResponse {
+    pub piece_id: String,
+    pub correct_row: u32,
+    pub correct_col: u32,
+    pub current_row: u32,
+    pub current_col: u32,
+    #[serde(default)]
+    pub merged_group_id: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleMergedGroupStateResponse {
+    pub group_id: String,
+    pub piece_ids: Vec<String>,
+    pub occupied_cells: Vec<PuzzleCellPositionResponse>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleBoardSnapshotResponse {
+    pub rows: u32,
+    pub cols: u32,
+    pub pieces: Vec<PuzzlePieceStateResponse>,
+    pub merged_groups: Vec<PuzzleMergedGroupStateResponse>,
+    #[serde(default)]
+    pub selected_piece_id: Option<String>,
+    pub all_tiles_resolved: bool,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleRuntimeLevelSnapshotResponse {
+    pub run_id: String,
+    pub level_index: u32,
+    pub grid_size: u32,
+    pub profile_id: String,
+    pub level_name: String,
+    pub author_display_name: String,
+    pub theme_tags: Vec<String>,
+    #[serde(default)]
+    pub cover_image_src: Option<String>,
+    pub board: PuzzleBoardSnapshotResponse,
+    pub status: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleRunSnapshotResponse {
+    pub run_id: String,
+    pub entry_profile_id: String,
+    pub cleared_level_count: u32,
+    pub current_level_index: u32,
+    pub current_grid_size: u32,
+    pub played_profile_ids: Vec<String>,
+    pub previous_level_tags: Vec<String>,
+    #[serde(default)]
+    pub current_level: Option<PuzzleRuntimeLevelSnapshotResponse>,
+    #[serde(default)]
+    pub recommended_next_profile_id: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleRunResponse {
+    pub run: PuzzleRunSnapshotResponse,
+}

server-rs/crates/shared-contracts/src/puzzle_works.rs

@@ -0,0 +1,65 @@
+use serde::{Deserialize, Serialize};
+
+use crate::puzzle_agent::PuzzleAnchorPackResponse;
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PutPuzzleWorkRequest {
+    pub level_name: String,
+    pub summary: String,
+    pub theme_tags: Vec<String>,
+    #[serde(default)]
+    pub cover_image_src: Option<String>,
+    #[serde(default)]
+    pub cover_asset_id: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleWorkSummaryResponse {
+    pub work_id: String,
+    pub profile_id: String,
+    pub owner_user_id: String,
+    #[serde(default)]
+    pub source_session_id: Option<String>,
+    pub author_display_name: String,
+    pub level_name: String,
+    pub summary: String,
+    pub theme_tags: Vec<String>,
+    #[serde(default)]
+    pub cover_image_src: Option<String>,
+    #[serde(default)]
+    pub cover_asset_id: Option<String>,
+    pub publication_status: String,
+    pub updated_at: String,
+    #[serde(default)]
+    pub published_at: Option<String>,
+    pub play_count: u32,
+    pub publish_ready: bool,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleWorkProfileResponse {
+    #[serde(flatten)]
+    pub summary: PuzzleWorkSummaryResponse,
+    pub anchor_pack: PuzzleAnchorPackResponse,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleWorksResponse {
+    pub items: Vec<PuzzleWorkSummaryResponse>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleWorkDetailResponse {
+    pub item: PuzzleWorkProfileResponse,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleWorkMutationResponse {
+    pub item: PuzzleWorkProfileResponse,
+}