Sync packages from monorepo (6ae3349)

Author: github-actions[bot]

packages/sdk/README.md

@@ -35,12 +35,12 @@ import { createPuzzmoSDK } from "@puzzmo/sdk"
 const sdk = createPuzzmoSDK()
 
 // 1. Wait for puzzle data from Puzzmo
-const { puzzleString, boardState, theme, completed } = await sdk.gameReady()
+const { puzzleString, inputString, theme, completed } = await sdk.gameReady()
 
 // 2. Set up your game with the puzzle data
 const puzzle = JSON.parse(puzzleString)
 initializeGame(puzzle)
-if (boardState) restoreState(boardState)
+if (inputString) restoreState(inputString)
 
 // 3. Signal that you're ready
 sdk.gameLoaded()
@@ -179,8 +179,8 @@ import type { EditorBundle, ValidationReport } from "@puzzmo/sdk"
 import { puzzleToSVG } from "./src/puzzleToSVG"
 
 export const AppBundle = {
-  renderThumbnail(puzzleString, boardState, config) {
-    return puzzleToSVG(puzzleString, boardState, config)
+  renderThumbnail(puzzleString, inputString, config) {
+    return puzzleToSVG(puzzleString, inputString, config)
   },
 } satisfies EditorBundle
 ```

packages/sdk/package.json

@@ -12,6 +12,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./inputs": {
+      "types": "./dist/inputs/index.d.ts",
+      "import": "./dist/inputs/index.js",
+      "require": "./dist/inputs/index.cjs"
+    },
     "./simulator": {
       "types": "./dist/simulator/index.d.ts",
       "import": "./dist/simulator/index.js",
@@ -52,6 +57,9 @@
     "provenance": true,
     "registry": "https://registry.npmjs.org/"
   },
+  "dependencies": {
+    "lz-string": "^1.5.0"
+  },
   "devDependencies": {
     "typescript": "catalog:",
     "vite": "catalog:"

packages/sdk/src/inputs/README.md

@@ -0,0 +1,111 @@
+# Input String Encoder
+
+A schema-driven library for encoding and decoding game state into compact, human-readable strings.
+
+## Features
+
+- **Compact encoding**: 40-60% size reduction vs JSON
+- **Human-readable**: Colon-delimited format for easy debugging
+- **Type-safe**: Full TypeScript inference
+- **Migration support**: Built-in version migration system
+- **Smart optimization**: Automatic sparse encoding for arrays, JSON compression with lz-string
+
+## Quick Start
+
+```typescript
+import { defineSchema, createEncoder } from '@puzzmo/sdk/inputs'
+
+// Define your data type
+type GameData = {
+  revealed: boolean[]
+  score: number
+  annotations: Record<string, { level: number; color: number }>
+}
+
+// Create a schema
+const schema = defineSchema<GameData>({
+  version: 1,
+  fields: {
+    revealed: { type: 'bitArray' },
+    score: { type: 'int' },
+    annotations: {
+      type: 'sparseMap',
+      valueEncoder: (ann) => `${ann.level}.${ann.color}`,
+      valueDecoder: (str) => {
+        const [level, color] = str.split('.').map(Number)
+        return { level, color }
+      }
+    }
+  }
+})
+
+// Create encoder/decoder with context for length-dependent fields
+const { encode, decode } = createEncoder(schema, {
+  revealed: { length: 100 }  // Required for bitArray decoding
+})
+
+// Use it
+const data = { revealed: [...], score: 42, annotations: { ... } }
+const inputString = encode(data)  // "v1:a3f5...:42:0,0=2.1;1,1=3.0"
+const decoded = decode(inputString)
+```
+
+## Field Types
+
+| Type | Use Case | Encoding | Example |
+|------|----------|----------|---------|
+| `bitArray` | Boolean arrays (revealed tiles, flags) | Hex (4 bits/char) | `[true, false, false, false, false, true]` → `"12"` |
+| `intArray` | Number arrays (scores, experience) | Smart sparse/CSV | `[0, 0, 5, 0, 3]` → `"2=5,4=3"` |
+| `int` | Single integers | Decimal | `42` → `"42"` |
+| `string` | Text values | As-is | `"Alice"` → `"Alice"` |
+| `stringArray` | String lists | Comma-separated | `["a", "b", "c"]` → `"a,b,c"` |
+| `sparseMap` | Key-value maps with custom encoding | `idx=value,...` or `key=value;...` | `{a: {x: 1}}` → `"0=1.2"` (with keys) or `"a=1.2"` |
+| `json` | Complex objects (fallback) | Compressed JSON | Auto lz-string compression |
+
+## Migrations
+
+Add version migrations to your schema:
+
+```typescript
+const schema = defineSchema({
+  version: 2,
+  fields: {
+    name: { type: 'string' },
+    value: { type: 'int' }
+  },
+  migrations: {
+    0: (old) => ({ ...old, value: 0 }),
+    1: (old) => ({ ...old, name: old.name.toUpperCase() })
+  }
+})
+
+const { migrate } = createEncoder(schema)
+const updated = migrate("v0:alice")  // "v2:ALICE:1"
+```
+
+## Context for Optimization
+
+Several field types benefit from context information:
+
+```typescript
+const { encode, decode } = createEncoder(schema, {
+  revealed: { length: 100 },        // Required for bitArray
+  scores: { length: 10 },           // Required for sparse intArray
+  annotations: { keys: tileIds }    // Optional: optimize sparseMap with numeric indices
+})
+```
+
+**sparseMap optimization**: Providing ordered keys converts string keys to numeric indices:
+- Without keys: `"0,0=2.1;1,1=3.0"` (17 chars, `;` separator)
+- With keys: `"0=2.1,11=3.0"` (13 chars, `,` separator)
+
+The keys array must match the key order used when creating the data.
+
+## Documentation
+
+See detailed documentation in [types.ts](./types.ts) for:
+- Complete field type specifications
+- When to use each type
+- Encoding/decoding details
+- Migration patterns
+- Best practices

packages/sdk/src/inputs/decoder.ts

@@ -0,0 +1,66 @@
+import type { Schema, FieldType } from "./types"
+import { decodeBitArrayFromHex, decodeIntArray, decodeStringArray, decodeSparseMap, decodeJson } from "./encodings"
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- context is dynamic and return type depends on fieldType
+export function decodeField(value: string, fieldType: FieldType, context?: any): any {
+  switch (fieldType.type) {
+    case "bitArray":
+      if (!context?.length) {
+        throw new Error("bitArray requires length in context")
+      }
+      return decodeBitArrayFromHex(value, context.length)
+
+    case "intArray":
+      return decodeIntArray(value, context?.length)
+
+    case "int":
+      return Number(value)
+
+    case "string":
+      return value
+
+    case "stringArray":
+      return decodeStringArray(value, fieldType.delimiter)
+
+    case "sparseMap":
+      return decodeSparseMap(value, fieldType.valueDecoder, context?.keys)
+
+    case "json":
+      return decodeJson(value)
+
+    default:
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- used in error message for invalid type
+      throw new Error(`Unknown field type: ${(fieldType as any).type}`)
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- context values are dynamic
+export function decode<TData>(schema: Schema<TData>, inputString: string, context?: Record<string, any>): TData {
+  const delimiter = schema.delimiter || ":"
+  const parts = inputString.split(delimiter)
+
+  const versionPart = parts[0]
+  const versionMatch = versionPart.match(/^v(\d+)$/)
+  if (!versionMatch) {
+    throw new Error(`Invalid input string format: ${versionPart}`)
+  }
+
+  const version = Number(versionMatch[1])
+  if (version !== schema.version) {
+    throw new Error(`Version mismatch: expected v${schema.version}, got v${version}. ` + `Make sure to run migrations first.`)
+  }
+
+  const fieldNames = Object.keys(schema.fields) as (keyof TData)[]
+  const data = {} as TData
+
+  for (let i = 0; i < fieldNames.length; i++) {
+    const fieldName = fieldNames[i]
+    const fieldType = schema.fields[fieldName]
+    const fieldValue = parts[i + 1] || ""
+
+    const fieldContext = context?.[fieldName as string]
+    data[fieldName] = decodeField(fieldValue, fieldType, fieldContext)
+  }
+
+  return data
+}

packages/sdk/src/inputs/encoder.ts

@@ -0,0 +1,44 @@
+import type { Schema, FieldType } from "./types"
+import { encodeBitArrayToHex, encodeIntArray, encodeStringArray, encodeSparseMap, encodeJson } from "./encodings"
+
+export function encodeField(value: any, fieldType: FieldType, context?: any): string {
+  switch (fieldType.type) {
+    case "bitArray":
+      return encodeBitArrayToHex(value)
+
+    case "intArray":
+      return encodeIntArray(value)
+
+    case "int":
+      return String(value)
+
+    case "string":
+      return String(value)
+
+    case "stringArray":
+      return encodeStringArray(value, fieldType.delimiter)
+
+    case "sparseMap":
+      return encodeSparseMap(value, fieldType.valueEncoder, context?.keys)
+
+    case "json":
+      return encodeJson(value)
+
+    default:
+      throw new Error(`Unknown field type: ${(fieldType as any).type}`)
+  }
+}
+
+export function encode<TData>(schema: Schema<TData>, data: TData, context?: Record<string, any>): string {
+  const delimiter = schema.delimiter || ":"
+  const fieldNames = Object.keys(schema.fields) as (keyof TData)[]
+
+  const encodedFields = fieldNames.map((fieldName) => {
+    const fieldType = schema.fields[fieldName]
+    const value = data[fieldName]
+    const fieldContext = context?.[fieldName as string]
+    return encodeField(value, fieldType, fieldContext)
+  })
+
+  return `v${schema.version}${delimiter}${encodedFields.join(delimiter)}`
+}