@magicborn/dialogue-forge 0.1.0

package/dist/esm/types/game-state.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Game State Integration Types
+ *
+ * These types define how Dialogue Forge integrates with your game's state system.
+ */
+import type { DialogueTree } from './index';
+import type { FlagSchema } from './flags';
+/**
+ * Flag value types - must be Yarn Spinner-compatible
+ */
+export type FlagValue = boolean | number | string;
+/**
+ * Current game state - flags and their values (flat, Yarn-compatible)
+ */
+export interface FlagState {
+    [flagId: string]: FlagValue;
+}
+/**
+ * Legacy alias for backward compatibility
+ */
+export type GameFlagState = FlagState;
+/**
+ * Base game state structure that users can extend
+ * Must have a 'flags' property, but can have any other structure
+ */
+export interface BaseGameState {
+    flags?: FlagState;
+}
+/**
+ * Convenience type for extending game state
+ */
+export type GameState<T extends Record<string, any> = {}> = BaseGameState & T;
+/**
+ * Updated flags after dialogue completes
+ */
+export interface DialogueResult {
+    updatedFlags: FlagState;
+    dialogueTree: DialogueTree;
+    completedNodeIds: string[];
+}
+/**
+ * Props for running a dialogue (simulation/play mode)
+ */
+export interface DialogueRunProps {
+    dialogue: DialogueTree;
+    gameState: Record<string, any>;
+    startNodeId?: string;
+    onComplete?: (result: DialogueResult) => void;
+    onFlagUpdate?: (flags: FlagState) => void;
+}
+/**
+ * Props for editing a dialogue
+ */
+export interface DialogueEditProps {
+    dialogue: DialogueTree | null;
+    flagSchema?: FlagSchema;
+    onChange: (dialogue: DialogueTree) => void;
+    onExportYarn?: (yarn: string) => void;
+    onExportJSON?: (json: string) => void;
+    className?: string;
+    showTitleEditor?: boolean;
+}

package/dist/esm/types/game-state.js

@@ -0,0 +1,6 @@
+/**
+ * Game State Integration Types
+ *
+ * These types define how Dialogue Forge integrates with your game's state system.
+ */
+export {};

package/dist/esm/types/index.d.ts

@@ -0,0 +1,77 @@
+import { ConditionOperator, NodeType } from './constants';
+export interface Choice {
+    id: string;
+    text: string;
+    nextNodeId?: string;
+    conditions?: Condition[];
+    setFlags?: string[];
+}
+export interface Condition {
+    flag: string;
+    operator: ConditionOperator;
+    value?: boolean | number | string;
+}
+/**
+ * Conditional content block for if/elseif/else statements
+ */
+export interface ConditionalBlock {
+    id: string;
+    type: 'if' | 'elseif' | 'else';
+    condition?: Condition[];
+    content: string;
+    speaker?: string;
+    nextNodeId?: string;
+}
+export interface DialogueNode {
+    id: string;
+    type: NodeType;
+    speaker?: string;
+    content: string;
+    choices?: Choice[];
+    nextNodeId?: string;
+    setFlags?: string[];
+    conditionalBlocks?: ConditionalBlock[];
+    x: number;
+    y: number;
+}
+export interface DialogueTree {
+    id: string;
+    title: string;
+    startNodeId: string;
+    nodes: Record<string, DialogueNode>;
+}
+import { FlagSchema } from './flags';
+export interface DialogueEditorProps {
+    dialogue: DialogueTree | null;
+    onChange: (dialogue: DialogueTree) => void;
+    onExportYarn?: (yarn: string) => void;
+    onExportJSON?: (json: string) => void;
+    flagSchema?: FlagSchema;
+    className?: string;
+    showTitleEditor?: boolean;
+    onNodeAdd?: (node: DialogueNode) => void;
+    onNodeDelete?: (nodeId: string) => void;
+    onNodeUpdate?: (nodeId: string, updates: Partial<DialogueNode>) => void;
+    onConnect?: (sourceId: string, targetId: string, sourceHandle?: string) => void;
+    onDisconnect?: (edgeId: string, sourceId: string, targetId: string) => void;
+    onNodeSelect?: (nodeId: string | null) => void;
+    onNodeDoubleClick?: (nodeId: string) => void;
+}
+export interface ContextMenu {
+    x: number;
+    y: number;
+    graphX: number;
+    graphY: number;
+}
+export interface EdgeDropMenu extends ContextMenu {
+    fromNodeId: string;
+    fromChoiceIdx?: number;
+}
+export interface DraggingEdge {
+    fromNodeId: string;
+    fromChoiceIdx?: number;
+    startX: number;
+    startY: number;
+    endX: number;
+    endY: number;
+}

package/dist/esm/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/utils/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const NODE_WIDTH = 200;
+export declare const NODE_HEIGHT = 100;
+export declare const DEFAULT_GRAPH_SCALE = 0.85;
+export declare const MIN_SCALE = 0.3;
+export declare const MAX_SCALE = 2;

package/dist/esm/utils/constants.js

@@ -0,0 +1,5 @@
+export const NODE_WIDTH = 200;
+export const NODE_HEIGHT = 100;
+export const DEFAULT_GRAPH_SCALE = 0.85;
+export const MIN_SCALE = 0.3;
+export const MAX_SCALE = 2;

package/dist/esm/utils/feature-flags.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Feature Flags
+ *
+ * Control optional features that are only for development/debugging.
+ * When users install the package, these can be disabled.
+ */
+/**
+ * Enable debug tools (ExampleLoader, etc.)
+ * Set to false in production builds or when distributing the package.
+ */
+export declare const ENABLE_DEBUG_TOOLS = true;

package/dist/esm/utils/feature-flags.js

@@ -0,0 +1,11 @@
+/**
+ * Feature Flags
+ *
+ * Control optional features that are only for development/debugging.
+ * When users install the package, these can be disabled.
+ */
+/**
+ * Enable debug tools (ExampleLoader, etc.)
+ * Set to false in production builds or when distributing the package.
+ */
+export const ENABLE_DEBUG_TOOLS = true;

package/dist/esm/utils/game-state-flattener.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Game State Flattening Utility
+ *
+ * Flattens nested game state structures into Yarn Spinner-compatible flat variables.
+ * Supports: flags, player, characters (as object), and any other nested structures.
+ *
+ * Rules:
+ * - Only includes truthy values (skips 0, false, null, undefined, empty strings)
+ * - Flattens nested objects using underscore separator
+ * - Characters are objects, not arrays (uses object keys as part of path)
+ * - All values must be boolean | number | string (Yarn-compatible)
+ */
+import type { FlagState } from '../types/game-state';
+export interface FlattenConfig {
+    /** Skip null/undefined values (default: true) */
+    excludeNull?: boolean;
+    /** Separator for nested keys (default: '_') */
+    separator?: string;
+    /** Maximum depth to flatten (default: 5, prevents infinite recursion) */
+    maxDepth?: number;
+}
+export interface FlattenedState {
+    flags: FlagState;
+    metadata: {
+        sourcePaths: Record<string, string>;
+    };
+}
+/**
+ * Flattens a game state object into Yarn Spinner-compatible flat variables
+ */
+export declare function flattenGameState(gameState: any, config?: FlattenConfig): FlattenedState;
+/**
+ * Validates that gameState has a valid structure
+ * Throws descriptive errors if validation fails
+ */
+export declare function validateGameState(gameState: any): asserts gameState is Record<string, any>;
+/**
+ * Extracts flags from gameState, flattening if necessary
+ * This is the main entry point for ScenePlayer
+ */
+export declare function extractFlagsFromGameState(gameState: any, config?: FlattenConfig): FlagState;

package/dist/esm/utils/game-state-flattener.js

@@ -0,0 +1,135 @@
+/**
+ * Game State Flattening Utility
+ *
+ * Flattens nested game state structures into Yarn Spinner-compatible flat variables.
+ * Supports: flags, player, characters (as object), and any other nested structures.
+ *
+ * Rules:
+ * - Only includes truthy values (skips 0, false, null, undefined, empty strings)
+ * - Flattens nested objects using underscore separator
+ * - Characters are objects, not arrays (uses object keys as part of path)
+ * - All values must be boolean | number | string (Yarn-compatible)
+ */
+/**
+ * Validates that a value is Yarn Spinner-compatible
+ */
+function isYarnCompatible(value) {
+    return typeof value === 'boolean' ||
+        typeof value === 'number' ||
+        typeof value === 'string';
+}
+/**
+ * Checks if a value is "truthy" for our purposes
+ * - Numbers: only include if !== 0
+ * - Booleans: only include if true
+ * - Strings: only include if non-empty
+ * - null/undefined: excluded if excludeNull is true
+ */
+function isTruthyValue(value, excludeNull) {
+    if (value == null) {
+        return !excludeNull; // Include null only if excludeNull is false
+    }
+    if (typeof value === 'number') {
+        return value !== 0; // Exclude zero
+    }
+    if (typeof value === 'boolean') {
+        return value === true; // Only include true
+    }
+    if (typeof value === 'string') {
+        return value.length > 0; // Exclude empty strings
+    }
+    return true; // Objects/arrays will be flattened further
+}
+/**
+ * Flattens a game state object into Yarn Spinner-compatible flat variables
+ */
+export function flattenGameState(gameState, config = {}) {
+    if (!gameState || typeof gameState !== 'object') {
+        throw new Error('GameState must be an object');
+    }
+    const { excludeNull = true, separator = '_', maxDepth = 5, } = config;
+    const flags = {};
+    const sourcePaths = {};
+    /**
+     * Recursively flatten a value
+     */
+    function flattenValue(value, path, depth = 0) {
+        // Prevent infinite recursion
+        if (depth > maxDepth) {
+            console.warn(`Max depth (${maxDepth}) reached at path: ${path}`);
+            return;
+        }
+        // Handle primitives (Yarn-compatible types)
+        if (isYarnCompatible(value)) {
+            // Only include truthy values
+            if (isTruthyValue(value, excludeNull)) {
+                const key = path.replace(/\./g, separator);
+                flags[key] = value;
+                sourcePaths[key] = path;
+            }
+            return;
+        }
+        // Handle null/undefined
+        if (value == null) {
+            if (!excludeNull) {
+                // Could store as string representation, but Yarn doesn't support null
+                // Skip for now - Yarn only supports boolean | number | string
+            }
+            return;
+        }
+        // Handle arrays - flatten all items
+        if (Array.isArray(value)) {
+            value.forEach((item, index) => {
+                const arrayPath = `${path}[${index}]`;
+                flattenValue(item, arrayPath, depth + 1);
+            });
+            return;
+        }
+        // Handle objects - flatten all properties
+        if (typeof value === 'object') {
+            Object.entries(value).forEach(([key, val]) => {
+                // Skip if value is not truthy (for nested objects, we still traverse)
+                // but we'll check truthiness when we hit primitives
+                const newPath = path ? `${path}.${key}` : key;
+                flattenValue(val, newPath, depth + 1);
+            });
+            return;
+        }
+        // Unknown type - skip
+        console.warn(`Skipping unsupported type at path: ${path} (type: ${typeof value})`);
+    }
+    // Flatten all top-level keys
+    Object.entries(gameState).forEach(([key, value]) => {
+        flattenValue(value, key, 0);
+    });
+    return {
+        flags,
+        metadata: {
+            sourcePaths,
+        },
+    };
+}
+/**
+ * Validates that gameState has a valid structure
+ * Throws descriptive errors if validation fails
+ */
+export function validateGameState(gameState) {
+    if (gameState == null) {
+        throw new Error('GameState cannot be null or undefined');
+    }
+    if (typeof gameState !== 'object') {
+        throw new Error(`GameState must be an object, got: ${typeof gameState}`);
+    }
+    if (Array.isArray(gameState)) {
+        throw new Error('GameState cannot be an array. Use an object with keys like { flags: {...}, player: {...} }');
+    }
+}
+/**
+ * Extracts flags from gameState, flattening if necessary
+ * This is the main entry point for ScenePlayer
+ */
+export function extractFlagsFromGameState(gameState, config) {
+    validateGameState(gameState);
+    const flattened = flattenGameState(gameState, config);
+    return flattened.flags;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Node Collision Resolution
+ *
+ * Utility for resolving overlapping nodes in freeform layout.
+ * Iteratively pushes overlapping nodes apart until stable.
+ *
+ * @see https://reactflow.dev/examples/layout/node-collisions
+ */
+import { DialogueTree } from '../../types';
+interface CollisionOptions {
+    /** Maximum iterations before giving up */
+    maxIterations?: number;
+    /** Overlap ratio threshold to trigger resolution (0-1) */
+    overlapThreshold?: number;
+    /** Extra margin to add when pushing nodes apart */
+    margin?: number;
+}
+/**
+ * Resolve node collisions for freeform layout.
+ * Iteratively pushes overlapping nodes apart until no collisions remain.
+ *
+ * @param dialogue - The dialogue tree with potentially overlapping nodes
+ * @param options - Configuration options
+ * @returns Updated dialogue tree with resolved positions
+ */
+export declare function resolveNodeCollisions(dialogue: DialogueTree, options?: CollisionOptions): DialogueTree;
+export {};

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

@@ -0,0 +1,74 @@
+/**
+ * Node Collision Resolution
+ *
+ * Utility for resolving overlapping nodes in freeform layout.
+ * Iteratively pushes overlapping nodes apart until stable.
+ *
+ * @see https://reactflow.dev/examples/layout/node-collisions
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+const NODE_WIDTH = 220;
+const NODE_HEIGHT = 120;
+// ============================================================================
+// Implementation
+// ============================================================================
+/**
+ * Resolve node collisions for freeform layout.
+ * Iteratively pushes overlapping nodes apart until no collisions remain.
+ *
+ * @param dialogue - The dialogue tree with potentially overlapping nodes
+ * @param options - Configuration options
+ * @returns Updated dialogue tree with resolved positions
+ */
+export function resolveNodeCollisions(dialogue, options = {}) {
+    const { maxIterations = 50, overlapThreshold = 0.3, margin = 20 } = options;
+    // Create mutable position array
+    const nodePositions = Object.values(dialogue.nodes).map(node => ({
+        id: node.id,
+        x: node.x,
+        y: node.y,
+        width: NODE_WIDTH,
+        height: NODE_HEIGHT,
+    }));
+    // Iteratively resolve collisions
+    for (let iter = 0; iter < maxIterations; iter++) {
+        let hasCollision = false;
+        for (let i = 0; i < nodePositions.length; i++) {
+            for (let j = i + 1; j < nodePositions.length; j++) {
+                const a = nodePositions[i];
+                const b = nodePositions[j];
+                // Calculate overlap
+                const overlapX = Math.max(0, Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x));
+                const overlapY = Math.max(0, Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y));
+                if (overlapX > 0 && overlapY > 0) {
+                    const overlapRatio = (overlapX * overlapY) / Math.min(a.width * a.height, b.width * b.height);
+                    if (overlapRatio > overlapThreshold) {
+                        hasCollision = true;
+                        // Calculate push direction (center to center)
+                        const dx = (b.x + b.width / 2) - (a.x + a.width / 2);
+                        const dy = (b.y + b.height / 2) - (a.y + a.height / 2);
+                        const dist = Math.sqrt(dx * dx + dy * dy) || 1;
+                        // Push apart
+                        const pushX = (dx / dist) * (overlapX / 2 + margin);
+                        const pushY = (dy / dist) * (overlapY / 2 + margin);
+                        a.x -= pushX / 2;
+                        a.y -= pushY / 2;
+                        b.x += pushX / 2;
+                        b.y += pushY / 2;
+                    }
+                }
+            }
+        }
+        // Exit early if no collisions found
+        if (!hasCollision)
+            break;
+    }
+    // Build updated dialogue with new positions
+    const updatedNodes = {};
+    for (const pos of nodePositions) {
+        updatedNodes[pos.id] = { ...dialogue.nodes[pos.id], x: pos.x, y: pos.y };
+    }
+    return { ...dialogue, nodes: updatedNodes };
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Layout Module
+ *
+ * Provides automatic graph layout algorithms for dialogue trees.
+ * Uses the Strategy pattern to allow swappable layout algorithms.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { layoutRegistry, applyLayout } from './layout';
+ *
+ * // Apply default layout (dagre)
+ * const result = applyLayout(dialogue);
+ *
+ * // Apply specific layout
+ * const result = applyLayout(dialogue, 'force');
+ *
+ * // With options
+ * const result = applyLayout(dialogue, 'dagre', { direction: 'LR' });
+ *
+ * // List available layouts
+ * console.log(layoutRegistry.list());
+ * ```
+ *
+ * ## Adding Custom Layouts
+ *
+ * See LAYOUT_STRATEGIES.md for documentation on creating custom layouts.
+ *
+ * @module layout
+ */
+import { DialogueTree } from '../../types';
+import { LayoutOptions, LayoutResult, LayoutDirection } from './types';
+/**
+ * Apply a layout algorithm to a dialogue tree
+ *
+ * @param dialogue - The dialogue tree to layout
+ * @param strategyId - Optional strategy ID (defaults to 'dagre')
+ * @param options - Optional layout configuration
+ * @returns Layout result with updated dialogue and metadata
+ *
+ * @example
+ * ```typescript
+ * // Default dagre layout
+ * const result = applyLayout(dialogue);
+ *
+ * // Horizontal dagre layout
+ * const result = applyLayout(dialogue, 'dagre', { direction: 'LR' });
+ *
+ * // Force-directed layout
+ * const result = applyLayout(dialogue, 'force');
+ *
+ * // Grid layout
+ * const result = applyLayout(dialogue, 'grid');
+ * ```
+ */
+export declare function applyLayout(dialogue: DialogueTree, strategyId?: string, options?: LayoutOptions): LayoutResult;
+/**
+ * Get the list of available layout strategies
+ */
+export declare function listLayouts(): Array<{
+    id: string;
+    name: string;
+    description: string;
+    isDefault: boolean;
+}>;
+/**
+ * Apply dagre layout (backward compatible function)
+ * @deprecated Use applyLayout(dialogue, 'dagre', options) instead
+ */
+export declare function applyDagreLayout(dialogue: DialogueTree, direction?: LayoutDirection): DialogueTree;
+/**
+ * Apply hierarchical layout (backward compatible alias)
+ * @deprecated Use applyLayout(dialogue, 'dagre', options) instead
+ */
+export declare const applyHierarchicalLayout: typeof applyDagreLayout;
+/**
+ * Resolve node collisions (kept for backward compatibility)
+ */
+export { resolveNodeCollisions } from './collision';
+export type { LayoutStrategy, LayoutOptions, LayoutResult, LayoutDirection } from './types';
+export { layoutRegistry } from './registry';
+export { DagreLayoutStrategy, ForceLayoutStrategy, GridLayoutStrategy } from './strategies';

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

@@ -0,0 +1,98 @@
+/**
+ * Layout Module
+ *
+ * Provides automatic graph layout algorithms for dialogue trees.
+ * Uses the Strategy pattern to allow swappable layout algorithms.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { layoutRegistry, applyLayout } from './layout';
+ *
+ * // Apply default layout (dagre)
+ * const result = applyLayout(dialogue);
+ *
+ * // Apply specific layout
+ * const result = applyLayout(dialogue, 'force');
+ *
+ * // With options
+ * const result = applyLayout(dialogue, 'dagre', { direction: 'LR' });
+ *
+ * // List available layouts
+ * console.log(layoutRegistry.list());
+ * ```
+ *
+ * ## Adding Custom Layouts
+ *
+ * See LAYOUT_STRATEGIES.md for documentation on creating custom layouts.
+ *
+ * @module layout
+ */
+import { layoutRegistry } from './registry';
+import { DagreLayoutStrategy, ForceLayoutStrategy, GridLayoutStrategy } from './strategies';
+// ============================================================================
+// Register Built-in Strategies
+// ============================================================================
+// Register all built-in strategies
+layoutRegistry.register(new DagreLayoutStrategy(), true); // Default
+layoutRegistry.register(new ForceLayoutStrategy());
+layoutRegistry.register(new GridLayoutStrategy());
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+/**
+ * Apply a layout algorithm to a dialogue tree
+ *
+ * @param dialogue - The dialogue tree to layout
+ * @param strategyId - Optional strategy ID (defaults to 'dagre')
+ * @param options - Optional layout configuration
+ * @returns Layout result with updated dialogue and metadata
+ *
+ * @example
+ * ```typescript
+ * // Default dagre layout
+ * const result = applyLayout(dialogue);
+ *
+ * // Horizontal dagre layout
+ * const result = applyLayout(dialogue, 'dagre', { direction: 'LR' });
+ *
+ * // Force-directed layout
+ * const result = applyLayout(dialogue, 'force');
+ *
+ * // Grid layout
+ * const result = applyLayout(dialogue, 'grid');
+ * ```
+ */
+export function applyLayout(dialogue, strategyId, options) {
+    return layoutRegistry.apply(strategyId, dialogue, options);
+}
+/**
+ * Get the list of available layout strategies
+ */
+export function listLayouts() {
+    return layoutRegistry.list();
+}
+// ============================================================================
+// Backward Compatibility
+// ============================================================================
+/**
+ * Apply dagre layout (backward compatible function)
+ * @deprecated Use applyLayout(dialogue, 'dagre', options) instead
+ */
+export function applyDagreLayout(dialogue, direction = 'TB') {
+    const result = applyLayout(dialogue, 'dagre', { direction });
+    return result.dialogue;
+}
+/**
+ * Apply hierarchical layout (backward compatible alias)
+ * @deprecated Use applyLayout(dialogue, 'dagre', options) instead
+ */
+export const applyHierarchicalLayout = applyDagreLayout;
+/**
+ * Resolve node collisions (kept for backward compatibility)
+ */
+export { resolveNodeCollisions } from './collision';
+// Registry
+export { layoutRegistry } from './registry';
+// Strategies (for direct use or extension)
+export { DagreLayoutStrategy, ForceLayoutStrategy, GridLayoutStrategy } from './strategies';