@magicborn/dialogue-forge 0.1.0

package/dist/esm/utils/layout/registry.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Layout Strategy Registry
+ *
+ * Central registry for all available layout algorithms.
+ * Implements the Registry pattern to manage strategy instances.
+ *
+ * @example
+ * ```typescript
+ * // Register a custom strategy
+ * layoutRegistry.register(new MyCustomLayout());
+ *
+ * // Use a strategy
+ * const result = layoutRegistry.apply('dagre', dialogue, { direction: 'LR' });
+ *
+ * // List available strategies
+ * const strategies = layoutRegistry.list();
+ * ```
+ */
+import { DialogueTree } from '../../types';
+import { LayoutStrategy, LayoutOptions, LayoutResult } from './types';
+declare class LayoutStrategyRegistry {
+    private strategies;
+    private defaultStrategyId;
+    /**
+     * Register a layout strategy
+     * @param strategy - The strategy to register
+     * @param isDefault - Whether this should be the default strategy
+     */
+    register(strategy: LayoutStrategy, isDefault?: boolean): void;
+    /**
+     * Unregister a layout strategy
+     * @param id - The strategy ID to remove
+     */
+    unregister(id: string): boolean;
+    /**
+     * Get a strategy by ID
+     * @param id - The strategy ID
+     */
+    get(id: string): LayoutStrategy | undefined;
+    /**
+     * Get the default strategy
+     */
+    getDefault(): LayoutStrategy | undefined;
+    /**
+     * Set the default strategy
+     * @param id - The strategy ID to set as default
+     */
+    setDefault(id: string): boolean;
+    /**
+     * List all registered strategies
+     */
+    list(): Array<{
+        id: string;
+        name: string;
+        description: string;
+        isDefault: boolean;
+    }>;
+    /**
+     * Apply a layout strategy to a dialogue tree
+     * @param id - The strategy ID (or undefined to use default)
+     * @param dialogue - The dialogue tree to layout
+     * @param options - Layout options
+     */
+    apply(id: string | undefined, dialogue: DialogueTree, options?: LayoutOptions): LayoutResult;
+    /**
+     * Check if a strategy is registered
+     * @param id - The strategy ID
+     */
+    has(id: string): boolean;
+    /**
+     * Get the number of registered strategies
+     */
+    get size(): number;
+    /**
+     * Clear all registered strategies
+     */
+    clear(): void;
+}
+/**
+ * Global layout strategy registry
+ *
+ * Use this to register custom strategies or apply layouts:
+ * ```typescript
+ * import { layoutRegistry } from './layout';
+ *
+ * // Apply layout
+ * const result = layoutRegistry.apply('dagre', dialogue);
+ * ```
+ */
+export declare const layoutRegistry: LayoutStrategyRegistry;
+export {};

package/dist/esm/utils/layout/registry.js

@@ -0,0 +1,148 @@
+/**
+ * Layout Strategy Registry
+ *
+ * Central registry for all available layout algorithms.
+ * Implements the Registry pattern to manage strategy instances.
+ *
+ * @example
+ * ```typescript
+ * // Register a custom strategy
+ * layoutRegistry.register(new MyCustomLayout());
+ *
+ * // Use a strategy
+ * const result = layoutRegistry.apply('dagre', dialogue, { direction: 'LR' });
+ *
+ * // List available strategies
+ * const strategies = layoutRegistry.list();
+ * ```
+ */
+// ============================================================================
+// Registry Implementation
+// ============================================================================
+class LayoutStrategyRegistry {
+    constructor() {
+        this.strategies = new Map();
+        this.defaultStrategyId = null;
+    }
+    /**
+     * Register a layout strategy
+     * @param strategy - The strategy to register
+     * @param isDefault - Whether this should be the default strategy
+     */
+    register(strategy, isDefault = false) {
+        if (this.strategies.has(strategy.id)) {
+            console.warn(`Layout strategy "${strategy.id}" is already registered. Overwriting.`);
+        }
+        this.strategies.set(strategy.id, { strategy, isDefault });
+        if (isDefault || this.defaultStrategyId === null) {
+            this.defaultStrategyId = strategy.id;
+        }
+    }
+    /**
+     * Unregister a layout strategy
+     * @param id - The strategy ID to remove
+     */
+    unregister(id) {
+        const removed = this.strategies.delete(id);
+        if (removed && this.defaultStrategyId === id) {
+            // Set a new default if we removed the default
+            const first = this.strategies.keys().next().value;
+            this.defaultStrategyId = first || null;
+        }
+        return removed;
+    }
+    /**
+     * Get a strategy by ID
+     * @param id - The strategy ID
+     */
+    get(id) {
+        return this.strategies.get(id)?.strategy;
+    }
+    /**
+     * Get the default strategy
+     */
+    getDefault() {
+        if (!this.defaultStrategyId)
+            return undefined;
+        return this.get(this.defaultStrategyId);
+    }
+    /**
+     * Set the default strategy
+     * @param id - The strategy ID to set as default
+     */
+    setDefault(id) {
+        if (!this.strategies.has(id)) {
+            console.warn(`Cannot set default: strategy "${id}" not found`);
+            return false;
+        }
+        this.defaultStrategyId = id;
+        return true;
+    }
+    /**
+     * List all registered strategies
+     */
+    list() {
+        return Array.from(this.strategies.entries()).map(([id, entry]) => ({
+            id,
+            name: entry.strategy.name,
+            description: entry.strategy.description,
+            isDefault: id === this.defaultStrategyId,
+        }));
+    }
+    /**
+     * Apply a layout strategy to a dialogue tree
+     * @param id - The strategy ID (or undefined to use default)
+     * @param dialogue - The dialogue tree to layout
+     * @param options - Layout options
+     */
+    apply(id, dialogue, options) {
+        const strategyId = id || this.defaultStrategyId;
+        if (!strategyId) {
+            throw new Error('No layout strategy available. Register a strategy first.');
+        }
+        const strategy = this.get(strategyId);
+        if (!strategy) {
+            throw new Error(`Layout strategy "${strategyId}" not found`);
+        }
+        // Check if strategy supports this dialogue
+        if (strategy.supports && !strategy.supports(dialogue)) {
+            console.warn(`Strategy "${strategyId}" may not support this dialogue structure`);
+        }
+        return strategy.apply(dialogue, options);
+    }
+    /**
+     * Check if a strategy is registered
+     * @param id - The strategy ID
+     */
+    has(id) {
+        return this.strategies.has(id);
+    }
+    /**
+     * Get the number of registered strategies
+     */
+    get size() {
+        return this.strategies.size;
+    }
+    /**
+     * Clear all registered strategies
+     */
+    clear() {
+        this.strategies.clear();
+        this.defaultStrategyId = null;
+    }
+}
+// ============================================================================
+// Singleton Instance
+// ============================================================================
+/**
+ * Global layout strategy registry
+ *
+ * Use this to register custom strategies or apply layouts:
+ * ```typescript
+ * import { layoutRegistry } from './layout';
+ *
+ * // Apply layout
+ * const result = layoutRegistry.apply('dagre', dialogue);
+ * ```
+ */
+export const layoutRegistry = new LayoutStrategyRegistry();

package/dist/esm/utils/layout/strategies/dagre.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Dagre Layout Strategy
+ *
+ * Hierarchical layout using the dagre library.
+ * Best for dialogue trees with clear start-to-end flow.
+ *
+ * @see https://github.com/dagrejs/dagre
+ * @see https://reactflow.dev/examples/layout/dagre
+ */
+import { DialogueTree } from '../../../types';
+import { LayoutStrategy, LayoutOptions, LayoutResult } from '../types';
+export declare class DagreLayoutStrategy implements LayoutStrategy {
+    readonly id = "dagre";
+    readonly name = "Dagre (Hierarchical)";
+    readonly description = "Hierarchical layout that flows from start to end. Best for linear dialogue with branches.";
+    readonly defaultOptions: Partial<LayoutOptions>;
+    apply(dialogue: DialogueTree, options?: LayoutOptions): LayoutResult;
+    supports(dialogue: DialogueTree): boolean;
+}

package/dist/esm/utils/layout/strategies/dagre.js

@@ -0,0 +1,182 @@
+/**
+ * Dagre Layout Strategy
+ *
+ * Hierarchical layout using the dagre library.
+ * Best for dialogue trees with clear start-to-end flow.
+ *
+ * @see https://github.com/dagrejs/dagre
+ * @see https://reactflow.dev/examples/layout/dagre
+ */
+import dagre from '@dagrejs/dagre';
+// ============================================================================
+// Constants
+// ============================================================================
+const NODE_WIDTH = 220;
+const NODE_HEIGHT = 120;
+const EXTRA_HEIGHT_PER_ITEM = 30;
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Calculate depth of each node from start using BFS
+ */
+function calculateNodeDepths(dialogue) {
+    const depths = new Map();
+    if (!dialogue.startNodeId)
+        return depths;
+    const queue = [
+        { id: dialogue.startNodeId, depth: 0 }
+    ];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const { id, depth } = queue.shift();
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        depths.set(id, depth);
+        const node = dialogue.nodes[id];
+        if (!node)
+            continue;
+        // Queue connected nodes
+        const nextIds = getOutgoingNodeIds(node);
+        for (const nextId of nextIds) {
+            if (dialogue.nodes[nextId] && !visited.has(nextId)) {
+                queue.push({ id: nextId, depth: depth + 1 });
+            }
+        }
+    }
+    return depths;
+}
+/**
+ * Get all outgoing node IDs from a node
+ */
+function getOutgoingNodeIds(node) {
+    const ids = [];
+    if (node.nextNodeId)
+        ids.push(node.nextNodeId);
+    node.choices?.forEach(c => c.nextNodeId && ids.push(c.nextNodeId));
+    node.conditionalBlocks?.forEach(b => b.nextNodeId && ids.push(b.nextNodeId));
+    return ids;
+}
+/**
+ * Estimate node height based on content
+ */
+function estimateNodeHeight(node) {
+    const itemCount = Math.max(node.choices?.length || 0, node.conditionalBlocks?.length || 0);
+    return NODE_HEIGHT + itemCount * EXTRA_HEIGHT_PER_ITEM;
+}
+// ============================================================================
+// Strategy Implementation
+// ============================================================================
+export class DagreLayoutStrategy {
+    constructor() {
+        this.id = 'dagre';
+        this.name = 'Dagre (Hierarchical)';
+        this.description = 'Hierarchical layout that flows from start to end. Best for linear dialogue with branches.';
+        this.defaultOptions = {
+            direction: 'TB',
+            nodeSpacingX: 80,
+            nodeSpacingY: 120,
+            margin: 50,
+        };
+    }
+    apply(dialogue, options) {
+        const startTime = performance.now();
+        const opts = { ...this.defaultOptions, ...options };
+        const direction = opts.direction || 'TB';
+        const isHorizontal = direction === 'LR';
+        // Create dagre graph
+        const g = new dagre.graphlib.Graph();
+        g.setDefaultEdgeLabel(() => ({}));
+        // Configure layout
+        g.setGraph({
+            rankdir: direction,
+            nodesep: isHorizontal ? opts.nodeSpacingX : opts.nodeSpacingY,
+            ranksep: isHorizontal ? opts.nodeSpacingY : opts.nodeSpacingX,
+            marginx: opts.margin,
+            marginy: opts.margin,
+            ranker: 'network-simplex',
+            align: 'UL',
+            acyclicer: 'greedy',
+            edgesep: 15,
+        });
+        // Add nodes ordered by depth
+        const nodeDepths = calculateNodeDepths(dialogue);
+        const sortedNodeIds = Object.keys(dialogue.nodes).sort((a, b) => {
+            return (nodeDepths.get(a) ?? Infinity) - (nodeDepths.get(b) ?? Infinity);
+        });
+        for (const nodeId of sortedNodeIds) {
+            const node = dialogue.nodes[nodeId];
+            g.setNode(nodeId, {
+                width: NODE_WIDTH,
+                height: estimateNodeHeight(node),
+            });
+        }
+        // Add edges with weights
+        for (const node of Object.values(dialogue.nodes)) {
+            if (node.nextNodeId && dialogue.nodes[node.nextNodeId]) {
+                g.setEdge(node.id, node.nextNodeId, { weight: 3, minlen: 1 });
+            }
+            for (const choice of node.choices || []) {
+                if (choice.nextNodeId && dialogue.nodes[choice.nextNodeId]) {
+                    g.setEdge(node.id, choice.nextNodeId, { weight: 2, minlen: 1 });
+                }
+            }
+            for (const block of node.conditionalBlocks || []) {
+                if (block.nextNodeId && dialogue.nodes[block.nextNodeId]) {
+                    g.setEdge(node.id, block.nextNodeId, { weight: 2, minlen: 1 });
+                }
+            }
+        }
+        // Run layout
+        dagre.layout(g);
+        // Extract positions and calculate bounds
+        let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+        const updatedNodes = {};
+        for (const nodeId of Object.keys(dialogue.nodes)) {
+            const node = dialogue.nodes[nodeId];
+            const dagreNode = g.node(nodeId);
+            if (dagreNode) {
+                const x = dagreNode.x - NODE_WIDTH / 2;
+                const y = dagreNode.y - NODE_HEIGHT / 2;
+                updatedNodes[nodeId] = { ...node, x, y };
+                minX = Math.min(minX, x);
+                maxX = Math.max(maxX, x + NODE_WIDTH);
+                minY = Math.min(minY, y);
+                maxY = Math.max(maxY, y + NODE_HEIGHT);
+            }
+            else {
+                // Orphan node
+                updatedNodes[nodeId] = { ...node };
+            }
+        }
+        // Ensure start node is at edge
+        const startNodeId = dialogue.startNodeId;
+        if (startNodeId && updatedNodes[startNodeId]) {
+            const threshold = 50;
+            if (isHorizontal && updatedNodes[startNodeId].x - minX > threshold) {
+                updatedNodes[startNodeId].x = minX;
+            }
+            else if (!isHorizontal && updatedNodes[startNodeId].y - minY > threshold) {
+                updatedNodes[startNodeId].y = minY;
+            }
+        }
+        const computeTimeMs = performance.now() - startTime;
+        return {
+            dialogue: { ...dialogue, nodes: updatedNodes },
+            metadata: {
+                computeTimeMs,
+                nodeCount: Object.keys(dialogue.nodes).length,
+                bounds: {
+                    minX, minY, maxX, maxY,
+                    width: maxX - minX,
+                    height: maxY - minY,
+                },
+            },
+        };
+    }
+    supports(dialogue) {
+        // Dagre works best with connected graphs that have a clear start
+        return !!dialogue.startNodeId && Object.keys(dialogue.nodes).length > 0;
+    }
+}

package/dist/esm/utils/layout/strategies/force.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Force-Directed Layout Strategy
+ *
+ * Physics-based layout that spreads nodes evenly.
+ * Good for exploring graph structure without hierarchy.
+ *
+ * Uses a simple force simulation:
+ * - Nodes repel each other (like charged particles)
+ * - Connected nodes attract (like springs)
+ */
+import { DialogueTree } from '../../../types';
+import { LayoutStrategy, LayoutOptions, LayoutResult } from '../types';
+export declare class ForceLayoutStrategy implements LayoutStrategy {
+    readonly id = "force";
+    readonly name = "Force-Directed";
+    readonly description = "Physics-based layout that spreads nodes evenly. Good for exploring complex graphs.";
+    readonly defaultOptions: Partial<LayoutOptions>;
+    apply(dialogue: DialogueTree, options?: LayoutOptions): LayoutResult;
+    private emptyResult;
+    supports(): boolean;
+}

package/dist/esm/utils/layout/strategies/force.js

@@ -0,0 +1,178 @@
+/**
+ * Force-Directed Layout Strategy
+ *
+ * Physics-based layout that spreads nodes evenly.
+ * Good for exploring graph structure without hierarchy.
+ *
+ * Uses a simple force simulation:
+ * - Nodes repel each other (like charged particles)
+ * - Connected nodes attract (like springs)
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+const NODE_WIDTH = 220;
+const NODE_HEIGHT = 120;
+// Force simulation parameters
+const REPULSION_STRENGTH = 5000; // How strongly nodes push each other
+const ATTRACTION_STRENGTH = 0.1; // How strongly edges pull nodes together
+const DAMPING = 0.9; // Velocity reduction per iteration
+const MAX_ITERATIONS = 100; // Maximum simulation steps
+const MIN_MOVEMENT = 0.5; // Stop when movement is below this
+// ============================================================================
+// Helper Functions
+// ============================================================================
+function getConnectedNodeIds(node) {
+    const ids = [];
+    if (node.nextNodeId)
+        ids.push(node.nextNodeId);
+    node.choices?.forEach(c => c.nextNodeId && ids.push(c.nextNodeId));
+    node.conditionalBlocks?.forEach(b => b.nextNodeId && ids.push(b.nextNodeId));
+    return ids;
+}
+// ============================================================================
+// Strategy Implementation
+// ============================================================================
+export class ForceLayoutStrategy {
+    constructor() {
+        this.id = 'force';
+        this.name = 'Force-Directed';
+        this.description = 'Physics-based layout that spreads nodes evenly. Good for exploring complex graphs.';
+        this.defaultOptions = {
+            nodeSpacingX: 300,
+            nodeSpacingY: 200,
+            margin: 50,
+        };
+    }
+    apply(dialogue, options) {
+        const startTime = performance.now();
+        const opts = { ...this.defaultOptions, ...options };
+        const nodeIds = Object.keys(dialogue.nodes);
+        if (nodeIds.length === 0) {
+            return this.emptyResult(dialogue, startTime);
+        }
+        // Initialize node positions in a circle
+        const states = new Map();
+        const centerX = 500;
+        const centerY = 500;
+        const radius = Math.max(200, nodeIds.length * 30);
+        nodeIds.forEach((id, i) => {
+            const angle = (2 * Math.PI * i) / nodeIds.length;
+            states.set(id, {
+                id,
+                x: centerX + radius * Math.cos(angle),
+                y: centerY + radius * Math.sin(angle),
+                vx: 0,
+                vy: 0,
+            });
+        });
+        // Build edge list for attraction
+        const edges = [];
+        for (const node of Object.values(dialogue.nodes)) {
+            for (const targetId of getConnectedNodeIds(node)) {
+                if (dialogue.nodes[targetId]) {
+                    edges.push({ source: node.id, target: targetId });
+                }
+            }
+        }
+        // Run force simulation
+        for (let iter = 0; iter < MAX_ITERATIONS; iter++) {
+            let maxMovement = 0;
+            // Calculate repulsion forces between all node pairs
+            for (let i = 0; i < nodeIds.length; i++) {
+                for (let j = i + 1; j < nodeIds.length; j++) {
+                    const a = states.get(nodeIds[i]);
+                    const b = states.get(nodeIds[j]);
+                    const dx = b.x - a.x;
+                    const dy = b.y - a.y;
+                    const dist = Math.sqrt(dx * dx + dy * dy) || 1;
+                    // Repulsion force (inverse square law)
+                    const force = REPULSION_STRENGTH / (dist * dist);
+                    const fx = (dx / dist) * force;
+                    const fy = (dy / dist) * force;
+                    a.vx -= fx;
+                    a.vy -= fy;
+                    b.vx += fx;
+                    b.vy += fy;
+                }
+            }
+            // Calculate attraction forces along edges
+            for (const edge of edges) {
+                const source = states.get(edge.source);
+                const target = states.get(edge.target);
+                if (!source || !target)
+                    continue;
+                const dx = target.x - source.x;
+                const dy = target.y - source.y;
+                const dist = Math.sqrt(dx * dx + dy * dy) || 1;
+                // Attraction force (Hooke's law)
+                const force = dist * ATTRACTION_STRENGTH;
+                const fx = (dx / dist) * force;
+                const fy = (dy / dist) * force;
+                source.vx += fx;
+                source.vy += fy;
+                target.vx -= fx;
+                target.vy -= fy;
+            }
+            // Apply velocities with damping
+            for (const state of states.values()) {
+                state.x += state.vx;
+                state.y += state.vy;
+                state.vx *= DAMPING;
+                state.vy *= DAMPING;
+                maxMovement = Math.max(maxMovement, Math.abs(state.vx) + Math.abs(state.vy));
+            }
+            // Early exit if stable
+            if (maxMovement < MIN_MOVEMENT)
+                break;
+        }
+        // Calculate bounds and apply positions
+        let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+        const updatedNodes = {};
+        for (const [id, state] of states) {
+            const node = dialogue.nodes[id];
+            updatedNodes[id] = { ...node, x: state.x, y: state.y };
+            minX = Math.min(minX, state.x);
+            maxX = Math.max(maxX, state.x + NODE_WIDTH);
+            minY = Math.min(minY, state.y);
+            maxY = Math.max(maxY, state.y + NODE_HEIGHT);
+        }
+        // Normalize to start from margin
+        const margin = opts.margin || 50;
+        const offsetX = margin - minX;
+        const offsetY = margin - minY;
+        for (const id of nodeIds) {
+            updatedNodes[id].x += offsetX;
+            updatedNodes[id].y += offsetY;
+        }
+        const computeTimeMs = performance.now() - startTime;
+        return {
+            dialogue: { ...dialogue, nodes: updatedNodes },
+            metadata: {
+                computeTimeMs,
+                nodeCount: nodeIds.length,
+                bounds: {
+                    minX: margin,
+                    minY: margin,
+                    maxX: maxX + offsetX,
+                    maxY: maxY + offsetY,
+                    width: maxX - minX,
+                    height: maxY - minY,
+                },
+            },
+        };
+    }
+    emptyResult(dialogue, startTime) {
+        return {
+            dialogue,
+            metadata: {
+                computeTimeMs: performance.now() - startTime,
+                nodeCount: 0,
+                bounds: { minX: 0, minY: 0, maxX: 0, maxY: 0, width: 0, height: 0 },
+            },
+        };
+    }
+    supports() {
+        return true; // Works with any graph
+    }
+}

package/dist/esm/utils/layout/strategies/grid.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Grid Layout Strategy
+ *
+ * Simple grid-based layout that arranges nodes in rows and columns.
+ * Useful for getting a quick overview of all nodes.
+ */
+import { DialogueTree } from '../../../types';
+import { LayoutStrategy, LayoutOptions, LayoutResult } from '../types';
+export declare class GridLayoutStrategy implements LayoutStrategy {
+    readonly id = "grid";
+    readonly name = "Grid";
+    readonly description = "Arranges nodes in a simple grid pattern. Good for viewing all nodes at once.";
+    readonly defaultOptions: Partial<LayoutOptions>;
+    apply(dialogue: DialogueTree, options?: LayoutOptions): LayoutResult;
+    private emptyResult;
+    supports(): boolean;
+}