@fgv/ts-sudoku-lib 5.0.1-0 → 5.0.1-2

package/lib/packlets/puzzles/killerCombinations.js

@@ -0,0 +1,226 @@
+"use strict";
+/*
+ * MIT License
+ *
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KillerCombinations = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../common");
+const combinationCache_1 = require("./internal/combinationCache");
+const combinationGenerator_1 = require("./internal/combinationGenerator");
+const possibilityAnalyzer_1 = require("./internal/possibilityAnalyzer");
+/**
+ * Helper class providing UI assistance functions for killer sudoku puzzle solving.
+ * Generates possible totals, number combinations with constraints, and cell-specific
+ * possibilities based on current puzzle state.
+ * @public
+ */
+class KillerCombinations {
+    /**
+     * Gets all mathematically possible totals for a given cage size.
+     *
+     * Uses the existing totalsByCageSize constant to determine the valid range
+     * of totals for the specified cage size and returns all integers in that range.
+     *
+     * @param cageSize - The number of cells in the cage (must be 1-9)
+     * @returns Result containing array of possible totals in ascending order
+     *
+     * @example
+     * ```typescript
+     * // Get possible totals for a 3-cell cage
+     * const result = KillerCombinations.getPossibleTotals(3);
+     * if (result.isSuccess()) {
+     *   console.log(result.value); // [6, 7, 8, 9, ..., 24]
+     * }
+     * ```
+     */
+    static getPossibleTotals(cageSize, maxValue = 9) {
+        // Validate cage size
+        if (!Number.isInteger(cageSize) || cageSize < 1 || cageSize > maxValue) {
+            return (0, ts_utils_1.fail)(`Cage size must be an integer between 1 and ${maxValue}, got ${cageSize}`);
+        }
+        const bounds = (0, common_1.getCageTotalBounds)(cageSize, maxValue);
+        // Generate all totals in the valid range
+        const totals = [];
+        for (let total = bounds.min; total <= bounds.max; total++) {
+            totals.push(total);
+        }
+        return (0, ts_utils_1.succeed)(totals);
+    }
+    /**
+     * Generates all possible number combinations that sum to the target total.
+     *
+     * Each combination contains unique numbers from 1-9 that sum exactly to the
+     * specified total. Combinations respect both excluded and required number
+     * constraints if provided.
+     *
+     * @param cageSize - The number of cells in the cage (must be 1-9)
+     * @param total - The target sum (must be valid for the cage size)
+     * @param constraints - Optional constraints on included/excluded numbers
+     * @returns Result containing array of combinations, each sorted in ascending order
+     *
+     * @example
+     * ```typescript
+     * // Get all combinations for a 3-cell cage with total 15
+     * const result = KillerCombinations.getCombinations(3, 15);
+     * if (result.isSuccess()) {
+     *   console.log(result.value); // [[1,5,9], [1,6,8], [2,4,9], ...]
+     * }
+     *
+     * // With constraints - exclude 1 and 2, require 9
+     * const constrained = KillerCombinations.getCombinations(3, 15, {
+     *   excludedNumbers: [1, 2],
+     *   requiredNumbers: [9]
+     * });
+     * ```
+     */
+    static getCombinations(cageSize, total, constraints, maxValue = 9) {
+        // Validate cage size
+        if (!Number.isInteger(cageSize) || cageSize < 1 || cageSize > maxValue) {
+            return (0, ts_utils_1.fail)(`Cage size must be an integer between 1 and ${maxValue}, got ${cageSize}`);
+        }
+        // Validate total against cage size bounds
+        const bounds = (0, common_1.getCageTotalBounds)(cageSize, maxValue);
+        if (!Number.isInteger(total) || total < bounds.min || total > bounds.max) {
+            return (0, ts_utils_1.fail)(`Total ${total} is invalid for cage size ${cageSize} - valid range: ${bounds.min}-${bounds.max}`);
+        }
+        // Validate constraints
+        const constraintValidation = this._validateConstraints(constraints, maxValue);
+        if (constraintValidation.isFailure()) {
+            return (0, ts_utils_1.fail)(constraintValidation.message);
+        }
+        // Check cache first
+        const cacheKey = combinationCache_1.CombinationCache.generateKey(cageSize, total, constraints);
+        const cached = combinationCache_1.CombinationCache.get(cacheKey);
+        if (cached) {
+            return (0, ts_utils_1.succeed)(cached);
+        }
+        // Generate combinations
+        const combinations = combinationGenerator_1.CombinationGenerator.generate(cageSize, total, constraints, maxValue);
+        // Cache the result
+        combinationCache_1.CombinationCache.set(cacheKey, combinations);
+        return (0, ts_utils_1.succeed)(combinations);
+    }
+    /**
+     * Determines possible values for each cell in a killer cage based on current puzzle state.
+     *
+     * Analyzes the current state of the puzzle and cage to determine which values
+     * are possible for each empty cell, considering both killer cage constraints
+     * and standard sudoku constraints (row, column, section uniqueness).
+     *
+     * @param puzzle - The puzzle instance
+     * @param state - Current puzzle state
+     * @param cage - The killer cage to analyze (must be of type 'killer')
+     * @returns Result containing map of CellId to possible number arrays
+     *
+     * @example
+     * ```typescript
+     * const cage = puzzle.getCage(cageId).orThrow();
+     * const possibilities = KillerCombinations.getCellPossibilities(puzzle, state, cage);
+     * if (possibilities.isSuccess()) {
+     *   for (const [cellId, values] of possibilities.value) {
+     *     console.log(`Cell ${cellId} can have values: ${values.join(', ')}`);
+     *   }
+     * }
+     * ```
+     */
+    static getCellPossibilities(puzzle, state, cage) {
+        // Validate cage type
+        if (cage.cageType !== 'killer') {
+            return (0, ts_utils_1.fail)(`Expected killer cage, got ${cage.cageType}`);
+        }
+        // Get current values in the cage to build constraints
+        // We need the concrete Cage class for containedValues method
+        const concreteCage = cage;
+        const currentValues = concreteCage.containedValues(state);
+        const constraints = {
+            excludedNumbers: Array.from(currentValues)
+        };
+        // Get valid combinations for this cage
+        const combinationsResult = this.getCombinations(cage.numCells, cage.total, constraints);
+        /* c8 ignore next 3 - error propagation from getCombinations already tested, integration error hard to trigger */
+        if (combinationsResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Failed to get combinations for cage ${cage.id}: ${combinationsResult.message}`);
+        }
+        // Analyze possibilities for each cell
+        return possibilityAnalyzer_1.PossibilityAnalyzer.analyze(puzzle, state, cage, combinationsResult.value);
+    }
+    /**
+     * Validate constraint parameters.
+     * @param constraints - Constraints to validate
+     * @param maxValue - Maximum value allowed in cells
+     * @returns Result indicating success or failure with error message
+     */
+    static _validateConstraints(constraints, maxValue = 9) {
+        if (!constraints) {
+            return (0, ts_utils_1.succeed)(true);
+        }
+        // Validate excluded numbers
+        if (constraints.excludedNumbers) {
+            const excluded = constraints.excludedNumbers;
+            if (!Array.isArray(excluded)) {
+                return (0, ts_utils_1.fail)('excludedNumbers must be an array');
+            }
+            for (const num of excluded) {
+                if (!Number.isInteger(num) || num < 1 || num > maxValue) {
+                    return (0, ts_utils_1.fail)(`excludedNumbers must contain integers between 1-${maxValue}, got ${num}`);
+                }
+            }
+            // Check for duplicates
+            const uniqueExcluded = new Set(excluded);
+            if (uniqueExcluded.size !== excluded.length) {
+                return (0, ts_utils_1.fail)('excludedNumbers must not contain duplicates');
+            }
+        }
+        // Validate required numbers
+        if (constraints.requiredNumbers) {
+            const required = constraints.requiredNumbers;
+            if (!Array.isArray(required)) {
+                return (0, ts_utils_1.fail)('requiredNumbers must be an array');
+            }
+            for (const num of required) {
+                if (!Number.isInteger(num) || num < 1 || num > maxValue) {
+                    return (0, ts_utils_1.fail)(`requiredNumbers must contain integers between 1-${maxValue}, got ${num}`);
+                }
+            }
+            // Check for duplicates
+            const uniqueRequired = new Set(required);
+            if (uniqueRequired.size !== required.length) {
+                return (0, ts_utils_1.fail)('requiredNumbers must not contain duplicates');
+            }
+        }
+        // Check for overlap between excluded and required
+        if (constraints.excludedNumbers && constraints.requiredNumbers) {
+            const excludedSet = new Set(constraints.excludedNumbers);
+            const requiredSet = new Set(constraints.requiredNumbers);
+            for (const required of requiredSet) {
+                if (excludedSet.has(required)) {
+                    return (0, ts_utils_1.fail)(`Number ${required} cannot be both required and excluded`);
+                }
+            }
+        }
+        return (0, ts_utils_1.succeed)(true);
+    }
+}
+exports.KillerCombinations = KillerCombinations;
+//# sourceMappingURL=killerCombinations.js.map

package/lib/packlets/puzzles/killerCombinationsTypes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Constraints that can be applied when generating killer cage combinations.
+ * @public
+ */
+export interface IKillerConstraints {
+    /**
+     * Numbers that cannot be present in the combination.
+     * Must be unique values between 1-9.
+     */
+    readonly excludedNumbers?: readonly number[];
+    /**
+     * Numbers that must be present in the combination.
+     * Must be unique values between 1-9.
+     */
+    readonly requiredNumbers?: readonly number[];
+}
+//# sourceMappingURL=killerCombinationsTypes.d.ts.map

package/lib/packlets/puzzles/killerCombinationsTypes.js

@@ -0,0 +1,26 @@
+"use strict";
+/*
+ * MIT License
+ *
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=killerCombinationsTypes.js.map

package/lib/packlets/puzzles/killerSudokuPuzzle.d.ts

@@ -1,11 +1,11 @@
 import { Result } from '@fgv/ts-utils';
-import { IPuzzleDescription, Puzzle } from '../common';
+import { IPuzzleDefinition, Puzzle } from '../common';
 /**
  * @public
  */
 export declare class KillerSudokuPuzzle extends Puzzle {
     private constructor();
-    static create(desc: IPuzzleDescription): Result<Puzzle>;
+    static create(desc: IPuzzleDefinition): Result<Puzzle>;
     private static _getKillerCages;
     private static _getCageCells;
     private static _getCages;

package/lib/packlets/puzzles/killerSudokuPuzzle.js

@@ -53,6 +53,7 @@ class KillerSudokuPuzzle extends common_1.Puzzle {
     }
     static _getKillerCages(puzzle) {
         const decl = puzzle.cells.split('|');
+        /* c8 ignore next 3 - tested but coverage has intermittent issues */
         if (decl.length !== 2) {
             throw new Error(`malformed cells|cages "${puzzle.cells}"`);
         }
@@ -66,13 +67,14 @@ class KillerSudokuPuzzle extends common_1.Puzzle {
         var _a;
         const cages = new Map();
         const cageMapping = Array.from(mappingDecl);
-        if (cageMapping.length !== puzzle.rows * puzzle.cols) {
-            const expected = puzzle.rows * puzzle.cols;
+        /* c8 ignore next 5 - defensive coding: protected by validation in puzzleDefinitions.ts */
+        if (cageMapping.length !== puzzle.totalRows * puzzle.totalColumns) {
+            const expected = puzzle.totalRows * puzzle.totalColumns;
             const got = cageMapping.length;
             throw new Error(`expected ${expected} cell mappings, found ${got}`);
         }
-        for (let row = 0; row < puzzle.rows; row++) {
-            for (let col = 0; col < puzzle.cols; col++) {
+        for (let row = 0; row < puzzle.totalRows; row++) {
+            for (let col = 0; col < puzzle.totalColumns; col++) {
                 const cage = cageMapping.shift();
                 const cell = common_1.Ids.cellId({ row, col }).orThrow();
                 const cells = (_a = cages.get(cage)) !== null && _a !== void 0 ? _a : [];
@@ -82,7 +84,7 @@ class KillerSudokuPuzzle extends common_1.Puzzle {
         }
         return cages;
     }
-    static _getCages(__puzzle, cageCells, cagePart) {
+    static _getCages(puzzle, cageCells, cagePart) {
         const cages = new Map();
         const cageDefs = cagePart.split(',');
         if (cageDefs.length !== cageCells.size) {
@@ -100,10 +102,12 @@ class KillerSudokuPuzzle extends common_1.Puzzle {
             if (!cells) {
                 throw new Error(`cage ${cageId} has no cells`);
             }
-            if (cells.length < 1 || cells.length > 9) {
-                throw new Error(`invalid cell count ${cells.length} for cage ${cageId}`);
+            // Use the puzzle's maxValue for dynamic validation
+            const maxValue = puzzle.maxValue;
+            if (cells.length < 1 || cells.length > maxValue) {
+                throw new Error(`invalid cell count ${cells.length} for cage ${cageId} (max ${maxValue})`);
             }
-            const { min, max } = common_1.totalsByCageSize[cells.length];
+            const { min, max } = (0, common_1.getCageTotalBounds)(cells.length, maxValue);
             if (total < min || total > max) {
                 throw new Error(`invalid total ${total} for cage ${cageId} (expected ${min}..${max})`);
             }
@@ -113,13 +117,13 @@ class KillerSudokuPuzzle extends common_1.Puzzle {
     }
     static _getKillerCells(puzzle, givens) {
         const cells = [];
-        for (let row = 0; row < puzzle.rows; row++) {
-            for (let col = 0; col < puzzle.cols; col++) {
+        for (let row = 0; row < puzzle.totalRows; row++) {
+            for (let col = 0; col < puzzle.totalColumns; col++) {
                 const cellId = common_1.Ids.cellId({ row, col }).orThrow();
                 const cage = givens.find((g) => g.cellIds[0] === cellId);
                 if (cage) {
                     /* c8 ignore next 3 - defense in depth should never happen */
-                    if (cage.total < 1 || cage.total > 9) {
+                    if (cage.total < 1 || cage.total > puzzle.maxValue) {
                         throw new Error(`invalid total ${cage.total} for cell ${cellId}`);
                     }
                     cells.push(String(cage.total));

package/lib/packlets/puzzles/sudokuPuzzle.d.ts

@@ -1,10 +1,10 @@
 import { Result } from '@fgv/ts-utils';
-import { IPuzzleDescription, Puzzle } from '../common';
+import { IPuzzleDefinition, Puzzle } from '../common';
 /**
  * @public
  */
 export declare class SudokuPuzzle extends Puzzle {
     private constructor();
-    static create(puzzle: IPuzzleDescription): Result<Puzzle>;
+    static create(puzzle: IPuzzleDefinition): Result<Puzzle>;
 }
 //# sourceMappingURL=sudokuPuzzle.d.ts.map

package/lib/packlets/puzzles/sudokuXPuzzle.d.ts

@@ -1,11 +1,11 @@
 import { Result } from '@fgv/ts-utils';
-import { IPuzzleDescription, Puzzle } from '../common';
+import { IPuzzleDefinition, Puzzle } from '../common';
 /**
  * @public
  */
 export declare class SudokuXPuzzle extends Puzzle {
     private constructor();
-    static create(puzzle: IPuzzleDescription): Result<Puzzle>;
+    static create(puzzle: IPuzzleDefinition): Result<Puzzle>;
     private static _getXCages;
 }
 //# sourceMappingURL=sudokuXPuzzle.d.ts.map

package/lib/packlets/puzzles/sudokuXPuzzle.js

@@ -36,7 +36,11 @@ class SudokuXPuzzle extends common_1.Puzzle {
     static create(puzzle) {
         /* c8 ignore next 3 */
         if (puzzle.type !== 'sudoku-x') {
-            return fail(`Puzzle '${puzzle.description}' unsupported type ${puzzle.type}`);
+            return (0, ts_utils_1.fail)(`Puzzle '${puzzle.description}' unsupported type ${puzzle.type}`);
+        }
+        // Sudoku X diagonals work for any square puzzle (totalRows === totalColumns)
+        if (puzzle.totalRows !== puzzle.totalColumns) {
+            return (0, ts_utils_1.fail)(`Sudoku X puzzle must be square, got ${puzzle.totalRows}x${puzzle.totalColumns}`);
         }
         return (0, ts_utils_1.captureResult)(() => {
             return new SudokuXPuzzle(puzzle, SudokuXPuzzle._getXCages(puzzle));
@@ -47,14 +51,14 @@ class SudokuXPuzzle extends common_1.Puzzle {
     static _getXCages(puzzle) {
         const x1Cells = [];
         const x2Cells = [];
-        for (let row = 0, col1 = 0, col2 = puzzle.cols - 1; row < puzzle.rows; row++, col1++, col2--) {
+        for (let row = 0, col1 = 0, col2 = puzzle.totalColumns - 1; row < puzzle.totalRows; row++, col1++, col2--) {
             x1Cells.push(common_1.Ids.cellId({ row, col: col1 }).orThrow());
             x2Cells.push(common_1.Ids.cellId({ row, col: col2 }).orThrow());
         }
         const x1Id = common_1.Ids.cageId('X1').orThrow();
         const x2Id = common_1.Ids.cageId('X2').orThrow();
-        const x1 = common_1.Cage.create(x1Id, 'x', 45, x1Cells).orThrow();
-        const x2 = common_1.Cage.create(x2Id, 'x', 45, x2Cells).orThrow();
+        const x1 = common_1.Cage.create(x1Id, 'x', puzzle.basicCageTotal, x1Cells).orThrow();
+        const x2 = common_1.Cage.create(x2Id, 'x', puzzle.basicCageTotal, x2Cells).orThrow();
         return [
             [x1Id, x1],
             [x2Id, x2]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-sudoku-lib",
-  "version": "5.0.1-0",
+  "version": "5.0.1-2",
   "description": "Sudoku rules library",
   "main": "lib/index.js",
   "types": "dist/ts-sudoku-lib.d.ts",
@@ -43,12 +43,12 @@
     "@rushstack/eslint-config": "4.4.0",
     "@rushstack/heft-jest-plugin": "0.16.13",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils": "5.0.1-0",
-    "@fgv/ts-utils-jest": "5.0.1-0",
-    "@fgv/ts-json-base": "5.0.1-0"
+    "@fgv/ts-utils": "5.0.1-2",
+    "@fgv/ts-json-base": "5.0.1-2",
+    "@fgv/ts-utils-jest": "5.0.1-2"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.0.1-0"
+    "@fgv/ts-utils": "5.0.1-2"
   },
   "scripts": {
     "build": "heft build --clean",

package/sample-12x12-puzzle.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+// Sample 12x12 puzzle generated from screenshot
+const { PuzzleDefinitionFactory, STANDARD_CONFIGS } = require('./lib/packlets/common');
+
+console.log('🧩 Sample 12x12 Sudoku Puzzle\n');
+
+// 12x12 puzzle from screenshot
+// Note: A=10, B=11, C=12 in standard 12x12 Sudoku
+// Rebuilding with exact 12 chars per row (total 144):
+// Row 0:  ..1.6.2.A7..  (12 chars)
+// Row 1:  62.5B....1..  (12 chars)
+// Row 2:  .8....C3B.62  (12 chars)
+// Row 3:  A97.2.6..B5.  (12 chars)
+// Row 4:  .5......37C.  (12 chars) - was missing final .
+// Row 5:  3B....7...9.  (12 chars) - was missing final .
+// Row 6:  57B.4.....1.  (12 chars) - was missing final .
+// Row 7:  8.....A.9...  (12 chars) - was missing final .
+// Row 8:  .4..97...6..  (12 chars)
+// Row 9:  .1C.......B.  (12 chars) - was missing final .
+// Row 10: 4....2.C....  (12 chars) - was missing final .
+// Row 11: ....5C..7126  (12 chars)
+
+const puzzle12x12Description = {
+  description: 'Sample 12x12 Sudoku #1',
+  type: 'sudoku',
+  level: 3,
+  cells:
+    '..1.6.2.A7..62.5B....1...8....C3B.62A97.2.6..B5..5......37C.3B....7...9.57B.4.....1.8.....A.9....4..97...6...1C.......B.4....2.C........5C..7126'
+};
+
+// Create puzzle definition
+console.log('Creating 12x12 puzzle definition...\n');
+
+const puzzleResult = PuzzleDefinitionFactory.create(STANDARD_CONFIGS.puzzle12x12, puzzle12x12Description);
+
+if (puzzleResult.isSuccess()) {
+  const puzzle = puzzleResult.value;
+
+  console.log('✅ 12x12 Puzzle:');
+  console.log(`  Description: ${puzzle.description}`);
+  console.log(`  Grid: ${puzzle.totalRows}x${puzzle.totalColumns}`);
+  console.log(`  Cage dimensions: ${puzzle.cageWidthInCells}x${puzzle.cageHeightInCells} (4 wide x 3 high)`);
+  console.log(`  Board dimensions: ${puzzle.boardWidthInCages}x${puzzle.boardHeightInCages} cages`);
+  console.log(`  Max value: ${puzzle.maxValue}`);
+  console.log(`  Cage total: ${puzzle.basicCageTotal} (sum 1+2+...+12 = 78)`);
+  console.log(`  Cells: ${puzzle.cells}`);
+  console.log('\n  Grid layout:');
+
+  for (let row = 0; row < 12; row++) {
+    const rowCells = puzzle.cells.slice(row * 12, (row + 1) * 12).split('');
+    const displayRow = rowCells.map((c) => (c === '.' ? ' ' : c)).join(' ');
+    console.log(`    ${displayRow}`);
+
+    // Show cage boundaries after rows 2, 5, 8
+    if (row === 2 || row === 5 || row === 8) {
+      console.log('    -----------------------------------------------'); // Horizontal cage separator
+    }
+  }
+
+  console.log('\n  Cage structure (4x3 sections):');
+  console.log('    Each cage is 4 cells wide × 3 cells high');
+  console.log('    Grid has 3×4 = 12 total cages');
+  console.log('    Values: 1,2,3,4,5,6,7,8,9,A(10),B(11),C(12)');
+
+  console.log('\n🎯 12x12 puzzle definition created successfully!');
+  console.log('This puzzle uses 4x3 cage dimensions with 3x4 cage layout.');
+  console.log('Each cage must contain all values 1-12 (represented as 1-9,A,B,C).');
+} else {
+  console.error('❌ Failed to create 12x12 puzzle definition:');
+  console.error(`  Error: ${puzzleResult.message}`);
+}

package/sample-4x4-puzzles.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+// Sample 4x4 puzzles generated from screenshot
+const { PuzzleDefinitionFactory, STANDARD_CONFIGS } = require('./lib/packlets/common');
+
+console.log('🧩 Sample 4x4 Sudoku Puzzles\n');
+
+// First 4x4 puzzle from screenshot
+const puzzle1Description = {
+  description: 'Sample 4x4 Sudoku #1',
+  type: 'sudoku',
+  level: 1,
+  cells: '..1....2.2....4.'
+};
+
+// Second 4x4 puzzle from screenshot
+const puzzle2Description = {
+  description: 'Sample 4x4 Sudoku #2',
+  type: 'sudoku',
+  level: 1,
+  cells: '3..1..2.4.......'
+};
+
+// Create puzzle definitions
+console.log('Creating puzzle definitions...\n');
+
+const puzzle1Result = PuzzleDefinitionFactory.create(STANDARD_CONFIGS.puzzle4x4, puzzle1Description);
+const puzzle2Result = PuzzleDefinitionFactory.create(STANDARD_CONFIGS.puzzle4x4, puzzle2Description);
+
+if (puzzle1Result.isSuccess() && puzzle2Result.isSuccess()) {
+  const puzzle1 = puzzle1Result.value;
+  const puzzle2 = puzzle2Result.value;
+
+  console.log('✅ Puzzle #1:');
+  console.log(`  Description: ${puzzle1.description}`);
+  console.log(`  Grid: ${puzzle1.totalRows}x${puzzle1.totalColumns}`);
+  console.log(`  Cage dimensions: ${puzzle1.cageWidthInCells}x${puzzle1.cageHeightInCells}`);
+  console.log(`  Max value: ${puzzle1.maxValue}`);
+  console.log(`  Cells: ${puzzle1.cells}`);
+  console.log('  Grid layout:');
+  for (let row = 0; row < 4; row++) {
+    const rowCells = puzzle1.cells.slice(row * 4, (row + 1) * 4).split('');
+    console.log(`    ${rowCells.map((c) => (c === '.' ? ' ' : c)).join(' ')}`);
+  }
+
+  console.log('\n✅ Puzzle #2:');
+  console.log(`  Description: ${puzzle2.description}`);
+  console.log(`  Grid: ${puzzle2.totalRows}x${puzzle2.totalColumns}`);
+  console.log(`  Cage dimensions: ${puzzle2.cageWidthInCells}x${puzzle2.cageHeightInCells}`);
+  console.log(`  Max value: ${puzzle2.maxValue}`);
+  console.log(`  Cells: ${puzzle2.cells}`);
+  console.log('  Grid layout:');
+  for (let row = 0; row < 4; row++) {
+    const rowCells = puzzle2.cells.slice(row * 4, (row + 1) * 4).split('');
+    console.log(`    ${rowCells.map((c) => (c === '.' ? ' ' : c)).join(' ')}`);
+  }
+
+  console.log('\n🎯 Both 4x4 puzzle definitions created successfully!');
+  console.log('These can be used with the Sudoku puzzle engine.');
+} else {
+  console.error('❌ Failed to create puzzle definitions:');
+  if (puzzle1Result.isFailure()) {
+    console.error(`  Puzzle #1: ${puzzle1Result.message}`);
+  }
+  if (puzzle2Result.isFailure()) {
+    console.error(`  Puzzle #2: ${puzzle2Result.message}`);
+  }
+}

package/sample-6x6-puzzle.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+// Sample 6x6 puzzle generated from screenshot
+const { PuzzleDefinitionFactory, STANDARD_CONFIGS } = require('./lib/packlets/common');
+
+console.log('🧩 Sample 6x6 Sudoku Puzzle\n');
+
+// 6x6 puzzle from screenshot
+// Row by row: 62..5.3, ......, 5....3, ..6..2, ....346, 3.6...
+const puzzle6x6Description = {
+  description: 'Sample 6x6 Sudoku #1',
+  type: 'sudoku',
+  level: 2,
+  cells: '62..533....5....3..6..2....3463.6...'
+};
+
+// Create puzzle definition
+console.log('Creating 6x6 puzzle definition...\n');
+
+const puzzleResult = PuzzleDefinitionFactory.create(STANDARD_CONFIGS.puzzle6x6, puzzle6x6Description);
+
+if (puzzleResult.isSuccess()) {
+  const puzzle = puzzleResult.value;
+
+  console.log('✅ 6x6 Puzzle:');
+  console.log(`  Description: ${puzzle.description}`);
+  console.log(`  Grid: ${puzzle.totalRows}x${puzzle.totalColumns}`);
+  console.log(`  Cage dimensions: ${puzzle.cageWidthInCells}x${puzzle.cageHeightInCells} (3 wide x 2 high)`);
+  console.log(`  Board dimensions: ${puzzle.boardWidthInCages}x${puzzle.boardHeightInCages} cages`);
+  console.log(`  Max value: ${puzzle.maxValue}`);
+  console.log(`  Cage total: ${puzzle.basicCageTotal} (sum 1+2+3+4+5+6)`);
+  console.log(`  Cells: ${puzzle.cells}`);
+  console.log('  Grid layout:');
+
+  for (let row = 0; row < 6; row++) {
+    const rowCells = puzzle.cells.slice(row * 6, (row + 1) * 6).split('');
+    const displayRow = rowCells.map((c) => (c === '.' ? ' ' : c)).join(' ');
+    console.log(`    ${displayRow}`);
+
+    // Show cage boundaries after rows 1, 3, 5
+    if (row === 1 || row === 3) {
+      console.log('    -----------'); // Horizontal cage separator
+    }
+  }
+
+  console.log('\n  Cage structure (3x2 sections):');
+  console.log('    Top left    | Top right');
+  console.log('    (rows 0-1)  | (rows 0-1)');
+  console.log('    -----------');
+  console.log('    Mid left    | Mid right');
+  console.log('    (rows 2-3)  | (rows 2-3)');
+  console.log('    -----------');
+  console.log('    Bot left    | Bot right');
+  console.log('    (rows 4-5)  | (rows 4-5)');
+
+  console.log('\n🎯 6x6 puzzle definition created successfully!');
+  console.log('This puzzle uses 3x2 cage dimensions with 2x3 cage layout.');
+} else {
+  console.error('❌ Failed to create 6x6 puzzle definition:');
+  console.error(`  Error: ${puzzleResult.message}`);
+}

package/temp_12x12_cells.txt

@@ -0,0 +1,12 @@
+Row 0:  ..1.6.2.A7..
+Row 1:  62.5B....1..
+Row 2:  .8....C3B.62
+Row 3:  A97.2.6..B5.
+Row 4:  .5......37C
+Row 5:  3B....7...9
+Row 6:  57B.4.....1
+Row 7:  8.....A.9..
+Row 8:  .4..97...6..
+Row 9:  .1C.......B
+Row 10: 4....2.C...
+Row 11: ....5C..7126