@fgv/ts-sudoku-lib 5.0.1-0 → 5.0.1-2

package/dist/ts-sudoku-lib.d.ts

@@ -1,5 +1,7 @@
 import { Brand } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+import { Logging } from '@fgv/ts-utils';
 import { Result } from '@fgv/ts-utils';
 
 /**
@@ -9,11 +11,99 @@ import { Result } from '@fgv/ts-utils';
 export declare const allPuzzleTypes: PuzzleType[];
 
 /**
- * Static class to instantiate any puzzle from a {@link PuzzleDescription | puzzle description}.
+ * Static class to instantiate any puzzle from a {@link IPuzzleDefinition | puzzle definition}.
  * @internal
  */
 declare class AnyPuzzle {
-    static create(puzzle: IPuzzleDescription): Result<Puzzle>;
+    static create(puzzle: IPuzzleDefinition): Result<Puzzle>;
+}
+
+/**
+ * Abstract base class providing common functionality for hint providers.
+ * @public
+ */
+declare abstract class BaseHintProvider implements IHintProvider {
+    readonly techniqueId: TechniqueId;
+    readonly techniqueName: string;
+    readonly difficulty: DifficultyLevel;
+    readonly priority: number;
+    protected readonly defaultConfidence: ConfidenceLevel;
+    protected constructor(config: IBaseHintProviderConfig);
+    /**
+     * Abstract method to be implemented by concrete providers.
+     * Determines if this provider can potentially generate hints for the given puzzle.
+     */
+    abstract canProvideHints(puzzle: Puzzle, state: PuzzleState): boolean;
+    /**
+     * Abstract method to be implemented by concrete providers.
+     * Generates all possible hints using this technique for the given puzzle.
+     */
+    abstract generateHints(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * Utility method to create a hint with consistent structure.
+     * @param cellActions - The actions to be performed on cells
+     * @param relevantCells - The cells relevant to understanding the hint
+     * @param explanations - The explanations for the hint
+     * @param confidence - The confidence level for this hint
+     * @returns A complete hint object
+     */
+    protected createHint(cellActions: readonly ICellAction[], relevantCells: IRelevantCells, explanations: readonly IHintExplanation[], confidence?: ConfidenceLevel): IHint;
+    /**
+     * Utility method to create cell actions.
+     * @param cellId - The ID of the cell to act upon
+     * @param action - The type of action to perform
+     * @param value - Optional value for set-value actions
+     * @param reason - Optional reason for the action
+     * @returns A cell action object
+     */
+    protected createCellAction(cellId: CellId, action: ICellAction['action'], value?: number, reason?: string): ICellAction;
+    /**
+     * Utility method to create relevant cells grouping.
+     * @param primary - Primary cells that are the focus of the hint
+     * @param secondary - Secondary cells that provide context
+     * @param affected - Cells that will be affected by applying the hint
+     * @returns A relevant cells object
+     */
+    protected createRelevantCells(primary: readonly CellId[], secondary?: readonly CellId[], affected?: readonly CellId[]): IRelevantCells;
+    /**
+     * Utility method to create hint explanations.
+     * @param level - The level of detail for the explanation
+     * @param title - The title of the explanation
+     * @param description - The main description
+     * @param steps - Optional step-by-step instructions
+     * @param tips - Optional tips for understanding the technique
+     * @returns A hint explanation object
+     */
+    protected createExplanation(level: ExplanationLevel, title: string, description: string, steps?: readonly string[], tips?: readonly string[]): IHintExplanation;
+    /**
+     * Filters hints based on generation options.
+     * @param hints - The hints to filter
+     * @param options - The filtering options
+     * @returns Filtered array of hints
+     */
+    protected filterHints(hints: readonly IHint[], options?: IHintGenerationOptions): readonly IHint[];
+    /**
+     * Validates generation options for consistency.
+     * @param options - The options to validate
+     * @returns Result indicating validation success or failure
+     */
+    protected validateOptions(options?: IHintGenerationOptions): Result<void>;
+    /**
+     * Gets all empty cells in the puzzle.
+     * @param puzzle - The puzzle structure
+     * @param state - The puzzle state to analyze
+     * @returns Array of cell IDs that are empty
+     */
+    protected getEmptyCells(puzzle: Puzzle, state: PuzzleState): CellId[];
+    /**
+     * Gets the possible candidate values for a specific cell using cage-based constraints.
+     * This implementation works with any puzzle variant by checking all applicable cages.
+     * @param cellId - The cell to analyze
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Array of possible values for the cell
+     */
+    protected getCandidates(cellId: CellId, puzzle: Puzzle, state: PuzzleState): number[];
 }
 
 /**
@@ -73,6 +163,12 @@ export declare class Cell implements ICellInit, ICell {
     toString(state?: PuzzleState): string;
 }
 
+/**
+ * The type of action that should be taken on a cell as part of a hint.
+ * @public
+ */
+declare type CellAction = 'set-value' | 'eliminate-candidate' | 'add-candidate' | 'highlight';
+
 /**
  * Nominal identifier for a single {@Link ICell | cell} in a {@link PuzzleSession | puzzle}.
  * @public
@@ -85,30 +181,540 @@ export declare type CellId = Brand<string, 'CellId'>;
  */
 declare const cellId: Converter<CellId>;
 
+/**
+ * Confidence level for a generated hint, ranging from 1 (low) to 5 (high).
+ * @public
+ */
+declare type ConfidenceLevel = Brand<1 | 2 | 3 | 4 | 5, 'ConfidenceLevel'>;
+
+/**
+ * Standard confidence levels as branded types.
+ * @public
+ */
+declare const ConfidenceLevels: {
+    readonly LOW: ConfidenceLevel;
+    readonly MEDIUM_LOW: ConfidenceLevel;
+    readonly MEDIUM: ConfidenceLevel;
+    readonly MEDIUM_HIGH: ConfidenceLevel;
+    readonly HIGH: ConfidenceLevel;
+};
+
 declare namespace Converters {
     export {
         cageId,
         cellId,
-        puzzleType,
-        puzzleDescription
+        puzzleType
     }
 }
 export { Converters }
 
 declare namespace Converters_2 {
     export {
-        loadJsonPuzzlesFileSync,
+        loadPuzzlesFile,
+        puzzleFileDimensions,
+        puzzleFileData,
         puzzlesFile
     }
 }
 
-declare namespace File_2 {
+/**
+ * Default hint applicator that converts hints to cell state updates.
+ * @public
+ */
+declare class DefaultHintApplicator implements IHintApplicator {
+    private readonly _log;
+    /**
+     * Creates a new {@link Hints.DefaultHintApplicator | DefaultHintApplicator}.
+     * @param logger - Optional logger for diagnostic output
+     */
+    constructor(logger?: Logging.LogReporter<unknown>);
+    /**
+     * Validates that a hint can be safely applied to the given state.
+     * @param hint - The hint to validate
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Result indicating validation success or failure with details
+     */
+    canApplyHint(hint: IHint, puzzle: Puzzle, state: PuzzleState): Result<void>;
+    /**
+     * Applies a hint to the puzzle state, generating the necessary cell updates.
+     * @param hint - The hint to apply
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Result containing the cell state updates needed to apply the hint
+     */
+    applyHint(hint: IHint, puzzle: Puzzle, state: PuzzleState): Result<readonly ICellState[]>;
+}
+
+/**
+ * Default no-op logger for use when diagnostic logging is not needed.
+ * @public
+ */
+export declare const DefaultSudokuLogger: Logging.LogReporter<unknown>;
+
+/**
+ * Standard difficulty classifications for Sudoku techniques.
+ * @public
+ */
+declare type DifficultyLevel = 'beginner' | 'intermediate' | 'advanced' | 'expert';
+
+/**
+ * Educational content manager for Sudoku solving techniques.
+ * @public
+ */
+declare class EducationalContent {
+    private static readonly _techniqueIntroductions;
+    private static readonly _techniqueRelationships;
+    /**
+     * Gets an introduction to a specific technique.
+     * @param techniqueId - The technique to introduce
+     * @returns Result containing the introduction text
+     */
+    static getTechniqueIntroduction(techniqueId: TechniqueId): Result<string>;
+    /**
+     * Gets relationship information for a technique.
+     * @param techniqueId - The technique to get relationships for
+     * @returns Result containing the relationship information
+     */
+    static getTechniqueRelationships(techniqueId: TechniqueId): Result<readonly string[]>;
+    /**
+     * Gets a complete educational overview for a technique.
+     * @param techniqueId - The technique to describe
+     * @returns Result containing the complete overview
+     */
+    static getTechniqueOverview(techniqueId: TechniqueId): Result<string>;
+    /**
+     * Gets general Sudoku solving advice.
+     * @returns Array of general solving tips
+     */
+    static getGeneralSolvingTips(): readonly string[];
+    /**
+     * Gets difficulty progression advice.
+     * @returns Advice for progressing through difficulty levels
+     */
+    static getDifficultyProgression(): readonly string[];
+    /**
+     * Creates a complete educational guide for beginners.
+     * @returns Comprehensive beginner guide
+     */
+    static createBeginnerGuide(): string;
+}
+
+/**
+ * Utility class for formatting and displaying hint explanations.
+ * @public
+ */
+declare class ExplanationFormatter {
+    /**
+     * Formats a hint explanation as a readable string.
+     * @param explanation - The explanation to format
+     * @param includeSteps - Whether to include step-by-step instructions
+     * @param includeTips - Whether to include tips
+     * @returns Formatted explanation string
+     */
+    static formatExplanation(explanation: IHintExplanation, includeSteps?: boolean, includeTips?: boolean): string;
+    /**
+     * Formats all explanations for a hint as a structured string.
+     * @param explanations - The explanations to format
+     * @returns Formatted explanations string
+     */
+    static formatAllExplanations(explanations: readonly IHintExplanation[]): string;
+    /**
+     * Creates a summary of available explanation levels.
+     * @param explanations - The explanations to summarize
+     * @returns Summary string
+     */
+    static createLevelSummary(explanations: readonly IHintExplanation[]): string;
+}
+
+/**
+ * The level of detail for hint explanations.
+ * @public
+ */
+declare type ExplanationLevel = 'brief' | 'detailed' | 'educational';
+
+/**
+ * Registry for managing hint explanation providers.
+ * @public
+ */
+declare class ExplanationRegistry {
+    private readonly _providers;
+    /**
+     * Creates a new ExplanationRegistry instance.
+     */
+    constructor();
+    /**
+     * Registers a new explanation provider.
+     * @param provider - The provider to register
+     * @returns Result indicating success or failure of registration
+     */
+    registerProvider(provider: IHintExplanationProvider): Result<void>;
+    /**
+     * Gets explanations for a specific hint.
+     * @param hint - The hint to explain
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The puzzle state context
+     * @returns Result containing the explanations
+     */
+    getExplanations(hint: IHint, puzzle: Puzzle, state: PuzzleState): Result<readonly IHintExplanation[]>;
+    /**
+     * Gets a specific explanation at the requested level.
+     * @param hint - The hint to explain
+     * @param level - The desired explanation level
+     * @param state - The puzzle state context
+     * @returns Result containing the explanation at the specified level
+     */
+    getExplanationAtLevel(hint: IHint, level: ExplanationLevel, puzzle: Puzzle, state: PuzzleState): Result<IHintExplanation>;
+}
+
+declare namespace Files {
     export {
         Converters_2 as Converters,
-        Model
+        Model,
+        FileSystem_2 as FileSystem
+    }
+}
+export { Files }
+
+declare namespace FileSystem_2 {
+    export {
+        loadJsonPuzzlesFileSync
     }
 }
-export { File_2 as File }
+
+/**
+ * The minimum and maximum possible values for a {@link ICage | cage}, by cage size in
+ * {@link ICell | cells}.
+ * @public
+ */
+/**
+ * Calculate the minimum and maximum possible totals for a cage of given size
+ * @param cageSize - Number of cells in the cage
+ * @param maxValue - Maximum value allowed in a cell (e.g., 9 for 9x9, 16 for 16x16)
+ * @returns Object with min and max possible totals
+ * @public
+ */
+export declare function getCageTotalBounds(cageSize: number, maxValue: number): {
+    min: number;
+    max: number;
+};
+
+/**
+ * Hint provider for the Hidden Singles technique.
+ *
+ * A Hidden Single occurs when a value can only be placed in one cell within
+ * a row, column, or 3x3 box, even though that cell may have multiple candidates.
+ *
+ * @public
+ */
+declare class HiddenSinglesProvider extends BaseHintProvider {
+    /**
+     * Creates a new HiddenSinglesProvider instance.
+     */
+    constructor();
+    /**
+     * Determines if this provider can potentially generate hints for the given puzzle.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns true if there are empty cells that might have hidden singles
+     */
+    canProvideHints(puzzle: Puzzle, state: PuzzleState): boolean;
+    /**
+     * Generates all hidden single hints for the given puzzle.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing array of hidden single hints
+     */
+    generateHints(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * Finds all hidden singles in the puzzle using cage-based analysis.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Array of hidden single information
+     */
+    private _findAllHiddenSingles;
+    /**
+     * Finds hidden singles in a specific cage using dynamic value analysis.
+     * @param cage - The cage to analyze
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Array of hidden singles in this cage
+     */
+    private _findHiddenSinglesInCage;
+    /**
+     * Gets a display-friendly index for a cage.
+     * @param cage - The cage to get index for
+     * @returns Display index for the cage
+     */
+    private _getCageDisplayIndex;
+    /**
+     * Removes duplicate hidden singles (same cell and value).
+     * @param hiddenSingles - Array of potentially duplicate hidden singles
+     * @returns Array with duplicates removed
+     */
+    private _removeDuplicateHiddenSingles;
+    /**
+     * Creates a hint for a specific hidden single.
+     * @param hiddenSingle - The hidden single information
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns A complete hint for this hidden single
+     */
+    private _createHiddenSingleHint;
+    /**
+     * Gets a human-readable name for a unit.
+     * @param unitType - The type of unit
+     * @param unitIndex - The index of the unit
+     * @returns Human-readable unit name
+     */
+    private _getUnitName;
+    /**
+     * Static factory method to create a new HiddenSinglesProvider.
+     * @returns Result containing the new provider
+     */
+    static create(): Result<HiddenSinglesProvider>;
+}
+
+/**
+ * Implementation of the hint registry that manages and coordinates multiple hint providers.
+ * @public
+ */
+declare class HintRegistry implements IHintRegistry {
+    private readonly _providers;
+    /**
+     * Creates a new HintRegistry instance.
+     */
+    constructor();
+    /**
+     * Creates a new HintRegistry with the specified providers pre-registered.
+     * @param providers - The providers to register
+     * @returns Result containing the new registry or failure if registration fails
+     */
+    static create(providers?: readonly IHintProvider[]): Result<HintRegistry>;
+    /**
+     * Registers a new hint provider.
+     * @param provider - The provider to register
+     * @returns Result indicating success or failure of registration
+     */
+    registerProvider(provider: IHintProvider): Result<void>;
+    /**
+     * Unregisters a hint provider.
+     * @param techniqueId - The ID of the technique to unregister
+     * @returns Result indicating success or failure of unregistration
+     */
+    unregisterProvider(techniqueId: TechniqueId): Result<void>;
+    /**
+     * Gets a specific provider by technique ID.
+     * @param techniqueId - The ID of the technique
+     * @returns Result containing the provider, or failure if not found
+     */
+    getProvider(techniqueId: TechniqueId): Result<IHintProvider>;
+    /**
+     * Gets all registered providers, optionally filtered by criteria.
+     * @param options - Optional filtering options
+     * @returns Array of providers matching the criteria
+     */
+    getProviders(options?: IHintGenerationOptions): readonly IHintProvider[];
+    /**
+     * Generates hints using all applicable providers.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing array of hints from all providers
+     */
+    generateAllHints(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * Gets the best available hint based on difficulty and confidence.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing the best hint, or failure if no hints available
+     */
+    getBestHint(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<IHint>;
+    /**
+     * Gets the number of registered providers.
+     * @returns The number of registered providers
+     */
+    get providerCount(): number;
+    /**
+     * Gets all registered technique IDs.
+     * @returns Array of technique IDs
+     */
+    getRegisteredTechniques(): readonly TechniqueId[];
+    /**
+     * Checks if a specific technique is registered.
+     * @param techniqueId - The technique ID to check
+     * @returns true if the technique is registered
+     */
+    hasProvider(techniqueId: TechniqueId): boolean;
+    /**
+     * Clears all registered providers.
+     * @returns Result indicating success
+     */
+    clear(): Result<void>;
+    /**
+     * Gets providers grouped by difficulty level.
+     * @returns Map of difficulty levels to providers
+     */
+    getProvidersByDifficulty(): Map<DifficultyLevel, readonly IHintProvider[]>;
+    /**
+     * Applies global filtering options to the collected hints.
+     * @param hints - The hints to filter
+     * @param options - The filtering options
+     * @returns Result containing the filtered hints
+     */
+    private _applyGlobalFiltering;
+}
+
+declare namespace Hints {
+    export {
+        TechniqueId,
+        ConfidenceLevel,
+        CellAction,
+        ExplanationLevel,
+        DifficultyLevel,
+        ICellAction,
+        IRelevantCells,
+        IHintExplanation,
+        IHint,
+        IHintGenerationOptions,
+        TechniqueIds,
+        ConfidenceLevels,
+        IHintProvider,
+        IHintRegistry,
+        IHintExplanationProvider,
+        IHintApplicator,
+        IBaseHintProviderConfig,
+        BaseHintProvider,
+        HintRegistry,
+        NakedSinglesProvider,
+        HiddenSinglesProvider,
+        ExplanationRegistry,
+        ExplanationFormatter,
+        EducationalContent,
+        IHintSystemConfig,
+        DefaultHintApplicator,
+        HintSystem,
+        IPuzzleSessionHintsConfig,
+        PuzzleSessionHints
+    }
+}
+export { Hints }
+
+/**
+ * Main hint system that provides comprehensive hint generation and management.
+ * @public
+ */
+declare class HintSystem {
+    private readonly _registry;
+    private readonly _applicator;
+    private readonly _config;
+    private readonly _log;
+    private readonly _logHints;
+    /**
+     * Creates a new HintSystem instance.
+     * @param registry - The hint registry to use
+     * @param applicator - The hint applicator to use
+     * @param config - Configuration options
+     */
+    constructor(registry: IHintRegistry, applicator: IHintApplicator, config: IHintSystemConfig);
+    /**
+     * Creates a new HintSystem with default providers and configuration.
+     * @param config - Optional configuration options
+     * @returns Result containing the new hint system
+     */
+    static create(config?: IHintSystemConfig): Result<HintSystem>;
+    /**
+     * Gets the hint registry.
+     * @returns The hint registry
+     */
+    get registry(): IHintRegistry;
+    /**
+     * Gets the hint applicator.
+     * @returns The hint applicator
+     */
+    get applicator(): IHintApplicator;
+    /**
+     * Gets the system configuration.
+     * @returns The configuration
+     */
+    get config(): IHintSystemConfig;
+    /**
+     * Generates all available hints for the current puzzle state.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing array of hints
+     */
+    generateHints(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * Gets the best available hint for the current puzzle state.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing the best hint
+     */
+    getBestHint(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<IHint>;
+    /**
+     * Applies a hint to generate cell state updates.
+     * @param hint - The hint to apply
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Result containing the cell updates
+     */
+    applyHint(hint: IHint, puzzle: Puzzle, state: PuzzleState): Result<readonly ICellState[]>;
+    /**
+     * Validates that a hint can be applied to the current state.
+     * @param hint - The hint to validate
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Result indicating validation success or failure
+     */
+    validateHint(hint: IHint, puzzle: Puzzle, state: PuzzleState): Result<void>;
+    /**
+     * Formats a hint explanation for display.
+     * @param hint - The hint to format
+     * @param level - The explanation level to use (defaults to config default)
+     * @returns Formatted explanation string
+     */
+    formatHintExplanation(hint: IHint, level?: ExplanationLevel): string;
+    /**
+     * Gets a summary of the hint system capabilities.
+     * @returns System capabilities summary
+     */
+    getSystemSummary(): string;
+    /**
+     * Checks if the puzzle state has any available hints.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Result containing boolean indicating if hints are available
+     */
+    hasHints(puzzle: Puzzle, state: PuzzleState): Result<boolean>;
+    /**
+     * Gets statistics about available hints for the current state.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Result containing hint statistics
+     */
+    getHintStatistics(puzzle: Puzzle, state: PuzzleState): Result<{
+        totalHints: number;
+        hintsByTechnique: Map<string, number>;
+        hintsByDifficulty: Map<string, number>;
+    }>;
+}
+
+/**
+ * Configuration for a {@link Hints.BaseHintProvider | BaseHintProvider} instance.
+ * @public
+ */
+declare interface IBaseHintProviderConfig {
+    readonly techniqueId: TechniqueId;
+    readonly techniqueName: string;
+    readonly difficulty: DifficultyLevel;
+    readonly priority: number;
+    readonly defaultConfidence?: ConfidenceLevel;
+}
 
 /**
  * Describes the structure of a single cage in a {@link PuzzleSession | puzzle}.
@@ -175,6 +781,17 @@ export declare interface ICell {
     readonly immutableValue?: number;
 }
 
+/**
+ * Describes an action to be taken on a specific cell as part of a hint.
+ * @public
+ */
+declare interface ICellAction {
+    readonly cellId: CellId;
+    readonly action: CellAction;
+    readonly value?: number;
+    readonly reason?: string;
+}
+
 /**
  * The contents of a single {@Link ICell | cell} in a {@link PuzzleSession | puzzle}.
  * @public
@@ -210,7 +827,8 @@ export declare interface ICellState extends ICellContents {
 }
 
 /**
- * @internal
+ * Describes a single cell update.
+ * @public
  */
 export declare interface ICellUpdate {
     from: ICellState;
@@ -225,22 +843,263 @@ export declare class Ids {
     static cellId(spec: string | IRowColumn | ICell): Result<CellId>;
     static rowCageId(row: number): CageId;
     static columnCageId(col: number): CageId;
-    static sectionCageId(row: number, col: number): CageId;
+    static sectionCageId(row: number, col: number, cageHeight?: number, cageWidth?: number): CageId;
     static cellIds(firstRow: number, numRows: number, firstCol: number, numCols: number): Result<CellId[]>;
 }
 
 /**
- * Description of a single puzzle.
+ * A complete hint with all necessary information for display and application.
+ * @public
+ */
+declare interface IHint {
+    readonly techniqueId: TechniqueId;
+    readonly techniqueName: string;
+    readonly difficulty: DifficultyLevel;
+    readonly confidence: ConfidenceLevel;
+    readonly cellActions: readonly ICellAction[];
+    readonly relevantCells: IRelevantCells;
+    readonly explanations: readonly IHintExplanation[];
+    readonly priority: number;
+}
+
+/**
+ * Interface for hint application and validation.
+ * @public
+ */
+declare interface IHintApplicator {
+    /**
+     * Validates that a hint can be safely applied to the given state.
+     * @param hint - The hint to validate
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Result indicating validation success or failure with details
+     */
+    canApplyHint(hint: IHint, puzzle: Puzzle, state: PuzzleState): Result<void>;
+    /**
+     * Applies a hint to the puzzle state, generating the necessary cell updates.
+     * @param hint - The hint to apply
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns Result containing the cell state updates needed to apply the hint
+     */
+    applyHint(hint: IHint, puzzle: Puzzle, state: PuzzleState): Result<readonly ICellState[]>;
+}
+
+/**
+ * A hint explanation at a specific level of detail.
+ * @public
+ */
+declare interface IHintExplanation {
+    readonly level: ExplanationLevel;
+    readonly title: string;
+    readonly description: string;
+    readonly steps?: readonly string[];
+    readonly tips?: readonly string[];
+}
+
+/**
+ * Interface for hint explanation generation and formatting.
+ * @public
+ */
+declare interface IHintExplanationProvider {
+    /**
+     * Gets the technique ID this explanation provider supports.
+     */
+    readonly techniqueId: TechniqueId;
+    /**
+     * Generates explanations for a specific hint.
+     * @param hint - The hint to explain
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The puzzle state context
+     * @returns Result containing array of explanations at different levels
+     */
+    generateExplanations(hint: IHint, puzzle: Puzzle, state: PuzzleState): Result<readonly IHintExplanation[]>;
+}
+
+/**
+ * Configuration options for hint generation.
+ * @public
+ */
+declare interface IHintGenerationOptions {
+    readonly maxHints?: number;
+    readonly minConfidence?: ConfidenceLevel;
+    readonly preferredDifficulty?: DifficultyLevel;
+    readonly enabledTechniques?: readonly TechniqueId[];
+    readonly explanationLevel?: ExplanationLevel;
+}
+
+/**
+ * Interface for classes that can provide hints using a specific solving technique.
+ * @public
+ */
+declare interface IHintProvider {
+    readonly techniqueId: TechniqueId;
+    readonly techniqueName: string;
+    readonly difficulty: DifficultyLevel;
+    readonly priority: number;
+    /**
+     * Determines if this provider can potentially generate hints for the given puzzle.
+     * This should be a fast check to avoid expensive hint generation when not applicable.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns true if this provider might be able to generate hints
+     */
+    canProvideHints(puzzle: Puzzle, state: PuzzleState): boolean;
+    /**
+     * Generates all possible hints using this technique for the given puzzle.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing array of hints, or failure if generation fails
+     */
+    generateHints(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+}
+
+/**
+ * Interface for managing and coordinating multiple hint providers.
+ * @public
+ */
+declare interface IHintRegistry {
+    /**
+     * Registers a new hint provider.
+     * @param provider - The provider to register
+     * @returns Result indicating success or failure of registration
+     */
+    registerProvider(provider: IHintProvider): Result<void>;
+    /**
+     * Unregisters a hint provider.
+     * @param techniqueId - The ID of the technique to unregister
+     * @returns Result indicating success or failure of unregistration
+     */
+    unregisterProvider(techniqueId: TechniqueId): Result<void>;
+    /**
+     * Gets a specific provider by technique ID.
+     * @param techniqueId - The ID of the technique
+     * @returns Result containing the provider, or failure if not found
+     */
+    getProvider(techniqueId: TechniqueId): Result<IHintProvider>;
+    /**
+     * Gets all registered providers, optionally filtered by criteria.
+     * @param options - Optional filtering options
+     * @returns Array of providers matching the criteria
+     */
+    getProviders(options?: IHintGenerationOptions): readonly IHintProvider[];
+    /**
+     * Generates hints using all applicable providers.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing array of hints from all providers
+     */
+    generateAllHints(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * Gets the best available hint based on difficulty and confidence.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing the best hint, or failure if no hints available
+     */
+    getBestHint(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<IHint>;
+    /**
+     * Gets all registered technique IDs.
+     * @returns Array of technique IDs
+     */
+    getRegisteredTechniques(): readonly TechniqueId[];
+}
+
+/**
+ * Configuration options for the hint system.
+ * @public
+ */
+declare interface IHintSystemConfig {
+    readonly enableNakedSingles?: boolean;
+    readonly enableHiddenSingles?: boolean;
+    readonly defaultExplanationLevel?: ExplanationLevel;
+    readonly logger?: Logging.LogReporter<unknown>;
+}
+
+/**
+ * Constraints that can be applied when generating killer cage combinations.
+ * @public
+ */
+declare interface IKillerConstraints {
+    /**
+     * Numbers that cannot be present in the combination.
+     * Must be unique values between 1-9.
+     */
+    readonly excludedNumbers?: readonly number[];
+    /**
+     * Numbers that must be present in the combination.
+     * Must be unique values between 1-9.
+     */
+    readonly requiredNumbers?: readonly number[];
+}
+
+/**
+ * Complete puzzle definition with derived properties
+ * @public
+ */
+export declare interface IPuzzleDefinition extends IPuzzleDimensions {
+    readonly id?: string;
+    readonly description: string;
+    readonly type: PuzzleType;
+    readonly level: number;
+    readonly cells: string;
+    readonly totalRows: number;
+    readonly totalColumns: number;
+    readonly maxValue: number;
+    readonly totalCages: number;
+    readonly basicCageTotal: number;
+    readonly cages?: ICage[];
+}
+
+/**
+ * Core dimensional configuration for a puzzle grid
+ * @public
+ */
+export declare interface IPuzzleDimensions {
+    /** Width of each section/cage (e.g., 3 for standard Sudoku) */
+    readonly cageWidthInCells: number;
+    /** Height of each section/cage (e.g., 3 for standard Sudoku) */
+    readonly cageHeightInCells: number;
+    /** Number of cages horizontally (e.g., 3 for standard Sudoku) */
+    readonly boardWidthInCages: number;
+    /** Number of cages vertically (e.g., 3 for standard Sudoku) */
+    readonly boardHeightInCages: number;
+}
+
+/**
+ * Input format for puzzle data in JSON files.
+ * Contains only the essential data needed to create an IPuzzleDefinition.
  * @public
  */
-export declare interface IPuzzleDescription {
+declare interface IPuzzleFileData {
     id?: string;
     description: string;
     type: PuzzleType;
     level: number;
-    rows: number;
-    cols: number;
     cells: string;
+    dimensions: IPuzzleFileDimensions;
+}
+
+/**
+ * Dimensional configuration for puzzles
+ * @public
+ */
+declare interface IPuzzleFileDimensions {
+    cageWidthInCells: number;
+    cageHeightInCells: number;
+    boardWidthInCages: number;
+    boardHeightInCages: number;
+}
+
+/**
+ * Configuration options for the PuzzleSessionHints integration.
+ * @public
+ */
+declare interface IPuzzleSessionHintsConfig extends IHintSystemConfig {
+    readonly cacheTimeoutMs?: number;
+    readonly maxCacheEntries?: number;
 }
 
 /**
@@ -248,7 +1107,7 @@ export declare interface IPuzzleDescription {
  * @public
  */
 declare interface IPuzzlesFile {
-    puzzles: IPuzzleDescription[];
+    puzzles: IPuzzleFileData[];
 }
 
 declare interface IPuzzleStep {
@@ -256,7 +1115,19 @@ declare interface IPuzzleStep {
 }
 
 /**
- * @internal
+ * Interface for puzzle type-specific validation
+ * @public
+ */
+export declare interface IPuzzleTypeValidator {
+    /**
+     * Validate the cells string for this puzzle type
+     */
+    validateCells(cells: string, dimensions: IPuzzleDimensions): Result<true>;
+}
+
+/**
+ * Describes a single puzzle update.
+ * @public
  */
 export declare interface IPuzzleUpdate {
     from: PuzzleState;
@@ -264,6 +1135,16 @@ export declare interface IPuzzleUpdate {
     cells: ICellUpdate[];
 }
 
+/**
+ * Information about the cells that are relevant to understanding a hint.
+ * @public
+ */
+declare interface IRelevantCells {
+    readonly primary: readonly CellId[];
+    readonly secondary: readonly CellId[];
+    readonly affected: readonly CellId[];
+}
+
 /**
  * The row/column coordinate of a single {@Link ICell | cell} in a {@link PuzzleSession | puzzle}.
  * @public
@@ -273,12 +1154,99 @@ export declare interface IRowColumn {
     col: number;
 }
 
+/**
+ * Helper class providing UI assistance functions for killer sudoku puzzle solving.
+ * Generates possible totals, number combinations with constraints, and cell-specific
+ * possibilities based on current puzzle state.
+ * @public
+ */
+declare class KillerCombinations {
+    /**
+     * Gets all mathematically possible totals for a given cage size.
+     *
+     * Uses the existing totalsByCageSize constant to determine the valid range
+     * of totals for the specified cage size and returns all integers in that range.
+     *
+     * @param cageSize - The number of cells in the cage (must be 1-9)
+     * @returns Result containing array of possible totals in ascending order
+     *
+     * @example
+     * ```typescript
+     * // Get possible totals for a 3-cell cage
+     * const result = KillerCombinations.getPossibleTotals(3);
+     * if (result.isSuccess()) {
+     *   console.log(result.value); // [6, 7, 8, 9, ..., 24]
+     * }
+     * ```
+     */
+    static getPossibleTotals(cageSize: number, maxValue?: number): Result<number[]>;
+    /**
+     * Generates all possible number combinations that sum to the target total.
+     *
+     * Each combination contains unique numbers from 1-9 that sum exactly to the
+     * specified total. Combinations respect both excluded and required number
+     * constraints if provided.
+     *
+     * @param cageSize - The number of cells in the cage (must be 1-9)
+     * @param total - The target sum (must be valid for the cage size)
+     * @param constraints - Optional constraints on included/excluded numbers
+     * @returns Result containing array of combinations, each sorted in ascending order
+     *
+     * @example
+     * ```typescript
+     * // Get all combinations for a 3-cell cage with total 15
+     * const result = KillerCombinations.getCombinations(3, 15);
+     * if (result.isSuccess()) {
+     *   console.log(result.value); // [[1,5,9], [1,6,8], [2,4,9], ...]
+     * }
+     *
+     * // With constraints - exclude 1 and 2, require 9
+     * const constrained = KillerCombinations.getCombinations(3, 15, {
+     *   excludedNumbers: [1, 2],
+     *   requiredNumbers: [9]
+     * });
+     * ```
+     */
+    static getCombinations(cageSize: number, total: number, constraints?: IKillerConstraints, maxValue?: number): Result<number[][]>;
+    /**
+     * Determines possible values for each cell in a killer cage based on current puzzle state.
+     *
+     * Analyzes the current state of the puzzle and cage to determine which values
+     * are possible for each empty cell, considering both killer cage constraints
+     * and standard sudoku constraints (row, column, section uniqueness).
+     *
+     * @param puzzle - The puzzle instance
+     * @param state - Current puzzle state
+     * @param cage - The killer cage to analyze (must be of type 'killer')
+     * @returns Result containing map of CellId to possible number arrays
+     *
+     * @example
+     * ```typescript
+     * const cage = puzzle.getCage(cageId).orThrow();
+     * const possibilities = KillerCombinations.getCellPossibilities(puzzle, state, cage);
+     * if (possibilities.isSuccess()) {
+     *   for (const [cellId, values] of possibilities.value) {
+     *     console.log(`Cell ${cellId} can have values: ${values.join(', ')}`);
+     *   }
+     * }
+     * ```
+     */
+    static getCellPossibilities(puzzle: Puzzle, state: PuzzleState, cage: ICage): Result<Map<CellId, number[]>>;
+    /**
+     * Validate constraint parameters.
+     * @param constraints - Constraints to validate
+     * @param maxValue - Maximum value allowed in cells
+     * @returns Result indicating success or failure with error message
+     */
+    private static _validateConstraints;
+}
+
 /**
  * @public
  */
 declare class KillerSudokuPuzzle extends Puzzle {
     private constructor();
-    static create(desc: IPuzzleDescription): Result<Puzzle>;
+    static create(desc: IPuzzleDefinition): Result<Puzzle>;
     private static _getKillerCages;
     private static _getCageCells;
     private static _getCages;
@@ -287,7 +1255,7 @@ declare class KillerSudokuPuzzle extends Puzzle {
 
 /**
  * Loads an arbitrary JSON file and parses it to return a validated
- * {@link File.Model.IPuzzlesFile | IPuzzlesFile}.
+ * {@link Files.Model.IPuzzlesFile | IPuzzlesFile}.
  * @param path - String path to the file
  * @returns `Success` with the resulting file, or `Failure` with details if an
  * error occurs.
@@ -295,12 +1263,76 @@ declare class KillerSudokuPuzzle extends Puzzle {
  */
 declare function loadJsonPuzzlesFileSync(path: string): Result<IPuzzlesFile>;
 
+/**
+ * Loads a puzzles file from a `IFileTreeFileItem`.
+ * @param file - The `IFileTreeFileItem` to load.
+ * @returns `Success` with the resulting {@link Files.Model.IPuzzlesFile | IPuzzlesFile}, or `Failure` with
+ * details if an error occurs.
+ * @public
+ */
+declare function loadPuzzlesFile(file: FileTree.IFileTreeFileItem): Result<IPuzzlesFile>;
+
 declare namespace Model {
     export {
+        IPuzzleFileDimensions,
+        IPuzzleFileData,
         IPuzzlesFile
     }
 }
 
+/**
+ * Hint provider for the Naked Singles technique.
+ *
+ * A Naked Single occurs when a cell has only one possible candidate value
+ * based on the constraints of its row, column, and 3x3 box.
+ *
+ * @public
+ */
+declare class NakedSinglesProvider extends BaseHintProvider {
+    /**
+     * Creates a new NakedSinglesProvider instance.
+     */
+    constructor();
+    /**
+     * Determines if this provider can potentially generate hints for the given puzzle.
+     * Always returns true since naked singles can potentially exist in any incomplete puzzle.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @returns true if there are empty cells that might have naked singles
+     */
+    canProvideHints(puzzle: Puzzle, state: PuzzleState): boolean;
+    /**
+     * Generates all naked single hints for the given puzzle.
+     * @param puzzle - The puzzle structure containing constraints
+     * @param state - The current puzzle state
+     * @param options - Optional generation options
+     * @returns Result containing array of naked single hints
+     */
+    generateHints(puzzle: Puzzle, state: PuzzleState, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * Creates a hint for a specific naked single.
+     * @param cellId - The cell containing the naked single
+     * @param value - The single possible value for the cell
+     * @param state - The current puzzle state
+     * @returns A complete hint for this naked single
+     */
+    private _createNakedSingleHint;
+    /**
+     * Finds cells in the same row, column, and box that constrain the given cell.
+     * @param cellId - The cell to analyze
+     * @param value - The value that will be placed
+     * @param state - The current puzzle state
+     * @param puzzle - The puzzle for dimensions
+     * @returns Array of cell IDs that are related to this naked single
+     */
+    private _findRelatedCells;
+    /**
+     * Static factory method to create a new NakedSinglesProvider.
+     * @returns Result containing the new provider
+     */
+    static create(): Result<NakedSinglesProvider>;
+}
+
 /**
  * Navigation direction within a puzzle.
  * @public
@@ -315,38 +1347,49 @@ export declare type NavigationDirection = 'down' | 'left' | 'right' | 'up';
 export declare type NavigationWrap = 'none' | 'wrap-around' | 'wrap-next';
 
 /**
- * @internal
+ * Parse a cell ID string back to row/column coordinates
+ * @param cellId - Cell ID string (e.g., "A1", "A01", "AB15")
+ * @returns Row and column indices (0-based) or undefined if invalid
+ * @public
+ */
+export declare function parseCellId(cellId: string): IRowColumn | undefined;
+
+/**
+ * Abstract base class for all puzzles.
+ * @public
  */
 export declare class Puzzle {
     readonly id?: string;
     readonly description: string;
+    readonly type: string;
     readonly initialState: PuzzleState;
+    readonly dimensions: IPuzzleDefinition;
     /**
-     * @internal
+     * @public
      */
     protected readonly _rows: Map<CageId, Cage>;
     /**
-     * @internal
+     * @public
      */
     protected readonly _columns: Map<CageId, Cage>;
     /**
-     * @internal
+     * @public
      */
     protected readonly _sections: Map<CageId, Cage>;
     /**
-     * @internal
+     * @public
      */
     protected readonly _cages: Map<CageId, Cage>;
     /**
-     * @internal
+     * @public
      */
     protected readonly _cells: Map<CellId, Cell>;
     /**
      * Constructs a new puzzle state.
-     * @param puzzle - {@Link IPuzzleDescription | Puzzle description} from which this puzzle state
+     * @param puzzle - {@Link IPuzzleDefinition | Puzzle definition} from which this puzzle state
      * is to be initialized.
      */
-    protected constructor(puzzle: IPuzzleDescription, extraCages?: [CageId, Cage][]);
+    protected constructor(puzzle: IPuzzleDefinition, extraCages?: [CageId, Cage][]);
     get numRows(): number;
     get numColumns(): number;
     get rows(): Cage[];
@@ -357,11 +1400,16 @@ export declare class Puzzle {
     /**
      * @internal
      */
-    protected static _createRowCages(numRows: number, numCols: number): Result<[CageId, Cage][]>;
+    protected static _createRowCages(numRows: number, numCols: number, basicCageTotal: number): Result<[CageId, Cage][]>;
+    /**
+     * @internal
+     */
+    protected static _createColumnCages(numRows: number, numCols: number, basicCageTotal: number): Result<[CageId, Cage][]>;
     /**
+     * Parse alphanumeric cell value (1-9, A-Z for values 10-35)
      * @internal
      */
-    protected static _createColumnCages(numRows: number, numCols: number): Result<[CageId, Cage][]>;
+    private _parseAlphanumericValue;
     /**
      * @internal
      */
@@ -399,23 +1447,23 @@ export declare class PuzzleCollection {
     /**
      * All puzzles in the collection.
      */
-    readonly puzzles: readonly IPuzzleDescription[];
+    readonly puzzles: readonly Files.Model.IPuzzleFileData[];
     private readonly _byId;
     private constructor();
     /**
-     * Creates a new puzzle from a loaded {@link File.Model.IPuzzlesFile | PuzzlesFile}
-     * @param from - The {@link File.Model.IPuzzlesFile | puzzles file} to be loaded.
+     * Creates a new puzzle from a loaded {@link Files.Model.IPuzzlesFile | PuzzlesFile}
+     * @param from - The {@link Files.Model.IPuzzlesFile | puzzles file} to be loaded.
      * @returns `Success` with the resulting {@link PuzzleCollection | PuzzleCollection}
      * or `Failure` with details if an error occurs.
      */
-    static create(from: File_2.Model.IPuzzlesFile): Result<PuzzleCollection>;
+    static create(from: Files.Model.IPuzzlesFile): Result<PuzzleCollection>;
     /**
      * Creates a new puzzle from a JSON file.
      * @param path - path to the JSON file to be loaded.
      * @returns `Success` with the resulting {@link PuzzleCollection | PuzzleCollection}
      * or `Failure` with details if an error occurs.
      */
-    static load(path: string): Result<PuzzleCollection>;
+    static load(file: FileTree.IFileTreeFileItem): Result<PuzzleCollection>;
     /**
      * Gets a puzzle by id from this collection.
      * @param id - The string ID of the puzzle to be returned.
@@ -423,13 +1471,19 @@ export declare class PuzzleCollection {
      * `Failure` with details if an error occurs.
      */
     getPuzzle(id: string): Result<PuzzleSession>;
+    /**
+     * Converts IPuzzleFileData to IPuzzleDefinition format.
+     * @param fileData - The puzzle file data to convert
+     * @returns Result containing the puzzle definition
+     */
+    private _convertToDefinition;
     /**
      * Gets a puzzle by id from this collection.
      * @param id - The string ID of the puzzle to be returned.
      * @returns `Success` with the requested {@link PuzzleSession | puzzle}, or
      * `Failure` with details if an error occurs.
      */
-    getDescription(id: string): Result<IPuzzleDescription>;
+    getDescription(id: string): Result<Files.Model.IPuzzleFileData>;
 }
 
 /**
@@ -445,17 +1499,73 @@ export declare class PuzzleCollections {
 }
 
 /**
- * Converts an arbitrary object to a {@link IPuzzleDescription | IPuzzleDescription}.
+ * Factory for creating and validating puzzle definitions
+ * @public
+ */
+export declare class PuzzleDefinitionFactory {
+    /**
+     * Create a puzzle definition from dimensions and options
+     */
+    static create(dimensions: IPuzzleDimensions, options?: Partial<IPuzzleDefinition>): Result<IPuzzleDefinition>;
+    /**
+     * Create killer sudoku puzzle definition with cage constraints
+     */
+    static createKiller(dimensions: IPuzzleDimensions, description: Omit<IPuzzleDefinition, 'cageWidthInCells' | 'cageHeightInCells' | 'boardWidthInCages' | 'boardHeightInCages' | 'totalRows' | 'totalColumns' | 'maxValue' | 'totalCages' | 'basicCageTotal' | 'cages'> & {
+        killerCages: Array<{
+            id: string;
+            cellPositions: Array<{
+                row: number;
+                col: number;
+            }>;
+            sum: number;
+        }>;
+    }): Result<IPuzzleDefinition>;
+    /**
+     * Validate puzzle dimensions
+     */
+    static validate(dimensions: IPuzzleDimensions): Result<true>;
+    /**
+     * Get a standard configuration by name
+     */
+    static getStandardConfig(name: StandardConfigName): IPuzzleDimensions;
+    /**
+     * Get all available standard configurations
+     */
+    static getStandardConfigs(): Record<StandardConfigName, IPuzzleDimensions>;
+    /**
+     * Get validator for a specific puzzle type
+     */
+    static getValidator(puzzleType: PuzzleType): IPuzzleTypeValidator | undefined;
+    /**
+     * Register a custom validator for a puzzle type
+     */
+    static registerValidator(puzzleType: PuzzleType, validator: IPuzzleTypeValidator): void;
+    /**
+     * Calculate the basic cage total (sum of 1 to maxValue)
+     */
+    private static _calculateBasicCageTotal;
+}
+
+/**
+ * Converts puzzle file data from JSON format
+ * @public
+ */
+declare const puzzleFileData: Converter<IPuzzleFileData>;
+
+/**
+ * Converts puzzle file dimensions from JSON format
  * @public
  */
-declare const puzzleDescription: Converter<IPuzzleDescription>;
+declare const puzzleFileDimensions: Converter<IPuzzleFileDimensions>;
 
 declare namespace Puzzles {
     export {
         AnyPuzzle as Any,
         KillerSudokuPuzzle as Killer,
+        KillerCombinations,
         SudokuPuzzle as Sudoku,
-        SudokuXPuzzle as SudokuX
+        SudokuXPuzzle as SudokuX,
+        IKillerConstraints
     }
 }
 export { Puzzles }
@@ -485,6 +1595,10 @@ export declare class PuzzleSession {
      * Description of the puzzle being solved.
      */
     get description(): string;
+    /**
+     * Type of the puzzle being solved.
+     */
+    get type(): string;
     /**
      * Number of rows in the puzzle being solved.
      */
@@ -513,6 +1627,10 @@ export declare class PuzzleSession {
      * The cells {@link ICell | cells} in the puzzle being solved.
      */
     get cells(): ICell[];
+    /**
+     * The puzzle structure for this session.
+     */
+    get puzzle(): Puzzle;
     /**
      * Index of the next step in this puzzle session.
      */
@@ -666,7 +1784,301 @@ export declare class PuzzleSession {
 }
 
 /**
- * Converts an arbitrary object to a {@link File.Model.IPuzzlesFile | IPuzzlesFile}.
+ * Wrapper class that integrates hint functionality with PuzzleSession.
+ * Provides hint generation, application, and explanation capabilities while
+ * maintaining integration with existing state management and undo/redo functionality.
+ * @public
+ */
+declare class PuzzleSessionHints {
+    private readonly _session;
+    private readonly _hintSystem;
+    private readonly _config;
+    private _hintCache;
+    /**
+     * @internal
+     */
+    private constructor();
+    /**
+     * Creates a new PuzzleSessionHints wrapper for an existing PuzzleSession.
+     * @param session - The PuzzleSession to wrap
+     * @param config - Optional configuration for the hint system
+     * @returns Result containing the new PuzzleSessionHints wrapper
+     */
+    static create(session: PuzzleSession, config?: IPuzzleSessionHintsConfig): Result<PuzzleSessionHints>;
+    /**
+     * Gets the wrapped PuzzleSession instance.
+     * @returns The underlying PuzzleSession
+     */
+    get session(): PuzzleSession;
+    /**
+     * Gets the HintSystem instance.
+     * @returns The hint system
+     */
+    get hintSystem(): HintSystem;
+    /**
+     * Gets the configuration.
+     * @returns The configuration
+     */
+    get config(): IPuzzleSessionHintsConfig;
+    /**
+     * Gets the puzzle ID.
+     * @returns The puzzle ID
+     */
+    get id(): string | undefined;
+    /**
+     * Gets the puzzle description.
+     * @returns The puzzle description
+     */
+    get description(): string;
+    /**
+     * Gets the number of rows in the puzzle.
+     * @returns The number of rows
+     */
+    get numRows(): number;
+    /**
+     * Gets the number of columns in the puzzle.
+     * @returns The number of columns
+     */
+    get numColumns(): number;
+    /**
+     * Gets the current puzzle state.
+     * @returns The current state
+     */
+    get state(): PuzzleState;
+    /**
+     * Gets whether undo is possible.
+     * @returns true if undo is possible
+     */
+    get canUndo(): boolean;
+    /**
+     * Gets whether redo is possible.
+     * @returns true if redo is possible
+     */
+    get canRedo(): boolean;
+    /**
+     * Checks if the puzzle is solved.
+     * @returns true if the puzzle is solved
+     */
+    checkIsSolved(): boolean;
+    /**
+     * Checks if the puzzle is valid.
+     * @returns true if the puzzle is valid
+     */
+    checkIsValid(): boolean;
+    /**
+     * Updates a cell value.
+     * @param spec - Cell specification
+     * @param value - New value
+     * @returns Result with this instance
+     */
+    updateCellValue(spec: string | IRowColumn | ICell, value: number | undefined): Result<this>;
+    /**
+     * Updates cell notes.
+     * @param spec - Cell specification
+     * @param notes - New notes
+     * @returns Result with this instance
+     */
+    updateCellNotes(spec: string | IRowColumn | ICell, notes: number[]): Result<this>;
+    /**
+     * Updates multiple cells.
+     * @param updates - Array of cell updates
+     * @returns Result with this instance
+     */
+    updateCells(updates: ICellState[]): Result<this>;
+    /**
+     * Performs an undo operation.
+     * @returns Result with this instance
+     */
+    undo(): Result<this>;
+    /**
+     * Performs a redo operation.
+     * @returns Result with this instance
+     */
+    redo(): Result<this>;
+    /**
+     * Gets the best available hint for the current puzzle state.
+     * @param options - Optional hint generation options
+     * @returns Result containing the best hint
+     */
+    getHint(options?: IHintGenerationOptions): Result<IHint>;
+    /**
+     * Gets all available hints for the current puzzle state.
+     * @param options - Optional hint generation options
+     * @returns Result containing array of hints
+     */
+    getAllHints(options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * Applies a hint to the puzzle, updating the state and adding to undo history.
+     * @param hint - The hint to apply
+     * @returns Result with this instance if successful
+     */
+    applyHint(hint: IHint): Result<this>;
+    /**
+     * Gets hints that specifically affect a given cell.
+     * @param spec - Cell specification (ID, row/column, or cell object)
+     * @param options - Optional hint generation options
+     * @returns Result containing hints affecting the specified cell
+     */
+    getHintsForCell(spec: string | IRowColumn | ICell, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * Gets a formatted explanation for a hint.
+     * @param hint - The hint to explain
+     * @param level - The explanation level (defaults to configured default)
+     * @returns Formatted explanation string
+     */
+    getExplanation(hint: IHint, level?: ExplanationLevel): string;
+    /**
+     * Validates that a hint can be applied to the current state.
+     * @param hint - The hint to validate
+     * @returns Result indicating validation success or failure
+     */
+    validateHint(hint: IHint): Result<void>;
+    /**
+     * Checks if hints are available for the current state.
+     * @param options - Optional hint generation options
+     * @returns Result containing boolean indicating availability
+     */
+    hasHints(options?: IHintGenerationOptions): Result<boolean>;
+    /**
+     * Gets statistics about available hints.
+     * @param options - Optional hint generation options
+     * @returns Result containing hint statistics
+     */
+    getHintStatistics(options?: IHintGenerationOptions): Result<{
+        totalHints: number;
+        hintsByTechnique: Map<string, number>;
+        hintsByDifficulty: Map<string, number>;
+    }>;
+    /**
+     * Gets a summary of the hint system capabilities.
+     * @returns System capabilities summary
+     */
+    getSystemSummary(): string;
+    /**
+     * Gets the rows.
+     * @returns Array of row cages
+     */
+    get rows(): ICage[];
+    /**
+     * Gets the columns.
+     * @returns Array of column cages
+     */
+    get cols(): ICage[];
+    /**
+     * Gets the sections.
+     * @returns Array of section cages
+     */
+    get sections(): ICage[];
+    /**
+     * Gets all cages.
+     * @returns Array of all cages
+     */
+    get cages(): ICage[];
+    /**
+     * Gets all cells.
+     * @returns Array of all cells
+     */
+    get cells(): ICell[];
+    /**
+     * Gets the next step index.
+     * @returns Next step index
+     */
+    get nextStep(): number;
+    /**
+     * Gets the number of steps.
+     * @returns Number of steps
+     */
+    get numSteps(): number;
+    /**
+     * Gets empty cells.
+     * @returns Array of empty cells
+     */
+    getEmptyCells(): ICell[];
+    /**
+     * Gets invalid cells.
+     * @returns Array of invalid cells
+     */
+    getInvalidCells(): ICell[];
+    /**
+     * Checks if a cell is valid.
+     * @param spec - Cell specification
+     * @returns true if valid
+     */
+    cellIsValid(spec: string | IRowColumn | ICell): boolean;
+    /**
+     * Checks if a cell has a value.
+     * @param spec - Cell specification
+     * @returns true if cell has value
+     */
+    cellHasValue(spec: string | IRowColumn | ICell): boolean;
+    /**
+     * Checks if a value is valid for a cell.
+     * @param spec - Cell specification
+     * @param value - Value to check
+     * @returns true if valid
+     */
+    isValidForCell(spec: string | IRowColumn | ICell, value: number): boolean;
+    /**
+     * Gets a cell neighbor.
+     * @param spec - Cell specification
+     * @param direction - Navigation direction
+     * @param wrap - Wrap behavior
+     * @returns Result containing neighbor cell
+     */
+    getCellNeighbor(spec: string | IRowColumn | ICell, direction: NavigationDirection, wrap: NavigationWrap): Result<ICell>;
+    /**
+     * Gets cell contents.
+     * @param spec - Cell specification
+     * @returns Result containing cell and contents
+     */
+    getCellContents(spec: string | IRowColumn): Result<{
+        cell: ICell;
+        contents: ICellContents;
+    }>;
+    /**
+     * Checks if a cage contains a value.
+     * @param spec - Cage specification
+     * @param value - Value to check
+     * @returns true if cage contains value
+     */
+    cageContainsValue(spec: string | ICage, value: number): boolean;
+    /**
+     * Gets contained values in a cage.
+     * @param spec - Cage specification
+     * @returns Set of contained values
+     */
+    cageContainedValues(spec: string | ICage): Set<number>;
+    /**
+     * Gets string representation of the puzzle.
+     * @returns Array of strings representing puzzle rows
+     */
+    toStrings(): string[];
+    /**
+     * Generates a cache key for the current state and options.
+     * @param options - Hint generation options
+     * @returns Cache key
+     */
+    private _generateCacheKey;
+    /**
+     * Gets cached hints if valid.
+     * @param options - Hint generation options
+     * @returns Cached hints or undefined
+     */
+    private _getCachedHints;
+    /**
+     * Updates the cache with new hints.
+     * @param hints - Generated hints
+     * @param options - Generation options
+     */
+    private _updateCache;
+    /**
+     * Invalidates the current hint cache.
+     */
+    private _invalidateCache;
+}
+
+/**
+ * Converts an arbitrary object to a {@link Files.Model.IPuzzlesFile | IPuzzlesFile}.
  * @public
  */
 declare const puzzlesFile: Converter<IPuzzlesFile>;
@@ -733,12 +2145,49 @@ export declare type PuzzleType = 'killer-sudoku' | 'sudoku' | 'sudoku-x';
  */
 declare const puzzleType: Converter<PuzzleType, ReadonlyArray<PuzzleType>>;
 
+/**
+ * Standard puzzle configurations
+ * @public
+ */
+export declare const STANDARD_CONFIGS: {
+    readonly puzzle4x4: {
+        readonly cageWidthInCells: 2;
+        readonly cageHeightInCells: 2;
+        readonly boardWidthInCages: 2;
+        readonly boardHeightInCages: 2;
+    };
+    readonly puzzle6x6: {
+        readonly cageWidthInCells: 3;
+        readonly cageHeightInCells: 2;
+        readonly boardWidthInCages: 2;
+        readonly boardHeightInCages: 3;
+    };
+    readonly puzzle9x9: {
+        readonly cageWidthInCells: 3;
+        readonly cageHeightInCells: 3;
+        readonly boardWidthInCages: 3;
+        readonly boardHeightInCages: 3;
+    };
+    readonly puzzle12x12: {
+        readonly cageWidthInCells: 4;
+        readonly cageHeightInCells: 3;
+        readonly boardWidthInCages: 3;
+        readonly boardHeightInCages: 4;
+    };
+};
+
+/**
+ * Type for standard configuration names
+ * @public
+ */
+export declare type StandardConfigName = keyof typeof STANDARD_CONFIGS;
+
 /**
  * @public
  */
 declare class SudokuPuzzle extends Puzzle {
     private constructor();
-    static create(puzzle: IPuzzleDescription): Result<Puzzle>;
+    static create(puzzle: IPuzzleDefinition): Result<Puzzle>;
 }
 
 /**
@@ -746,13 +2195,27 @@ declare class SudokuPuzzle extends Puzzle {
  */
 declare class SudokuXPuzzle extends Puzzle {
     private constructor();
-    static create(puzzle: IPuzzleDescription): Result<Puzzle>;
+    static create(puzzle: IPuzzleDefinition): Result<Puzzle>;
     private static _getXCages;
 }
 
 /**
- * The minimum and maximum possible values for a {@link ICage | cage}, by cage size in
- * {@link ICell | cells}.
+ * Nominal identifier for a hint generation technique.
+ * @public
+ */
+declare type TechniqueId = Brand<string, 'TechniqueId'>;
+
+/**
+ * Standard technique identifiers for built-in solving techniques.
+ * @public
+ */
+declare const TechniqueIds: {
+    readonly NAKED_SINGLES: TechniqueId;
+    readonly HIDDEN_SINGLES: TechniqueId;
+};
+
+/**
+ * Legacy array for backward compatibility - supports standard 9x9 Sudoku
  * @public
  */
 export declare const totalsByCageSize: readonly {