@kokimoki/app 2.1.1 → 3.1.0

package/README.md

@@ -0,0 +1,72 @@
+# @kokimoki/app
+
+The core SDK for building real-time multiplayer games with Kokimoki.
+
+## Installation
+
+```bash
+npm install @kokimoki/app
+```
+
+## Quick Start
+
+```typescript
+import { getKmClient } from "@kokimoki/app";
+
+const kmClient = getKmClient();
+
+// Create a synchronized store
+const gameStore = kmClient.store("game", {
+  players: {},
+  status: "waiting",
+});
+
+// Update state with transactions
+await kmClient.transact([gameStore], ([state]) => {
+  state.players[kmClient.id] = { name: "Player 1", score: 0 };
+});
+```
+
+## Features
+
+- **Real-time State Sync** - Synchronized stores across all connected clients
+- **Dynamic Stores** - Room-based state isolation for teams, chat, breakout rooms
+- **AI Services** - Text and image generation
+- **Storage** - File uploads to CDN
+- **i18n** - Internationalization with AI-powered translation
+- **Leaderboards** - Player rankings and scores
+
+## Documentation
+
+See the [docs](./docs/) folder for detailed instructions:
+
+| File                                                                                      | Description                                   |
+| ----------------------------------------------------------------------------------------- | --------------------------------------------- |
+| [kokimoki-sdk.instructions.md](./docs/kokimoki-sdk.instructions.md)                       | Core SDK usage (client, stores, transactions) |
+| [kokimoki-dynamic-stores.instructions.md](./docs/kokimoki-dynamic-stores.instructions.md) | Room-based state isolation                    |
+| [kokimoki-ai.instructions.md](./docs/kokimoki-ai.instructions.md)                         | AI text and image generation                  |
+| [kokimoki-storage.instructions.md](./docs/kokimoki-storage.instructions.md)               | File storage and CDN uploads                  |
+| [kokimoki-i18n.instructions.md](./docs/kokimoki-i18n.instructions.md)                     | Internationalization                          |
+| [kokimoki-leaderboard.instructions.md](./docs/kokimoki-leaderboard.instructions.md)       | Player rankings                               |
+
+## Usage with React
+
+```tsx
+import { useSnapshot } from "valtio";
+import { getKmClient } from "@kokimoki/app";
+
+const kmClient = getKmClient();
+const gameStore = kmClient.store("game", { count: 0 });
+
+function Counter() {
+  const { count } = useSnapshot(gameStore.proxy);
+
+  const increment = () => {
+    kmClient.transact([gameStore], ([state]) => {
+      state.count++;
+    });
+  };
+
+  return <button onClick={increment}>Count: {count}</button>;
+}
+```

package/dist/core/kokimoki-client.d.ts

@@ -1,14 +1,39 @@
 import type TypedEmitter from "typed-emitter";
-import { KokimokiAiService, KokimokiLeaderboardService, KokimokiStorageService } from "../services";
+import { KokimokiAiService, KokimokiI18nService, KokimokiLeaderboardService, KokimokiStorageService } from "../services";
 import { KokimokiLocalStore, KokimokiStore } from "../stores";
-import type { KokimokiClientEvents } from "../types";
+import type { KokimokiClientEvents, KokimokiEnv } from "../types";
+/**
+ * Reserved store name for the App Meta store.
+ * Stores with the `__km/` prefix are reserved for SDK internal use.
+ */
+export declare const APP_META_STORE_NAME = "__km/app-meta";
+/**
+ * State type for the App Meta store.
+ * Used by the server to inject meta tags into the HTML response.
+ *
+ * All fields are optional - missing fields will fall back to defaults in index.html.
+ */
+export interface AppMetaState {
+    /** HTML lang attribute (e.g., 'en', 'et', 'de') */
+    lang?: string;
+    /** Document title (browser tab) */
+    title?: string;
+    /** Meta description */
+    description?: string;
+    /** Open Graph title (defaults to title if not set) */
+    ogTitle?: string;
+    /** Open Graph description (defaults to description if not set) */
+    ogDescription?: string;
+    /** Open Graph image URL */
+    ogImage?: string;
+    /** Favicon URL */
+    favicon?: string;
+}
 type Mutable<T> = {
     -readonly [K in keyof T]: T[K] extends object ? Mutable<T[K]> : T[K];
 };
 type StoreValue<S> = S extends KokimokiStore<infer U> ? Mutable<U> : never;
-declare const KokimokiClient_base: {
-    new (): TypedEmitter<KokimokiClientEvents>;
-};
+declare const KokimokiClient_base: new () => TypedEmitter<KokimokiClientEvents>;
 /**
  * Kokimoki Client - Real-time Collaborative Game Development SDK
  *
@@ -30,12 +55,8 @@ declare const KokimokiClient_base: {
  * ```typescript
  * import { KokimokiClient } from '@kokimoki/app';
  *
- * // Initialize the client
- * const kmClient = new KokimokiClient(
- *   'your-host.kokimoki.com',
- *   'your-app-id',
- *   'optional-access-code'
- * );
+ * // Initialize the client (uses environment config from @kokimoki/kit)
+ * const kmClient = new KokimokiClient();
  *
  * // Connect to the server
  * await kmClient.connect();
@@ -163,9 +184,6 @@ declare const KokimokiClient_base: {
  * ```
  */
 export declare class KokimokiClient<ClientContextT = any> extends KokimokiClient_base {
-    readonly host: string;
-    readonly appId: string;
-    readonly code: string;
     private _wsUrl;
     private _apiUrl;
     private _id?;
@@ -189,9 +207,55 @@ export declare class KokimokiClient<ClientContextT = any> extends KokimokiClient
     private _clientTokenKey;
     private _editorContext;
     private _ai?;
+    private _i18n?;
     private _storage?;
     private _leaderboard?;
-    constructor(host: string, appId: string, code?: string);
+    private _metaStore?;
+    /**
+     * Dev mode config - set when running in dev frame with ?key= param
+     */
+    private _devModeConfig?;
+    /**
+     * Environment configuration
+     */
+    private _env;
+    /**
+     * The WebSocket server host.
+     */
+    readonly host: string;
+    /**
+     * The application identifier.
+     */
+    readonly appId: string;
+    /**
+     * The deploy code slug.
+     */
+    readonly code: string;
+    /**
+     * Built-in App Meta store for managing HTML meta tags.
+     *
+     * This store is automatically joined when the client connects.
+     * The server uses this store to inject meta tags into the HTML response
+     * for proper SEO and social sharing previews.
+     *
+     * @example
+     * ```typescript
+     * import { useSnapshot } from 'valtio';
+     *
+     * const kmClient = getKmClient();
+     *
+     * // Read meta state
+     * const { title, description } = useSnapshot(kmClient.metaStore.proxy);
+     *
+     * // Update meta via transaction
+     * await kmClient.transact([kmClient.metaStore], ([meta]) => {
+     *   meta.title = 'My Game';
+     *   meta.description = 'An awesome multiplayer game';
+     * });
+     * ```
+     */
+    get metaStore(): KokimokiStore<AppMetaState>;
+    constructor(env?: KokimokiEnv);
     get id(): string;
     get connectionId(): string;
     get token(): string;
@@ -207,6 +271,32 @@ export declare class KokimokiClient<ClientContextT = any> extends KokimokiClient
      * Indicates whether the client is running in editor/development mode.
      */
     get isEditor(): boolean;
+    /**
+     * Generates a link for joining the app via URL or QR code.
+     *
+     * In dev mode, the link includes the code and context as URL parameters
+     * for local testing. In production, it generates a clean path-based URL.
+     *
+     * @param code - The join code (e.g., playerCode or presenterCode from clientContext)
+     * @param context - The client context to embed in the link (used in dev mode only)
+     * @returns The generated URL string
+     *
+     * @example
+     * ```typescript
+     * // Generate a player join link
+     * const playerLink = kmClient.generateLink(
+     *   kmClient.clientContext.playerCode,
+     *   { mode: 'player' }
+     * );
+     *
+     * // Generate a presenter link with player code
+     * const presenterLink = kmClient.generateLink(
+     *   kmClient.clientContext.presenterCode,
+     *   { mode: 'presenter', playerCode: kmClient.clientContext.playerCode }
+     * );
+     * ```
+     */
+    generateLink(code: string, context: object): string;
     /**
      * Establishes a connection to the Kokimoki server.
      *
@@ -288,6 +378,24 @@ export declare class KokimokiClient<ClientContextT = any> extends KokimokiClient
      * Disables automatic reconnection, closes the WebSocket, and clears all intervals.
      */
     close(): Promise<void>;
+    /**
+     * Waits for all subscriptions to be fully joined and notifies the loading screen.
+     *
+     * This should be called before rendering the app. It will:
+     * 1. Wait for all stores to complete initial synchronization
+     * 2. Post a 'km:ready' message to trigger loading screen fade
+     * 3. Post a 'km:ready' message to the parent window (for dev frame coordination)
+     *
+     * @param timeout - Maximum time to wait for subscriptions in milliseconds (default: 5000ms).
+     * @returns A promise that resolves when ready to render.
+     *
+     * @example
+     * ```ts
+     * await kmClient.waitForReady();
+     * renderApp(<App />);
+     * ```
+     */
+    waitForReady(timeout?: number): Promise<void>;
     /**
      * Gets the internal room hash identifier for a store.
      *
@@ -349,6 +457,10 @@ export declare class KokimokiClient<ClientContextT = any> extends KokimokiClient
      * Access AI capabilities including text generation, structured JSON output, and image modification.
      */
     get ai(): KokimokiAiService;
+    /**
+     * Access i18n URL resolution and translation loading utilities.
+     */
+    get i18n(): KokimokiI18nService;
     /**
      * Access file upload and management for media files, images, and user-generated content.
      */

package/dist/core/kokimoki-client.js

@@ -1,10 +1,17 @@
 import EventEmitter from "events";
 import * as Y from "yjs";
 import { WsMessageReader, WsMessageType, WsMessageWriter, } from "../protocol/ws-message";
-import { KokimokiAiService, KokimokiLeaderboardService, KokimokiStorageService, } from "../services";
+import { KokimokiAiService, KokimokiI18nService, KokimokiLeaderboardService, KokimokiStorageService, } from "../services";
 import { KokimokiLocalStore, KokimokiStore, KokimokiTransaction, } from "../stores";
+import { initDevMode } from "../utils/kokimoki-dev";
+import { getKmEnv } from "../utils/kokimoki-env";
 import { KOKIMOKI_APP_VERSION } from "../version";
 import { RoomSubscription } from "./room-subscription";
+/**
+ * Reserved store name for the App Meta store.
+ * Stores with the `__km/` prefix are reserved for SDK internal use.
+ */
+export const APP_META_STORE_NAME = "__km/app-meta";
 /**
  * Kokimoki Client - Real-time Collaborative Game Development SDK
  *
@@ -26,12 +33,8 @@ import { RoomSubscription } from "./room-subscription";
  * ```typescript
  * import { KokimokiClient } from '@kokimoki/app';
  *
- * // Initialize the client
- * const kmClient = new KokimokiClient(
- *   'your-host.kokimoki.com',
- *   'your-app-id',
- *   'optional-access-code'
- * );
+ * // Initialize the client (uses environment config from @kokimoki/kit)
+ * const kmClient = new KokimokiClient();
  *
  * // Connect to the server
  * await kmClient.connect();
@@ -159,9 +162,6 @@ import { RoomSubscription } from "./room-subscription";
  * ```
  */
 export class KokimokiClient extends EventEmitter {
-    host;
-    appId;
-    code;
     _wsUrl;
     _apiUrl;
     _id;
@@ -185,19 +185,79 @@ export class KokimokiClient extends EventEmitter {
     _clientTokenKey = "KM_TOKEN";
     _editorContext;
     _ai;
+    _i18n;
     _storage;
     _leaderboard;
-    constructor(host, appId, code = "") {
+    _metaStore;
+    /**
+     * Dev mode config - set when running in dev frame with ?key= param
+     */
+    _devModeConfig;
+    /**
+     * Environment configuration
+     */
+    _env;
+    /**
+     * The WebSocket server host.
+     */
+    host;
+    /**
+     * The application identifier.
+     */
+    appId;
+    /**
+     * The deploy code slug.
+     */
+    code;
+    /**
+     * Built-in App Meta store for managing HTML meta tags.
+     *
+     * This store is automatically joined when the client connects.
+     * The server uses this store to inject meta tags into the HTML response
+     * for proper SEO and social sharing previews.
+     *
+     * @example
+     * ```typescript
+     * import { useSnapshot } from 'valtio';
+     *
+     * const kmClient = getKmClient();
+     *
+     * // Read meta state
+     * const { title, description } = useSnapshot(kmClient.metaStore.proxy);
+     *
+     * // Update meta via transaction
+     * await kmClient.transact([kmClient.metaStore], ([meta]) => {
+     *   meta.title = 'My Game';
+     *   meta.description = 'An awesome multiplayer game';
+     * });
+     * ```
+     */
+    get metaStore() {
+        if (!this._metaStore) {
+            throw new Error("Client not connected");
+        }
+        return this._metaStore;
+    }
+    constructor(env = getKmEnv()) {
         super();
-        this.host = host;
-        this.appId = appId;
-        this.code = code;
+        this._env = env;
+        this.host = env.host;
+        this.appId = env.appId;
+        this.code = env.code ?? "";
+        // Initialize dev mode from URL params if running in dev environment
+        if (env.dev) {
+            this._devModeConfig = initDevMode();
+            if (this._devModeConfig) {
+                this._clientTokenKey = this._devModeConfig.tokenKey;
+            }
+        }
         // Set up the URLs
         const secure = this.host.indexOf(":") === -1;
         this._wsUrl = `ws${secure ? "s" : ""}://${this.host}`;
         this._apiUrl = `http${secure ? "s" : ""}://${this.host}`;
         // Initialize modules
         this._ai = new KokimokiAiService(this);
+        this._i18n = new KokimokiI18nService(this);
         this._storage = new KokimokiStorageService(this);
         this._leaderboard = new KokimokiLeaderboardService(this);
         // Set up ping interval
@@ -278,6 +338,37 @@ export class KokimokiClient extends EventEmitter {
     get isEditor() {
         return !!this._editorContext;
     }
+    /**
+     * Generates a link for joining the app via URL or QR code.
+     *
+     * In dev mode, the link includes the code and context as URL parameters
+     * for local testing. In production, it generates a clean path-based URL.
+     *
+     * @param code - The join code (e.g., playerCode or presenterCode from clientContext)
+     * @param context - The client context to embed in the link (used in dev mode only)
+     * @returns The generated URL string
+     *
+     * @example
+     * ```typescript
+     * // Generate a player join link
+     * const playerLink = kmClient.generateLink(
+     *   kmClient.clientContext.playerCode,
+     *   { mode: 'player' }
+     * );
+     *
+     * // Generate a presenter link with player code
+     * const presenterLink = kmClient.generateLink(
+     *   kmClient.clientContext.presenterCode,
+     *   { mode: 'presenter', playerCode: kmClient.clientContext.playerCode }
+     * );
+     * ```
+     */
+    generateLink(code, context) {
+        if (this._env.dev) {
+            return `${window.location.origin}?key=${code}&context=${btoa(JSON.stringify(context))}`;
+        }
+        return `${window.location.origin}/${code}`;
+    }
     /**
      * Establishes a connection to the Kokimoki server.
      *
@@ -291,14 +382,11 @@ export class KokimokiClient extends EventEmitter {
         if (this._connectPromise) {
             return await this._connectPromise;
         }
-        // Detect devtools
-        if (window.parent && window.self !== window.parent) {
+        // Detect devtools (editor)
+        if (!this._devModeConfig &&
+            window.parent &&
+            window.self !== window.parent) {
             await new Promise((resolve) => {
-                /* // Wait up to 500ms for parent to respond
-                const timeout = setTimeout(() => {
-                  window.removeEventListener("message", onMessage);
-                  resolve();
-                }, 500); */
                 // Listen for parent response
                 const onMessage = (e) => {
                     // clearTimeout(timeout);
@@ -390,6 +478,8 @@ export class KokimokiClient extends EventEmitter {
                 console.error(`[Kokimoki] Failed to restore subscription for "${subscription.roomName}":`, err);
             }
         }
+        // Auto-join the built-in meta store with defaults from config
+        this._metaStore = this.store(APP_META_STORE_NAME, this._env.defaultAppMeta ?? {});
         // Emit connected event
         this._reconnectTimeout = 0;
         this.emit("connected");
@@ -399,7 +489,20 @@ export class KokimokiClient extends EventEmitter {
         this._id = message.clientId;
         this._connectionId = message.id;
         this._token = message.appToken;
-        this._clientContext = message.clientContext;
+        // Context priority: dev mode URL params > test mode env > server context
+        if (this._devModeConfig?.context !== undefined) {
+            this._clientContext = this._devModeConfig.context;
+        }
+        else if (this._env.test && this._env.clientContext) {
+            this._clientContext = JSON.parse(this._env.clientContext);
+        }
+        else {
+            this._clientContext = message.clientContext;
+        }
+        // Notify parent window in test mode (editor)
+        if (this._env.test) {
+            setTimeout(() => window.postMessage({ clientKey: "test" }, "*"));
+        }
         // Set up the auth headers
         this._apiHeaders = new Headers({
             Authorization: `Bearer ${this.token}`,
@@ -707,6 +810,46 @@ export class KokimokiClient extends EventEmitter {
             clearInterval(this._pingInterval);
         }
     }
+    /**
+     * Waits for all subscriptions to be fully joined and notifies the loading screen.
+     *
+     * This should be called before rendering the app. It will:
+     * 1. Wait for all stores to complete initial synchronization
+     * 2. Post a 'km:ready' message to trigger loading screen fade
+     * 3. Post a 'km:ready' message to the parent window (for dev frame coordination)
+     *
+     * @param timeout - Maximum time to wait for subscriptions in milliseconds (default: 5000ms).
+     * @returns A promise that resolves when ready to render.
+     *
+     * @example
+     * ```ts
+     * await kmClient.waitForReady();
+     * renderApp(<App />);
+     * ```
+     */
+    async waitForReady(timeout = 5000) {
+        const checkInterval = 10;
+        const maxChecks = Math.ceil(timeout / checkInterval);
+        await new Promise((resolve) => {
+            let checks = 0;
+            const intervalId = setInterval(() => {
+                let allJoined = true;
+                for (const subscription of this._subscriptionsByName.values()) {
+                    if (!subscription.joined) {
+                        allJoined = false;
+                        break;
+                    }
+                }
+                if (allJoined || ++checks >= maxChecks) {
+                    clearInterval(intervalId);
+                    resolve();
+                }
+            }, checkInterval);
+        });
+        // Post to both parent (for dev frame) and self (for loading screen)
+        window.parent.postMessage("km:ready", "*");
+        window.postMessage("km:ready", "*");
+    }
     /**
      * Gets the internal room hash identifier for a store.
      *
@@ -798,6 +941,15 @@ export class KokimokiClient extends EventEmitter {
         }
         return this._ai;
     }
+    /**
+     * Access i18n URL resolution and translation loading utilities.
+     */
+    get i18n() {
+        if (!this._i18n) {
+            throw new Error("I18n client not initialized");
+        }
+        return this._i18n;
+    }
     /**
      * Access file upload and management for media files, images, and user-generated content.
      */

package/dist/core/room-subscription-mode.d.ts

@@ -1,5 +1 @@
-export declare enum RoomSubscriptionMode {
-    Read = "r",
-    Write = "w",
-    ReadWrite = "b"
-}
+export { RoomSubscriptionMode } from "../stores/kokimoki-store";

package/dist/core/room-subscription-mode.js

@@ -1,6 +1,3 @@
-export var RoomSubscriptionMode;
-(function (RoomSubscriptionMode) {
-    RoomSubscriptionMode["Read"] = "r";
-    RoomSubscriptionMode["Write"] = "w";
-    RoomSubscriptionMode["ReadWrite"] = "b";
-})(RoomSubscriptionMode || (RoomSubscriptionMode = {}));
+// Re-export from stores to maintain backwards compatibility
+// The enum is defined in kokimoki-store.ts to avoid circular dependencies
+export { RoomSubscriptionMode } from "../stores/kokimoki-store";

package/dist/index.d.ts

@@ -1,4 +1,11 @@
 export { KokimokiClient } from "./core";
+export { APP_META_STORE_NAME } from "./core/kokimoki-client";
+export type { AppMetaState } from "./core/kokimoki-client";
 export { KokimokiStore } from "./stores";
-export type { KokimokiClientEvents, Paginated, Upload } from "./types";
+export type { KokimokiClientEvents, KokimokiEnv, Paginated, PollOptions, Upload, } from "./types";
+export type { AllLanguagesStatus, I18nOptions, LanguageStatus, NamespaceStatus, RequestTranslationResult, TranslationStatus, } from "./services/kokimoki-i18n";
+export type { AiJob, AiJobStatus, AiJobType } from "./services/kokimoki-ai";
+export { getKmClient } from "./utils/kokimoki-client";
+export { getKmEnv } from "./utils/kokimoki-env";
 export * from "./utils/valtio";
+export { z, type ZodType } from "zod/v4";

package/dist/index.js

@@ -1,4 +1,9 @@
 export { KokimokiClient } from "./core";
+export { APP_META_STORE_NAME } from "./core/kokimoki-client";
 export { KokimokiStore } from "./stores";
+export { getKmClient } from "./utils/kokimoki-client";
+export { getKmEnv } from "./utils/kokimoki-env";
 // Re-export Valtio utilities
 export * from "./utils/valtio";
+// Re-export Zod for schema definitions
+export { z } from "zod/v4";