@kokimoki/kit 1.7.0 → 1.8.1

package/dist/api.js

@@ -4,12 +4,7 @@
  * Shared between @kokimoki/cli and @kokimoki/kit
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_ENDPOINT = void 0;
-exports.createConcept = createConcept;
-exports.getOrganization = getOrganization;
-exports.getConceptOrganization = getConceptOrganization;
-exports.createBuild = createBuild;
-exports.getDeployUrl = getDeployUrl;
+exports.getDeployUrl = exports.createBuild = exports.getConceptOrganization = exports.getOrganization = exports.createConcept = exports.DEFAULT_ENDPOINT = void 0;
 exports.DEFAULT_ENDPOINT = "https://api.kokimoki.com";
 /**
  * Make a request to the Kokimoki API
@@ -39,6 +34,7 @@ async function createConcept(options, request) {
         body: JSON.stringify(request),
     });
 }
+exports.createConcept = createConcept;
 /**
  * Get organization details via the Kokimoki API
  * Used for authentication validation
@@ -46,6 +42,7 @@ async function createConcept(options, request) {
 async function getOrganization(endpoint, apiKey) {
     return kokimokiApiRequest("/auth", { endpoint, apiKey }, { method: "GET" });
 }
+exports.getOrganization = getOrganization;
 /**
  * Get the organization that owns a concept (by concept ID)
  */
@@ -63,6 +60,7 @@ async function getConceptOrganization(endpoint, conceptId) {
     }
     return await res.json();
 }
+exports.getConceptOrganization = getConceptOrganization;
 /**
  * Create a new build via the Kokimoki API
  */
@@ -75,6 +73,7 @@ async function createBuild(options, request, cliVersion) {
         body: JSON.stringify(request),
     });
 }
+exports.createBuild = createBuild;
 /**
  * Get the deploy URL for a build
  */
@@ -93,3 +92,4 @@ async function getDeployUrl(endpoint, apiKey, buildId) {
     }
     return await res.json();
 }
+exports.getDeployUrl = getDeployUrl;

package/dist/credentials.js

@@ -7,9 +7,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCredentialsPath = getCredentialsPath;
-exports.readCredentials = readCredentials;
-exports.writeCredentials = writeCredentials;
+exports.writeCredentials = exports.readCredentials = exports.getCredentialsPath = void 0;
 const promises_1 = __importDefault(require("fs/promises"));
 const os_1 = require("os");
 const path_1 = __importDefault(require("path"));
@@ -19,6 +17,7 @@ const path_1 = __importDefault(require("path"));
 function getCredentialsPath() {
     return path_1.default.join((0, os_1.homedir)(), ".kokimoki");
 }
+exports.getCredentialsPath = getCredentialsPath;
 /**
  * Read credentials from the ~/.kokimoki file
  */
@@ -35,6 +34,7 @@ async function readCredentials() {
         throw e;
     }
 }
+exports.readCredentials = readCredentials;
 /**
  * Write credentials to the ~/.kokimoki file
  */
@@ -42,3 +42,4 @@ async function writeCredentials(credentials) {
     const credentialsPath = getCredentialsPath();
     await promises_1.default.writeFile(credentialsPath, JSON.stringify(credentials, null, 2));
 }
+exports.writeCredentials = writeCredentials;

package/dist/dev-app.js

@@ -3,13 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.deleteAppId = deleteAppId;
-exports.setDevAppI18n = setDevAppI18n;
-exports.setDevAppTranslation = setDevAppTranslation;
-exports.computeStoresHash = computeStoresHash;
-exports.readStoresHash = readStoresHash;
-exports.writeStoresHash = writeStoresHash;
-exports.getOrCreateDevApp = getOrCreateDevApp;
+exports.getOrCreateDevApp = exports.writeStoresHash = exports.readStoresHash = exports.computeStoresHash = exports.setDevAppTranslation = exports.setDevAppI18n = exports.deleteAppId = void 0;
 const crypto_1 = __importDefault(require("crypto"));
 const bson_objectid_1 = __importDefault(require("bson-objectid"));
 const promises_1 = __importDefault(require("fs/promises"));
@@ -108,6 +102,7 @@ async function deleteAppId() {
         }
     }
 }
+exports.deleteAppId = deleteAppId;
 /**
  * Set i18n metadata for a dev app
  */
@@ -126,6 +121,7 @@ async function setDevAppI18n(endpoint, apiKey, appId, i18nMeta) {
         throw new Error(`Failed to set dev app i18n: ${res.status} ${errorText}`);
     }
 }
+exports.setDevAppI18n = setDevAppI18n;
 /**
  * Set translations for a specific language and namespace in a dev app
  */
@@ -144,6 +140,7 @@ async function setDevAppTranslation(endpoint, apiKey, appId, lng, namespace, tra
         throw new Error(`Failed to set dev app translation: ${res.status} ${errorText}`);
     }
 }
+exports.setDevAppTranslation = setDevAppTranslation;
 /**
  * Compute a hash of the stores configuration
  */
@@ -151,6 +148,7 @@ function computeStoresHash(stores) {
     const content = JSON.stringify(stores ?? []);
     return crypto_1.default.createHash("sha256").update(content).digest("hex").slice(0, 16);
 }
+exports.computeStoresHash = computeStoresHash;
 /**
  * Read the stored stores hash from .kokimoki/stores-hash
  */
@@ -166,6 +164,7 @@ async function readStoresHash() {
         throw e;
     }
 }
+exports.readStoresHash = readStoresHash;
 /**
  * Write the stores hash to .kokimoki/stores-hash
  */
@@ -173,6 +172,7 @@ async function writeStoresHash(hash) {
     await ensureKokimokiDir();
     await promises_1.default.writeFile(path_1.default.join(KOKIMOKI_DIR, STORES_HASH_FILE), hash);
 }
+exports.writeStoresHash = writeStoresHash;
 /**
  * Get or create a dev app for local development.
  *
@@ -269,3 +269,4 @@ async function getOrCreateDevApp(config) {
         };
     }
 }
+exports.getOrCreateDevApp = getOrCreateDevApp;

package/dist/dev-frame/render-dev-frame.d.ts

@@ -10,6 +10,18 @@ export interface DevFrameCell {
 export interface DevFrameConfig {
     /** Title shown in browser tab */
     title?: string;
+    /**
+     * App meta for SEO and social sharing. Title will be appended with " - Dev View".
+     */
+    appMeta?: {
+        lang?: string;
+        title?: string;
+        description?: string;
+        ogTitle?: string;
+        ogDescription?: string;
+        ogImage?: string;
+        favicon?: string;
+    };
     /**
      * Grid layout for the dev frame. Each inner array is a row,
      * and each item in the row is a cell/frame.

package/dist/dev-frame/render-dev-frame.js

@@ -3,7 +3,7 @@
  * Renders the dev frame HTML page - a multi-window view for development
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.renderDevFrame = renderDevFrame;
+exports.renderDevFrame = void 0;
 const styles_1 = require("./styles");
 /**
  * Generate URL for a dev frame iframe
@@ -138,16 +138,44 @@ function renderScript() {
  * Render the complete dev frame HTML page
  */
 function renderDevFrame(config) {
-    const { title = "Dev View", rows } = config;
+    const { rows, appMeta } = config;
+    // Build title: use appMeta.title if available, append " - Dev View"
+    const baseTitle = appMeta?.title || config.title || "Kokimoki";
+    const title = `${baseTitle} - Dev View`;
+    // Build meta tags from appMeta
+    const lang = appMeta?.lang || "en";
+    const description = appMeta?.description || "";
+    const ogTitle = appMeta?.ogTitle || baseTitle;
+    const ogDescription = appMeta?.ogDescription || description;
+    const ogImage = appMeta?.ogImage || "";
+    const favicon = appMeta?.favicon || "";
     // Track seen labels across all rows for duplicate detection
     const seenLabels = new Set();
     const rowsHtml = rows.map((row) => renderRow(row, seenLabels)).join("\n");
+    // Build optional meta tags
+    const metaTags = [];
+    if (description) {
+        metaTags.push(`<meta name="description" content="${description}">`);
+    }
+    if (ogTitle) {
+        metaTags.push(`<meta property="og:title" content="${ogTitle}">`);
+    }
+    if (ogDescription) {
+        metaTags.push(`<meta property="og:description" content="${ogDescription}">`);
+    }
+    if (ogImage) {
+        metaTags.push(`<meta property="og:image" content="${ogImage}">`);
+    }
+    if (favicon) {
+        metaTags.push(`<link rel="icon" href="${favicon}">`);
+    }
     return `<!DOCTYPE html>
-<html lang="en">
+<html lang="${lang}">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>${title}</title>
+  ${metaTags.join("\n  ")}
   <style>${styles_1.devFrameStyles}</style>
 </head>
 <body>
@@ -158,3 +186,4 @@ function renderDevFrame(config) {
 </body>
 </html>`;
 }
+exports.renderDevFrame = renderDevFrame;

package/dist/dev-i18n.js

@@ -3,10 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadI18nFromPath = loadI18nFromPath;
-exports.getI18nMeta = getI18nMeta;
-exports.syncAllI18nToDevApp = syncAllI18nToDevApp;
-exports.syncI18nFile = syncI18nFile;
+exports.syncI18nFile = exports.syncAllI18nToDevApp = exports.getI18nMeta = exports.loadI18nFromPath = void 0;
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
 const dev_app_1 = require("./dev-app");
@@ -41,6 +38,7 @@ async function loadI18nFromPath(i18nPath) {
     }
     return resources;
 }
+exports.loadI18nFromPath = loadI18nFromPath;
 /**
  * Scan an i18n folder and return i18n metadata.
  * Expected structure: `{i18nPath}/{lng}/{namespace}.json`
@@ -94,6 +92,7 @@ async function getI18nMeta(i18nPath, primaryLng = "en") {
         languages,
     };
 }
+exports.getI18nMeta = getI18nMeta;
 /**
  * Sync primary language i18n files to the dev app build directory (initial sync).
  * Only uploads primaryLng since that's what AI translations use as source.
@@ -135,6 +134,7 @@ async function syncAllI18nToDevApp(devAppInfo, i18nResources, primaryLng = "en")
         console.warn(`[kokimoki-kit] Synced i18n: ${syncedFiles.join(", ")}`);
     }
 }
+exports.syncAllI18nToDevApp = syncAllI18nToDevApp;
 /**
  * Sync a single i18n file to the dev app build directory.
  * Only syncs if the file is for the primary language.
@@ -162,3 +162,4 @@ async function syncI18nFile(devAppInfo, i18nPath, changedFilePath, primaryLng =
         console.warn(`[kokimoki-kit] Failed to sync i18n ${lng}/${ns}:`, e instanceof Error ? e.message : e);
     }
 }
+exports.syncI18nFile = syncI18nFile;

package/dist/dev-overlays.js

@@ -3,9 +3,7 @@
  * Development overlay HTML templates for kokimoki-kit plugin
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.renderLoadingPage = renderLoadingPage;
-exports.renderErrorPage = renderErrorPage;
-exports.renderStoresChangedPage = renderStoresChangedPage;
+exports.renderStoresChangedPage = exports.renderErrorPage = exports.renderLoadingPage = void 0;
 const pageBaseStyles = `
   color: white;
   display: flex;
@@ -111,6 +109,7 @@ function renderLoadingPage() {
 </body>
 </html>`;
 }
+exports.renderLoadingPage = renderLoadingPage;
 /**
  * Generate error page HTML for dev app errors (full page)
  */
@@ -176,6 +175,7 @@ function renderErrorPage(error) {
 </body>
 </html>`;
 }
+exports.renderErrorPage = renderErrorPage;
 /**
  * Generate stores changed warning page HTML (full page, not overlay)
  */
@@ -298,3 +298,4 @@ function renderStoresChangedPage(canReset) {
 </body>
 </html>`;
 }
+exports.renderStoresChangedPage = renderStoresChangedPage;

package/dist/index.d.ts

@@ -3,5 +3,6 @@ export * from "./dev-frame";
 export * from "./kokimoki-kit-plugin";
 export * from "./preprocess-style";
 export * from "./zod";
+export * from "./schemas/app-meta-schema";
 export * from "./api";
 export * from "./credentials";

package/dist/index.js

@@ -20,6 +20,8 @@ __exportStar(require("./kokimoki-kit-plugin"), exports);
 __exportStar(require("./preprocess-style"), exports);
 // Re-export Zod utilities for schema definition
 __exportStar(require("./zod"), exports);
+// App Meta schema for built-in store
+__exportStar(require("./schemas/app-meta-schema"), exports);
 // Shared utilities (used by both kit and cli)
 __exportStar(require("./api"), exports);
 __exportStar(require("./credentials"), exports);

package/dist/kokimoki-kit-plugin.d.ts

@@ -1,6 +1,7 @@
 import type { PluginOption } from "vite";
 import { ZodType } from "zod/v4";
 import type { DevFrameCell } from "./dev-frame";
+import { type AppMetaState } from "./schemas/app-meta-schema";
 export { getI18nMeta, type I18nMeta } from "./dev-i18n";
 export interface KokimokiKitConfig {
     conceptId: string;
@@ -27,6 +28,7 @@ export interface KokimokiKitConfig {
         pattern: string;
         schema: ZodType;
         local?: boolean;
+        isTransferable?: boolean;
     }[];
     /** API endpoint for kokimoki services. Defaults to https://api.kokimoki.com */
     endpoint?: string;
@@ -53,5 +55,11 @@ export interface KokimokiKitConfig {
      * ```
      */
     devView?: readonly (readonly DevFrameCell[])[] | false;
+    /**
+     * Default app meta values for SEO and social sharing.
+     * These values are used as initial state for the built-in appMetaStore
+     * and for server-side HTML meta tag injection.
+     */
+    defaultAppMeta?: AppMetaState;
 }
 export declare function kokimokiKitPlugin(config: KokimokiKitConfig): PluginOption;

package/dist/kokimoki-kit-plugin.js

@@ -15,30 +15,20 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getI18nMeta = void 0;
-exports.kokimokiKitPlugin = kokimokiKitPlugin;
+exports.kokimokiKitPlugin = exports.getI18nMeta = void 0;
 const promises_1 = __importDefault(require("fs/promises"));
+const node_html_parser_1 = require("node-html-parser");
 const path_1 = __importDefault(require("path"));
 const yaml = __importStar(require("yaml"));
 const v4_1 = require("zod/v4");
@@ -50,10 +40,23 @@ const dev_i18n_1 = require("./dev-i18n");
 const dev_overlays_1 = require("./dev-overlays");
 const preprocess_style_1 = require("./preprocess-style");
 const production_loading_screen_1 = require("./production-loading-screen");
+const app_meta_schema_1 = require("./schemas/app-meta-schema");
 const version_1 = require("./version");
 var dev_i18n_2 = require("./dev-i18n");
 Object.defineProperty(exports, "getI18nMeta", { enumerable: true, get: function () { return dev_i18n_2.getI18nMeta; } });
+/**
+ * Built-in app meta store configuration.
+ * Automatically injected into all apps for server-side meta tag injection.
+ */
+const BUILT_IN_APP_META_STORE = {
+    pattern: app_meta_schema_1.APP_META_STORE_NAME,
+    schema: app_meta_schema_1.appMetaStoreSchema,
+    local: false,
+    isTransferable: true,
+};
 function kokimokiKitPlugin(config) {
+    // Combine user stores with built-in stores
+    const allStores = [...(config.stores ?? []), BUILT_IN_APP_META_STORE];
     // Cache for loaded i18n resources
     let cachedI18n = null;
     // Cache dev app info for syncing
@@ -63,6 +66,37 @@ function kokimokiKitPlugin(config) {
     let initPromise = null;
     // Cached dev app result
     let cachedDevAppResult = null;
+    /**
+     * Resolve asset path for meta tags.
+     * In production, prepends %KM_ASSETS% placeholder for relative paths.
+     * In dev, returns path as-is since assets are served from root.
+     */
+    function resolveAssetUrl(path, isProduction) {
+        if (!path)
+            return path;
+        // Only prefix relative paths (starting with /)
+        if (isProduction && path.startsWith("/")) {
+            return `%KM_ASSETS%${path}`;
+        }
+        return path;
+    }
+    /**
+     * Resolve asset URLs in defaultAppMeta object.
+     * Creates a new object with ogImage and favicon paths resolved.
+     */
+    function resolveAppMetaAssets(meta, isProduction) {
+        if (!meta)
+            return null;
+        return {
+            ...meta,
+            ogImage: meta.ogImage
+                ? resolveAssetUrl(meta.ogImage, isProduction)
+                : undefined,
+            favicon: meta.favicon
+                ? resolveAssetUrl(meta.favicon, isProduction)
+                : undefined,
+        };
+    }
     /**
      * Start initialization if not already started.
      * Returns a promise that resolves when initialization is complete.
@@ -137,11 +171,15 @@ function kokimokiKitPlugin(config) {
             if (process.env.NODE_ENV !== "development") {
                 // Remove any existing km-loading element from the HTML
                 const processedHtml = (0, production_loading_screen_1.removeExistingLoadingScreen)(html);
-                // NOTE: Try https://github.com/jsdom/jsdom instead of regex parsing
-                const result = processedHtml
-                    .replace("<head>", `<head>
-              <base href="%KM_BASE%">
-              <script id="kokimoki-env" type="application/json">
+                // Parse HTML for DOM manipulation
+                const doc = (0, node_html_parser_1.parse)(processedHtml);
+                const head = doc.querySelector("head");
+                const body = doc.querySelector("body");
+                const htmlEl = doc.querySelector("html");
+                // Add base tag
+                head?.insertAdjacentHTML("afterbegin", `<base href="%KM_BASE%">`);
+                // Inject kokimoki-env script
+                head?.insertAdjacentHTML("afterbegin", `<script id="kokimoki-env" type="application/json">
               {
                 "dev": %KM_DEV%,
                 "test": %KM_TEST%,
@@ -154,10 +192,12 @@ function kokimokiKitPlugin(config) {
                 "i18nNamespaces": ${JSON.stringify(i18nNamespaces)},
                 "i18nLanguages": ${JSON.stringify(i18nLanguages)},
                 "base": "%KM_BASE%",
-                "assets": "%KM_ASSETS%"
+                "assets": "%KM_ASSETS%",
+                "defaultAppMeta": ${JSON.stringify(resolveAppMetaAssets(config.defaultAppMeta, true))}
               }
-              </script>
-              <script>
+              </script>`);
+                // Inject assets URL helper script
+                head?.insertAdjacentHTML("beforeend", `<script>
                 window.__toAssetsUrl = (path) => {
                   if (path.startsWith("km-proxy")) {
                     return "/%KM_BUILD_ID%/" + path;
@@ -165,16 +205,50 @@ function kokimokiKitPlugin(config) {
 
                   return "%KM_ASSETS%/" + path;
                 };
-              </script>${production_loading_screen_1.loadingScreenStyles}${production_loading_screen_1.loadingScreenScript}
-            `)
-                    .replace(/<body([^>]*)>/, `<body$1>${production_loading_screen_1.loadingScreenElement}`)
-                    .replace(/<link.*?href="(.*?)".*?>/g, (match, p1) => {
-                    return match.replace(p1, `%KM_ASSETS%${p1.startsWith("/") ? "" : "/"}${p1}`);
-                })
-                    .replace(/<script.*?src="(.*?)".*?>/g, (match, p1) => {
-                    return match.replace(p1, `%KM_ASSETS%${p1.startsWith("/") ? "" : "/"}${p1}`);
+              </script>`);
+                // Inject loading screen
+                head?.insertAdjacentHTML("beforeend", production_loading_screen_1.loadingScreenStyles);
+                head?.insertAdjacentHTML("beforeend", production_loading_screen_1.loadingScreenScript);
+                body?.insertAdjacentHTML("afterbegin", production_loading_screen_1.loadingScreenElement);
+                // Inject meta tags from defaultAppMeta
+                if (config.defaultAppMeta) {
+                    const meta = config.defaultAppMeta;
+                    if (meta.lang) {
+                        htmlEl?.setAttribute("lang", meta.lang);
+                    }
+                    if (meta.title) {
+                        head?.insertAdjacentHTML("beforeend", `<title>${meta.title}</title>`);
+                    }
+                    if (meta.description) {
+                        head?.insertAdjacentHTML("beforeend", `<meta name="description" content="${meta.description}" />`);
+                    }
+                    if (meta.ogTitle ?? meta.title) {
+                        head?.insertAdjacentHTML("beforeend", `<meta property="og:title" content="${meta.ogTitle ?? meta.title}" />`);
+                    }
+                    if (meta.ogDescription ?? meta.description) {
+                        head?.insertAdjacentHTML("beforeend", `<meta property="og:description" content="${meta.ogDescription ?? meta.description}" />`);
+                    }
+                    if (meta.ogImage) {
+                        head?.insertAdjacentHTML("beforeend", `<meta property="og:image" content="${resolveAssetUrl(meta.ogImage, true)}" />`);
+                    }
+                    if (meta.favicon) {
+                        head?.insertAdjacentHTML("beforeend", `<link rel="icon" type="image/png" href="${resolveAssetUrl(meta.favicon, true)}" />`);
+                    }
+                }
+                // Update asset URLs in link and script tags
+                doc.querySelectorAll("link[href]").forEach((el) => {
+                    const href = el.getAttribute("href");
+                    if (href) {
+                        el.setAttribute("href", `%KM_ASSETS%${href.startsWith("/") ? "" : "/"}${href}`);
+                    }
+                });
+                doc.querySelectorAll("script[src]").forEach((el) => {
+                    const src = el.getAttribute("src");
+                    if (src) {
+                        el.setAttribute("src", `%KM_ASSETS%${src.startsWith("/") ? "" : "/"}${src}`);
+                    }
                 });
-                return result;
+                return doc.toString();
             }
             // Development mode: ensure initialization is started and wait for it
             if (initState === "pending" || initState === "initializing") {
@@ -191,7 +265,7 @@ function kokimokiKitPlugin(config) {
                 error: { code: "INIT_ERROR", message: "Initialization failed" },
             };
             // Check if stores configuration has changed
-            const currentStoresHash = (0, dev_app_1.computeStoresHash)(config.stores);
+            const currentStoresHash = (0, dev_app_1.computeStoresHash)(allStores);
             const previousStoresHash = await (0, dev_app_1.readStoresHash)();
             const storesChanged = previousStoresHash !== null && previousStoresHash !== currentStoresHash;
             // Write initial stores hash if it doesn't exist yet
@@ -212,9 +286,12 @@ function kokimokiKitPlugin(config) {
                 const defaultProjectConfigFile = await promises_1.default.readFile(config.defaultProjectConfigPath, "utf8");
                 defaultProjectConfig = config.schema.parse(yaml.parse(defaultProjectConfigFile));
             }
-            // Inject the app id into the index.html
-            html = html.replace("<head>", `<head>
-          <script id="kokimoki-env" type="application/json">
+            // Parse HTML for DOM manipulation
+            const doc = (0, node_html_parser_1.parse)(html);
+            const head = doc.querySelector("head");
+            const htmlEl = doc.querySelector("html");
+            // Inject kokimoki-env script
+            const envScript = (0, node_html_parser_1.parse)(`<script id="kokimoki-env" type="application/json">
           {
             "dev": true,
             "test": true,
@@ -225,15 +302,43 @@ function kokimokiKitPlugin(config) {
             "i18nLanguages": ${JSON.stringify(i18nLanguages)},
             "base": "/",
             "assets": "/",
-            "buildUrl": ${JSON.stringify(buildUrl ?? null)}
+            "buildUrl": ${JSON.stringify(buildUrl ?? null)},
+            "defaultAppMeta": ${JSON.stringify(config.defaultAppMeta ?? null)}
           }
           </script>`);
+            head?.insertAdjacentHTML("afterbegin", envScript.toString());
+            // Inject meta tags from defaultAppMeta in development
+            if (config.defaultAppMeta) {
+                const meta = config.defaultAppMeta;
+                if (meta.lang) {
+                    htmlEl?.setAttribute("lang", meta.lang);
+                }
+                if (meta.title) {
+                    head?.insertAdjacentHTML("beforeend", `<title>${meta.title}</title>`);
+                }
+                if (meta.description) {
+                    head?.insertAdjacentHTML("beforeend", `<meta name="description" content="${meta.description}" />`);
+                }
+                if (meta.ogTitle ?? meta.title) {
+                    head?.insertAdjacentHTML("beforeend", `<meta property="og:title" content="${meta.ogTitle ?? meta.title}" />`);
+                }
+                if (meta.ogDescription ?? meta.description) {
+                    head?.insertAdjacentHTML("beforeend", `<meta property="og:description" content="${meta.ogDescription ?? meta.description}" />`);
+                }
+                if (meta.ogImage) {
+                    head?.insertAdjacentHTML("beforeend", `<meta property="og:image" content="${meta.ogImage}" />`);
+                }
+                if (meta.favicon) {
+                    head?.insertAdjacentHTML("beforeend", `<link rel="icon" type="image/png" href="${meta.favicon}" />`);
+                }
+            }
             // Inject default project style in development
             if (config.defaultProjectStylePath) {
                 const defaultProjectStyle = await promises_1.default.readFile(config.defaultProjectStylePath, "utf8");
-                html = html.replace("</body>", `<style id="km-dev-style">${(0, preprocess_style_1.preprocessStyle)(defaultProjectStyle)}</style></body>`);
+                const body = doc.querySelector("body");
+                body?.insertAdjacentHTML("beforeend", `<style id="km-dev-style">${(0, preprocess_style_1.preprocessStyle)(defaultProjectStyle)}</style>`);
             }
-            return html;
+            return doc.toString();
         },
         // write kokimoki metadata to .kokimoki directory
         async generateBundle(_, _bundle) {
@@ -259,6 +364,7 @@ function kokimokiKitPlugin(config) {
                 build: "dist",
                 defaultProjectConfigPath: config.defaultProjectConfigPath,
                 defaultProjectStylePath: config.defaultProjectStylePath,
+                defaultAppMeta: config.defaultAppMeta,
                 i18n,
             }, null, 2));
             // write schema
@@ -297,19 +403,18 @@ function kokimokiKitPlugin(config) {
                     properties: {},
                 };
             await promises_1.default.writeFile(".kokimoki/schema.json", JSON.stringify(jsonSchema, null, 2));
-            // write stores config with JSON schemas to build output
-            if (config.stores) {
-                const storesWithJsonSchema = config.stores.map((store) => ({
-                    pattern: store.pattern,
-                    local: store.local,
-                    schema: v4_1.z.toJSONSchema(store.schema),
-                }));
-                this.emitFile({
-                    type: "asset",
-                    fileName: "km-stores.json",
-                    source: JSON.stringify(storesWithJsonSchema, null, 2),
-                });
-            }
+            // write stores config with JSON schemas to build output (always includes built-in stores)
+            const storesWithJsonSchema = allStores.map((store) => ({
+                pattern: store.pattern,
+                local: store.local,
+                schema: v4_1.z.toJSONSchema(store.schema),
+                isTransferable: store.isTransferable ?? false,
+            }));
+            this.emitFile({
+                type: "asset",
+                fileName: "km-stores.json",
+                source: JSON.stringify(storesWithJsonSchema, null, 2),
+            });
             // write i18n files to build output as individual files per lng/ns
             const i18nResources = await getI18nResources();
             if (Object.keys(i18nResources).length > 0) {
@@ -340,7 +445,7 @@ function kokimokiKitPlugin(config) {
             startInitialization();
             // Helper to check stores changed status
             async function checkStoresChanged() {
-                const currentStoresHash = (0, dev_app_1.computeStoresHash)(config.stores);
+                const currentStoresHash = (0, dev_app_1.computeStoresHash)(allStores);
                 const previousStoresHash = await (0, dev_app_1.readStoresHash)();
                 return (previousStoresHash !== null &&
                     previousStoresHash !== currentStoresHash);
@@ -387,7 +492,7 @@ function kokimokiKitPlugin(config) {
             // API endpoint to acknowledge stores hash change (dismiss the popup)
             server.middlewares.use("/__kokimoki/stores-hash/acknowledge", async (_req, res) => {
                 try {
-                    const currentStoresHash = (0, dev_app_1.computeStoresHash)(config.stores);
+                    const currentStoresHash = (0, dev_app_1.computeStoresHash)(allStores);
                     await (0, dev_app_1.writeStoresHash)(currentStoresHash);
                     res.statusCode = 200;
                     res.setHeader("Content-Type", "application/json");
@@ -407,7 +512,7 @@ function kokimokiKitPlugin(config) {
                     // Delete the app-id file so a new dev app will be created
                     await (0, dev_app_1.deleteAppId)();
                     // Update the stores hash
-                    const currentStoresHash = (0, dev_app_1.computeStoresHash)(config.stores);
+                    const currentStoresHash = (0, dev_app_1.computeStoresHash)(allStores);
                     await (0, dev_app_1.writeStoresHash)(currentStoresHash);
                     // Reset initialization state so next request triggers re-initialization
                     initState = "pending";
@@ -523,8 +628,8 @@ function kokimokiKitPlugin(config) {
                 }
                 // Render dev view HTML at root
                 const devViewHtml = (0, dev_frame_1.renderDevFrame)({
-                    title: "Dev View",
                     rows: config.devView,
+                    appMeta: config.defaultAppMeta,
                 });
                 res.statusCode = 200;
                 res.setHeader("Content-Type", "text/html");
@@ -534,3 +639,4 @@ function kokimokiKitPlugin(config) {
         },
     };
 }
+exports.kokimokiKitPlugin = kokimokiKitPlugin;

package/dist/preprocess-style.js

@@ -3,17 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hexToRgb = hexToRgb;
-exports.rgbToHex = rgbToHex;
-exports.revertReplaceForColorPickers = revertReplaceForColorPickers;
-exports.hexToTailwindRgbString = hexToTailwindRgbString;
-exports.getLuminance = getLuminance;
-exports.calculateRatio = calculateRatio;
-exports.handleStringColor = handleStringColor;
-exports.destringRgb = destringRgb;
-exports.generateA11yOnColor = generateA11yOnColor;
-exports.generatePalette = generatePalette;
-exports.preprocessStyle = preprocessStyle;
+exports.preprocessStyle = exports.generatePalette = exports.generateA11yOnColor = exports.destringRgb = exports.handleStringColor = exports.calculateRatio = exports.getLuminance = exports.hexToTailwindRgbString = exports.revertReplaceForColorPickers = exports.rgbToHex = exports.hexToRgb = void 0;
 const colorjs_io_1 = __importDefault(require("colorjs.io"));
 const colornames_1 = __importDefault(require("colornames"));
 // List of rgb tuple variable names (possibly temporary system to support color picker for these variables)
@@ -113,10 +103,12 @@ function hexToRgb(hex) {
         b: parseInt(b, 16),
     };
 }
+exports.hexToRgb = hexToRgb;
 function rgbToHex(r, g, b) {
     const toHex = (c) => `0${c.toString(16)}`.slice(-2);
     return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
 }
+exports.rgbToHex = rgbToHex;
 // export function replaceForColorPickers(code: string) {
 //   return code.replace(
 //     /--([a-z0-9-]+):\s*(\d+)\s+(\d+)\s+(\d+);/gi,
@@ -153,6 +145,7 @@ function revertReplaceForColorPickers(code) {
         return match;
     });
 }
+exports.revertReplaceForColorPickers = revertReplaceForColorPickers;
 function lighten(hex, intensity) {
     const color = hexToRgb(`#${hex}`);
     if (!color)
@@ -179,6 +172,7 @@ function hexToTailwindRgbString(hex) {
     const [, r, g, b] = colorParts;
     return `${parseInt(r, 16)} ${parseInt(g, 16)} ${parseInt(b, 16)}`;
 }
+exports.hexToTailwindRgbString = hexToTailwindRgbString;
 function getLuminance(r, g, b) {
     const { _r, _g, _b } = typeof r === "object"
         ? { _r: r.r, _g: r.g, _b: r.b }
@@ -192,6 +186,7 @@ function getLuminance(r, g, b) {
     });
     return a[0] * 0.2126 + a[1] * 0.7152 + a[2] * 0.0722;
 }
+exports.getLuminance = getLuminance;
 function calculateRatio(luminance1, luminance2) {
     const lum1 = typeof luminance1 === "string"
         ? getLuminance(handleStringColor(luminance1))
@@ -205,6 +200,7 @@ function calculateRatio(luminance1, luminance2) {
         ? (lum2 + 0.05) / (lum1 + 0.05)
         : (lum1 + 0.05) / (lum2 + 0.05);
 }
+exports.calculateRatio = calculateRatio;
 function handleStringColor(colorString, returnType = "rgb") {
     // if it's a css variable
     if (colorString.includes("--")) {
@@ -228,6 +224,7 @@ function handleStringColor(colorString, returnType = "rgb") {
     }
     return colorString;
 }
+exports.handleStringColor = handleStringColor;
 function cssColorToHex(colorString) {
     if (colorString.includes("#"))
         return colorString;
@@ -254,11 +251,13 @@ function destringRgb(rgbString) {
         b: parseInt(rgb[3], 10),
     };
 }
+exports.destringRgb = destringRgb;
 function generateA11yOnColor(hex) {
     const black = calculateRatio(hex, "#000000");
     const white = calculateRatio(hex, "#FFFFFF");
     return black < white ? "0 0 0" : "255 255 255";
 }
+exports.generateA11yOnColor = generateA11yOnColor;
 function generatePalette(baseColor) {
     const hexValidation = new RegExp(/^#[0-9a-f]{6}$/i);
     if (!hexValidation.test(baseColor))
@@ -300,6 +299,7 @@ function generatePalette(baseColor) {
     });
     return response;
 }
+exports.generatePalette = generatePalette;
 function preprocessGfcThemeBlock(code) {
     // Generate map of defined css variables
     const cssVariableMap = {};
@@ -376,3 +376,4 @@ function preprocessStyle(code) {
         }
     });
 }
+exports.preprocessStyle = preprocessStyle;

package/dist/production-loading-screen.js

@@ -4,8 +4,7 @@
  * This screen is injected into production builds and removed when km:ready is received.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadingScreenElement = exports.loadingScreenScript = exports.loadingScreenStyles = void 0;
-exports.removeExistingLoadingScreen = removeExistingLoadingScreen;
+exports.removeExistingLoadingScreen = exports.loadingScreenElement = exports.loadingScreenScript = exports.loadingScreenStyles = void 0;
 /**
  * Loading screen styles
  */
@@ -121,3 +120,4 @@ function removeExistingLoadingScreen(html) {
         .replace(/<div[^>]*id=["']km-loading["'][^>]*>[\s\S]*?<\/div>/gi, "")
         .replace(/<style[^>]*id=["']km-loading-style["'][^>]*>[\s\S]*?<\/style>/gi, "");
 }
+exports.removeExistingLoadingScreen = removeExistingLoadingScreen;

package/dist/schemas/app-meta-schema.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod/v4";
+/**
+ * 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";
+/**
+ * Schema 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 declare const appMetaStoreSchema: z.ZodObject<{
+    lang: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    ogTitle: z.ZodOptional<z.ZodString>;
+    ogDescription: z.ZodOptional<z.ZodString>;
+    ogImage: z.ZodOptional<z.ZodString>;
+    favicon: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AppMetaState = z.infer<typeof appMetaStoreSchema>;

package/dist/schemas/app-meta-schema.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appMetaStoreSchema = exports.APP_META_STORE_NAME = void 0;
+const v4_1 = require("zod/v4");
+/**
+ * Reserved store name for the App Meta store.
+ * Stores with the `__km/` prefix are reserved for SDK internal use.
+ */
+exports.APP_META_STORE_NAME = "__km/app-meta";
+/**
+ * Schema 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.
+ */
+exports.appMetaStoreSchema = v4_1.z.object({
+    /** HTML lang attribute (e.g., 'en', 'et', 'de') */
+    lang: v4_1.z.string().optional(),
+    /** Document title (browser tab) */
+    title: v4_1.z.string().optional(),
+    /** Meta description */
+    description: v4_1.z.string().optional(),
+    /** Open Graph title (defaults to title if not set) */
+    ogTitle: v4_1.z.string().optional(),
+    /** Open Graph description (defaults to description if not set) */
+    ogDescription: v4_1.z.string().optional(),
+    /** Open Graph image URL */
+    ogImage: v4_1.z.string().optional(),
+    /** Favicon URL */
+    favicon: v4_1.z.string().optional(),
+});

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const KOKIMOKI_KIT_VERSION = "1.7.0";
+export declare const KOKIMOKI_KIT_VERSION = "1.8.1";

package/dist/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KOKIMOKI_KIT_VERSION = void 0;
-exports.KOKIMOKI_KIT_VERSION = "1.7.0";
+exports.KOKIMOKI_KIT_VERSION = "1.8.1";

package/docs/kokimoki-kit.instructions.md

@@ -15,77 +15,93 @@ npm install @kokimoki/kit
 
 ## Plugin Configuration
 
+Create a `kokimoki.config.ts` file in your project root to define your Kokimoki Kit configuration:
+
+```typescript
+export const kokimokiConfig: KokimokiKitConfig = {
+  // Required: Your concept ID from Kokimoki
+  conceptId: "your-concept-id",
+
+  // Required: Deploy configurations
+  deployCodes: [
+    {
+      name: "default",
+      description: "Default game mode",
+      clientContext: { mode: "standard" },
+    },
+    {
+      name: "tournament",
+      description: "Tournament mode with stricter rules",
+      clientContext: { mode: "tournament", maxPlayers: 100 },
+    },
+  ],
+
+  /**
+   * Store schemas for validation
+   * marking stores as transferable allows their content to be used
+   * when creating new apps based on this one.
+   *
+   * For example, game configuration can contain content and settings
+   * that can be reused when setting up a new game instance. Dynamic
+   * game state, on the other hand, should not be transferable.
+   */
+  stores: [
+    {
+      pattern: "config",
+      schema: z.object({
+        mode: z.enum(["standard", "tournament"]),
+        duration: z.number().min(1).describe("Game duration in minutes"),
+      }),
+      isTransferable: true, // This store content can be used to create a new app with the same content
+    },
+    {
+      pattern: "game",
+      schema: z.object({
+        status: z.enum(["waiting", "playing", "finished"]),
+        round: z.number(),
+      }),
+      isTransferable: false, // Dynamic game state should not be marked as transferable
+    },
+    {
+      pattern: "player-*",
+      schema: z.object({
+        name: z.string(),
+        score: z.number(),
+      }),
+      local: true, // Local store (per-client)
+      isTransferable: false, // Local stores cannot be transferable
+    },
+  ],
+
+  // Optional: i18n configuration
+  i18nPath: "./src/i18n",
+  i18nPrimaryLng: "en", // Source language for AI translations
+
+  // Optional: Custom API endpoint
+  endpoint: "https://api.kokimoki.com",
+  host: "y-wss.kokimoki.com",
+
+  // Optional: Dev view layout (see Dev Frame section)
+  devView: [
+    [{ label: "host", clientContext: { mode: "host" } }],
+    [
+      { label: "player1", clientContext: { mode: "player" } },
+      { label: "player2", clientContext: { mode: "player" } },
+    ],
+  ],
+};
+```
+
 Add the plugin to your `vite.config.ts`:
 
 ```typescript
 import { defineConfig } from "vite";
 import { kokimokiKitPlugin } from "@kokimoki/kit";
 import { z } from "@kokimoki/kit";
+import { kokimokiConfig } from "./kokimoki.config";
 
 export default defineConfig({
-  plugins: [
-    kokimokiKitPlugin({
-      // Required: Your concept ID from Kokimoki
-      conceptId: "your-concept-id",
-
-      // Required: Deploy configurations
-      deployCodes: [
-        {
-          name: "default",
-          description: "Default game mode",
-          clientContext: { mode: "standard" },
-        },
-        {
-          name: "tournament",
-          description: "Tournament mode with stricter rules",
-          clientContext: { mode: "tournament", maxPlayers: 100 },
-        },
-      ],
-
-      // Optional: Project config schema (validated in admin panel)
-      schema: z.object({
-        title: z.string(),
-        maxPlayers: z.number().min(2).max(100),
-        timeLimit: z.number().optional(),
-      }),
-
-      // Optional: Store schemas for validation
-      stores: [
-        {
-          pattern: "game",
-          schema: z.object({
-            status: z.enum(["waiting", "playing", "finished"]),
-            round: z.number(),
-          }),
-        },
-        {
-          pattern: "player-*",
-          schema: z.object({
-            name: z.string(),
-            score: z.number(),
-          }),
-          local: true, // Local store (per-client)
-        },
-      ],
-
-      // Optional: i18n configuration
-      i18nPath: "./src/i18n",
-      i18nPrimaryLng: "en", // Source language for AI translations
-
-      // Optional: Custom API endpoint
-      endpoint: "https://api.kokimoki.com",
-      host: "y-wss.kokimoki.com",
-
-      // Optional: Dev view layout (see Dev Frame section)
-      devView: [
-        [{ label: "host", clientContext: { mode: "host" } }],
-        [
-          { label: "player1", clientContext: { mode: "player" } },
-          { label: "player2", clientContext: { mode: "player" } },
-        ],
-      ],
-    }),
-  ],
+  plugins: [kokimokiKitPlugin(kokimokiConfig)],
 });
 ```
 
@@ -100,17 +116,65 @@ export default defineConfig({
 
 ### Optional Options
 
-| Option                     | Type             | Description                                        |
-| -------------------------- | ---------------- | -------------------------------------------------- |
-| `schema`                   | `ZodType`        | Zod schema for project configuration               |
-| `stores`                   | `array`          | Store definitions with patterns and schemas        |
-| `i18nPath`                 | `string`         | Path to i18n folder (e.g., `./src/i18n`)           |
-| `i18nPrimaryLng`           | `string`         | Source language code (default: `"en"`)             |
-| `endpoint`                 | `string`         | API endpoint (default: `https://api.kokimoki.com`) |
-| `host`                     | `string`         | WebSocket host (default: `y-wss.kokimoki.com`)     |
-| `devView`                  | `array \| false` | Dev frame layout or `false` to disable             |
-| `defaultProjectConfigPath` | `string`         | Path to default project config file                |
-| `defaultProjectStylePath`  | `string`         | Path to default project style file                 |
+| Option                    | Type             | Description                                        |
+| ------------------------- | ---------------- | -------------------------------------------------- |
+| `schema`                  | `ZodType`        | Zod schema for project configuration               |
+| `stores`                  | `array`          | Store definitions with patterns and schemas        |
+| `i18nPath`                | `string`         | Path to i18n folder (e.g., `./src/i18n`)           |
+| `i18nPrimaryLng`          | `string`         | Source language code (default: `"en"`)             |
+| `endpoint`                | `string`         | API endpoint (default: `https://api.kokimoki.com`) |
+| `host`                    | `string`         | WebSocket host (default: `y-wss.kokimoki.com`)     |
+| `devView`                 | `array \| false` | Dev frame layout or `false` to disable             |
+| `defaultAppMeta`          | `object`         | Default meta tags for SEO and social sharing       |
+| `defaultProjectStylePath` | `string`         | Path to default project style file                 |
+
+## App Meta
+
+The `defaultAppMeta` option configures HTML meta tags for SEO and social sharing previews. These defaults are injected into the HTML at build time and used as the initial state for `kmClient.metaStore`.
+
+### Configuration
+
+```typescript
+kokimokiKitPlugin({
+  // ...
+  defaultAppMeta: {
+    lang: "en",
+    title: "My Game",
+    description: "An awesome multiplayer game",
+    ogTitle: "My Game",
+    ogDescription: "Join the fun!",
+    ogImage: "/og-image.png",
+    favicon: "/favicon.png",
+  },
+});
+```
+
+### Fields
+
+| Field           | Description                                                   |
+| --------------- | ------------------------------------------------------------- |
+| `lang`          | HTML `lang` attribute (e.g., `"en"`, `"de"`)                  |
+| `title`         | Document title (browser tab)                                  |
+| `description`   | Meta description for SEO                                      |
+| `ogTitle`       | Open Graph title (defaults to `title` if not set)             |
+| `ogDescription` | Open Graph description (defaults to `description`)            |
+| `ogImage`       | Open Graph image URL (use relative path like `/og-image.png`) |
+| `favicon`       | Favicon URL (use relative path like `/favicon.png`)           |
+
+### Asset Path Resolution
+
+Relative paths (starting with `/`) for `ogImage` and `favicon` are automatically prefixed with the assets base URL in production builds. This ensures images work correctly when served from a CDN.
+
+### Runtime Updates
+
+The meta state can be updated at runtime via `kmClient.metaStore`:
+
+```typescript
+await kmClient.transact([kmClient.metaStore], ([meta]) => {
+  meta.title = "Game Room: Epic Battle";
+  meta.ogImage = "https://example.com/custom-preview.png";
+});
+```
 
 ## Dev Frame
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokimoki/kit",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,6 +26,7 @@
     "bson-objectid": "^2.0.4",
     "colorjs.io": "^0.5.2",
     "colornames": "^1.1.1",
+    "node-html-parser": "^7.0.1",
     "yaml": "^2.7.0",
     "zod": "^4.3.5"
   },