@kokimoki/app 2.1.0 → 3.0.0

package/dist/services/kokimoki-i18n.js

@@ -0,0 +1,325 @@
+import i18next from "i18next";
+import HttpBackend from "i18next-http-backend";
+import { getKmEnv } from "../utils/kokimoki-env";
+/**
+ * Kokimoki i18n Service
+ *
+ * Provides translation loading via HTTP backend. Both development and production
+ * use HTTP to load translations consistently.
+ *
+ * In development, translations are served by @kokimoki/kit's dev server middleware.
+ * In production, translations are served from the assets CDN.
+ *
+ * **Key Features:**
+ * - Pre-configured i18next instance creation
+ * - Consistent HTTP-based loading in dev and prod
+ * - URL resolution for translation namespaces
+ * - AI-powered translation requests with polling support
+ *
+ * Access via `kmClient.i18n`
+ *
+ * @example
+ * ```typescript
+ * // Setup with React
+ * import { initReactI18next } from 'react-i18next';
+ *
+ * export const i18n = kmClient.i18n.createI18n({
+ *   use: [initReactI18next]
+ * });
+ *
+ * // Initialize with primary language
+ * await kmClient.i18n.init('en');
+ *
+ * // Request AI translation and wait for it
+ * await kmClient.i18n.requestTranslation('de');
+ * await kmClient.i18n.pollTranslation('de', {
+ *   onProgress: (status) => console.log('Translation status:', status.status)
+ * });
+ *
+ * // Now safe to switch language
+ * i18next.changeLanguage('de');
+ * ```
+ */
+export class KokimokiI18nService {
+    client;
+    initPromise = null;
+    instance = null;
+    options = {};
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Create and configure an i18next instance.
+     *
+     * This sets up the instance with plugins but does NOT initialize it.
+     * Call `init(lng)` to initialize with a specific language.
+     *
+     * @param options - Configuration options (plugins, fallback, defaultNS)
+     * @returns Configured i18next instance (not yet initialized)
+     *
+     * @example
+     * ```typescript
+     * // With React
+     * import { initReactI18next } from 'react-i18next';
+     *
+     * export const i18n = kmClient.i18n.createI18n({
+     *   use: [initReactI18next]
+     * });
+     *
+     * // Later, when you know the language:
+     * await kmClient.i18n.init('en');
+     *
+     * // Then in components:
+     * const { t } = useTranslation('game');
+     * ```
+     */
+    createI18n(options) {
+        const env = getKmEnv();
+        const namespaces = env.i18nNamespaces ?? [];
+        if (namespaces.length === 0) {
+            console.warn("[KokimokiI18n] No i18n namespaces found. Make sure i18n is configured in @kokimoki/kit plugin.");
+        }
+        this.options = options ?? {};
+        this.instance = i18next.createInstance();
+        // Apply plugins
+        if (options?.use) {
+            for (const plugin of options.use) {
+                this.instance.use(plugin);
+            }
+        }
+        // Add HTTP backend
+        this.instance.use(HttpBackend);
+        return this.instance;
+    }
+    /**
+     * Initialize the i18next instance with a specific language.
+     *
+     * Must call `createI18n()` first to set up the instance.
+     *
+     * @param lng - The language code to initialize with (e.g., 'en', 'de')
+     * @returns Promise that resolves when i18n is ready
+     *
+     * @example
+     * ```typescript
+     * // Create instance first
+     * const i18n = kmClient.i18n.createI18n({ use: [initReactI18next] });
+     *
+     * // Then initialize when you know the language
+     * await kmClient.i18n.init('en');
+     * ```
+     */
+    async init(lng) {
+        if (!this.instance) {
+            throw new Error("Call createI18n() before init()");
+        }
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        const env = getKmEnv();
+        const namespaces = env.i18nNamespaces ?? [];
+        const fallbackLng = this.options.fallbackLng ?? lng;
+        const defaultNS = this.options.defaultNS;
+        this.initPromise = this.instance.init({
+            lng,
+            fallbackLng,
+            ns: namespaces,
+            defaultNS,
+            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);
+                },
+            },
+            interpolation: {
+                escapeValue: false,
+            },
+        });
+        return this.initPromise;
+    }
+    /**
+     * Get the URL for a translation namespace.
+     *
+     * Returns the appropriate URL based on environment and language source:
+     * - Development (local language): `/__kokimoki/i18n/{lng}/{ns}.json`
+     * - Development (AI-translated): `{buildUrl}km-i18n/{lng}/{ns}.json`
+     * - Production: `{assets}/km-i18n/{lng}/{ns}.json`
+     *
+     * @param lng - Language code (e.g., 'en', 'et', 'de')
+     * @param ns - Namespace (e.g., 'ui', 'game', 'setup')
+     * @returns Full URL to the translation JSON file
+     *
+     * @example
+     * ```typescript
+     * const url = kmClient.i18n.getNamespaceUrl('en', 'game');
+     * // Dev (local): "/__kokimoki/i18n/en/game.json"
+     * // Dev (AI): "https://builds.kokimoki.com/build-123/km-i18n/de/game.json"
+     * // Prod: "https://cdn.kokimoki.com/build-123/km-i18n/en/game.json"
+     * ```
+     */
+    getNamespaceUrl(lng, ns) {
+        const env = getKmEnv();
+        if (env.dev) {
+            // Check if this is a local language (served by kit middleware)
+            const localLanguages = env.i18nLanguages ?? [];
+            if (localLanguages.includes(lng)) {
+                return `/__kokimoki/i18n/${lng}/${ns}.json`;
+            }
+            // AI-translated language: use buildUrl (S3)
+            if (env.buildUrl) {
+                return `${env.buildUrl}km-i18n/${lng}/${ns}.json`;
+            }
+            // Fallback to local path (will 404 but better than crashing)
+            return `/__kokimoki/i18n/${lng}/${ns}.json`;
+        }
+        // Production: use assets CDN with configured i18n path
+        const i18nPath = env.i18nPath ?? "km-i18n";
+        return `${env.assets}/${i18nPath}/${lng}/${ns}.json`;
+    }
+    /**
+     * Get the list of available namespaces.
+     *
+     * @returns Array of namespace names configured in @kokimoki/kit
+     */
+    getNamespaces() {
+        return getKmEnv().i18nNamespaces ?? [];
+    }
+    /**
+     * Get the list of available languages.
+     *
+     * @returns Array of language codes configured in @kokimoki/kit
+     */
+    getLanguages() {
+        return getKmEnv().i18nLanguages ?? [];
+    }
+    /**
+     * Get the status of all languages that have been requested for AI translation.
+     *
+     * @returns Promise with array of language statuses
+     *
+     * @example
+     * ```typescript
+     * const { languages } = await kmClient.i18n.getAllLanguagesStatus();
+     * // [{ lng: 'de', status: 'available' }, { lng: 'fr', status: 'processing' }]
+     * ```
+     */
+    async getAllLanguagesStatus() {
+        const res = await fetch(`${this.client.apiUrl}/i18n`, {
+            method: "GET",
+            headers: this.client.apiHeaders,
+        });
+        return await res.json();
+    }
+    /**
+     * Get the translation status for a specific language.
+     *
+     * Returns the overall status and per-namespace status for the given language.
+     *
+     * @param lng - Target language code (e.g., 'de', 'fr', 'es')
+     * @returns Promise with translation status
+     *
+     * @example
+     * ```typescript
+     * const status = await kmClient.i18n.getTranslationStatus('de');
+     * if (status.status === 'available') {
+     *   // All translations ready, can switch language
+     *   i18next.changeLanguage('de');
+     * } else if (status.status === 'processing') {
+     *   // Show loading indicator
+     * } else {
+     *   // Request translation
+     *   await kmClient.i18n.requestTranslation('de');
+     * }
+     * ```
+     */
+    async getTranslationStatus(lng) {
+        const res = await fetch(`${this.client.apiUrl}/i18n/${encodeURIComponent(lng)}/status`, {
+            method: "GET",
+            headers: this.client.apiHeaders,
+        });
+        return await res.json();
+    }
+    /**
+     * Request AI translation for a target language.
+     *
+     * Triggers background AI translation jobs for all namespaces that are not yet available.
+     * Uses the build's configured primary language as the source.
+     *
+     * @param lng - Target language code (e.g., 'de', 'fr', 'es')
+     * @returns Promise with the result of the request
+     *
+     * @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', {
+     *     onProgress: (status) => console.log('Status:', status.status)
+     *   });
+     *   i18next.changeLanguage('de');
+     * }
+     * ```
+     */
+    async requestTranslation(lng) {
+        const res = await fetch(`${this.client.apiUrl}/i18n/${encodeURIComponent(lng)}/translate`, {
+            method: "POST",
+            headers: this.client.apiHeaders,
+        });
+        const data = await res.json();
+        return { lng, ...data };
+    }
+    /**
+     * Poll a translation request until all namespaces are available.
+     *
+     * @param lng - The language code to poll for.
+     * @param options - Polling options (interval, timeout, progress callback).
+     * @returns Promise that resolves when all namespaces are available.
+     * @throws If the translation fails or times out.
+     *
+     * @example
+     * ```typescript
+     * // Request and poll with progress
+     * await kmClient.i18n.requestTranslation('de');
+     * 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');
+     * ```
+     */
+    async pollTranslation(lng, options) {
+        const pollInterval = Math.max(1000, options?.pollInterval ?? 2000);
+        const timeout = options?.timeout ?? 120000;
+        const startTime = Date.now();
+        while (true) {
+            const status = await this.getTranslationStatus(lng);
+            // Call progress callback
+            options?.onProgress?.(status);
+            if (status.status === "available") {
+                return;
+            }
+            // Check for failed namespaces
+            const failedNamespaces = Object.entries(status.namespaces)
+                .filter(([_, ns]) => ns === "failed")
+                .map(([name]) => name);
+            if (failedNamespaces.length > 0) {
+                throw new Error(`Translation failed for namespaces: ${failedNamespaces.join(", ")}`);
+            }
+            // Check timeout
+            if (Date.now() - startTime > timeout) {
+                throw new Error(`Translation timed out after ${timeout}ms`);
+            }
+            // Wait before next poll
+            await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        }
+    }
+}

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

@@ -6,6 +6,6 @@ export declare class KokimokiLocalStore<T extends object> extends KokimokiStore<
     constructor(localRoomName: string, defaultState: T);
     getInitialUpdate(appId: string, clientId: string): {
         roomHash: number;
-        initialUpdate: Uint8Array<ArrayBufferLike> | undefined;
+        initialUpdate: Uint8Array | undefined;
     };
 }

package/dist/types/common.d.ts

@@ -2,3 +2,12 @@ export interface Paginated<T> {
     items: T[];
     total: number;
 }
+/** Common options for polling methods */
+export interface PollOptions<T = void> {
+    /** Polling interval in milliseconds. Default: 2000ms, minimum: 1000ms */
+    pollInterval?: number;
+    /** Timeout in milliseconds. Default: 120000ms (2 minutes) */
+    timeout?: number;
+    /** Progress callback */
+    onProgress?: (status: T) => void;
+}

package/dist/types/env.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Kokimoki environment configuration injected into the HTML by @kokimoki/kit.
+ *
+ * Parsed from `#kokimoki-env` script tag at runtime.
+ * In production, placeholder values (%KM_*%) are replaced by the server.
+ */
+export interface KokimokiEnv {
+    /** Whether running in development mode */
+    dev: boolean;
+    /** Whether running in test/preview mode (no real deploy code) */
+    test: boolean;
+    /** WebSocket server host */
+    host: string;
+    /** Application identifier */
+    appId: string;
+    /** Base URL for routing */
+    base: string;
+    /** Base URL for static assets (CDN in production) */
+    assets: string;
+    /** Deploy code slug (production only) */
+    code?: string;
+    /** Client context JSON string - mode, player/presenter codes (production only) */
+    clientContext?: string;
+    /** App configuration JSON string (production, legacy) */
+    config?: string;
+    /** Parsed app configuration object (dev only) */
+    configObject?: unknown;
+    /** List of i18n namespace names */
+    i18nNamespaces?: string[];
+    /** List of i18n language codes */
+    i18nLanguages?: string[];
+    /** Path to i18n files (e.g., "km-i18n") */
+    i18nPath?: string;
+    /** Build URL for dev mode (S3 URL where AI translations are stored) */
+    buildUrl?: string;
+}

package/dist/types/env.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./common";
+export * from "./env";
 export * from "./events";
 export * from "./upload";

package/dist/types/index.js

@@ -1,3 +1,4 @@
 export * from "./common";
+export * from "./env";
 export * from "./events";
 export * from "./upload";

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

@@ -0,0 +1,31 @@
+import { KokimokiClient } from "../core";
+/**
+ * Returns the singleton Kokimoki client instance.
+ *
+ * Creates and caches a single KokimokiClient instance for the application.
+ * This is the recommended way to access the client throughout your app.
+ *
+ * @typeParam T - The client context type for storing custom data per client
+ * @returns The singleton KokimokiClient instance
+ *
+ * @example
+ * ```typescript
+ * import { getKmClient } from '@kokimoki/app';
+ *
+ * interface MyClientContext {
+ *   name: string;
+ *   avatar: string;
+ * }
+ *
+ * const kmClient = getKmClient<MyClientContext>();
+ *
+ * // Create stores
+ * const gameStore = kmClient.store<GameState>('game', initialState);
+ *
+ * // Use in components or actions
+ * await kmClient.transact([gameStore], ([game]) => {
+ *   game.score += 10;
+ * });
+ * ```
+ */
+export declare function getKmClient<T = any>(): KokimokiClient<T>;

package/dist/utils/kokimoki-client.js

@@ -0,0 +1,38 @@
+import { KokimokiClient } from "../core";
+let _kmClient;
+/**
+ * Returns the singleton Kokimoki client instance.
+ *
+ * Creates and caches a single KokimokiClient instance for the application.
+ * This is the recommended way to access the client throughout your app.
+ *
+ * @typeParam T - The client context type for storing custom data per client
+ * @returns The singleton KokimokiClient instance
+ *
+ * @example
+ * ```typescript
+ * import { getKmClient } from '@kokimoki/app';
+ *
+ * interface MyClientContext {
+ *   name: string;
+ *   avatar: string;
+ * }
+ *
+ * const kmClient = getKmClient<MyClientContext>();
+ *
+ * // Create stores
+ * const gameStore = kmClient.store<GameState>('game', initialState);
+ *
+ * // Use in components or actions
+ * await kmClient.transact([gameStore], ([game]) => {
+ *   game.score += 10;
+ * });
+ * ```
+ */
+export function getKmClient() {
+    if (_kmClient) {
+        return _kmClient;
+    }
+    _kmClient = new KokimokiClient();
+    return _kmClient;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Dev mode utilities for Kokimoki client.
+ * Handles URL-based context injection and error forwarding when running in dev frame.
+ */
+export interface DevModeConfig {
+    /** Unique key for this dev session (from ?key= URL param) */
+    key: string;
+    /** Token storage key */
+    tokenKey: string;
+    /** Parsed context from URL (from ?context= URL param) */
+    context?: unknown;
+}
+/**
+ * Parse dev mode configuration from URL parameters.
+ * Returns undefined if not in dev mode or missing required params.
+ */
+export declare function parseDevModeConfig(): DevModeConfig | undefined;
+/**
+ * Set up console prefix for dev mode logging.
+ */
+export declare function setupDevConsolePrefix(key: string): void;
+/**
+ * Set up error handlers to forward errors to parent dev frame.
+ */
+export declare function setupDevErrorHandlers(): void;
+/**
+ * Initialize dev mode. Call this before connecting if env.dev is true.
+ * Returns the dev config if successfully initialized, undefined otherwise.
+ */
+export declare function initDevMode(): DevModeConfig | undefined;

package/dist/utils/kokimoki-dev.js

@@ -0,0 +1,75 @@
+/**
+ * Dev mode utilities for Kokimoki client.
+ * Handles URL-based context injection and error forwarding when running in dev frame.
+ */
+/**
+ * Parse dev mode configuration from URL parameters.
+ * Returns undefined if not in dev mode or missing required params.
+ */
+export function parseDevModeConfig() {
+    const url = new URL(window.location.href);
+    const key = url.searchParams.get("key");
+    if (!key) {
+        return undefined;
+    }
+    const contextBase64 = url.searchParams.get("context");
+    let context;
+    if (contextBase64) {
+        try {
+            context = JSON.parse(atob(contextBase64));
+        }
+        catch (e) {
+            console.warn("[Kokimoki] Failed to parse dev context:", e);
+        }
+    }
+    return {
+        key,
+        tokenKey: `KM_TOKEN/${key}`,
+        context,
+    };
+}
+/**
+ * Set up console prefix for dev mode logging.
+ */
+export function setupDevConsolePrefix(key) {
+    console.log = console.log.bind(console, `[${key}]`);
+}
+/**
+ * Set up error handlers to forward errors to parent dev frame.
+ */
+export function setupDevErrorHandlers() {
+    const notifyError = (error) => {
+        if (window.parent && window.self !== window.parent) {
+            const message = error instanceof Error ? error.message : error;
+            const stack = error instanceof Error ? error.stack : undefined;
+            window.parent.postMessage({ type: "km:error", message, stack }, "*");
+        }
+    };
+    window.onerror = (_message, _source, _lineno, _colno, error) => {
+        if (error) {
+            notifyError(error);
+        }
+    };
+    window.onunhandledrejection = (event) => {
+        const error = event.reason;
+        if (error instanceof Error) {
+            notifyError(error);
+        }
+        else {
+            notifyError(String(error));
+        }
+    };
+}
+/**
+ * Initialize dev mode. Call this before connecting if env.dev is true.
+ * Returns the dev config if successfully initialized, undefined otherwise.
+ */
+export function initDevMode() {
+    const config = parseDevModeConfig();
+    if (!config) {
+        return undefined;
+    }
+    setupDevConsolePrefix(config.key);
+    setupDevErrorHandlers();
+    return config;
+}

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

@@ -0,0 +1,20 @@
+import type { KokimokiEnv } from "../types";
+/**
+ * Parses and returns the Kokimoki environment configuration.
+ *
+ * The environment is injected into the HTML by @kokimoki/kit as a JSON script tag
+ * with id `kokimoki-env`. In production, placeholder values are replaced by the server.
+ *
+ * @returns The parsed KokimokiEnv object
+ * @throws Error if the kokimoki-env element is not found
+ *
+ * @example
+ * ```typescript
+ * import { getKmEnv } from '@kokimoki/app';
+ *
+ * const env = getKmEnv();
+ * console.log(env.dev); // true in development
+ * console.log(env.assets); // CDN URL in production
+ * ```
+ */
+export declare function getKmEnv(): KokimokiEnv;

package/dist/utils/kokimoki-env.js

@@ -0,0 +1,30 @@
+let _kmEnv;
+/**
+ * Parses and returns the Kokimoki environment configuration.
+ *
+ * The environment is injected into the HTML by @kokimoki/kit as a JSON script tag
+ * with id `kokimoki-env`. In production, placeholder values are replaced by the server.
+ *
+ * @returns The parsed KokimokiEnv object
+ * @throws Error if the kokimoki-env element is not found
+ *
+ * @example
+ * ```typescript
+ * import { getKmEnv } from '@kokimoki/app';
+ *
+ * const env = getKmEnv();
+ * console.log(env.dev); // true in development
+ * console.log(env.assets); // CDN URL in production
+ * ```
+ */
+export function getKmEnv() {
+    if (_kmEnv) {
+        return _kmEnv;
+    }
+    const element = document.getElementById("kokimoki-env");
+    if (!element) {
+        throw new Error("kokimoki-env element not found. Ensure the app is built with @kokimoki/kit.");
+    }
+    _kmEnv = JSON.parse(element.textContent);
+    return _kmEnv;
+}

package/dist/version.d.ts

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

package/dist/version.js

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