@omercnet/paseo-queens 0.1.0-next.126.2

package/server/curated-manifest.ts

@@ -0,0 +1,334 @@
+import type { PuzzleDifficulty } from "../shared/puzzle-catalog";
+
+/** Pinned, integrity-checked files in an unlisted GitHub Gist. */
+export type RemotePuzzleGroup = {
+  readonly size: number;
+  readonly difficulty: PuzzleDifficulty;
+  readonly count: number;
+  readonly recordBytes: number;
+  readonly sha256: string;
+  readonly url: string;
+};
+
+export const REMOTE_PUZZLE_GROUPS: Readonly<Record<string, RemotePuzzleGroup>> = {
+  "5-beginner": {
+    size: 5,
+    difficulty: "beginner",
+    count: 237,
+    recordBytes: 20,
+    sha256: "a0eb4398895869f50cf81562b96db1703b5886e6c98c0926296eb8a0a01be101",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/5-beginner.b64",
+  },
+  "5-easy": {
+    size: 5,
+    difficulty: "easy",
+    count: 4661,
+    recordBytes: 20,
+    sha256: "98a26f23e42bb1587cb660f4a11adeccb26e8142fd33b6c5c2a7a8d39a7185e4",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/5-easy.b64",
+  },
+  "5-medium": {
+    size: 5,
+    difficulty: "medium",
+    count: 1044,
+    recordBytes: 20,
+    sha256: "2b37f37fbeff1fc91feb9219efb4b86fe7935260b003bc996c807c734cb2a28c",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/5-medium.b64",
+  },
+  "5-hard": {
+    size: 5,
+    difficulty: "hard",
+    count: 178,
+    recordBytes: 20,
+    sha256: "e620330449d1592893950b54afa341d77a4fb6b5028575e110640cf5f31a9a74",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/5-hard.b64",
+  },
+  "6-beginner": {
+    size: 6,
+    difficulty: "beginner",
+    count: 311,
+    recordBytes: 26,
+    sha256: "88423258dd66d3d88a7813c9665a26ce39a14b2357c94551009bd51e007e314e",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/6-beginner.b64",
+  },
+  "6-easy": {
+    size: 6,
+    difficulty: "easy",
+    count: 6172,
+    recordBytes: 26,
+    sha256: "c1ddd59328108831787195f9c218b3d35c0497bead6fc61d37bc4a6cb5810191",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/6-easy.b64",
+  },
+  "6-medium": {
+    size: 6,
+    difficulty: "medium",
+    count: 2059,
+    recordBytes: 26,
+    sha256: "e07837d97570709f6e32a0e4a3b38b496a1f819fe43134168ab9c01af2ba8e7c",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/6-medium.b64",
+  },
+  "6-hard": {
+    size: 6,
+    difficulty: "hard",
+    count: 181,
+    recordBytes: 26,
+    sha256: "ae71e185be0e5732b4351c1c042484731c4b7e0443b07cba4748f78f4e988859",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/6-hard.b64",
+  },
+  "7-beginner": {
+    size: 7,
+    difficulty: "beginner",
+    count: 253,
+    recordBytes: 34,
+    sha256: "83171ec81b3a347023aa1577a771627af98794b6e938857729a45e8ea1643b3c",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/7-beginner.b64",
+  },
+  "7-easy": {
+    size: 7,
+    difficulty: "easy",
+    count: 5899,
+    recordBytes: 34,
+    sha256: "d95beb7dca32b83b5639afe7e673ca10575d6499100bd6a02beaff012d291713",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/7-easy.b64",
+  },
+  "7-medium": {
+    size: 7,
+    difficulty: "medium",
+    count: 3034,
+    recordBytes: 34,
+    sha256: "dd93b0c0d4a3bfd7d2401b2aefbea81c10153adc69dd9cc512d944a876501815",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/7-medium.b64",
+  },
+  "7-hard": {
+    size: 7,
+    difficulty: "hard",
+    count: 310,
+    recordBytes: 34,
+    sha256: "c7f6e137741e6b03f2fa8626a73f63b1f1fea7c5de8f35121a388dde9c87f937",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/7-hard.b64",
+  },
+  "8-beginner": {
+    size: 8,
+    difficulty: "beginner",
+    count: 164,
+    recordBytes: 42,
+    sha256: "e8a8790dd97b54e0d0baac0c2e16b7ad01c0ba3b40575e9283a0797284dd0a8e",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/8-beginner.b64",
+  },
+  "8-easy": {
+    size: 8,
+    difficulty: "easy",
+    count: 5187,
+    recordBytes: 42,
+    sha256: "55f53bb48eb0f42d1251abe747bf720cbcf50256db98a81b015ef4f4d3de536b",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/8-easy.b64",
+  },
+  "8-medium": {
+    size: 8,
+    difficulty: "medium",
+    count: 4203,
+    recordBytes: 42,
+    sha256: "882f9f58b6b90723252c34c7e4b5c4adffe8537e637649f6705d43ed60d4a149",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/8-medium.b64",
+  },
+  "8-hard": {
+    size: 8,
+    difficulty: "hard",
+    count: 456,
+    recordBytes: 42,
+    sha256: "cf89a88a7e3aff16a311cad357982bddc21bb851c83b38d5657da1a6a90d49e1",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/8-hard.b64",
+  },
+  "9-beginner": {
+    size: 9,
+    difficulty: "beginner",
+    count: 119,
+    recordBytes: 52,
+    sha256: "c84d59f243ecef3db80b49bf629803814e47bfa16db6a53e601d234f04932d41",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/9-beginner.b64",
+  },
+  "9-easy": {
+    size: 9,
+    difficulty: "easy",
+    count: 3989,
+    recordBytes: 52,
+    sha256: "30a6832ac47bd5fe02f272e34bde499bfdcaad6830058de50f2ad137fb4780d7",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/9-easy.b64",
+  },
+  "9-medium": {
+    size: 9,
+    difficulty: "medium",
+    count: 5002,
+    recordBytes: 52,
+    sha256: "dca2c411656446d3bfd741b942cd4fded86da1438e15689549c19fa14f0d2c27",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/9-medium.b64",
+  },
+  "9-hard": {
+    size: 9,
+    difficulty: "hard",
+    count: 721,
+    recordBytes: 52,
+    sha256: "b3782fb6a4858c38f6060ca3c0e74ab62bb5c9e826c3c6bf31288c73a99506b6",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/9-hard.b64",
+  },
+  "10-beginner": {
+    size: 10,
+    difficulty: "beginner",
+    count: 61,
+    recordBytes: 62,
+    sha256: "d0b030ae157690fd8306666cd75610d9f724c6fdbf847dc3252de55c4ad97c52",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/10-beginner.b64",
+  },
+  "10-easy": {
+    size: 10,
+    difficulty: "easy",
+    count: 2974,
+    recordBytes: 62,
+    sha256: "51e3b5bd38f91cce2ae9e13942e0b1284f1a8f6489006033cf6917a908691124",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/10-easy.b64",
+  },
+  "10-medium": {
+    size: 10,
+    difficulty: "medium",
+    count: 5842,
+    recordBytes: 62,
+    sha256: "51df6bee224ea44dc58757f960a5e418f01241caddcdd23fd603fee8fb72dbd5",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/10-medium.b64",
+  },
+  "10-hard": {
+    size: 10,
+    difficulty: "hard",
+    count: 1044,
+    recordBytes: 62,
+    sha256: "2481a379ccb608e3f3e21e8068b616f63523c5d70152bb50034cb0041dc46faa",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/10-hard.b64",
+  },
+  "11-beginner": {
+    size: 11,
+    difficulty: "beginner",
+    count: 55,
+    recordBytes: 74,
+    sha256: "3b4aa704d937035969580ff8b8270e3ce672287027d590a99a9a67457b384c4a",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/11-beginner.b64",
+  },
+  "11-easy": {
+    size: 11,
+    difficulty: "easy",
+    count: 2257,
+    recordBytes: 74,
+    sha256: "1c4c5ac5a6d262babac70144024fd5829ebbca5d657cbd4534a6da9b7377e046",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/11-easy.b64",
+  },
+  "11-medium": {
+    size: 11,
+    difficulty: "medium",
+    count: 6592,
+    recordBytes: 74,
+    sha256: "6dea1159d6159ded26743accf88eee714f0ee1dc98bda8a5d998a282f2879ed0",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/11-medium.b64",
+  },
+  "11-hard": {
+    size: 11,
+    difficulty: "hard",
+    count: 1750,
+    recordBytes: 74,
+    sha256: "30c04ec600b0ae57e90d049f8194af67bcb1dfbae29df57c1b2a06a82995c356",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/11-hard.b64",
+  },
+  "12-beginner": {
+    size: 12,
+    difficulty: "beginner",
+    count: 20,
+    recordBytes: 86,
+    sha256: "e59449cc42c78b25e2a82e1fd22cf7a0e021fe9d08517e92ed24b74a7c99eb63",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/12-beginner.b64",
+  },
+  "12-easy": {
+    size: 12,
+    difficulty: "easy",
+    count: 1552,
+    recordBytes: 86,
+    sha256: "05e24ded88bd1f2ba66d2d5bae31b96659a1173e222d067e8afaf22679c38186",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/12-easy.b64",
+  },
+  "12-medium": {
+    size: 12,
+    difficulty: "medium",
+    count: 6145,
+    recordBytes: 86,
+    sha256: "ffe7226b9ed146a91696966ec3d5ef92244a3287baa3081ff8f732f1fe5ad027",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/12-medium.b64",
+  },
+  "12-hard": {
+    size: 12,
+    difficulty: "hard",
+    count: 2278,
+    recordBytes: 86,
+    sha256: "dfe7f957e895dd9f9d3a10bef34615ad1a106f9a2bfa8c54c5db5c75e5e8c679",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/12-hard.b64",
+  },
+  "13-beginner": {
+    size: 13,
+    difficulty: "beginner",
+    count: 53,
+    recordBytes: 100,
+    sha256: "d7bcc65265743fd276da25a2fa1768f38ace124930d3c44d51b54c1f7315eb47",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/13-beginner.b64",
+  },
+  "13-easy": {
+    size: 13,
+    difficulty: "easy",
+    count: 2646,
+    recordBytes: 100,
+    sha256: "8ab626bc8b7bf3362403839b2a3127a3a3eea09f484e20a931fd6515ebf4c56c",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/13-easy.b64",
+  },
+  "13-medium": {
+    size: 13,
+    difficulty: "medium",
+    count: 2949,
+    recordBytes: 100,
+    sha256: "5fd11c7100d513dd1e4a31254d1f857ca27403337b4b24d4989f3f35dffbc4b6",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/13-medium.b64",
+  },
+  "13-hard": {
+    size: 13,
+    difficulty: "hard",
+    count: 4582,
+    recordBytes: 100,
+    sha256: "928d08e0b2d272781adae11692c500629d91db89583778640618f8e969c09e0f",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/13-hard.b64",
+  },
+  "14-beginner": {
+    size: 14,
+    difficulty: "beginner",
+    count: 99,
+    recordBytes: 114,
+    sha256: "53a77886ed0156726e178aed64e558a4777801243875b3347eda87b6fea9e944",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/14-beginner.b64",
+  },
+  "14-easy": {
+    size: 14,
+    difficulty: "easy",
+    count: 3338,
+    recordBytes: 114,
+    sha256: "9959ea694895cc76dbd171c585e03ac5ef913373fb583b038387f7937e55dd9e",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/14-easy.b64",
+  },
+  "14-medium": {
+    size: 14,
+    difficulty: "medium",
+    count: 2960,
+    recordBytes: 114,
+    sha256: "c1e50bb2acd25cbbcdf45fc78dc65f6d292e6ec9af743f207ac4c9930b786090",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/14-medium.b64",
+  },
+  "14-hard": {
+    size: 14,
+    difficulty: "hard",
+    count: 5807,
+    recordBytes: 114,
+    sha256: "c01f62423bf0f8940f26e98f2fab5e276a845194b01ae3e6c5337cdff29493c5",
+    url: "https://gist.githubusercontent.com/omercnet/652af12e2640979ba7fb5dc5adddde42/raw/4f3e565c2805a709a5121c5617bdd6f327a2ecd8/14-hard.b64",
+  },
+};

package/server/puzzle-catalog.ts

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import type { z } from "zod";
+import type { loadPuzzleDeck } from "../shared/puzzle-catalog";
+import { REMOTE_PUZZLE_GROUPS, type RemotePuzzleGroup } from "./curated-manifest";
+
+const MAX_REMOTE_BYTES = 2_000_000;
+const FETCH_TIMEOUT_MS = 15_000;
+
+type PuzzleDeckInput = z.output<typeof loadPuzzleDeck.input>;
+type PuzzleGroupManifest = Readonly<Record<string, RemotePuzzleGroup>>;
+
+export function createPuzzleDeckLoader(
+  fetcher: typeof fetch = fetch,
+  groups: PuzzleGroupManifest = REMOTE_PUZZLE_GROUPS,
+) {
+  const cache = new Map<string, Promise<string>>();
+
+  const fetchGroup = (key: string, group: RemotePuzzleGroup) => {
+    const existing = cache.get(key);
+    if (existing) return existing;
+
+    const request = (async () => {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+      try {
+        const response = await fetcher(group.url, { signal: controller.signal });
+        if (!response.ok) throw new Error(`Curated puzzle host returned HTTP ${response.status}.`);
+        const declaredLength = Number(response.headers.get("content-length"));
+        if (Number.isFinite(declaredLength) && declaredLength > MAX_REMOTE_BYTES) {
+          throw new RangeError("Curated puzzle payload exceeds the download limit.");
+        }
+        const data = (await response.text()).trim();
+        if (data.length === 0 || data.length > MAX_REMOTE_BYTES) {
+          throw new RangeError("Curated puzzle payload has an invalid size.");
+        }
+        const digest = createHash("sha256").update(data).digest("hex");
+        if (digest !== group.sha256) {
+          throw new Error("Curated puzzle payload failed its integrity check.");
+        }
+        return data;
+      } finally {
+        clearTimeout(timeout);
+      }
+    })().catch((error: unknown) => {
+      cache.delete(key);
+      throw error;
+    });
+
+    cache.set(key, request);
+    return request;
+  };
+
+  return async (input: PuzzleDeckInput) => {
+    const key = `${input.size}-${input.difficulty}`;
+    const group = groups[key];
+    if (!group) {
+      throw new RangeError(`No curated ${input.size}×${input.size} ${input.difficulty} deck.`);
+    }
+    const data = await fetchGroup(key, group);
+    return {
+      size: group.size,
+      difficulty: group.difficulty,
+      count: group.count,
+      recordBytes: group.recordBytes,
+      data,
+    };
+  };
+}
+
+export const getPuzzleDeck = createPuzzleDeckLoader();

package/shared/game-settings.ts

@@ -0,0 +1,114 @@
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+import { PuzzleDifficultySchema, PuzzleSizeSchema } from "./puzzle-catalog";
+
+export const DEFAULT_PUZZLE_ID = "paseo-queens-01";
+export const DEFAULT_BOARD_SIZE = 6;
+export const DEFAULT_DIFFICULTY = "easy" as const;
+
+export const GAME_SETTINGS_LIMITS = {
+  puzzleIdLength: 128,
+  puzzles: 256,
+  cellsPerPuzzle: 400,
+  completionsPerPuzzle: 1_000_000,
+} as const;
+
+export const PersistedCellStateSchema = z.enum(["empty", "excluded", "marked"]);
+
+export const PuzzleIdSchema = z
+  .string()
+  .min(1)
+  .max(GAME_SETTINGS_LIMITS.puzzleIdLength)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+
+const TimestampMsSchema = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+
+export const PuzzleStateSchema = z
+  .object({
+    cells: z.array(PersistedCellStateSchema).min(1).max(GAME_SETTINGS_LIMITS.cellsPerPuzzle),
+    startedAtMs: TimestampMsSchema.nullable(),
+    completedAtMs: TimestampMsSchema.nullable(),
+    hintUsed: z.boolean(),
+  })
+  .strict()
+  .superRefine((state, context) => {
+    if (state.completedAtMs !== null && state.startedAtMs === null) {
+      context.addIssue({
+        code: "custom",
+        path: ["completedAtMs"],
+        message: "A completed puzzle must have a start timestamp",
+      });
+      return;
+    }
+
+    if (
+      state.completedAtMs !== null &&
+      state.startedAtMs !== null &&
+      state.completedAtMs < state.startedAtMs
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["completedAtMs"],
+        message: "Completion timestamp cannot precede start timestamp",
+      });
+    }
+  });
+
+export const CompletionRecordSchema = z
+  .object({
+    completions: z.number().int().min(1).max(GAME_SETTINGS_LIMITS.completionsPerPuzzle),
+    bestTimeMs: TimestampMsSchema,
+  })
+  .strict();
+
+export const PuzzleStatesSchema = z
+  .record(PuzzleIdSchema, PuzzleStateSchema)
+  .superRefine((states, context) => {
+    if (Object.keys(states).length > GAME_SETTINGS_LIMITS.puzzles) {
+      context.addIssue({
+        code: "custom",
+        message: `Puzzle state collection cannot exceed ${GAME_SETTINGS_LIMITS.puzzles} entries`,
+      });
+    }
+  });
+
+export const CompletionRecordsSchema = z
+  .record(PuzzleIdSchema, CompletionRecordSchema)
+  .superRefine((records, context) => {
+    if (Object.keys(records).length > GAME_SETTINGS_LIMITS.puzzles) {
+      context.addIssue({
+        code: "custom",
+        message: `Completion record collection cannot exceed ${GAME_SETTINGS_LIMITS.puzzles} entries`,
+      });
+    }
+  });
+
+export const GameSettingsSchema = z
+  .object({
+    boardSize: PuzzleSizeSchema.default(DEFAULT_BOARD_SIZE),
+    difficulty: PuzzleDifficultySchema.default(DEFAULT_DIFFICULTY),
+    currentPuzzleId: PuzzleIdSchema.default(DEFAULT_PUZZLE_ID),
+    puzzleStates: PuzzleStatesSchema.default({}),
+    records: CompletionRecordsSchema.default({}),
+  })
+  .strict();
+
+export type PersistedCellState = z.infer<typeof PersistedCellStateSchema>;
+export type PuzzleState = z.infer<typeof PuzzleStateSchema>;
+export type CompletionRecord = z.infer<typeof CompletionRecordSchema>;
+export type GameSettings = z.infer<typeof GameSettingsSchema>;
+
+export const DEFAULT_GAME_SETTINGS = {
+  boardSize: DEFAULT_BOARD_SIZE,
+  difficulty: DEFAULT_DIFFICULTY,
+  currentPuzzleId: DEFAULT_PUZZLE_ID,
+  puzzleStates: {},
+  records: {},
+} satisfies GameSettings;
+
+export const gameSettings = defineSettings({
+  id: "paseo-queens-game",
+  scope: "host",
+  version: 1,
+  schema: GameSettingsSchema,
+});

package/shared/puzzle-catalog.ts

@@ -0,0 +1,29 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const PUZZLE_SIZES = [5, 6, 7, 8, 9, 10, 11, 12, 13, 14] as const;
+export const PUZZLE_DIFFICULTIES = ["beginner", "easy", "medium", "hard"] as const;
+
+export const PuzzleSizeSchema = z.number().int().min(5).max(14);
+export const PuzzleDifficultySchema = z.enum(PUZZLE_DIFFICULTIES);
+
+export type PuzzleDifficulty = z.infer<typeof PuzzleDifficultySchema>;
+
+export const loadPuzzleDeck = defineRpc({
+  name: "queens.load-puzzle-deck",
+  input: z
+    .object({
+      size: PuzzleSizeSchema,
+      difficulty: PuzzleDifficultySchema,
+    })
+    .strict(),
+  output: z
+    .object({
+      size: PuzzleSizeSchema,
+      difficulty: PuzzleDifficultySchema,
+      count: z.number().int().positive().max(20_000),
+      recordBytes: z.number().int().positive().max(256),
+      data: z.string().min(1).max(2_000_000),
+    })
+    .strict(),
+});