@kokimoki/kit 1.6.7 → 1.8.0

package/docs/kokimoki-kit.instructions.md

@@ -0,0 +1,389 @@
+---
+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             |
+| `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
+
+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.8.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",
@@ -24,10 +26,16 @@
     "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": "^3.25.30"
+    "zod": "^4.3.5"
   },
   "peerDependencies": {
     "vite": ">=4 <=6"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
   }
 }