@kokimoki/app 3.1.3 → 3.1.5

package/README.md

@@ -52,8 +52,7 @@ See the [docs](./docs/) folder for detailed instructions:
 ## Usage with React
 
 ```tsx
-import { useSnapshot } from "valtio";
-import { getKmClient } from "@kokimoki/app";
+import { getKmClient, useSnapshot } from "@kokimoki/app";
 
 const kmClient = getKmClient();
 const gameStore = kmClient.store("game", { count: 0 });

package/dist/core/kokimoki-client.d.ts

@@ -78,8 +78,8 @@ declare const KokimokiClient_base: new () => TypedEmitter<KokimokiClientEvents>;
  *   game.round = 2;
  * });
  *
- * // Use in React components with Valtio
- * import { useSnapshot } from 'valtio';
+ * // Use in React components (useSnapshot is re-exported from valtio)
+ * import { useSnapshot } from '@kokimoki/app';
  *
  * function GameComponent() {
  *   const game = useSnapshot(gameStore.proxy);
@@ -93,7 +93,7 @@ declare const KokimokiClient_base: new () => TypedEmitter<KokimokiClientEvents>;
  * - Create global stores shared across all players: `kmClient.store()`
  * - Create local stores for client-side data: `kmClient.localStore()`
  * - Automatic synchronization and conflict resolution
- * - Use `useSnapshot()` from Valtio for reactive React components
+ * - Use `useSnapshot()` from `@kokimoki/app` for reactive React components (re-exported from valtio)
  *
  * **2. Atomic Transactions**
  * ```typescript
@@ -240,7 +240,7 @@ export declare class KokimokiClient<ClientContextT = any> extends KokimokiClient
      *
      * @example
      * ```typescript
-     * import { useSnapshot } from 'valtio';
+     * import { useSnapshot } from '@kokimoki/app';
      *
      * const kmClient = getKmClient();
      *

package/dist/core/kokimoki-client.js

@@ -56,8 +56,8 @@ export const APP_META_STORE_NAME = "__km/app-meta";
  *   game.round = 2;
  * });
  *
- * // Use in React components with Valtio
- * import { useSnapshot } from 'valtio';
+ * // Use in React components (useSnapshot is re-exported from valtio)
+ * import { useSnapshot } from '@kokimoki/app';
  *
  * function GameComponent() {
  *   const game = useSnapshot(gameStore.proxy);
@@ -71,7 +71,7 @@ export const APP_META_STORE_NAME = "__km/app-meta";
  * - Create global stores shared across all players: `kmClient.store()`
  * - Create local stores for client-side data: `kmClient.localStore()`
  * - Automatic synchronization and conflict resolution
- * - Use `useSnapshot()` from Valtio for reactive React components
+ * - Use `useSnapshot()` from `@kokimoki/app` for reactive React components (re-exported from valtio)
  *
  * **2. Atomic Transactions**
  * ```typescript
@@ -218,7 +218,7 @@ export class KokimokiClient extends EventEmitter {
      *
      * @example
      * ```typescript
-     * import { useSnapshot } from 'valtio';
+     * import { useSnapshot } from '@kokimoki/app';
      *
      * const kmClient = getKmClient();
      *

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-export { KokimokiClient } from "./core";
-export { APP_META_STORE_NAME } from "./core/kokimoki-client";
+export { APP_META_STORE_NAME, KokimokiClient } from "./core/kokimoki-client";
 export type { AppMetaState } from "./core/kokimoki-client";
 export { KokimokiStore } from "./stores";
 export type { KokimokiClientEvents, KokimokiEnv, Paginated, PollOptions, Upload, } from "./types";

package/dist/index.js

@@ -1,5 +1,4 @@
-export { KokimokiClient } from "./core";
-export { APP_META_STORE_NAME } from "./core/kokimoki-client";
+export { APP_META_STORE_NAME, KokimokiClient } from "./core/kokimoki-client";
 export { KokimokiStore } from "./stores";
 export { getKmClient } from "./utils/kokimoki-client";
 export { getKmEnv } from "./utils/kokimoki-env";

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.5";

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.5';

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,10 +1,17 @@
 {
   "name": "@kokimoki/app",
-  "version": "3.1.3",
+  "version": "3.1.5",
   "type": "module",
   "description": "Kokimoki app",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./llms.txt": "./llms.txt"
+  },
   "files": [
     "dist",
     "docs",
@@ -19,17 +26,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 {}