@kokimoki/kit 1.6.7 → 1.7.0

package/dist/production-loading-screen.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Production loading screen HTML/CSS/JS for kokimoki-kit plugin.
+ * 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;
+/**
+ * Loading screen styles
+ */
+exports.loadingScreenStyles = `
+<style id="km-loading-style">
+  #km-loading {
+    position: fixed;
+    inset: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 1.5rem;
+    background: #fff;
+    z-index: 9999;
+    transition: opacity 0.3s ease-out;
+    color: #1a1a2e;
+    text-decoration: none;
+  }
+  #km-loading.km-ready {
+    opacity: 0;
+    pointer-events: none;
+  }
+  #km-loading .km-spinner {
+    height: 2rem;
+    animation: km-spin 1s linear infinite;
+  }
+  #km-loading .km-logo {
+    height: 3rem;
+  }
+  #km-loading .km-powered {
+    font-size: 0.75rem;
+    font-weight: 600;
+    opacity: 0.65;
+    font-family: system-ui, -apple-system, sans-serif;
+  }
+  @keyframes km-spin {
+    to { transform: rotate(360deg); }
+  }
+</style>`;
+/**
+ * km:ready listener script with 3s minimum display time
+ */
+exports.loadingScreenScript = `
+<script>
+  (function() {
+    var startTime = Date.now();
+    var minDisplayTime = 3000;
+    var appReady = false;
+    
+    function hideLoading() {
+      var el = document.getElementById('km-loading');
+      var style = document.getElementById('km-loading-style');
+      if (el) {
+        el.classList.add('km-ready');
+        setTimeout(function() {
+          el.remove();
+          if (style) style.remove();
+        }, 300);
+      }
+    }
+    
+    function tryHide() {
+      if (!appReady) return;
+      var elapsed = Date.now() - startTime;
+      var remaining = Math.max(0, minDisplayTime - elapsed);
+      setTimeout(hideLoading, remaining);
+    }
+    
+    window.addEventListener('message', function(e) {
+      if (e.data === 'km:ready' && !appReady) {
+        appReady = true;
+        tryHide();
+      }
+    });
+  })();
+</script>`;
+/**
+ * Loading screen HTML element with Games for Crowds branding
+ */
+exports.loadingScreenElement = `<a href="https://gamesforcrowds.com" target="_blank" id="km-loading">
+  <svg class="km-spinner" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+    <path fill="currentColor" d="M12 22q-2.05 0-3.875-.788t-3.187-2.15t-2.15-3.187T2 12q0-2.075.788-3.887t2.15-3.175t3.187-2.15T12 2q.425 0 .713.288T13 3t-.288.713T12 4Q8.675 4 6.337 6.338T4 12t2.338 5.663T12 20t5.663-2.337T20 12q0-.425.288-.712T21 11t.713.288T22 12q0 2.05-.788 3.875t-2.15 3.188t-3.175 2.15T12 22"/>
+  </svg>
+  <svg class="km-logo" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 797.59 219.07" fill="currentColor">
+    <g>
+      <path d="M162.8,96.03c30.87-26.51,10.41-92.22-28.46-95.03-29.39-2.13-60.31-.26-90.99.07-.73,0-1.45-.02-2.17.09C20.3,4.26,3.91,21.33.05,41.8l-.05,123.54c2.6,4.28,5.58,6,10.54,3.94,6.74-3.82,26.58-29.17,31.77-30.22,1.69-.34,3.72.1,5.48-.03-1.15,26.53,19.87,47.52,45.62,49.88,10.24.94,31.34-1.93,39.43.57,8.71,2.7,26.57,28.84,33.53,29.55,3.29.34,7.74-2.14,8.38-5.52,1.72-9.15-2.16-26.7.23-34.77.33-1.1,7.39-8.47,9.02-10.98,16.21-24.98,7.36-61.07-21.22-71.74ZM50.83,121.59l-15.96,2.04-19.08,18.42V46.55c1.67-14.1,15.14-27.27,28.74-30.26,27.33,1.33,57.83-2.6,84.8-.28,20.06,1.73,36.5,34.92,31,55.08-7.53,27.65-45.72,17.08-67.02,18.97-18.52,1.65-36.21,13.88-42.47,31.53ZM170.32,159.08c-1.85,3-10.53,10.69-10.53,11.47v20.5c-1.75.44-2-.72-3.01-1.49-5.71-4.38-11.7-14.4-18.92-16.08-20.43-4.73-47.91,7.68-65.09-10.9-16.98-18.36-8.23-50.63,16.23-55.82,10.35-2.2,44.8-1.74,56.33-.74,24.82,2.14,38.05,31.97,25,53.07Z"/>
+      <polygon points="573.74 181.88 556.14 122.98 538.69 122.81 519.73 181.89 501.74 122.88 481.24 122.88 508.73 212.9 525.78 213.95 527.35 213.29 545.25 152.88 564.73 212.9 583.28 213.42 611.24 122.88 590.24 122.88 573.74 181.88"/>
+      <path d="M666.74,122.88c-13.74-1.63-30.44,1.21-44.5,0v91h40.5c2.92,0,11.75-2.85,14.86-4.14,38.57-16.14,31.3-81.86-10.86-86.86ZM678.08,187.22c-2.88,4.2-11.41,9.66-16.34,9.66h-20.5v-58c6.18.55,13.48-.75,19.5,0,22.38,2.79,28.85,31.55,17.34,48.34Z"/>
+      <path d="M425,121.14c-41.35,5.24-51.11,67.28-16.45,87.94,28.45,16.96,67.81.39,70.73-33.66,2.97-34.62-18.81-58.77-54.28-54.28ZM427.98,198.64c-27.94-4.46-28.04-57.3,1.02-61.5,40.78-5.9,43.14,68.55-1.02,61.5Z"/>
+      <path d="M363.48,127.14c-1.58-.84-10.61-4.26-11.74-4.26h-41.5v91h19v-33l11.58.92,18.92,32.08h21.5l-20.99-35.44c19.78-8.94,22.88-40.88,3.23-51.3ZM355.77,157.91c-1.32,4.05-6.98,7.97-11.02,7.97h-15.5v-27c5.36.62,12.39-.85,17.5,0,9.11,1.51,11.57,11.21,9.02,19.03Z"/>
+      <path d="M777.02,179.61c-3.95-19.44-32.26-17.78-42.74-26.26-5.4-4.37-4.24-12.34,1.69-15.23,9.47-4.61,20.58,1.49,27.6,7.63l12.65-9.36c-10.04-12.51-23.17-17.41-39.22-15.24-28.56,3.86-35.71,38.53-7.02,50.5,9.33,3.89,33.09,5.53,28.6,20.07-3.99,12.93-29.66,6.57-35.83-2.65l-12.44,11.18c19.81,25.44,74.88,19.65,66.7-20.64Z"/>
+      <path d="M267.5,198.64c-41.37,7.02-43.83-58.8-9.75-61.75,10.54-.91,17.28,3.56,24.13,10.88l14.35-7.92c-9.32-19.99-38.11-23.5-56.51-14.99-32.89,15.21-33.7,69.52-.86,85.89,19.28,9.61,48.03,5.78,58.38-14.86l-12.64-7.94c-5.5,3.74-10.09,9.5-17.1,10.69Z"/>
+      <path d="M433.4,44.09l21.29,35.46c2.72,2.8,9.85,1.78,13.55,1.07l22.47-37.65v59.55h21.35V4.76l-20.8,1.11-27.53,50.58-29.76-51.69h-20.79v97.76h20.23v-58.43Z"/>
+      <path d="M306.43,48.58h-42.7v16.85h21.35c-.27,13.22-7.04,21.88-20.74,22.52-41.54,1.94-38.23-76.19,5.07-66.97,7.84,1.67,10.69,7.85,16.21,11.88l15.05-8.01c-.07-9-13.02-17.18-20.95-19.79-43.1-14.17-73.97,23.73-63.98,65.1,11.75,48.67,85.6,47.68,90.69-4.17.54-5.55-.39-11.78,0-17.42Z"/>
+      <path d="M340.09,81.68l33.82-.02,6.67,20.85h23.6L368.81,5.87c-1.88-2.26-20.12-1.02-24.2-.56l-34.81,97.22h23.6l6.7-20.83ZM356.43,29.47l10.67,34.84h-21.35l10.67-34.84Z"/>
+      <polygon points="590.71 84.54 551.39 84.54 551.39 60.94 585.1 60.94 585.1 42.96 551.39 42.96 551.39 22.74 588.47 22.74 588.47 4.76 530.04 4.76 530.04 102.52 590.71 102.52 590.71 84.54"/>
+      <path d="M608.77,97.39c25.08,16.57,67.45,5.44,61.46-30-1.89-11.15-12.36-17.09-21.93-20.77-7.64-2.94-35.54-8.52-22.36-22.37,8.09-8.51,23.15-1.69,30.32,5.07,2.52-1.37,13.45-9.1,13.04-11.48-14.3-20.97-60.08-20.5-65.72,7.08-2.89,14.13,1.82,25,14.48,31.72,10.24,5.44,38.71,7.15,31.37,24.24-3.47,8.09-18.1,7.13-25,4.22-4.16-1.76-9.85-8.71-12.66-8.29-2.01.3-13.33,8.46-13.03,10.32.38,2.39,7.73,8.73,10.04,10.25Z"/>
+    </g>
+    <g>
+      <path fill="#3c63e7" d="M735,55.98c-24.25,4.14-27.28,47.44,1.59,47.65,31.23.23,35.57-53.99-1.59-47.65ZM734.29,92.39c-9.51-2.94-5.29-24.14,2.49-26.5,16.88-5.12,14.38,31.73-2.49,26.5Z"/>
+      <path fill="#3c63e7" d="M716.28,56.67c-3.34-.27-7.15.39-10.41,0-1.21-.14-1.64.47-1.24-1.25,1.77-7.6,5.49-10.69,13.44-7.79l.86-10.79c-14.12-3.91-26.67,3.85-26.53,18.98l-8.25,1.69-1.3,9.08,8.13.02-3.61,36.13,12.26-.85,4.05-35.24h11.1c1.99-.47,1.49-8.28,1.51-9.99Z"/>
+      <path fill="#3c63e7" d="M796.72,56.17c-6.86-1.78-12.48,2-15.87,7.73l.45-7.22h-11.74s-4.51,46.06-4.51,46.06h12.65c2.16-13.01-1.47-38.8,18.96-34.32-.94-2.92,2.45-10.57.06-12.25Z"/>
+    </g>
+  </svg>
+  <p class="km-powered">Powered by Kokimoki</p>
+</a>`;
+/**
+ * Removes any existing km-loading elements from HTML
+ */
+function removeExistingLoadingScreen(html) {
+    return html
+        .replace(/<div[^>]*id=["']km-loading["'][^>]*>[\s\S]*?<\/div>/gi, "")
+        .replace(/<style[^>]*id=["']km-loading-style["'][^>]*>[\s\S]*?<\/style>/gi, "");
+}

package/dist/version.d.ts

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

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.6.7";
+exports.KOKIMOKI_KIT_VERSION = "1.7.0";

package/docs/kokimoki-kit.instructions.md

@@ -0,0 +1,341 @@
+---
+description: Vite plugin and development tools for Kokimoki apps
+applyTo: "**/vite.config.{ts,js,mts,mjs}"
+---
+
+# Kokimoki Kit
+
+The `@kokimoki/kit` package provides the Vite plugin and development tools for building Kokimoki apps.
+
+## Installation
+
+```bash
+npm install @kokimoki/kit
+```
+
+## Plugin Configuration
+
+Add the plugin to your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from "vite";
+import { kokimokiKitPlugin } from "@kokimoki/kit";
+import { z } from "@kokimoki/kit";
+
+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" } },
+        ],
+      ],
+    }),
+  ],
+});
+```
+
+## Configuration Options
+
+### Required Options
+
+| Option        | Type     | Description                       |
+| ------------- | -------- | --------------------------------- |
+| `conceptId`   | `string` | Your concept ID from Kokimoki     |
+| `deployCodes` | `array`  | List of deployment configurations |
+
+### 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                 |
+
+## Dev Frame
+
+The dev frame provides a multi-window view for testing different player modes simultaneously during development.
+
+### Configuration
+
+```typescript
+devView: [
+  // Row 1: Host and presenter
+  [
+    { label: "host", clientContext: { mode: "host", playerCode: "admin" } },
+    { label: "presenter", clientContext: { mode: "presenter" } },
+  ],
+  // Row 2: Three players
+  [
+    { label: "player1", clientContext: { mode: "player" } },
+    { label: "player2", clientContext: { mode: "player" } },
+    { label: "player3", clientContext: { mode: "player" } },
+  ],
+];
+```
+
+### DevFrameCell Interface
+
+```typescript
+interface DevFrameCell {
+  /** Label shown in the frame header (must be unique) */
+  label: string;
+  /** Client context passed to the app via URL */
+  clientContext: unknown;
+}
+```
+
+### Features
+
+- **Grid layout**: Each inner array is a row of frames
+- **Unique labels**: Each cell must have a unique label
+- **New tab button**: Open any frame in a separate tab
+- **Reset button**: Clear frame's local storage and reload
+- **Error overlay**: Shows errors with reload option
+
+### Disabling Dev Frame
+
+Set `devView: false` to disable the dev frame entirely:
+
+```typescript
+kokimokiKitPlugin({
+  conceptId: "...",
+  deployCodes: [...],
+  devView: false,
+})
+```
+
+## Store Schemas
+
+Define schemas to validate store state during development:
+
+```typescript
+stores: [
+  // Global store - shared across all clients
+  {
+    pattern: "game",
+    schema: z.object({
+      status: z.enum(["waiting", "playing", "finished"]),
+      players: z.record(
+        z.string(),
+        z.object({
+          name: z.string(),
+          score: z.number(),
+        })
+      ),
+    }),
+  },
+
+  // Wildcard pattern - matches player-abc123, player-xyz789, etc.
+  {
+    pattern: "player-*",
+    schema: z.object({
+      name: z.string(),
+      avatar: z.string().optional(),
+    }),
+    local: true, // Local store (client-specific)
+  },
+
+  // Dynamic stores - chat rooms, teams, etc.
+  {
+    pattern: "chat-*",
+    schema: z.object({
+      messages: z.record(
+        z.string(),
+        z.object({
+          text: z.string(),
+          sender: z.string(),
+        })
+      ),
+    }),
+  },
+];
+```
+
+## i18n Integration
+
+The plugin syncs translations to your dev app automatically.
+
+### Folder Structure
+
+```
+src/i18n/
+├── en/
+│   ├── ui.json
+│   └── game.json
+├── et/
+│   ├── ui.json
+│   └── game.json
+└── de/
+    ├── ui.json
+    └── game.json
+```
+
+### Configuration
+
+```typescript
+kokimokiKitPlugin({
+  // ...
+  i18nPath: "./src/i18n",
+  i18nPrimaryLng: "en", // Source language for AI translations
+});
+```
+
+### HMR Support
+
+- Translation files are watched for changes
+- Changes are synced to the dev app in real-time
+- No need to restart the dev server
+
+## Zod Re-export
+
+The kit re-exports Zod for convenience:
+
+```typescript
+import { z } from "@kokimoki/kit";
+
+const mySchema = z.object({
+  name: z.string(),
+  count: z.number(),
+});
+```
+
+## Project Files
+
+### .kokimoki Directory
+
+The plugin creates a `.kokimoki` directory in your project root:
+
+```
+.kokimoki/
+├── app-id        # Dev app ID (cached)
+└── stores-hash   # Hash of store schemas (for change detection)
+```
+
+**Add to `.gitignore`:**
+
+```gitignore
+.kokimoki/
+```
+
+### Credentials
+
+Global credentials are stored in `~/.kokimoki`:
+
+```json
+{
+  "apiKeys": {
+    "org-id-1": "api-key-1",
+    "org-id-2": "api-key-2"
+  }
+}
+```
+
+Use `npx @kokimoki/cli login` to authenticate.
+
+## Style Preprocessing
+
+The plugin processes CSS files with theme color variables:
+
+- Converts color names to hex values
+- Generates RGB tuple variables for opacity support
+- Processes palette color scales (50-900)
+
+### Supported Variables
+
+```css
+:root {
+  --color-primary-500: #3b82f6;
+  --color-secondary-500: #10b981;
+  --on-primary: 255 255 255;
+  --on-secondary: 255 255 255;
+}
+```
+
+## Production Build
+
+During production builds, the plugin:
+
+1. Validates all store schemas
+2. Generates production loading screen
+3. Embeds i18n metadata for runtime loading
+4. Removes dev frame and development overlays
+
+## Error Handling
+
+### Common Errors
+
+| Error                 | Cause              | Solution                         |
+| --------------------- | ------------------ | -------------------------------- |
+| `CONCEPT_NOT_FOUND`   | Invalid concept ID | Check your `conceptId` in config |
+| `NO_CREDENTIALS`      | Not logged in      | Run `npx @kokimoki/cli login`    |
+| `DEV_APP_INIT_FAILED` | API error          | Check network and API endpoint   |
+
+### Store Schema Changes
+
+If you change store schemas, the plugin detects this and shows a warning page with two options:
+
+- **Keep Current State**: Dismiss the warning and continue with existing data
+- **Reset State**: Clear the dev app state and localStorage to start fresh
+
+No dev server restart is required.

package/llms.txt

@@ -0,0 +1,46 @@
+# Kokimoki Kit Documentation
+
+> Documentation for @kokimoki/kit - Vite plugin and development tools for Kokimoki apps.
+
+## Instruction Files
+
+The following instruction files provide detailed guidance for AI assistants:
+
+### Plugin Configuration
+- docs/kokimoki-kit.instructions.md: Complete guide to configuring the Vite plugin, including dev frame setup, store schemas, i18n integration, and style preprocessing.
+
+## Key Concepts
+
+- **kokimokiKitPlugin**: Vite plugin that integrates Kokimoki into your build
+- **conceptId**: Unique identifier for your Kokimoki project/concept
+- **deployCodes**: Named configurations for different deployment scenarios
+- **devView**: Multi-window grid layout for development testing
+- **stores**: Schema definitions for validating store state
+- **i18nPath**: Folder path for translation files with auto-sync
+
+## Configuration Structure
+
+```typescript
+kokimokiKitPlugin({
+  conceptId: string,           // Required
+  deployCodes: DeployCode[],   // Required
+  schema?: ZodType,            // Project config schema
+  stores?: StoreConfig[],      // Store schemas
+  i18nPath?: string,           // i18n folder path
+  i18nPrimaryLng?: string,     // Source language (default: 'en')
+  devView?: DevFrameCell[][] | false,  // Dev frame layout
+  endpoint?: string,           // API endpoint
+  host?: string,               // WebSocket host
+})
+```
+
+## Related Packages
+
+- @kokimoki/app: Core SDK for runtime (stores, transactions, AI, storage, i18n, leaderboard)
+- @kokimoki/cli: CLI for project creation, login, and deployment
+
+## File Patterns
+
+Instruction files use YAML frontmatter with:
+- `description`: Brief description of the file's purpose
+- `applyTo`: Glob pattern for when the instructions apply (e.g., "**/vite.config.{ts,js}")

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@kokimoki/kit",
-  "version": "1.6.7",
+  "version": "1.7.0",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "llms.txt"
   ],
   "scripts": {
     "test": "ts-mocha  src/**/*.spec.ts --exit",
@@ -25,9 +27,14 @@
     "colorjs.io": "^0.5.2",
     "colornames": "^1.1.1",
     "yaml": "^2.7.0",
-    "zod": "^3.25.30"
+    "zod": "^4.3.5"
   },
   "peerDependencies": {
     "vite": ">=4 <=6"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
   }
 }