@kokimoki/app 3.0.0 → 3.1.1

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

@@ -2,6 +2,33 @@ import type TypedEmitter from "typed-emitter";
 import { KokimokiAiService, KokimokiI18nService, KokimokiLeaderboardService, KokimokiStorageService } from "../services";
 import { KokimokiLocalStore, KokimokiStore } from "../stores";
 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];
 };
@@ -183,6 +210,7 @@ export declare class KokimokiClient<ClientContextT = any> extends KokimokiClient
     private _i18n?;
     private _storage?;
     private _leaderboard?;
+    private _metaStore?;
     /**
      * Dev mode config - set when running in dev frame with ?key= param
      */
@@ -203,6 +231,30 @@ export declare class KokimokiClient<ClientContextT = any> extends KokimokiClient
      * 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;

package/dist/core/kokimoki-client.js

@@ -7,6 +7,11 @@ 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
  *
@@ -183,6 +188,7 @@ export class KokimokiClient extends EventEmitter {
     _i18n;
     _storage;
     _leaderboard;
+    _metaStore;
     /**
      * Dev mode config - set when running in dev frame with ?key= param
      */
@@ -203,6 +209,35 @@ export class KokimokiClient extends EventEmitter {
      * 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._env = env;
@@ -443,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");

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,6 @@
 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, KokimokiEnv, Paginated, PollOptions, Upload, } from "./types";
 export type { AllLanguagesStatus, I18nOptions, LanguageStatus, NamespaceStatus, RequestTranslationResult, TranslationStatus, } from "./services/kokimoki-i18n";

package/dist/index.js

@@ -1,4 +1,5 @@
 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";

package/dist/services/kokimoki-i18n.d.ts

@@ -124,7 +124,7 @@ export declare class KokimokiI18nService {
      *
      * Must call `createI18n()` first to set up the instance.
      *
-     * @param lng - The language code to initialize with (e.g., 'en', 'de')
+     * @param lng - The language code to initialize with (e.g., 'en', 'de'). If not provided, reads from the HTML element's lang attribute.
      * @returns Promise that resolves when i18n is ready
      *
      * @example
@@ -132,11 +132,14 @@ export declare class KokimokiI18nService {
      * // Create instance first
      * const i18n = kmClient.i18n.createI18n({ use: [initReactI18next] });
      *
-     * // Then initialize when you know the language
+     * // Then initialize (reads lang from <html> element if not specified)
+     * await kmClient.i18n.init();
+     *
+     * // Or with explicit language
      * await kmClient.i18n.init('en');
      * ```
      */
-    init(lng: string): Promise<void>;
+    init(lng?: string): Promise<void>;
     /**
      * Get the URL for a translation namespace.
      *

package/dist/services/kokimoki-i18n.js

@@ -96,7 +96,7 @@ export class KokimokiI18nService {
      *
      * Must call `createI18n()` first to set up the instance.
      *
-     * @param lng - The language code to initialize with (e.g., 'en', 'de')
+     * @param lng - The language code to initialize with (e.g., 'en', 'de'). If not provided, reads from the HTML element's lang attribute.
      * @returns Promise that resolves when i18n is ready
      *
      * @example
@@ -104,7 +104,10 @@ export class KokimokiI18nService {
      * // Create instance first
      * const i18n = kmClient.i18n.createI18n({ use: [initReactI18next] });
      *
-     * // Then initialize when you know the language
+     * // Then initialize (reads lang from <html> element if not specified)
+     * await kmClient.i18n.init();
+     *
+     * // Or with explicit language
      * await kmClient.i18n.init('en');
      * ```
      */
@@ -115,20 +118,24 @@ export class KokimokiI18nService {
         if (this.initPromise) {
             return this.initPromise;
         }
+        // Default to HTML lang attribute if not provided
+        const language = lng ?? document.documentElement.lang ?? "en";
         const env = getKmEnv();
         const namespaces = env.i18nNamespaces ?? [];
-        const fallbackLng = this.options.fallbackLng ?? lng;
+        const fallbackLng = this.options.fallbackLng ?? language;
         const defaultNS = this.options.defaultNS;
         this.initPromise = this.instance.init({
-            lng,
+            lng: language,
             fallbackLng,
             ns: namespaces,
             defaultNS,
+            // Wait for backend to load translations before resolving
+            initImmediate: false,
             backend: {
                 // i18next-http-backend passes lng as array, extract first element
                 loadPath: (lngs, ns) => {
-                    const language = Array.isArray(lngs) ? lngs[0] : lngs;
-                    return this.getNamespaceUrl(language, ns);
+                    const lang = Array.isArray(lngs) ? lngs[0] : lngs;
+                    return this.getNamespaceUrl(lang, ns);
                 },
             },
             interpolation: {

package/dist/stores/kokimoki-store.d.ts

@@ -1,6 +1,15 @@
 import { Snapshot } from "valtio/vanilla";
 import * as Y from "yjs";
-import { type KokimokiClient, RoomSubscriptionMode } from "../core";
+import type { KokimokiClient } from "../core";
+/**
+ * Mode for room subscription - determines read/write permissions.
+ * Re-exported here to avoid circular dependency issues.
+ */
+export declare enum RoomSubscriptionMode {
+    Read = "r",
+    Write = "w",
+    ReadWrite = "b"
+}
 export declare class KokimokiStore<T extends object> {
     readonly roomName: string;
     readonly defaultValue: T;

package/dist/stores/kokimoki-store.js

@@ -1,7 +1,16 @@
 import { bind as yjsBind } from "valtio-yjs";
 import { proxy, snapshot, subscribe } from "valtio/vanilla";
 import * as Y from "yjs";
-import { RoomSubscriptionMode } from "../core";
+/**
+ * Mode for room subscription - determines read/write permissions.
+ * Re-exported here to avoid circular dependency issues.
+ */
+export var RoomSubscriptionMode;
+(function (RoomSubscriptionMode) {
+    RoomSubscriptionMode["Read"] = "r";
+    RoomSubscriptionMode["Write"] = "w";
+    RoomSubscriptionMode["ReadWrite"] = "b";
+})(RoomSubscriptionMode || (RoomSubscriptionMode = {}));
 export class KokimokiStore {
     roomName;
     defaultValue;

package/dist/types/env.d.ts

@@ -33,4 +33,14 @@ export interface KokimokiEnv {
     i18nPath?: string;
     /** Build URL for dev mode (S3 URL where AI translations are stored) */
     buildUrl?: string;
+    /** Default app meta values from kokimoki.config.ts */
+    defaultAppMeta?: {
+        lang?: string;
+        title?: string;
+        description?: string;
+        ogTitle?: string;
+        ogDescription?: string;
+        ogImage?: string;
+        favicon?: string;
+    };
 }

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

@@ -5,6 +5,10 @@ import { KokimokiClient } from "../core";
  * Creates and caches a single KokimokiClient instance for the application.
  * This is the recommended way to access the client throughout your app.
  *
+ * The client includes a built-in `metaStore` for managing HTML meta tags.
+ * If `defaultAppMeta` is configured in kokimoki.config.ts, it will be used
+ * as the initial state for the metaStore when the client connects.
+ *
  * @typeParam T - The client context type for storing custom data per client
  * @returns The singleton KokimokiClient instance
  *
@@ -22,9 +26,9 @@ import { KokimokiClient } from "../core";
  * // Create stores
  * const gameStore = kmClient.store<GameState>('game', initialState);
  *
- * // Use in components or actions
- * await kmClient.transact([gameStore], ([game]) => {
- *   game.score += 10;
+ * // Access the built-in meta store
+ * await kmClient.transact([kmClient.metaStore], ([meta]) => {
+ *   meta.title = 'My Game';
  * });
  * ```
  */

package/dist/utils/kokimoki-client.js

@@ -6,6 +6,10 @@ let _kmClient;
  * Creates and caches a single KokimokiClient instance for the application.
  * This is the recommended way to access the client throughout your app.
  *
+ * The client includes a built-in `metaStore` for managing HTML meta tags.
+ * If `defaultAppMeta` is configured in kokimoki.config.ts, it will be used
+ * as the initial state for the metaStore when the client connects.
+ *
  * @typeParam T - The client context type for storing custom data per client
  * @returns The singleton KokimokiClient instance
  *
@@ -23,9 +27,9 @@ let _kmClient;
  * // Create stores
  * const gameStore = kmClient.store<GameState>('game', initialState);
  *
- * // Use in components or actions
- * await kmClient.transact([gameStore], ([game]) => {
- *   game.score += 10;
+ * // Access the built-in meta store
+ * await kmClient.transact([kmClient.metaStore], ([meta]) => {
+ *   meta.title = 'My Game';
  * });
  * ```
  */

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const KOKIMOKI_APP_VERSION = "3.0.0";
+export declare const KOKIMOKI_APP_VERSION = "3.1.1";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Auto-generated file. Do not edit manually.
-export const KOKIMOKI_APP_VERSION = '3.0.0';
+export const KOKIMOKI_APP_VERSION = '3.1.1';

package/docs/kokimoki-sdk.instructions.md

@@ -219,3 +219,42 @@ const PlayerList = () => {
 - 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
+
+## App Meta Store
+
+The SDK provides a built-in `metaStore` on the client for managing HTML meta tags. The server uses this store to inject meta tags (title, description, Open Graph, favicon) into the HTML response for proper SEO and social sharing previews.
+
+### Reserved Store Names
+
+Store names with the `__km/` prefix are reserved for SDK internal use. Do not create stores with this prefix.
+
+### Using App Meta
+
+```tsx
+import { getKmClient } from "@kokimoki/app";
+import { useSnapshot } from "valtio";
+
+const kmClient = getKmClient();
+
+// Read meta state anywhere
+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";
+  meta.ogImage = "https://example.com/og-image.png";
+});
+```
+
+### App Meta Fields
+
+| Field           | Description                                        |
+| --------------- | -------------------------------------------------- |
+| `lang`          | HTML lang attribute (e.g., 'en', 'et', 'de')       |
+| `title`         | Document title (browser tab)                       |
+| `description`   | Meta description                                   |
+| `ogTitle`       | Open Graph title (defaults to `title` if not set)  |
+| `ogDescription` | Open Graph description (defaults to `description`) |
+| `ogImage`       | Open Graph image URL                               |
+| `favicon`       | Favicon URL                                        |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokimoki/app",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "type": "module",
   "description": "Kokimoki app",
   "main": "dist/index.js",