qnce-engine 1.2.1 → 1.2.3

package/README.md

@@ -2,7 +2,7 @@
 
 **Quantum Narrative Convergence Engine** - A framework-agnostic TypeScript library for creating interactive narrative experiences with quantum-inspired mechanics.
 
-> **🚀 NEW in v1.2.0:** Complete state persistence, advanced branching with AI integration, autosave & undo/redo system, conditional choice display, and comprehensive UI components with React integration.
+> **🚀 Latest v1.2.2:** Complete state persistence, advanced branching with AI integration, autosave & undo/redo system, conditional choice display, and comprehensive UI components with React integration.
 
 [![npm version](https://badge.fury.io/js/qnce-engine.svg)](https://badge.fury.io/js/qnce-engine)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
@@ -14,7 +14,7 @@
 - **Collapse:** Player choices "collapse" the narrative to a specific path, updating state and flags
 - **Entanglement:** Early decisions affect later outcomes, enabling complex, interconnected stories
 
-## ✨ What's New in v1.2.0
+## ✨ Current Features (v1.2.2)
 
 ### 💾 State Persistence & Checkpoints
 - **Complete save/load system** with data integrity validation
@@ -348,7 +348,7 @@ console.log('Restored to checkpoint:', engine.getCurrentNode().text);
 
 ### 🔄 Autosave & Undo/Redo System
 
-QNCE Engine v1.2.0 introduces an advanced autosave and undo/redo system that automatically tracks state changes and provides instant rollback capabilities with sub-millisecond performance.
+QNCE Engine v1.2.2 introduces an advanced autosave and undo/redo system that automatically tracks state changes and provides instant rollback capabilities with sub-millisecond performance.
 
 **Key Features:**
 - **Automatic State Tracking:** Intelligently captures state snapshots on key events (choice selection, flag changes, state loading)
@@ -677,7 +677,7 @@ Features:
 
 ### qnce-perf
 
-**NEW in v1.2.0:** Real-time performance monitoring and analytics:
+**Current in v1.2.2:** Real-time performance monitoring and analytics:
 
 ```bash
 # Launch interactive performance dashboard
@@ -990,7 +990,7 @@ The repository includes comprehensive examples demonstrating all features:
 - **Features:** Complex narrative flows, conditional branching, analytics
 - **Story:** "The Mysterious Library" - Interactive mystery with multiple paths
 
-### 💾 Autosave & Undo Demo (NEW in v1.2.0)
+### 💾 Autosave & Undo Demo (Available in v1.2.2)
 - **File:** `examples/autosave-undo-demo.ts`
 - **Features:** Autosave, undo/redo, performance monitoring, state management
 - **Run:** `npm run demo:autosave`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qnce-engine",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Core QNCE (Quantum Narrative Convergence Engine) - Framework agnostic narrative engine with performance optimization",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,7 +33,7 @@
     "choice-based",
     "typescript"
   ],
-  "author": "ByteSower",
+  "author": "QNCE Development Team",
   "license": "MIT",
   "repository": {
     "type": "git",

package/docs/branching/PDM.md

@@ -1,443 +0,0 @@
-# QNCE Branching System - Platform Data Model (PDM) Specification
-
-**Sprint #3 - Advanced Narrative & AI Integration**  
-**Version:** 1.0.0  
-**Date:** July 2, 2025  
-**Owner:** Body (VS Code Agent)  
-**Reviewers:** Brain (Copilot), ByteSower (Bull)
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Design Principles](#design-principles)
-3. [Entity Definitions](#entity-definitions)
-4. [Data Relationships](#data-relationships)
-5. [Performance Considerations](#performance-considerations)
-6. [AI Integration Points](#ai-integration-points)
-7. [Usage Examples](#usage-examples)
-8. [Migration Guide](#migration-guide)
-
-## Overview
-
-The QNCE Branching System PDM defines the data structures and relationships needed to support dynamic narrative branching, AI-driven content generation, and real-time story modification. Built on Sprint #2's performance infrastructure, this PDM enables complex, interconnected narratives with enterprise-grade performance.
-
-### Key Capabilities
-
-- **Dynamic Branching**: Runtime insertion, removal, and modification of narrative paths
-- **AI Integration**: Rich context for procedural dialogue and content generation
-- **Performance Optimization**: Built on object pooling and profiling infrastructure
-- **Analytics Support**: Comprehensive tracking of player behavior and story flow
-- **Modular Design**: Clean separation of concerns for maintainable code
-
-## Design Principles
-
-### 1. Performance-First Architecture
-- All entities support object pooling from Sprint #2
-- Minimal memory allocations during runtime
-- Efficient data structures for frequent operations
-- Background processing for analytics and caching
-
-### 2. AI Integration Ready
-- Rich context interfaces for AI systems
-- Extensible generation hints and constraints
-- Player profiling for personalized experiences
-- Content quality tracking and feedback loops
-
-### 3. Developer Experience
-- Clear entity hierarchies and relationships
-- Type-safe interfaces with comprehensive documentation
-- Debugging-friendly data structures
-- Migration paths from existing story formats
-
-### 4. Scalability & Modularity
-- Support for large, complex narratives
-- Chapter-based organization for memory efficiency
-- Dynamic loading and unloading of story content
-- Plugin architecture for custom branching logic
-
-## Entity Definitions
-
-### Core Story Structure
-
-#### QNCEStory
-Top-level container for all narrative content with branching metadata.
-
-```typescript
-interface QNCEStory {
-  id: string;                    // Unique story identifier
-  title: string;                 // Human-readable story title
-  version: string;               // Semantic version (e.g., "1.2.3")
-  metadata: StoryMetadata;       // Author, description, creation info
-  chapters: Chapter[];           // Ordered list of story chapters
-  branchingConfig: BranchingConfig; // Performance and behavior settings
-}
-```
-
-**Key Features:**
-- Versioning support for iterative development
-- Configurable branching behavior per story
-- Metadata for discovery and organization
-
-#### Chapter
-Logical grouping of narrative flows with branching points.
-
-```typescript
-interface Chapter {
-  id: string;                    // Unique chapter identifier
-  title: string;                 // Chapter title for navigation
-  description?: string;          // Optional chapter summary
-  flows: NarrativeFlow[];        // Available narrative flows
-  branches: BranchPoint[];       // Dynamic branching logic
-  prerequisites?: ChapterPrerequisites; // Access requirements
-  metadata: ChapterMetadata;     // Difficulty, themes, duration
-}
-```
-
-**Key Features:**
-- Prerequisites for gated content progression
-- Metadata for AI-driven content selection
-- Flexible flow organization
-
-#### NarrativeFlow
-Sequence of connected nodes with defined entry/exit points.
-
-```typescript
-interface NarrativeFlow {
-  id: string;                    // Unique flow identifier
-  name: string;                  // Flow name for debugging
-  description?: string;          // Optional flow summary
-  nodes: NarrativeNode[];        // Ordered narrative nodes
-  entryPoints: FlowEntryPoint[]; // Ways to enter this flow
-  exitPoints: FlowExitPoint[];   // Ways to exit this flow
-  flowType: FlowType;            // 'linear' | 'branching' | 'conditional' | 'procedural'
-  metadata: FlowMetadata;        // Complexity, timing, AI flags
-}
-```
-
-**Key Features:**
-- Multiple entry/exit points for complex branching
-- Type classification for AI optimization
-- Performance metadata for analytics
-
-### Branching Logic
-
-#### BranchPoint
-Dynamic branching logic between flows with runtime modification support.
-
-```typescript
-interface BranchPoint {
-  id: string;                    // Unique branch identifier
-  name: string;                  // Branch name for debugging
-  sourceFlowId: string;          // Origin flow
-  sourceNodeId: string;          // Specific trigger node
-  branchOptions: BranchOption[]; // Available branch paths
-  branchType: BranchType;        // How branching is determined
-  conditions?: BranchCondition[]; // Global branch conditions
-  metadata: BranchMetadata;      // Usage analytics and preferences
-}
-```
-
-**Key Features:**
-- Multiple branching strategies (choice, flag, time, procedural)
-- Runtime condition evaluation
-- Analytics for optimization
-
-#### BranchOption
-Individual branching path with conditions and effects.
-
-```typescript
-interface BranchOption {
-  id: string;                    // Unique option identifier
-  targetFlowId: string;          // Destination flow
-  targetNodeId?: string;         // Specific entry point (optional)
-  displayText: string;           // Player-facing text
-  conditions?: BranchCondition[]; // Availability conditions
-  flagEffects?: Record<string, unknown>; // State changes
-  weight: number;                // For procedural selection
-}
-```
-
-### Runtime Context
-
-#### BranchContext
-Complete runtime state for branch evaluation and tracking.
-
-```typescript
-interface BranchContext {
-  currentStory: QNCEStory;       // Active story
-  currentChapter: Chapter;       // Current chapter
-  currentFlow: NarrativeFlow;    // Active flow
-  activeState: QNCEState;        // Engine state
-  branchHistory: BranchHistoryEntry[]; // Decision history
-  pendingBranches: PendingBranch[]; // Deferred branches
-  analytics: BranchAnalytics;    // Performance metrics
-}
-```
-
-**Key Features:**
-- Complete context for AI decision making
-- History tracking for complex narrative dependencies
-- Real-time analytics collection
-
-## Data Relationships
-
-### Hierarchical Structure
-```
-QNCEStory
-├── Chapter (1..*)
-│   ├── NarrativeFlow (1..*)
-│   │   ├── NarrativeNode (1..*)
-│   │   ├── FlowEntryPoint (0..*)
-│   │   └── FlowExitPoint (0..*)
-│   └── BranchPoint (0..*)
-│       └── BranchOption (1..*)
-└── BranchingConfig
-```
-
-### Cross-References
-- **BranchPoint.sourceFlowId** → **NarrativeFlow.id**
-- **BranchOption.targetFlowId** → **NarrativeFlow.id**
-- **FlowEntryPoint.nodeId** → **NarrativeNode.id**
-- **FlowExitPoint.nodeId** → **NarrativeNode.id**
-
-### Runtime Associations
-- **BranchContext** maintains references to active entities
-- **BranchHistory** links to **BranchPoint** and **BranchOption**
-- **PendingBranch** references **BranchPoint** for deferred execution
-
-## Performance Considerations
-
-### Object Pooling Integration
-
-All frequently-created entities support object pooling:
-
-```typescript
-interface PooledBranchContext extends BranchContext {
-  poolId: string;                // Pool identifier
-  acquisitionTime: number;       // Performance tracking
-  maxLifetime: number;           // Auto-cleanup threshold
-}
-```
-
-### Memory Management
-
-- **Chapter-based loading**: Only active chapters kept in memory
-- **Flow caching**: LRU cache for recently accessed flows
-- **Branch pruning**: Remove unused branches after timeout
-- **Analytics batching**: Batch analytics writes to reduce overhead
-
-### Performance Targets
-
-| Operation | Target | Measurement |
-|-----------|--------|-------------|
-| Branch evaluation | <5ms | 95th percentile |
-| Flow transition | <10ms | Average |
-| Dynamic insertion | <20ms | 95th percentile |
-| Analytics update | <1ms | Average |
-
-## AI Integration Points
-
-### Content Generation Context
-
-The PDM provides rich context for AI systems:
-
-```typescript
-interface AIBranchingContext {
-  playerProfile: PlayerProfile;     // Behavioral patterns
-  narrativeContext: NarrativeContext; // Story state
-  generationHints: AIGenerationHints; // Constraints
-}
-```
-
-### Player Profiling
-
-```typescript
-interface PlayerProfile {
-  playStyle: 'explorer' | 'achiever' | 'socializer' | 'killer';
-  preferences: Record<string, number>; // Weighted preferences
-  historicalChoices: string[];         // Past decisions
-  averageDecisionTime: number;         // Behavioral metric
-}
-```
-
-### Dynamic Content Integration
-
-- **Procedural flows**: AI-generated narrative sequences
-- **Dynamic options**: Context-aware branch generation
-- **Adaptive difficulty**: AI-driven complexity adjustment
-- **Content quality**: Feedback loops for improvement
-
-## Usage Examples
-
-### 1. Basic Story Structure
-
-```typescript
-const story: QNCEStory = {
-  id: "cyberpunk-heist",
-  title: "Neon Shadows",
-  version: "1.0.0",
-  metadata: {
-    author: "ByteSower",
-    description: "A cyberpunk heist story with AI companions",
-    tags: ["cyberpunk", "heist", "ai"],
-    createDate: new Date("2025-07-01"),
-    lastModified: new Date("2025-07-02"),
-    estimatedPlaytime: 45
-  },
-  chapters: [
-    {
-      id: "chapter-1-planning",
-      title: "The Planning Phase",
-      flows: [
-        {
-          id: "flow-intro",
-          name: "Introduction",
-          nodes: [/* ... */],
-          entryPoints: [{ id: "start", nodeId: "intro-1", priority: 1 }],
-          exitPoints: [{ id: "to-team", nodeId: "intro-final" }],
-          flowType: "linear",
-          metadata: { complexity: 2, avgCompletionTime: 300000 }
-        }
-      ],
-      branches: [
-        {
-          id: "team-selection",
-          name: "Choose Your Team",
-          sourceFlowId: "flow-intro",
-          sourceNodeId: "intro-final",
-          branchType: "choice-driven",
-          branchOptions: [
-            {
-              id: "tech-specialist",
-              targetFlowId: "flow-tech-path",
-              displayText: "Recruit the tech specialist",
-              weight: 1.0
-            },
-            {
-              id: "social-engineer",
-              targetFlowId: "flow-social-path", 
-              displayText: "Recruit the social engineer",
-              weight: 1.0
-            }
-          ],
-          metadata: { usageCount: 0, avgTraversalTime: 0 }
-        }
-      ],
-      metadata: { difficulty: "medium", themes: ["planning"] }
-    }
-  ],
-  branchingConfig: {
-    maxActiveBranches: 10,
-    branchCacheSize: 50,
-    enableDynamicInsertion: true,
-    enableAnalytics: true,
-    performanceMode: true
-  }
-};
-```
-
-### 2. Dynamic Branch Insertion
-
-```typescript
-const dynamicBranch: DynamicBranchOperation = {
-  type: "insert",
-  branchId: "emergency-exit",
-  targetLocation: {
-    chapterId: "chapter-1-planning",
-    flowId: "flow-tech-path",
-    nodeId: "tech-decision-point",
-    insertionPoint: "after"
-  },
-  payload: {
-    id: "emergency-exit",
-    name: "Emergency Exit Option",
-    sourceFlowId: "flow-tech-path",
-    sourceNodeId: "tech-decision-point",
-    branchType: "conditional",
-    branchOptions: [{
-      id: "abort-mission",
-      targetFlowId: "flow-abort-sequence",
-      displayText: "Abort the mission",
-      conditions: [
-        { type: "flag", operator: "equals", key: "danger_level", value: "high" }
-      ],
-      weight: 0.5
-    }]
-  },
-  conditions: [
-    { type: "flag", operator: "greater", key: "tension", value: 0.8 }
-  ]
-};
-```
-
-### 3. AI-Driven Content Generation
-
-```typescript
-const aiContext: AIBranchingContext = {
-  playerProfile: {
-    playStyle: "explorer",
-    preferences: { "dialogue": 0.8, "action": 0.3, "puzzle": 0.6 },
-    historicalChoices: ["investigate", "ask-questions", "explore-optional"],
-    averageDecisionTime: 12000
-  },
-  narrativeContext: {
-    currentTone: "mysterious",
-    thematicElements: ["betrayal", "discovery", "technology"],
-    characterRelationships: { "ally-1": 0.7, "mentor": 0.9 },
-    plotTension: 0.6
-  },
-  generationHints: {
-    maxBranchDepth: 3,
-    desiredComplexity: 7,
-    contentThemes: ["investigation", "character-development"],
-    avoidElements: ["violence", "time-pressure"]
-  }
-};
-```
-
-## Migration Guide
-
-### From Sprint #2 Core to Sprint #3 Branching
-
-1. **Story Data Format**:
-   - Wrap existing `StoryData` in `QNCEStory` structure
-   - Organize nodes into `NarrativeFlow` entities
-   - Group flows into logical `Chapter` divisions
-
-2. **Choice Enhancement**:
-   - Convert simple choices to `BranchOption` entities
-   - Add conditions for complex choice logic
-   - Implement weight-based selection for AI
-
-3. **State Integration**:
-   - Extend `QNCEState` with branching context
-   - Add analytics tracking to existing workflows
-   - Integrate with object pooling for performance
-
-### Backward Compatibility
-
-The PDM maintains compatibility with existing QNCE engines:
-
-- **Legacy node format**: Direct mapping to `NarrativeNode`
-- **Simple choices**: Automatic conversion to `BranchOption`
-- **Existing state**: Seamless integration with `BranchContext`
-
-## Conclusion
-
-This PDM provides a comprehensive foundation for Sprint #3's advanced narrative features while maintaining the performance optimizations from Sprint #2. The design supports:
-
-- ✅ **Dynamic Branching**: Runtime story modification
-- ✅ **AI Integration**: Rich context for content generation  
-- ✅ **Performance**: Built on proven optimization infrastructure
-- ✅ **Analytics**: Comprehensive player behavior tracking
-- ✅ **Scalability**: Support for complex, large-scale narratives
-
-The next step is to implement the **Branching API** that operates on this PDM, providing the runtime functionality needed for the complete Sprint #3 feature set.
-
----
-
-**Next Actions:**
-1. **Brain Review**: Architectural alignment and performance considerations
-2. **ByteSower Validation**: Use case coverage and content creator workflow  
-3. **Implementation**: Build the Branching API on this PDM foundation
-4. **Testing**: Comprehensive test suite for all entity relationships

package/docs/branching/RELEASE-v1.2.0.md

@@ -1,169 +0,0 @@
-# 🎉 QNCE Engine v1.2.0 - Advanced Branching & AI Integration
-
-**Release Date:** July 2, 2025  
-**Version:** 1.2.0  
-**Status:** ✅ **PRODUCTION READY**
-
-## 🚀 Release Highlights
-
-This major release introduces the **Advanced Branching API & Platform Data Model (PDM)**, delivering a comprehensive foundation for sophisticated interactive narratives with AI integration.
-
-## 📋 Deliverables Summary
-
-### ✅ 1. Platform Data Model (PDM)
-**File:** `docs/branching/PDM.md` (26 pages, comprehensive spec)
-
-- **20+ TypeScript interfaces** defining the complete entity hierarchy
-- **Story → Chapter → Flow → Node** structure with branching logic
-- **AI integration points** for procedural content generation
-- **Performance optimization** interfaces compatible with Sprint #2
-- **Migration guide** from existing QNCE formats
-
-### ✅ 2. UML Entity Relationship Diagram
-**File:** `docs/branching/ERD.md` (visual documentation)
-
-- **Mermaid ERD diagrams** showing all entity relationships
-- **Data flow documentation** for runtime operations
-- **Cross-reference mapping** between entities
-- **Performance and pooling integration** diagrams
-
-### ✅ 3. Runtime Branching API
-**File:** `src/narrative/branching/engine-simple.ts` (340 lines)
-
-**Core Operations:**
-```typescript
-// Branch evaluation and execution
-await engine.evaluateAvailableBranches()
-await engine.executeBranch(optionId)
-
-// Dynamic content management  
-await engine.insertDynamicBranch(operation)
-await engine.removeDynamicBranch(branchId)
-
-// AI integration
-engine.setAIContext(aiContext)
-await engine.generateAIBranches(maxOptions)
-
-// Analytics and monitoring
-engine.getBranchingAnalytics()
-engine.exportBranchingData()
-```
-
-### ✅ 4. Comprehensive Test Suite
-**File:** `tests/branching.test.ts` (24 tests, 100% passing)
-
-**Test Coverage:**
-- ✅ Engine creation and initialization
-- ✅ Branch evaluation with conditions
-- ✅ Branch execution and state transitions
-- ✅ Dynamic branch insertion/removal
-- ✅ AI integration and context management
-- ✅ Analytics tracking and export
-- ✅ Condition evaluation (equals, greater, custom)
-- ✅ Performance benchmarks (<5ms evaluation, <10ms execution)
-
-## 🏗️ Technical Architecture
-
-### Entity Hierarchy
-```
-QNCEStory
-├── BranchingConfig (performance settings)
-├── Chapter[] (logical groupings)
-│   ├── NarrativeFlow[] (node sequences)
-│   │   ├── NarrativeNode[] (story content)
-│   │   ├── FlowEntryPoint[] (entry conditions)
-│   │   └── FlowExitPoint[] (exit transitions)
-│   └── BranchPoint[] (decision logic)
-│       └── BranchOption[] (player choices)
-└── Metadata (author, version, etc.)
-```
-
-### Key Features
-- **Dynamic Branching**: Runtime insertion/removal of narrative paths
-- **Conditional Logic**: Flag/choice/time/custom condition evaluation
-- **AI Integration**: Rich context for procedural content generation
-- **Performance Ready**: Built on Sprint #2 object pooling infrastructure
-- **Analytics Support**: Comprehensive player behavior tracking
-- **Type Safety**: Complete TypeScript interface coverage
-
-### Performance Characteristics
-- **Branch Evaluation**: <5ms (target achieved)
-- **Branch Execution**: <10ms (target achieved) 
-- **Memory Efficient**: Compatible with object pooling
-- **Scalable**: Support for large, complex narratives
-
-## 🤖 AI Integration Ready
-
-The PDM provides comprehensive context for AI systems:
-
-```typescript
-interface AIBranchingContext {
-  playerProfile: PlayerProfile;     // Behavioral patterns
-  narrativeContext: NarrativeContext; // Story state & tension
-  generationHints: AIGenerationHints; // Content constraints
-}
-```
-
-This enables:
-- **Personalized branching** based on player behavior
-- **Context-aware content generation**
-- **Dynamic difficulty adjustment**
-- **Quality feedback loops**
-
-## 🔗 Sprint #2 Integration
-
-Built on the performance infrastructure from Sprint #2:
-- **Object pooling** interfaces for memory efficiency
-- **Performance monitoring** hooks for analytics
-- **Hot-reload compatibility** for live development
-- **Background processing** support for AI operations
-
-## 📊 Test Results
-
-```
-✅ 24/24 tests passing (100% success rate)
-✅ Performance targets met:
-   - Branch evaluation: <5ms ✅
-   - Branch execution: <10ms ✅ 
-✅ All entity relationships validated
-✅ AI integration functionality confirmed
-✅ Dynamic operations working correctly
-```
-
-## 🎯 Sprint #3 Impact
-
-This PDM enables all remaining Sprint #3 features:
-
-- **S3-T2: Procedural Dialogue Module** → AI context interfaces ready
-- **S3-T3: NLP Choice Parser** → Branch option framework prepared  
-- **S3-T4: Narrative Analytics Dashboard** → Analytics export implemented
-- **S3-T5: In-Engine Debug Console** → State inspection APIs available
-
-## 🎊 What's Next?
-
-### Immediate Actions
-1. **Brain Review** 🧠 - Architecture alignment and performance validation
-2. **ByteSower Validation** - Use case coverage and content creator workflow
-3. **Core Engine Integration** - Extend existing QNCE engine with branching
-
-### Sprint #3 Progression
-- **S3-T2**: Build procedural dialogue on this PDM foundation
-- **S3-T3**: Implement NLP choice parsing using BranchOption structure  
-- **S3-T4**: Extend analytics dashboard with branching metrics
-- **S3-T5**: Add debug console with branch state inspection
-
-## 🌟 Key Achievements
-
-✅ **Complete PDM**: 20+ interfaces covering all branching scenarios  
-✅ **Working API**: Full runtime implementation with 100% test coverage  
-✅ **AI Ready**: Rich context interfaces for procedural content  
-✅ **Performance Optimized**: Built on Sprint #2 infrastructure  
-✅ **Documentation**: Comprehensive specs and visual diagrams  
-✅ **Extensible**: Plugin architecture for custom branching logic  
-
-**This foundation positions QNCE for advanced narrative AI integration while maintaining the stellar performance achieved in Sprint #2!** 🚀
-
----
-
-**Branch:** `feature/sprint3-branching-pdm`  
-**Ready for merge after review and validation** ✅