@kokimoki/app 2.1.0 → 3.0.0

package/docs/kokimoki-leaderboard.instructions.md

@@ -0,0 +1,189 @@
+---
+description: "Leaderboard and player rankings with Kokimoki SDK"
+applyTo: "**/*.ts,**/*.tsx"
+---
+
+# Leaderboard
+
+Kokimoki SDK provides a leaderboard system to track and display player rankings. No setup required.
+
+For core SDK concepts, see [Kokimoki SDK](./kokimoki-sdk.instructions.md).
+
+Access leaderboard API via `kmClient.leaderboard`.
+
+## When to Use Leaderboard API vs Global Store
+
+**Use the Leaderboard API when:**
+
+- You have a large number of entries (hundreds to thousands of players)
+- You need efficient ranking and sorting with database indexes
+- You want pagination and optimized queries for top scores
+- Memory and network efficiency are important
+
+**Use a Global Store when:**
+
+- You have a small number of players (typically under 100)
+- You need real-time updates and live leaderboard changes
+- You want to combine player scores with other game state
+- The leaderboard is temporary (session-based or reset frequently)
+
+The leaderboard API is optimized for scalability with database indexes and efficient queries, making it the better choice for games with many players. Global stores are ideal for smaller, real-time collaborative scenarios where you want immediate synchronization.
+
+## API Methods
+
+### leaderboard.insertEntry<MetadataT, PrivateMetadataT>(leaderboardName, sortDir, score, metadata, privateMetadata): Promise<{ rank: number }>
+
+Add a new entry to a leaderboard. Creates a new entry each time it's called.
+
+**Parameters:**
+
+- **leaderboardName**: `string` Name of the leaderboard
+- **sortDir**: `"asc" | "desc"` Sort direction (asc = lowest is best, desc = highest is best)
+- **score**: `number` The score value
+- **metadata**: `MetadataT` Public metadata visible to all players
+- **privateMetadata**: `PrivateMetadataT` Private metadata only accessible via API
+
+**Returns:** Promise resolving to an object with the entry's rank
+
+**Example:**
+
+```typescript
+const { rank } = await kmClient.leaderboard.insertEntry(
+  "high-scores",
+  "desc",
+  1500,
+  { playerName: "Alice", level: 10 },
+  { sessionId: "abc123" }
+);
+console.log(`New rank: ${rank}`);
+```
+
+### leaderboard.upsertEntry<MetadataT, PrivateMetadataT>(leaderboardName, sortDir, score, metadata, privateMetadata): Promise<{ rank: number }>
+
+Add or update the latest entry for the current client in a leaderboard. Replaces the previous entry if one exists.
+
+**Parameters:**
+
+- **leaderboardName**: `string` Name of the leaderboard
+- **sortDir**: `"asc" | "desc"` Sort direction (asc = lowest is best, desc = highest is best)
+- **score**: `number` The score value
+- **metadata**: `MetadataT` Public metadata visible to all players
+- **privateMetadata**: `PrivateMetadataT` Private metadata only accessible via API
+
+**Returns:** Promise resolving to an object with the entry's rank
+
+**Example:**
+
+```typescript
+const { rank } = await kmClient.leaderboard.upsertEntry(
+  "daily-scores",
+  "desc",
+  2000,
+  { playerName: "Bob", completionTime: 120 },
+  { deviceId: "xyz789" }
+);
+console.log(`Updated rank: ${rank}`);
+```
+
+### leaderboard.listEntries<MetadataT>(leaderboardName, sortDir, skip?, limit?): Promise<Paginated<{ rank: number; score: number; metadata: MetadataT }>>
+
+List entries in a leaderboard with pagination.
+
+**Parameters:**
+
+- **leaderboardName**: `string` Name of the leaderboard
+- **sortDir**: `"asc" | "desc"` Sort direction (asc = lowest is best, desc = highest is best)
+- **skip**: `number` Number of entries to skip for pagination (default: 0)
+- **limit**: `number` Maximum number of entries to return (default: 100)
+
+**Returns:** Promise resolving to a paginated list of entries
+
+**Example:**
+
+```typescript
+const { items, total } = await kmClient.leaderboard.listEntries(
+  "weekly-scores",
+  "desc",
+  0, // skip
+  10 // limit - get top 10
+);
+
+items.forEach((entry) => {
+  console.log(
+    `Rank ${entry.rank}: ${entry.metadata.playerName} - ${entry.score}`
+  );
+});
+```
+
+### leaderboard.getBestEntry<MetadataT>(leaderboardName, sortDir, clientId?): Promise<{ rank: number; score: number; metadata: MetadataT }>
+
+Get the best entry for a specific client in a leaderboard.
+
+**Parameters:**
+
+- **leaderboardName**: `string` Name of the leaderboard
+- **sortDir**: `"asc" | "desc"` Sort direction (asc = lowest is best, desc = highest is best)
+- **clientId**: `string` (optional) Client ID to get entry for. Defaults to current client if not provided.
+
+**Returns:** Promise resolving to the best entry for the client
+
+**Example:**
+
+```typescript
+// Get current client's best entry
+const myBest = await kmClient.leaderboard.getBestEntry("all-time-high", "desc");
+console.log(`My best: Rank ${myBest.rank}, Score ${myBest.score}`);
+
+// Get another player's best entry
+const otherBest = await kmClient.leaderboard.getBestEntry(
+  "all-time-high",
+  "desc",
+  "other-client-id"
+);
+```
+
+## Common Patterns
+
+### Example: Track High Scores
+
+```typescript
+// Submit a new high score
+await kmClient.leaderboard.upsertEntry(
+  "high-scores",
+  "desc",
+  score,
+  { playerName: player.name },
+  { timestamp: Date.now() }
+);
+
+// Display top 10
+const { items } = await kmClient.leaderboard.listEntries(
+  "high-scores",
+  "desc",
+  0,
+  10
+);
+```
+
+### Example: Track Speed Run Times
+
+```typescript
+// Submit completion time (lower is better)
+await kmClient.leaderboard.upsertEntry(
+  "speed-run",
+  "asc",
+  completionTimeInSeconds,
+  { playerName: player.name, difficulty: "hard" },
+  {}
+);
+
+// Get personal best
+const myBest = await kmClient.leaderboard.getBestEntry("speed-run", "asc");
+```
+
+## Key Points
+
+- **Sort Direction**: Use `asc` when lower scores are better (e.g., completion time), `desc` when higher scores are better (e.g., points)
+- **Insert vs Upsert**: Use `insertEntry` to keep all attempts, `upsertEntry` to keep only the latest/best
+- **Metadata**: Public metadata is visible to all, private metadata is only accessible via API calls
+- **Pagination**: Use skip/limit to implement leaderboard pages or "load more" functionality

package/docs/kokimoki-sdk.instructions.md

@@ -0,0 +1,221 @@
+---
+description: "Core Kokimoki SDK for real-time collaborative game applications"
+applyTo: "**/*.ts,**/*.tsx"
+---
+
+# Kokimoki SDK
+
+The Kokimoki SDK is a comprehensive development toolkit for building real-time collaborative game applications
+
+## General guidelines
+
+- **IMPORTANT** Use `getKmClient()` from `@kokimoki/app` to get the singleton client instance
+- Use `kmClient.id` as a unique identifier for each client (player)
+- Use `kmClient.store` for global stores and `kmClient.localStore` for local stores
+- Use dynamic stores with `kmClient.join()` and `kmClient.leave()` for room-based isolation (teams, chat rooms, breakout rooms)
+- Use `kmClient.transact` for atomic state updates across single store or multiple stores
+- Use `kmClient.storage.upload` and related API methods to handle file uploads (media, JSON, etc.) in application
+- Use `kmClient.serverTimestamp()` for time-related matters as this will be synced among players
+- Use `useSnapshot` hook from `valtio` to get reactive state inside React components
+- Use AI integration API methods: `kmClient.ai.generateText`, `kmClient.ai.generateJson`, and `kmClient.ai.generateImage` with corresponding poll methods for AI capabilities
+- Use i18n API methods: `kmClient.i18n.createI18n`, `kmClient.i18n.init`, and `kmClient.i18n.requestTranslation` for internationalization with AI-powered translations
+- Use leaderboard API methods: `kmClient.leaderboard.insertEntry`, `kmClient.leaderboard.upsertEntry`, `kmClient.leaderboard.listEntries`, and `kmClient.leaderboard.getBestEntry` to add leaderboard capabilities to application
+
+## Kokimoki Client
+
+- Use `getKmClient()` to get the singleton Kokimoki client instance
+- The `kmClient` provides the following key functionalities:
+  - `kmClient.store` and `kmClient.localStore` for creating stores
+  - `kmClient.join` and `kmClient.leave` for dynamic store lifecycle management
+  - `kmClient.transact` for atomic state updates
+  - `kmClient.serverTimestamp()` for synchronized timestamps
+  - `kmClient.id` for unique player identification
+
+**Example: Getting the Client**
+
+```typescript
+import { getKmClient } from "@kokimoki/app";
+
+const kmClient = getKmClient();
+```
+
+## Client ID
+
+- Each client (player) has a unique `kmClient.id` (aka `clientId`), stable identifier that represents a player across multiple connections
+  (client sessions)
+- The `kmClient.id` is persistent across client connections
+- The `kmClient.id` remains consistent after user reconnect or page reload
+- Use `kmClient.id` to identify players in global stores
+- Each client (player) can have multiple connections, but all connections share the same `kmClient.id`
+
+## Kokimoki Store
+
+Kokimoki Store powered by `valtio` and `valtio-yjs` for real-time state management in Kokimoki game applications
+
+### Store initialization
+
+- Stores should be defined in `src/state/stores/`
+- Store can be created in two ways:
+  - `kmClient.localStore` is used for data stored on the player device (local)
+  - `kmClient.store` is used for data shared among all players in a game (global)
+
+**Example: Creating a Store**
+
+```typescript
+import { getKmClient } from "@kokimoki/app";
+
+const kmClient = getKmClient();
+
+interface State {
+  title: string;
+  count: number;
+}
+
+const initialState: State = {
+  title: "Store",
+  count: 0,
+};
+
+// Initialize global store with initial state
+export const store = kmClient.store<State>("store-name", initialState);
+```
+
+### State management
+
+- State actions are functions that modify the store state by performing transactions
+- Actions should be defined in `/src/state/actions/`
+- Use async/await for all state transactions by `kmClient.transact` function for global stores
+- Transactions are atomic and ensure state consistency
+- ALWAYS update store state inside `kmClient.transact()` within action function
+- Prefer using records, not arrays: store collections as `Record<string, T>` with timestamp keys for automatic sorting and better sync performance
+
+**Example: Updating State**
+
+```typescript
+import { store } from "../store";
+
+// Update state
+await kmClient.transact([store], ([state]) => {
+  state.title = "New store";
+  state.count += 1;
+});
+```
+
+### Combining Stores
+
+- Multiple stores can be updated in a single transaction
+- Prefer to update stores in a single transaction to ensure state consistency
+
+**Example: Multiple Stores**
+
+```typescript
+// Update multiple stores in a single transaction
+await kmClient.transact([store1, store2], ([state1, state2]) => {
+  state1.name = "My Store1";
+  state2.name = "My Store2";
+});
+```
+
+### Reactive State in Components
+
+- Use `useSnapshot` hook from `valtio` to get reactive state inside React components
+- The component will re-render when the store state changes
+
+**Example: Using State in Components**
+
+```tsx
+import { useSnapshot } from "valtio";
+import { store } from "../store";
+
+const Component = () => {
+  // Get reactive snapshot of the store state
+  const { title, count } = useSnapshot(store.proxy);
+
+  return (
+    <div>
+      <h1>Title: {title}</h1>
+      <p>Count: {count}</p>
+    </div>
+  );
+};
+```
+
+## Dynamic Stores
+
+For room-based state isolation (teams, chat rooms, breakout rooms), see [Dynamic Stores](./kokimoki-dynamic-stores.instructions.md).
+
+## Server Time Synchronization
+
+Kokimoki SDK implements a time synchronization system to ensure consistent timestamps across all connected clients, regardless of their local clock differences
+
+- Use `kmClient.serverTimestamp()` to get the current server-synchronized timestamp
+- The timestamp is a Epoch Unix Timestamp
+- Use server timestamps for time-related matters like event scheduling, timeouts, timers, etc.
+
+## Store Connections
+
+Each Kokimoki store has a `connections` property that provides real-time presence information of all clients connected to that store.
+
+### Accessing Connections
+
+- Use `store.connections` to access the connections proxy for any Kokimoki store
+- Use `store.connections.clientIds` to get a `Set` of online client IDs
+- Use `useSnapshot` to get reactive updates when connections change
+- **ALWAYS** use `useSnapshot(store.connections)` to get reactive updates when connections change
+
+### Example: Track Online Players
+
+```tsx
+import { useSnapshot } from "valtio";
+import { globalStore } from "@/state/stores/global-store";
+
+const Component = () => {
+  // Get online client IDs from store connections
+  const onlineClientIds = useSnapshot(globalStore.connections).clientIds;
+
+  // Check if specific player is online
+  const isPlayerOnline = onlineClientIds.has(playerId);
+
+  // Get count of online players
+  const onlineCount = onlineClientIds.size;
+
+  return <div>Online players: {onlineCount}</div>;
+};
+```
+
+### Example: Display Player List with Online Status
+
+```tsx
+import { useSnapshot } from "valtio";
+import { globalStore } from "@/state/stores/global-store";
+
+const PlayerList = () => {
+  const players = useSnapshot(globalStore.proxy).players;
+  const onlineClientIds = useSnapshot(globalStore.connections).clientIds;
+
+  const playersList = Object.entries(players).map(([clientId, player]) => ({
+    clientId,
+    name: player.name,
+
+    isOnline: onlineClientIds.has(clientId),
+  }));
+
+  return (
+    <ul>
+      {playersList.map((player) => (
+        <li key={player.clientId}>
+          {player.name} - {player.isOnline ? "Online" : "Offline"}
+        </li>
+      ))}
+    </ul>
+  );
+};
+```
+
+### Key Points
+
+- Each store has its own `connections` property
+- `connections.clientIds` is a `Set<string>` containing connected client IDs
+- Use `useSnapshot(store.connections)` to get reactive updates
+- Players can have multiple browser tabs open, but all share the same `clientId`
+- A player is considered online if their `clientId` is in the `clientIds` set

package/docs/kokimoki-storage.instructions.md

@@ -0,0 +1,162 @@
+---
+description: "File storage and CDN uploads with Kokimoki SDK"
+applyTo: "**/*.ts,**/*.tsx"
+---
+
+# Storage
+
+Kokimoki SDK provides a storage service for uploading and managing files. Commonly used for media files (images, videos, audio), but also supports other file types like JSON or text files that aren't suitable for real-time stores. No setup required.
+
+For core SDK concepts, see [Kokimoki SDK](./kokimoki-sdk.instructions.md).
+
+Access storage API via `kmClient.storage`.
+
+## API Methods
+
+### storage.upload(name, blob, tags?): Promise<Upload>
+
+Uploads a file to storage.
+
+**Parameters:**
+
+- **name**: `string` filename
+- **blob**: `Blob` object to upload
+- **tags**: `string[]` (optional, default: [])
+
+**Example:**
+
+```typescript
+const upload: Upload = await kmClient.storage.upload("filename.jpg", fileBlob, [
+  "tag1",
+  "tag2",
+]);
+// Use upload.url to access the media file
+```
+
+### storage.listUploads(filter?, skip?, limit?): Promise<Paginated<Upload>>
+
+Query uploaded files by filter and pagination
+
+**Parameters:**
+
+- **filter.clientId**: `string` Specific client (optional)
+- **filter.mimeTypes**: `string[]` E.g., ['image/jpeg', 'image/png'] (optional)
+- **filter.tags**: `string[]` All tags must match (optional)
+- **skip**: `number` Pagination offset (default: 0)
+- **limit**: `number` Max results (default: 100)
+
+**Example:**
+
+```typescript
+// Query uploads by tag and uploaded by this client
+const { items, total } = await kmClient.storage.listUploads(
+  { clientId: kmClient.id, tags: ["tag1"] },
+  skip,
+  limit
+);
+```
+
+### storage.updateUpload(id, update): Promise<Upload>
+
+Replace uploaded file tags with new tags
+
+**Parameters:**
+
+- **id**: `string` Upload id
+- **update.tags**: `string[]` (optional)
+
+**Example:**
+
+```typescript
+const updatedUpload: Upload = await kmClient.storage.updateUpload(upload.id, {
+  tags: ["new"],
+});
+```
+
+### storage.deleteUpload(id): Promise<{ acknowledged: boolean; deletedCount: number }>
+
+Permanently delete uploaded file
+
+**Parameters:**
+
+- **id**: `string` Upload id
+
+**Example:**
+
+```typescript
+await kmClient.storage.deleteUpload(upload.id);
+```
+
+## Types
+
+```typescript
+interface Upload {
+  id: string; // unique id
+  url: string; // file url (CDN)
+  name: string; // original filename
+  size: number; // in bytes
+  mimeType: string;
+  clientId: string; // who uploaded
+  tags: string[]; // metadata for filtering and organization
+  completed: boolean; // upload status
+  createdAt: Date;
+  appId: string;
+}
+
+interface Paginated<T> {
+  items: T[];
+  total: number;
+}
+```
+
+## Common Patterns
+
+### Example: User-specific uploads
+
+```typescript
+// Get uploaded files by clientId
+const clientUploads = await kmClient.storage.listUploads({
+  clientId: kmClient.id,
+});
+```
+
+### Example: Filter by file type
+
+```typescript
+// Get only uploaded images
+const images = await kmClient.storage.listUploads({
+  mimeTypes: ["image/jpeg", "image/png"],
+});
+```
+
+### Example: Tag-based uploads
+
+```typescript
+// Upload file with tag
+await kmClient.storage.upload("avatar.jpg", blob, ["profile"]);
+
+// Query uploads by tag
+const profileUploads = await kmClient.storage.listUploads({
+  tags: ["profile"],
+});
+```
+
+### Example: Usage in Kokimoki Store
+
+```typescript
+// Upload image from Blob
+const upload = await kmClient.storage.upload("file.jpg", blob);
+
+await kmClient.transact([store], (state) => {
+  // Add image to images array in the store
+  state.playerImages[upload.id] = { url: upload.url };
+});
+```
+
+## Key Points
+
+- **Use Cases**: Commonly used for media files (images, videos, audio), but also supports JSON, text files, or any data not suitable for real-time stores
+- **CDN**: File `upload.url` is public and can be used directly
+- **Tags**: Use tag system to organize uploads
+- **Pagination**: Use skip/limit to paginate results
+- **Filtering**: Combine clientId, mimeTypes, and tags to query uploads

package/llms.txt

@@ -0,0 +1,43 @@
+# Kokimoki SDK Documentation
+
+> Documentation for @kokimoki/app - the core SDK for building real-time multiplayer games.
+
+## Instruction Files
+
+The following instruction files provide detailed guidance for AI assistants:
+
+### Core SDK
+- docs/kokimoki-sdk.instructions.md: Core SDK usage including client initialization, stores, transactions, server time synchronization, and store connections. Start here for basic Kokimoki development.
+
+### Dynamic Stores
+- docs/kokimoki-dynamic-stores.instructions.md: Room-based state isolation for teams, chat rooms, and breakout rooms. Includes the useDynamicStore hook pattern and lifecycle management.
+
+### Services
+
+- docs/kokimoki-ai.instructions.md: AI-powered text and image generation using generateText() and generateImage() APIs.
+
+- docs/kokimoki-storage.instructions.md: File storage and CDN uploads using the storage service.
+
+- docs/kokimoki-i18n.instructions.md: Internationalization with AI-powered translation support.
+
+- docs/kokimoki-leaderboard.instructions.md: Player rankings and score management.
+
+## Key Concepts
+
+- **KmClient**: Central client instance obtained via getKmClient()
+- **Stores**: Synchronized state containers using Valtio proxies
+- **Transactions**: Atomic state updates via kmClient.transact()
+- **Dynamic Stores**: Room-scoped stores with join/leave lifecycle
+- **Server Time**: Synchronized timestamps via kmClient.serverTimestamp()
+
+## File Patterns
+
+Instruction files use YAML frontmatter with:
+- `description`: Brief description of the file's purpose
+- `applyTo`: Glob pattern for when the instructions apply (e.g., "**/*.{ts,tsx}")
+
+## Recommended Reading Order
+
+1. docs/kokimoki-sdk.instructions.md (required - core concepts)
+2. docs/kokimoki-dynamic-stores.instructions.md (if using rooms/teams)
+3. Service-specific files as needed

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@kokimoki/app",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "type": "module",
   "description": "Kokimoki app",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "llms.txt"
   ],
   "ts-node": {
     "esm": true,
@@ -16,19 +18,12 @@
     "test": "NODE_OPTIONS='--import tsx' mocha",
     "prebuild": "node scripts/generate-version.js",
     "build": "tsc",
-    "postbuild": "rollup --config && cp docs/instructions.md dist/llms.txt",
     "dev": "tsc -w",
-    "docs": "typedoc src/index.ts",
-    "rollup": "rollup --config"
+    "docs": "typedoc src/index.ts"
   },
   "author": "Loquiz OÜ",
   "license": "Apache-2.0",
   "devDependencies": {
-    "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-replace": "^5.0.5",
-    "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^11.1.6",
     "@types/chai": "^4",
     "@types/mocha": "^10",
     "@types/node": "^18",
@@ -36,8 +31,6 @@
     "bson-objectid": "^2.0.4",
     "chai": "^4",
     "mocha": "^10",
-    "rollup": "^4.13.0",
-    "rollup-plugin-dts": "^6.1.0",
     "ts-node": "^10",
     "tsx": "^4",
     "typedoc": "^0.24.8",
@@ -47,9 +40,12 @@
     "derive-valtio": "^0.2.0",
     "events": "^3.3.0",
     "farmhash-modern": "^1.1.0",
+    "i18next": "^25.7.4",
+    "i18next-http-backend": "^3.0.2",
     "typed-emitter": "^2.1.0",
     "valtio": "^2.1.5",
     "valtio-yjs": "^0.6.0",
-    "yjs": "^13.6.27"
+    "yjs": "^13.6.27",
+    "zod": "^4.3.5"
   }
 }