logic-puzzle-generator 1.2.3 → 1.2.4

package/README.md

@@ -197,6 +197,7 @@ The main class. Use `new Generator(seed)` to initialize.
         - `includeSubjects`: `string[]` (New in v1.1.X). Restrict to clues involving these values.
         - `excludeSubjects`: `string[]` (New in v1.1.X). Exclude clues involving these values.
         - `minDeductions`: `number` (New in v1.1.X). Min new info required (default 1). Set to 0 for filler.
+        - `maxDeductions`: `number`. Max new info allowed. Set to 0 to force redundant clues.
     - `options.onTrace`: **(Debug)** Callback `(msg: string) => void`. Receives real-time logs about the generation process.
 - `generatePuzzleAsync(...)`: **New in v1.1.0**. Non-blocking version of `generatePuzzle`. Returns `Promise<Puzzle>`.
 - `getClueCountBounds(categories, target)`: Returns plausible Min/Max clue counts.
@@ -236,7 +237,7 @@ The logical engine responsible for applying clues and performing deductions.
 Manages a stateful, step-by-step puzzle generation process.
 - `getNextClue(constraints?)`: Returns `{ clue: Clue | null, remaining: number, solved: boolean }`.
     - Generates and selects the next best clue based on the current grid state.
-    -### `session.getNextClue(options?: ClueGenerationConstraints)`
+### `session.getNextClue(options?: ClueGenerationConstraints)`
 
 Generates the next step in the puzzle, returning the best available clue based on internal scoring and provided constraints.
 
@@ -259,11 +260,30 @@ Each result object contains:
 
 ### `session.useClue(clue: Clue)`
 
-Manually applies a specific clue to the board. Useful for interactive search features.
+Manually applies a specific clue to the board. 
+**Safety**: This method validates the clue against the hidden solution. If the clue implies a contradiction (i.e. is logically false), it throws an `Error`.
 
-### `session.rollbackLastClue()`: Returns `{ success: boolean, clue: Clue | null }`. Undoes the last step.
-- `getNextClueAsync(constraints?)`: **New in v1.1.1**. Non-blocking version. Returns `Promise<{ clue, remaining, solved }>`.
-- `rollbackLastClue()`: Returns `{ success: boolean, clue: Clue | null }`. Undoes the last step.
+### `session.rollbackLastClue()`
+Returns `{ success: boolean, clue: Clue | null }`. Undoes the last step.
+
+### `session.removeClue(index: number)`
+**New in v1.2.0**. Removes a clue from the current proof chain at the specified index.
+- Automatically recalculates all deductions for subsequent clues.
+- Updates the "Target Solved" status if the removal breaks the logical path to the goal.
+
+### `session.moveClue(fromIndex: number, toIndex: number)`
+**New in v1.2.0**. Reorders clues in the proof chain.
+- Returns `true` if the move was valid and successful.
+- Recalculates the entire puzzle state based on the new order.
+- This allows for "What If?" scenarios: "What if I knew this fact earlier?"
+
+### `session.getTargetSolvedStepIndex()`
+**New in v1.2.0**. Returns the index of the clue that first makes the Target Fact deducible.
+- Returns `-1` if the target is not yet solved.
+- This is dynamic: removing or reordering clues will change this index, allowing you to find the exact "Eureka!" moment in the chain.
+
+### `session.getNextClueAsync(constraints?)`
+**New in v1.1.1**. Non-blocking version. Returns `Promise<{ clue, remaining, solved }>`.
 - `getGrid()`: Returns the current `LogicGrid` state.
 - `getSolution()`: Returns the target `Solution` map.
 - `getProofChain()`: Returns the list of `Clue`s applied so far.
@@ -310,7 +330,8 @@ while (!solved) {
         allowedClueTypes: [ClueType.BINARY, ClueType.ORDINAL],
         includeSubjects: ['Mustard', 'Plum'],     // Only clues about these entities
         excludeSubjects: ['Revolver'],            // No clues dealing with Revolvers
-        minDeductions: 0                          // Allow "useless" clues (flavor text)
+        minDeductions: 0,                         // Allow "useless" clues (flavor text)
+        maxDeductions: 0                          // STRICTLY "useless" clues (0 deductions)
     });
     });
 

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

@@ -72,4 +72,15 @@ export interface CrossOrdinalClue {
     /** The offset from the anchor (-1 = before, +1 = after) */
     offset2: number;
 }
+/**
+ * Union type representing any valid clue.
+ */
 export type Clue = BinaryClue | OrdinalClue | SuperlativeClue | UnaryClue | CrossOrdinalClue;
+/**
+ * Extension for clues with metadata attached during generation/solving.
+ */
+export type ClueWithMetadata = Clue & {
+    deductions?: number;
+    updates?: number;
+    percentComplete?: number;
+};

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

@@ -13,16 +13,20 @@ export declare class GenerativeSession {
     private availableClues;
     private proofChain;
     private solver;
+    private targetSolvedStepIndex;
     private historyStack;
     constructor(generator: Generator, categories: CategoryConfig[], solution: Solution, reverseSolution: Map<string, Map<ValueLabel, ValueLabel>>, valueMap: Map<ValueLabel, Record<string, ValueLabel>>, targetFact: TargetFact);
     getTotalClueCount(): number;
+    getTargetSolvedStepIndex(): number;
     getMatchingClueCount(constraints?: ClueGenerationConstraints): number;
     getMatchingClues(constraints?: ClueGenerationConstraints, limit?: number): Clue[];
     getScoredMatchingClues(constraints?: ClueGenerationConstraints, limit?: number): {
         clue: Clue;
         score: number;
         deductions: number;
+        updates: number;
         isDirectAnswer: boolean;
+        percentComplete: number;
     }[];
     useClue(clue: Clue): {
         remaining: number;
@@ -30,6 +34,8 @@ export declare class GenerativeSession {
     };
     private filterClues;
     private applyAndSave;
+    private checkTargetSolvedInternal;
+    private checkTargetSolved;
     getNextClue(constraints?: ClueGenerationConstraints): {
         clue: Clue | null;
         remaining: number;
@@ -49,6 +55,18 @@ export declare class GenerativeSession {
         clue: Clue | null;
     };
     private isUseful;
+    /**
+     * Removes a clue from the proof chain at the specified index.
+     * Replays all subsequent clues to ensure state consistency.
+     * @param index Index of the clue in the proofChain (0-based)
+     */
+    removeClueAt(index: number): boolean;
+    /**
+     * Moves a clue from one index to another in the proof chain.
+     * Replays all clues to update metadata and target detection.
+     */
+    moveClue(fromIndex: number, toIndex: number): boolean;
+    private replayProofChain;
     getGrid(): LogicGrid;
     getProofChain(): Clue[];
     getSolution(): Solution;

package/dist/src/engine/GenerativeSession.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GenerativeSession = void 0;
 const types_1 = require("../types");
+const errors_1 = require("../errors");
 const LogicGrid_1 = require("./LogicGrid");
 const Solver_1 = require("./Solver");
 class GenerativeSession {
@@ -14,9 +15,11 @@ class GenerativeSession {
         this.targetFact = targetFact;
         this.availableClues = [];
         this.proofChain = [];
+        this.targetSolvedStepIndex = -1; // -1 means logic not solved by clues yet
         this.historyStack = [];
         this.grid = new LogicGrid_1.LogicGrid(categories);
         this.solver = new Solver_1.Solver();
+        this.checkTargetSolved(); // Check initial state (unlikely solved unless trivial)
         // Initial Generation of ALL possibilities (we filter later)
         // We need access to the generator's clue generation logic.
         // We will call a public method on generator.
@@ -25,6 +28,9 @@ class GenerativeSession {
     getTotalClueCount() {
         return this.availableClues.length;
     }
+    getTargetSolvedStepIndex() {
+        return this.targetSolvedStepIndex;
+    }
     getMatchingClueCount(constraints) {
         return this.filterClues(constraints).length;
     }
@@ -33,22 +39,23 @@ class GenerativeSession {
         return clues.slice(0, limit);
     }
     getScoredMatchingClues(constraints, limit = 50) {
-        const clues = this.filterClues(constraints);
-        // Score all (or up to a reasonable hard limit to avoid perf issues, say 200)
-        // Then sort and take top 'limit'
-        const candidateLimit = 200;
-        const candidates = clues.slice(0, candidateLimit);
-        const scored = candidates.map(clue => {
-            // Score Logic - similar to getNextClue but without the constraints checks (already done)
+        const validClues = this.filterClues(constraints);
+        const results = [];
+        const minDeductions = constraints?.minDeductions ?? 0;
+        const maxDeductions = constraints?.maxDeductions;
+        if (maxDeductions !== undefined && minDeductions > maxDeductions) {
+            throw new errors_1.ConfigurationError(`Invalid constraints: minDeductions (${minDeductions}) cannot be greater than maxDeductions (${maxDeductions}).`);
+        }
+        for (const clue of validClues) {
             const tempGrid = this.grid.clone();
             const { deductions } = this.solver.applyClue(tempGrid, clue);
-            // Calculate real score
+            if (deductions < minDeductions)
+                continue;
+            if (maxDeductions !== undefined && deductions > maxDeductions)
+                continue;
             const score = this.generator.calculateClueScore(this.grid, this.targetFact, deductions, clue, this.proofChain, this.solution, this.reverseSolution);
-            // Check if this is the "Direct Answer" (Positive link for the target fact)
             let isDirectAnswer = false;
             if (clue.type === types_1.ClueType.BINARY) {
-                // Check if it links the target subject to the target category
-                // Positive operators: IS (0). Assuming enum values.
                 const isPositive = clue.operator === types_1.BinaryOperator.IS;
                 if (isPositive) {
                     const c = clue;
@@ -59,17 +66,28 @@ class GenerativeSession {
                     }
                 }
             }
-            return { clue, score, deductions, isDirectAnswer };
-        });
-        // Sort by score descending
-        scored.sort((a, b) => b.score - a.score);
-        // Filter by minDeductions if provided
-        // Defaults to 0 if undefined (allow all)
-        const minDeductions = constraints?.minDeductions ?? 0;
-        const finalResults = scored.filter(s => s.deductions >= minDeductions);
-        return finalResults.slice(0, limit);
+            // Calculate Projected % Complete
+            const stats = tempGrid.getGridStats();
+            const range = stats.totalPossible - stats.solutionPossible;
+            const progress = stats.totalPossible - stats.currentPossible;
+            let percentComplete = 0;
+            if (range > 0) {
+                percentComplete = Math.min(100, Math.max(0, (progress / range) * 100));
+            }
+            else {
+                percentComplete = 100;
+            }
+            const updates = tempGrid.compareVisualState(this.grid);
+            results.push({ clue, score, deductions, updates, isDirectAnswer, percentComplete });
+        }
+        return results.sort((a, b) => b.score - a.score).slice(0, limit);
     }
     useClue(clue) {
+        // Validate against solution (Anti-Cheat / Logic Guard)
+        const isConsistent = this.generator.checkClueConsistency(clue, this.solution, this.reverseSolution, this.valueMap);
+        if (!isConsistent) {
+            throw new Error("Invalid Clue: This clue contradicts the puzzle solution.");
+        }
         // Ensure the clue is removed from available if it was there
         // (If searching, the UI passes a Clue object that should exist in our availableClues)
         this.applyAndSave(clue);
@@ -108,13 +126,71 @@ class GenerativeSession {
         // Save state
         this.historyStack.push(this.grid.clone());
         // Apply it
-        this.solver.applyClue(this.grid, clue);
+        const result = this.solver.applyClue(this.grid, clue);
+        clue.deductions = result.deductions;
+        // Calculate % Complete
+        // Grid starts with 'totalPossible' and ends with 'solutionPossible'.
+        // % = (Total - Current) / (Total - Solution)
+        const stats = this.grid.getGridStats();
+        // Avoid division by zero if puzzle is tiny or trivial
+        const range = stats.totalPossible - stats.solutionPossible;
+        const progress = stats.totalPossible - stats.currentPossible;
+        if (range > 0) {
+            clue.percentComplete = Math.min(100, Math.max(0, (progress / range) * 100));
+        }
+        else {
+            clue.percentComplete = 100;
+        }
+        // Calculate Visual Updates (Red Crosses + Green Checks)
+        // We compare the grid before (this.historyStack.last?) application
+        // Wait, 'this.grid' is ALREADY modified here.
+        // We saved the previous state in historyStack.
+        const prevGrid = this.historyStack[this.historyStack.length - 1];
+        if (prevGrid) {
+            clue.updates = this.grid.compareVisualState(prevGrid);
+        }
+        else {
+            // Should not happen unless history empty? Initial state?
+            clue.updates = clue.deductions; // Fallback
+        }
         this.proofChain.push(clue);
+        // Check if target is solved now (if it wasn't before)
+        if (this.targetSolvedStepIndex === -1) {
+            const isSolved = this.checkTargetSolvedInternal();
+            if (isSolved) {
+                this.targetSolvedStepIndex = this.proofChain.length - 1;
+            }
+        }
         // Remove from available
         const idx = this.availableClues.indexOf(clue);
         if (idx > -1)
             this.availableClues.splice(idx, 1);
     }
+    checkTargetSolvedInternal() {
+        // Check if the specific target fact is confirmed in the grid
+        // Fact: (Cat1, Val1) is linked to (Cat2) -> ?
+        // We need to check if grid has determined the link.
+        // targetFact has Cat1, Val1, Cat2.
+        // Ideally we check if Possibilities(Cat1, Val1, Cat2) === 1.
+        // Wait, TargetFact structure:
+        // { category1Id, value1, category2Id, value2? }
+        // If value2 is present (specific pairing target), we check isFactConfirmed.
+        // If value2 is NOT present (general "find the husband" target), we check if ANY link is confirmed?
+        // Actually, usually the target is "Find the Value in Cat2 for (Cat1, Val1)".
+        // So we check if the Number of Possibilities for (Cat1, Val1) in Cat2 is exactly 1.
+        return this.grid.getPossibilitiesCount(this.targetFact.category1Id, this.targetFact.value1, this.targetFact.category2Id) === 1;
+    }
+    checkTargetSolved() {
+        if (this.checkTargetSolvedInternal()) {
+            // If solved at start (step -1?) logic handles index relative to proof chain.
+            // If solved initially, maybe index is -1?
+            // But if it's -1, it means "Before any clues".
+            // Let's stick to -1 being "Not Found Yet" vs "Found at Initial State"?
+            // If found at start, we might want to know.
+            // But normally target is unknown.
+            // Let's assume -1 is "Not Solved".
+        }
+    }
     getNextClue(constraints) {
         const validClues = this.filterClues(constraints);
         // Score them
@@ -126,6 +202,10 @@ class GenerativeSession {
         const searchLimit = 50;
         let checked = 0;
         const minDeductions = constraints?.minDeductions ?? 0;
+        const maxDeductions = constraints?.maxDeductions;
+        if (maxDeductions !== undefined && minDeductions > maxDeductions) {
+            throw new errors_1.ConfigurationError(`Invalid constraints: minDeductions (${minDeductions}) cannot be greater than maxDeductions (${maxDeductions}).`);
+        }
         for (const clue of candidates) {
             checked++;
             if (checked > searchLimit && bestClue)
@@ -138,12 +218,31 @@ class GenerativeSession {
             if (deductions < minDeductions) {
                 continue;
             }
+            if (maxDeductions !== undefined && deductions > maxDeductions) {
+                continue;
+            }
             // Re-calc score with deductions
             const realScore = this.generator.calculateClueScore(this.grid, this.targetFact, deductions, clue, this.proofChain, this.solution, this.reverseSolution);
+            // Calculate Projected % Complete
+            const stats = tempGrid.getGridStats();
+            const range = stats.totalPossible - stats.solutionPossible;
+            const progress = stats.totalPossible - stats.currentPossible;
+            let percentComplete = 0;
+            if (range > 0) {
+                percentComplete = Math.min(100, Math.max(0, (progress / range) * 100));
+            }
+            else {
+                percentComplete = 100;
+            }
             if (realScore > bestScore) {
                 bestScore = realScore;
                 bestClue = clue;
             }
+            // Note: getScoredMatchingClues will need to collect this.
+            // But this is getNextClue.
+            // Wait, I need to update getScoredMatchingClues, not getNextClue loop?
+            // Yes, user said "search list".
+            // Let's modify getScoredMatchingClues below, but first let me fix the tool call target.
         }
         if (bestClue) {
             this.applyAndSave(bestClue);
@@ -189,6 +288,69 @@ class GenerativeSession {
         // If deductions > 0, it's useful.
         return true;
     }
+    /**
+     * Removes a clue from the proof chain at the specified index.
+     * Replays all subsequent clues to ensure state consistency.
+     * @param index Index of the clue in the proofChain (0-based)
+     */
+    removeClueAt(index) {
+        if (index < 0 || index >= this.proofChain.length)
+            return false;
+        const removedClue = this.proofChain[index];
+        // 1. Remove from proofChain
+        this.proofChain.splice(index, 1);
+        // 2. Return to availableClues
+        this.availableClues.push(removedClue);
+        // 3. Replay Logic
+        return this.replayProofChain();
+    }
+    /**
+     * Moves a clue from one index to another in the proof chain.
+     * Replays all clues to update metadata and target detection.
+     */
+    moveClue(fromIndex, toIndex) {
+        if (fromIndex < 0 || fromIndex >= this.proofChain.length)
+            return false;
+        if (toIndex < 0 || toIndex >= this.proofChain.length)
+            return false;
+        if (fromIndex === toIndex)
+            return true; // No op
+        const clue = this.proofChain[fromIndex];
+        // Remove
+        this.proofChain.splice(fromIndex, 1);
+        // Insert
+        this.proofChain.splice(toIndex, 0, clue);
+        return this.replayProofChain();
+    }
+    replayProofChain() {
+        // Reset grid to initial state
+        this.grid = new LogicGrid_1.LogicGrid(this.categories);
+        this.historyStack = []; // Reset history
+        this.solver = new Solver_1.Solver(); // Fresh solver (stateless anyway)
+        this.targetSolvedStepIndex = -1; // Reset target detection
+        // Check if solved initially (unlikely)
+        if (this.checkTargetSolvedInternal()) {
+            // If solved with 0 clues, maybe set to -1 (start)? 
+            // Or a special value? Let's leave it -1 and handle it?
+            // Actually if it's solved at start, then stepIndex = -1 makes sense if we consider 0-based index of clues.
+            // But usually we mark "Revealed AFTER step X".
+        }
+        // Put ALL proofChain clues back into available first (so applyAndSave finds them)
+        // We must push them all back because applyAndSave will splice them out.
+        // Note: availableClues might ideally be a Set or map for speed, but array is fine for now.
+        // We should add them ONLY if they are not already there?
+        // Actually, proofChain clues are NOT in availableClues.
+        this.availableClues.push(...this.proofChain);
+        // Capture chain
+        const chainToReplay = [...this.proofChain];
+        // Clear proofChain
+        this.proofChain = [];
+        // Re-apply
+        for (const c of chainToReplay) {
+            this.applyAndSave(c);
+        }
+        return true;
+    }
     // Getters for UI
     getGrid() { return this.grid; }
     getProofChain() { return this.proofChain; }

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

@@ -140,5 +140,11 @@ export declare class Generator {
      * Higher scores represent better clues according to the current strategy.
      */
     calculateClueScore(grid: LogicGrid, target: TargetFact, deductions: number, clue: Clue, previouslySelectedClues: Clue[], solution: Solution, reverseSolution: Map<string, Map<ValueLabel, ValueLabel>>): number;
+    /**
+     * Checks if a clue is logically consistent with the provided solution.
+     * Returns true if the clue is TRUE in the context of the solution.
+     * Returns false if the clue is FALSE (contradicts the solution).
+     */
+    checkClueConsistency(clue: Clue, solution: Solution, reverseSolution: Map<string, Map<ValueLabel, ValueLabel>>, valueMap: Map<ValueLabel, Record<string, ValueLabel>>): boolean;
     isPuzzleSolved(grid: LogicGrid, solution: Solution, reverseSolution: Map<string, Map<ValueLabel, ValueLabel>>): boolean;
 }

package/dist/src/engine/Generator.js

@@ -440,6 +440,26 @@ class Generator {
             if (this.isPuzzleSolved(logicGrid, this.solution, this.reverseSolution))
                 break;
         }
+        // ---------------------------------------------------------
+        // METADATA REPLAY PASS
+        // ---------------------------------------------------------
+        // Re-apply clues to a fresh grid to calculate accurate metadata (deductions, % complete)
+        // for the final solution view.
+        const replayGrid = new LogicGrid_1.LogicGrid(categories);
+        const replayStats = replayGrid.getGridStats();
+        const totalRange = replayStats.totalPossible - replayStats.solutionPossible;
+        for (const step of proofChain) {
+            const result = this.solver.applyClue(replayGrid, step.clue);
+            step.clue.deductions = result.deductions;
+            const currentStats = replayGrid.getGridStats();
+            const progress = currentStats.totalPossible - currentStats.currentPossible;
+            if (totalRange > 0) {
+                step.clue.percentComplete = Math.min(100, Math.max(0, (progress / totalRange) * 100));
+            }
+            else {
+                step.clue.percentComplete = 100;
+            }
+        }
         return {
             solution: this.solution,
             clues: proofChain.map(p => p.clue),
@@ -1096,6 +1116,125 @@ class Generator {
         const score = ((synergyScore * complexityBonus) + (completenessScore * 5)) * repetitionPenalty;
         return score;
     }
+    /**
+     * Checks if a clue is logically consistent with the provided solution.
+     * Returns true if the clue is TRUE in the context of the solution.
+     * Returns false if the clue is FALSE (contradicts the solution).
+     */
+    checkClueConsistency(clue, solution, reverseSolution, valueMap) {
+        // Helper to get real value
+        const getRealValue = (catId, val, targetCatId) => {
+            const baseVal = reverseSolution.get(catId)?.get(val);
+            if (!baseVal)
+                return undefined;
+            return solution[targetCatId][baseVal];
+        };
+        const getBaseValue = (catId, val) => {
+            return reverseSolution.get(catId)?.get(val);
+        };
+        // Helper to get Ordinal Numeric Value
+        const getOrdinalValue = (catId, val, ordinalCatId) => {
+            const baseVal = getBaseValue(catId, val);
+            if (!baseVal)
+                return undefined;
+            const mappings = valueMap.get(baseVal);
+            if (!mappings)
+                return undefined;
+            const ordVal = mappings[ordinalCatId];
+            return typeof ordVal === 'number' ? ordVal : undefined;
+        };
+        switch (clue.type) {
+            case types_1.ClueType.BINARY: {
+                const b = clue;
+                const realVal2 = getRealValue(b.cat1, b.val1, b.cat2);
+                if (realVal2 === undefined)
+                    return false; // Should not happen in consistent state
+                if (b.operator === types_1.BinaryOperator.IS) {
+                    return realVal2 === b.val2;
+                }
+                else if (b.operator === types_1.BinaryOperator.IS_NOT) {
+                    return realVal2 !== b.val2;
+                }
+                break;
+            }
+            case types_1.ClueType.ORDINAL: {
+                const o = clue;
+                const v1 = getOrdinalValue(o.item1Cat, o.item1Val, o.ordinalCat);
+                const v2 = getOrdinalValue(o.item2Cat, o.item2Val, o.ordinalCat);
+                if (v1 === undefined || v2 === undefined)
+                    return false;
+                switch (o.operator) {
+                    case types_1.OrdinalOperator.GREATER_THAN: return v1 > v2;
+                    case types_1.OrdinalOperator.LESS_THAN: return v1 < v2;
+                    case types_1.OrdinalOperator.NOT_GREATER_THAN: return v1 <= v2; // Not After
+                    case types_1.OrdinalOperator.NOT_LESS_THAN: return v1 >= v2; // Not Before
+                }
+                break;
+            }
+            case types_1.ClueType.SUPERLATIVE: {
+                const s = clue;
+                const v = getOrdinalValue(s.targetCat, s.targetVal, s.ordinalCat);
+                if (v === undefined)
+                    return false;
+                // We need the min/max of the ordinal category
+                // Since we don't have categories passed in directly, we can infer from valueMap or we need categories?
+                // valueMap has all values.
+                // But simpler: we know mappings for ALL items in ordinal cat.
+                // Let's iterate all base values to find min/max for that ordinal cat.
+                let min = Infinity;
+                let max = -Infinity;
+                // valueMap keys are baseValues (Category[0] values)
+                for (const baseVal of this.valueMap.keys()) {
+                    const mappings = this.valueMap.get(baseVal);
+                    if (mappings) {
+                        const ov = mappings[s.ordinalCat];
+                        if (typeof ov === 'number') {
+                            if (ov < min)
+                                min = ov;
+                            if (ov > max)
+                                max = ov;
+                        }
+                    }
+                }
+                if (min === Infinity)
+                    return false; // No ordinal values found?
+                switch (s.operator) {
+                    case types_1.SuperlativeOperator.MIN: return v === min;
+                    case types_1.SuperlativeOperator.MAX: return v === max;
+                    case types_1.SuperlativeOperator.NOT_MIN: return v !== min;
+                    case types_1.SuperlativeOperator.NOT_MAX: return v !== max;
+                }
+                break;
+            }
+            case types_1.ClueType.UNARY: {
+                const u = clue;
+                const v = getOrdinalValue(u.targetCat, u.targetVal, u.ordinalCat);
+                if (v === undefined)
+                    return false;
+                switch (u.filter) {
+                    case types_1.UnaryFilter.IS_ODD: return (v % 2 !== 0);
+                    case types_1.UnaryFilter.IS_EVEN: return (v % 2 === 0);
+                }
+                break;
+            }
+            case types_1.ClueType.CROSS_ORDINAL: {
+                const c = clue;
+                const v1 = getOrdinalValue(c.item1Cat, c.item1Val, c.ordinal1);
+                const v2 = getOrdinalValue(c.item2Cat, c.item2Val, c.ordinal2);
+                if (v1 === undefined || v2 === undefined)
+                    return false;
+                const op = c.operator;
+                switch (op) {
+                    case types_1.OrdinalOperator.GREATER_THAN: return v1 > v2;
+                    case types_1.OrdinalOperator.LESS_THAN: return v1 < v2;
+                    case types_1.OrdinalOperator.NOT_GREATER_THAN: return v1 <= v2;
+                    case types_1.OrdinalOperator.NOT_LESS_THAN: return v1 >= v2;
+                }
+                break;
+            }
+        }
+        return true;
+    }
     isPuzzleSolved(grid, solution, reverseSolution) {
         const categories = grid.categories;
         const baseCategory = categories[0];

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

@@ -67,4 +67,14 @@ export declare class LogicGrid {
      * @returns A new LogicGrid instance with the exact same state.
      */
     clone(): LogicGrid;
+    /**
+     * Compares this grid with a previous state and counts visual updates.
+     * A "Visual Update" is defined as:
+     * 1. A cell changing from Possible (True) to Eliminated (False) [Red Cross]
+     * 2. A cell changing from Ambiguous (Count > 1) to Unique (Count == 1) [Green Check]
+     *
+     * @param prevGrid - The previous grid state.
+     * @returns The number of visual updates.
+     */
+    compareVisualState(prevGrid: LogicGrid): number;
 }

package/dist/src/engine/LogicGrid.js

@@ -186,5 +186,50 @@ class LogicGrid {
         ]));
         return newGrid;
     }
+    /**
+     * Compares this grid with a previous state and counts visual updates.
+     * A "Visual Update" is defined as:
+     * 1. A cell changing from Possible (True) to Eliminated (False) [Red Cross]
+     * 2. A cell changing from Ambiguous (Count > 1) to Unique (Count == 1) [Green Check]
+     *
+     * @param prevGrid - The previous grid state.
+     * @returns The number of visual updates.
+     */
+    compareVisualState(prevGrid) {
+        let updates = 0;
+        const categories = this.categories;
+        for (const cat1 of categories) {
+            for (const val1 of cat1.values) {
+                for (const cat2 of categories) {
+                    if (cat1.id >= cat2.id)
+                        continue;
+                    // 1. Check for Red Crosses (True -> False)
+                    // We iterate individual cells
+                    const val1Map = this.grid.get(cat1.id)?.get(val1);
+                    const prevVal1Map = prevGrid.grid.get(cat1.id)?.get(val1);
+                    if (val1Map && prevVal1Map) {
+                        const vals2Arr = val1Map.get(cat2.id);
+                        const prevVals2Arr = prevVal1Map.get(cat2.id);
+                        if (vals2Arr && prevVals2Arr) {
+                            for (let i = 0; i < vals2Arr.length; i++) {
+                                // If it WAS true and IS NOW false
+                                if (prevVals2Arr[i] && !vals2Arr[i]) {
+                                    updates++;
+                                }
+                            }
+                        }
+                    }
+                    // 2. Check for Green Checks (Ambiguous -> Unique)
+                    // We check the Row Context (Possibilities Count)
+                    const prevCount = prevGrid.getPossibilitiesCount(cat1.id, val1, cat2.id);
+                    const currCount = this.getPossibilitiesCount(cat1.id, val1, cat2.id);
+                    if (prevCount > 1 && currCount === 1) {
+                        updates++;
+                    }
+                }
+            }
+        }
+        return updates;
+    }
 }
 exports.LogicGrid = LogicGrid;

package/dist/src/engine/Solver.js

@@ -382,6 +382,10 @@ class Solver {
         if (!cat1Config || !cat2Config)
             return 0;
         if (clue.operator === types_1.BinaryOperator.IS) {
+            // Count the "Positive Confirmation" (Green Check) as a deduction if it wasn't already known
+            if (grid.getPossibilitiesCount(clue.cat1, clue.val1, clue.cat2) > 1) {
+                deductions++;
+            }
             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.
             }

package/dist/src/types.d.ts

@@ -97,4 +97,9 @@ export interface ClueGenerationConstraints {
      * Default is 0 (allow all clues). Set to 1 to ensure progress.
      */
     minDeductions?: number;
+    /**
+     * Maximum number of new deductions this clue is allowed to provide.
+     * Useful for finding low-impact or "filler" clues, or ensuring a clue isn't *too* powerful.
+     */
+    maxDeductions?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "logic-puzzle-generator",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -45,4 +45,4 @@
     "ts-jest": "^29.1.2",
     "typescript": "^5.4.5"
   }
-}
+}