Enforce Genarrative play-type SOP and update docs

Rewrite Genarrative play-type integration guidance across .codex and .hermes to define a platform-level SOP: default to form/image workbench, unify single-image asset slots (CreativeImageInputPanel), standardize series-material sheet->cut->transparent->OSS pipeline, and forbid copying legacy chat/agent workflows as the default. Add decision-log entry freezing the SOP and a pitfalls note warning against direct reuse of old play tools. Update CONTEXT.md and docs/README.md, add a new PRD file, and apply related small server-side changes (module-auth, spacetime-client mappers and runtime) to align back-end code with the new contracts and flows.

server-rs/crates/spacetime-module/Cargo.toml

@@ -18,6 +18,7 @@ module-big-fish = { workspace = true, features = ["spacetime-types"] }
 module-combat = { workspace = true, features = ["spacetime-types"] }
 module-inventory = { workspace = true, features = ["spacetime-types"] }
 module-custom-world = { workspace = true, features = ["spacetime-types"] }
+module-jump-hop = { workspace = true, features = ["spacetime-types"] }
 module-match3d = { workspace = true }
 module-npc = { workspace = true, features = ["spacetime-types"] }
 module-puzzle = { workspace = true, features = ["spacetime-types"] }

server-rs/crates/spacetime-module/src/jump_hop/tables.rs

@@ -0,0 +1,91 @@
+use crate::*;
+
+#[spacetimedb::table(
+    accessor = jump_hop_agent_session,
+    index(accessor = by_jump_hop_agent_session_owner_user_id, btree(columns = [owner_user_id]))
+)]
+pub struct JumpHopAgentSessionRow {
+    #[primary_key]
+    pub(crate) session_id: String,
+    pub(crate) owner_user_id: String,
+    pub(crate) seed_text: String,
+    pub(crate) current_turn: u32,
+    pub(crate) progress_percent: u32,
+    pub(crate) stage: String,
+    pub(crate) config_json: String,
+    pub(crate) draft_json: String,
+    pub(crate) last_assistant_reply: String,
+    pub(crate) published_profile_id: String,
+    pub(crate) created_at: Timestamp,
+    pub(crate) updated_at: Timestamp,
+}
+
+#[spacetimedb::table(
+    accessor = jump_hop_work_profile,
+    index(accessor = by_jump_hop_work_owner_user_id, btree(columns = [owner_user_id])),
+    index(accessor = by_jump_hop_work_publication_status, btree(columns = [publication_status]))
+)]
+pub struct JumpHopWorkProfileRow {
+    #[primary_key]
+    pub(crate) profile_id: String,
+    pub(crate) work_id: String,
+    pub(crate) owner_user_id: String,
+    pub(crate) source_session_id: String,
+    pub(crate) author_display_name: String,
+    pub(crate) work_title: String,
+    pub(crate) work_description: String,
+    pub(crate) theme_tags_json: String,
+    pub(crate) difficulty: String,
+    pub(crate) style_preset: String,
+    pub(crate) character_prompt: String,
+    pub(crate) tile_prompt: String,
+    pub(crate) end_mood_prompt: String,
+    pub(crate) character_asset_json: String,
+    pub(crate) tile_atlas_asset_json: String,
+    pub(crate) tile_assets_json: String,
+    pub(crate) path_json: String,
+    pub(crate) cover_image_src: String,
+    pub(crate) cover_composite: String,
+    pub(crate) generation_status: String,
+    pub(crate) publication_status: String,
+    pub(crate) play_count: u32,
+    pub(crate) updated_at: Timestamp,
+    pub(crate) published_at: Option<Timestamp>,
+}
+
+#[spacetimedb::table(
+    accessor = jump_hop_runtime_run,
+    index(accessor = by_jump_hop_run_owner_user_id, btree(columns = [owner_user_id])),
+    index(accessor = by_jump_hop_run_profile_id, btree(columns = [profile_id]))
+)]
+pub struct JumpHopRuntimeRunRow {
+    #[primary_key]
+    pub(crate) run_id: String,
+    pub(crate) owner_user_id: String,
+    pub(crate) profile_id: String,
+    pub(crate) status: String,
+    pub(crate) started_at_ms: i64,
+    pub(crate) finished_at_ms: i64,
+    pub(crate) current_platform_index: u32,
+    pub(crate) score: u32,
+    pub(crate) combo: u32,
+    pub(crate) snapshot_json: String,
+    pub(crate) created_at: Timestamp,
+    pub(crate) updated_at: Timestamp,
+}
+
+#[spacetimedb::table(
+    accessor = jump_hop_event,
+    index(accessor = by_jump_hop_event_profile_id, btree(columns = [profile_id])),
+    index(accessor = by_jump_hop_event_run_id, btree(columns = [run_id]))
+)]
+pub struct JumpHopEventRow {
+    #[primary_key]
+    pub(crate) event_id: String,
+    pub(crate) owner_user_id: String,
+    pub(crate) profile_id: String,
+    pub(crate) run_id: String,
+    pub(crate) event_type: String,
+    pub(crate) result: String,
+    pub(crate) occurred_at: Timestamp,
+}

server-rs/crates/spacetime-module/src/jump_hop/types.rs

@@ -0,0 +1,261 @@
+use crate::*;
+use serde::{Deserialize, Serialize};
+
+pub const JUMP_HOP_TEMPLATE_ID: &str = "jump-hop";
+pub const JUMP_HOP_TEMPLATE_NAME: &str = "跳一跳";
+pub const JUMP_HOP_STYLE_MINIMAL_BLOCKS: &str = "minimal-blocks";
+pub const JUMP_HOP_STAGE_COLLECTING: &str = "Collecting";
+pub const JUMP_HOP_STAGE_DRAFT_COMPILED: &str = "DraftCompiled";
+pub const JUMP_HOP_STAGE_PUBLISHED: &str = "Published";
+pub const JUMP_HOP_PUBLICATION_DRAFT: &str = "Draft";
+pub const JUMP_HOP_PUBLICATION_PUBLISHED: &str = "Published";
+pub const JUMP_HOP_GENERATION_DRAFT: &str = "draft";
+pub const JUMP_HOP_GENERATION_READY: &str = "ready";
+pub const JUMP_HOP_EVENT_RUN_STARTED: &str = "run-started";
+pub const JUMP_HOP_EVENT_RUN_RESTARTED: &str = "run-restarted";
+pub const JUMP_HOP_EVENT_JUMP: &str = "jump";
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopAgentSessionCreateInput {
+    pub session_id: String,
+    pub owner_user_id: String,
+    pub seed_text: String,
+    pub work_title: String,
+    pub work_description: String,
+    pub theme_tags_json: Option<String>,
+    pub welcome_message_text: String,
+    pub config_json: Option<String>,
+    pub created_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopAgentSessionGetInput {
+    pub session_id: String,
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopDraftCompileInput {
+    pub session_id: String,
+    pub owner_user_id: String,
+    pub profile_id: String,
+    pub author_display_name: String,
+    pub seed_text: String,
+    pub work_title: String,
+    pub work_description: String,
+    pub theme_tags_json: Option<String>,
+    pub theme_text: Option<String>,
+    pub difficulty: Option<String>,
+    pub style_preset: Option<String>,
+    pub character_prompt: Option<String>,
+    pub tile_prompt: Option<String>,
+    pub end_mood_prompt: Option<String>,
+    pub character_asset_json: Option<String>,
+    pub tile_atlas_asset_json: Option<String>,
+    pub tile_assets_json: Option<String>,
+    pub cover_composite: Option<String>,
+    pub generation_status: Option<String>,
+    pub compiled_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopWorkUpdateInput {
+    pub profile_id: String,
+    pub owner_user_id: String,
+    pub work_title: String,
+    pub work_description: String,
+    pub theme_tags_json: String,
+    pub difficulty: Option<String>,
+    pub style_preset: Option<String>,
+    pub cover_image_src: Option<String>,
+    pub cover_composite: Option<String>,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopWorkPublishInput {
+    pub profile_id: String,
+    pub owner_user_id: String,
+    pub published_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopWorksListInput {
+    pub owner_user_id: String,
+    pub published_only: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopWorkGetInput {
+    pub profile_id: String,
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopRunStartInput {
+    pub run_id: String,
+    pub owner_user_id: String,
+    pub profile_id: String,
+    pub client_event_id: String,
+    pub started_at_ms: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopRunGetInput {
+    pub run_id: String,
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopRunJumpInput {
+    pub run_id: String,
+    pub owner_user_id: String,
+    pub charge_ms: u32,
+    pub client_event_id: String,
+    pub jumped_at_ms: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopRunRestartInput {
+    pub source_run_id: String,
+    pub next_run_id: String,
+    pub owner_user_id: String,
+    pub client_action_id: String,
+    pub restarted_at_ms: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct JumpHopAgentSessionProcedureResult {
+    pub ok: bool,
+    pub session: Option<JumpHopAgentSessionSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct JumpHopWorkProcedureResult {
+    pub ok: bool,
+    pub work: Option<JumpHopWorkSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct JumpHopWorksProcedureResult {
+    pub ok: bool,
+    pub items: Vec<JumpHopWorkSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct JumpHopRunProcedureResult {
+    pub ok: bool,
+    pub run: Option<module_jump_hop::JumpHopRunSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, SpacetimeType)]
+#[serde(rename_all = "camelCase")]
+pub struct JumpHopCreatorConfigSnapshot {
+    pub theme_text: String,
+    pub difficulty: String,
+    pub style_preset: String,
+    pub character_prompt: String,
+    pub tile_prompt: String,
+    #[serde(default)]
+    pub end_mood_prompt: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, SpacetimeType)]
+#[serde(rename_all = "camelCase")]
+pub struct JumpHopCharacterAssetSnapshot {
+    pub asset_id: String,
+    pub image_src: String,
+    pub image_object_key: String,
+    pub asset_object_id: String,
+    pub generation_provider: String,
+    pub prompt: String,
+    pub width: u32,
+    pub height: u32,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, SpacetimeType)]
+#[serde(rename_all = "camelCase")]
+pub struct JumpHopTileAssetSnapshot {
+    pub tile_type: String,
+    pub image_src: String,
+    pub image_object_key: String,
+    pub asset_object_id: String,
+    pub source_atlas_cell: String,
+    pub visual_width: u32,
+    pub visual_height: u32,
+    pub top_surface_radius: f32,
+    pub landing_radius: f32,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, SpacetimeType)]
+#[serde(rename_all = "camelCase")]
+pub struct JumpHopDraftSnapshot {
+    pub template_id: String,
+    pub template_name: String,
+    pub profile_id: Option<String>,
+    pub work_title: String,
+    pub work_description: String,
+    pub theme_tags: Vec<String>,
+    pub difficulty: String,
+    pub style_preset: String,
+    pub character_prompt: String,
+    pub tile_prompt: String,
+    pub end_mood_prompt: Option<String>,
+    pub character_asset: Option<JumpHopCharacterAssetSnapshot>,
+    pub tile_atlas_asset: Option<JumpHopCharacterAssetSnapshot>,
+    pub tile_assets: Vec<JumpHopTileAssetSnapshot>,
+    pub path: Option<module_jump_hop::JumpHopPath>,
+    pub cover_composite: Option<String>,
+    pub generation_status: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, SpacetimeType)]
+#[serde(rename_all = "camelCase")]
+pub struct JumpHopAgentSessionSnapshot {
+    pub session_id: String,
+    pub owner_user_id: String,
+    pub seed_text: String,
+    pub current_turn: u32,
+    pub progress_percent: u32,
+    pub stage: String,
+    pub config: JumpHopCreatorConfigSnapshot,
+    pub draft: Option<JumpHopDraftSnapshot>,
+    pub last_assistant_reply: String,
+    pub published_profile_id: Option<String>,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, SpacetimeType)]
+#[serde(rename_all = "camelCase")]
+pub struct JumpHopWorkSnapshot {
+    pub work_id: String,
+    pub profile_id: String,
+    pub owner_user_id: String,
+    pub source_session_id: String,
+    pub author_display_name: String,
+    pub work_title: String,
+    pub work_description: String,
+    pub theme_tags: Vec<String>,
+    pub difficulty: String,
+    pub style_preset: String,
+    pub character_prompt: String,
+    pub tile_prompt: String,
+    pub end_mood_prompt: Option<String>,
+    pub character_asset: Option<JumpHopCharacterAssetSnapshot>,
+    pub tile_atlas_asset: Option<JumpHopCharacterAssetSnapshot>,
+    pub tile_assets: Vec<JumpHopTileAssetSnapshot>,
+    pub path: module_jump_hop::JumpHopPath,
+    pub cover_image_src: String,
+    pub cover_composite: Option<String>,
+    pub publication_status: String,
+    pub publish_ready: bool,
+    pub play_count: u32,
+    pub generation_status: String,
+    pub updated_at_micros: i64,
+    pub published_at_micros: Option<i64>,
+}

server-rs/crates/spacetime-module/src/lib.rs

@@ -8,6 +8,7 @@ pub use module_big_fish::*;
 pub use module_combat::*;
 pub use module_custom_world::*;
 pub use module_inventory::*;
+pub use module_jump_hop::*;
 pub use module_npc::*;
 pub use module_progression::*;
 pub use module_quest::*;
@@ -29,6 +30,7 @@ mod custom_world;
 mod domain_types;
 mod entry;
 mod gameplay;
+mod jump_hop;
 mod match3d;
 mod migration;
 mod puzzle;
@@ -45,6 +47,7 @@ pub use custom_world::*;
 pub use domain_types::*;
 pub use entry::*;
 pub use gameplay::*;
+pub use jump_hop::*;
 pub use match3d::*;
 pub use migration::*;
 pub use runtime::*;

server-rs/crates/spacetime-module/src/migration.rs

@@ -12,6 +12,9 @@ use crate::bark_battle::tables::{
     bark_battle_work_stats_projection,
 };
 use crate::big_fish::big_fish_runtime_run;
+use crate::jump_hop::tables::{
+    jump_hop_agent_session, jump_hop_event, jump_hop_runtime_run, jump_hop_work_profile,
+};
 use crate::match3d::tables::{
     match3d_agent_message, match3d_agent_session, match3d_runtime_run, match3d_work_profile,
 };
@@ -234,6 +237,10 @@ macro_rules! migration_tables {
             match3d_agent_message,
             match3d_work_profile,
             match3d_runtime_run,
+            jump_hop_agent_session,
+            jump_hop_work_profile,
+            jump_hop_runtime_run,
+            jump_hop_event,
             square_hole_agent_session,
             square_hole_agent_message,
             square_hole_work_profile,