logic-puzzle-generator 1.0.0

package/dist/Generator.js

@@ -0,0 +1,433 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Generator = void 0;
+const types_1 = require("./types");
+const Clue_1 = require("./Clue");
+const LogicGrid_1 = require("./LogicGrid");
+const Solver_1 = require("./Solver");
+// A simple seeded PRNG (mulberry32)
+function mulberry32(a) {
+    return function () {
+        a |= 0;
+        a = a + 0x6D2B79F5 | 0;
+        var t = Math.imul(a ^ a >>> 15, 1 | a);
+        t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+        return ((t ^ t >>> 14) >>> 0) / 4294967296;
+    };
+}
+/**
+ * The main class responsible for generating logic puzzles.
+ *
+ * It handles the creation of a consistent solution, the generation of all possible clues,
+ * and the selection of an optimal set of clues to form a solvable puzzle with a specific target.
+ */
+class Generator {
+    /**
+     * Creates a new Generator instance.
+     *
+     * @param seed - A numeric seed for the random number generator to ensure reproducibility.
+     */
+    constructor(seed) {
+        this.solution = {};
+        this.valueMap = new Map();
+        this.reverseSolution = new Map();
+        this.seed = seed;
+        this.random = mulberry32(seed);
+        this.solver = new Solver_1.Solver();
+    }
+    /**
+     * Generates a fully solvable logic puzzle based on the provided configuration.
+     *
+     * @param categories - The categories and values to include in the puzzle.
+     * @param target - The specific fact that should be the final deduction of the puzzle.
+     * @returns A complete Puzzle object containing the solution, clues, and proof chain.
+     */
+    generatePuzzle(categories, target) {
+        this.createSolution(categories);
+        let availableClues = this.generateAllPossibleClues(categories);
+        const logicGrid = new LogicGrid_1.LogicGrid(categories);
+        const proofChain = [];
+        while (proofChain.length < 100) { // Safety break
+            let bestCandidate = null;
+            let finalCandidate = null;
+            // Iterate backwards to safely remove clues
+            for (let i = availableClues.length - 1; i >= 0; i--) {
+                const clue = availableClues[i];
+                const tempGrid = logicGrid.clone();
+                const { deductions } = this.solver.applyClue(tempGrid, clue);
+                if (deductions === 0) {
+                    availableClues.splice(i, 1); // Permanently remove redundant clue
+                    continue;
+                }
+                const score = this.calculateScore(tempGrid, target, deductions, clue, proofChain.map(p => p.clue));
+                if (score > -1000000) { // Not a premature solve
+                    if (!bestCandidate || score > bestCandidate.score) {
+                        bestCandidate = { clue, score };
+                    }
+                }
+                else {
+                    finalCandidate = { clue, score }; // It solves the target, keep as a final option
+                }
+            }
+            const chosenCandidate = bestCandidate || finalCandidate;
+            if (!chosenCandidate) {
+                // No more useful clues found
+                break;
+            }
+            const chosenClue = chosenCandidate.clue;
+            const { deductions } = this.solver.applyClue(logicGrid, chosenClue);
+            proofChain.push({ clue: chosenClue, deductions });
+            // Remove the chosen clue from the available list
+            const chosenIndex = availableClues.findIndex(c => JSON.stringify(c) === JSON.stringify(chosenClue));
+            if (chosenIndex > -1) {
+                availableClues.splice(chosenIndex, 1);
+            }
+            if (this.isPuzzleSolved(logicGrid)) {
+                break;
+            }
+        }
+        return {
+            solution: this.solution,
+            clues: proofChain.map(p => p.clue),
+            proofChain,
+            categories,
+            targetFact: target,
+        };
+    }
+    createSolution(categories) {
+        const baseCategory = categories[0];
+        baseCategory.values.forEach(val => {
+            this.valueMap.set(val, { [baseCategory.id]: val });
+        });
+        for (let i = 1; i < categories.length; i++) {
+            const currentCategory = categories[i];
+            const shuffledValues = [...currentCategory.values].sort(() => this.random() - 0.5);
+            let i_shuffled = 0;
+            for (const val of baseCategory.values) {
+                const record = this.valueMap.get(val);
+                if (record)
+                    record[currentCategory.id] = shuffledValues[i_shuffled++];
+            }
+        }
+        for (const cat of categories) {
+            this.solution[cat.id] = {};
+            this.reverseSolution.set(cat.id, new Map());
+        }
+        for (const baseVal of baseCategory.values) {
+            const mappings = this.valueMap.get(baseVal);
+            if (mappings) {
+                for (const catId in mappings) {
+                    this.solution[catId][baseVal] = mappings[catId];
+                    this.reverseSolution.get(catId)?.set(mappings[catId], baseVal);
+                }
+            }
+        }
+    }
+    generateAllPossibleClues(categories) {
+        const clues = [];
+        const baseCategory = categories[0];
+        // Generate BinaryClues
+        for (const cat1 of categories) {
+            for (const val1 of cat1.values) {
+                for (const cat2 of categories) {
+                    if (cat1.id >= cat2.id)
+                        continue;
+                    const baseVal = this.reverseSolution.get(cat1.id)?.get(val1);
+                    if (!baseVal)
+                        continue;
+                    const mappings = this.valueMap.get(baseVal);
+                    if (!mappings)
+                        continue;
+                    for (const val2 of cat2.values) {
+                        const correctVal2 = mappings[cat2.id];
+                        if (val2 === correctVal2) {
+                            clues.push({
+                                type: Clue_1.ClueType.BINARY,
+                                operator: Clue_1.BinaryOperator.IS,
+                                cat1: cat1.id,
+                                val1: val1,
+                                cat2: cat2.id,
+                                val2: val2,
+                            });
+                        }
+                        else {
+                            clues.push({
+                                type: Clue_1.ClueType.BINARY,
+                                operator: Clue_1.BinaryOperator.IS_NOT,
+                                cat1: cat1.id,
+                                val1: val1,
+                                cat2: cat2.id,
+                                val2: val2,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        // Generate Ordinal and SuperlativeClues
+        for (const ordCategory of categories.filter(c => c.type === types_1.CategoryType.ORDINAL)) {
+            const sortedValues = [...ordCategory.values].sort((a, b) => a - b);
+            const minVal = sortedValues[0];
+            const maxVal = sortedValues[sortedValues.length - 1];
+            // Generate SuperlativeClues for all categories
+            for (const targetCat of categories) {
+                if (targetCat.id === ordCategory.id)
+                    continue;
+                const baseValForMin = this.reverseSolution.get(ordCategory.id).get(minVal);
+                const itemValForMin = this.valueMap.get(baseValForMin)[targetCat.id];
+                clues.push({
+                    type: Clue_1.ClueType.SUPERLATIVE,
+                    operator: Clue_1.SuperlativeOperator.MIN,
+                    targetCat: targetCat.id,
+                    targetVal: itemValForMin,
+                    ordinalCat: ordCategory.id,
+                });
+                const baseValForMax = this.reverseSolution.get(ordCategory.id).get(maxVal);
+                const itemValForMax = this.valueMap.get(baseValForMax)[targetCat.id];
+                clues.push({
+                    type: Clue_1.ClueType.SUPERLATIVE,
+                    operator: Clue_1.SuperlativeOperator.MAX,
+                    targetCat: targetCat.id,
+                    targetVal: itemValForMax,
+                    ordinalCat: ordCategory.id,
+                });
+            }
+            // Generate OrdinalClues for all pairs of categories
+            for (const item1Cat of categories) {
+                if (item1Cat.id === ordCategory.id)
+                    continue;
+                for (const item2Cat of categories) {
+                    if (item2Cat.id === ordCategory.id)
+                        continue;
+                    for (const item1Val of item1Cat.values) {
+                        for (const item2Val of item2Cat.values) {
+                            if (item1Cat.id === item2Cat.id && item1Val === item2Val)
+                                continue;
+                            const baseVal1 = this.reverseSolution.get(item1Cat.id)?.get(item1Val);
+                            const baseVal2 = this.reverseSolution.get(item2Cat.id)?.get(item2Val);
+                            if (!baseVal1 || !baseVal2)
+                                continue;
+                            // if they are the same entity, don't compare
+                            if (baseVal1 === baseVal2)
+                                continue;
+                            const mappings1 = this.valueMap.get(baseVal1);
+                            const mappings2 = this.valueMap.get(baseVal2);
+                            if (!mappings1 || !mappings2)
+                                continue;
+                            const ordVal1 = mappings1[ordCategory.id];
+                            const ordVal2 = mappings2[ordCategory.id];
+                            if (ordVal1 > ordVal2) {
+                                clues.push({
+                                    type: Clue_1.ClueType.ORDINAL,
+                                    operator: Clue_1.OrdinalOperator.GREATER_THAN,
+                                    item1Cat: item1Cat.id,
+                                    item1Val: item1Val,
+                                    item2Cat: item2Cat.id,
+                                    item2Val: item2Val,
+                                    ordinalCat: ordCategory.id,
+                                });
+                            }
+                            else if (ordVal1 < ordVal2) {
+                                clues.push({
+                                    type: Clue_1.ClueType.ORDINAL,
+                                    operator: Clue_1.OrdinalOperator.LESS_THAN,
+                                    item1Cat: item1Cat.id,
+                                    item1Val: item1Val,
+                                    item2Cat: item2Cat.id,
+                                    item2Val: item2Val,
+                                    ordinalCat: ordCategory.id,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        // Generate UnaryClues
+        for (const ordCategory of categories) {
+            if (ordCategory.type !== types_1.CategoryType.ORDINAL)
+                continue;
+            // Check if all values are numbers
+            if (!ordCategory.values.every(v => typeof v === 'number'))
+                continue;
+            for (const targetCategory of categories) {
+                if (targetCategory.id === ordCategory.id)
+                    continue;
+                for (const targetVal of targetCategory.values) {
+                    const baseVal = this.reverseSolution.get(targetCategory.id)?.get(targetVal);
+                    if (!baseVal)
+                        continue;
+                    const mappings = this.valueMap.get(baseVal);
+                    if (!mappings)
+                        continue;
+                    const ordValue = mappings[ordCategory.id];
+                    if (ordValue % 2 === 0) {
+                        clues.push({
+                            type: Clue_1.ClueType.UNARY,
+                            filter: Clue_1.UnaryFilter.IS_EVEN,
+                            targetCat: targetCategory.id,
+                            targetVal: targetVal,
+                            ordinalCat: ordCategory.id,
+                        });
+                    }
+                    else {
+                        clues.push({
+                            type: Clue_1.ClueType.UNARY,
+                            filter: Clue_1.UnaryFilter.IS_ODD,
+                            targetCat: targetCategory.id,
+                            targetVal: targetVal,
+                            ordinalCat: ordCategory.id,
+                        });
+                    }
+                }
+            }
+        }
+        return clues;
+    }
+    calculateScore(grid, target, deductions, clue, previouslySelectedClues) {
+        const clueType = clue.type;
+        const targetValue = this.solution[target.category2Id][target.value1];
+        const isTargetSolved = grid.isPossible(target.category1Id, target.value1, target.category2Id, targetValue) &&
+            grid.getPossibilitiesCount(target.category1Id, target.value1, target.category2Id) === 1;
+        const puzzleSolved = this.isPuzzleSolved(grid);
+        if (isTargetSolved && puzzleSolved) {
+            return 1000000; // This is the winning clue
+        }
+        if (isTargetSolved && !puzzleSolved) {
+            return -1000000; // This clue solves the target too early
+        }
+        const synergyScore = deductions;
+        const { totalPossible, currentPossible, solutionPossible } = grid.getGridStats();
+        const totalEliminatable = totalPossible - solutionPossible;
+        const eliminatedSoFar = totalPossible - currentPossible;
+        const completenessScore = totalEliminatable > 0 ? (eliminatedSoFar / totalEliminatable) : 0;
+        let complexityBonus = 0;
+        switch (clueType) {
+            case Clue_1.ClueType.ORDINAL:
+                complexityBonus = 1.5;
+                break;
+            case Clue_1.ClueType.SUPERLATIVE:
+                complexityBonus = 1.2;
+                break;
+            case Clue_1.ClueType.UNARY:
+                complexityBonus = 1.2;
+                break;
+            case Clue_1.ClueType.BINARY:
+                complexityBonus = 1.0;
+                // Boost IS_NOT to encourage variety, as they are weaker deduction-wise
+                if (clue.operator === Clue_1.BinaryOperator.IS_NOT) {
+                    complexityBonus = 5.0;
+                }
+                break;
+        }
+        // --- Combined Three-Part Penalty Logic ---
+        let repetitionScore = 0;
+        // 1. Subject Penalty
+        const getEntities = (c) => {
+            const safeGet = (cat, val) => this.reverseSolution.get(cat)?.get(val);
+            let primary = [];
+            let secondary = [];
+            switch (c.type) {
+                case Clue_1.ClueType.BINARY:
+                    const b = c;
+                    primary.push(safeGet(b.cat1, b.val1));
+                    if (b.operator === Clue_1.BinaryOperator.IS_NOT) {
+                        secondary.push(safeGet(b.cat2, b.val2));
+                    }
+                    break;
+                case Clue_1.ClueType.SUPERLATIVE:
+                    const s = c;
+                    primary.push(safeGet(s.targetCat, s.targetVal));
+                    break;
+                case Clue_1.ClueType.ORDINAL:
+                    const o = c;
+                    primary.push(safeGet(o.item1Cat, o.item1Val));
+                    secondary.push(safeGet(o.item2Cat, o.item2Val));
+                    break;
+                case Clue_1.ClueType.UNARY:
+                    const u = c;
+                    primary.push(safeGet(u.targetCat, u.targetVal));
+                    break;
+            }
+            return {
+                primary: primary.filter((e) => !!e),
+                secondary: secondary.filter((e) => !!e)
+            };
+        };
+        const mentionedEntities = new Set();
+        for (const pClue of previouslySelectedClues) {
+            const { primary, secondary } = getEntities(pClue);
+            primary.forEach(e => mentionedEntities.add(e));
+            secondary.forEach(e => mentionedEntities.add(e));
+        }
+        const { primary: currentPrimary, secondary: currentSecondary } = getEntities(clue);
+        currentPrimary.forEach(e => {
+            if (mentionedEntities.has(e)) {
+                repetitionScore += 1.0; // Full penalty for primary subject
+            }
+        });
+        currentSecondary.forEach(e => {
+            if (mentionedEntities.has(e)) {
+                repetitionScore += 0.5; // Half penalty for secondary subject
+            }
+        });
+        // 2. Dimension (Ordinal Category) Penalty
+        const currentOrdinalCat = clue.ordinalCat;
+        if (currentOrdinalCat) {
+            for (const pClue of previouslySelectedClues) {
+                const prevOrdinalCat = pClue.ordinalCat;
+                if (currentOrdinalCat === prevOrdinalCat) {
+                    repetitionScore += 0.5; // Penalize reuse of 'Age'
+                }
+            }
+        }
+        // 3. Structure (Clue Type) Penalty
+        if (previouslySelectedClues.length > 0) {
+            const lastClue = previouslySelectedClues[previouslySelectedClues.length - 1];
+            // Immediate Repetition Penalty
+            if (clue.type === lastClue.type) {
+                repetitionScore += 2.0; // Strong penalty for same type
+                // Double "IS" Penalty - Binary IS clues are very powerful but boring if repeated
+                if (clue.type === Clue_1.ClueType.BINARY &&
+                    clue.operator === Clue_1.BinaryOperator.IS &&
+                    lastClue.operator === Clue_1.BinaryOperator.IS) {
+                    repetitionScore += 2.0;
+                }
+            }
+            // Streak Penalty (3 in a row)
+            if (previouslySelectedClues.length > 1) {
+                const secondLastClue = previouslySelectedClues[previouslySelectedClues.length - 2];
+                if (clue.type === lastClue.type && clue.type === secondLastClue.type) {
+                    repetitionScore += 5.0; // Massive penalty for 3-streak
+                }
+            }
+        }
+        const repetitionPenalty = Math.pow(0.4, repetitionScore);
+        const score = ((synergyScore * complexityBonus) + (completenessScore * 5)) * repetitionPenalty;
+        return score;
+    }
+    isPuzzleSolved(grid) {
+        const categories = grid.categories;
+        const baseCategory = categories[0];
+        for (const cat1 of categories) {
+            for (const val1 of cat1.values) {
+                for (const cat2 of categories) {
+                    if (cat1.id >= cat2.id)
+                        continue;
+                    const baseVal = this.reverseSolution.get(cat1.id)?.get(val1);
+                    if (!baseVal)
+                        return false; // Should not happen
+                    const correctVal2 = this.solution[cat2.id][baseVal];
+                    if (grid.getPossibilitiesCount(cat1.id, val1, cat2.id) > 1) {
+                        return false;
+                    }
+                    if (!grid.isPossible(cat1.id, val1, cat2.id, correctVal2)) {
+                        return false;
+                    }
+                }
+            }
+        }
+        return true;
+    }
+}
+exports.Generator = Generator;

package/dist/LogicGrid.d.ts

@@ -0,0 +1,70 @@
+import { CategoryConfig, ValueLabel } from './types';
+/**
+ * Represents the state of the logic puzzle grid.
+ *
+ * It manages the possibilities between every pair of values across different categories.
+ * The grid is initialized where all connections are possible (true).
+ * As clues are applied, possibilities are eliminated (set to false).
+ */
+export declare class LogicGrid {
+    private grid;
+    private categories;
+    private valueMap;
+    /**
+     * Creates a new LogicGrid instance.
+     *
+     * @param categories - The configuration of categories and their values for the puzzle.
+     * @throws {Error} If the configuration is invalid (duplicate IDs, duplicate values, or mismatched value counts).
+     */
+    constructor(categories: CategoryConfig[]);
+    private _validateCategories;
+    /**
+     * Sets the possibility state between two values from different categories.
+     *
+     * @param cat1Id - The ID of the first category.
+     * @param val1 - The value from the first category.
+     * @param cat2Id - The ID of the second category.
+     * @param val2 - The value from the second category.
+     * @param state - true if the connection is possible, false if eliminated.
+     */
+    setPossibility(cat1Id: string, val1: ValueLabel, cat2Id: string, val2: ValueLabel, state: boolean): void;
+    /**
+     * Checks if a connection between two values is currently possible.
+     *
+     * @param cat1Id - The ID of the first category.
+     * @param val1 - The value from the first category.
+     * @param cat2Id - The ID of the second category.
+     * @param val2 - The value from the second category.
+     * @returns true if the connection is possible, false otherwise.
+     */
+    isPossible(cat1Id: string, val1: ValueLabel, cat2Id: string, val2: ValueLabel): boolean;
+    /**
+     * Gets the number of possible connections for a specific value in one category
+     * relative to another category.
+     *
+     * @param cat1Id - The ID of the starting category.
+     * @param val1 - The value from the starting category.
+     * @param cat2Id - The target category ID.
+     * @returns The number of values in cat2 that are still possible for val1.
+     */
+    getPossibilitiesCount(cat1Id: string, val1: ValueLabel, cat2Id: string): number;
+    /**
+     * Calculates statistics about the current state of the grid.
+     *
+     * @returns An object containing:
+     *  - totalPossible: The initial total logical connections.
+     *  - currentPossible: The number of remaining possible connections.
+     *  - solutionPossible: The target number of connections for a solved grid.
+     */
+    getGridStats(): {
+        totalPossible: number;
+        currentPossible: number;
+        solutionPossible: number;
+    };
+    /**
+     * Creates a deep copy of the current LogicGrid.
+     *
+     * @returns A new LogicGrid instance with the exact same state.
+     */
+    clone(): LogicGrid;
+}

package/dist/LogicGrid.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogicGrid = void 0;
+/**
+ * Represents the state of the logic puzzle grid.
+ *
+ * It manages the possibilities between every pair of values across different categories.
+ * The grid is initialized where all connections are possible (true).
+ * As clues are applied, possibilities are eliminated (set to false).
+ */
+class LogicGrid {
+    /**
+     * Creates a new LogicGrid instance.
+     *
+     * @param categories - The configuration of categories and their values for the puzzle.
+     * @throws {Error} If the configuration is invalid (duplicate IDs, duplicate values, or mismatched value counts).
+     */
+    constructor(categories) {
+        this._validateCategories(categories);
+        this.categories = categories;
+        this.valueMap = new Map(categories.map(c => [c.id, new Map(c.values.map((v, i) => [v, i]))]));
+        this.grid = new Map();
+        for (const cat1 of categories) {
+            const cat1Map = new Map();
+            for (const val1 of cat1.values) {
+                const cat2Map = new Map();
+                for (const cat2 of categories) {
+                    if (cat1.id === cat2.id)
+                        continue;
+                    cat2Map.set(cat2.id, Array(cat2.values.length).fill(true));
+                }
+                cat1Map.set(val1, cat2Map);
+            }
+            this.grid.set(cat1.id, cat1Map);
+        }
+    }
+    _validateCategories(categories) {
+        if (categories.length === 0) {
+            return; // Or throw an error, for now we allow it.
+        }
+        const firstCategoryValueCount = categories[0].values.length;
+        const categoryIds = new Set();
+        for (const category of categories) {
+            if (categoryIds.has(category.id)) {
+                throw new Error(`Invalid configuration: Duplicate category ID found: "${category.id}".`);
+            }
+            categoryIds.add(category.id);
+            if (category.values.length !== firstCategoryValueCount) {
+                throw new Error(`Invalid configuration: All categories must have the same number of values. Category "${category.id}" has ${category.values.length} values, but category "${categories[0].id}" has ${firstCategoryValueCount}.`);
+            }
+            const categoryValues = new Set();
+            for (const value of category.values) {
+                if (categoryValues.has(value)) {
+                    throw new Error(`Invalid configuration: Duplicate value "${value}" found in category "${category.id}".`);
+                }
+                categoryValues.add(value);
+            }
+        }
+    }
+    /**
+     * Sets the possibility state between two values from different categories.
+     *
+     * @param cat1Id - The ID of the first category.
+     * @param val1 - The value from the first category.
+     * @param cat2Id - The ID of the second category.
+     * @param val2 - The value from the second category.
+     * @param state - true if the connection is possible, false if eliminated.
+     */
+    setPossibility(cat1Id, val1, cat2Id, val2, state) {
+        const val2Index = this.valueMap.get(cat2Id)?.get(val2);
+        if (val2Index !== undefined) {
+            const cat1Map = this.grid.get(cat1Id);
+            if (cat1Map) {
+                const val1Map = cat1Map.get(val1);
+                if (val1Map) {
+                    const cat2Arr = val1Map.get(cat2Id);
+                    if (cat2Arr) {
+                        cat2Arr[val2Index] = state;
+                    }
+                }
+            }
+        }
+        const val1Index = this.valueMap.get(cat1Id)?.get(val1);
+        if (val1Index !== undefined) {
+            const cat2Map = this.grid.get(cat2Id);
+            if (cat2Map) {
+                const val2Map = cat2Map.get(val2);
+                if (val2Map) {
+                    const cat1Arr = val2Map.get(cat1Id);
+                    if (cat1Arr) {
+                        cat1Arr[val1Index] = state;
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Checks if a connection between two values is currently possible.
+     *
+     * @param cat1Id - The ID of the first category.
+     * @param val1 - The value from the first category.
+     * @param cat2Id - The ID of the second category.
+     * @param val2 - The value from the second category.
+     * @returns true if the connection is possible, false otherwise.
+     */
+    isPossible(cat1Id, val1, cat2Id, val2) {
+        const val2Index = this.valueMap.get(cat2Id)?.get(val2);
+        if (val2Index === undefined)
+            return false;
+        const cat1Grid = this.grid.get(cat1Id);
+        if (!cat1Grid)
+            return false;
+        const val1Grid = cat1Grid.get(val1);
+        if (!val1Grid)
+            return false;
+        const cat2Arr = val1Grid.get(cat2Id);
+        if (!cat2Arr)
+            return false;
+        return cat2Arr[val2Index];
+    }
+    /**
+     * Gets the number of possible connections for a specific value in one category
+     * relative to another category.
+     *
+     * @param cat1Id - The ID of the starting category.
+     * @param val1 - The value from the starting category.
+     * @param cat2Id - The target category ID.
+     * @returns The number of values in cat2 that are still possible for val1.
+     */
+    getPossibilitiesCount(cat1Id, val1, cat2Id) {
+        const possibilities = this.grid.get(cat1Id)?.get(val1)?.get(cat2Id);
+        if (!possibilities)
+            return 0;
+        return possibilities.filter(p => p).length;
+    }
+    /**
+     * Calculates statistics about the current state of the grid.
+     *
+     * @returns An object containing:
+     *  - totalPossible: The initial total logical connections.
+     *  - currentPossible: The number of remaining possible connections.
+     *  - solutionPossible: The target number of connections for a solved grid.
+     */
+    getGridStats() {
+        let currentPossible = 0;
+        const catCount = this.categories.length;
+        const valCount = this.categories[0]?.values.length || 0;
+        if (valCount === 0 || catCount < 2) {
+            return { totalPossible: 0, currentPossible: 0, solutionPossible: 0 };
+        }
+        const numPairs = catCount * (catCount - 1) / 2;
+        const totalPossible = numPairs * valCount * valCount;
+        const solutionPossible = numPairs * valCount;
+        for (const cat1 of this.categories) {
+            for (const val1 of cat1.values) {
+                for (const cat2 of this.categories) {
+                    if (cat1.id >= cat2.id)
+                        continue;
+                    const possibilities = this.grid.get(cat1.id)?.get(val1)?.get(cat2.id);
+                    if (possibilities) {
+                        currentPossible += possibilities.filter(p => p).length;
+                    }
+                }
+            }
+        }
+        return { totalPossible, currentPossible, solutionPossible };
+    }
+    /**
+     * Creates a deep copy of the current LogicGrid.
+     *
+     * @returns A new LogicGrid instance with the exact same state.
+     */
+    clone() {
+        const newGrid = new LogicGrid(this.categories);
+        newGrid.grid = new Map([...this.grid.entries()].map(([cat1Id, cat1Map]) => [
+            cat1Id,
+            new Map([...cat1Map.entries()].map(([val1, val1Map]) => [
+                val1,
+                new Map([...val1Map.entries()].map(([cat2Id, cat2Arr]) => [
+                    cat2Id,
+                    [...cat2Arr],
+                ])),
+            ])),
+        ]));
+        return newGrid;
+    }
+}
+exports.LogicGrid = LogicGrid;