qnce-engine 1.3.2 → 1.4.1

package/dist/qnce-engine.d.ts

@@ -0,0 +1,2258 @@
+import { default as React_2 } from 'react';
+
+/**
+ * Interfaces for AI-driven content generation and branching
+ */
+declare interface AIBranchingContext {
+    playerProfile: PlayerProfile;
+    narrativeContext: NarrativeContext;
+    generationHints: AIGenerationHints;
+}
+
+declare interface AIGenerationHints {
+    maxBranchDepth: number;
+    desiredComplexity: number;
+    contentThemes: string[];
+    avoidElements: string[];
+}
+
+/**
+ * Attach optional quantum helpers to an engine instance. No-ops unless the corresponding
+ * feature flags are enabled. This does not mutate engine behavior; it only provides
+ * opt-in utilities that operate against engine.flags.
+ */
+/** @beta @experimental */
+export declare function attachQuantumFeatures(engine: Pick<QNCEEngine, 'flags'>, flagsConfig?: FeatureFlags | FeatureFlagsConfig): QuantumIntegration;
+
+/**
+ * Configuration for autosave functionality
+ */
+declare interface AutosaveConfig {
+    /** Whether autosave is enabled */
+    enabled: boolean;
+    /** Triggers that should cause an autosave */
+    triggers: ('choice' | 'flag-change' | 'state-load' | 'branch-exit' | 'custom')[];
+    /** Maximum number of autosave entries to keep */
+    maxEntries: number;
+    /** Minimum time between autosaves (ms) to prevent spam */
+    throttleMs: number;
+    /** Whether to include metadata in autosave entries */
+    includeMetadata: boolean;
+    /** Custom autosave naming pattern */
+    namePattern?: string;
+}
+
+/**
+ * AutosaveIndicator Component
+ *
+ * Visual indicator showing autosave status with animated feedback,
+ * timestamp display, and customizable positioning.
+ *
+ * Features:
+ * - Real-time autosave status updates (idle, saving, saved, error)
+ * - Animated visual feedback with spinner and status icons
+ * - Configurable positioning (corners, inline)
+ * - Timestamp of last successful save
+ * - Auto-hide functionality
+ * - Accessible with proper ARIA labels
+ * @public
+ */
+export declare const AutosaveIndicator: React_2.FC<AutosaveIndicatorProps>;
+
+/**
+ * Props for AutosaveIndicator component
+ * @public
+ */
+export declare interface AutosaveIndicatorProps {
+    /** QNCE Engine instance */
+    engine: QNCEEngine;
+    /** Custom theme (optional, uses default if not provided) */
+    theme?: Partial<QNCETheme>;
+    /** Additional CSS class name */
+    className?: string;
+    /** Custom styling */
+    style?: React.CSSProperties;
+    /** Indicator variant */
+    variant?: 'minimal' | 'detailed' | 'icon-only';
+    /** Position of the indicator */
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'inline';
+    /** Custom status messages */
+    messages?: {
+        idle: string;
+        saving: string;
+        saved: string;
+        error: string;
+    };
+    /** Show timestamp of last save */
+    showTimestamp?: boolean;
+    /** Auto-hide after successful save (ms) */
+    autoHideDelay?: number;
+}
+
+/**
+ * Autosave operation result
+ */
+declare interface AutosaveResult {
+    /** Whether the autosave succeeded */
+    success: boolean;
+    /** Error message if autosave failed */
+    error?: string;
+    /** The checkpoint ID created by autosave */
+    checkpointId?: string;
+    /** Trigger that caused this autosave */
+    trigger?: string;
+    /** Time taken for autosave operation (ms) */
+    duration?: number;
+    /** Size of the autosaved data */
+    size?: number;
+}
+
+declare interface BranchAnalytics {
+    totalBranchesTraversed: number;
+    avgBranchDecisionTime: number;
+    mostPopularBranches: string[];
+    abandonmentPoints: string[];
+    completionRate: number;
+    sessionStartTime: Date;
+}
+
+declare interface BranchCondition {
+    type: 'flag' | 'choice' | 'time' | 'random' | 'custom';
+    operator: 'equals' | 'not_equals' | 'greater' | 'less' | 'contains' | 'exists';
+    key: string;
+    value: unknown;
+    evaluator?: (state: QNCEState, context: BranchContext) => boolean;
+}
+
+/**
+ * BranchContext: Runtime state for branch evaluation and tracking
+ */
+declare interface BranchContext {
+    currentStory: QNCEStory;
+    currentChapter: Chapter;
+    currentFlow: NarrativeFlow;
+    activeState: QNCEState;
+    branchHistory: BranchHistoryEntry[];
+    pendingBranches: PendingBranch[];
+    analytics: BranchAnalytics;
+}
+
+declare interface BranchHistoryEntry {
+    id: string;
+    branchPointId: string;
+    chosenOptionId: string;
+    timestamp: Date;
+    executionTime: number;
+    context: Partial<QNCEState>;
+}
+
+declare interface BranchingConfig {
+    maxActiveBranches: number;
+    branchCacheSize: number;
+    enableDynamicInsertion: boolean;
+    enableAnalytics: boolean;
+    performanceMode: boolean;
+}
+
+declare interface BranchLocation {
+    chapterId: string;
+    flowId: string;
+    nodeId: string;
+    insertionPoint: 'before' | 'after' | 'replace';
+}
+
+declare interface BranchMetadata {
+    usageCount: number;
+    avgTraversalTime: number;
+    playerPreference: number;
+    lastUsed: Date;
+}
+
+declare interface BranchOption {
+    id: string;
+    targetFlowId: string;
+    targetNodeId?: string;
+    displayText: string;
+    conditions?: BranchCondition[];
+    flagEffects?: Record<string, unknown>;
+    weight: number;
+}
+
+/**
+ * BranchPoint: Dynamic branching logic between flows
+ */
+declare interface BranchPoint {
+    id: string;
+    name: string;
+    sourceFlowId: string;
+    sourceNodeId: string;
+    branchOptions: BranchOption[];
+    branchType: BranchType;
+    conditions?: BranchCondition[];
+    metadata: BranchMetadata;
+}
+
+declare type BranchType = 'choice-driven' | 'flag-conditional' | 'time-based' | 'procedural' | 'conditional';
+
+/**
+ * Chapter: Logical grouping of narrative flows with branching points
+ */
+declare interface Chapter {
+    id: string;
+    title: string;
+    description?: string;
+    flows: NarrativeFlow[];
+    branches: BranchPoint[];
+    prerequisites?: ChapterPrerequisites;
+    metadata: ChapterMetadata;
+}
+
+declare interface ChapterMetadata {
+    difficulty: 'easy' | 'medium' | 'hard';
+    themes: string[];
+    estimatedDuration: number;
+    branchComplexity: number;
+}
+
+declare interface ChapterPrerequisites {
+    requiredFlags: Record<string, unknown>;
+    requiredChoices: string[];
+    minPlaytime?: number;
+}
+
+/**
+ * Lightweight checkpoint for quick save/restore operations
+ * Contains minimal data for fast state snapshots
+ */
+declare interface Checkpoint {
+    /** Unique checkpoint identifier */
+    id: string;
+    /** Human-readable checkpoint name/label */
+    name?: string;
+    /** Core state snapshot (deep copied) */
+    state: QNCEState;
+    /** Checkpoint creation timestamp */
+    timestamp: string;
+    /** Optional description or context */
+    description?: string;
+    /** Tags for checkpoint organization */
+    tags?: string[];
+    /** Lightweight metadata */
+    metadata?: {
+        nodeTitle?: string;
+        choiceCount?: number;
+        flagCount?: number;
+        historyLength?: number;
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * Checkpoint management options
+ */
+declare interface CheckpointOptions {
+    /** Maximum number of checkpoints to keep */
+    maxCheckpoints?: number;
+    /** Auto-cleanup strategy */
+    cleanupStrategy?: 'lru' | 'fifo' | 'timestamp' | 'manual';
+    /** Include metadata in checkpoint */
+    includeMetadata?: boolean;
+    /** Tags to automatically apply */
+    autoTags?: string[];
+}
+
+/** Narrative choice presented to user */
+/** @public */
+export declare interface Choice {
+    text: string;
+    nextNodeId: string;
+    flagEffects?: Record<string, unknown>;
+    flagRequirements?: Record<string, unknown>;
+    timeRequirements?: {
+        minTime?: number;
+        maxTime?: number;
+        availableAfter?: Date;
+        availableBefore?: Date;
+    };
+    inventoryRequirements?: Record<string, number>;
+    enabled?: boolean;
+    condition?: string;
+}
+
+/**
+ * Error thrown when choice validation fails
+ * Provides detailed information about why the choice is invalid
+ * @public
+ */
+export declare class ChoiceValidationError extends QNCEError {
+    readonly choice: Choice;
+    readonly validationResult: ValidationResult;
+    readonly availableChoices?: Choice[];
+    constructor(choice: Choice, validationResult: ValidationResult, availableChoices?: Choice[]);
+    /**
+     * Get a user-friendly error message with suggestions
+     */
+    getUserFriendlyMessage(): string;
+    /**
+     * Get debugging information for developers
+     */
+    getDebugInfo(): Record<string, unknown>;
+}
+
+/**
+ * Core ChoiceValidator interface
+ * Provides validation logic for choice execution and availability filtering
+ */
+declare interface ChoiceValidator {
+    /**
+     * Validate a specific choice against current state
+     * @param choice - The choice to validate
+     * @param context - Current validation context
+     * @returns Validation result with details
+     */
+    validate(choice: Choice, context: ValidationContext): ValidationResult;
+    /**
+     * Get all currently available/valid choices
+     * @param context - Current validation context
+     * @returns Array of valid choices
+     */
+    getAvailableChoices(context: ValidationContext): Choice[];
+    /**
+     * Add a validation rule to the validator
+     * @param rule - Validation rule to add
+     */
+    addRule(rule: ValidationRule): void;
+    /**
+     * Remove a validation rule by name
+     * @param ruleName - Name of the rule to remove
+     */
+    removeRule(ruleName: string): void;
+    /**
+     * Get all registered validation rules
+     * @returns Array of validation rules sorted by priority
+     */
+    getRules(): ValidationRule[];
+}
+
+/**
+ * Context object passed to condition evaluators
+ * @public
+ */
+export declare interface ConditionContext {
+    /** Current engine state */
+    state: QNCEState;
+    /** Current timestamp for time-based conditions */
+    timestamp: number;
+    /** Additional custom context data */
+    customData?: Record<string, unknown>;
+}
+
+/**
+ * Error thrown when condition evaluation fails
+ * @public
+ */
+export declare class ConditionEvaluationError extends Error {
+    readonly expression?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, expression?: string | undefined, cause?: Error | undefined);
+}
+
+/**
+ * Condition evaluator service for parsing and executing conditional expressions
+ * @public
+ */
+export declare class ConditionEvaluator {
+    private customEvaluator?;
+    private functionCache;
+    private maxCacheSize;
+    private expressionCache;
+    private maxExpressionCacheSize;
+    private contextPool;
+    private maxContextPoolSize;
+    private poolingEnabled;
+    /** @internal Enable/disable context pooling (engine toggles in perf mode) */
+    enablePooling(enable: boolean): void;
+    /** @internal Adjust pool cap during tuning */
+    setMaxContextPoolSize(size: number): void;
+    /**
+     * Set a custom evaluator function for handling complex conditions
+     */
+    setCustomEvaluator(evaluator: CustomEvaluatorFunction): void;
+    /**
+     * Clear the custom evaluator
+     */
+    clearCustomEvaluator(): void;
+    /**
+     * Evaluate a condition expression against the provided context
+     */
+    evaluate(expression: string, context: ConditionContext): boolean;
+    /**
+     * Built-in expression evaluator with support for common patterns
+     */
+    private evaluateBuiltIn;
+    /**
+     * Sanitize expression to prevent code injection
+     */
+    private sanitizeExpression;
+    /** Normalize + intern expression with LRU retention */
+    private internAndNormalize;
+    /**
+     * Create a safe evaluation context from the condition context
+     */
+    private createEvaluationContext;
+    private releaseEvaluationContext;
+    /**
+     * Validate that an expression is syntactically correct without evaluating it
+     */
+    validateExpression(expression: string): {
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * Get list of flag names referenced in an expression
+     */
+    getReferencedFlags(expression: string): string[];
+}
+
+/** @public */
+export declare const conditionEvaluator: ConditionEvaluator;
+
+/**
+ * Built-in console adapter (dev-friendly pretty print)
+ * @beta
+ * @experimental
+ */
+export declare class ConsoleAdapter implements TelemetryAdapter {
+    configure(): void;
+    send(batch: QEvent[]): Promise<void>;
+}
+
+/**
+ * Factory function to create a QNCE engine instance
+ */
+/**
+ * Factory to create a QNCE engine instance.
+ * @public
+ */
+export declare function createQNCEEngine(storyData: StoryData, initialState?: Partial<QNCEState>, performanceMode?: boolean, threadPoolConfig?: Partial<ThreadPoolConfig>, options?: {
+    telemetry?: Telemetry;
+    env?: 'dev' | 'test' | 'prod';
+    appVersion?: string;
+    sessionId?: string;
+    suppressTelemetryWarnings?: boolean;
+    logger?: Logger;
+    minimalTelemetry?: boolean;
+}): QNCEEngine;
+
+/**
+ * Core factory – always returns a StructuredQNCEError.
+ * Prefer this over direct `new QNCEError` when emitting from engine internals.
+ * @public
+ */
+export declare function createStructuredError(kind: QNCEErrorKind, message: string, context?: QNCEErrorContext): StructuredQNCEError;
+
+/**
+ * Create a telemetry instance; pass adapter + options
+ * @beta
+ * @experimental
+ */
+export declare function createTelemetry(options: TelemetryOptions): Telemetry;
+
+/**
+ * Factory for built-in telemetry adapters
+ * @beta
+ * @experimental
+ */
+export declare function createTelemetryAdapter(kind: 'console' | 'file', opts?: {
+    path?: string;
+}): TelemetryAdapter;
+
+/**
+ * Custom evaluator function signature
+ * @public
+ */
+export declare type CustomEvaluatorFunction = (expression: string, context: ConditionContext) => boolean;
+
+/** Lightweight ring-buffer debug logger (opt-in at runtime). */
+declare interface DebugLogEntry {
+    ts: number;
+    level: 'debug';
+    event: string;
+    data?: Record<string, unknown>;
+}
+
+/** @public */
+export declare const DEMO_STORY: StoryData;
+
+/**
+ * Dynamic branching operations for runtime story modification
+ */
+declare interface DynamicBranchOperation {
+    type: 'insert' | 'remove' | 'modify';
+    branchId: string;
+    targetLocation: BranchLocation;
+    payload?: Partial<BranchPoint>;
+    conditions?: BranchCondition[];
+}
+
+/** Engine hook context */
+/** @public */
+export declare interface EngineHookContext {
+    engine: QNCEEngine;
+    node: NarrativeNode;
+    choice?: Choice;
+}
+
+/** @beta @experimental */
+export declare class Entangler<TKey extends string = string> {
+    private bindings;
+    bind(from: TKey, to: TKey, transform?: TransformFn): this;
+    apply(flags: Record<string, unknown>): void;
+}
+
+/** @beta @experimental */
+export declare type EntangleTransform = (value: unknown) => unknown;
+
+/**
+ * Environment identifier for telemetry context
+ * @beta
+ * @experimental
+ */
+declare type Env = 'dev' | 'test' | 'prod';
+
+/**
+ * Convenience helpers by category
+ * @public
+ */
+export declare const ErrorFactory: {
+    navigation: (msg: string, ctx?: QNCEErrorContext) => StructuredQNCEError;
+    choiceValidation: (msg: string, ctx?: QNCEErrorContext) => StructuredQNCEError;
+    storyData: (msg: string, ctx?: QNCEErrorContext) => StructuredQNCEError;
+    state: (msg: string, ctx?: QNCEErrorContext) => StructuredQNCEError;
+    hook: (msg: string, ctx?: QNCEErrorContext) => StructuredQNCEError;
+    condition: (msg: string, ctx?: QNCEErrorContext) => StructuredQNCEError;
+    persistence: (msg: string, ctx?: QNCEErrorContext) => StructuredQNCEError;
+    telemetry: (msg: string, ctx?: QNCEErrorContext) => StructuredQNCEError;
+    adapter: (msg: string, ctx?: QNCEErrorContext) => StructuredQNCEError;
+    unknown: (msg: string, ctx?: QNCEErrorContext) => StructuredQNCEError;
+};
+
+/** @beta @experimental */
+export declare type FeatureFlagKey = string;
+
+/** @beta @experimental */
+export declare class FeatureFlags {
+    private flags;
+    constructor(initial?: FeatureFlagsConfig);
+    enable(flag: string): void;
+    disable(flag: string): void;
+    isEnabled(flag: string): boolean;
+    getAll(): {
+        [x: string]: boolean;
+    };
+}
+
+/**
+ * Feature flags utility to gate experimental behavior
+ * @beta
+ * @experimental
+ */
+/**
+ * @beta
+ * @experimental
+ */
+export declare type FeatureFlagsConfig = {
+    [flag: string]: boolean;
+};
+
+/**
+ * File adapter writing newline-delimited JSON events
+ * @beta
+ * @experimental
+ */
+export declare class FileAdapter implements TelemetryAdapter {
+    private opts;
+    private stream;
+    constructor(opts: FileAdapterOptions);
+    send(batch: QEvent[]): Promise<void>;
+    flush(): Promise<void>;
+    dispose(): Promise<void>;
+}
+
+declare interface FileAdapterOptions {
+    path: string;
+    rotateBytes?: number;
+}
+
+declare interface FlowEntryPoint {
+    id: string;
+    nodeId: string;
+    conditions?: BranchCondition[];
+    priority: number;
+}
+
+/** Flow event captured during narrative traversal */
+/** @public */
+export declare interface FlowEvent {
+    id: string;
+    fromNodeId: string;
+    toNodeId: string;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+
+declare interface FlowExitPoint {
+    id: string;
+    nodeId: string;
+    targetFlowId?: string;
+    conditions?: BranchCondition[];
+}
+
+declare interface FlowMetadata {
+    complexity: number;
+    avgCompletionTime: number;
+    playerChoiceCount: number;
+    aiGeneratedContent: boolean;
+}
+
+declare type FlowType = 'linear' | 'branching' | 'conditional' | 'procedural';
+
+/**
+ * @beta
+ */
+export declare function getPerfReporter(config?: Partial<PerfReporterConfig>): PerfReporter;
+
+/**
+ * History summary for undo/redo state
+ * @public
+ */
+export declare interface HistorySummary {
+    undoCount: number;
+    redoCount: number;
+    canUndo: boolean;
+    canRedo: boolean;
+}
+
+/** Hook execution stage for errors arising inside hooks */
+/** @public */
+export declare type HookStage = 'pre-choice' | 'post-choice';
+
+/**
+ * Keyboard shortcuts configuration
+ * @public
+ */
+export declare interface KeyboardShortcutsConfig {
+    /** Enable/disable keyboard shortcuts */
+    enabled?: boolean;
+    /** Custom key bindings */
+    bindings?: {
+        undo?: string[];
+        redo?: string[];
+        save?: string[];
+        reset?: string[];
+    };
+    /** Prevent default browser behavior */
+    preventDefault?: boolean;
+    /** Element to attach listeners to (defaults to document) */
+    target?: HTMLElement | Document;
+}
+
+/**
+ * Options for state loading/deserialization
+ */
+declare interface LoadOptions {
+    /** Verify checksum integrity before loading */
+    verifyChecksum?: boolean;
+    /** Skip compatibility checks (dangerous) */
+    skipCompatibilityCheck?: boolean;
+    /** Restore performance state */
+    restorePerformanceState?: boolean;
+    /** Restore flow events */
+    restoreFlowEvents?: boolean;
+    /** Restore branching context */
+    restoreBranchingContext?: boolean;
+    /** Restore validation state */
+    restoreValidationState?: boolean;
+    /** Migration function for version compatibility */
+    migrationFunction?: (serializedState: SerializedState) => SerializedState;
+}
+
+/**
+ * Load story data from JSON
+ */
+/**
+ * Load and validate StoryData from JSON-like input.
+ * @public
+ */
+export declare function loadStoryData(jsonData: unknown): StoryData;
+
+declare interface Logger {
+    level: LogLevelName;
+    setLevel(lvl: LogLevelName): void;
+    error(msg: string): void;
+    warn(msg: string): void;
+    info(msg: string): void;
+    success(msg: string): void;
+    debug(msg: string): void;
+    child(pfx: string): Logger;
+}
+
+/** Lightweight logger with level filtering and pluggable sink (no external deps). */
+declare type LogLevelName = 'silent' | 'error' | 'warn' | 'info' | 'success' | 'debug';
+
+/** @beta @experimental */
+export declare class Measurement {
+    readonly name: string;
+    private sampler?;
+    private trials;
+    private successes;
+    constructor(name: string, sampler?: Sampler);
+    sample(ctx?: MeasurementContext): boolean;
+    getStats(): {
+        trials: number;
+        successes: number;
+        rate: number;
+    };
+}
+
+/** @beta @experimental */
+export declare type MeasurementContext = {
+    flags: Record<string, unknown>;
+    nodeId?: string;
+};
+
+declare interface NarrativeContext {
+    currentTone: string;
+    thematicElements: string[];
+    characterRelationships: Record<string, number>;
+    plotTension: number;
+}
+
+/**
+ * NarrativeFlow: Sequence of connected nodes with entry/exit points
+ */
+declare interface NarrativeFlow {
+    id: string;
+    name: string;
+    description?: string;
+    nodes: NarrativeNode[];
+    entryPoints: FlowEntryPoint[];
+    exitPoints: FlowExitPoint[];
+    flowType: FlowType;
+    metadata: FlowMetadata;
+}
+
+/** Story node containing narrative text and available choices */
+/** @public */
+export declare interface NarrativeNode {
+    id: string;
+    text: string;
+    choices: Choice[];
+    meta?: {
+        tags?: string[];
+    };
+}
+
+declare interface PendingBranch {
+    id: string;
+    branchPointId: string;
+    triggerConditions: BranchCondition[];
+    timeoutMs?: number;
+    createdAt: Date;
+}
+
+declare interface PerfEvent {
+    id: string;
+    type: 'flow-start' | 'flow-complete' | 'cache-hit' | 'cache-miss' | 'hot-reload-start' | 'hot-reload-end' | 'state-transition' | 'custom';
+    timestamp: number;
+    duration?: number;
+    metadata: Record<string, unknown>;
+    category: 'engine' | 'cache' | 'hot-reload' | 'user' | 'system';
+}
+
+/**
+ * Flush metrics snapshot returned by getPerfFlushMetrics().
+ * Designed to be immutable from consumer perspective (frozen object returned).
+ */
+/**
+ * @beta
+ */
+export declare interface PerfFlushMetrics {
+    totalFlushAttempts: number;
+    successfulFlushes: number;
+    rejectedFlushes: number;
+    rejectedFlushesSinceLastSuccess?: number;
+    totalBatchesDispatched: number;
+    totalEventsDispatched: number;
+    lastFlushDurationMs: number;
+    avgEventsPerBatch: number;
+    p50DispatchLatencyMs: number;
+    p95DispatchLatencyMs: number;
+    smoothedP95DispatchLatencyMs?: number;
+    histogramBuckets: ReadonlyArray<{
+        upperBoundMs: number;
+        count: number;
+    }>;
+    rejectionRate: number;
+    lastEffectiveBatchSize?: number;
+    lastUpdated: number;
+    adaptiveEnabled: boolean;
+    backoffActive?: boolean;
+    consecutiveRejects?: number;
+    backoffDelayMs?: number;
+}
+
+/**
+ * PerfReporter - Batched performance event collection and analysis
+ * Designed to work off main thread for minimal performance impact
+ */
+declare class PerfReporter {
+    private events;
+    private config;
+    private flushTimer;
+    private nextAllowedFlushTime;
+    private consecutiveRejects;
+    private backoffDelayMs;
+    private startTime;
+    private activeSpans;
+    private sampler;
+    private metrics;
+    private static readonly MAX_LATENCY_SAMPLES;
+    constructor(config?: Partial<PerfReporterConfig>);
+    /**
+     * Internal override hook for tests to inject a deterministic thread pool implementation.
+     * Not part of public API surface; subject to change without notice.
+     */
+    private static __threadPoolOverride;
+    static __setThreadPoolOverride(override: {
+        writeTelemetry: (payload: unknown) => Promise<unknown>;
+    } | null): void;
+    /**
+     * Record a performance event
+     */
+    record(type: PerfEvent['type'], metadata?: Record<string, unknown>, category?: PerfEvent['category']): string;
+    /**
+     * Start a performance span (for measuring duration)
+     */
+    startSpan(type: PerfEvent['type'], metadata?: Record<string, unknown>, category?: PerfEvent['category']): string;
+    /**
+     * End a performance span and record the complete event
+     */
+    endSpan(spanId: string, additionalMetadata?: Record<string, unknown>): void;
+    /**
+     * Record flow start event (S2-T4 requirement)
+     */
+    recordFlowStart(nodeId: string, metadata?: Record<string, unknown>): string;
+    /**
+     * Record flow completion event (S2-T4 requirement)
+     */
+    recordFlowComplete(spanId: string, nextNodeId: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Record cache hit event (S2-T4 requirement)
+     */
+    recordCacheHit(cacheKey: string, metadata?: Record<string, unknown>): string;
+    /**
+     * Record cache miss event (S2-T4 requirement)
+     */
+    recordCacheMiss(cacheKey: string, metadata?: Record<string, unknown>): string;
+    /**
+     * Record hot-reload start event (S2-T4 requirement)
+     */
+    recordHotReloadStart(deltaSize: number, metadata?: Record<string, unknown>): string;
+    /**
+     * Record hot-reload completion event (S2-T4 requirement)
+     */
+    recordHotReloadEnd(spanId: string, success: boolean, metadata?: Record<string, unknown>): void;
+    /**
+     * Generate performance summary for CLI dashboard
+     */
+    summary(): PerfSummary;
+    /**
+     * Get raw events for detailed analysis
+     */
+    getEvents(): PerfEvent[];
+    /**
+     * Clear event history
+     */
+    clear(): void;
+    /**
+     * Flush events to background processing
+     */
+    flush(): void;
+    /**
+     * Start automatic flush timer
+     */
+    private startFlushTimer;
+    /**
+     * Stop automatic flush timer
+     */
+    stopFlushTimer(): void;
+    /** Dispose reporter (stop timers) */
+    dispose(): void;
+    /**
+     * Generate unique event ID
+     */
+    private generateEventId;
+    /** Internal: record dispatch latency after counters were eagerly incremented */
+    private recordDispatchSuccessPostLatency;
+    /** Internal: record dispatch failure */
+    private recordDispatchFailure;
+    /** Compute derived metrics (avg, percentiles) */
+    private recomputeDerivedMetrics;
+    /** Public snapshot accessor (frozen copy) */
+    getFlushMetrics(): PerfFlushMetrics;
+    /** @internal Debug accessor for tests (not part of public API surface) */
+    __getInternalPerfDebug(): {
+        consecutiveRejects: number;
+        backoffDelayMs: number;
+        nextAllowedFlushTime: number;
+        lastEffectiveBatchSize: number;
+    };
+    /** @internal Inject a synthetic dispatch latency sample (test helper) */
+    __injectLatencySample(latencyMs: number): void;
+}
+
+declare interface PerfReporterConfig {
+    batchSize: number;
+    flushInterval: number;
+    enableBackgroundFlush: boolean;
+    maxEventHistory: number;
+    enableConsoleOutput: boolean;
+    disableAdaptiveBatch?: boolean;
+    smoothingAlpha?: number;
+}
+
+declare interface PerfSummary {
+    totalEvents: number;
+    eventsByType: Record<string, number>;
+    avgDurations: Record<string, number>;
+    maxDurations: Record<string, number>;
+    minDurations: Record<string, number>;
+    cacheHitRate: number;
+    hotReloadPerformance: {
+        avgTime: number;
+        maxTime: number;
+        totalReloads: number;
+    };
+    timeRange: {
+        start: number;
+        end: number;
+        duration: number;
+    };
+}
+
+/**
+ * State persistence result with success/error information
+ */
+declare interface PersistenceResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Error message if operation failed */
+    error?: string;
+    /** Operation-specific data */
+    data?: {
+        /** Serialized state size in bytes */
+        size?: number;
+        /** Compression ratio achieved */
+        compressionRatio?: number;
+        /** Checksum of saved data */
+        checksum?: string;
+        /** Time taken for operation (ms) */
+        duration?: number;
+    };
+    /** Warnings or informational messages */
+    warnings?: string[];
+}
+
+/** @beta @experimental */
+export declare class Phase {
+    readonly name: string;
+    when?: PhasePredicate_2 | undefined;
+    constructor(name: string, when?: PhasePredicate_2 | undefined);
+    isActive(ctx: PhaseContext): boolean;
+}
+
+/**
+ * Phase primitive representing a labeled coexistence region
+ * @beta
+ * @experimental
+ */
+/** @beta @experimental */
+export declare interface PhaseContext {
+    flags: Record<string, unknown>;
+    nodeId?: string;
+}
+
+/** @beta @experimental */
+export declare type PhasePredicate = (ctx: PhasePredicateContext) => boolean;
+
+/** @beta @experimental */
+declare type PhasePredicate_2 = (ctx: PhaseContext) => boolean;
+
+/** @beta @experimental */
+export declare interface PhasePredicateContext {
+    flags: Record<string, unknown>;
+    nodeId?: string;
+}
+
+declare interface PlayerProfile {
+    playStyle: 'explorer' | 'achiever' | 'socializer' | 'killer';
+    preferences: Record<string, number>;
+    historicalChoices: string[];
+    averageDecisionTime: number;
+}
+
+/** @public */
+export declare type PostChoiceHook = (ctx: EngineHookContext) => void;
+
+/** @public */
+export declare type PreChoiceHook = (ctx: EngineHookContext) => void | boolean;
+
+/**
+ * Generic telemetry event shape emitted by the engine
+ * @beta
+ * @experimental
+ */
+export declare interface QEvent<T extends string = string, P = unknown> {
+    type: T;
+    payload: P;
+    ts: number;
+    ctx: {
+        sessionId: string;
+        storyId?: string;
+        appVersion?: string;
+        engineVersion: string;
+        env?: Env;
+    };
+    meta?: {
+        seq?: number;
+        source?: 'engine' | 'cli' | 'ui';
+    };
+}
+
+/**
+ * QNCE Branching Engine - Core API for dynamic narrative branching
+ * Simplified implementation focusing on core functionality
+ */
+declare class QNCEBranchingEngine {
+    private story;
+    private context;
+    private aiContext?;
+    constructor(story: QNCEStory, initialState: QNCEState);
+    /**
+     * Evaluate available branches from current position
+     */
+    evaluateAvailableBranches(): Promise<BranchOption[]>;
+    /**
+     * Execute a branch transition
+     */
+    executeBranch(optionId: string): Promise<boolean>;
+    /**
+     * Dynamic branch insertion at runtime
+     */
+    insertDynamicBranch(operation: DynamicBranchOperation): Promise<boolean>;
+    /**
+     * Remove dynamic branch
+     */
+    removeDynamicBranch(branchId: string): Promise<boolean>;
+    /**
+     * Set AI context for enhanced branching decisions
+     */
+    setAIContext(aiContext: AIBranchingContext): void;
+    /**
+     * Generate AI-driven branch options
+     */
+    generateAIBranches(maxOptions?: number): Promise<BranchOption[]>;
+    /**
+     * Get current branching analytics
+     */
+    getBranchingAnalytics(): {
+        currentChapter: string;
+        currentFlow: string;
+        historyLength: number;
+        pendingBranches: number;
+        totalBranchesTraversed: number;
+        avgBranchDecisionTime: number;
+        mostPopularBranches: string[];
+        abandonmentPoints: string[];
+        completionRate: number;
+        sessionStartTime: Date;
+    };
+    /**
+     * Export branching data for external analysis
+     */
+    exportBranchingData(): {
+        story: {
+            id: string;
+            title: string;
+            version: string;
+        };
+        session: {
+            startTime: Date;
+            currentState: QNCEState;
+            branchHistory: BranchHistoryEntry[];
+            analytics: BranchAnalytics;
+        };
+    };
+    private createBranchContext;
+    private getCurrentNode;
+    private findBranchPointsForNode;
+    private evaluateConditions;
+    private evaluateCondition;
+    private findBranchOption;
+    private findFlow;
+    private findChapter;
+    private transitionToFlow;
+    private recordBranchHistory;
+    private updateBranchAnalytics;
+}
+
+/**
+ * QNCE Engine - Core narrative state management
+ * Framework agnostic implementation with object pooling integration
+ */
+/**
+ * Main engine class.
+ * @public
+ */
+export declare class QNCEEngine {
+    private state;
+    storyData: StoryData;
+    private activeFlowEvents;
+    private performanceMode;
+    private enableProfiling;
+    private debugMode;
+    private branchingEngine?;
+    private choiceValidator;
+    private checkpoints;
+    private maxCheckpoints;
+    private autoCheckpointEnabled;
+    private flagKeyPool;
+    private flagValuePool;
+    private internFlagKey;
+    private internFlagValue;
+    private checkpointManager?;
+    private undoStack;
+    private redoStack;
+    private autosaveConfig;
+    private undoRedoConfig;
+    private lastAutosaveTime;
+    private isUndoRedoOperation;
+    private storageAdapter?;
+    private storageRetryPolicy;
+    private telemetry?;
+    private defaultTelemetryCtx?;
+    private preChoiceHooks;
+    private postChoiceHooks;
+    private hookCounter;
+    private logger;
+    private engineOptions?;
+    private minimalTelemetry;
+    get flags(): Record<string, unknown>;
+    get history(): string[];
+    /** Access the engine logger (public read-only) */
+    getLogger(): Logger;
+    get isComplete(): boolean;
+    constructor(storyData: StoryData, initialState?: Partial<QNCEState>, performanceMode?: boolean, threadPoolConfig?: Partial<ThreadPoolConfig>, options?: {
+        telemetry?: Telemetry;
+        env?: 'dev' | 'test' | 'prod';
+        appVersion?: string;
+        sessionId?: string;
+        logger?: Logger;
+        suppressTelemetryWarnings?: boolean;
+        minimalTelemetry?: boolean;
+    });
+    /**
+     * Dispose engine resources (telemetry, performance reporter, background thread pool in perf mode)
+     * @public
+     */
+    dispose(): Promise<void>;
+    /** Attach a storage adapter for persistence */
+    attachStorageAdapter(adapter: StorageAdapter): void;
+    /**
+     * Configure storage retry policy for transient save failures.
+     * @param policy - Partial policy overriding defaults. Set maxAttempts to 1 to disable retries.
+     * @beta
+     */
+    setStorageRetryPolicy(policy: Partial<{
+        maxAttempts: number;
+        baseDelayMs: number;
+        factor: number;
+        maxDelayMs: number;
+        jitter: boolean;
+    }>): void;
+    private sleep;
+    private computeBackoff;
+    /** Save current state through the attached storage adapter */
+    saveToStorage(key: string, options?: SerializationOptions): Promise<PersistenceResult>;
+    /** Load state from the attached storage adapter */
+    loadFromStorage(key: string, options?: LoadOptions): Promise<PersistenceResult>;
+    /** Delete a stored state via the adapter */
+    deleteFromStorage(key: string): Promise<boolean>;
+    /** List keys from the adapter */
+    listStorageKeys(): Promise<string[]>;
+    /** Check if a key exists via the adapter */
+    storageExists(key: string): Promise<boolean>;
+    /** Clear all stored data via the adapter */
+    clearStorage(): Promise<boolean>;
+    /** Get storage statistics from the adapter */
+    getStorageStats(): Promise<{
+        totalSize: number;
+        keyCount: number;
+        [key: string]: unknown;
+    } | null>;
+    /**
+     * Navigate directly to a specific node by ID
+     * @param nodeId - The ID of the node to navigate to
+     * @throws \{QNCENavigationError\} When nodeId is invalid or not found
+     */
+    goToNodeById(nodeId: string): void;
+    /**
+     * Get the current narrative node
+     * @returns The current node object
+     */
+    getCurrentNode(): NarrativeNode;
+    /**
+     * Get available choices from the current node with validation and conditional filtering
+     * @returns Array of available choices
+     */
+    getAvailableChoices(): Choice[];
+    makeChoice(choiceIndex: number): void;
+    getState(): QNCEState;
+    getFlags(): Record<string, unknown>;
+    setFlag(key: string, value: unknown): void;
+    getHistory(): string[];
+    selectChoice(choice: Choice): void;
+    /** Register a hook */
+    registerHook(type: 'pre-choice', handler: PreChoiceHook, priority?: number): () => void;
+    registerHook(type: 'post-choice', handler: PostChoiceHook, priority?: number): () => void;
+    /** Clear all hooks (testing / reset) */
+    clearHooks(): void;
+    /** Enable verbose debug logging (stored in ring buffer) */
+    enableDebug(): void;
+    disableDebug(): void;
+    getDebugLogs(): DebugLogEntry[];
+    clearDebugLogs(): void;
+    /** Enable aggregated hot path profiling */
+    enableHotProfiling(): void;
+    disableHotProfiling(): void;
+    getHotProfileSummary(): Record<string, {
+        count: number;
+        avgMs: number;
+        maxMs: number;
+    }>;
+    resetHotProfile(): void;
+    /** Flush telemetry (useful before process exit) */
+    flushTelemetry(): Promise<void>;
+    resetNarrative(): void;
+    /**
+     * Load simple state (legacy method for backward compatibility)
+     * @param state - QNCEState to load
+     */
+    loadSimpleState(state: QNCEState): void;
+    /**
+     * Save current engine state to a serialized format
+     * @param options - Serialization options
+     * @returns Promise resolving to serialized state
+     */
+    saveState(options?: SerializationOptions): Promise<SerializedState>;
+    /**
+     * Load engine state from serialized format
+     * @param serializedState - The serialized state to load
+     * @param options - Load options
+     * @returns Promise resolving to persistence result
+     */
+    loadState(serializedState: SerializedState, options?: LoadOptions): Promise<PersistenceResult>;
+    /**
+     * Create a lightweight checkpoint of current state
+     * @param name - Optional checkpoint name
+     * @param options - Checkpoint options
+     * @returns Promise resolving to created checkpoint
+     */
+    createCheckpoint(name?: string, options?: CheckpointOptions): Promise<Checkpoint>;
+    /**
+     * Restore engine state from a checkpoint
+     * @param checkpointId - ID of checkpoint to restore
+     * @returns Promise resolving to persistence result
+     */
+    restoreFromCheckpoint(checkpointId: string): Promise<PersistenceResult>;
+    checkFlag(flagName: string, expectedValue?: unknown): boolean;
+    /**
+     * Get the choice validator instance
+     * @returns The current choice validator
+     */
+    getChoiceValidator(): ChoiceValidator;
+    /**
+     * Validate a specific choice without executing it
+     * @param choice - The choice to validate
+     * @returns Validation result with details
+     */
+    validateChoice(choice: Choice): ValidationResult;
+    /**
+     * Check if a specific choice is valid without executing it
+     * @param choice - The choice to check
+     * @returns True if the choice is valid, false otherwise
+     */
+    isChoiceValid(choice: Choice): boolean;
+    /**
+     * Create a flow event using pooled objects for performance tracking
+     */
+    private createFlowEvent;
+    /**
+     * Record and manage flow events
+     */
+    private recordFlowEvent;
+    /**
+     * Get current flow events (for debugging/monitoring)
+     */
+    getActiveFlows(): FlowEvent[];
+    /**
+     * Get object pool statistics for performance monitoring
+     */
+    getPoolStats(): {
+        flows: {
+            poolSize: number;
+            maxSize: number;
+            created: number;
+            borrowed: number;
+            returned: number;
+            inUse: number;
+            hitRate: number;
+        };
+        nodes: {
+            poolSize: number;
+            maxSize: number;
+            created: number;
+            borrowed: number;
+            returned: number;
+            inUse: number;
+            hitRate: number;
+        };
+        assets: {
+            poolSize: number;
+            maxSize: number;
+            created: number;
+            borrowed: number;
+            returned: number;
+            inUse: number;
+            hitRate: number;
+        };
+    } | null;
+    /**
+     * Return all pooled objects (cleanup method)
+     */
+    private cleanupPools;
+    /**
+     * Preload next possible nodes in background using ThreadPool
+     */
+    preloadNextNodes(choice?: Choice): Promise<void>;
+    /**
+     * Write telemetry data in background using ThreadPool
+     */
+    backgroundTelemetryWrite(eventData: Record<string, unknown>): Promise<void>;
+    /**
+     * Enable advanced branching capabilities for this story
+     * Integrates the QNCE Branching API with the core engine
+     */
+    enableBranching(story: QNCEStory): QNCEBranchingEngine;
+    /**
+     * Get the branching engine if enabled
+     */
+    getBranchingEngine(): QNCEBranchingEngine | undefined;
+    /**
+     * Check if branching is enabled
+     */
+    isBranchingEnabled(): boolean;
+    /**
+     * Sync core engine state with branching engine
+     * Call this when core state changes to keep branching engine updated
+     */
+    syncBranchingState(): void;
+    /**
+     * Disable branching and cleanup resources
+     */
+    disableBranching(): void;
+    /**
+     * Background cache warming for story data
+     */
+    warmCache(): Promise<void>;
+    /**
+     * Deep copy utility for state objects
+     * @param obj - Object to deep copy
+     * @returns Deep copied object
+     */
+    private deepCopy;
+    /**
+     * Generate a hash for the current story data
+     * @returns Story hash string
+     */
+    private generateStoryHash;
+    /**
+     * Generate a unique checkpoint ID
+     * @returns Unique checkpoint ID
+     */
+    private generateCheckpointId;
+    /**
+     * Generate checksum for data integrity
+     * @param data - Data to generate checksum for
+     * @returns Promise resolving to checksum string
+     */
+    private generateChecksum;
+    /**
+     * Verify checksum integrity
+     * @param serializedState - State with checksum to verify
+     * @returns Promise resolving to verification result
+     */
+    private verifyChecksum;
+    /**
+     * Validate the structure of the serialized state object
+     * @param serializedState - State to validate
+     * @returns Validation result
+     */
+    private validateSerializedState;
+    /**
+     * Check version compatibility
+     * @param metadata - Serialization metadata
+     * @returns Compatibility check result
+     */
+    private checkCompatibility;
+    /**
+     * Cleanup old checkpoints based on strategy
+     * @param strategy - Cleanup strategy
+     * @param maxCheckpoints - Maximum number of checkpoints to keep
+     * @returns Promise resolving to number of cleaned checkpoints
+     */
+    private cleanupCheckpoints;
+    /**
+     * Get all checkpoints
+     * @returns Array of all checkpoints
+     */
+    getCheckpoints(): Checkpoint[];
+    /**
+     * Get specific checkpoint by ID
+     * @param id - Checkpoint ID
+     * @returns Checkpoint or undefined
+     */
+    getCheckpoint(id: string): Checkpoint | undefined;
+    /**
+     * Delete a checkpoint
+     * @param id - Checkpoint ID to delete
+     * @returns Whether checkpoint was deleted
+     */
+    deleteCheckpoint(id: string): boolean;
+    /**
+     * Enable/disable automatic checkpointing
+     * @param enabled - Whether to enable auto-checkpointing
+     */
+    setAutoCheckpoint(enabled: boolean): void;
+    /**
+     * Configure autosave settings
+     * @param config - Autosave configuration
+     */
+    configureAutosave(config: Partial<AutosaveConfig>): void;
+    /**
+     * Configure undo/redo settings
+     * @param config - Undo/redo configuration
+     */
+    configureUndoRedo(config: Partial<UndoRedoConfig>): void;
+    /**
+     * Push a state to the undo stack
+     * @param state - State to save
+     * @param action - Action that caused this state change
+     * @param metadata - Optional metadata about the change
+     */
+    private pushToUndoStack;
+    /**
+     * Undo the last operation
+     * @returns Result of undo operation
+     */
+    undo(): UndoRedoResult_2;
+    /**
+     * Redo the last undone operation
+     * @returns Result of redo operation
+     */
+    redo(): UndoRedoResult_2;
+    /**
+     * Check if undo is available
+     * @returns True if undo is possible
+     */
+    canUndo(): boolean;
+    /**
+     * Check if redo is available
+     * @returns True if redo is possible
+     */
+    canRedo(): boolean;
+    /**
+     * Get the number of available undo operations
+     * @returns Number of undo entries
+     */
+    getUndoCount(): number;
+    /**
+     * Get the number of available redo operations
+     * @returns Number of redo entries
+     */
+    getRedoCount(): number;
+    /**
+     * Clear all undo/redo history
+     */
+    clearHistory(): void;
+    /**
+     * Get history summary for debugging
+     * @returns Summary of undo/redo history
+     */
+    getHistorySummary(): {
+        undoEntries: {
+            id: string;
+            timestamp: string;
+            action?: string;
+        }[];
+        redoEntries: {
+            id: string;
+            timestamp: string;
+            action?: string;
+        }[];
+    };
+    /**
+     * Trigger an autosave operation
+     * @param trigger - What triggered the autosave
+     * @param metadata - Optional metadata about the trigger
+     * @returns Promise resolving to autosave result
+     */
+    private triggerAutosave;
+    /**
+     * Manually trigger an autosave
+     * @param metadata - Optional metadata
+     * @returns Promise resolving to autosave result
+     */
+    manualAutosave(metadata?: Record<string, unknown>): Promise<AutosaveResult>;
+    /**
+     * Generate a unique history entry ID
+     * @returns Unique ID string
+     */
+    private generateHistoryId;
+    /**
+     * Set a custom condition evaluator function for complex choice logic
+     * @param evaluator - Custom evaluator function
+     */
+    setConditionEvaluator(evaluator: CustomEvaluatorFunction): void;
+    /**
+     * Clear the custom condition evaluator
+     */
+    clearConditionEvaluator(): void;
+    /**
+     * Validate a condition expression without evaluating it
+     * @param expression - Condition expression to validate
+     * @returns Validation result
+     */
+    validateCondition(expression: string): {
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * Get flags referenced in a condition expression
+     * @param expression - Condition expression to analyze
+     * @returns Array of flag names referenced
+     */
+    getConditionFlags(expression: string): string[];
+}
+
+/**
+ * Base class for all QNCE-specific errors
+ * @public
+ */
+declare class QNCEError extends Error {
+    readonly errorCode: string;
+    readonly timestamp: number;
+    readonly metadata?: Record<string, unknown>;
+    constructor(message: string, errorCode: string, metadata?: Record<string, unknown>);
+}
+
+/** Standardized context captured with every structured error */
+/** @public */
+export declare interface QNCEErrorContext {
+    storyId?: string;
+    nodeId?: string;
+    fromNodeId?: string;
+    toNodeId?: string;
+    choiceText?: string;
+    hookStage?: HookStage;
+    adapter?: string;
+    operation?: string;
+    conditionExpression?: string;
+    flagKey?: string;
+    flagValue?: unknown;
+    serialized?: boolean;
+    retryable?: boolean;
+    cause?: unknown;
+    [extra: string]: unknown;
+}
+
+/** @public */
+export declare type QNCEErrorKind = 'navigation' | 'choice-validation' | 'story-data' | 'state' | 'hook' | 'condition' | 'persistence' | 'telemetry' | 'adapter' | 'unknown';
+
+/**
+ * Error thrown when navigation to a node fails
+ * Used by goToNodeById() and related navigation methods
+ * @public
+ */
+export declare class QNCENavigationError extends QNCEError {
+    readonly nodeId?: string;
+    constructor(message: string, nodeId?: string, metadata?: Record<string, unknown>);
+}
+
+/** Serializable engine state snapshot */
+/** @public */
+export declare interface QNCEState {
+    currentNodeId: string;
+    flags: Record<string, unknown>;
+    history: string[];
+}
+
+/**
+ * Top-level story container with branching metadata
+ * @public
+ */
+export declare interface QNCEStory {
+    id: string;
+    title: string;
+    version: string;
+    metadata: StoryMetadata;
+    chapters: Chapter[];
+    branchingConfig: BranchingConfig;
+}
+
+/**
+ * Theme configuration for QNCE UI components
+ * @public
+ */
+export declare interface QNCETheme {
+    colors: {
+        primary: string;
+        secondary: string;
+        success: string;
+        warning: string;
+        error: string;
+        disabled: string;
+        background: string;
+        surface: string;
+        text: string;
+        textSecondary: string;
+    };
+    spacing: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+    };
+    borderRadius: {
+        sm: string;
+        md: string;
+        lg: string;
+    };
+    typography: {
+        fontFamily: string;
+        fontSize: {
+            sm: string;
+            md: string;
+            lg: string;
+        };
+        fontWeight: {
+            normal: number;
+            medium: number;
+            semibold: number;
+        };
+    };
+    shadows: {
+        sm: string;
+        md: string;
+        lg: string;
+    };
+}
+
+/** @beta @experimental */
+export declare type QuantumIntegration = {
+    isPhaseActive: (phase: Phase, ctx?: {
+        nodeId?: string;
+    }) => boolean;
+    entangle: (configure: (e: Entangler) => Entangler) => void;
+    detach: () => void;
+    flags: FeatureFlags;
+};
+
+/** @beta @experimental */
+export declare type Sampler = (ctx: MeasurementContext) => boolean | number;
+
+/**
+ * Metadata about the serialization process and compatibility
+ */
+declare interface SerializationMetadata {
+    /** Engine version that created this serialized state */
+    engineVersion: string;
+    /** Timestamp when the state was serialized (ISO string) */
+    timestamp: string;
+    /** Story identifier/hash for compatibility checking */
+    storyId?: string;
+    /** Custom metadata for application-specific use */
+    customMetadata?: Record<string, unknown>;
+    /** Compression level used (if any) */
+    compression?: 'none' | 'gzip' | 'lz4';
+    /** Checksum for integrity verification */
+    checksum?: string;
+}
+
+/**
+ * Options for state serialization
+ */
+declare interface SerializationOptions {
+    /** Include performance data in serialization */
+    includePerformanceData?: boolean;
+    /** Include flow events in serialization */
+    includeFlowEvents?: boolean;
+    /** Include branching context */
+    includeBranchingContext?: boolean;
+    /** Include validation state */
+    includeValidationState?: boolean;
+    /** Compression to apply */
+    compression?: 'none' | 'gzip' | 'lz4';
+    /** Generate integrity checksum */
+    generateChecksum?: boolean;
+    /** Custom metadata to include */
+    customMetadata?: Record<string, unknown>;
+    /** Pretty print JSON (increases size but improves readability) */
+    prettyPrint?: boolean;
+}
+
+/**
+ * Complete serialized state that can be saved/restored
+ * Includes all necessary data to fully reconstruct engine state
+ */
+declare interface SerializedState {
+    /** Core narrative state (current node, flags, history) */
+    state: QNCEState;
+    /** Active flow events for performance tracking */
+    flowEvents: FlowEvent[];
+    /** Performance and pool statistics snapshot */
+    poolStats?: Record<string, unknown>;
+    /** Branching context and branch state */
+    branchingContext?: {
+        activeBranches: string[];
+        branchStates: Record<string, unknown>;
+        convergencePoints: string[];
+    };
+    /** Validation state and rule overrides */
+    validationState?: {
+        disabledRules: string[];
+        customRules: Record<string, unknown>;
+        validationErrors: string[];
+    };
+    /** Thread pool and background operation state */
+    performanceState?: {
+        performanceMode: boolean;
+        enableProfiling: boolean;
+        backgroundTasks: string[];
+        telemetryData: Record<string, unknown>[];
+    };
+    /** Serialization metadata */
+    metadata: SerializationMetadata;
+}
+
+/** Serialize a structured error into a safe plain object for logging or transport */
+/** @public */
+export declare function serializeStructuredError(struct: StructuredQNCEError): {
+    code: string;
+    kind: QNCEErrorKind;
+    message: string;
+    timestamp: number;
+    context: {
+        cause: undefined;
+        storyId?: string;
+        nodeId?: string;
+        fromNodeId?: string;
+        toNodeId?: string;
+        choiceText?: string;
+        hookStage?: HookStage;
+        adapter?: string;
+        operation?: string;
+        conditionExpression?: string;
+        flagKey?: string;
+        flagValue?: unknown;
+        serialized?: boolean;
+        retryable?: boolean;
+    };
+    stack: string | undefined;
+};
+
+/**
+ * Storage adapter interface for different persistence backends
+ */
+declare interface StorageAdapter {
+    /** Save serialized state */
+    save(key: string, data: SerializedState, options?: SerializationOptions): Promise<PersistenceResult>;
+    /** Load serialized state */
+    load(key: string, options?: LoadOptions): Promise<SerializedState | null>;
+    /** Delete stored state */
+    delete(key: string): Promise<boolean>;
+    /** List all stored keys */
+    list(): Promise<string[]>;
+    /** Check if key exists */
+    exists(key: string): Promise<boolean>;
+    /** Get storage statistics */
+    getStats(): Promise<{
+        totalSize: number;
+        keyCount: number;
+        [key: string]: unknown;
+    }>;
+    /** Clear all stored data */
+    clear(): Promise<boolean>;
+}
+
+/** Full story data input structure */
+/** @public */
+export declare interface StoryData {
+    nodes: NarrativeNode[];
+    initialNodeId: string;
+}
+
+declare interface StoryMetadata {
+    author: string;
+    description: string;
+    tags: string[];
+    createDate: Date;
+    lastModified: Date;
+    estimatedPlaytime: number;
+}
+
+/** Shape returned by factory functions */
+/** @public */
+export declare interface StructuredQNCEError {
+    error: QNCEError;
+    kind: QNCEErrorKind;
+    code: string;
+    message: string;
+    timestamp: number;
+    context: QNCEErrorContext;
+}
+
+/**
+ * Public telemetry facade used by engine and consumers
+ * @beta
+ * @experimental
+ */
+export declare interface Telemetry {
+    configure(opts: Partial<TelemetryOptions>): void;
+    emit<T extends string, P>(event: QEvent<T, P>): void;
+    flush(): Promise<void>;
+    stats(): {
+        queued: number;
+        dropped: number;
+        sent: number;
+        lastFlushTs: number | null;
+        p50?: number;
+        p95?: number;
+    };
+    dispose(): Promise<void>;
+}
+
+/**
+ * Adapter contract for delivering batched telemetry events
+ * @beta
+ * @experimental
+ */
+export declare interface TelemetryAdapter {
+    configure?(opts: Record<string, unknown>): void;
+    send(batch: QEvent[]): Promise<void>;
+    flush?(): Promise<void>;
+    dispose?(): Promise<void>;
+}
+
+/**
+ * Configuration options for telemetry system
+ * @beta
+ * @experimental
+ */
+export declare interface TelemetryOptions {
+    adapter: TelemetryAdapter;
+    sampleRate?: number;
+    maxQueue?: number;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    onDrop?: (reason: 'queue_full' | 'filter') => void;
+    enabled?: boolean;
+    defaultCtx?: Partial<QEvent['ctx']>;
+    sampleSeed?: number;
+    /** Overflow strategy when queue is full (default 'drop') */
+    overflowStrategy?: 'drop' | 'drop-oldest' | 'error';
+}
+
+declare interface ThreadPoolConfig {
+    maxWorkers: number;
+    queueLimit: number;
+    idleTimeout: number;
+    enableProfiling: boolean;
+}
+
+/** Try to unwrap unknown thrown values into a structured error (best effort) */
+/** @public */
+export declare function toStructuredError(input: unknown, fallbackMessage?: string): StructuredQNCEError;
+
+/**
+ * Entangler primitive for declarative variable binding
+ * @beta
+ * @experimental
+ */
+declare type TransformFn = (value: unknown) => unknown;
+
+/**
+ * Configuration for undo/redo history
+ */
+declare interface UndoRedoConfig {
+    /** Whether undo/redo is enabled */
+    enabled: boolean;
+    /** Maximum number of undo entries to keep */
+    maxUndoEntries: number;
+    /** Maximum number of redo entries to keep */
+    maxRedoEntries: number;
+    /** Whether to track flag changes for undo metadata */
+    trackFlagChanges: boolean;
+    /** Whether to track choice text for undo metadata */
+    trackChoiceText: boolean;
+    /** Actions that should create undo entries */
+    trackActions: ('choice' | 'flag-change' | 'state-load' | 'reset' | 'custom')[];
+}
+
+/**
+ * UndoRedoControls Component
+ *
+ * Provides accessible undo/redo buttons with real-time state updates,
+ * tooltips, keyboard support, and customizable theming.
+ *
+ * Features:
+ * - Real-time enable/disable based on undo/redo availability
+ * - Accessible with ARIA labels and keyboard navigation
+ * - Customizable themes and layouts
+ * - Integration with QNCE Engine undo/redo system
+ * @public
+ */
+export declare const UndoRedoControls: React_2.FC<UndoRedoControlsProps>;
+
+/**
+ * Props for UndoRedoControls component
+ * @public
+ */
+export declare interface UndoRedoControlsProps {
+    /** QNCE Engine instance */
+    engine: QNCEEngine;
+    /** Custom theme (optional, uses default if not provided) */
+    theme?: Partial<QNCETheme>;
+    /** Additional CSS class name */
+    className?: string;
+    /** Custom styling */
+    style?: React.CSSProperties;
+    /** Disable the controls */
+    disabled?: boolean;
+    /** Show labels on buttons */
+    showLabels?: boolean;
+    /** Custom button labels */
+    labels?: {
+        undo: string;
+        redo: string;
+    };
+    /** Button size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Button layout */
+    layout?: 'horizontal' | 'vertical';
+    /** Callback when undo is performed */
+    onUndo?: (result: {
+        success: boolean;
+        description?: string;
+        error?: string;
+    }) => void;
+    /** Callback when redo is performed */
+    onRedo?: (result: {
+        success: boolean;
+        description?: string;
+        error?: string;
+    }) => void;
+}
+
+/**
+ * Result type for undo/redo operations
+ * @public
+ */
+export declare interface UndoRedoResult {
+    success: boolean;
+    description?: string;
+    error?: string;
+}
+
+/**
+ * Result of undo/redo operations
+ */
+declare interface UndoRedoResult_2 {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Error message if operation failed */
+    error?: string;
+    /** The state that was restored */
+    restoredState?: QNCEState;
+    /** Information about the restored entry */
+    entry?: {
+        id: string;
+        timestamp: string;
+        action?: string;
+        nodeId?: string;
+    };
+    /** Current undo/redo stack sizes after operation */
+    stackSizes?: {
+        undoCount: number;
+        redoCount: number;
+    };
+}
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+/**
+ * React hook enabling autosave behavior with throttle and event triggers.
+ * @public
+ */
+export declare function useAutosave(engine: QNCEEngine, config?: {
+    throttleMs?: number;
+    triggers?: ('choice' | 'flag-change' | 'state-load' | 'branch-exit' | 'custom')[];
+    enabled?: boolean;
+}): {
+    autosave: () => Promise<void>;
+    configure: (config: Partial<AutosaveConfig>) => void;
+    isEnabled: boolean;
+    lastAutosave: Date | null;
+    isSaving: boolean;
+};
+
+/**
+ * useKeyboardShortcuts Hook
+ *
+ * Provides keyboard shortcuts for common QNCE operations like undo/redo and autosave.
+ *
+ * Features:
+ * - Configurable key bindings
+ * - Support for modifier keys (Ctrl, Alt, Shift, Meta)
+ * - Automatic cleanup on unmount
+ * - Prevention of default browser behavior
+ * - Accessibility-friendly implementation
+ *
+ * Default shortcuts:
+ * - Ctrl+Z / Cmd+Z: Undo
+ * - Ctrl+Y / Cmd+Y / Ctrl+Shift+Z: Redo
+ * - Ctrl+S / Cmd+S: Manual autosave
+ * - Ctrl+R / Cmd+R: Reset narrative (disabled by default)
+ * @public
+ */
+export declare function useKeyboardShortcuts(engine: QNCEEngine, config?: KeyboardShortcutsConfig): 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>
+ *   );
+ * }
+ * ```
+ */
+/** React integration hook for QNCE engine */
+/** @public */
+/** React integration hook for QNCE engine
+ * @public
+ */
+export declare function useQNCE(engine: QNCEEngine, config?: UseQNCEConfig): UseQNCEReturn;
+
+/**
+ * Configuration for the useQNCE hook
+ * @public
+ */
+export declare 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
+ * @public
+ */
+export declare interface UseQNCEReturn {
+    engine: QNCEEngine;
+    currentNode: NarrativeNode | null;
+    availableChoices: Choice[];
+    flags: Record<string, unknown>;
+    selectChoice: (choice: Choice | string) => Promise<void>;
+    setFlag: (key: string, value: unknown) => 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;
+}
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+/**
+ * React hook providing undo/redo state and actions for a QNCE engine instance.
+ * @public
+ */
+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;
+};
+
+/**
+ * Validation context containing all state needed for choice validation
+ */
+declare interface ValidationContext {
+    currentNode: NarrativeNode;
+    state: QNCEState;
+    availableChoices: Choice[];
+    timestamp?: number;
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result of choice validation with detailed information
+ */
+declare interface ValidationResult {
+    isValid: boolean;
+    reason?: string;
+    failedConditions?: string[];
+    suggestedChoices?: Choice[];
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Choice validation rule interface for extensible validation logic
+ */
+declare interface ValidationRule {
+    name: string;
+    priority: number;
+    validate(choice: Choice, context: ValidationContext): ValidationResult;
+}
+
+export { }