@magicborn/dialogue-forge 0.1.0 → 0.1.2

package/dist/esm/components/CharacterSelector.js

@@ -0,0 +1,89 @@
+/**
+ * CharacterSelector - Combobox with search for selecting characters
+ */
+import React, { useState, useRef, useEffect } from 'react';
+import { Search, X, User } from 'lucide-react';
+export function CharacterSelector({ characters = {}, selectedCharacterId, onSelect, placeholder = 'Select character...', className = '', compact = false, }) {
+    const [isOpen, setIsOpen] = useState(false);
+    const [searchQuery, setSearchQuery] = useState('');
+    const containerRef = useRef(null);
+    const inputRef = useRef(null);
+    const selectedCharacter = selectedCharacterId ? characters[selectedCharacterId] : undefined;
+    // Filter characters based on search query
+    const filteredCharacters = Object.entries(characters).filter(([id, character]) => {
+        if (!searchQuery.trim())
+            return true;
+        const query = searchQuery.toLowerCase();
+        return (character.name.toLowerCase().includes(query) ||
+            character.id.toLowerCase().includes(query) ||
+            (character.description && character.description.toLowerCase().includes(query)));
+    });
+    // Close dropdown when clicking outside
+    useEffect(() => {
+        function handleClickOutside(event) {
+            if (containerRef.current && !containerRef.current.contains(event.target)) {
+                setIsOpen(false);
+                setSearchQuery('');
+            }
+        }
+        if (isOpen) {
+            document.addEventListener('mousedown', handleClickOutside);
+            // Focus input when dropdown opens
+            setTimeout(() => inputRef.current?.focus(), 0);
+        }
+        return () => {
+            document.removeEventListener('mousedown', handleClickOutside);
+        };
+    }, [isOpen]);
+    const handleSelect = (characterId) => {
+        onSelect(characterId);
+        setIsOpen(false);
+        setSearchQuery('');
+    };
+    const handleClear = (e) => {
+        e.stopPropagation();
+        onSelect(undefined);
+        setIsOpen(false);
+        setSearchQuery('');
+    };
+    // Compact mode for conditional blocks
+    if (compact) {
+        return (React.createElement("div", { ref: containerRef, className: `relative ${className}` },
+            React.createElement("button", { type: "button", onClick: () => setIsOpen(!isOpen), className: "flex items-center gap-1.5 bg-df-elevated border border-df-control-border rounded px-1.5 py-0.5 text-[10px] text-df-text-primary hover:border-df-control-hover transition-colors" }, selectedCharacter ? (React.createElement(React.Fragment, null,
+                React.createElement("span", { className: "text-sm flex-shrink-0" }, selectedCharacter.avatar || '👤'),
+                React.createElement("span", { className: "text-[10px] truncate max-w-[80px]" }, selectedCharacter.name),
+                React.createElement("button", { onClick: handleClear, className: "flex-shrink-0 p-0.5 hover:bg-df-control-hover rounded", title: "Clear character" },
+                    React.createElement(X, { size: 10, className: "text-df-text-secondary" })))) : (React.createElement(React.Fragment, null,
+                React.createElement(User, { size: 10, className: "text-df-text-secondary flex-shrink-0" }),
+                React.createElement("span", { className: "text-[10px] text-df-text-secondary" }, placeholder)))),
+            isOpen && (React.createElement("div", { className: "absolute z-50 mt-1 w-48 bg-df-sidebar-bg border border-df-sidebar-border rounded-lg shadow-xl max-h-48 overflow-hidden flex flex-col" },
+                React.createElement("div", { className: "p-1.5 border-b border-df-sidebar-border" },
+                    React.createElement("div", { className: "relative" },
+                        React.createElement(Search, { size: 12, className: "absolute left-1.5 top-1/2 -translate-y-1/2 text-df-text-secondary" }),
+                        React.createElement("input", { ref: inputRef, type: "text", value: searchQuery, onChange: (e) => setSearchQuery(e.target.value), placeholder: "Search...", className: "w-full bg-df-elevated border border-df-control-border rounded px-1.5 py-1 pl-6 text-[10px] text-df-text-primary placeholder:text-df-text-tertiary focus:border-df-control-hover outline-none" }))),
+                React.createElement("div", { className: "overflow-y-auto" }, filteredCharacters.length === 0 ? (React.createElement("div", { className: "p-2 text-[10px] text-df-text-secondary text-center" }, searchQuery ? 'No matches' : 'No characters')) : (filteredCharacters.map(([id, character]) => (React.createElement("button", { key: id, type: "button", onClick: () => handleSelect(id), className: `w-full flex items-center gap-1.5 px-2 py-1 text-left hover:bg-df-elevated transition-colors ${selectedCharacterId === id ? 'bg-df-npc-selected/20' : ''}` },
+                    React.createElement("span", { className: "text-sm flex-shrink-0" }, character.avatar || '👤'),
+                    React.createElement("span", { className: "text-[10px] text-df-text-primary truncate flex-1" }, character.name),
+                    selectedCharacterId === id && (React.createElement("div", { className: "flex-shrink-0 w-1.5 h-1.5 rounded-full bg-df-npc-selected" })))))))))));
+    }
+    // Full mode (existing)
+    return (React.createElement("div", { ref: containerRef, className: `relative ${className}` },
+        React.createElement("button", { type: "button", onClick: () => setIsOpen(!isOpen), className: "w-full flex items-center gap-2 bg-df-elevated border border-df-control-border rounded px-2 py-1.5 text-sm text-df-text-primary hover:border-df-control-hover transition-colors" }, selectedCharacter ? (React.createElement(React.Fragment, null,
+            React.createElement("span", { className: "text-lg flex-shrink-0" }, selectedCharacter.avatar || '👤'),
+            React.createElement("span", { className: "flex-1 text-left truncate" }, selectedCharacter.name),
+            React.createElement("button", { onClick: handleClear, className: "flex-shrink-0 p-0.5 hover:bg-df-control-hover rounded", title: "Clear character" },
+                React.createElement(X, { size: 12, className: "text-df-text-secondary" })))) : (React.createElement(React.Fragment, null,
+            React.createElement(User, { size: 14, className: "text-df-text-secondary flex-shrink-0" }),
+            React.createElement("span", { className: "flex-1 text-left text-df-text-secondary" }, placeholder)))),
+        isOpen && (React.createElement("div", { className: "absolute z-50 mt-1 w-full bg-df-sidebar-bg border border-df-sidebar-border rounded-lg shadow-xl max-h-64 overflow-hidden flex flex-col" },
+            React.createElement("div", { className: "p-2 border-b border-df-sidebar-border" },
+                React.createElement("div", { className: "relative" },
+                    React.createElement(Search, { size: 14, className: "absolute left-2 top-1/2 -translate-y-1/2 text-df-text-secondary" }),
+                    React.createElement("input", { ref: inputRef, type: "text", value: searchQuery, onChange: (e) => setSearchQuery(e.target.value), placeholder: "Search characters...", className: "w-full bg-df-elevated border border-df-control-border rounded px-2 py-1.5 pl-7 text-sm text-df-text-primary placeholder:text-df-text-tertiary focus:border-df-control-hover outline-none" }))),
+            React.createElement("div", { className: "overflow-y-auto" }, filteredCharacters.length === 0 ? (React.createElement("div", { className: "p-3 text-sm text-df-text-secondary text-center" }, searchQuery ? 'No characters found' : 'No characters available')) : (filteredCharacters.map(([id, character]) => (React.createElement("button", { key: id, type: "button", onClick: () => handleSelect(id), className: `w-full flex items-center gap-2 px-3 py-2 text-left hover:bg-df-elevated transition-colors ${selectedCharacterId === id ? 'bg-df-npc-selected/20' : ''}` },
+                React.createElement("span", { className: "text-lg flex-shrink-0" }, character.avatar || '👤'),
+                React.createElement("div", { className: "flex-1 min-w-0" },
+                    React.createElement("div", { className: "text-sm text-df-text-primary font-medium truncate" }, character.name),
+                    character.description && (React.createElement("div", { className: "text-xs text-df-text-secondary truncate" }, character.description))),
+                selectedCharacterId === id && (React.createElement("div", { className: "flex-shrink-0 w-2 h-2 rounded-full bg-df-npc-selected" })))))))))));
+}

package/dist/esm/components/ConditionalNodeV2.d.ts

@@ -2,10 +2,12 @@ import React from 'react';
 import { NodeProps } from 'reactflow';
 import { DialogueNode } from '../types';
 import { FlagSchema } from '../types/flags';
+import { Character } from '../types/characters';
 import { LayoutDirection } from '../utils/layout';
 interface ConditionalNodeData {
     node: DialogueNode;
     flagSchema?: FlagSchema;
+    characters?: Record<string, Character>;
     isDimmed?: boolean;
     isInPath?: boolean;
     layoutDirection?: LayoutDirection;

package/dist/esm/components/ConditionalNodeV2.js

@@ -1,10 +1,10 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { Handle, Position, useUpdateNodeInternals } from 'reactflow';
-import { GitBranch, Play, Flag } from 'lucide-react';
+import { GitBranch, Play, Flag, Hash, Code } from 'lucide-react';
 // Color scheme for conditional block edges
 const CONDITIONAL_COLORS = ['#3b82f6', '#8b5cf6', '#06b6d4', '#22c55e', '#f59e0b'];
 export function ConditionalNodeV2({ data, selected }) {
-    const { node, flagSchema, isDimmed, isInPath, layoutDirection = 'TB', isStartNode, isEndNode } = data;
+    const { node, flagSchema, characters = {}, isDimmed, isInPath, layoutDirection = 'TB', isStartNode, isEndNode } = data;
     const blocks = node.conditionalBlocks || [];
     const updateNodeInternals = useUpdateNodeInternals();
     const headerRef = useRef(null);
@@ -13,6 +13,7 @@ export function ConditionalNodeV2({ data, selected }) {
     // Handle positions based on layout direction
     const isHorizontal = layoutDirection === 'LR';
     const targetPosition = isHorizontal ? Position.Left : Position.Top;
+    const sourcePosition = isHorizontal ? Position.Right : Position.Bottom;
     // Calculate handle positions based on actual rendered heights
     useEffect(() => {
         if (headerRef.current && blocks.length > 0) {
@@ -49,23 +50,41 @@ export function ConditionalNodeV2({ data, selected }) {
             : isEndNode
                 ? 'border-df-end shadow-md'
                 : 'border-df-conditional-border';
-    return (React.createElement("div", { className: `rounded-lg border-2 transition-all duration-300 ${borderClass} ${isInPath ? 'border-df-conditional-border/70' : ''} bg-df-conditional-bg min-w-[200px] relative`, style: isDimmed ? { opacity: 0.35, filter: 'saturate(0.3)' } : undefined },
-        isStartNode && (React.createElement("div", { className: "absolute -top-2 -left-2 bg-df-start text-df-text-primary text-[8px] font-bold px-1.5 py-0.5 rounded-full flex items-center gap-0.5 shadow-lg z-10" },
-            React.createElement(Play, { size: 8, fill: "currentColor" }),
-            " START")),
-        isEndNode && (React.createElement("div", { className: "absolute -top-2 -right-2 bg-df-end text-df-text-primary text-[8px] font-bold px-1.5 py-0.5 rounded-full flex items-center gap-0.5 shadow-lg z-10" },
-            React.createElement(Flag, { size: 8 }),
-            " END")),
+    // Header background for conditional nodes
+    const headerBgClass = isStartNode
+        ? 'bg-df-start-bg'
+        : isEndNode
+            ? 'bg-df-end-bg'
+            : 'bg-df-conditional-header';
+    return (React.createElement("div", { className: `rounded-lg border-2 transition-all duration-300 ${borderClass} ${isInPath ? 'border-df-conditional-border/70' : ''} bg-df-conditional-bg min-w-[320px] max-w-[450px] relative overflow-hidden`, style: isDimmed ? { opacity: 0.35, filter: 'saturate(0.3)' } : undefined },
         React.createElement(Handle, { type: "target", position: targetPosition, className: "!bg-df-control-bg !border-df-control-border !w-4 !h-4 !rounded-full" }),
-        React.createElement("div", { ref: headerRef, className: "px-3 py-1.5 border-b border-df-control-border bg-df-conditional-header flex items-center gap-2 rounded-t-lg" },
-            React.createElement(GitBranch, { size: 12, className: "text-df-conditional-border" }),
-            React.createElement("span", { className: "text-[10px] font-mono text-df-text-secondary truncate flex-1" }, node.id),
-            React.createElement("span", { className: "text-[10px] text-df-conditional-border" }, "IF/ELSE")),
-        React.createElement("div", { className: "py-1" }, blocks.map((block, idx) => {
+        React.createElement("div", { ref: headerRef, className: `${headerBgClass} border-b-2 border-df-conditional-border px-3 py-2.5 flex items-center gap-3 relative` },
+            React.createElement("div", { className: "w-14 h-14 rounded-full bg-df-conditional-bg border-[3px] border-df-conditional-border flex items-center justify-center shadow-lg flex-shrink-0" },
+                React.createElement(Code, { size: 20, className: "text-df-conditional-selected" })),
+            React.createElement("div", { className: "flex-1 min-w-0" },
+                React.createElement("h3", { className: "text-base font-bold text-df-text-primary truncate leading-tight" }, "Conditional Logic")),
+            React.createElement("div", { className: "flex items-center gap-2 flex-shrink-0" },
+                React.createElement("div", { className: "flex items-center gap-1 px-2 py-1 rounded bg-df-base/50 border border-df-control-border", title: `Node ID: ${node.id}` },
+                    React.createElement(Hash, { size: 12, className: "text-df-text-secondary" }),
+                    React.createElement("span", { className: "text-[10px] font-mono text-df-text-secondary" }, node.id)),
+                React.createElement("div", { className: "flex items-center gap-1 px-2 py-1 rounded bg-df-conditional-selected/20 border border-df-conditional-selected/50", title: "Conditional Node" },
+                    React.createElement(GitBranch, { size: 14, className: "text-df-conditional-selected" }),
+                    React.createElement("span", { className: "text-[10px] font-semibold text-df-conditional-selected" }, "IF/ELSE"))),
+            isStartNode && (React.createElement("div", { className: "absolute top-1 right-1 bg-df-start text-df-text-primary text-[8px] font-bold px-1.5 py-0.5 rounded flex items-center gap-0.5 shadow-lg z-20" },
+                React.createElement(Play, { size: 8, fill: "currentColor" }),
+                " START")),
+            isEndNode && (React.createElement("div", { className: "absolute top-1 right-1 bg-df-end text-df-text-primary text-[8px] font-bold px-1.5 py-0.5 rounded flex items-center gap-0.5 shadow-lg z-20" },
+                React.createElement(Flag, { size: 8 }),
+                " END"))),
+        React.createElement("div", { className: "px-4 py-3" }, blocks.map((block, idx) => {
             const color = CONDITIONAL_COLORS[idx % CONDITIONAL_COLORS.length];
             const blockType = block.type === 'if' ? 'IF' : block.type === 'elseif' ? 'ELSE IF' : 'ELSE';
-            return (React.createElement("div", { key: block.id, ref: el => { blockRefs.current[idx] = el; }, className: "px-3 py-1.5 border-b border-df-control-border last:border-b-0" },
-                React.createElement("div", { className: "flex items-center gap-2 mb-1" },
+            // Get character if characterId is set
+            const character = block.characterId ? characters[block.characterId] : undefined;
+            const displayName = character ? character.name : (block.speaker || undefined);
+            const avatar = character?.avatar || '👤';
+            return (React.createElement("div", { key: block.id, ref: el => { blockRefs.current[idx] = el; }, className: "px-3 py-2 border-b border-df-control-border last:border-b-0" },
+                React.createElement("div", { className: "flex items-center gap-2 mb-1.5" },
                     React.createElement("span", { className: "text-[9px] px-1.5 py-0.5 rounded bg-df-base text-df-text-primary font-semibold" }, blockType),
                     block.condition && block.condition.length > 0 && (React.createElement("span", { className: "text-[9px] text-df-text-secondary font-mono truncate flex-1" }, block.condition.map((c) => {
                         const varName = `$${c.flag}`;
@@ -85,27 +104,29 @@ export function ConditionalNodeV2({ data, selected }) {
                         }
                         return '';
                     }).filter(c => c).join(' and ').slice(0, 30)))),
-                block.speaker && (React.createElement("div", { className: "text-[9px] text-df-conditional-border font-medium" }, block.speaker)),
-                React.createElement("div", { className: "text-[10px] text-df-text-primary line-clamp-1 bg-df-base border border-df-control-border rounded px-2 py-1 mt-1" },
+                displayName && (React.createElement("div", { className: "flex items-center gap-1.5 mb-1.5" },
+                    React.createElement("span", { className: "text-sm flex-shrink-0" }, avatar),
+                    React.createElement("span", { className: "text-[10px] text-df-conditional-selected font-medium" }, displayName))),
+                React.createElement("div", { className: "text-xs text-df-text-primary line-clamp-2 bg-df-elevated border border-df-control-border rounded px-3 py-1.5" },
                     "\"",
-                    block.content.slice(0, 40) + (block.content.length > 40 ? '...' : ''),
+                    block.content.slice(0, 60) + (block.content.length > 60 ? '...' : ''),
                     "\""),
                 React.createElement(Handle, { type: "source", position: Position.Right, id: `block-${idx}`, style: {
                         top: `${handlePositions[idx] || 0}px`,
                         right: -8,
-                    }, className: "!bg-[#2a2a3e] !border-[#4a4a6a] !w-3 !h-3 !rounded-full hover:!border-blue-400 hover:!bg-blue-400/20" })));
+                    }, className: "!bg-df-control-bg !border-df-control-border !w-3 !h-3 !rounded-full hover:!border-df-conditional-selected hover:!bg-df-conditional-selected/20" })));
         })),
-        node.setFlags && node.setFlags.length > 0 && (React.createElement("div", { className: "px-3 py-1 border-t border-[#2a2a3e] flex flex-wrap gap-1" }, node.setFlags.map(flagId => {
+        node.setFlags && node.setFlags.length > 0 && (React.createElement("div", { className: "px-4 py-2 border-t border-df-control-border flex flex-wrap gap-1" }, node.setFlags.map(flagId => {
             const flag = flagSchema?.flags.find(f => f.id === flagId);
             const flagType = flag?.type || 'dialogue';
-            const colorClass = flagType === 'dialogue' ? 'bg-gray-500/20 text-gray-400 border-gray-500/30' :
-                flagType === 'quest' ? 'bg-blue-500/20 text-blue-400 border-blue-500/30' :
-                    flagType === 'achievement' ? 'bg-yellow-500/20 text-yellow-400 border-yellow-500/30' :
-                        flagType === 'item' ? 'bg-green-500/20 text-green-400 border-green-500/30' :
-                            flagType === 'stat' ? 'bg-purple-500/20 text-purple-400 border-purple-500/30' :
-                                flagType === 'title' ? 'bg-pink-500/20 text-pink-400 border-pink-500/30' :
-                                    flagType === 'global' ? 'bg-orange-500/20 text-orange-400 border-orange-500/30' :
-                                        'bg-gray-500/20 text-gray-400 border-gray-500/30';
-            return (React.createElement("span", { key: flagId, className: `text-[8px] px-1 py-0.5 rounded border ${colorClass}`, title: flag?.name || flagId }, flagType === 'dialogue' ? 't' : flagType[0]));
+            const colorClass = flagType === 'dialogue' ? 'bg-df-flag-dialogue-bg text-df-flag-dialogue border-df-flag-dialogue' :
+                flagType === 'quest' ? 'bg-df-flag-quest-bg text-df-flag-quest border-df-flag-quest' :
+                    flagType === 'achievement' ? 'bg-df-flag-achievement-bg text-df-flag-achievement border-df-flag-achievement' :
+                        flagType === 'item' ? 'bg-df-flag-item-bg text-df-flag-item border-df-flag-item' :
+                            flagType === 'stat' ? 'bg-df-flag-stat-bg text-df-flag-stat border-df-flag-stat' :
+                                flagType === 'title' ? 'bg-df-flag-title-bg text-df-flag-title border-df-flag-title' :
+                                    flagType === 'global' ? 'bg-df-flag-global-bg text-df-flag-global border-df-flag-global' :
+                                        'bg-df-flag-dialogue-bg text-df-flag-dialogue border-df-flag-dialogue';
+            return (React.createElement("span", { key: flagId, className: `text-[8px] px-1.5 py-0.5 rounded-full border ${colorClass}`, title: flag?.name || flagId }, flagType === 'dialogue' ? 't' : flagType[0]));
         })))));
 }

package/dist/esm/components/DialogueEditorV2.d.ts

@@ -8,9 +8,11 @@ import React from 'react';
 import 'reactflow/dist/style.css';
 import { DialogueEditorProps } from '../types';
 import { FlagSchema } from '../types/flags';
+import { Character } from '../types/characters';
 type ViewMode = 'graph' | 'yarn' | 'play';
 export declare function DialogueEditorV2(props: DialogueEditorProps & {
     flagSchema?: FlagSchema;
+    characters?: Record<string, Character>;
     initialViewMode?: ViewMode;
     viewMode?: ViewMode;
     onViewModeChange?: (mode: ViewMode) => void;

package/dist/esm/components/DialogueEditorV2.js

@@ -32,7 +32,7 @@ const edgeTypes = {
     choice: ChoiceEdgeV2,
     default: NPCEdgeV2, // Use custom component for NPC edges instead of React Flow default
 };
-function DialogueEditorV2Internal({ dialogue, onChange, onExportYarn, onExportJSON, className = '', showTitleEditor = true, flagSchema, initialViewMode = 'graph', viewMode: controlledViewMode, onViewModeChange, layoutStrategy: propLayoutStrategy = 'dagre', // Accept from parent
+function DialogueEditorV2Internal({ dialogue, onChange, onExportYarn, onExportJSON, className = '', showTitleEditor = true, flagSchema, characters = {}, initialViewMode = 'graph', viewMode: controlledViewMode, onViewModeChange, layoutStrategy: propLayoutStrategy = 'dagre', // Accept from parent
 onLayoutStrategyChange, onOpenFlagManager, onOpenGuide, onLoadExampleDialogue, onLoadExampleFlags, 
 // Event hooks
 onNodeAdd, onNodeDelete, onNodeUpdate, onConnect: onConnectHook, onDisconnect, onNodeSelect, onNodeDoubleClick: onNodeDoubleClickHook, }) {
@@ -48,6 +48,8 @@ onNodeAdd, onNodeDelete, onNodeUpdate, onConnect: onConnectHook, onDisconnect, o
     const [layoutDirection, setLayoutDirection] = useState('TB');
     const layoutStrategy = propLayoutStrategy; // Use prop instead of state
     const [autoOrganize, setAutoOrganize] = useState(false); // Auto-layout on changes
+    // Track if we've made a direct React Flow update to avoid unnecessary conversions
+    const directUpdateRef = useRef(null);
     const [showPathHighlight, setShowPathHighlight] = useState(true); // Toggle path highlighting
     const [showBackEdges, setShowBackEdges] = useState(true); // Toggle back-edge styling
     const [showLayoutMenu, setShowLayoutMenu] = useState(false);
@@ -138,13 +140,20 @@ onNodeAdd, onNodeDelete, onNodeUpdate, onConnect: onConnectHook, onDisconnect, o
         return { edgesToSelectedNode: edgesOnPath, nodeDepths: nodeDepthMap };
     }, [selectedNodeId, dialogue]);
     // Update nodes/edges when dialogue changes externally
+    // Skip conversion if we just made a direct React Flow update (for simple text changes)
     React.useEffect(() => {
         if (dialogue) {
+            // If we just updated a node directly in React Flow, skip full conversion
+            // The direct update already handled the visual change
+            if (directUpdateRef.current) {
+                directUpdateRef.current = null; // Clear the flag
+                return; // Skip conversion - React Flow is already updated
+            }
             const { nodes: newNodes, edges: newEdges } = convertDialogueTreeToReactFlow(dialogue, layoutDirection);
             setNodes(newNodes);
             setEdges(newEdges);
         }
-    }, [dialogue]);
+    }, [dialogue, layoutDirection]);
     // Calculate end nodes (nodes with no outgoing connections)
     const endNodeIds = useMemo(() => {
         if (!dialogue)
@@ -160,7 +169,7 @@ onNodeAdd, onNodeDelete, onNodeUpdate, onConnect: onConnectHook, onDisconnect, o
         });
         return ends;
     }, [dialogue]);
-    // Add flagSchema, dim state, and layout direction to node data
+    // Add flagSchema, characters, dim state, and layout direction to node data
     const nodesWithFlags = useMemo(() => {
         const hasSelection = selectedNodeId !== null && showPathHighlight;
         const startNodeId = dialogue?.startNodeId;
@@ -176,6 +185,7 @@ onNodeAdd, onNodeDelete, onNodeUpdate, onConnect: onConnectHook, onDisconnect, o
                 data: {
                     ...node.data,
                     flagSchema,
+                    characters, // Pass characters to all nodes including conditional
                     isDimmed,
                     isInPath,
                     layoutDirection,
@@ -184,7 +194,7 @@ onNodeAdd, onNodeDelete, onNodeUpdate, onConnect: onConnectHook, onDisconnect, o
                 },
             };
         });
-    }, [nodes, flagSchema, nodeDepths, selectedNodeId, layoutDirection, showPathHighlight, dialogue, endNodeIds]);
+    }, [nodes, flagSchema, characters, nodeDepths, selectedNodeId, layoutDirection, showPathHighlight, dialogue, endNodeIds]);
     if (!dialogue) {
         return (React.createElement("div", { className: `dialogue-editor-v2-empty ${className}` },
             React.createElement("p", null, "No dialogue loaded. Please provide a dialogue tree.")));
@@ -746,6 +756,33 @@ onNodeAdd, onNodeDelete, onNodeUpdate, onConnect: onConnectHook, onDisconnect, o
     // Handle node updates
     const handleUpdateNode = useCallback((nodeId, updates) => {
         const updatedNode = { ...dialogue.nodes[nodeId], ...updates };
+        // Check if this is a "simple" update (just text/content changes, not structural)
+        // Simple updates: speaker, content, characterId (non-structural properties)
+        // Structural updates: choices, conditionalBlocks, nextNodeId (affect edges/connections)
+        const isSimpleUpdate = Object.keys(updates).every(key => ['speaker', 'content', 'characterId', 'setFlags'].includes(key));
+        if (isSimpleUpdate && reactFlowInstance) {
+            // For simple updates, update React Flow directly without full tree conversion
+            // This is much faster and avoids expensive recalculations
+            const allNodes = reactFlowInstance.getNodes();
+            const nodeToUpdate = allNodes.find(n => n.id === nodeId);
+            if (nodeToUpdate) {
+                // Mark that we're doing a direct update to skip full conversion
+                directUpdateRef.current = nodeId;
+                // Update the node data directly in React Flow
+                const updatedReactFlowNode = {
+                    ...nodeToUpdate,
+                    data: {
+                        ...nodeToUpdate.data,
+                        node: updatedNode, // Update the dialogue node in the data
+                    },
+                };
+                // Update just this node in React Flow
+                const updatedNodes = allNodes.map(n => n.id === nodeId ? updatedReactFlowNode : n);
+                reactFlowInstance.setNodes(updatedNodes);
+            }
+        }
+        // Always update the dialogue tree (source of truth) - but this triggers full conversion
+        // The useEffect will handle the full conversion, but React Flow is already updated above
         onChange({
             ...dialogue,
             nodes: {
@@ -755,7 +792,7 @@ onNodeAdd, onNodeDelete, onNodeUpdate, onConnect: onConnectHook, onDisconnect, o
         });
         // Call onNodeUpdate hook
         onNodeUpdate?.(nodeId, updates);
-    }, [dialogue, onChange, onNodeUpdate]);
+    }, [dialogue, onChange, onNodeUpdate, reactFlowInstance]);
     // Handle choice updates
     const handleAddChoice = useCallback((nodeId) => {
         const updated = addChoiceToNode(dialogue.nodes[nodeId]);
@@ -1075,7 +1112,7 @@ onNodeAdd, onNodeDelete, onNodeUpdate, onConnect: onConnectHook, onDisconnect, o
                                         " Delete"))));
                             })(),
                             React.createElement("button", { onClick: () => setNodeContextMenu(null), className: "w-full px-4 py-1.5 text-xs text-df-text-secondary hover:text-df-text-primary border-t border-df-control-border mt-1" }, "Cancel")))))),
-            selectedNode && (React.createElement(NodeEditor, { node: selectedNode, dialogue: dialogue, onUpdate: (updates) => handleUpdateNode(selectedNode.id, updates), onFocusNode: (nodeId) => {
+            selectedNode && (React.createElement(NodeEditor, { node: selectedNode, dialogue: dialogue, characters: characters, onUpdate: (updates) => handleUpdateNode(selectedNode.id, updates), onFocusNode: (nodeId) => {
                     const targetNode = nodes.find(n => n.id === nodeId);
                     if (targetNode && reactFlowInstance) {
                         // Set selectedNodeId first so NodeEditor updates

package/dist/esm/components/GuidePanel.js

@@ -363,9 +363,9 @@ const [gameState, setGameState] = useState<GameState>({
   }}
   flagSchema={flagSchema}
   // Event hooks
-  onNodeAdd={(node) => console.log('Node added:', node.id)}
-  onNodeDelete={(nodeId) => console.log('Node deleted:', nodeId)}
-  onConnect={(source, target) => console.log('Connected:', source, '->', target)}
+  onNodeAdd={(node) => {/* Example: handle node add */}}
+  onNodeDelete={(nodeId) => {/* Example: handle node delete */}}
+  onConnect={(source, target) => {/* Example: handle connect */}}
 />`, language: "typescript" }),
                 React.createElement("h3", { className: "text-lg font-semibold mt-6 mb-2 text-white" }, "6. Define Game State"),
                 React.createElement("p", { className: "text-gray-400 text-sm mb-2" }, "Game state can be any JSON object. Flags should represent the dialogue-relevant portion of your game state."),
@@ -429,21 +429,21 @@ const gameState: GameState = {
   }}
   // Event hooks
   onNodeEnter={(nodeId, node) => {
-    console.log('Entered node:', nodeId, node);
+    // Example: handle node enter
     // Trigger animations, sound effects, etc.
   }}
   onNodeExit={(nodeId, node) => {
-    console.log('Exited node:', nodeId, node);
+    // Example: handle node exit
   }}
   onChoiceSelect={(nodeId, choice) => {
-    console.log('Selected choice:', choice.text);
+    // Example: handle choice select
     // Track player decisions
   }}
   onDialogueStart={() => {
-    console.log('Dialogue started');
+    // Example: handle dialogue start
   }}
   onDialogueEnd={() => {
-    console.log('Dialogue ended');
+    // Example: handle dialogue end
   }}
 />`, language: "typescript" }),
                 React.createElement("h3", { className: "text-lg font-semibold mt-6 mb-2 text-white" }, "Complete Example"),
@@ -502,23 +502,23 @@ const dialogue = importFromYarn(yarnFile, 'Merchant');
   flagSchema={flagSchema}
   // Event hooks
   onNodeAdd={(node) => {
-    console.log('Node added:', node.id);
+    // Example: handle node add
     // Track node creation
   }}
   onNodeDelete={(nodeId) => {
-    console.log('Node deleted:', nodeId);
+    // Example: handle node delete
   }}
   onNodeUpdate={(nodeId, updates) => {
-    console.log('Node updated:', nodeId, updates);
+    // Example: handle node update
   }}
   onConnect={(sourceId, targetId, sourceHandle) => {
-    console.log('Connected:', sourceId, '->', targetId);
+    // Example: handle connect
   }}
   onDisconnect={(edgeId, sourceId, targetId) => {
-    console.log('Disconnected:', sourceId, '->', targetId);
+    // Example: handle disconnect
   }}
   onNodeSelect={(nodeId) => {
-    console.log('Node selected:', nodeId);
+    // Example: handle node select
   }}
 />
 
@@ -534,11 +534,11 @@ const dialogue = importFromYarn(yarnFile, 'Merchant');
     }));
   }}
   onNodeEnter={(nodeId, node) => {
-    console.log('Entered node:', nodeId);
+    // Example: handle node enter
     // Play animations, sound effects
   }}
   onChoiceSelect={(nodeId, choice) => {
-    console.log('Selected:', choice.text);
+    // Example: handle choice select
     // Track player decisions
   }}
 />`, language: "typescript" }),
@@ -1008,6 +1008,89 @@ await saveFile('dialogue.yarn', newYarn);`))))
                                 React.createElement("strong", { className: "text-white text-xs" }, "Square Selection"),
                                 React.createElement("p", { className: "text-gray-400 text-xs mt-1" }, "Selection box doesn't always capture all nodes within the selection area (deprioritized)")))))))
         },
+        characters: {
+            title: 'Characters',
+            content: (React.createElement("div", { className: "space-y-4 text-sm" },
+                React.createElement("p", { className: "text-gray-300" }, "Dialogue Forge supports character assignment for NPC and Player nodes. Characters are defined in your game state and can be selected from a searchable dropdown."),
+                React.createElement("h3", { className: "text-lg font-semibold mt-6 mb-2 text-white" }, "Character System"),
+                React.createElement("p", { className: "text-gray-300 mb-3" }, "Each node (NPC or Player) can be assigned a character from your game state. When a character is assigned:"),
+                React.createElement("ul", { className: "list-disc list-inside space-y-1 text-sm ml-2 text-gray-300" },
+                    React.createElement("li", null, "The character's avatar and name are displayed on the node in the graph"),
+                    React.createElement("li", null, "The character name is used as the speaker name"),
+                    React.createElement("li", null, "You can still override with a custom speaker name if needed")),
+                React.createElement("h3", { className: "text-lg font-semibold mt-6 mb-2 text-white" }, "Game State Structure"),
+                React.createElement("p", { className: "text-gray-300 mb-3" },
+                    "Characters should be defined in your game state under the ",
+                    React.createElement("code", { className: "bg-[#0d0d14] px-1 rounded" }, "characters"),
+                    " property:"),
+                React.createElement(CodeBlock, { code: `interface GameState {
+  flags?: FlagState;
+  characters?: {
+    [characterId: string]: Character;
+  };
+}
+
+interface Character {
+  id: string;
+  name: string;
+  avatar?: string; // URL or emoji (e.g., "👤", "🧙", "/avatars/wizard.png")
+  description?: string;
+}`, language: "typescript" }),
+                React.createElement("h3", { className: "text-lg font-semibold mt-6 mb-2 text-white" }, "Using Characters"),
+                React.createElement("ol", { className: "list-decimal list-inside space-y-2 text-sm ml-2 text-gray-300" },
+                    React.createElement("li", null,
+                        React.createElement("strong", null, "Define characters"),
+                        " in your game state with ",
+                        React.createElement("code", { className: "bg-[#0d0d14] px-1 rounded" }, "id"),
+                        ", ",
+                        React.createElement("code", { className: "bg-[#0d0d14] px-1 rounded" }, "name"),
+                        ", and optionally ",
+                        React.createElement("code", { className: "bg-[#0d0d14] px-1 rounded" }, "avatar")),
+                    React.createElement("li", null,
+                        React.createElement("strong", null, "Pass characters"),
+                        " to ",
+                        React.createElement("code", { className: "bg-[#0d0d14] px-1 rounded" }, "DialogueEditorV2"),
+                        " via the ",
+                        React.createElement("code", { className: "bg-[#0d0d14] px-1 rounded" }, "characters"),
+                        " prop"),
+                    React.createElement("li", null,
+                        React.createElement("strong", null, "Select a character"),
+                        " in the Node Editor using the character dropdown (searchable combobox)"),
+                    React.createElement("li", null,
+                        React.createElement("strong", null, "View on graph"),
+                        " - The character's avatar and name appear on the node")),
+                React.createElement("h3", { className: "text-lg font-semibold mt-6 mb-2 text-white" }, "Example"),
+                React.createElement(CodeBlock, { code: `// Game state with characters
+const gameState = {
+  flags: { reputation: 50 },
+  characters: {
+    stranger: {
+      id: 'stranger',
+      name: 'Mysterious Stranger',
+      avatar: '👤',
+      description: 'A cloaked figure'
+    },
+    player: {
+      id: 'player',
+      name: 'Player',
+      avatar: '🎮',
+      description: 'The player character'
+    }
+  }
+};
+
+// Pass to DialogueEditorV2
+<DialogueEditorV2
+  dialogue={dialogueTree}
+  characters={gameState.characters}
+  flagSchema={flagSchema}
+  onChange={setDialogueTree}
+/>`, language: "typescript" }),
+                React.createElement("div", { className: "bg-[#1a2a3e] border-l-4 border-blue-500 p-4 rounded mt-4" },
+                    React.createElement("p", { className: "text-gray-300 text-xs" },
+                        React.createElement("strong", null, "Note:"),
+                        " If a character is not assigned, you can still use a custom speaker name. The character system is optional but recommended for consistency across your dialogue system."))))
+        },
         theming: {
             title: 'Theming',
             content: (React.createElement("div", { className: "space-y-4 text-sm" },

package/dist/esm/components/NPCNodeV2.d.ts

@@ -11,11 +11,13 @@
 import React from 'react';
 import { NodeProps } from 'reactflow';
 import { DialogueNode } from '../types';
+import { Character } from '../types/characters';
 import { FlagSchema } from '../types/flags';
 import { LayoutDirection } from '../utils/layout';
 interface NPCNodeData {
     node: DialogueNode;
     flagSchema?: FlagSchema;
+    characters?: Record<string, Character>;
     isDimmed?: boolean;
     isInPath?: boolean;
     layoutDirection?: LayoutDirection;