@kokimoki/kit 1.6.6 → 1.7.0

package/dist/schema-builder.js

@@ -1,166 +1,183 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Form = exports.FormArray = exports.FormGroup = exports.FloatField = exports.IntegerField = exports.EnumField = exports.TextField = exports.ImageField = exports.ConstField = exports.BooleanField = exports.Field = void 0;
+exports.Form =
+  exports.FormArray =
+  exports.FormGroup =
+  exports.FloatField =
+  exports.IntegerField =
+  exports.EnumField =
+  exports.TextField =
+  exports.ImageField =
+  exports.ConstField =
+  exports.BooleanField =
+  exports.Field =
+    void 0;
 const defaultFieldOptions = {};
 class Field {
-    options;
-    constructor(options) {
-        this.options = options;
-    }
+  options;
+  constructor(options) {
+    this.options = options;
+  }
 }
 exports.Field = Field;
 class BooleanField extends Field {
-    value;
-    constructor(value, options = defaultFieldOptions) {
-        super(options);
-        this.value = value;
-    }
-    get schema() {
-        return {
-            type: "boolean",
-            default: this.value,
-        };
-    }
+  value;
+  constructor(value, options = defaultFieldOptions) {
+    super(options);
+    this.value = value;
+  }
+  get schema() {
+    return {
+      type: "boolean",
+      default: this.value,
+    };
+  }
 }
 exports.BooleanField = BooleanField;
 class ConstField extends Field {
-    value;
-    constructor(value, options = defaultFieldOptions) {
-        super(options);
-        this.value = value;
-    }
-    get schema() {
-        return {
-            const: this.value,
-        };
-    }
+  value;
+  constructor(value, options = defaultFieldOptions) {
+    super(options);
+    this.value = value;
+  }
+  get schema() {
+    return {
+      const: this.value,
+    };
+  }
 }
 exports.ConstField = ConstField;
 class ImageField extends Field {
-    value;
-    constructor(value, options = defaultFieldOptions) {
-        super(options);
-        this.value = value;
-    }
-    get schema() {
-        return {
-            type: "string",
-            default: this.value,
-        };
-    }
+  value;
+  constructor(value, options = defaultFieldOptions) {
+    super(options);
+    this.value = value;
+  }
+  get schema() {
+    return {
+      type: "string",
+      default: this.value,
+    };
+  }
 }
 exports.ImageField = ImageField;
 class TextField extends Field {
-    value;
-    constructor(value, options = defaultFieldOptions) {
-        super(options);
-        this.value = value;
-    }
-    get schema() {
-        return {
-            type: "string",
-            default: this.value,
-        };
-    }
+  value;
+  constructor(value, options = defaultFieldOptions) {
+    super(options);
+    this.value = value;
+  }
+  get schema() {
+    return {
+      type: "string",
+      default: this.value,
+    };
+  }
 }
 exports.TextField = TextField;
 class EnumField extends Field {
-    enumValues;
-    value;
-    constructor(enumValues, value, options = defaultFieldOptions) {
-        super(options);
-        this.enumValues = enumValues;
-        this.value = value;
-    }
-    get schema() {
-        return {
-            enum: Object.keys(this.enumValues),
-        };
-    }
+  enumValues;
+  value;
+  constructor(enumValues, value, options = defaultFieldOptions) {
+    super(options);
+    this.enumValues = enumValues;
+    this.value = value;
+  }
+  get schema() {
+    return {
+      enum: Object.keys(this.enumValues),
+    };
+  }
 }
 exports.EnumField = EnumField;
 class IntegerField extends Field {
-    value;
-    constructor(value, options = defaultFieldOptions) {
-        super(options);
-        this.value = value;
-    }
-    get schema() {
-        return {
-            type: "integer",
-            default: this.value,
-        };
-    }
+  value;
+  constructor(value, options = defaultFieldOptions) {
+    super(options);
+    this.value = value;
+  }
+  get schema() {
+    return {
+      type: "integer",
+      default: this.value,
+    };
+  }
 }
 exports.IntegerField = IntegerField;
 class FloatField extends Field {
-    value;
-    constructor(value, options = defaultFieldOptions) {
-        super(options);
-        this.value = value;
-    }
-    get schema() {
-        return {
-            type: "number",
-            default: this.value,
-        };
-    }
+  value;
+  constructor(value, options = defaultFieldOptions) {
+    super(options);
+    this.value = value;
+  }
+  get schema() {
+    return {
+      type: "number",
+      default: this.value,
+    };
+  }
 }
 exports.FloatField = FloatField;
 class FormGroup extends Field {
-    requiredFields;
-    optionalFields;
-    constructor(requiredFields, optionalFields = {}, options = defaultFieldOptions) {
-        super(options);
-        this.requiredFields = requiredFields;
-        this.optionalFields = optionalFields;
-    }
-    get value() {
-        const value = Object.entries(this.requiredFields).reduce((acc, [key, field]) => {
-            acc[key] = field.value;
-            return acc;
-        }, {});
-        Object.entries(this.optionalFields).forEach(([key, field]) => {
-            if (field.value !== undefined) {
-                value[key] = field.value;
-            }
-        });
-        return value;
-    }
-    get schema() {
-        const properties = {};
-        Object.entries(this.requiredFields).forEach(([key, field]) => {
-            properties[key] = field.schema;
-        });
-        Object.entries(this.optionalFields).forEach(([key, field]) => {
-            properties[key] = field.schema;
-        });
-        return {
-            type: "object",
-            properties,
-            required: Object.keys(this.requiredFields),
-        };
-    }
+  requiredFields;
+  optionalFields;
+  constructor(
+    requiredFields,
+    optionalFields = {},
+    options = defaultFieldOptions,
+  ) {
+    super(options);
+    this.requiredFields = requiredFields;
+    this.optionalFields = optionalFields;
+  }
+  get value() {
+    const value = Object.entries(this.requiredFields).reduce(
+      (acc, [key, field]) => {
+        acc[key] = field.value;
+        return acc;
+      },
+      {},
+    );
+    Object.entries(this.optionalFields).forEach(([key, field]) => {
+      if (field.value !== undefined) {
+        value[key] = field.value;
+      }
+    });
+    return value;
+  }
+  get schema() {
+    const properties = {};
+    Object.entries(this.requiredFields).forEach(([key, field]) => {
+      properties[key] = field.schema;
+    });
+    Object.entries(this.optionalFields).forEach(([key, field]) => {
+      properties[key] = field.schema;
+    });
+    return {
+      type: "object",
+      properties,
+      required: Object.keys(this.requiredFields),
+    };
+  }
 }
 exports.FormGroup = FormGroup;
 class FormArray extends Field {
-    factory;
-    value;
-    constructor(factory, value, options = defaultFieldOptions) {
-        super(options);
-        this.factory = factory;
-        this.value = value;
-    }
-    get schema() {
-        const field = this.factory();
-        return {
-            type: "array",
-            items: field.schema,
-            default: this.value,
-        };
-    }
+  factory;
+  value;
+  constructor(factory, value, options = defaultFieldOptions) {
+    super(options);
+    this.factory = factory;
+    this.value = value;
+  }
+  get schema() {
+    const field = this.factory();
+    return {
+      type: "array",
+      items: field.schema,
+      default: this.value,
+    };
+  }
 }
 exports.FormArray = FormArray;
-class Form extends FormGroup {
-}
+class Form extends FormGroup {}
 exports.Form = Form;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const KOKIMOKI_KIT_VERSION = "1.6.6";
+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.6";
+exports.KOKIMOKI_KIT_VERSION = "1.7.0";

package/dist/zod.d.ts

@@ -0,0 +1 @@
+export { z, type ZodType } from "zod/v4";

package/dist/zod.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.z = void 0;
+var v4_1 = require("zod/v4");
+Object.defineProperty(exports, "z", { enumerable: true, get: function () { return v4_1.z; } });

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.