@sudobility/sudojo_lib 0.0.201 → 0.0.203

package/dist/admin/adminApi.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Imperative network surface for the admin jobs, built only from
+ * `@sudobility/sudojo_client` hooks (never a hand-made SudojoClient).
+ *
+ * - Writes, /solve, /validate, /generate and the boards list use mutation
+ *   hooks' `mutateAsync` (per-call arguments).
+ * - Fixed-key reads (levels, techniques) use a disabled query hook's
+ *   `refetch()`, which fetches regardless of `enabled`/`staleTime`.
+ *
+ * The jobs depend on the {@link AdminApi} interface, not on the hooks, so
+ * they can be driven by a fake in tests.
+ */
+import type { BaseResponse, Board, BoardCreateRequest, BoardQueryParams, BoardUpdateRequest, GenerateData, GenerateOptions, Level, SolveData, SolveOptions, Technique, TechniqueExample, TechniqueExampleCreateRequest, TechniquePractice, TechniquePracticeCreateRequest, ValidateData, ValidateOptions } from '@sudobility/sudojo_types';
+import type { NetworkClient } from '@sudobility/types';
+/** Network calls the admin jobs make. `token` is the admin ID token. */
+export interface AdminApi {
+    solve(token: string, options: SolveOptions): Promise<BaseResponse<SolveData>>;
+    validate(token: string, options: ValidateOptions): Promise<BaseResponse<ValidateData>>;
+    generate(token: string, options: GenerateOptions): Promise<BaseResponse<GenerateData>>;
+    getBoards(token: string, queryParams: BoardQueryParams): Promise<BaseResponse<Board[]>>;
+    getLevels(): Promise<BaseResponse<Level[]>>;
+    getTechniques(): Promise<BaseResponse<Technique[]>>;
+    createBoard(token: string, data: BoardCreateRequest): Promise<BaseResponse<Board>>;
+    updateBoard(token: string, uuid: string, data: BoardUpdateRequest): Promise<BaseResponse<Board>>;
+    createExample(token: string, data: TechniqueExampleCreateRequest): Promise<BaseResponse<TechniqueExample>>;
+    createPractice(token: string, data: TechniquePracticeCreateRequest): Promise<BaseResponse<TechniquePractice>>;
+}
+/**
+ * Build an {@link AdminApi} from sudojo_client hooks. The returned object is
+ * stable for the component's lifetime and always calls the latest hook
+ * results, so a long-running job can hold on to it.
+ */
+export declare function useAdminApi(networkClient: NetworkClient, baseUrl: string): AdminApi;
+//# sourceMappingURL=adminApi.d.ts.map

package/dist/admin/adminApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adminApi.d.ts","sourceRoot":"","sources":["../../src/admin/adminApi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH,OAAO,KAAK,EACV,YAAY,EACZ,KAAK,EACL,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,KAAK,EACL,SAAS,EACT,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,6BAA6B,EAC7B,iBAAiB,EACjB,8BAA8B,EAC9B,YAAY,EACZ,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,wEAAwE;AACxE,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC;IAC9E,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;IACvC,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;IACvC,SAAS,CACP,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,gBAAgB,GAC5B,OAAO,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAClC,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC5C,aAAa,IAAI,OAAO,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IACpD,WAAW,CACT,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IAChC,WAAW,CACT,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IAChC,aAAa,CACX,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,6BAA6B,GAClC,OAAO,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC3C,cAAc,CACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,8BAA8B,GACnC,OAAO,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC,CAAC;CAC7C;AAWD;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,aAAa,EAAE,aAAa,EAC5B,OAAO,EAAE,MAAM,GACd,QAAQ,CA2CV"}

package/dist/admin/adminApi.js

@@ -0,0 +1,59 @@
+/**
+ * Imperative network surface for the admin jobs, built only from
+ * `@sudobility/sudojo_client` hooks (never a hand-made SudojoClient).
+ *
+ * - Writes, /solve, /validate, /generate and the boards list use mutation
+ *   hooks' `mutateAsync` (per-call arguments).
+ * - Fixed-key reads (levels, techniques) use a disabled query hook's
+ *   `refetch()`, which fetches regardless of `enabled`/`staleTime`.
+ *
+ * The jobs depend on the {@link AdminApi} interface, not on the hooks, so
+ * they can be driven by a fake in tests.
+ */
+import { useSolverGenerateMutation, useSolverSolveMutation, useSolverValidateMutation, useSudojoCreateBoard, useSudojoCreateExample, useSudojoCreatePractice, useSudojoFetchBoards, useSudojoLevels, useSudojoTechniques, useSudojoUpdateBoard, } from '@sudobility/sudojo_client';
+import { useMemo, useRef } from 'react';
+async function dataOrThrow(refetch) {
+    const result = await refetch();
+    if (result.error)
+        throw result.error;
+    if (result.data === undefined)
+        throw new Error('No response');
+    return result.data;
+}
+/**
+ * Build an {@link AdminApi} from sudojo_client hooks. The returned object is
+ * stable for the component's lifetime and always calls the latest hook
+ * results, so a long-running job can hold on to it.
+ */
+export function useAdminApi(networkClient, baseUrl) {
+    const hooks = {
+        solve: useSolverSolveMutation(networkClient, baseUrl),
+        validate: useSolverValidateMutation(networkClient, baseUrl),
+        generate: useSolverGenerateMutation(networkClient, baseUrl),
+        fetchBoards: useSudojoFetchBoards(networkClient, baseUrl),
+        createBoard: useSudojoCreateBoard(networkClient, baseUrl),
+        updateBoard: useSudojoUpdateBoard(networkClient, baseUrl),
+        createExample: useSudojoCreateExample(networkClient, baseUrl),
+        createPractice: useSudojoCreatePractice(networkClient, baseUrl),
+        // Public GETs: no token needed. Disabled; read with refetch().
+        levels: useSudojoLevels(networkClient, baseUrl, '', { enabled: false }),
+        techniques: useSudojoTechniques(networkClient, baseUrl, '', undefined, {
+            enabled: false,
+        }),
+    };
+    const latest = useRef(hooks);
+    latest.current = hooks;
+    return useMemo(() => ({
+        solve: (token, options) => latest.current.solve.mutateAsync({ token, options }),
+        validate: (token, options) => latest.current.validate.mutateAsync({ token, options }),
+        generate: (token, options) => latest.current.generate.mutateAsync({ token, options }),
+        getBoards: (token, queryParams) => latest.current.fetchBoards.mutateAsync({ token, queryParams }),
+        getLevels: () => dataOrThrow(() => latest.current.levels.refetch()),
+        getTechniques: () => dataOrThrow(() => latest.current.techniques.refetch()),
+        createBoard: (token, data) => latest.current.createBoard.mutateAsync({ token, data }),
+        updateBoard: (token, uuid, data) => latest.current.updateBoard.mutateAsync({ token, uuid, data }),
+        createExample: (token, data) => latest.current.createExample.mutateAsync({ token, data }),
+        createPractice: (token, data) => latest.current.createPractice.mutateAsync({ token, data }),
+    }), []);
+}
+//# sourceMappingURL=adminApi.js.map

package/dist/admin/adminApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adminApi.js","sourceRoot":"","sources":["../../src/admin/adminApi.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Imperative network surface for the admin jobs, built only from\n * `@sudobility/sudojo_client` hooks (never a hand-made SudojoClient).\n *\n * - Writes, /solve, /validate, /generate and the boards list use mutation\n *   hooks' `mutateAsync` (per-call arguments).\n * - Fixed-key reads (levels, techniques) use a disabled query hook's\n *   `refetch()`, which fetches regardless of `enabled`/`staleTime`.\n *\n * The jobs depend on the {@link AdminApi} interface, not on the hooks, so\n * they can be driven by a fake in tests.\n */\n\nimport {\n  useSolverGenerateMutation,\n  useSolverSolveMutation,\n  useSolverValidateMutation,\n  useSudojoCreateBoard,\n  useSudojoCreateExample,\n  useSudojoCreatePractice,\n  useSudojoFetchBoards,\n  useSudojoLevels,\n  useSudojoTechniques,\n  useSudojoUpdateBoard,\n} from '@sudobility/sudojo_client';\nimport type {\n  BaseResponse,\n  Board,\n  BoardCreateRequest,\n  BoardQueryParams,\n  BoardUpdateRequest,\n  GenerateData,\n  GenerateOptions,\n  Level,\n  SolveData,\n  SolveOptions,\n  Technique,\n  TechniqueExample,\n  TechniqueExampleCreateRequest,\n  TechniquePractice,\n  TechniquePracticeCreateRequest,\n  ValidateData,\n  ValidateOptions,\n} from '@sudobility/sudojo_types';\nimport type { NetworkClient } from '@sudobility/types';\nimport { useMemo, useRef } from 'react';\n\n/** Network calls the admin jobs make. `token` is the admin ID token. */\nexport interface AdminApi {\n  solve(token: string, options: SolveOptions): Promise<BaseResponse<SolveData>>;\n  validate(\n    token: string,\n    options: ValidateOptions\n  ): Promise<BaseResponse<ValidateData>>;\n  generate(\n    token: string,\n    options: GenerateOptions\n  ): Promise<BaseResponse<GenerateData>>;\n  getBoards(\n    token: string,\n    queryParams: BoardQueryParams\n  ): Promise<BaseResponse<Board[]>>;\n  getLevels(): Promise<BaseResponse<Level[]>>;\n  getTechniques(): Promise<BaseResponse<Technique[]>>;\n  createBoard(\n    token: string,\n    data: BoardCreateRequest\n  ): Promise<BaseResponse<Board>>;\n  updateBoard(\n    token: string,\n    uuid: string,\n    data: BoardUpdateRequest\n  ): Promise<BaseResponse<Board>>;\n  createExample(\n    token: string,\n    data: TechniqueExampleCreateRequest\n  ): Promise<BaseResponse<TechniqueExample>>;\n  createPractice(\n    token: string,\n    data: TechniquePracticeCreateRequest\n  ): Promise<BaseResponse<TechniquePractice>>;\n}\n\nasync function dataOrThrow<T>(\n  refetch: () => Promise<{ data?: T | undefined; error?: Error | null }>\n): Promise<T> {\n  const result = await refetch();\n  if (result.error) throw result.error;\n  if (result.data === undefined) throw new Error('No response');\n  return result.data;\n}\n\n/**\n * Build an {@link AdminApi} from sudojo_client hooks. The returned object is\n * stable for the component's lifetime and always calls the latest hook\n * results, so a long-running job can hold on to it.\n */\nexport function useAdminApi(\n  networkClient: NetworkClient,\n  baseUrl: string\n): AdminApi {\n  const hooks = {\n    solve: useSolverSolveMutation(networkClient, baseUrl),\n    validate: useSolverValidateMutation(networkClient, baseUrl),\n    generate: useSolverGenerateMutation(networkClient, baseUrl),\n    fetchBoards: useSudojoFetchBoards(networkClient, baseUrl),\n    createBoard: useSudojoCreateBoard(networkClient, baseUrl),\n    updateBoard: useSudojoUpdateBoard(networkClient, baseUrl),\n    createExample: useSudojoCreateExample(networkClient, baseUrl),\n    createPractice: useSudojoCreatePractice(networkClient, baseUrl),\n    // Public GETs: no token needed. Disabled; read with refetch().\n    levels: useSudojoLevels(networkClient, baseUrl, '', { enabled: false }),\n    techniques: useSudojoTechniques(networkClient, baseUrl, '', undefined, {\n      enabled: false,\n    }),\n  };\n  const latest = useRef(hooks);\n  latest.current = hooks;\n\n  return useMemo<AdminApi>(\n    () => ({\n      solve: (token, options) =>\n        latest.current.solve.mutateAsync({ token, options }),\n      validate: (token, options) =>\n        latest.current.validate.mutateAsync({ token, options }),\n      generate: (token, options) =>\n        latest.current.generate.mutateAsync({ token, options }),\n      getBoards: (token, queryParams) =>\n        latest.current.fetchBoards.mutateAsync({ token, queryParams }),\n      getLevels: () => dataOrThrow(() => latest.current.levels.refetch()),\n      getTechniques: () =>\n        dataOrThrow(() => latest.current.techniques.refetch()),\n      createBoard: (token, data) =>\n        latest.current.createBoard.mutateAsync({ token, data }),\n      updateBoard: (token, uuid, data) =>\n        latest.current.updateBoard.mutateAsync({ token, uuid, data }),\n      createExample: (token, data) =>\n        latest.current.createExample.mutateAsync({ token, data }),\n      createPractice: (token, data) =>\n        latest.current.createPractice.mutateAsync({ token, data }),\n    }),\n    []\n  );\n}\n"]}

package/dist/admin/boardRules.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Pure rules for the board jobs: reading a /generate response, turning a
+ * /validate result into a create request, the board query filters, and the
+ * frontend-vs-solver comparison of the technique extractor.
+ *
+ * Masks are exact `bigint`s here and go on the wire as base-10 strings
+ * (`formatTechniqueBitmask`): a JSON number drops the low bits once any
+ * technique id >= 54 is set.
+ *
+ * Ported from `sudojo_app/src/utils/admin/BoardGenerator.ts`,
+ * `TechniqueExtractor.ts` and `boardTechniquesApi.ts`.
+ */
+import { type BoardCreateRequest, type BoardQueryParams, type BoardUpdateRequest, type TechniqueId, type ValidateData } from '@sudobility/sudojo_types';
+import type { BoardExtractionResult } from './extraction';
+/** Puzzle read from a /generate response. */
+export interface GeneratedPuzzle {
+    level: number;
+    original: string;
+    solution: string;
+}
+export type ParseGeneratedBoardResult = ({
+    ok: true;
+} & GeneratedPuzzle) | {
+    ok: false;
+    reason: 'invalid' | 'missing-puzzle';
+};
+/**
+ * Read level/original/solution from a /generate `data`, tolerating the older
+ * shapes the web app accepted: `{ board: { level, board: {original, …} } }`,
+ * `{ board: { level, original, … } }` and `{ level, original, … }`.
+ * `invalid` = no numeric level; `missing-puzzle` = no original.
+ */
+export declare function parseGeneratedBoard(data: unknown): ParseGeneratedBoardResult;
+/** A board ready to save, with the values reported back to the UI. */
+export interface ValidatedBoard {
+    request: BoardCreateRequest;
+    level: number;
+    /** Exact bitmask (bit N = technique N) */
+    techniques: bigint;
+}
+/**
+ * Create request for a generated board. The /validate result is the source of
+ * truth for level, techniques and solution; the /generate values are only a
+ * fallback when /validate omits them.
+ */
+export declare function buildValidatedBoard(generated: GeneratedPuzzle, validateData: ValidateData | undefined | null, symmetrical: boolean): ValidatedBoard;
+/** Update request that sets only a board's techniques bitmask and level. */
+export declare function buildBoardTechniquesUpdate(techniques: bigint, level: number | null): BoardUpdateRequest;
+/** Filter for the next board whose techniques were never extracted. */
+export declare function boardsWithoutTechniquesQuery(): BoardQueryParams;
+/**
+ * Filter for boards with the technique's bit set (API `technique_bit`, sent
+ * as an exact string). Not filtered by level: boards with the technique may
+ * sit at higher levels.
+ */
+export declare function boardsWithTechniqueQuery(techniqueId: TechniqueId, limit: number): BoardQueryParams;
+/** Filter for boards at one level. */
+export declare function boardsAtLevelQuery(level: number, limit: number): BoardQueryParams;
+/** Frontend extraction disagreed with /validate. */
+export interface ExtractionMismatch {
+    solverTechniques: bigint;
+    solverLevel: number;
+    message: string;
+}
+/**
+ * Compare a frontend extraction with /validate. Exact bigint comparison: the
+ * numeric `techniques` drops low bits above 2^53, which would hide mismatches.
+ * Returns null when techniques and level both match.
+ */
+export declare function compareExtractionWithSolver(boardUuid: string, frontend: BoardExtractionResult, solver: {
+    level: number;
+    techniques: number;
+    techniques_bitmask?: string;
+}): ExtractionMismatch | null;
+//# sourceMappingURL=boardRules.d.ts.map

package/dist/admin/boardRules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boardRules.d.ts","sourceRoot":"","sources":["../../src/admin/boardRules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EAGvB,KAAK,WAAW,EAEhB,KAAK,YAAY,EAClB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,yBAAyB,GACjC,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,eAAe,CAAC,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,gBAAgB,CAAA;CAAE,CAAC;AAExD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,yBAAyB,CAe5E;AAeD,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,eAAe,EAC1B,YAAY,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI,EAC7C,WAAW,EAAE,OAAO,GACnB,cAAc,CAgBhB;AAED,4EAA4E;AAC5E,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GAAG,IAAI,GACnB,kBAAkB,CAQpB;AAWD,uEAAuE;AACvE,wBAAgB,4BAA4B,IAAI,gBAAgB,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,MAAM,GACZ,gBAAgB,CAMlB;AAED,sCAAsC;AACtC,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,gBAAgB,CAElB;AAED,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GACzE,kBAAkB,GAAG,IAAI,CAgB3B"}

package/dist/admin/boardRules.js

@@ -0,0 +1,127 @@
+/**
+ * Pure rules for the board jobs: reading a /generate response, turning a
+ * /validate result into a create request, the board query filters, and the
+ * frontend-vs-solver comparison of the technique extractor.
+ *
+ * Masks are exact `bigint`s here and go on the wire as base-10 strings
+ * (`formatTechniqueBitmask`): a JSON number drops the low bits once any
+ * technique id >= 54 is set.
+ *
+ * Ported from `sudojo_app/src/utils/admin/BoardGenerator.ts`,
+ * `TechniqueExtractor.ts` and `boardTechniquesApi.ts`.
+ */
+import { formatTechniqueBitmask, techniqueBitmaskOf, techniqueIdsToBitmask, } from '@sudobility/sudojo_types';
+import { formatTechniqueMaskHex, shortUuid } from './boardStrings';
+/**
+ * Read level/original/solution from a /generate `data`, tolerating the older
+ * shapes the web app accepted: `{ board: { level, board: {original, …} } }`,
+ * `{ board: { level, original, … } }` and `{ level, original, … }`.
+ * `invalid` = no numeric level; `missing-puzzle` = no original.
+ */
+export function parseGeneratedBoard(data) {
+    const root = asRecord(data);
+    const nested = asRecord(root?.board);
+    const boardData = nested?.level !== undefined ? nested : root;
+    if (!boardData || typeof boardData.level !== 'number') {
+        return { ok: false, reason: 'invalid' };
+    }
+    const puzzleData = asRecord(boardData.board) ?? boardData;
+    const inner = asRecord(puzzleData.board);
+    const original = firstString(puzzleData.original, inner?.original);
+    const solution = firstString(puzzleData.solution, inner?.solution);
+    if (!original)
+        return { ok: false, reason: 'missing-puzzle' };
+    return { ok: true, level: boardData.level, original, solution };
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null
+        ? value
+        : null;
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value)
+            return value;
+    }
+    return '';
+}
+/**
+ * Create request for a generated board. The /validate result is the source of
+ * truth for level, techniques and solution; the /generate values are only a
+ * fallback when /validate omits them.
+ */
+export function buildValidatedBoard(generated, validateData, symmetrical) {
+    const board = validateData?.board;
+    const level = board?.level ?? generated.level;
+    // Prefers the exact `techniques_bitmask` string over the lossy number.
+    const techniques = board ? techniqueBitmaskOf(board) : 0n;
+    return {
+        request: {
+            board: generated.original,
+            solution: board?.solution ?? generated.solution,
+            level,
+            symmetrical,
+            techniques: formatTechniqueBitmask(techniques),
+        },
+        level,
+        techniques,
+    };
+}
+/** Update request that sets only a board's techniques bitmask and level. */
+export function buildBoardTechniquesUpdate(techniques, level) {
+    return {
+        techniques: formatTechniqueBitmask(techniques),
+        level,
+        symmetrical: undefined,
+        board: undefined,
+        solution: undefined,
+    };
+}
+const NO_BOARD_FILTERS = {
+    level: undefined,
+    symmetrical: undefined,
+    limit: undefined,
+    offset: undefined,
+    techniques: undefined,
+    technique_bit: undefined,
+};
+/** Filter for the next board whose techniques were never extracted. */
+export function boardsWithoutTechniquesQuery() {
+    return { ...NO_BOARD_FILTERS, techniques: 0, limit: 1 };
+}
+/**
+ * Filter for boards with the technique's bit set (API `technique_bit`, sent
+ * as an exact string). Not filtered by level: boards with the technique may
+ * sit at higher levels.
+ */
+export function boardsWithTechniqueQuery(techniqueId, limit) {
+    return {
+        ...NO_BOARD_FILTERS,
+        limit,
+        technique_bit: formatTechniqueBitmask(techniqueIdsToBitmask([techniqueId])),
+    };
+}
+/** Filter for boards at one level. */
+export function boardsAtLevelQuery(level, limit) {
+    return { ...NO_BOARD_FILTERS, level, limit };
+}
+/**
+ * Compare a frontend extraction with /validate. Exact bigint comparison: the
+ * numeric `techniques` drops low bits above 2^53, which would hide mismatches.
+ * Returns null when techniques and level both match.
+ */
+export function compareExtractionWithSolver(boardUuid, frontend, solver) {
+    const solverTechniques = techniqueBitmaskOf(solver);
+    if (solverTechniques === frontend.techniques &&
+        solver.level === frontend.level) {
+        return null;
+    }
+    return {
+        solverTechniques,
+        solverLevel: solver.level,
+        message: `MISMATCH: Board ${shortUuid(boardUuid)} - ` +
+            `FE techniques ${formatTechniqueMaskHex(frontend.techniques)} level ${frontend.level} vs ` +
+            `Solver techniques ${formatTechniqueMaskHex(solverTechniques)} level ${solver.level}`,
+    };
+}
+//# sourceMappingURL=boardRules.js.map

package/dist/admin/boardRules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boardRules.js","sourceRoot":"","sources":["../../src/admin/boardRules.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure rules for the board jobs: reading a /generate response, turning a\n * /validate result into a create request, the board query filters, and the\n * frontend-vs-solver comparison of the technique extractor.\n *\n * Masks are exact `bigint`s here and go on the wire as base-10 strings\n * (`formatTechniqueBitmask`): a JSON number drops the low bits once any\n * technique id >= 54 is set.\n *\n * Ported from `sudojo_app/src/utils/admin/BoardGenerator.ts`,\n * `TechniqueExtractor.ts` and `boardTechniquesApi.ts`.\n */\n\nimport {\n  type BoardCreateRequest,\n  type BoardQueryParams,\n  type BoardUpdateRequest,\n  formatTechniqueBitmask,\n  techniqueBitmaskOf,\n  type TechniqueId,\n  techniqueIdsToBitmask,\n  type ValidateData,\n} from '@sudobility/sudojo_types';\nimport { formatTechniqueMaskHex, shortUuid } from './boardStrings';\nimport type { BoardExtractionResult } from './extraction';\n\n/** Puzzle read from a /generate response. */\nexport interface GeneratedPuzzle {\n  level: number;\n  original: string;\n  solution: string;\n}\n\nexport type ParseGeneratedBoardResult =\n  | ({ ok: true } & GeneratedPuzzle)\n  | { ok: false; reason: 'invalid' | 'missing-puzzle' };\n\n/**\n * Read level/original/solution from a /generate `data`, tolerating the older\n * shapes the web app accepted: `{ board: { level, board: {original, …} } }`,\n * `{ board: { level, original, … } }` and `{ level, original, … }`.\n * `invalid` = no numeric level; `missing-puzzle` = no original.\n */\nexport function parseGeneratedBoard(data: unknown): ParseGeneratedBoardResult {\n  const root = asRecord(data);\n  const nested = asRecord(root?.board);\n  const boardData = nested?.level !== undefined ? nested : root;\n  if (!boardData || typeof boardData.level !== 'number') {\n    return { ok: false, reason: 'invalid' };\n  }\n\n  const puzzleData = asRecord(boardData.board) ?? boardData;\n  const inner = asRecord(puzzleData.board);\n  const original = firstString(puzzleData.original, inner?.original);\n  const solution = firstString(puzzleData.solution, inner?.solution);\n  if (!original) return { ok: false, reason: 'missing-puzzle' };\n\n  return { ok: true, level: boardData.level, original, solution };\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | null {\n  return typeof value === 'object' && value !== null\n    ? (value as Record<string, unknown>)\n    : null;\n}\n\nfunction firstString(...values: unknown[]): string {\n  for (const value of values) {\n    if (typeof value === 'string' && value) return value;\n  }\n  return '';\n}\n\n/** A board ready to save, with the values reported back to the UI. */\nexport interface ValidatedBoard {\n  request: BoardCreateRequest;\n  level: number;\n  /** Exact bitmask (bit N = technique N) */\n  techniques: bigint;\n}\n\n/**\n * Create request for a generated board. The /validate result is the source of\n * truth for level, techniques and solution; the /generate values are only a\n * fallback when /validate omits them.\n */\nexport function buildValidatedBoard(\n  generated: GeneratedPuzzle,\n  validateData: ValidateData | undefined | null,\n  symmetrical: boolean\n): ValidatedBoard {\n  const board = validateData?.board;\n  const level = board?.level ?? generated.level;\n  // Prefers the exact `techniques_bitmask` string over the lossy number.\n  const techniques = board ? techniqueBitmaskOf(board) : 0n;\n  return {\n    request: {\n      board: generated.original,\n      solution: board?.solution ?? generated.solution,\n      level,\n      symmetrical,\n      techniques: formatTechniqueBitmask(techniques),\n    },\n    level,\n    techniques,\n  };\n}\n\n/** Update request that sets only a board's techniques bitmask and level. */\nexport function buildBoardTechniquesUpdate(\n  techniques: bigint,\n  level: number | null\n): BoardUpdateRequest {\n  return {\n    techniques: formatTechniqueBitmask(techniques),\n    level,\n    symmetrical: undefined,\n    board: undefined,\n    solution: undefined,\n  };\n}\n\nconst NO_BOARD_FILTERS: BoardQueryParams = {\n  level: undefined,\n  symmetrical: undefined,\n  limit: undefined,\n  offset: undefined,\n  techniques: undefined,\n  technique_bit: undefined,\n};\n\n/** Filter for the next board whose techniques were never extracted. */\nexport function boardsWithoutTechniquesQuery(): BoardQueryParams {\n  return { ...NO_BOARD_FILTERS, techniques: 0, limit: 1 };\n}\n\n/**\n * Filter for boards with the technique's bit set (API `technique_bit`, sent\n * as an exact string). Not filtered by level: boards with the technique may\n * sit at higher levels.\n */\nexport function boardsWithTechniqueQuery(\n  techniqueId: TechniqueId,\n  limit: number\n): BoardQueryParams {\n  return {\n    ...NO_BOARD_FILTERS,\n    limit,\n    technique_bit: formatTechniqueBitmask(techniqueIdsToBitmask([techniqueId])),\n  };\n}\n\n/** Filter for boards at one level. */\nexport function boardsAtLevelQuery(\n  level: number,\n  limit: number\n): BoardQueryParams {\n  return { ...NO_BOARD_FILTERS, level, limit };\n}\n\n/** Frontend extraction disagreed with /validate. */\nexport interface ExtractionMismatch {\n  solverTechniques: bigint;\n  solverLevel: number;\n  message: string;\n}\n\n/**\n * Compare a frontend extraction with /validate. Exact bigint comparison: the\n * numeric `techniques` drops low bits above 2^53, which would hide mismatches.\n * Returns null when techniques and level both match.\n */\nexport function compareExtractionWithSolver(\n  boardUuid: string,\n  frontend: BoardExtractionResult,\n  solver: { level: number; techniques: number; techniques_bitmask?: string }\n): ExtractionMismatch | null {\n  const solverTechniques = techniqueBitmaskOf(solver);\n  if (\n    solverTechniques === frontend.techniques &&\n    solver.level === frontend.level\n  ) {\n    return null;\n  }\n  return {\n    solverTechniques,\n    solverLevel: solver.level,\n    message:\n      `MISMATCH: Board ${shortUuid(boardUuid)} - ` +\n      `FE techniques ${formatTechniqueMaskHex(frontend.techniques)} level ${frontend.level} vs ` +\n      `Solver techniques ${formatTechniqueMaskHex(solverTechniques)} level ${solver.level}`,\n  };\n}\n"]}

package/dist/admin/boardStrings.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Pure helpers on 81-char board strings and technique bitmasks used by the
+ * admin jobs.
+ *
+ * Ported from `sudojo_app/src/utils/admin/utils.ts` and the private helpers
+ * of `ExampleCreator.ts` / `TechniqueExtractor.ts`.
+ */
+/**
+ * True when every cell has a digit, taking the user's digit over the given.
+ *
+ * @param original - 81-char original puzzle (0 = empty)
+ * @param user - 81-char user input (0 = no input)
+ */
+export declare function isPuzzleFilled(original: string, user: string): boolean;
+/**
+ * True when every cell has a digit AND matches the solution.
+ *
+ * @param original - 81-char original puzzle (0 = empty)
+ * @param user - 81-char user input (0 = no input)
+ * @param solution - 81-char full solution
+ */
+export declare function isPuzzleSolved(original: string, user: string, solution: string): boolean;
+/** True when any solver hint step is the "Invalid Pencilmarks" correction. */
+export declare function hasInvalidPencilmarksStep(steps: ReadonlyArray<{
+    title?: string;
+}> | undefined | null): boolean;
+/**
+ * Overlay user input on the original board: each cell takes the user's digit
+ * when it is not '0', else the original's. Always returns 81 chars.
+ *
+ * The solver's `user` string never contains the givens, so a technique example
+ * must be stored as `mergeBoardWithUserInput(board.board, found.userInput)` or
+ * it comes out near-empty.
+ */
+export declare function mergeBoardWithUserInput(original: string, userInput: string): string;
+/**
+ * Solution for a practice built from `mergedBoard`: '0' wherever the merged
+ * board already has a digit, else the solution's digit. Always 81 chars.
+ */
+export declare function adjustPracticeSolution(mergedBoard: string, solution: string): string;
+/** `0x…` form of an exact technique bitmask, for progress lines. */
+export declare function formatTechniqueMaskHex(mask: bigint): string;
+/** Log-friendly forms of an exact bitmask (decimal, binary, hex). */
+export declare function describeTechniqueMask(mask: bigint): {
+    techniques: string;
+    techniquesBinary: string;
+    techniquesHex: string;
+};
+/** Level to store for a board: positive levels as-is, 0 or less as null. */
+export declare function levelToSave(level: number): number | null;
+/** First 8 chars of a UUID, as used in every admin progress line. */
+export declare function shortUuid(uuid: string): string;
+/** Message of an unknown thrown value. */
+export declare function errorMessage(err: unknown): string;
+//# sourceMappingURL=boardStrings.d.ts.map

package/dist/admin/boardStrings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boardStrings.d.ts","sourceRoot":"","sources":["../../src/admin/boardStrings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAOtE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,OAAO,CAOT;AAED,8EAA8E;AAC9E,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,aAAa,CAAC;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,GAAG,IAAI,GAC1D,OAAO,CAGT;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,CAOR;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,MAAM,CAMR;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;CACvB,CAMA;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAExD;AAED,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,0CAA0C;AAC1C,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEjD"}

package/dist/admin/boardStrings.js

@@ -0,0 +1,99 @@
+/**
+ * Pure helpers on 81-char board strings and technique bitmasks used by the
+ * admin jobs.
+ *
+ * Ported from `sudojo_app/src/utils/admin/utils.ts` and the private helpers
+ * of `ExampleCreator.ts` / `TechniqueExtractor.ts`.
+ */
+import { formatTechniqueBitmask, TOTAL_CELLS } from '@sudobility/sudojo_types';
+/** Digit at `index`, or '0' when the string is short. */
+const cellAt = (board, index) => board[index] || '0';
+/**
+ * True when every cell has a digit, taking the user's digit over the given.
+ *
+ * @param original - 81-char original puzzle (0 = empty)
+ * @param user - 81-char user input (0 = no input)
+ */
+export function isPuzzleFilled(original, user) {
+    for (let i = 0; i < TOTAL_CELLS; i++) {
+        const userChar = cellAt(user, i);
+        const actual = userChar !== '0' ? userChar : cellAt(original, i);
+        if (actual === '0')
+            return false;
+    }
+    return true;
+}
+/**
+ * True when every cell has a digit AND matches the solution.
+ *
+ * @param original - 81-char original puzzle (0 = empty)
+ * @param user - 81-char user input (0 = no input)
+ * @param solution - 81-char full solution
+ */
+export function isPuzzleSolved(original, user, solution) {
+    for (let i = 0; i < TOTAL_CELLS; i++) {
+        const userChar = cellAt(user, i);
+        const actual = userChar !== '0' ? userChar : cellAt(original, i);
+        if (actual === '0' || actual !== cellAt(solution, i))
+            return false;
+    }
+    return true;
+}
+/** True when any solver hint step is the "Invalid Pencilmarks" correction. */
+export function hasInvalidPencilmarksStep(steps) {
+    if (!steps)
+        return false;
+    return steps.some(step => step.title === 'Invalid Pencilmarks');
+}
+/**
+ * Overlay user input on the original board: each cell takes the user's digit
+ * when it is not '0', else the original's. Always returns 81 chars.
+ *
+ * The solver's `user` string never contains the givens, so a technique example
+ * must be stored as `mergeBoardWithUserInput(board.board, found.userInput)` or
+ * it comes out near-empty.
+ */
+export function mergeBoardWithUserInput(original, userInput) {
+    let result = '';
+    for (let i = 0; i < TOTAL_CELLS; i++) {
+        const userChar = cellAt(userInput, i);
+        result += userChar !== '0' ? userChar : cellAt(original, i);
+    }
+    return result;
+}
+/**
+ * Solution for a practice built from `mergedBoard`: '0' wherever the merged
+ * board already has a digit, else the solution's digit. Always 81 chars.
+ */
+export function adjustPracticeSolution(mergedBoard, solution) {
+    let result = '';
+    for (let i = 0; i < TOTAL_CELLS; i++) {
+        result += cellAt(mergedBoard, i) !== '0' ? '0' : cellAt(solution, i);
+    }
+    return result;
+}
+/** `0x…` form of an exact technique bitmask, for progress lines. */
+export function formatTechniqueMaskHex(mask) {
+    return `0x${mask.toString(16)}`;
+}
+/** Log-friendly forms of an exact bitmask (decimal, binary, hex). */
+export function describeTechniqueMask(mask) {
+    return {
+        techniques: formatTechniqueBitmask(mask),
+        techniquesBinary: `0b${mask.toString(2)}`,
+        techniquesHex: formatTechniqueMaskHex(mask),
+    };
+}
+/** Level to store for a board: positive levels as-is, 0 or less as null. */
+export function levelToSave(level) {
+    return level > 0 ? level : null;
+}
+/** First 8 chars of a UUID, as used in every admin progress line. */
+export function shortUuid(uuid) {
+    return uuid.slice(0, 8);
+}
+/** Message of an unknown thrown value. */
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=boardStrings.js.map

package/dist/admin/boardStrings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boardStrings.js","sourceRoot":"","sources":["../../src/admin/boardStrings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure helpers on 81-char board strings and technique bitmasks used by the\n * admin jobs.\n *\n * Ported from `sudojo_app/src/utils/admin/utils.ts` and the private helpers\n * of `ExampleCreator.ts` / `TechniqueExtractor.ts`.\n */\n\nimport { formatTechniqueBitmask, TOTAL_CELLS } from '@sudobility/sudojo_types';\n\n/** Digit at `index`, or '0' when the string is short. */\nconst cellAt = (board: string, index: number): string => board[index] || '0';\n\n/**\n * True when every cell has a digit, taking the user's digit over the given.\n *\n * @param original - 81-char original puzzle (0 = empty)\n * @param user - 81-char user input (0 = no input)\n */\nexport function isPuzzleFilled(original: string, user: string): boolean {\n  for (let i = 0; i < TOTAL_CELLS; i++) {\n    const userChar = cellAt(user, i);\n    const actual = userChar !== '0' ? userChar : cellAt(original, i);\n    if (actual === '0') return false;\n  }\n  return true;\n}\n\n/**\n * True when every cell has a digit AND matches the solution.\n *\n * @param original - 81-char original puzzle (0 = empty)\n * @param user - 81-char user input (0 = no input)\n * @param solution - 81-char full solution\n */\nexport function isPuzzleSolved(\n  original: string,\n  user: string,\n  solution: string\n): boolean {\n  for (let i = 0; i < TOTAL_CELLS; i++) {\n    const userChar = cellAt(user, i);\n    const actual = userChar !== '0' ? userChar : cellAt(original, i);\n    if (actual === '0' || actual !== cellAt(solution, i)) return false;\n  }\n  return true;\n}\n\n/** True when any solver hint step is the \"Invalid Pencilmarks\" correction. */\nexport function hasInvalidPencilmarksStep(\n  steps: ReadonlyArray<{ title?: string }> | undefined | null\n): boolean {\n  if (!steps) return false;\n  return steps.some(step => step.title === 'Invalid Pencilmarks');\n}\n\n/**\n * Overlay user input on the original board: each cell takes the user's digit\n * when it is not '0', else the original's. Always returns 81 chars.\n *\n * The solver's `user` string never contains the givens, so a technique example\n * must be stored as `mergeBoardWithUserInput(board.board, found.userInput)` or\n * it comes out near-empty.\n */\nexport function mergeBoardWithUserInput(\n  original: string,\n  userInput: string\n): string {\n  let result = '';\n  for (let i = 0; i < TOTAL_CELLS; i++) {\n    const userChar = cellAt(userInput, i);\n    result += userChar !== '0' ? userChar : cellAt(original, i);\n  }\n  return result;\n}\n\n/**\n * Solution for a practice built from `mergedBoard`: '0' wherever the merged\n * board already has a digit, else the solution's digit. Always 81 chars.\n */\nexport function adjustPracticeSolution(\n  mergedBoard: string,\n  solution: string\n): string {\n  let result = '';\n  for (let i = 0; i < TOTAL_CELLS; i++) {\n    result += cellAt(mergedBoard, i) !== '0' ? '0' : cellAt(solution, i);\n  }\n  return result;\n}\n\n/** `0x…` form of an exact technique bitmask, for progress lines. */\nexport function formatTechniqueMaskHex(mask: bigint): string {\n  return `0x${mask.toString(16)}`;\n}\n\n/** Log-friendly forms of an exact bitmask (decimal, binary, hex). */\nexport function describeTechniqueMask(mask: bigint): {\n  techniques: string;\n  techniquesBinary: string;\n  techniquesHex: string;\n} {\n  return {\n    techniques: formatTechniqueBitmask(mask),\n    techniquesBinary: `0b${mask.toString(2)}`,\n    techniquesHex: formatTechniqueMaskHex(mask),\n  };\n}\n\n/** Level to store for a board: positive levels as-is, 0 or less as null. */\nexport function levelToSave(level: number): number | null {\n  return level > 0 ? level : null;\n}\n\n/** First 8 chars of a UUID, as used in every admin progress line. */\nexport function shortUuid(uuid: string): string {\n  return uuid.slice(0, 8);\n}\n\n/** Message of an unknown thrown value. */\nexport function errorMessage(err: unknown): string {\n  return err instanceof Error ? err.message : String(err);\n}\n"]}

package/dist/admin/examples.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Pure rules for the technique-example creator: which techniques still need
+ * examples, where to search for boards, and the example + linked practice
+ * requests built from a find.
+ *
+ * Ported from `sudojo_app/src/utils/admin/ExampleCreator.ts` and the
+ * constants of `sudojo_app/src/pages/AdminPage.tsx`.
+ */
+import { type Board, type Technique, type TechniqueExampleCreateRequest, type TechniqueId, type TechniquePracticeCreateRequest } from '@sudobility/sudojo_types';
+import type { TechniqueExampleFound } from './extraction';
+/** Examples wanted per technique. */
+export declare const ADMIN_EXAMPLE_TARGET_PER_TECHNIQUE = 1;
+/** Every technique id, easiest (lowest id) first: the creator's work order. */
+export declare const ADMIN_TECHNIQUE_ORDER: readonly TechniqueId[];
+/** Boards fetched per technique by bit. */
+export declare const BOARDS_WITH_TECHNIQUE_LIMIT = 50;
+/** Boards fetched per level in the level-based search. */
+export declare const BOARDS_PER_LEVEL_LIMIT = 100;
+/** Example counts keyed by technique id. */
+export type TechniqueCounts = Readonly<Record<number, number>>;
+/**
+ * Normalize an API counts map (string keys, e.g. `/examples/counts`) to
+ * numeric technique-id keys. null/undefined → {}.
+ */
+export declare function normalizeTechniqueCounts(data: Readonly<Record<string, number>> | Readonly<Record<number, number>> | null | undefined): Record<number, number>;
+/** Count for a technique (0 when absent). */
+export declare function countForTechnique(counts: TechniqueCounts, techniqueId: number): number;
+/** True when the technique already has `target` examples. */
+export declare function hasReachedTarget(counts: TechniqueCounts, techniqueId: number, target: number): boolean;
+/** Techniques in `order` that still need examples. */
+export declare function techniquesNeedingExamples(order: readonly TechniqueId[], counts: TechniqueCounts, target: number): TechniqueId[];
+/** Sum of all counts. */
+export declare function totalTechniqueCount(counts: TechniqueCounts): number;
+/** technique id → level (null when the technique has no level). */
+export declare function buildTechniqueLevelMap(techniques: readonly Technique[] | null | undefined): Map<number, number | null>;
+/**
+ * Levels to search, in order, for a technique at `techniqueLevel`: one below,
+ * its own, then two above (a technique often first appears on harder
+ * boards). Clamped to MIN_LEVEL..MAX_LEVEL.
+ */
+export declare function levelsToSearchForTechnique(techniqueLevel: number): number[];
+/** Requests to save a find: the example, then (after it) the linked practice. */
+export interface ExampleSaveRequests {
+    /** Source givens + the cells the solver filled before reaching the technique */
+    mergedBoard: string;
+    example: TechniqueExampleCreateRequest;
+    /** Practice request without `source_example_uuid` (set it from the example) */
+    practice: TechniquePracticeCreateRequest;
+}
+/**
+ * Build the example and practice requests for a find on `board`.
+ *
+ * `found.userInput` holds only the solver's cells (never the givens), so the
+ * stored board is `mergeBoardWithUserInput(board.board, found.userInput)`.
+ * The practice's solution is blanked ('0') wherever that board is filled.
+ */
+export declare function buildExampleSaveRequests(board: Pick<Board, 'uuid' | 'board' | 'solution'>, found: TechniqueExampleFound): ExampleSaveRequests;
+//# sourceMappingURL=examples.d.ts.map

package/dist/admin/examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"examples.d.ts","sourceRoot":"","sources":["../../src/admin/examples.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,KAAK,KAAK,EAIV,KAAK,SAAS,EACd,KAAK,6BAA6B,EAClC,KAAK,WAAW,EAEhB,KAAK,8BAA8B,EACpC,MAAM,0BAA0B,CAAC;AAKlC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,qCAAqC;AACrC,eAAO,MAAM,kCAAkC,IAAI,CAAC;AAEpD,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,EAAE,SAAS,WAAW,EAEjC,CAAC;AAExB,2CAA2C;AAC3C,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,0DAA0D;AAC1D,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,4CAA4C;AAC5C,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EACA,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAChC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAChC,IAAI,GACJ,SAAS,GACZ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxB;AAED,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAET;AAED,sDAAsD;AACtD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,GACb,WAAW,EAAE,CAEf;AAED,yBAAyB;AACzB,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAEnE;AAED,mEAAmE;AACnE,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,GAAG,SAAS,GAClD,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAI5B;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,CAO3E;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,6BAA6B,CAAC;IACvC,+EAA+E;IAC/E,QAAQ,EAAE,8BAA8B,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC,EACjD,KAAK,EAAE,qBAAqB,GAC3B,mBAAmB,CA0BrB"}