logic-puzzle-generator 1.0.0 → 1.2.0

package/README.md

@@ -5,6 +5,10 @@
 ![License](https://img.shields.io/badge/license-MIT-green)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)
 
+[View the interactive demo](https://project.joshhills.dev/logic-puzzle-generator/)
+
+![Interactive Demo Screenshot](./demo.png)
+
 
 A TypeScript library for generating, solving, and verifying "Zebra Puzzle" style logic grid puzzles.
 
@@ -183,24 +187,156 @@ The generator solves the puzzle as it builds it. The `puzzle.proofChain` array c
 ### `Generator`
 The main class. Use `new Generator(seed)` to initialize.
 
-- `generatePuzzle(categories, target, options)`: Returns a `Puzzle` object.
-    - `options.targetClueCount`: Attempt to find exact solution length.
-    - `options.maxCandidates`: Performance tuning (default 50).
-    - `options.onTrace`: **(Debug)** Callback `(msg: string) => void`. Receives real-time logs about the generation process (e.g., "Backtracking", "Pruning", "Solution Found"). Useful for debugging timeouts or understanding the generator's decision making.
+- `generatePuzzle(categories, target?, options?)`: Returns a `Puzzle` object.
+    - `target` (Optional): The `TargetFact` to solve for. If omitted, a random target is selected.
+    - `options.targetClueCount`: Attempt to find exact solution length. Avoids early termination.
+    - `options.maxCandidates`: Performance tuning (default 50). Limits the heuristic search width.
+    - `options.timeoutMs`: Abort generation if it exceeds this limit (default 10000ms).
+    - `options.constraints`: Filter/control generated clues.
+        - `allowedClueTypes`: `ClueType[]`.
+        - `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.
+    - `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.
-- `startSession(categories, target?)`: [Beta] Starts a `GenerativeSession` for step-by-step interactive generation (useful for "Builder Mode" UIs).
+- `getClueCountBoundsAsync(...)`: **New in v1.1.0**. Non-blocking version. Returns `Promise<{ min, max }>`.
+- `startSession(categories, target?)`: [Beta] Starts a `GenerativeSession` for step-by-step interactive generation.
+
+#### Advanced / Internal API
+- `calculateClueScore(grid, target, deductions, clue, ...)`: **(Extensible)** detailed heuristic scoring for clue selection.
+- `isPuzzleSolved(grid, solution, ...)`: Checks if the grid matches the unique solution.
+- `generateAllPossibleClues(...)`: Generates every valid clue for the current configuration (unfiltered).
 
 ### Extensibility
 The `Generator` class is designed to be extensible. Key methods like `calculateClueScore` are `public`, allowing you to extend the class and inject custom heuristics.
 
 ### `LogicGrid`
 Manages the state of the puzzle grid (possibility matrix).
+- `constructor(categories: CategoryConfig[])`: Initializes a new grid.
 - `isPossible(cat1, val1, cat2, val2)`: Returns true if a connection is possible.
-- `setPossibility(...)`: Manually set states (useful for custom solvers).
+- `setPossibility(cat1, val1, cat2, val2, state)`: Manually set connection state.
+- `getPossibilitiesCount(cat1, val1, cat2)`: Returns the number of remaining possibilities for a value in a target category.
+- `getGridStats()`: Returns `{ totalPossible, currentPossible, solutionPossible }` to track solving progress.
+- `clone()`: Creates a deep copy of the grid.
 
 ### `Solver`
-The logical engine.
-- `applyClue(grid, clue)`: Applies a clue and cascades deductions.
+The logical engine responsible for applying clues and performing deductions.
+- `applyClue(grid, clue)`: Applies a clue and cascades deductions. Returns `{ deductions: number }`.
+- `runDeductionLoop(grid)`: repeatedly applies elimination logic until the grid stabilizes.
+
+#### Internal Deduction Methods
+- `applyBinaryClue(grid, clue)`
+- `applyOrdinalClue(grid, clue)`
+- `applyCrossOrdinalClue(grid, clue)`
+- `applySuperlativeClue(grid, clue)`
+- `applyUnaryClue(grid, clue)`
+
+### `GenerativeSession`
+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)`
+
+Generates the next step in the puzzle, returning the best available clue based on internal scoring and provided constraints.
+
+### `session.getTotalClueCount()`
+
+Returns the total number of valid clues remaining in the pool.
+
+### `session.getMatchingClueCount(options?: ClueGenerationConstraints)`
+
+Returns the number of clues that match the current filtering criteria.
+
+### `session.getScoredMatchingClues(options?: ClueGenerationConstraints, limit: number = 50)`
+
+Returns a list of clues matching the constraints, sorted by heuristic score.
+Each result object contains:
+- `clue`: The Clue object.
+- `score`: The calculated helpfulness score.
+- `deductions`: The number of new cell updates this clue provides.
+- `isDirectAnswer`: Boolean indicating if this clue directly reveals the puzzle's goal.
+
+### `session.useClue(clue: Clue)`
+
+Manually applies a specific clue to the board. Useful for interactive search features.
+
+### `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.
+- `getGrid()`: Returns the current `LogicGrid` state.
+- `getSolution()`: Returns the target `Solution` map.
+- `getProofChain()`: Returns the list of `Clue`s applied so far.
+- `getValueMap()`: Returns the optimized internal value categorization map.
+
+### Data Types
+
+#### `CategoryConfig`
+Configuration for a single category.
+```typescript
+interface CategoryConfig {
+  id: string; // e.g. "Suspect"
+  values: string[]; // e.g. ["Mustard", "Plum"...]
+  type: CategoryType; // NOMINAL | ORDINAL
+}
+```
+
+#### `TargetFact`
+Defines the goal of the puzzle (e.g., "Who killed Mr. Boddy?").
+```typescript
+interface TargetFact {
+  category1Id: string;
+  value1: string;
+  category2Id: string;
+}
+```
+
+#### `ClueType`
+Enum for available clue logic: `BINARY` (Direct), `ORDINAL` (Comparison), `CROSS_ORDINAL` (Relative), `SUPERLATIVE` (Min/Max), `UNARY` (Properties).
+
+## Interactive Generation (Builder Mode)
+
+For UIs where you want to watch the puzzle being built (or let the user manually pick the next clue type), use the `GenerativeSession`.
+
+```typescript
+const session = generator.startSession(categories, target);
+let solved = false;
+
+while (!solved) {
+    // 1. Get the next best clue (optionally force a specific type)
+    const result = session.getNextClue({ 
+    // 1. Get the next best clue (optionally force a specific type)
+    const result = session.getNextClue({ 
+        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)
+    });
+    });
+
+    if (result.clue) {
+        console.log("Next Clue:", result.clue);
+        solved = result.solved;
+    } else {
+        console.warn("No more clues available.");
+        break;
+    }
+}
+```
+
+## Error Handling
+
+The library uses specific error types to help you debug configuration issues.
+
+| Method | Throws | Reason |
+| :--- | :--- | :--- |
+| `new Generator()` | `Error` | If `seed` is invalid (NaN). |
+| `generatePuzzle()` | `ConfigurationError` | **Configuration**: <br> - Less than 2 categories. <br> - `maxCandidates` < 1. <br> - `targetClueCount` < 1. <br> **Target Fact**: <br> Refers to non-existent category/value or uses same category twice. <br> **Constraints**: <br> - Ambiguous (Weak) types only. <br> - Requesting `ORDINAL` without Ordinal categories. <br> - Requesting `CROSS_ORDINAL` with < 2 Ordinal categories. <br> - Requesting `UNARY` (Even/Odd) without mixed numeric values. <br> **Data**: <br> - `ORDINAL` category contains non-numeric values. <br> **Runtime**: <br> - Could not find solution with exact `targetClueCount` within timeout. |
+| `startSession()` | `ConfigurationError` | - Less than 2 categories. |
+| `LogicGrid()` | `ConfigurationError` | - Duplicate Category IDs <br> - Duplicate Values within a category <br> - Mismatched value counts (all categories must be same size). |
+
+
+
 
 ## AI Disclosure & Liability Policy
 

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

@@ -15,11 +15,35 @@ export declare class GenerativeSession {
     private solver;
     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;
+    getMatchingClueCount(constraints?: ClueGenerationConstraints): number;
+    getMatchingClues(constraints?: ClueGenerationConstraints, limit?: number): Clue[];
+    getScoredMatchingClues(constraints?: ClueGenerationConstraints, limit?: number): {
+        clue: Clue;
+        score: number;
+        deductions: number;
+        isDirectAnswer: boolean;
+    }[];
+    useClue(clue: Clue): {
+        remaining: number;
+        solved: boolean;
+    };
+    private filterClues;
+    private applyAndSave;
     getNextClue(constraints?: ClueGenerationConstraints): {
         clue: Clue | null;
         remaining: number;
         solved: boolean;
     };
+    /**
+     * Asynchronously gets the next clue (non-blocking wrapper).
+     * @param constraints
+     */
+    getNextClueAsync(constraints?: ClueGenerationConstraints): Promise<{
+        clue: Clue | null;
+        remaining: number;
+        solved: boolean;
+    }>;
     rollbackLastClue(): {
         success: boolean;
         clue: Clue | null;
@@ -29,4 +53,5 @@ export declare class GenerativeSession {
     getProofChain(): Clue[];
     getSolution(): Solution;
     getValueMap(): Map<ValueLabel, Record<string, ValueLabel>>;
+    private extractValuesFromClue;
 }

package/dist/src/engine/GenerativeSession.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GenerativeSession = void 0;
+const types_1 = require("../types");
 const LogicGrid_1 = require("./LogicGrid");
 const Solver_1 = require("./Solver");
 class GenerativeSession {
@@ -21,41 +22,116 @@ class GenerativeSession {
         // We will call a public method on generator.
         this.availableClues = this.generator.generateAllPossibleClues(categories, undefined, reverseSolution, valueMap);
     }
-    getNextClue(constraints) {
-        // Filter available clues based on constraints & current relevance
-        // Use the same heuristic logic as Generator?
-        const validClues = this.availableClues.filter(clue => {
-            // 1. Must not define something already known (Solver.applyClue check basically)
-            // Actually, redundancy check happens in scoring.
+    getTotalClueCount() {
+        return this.availableClues.length;
+    }
+    getMatchingClueCount(constraints) {
+        return this.filterClues(constraints).length;
+    }
+    getMatchingClues(constraints, limit = 50) {
+        const clues = this.filterClues(constraints);
+        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 tempGrid = this.grid.clone();
+            const { deductions } = this.solver.applyClue(tempGrid, clue);
+            // Calculate real score
+            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;
+                    const matchForward = c.cat1 === this.targetFact.category1Id && c.val1 === this.targetFact.value1 && c.cat2 === this.targetFact.category2Id;
+                    const matchReverse = c.cat2 === this.targetFact.category1Id && c.val2 === this.targetFact.value1 && c.cat1 === this.targetFact.category2Id;
+                    if (matchForward || matchReverse) {
+                        isDirectAnswer = true;
+                    }
+                }
+            }
+            return { clue, score, deductions, isDirectAnswer };
+        });
+        // Sort by score descending
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, limit);
+    }
+    useClue(clue) {
+        // 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);
+        return { remaining: this.availableClues.length, solved: this.generator.isPuzzleSolved(this.grid, this.solution, this.reverseSolution) };
+    }
+    filterClues(constraints) {
+        return this.availableClues.filter(clue => {
             // 2. Constraints
             if (constraints?.allowedClueTypes && !constraints.allowedClueTypes.includes(clue.type))
                 return false;
+            // Validation: Check for intersection
+            if (constraints?.includeSubjects && constraints?.excludeSubjects) {
+                const intersection = constraints.includeSubjects.filter(s => constraints.excludeSubjects.includes(s));
+                if (intersection.length > 0) {
+                    throw new Error(`Constraint Error: The following subjects are both included and excluded: ${intersection.join(', ')}`);
+                }
+            }
+            // Subject Constraints
+            if (constraints?.includeSubjects || constraints?.excludeSubjects) {
+                const valuesInClue = this.extractValuesFromClue(clue);
+                if (constraints.includeSubjects) {
+                    const hasMatch = constraints.includeSubjects.some(s => valuesInClue.includes(s));
+                    if (!hasMatch)
+                        return false;
+                }
+                if (constraints.excludeSubjects) {
+                    const hasMatch = constraints.excludeSubjects.some(s => valuesInClue.includes(s));
+                    if (hasMatch)
+                        return false;
+                }
+            }
             return true;
         });
+    }
+    applyAndSave(clue) {
+        // Save state
+        this.historyStack.push(this.grid.clone());
+        // Apply it
+        this.solver.applyClue(this.grid, clue);
+        this.proofChain.push(clue);
+        // Remove from available
+        const idx = this.availableClues.indexOf(clue);
+        if (idx > -1)
+            this.availableClues.splice(idx, 1);
+    }
+    getNextClue(constraints) {
+        const validClues = this.filterClues(constraints);
         // Score them
         let bestClue = null;
         let bestScore = -Infinity;
-        // We should shuffle validClues to limit search space or just search all?
-        // For interactive session, speed is less critical than quality, but we want variety.
-        // Shuffle validClues first.
-        // In-place shuffle copy
+        // Shuffle validClues first to ensure variety.
         const candidates = [...validClues].sort(() => Math.random() - 0.5);
         // Take top N candidates?
         const searchLimit = 50;
         let checked = 0;
+        const minDeductions = constraints?.minDeductions ?? 0;
         for (const clue of candidates) {
             checked++;
             if (checked > searchLimit && bestClue)
                 break; // found something good enough?
-            const score = this.generator.calculateClueScore(this.grid, this.targetFact, 0, clue, this.proofChain, this.solution, this.reverseSolution
-            // Note: we need to actually apply it to get deductions count for scoring to work well
-            );
-            // Wait, publicCalculateScore needs `deductions`.
-            // So we must clone grid and apply.
+            // Score Logic
+            // We must clone grid and apply to see deductions.
             const tempGrid = this.grid.clone();
             const { deductions } = this.solver.applyClue(tempGrid, clue);
-            if (deductions === 0 && !this.isUseful(tempGrid)) {
-                // Useless clue
+            // Check Deduction Floor
+            if (deductions < minDeductions) {
                 continue;
             }
             // Re-calc score with deductions
@@ -66,19 +142,28 @@ class GenerativeSession {
             }
         }
         if (bestClue) {
-            // Save state
-            this.historyStack.push(this.grid.clone());
-            // Apply it
-            this.solver.applyClue(this.grid, bestClue);
-            this.proofChain.push(bestClue);
-            // Remove from available
-            const idx = this.availableClues.indexOf(bestClue);
-            if (idx > -1)
-                this.availableClues.splice(idx, 1);
+            this.applyAndSave(bestClue);
             return { clue: bestClue, remaining: this.availableClues.length, solved: this.generator.isPuzzleSolved(this.grid, this.solution, this.reverseSolution) };
         }
         return { clue: null, remaining: validClues.length, solved: this.generator.isPuzzleSolved(this.grid, this.solution, this.reverseSolution) };
     }
+    /**
+     * Asynchronously gets the next clue (non-blocking wrapper).
+     * @param constraints
+     */
+    async getNextClueAsync(constraints) {
+        return new Promise((resolve, reject) => {
+            setTimeout(() => {
+                try {
+                    const result = this.getNextClue(constraints);
+                    resolve(result);
+                }
+                catch (e) {
+                    reject(e);
+                }
+            }, 0);
+        });
+    }
     rollbackLastClue() {
         if (this.historyStack.length === 0)
             return { success: false, clue: null };
@@ -105,5 +190,24 @@ class GenerativeSession {
     getProofChain() { return this.proofChain; }
     getSolution() { return this.solution; }
     getValueMap() { return this.valueMap; }
+    extractValuesFromClue(clue) {
+        const values = [];
+        // Extract based on type (simpler than full traversal)
+        // We cast values to string for easy comparison
+        const add = (v) => { if (v !== undefined)
+            values.push(String(v)); };
+        // Common fields
+        // @ts-ignore
+        add(clue.val1);
+        // @ts-ignore
+        add(clue.val2);
+        // @ts-ignore
+        add(clue.item1Val);
+        // @ts-ignore
+        add(clue.item2Val);
+        // @ts-ignore
+        add(clue.targetVal);
+        return values;
+    }
 }
 exports.GenerativeSession = GenerativeSession;

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

@@ -96,6 +96,31 @@ export declare class Generator {
      * @param config - Generation options.
      */
     generatePuzzle(categories: CategoryConfig[], target?: TargetFact, config?: GeneratorOptions): Puzzle;
+    /**
+     * Helper to validate a target against categories
+     */
+    private validateTarget;
+    /**
+     * Helper to generate a random target
+     */
+    private generateRandomTarget;
+    /**
+     * Asynchronously generates a puzzle (non-blocking wrapper).
+     * @param categories
+     * @param target
+     * @param config
+     */
+    generatePuzzleAsync(categories: CategoryConfig[], target?: TargetFact, config?: GeneratorOptions): Promise<Puzzle>;
+    /**
+     * Asynchronously estimates clue count bounds (non-blocking wrapper).
+     * @param categories
+     * @param target
+     * @param maxIterations
+     */
+    getClueCountBoundsAsync(categories: CategoryConfig[], target: TargetFact, maxIterations?: number): Promise<{
+        min: number;
+        max: number;
+    }>;
     /**
      * Starts an interactive generative session.
      * @param categories

package/dist/src/engine/Generator.js

@@ -81,41 +81,106 @@ class Generator {
      * @param config - Generation options.
      */
     generatePuzzle(categories, target, config = {}) {
+        // Validation:
+        // 1. Min Categories
+        if (categories.length < 2) {
+            throw new errors_1.ConfigurationError('Puzzle must have at least 2 categories.');
+        }
         const { targetClueCount, maxCandidates = 50, timeoutMs = 10000 } = config;
-        // Validation
-        if (categories.length < 2)
-            throw new errors_1.ConfigurationError("Must have at least 2 categories.");
-        if (targetClueCount !== undefined && targetClueCount < 1)
-            throw new errors_1.ConfigurationError("Target clue count must be at least 1");
-        if (maxCandidates < 1)
-            throw new errors_1.ConfigurationError("maxCandidates must be at least 1");
-        // Synthesize Target if Missing
-        let finalTarget = target;
-        if (!finalTarget) {
-            // Pick Random Target
-            const cat1Idx = Math.floor(this.random() * categories.length);
-            let cat2Idx = Math.floor(this.random() * categories.length);
-            while (cat2Idx === cat1Idx) {
-                cat2Idx = Math.floor(this.random() * categories.length);
+        // 2. Validate Target
+        const finalTarget = target || this.generateRandomTarget(categories);
+        this.validateTarget(categories, finalTarget);
+        // 3. Constraints
+        // Check for impossible requests
+        const constraints = config.constraints;
+        if (constraints?.allowedClueTypes) {
+            const types = constraints.allowedClueTypes;
+            const hasOrdinalCategory = categories.some(c => c.type === types_1.CategoryType.ORDINAL);
+            const requestedOrdinal = types.includes(types_1.ClueType.ORDINAL);
+            const requestedCrossOrdinal = types.includes(types_1.ClueType.CROSS_ORDINAL);
+            if (requestedOrdinal && !hasOrdinalCategory) {
+                // If Binary is allowed, we can fallback to just Binary. 
+                // Only throw if we strictly CANNOT satisfy this without Ordinal categories.
+                if (!types.includes(types_1.ClueType.BINARY)) {
+                    throw new errors_1.ConfigurationError('Invalid Constraints: Ordinal-based clue types were requested, but no Ordinal categories exist. Please add an ordinal category or allow Binary clues.');
+                }
+            }
+            if (requestedCrossOrdinal) {
+                const ordinalCount = categories.filter(c => c.type === types_1.CategoryType.ORDINAL).length;
+                if (ordinalCount < 2) {
+                    throw new errors_1.ConfigurationError('Invalid Constraints: Cross-Ordinal clues require at least 2 Ordinal Categories.');
+                }
             }
-            const c1 = categories[cat1Idx];
-            const c2 = categories[cat2Idx];
-            const valIdx = Math.floor(this.random() * c1.values.length);
-            finalTarget = {
-                category1Id: c1.id,
-                value1: c1.values[valIdx],
-                category2Id: c2.id
-            };
         }
-        // Validate target fact
+        return this.internalGenerate(categories, finalTarget, 'standard', { maxCandidates, targetClueCount, timeoutMs, constraints: config.constraints, onTrace: config.onTrace });
+    }
+    /**
+     * Helper to validate a target against categories
+     */
+    validateTarget(categories, target) {
         const catIds = new Set(categories.map(c => c.id));
-        if (!catIds.has(finalTarget.category1Id) || !catIds.has(finalTarget.category2Id)) {
+        if (!catIds.has(target.category1Id) || !catIds.has(target.category2Id)) {
             throw new errors_1.ConfigurationError('Target fact refers to non-existent categories.');
         }
-        if (finalTarget.category1Id === finalTarget.category2Id) {
+        if (target.category1Id === target.category2Id) {
             throw new errors_1.ConfigurationError('Target fact must refer to two different categories.');
         }
-        return this.internalGenerate(categories, finalTarget, 'standard', { maxCandidates, targetClueCount, timeoutMs, constraints: config.constraints, onTrace: config.onTrace });
+    }
+    /**
+     * Helper to generate a random target
+     */
+    generateRandomTarget(categories) {
+        const cat1Idx = Math.floor(this.random() * categories.length);
+        let cat2Idx = Math.floor(this.random() * categories.length);
+        while (cat2Idx === cat1Idx) {
+            cat2Idx = Math.floor(this.random() * categories.length);
+        }
+        const c1 = categories[cat1Idx];
+        const c2 = categories[cat2Idx];
+        const valIdx = Math.floor(this.random() * c1.values.length);
+        return {
+            category1Id: c1.id,
+            value1: c1.values[valIdx],
+            category2Id: c2.id
+        };
+    }
+    /**
+     * Asynchronously generates a puzzle (non-blocking wrapper).
+     * @param categories
+     * @param target
+     * @param config
+     */
+    async generatePuzzleAsync(categories, target, config = {}) {
+        return new Promise((resolve, reject) => {
+            setTimeout(() => {
+                try {
+                    const result = this.generatePuzzle(categories, target, config);
+                    resolve(result);
+                }
+                catch (e) {
+                    reject(e);
+                }
+            }, 0);
+        });
+    }
+    /**
+     * Asynchronously estimates clue count bounds (non-blocking wrapper).
+     * @param categories
+     * @param target
+     * @param maxIterations
+     */
+    async getClueCountBoundsAsync(categories, target, maxIterations = 10) {
+        return new Promise((resolve, reject) => {
+            setTimeout(() => {
+                try {
+                    const result = this.getClueCountBounds(categories, target, maxIterations);
+                    resolve(result);
+                }
+                catch (e) {
+                    reject(e);
+                }
+            }, 0);
+        });
     }
     /**
      * Starts an interactive generative session.

package/dist/src/types.d.ts

@@ -83,4 +83,18 @@ export interface ClueGenerationConstraints {
      * Use this to control difficulty or puzzle attributes.
      */
     allowedClueTypes?: ClueType[];
+    /**
+     * If provided, only clues that refer to these specific values (as subjects or objects) will be generated.
+     * Useful for "Ask this suspect" mechanics.
+     */
+    includeSubjects?: string[];
+    /**
+     * If provided, clues referring to these values will be excluded.
+     */
+    excludeSubjects?: string[];
+    /**
+     * Minimum number of new deductions this clue must provide to be considered valid.
+     * Default is 0 (allow all clues). Set to 1 to ensure progress.
+     */
+    minDeductions?: number;
 }

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "logic-puzzle-generator",
-  "version": "1.0.0",
+  "version": "1.2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joshhills/logic-puzzle-generator.git"
+  },
   "description": "A headless, TypeScript-based Logic Grid Puzzle Engine.",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",