logic-puzzle-generator 1.0.0 → 1.1.9

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,124 @@ 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 allowed clue types.
+        - `allowedClueTypes`: `ClueType[]` (e.g. `[ClueType.BINARY, ClueType.ORDINAL]`).
+    - `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.
+    - `constraints`: Optional `ClueGenerationConstraints`.
+- `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({ 
+        allowedClueTypes: [ClueType.BINARY, ClueType.ORDINAL] 
+    });
+
+    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 |
+| :--- | :--- | :--- |
+| 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

@@ -20,6 +20,15 @@ export declare class GenerativeSession {
         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;

package/dist/src/engine/GenerativeSession.js

@@ -79,6 +79,23 @@ class GenerativeSession {
         }
         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 };

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/package.json

@@ -1,6 +1,14 @@
 {
   "name": "logic-puzzle-generator",
-  "version": "1.0.0",
+  "version": "1.1.9",
+  "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",

package/dist/Clue.d.ts

@@ -1,81 +0,0 @@
-import { ValueLabel } from './types';
-/**
- * Enumeration of all supported clue types.
- */
-export declare enum ClueType {
-    /** Expresses a direct relationship (IS or IS NOT) between two values. */
-    BINARY = 0,
-    /** Expresses a comparison (GREATER THAN or LESS THAN) between two values based on an ordinal category. */
-    ORDINAL = 1,
-    /** Expresses an extreme value relationship (MIN or MAX) within an ordinal category. */
-    SUPERLATIVE = 2,
-    /** Expresses a property of a single value (e.g., IS EVEN) relative to an ordinal category. */
-    UNARY = 3
-}
-export declare enum BinaryOperator {
-    IS = 0,
-    IS_NOT = 1
-}
-export declare enum OrdinalOperator {
-    GREATER_THAN = 0,
-    LESS_THAN = 1
-}
-export declare enum SuperlativeOperator {
-    MIN = 0,
-    MAX = 1
-}
-export declare enum UnaryFilter {
-    IS_ODD = 0,
-    IS_EVEN = 1
-}
-/**
- * A clue that establishes a direct link or separation between two specific values.
- * Example: "Alice likes Horror movies." (IS)
- * Example: "Bob does not like Comedy." (IS_NOT)
- */
-export interface BinaryClue {
-    type: ClueType.BINARY;
-    operator: BinaryOperator;
-    cat1: string;
-    val1: ValueLabel;
-    cat2: string;
-    val2: ValueLabel;
-}
-/**
- * A clue that compares two entities based on a third ordinal category.
- * Example: "The person who likes Horror is older than Alice."
- */
-export interface OrdinalClue {
-    type: ClueType.ORDINAL;
-    operator: OrdinalOperator;
-    item1Cat: string;
-    item1Val: ValueLabel;
-    item2Cat: string;
-    item2Val: ValueLabel;
-    /** The ordinal category used for comparison (e.g., "Age"). */
-    ordinalCat: string;
-}
-/**
- * A clue that identifies an entity as having an extreme value in an ordinal category.
- * Example: "The person who likes Popcorn is the oldest."
- */
-export interface SuperlativeClue {
-    type: ClueType.SUPERLATIVE;
-    operator: SuperlativeOperator;
-    targetCat: string;
-    targetVal: ValueLabel;
-    /** The ordinal category (e.g., "Age") where the value is extreme. */
-    ordinalCat: string;
-}
-/**
- * A clue that filters a value based on a property of its associated ordinal value.
- * Example: "The person who likes Chips has an even age."
- */
-export interface UnaryClue {
-    type: ClueType.UNARY;
-    filter: UnaryFilter;
-    targetCat: string;
-    targetVal: ValueLabel;
-    ordinalCat: string;
-}
-export type Clue = BinaryClue | OrdinalClue | SuperlativeClue | UnaryClue;

package/dist/Clue.js

@@ -1,37 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnaryFilter = exports.SuperlativeOperator = exports.OrdinalOperator = exports.BinaryOperator = exports.ClueType = void 0;
-/**
- * Enumeration of all supported clue types.
- */
-var ClueType;
-(function (ClueType) {
-    /** Expresses a direct relationship (IS or IS NOT) between two values. */
-    ClueType[ClueType["BINARY"] = 0] = "BINARY";
-    /** Expresses a comparison (GREATER THAN or LESS THAN) between two values based on an ordinal category. */
-    ClueType[ClueType["ORDINAL"] = 1] = "ORDINAL";
-    /** Expresses an extreme value relationship (MIN or MAX) within an ordinal category. */
-    ClueType[ClueType["SUPERLATIVE"] = 2] = "SUPERLATIVE";
-    /** Expresses a property of a single value (e.g., IS EVEN) relative to an ordinal category. */
-    ClueType[ClueType["UNARY"] = 3] = "UNARY";
-})(ClueType || (exports.ClueType = ClueType = {}));
-var BinaryOperator;
-(function (BinaryOperator) {
-    BinaryOperator[BinaryOperator["IS"] = 0] = "IS";
-    BinaryOperator[BinaryOperator["IS_NOT"] = 1] = "IS_NOT";
-})(BinaryOperator || (exports.BinaryOperator = BinaryOperator = {}));
-var OrdinalOperator;
-(function (OrdinalOperator) {
-    OrdinalOperator[OrdinalOperator["GREATER_THAN"] = 0] = "GREATER_THAN";
-    OrdinalOperator[OrdinalOperator["LESS_THAN"] = 1] = "LESS_THAN";
-})(OrdinalOperator || (exports.OrdinalOperator = OrdinalOperator = {}));
-var SuperlativeOperator;
-(function (SuperlativeOperator) {
-    SuperlativeOperator[SuperlativeOperator["MIN"] = 0] = "MIN";
-    SuperlativeOperator[SuperlativeOperator["MAX"] = 1] = "MAX";
-})(SuperlativeOperator || (exports.SuperlativeOperator = SuperlativeOperator = {}));
-var UnaryFilter;
-(function (UnaryFilter) {
-    UnaryFilter[UnaryFilter["IS_ODD"] = 0] = "IS_ODD";
-    UnaryFilter[UnaryFilter["IS_EVEN"] = 1] = "IS_EVEN";
-})(UnaryFilter || (exports.UnaryFilter = UnaryFilter = {}));

package/dist/Generator.d.ts

@@ -1,58 +0,0 @@
-import { CategoryConfig, Solution, TargetFact } from './types';
-import { Clue } from './Clue';
-/**
- * Represents a single step in the logical deduction path.
- */
-export interface ProofStep {
-    /** The clue applied at this step. */
-    clue: Clue;
-    /** The number of logical eliminations that resulted immediately from this clue. */
-    deductions: number;
-}
-/**
- * The complete result of the puzzle generation process.
- */
-export interface Puzzle {
-    /** The solution grid (Category -> Value -> Corresponding Value). */
-    solution: Solution;
-    /** The list of clues needed to solve the puzzle, in no particular order. */
-    clues: Clue[];
-    /** An ordered list of clues that demonstrates a step-by-step logical solution. */
-    proofChain: ProofStep[];
-    /** The configuration used to generate this puzzle. */
-    categories: CategoryConfig[];
-    /** The specific fact that the puzzle is designed to reveal at the end. */
-    targetFact: TargetFact;
-}
-/**
- * The main class responsible for generating logic puzzles.
- *
- * It handles the creation of a consistent solution, the generation of all possible clues,
- * and the selection of an optimal set of clues to form a solvable puzzle with a specific target.
- */
-export declare class Generator {
-    private seed;
-    private random;
-    private solver;
-    private solution;
-    private valueMap;
-    private reverseSolution;
-    /**
-     * Creates a new Generator instance.
-     *
-     * @param seed - A numeric seed for the random number generator to ensure reproducibility.
-     */
-    constructor(seed: number);
-    /**
-     * Generates a fully solvable logic puzzle based on the provided configuration.
-     *
-     * @param categories - The categories and values to include in the puzzle.
-     * @param target - The specific fact that should be the final deduction of the puzzle.
-     * @returns A complete Puzzle object containing the solution, clues, and proof chain.
-     */
-    generatePuzzle(categories: CategoryConfig[], target: TargetFact): Puzzle;
-    private createSolution;
-    private generateAllPossibleClues;
-    private calculateScore;
-    private isPuzzleSolved;
-}