qnce-engine 0.1.0 → 1.2.1

package/examples/persistence-demo.ts

@@ -0,0 +1,84 @@
+import { createQNCEEngine, DEMO_STORY } from '../src';
+import { Checkpoint } from '../src/engine/types';
+
+/**
+ * Demonstrates the state persistence and checkpoint features of the QNCE Engine.
+ * This example covers:
+ * 1. Saving the complete narrative state.
+ * 2. Loading that state into a new engine instance.
+ * 3. Creating lightweight checkpoints for undo/redo functionality.
+ * 4. Restoring the state from a checkpoint.
+ */
+async function runPersistenceDemo() {
+  console.log('🚀 Starting QNCE Engine Persistence Demo 🚀\n');
+
+  // 1. Initialize the engine and advance the story
+  const engine = createQNCEEngine(DEMO_STORY);
+  console.log('Initial Node:', engine.getCurrentNode().text);
+
+  let choices = engine.getAvailableChoices();
+  engine.selectChoice(choices[1]); // Choose "Examine the shimmering portal."
+  console.log('\nChoice Made. Current Node:', engine.getCurrentNode().text);
+
+  choices = engine.getAvailableChoices();
+  engine.selectChoice(choices[0]); // Choose "Step through the portal."
+  console.log('Choice Made. Current Node:', engine.getCurrentNode().text);
+  console.log('Current Flags:', engine.getFlags());
+
+  // 2. Create a checkpoint before making another choice
+  console.log('\n💾 Creating a checkpoint...');
+  const checkpoint = await engine.createCheckpoint('Before the final choice');
+  console.log(`Checkpoint '${checkpoint.name}' created with ID: ${checkpoint.id}`);
+
+  // 3. Save the complete engine state to a string
+  console.log('\n💾 Saving engine state to JSON...');
+  const savedState = await engine.saveState({ prettyPrint: true });
+  const savedStateJSON = JSON.stringify(savedState);
+  console.log('State saved successfully! Size:', savedStateJSON.length, 'bytes');
+  // In a real application, you would store this JSON string in localStorage,
+  // a file, or a remote database.
+
+  // 4. Continue the story
+  choices = engine.getAvailableChoices();
+  engine.selectChoice(choices[0]);
+  console.log('\nMade one more choice. Current Node:', engine.getCurrentNode().text);
+  console.log('Final Flags:', engine.getFlags());
+
+
+  // 5. Restore from the checkpoint to "undo" the last choice
+  console.log(`\n🔄 Restoring from checkpoint '${checkpoint.name}'...`);
+  await engine.restoreFromCheckpoint(checkpoint.id);
+  console.log('State restored from checkpoint!');
+  console.log('Current Node after restore:', engine.getCurrentNode().text);
+  console.log('Flags after restore:', engine.getFlags());
+
+
+  // 6. Create a new engine instance and load the saved state
+  console.log('\n🔄 Creating a new engine and loading the saved state...');
+  const newEngine = createQNCEEngine(DEMO_STORY);
+
+  // The state can be loaded from a JSON string or a parsed object
+  await newEngine.loadState(savedState);
+  console.log('State loaded into new engine instance!');
+
+  // 7. Verify that the state was restored correctly
+  console.log('\n🔍 Verifying restored state...');
+  console.log('Restored Node:', newEngine.getCurrentNode().text);
+  console.log('Restored Flags:', newEngine.getFlags());
+  console.log(
+    'History length:',
+    newEngine.getHistory().length,
+    '| Expected:',
+    2
+  );
+
+  const areFlagsEqual = JSON.stringify(engine.getFlags()) === JSON.stringify(newEngine.getFlags());
+  console.log('Verification successful:', areFlagsEqual);
+
+
+  console.log('\n✅ Persistence Demo Completed Successfully! ✅');
+}
+
+runPersistenceDemo().catch(error => {
+  console.error('An error occurred during the persistence demo:', error);
+});

package/examples/quickstart-demo.js

@@ -0,0 +1,82 @@
+// QNCE Branching Demo - JavaScript Quick Start
+// Demonstrates v1.2.0 Advanced Branching API integration
+
+const { createQNCEEngine } = require('../dist/engine/core');
+
+console.log('🚀 QNCE Engine v1.2.0 - Advanced Branching Demo');
+console.log('=================================================\n');
+
+// Create a simple story for demonstration
+const simpleStory = {
+  nodes: [
+    {
+      id: 'start',
+      text: 'You discover a mysterious quantum portal. What do you do?',
+      choices: [
+        {
+          text: 'Step through the portal',
+          nextNodeId: 'portal-world',
+          flagEffects: { courage: 5, portal_used: true }
+        },
+        {
+          text: 'Study the portal carefully',
+          nextNodeId: 'study-portal',
+          flagEffects: { wisdom: 5, careful: true }
+        }
+      ]
+    },
+    {
+      id: 'portal-world',
+      text: 'You emerge in a strange quantum realm where multiple realities overlap.',
+      choices: []
+    },
+    {
+      id: 'study-portal',
+      text: 'Your careful study reveals ancient quantum equations etched around the portal\'s edge.',
+      choices: []
+    }
+  ],
+  initialNodeId: 'start'
+};
+
+// Create the QNCE engine
+console.log('✅ Creating QNCE Engine...');
+const engine = createQNCEEngine(simpleStory);
+
+// Display current state
+console.log('📖 Current Story Node:');
+console.log('  ' + engine.getCurrentNode().text);
+
+console.log('\n🎯 Available Choices:');
+const choices = engine.getAvailableChoices();
+choices.forEach((choice, i) => {
+  console.log(`  ${i + 1}. ${choice.text}`);
+});
+
+// Make a choice automatically for demo
+if (choices.length > 0) {
+  console.log('\n🚀 Making choice: "' + choices[0].text + '"');
+  engine.selectChoice(choices[0]);
+  
+  console.log('\n📖 New Story Node:');
+  console.log('  ' + engine.getCurrentNode().text);
+  
+  console.log('\n🏴 Updated Flags:');
+  const flags = engine.getFlags();
+  Object.entries(flags).forEach(([key, value]) => {
+    console.log(`  ${key}: ${value}`);
+  });
+  
+  console.log('\n📚 Choice History:');
+  const history = engine.getHistory();
+  history.forEach((nodeId, i) => {
+    console.log(`  ${i + 1}. ${nodeId}`);
+  });
+}
+
+console.log('\n🎉 Demo Complete!');
+console.log('=================');
+console.log('✅ QNCE Engine v1.2.0 basic functionality working');
+console.log('📚 For advanced branching features, see TypeScript examples');
+console.log('🔗 Advanced features: AI generation, dynamic branches, analytics');
+console.log('\n🚀 Ready for your interactive narratives!');

package/examples/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "noEmit": true
+  },
+  "include": [
+    "./**/*",
+    "../src/**/*"
+  ]
+}

package/examples/ui-components-demo.tsx

@@ -0,0 +1,320 @@
+import React, { useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { 
+  createQNCEEngine, 
+  DEMO_STORY,
+  useQNCE,
+  UndoRedoControls,
+  AutosaveIndicator,
+  useKeyboardShortcuts
+} from '../src/index';
+
+/**
+ * QNCE Engine UI Components Demo
+ * Sprint 3.6: Demonstrates autosave indicators, undo/redo controls, and keyboard shortcuts
+ * 
+ * Features showcased:
+ * - UndoRedoControls component with different layouts and themes
+ * - AutosaveIndicator with various configurations
+ * - Keyboard shortcuts integration
+ * - Real-time state updates and visual feedback
+ * - Accessibility features
+ */
+
+const QNCEDemo: React.FC = () => {
+  const [engine] = useState(() => createQNCEEngine(DEMO_STORY));
+  const { currentNode, availableChoices, flags, selectChoice, resetNarrative } = useQNCE(engine);
+
+  // Enable keyboard shortcuts
+  useKeyboardShortcuts(engine, {
+    enabled: true,
+    bindings: {
+      undo: ['ctrl+z', 'cmd+z'],
+      redo: ['ctrl+y', 'cmd+y', 'ctrl+shift+z'],
+      save: ['ctrl+s', 'cmd+s'],
+      reset: ['ctrl+r'] // Enable reset with confirmation
+    }
+  });
+
+  const [showAdvanced, setShowAdvanced] = useState(false);
+
+  const appStyle: React.CSSProperties = {
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+    maxWidth: '800px',
+    margin: '0 auto',
+    padding: '2rem',
+    lineHeight: 1.6,
+    color: '#333'
+  };
+
+  const headerStyle: React.CSSProperties = {
+    textAlign: 'center',
+    marginBottom: '2rem',
+    padding: '1rem',
+    backgroundColor: '#f8f9fa',
+    borderRadius: '8px',
+    border: '1px solid #e9ecef'
+  };
+
+  const sectionStyle: React.CSSProperties = {
+    marginBottom: '2rem',
+    padding: '1rem',
+    backgroundColor: '#ffffff',
+    borderRadius: '8px',
+    border: '1px solid #e9ecef',
+    boxShadow: '0 2px 4px rgba(0,0,0,0.1)'
+  };
+
+  const narrativeStyle: React.CSSProperties = {
+    fontSize: '1.1rem',
+    lineHeight: 1.8,
+    marginBottom: '1rem',
+    padding: '1rem',
+    backgroundColor: '#f8f9fa',
+    borderLeft: '4px solid #007bff',
+    borderRadius: '0 4px 4px 0'
+  };
+
+  const choiceButtonStyle: React.CSSProperties = {
+    display: 'block',
+    width: '100%',
+    padding: '0.75rem 1rem',
+    margin: '0.5rem 0',
+    fontSize: '1rem',
+    backgroundColor: '#007bff',
+    color: 'white',
+    border: 'none',
+    borderRadius: '4px',
+    cursor: 'pointer',
+    transition: 'background-color 0.2s'
+  };
+
+  const controlsContainerStyle: React.CSSProperties = {
+    display: 'flex',
+    gap: '1rem',
+    alignItems: 'center',
+    flexWrap: 'wrap',
+    padding: '1rem',
+    backgroundColor: '#f8f9fa',
+    borderRadius: '8px',
+    marginBottom: '1rem'
+  };
+
+  const flagsStyle: React.CSSProperties = {
+    fontSize: '0.9rem',
+    color: '#6c757d',
+    backgroundColor: '#e9ecef',
+    padding: '0.5rem',
+    borderRadius: '4px',
+    fontFamily: 'monospace'
+  };
+
+  return (
+    <div style={appStyle}>
+      {/* Header */}
+      <header style={headerStyle}>
+        <h1>🎮 QNCE Engine UI Components Demo</h1>
+        <p>Sprint 3.6: Interactive showcase of autosave indicators, undo/redo controls, and keyboard shortcuts</p>
+        <p style={{ fontSize: '0.9rem', color: '#6c757d' }}>
+          <strong>Keyboard shortcuts:</strong> Ctrl/Cmd+Z (Undo), Ctrl/Cmd+Y (Redo), Ctrl/Cmd+S (Save)
+        </p>
+      </header>
+
+      {/* Controls Section */}
+      <section style={sectionStyle}>
+        <h2>🎛️ Controls & Status</h2>
+        <div style={controlsContainerStyle}>
+          {/* Autosave Indicator */}
+          <AutosaveIndicator 
+            engine={engine}
+            variant="detailed"
+            showTimestamp={true}
+            autoHideDelay={3000}
+          />
+
+          {/* Undo/Redo Controls - Horizontal Layout */}
+          <UndoRedoControls
+            engine={engine}
+            size="md"
+            layout="horizontal"
+            showLabels={true}
+            onUndo={() => console.log('Undo performed')}
+            onRedo={() => console.log('Redo performed')}
+          />
+
+          {/* Reset Button */}
+          <button
+            onClick={resetNarrative}
+            style={{
+              padding: '0.5rem 1rem',
+              backgroundColor: '#dc3545',
+              color: 'white',
+              border: 'none',
+              borderRadius: '4px',
+              cursor: 'pointer'
+            }}
+          >
+            Reset
+          </button>
+
+          {/* Toggle Advanced View */}
+          <button
+            onClick={() => setShowAdvanced(!showAdvanced)}
+            style={{
+              padding: '0.5rem 1rem',
+              backgroundColor: '#6c757d',
+              color: 'white',
+              border: 'none',
+              borderRadius: '4px',
+              cursor: 'pointer'
+            }}
+          >
+            {showAdvanced ? 'Hide' : 'Show'} Advanced
+          </button>
+        </div>
+      </section>
+
+      {/* Advanced Controls (when enabled) */}
+      {showAdvanced && (
+        <section style={sectionStyle}>
+          <h3>🔧 Advanced Controls</h3>
+          <div style={{ display: 'flex', gap: '1rem', alignItems: 'center', flexWrap: 'wrap' }}>
+            {/* Vertical Layout Undo/Redo */}
+            <div>
+              <h4 style={{ margin: '0 0 0.5rem 0', fontSize: '0.9rem' }}>Vertical Layout</h4>
+              <UndoRedoControls
+                engine={engine}
+                size="sm"
+                layout="vertical"
+                showLabels={false}
+              />
+            </div>
+
+            {/* Large Size Controls */}
+            <div>
+              <h4 style={{ margin: '0 0 0.5rem 0', fontSize: '0.9rem' }}>Large Size</h4>
+              <UndoRedoControls
+                engine={engine}
+                size="lg"
+                layout="horizontal"
+                showLabels={true}
+                theme={{
+                  colors: {
+                    primary: '#28a745',
+                    background: '#ffffff'
+                  }
+                }}
+              />
+            </div>
+
+            {/* Icon-only Autosave */}
+            <div>
+              <h4 style={{ margin: '0 0 0.5rem 0', fontSize: '0.9rem' }}>Icon-only</h4>
+              <AutosaveIndicator 
+                engine={engine}
+                variant="icon-only"
+                showTimestamp={false}
+              />
+            </div>
+
+            {/* Minimal Autosave */}
+            <div>
+              <h4 style={{ margin: '0 0 0.5rem 0', fontSize: '0.9rem' }}>Minimal</h4>
+              <AutosaveIndicator 
+                engine={engine}
+                variant="minimal"
+                showTimestamp={false}
+                theme={{
+                  colors: {
+                    success: '#17a2b8',
+                    warning: '#ffc107'
+                  }
+                }}
+              />
+            </div>
+          </div>
+        </section>
+      )}
+
+      {/* Narrative Section */}
+      <section style={sectionStyle}>
+        <h2>📖 Current Scene</h2>
+        <div style={narrativeStyle}>
+          {currentNode.text}
+        </div>
+
+        {/* Choices */}
+        {availableChoices.length > 0 && (
+          <div>
+            <h3>Choose your path:</h3>
+            {availableChoices.map((choice, index) => (
+              <button
+                key={index}
+                onClick={() => selectChoice(choice)}
+                style={choiceButtonStyle}
+                onMouseEnter={(e) => {
+                  e.currentTarget.style.backgroundColor = '#0056b3';
+                }}
+                onMouseLeave={(e) => {
+                  e.currentTarget.style.backgroundColor = '#007bff';
+                }}
+              >
+                {choice.text}
+              </button>
+            ))}
+          </div>
+        )}
+
+        {/* End of story message */}
+        {availableChoices.length === 0 && (
+          <div style={{ textAlign: 'center', padding: '2rem' }}>
+            <h3>🎊 The End</h3>
+            <p>You've reached the end of this narrative path.</p>
+            <button
+              onClick={resetNarrative}
+              style={{
+                ...choiceButtonStyle,
+                backgroundColor: '#28a745',
+                width: 'auto',
+                display: 'inline-block'
+              }}
+            >
+              Start Over
+            </button>
+          </div>
+        )}
+      </section>
+
+      {/* Story State Info */}
+      <section style={sectionStyle}>
+        <h3>📊 Story State</h3>
+        <div style={flagsStyle}>
+          <strong>Current Node:</strong> {currentNode.id}<br/>
+          <strong>Flags:</strong> {Object.keys(flags).length > 0 ? JSON.stringify(flags, null, 2) : 'None set'}
+        </div>
+      </section>
+
+      {/* Instructions */}
+      <section style={sectionStyle}>
+        <h3>💡 Usage Instructions</h3>
+        <ul style={{ lineHeight: 1.8 }}>
+          <li><strong>Make choices</strong> to progress through the story and see autosave indicators</li>
+          <li><strong>Use keyboard shortcuts:</strong> Ctrl/Cmd+Z to undo, Ctrl/Cmd+Y to redo, Ctrl/Cmd+S to save</li>
+          <li><strong>Watch the autosave indicator</strong> show status changes in real-time</li>
+          <li><strong>Try the undo/redo buttons</strong> to navigate through your choice history</li>
+          <li><strong>Toggle advanced view</strong> to see different component variations</li>
+          <li><strong>All components are accessible</strong> with keyboard navigation and screen readers</li>
+        </ul>
+      </section>
+    </div>
+  );
+};
+
+// Initialize the demo
+const container = document.getElementById('root');
+if (container) {
+  const root = createRoot(container);
+  root.render(<QNCEDemo />);
+} else {
+  console.error('Root container not found');
+}

package/examples/validation-demo-story.json

@@ -0,0 +1,177 @@
+{
+  "initialNodeId": "entrance",
+  "nodes": [
+    {
+      "id": "entrance",
+      "text": "You stand before an ancient castle. The heavy oak doors are locked, and storm clouds gather overhead.",
+      "choices": [
+        {
+          "text": "Try to force the door open",
+          "nextNodeId": "door_attempt"
+        },
+        {
+          "text": "Use the golden key",
+          "nextNodeId": "unlock_door",
+          "flagRequirements": {
+            "hasGoldenKey": true
+          }
+        },
+        {
+          "text": "Wait outside in the storm",
+          "nextNodeId": "storm_wait",
+          "enabled": false
+        },
+        {
+          "text": "Purchase a lockpick from the merchant",
+          "nextNodeId": "buy_lockpick",
+          "inventoryRequirements": {
+            "gold": 25,
+            "reputation": 5
+          }
+        },
+        {
+          "text": "Visit the tavern (opens at sunset)",
+          "nextNodeId": "tavern",
+          "timeRequirements": {
+            "availableAfter": "2025-01-01T18:00:00.000Z",
+            "availableBefore": "2025-01-01T23:59:59.000Z"
+          }
+        }
+      ]
+    },
+    {
+      "id": "door_attempt",
+      "text": "You push against the heavy doors, but they remain firmly shut. Your shoulder aches from the effort.",
+      "choices": [
+        {
+          "text": "Return to the entrance",
+          "nextNodeId": "entrance"
+        }
+      ]
+    },
+    {
+      "id": "unlock_door",
+      "text": "The golden key turns smoothly in the lock. The doors swing open with a satisfying creak, revealing a grand hallway beyond.",
+      "choices": [
+        {
+          "text": "Enter the castle",
+          "nextNodeId": "grand_hall",
+          "flagEffects": {
+            "enteredCastle": true
+          }
+        }
+      ]
+    },
+    {
+      "id": "storm_wait",
+      "text": "You decide to wait outside, but this choice should never be reachable due to validation.",
+      "choices": []
+    },
+    {
+      "id": "buy_lockpick",
+      "text": "The merchant smiles as you purchase a masterfully crafted lockpick. 'This will open any door,' he promises.",
+      "choices": [
+        {
+          "text": "Return to the entrance with lockpick",
+          "nextNodeId": "entrance",
+          "flagEffects": {
+            "hasLockpick": true
+          }
+        }
+      ]
+    },
+    {
+      "id": "tavern",
+      "text": "The warm tavern glows with candlelight. Travelers share stories and the aroma of roasted meat fills the air.",
+      "choices": [
+        {
+          "text": "Listen to the bard's tale",
+          "nextNodeId": "bard_story"
+        },
+        {
+          "text": "Ask about the castle",
+          "nextNodeId": "castle_info"
+        }
+      ]
+    },
+    {
+      "id": "grand_hall",
+      "text": "You stand in an opulent grand hall with marble columns and tapestries depicting ancient battles.",
+      "choices": [
+        {
+          "text": "Explore the east wing",
+          "nextNodeId": "east_wing"
+        },
+        {
+          "text": "Climb the grand staircase",
+          "nextNodeId": "upper_floor"
+        }
+      ]
+    },
+    {
+      "id": "bard_story",
+      "text": "The bard tells of a legendary treasure hidden deep within the castle, guarded by ancient magic.",
+      "choices": [
+        {
+          "text": "Ask about the treasure",
+          "nextNodeId": "treasure_info",
+          "flagEffects": {
+            "knowsAboutTreasure": true
+          }
+        }
+      ]
+    },
+    {
+      "id": "castle_info",
+      "text": "A grizzled traveler warns you about the castle's dangers but mentions a golden key hidden in the forest.",
+      "choices": [
+        {
+          "text": "Ask where to find the key",
+          "nextNodeId": "key_location",
+          "flagEffects": {
+            "knowsKeyLocation": true
+          }
+        }
+      ]
+    },
+    {
+      "id": "treasure_info",
+      "text": "The bard leans closer and whispers the secret of the treasure's location...",
+      "choices": []
+    },
+    {
+      "id": "key_location",
+      "text": "The traveler draws a rough map on a napkin, marking where the golden key lies buried.",
+      "choices": [
+        {
+          "text": "Search for the key",
+          "nextNodeId": "find_key",
+          "flagEffects": {
+            "hasGoldenKey": true,
+            "foundKey": true
+          }
+        }
+      ]
+    },
+    {
+      "id": "find_key",
+      "text": "After searching through the undergrowth, your fingers close around a cold, golden key. Success!",
+      "choices": [
+        {
+          "text": "Return to the castle",
+          "nextNodeId": "entrance"
+        }
+      ]
+    },
+    {
+      "id": "east_wing",
+      "text": "The east wing is filled with ancient artifacts and dusty paintings.",
+      "choices": []
+    },
+    {
+      "id": "upper_floor",
+      "text": "The upper floor overlooks the grand hall. Moonlight streams through stained glass windows.",
+      "choices": []
+    }
+  ]
+}