logic-puzzle-generator 1.0.0

package/dist/Solver.d.ts

@@ -0,0 +1,29 @@
+import { LogicGrid } from './LogicGrid';
+import { Clue } from './Clue';
+/**
+ * The logical engine responsible for applying clues to a LogicGrid and deducing consequences.
+ *
+ * It implements various deduction strategies including basic elimination, uniqueness checks,
+ * and transitive logic logic (if A=B and B=C, then A=C).
+ */
+export declare class Solver {
+    /**
+     * Applies a single clue to the grid and propagates logical deductions.
+     *
+     * This method runs a loop that explicitly applies the clue and then repeatedly
+     * triggers the internal deduction engine until no further eliminations can be made.
+     *
+     * @param grid - The LogicGrid to modify.
+     * @param clue - The Clue to apply.
+     * @returns An object containing the modified grid and the total count of eliminations made.
+     */
+    applyClue(grid: LogicGrid, clue: Clue): {
+        grid: LogicGrid;
+        deductions: number;
+    };
+    private applyUnaryClue;
+    private applyBinaryClue;
+    private runDeductionLoop;
+    private applyOrdinalClue;
+    private applySuperlativeClue;
+}

package/dist/Solver.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Solver = void 0;
+const Clue_1 = require("./Clue");
+const types_1 = require("./types");
+/**
+ * The logical engine responsible for applying clues to a LogicGrid and deducing consequences.
+ *
+ * It implements various deduction strategies including basic elimination, uniqueness checks,
+ * and transitive logic logic (if A=B and B=C, then A=C).
+ */
+class Solver {
+    /**
+     * Applies a single clue to the grid and propagates logical deductions.
+     *
+     * This method runs a loop that explicitly applies the clue and then repeatedly
+     * triggers the internal deduction engine until no further eliminations can be made.
+     *
+     * @param grid - The LogicGrid to modify.
+     * @param clue - The Clue to apply.
+     * @returns An object containing the modified grid and the total count of eliminations made.
+     */
+    applyClue(grid, clue) {
+        let deductions = 0;
+        switch (clue.type) {
+            case Clue_1.ClueType.BINARY:
+                deductions += this.applyBinaryClue(grid, clue);
+                break;
+            case Clue_1.ClueType.SUPERLATIVE:
+                deductions += this.applySuperlativeClue(grid, clue);
+                break;
+            case Clue_1.ClueType.ORDINAL:
+                deductions += this.applyOrdinalClue(grid, clue);
+                break;
+            case Clue_1.ClueType.UNARY:
+                deductions += this.applyUnaryClue(grid, clue);
+                break;
+        }
+        let newDeductions;
+        do {
+            newDeductions = this.runDeductionLoop(grid);
+            deductions += newDeductions;
+        } while (newDeductions > 0);
+        return { grid, deductions };
+    }
+    applyUnaryClue(grid, clue) {
+        let deductions = 0;
+        const categories = grid.categories;
+        const ordinalCatConfig = categories.find(c => c.id === clue.ordinalCat);
+        if (!ordinalCatConfig || ordinalCatConfig.type !== types_1.CategoryType.ORDINAL)
+            return 0;
+        if (!ordinalCatConfig.values.every(v => typeof v === 'number'))
+            return 0;
+        const isEven = clue.filter === Clue_1.UnaryFilter.IS_EVEN;
+        for (const ordVal of ordinalCatConfig.values) {
+            const ordNum = ordVal;
+            const shouldEliminate = isEven ? ordNum % 2 !== 0 : ordNum % 2 === 0;
+            if (shouldEliminate) {
+                if (grid.isPossible(clue.targetCat, clue.targetVal, clue.ordinalCat, ordVal)) {
+                    grid.setPossibility(clue.targetCat, clue.targetVal, clue.ordinalCat, ordVal, false);
+                    deductions++;
+                }
+            }
+        }
+        return deductions;
+    }
+    applyBinaryClue(grid, clue) {
+        let deductions = 0;
+        const categories = grid.categories;
+        const cat1Config = categories.find(c => c.id === clue.cat1);
+        const cat2Config = categories.find(c => c.id === clue.cat2);
+        if (!cat1Config || !cat2Config)
+            return 0;
+        if (clue.operator === Clue_1.BinaryOperator.IS) {
+            if (grid.isPossible(clue.cat1, clue.val1, clue.cat2, clue.val2)) {
+                // This is not a deduction, but a fact application. Still, we need to eliminate other possibilities.
+            }
+            grid.setPossibility(clue.cat1, clue.val1, clue.cat2, clue.val2, true);
+            for (const val of cat2Config.values) {
+                if (val !== clue.val2) {
+                    if (grid.isPossible(clue.cat1, clue.val1, clue.cat2, val)) {
+                        grid.setPossibility(clue.cat1, clue.val1, clue.cat2, val, false);
+                        deductions++;
+                    }
+                }
+            }
+            for (const val of cat1Config.values) {
+                if (val !== clue.val1) {
+                    if (grid.isPossible(clue.cat1, val, clue.cat2, clue.val2)) {
+                        grid.setPossibility(clue.cat1, val, clue.cat2, clue.val2, false);
+                        deductions++;
+                    }
+                }
+            }
+        }
+        else { // IS_NOT
+            if (grid.isPossible(clue.cat1, clue.val1, clue.cat2, clue.val2)) {
+                grid.setPossibility(clue.cat1, clue.val1, clue.cat2, clue.val2, false);
+                deductions++;
+            }
+        }
+        return deductions;
+    }
+    runDeductionLoop(grid) {
+        let deductions = 0;
+        const categories = grid.categories;
+        for (const cat1 of categories) {
+            for (const val1 of cat1.values) {
+                for (const cat2 of categories) {
+                    if (cat1.id === cat2.id)
+                        continue;
+                    // Uniqueness Check
+                    const possibleValues = cat2.values.filter(val2 => grid.isPossible(cat1.id, val1, cat2.id, val2));
+                    if (possibleValues.length === 1) {
+                        const val2 = possibleValues[0];
+                        // If val1 is uniquely associated with val2, then no other val from cat1 can be associated with val2
+                        for (const otherVal1 of cat1.values) {
+                            if (otherVal1 !== val1) {
+                                if (grid.isPossible(cat1.id, otherVal1, cat2.id, val2)) {
+                                    grid.setPossibility(cat1.id, otherVal1, cat2.id, val2, false);
+                                    deductions++;
+                                }
+                            }
+                        }
+                    }
+                    // Transitivity
+                    for (const cat3 of categories) {
+                        if (cat1.id === cat3.id || cat2.id === cat3.id)
+                            continue;
+                        // Positive Transitivity
+                        const definiteVal2 = possibleValues.length === 1 ? possibleValues[0] : null;
+                        if (definiteVal2) {
+                            const possibleVal3s = cat3.values.filter(val3 => grid.isPossible(cat2.id, definiteVal2, cat3.id, val3));
+                            if (possibleVal3s.length === 1) {
+                                const definiteVal3 = possibleVal3s[0];
+                                if (grid.isPossible(cat1.id, val1, cat3.id, definiteVal3) === false) {
+                                    // This indicates a contradiction, but for now we are just making deductions.
+                                }
+                                else if (grid.getPossibilitiesCount(cat1.id, val1, cat3.id) > 1) {
+                                    grid.setPossibility(cat1.id, val1, cat3.id, definiteVal3, true);
+                                    deductions++;
+                                }
+                            }
+                        }
+                        // Negative Transitivity
+                        for (const val3 of cat3.values) {
+                            if (grid.isPossible(cat1.id, val1, cat3.id, val3)) {
+                                const isPathPossible = cat2.values.some(val2 => grid.isPossible(cat1.id, val1, cat2.id, val2) && grid.isPossible(cat2.id, val2, cat3.id, val3));
+                                if (!isPathPossible) {
+                                    grid.setPossibility(cat1.id, val1, cat3.id, val3, false);
+                                    deductions++;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        return deductions;
+    }
+    applyOrdinalClue(grid, constraint) {
+        let deductions = 0;
+        const categories = grid.categories;
+        const ordCatConfig = categories.find(c => c.id === constraint.ordinalCat);
+        if (!ordCatConfig || ordCatConfig.type !== types_1.CategoryType.ORDINAL)
+            return 0;
+        const possibleVals1 = ordCatConfig.values
+            .map((v, i) => ({ val: v, idx: i }))
+            .filter(v => grid.isPossible(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, v.val));
+        const possibleVals2 = ordCatConfig.values
+            .map((v, i) => ({ val: v, idx: i }))
+            .filter(v => grid.isPossible(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, v.val));
+        if (possibleVals1.length === 0 || possibleVals2.length === 0)
+            return 0;
+        if (constraint.operator === Clue_1.OrdinalOperator.GREATER_THAN) { // item1 > item2
+            // Prune item1's possibilities
+            for (const pval1 of possibleVals1) {
+                const canBeGreaterThan = possibleVals2.some(pval2 => pval1.idx > pval2.idx);
+                if (!canBeGreaterThan) {
+                    if (grid.isPossible(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, pval1.val)) {
+                        grid.setPossibility(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, pval1.val, false);
+                        deductions++;
+                    }
+                }
+            }
+            // Prune item2's possibilities
+            for (const pval2 of possibleVals2) {
+                const canBeLessThan = possibleVals1.some(pval1 => pval1.idx > pval2.idx);
+                if (!canBeLessThan) {
+                    if (grid.isPossible(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, pval2.val)) {
+                        grid.setPossibility(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, pval2.val, false);
+                        deductions++;
+                    }
+                }
+            }
+        }
+        else if (constraint.operator === Clue_1.OrdinalOperator.LESS_THAN) { // item1 < item2
+            // Prune item1's possibilities
+            for (const pval1 of possibleVals1) {
+                const canBeLessThan = possibleVals2.some(pval2 => pval1.idx < pval2.idx);
+                if (!canBeLessThan) {
+                    if (grid.isPossible(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, pval1.val)) {
+                        grid.setPossibility(constraint.item1Cat, constraint.item1Val, constraint.ordinalCat, pval1.val, false);
+                        deductions++;
+                    }
+                }
+            }
+            // Prune item2's possibilities
+            for (const pval2 of possibleVals2) {
+                const canBeGreaterThan = possibleVals1.some(pval1 => pval1.idx < pval2.idx);
+                if (!canBeGreaterThan) {
+                    if (grid.isPossible(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, pval2.val)) {
+                        grid.setPossibility(constraint.item2Cat, constraint.item2Val, constraint.ordinalCat, pval2.val, false);
+                        deductions++;
+                    }
+                }
+            }
+        }
+        return deductions;
+    }
+    applySuperlativeClue(grid, clue) {
+        const categories = grid.categories;
+        const ordinalCatConfig = categories.find(c => c.id === clue.ordinalCat);
+        if (!ordinalCatConfig || ordinalCatConfig.type !== types_1.CategoryType.ORDINAL)
+            return 0;
+        // Assuming values are sorted in ascending order for ordinal categories
+        const extremeValue = clue.operator === Clue_1.SuperlativeOperator.MAX
+            ? ordinalCatConfig.values[ordinalCatConfig.values.length - 1]
+            : ordinalCatConfig.values[0];
+        // This clue is essentially a binary IS clue.
+        const binaryClue = {
+            type: Clue_1.ClueType.BINARY,
+            cat1: clue.targetCat,
+            val1: clue.targetVal,
+            cat2: clue.ordinalCat,
+            val2: extremeValue,
+            operator: Clue_1.BinaryOperator.IS,
+        };
+        return this.applyBinaryClue(grid, binaryClue);
+    }
+}
+exports.Solver = Solver;

package/dist/examples/benchmark.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/benchmark.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const Generator_1 = require("../src/engine/Generator");
+const types_1 = require("../src/types");
+const Clue_1 = require("../src/engine/Clue");
+const perf_hooks_1 = require("perf_hooks");
+// Helper to generate random config
+function generateConfig(numCats, numVals) {
+    const cats = [];
+    for (let c = 0; c < numCats; c++) {
+        const isOrdinal = c === numCats - 1;
+        const values = [];
+        for (let v = 0; v < numVals; v++) {
+            if (isOrdinal)
+                values.push((v + 1) * 10);
+            else
+                values.push(`V${v}`);
+        }
+        cats.push({
+            id: `C${c}`,
+            type: isOrdinal ? types_1.CategoryType.ORDINAL : types_1.CategoryType.NOMINAL,
+            values: values
+        });
+    }
+    return cats;
+}
+const MATRIX = [
+    { name: 'Standard (3x4)', cats: 3, vals: 4, iters: 10 },
+    { name: 'Medium   (4x5)', cats: 4, vals: 5, iters: 5 },
+    { name: 'Large    (5x5)', cats: 5, vals: 5, iters: 2 },
+    { name: 'Wide     (6x4)', cats: 6, vals: 4, iters: 2 },
+    { name: 'Tall     (3x8)', cats: 3, vals: 8, iters: 2 },
+    { name: 'Stress   (8x5)', cats: 8, vals: 5, iters: 1 },
+    { name: 'Deep     (3x10)', cats: 3, vals: 10, iters: 1 },
+];
+console.log('--- Scalability Benchmark ---');
+for (const test of MATRIX) {
+    const seed = Math.floor(Math.random() * 10000);
+    const generator = new Generator_1.Generator(seed);
+    const config = generateConfig(test.cats, test.vals);
+    // Target: Cat0:Val0 -> Cat1
+    const target = {
+        category1Id: config[0].id,
+        value1: config[0].values[0],
+        category2Id: config[1].id,
+    };
+    const start = perf_hooks_1.performance.now();
+    let success = 0;
+    process.stdout.write(`Running ${test.name} ... `);
+    for (let i = 0; i < test.iters; i++) {
+        try {
+            let options = undefined;
+            if (test.cats >= 8)
+                options = { maxCandidates: 50 };
+            else if (test.cats >= 6)
+                options = { maxCandidates: 200 };
+            const puzzle = generator.generatePuzzle(config, target, options);
+            if (puzzle)
+                success++;
+        }
+        catch (e) {
+            console.error(e);
+        }
+    }
+    const end = perf_hooks_1.performance.now();
+    const duration = end - start;
+    const avg = duration / test.iters;
+    console.log(`${avg.toFixed(2)}ms / puzzle (Success: ${success}/${test.iters})`);
+}
+// Stats Benchmark
+console.log('--- Clue Variety Benchmark ---');
+{
+    const ITERATIONS = 20;
+    const generator = new Generator_1.Generator(999);
+    const config = generateConfig(4, 5);
+    const target = { category1Id: config[0].id, value1: config[0].values[0], category2Id: config[1].id };
+    // Stats
+    const stats = {};
+    process.stdout.write(`Running Stats (4x5, N=${ITERATIONS}) ... `);
+    let totalClues = 0;
+    for (let i = 0; i < ITERATIONS; i++) {
+        try {
+            const p = generator.generatePuzzle(config, target);
+            if (p) {
+                for (const c of p.clues) {
+                    totalClues++;
+                    let key = 'UNKNOWN';
+                    if (c.type === Clue_1.ClueType.BINARY)
+                        key = `BINARY_${c.operator === Clue_1.BinaryOperator.IS ? 'IS' : 'IS_NOT'}`;
+                    else if (c.type === Clue_1.ClueType.ORDINAL) {
+                        const op = c.operator;
+                        if (op === 0)
+                            key = 'ORD_GT';
+                        else if (op === 1)
+                            key = 'ORD_LT';
+                        else if (op === 2)
+                            key = 'ORD_NOT_GT'; // <=
+                        else if (op === 3)
+                            key = 'ORD_NOT_LT'; // >=
+                    }
+                    else if (c.type === Clue_1.ClueType.SUPERLATIVE) {
+                        const op = c.operator;
+                        if (op === 0)
+                            key = 'SUP_MIN';
+                        else if (op === 1)
+                            key = 'SUP_MAX';
+                        else if (op === 2)
+                            key = 'SUP_NOT_MIN';
+                        else if (op === 3)
+                            key = 'SUP_NOT_MAX';
+                    }
+                    else if (c.type === Clue_1.ClueType.UNARY)
+                        key = 'UNARY';
+                    else if (c.type === Clue_1.ClueType.CROSS_ORDINAL)
+                        key = 'CROSS_ORDINAL';
+                    stats[key] = (stats[key] || 0) + 1;
+                }
+            }
+        }
+        catch (e) { }
+    }
+    console.log('Done.');
+    console.log(`Total Clues: ${totalClues}`);
+    Object.keys(stats).sort().forEach(k => {
+        const pct = ((stats[k] / totalClues) * 100).toFixed(1);
+        console.log(`  ${k}: ${stats[k]} (${pct}%)`);
+    });
+}
+console.log('-----------------------------');

package/dist/examples/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/cli.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const types_1 = require("../src/types");
+const Generator_1 = require("../src/engine/Generator");
+const Solver_1 = require("../src/engine/Solver");
+const LogicGrid_1 = require("../src/engine/LogicGrid");
+const Clue_1 = require("../src/engine/Clue");
+const categories = [
+    { id: 'Name', type: types_1.CategoryType.NOMINAL, values: ['Alice', 'Bob', 'Charlie', 'David'] },
+    { id: 'Genre', type: types_1.CategoryType.NOMINAL, values: ['Horror', 'Sci-Fi', 'Comedy', 'Drama'] },
+    { id: 'Snack', type: types_1.CategoryType.NOMINAL, values: ['Chips', 'Popcorn', 'Candy', 'Chocolate'] },
+    { id: 'Age', type: types_1.CategoryType.ORDINAL, values: [20, 30, 40, 50] },
+];
+const targetFact = {
+    category1Id: 'Name',
+    value1: 'David',
+    category2Id: 'Snack',
+};
+const seed = 1234;
+const generator = new Generator_1.Generator(seed);
+const puzzle = generator.generatePuzzle(categories, targetFact);
+console.log(`## ✨ Generated Puzzle (Seed: ${seed})`);
+console.log('\n---\n');
+console.log('### The Answer Key (For Verification Only)');
+const baseCat = puzzle.categories[0];
+for (const val of baseCat.values) {
+    let line = '';
+    for (const cat of puzzle.categories) {
+        line += `${cat.id}: ${puzzle.solution[cat.id][val]} | `;
+    }
+    console.log(line.slice(0, -3));
+}
+console.log('\n### Goal');
+console.log(`What ${puzzle.targetFact.category2Id} does [Name: ${puzzle.targetFact.value1}] have?`);
+console.log('\n---\n');
+console.log('### 🧩 Clue-by-Clue Proof Chain\n');
+// The new API provides the proof chain directly, so we don't need to re-run the solver.
+// We still create a grid to show the ambiguity snapshot at each step.
+const logicGrid = new LogicGrid_1.LogicGrid(categories);
+const solver = new Solver_1.Solver();
+puzzle.proofChain.forEach((step, index) => {
+    console.log(`STEP ${index + 1}: Clue: ${clueToString(step.clue)}`);
+    console.log(`Deductions: ${step.deductions} eliminations made.`);
+    // Apply the clue to our local grid to show the state *after* this clue is applied
+    solver.applyClue(logicGrid, step.clue);
+    console.log('\nAmbiguity Snapshot:');
+    // Focused snapshot for the target fact
+    const targetCat2 = categories.find(c => c.id === puzzle.targetFact.category2Id);
+    if (targetCat2) {
+        const possibleValues = targetCat2.values.filter((v) => logicGrid.isPossible(puzzle.targetFact.category1Id, puzzle.targetFact.value1, puzzle.targetFact.category2Id, v));
+        console.log(`- Target: [${puzzle.targetFact.category1Id}: ${puzzle.targetFact.value1}] vs [${puzzle.targetFact.category2Id}]: ${possibleValues.length} possibilities remain -> [${possibleValues.join(', ')}]`);
+    }
+    // Overall grid completion
+    const { totalPossible, currentPossible, solutionPossible } = logicGrid.getGridStats();
+    const totalEliminatable = totalPossible - solutionPossible;
+    const eliminatedSoFar = totalPossible - currentPossible;
+    const percentageSolved = totalEliminatable > 0 ? (eliminatedSoFar / totalEliminatable) * 100 : 0;
+    console.log(`- Grid Solved: ${percentageSolved.toFixed(1)}%`);
+    console.log('\n---\n');
+});
+const targetValue = puzzle.solution[puzzle.targetFact.category2Id][puzzle.targetFact.value1];
+console.log(`\n**Target Fact Solved:** [${puzzle.targetFact.category1Id}: ${puzzle.targetFact.value1}] is correlated with [${puzzle.targetFact.category2Id}: ${targetValue}]!`);
+function clueToString(clue) {
+    switch (clue.type) {
+        case Clue_1.ClueType.BINARY:
+            const b = clue;
+            const op = b.operator === Clue_1.BinaryOperator.IS ? 'is' : 'is not';
+            return `[${b.cat1}: ${b.val1}] ${op} [${b.cat2}: ${b.val2}]`;
+        case Clue_1.ClueType.ORDINAL:
+            const o = clue;
+            const ordOp = o.operator === Clue_1.OrdinalOperator.GREATER_THAN ? 'is greater than' : 'is less than';
+            return `The one with [${o.item1Cat}: ${o.item1Val}] ${ordOp} the one with [${o.item2Cat}: ${o.item2Val}] (by ${o.ordinalCat})`;
+        case Clue_1.ClueType.SUPERLATIVE:
+            const s = clue;
+            const supOp = s.operator === Clue_1.SuperlativeOperator.MAX ? 'is the oldest' : 'is the youngest';
+            return `[${s.targetCat}: ${s.targetVal}] ${supOp}`;
+        case Clue_1.ClueType.UNARY:
+            const u = clue;
+            const filterStr = u.filter === Clue_1.UnaryFilter.IS_EVEN ? 'even' : 'odd';
+            return `[${u.targetCat}: ${u.targetVal}] is associated with an ${filterStr} ${u.ordinalCat}`;
+        default:
+            return 'Unknown Clue Type';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './Clue';
+export * from './LogicGrid';
+export * from './Solver';
+export * from './Generator';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./Clue"), exports);
+__exportStar(require("./LogicGrid"), exports);
+__exportStar(require("./Solver"), exports);
+__exportStar(require("./Generator"), exports);

package/dist/run_generator.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/run_generator.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const types_1 = require("./types");
+const Generator_1 = require("./Generator");
+const Solver_1 = require("./Solver");
+const LogicGrid_1 = require("./LogicGrid");
+const Clue_1 = require("./Clue");
+const categories = [
+    { id: 'Name', type: types_1.CategoryType.NOMINAL, values: ['Alice', 'Bob', 'Charlie', 'David'] },
+    { id: 'Genre', type: types_1.CategoryType.NOMINAL, values: ['Horror', 'Sci-Fi', 'Comedy', 'Drama'] },
+    { id: 'Snack', type: types_1.CategoryType.NOMINAL, values: ['Chips', 'Popcorn', 'Candy', 'Chocolate'] },
+    { id: 'Age', type: types_1.CategoryType.ORDINAL, values: [20, 30, 40, 50] },
+];
+const targetFact = {
+    category1Id: 'Name',
+    value1: 'David',
+    category2Id: 'Snack',
+};
+const seed = 1234;
+const generator = new Generator_1.Generator(seed);
+const puzzle = generator.generatePuzzle(categories, targetFact);
+console.log(`## ✨ Generated Puzzle (Seed: ${seed})`);
+console.log('\n---\n');
+console.log('### The Answer Key (For Verification Only)');
+const baseCat = puzzle.categories[0];
+for (const val of baseCat.values) {
+    let line = '';
+    for (const cat of puzzle.categories) {
+        line += `${cat.id}: ${puzzle.solution[cat.id][val]} | `;
+    }
+    console.log(line.slice(0, -3));
+}
+console.log('\n### Goal');
+console.log(`What ${puzzle.targetFact.category2Id} does [Name: ${puzzle.targetFact.value1}] have?`);
+console.log('\n---\n');
+console.log('### 🧩 Clue-by-Clue Proof Chain\n');
+// The new API provides the proof chain directly, so we don't need to re-run the solver.
+// We still create a grid to show the ambiguity snapshot at each step.
+const logicGrid = new LogicGrid_1.LogicGrid(categories);
+const solver = new Solver_1.Solver();
+puzzle.proofChain.forEach((step, index) => {
+    console.log(`STEP ${index + 1}: Clue: ${clueToString(step.clue)}`);
+    console.log(`Deductions: ${step.deductions} eliminations made.`);
+    // Apply the clue to our local grid to show the state *after* this clue is applied
+    solver.applyClue(logicGrid, step.clue);
+    console.log('\nAmbiguity Snapshot:');
+    // Focused snapshot for the target fact
+    const targetCat2 = categories.find(c => c.id === puzzle.targetFact.category2Id);
+    if (targetCat2) {
+        const possibleValues = targetCat2.values.filter(v => logicGrid.isPossible(puzzle.targetFact.category1Id, puzzle.targetFact.value1, puzzle.targetFact.category2Id, v));
+        console.log(`- Target: [${puzzle.targetFact.category1Id}: ${puzzle.targetFact.value1}] vs [${puzzle.targetFact.category2Id}]: ${possibleValues.length} possibilities remain -> [${possibleValues.join(', ')}]`);
+    }
+    // Overall grid completion
+    const { totalPossible, currentPossible, solutionPossible } = logicGrid.getGridStats();
+    const totalEliminatable = totalPossible - solutionPossible;
+    const eliminatedSoFar = totalPossible - currentPossible;
+    const percentageSolved = totalEliminatable > 0 ? (eliminatedSoFar / totalEliminatable) * 100 : 0;
+    console.log(`- Grid Solved: ${percentageSolved.toFixed(1)}%`);
+    console.log('\n---\n');
+});
+const targetValue = puzzle.solution[puzzle.targetFact.category2Id][puzzle.targetFact.value1];
+console.log(`\n**Target Fact Solved:** [${puzzle.targetFact.category1Id}: ${puzzle.targetFact.value1}] is correlated with [${puzzle.targetFact.category2Id}: ${targetValue}]!`);
+function clueToString(clue) {
+    switch (clue.type) {
+        case Clue_1.ClueType.BINARY:
+            const b = clue;
+            const op = b.operator === Clue_1.BinaryOperator.IS ? 'is' : 'is not';
+            return `[${b.cat1}: ${b.val1}] ${op} [${b.cat2}: ${b.val2}]`;
+        case Clue_1.ClueType.ORDINAL:
+            const o = clue;
+            const ordOp = o.operator === Clue_1.OrdinalOperator.GREATER_THAN ? 'is greater than' : 'is less than';
+            return `The one with [${o.item1Cat}: ${o.item1Val}] ${ordOp} the one with [${o.item2Cat}: ${o.item2Val}] (by ${o.ordinalCat})`;
+        case Clue_1.ClueType.SUPERLATIVE:
+            const s = clue;
+            const supOp = s.operator === Clue_1.SuperlativeOperator.MAX ? 'is the oldest' : 'is the youngest';
+            return `[${s.targetCat}: ${s.targetVal}] ${supOp}`;
+        case Clue_1.ClueType.UNARY:
+            const u = clue;
+            const filterStr = u.filter === Clue_1.UnaryFilter.IS_EVEN ? 'even' : 'odd';
+            return `[${u.targetCat}: ${u.targetVal}] is associated with an ${filterStr} ${u.ordinalCat}`;
+        default:
+            return 'Unknown Clue Type';
+    }
+}

package/dist/src/defaults.d.ts

@@ -0,0 +1,5 @@
+import { CategoryConfig } from './types';
+/**
+ * A default set of categories for a standard logic puzzle (Name, Snack, Age).
+ */
+export declare const DEFAULT_CATEGORIES: CategoryConfig[];

package/dist/src/defaults.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CATEGORIES = void 0;
+const types_1 = require("./types");
+/**
+ * A default set of categories for a standard logic puzzle (Name, Snack, Age).
+ */
+exports.DEFAULT_CATEGORIES = [
+    {
+        id: 'Name',
+        type: types_1.CategoryType.NOMINAL,
+        values: ['Alice', 'Bob', 'Charlie', 'David'],
+    },
+    {
+        id: 'Snack',
+        type: types_1.CategoryType.NOMINAL,
+        values: ['Chips', 'Popcorn', 'Candy', 'Chocolate'],
+    },
+    {
+        id: 'Age',
+        type: types_1.CategoryType.ORDINAL,
+        values: [20, 30, 40, 50],
+    },
+];

package/dist/src/engine/BoundsCalculator.d.ts

@@ -0,0 +1,6 @@
+export declare class BoundsCalculator {
+    static calculate(numCats: number, numItems: number, iterations?: number): {
+        min: number;
+        max: number;
+    };
+}