qnce-engine 0.1.0 → 1.2.1

package/dist/examples/src/engine/demo-story.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEMO_STORY = void 0;
+// Demo narrative data for QNCE Engine
+exports.DEMO_STORY = {
+    initialNodeId: 'start',
+    nodes: [
+        {
+            id: 'start',
+            text: 'You stand at a crossroads in an ancient land. Mysterious energy flows through the air. Do you go left or right?',
+            choices: [
+                { text: 'Left', nextNodeId: 'river', flagEffects: { wentLeft: true, curiosity: 1 } },
+                { text: 'Right', nextNodeId: 'mountain', flagEffects: { wentLeft: false, courage: 1 } },
+            ],
+        },
+        {
+            id: 'river',
+            text: 'You encounter a rushing river. The water sparkles with an otherworldly light. Do you swim or build a raft?',
+            choices: [
+                { text: 'Swim', nextNodeId: 'swim', flagEffects: { gotWet: true, courage: 2 } },
+                { text: 'Build a raft', nextNodeId: 'raft', flagEffects: { gotWet: false, patience: 1 } },
+                {
+                    text: 'Use magic to cross (requires curiosity)',
+                    nextNodeId: 'magical_crossing',
+                    flagEffects: { usedMagic: true, magicPower: 1 },
+                    condition: 'flags.curiosity >= 1'
+                },
+            ],
+        },
+        {
+            id: 'mountain',
+            text: 'You find a towering mountain shrouded in mist. Ancient runes glow faintly on its slopes. Do you climb or go around?',
+            choices: [
+                { text: 'Climb', nextNodeId: 'climb', flagEffects: { climbed: true, courage: 2 } },
+                { text: 'Go around', nextNodeId: 'village', flagEffects: { climbed: false, patience: 1 } },
+                {
+                    text: 'Study the runes (requires courage)',
+                    nextNodeId: 'rune_study',
+                    flagEffects: { studiedRunes: true, knowledge: 2 },
+                    condition: 'flags.courage >= 1'
+                }
+            ],
+        },
+        // --- Expanded Narrative Branches ---
+        {
+            id: 'magical_crossing',
+            text: 'You focus your energy and step onto the water\'s surface. It holds! You walk across safely, your magical abilities awakened.',
+            choices: [
+                { text: 'Continue to the mystical grove', nextNodeId: 'mystical_grove', flagEffects: { discoveredGrove: true } },
+            ],
+        },
+        {
+            id: 'rune_study',
+            text: 'The runes reveal ancient secrets of power. You feel wisdom flowing through you.',
+            choices: [
+                { text: 'Ascend the mountain with new knowledge', nextNodeId: 'peak_ascension', flagEffects: { enlightened: true } },
+            ],
+        },
+        {
+            id: 'swim',
+            text: 'You swim across and reach the other side, but you are soaked and cold. Ahead, you see a cave and a campfire.',
+            choices: [
+                { text: 'Warm up by the campfire', nextNodeId: 'campfire', flagEffects: { warmedUp: true } },
+                { text: 'Explore the cave', nextNodeId: 'cave', flagEffects: { exploredCave: true, curiosity: 1 } },
+                {
+                    text: 'Use magic to dry yourself (requires magic power)',
+                    nextNodeId: 'magical_warmth',
+                    flagEffects: { magicallyDried: true },
+                    condition: 'flags.magicPower >= 1'
+                }
+            ],
+        },
+        {
+            id: 'raft',
+            text: 'You build a raft and float safely. On the far bank, a merchant greets you.',
+            choices: [
+                { text: 'Trade with the merchant', nextNodeId: 'merchant', flagEffects: { metMerchant: true } },
+                { text: 'Ignore and continue', nextNodeId: 'forest', flagEffects: { metMerchant: false } },
+            ],
+        },
+        {
+            id: 'climb',
+            text: 'You climb and see a vast land. The wind is strong. Do you signal for help or descend?',
+            choices: [
+                { text: 'Signal for help', nextNodeId: 'signal', flagEffects: { signaled: true } },
+                { text: 'Descend', nextNodeId: 'forest', flagEffects: { signaled: false } },
+            ],
+        },
+        {
+            id: 'village',
+            text: 'You go around and find a village. The villagers are wary. Do you introduce yourself or sneak past?',
+            choices: [
+                { text: 'Introduce yourself', nextNodeId: 'welcome', flagEffects: { welcomed: true } },
+                { text: 'Sneak past', nextNodeId: 'forest', flagEffects: { welcomed: false } },
+            ],
+        },
+        // --- New Unique Outcomes & Entanglement ---
+        {
+            id: 'campfire',
+            text: 'You warm up by the fire. A traveler offers you advice. (Success!)',
+            choices: [],
+        },
+        {
+            id: 'cave',
+            text: 'Inside the cave, you find ancient markings. Suddenly, you slip and must return to the river bank. (Loop)',
+            choices: [
+                { text: 'Return to river', nextNodeId: 'river', flagEffects: { slipped: true } },
+            ],
+        },
+        {
+            id: 'merchant',
+            text: 'The merchant gives you a mysterious key. (Reward!)',
+            choices: [],
+        },
+        {
+            id: 'forest',
+            text: 'You enter a dense forest. The trees whisper ancient secrets. Multiple paths reveal themselves based on your journey.',
+            choices: [
+                {
+                    text: 'Use the merchant\'s key (if you have it)',
+                    nextNodeId: 'shortcut',
+                    flagEffects: { usedKey: true },
+                    condition: 'flags.metMerchant'
+                },
+                { text: 'Push through the forest', nextNodeId: 'lost', flagEffects: { usedKey: false } },
+                {
+                    text: 'Seek guidance from the spirits (requires wisdom)',
+                    nextNodeId: 'spirit_guidance',
+                    flagEffects: { talkedToSpirits: true },
+                    condition: 'flags.knowledge >= 2 || flags.studiedRunes'
+                },
+                {
+                    text: 'Use enhanced senses (requires multiple experiences)',
+                    nextNodeId: 'enhanced_path',
+                    flagEffects: { usedSenses: true },
+                    condition: 'flags.curiosity >= 1 && flags.courage >= 1'
+                }
+            ],
+        },
+        {
+            id: 'signal',
+            text: 'Your signal is seen! A rescue party arrives. (Success!)',
+            choices: [],
+        },
+        {
+            id: 'welcome',
+            text: 'The villagers welcome you and offer food. (Success!)',
+            choices: [],
+        },
+        {
+            id: 'shortcut',
+            text: 'You use the key to unlock a hidden path and escape the forest. (Success!)',
+            choices: [],
+        },
+        {
+            id: 'lost',
+            text: 'You get lost in the forest. The paths seem to shift and change around you.',
+            choices: [
+                { text: 'Try to find your way back', nextNodeId: 'forest', flagEffects: { triedAgain: true } },
+                {
+                    text: 'Meditate and center yourself (requires patience)',
+                    nextNodeId: 'inner_peace',
+                    flagEffects: { foundPeace: true },
+                    condition: 'flags.patience >= 1'
+                }
+            ],
+        },
+        // --- New Conditional Ending Nodes ---
+        {
+            id: 'mystical_grove',
+            text: 'You discover a hidden grove where time seems to stand still. This is a sacred place of great power. (Magical Success!)',
+            choices: [],
+        },
+        {
+            id: 'peak_ascension',
+            text: 'With ancient knowledge guiding you, you reach the mountain\'s peak and unlock the secrets of the realm. (Enlightened Success!)',
+            choices: [],
+        },
+        {
+            id: 'magical_warmth',
+            text: 'Your magic flows through you, instantly drying your clothes and warming your body. You feel your power growing stronger. (Magical Mastery!)',
+            choices: [],
+        },
+        {
+            id: 'spirit_guidance',
+            text: 'The forest spirits, impressed by your wisdom, guide you to a hidden sanctuary. (Spiritual Success!)',
+            choices: [],
+        },
+        {
+            id: 'enhanced_path',
+            text: 'Your varied experiences have heightened your senses. You navigate the forest with ease and discover a treasure trove. (Master Explorer Success!)',
+            choices: [],
+        },
+        {
+            id: 'inner_peace',
+            text: 'Through meditation, you find inner peace and the forest reveals its true beauty. You emerge transformed. (Peaceful Resolution!)',
+            choices: [],
+        },
+    ],
+};

package/dist/examples/src/engine/types.js

@@ -0,0 +1,8 @@
+"use strict";
+// QNCE Engine Types - Sprint 3.3: State Persistence & Checkpoints
+// Comprehensive type definitions for serialization and checkpoint features
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_VERSIONS = exports.PERSISTENCE_VERSION = void 0;
+// Version constants
+exports.PERSISTENCE_VERSION = '1.0.0';
+exports.SUPPORTED_VERSIONS = ['1.0.0'];

package/dist/examples/src/index.js

@@ -0,0 +1,35 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.conditionEvaluator = exports.ConditionEvaluationError = exports.ConditionEvaluator = exports.loadStoryData = exports.createQNCEEngine = exports.QNCEEngine = exports.DEMO_STORY = void 0;
+// QNCE Engine - Main Export
+__exportStar(require("./engine/core.js"), exports);
+var demo_story_js_1 = require("./engine/demo-story.js");
+Object.defineProperty(exports, "DEMO_STORY", { enumerable: true, get: function () { return demo_story_js_1.DEMO_STORY; } });
+// Sprint 3.4: Conditional choice display exports
+__exportStar(require("./engine/condition.js"), exports);
+// Sprint 3.5: React integration for autosave/undo functionality
+__exportStar(require("./integrations/react.js"), exports);
+// Re-export for convenience
+var core_js_1 = require("./engine/core.js");
+Object.defineProperty(exports, "QNCEEngine", { enumerable: true, get: function () { return core_js_1.QNCEEngine; } });
+Object.defineProperty(exports, "createQNCEEngine", { enumerable: true, get: function () { return core_js_1.createQNCEEngine; } });
+Object.defineProperty(exports, "loadStoryData", { enumerable: true, get: function () { return core_js_1.loadStoryData; } });
+// Sprint 3.4: Conditional choice types
+var condition_js_1 = require("./engine/condition.js");
+Object.defineProperty(exports, "ConditionEvaluator", { enumerable: true, get: function () { return condition_js_1.ConditionEvaluator; } });
+Object.defineProperty(exports, "ConditionEvaluationError", { enumerable: true, get: function () { return condition_js_1.ConditionEvaluationError; } });
+Object.defineProperty(exports, "conditionEvaluator", { enumerable: true, get: function () { return condition_js_1.conditionEvaluator; } });

package/dist/examples/src/integrations/react.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useQNCE = useQNCE;
+exports.useUndoRedo = useUndoRedo;
+exports.useAutosave = useAutosave;
+const react_1 = require("react");
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+function useQNCE(engine, config = {}) {
+    const { autoUpdate = true, enableUndoRedo = true, maxUndoEntries = 50, maxRedoEntries = 25, enableAutosave = true, autosaveThrottleMs = 100 } = config;
+    // Force re-render counter
+    const [, setUpdateCounter] = (0, react_1.useState)(0);
+    // Initialize engine configuration
+    (0, react_1.useEffect)(() => {
+        if (enableUndoRedo) {
+            engine.configureUndoRedo({
+                enabled: true,
+                maxUndoEntries,
+                maxRedoEntries
+            });
+        }
+        if (enableAutosave) {
+            engine.configureAutosave({
+                enabled: true,
+                throttleMs: autosaveThrottleMs,
+                triggers: ['choice', 'flag-change', 'state-load']
+            });
+        }
+    }, [engine, enableUndoRedo, maxUndoEntries, maxRedoEntries, enableAutosave, autosaveThrottleMs]);
+    // Force re-render when autoUpdate is enabled
+    const refresh = (0, react_1.useCallback)(() => {
+        if (autoUpdate) {
+            setUpdateCounter(prev => prev + 1);
+        }
+    }, [autoUpdate]);
+    // Memoized state getters
+    const currentNode = (0, react_1.useMemo)(() => {
+        try {
+            return engine.getCurrentNode();
+        }
+        catch {
+            return null;
+        }
+    }, [engine, autoUpdate]);
+    const availableChoices = (0, react_1.useMemo)(() => {
+        try {
+            return engine.getAvailableChoices();
+        }
+        catch {
+            return [];
+        }
+    }, [engine, autoUpdate]);
+    const flags = (0, react_1.useMemo)(() => {
+        return engine.getState().flags;
+    }, [engine, autoUpdate]);
+    // Undo/Redo state
+    const canUndo = (0, react_1.useMemo)(() => engine.canUndo(), [engine, autoUpdate]);
+    const canRedo = (0, react_1.useMemo)(() => engine.canRedo(), [engine, autoUpdate]);
+    const undoCount = (0, react_1.useMemo)(() => engine.getUndoCount(), [engine, autoUpdate]);
+    const redoCount = (0, react_1.useMemo)(() => engine.getRedoCount(), [engine, autoUpdate]);
+    // Actions with automatic refresh
+    const selectChoice = (0, react_1.useCallback)(async (choice) => {
+        let choiceToSelect;
+        if (typeof choice === 'string') {
+            // Find choice by text
+            const foundChoice = availableChoices.find(c => c.text === choice);
+            if (!foundChoice) {
+                throw new Error(`Choice not found: ${choice}`);
+            }
+            choiceToSelect = foundChoice;
+        }
+        else {
+            choiceToSelect = choice;
+        }
+        engine.selectChoice(choiceToSelect);
+        refresh();
+    }, [engine, refresh, availableChoices]);
+    const setFlag = (0, react_1.useCallback)((key, value) => {
+        engine.setFlag(key, value);
+        refresh();
+    }, [engine, refresh]);
+    const resetNarrative = (0, react_1.useCallback)(() => {
+        engine.resetNarrative();
+        refresh();
+    }, [engine, refresh]);
+    const undo = (0, react_1.useCallback)(() => {
+        const result = engine.undo();
+        refresh();
+        return result;
+    }, [engine, refresh]);
+    const redo = (0, react_1.useCallback)(() => {
+        const result = engine.redo();
+        refresh();
+        return result;
+    }, [engine, refresh]);
+    const clearHistory = (0, react_1.useCallback)(() => {
+        engine.clearHistory();
+        refresh();
+    }, [engine, refresh]);
+    const autosave = (0, react_1.useCallback)(async () => {
+        await engine.manualAutosave();
+    }, [engine]);
+    const configureAutosave = (0, react_1.useCallback)((config) => {
+        engine.configureAutosave(config);
+    }, [engine]);
+    const saveState = (0, react_1.useCallback)(async () => {
+        return await engine.saveState();
+    }, [engine]);
+    const loadState = (0, react_1.useCallback)(async (serializedState) => {
+        await engine.loadState(serializedState);
+        refresh();
+    }, [engine, refresh]);
+    return {
+        // Core state
+        engine,
+        currentNode,
+        availableChoices,
+        flags,
+        // Actions
+        selectChoice,
+        setFlag,
+        resetNarrative,
+        // Undo/Redo
+        undo,
+        redo,
+        canUndo,
+        canRedo,
+        undoCount,
+        redoCount,
+        clearHistory,
+        // Autosave
+        autosave,
+        configureAutosave,
+        // State management
+        saveState,
+        loadState,
+        // Utility
+        refresh
+    };
+}
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+function useUndoRedo(engine, config = {}) {
+    const { maxUndoEntries = 50, maxRedoEntries = 25 } = config;
+    const [, setUpdateCounter] = (0, react_1.useState)(0);
+    // Configure undo/redo on mount
+    (0, react_1.useEffect)(() => {
+        engine.configureUndoRedo({
+            enabled: true,
+            maxUndoEntries,
+            maxRedoEntries
+        });
+    }, [engine, maxUndoEntries, maxRedoEntries]);
+    const refresh = (0, react_1.useCallback)(() => {
+        setUpdateCounter(prev => prev + 1);
+    }, []);
+    const undo = (0, react_1.useCallback)(() => {
+        const result = engine.undo();
+        refresh();
+        return result;
+    }, [engine, refresh]);
+    const redo = (0, react_1.useCallback)(() => {
+        const result = engine.redo();
+        refresh();
+        return result;
+    }, [engine, refresh]);
+    const clearHistory = (0, react_1.useCallback)(() => {
+        engine.clearHistory();
+        refresh();
+    }, [engine, refresh]);
+    const canUndo = (0, react_1.useMemo)(() => engine.canUndo(), [engine]);
+    const canRedo = (0, react_1.useMemo)(() => engine.canRedo(), [engine]);
+    const undoCount = (0, react_1.useMemo)(() => engine.getUndoCount(), [engine]);
+    const redoCount = (0, react_1.useMemo)(() => engine.getRedoCount(), [engine]);
+    const historySummary = (0, react_1.useMemo)(() => ({
+        undoCount,
+        redoCount,
+        canUndo,
+        canRedo
+    }), [undoCount, redoCount, canUndo, canRedo]);
+    return {
+        undo,
+        redo,
+        canUndo,
+        canRedo,
+        undoCount,
+        redoCount,
+        clearHistory,
+        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>
+ *   );
+ * }
+ * ```
+ */
+function useAutosave(engine, config = {}) {
+    const { throttleMs = 100, triggers = ['choice', 'flag-change', 'state-load'], enabled = true } = config;
+    (0, react_1.useEffect)(() => {
+        engine.configureAutosave({
+            enabled,
+            throttleMs,
+            triggers: triggers
+        });
+    }, [engine, enabled, throttleMs, triggers]);
+    const autosave = (0, react_1.useCallback)(async () => {
+        await engine.manualAutosave();
+    }, [engine]);
+    const configure = (0, react_1.useCallback)((config) => {
+        engine.configureAutosave(config);
+    }, [engine]);
+    return {
+        autosave,
+        configure,
+        isEnabled: enabled
+    };
+}