qnce-engine 1.2.0 → 1.2.1

package/dist/examples/src/narrative/branching/engine-simple.js

@@ -0,0 +1,348 @@
+"use strict";
+// QNCE Branching API - Simplified Runtime Implementation  
+// Sprint #3 - Advanced Narrative & AI Integration
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.QNCEBranchingEngine = void 0;
+exports.createBranchingEngine = createBranchingEngine;
+/**
+ * QNCE Branching Engine - Core API for dynamic narrative branching
+ * Simplified implementation focusing on core functionality
+ */
+class QNCEBranchingEngine {
+    story;
+    context;
+    aiContext;
+    constructor(story, initialState) {
+        this.story = story;
+        this.context = this.createBranchContext(story, initialState);
+    }
+    // ================================
+    // Core Branching Operations
+    // ================================
+    /**
+     * Evaluate available branches from current position
+     */
+    async evaluateAvailableBranches() {
+        const currentNode = this.getCurrentNode();
+        const availableBranches = this.findBranchPointsForNode(this.context.currentFlow.id, currentNode.id);
+        const validOptions = [];
+        for (const branchPoint of availableBranches) {
+            // Evaluate branch point conditions
+            if (await this.evaluateConditions(branchPoint.conditions || [])) {
+                // Evaluate individual option conditions
+                for (const option of branchPoint.branchOptions) {
+                    if (await this.evaluateConditions(option.conditions || [])) {
+                        validOptions.push(option);
+                    }
+                }
+            }
+        }
+        return validOptions;
+    }
+    /**
+     * Execute a branch transition
+     */
+    async executeBranch(optionId) {
+        const option = await this.findBranchOption(optionId);
+        if (!option) {
+            throw new Error(`Branch option not found: ${optionId}`);
+        }
+        // Apply flag effects
+        if (option.flagEffects) {
+            Object.assign(this.context.activeState.flags, option.flagEffects);
+        }
+        // Execute flow transition
+        const targetFlow = this.findFlow(option.targetFlowId);
+        if (!targetFlow) {
+            throw new Error(`Target flow not found: ${option.targetFlowId}`);
+        }
+        const success = await this.transitionToFlow(targetFlow, option.targetNodeId);
+        if (success) {
+            // Record branch execution in history
+            this.recordBranchHistory(optionId, option);
+            // Update analytics
+            this.updateBranchAnalytics(optionId);
+        }
+        return success;
+    }
+    /**
+     * Dynamic branch insertion at runtime
+     */
+    async insertDynamicBranch(operation) {
+        // Validate operation conditions
+        if (operation.conditions && !await this.evaluateConditions(operation.conditions)) {
+            return false;
+        }
+        // Find target location
+        const chapter = this.findChapter(operation.targetLocation.chapterId);
+        if (!chapter) {
+            throw new Error(`Chapter not found: ${operation.targetLocation.chapterId}`);
+        }
+        // Create new branch point
+        const branchPoint = {
+            id: operation.branchId,
+            name: operation.payload?.name || `Dynamic Branch ${operation.branchId}`,
+            sourceFlowId: operation.targetLocation.flowId,
+            sourceNodeId: operation.targetLocation.nodeId,
+            branchType: operation.payload?.branchType || 'conditional',
+            branchOptions: operation.payload?.branchOptions || [],
+            conditions: operation.conditions,
+            metadata: {
+                usageCount: 0,
+                avgTraversalTime: 0,
+                playerPreference: 0,
+                lastUsed: new Date()
+            }
+        };
+        // Insert into chapter
+        chapter.branches.push(branchPoint);
+        return true;
+    }
+    /**
+     * Remove dynamic branch
+     */
+    async removeDynamicBranch(branchId) {
+        for (const chapter of this.story.chapters) {
+            const index = chapter.branches.findIndex(b => b.id === branchId);
+            if (index !== -1) {
+                chapter.branches.splice(index, 1);
+                return true;
+            }
+        }
+        return false;
+    }
+    // ================================
+    // AI Integration Methods
+    // ================================
+    /**
+     * Set AI context for enhanced branching decisions
+     */
+    setAIContext(aiContext) {
+        this.aiContext = aiContext;
+    }
+    /**
+     * Generate AI-driven branch options
+     */
+    async generateAIBranches(maxOptions = 3) {
+        if (!this.aiContext) {
+            throw new Error('AI context not set. Call setAIContext() first.');
+        }
+        const generatedOptions = [];
+        const playerProfile = this.aiContext.playerProfile;
+        // Example: Generate options based on player style
+        if (playerProfile.playStyle === 'explorer') {
+            generatedOptions.push({
+                id: `ai-explore-${Date.now()}`,
+                targetFlowId: this.context.currentFlow.id,
+                displayText: "Investigate the mysterious artifact",
+                weight: 0.8
+            });
+        }
+        if (playerProfile.playStyle === 'socializer') {
+            generatedOptions.push({
+                id: `ai-social-${Date.now()}`,
+                targetFlowId: this.context.currentFlow.id,
+                displayText: "Ask your companion about their past",
+                weight: 0.7
+            });
+        }
+        return generatedOptions.slice(0, maxOptions);
+    }
+    // ================================
+    // Analytics & Monitoring
+    // ================================
+    /**
+     * Get current branching analytics
+     */
+    getBranchingAnalytics() {
+        return {
+            ...this.context.analytics,
+            currentChapter: this.context.currentChapter.id,
+            currentFlow: this.context.currentFlow.id,
+            historyLength: this.context.branchHistory.length,
+            pendingBranches: this.context.pendingBranches.length
+        };
+    }
+    /**
+     * Export branching data for external analysis
+     */
+    exportBranchingData() {
+        return {
+            story: {
+                id: this.story.id,
+                title: this.story.title,
+                version: this.story.version
+            },
+            session: {
+                startTime: this.context.analytics.sessionStartTime,
+                currentState: this.context.activeState,
+                branchHistory: this.context.branchHistory,
+                analytics: this.context.analytics
+            }
+        };
+    }
+    // ================================
+    // Private Helper Methods
+    // ================================
+    createBranchContext(story, initialState) {
+        const initialChapter = story.chapters[0];
+        const initialFlow = initialChapter.flows[0];
+        return {
+            currentStory: story,
+            currentChapter: initialChapter,
+            currentFlow: initialFlow,
+            activeState: initialState,
+            branchHistory: [],
+            pendingBranches: [],
+            analytics: {
+                totalBranchesTraversed: 0,
+                avgBranchDecisionTime: 0,
+                mostPopularBranches: [],
+                abandonmentPoints: [],
+                completionRate: 0,
+                sessionStartTime: new Date()
+            }
+        };
+    }
+    getCurrentNode() {
+        const currentNodeId = this.context.activeState.currentNodeId;
+        const node = this.context.currentFlow.nodes.find(n => n.id === currentNodeId);
+        if (!node) {
+            throw new Error(`Current node not found: ${currentNodeId}`);
+        }
+        return node;
+    }
+    findBranchPointsForNode(flowId, nodeId) {
+        return this.context.currentChapter.branches.filter(b => b.sourceFlowId === flowId && b.sourceNodeId === nodeId);
+    }
+    async evaluateConditions(conditions) {
+        for (const condition of conditions) {
+            if (!await this.evaluateCondition(condition)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    async evaluateCondition(condition) {
+        const { operator, key, value, evaluator } = condition;
+        // Custom evaluator takes precedence
+        if (evaluator) {
+            return evaluator(this.context.activeState, this.context);
+        }
+        // Standard condition evaluation
+        const stateValue = this.context.activeState.flags[key];
+        switch (operator) {
+            case 'equals':
+                return stateValue === value;
+            case 'not_equals':
+                return stateValue !== value;
+            case 'greater':
+                return Number(stateValue) > Number(value);
+            case 'less':
+                return Number(stateValue) < Number(value);
+            case 'contains':
+                return Array.isArray(stateValue) && stateValue.includes(value);
+            case 'exists':
+                return stateValue !== undefined;
+            default:
+                return false;
+        }
+    }
+    async findBranchOption(optionId) {
+        for (const chapter of this.story.chapters) {
+            for (const branchPoint of chapter.branches) {
+                const option = branchPoint.branchOptions.find(o => o.id === optionId);
+                if (option) {
+                    return option;
+                }
+            }
+        }
+        return null;
+    }
+    findFlow(flowId) {
+        for (const chapter of this.story.chapters) {
+            const flow = chapter.flows.find(f => f.id === flowId);
+            if (flow) {
+                return flow;
+            }
+        }
+        return null;
+    }
+    findChapter(chapterId) {
+        return this.story.chapters.find(c => c.id === chapterId) || null;
+    }
+    async transitionToFlow(targetFlow, targetNodeId) {
+        // Find entry point
+        let entryNodeId;
+        if (targetNodeId) {
+            entryNodeId = targetNodeId;
+        }
+        else if (targetFlow.entryPoints.length > 0) {
+            // Use highest priority entry point
+            const entryPoint = targetFlow.entryPoints.sort((a, b) => b.priority - a.priority)[0];
+            entryNodeId = entryPoint.nodeId;
+        }
+        else if (targetFlow.nodes.length > 0) {
+            // Use first node as fallback
+            entryNodeId = targetFlow.nodes[0].id;
+        }
+        else {
+            return false;
+        }
+        // Update context
+        this.context.currentFlow = targetFlow;
+        this.context.activeState.currentNodeId = entryNodeId;
+        this.context.activeState.history.push(entryNodeId);
+        // Update chapter if necessary
+        const targetChapter = this.story.chapters.find(c => c.flows.some(f => f.id === targetFlow.id));
+        if (targetChapter) {
+            this.context.currentChapter = targetChapter;
+        }
+        return true;
+    }
+    recordBranchHistory(optionId, option) {
+        const historyEntry = {
+            id: `history-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+            branchPointId: 'unknown', // Would need to track this
+            chosenOptionId: optionId,
+            timestamp: new Date(),
+            executionTime: 0, // Would measure actual execution time
+            context: {
+                currentNodeId: this.context.activeState.currentNodeId,
+                flags: { ...this.context.activeState.flags }
+            }
+        };
+        this.context.branchHistory.push(historyEntry);
+        // Limit history size for memory management
+        if (this.context.branchHistory.length > 1000) {
+            this.context.branchHistory.splice(0, 100);
+        }
+    }
+    updateBranchAnalytics(optionId) {
+        this.context.analytics.totalBranchesTraversed++;
+        // Update popular branches
+        const popular = this.context.analytics.mostPopularBranches;
+        const index = popular.indexOf(optionId);
+        if (index !== -1) {
+            // Move to front
+            popular.splice(index, 1);
+            popular.unshift(optionId);
+        }
+        else {
+            // Add to front
+            popular.unshift(optionId);
+            // Limit to top 10
+            if (popular.length > 10) {
+                popular.pop();
+            }
+        }
+    }
+}
+exports.QNCEBranchingEngine = QNCEBranchingEngine;
+exports.default = QNCEBranchingEngine;
+/**
+ * Factory function for creating branching engines
+ */
+function createBranchingEngine(story, initialState) {
+    return new QNCEBranchingEngine(story, initialState);
+}

package/dist/examples/src/narrative/branching/index.js

@@ -0,0 +1,55 @@
+"use strict";
+// QNCE Branching System - Main Export
+// Sprint #3 - Advanced Narrative & AI Integration
+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.example = exports.createBranchingEngine = exports.QNCEBranchingEngine = void 0;
+// Core branching engine
+var engine_simple_1 = require("./engine-simple");
+Object.defineProperty(exports, "QNCEBranchingEngine", { enumerable: true, get: function () { return engine_simple_1.QNCEBranchingEngine; } });
+Object.defineProperty(exports, "createBranchingEngine", { enumerable: true, get: function () { return engine_simple_1.createBranchingEngine; } });
+// Complete type system
+__exportStar(require("./models"), exports);
+// Usage example for documentation
+exports.example = {
+    // Example story structure showing branching capabilities
+    storyStructure: {
+        story: 'QNCEStory with chapters and branching config',
+        chapters: 'Logical groupings of flows and branch points',
+        flows: 'Sequences of narrative nodes with entry/exit points',
+        branches: 'Dynamic decision points with conditions and options'
+    },
+    // Example API usage
+    usage: `
+    import { createBranchingEngine, QNCEStory } from 'qnce-engine/branching';
+    
+    // Create branching engine
+    const engine = createBranchingEngine(story, initialState);
+    
+    // Evaluate available branches
+    const options = await engine.evaluateAvailableBranches();
+    
+    // Execute player choice
+    await engine.executeBranch(selectedOptionId);
+    
+    // Dynamic content insertion
+    await engine.insertDynamicBranch(branchOperation);
+    
+    // AI-driven content generation
+    engine.setAIContext(aiContext);
+    const aiBranches = await engine.generateAIBranches();
+  `
+};

package/dist/examples/src/narrative/branching/models.js

@@ -0,0 +1,5 @@
+"use strict";
+// QNCE Branching System - Platform Data Model (PDM)
+// Sprint #3 - Advanced Narrative & AI Integration
+Object.defineProperty(exports, "__esModule", { value: true });
+// All interfaces are exported above and ready for engine integration

package/dist/examples/src/performance/ObjectPool.js

@@ -0,0 +1,296 @@
+"use strict";
+// S2-T1: Object Pooling for Narrative Objects
+// Generic object pool to eliminate runtime allocations and reduce GC pressure
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.poolManager = exports.PoolManager = exports.PooledAsset = exports.PooledNode = exports.PooledFlow = exports.ObjectPool = void 0;
+/**
+ * Generic Object Pool for QNCE narrative objects
+ * Reduces GC pressure by reusing objects instead of creating new ones
+ */
+class ObjectPool {
+    pool = [];
+    createFn;
+    maxSize;
+    created = 0;
+    borrowed = 0;
+    returned = 0;
+    constructor(createFn, initialSize = 10, maxSize = 100) {
+        this.createFn = createFn;
+        this.maxSize = maxSize;
+        // Pre-populate pool
+        for (let i = 0; i < initialSize; i++) {
+            const obj = this.createFn();
+            obj.setInUse(false);
+            this.pool.push(obj);
+            this.created++;
+        }
+    }
+    /**
+     * Borrow an object from the pool
+     */
+    borrow() {
+        let obj;
+        if (this.pool.length > 0) {
+            obj = this.pool.pop();
+        }
+        else {
+            // Pool exhausted, create new object
+            obj = this.createFn();
+            this.created++;
+        }
+        obj.reset();
+        obj.setInUse(true);
+        this.borrowed++;
+        return obj;
+    }
+    /**
+     * Return an object to the pool
+     */
+    return(obj) {
+        if (!obj.isInUse()) {
+            console.warn('Attempting to return object that is not in use');
+            return;
+        }
+        obj.setInUse(false);
+        this.returned++;
+        // Only return to pool if under max size
+        if (this.pool.length < this.maxSize) {
+            this.pool.push(obj);
+        }
+        // Otherwise let GC handle it (controlled disposal)
+    }
+    /**
+     * Get pool statistics for monitoring
+     */
+    getStats() {
+        return {
+            poolSize: this.pool.length,
+            maxSize: this.maxSize,
+            created: this.created,
+            borrowed: this.borrowed,
+            returned: this.returned,
+            inUse: this.borrowed - this.returned,
+            hitRate: this.borrowed > 0 ? ((this.borrowed - this.created) / this.borrowed) * 100 : 0
+        };
+    }
+    /**
+     * Clear the pool (useful for testing)
+     */
+    clear() {
+        this.pool.forEach(obj => obj.setInUse(false));
+        this.pool.length = 0;
+        this.created = 0;
+        this.borrowed = 0;
+        this.returned = 0;
+    }
+    /**
+     * Resize the pool
+     */
+    resize(newSize) {
+        if (newSize < this.pool.length) {
+            // Shrink pool
+            this.pool.splice(newSize);
+        }
+        else if (newSize > this.pool.length) {
+            // Grow pool
+            const toAdd = newSize - this.pool.length;
+            for (let i = 0; i < toAdd && this.pool.length < this.maxSize; i++) {
+                const obj = this.createFn();
+                obj.setInUse(false);
+                this.pool.push(obj);
+                this.created++;
+            }
+        }
+    }
+}
+exports.ObjectPool = ObjectPool;
+/**
+ * Pooled Flow object for narrative state management
+ */
+class PooledFlow {
+    _inUse = false;
+    nodeId = '';
+    timestamp = 0;
+    metadata = {};
+    transitions = [];
+    constructor() {
+        this.reset();
+    }
+    reset() {
+        this.nodeId = '';
+        this.timestamp = 0;
+        this.metadata = {};
+        this.transitions.length = 0;
+    }
+    isInUse() {
+        return this._inUse;
+    }
+    setInUse(inUse) {
+        this._inUse = inUse;
+    }
+    // Flow-specific methods
+    initialize(nodeId, metadata) {
+        this.nodeId = nodeId;
+        this.timestamp = performance.now();
+        if (metadata) {
+            this.metadata = { ...metadata };
+        }
+    }
+    addTransition(fromNodeId, toNodeId) {
+        this.transitions.push(`${fromNodeId}->${toNodeId}`);
+    }
+    getDuration() {
+        return performance.now() - this.timestamp;
+    }
+}
+exports.PooledFlow = PooledFlow;
+/**
+ * Pooled Node object for narrative content
+ */
+class PooledNode {
+    _inUse = false;
+    id = '';
+    text = '';
+    choices = [];
+    flags = {};
+    lastAccessed = 0;
+    constructor() {
+        this.reset();
+    }
+    reset() {
+        this.id = '';
+        this.text = '';
+        this.choices.length = 0;
+        this.flags = {};
+        this.lastAccessed = 0;
+    }
+    isInUse() {
+        return this._inUse;
+    }
+    setInUse(inUse) {
+        this._inUse = inUse;
+    }
+    // Node-specific methods
+    initialize(id, text, choices = []) {
+        this.id = id;
+        this.text = text;
+        this.choices = [...choices];
+        this.lastAccessed = performance.now();
+    }
+    touch() {
+        this.lastAccessed = performance.now();
+    }
+}
+exports.PooledNode = PooledNode;
+/**
+ * Pooled Asset object for narrative resources
+ */
+class PooledAsset {
+    _inUse = false;
+    id = '';
+    type = '';
+    data = null;
+    size = 0;
+    loaded = false;
+    constructor() {
+        this.reset();
+    }
+    reset() {
+        this.id = '';
+        this.type = '';
+        this.data = null;
+        this.size = 0;
+        this.loaded = false;
+    }
+    isInUse() {
+        return this._inUse;
+    }
+    setInUse(inUse) {
+        this._inUse = inUse;
+    }
+    // Asset-specific methods
+    initialize(id, type, data) {
+        this.id = id;
+        this.type = type;
+        this.data = data;
+        this.size = this.calculateSize(data);
+        this.loaded = true;
+    }
+    calculateSize(data) {
+        if (typeof data === 'string') {
+            return data.length * 2; // Approximate UTF-16 size
+        }
+        if (data && typeof data === 'object') {
+            return JSON.stringify(data).length * 2;
+        }
+        return 0;
+    }
+}
+exports.PooledAsset = PooledAsset;
+/**
+ * Pool Manager - Centralized management of all object pools
+ */
+class PoolManager {
+    static instance;
+    flowPool;
+    nodePool;
+    assetPool;
+    constructor() {
+        // Initialize pools with different sizes based on expected usage
+        this.flowPool = new ObjectPool(() => new PooledFlow(), 5, 50);
+        this.nodePool = new ObjectPool(() => new PooledNode(), 20, 200);
+        this.assetPool = new ObjectPool(() => new PooledAsset(), 10, 100);
+    }
+    static getInstance() {
+        if (!PoolManager.instance) {
+            PoolManager.instance = new PoolManager();
+        }
+        return PoolManager.instance;
+    }
+    // Flow pool methods
+    borrowFlow() {
+        return this.flowPool.borrow();
+    }
+    returnFlow(flow) {
+        this.flowPool.return(flow);
+    }
+    // Node pool methods
+    borrowNode() {
+        return this.nodePool.borrow();
+    }
+    returnNode(node) {
+        this.nodePool.return(node);
+    }
+    // Asset pool methods
+    borrowAsset() {
+        return this.assetPool.borrow();
+    }
+    returnAsset(asset) {
+        this.assetPool.return(asset);
+    }
+    // Statistics and monitoring
+    getAllStats() {
+        return {
+            flows: this.flowPool.getStats(),
+            nodes: this.nodePool.getStats(),
+            assets: this.assetPool.getStats()
+        };
+    }
+    // Performance monitoring
+    getGCPressureReduction() {
+        const stats = this.getAllStats();
+        const totalHitRate = (stats.flows.hitRate +
+            stats.nodes.hitRate +
+            stats.assets.hitRate) / 3;
+        return totalHitRate;
+    }
+    // Cleanup for testing
+    clearAllPools() {
+        this.flowPool.clear();
+        this.nodePool.clear();
+        this.assetPool.clear();
+    }
+}
+exports.PoolManager = PoolManager;
+// Export singleton instance
+exports.poolManager = PoolManager.getInstance();