@kokimoki/app 3.1.3 → 3.1.4

package/dist/utils/valtio.d.ts

@@ -1,7 +1,4 @@
-import "valtio";
-declare module "valtio" {
-    function useSnapshot<T extends object>(p: T): T;
-}
-export { proxy, ref, snapshot, subscribe, useSnapshot } from "valtio";
+export { proxy, ref, snapshot, subscribe } from "valtio";
+export declare const useSnapshot: <T extends object>(p: T) => T;
 export { derive, underive } from "derive-valtio";
 export { devtools, subscribeKey, useProxy, watch } from "valtio/utils";

package/dist/utils/valtio.js

@@ -1,6 +1,8 @@
-import "valtio";
+import { useSnapshot as _useSnapshot } from "valtio";
 // Core Valtio exports
-export { proxy, ref, snapshot, subscribe, useSnapshot } from "valtio";
+export { proxy, ref, snapshot, subscribe } from "valtio";
+// Loosen useSnapshot return type (valtio returns DeepReadonly<T>, which is too strict)
+export const useSnapshot = _useSnapshot;
 // Valtio utilities
 export { derive, underive } from "derive-valtio";
 export { devtools, subscribeKey, useProxy, watch } from "valtio/utils";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const KOKIMOKI_APP_VERSION = "3.1.3";
+export declare const KOKIMOKI_APP_VERSION = "3.1.4";

package/dist/version.js

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

package/docs/kokimoki-ai.instructions.md

@@ -86,7 +86,7 @@ Submits a JSON generation job with Zod schema validation. Use `getJob<T>()` to w
 **Example:**
 
 ```typescript
-import { z } from "zod/v4";
+import { z } from "@kokimoki/app";
 
 // Define schema with Zod
 const enemySchema = z.object({
@@ -205,6 +205,8 @@ if (job.status === "completed") {
 ### Example: Persist Jobs Across Page Reloads
 
 ```typescript
+import { snapshot } from "@kokimoki/app";
+
 // Store jobId in local store for persistence
 const { jobId } = await kmClient.ai.generateJson({
   schema: questSchema,
@@ -216,7 +218,7 @@ await kmClient.transact([localStore], ([state]) => {
 });
 
 // On page load, resume polling if job is pending
-const pendingJobId = localStore.proxy.pendingQuestJobId;
+const pendingJobId = snapshot(localStore.proxy).pendingQuestJobId;
 if (pendingJobId) {
   const quest = await kmClient.ai.pollJson(pendingJobId, {
     schema: questSchema,

package/docs/kokimoki-dynamic-stores.instructions.md

@@ -133,7 +133,7 @@ export function useDynamicStore<T extends object>(
 ## Basic Usage
 
 ```tsx
-import { useSnapshot } from "valtio";
+import { useSnapshot } from "@kokimoki/app";
 import { useDynamicStore } from "@/hooks/useDynamicStore";
 
 interface RoomState {
@@ -350,7 +350,7 @@ const BreakoutRoom = ({ roomId }: { roomId: string }) => {
 
 ## File Organization
 
-**ALWAYS** organize dynamic store code using the standard store/actions pattern:
+**ALWAYS** organize dynamic store code using the standard state/actions pattern:
 
 **State definition** (`src/state/chat-store.ts`):
 
@@ -408,7 +408,7 @@ export const chatActions = {
 **Usage in component** (`src/views/chat-view.tsx`):
 
 ```tsx
-import { useSnapshot } from "valtio";
+import { useSnapshot } from "@kokimoki/app";
 import { useDynamicStore } from "@/hooks/useDynamicStore";
 import { createChatState, type ChatState } from "@/state/chat-store";
 import { chatActions } from "@/state/actions/chat-actions";

package/docs/kokimoki-i18n.instructions.md

@@ -141,7 +141,7 @@ type TranslationStatus = "available" | "processing" | "failed";
 ```typescript
 const status = await kmClient.i18n.requestTranslation("de");
 
-if (status === "already_available") {
+if (status === "available") {
   // Already translated, switch immediately
   i18next.changeLanguage("de");
 } else {

package/docs/kokimoki-sdk.instructions.md

@@ -16,7 +16,9 @@ The Kokimoki SDK is a comprehensive development toolkit for building real-time c
 - Use `kmClient.transact` for atomic state updates across single store or multiple stores
 - Use `kmClient.storage.upload` and related API methods to handle file uploads (media, JSON, etc.) in application
 - Use `kmClient.serverTimestamp()` for time-related matters as this will be synced among players
-- Use `useSnapshot` hook from `valtio` to get reactive state inside React components
+- Use `useSnapshot` hook to get reactive state inside React components — import from `@kokimoki/app` (re-exports valtio)
+- Use `snapshot` function to read immutable state outside React components (in actions, event handlers, etc.) — import from `@kokimoki/app` — **NEVER** read directly from `store.proxy.field`
+- Use `z` and `ZodType` from `@kokimoki/app` for schema definitions (re-exports zod)
 - Use AI integration API methods: `kmClient.ai.generateText`, `kmClient.ai.generateJson`, and `kmClient.ai.generateImage` with corresponding poll methods for AI capabilities
 - Use i18n API methods: `kmClient.i18n.createI18n`, `kmClient.i18n.init`, and `kmClient.i18n.requestTranslation` for internationalization with AI-powered translations
 - Use leaderboard API methods: `kmClient.leaderboard.insertEntry`, `kmClient.leaderboard.upsertEntry`, `kmClient.leaderboard.listEntries`, and `kmClient.leaderboard.getBestEntry` to add leaderboard capabilities to application
@@ -118,13 +120,13 @@ await kmClient.transact([store1, store2], ([state1, state2]) => {
 
 ### Reactive State in Components
 
-- Use `useSnapshot` hook from `valtio` to get reactive state inside React components
+- Use `useSnapshot` hook to get reactive state inside React components (import from `@kokimoki/app`)
 - The component will re-render when the store state changes
 
 **Example: Using State in Components**
 
 ```tsx
-import { useSnapshot } from "valtio";
+import { useSnapshot } from "@kokimoki/app";
 import { store } from "../store";
 
 const Component = () => {
@@ -140,6 +142,44 @@ const Component = () => {
 };
 ```
 
+### Reading State Outside Components
+
+When reading state **outside React components** (in store actions, event handlers, initialization logic), use `snapshot()` from `@kokimoki/app` to get an immutable copy.
+**NEVER** read directly from `store.proxy` — the proxy is mutable and values can change between read and use.
+
+```typescript
+import { snapshot } from "@kokimoki/app";
+
+// WRONG — mutable proxy, value can change unexpectedly
+const value = store.proxy.someField;
+
+// CORRECT — immutable snapshot, safe to use
+const value = snapshot(store.proxy).someField;
+```
+
+**Example: Reading state in an store actions**
+
+```typescript
+import { snapshot } from "@kokimoki/app";
+
+// Action function that reads state and updates it based on conditions
+async function doSomething() {
+  const { count, completed } = snapshot(store.proxy);
+
+  if (count > 10 && !completed) {
+    await kmClient.transact([store], ([state]) => {
+      state.completed = true;
+    });
+  }
+}
+```
+
+### Common Patterns
+
+- **Inside React components** → `useSnapshot(store.proxy)` (reactive, triggers re-renders)
+- **Outside React components** → `snapshot(store.proxy)` (immutable, read-only)
+- **Writing state** → Always use `kmClient.transact()` (never assign to proxy directly)
+
 ## Dynamic Stores
 
 For room-based state isolation (teams, chat rooms, breakout rooms), see [Dynamic Stores](./kokimoki-dynamic-stores.instructions.md).
@@ -166,7 +206,7 @@ Each Kokimoki store has a `connections` property that provides real-time presenc
 ### Example: Track Online Players
 
 ```tsx
-import { useSnapshot } from "valtio";
+import { useSnapshot } from "@kokimoki/app";
 import { globalStore } from "@/state/stores/global-store";
 
 const Component = () => {
@@ -186,7 +226,7 @@ const Component = () => {
 ### Example: Display Player List with Online Status
 
 ```tsx
-import { useSnapshot } from "valtio";
+import { useSnapshot } from "@kokimoki/app";
 import { globalStore } from "@/state/stores/global-store";
 
 const PlayerList = () => {
@@ -231,8 +271,7 @@ Store names with the `__km/` prefix are reserved for SDK internal use. Do not cr
 ### Using App Meta
 
 ```tsx
-import { getKmClient } from "@kokimoki/app";
-import { useSnapshot } from "valtio";
+import { useSnapshot, getKmClient } from "@kokimoki/app";
 
 const kmClient = getKmClient();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokimoki/app",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "type": "module",
   "description": "Kokimoki app",
   "main": "dist/index.js",
@@ -19,17 +19,23 @@
     "prebuild": "node scripts/generate-version.js",
     "build": "tsc",
     "dev": "tsc -w",
-    "docs": "typedoc src/index.ts"
+    "docs": "typedoc src/index.ts",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
   },
   "author": "Loquiz OÜ",
   "license": "Apache-2.0",
   "devDependencies": {
+    "eslint-config": "*",
     "@types/chai": "^4",
     "@types/mocha": "^10",
     "@types/node": "^18",
     "@types/ws": "^8.5.5",
     "bson-objectid": "^2.0.4",
     "chai": "^4",
+    "eslint": "^9.39.1",
+    "eslint-plugin-chai-friendly": "^1.1.0",
+    "eslint-plugin-valtio": "^0.8.0",
     "mocha": "^10",
     "ts-node": "^10",
     "tsx": "^4",

package/dist/fields.d.ts

@@ -1,110 +0,0 @@
-export interface FieldOptions {
-  label?: string;
-}
-export declare abstract class Field<T> {
-  readonly options: FieldOptions;
-  constructor(options: FieldOptions);
-  abstract get value(): T;
-  abstract get schema(): any;
-}
-export declare class BooleanField extends Field<boolean> {
-  value: boolean;
-  constructor(value: boolean, options?: FieldOptions);
-  get schema(): {
-    type: string;
-    default: boolean;
-  };
-}
-export declare class ConstField<T extends string> extends Field<
-  string extends T ? never : T
-> {
-  value: string extends T ? never : T;
-  constructor(value: string extends T ? never : T, options?: FieldOptions);
-  get schema(): {
-    const: string extends T ? never : T;
-  };
-}
-export declare class ImageField extends Field<string> {
-  value: string;
-  constructor(value: string, options?: FieldOptions);
-  get schema(): {
-    type: string;
-    default: string;
-  };
-}
-export declare class TextField extends Field<string> {
-  value: string;
-  constructor(value: string, options?: FieldOptions);
-  get schema(): {
-    type: string;
-    default: string;
-  };
-}
-export declare class EnumField<T extends Record<string, string>> extends Field<
-  keyof T
-> {
-  enumValues: T;
-  value: keyof T;
-  constructor(enumValues: T, value: keyof T, options?: FieldOptions);
-  get schema(): {
-    enum: string[];
-  };
-}
-export declare class IntegerField extends Field<number> {
-  value: number;
-  constructor(value: number, options?: FieldOptions);
-  get schema(): {
-    type: string;
-    default: number;
-  };
-}
-export declare class FloatField extends Field<number> {
-  value: number;
-  constructor(value: number, options?: FieldOptions);
-  get schema(): {
-    type: string;
-    default: number;
-  };
-}
-export declare class FormGroup<
-  T extends Record<string, Field<any>>,
-  O extends Record<string, Field<any>>,
-> extends Field<
-  {
-    [key in keyof T]: T[key]["value"];
-  } & Partial<{
-    [key in keyof O]: O[key]["value"];
-  }>
-> {
-  requiredFields: T;
-  optionalFields: O;
-  constructor(requiredFields: T, optionalFields?: O, options?: FieldOptions);
-  get value(): {
-    [key in keyof T]: T[key]["value"];
-  } & Partial<{
-    [key in keyof O]: O[key]["value"];
-  }>;
-  get schema(): {
-    type: string;
-    properties: any;
-    required: string[];
-  };
-}
-export declare class FormArray<T> extends Field<T[]> {
-  private factory;
-  value: Field<T>["value"][];
-  constructor(
-    factory: () => Field<T>,
-    value: Field<T>["value"][],
-    options?: FieldOptions,
-  );
-  get schema(): {
-    type: string;
-    items: any;
-    default: T[];
-  };
-}
-export declare class Form<
-  R extends Record<string, Field<any>>,
-  O extends Record<string, Field<any>>,
-> extends FormGroup<R, O> {}

package/dist/fields.js

@@ -1,158 +0,0 @@
-const defaultFieldOptions = {};
-export class Field {
-  options;
-  constructor(options) {
-    this.options = options;
-  }
-}
-export class BooleanField extends Field {
-  value;
-  constructor(value, options = defaultFieldOptions) {
-    super(options);
-    this.value = value;
-  }
-  get schema() {
-    return {
-      type: "boolean",
-      default: this.value,
-    };
-  }
-}
-export class ConstField extends Field {
-  value;
-  constructor(value, options = defaultFieldOptions) {
-    super(options);
-    this.value = value;
-  }
-  get schema() {
-    return {
-      const: this.value,
-    };
-  }
-}
-export class ImageField extends Field {
-  value;
-  constructor(value, options = defaultFieldOptions) {
-    super(options);
-    this.value = value;
-  }
-  get schema() {
-    return {
-      type: "string",
-      default: this.value,
-    };
-  }
-}
-export class TextField extends Field {
-  value;
-  constructor(value, options = defaultFieldOptions) {
-    super(options);
-    this.value = value;
-  }
-  get schema() {
-    return {
-      type: "string",
-      default: this.value,
-    };
-  }
-}
-export 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),
-    };
-  }
-}
-export class IntegerField extends Field {
-  value;
-  constructor(value, options = defaultFieldOptions) {
-    super(options);
-    this.value = value;
-  }
-  get schema() {
-    return {
-      type: "integer",
-      default: this.value,
-    };
-  }
-}
-export class FloatField extends Field {
-  value;
-  constructor(value, options = defaultFieldOptions) {
-    super(options);
-    this.value = value;
-  }
-  get schema() {
-    return {
-      type: "number",
-      default: this.value,
-    };
-  }
-}
-export 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),
-    };
-  }
-}
-export 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,
-    };
-  }
-}
-export class Form extends FormGroup {}

package/dist/kokimoki-ai.d.ts

@@ -1,153 +0,0 @@
-import type { Upload } from "./types/upload";
-import { KokimokiClient } from "./kokimoki-client";
-/**
- * Kokimoki AI Integration Service
- *
- * Provides built-in AI capabilities for game applications without requiring API keys or setup.
- * Includes text generation, structured JSON output, and image modification.
- *
- * **Key Features:**
- * - Multiple AI models (GPT-4, GPT-5, Gemini variants)
- * - Text generation with configurable creativity (temperature)
- * - Structured JSON output for game data
- * - AI-powered image modifications
- * - No API keys or configuration required
- *
- * **Common Use Cases:**
- * - Generate dynamic game content (quests, dialogues, stories)
- * - Create AI opponents or NPCs with personalities
- * - Generate quiz questions or trivia
- * - Create game assets (character stats, item descriptions)
- * - Transform user-uploaded images
- * - Generate procedural content
- *
- * Access via `kmClient.ai`
- *
- * @example
- * ```typescript
- * // Generate story text
- * const story = await kmClient.ai.chat({
- *   systemPrompt: 'You are a fantasy story writer',
- *   userPrompt: 'Write a short quest description',
- *   temperature: 0.8
- * });
- *
- * // Generate structured game data
- * interface Enemy {
- *   name: string;
- *   health: number;
- *   attack: number;
- * }
- * const enemy = await kmClient.ai.generateJson<Enemy>({
- *   userPrompt: 'Create a level 5 goblin warrior'
- * });
- *
- * // Transform image
- * const modified = await kmClient.ai.modifyImage(
- *   imageUrl,
- *   'Make it look like pixel art'
- * );
- * ```
- */
-export declare class KokimokiAi {
-    private readonly client;
-    constructor(client: KokimokiClient);
-    /**
-     * Generate a chat response from the AI model.
-     *
-     * Sends a chat request to the AI service and returns the generated response.
-     * Supports multiple AI models including GPT and Gemini variants with configurable
-     * parameters for fine-tuning the response behavior.
-     *
-     * @param req The chat request parameters.
-     * @param req.model Optional. The AI model to use. Defaults to server-side default if not specified.
-     *                  Available models:
-     *                  - `gpt-4o`: OpenAI GPT-4 Optimized
-     *                  - `gpt-4o-mini`: Smaller, faster GPT-4 variant
-     *                  - `gpt-5`: OpenAI GPT-5 (latest)
-     *                  - `gpt-5-mini`: Smaller GPT-5 variant
-     *                  - `gpt-5-nano`: Smallest GPT-5 variant for lightweight tasks
-     *                  - `gemini-2.5-flash-lite`: Google Gemini lite variant
-     *                  - `gemini-2.5-flash`: Google Gemini fast variant
-     * @param req.systemPrompt Optional. The system message that sets the behavior and context for the AI.
-     *                         This helps define the AI's role, personality, and constraints.
-     * @param req.userPrompt The user's message or question to send to the AI.
-     * @param req.temperature Optional. Controls randomness in the response (0.0 to 1.0).
-     *                        Lower values make output more focused and deterministic,
-     *                        higher values make it more creative and varied.
-     * @param req.maxTokens Optional. The maximum number of tokens to generate in the response.
-     *                      Controls the length of the AI's output.
-     *
-     * @returns A promise that resolves to an object containing the AI-generated response.
-     * @returns {string} content The text content of the AI's response.
-     *
-     * @throws An error object if the API request fails.
-     *
-     * @example
-     * ```typescript
-     * const response = await client.ai.chat({
-     *   model: "gpt-4o",
-     *   systemPrompt: "You are a helpful coding assistant.",
-     *   userPrompt: "Explain what TypeScript is in one sentence.",
-     *   temperature: 0.7,
-     *   maxTokens: 100
-     * });
-     * console.log(response.content);
-     * ```
-     */
-    chat(req: {
-        model?: "gpt-4o" | "gpt-4o-mini" | "gpt-5" | "gpt-5-mini" | "gpt-5-nano" | "gemini-2.5-flash-lite" | "gemini-2.5-flash";
-        systemPrompt?: string;
-        userPrompt: string;
-        temperature?: number;
-        maxTokens?: number;
-        responseMimeType?: string;
-    }): Promise<{
-        content: string;
-    }>;
-    /**
-     * Generate structured JSON output from the AI model.
-     *
-     * Sends a chat request to the AI service with the expectation of receiving
-     * a JSON-formatted response. This is useful for scenarios where the output
-     * needs to be parsed or processed programmatically.
-     *
-     * @param req The chat request parameters.
-     * @param req.model Optional. The AI model to use. Defaults to server-side default if not specified.
-     *                  Available models:
-     *                  - `gpt-4o`: OpenAI GPT-4 Optimized
-     *                  - `gpt-4o-mini`: Smaller, faster GPT-4 variant
-     *                  - `gpt-5`: OpenAI GPT-5 (latest)
-     *                  - `gpt-5-mini`: Smaller GPT-5 variant
-     *                  - `gpt-5-nano`: Smallest GPT-5 variant for lightweight tasks
-     *                  - `gemini-2.5-flash-lite`: Google Gemini lite variant
-     *                  - `gemini-2.5-flash`: Google Gemini fast variant
-     * @param req.systemPrompt Optional. The system message that sets the behavior and context for the AI.
-     *                         This helps define the AI's role, personality, and constraints.
-     * @param req.userPrompt The user's message or question to send to the AI.
-     * @param req.temperature Optional. Controls randomness in the response (0.0 to 1.0).
-     *                        Lower values make output more focused and deterministic,
-     *                        higher values make it more creative and varied.
-     * @param req.maxTokens Optional. The maximum number of tokens to generate in the response.
-     *                      Controls the length of the AI's output.
-     *
-     * @returns A promise that resolves to the parsed JSON object generated by the AI.
-     *
-     * @throws An error object if the API request fails or if the response is not valid JSON.
-     */
-    generateJson<T extends object>(req: {
-        model?: "gpt-4o" | "gpt-4o-mini" | "gpt-5" | "gpt-5-mini" | "gpt-5-nano" | "gemini-2.5-flash-lite" | "gemini-2.5-flash";
-        systemPrompt?: string;
-        userPrompt: string;
-        temperature?: number;
-        maxTokens?: number;
-    }): Promise<T>;
-    /**
-     * Modify an image using the AI service.
-     * @param baseImageUrl The URL of the base image to modify.
-     * @param prompt The modification prompt to apply to the image.
-     * @param tags Optional. Tags to associate with the image.
-     * @returns A promise that resolves to the modified image upload information.
-     */
-    modifyImage(baseImageUrl: string, prompt: string, tags?: string[]): Promise<Upload>;
-}