qnce-engine/dist/integrations/react.d.ts

Core QNCE (Quantum Narrative Convergence Engine) - Framework agnostic narrative engine with performance optimization

/**
 * QNCE Engine React Integration
 *
 * React hooks and utilities for integrating QNCE Engine with React applications.
 * Provides convenient hooks for managing narrative state, undo/redo operations,
 * and autosave functionality.
 */
import { QNCEEngine, type Choice, type NarrativeNode } from '../engine/core.js';
import { type AutosaveConfig, type SerializedState } from '../engine/types.js';
/**
 * Result type for undo/redo operations
 */
export interface UndoRedoResult {
    success: boolean;
    description?: string;
    error?: string;
}
/**
 * History summary for undo/redo state
 */
export interface HistorySummary {
    undoCount: number;
    redoCount: number;
    canUndo: boolean;
    canRedo: boolean;
}
/**
 * Configuration for the useQNCE hook
 */
export interface UseQNCEConfig {
    /** Enable automatic re-renders when state changes */
    autoUpdate?: boolean;
    /** Enable undo/redo functionality */
    enableUndoRedo?: boolean;
    /** Maximum number of undo operations to track */
    maxUndoEntries?: number;
    /** Maximum number of redo operations to track */
    maxRedoEntries?: number;
    /** Enable autosave functionality */
    enableAutosave?: boolean;
    /** Autosave throttle time in milliseconds */
    autosaveThrottleMs?: number;
}
/**
 * Return type for the useQNCE hook
 */
export interface UseQNCEReturn {
    engine: QNCEEngine;
    currentNode: NarrativeNode | null;
    availableChoices: Choice[];
    flags: Record<string, any>;
    selectChoice: (choice: Choice | string) => Promise<void>;
    setFlag: (key: string, value: any) => void;
    resetNarrative: () => void;
    undo: () => UndoRedoResult;
    redo: () => UndoRedoResult;
    canUndo: boolean;
    canRedo: boolean;
    undoCount: number;
    redoCount: number;
    clearHistory: () => void;
    autosave: () => Promise<void>;
    configureAutosave: (config: Partial<AutosaveConfig>) => void;
    saveState: () => Promise<SerializedState>;
    loadState: (serializedState: SerializedState) => Promise<void>;
    refresh: () => void;
}
/**
 * React hook for QNCE Engine integration
 *
 * Provides a complete interface for managing QNCE Engine state in React applications,
 * including undo/redo functionality, autosave, and automatic re-renders.
 *
 * @param engine - The QNCE Engine instance
 * @param config - Configuration options for the hook
 * @returns Hook return object with state and actions
 *
 * @example
 * ```tsx
 * function NarrativeComponent() {
 *   const engine = useMemo(() => createQNCEEngine(DEMO_STORY), []);
 *   const {
 *     currentNode,
 *     availableChoices,
 *     selectChoice,
 *     undo,
 *     redo,
 *     canUndo,
 *     canRedo
 *   } = useQNCE(engine, {
 *     enableUndoRedo: true,
 *     enableAutosave: true,
 *     maxUndoEntries: 50
 *   });
 *
 *   return (
 *     <div>
 *       <p>{currentNode?.text}</p>
 *
 *       <div>
 *         {availableChoices.map(choice => (
 *           <button key={choice.text} onClick={() => selectChoice(choice)}>
 *             {choice.text}
 *           </button>
 *         ))}
 *       </div>
 *
 *       <div>
 *         <button onClick={undo} disabled={!canUndo}>
 *           Undo
 *         </button>
 *         <button onClick={redo} disabled={!canRedo}>
 *           Redo
 *         </button>
 *       </div>
 *     </div>
 *   );
 * }
 * ```
 */
export declare function useQNCE(engine: QNCEEngine, config?: UseQNCEConfig): UseQNCEReturn;
/**
 * Hook for managing just undo/redo functionality
 *
 * A lightweight hook focused specifically on undo/redo operations.
 * Useful when you want to add undo/redo to an existing QNCE integration.
 *
 * @param engine - The QNCE Engine instance
 * @param config - Undo/redo configuration
 * @returns Undo/redo state and actions
 *
 * @example
 * ```tsx
 * function UndoRedoControls({ engine }: { engine: QNCEEngine }) {
 *   const { undo, redo, canUndo, canRedo, undoCount, redoCount } = useUndoRedo(engine);
 *
 *   return (
 *     <div className="undo-redo-controls">
 *       <button onClick={undo} disabled={!canUndo}>
 *         ← Undo ({undoCount})
 *       </button>
 *       <button onClick={redo} disabled={!canRedo}>
 *         Redo ({redoCount}) →
 *       </button>
 *     </div>
 *   );
 * }
 * ```
 */
export declare function useUndoRedo(engine: QNCEEngine, config?: {
    maxUndoEntries?: number;
    maxRedoEntries?: number;
}): {
    undo: () => UndoRedoResult;
    redo: () => UndoRedoResult;
    canUndo: boolean;
    canRedo: boolean;
    undoCount: number;
    redoCount: number;
    clearHistory: () => void;
    historySummary: HistorySummary;
};
/**
 * Hook for managing autosave functionality
 *
 * Provides control over the autosave system for fine-grained management.
 *
 * @param engine - The QNCE Engine instance
 * @param config - Autosave configuration
 * @returns Autosave state and actions
 *
 * @example
 * ```tsx
 * function AutosaveIndicator({ engine }: { engine: QNCEEngine }) {
 *   const { autosave, configure, isEnabled } = useAutosave(engine, {
 *     throttleMs: 200,
 *     triggers: ['choice', 'flag-change']
 *   });
 *
 *   return (
 *     <div>
 *       <span>Autosave: {isEnabled ? 'ON' : 'OFF'}</span>
 *       <button onClick={autosave}>Save Now</button>
 *     </div>
 *   );
 * }
 * ```
 */
export declare function useAutosave(engine: QNCEEngine, config?: {
    throttleMs?: number;
    triggers?: string[];
    enabled?: boolean;
}): {
    autosave: () => Promise<void>;
    configure: (config: Partial<AutosaveConfig>) => void;
    isEnabled: boolean;
    lastAutosave: Date | null;
    isSaving: boolean;
};
//# sourceMappingURL=react.d.ts.map