@kokimoki/app 2.1.0 → 3.0.0

package/docs/kokimoki-dynamic-stores.instructions.md

@@ -0,0 +1,439 @@
+---
+description: "Dynamic stores for room-based state management with Kokimoki SDK"
+applyTo: "**/*.ts,**/*.tsx"
+---
+
+# Dynamic Stores
+
+Dynamic stores enable creation of isolated, room-based state management. This is useful for scenarios where subsets of players need to share state without affecting the global store.
+
+For core SDK concepts, see [Kokimoki SDK](./kokimoki-sdk.instructions.md).
+
+## When to Use Dynamic Stores
+
+**Use for:**
+
+- **Room-based isolation**: Chat rooms, team spaces, breakout rooms
+- **Player grouping**: Teams, squads, parties that share private state
+- **Multi-instance features**: Multiple parallel games or activities
+- **Scoped collaboration**: Players working together on specific tasks
+
+**Do NOT use for:**
+
+- Global game state (use `kmClient.store()` instead)
+- Player-specific data (use `kmClient.localStore()` instead)
+- Single shared space for all players
+
+## General Best Practices
+
+- **Unique room names**: Use descriptive prefixes (e.g., `"chat-room-"`, `"team-"`)
+- **Key remounting**: Use `key={roomCode}` on components to force remount when switching rooms
+- **Check isConnected**: Wait for connection before showing/updating content
+- **Defensive state checks**: Always verify properties exist before accessing (e.g., `if (!state.players)` before using)
+- **UseEffect guards**: Check for undefined/null in useEffect conditions that depend on dynamic store state
+- **Cleanup on leave**: Remove player-specific data when leaving a room
+- **Use actions**: Never inline `kmClient.transact` calls in components
+- **Use Records, not Arrays**: Store collections as `Record<string, T>` with timestamp keys for automatic sorting and better sync performance
+- **Atomic transactions**: Combine related state updates in single transaction when possible
+
+## Creating a useDynamicStore Hook
+
+Since dynamic stores require lifecycle management (join/leave), create a custom hook that wraps the store lifecycle:
+
+**Hook implementation** (`src/hooks/useDynamicStore.ts`):
+
+```typescript
+import { useState, useEffect, useRef } from "react";
+import { getKmClient, KokimokiStore } from "@kokimoki/app";
+
+const kmClient = getKmClient();
+
+// Global store cache for reference counting
+const storeCache = new Map<
+  string,
+  { store: KokimokiStore<any>; refCount: number }
+>();
+
+export function useDynamicStore<T extends object>(
+  roomName: string,
+  initialState: T
+) {
+  const [isConnecting, setIsConnecting] = useState(true);
+  const [isConnected, setIsConnected] = useState(false);
+  const storeRef = useRef<KokimokiStore<T> | null>(null);
+
+  // Get or create the store
+  if (!storeRef.current) {
+    const cached = storeCache.get(roomName);
+    if (cached) {
+      storeRef.current = cached.store;
+      cached.refCount++;
+    } else {
+      const store = kmClient.store<T>(roomName, initialState);
+      storeRef.current = store;
+      storeCache.set(roomName, { store, refCount: 1 });
+    }
+  }
+
+  useEffect(() => {
+    const store = storeRef.current!;
+    let mounted = true;
+
+    const joinStore = async () => {
+      try {
+        await kmClient.join(store);
+        if (mounted) {
+          setIsConnected(true);
+          setIsConnecting(false);
+        }
+      } catch (error) {
+        console.error(`Failed to join store "${roomName}":`, error);
+        if (mounted) {
+          setIsConnecting(false);
+        }
+      }
+    };
+
+    joinStore();
+
+    return () => {
+      mounted = false;
+      const cached = storeCache.get(roomName);
+      if (cached) {
+        cached.refCount--;
+        if (cached.refCount <= 0) {
+          kmClient.leave(store);
+          storeCache.delete(roomName);
+        }
+      }
+    };
+  }, [roomName]);
+
+  return {
+    store: storeRef.current!,
+    isConnected,
+    isConnecting,
+  };
+}
+```
+
+## Hook API
+
+**Parameters:**
+
+- **roomName**: `string` - Unique identifier for the store (e.g., `"chat-room-abc123"`)
+- **initialState**: `T` - Default state structure with initial values
+
+**Return Values:**
+
+- **store**: `KokimokiStore<T>` - The Kokimoki store instance
+- **isConnected**: `boolean` - Whether successfully joined the store
+- **isConnecting**: `boolean` - Whether currently joining the store
+
+## Basic Usage
+
+```tsx
+import { useSnapshot } from "valtio";
+import { useDynamicStore } from "@/hooks/useDynamicStore";
+
+interface RoomState {
+  messages: Record<string, string>; // key: timestamp, value: message
+  count: number;
+}
+
+const initialState: RoomState = {
+  messages: {},
+  count: 0,
+};
+
+const MyComponent = ({ roomCode }: { roomCode: string }) => {
+  const { store, isConnected } = useDynamicStore<RoomState>(
+    `my-room-${roomCode}`,
+    initialState
+  );
+
+  const roomState = useSnapshot(store.proxy);
+
+  // Update state
+  const addMessage = async (message: string) => {
+    await kmClient.transact([store], ([state]) => {
+      const timestamp = kmClient.serverTimestamp().toString();
+      state.messages[timestamp] = message;
+    });
+  };
+
+  if (!isConnected) {
+    return <div>Connecting...</div>;
+  }
+
+  return <div>Messages: {Object.keys(roomState.messages).length}</div>;
+};
+
+// Use key to remount component on roomCode change
+<MyComponent key={roomCode} roomCode={roomCode} />;
+```
+
+## Common Patterns
+
+### Example: Team-based State
+
+Players can be grouped into teams with private team state:
+
+```tsx
+interface TeamState {
+  teamName: string;
+  players: Record<string, { name: string; role: string }>;
+  score: number;
+  strategy: string;
+}
+
+const TeamView = ({ teamId }: { teamId: string }) => {
+  const { name } = useSnapshot(playerStore.proxy);
+  const { store: teamStore, isConnected } = useDynamicStore<TeamState>(
+    `team-${teamId}`,
+    {
+      teamName: `Team ${teamId}`,
+      players: {},
+      score: 0,
+      strategy: "",
+    }
+  );
+
+  const teamState = useSnapshot(teamStore.proxy);
+
+  // Join team on connect
+  useEffect(() => {
+    if (isConnected) {
+      kmClient.transact([teamStore], ([state]) => {
+        state.players[kmClient.id] = { name, role: "member" };
+      });
+    }
+  }, [isConnected]);
+
+  // Update team strategy
+  const updateStrategy = async (strategy: string) => {
+    await kmClient.transact([teamStore], ([state]) => {
+      state.strategy = strategy;
+    });
+  };
+
+  return (
+    <div>
+      <h2>{teamState.teamName}</h2>
+      <p>Score: {teamState.score}</p>
+      <p>Players: {Object.keys(teamState.players || {}).length}</p>
+    </div>
+  );
+};
+```
+
+### Example: Chat Rooms
+
+Multiple independent chat rooms:
+
+```tsx
+interface ChatMessage {
+  clientId: string;
+  playerName: string;
+  text: string;
+  timestamp: number;
+}
+
+interface ChatState {
+  messages: Record<string, ChatMessage>; // key: timestamp as string
+}
+
+const ChatRoom = ({ roomCode }: { roomCode: string }) => {
+  const { store, isConnected } = useDynamicStore<ChatState>(
+    `chat-${roomCode}`,
+    { messages: {} }
+  );
+
+  const { messages } = useSnapshot(store.proxy);
+
+  const sendMessage = async (playerName: string, text: string) => {
+    await kmClient.transact([store], ([state]) => {
+      const timestamp = kmClient.serverTimestamp();
+      state.messages[timestamp.toString()] = {
+        clientId: kmClient.id,
+        playerName,
+        text,
+        timestamp,
+      };
+    });
+  };
+
+  // Get sorted messages
+  const sortedMessages = Object.entries(messages || {})
+    .sort(([a], [b]) => Number(a) - Number(b))
+    .map(([, msg]) => msg);
+
+  return <div>{sortedMessages.length} messages</div>;
+};
+```
+
+### Example: Breakout Rooms
+
+Small group discussions or activities:
+
+```tsx
+interface BreakoutRoomState {
+  topic: string;
+  participants: Record<string, { joinedAt: number }>; // key: clientId
+  responses: Record<string, string>; // key: clientId
+  completed: boolean;
+}
+
+const BreakoutRoom = ({ roomId }: { roomId: string }) => {
+  const { store, isConnected } = useDynamicStore<BreakoutRoomState>(
+    `breakout-${roomId}`,
+    {
+      topic: "",
+      participants: {},
+      responses: {},
+      completed: false,
+    }
+  );
+
+  const roomState = useSnapshot(store.proxy);
+
+  // Join room on connect
+  useEffect(() => {
+    if (isConnected) {
+      kmClient.transact([store], ([state]) => {
+        if (!state.participants[kmClient.id]) {
+          state.participants[kmClient.id] = {
+            joinedAt: kmClient.serverTimestamp(),
+          };
+        }
+      });
+    }
+  }, [isConnected]);
+
+  const submitResponse = async (response: string) => {
+    await kmClient.transact([store], ([state]) => {
+      state.responses[kmClient.id] = response;
+    });
+  };
+
+  return (
+    <div>
+      <h3>{roomState.topic}</h3>
+      <p>Participants: {Object.keys(roomState.participants || {}).length}</p>
+    </div>
+  );
+};
+```
+
+## Key Behaviors
+
+**Store Lifecycle:**
+
+- Stores are **created on first use** and **cached** globally
+- Multiple components using the same `roomName` share the same store instance
+- Reference counting ensures cleanup only when all components unmount
+
+**State Synchronization:**
+
+- State syncs in real-time across all clients joined to the same room
+- Use transactions to update state atomically
+- **CRITICAL**: Always check if state properties exist before accessing them (e.g., `if (state.players)` before `Object.keys(state.players)`)
+- Initial state may be `undefined` during connection/sync - add defensive checks
+
+**Connection Management:**
+
+- Component automatically joins the store on mount
+- Component automatically leaves the store on unmount
+- `isConnected` indicates successful join
+- `isConnecting` indicates join in progress
+- **Store state may not be fully initialized immediately after `isConnected` becomes true**
+
+## File Organization
+
+**ALWAYS** organize dynamic store code using the standard store/actions pattern:
+
+**State definition** (`src/state/chat-store.ts`):
+
+```typescript
+// Export message interface
+export interface ChatMessage {
+  clientId: string;
+  playerName: string;
+  message: string;
+  timestamp: number;
+}
+
+// Export state interface
+export interface ChatState {
+  messages: Record<string, ChatMessage>; // key: timestamp as string
+}
+
+// Export function to generate initial state
+export function createChatState(): ChatState {
+  return {
+    messages: {},
+  };
+}
+```
+
+**Actions** (`src/state/actions/chat-actions.ts`):
+
+```typescript
+import type { KokimokiStore } from "@kokimoki/app";
+import { getKmClient } from "@kokimoki/app";
+import type { ChatState, ChatMessage } from "../chat-store";
+
+const kmClient = getKmClient();
+
+export const chatActions = {
+  async sendMessage(
+    store: KokimokiStore<ChatState>,
+    playerName: string,
+    message: string
+  ) {
+    await kmClient.transact([store], ([state]) => {
+      const timestamp = kmClient.serverTimestamp();
+      const newMessage: ChatMessage = {
+        clientId: kmClient.id,
+        playerName,
+        message,
+        timestamp,
+      };
+      state.messages[timestamp.toString()] = newMessage;
+    });
+  },
+};
+```
+
+**Usage in component** (`src/views/chat-view.tsx`):
+
+```tsx
+import { useSnapshot } from "valtio";
+import { useDynamicStore } from "@/hooks/useDynamicStore";
+import { createChatState, type ChatState } from "@/state/chat-store";
+import { chatActions } from "@/state/actions/chat-actions";
+
+const ChatRoom = ({ roomCode }: { roomCode: string }) => {
+  const { store, isConnected } = useDynamicStore<ChatState>(
+    `chat-${roomCode}`,
+    createChatState()
+  );
+
+  const { messages } = useSnapshot(store.proxy);
+
+  // Get sorted messages
+  const sortedMessages = Object.entries(messages || {})
+    .sort(([a], [b]) => Number(a) - Number(b))
+    .map(([, msg]) => msg);
+
+  const handleSend = async (message: string) => {
+    await chatActions.sendMessage(store, playerName, message);
+  };
+
+  if (!isConnected) {
+    return <div>Connecting...</div>;
+  }
+
+  return <div>{sortedMessages.length} messages</div>;
+};
+```

package/docs/kokimoki-i18n.instructions.md

@@ -0,0 +1,285 @@
+---
+description: "Internationalization with AI-powered translations in Kokimoki SDK"
+applyTo: "**/*.ts,**/*.tsx"
+---
+
+# Internationalization (i18n)
+
+Kokimoki SDK provides built-in internationalization support powered by i18next with AI-powered translation capabilities. No manual translation files needed for additional languages.
+
+For core SDK concepts, see [Kokimoki SDK](./kokimoki-sdk.instructions.md).
+
+Access i18n API via `kmClient.i18n`.
+
+## Key Features
+
+- Pre-configured i18next instance creation
+- Consistent HTTP-based loading in dev and production
+- AI-powered translation requests with polling support
+- Automatic namespace management
+
+## Setup
+
+```typescript
+// src/i18n.ts
+import { initReactI18next } from "react-i18next";
+import { getKmClient } from "@kokimoki/app";
+
+const kmClient = getKmClient();
+
+// Create i18next instance with React integration
+export const i18n = kmClient.i18n.createI18n({
+  use: [initReactI18next],
+  fallbackLng: "en",
+  defaultNS: "game",
+});
+
+// Initialize with primary language
+await kmClient.i18n.init("en");
+```
+
+## API Methods
+
+### i18n.createI18n(options?): i18n
+
+Create and configure an i18next instance. Call `init()` to initialize with a specific language.
+
+**Parameters:**
+
+- **options.use**: `Plugin[]` Array of i18next plugins (e.g., `initReactI18next`)
+- **options.fallbackLng**: `string` Fallback language code (default: same as `lng` passed to init)
+- **options.defaultNS**: `string` Default namespace (default: first namespace in config)
+
+**Example:**
+
+```typescript
+import { initReactI18next } from "react-i18next";
+
+export const i18n = kmClient.i18n.createI18n({
+  use: [initReactI18next],
+  fallbackLng: "en",
+});
+```
+
+### i18n.init(lng): Promise<void>
+
+Initialize the i18next instance with a specific language. Must call `createI18n()` first.
+
+**Parameters:**
+
+- **lng**: `string` Language code to initialize with (e.g., 'en', 'de')
+
+**Example:**
+
+```typescript
+await kmClient.i18n.init("en");
+```
+
+### i18n.getNamespaces(): string[]
+
+Get the list of available namespaces configured in @kokimoki/kit.
+
+```typescript
+const namespaces = kmClient.i18n.getNamespaces();
+// ['game', 'ui', 'common']
+```
+
+### i18n.getLanguages(): string[]
+
+Get the list of available languages configured in @kokimoki/kit.
+
+```typescript
+const languages = kmClient.i18n.getLanguages();
+// ['en', 'et']
+```
+
+### i18n.getNamespaceUrl(lng, ns): string
+
+Get the URL for a translation namespace file.
+
+**Parameters:**
+
+- **lng**: `string` Language code
+- **ns**: `string` Namespace name
+
+```typescript
+const url = kmClient.i18n.getNamespaceUrl("en", "game");
+// Dev: "/__kokimoki/i18n/en/game.json"
+// Prod: "https://cdn.kokimoki.com/build-123/km-i18n/en/game.json"
+```
+
+## AI Translation API
+
+### i18n.getAllLanguagesStatus(): Promise<AllLanguagesStatus>
+
+Get the status of all languages that have been requested for AI translation.
+
+```typescript
+interface AllLanguagesStatus {
+  languages: { lng: string; status: LanguageStatus }[];
+}
+
+type LanguageStatus = "available" | "processing" | "failed" | "partial";
+```
+
+**Example:**
+
+```typescript
+const { languages } = await kmClient.i18n.getAllLanguagesStatus();
+// [{ lng: 'de', status: 'available' }, { lng: 'fr', status: 'processing' }]
+```
+
+### i18n.getTranslationStatus(lng): Promise<TranslationStatus>
+
+Get the translation status for a specific language.
+
+```typescript
+interface TranslationStatus {
+  status: "available" | "processing" | "not_available";
+  namespaces: Record<string, NamespaceStatus>;
+}
+
+type NamespaceStatus = "available" | "processing" | "failed" | "not_available";
+```
+
+**Example:**
+
+```typescript
+const status = await kmClient.i18n.getTranslationStatus("de");
+
+if (status.status === "available") {
+  i18next.changeLanguage("de");
+} else if (status.status === "processing") {
+  // Show loading indicator
+} else {
+  // Request translation
+  await kmClient.i18n.requestTranslation("de");
+}
+```
+
+### i18n.requestTranslation(lng): Promise<RequestTranslationResult>
+
+Request AI translation for a target language. Triggers background AI translation jobs for all namespaces.
+
+```typescript
+interface RequestTranslationResult {
+  lng: string;
+  status: "started" | "already_processing" | "already_available";
+}
+```
+
+**Example:**
+
+```typescript
+const result = await kmClient.i18n.requestTranslation("de");
+
+if (result.status === "already_available") {
+  // Already translated, switch immediately
+  i18next.changeLanguage("de");
+} else {
+  // Poll until ready
+  await kmClient.i18n.pollTranslation("de");
+  i18next.changeLanguage("de");
+}
+```
+
+### i18n.pollTranslation(lng, options?): Promise<void>
+
+Poll a translation request until all namespaces are available.
+
+**Parameters:**
+
+- **lng**: `string` Language code to poll for
+- **options.pollInterval**: `number` Polling interval in ms (default: 2000, min: 1000)
+- **options.timeout**: `number` Timeout in ms (default: 120000)
+- **options.onProgress**: `(status: TranslationStatus) => void` Progress callback
+
+**Example:**
+
+```typescript
+await kmClient.i18n.pollTranslation("de", {
+  timeout: 60000,
+  onProgress: (status) => {
+    console.log("Overall:", status.status);
+    console.log("Namespaces:", status.namespaces);
+  },
+});
+
+// Now safe to switch
+i18next.changeLanguage("de");
+```
+
+## Common Patterns
+
+### Example: Language Switcher with AI Translation
+
+```tsx
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import { getKmClient } from "@kokimoki/app";
+
+const kmClient = getKmClient();
+
+const LanguageSwitcher = () => {
+  const { i18n } = useTranslation();
+  const [loading, setLoading] = useState(false);
+
+  const switchLanguage = async (lng: string) => {
+    // Check if translation is available
+    const status = await kmClient.i18n.getTranslationStatus(lng);
+
+    if (status.status === "available") {
+      i18n.changeLanguage(lng);
+      return;
+    }
+
+    // Request and wait for AI translation
+    setLoading(true);
+    await kmClient.i18n.requestTranslation(lng);
+    await kmClient.i18n.pollTranslation(lng, {
+      onProgress: (s) => console.log(`Translating: ${s.status}`),
+    });
+    setLoading(false);
+
+    i18n.changeLanguage(lng);
+  };
+
+  return (
+    <select
+      value={i18n.language}
+      onChange={(e) => switchLanguage(e.target.value)}
+      disabled={loading}
+    >
+      <option value="en">English</option>
+      <option value="de">Deutsch</option>
+      <option value="fr">Français</option>
+    </select>
+  );
+};
+```
+
+### Example: Using Translations in Components
+
+```tsx
+import { useTranslation } from "react-i18next";
+
+const GameUI = () => {
+  const { t } = useTranslation("game");
+
+  return (
+    <div>
+      <h1>{t("title")}</h1>
+      <button>{t("startButton")}</button>
+      <p>{t("score", { points: 100 })}</p>
+    </div>
+  );
+};
+```
+
+## Key Points
+
+- **Setup**: Call `createI18n()` first, then `init()` with the primary language
+- **React Integration**: Pass `initReactI18next` to `use` option for React hooks support
+- **AI Translation**: Request translations for any language, AI translates from your primary language
+- **Polling**: Use `pollTranslation()` to wait for AI translation to complete
+- **Namespaces**: Translations are organized by namespaces configured in @kokimoki/kit