Notice (Feb 2026): The QNCE Engine is currently undergoing major reconstruction. Many features, including narrative rules and story flow, may not behave as expected. The engine is transitioning toward broader quantum modeling principles and improved performance. If you require stability, consider waiting for a future release. See GitHub and npm for updates.

Release Date: August 25, 2025
NPM: npm install [email protected]

• New qnce-import CLI that normalizes external formats into QNCE StoryData
  • Custom JSON with JSON Schema validation (strict/lenient)
  • Twison/Twine JSON with tags → node.meta.tags, robust start detection, link mapping
  • Minimal Ink JSON (developer preview); pass --experimental-ink for best effort
• Storage adapters and engine helpers for persistence across backends
  • Memory, LocalStorage, SessionStorage, File, IndexedDB
  • Engine methods: attachStorageAdapter, saveToStorage, loadFromStorage, listStorageKeys, etc.
• qnce-play CLI: storage flags and non-interactive mode for scripting/CI

• Twison tags preserved under node.meta.tags (string[]). Non-breaking, optional to consume.
• If you used custom import scripts, consider switching to qnce-import for consistency and validation.

npm install [email protected]

Complete version history and migration guides for QNCE Engine.

Release Date: August 24, 2025
NPM: npm install [email protected]

• Import CLI hardening and semantic validation for story normalization
• Twison adapter: passage tags are now mapped into node.meta.tags
• JSON Schema updated to allow meta.tags on narrative nodes
• Improved start node detection and dangling link checks

• Twison tags: Previously logged-only, tags are now preserved in output as node.meta.tags: string[].
  • This change is additive and non-breaking. Existing consumers can ignore meta or leverage tags for features.
  • Optional: post-process tags into flags/requirements if your pipeline expects them.
• CLI behavior and exit codes are unchanged: 0 (success), 1 (warnings in lenient mode), 2 (errors).

npm install [email protected]

Release Date: July 5, 2025
NPM: npm install [email protected]

• Complete Repository Security Audit - Comprehensive review and cleanup of all public repository content
• Professional Metadata Standards - Updated NPM package information to maintain professional presentation
• Enhanced Privacy Protection - Improved .gitignore patterns to prevent future sensitive file exposure

• Documentation Sanitization - Removed internal development processes and team-specific references
• Code Attribution Standards - Updated all script and code attributions to professional standards
• Public Content Quality - Ensured all public-facing content maintains enterprise-level quality

No breaking changes or API modifications. This is a metadata and security update:

npm update qnce-engine

Released: July 5, 2025
NPM: npm install [email protected]

• Fixed Set spread operator in condition.ts for better cross-environment compatibility
• Enhanced package metadata with correct homepage and bugs URLs

• React UI Components: Added comprehensive documentation for useQNCE hook, UndoRedoControls, and AutosaveIndicator components
• API Reference: Enhanced with complete TypeScript interfaces and practical examples
• Getting Started: Updated React integration examples to use current v1.2.0 patterns
• Feature Coverage: Added missing v1.2.0 documentation for State Persistence, React UI, and Undo/Redo systems
• Code Quality: All documentation examples now compile successfully

No breaking changes - this is a documentation and compatibility update. Simply update:

npm install [email protected]

Released: July 2, 2025
NPM: npm install [email protected]

This marks the first public release of the Quantum Narrative Convergence Engine. After extensive development and optimization, QNCE Engine is now ready for production use.

• Multi-path narratives with conditional logic and flag-based branching
• AI-driven content generation for dynamic story expansion using configurable AI contexts
• Real-time branch insertion/removal for live content updates during gameplay
• Comprehensive analytics for narrative optimization and player behavior tracking
• Dynamic branch evaluation with custom condition evaluators

• 🏊‍♂️ Object Pooling: 90%+ allocation reduction, eliminating garbage collection pressure
• 🧵 Background Processing: Non-blocking cache preloading and telemetry writes using thread pools
• 🔥 Hot-Reload: Sub-3.5ms live story updates with intelligent delta patching
• 📊 Real-time Profiling: Comprehensive event instrumentation and performance analysis
• 🖥️ Live Monitoring: qnce-perf CLI dashboard with performance alerts and metrics

• qnce-audit - Advanced story validation with dead-end detection and reference checking
• qnce-init - Project scaffolding with multiple templates and configurations
• qnce-perf - Real-time performance monitoring with customizable dashboards

• Framework-agnostic design - Works with React, Vue, Node.js, vanilla JavaScript
• TypeScript-first with comprehensive type definitions and IntelliSense support
• Modular architecture allowing selective feature imports
• Extensive examples from basic quickstart to advanced enterprise scenarios

• Full state serialization with compression and validation
• Automatic save/restore with configurable intervals and triggers
• Checkpoint system for implementing undo/redo functionality
• Cross-session persistence with localStorage and custom storage adapters
• Save validation ensuring data integrity and version compatibility

• useQNCE Hook - Reactive state management for React components
• UndoRedoControls - Pre-built accessible undo/redo controls with theming
• AutosaveIndicator - Visual feedback for autosave status with timestamps
• useKeyboardShortcuts - Keyboard shortcut integration for common actions
• Framework Integration - Built-in React, Vue, and vanilla JS adapters

• Multi-level undo/redo with configurable history depth
• Automatic checkpointing before critical choices and state changes
• Memory-efficient snapshots using differential state compression
• UI integration with keyboard shortcuts and accessibility support

• Superposition: Multiple narrative outcomes exist simultaneously until a choice is made
• Collapse: Player choices "collapse" the narrative to a specific path, updating state and flags
• Entanglement: Early decisions affect later outcomes, enabling complex, interconnected stories

# Install QNCE Engine
npm install qnce-engine

# Global CLI installation
npm install -g qnce-engine

# Create new project
npx qnce-init my-story

import { createQNCEEngine, DEMO_STORY } from 'qnce-engine';

// Create engine with performance optimization
const engine = createQNCEEngine(DEMO_STORY, {
  enablePerformanceMode: true,
  enableBranching: true
});

// Get current narrative state
const currentNode = engine.getCurrentNode();
console.log(currentNode.text);

// Display available choices
const choices = engine.getAvailableChoices();
choices.forEach((choice, index) => {
  console.log(`${index + 1}. ${choice.text}`);
});

// Make a choice and advance
engine.makeChoice(0);

// v1.1.x
const engine = new QNCEEngine(story);

// v1.2.0 
const engine = createQNCEEngine(story, {
  enablePerformanceMode: true,
  enableBranching: true
});

// v1.1.x - Simple configuration
const options = {
  debug: true
};

// v1.2.0 - Structured configuration
const options = {
  enablePerformanceMode: true,
  performanceOptions: {
    objectPooling: { enable: true },
    backgroundProcessing: { enable: true }
  },
  enableBranching: true,
  validationMode: 'strict'
};

1. Update Constructor Calls

   // Old
   const engine = new QNCEEngine(story);
   
   // New
   const engine = createQNCEEngine(story);

2. Update Configuration

   // Old
   const engine = new QNCEEngine(story, { debug: true });
   
   // New
   const engine = createQNCEEngine(story, {
     debugMode: true,
     enablePerformanceMode: true
   });

3. Update CLI Commands

   # Old
   qnce-validate story.json
   
   # New
   qnce-audit story.json

4. Update Dependencies

   npm uninstall qnce-engine-beta
   npm install [email protected]

• 61/61 tests passing ✅
• 90%+ code coverage
• Performance regression testing
• Memory leak detection
• Cross-platform compatibility (Node.js 16+, modern browsers)

• Complete Wiki with guides and examples
• API Reference with TypeScript definitions
• Performance Guide for optimization
• CLI Documentation for all tools

• GitHub Repository - Source code and issues
• GitHub Discussions - Community Q&A
• Contributing Guide - How to contribute
• Issue Templates - Report bugs or request features

• Visual story editor with drag-and-drop interface
• Advanced AI integration with GPT and Claude support
• Multiplayer narratives with real-time synchronization
• Visual novel renderer for rich media stories
• Analytics dashboard with detailed player insights

• Released: June 2025
• Basic branching system implementation
• Initial performance infrastructure
• CLI tools prototype
• TypeScript migration

• Released: May 2025
• Core engine implementation
• Basic story format
• Node.js support
• Initial testing framework

• Released: April 2025 (Development)
• Proof of concept
• Core narrative mechanics
• Basic JavaScript implementation

• Object-oriented design with clean separation of concerns
• Modular architecture allowing selective imports
• Plugin system for extending functionality
• Event-driven architecture for reactive programming

• Object pooling reducing allocations by 90%+
• Background processing for non-blocking operations
• Intelligent caching with 98% hit rates
• Memory management with automatic cleanup

• TypeScript-first development with full type safety
• Comprehensive testing with 61 test cases
• Professional CLI tools for all development tasks
• Framework integrations for popular platforms

• Modern build pipeline with TypeScript compilation
• ES modules and CommonJS dual package support
• Tree-shaking optimization for smaller bundles
• Source maps for debugging
• Automated testing with CI/CD integration

# Remove old version
npm uninstall qnce-engine-beta

# Install stable version
npm install [email protected]

// v1.1.x
import { QNCEEngine } from 'qnce-engine';

// v1.2.0 - Recommended
import { createQNCEEngine } from 'qnce-engine';

// v1.2.0 - Direct class import still supported
import { QNCEEngine } from 'qnce-engine';

// v1.1.x
const engine = new QNCEEngine(story, {
  debug: true,
  performance: false
});

// v1.2.0
const engine = createQNCEEngine(story, {
  debugMode: true,
  enablePerformanceMode: true,
  enableBranching: false // Add if needed
});

While v1.2.0 maintains backward compatibility, you can optionally upgrade to the new branching format:

// v1.1.x - Basic format (still supported)
const basicStory = {
  nodes: [
    {
      id: 'start',
      text: 'Story text...',
      choices: [
        { text: 'Choice 1', nextNodeId: 'node1' }
      ]
    }
  ]
};

// v1.2.0 - Enhanced format (recommended for new projects)
const enhancedStory: QNCEStory = {
  id: 'my-story',
  title: 'My Interactive Story',
  version: '1.0.0',
  metadata: {
    author: 'Your Name',
    description: 'Story description'
  },
  branchingConfig: {
    maxActiveBranches: 5,
    enableDynamicInsertion: true,
    enableAnalytics: true
  },
  chapters: [
    {
      id: 'chapter-1',
      title: 'Beginning',
      flows: [
        {
          id: 'main-flow',
          nodes: [
            {
              id: 'start',
              text: 'Enhanced story text...',
              choices: [
                {
                  text: 'Enhanced choice',
                  nextNodeId: 'node1',
                  flagEffects: { courage: 1 }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
};

# v1.1.x
qnce-validate story.json
qnce-monitor story.json

# v1.2.0
qnce-audit story.json
qnce-perf monitor story.json

• Hot-reload performance warning: In very large stories (2000+ nodes), hot-reload may occasionally exceed the 2ms target. This doesn't affect functionality but may trigger performance warnings.
  • Workaround: Increase performance warning threshold in development
  • Fix planned: v1.2.2

• Node.js 14: While not officially supported, basic functionality works on Node.js 14. Node.js 16+ recommended for full feature support.
• Internet Explorer: Not supported. Modern browsers (Chrome 80+, Firefox 75+, Safari 13+) required.

Planned: Q3 2025

• Visual Story Editor with drag-and-drop interface
• Advanced AI Integration with GPT and Claude
• Real-time Collaboration for team story development
• Performance Dashboard with detailed analytics

Planned: Q4 2025

• Multiplayer Narratives with synchronized choices
• Real-time Story Sharing across devices
• Live Events System for dynamic content
• Advanced Analytics with player behavior insights

Planned: 2026

• 3D Story Visualization with immersive interfaces
• Voice Integration with speech recognition
• Machine Learning for adaptive storytelling
• Platform Integrations with game engines and platforms

QNCE Engine is released under the MIT License.

Special thanks to all contributors, beta testers, and the community for making QNCE Engine possible!

← Previous: Contributing | You are here: Release Notes

All Pages: Home • Getting Started • Branching Guide • Performance Tuning • CLI Usage • API Reference • Contributing • Release Notes

← Previous: Contributing | You are here: Release Notes

All Pages: Home • Getting Started • Branching Guide • Performance Tuning • CLI Usage • API Reference • Contributing • Release Notes

This documentation is maintained for QNCE Engine v1.2.3 with complete advanced feature set including Choice Validation, State Persistence, Conditional Choices, Autosave & Undo/Redo, and UI Components.