@magicborn/dialogue-forge 0.1.0

package/dist/esm/examples/yarn-examples.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Inline Yarn file contents for examples
+ * This allows examples to be bundled and loaded synchronously
+ *
+ * To add a new example:
+ * 1. Create a .yarn file in the examples directory
+ * 2. Copy its content here as a string literal
+ * 3. Add it to the yarnExamplesContent object
+ */
+import { DialogueTree } from '../types';
+/**
+ * Load all examples synchronously
+ * This should be called once at initialization
+ */
+export declare function loadAllExamples(): Record<string, DialogueTree>;
+/**
+ * Get a loaded example dialogue
+ */
+export declare function getExampleDialogue(exampleId: string): DialogueTree | null;
+/**
+ * Get all loaded examples
+ */
+export declare function getAllExampleDialogues(): Record<string, DialogueTree>;
+/**
+ * Get flag schema for an example
+ */
+export declare function getExampleFlagSchema(exampleId: string): import("..").FlagSchema | null;
+/**
+ * Check if an example has Yarn content available
+ */
+export declare function hasExampleContent(exampleId: string): boolean;
+/**
+ * Get list of example IDs that have content available
+ */
+export declare function getAvailableExampleIds(): string[];

package/dist/esm/examples/yarn-examples.js

@@ -0,0 +1,181 @@
+/**
+ * Inline Yarn file contents for examples
+ * This allows examples to be bundled and loaded synchronously
+ *
+ * To add a new example:
+ * 1. Create a .yarn file in the examples directory
+ * 2. Copy its content here as a string literal
+ * 3. Add it to the yarnExamplesContent object
+ */
+import { importFromYarn } from '../lib/yarn-converter';
+import { examplesRegistry, exampleFlagSchemas } from './examples-registry';
+/**
+ * Map of example ID to Yarn file content
+ * All examples are stored as Yarn strings here for easy discovery and maintenance
+ */
+const yarnExamplesContent = {
+    'variable-operations': `title: merchant_shop
+---
+Merchant: Welcome to my shop, {$player_name}!
+Merchant: You currently have {$stat_gold} gold pieces.
+<<if $stat_gold >= 100>>
+    Merchant: You can afford the sword! It costs 100 gold.
+    -> Buy the sword
+        <<set $item_sword = true>>
+        <<set $stat_gold -= 100>>
+        Merchant: Thank you for your purchase! You now have {$stat_gold} gold.
+        <<jump after_purchase>>
+    -> Maybe later
+        Merchant: Come back anytime!
+        <<jump end>>
+<<elseif $stat_gold >= 50>>
+    Merchant: You can afford the potion! It costs 50 gold.
+    -> Buy the potion
+        <<set $item_potion = true>>
+        <<set $stat_gold -= 50>>
+        Merchant: Thank you! You now have {$stat_gold} gold.
+        <<jump after_purchase>>
+    -> Save up for the sword
+        Merchant: Wise choice! Come back when you have more gold.
+        <<jump end>>
+<<else>>
+    Merchant: I'm sorry, but you don't have enough gold for anything.
+    Merchant: Come back when you have at least 50 gold pieces.
+    <<jump end>>
+<<endif>>
+===
+
+title: after_purchase
+---
+Merchant: Is there anything else you'd like?
+<<set $stat_reputation += 5>>
+Merchant: Your reputation with me has increased! It's now {$stat_reputation}.
+-> Browse more
+    <<jump merchant_shop>>
+-> Leave
+    Merchant: Thanks for shopping!
+    <<jump end>>
+===
+
+title: quest_reward
+---
+QuestGiver: You've completed the quest! Here's your reward.
+<<set $stat_gold += 500>>
+<<set $stat_experience += 100>>
+<<set $quest_dragon_slayer = "complete">>
+QuestGiver: You received 500 gold and 100 experience!
+QuestGiver: You now have {$stat_gold} gold and {$stat_experience} experience points.
+<<jump end>>
+===
+
+title: stat_multiplier
+---
+Trainer: I can double your strength for a price.
+<<if $stat_gold >= 200>>
+    Trainer: For 200 gold, I'll double your strength stat.
+    -> Pay for training
+        <<set $stat_strength *= 2>>
+        <<set $stat_gold -= 200>>
+        Trainer: Your strength is now {$stat_strength}!
+        <<jump end>>
+    -> Not right now
+        Trainer: Come back when you're ready.
+        <<jump end>>
+<<else>>
+    Trainer: You need 200 gold for this training.
+    <<jump end>>
+<<endif>>
+===
+
+title: string_variables
+---
+NPC: Hello, {$player_name}! Welcome to {$location_name}.
+NPC: Your title is {$player_title}.
+<<set $greeting_count += 1>>
+NPC: I've greeted you {$greeting_count} times now.
+<<if $greeting_count >= 5>>
+    NPC: You're a regular here! Let me give you a discount.
+    <<set $stat_reputation += 10>>
+<<endif>>
+<<jump end>>
+===
+
+title: end
+---
+===
+`,
+    // Add more examples here as they're converted to Yarn format
+};
+/**
+ * Pre-loaded examples cache
+ */
+let examplesCache = {};
+/**
+ * Load all examples synchronously
+ * This should be called once at initialization
+ */
+export function loadAllExamples() {
+    if (Object.keys(examplesCache).length > 0) {
+        return examplesCache;
+    }
+    const loaded = {};
+    for (const metadata of examplesRegistry) {
+        const yarnContent = yarnExamplesContent[metadata.id];
+        if (yarnContent) {
+            try {
+                const dialogue = importFromYarn(yarnContent, metadata.title);
+                loaded[metadata.id] = dialogue;
+                metadata.nodeCount = Object.keys(dialogue.nodes).length;
+            }
+            catch (error) {
+                console.error(`Error loading example ${metadata.id}:`, error);
+            }
+        }
+    }
+    examplesCache = loaded;
+    return loaded;
+}
+// Pre-load examples when module is imported
+loadAllExamples();
+/**
+ * Get a loaded example dialogue
+ */
+export function getExampleDialogue(exampleId) {
+    if (Object.keys(examplesCache).length === 0) {
+        loadAllExamples();
+    }
+    return examplesCache[exampleId] || null;
+}
+/**
+ * Get all loaded examples
+ */
+export function getAllExampleDialogues() {
+    if (Object.keys(examplesCache).length === 0) {
+        loadAllExamples();
+    }
+    return examplesCache;
+}
+/**
+ * Get flag schema for an example
+ */
+export function getExampleFlagSchema(exampleId) {
+    const metadata = examplesRegistry.find(ex => ex.id === exampleId);
+    if (!metadata) {
+        return null;
+    }
+    return exampleFlagSchemas[metadata.flagSchemaId] || null;
+}
+/**
+ * Check if an example has Yarn content available
+ */
+export function hasExampleContent(exampleId) {
+    return exampleId in yarnExamplesContent;
+}
+/**
+ * Get list of example IDs that have content available
+ */
+export function getAvailableExampleIds() {
+    return examplesRegistry
+        .filter(metadata => hasExampleContent(metadata.id))
+        .map(metadata => metadata.id);
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,21 @@
+export { DialogueEditorV2 } from './components/DialogueEditorV2';
+export { ScenePlayer } from './components/ScenePlayer';
+export type { ScenePlayerProps } from './components/ScenePlayer';
+export { ScenePlayer as DialogueSimulator } from './components/ScenePlayer';
+export { GuidePanel } from './components/GuidePanel';
+export { FlagSelector } from './components/FlagSelector';
+export { FlagManager } from './components/FlagManager';
+export { ZoomControls } from './components/ZoomControls';
+export { ExampleLoader } from './components/ExampleLoader';
+import './styles/scrollbar.css';
+import './styles/theme.css';
+export { exampleDialogues, demoFlagSchemas, getExampleDialogue, getDemoFlagSchema, listExamples, listDemoFlagSchemas } from './examples';
+export * from './types';
+export * from './types/flags';
+export * from './types/game-state';
+export * from './types/constants';
+export { flattenGameState, validateGameState, extractFlagsFromGameState, type FlattenConfig, type FlattenedState } from './utils/game-state-flattener';
+export { exportToYarn, importFromYarn } from './lib/yarn-converter';
+export { initializeFlags, mergeFlagUpdates, validateFlags, getFlagValue } from './lib/flag-manager';
+export * from './utils/node-helpers';
+export * from './utils/feature-flags';

package/dist/esm/index.js

@@ -0,0 +1,26 @@
+export { DialogueEditorV2 } from './components/DialogueEditorV2';
+export { ScenePlayer } from './components/ScenePlayer';
+// Legacy export for backward compatibility
+export { ScenePlayer as DialogueSimulator } from './components/ScenePlayer';
+export { GuidePanel } from './components/GuidePanel';
+export { FlagSelector } from './components/FlagSelector';
+export { FlagManager } from './components/FlagManager';
+export { ZoomControls } from './components/ZoomControls';
+export { ExampleLoader } from './components/ExampleLoader';
+// Export styles
+import './styles/scrollbar.css';
+import './styles/theme.css';
+// Export examples
+export { exampleDialogues, demoFlagSchemas, getExampleDialogue, getDemoFlagSchema, listExamples, listDemoFlagSchemas } from './examples';
+// Export all types
+export * from './types';
+export * from './types/flags';
+export * from './types/game-state';
+export * from './types/constants';
+// Export game state utilities
+export { flattenGameState, validateGameState, extractFlagsFromGameState } from './utils/game-state-flattener';
+// Export utilities
+export { exportToYarn, importFromYarn } from './lib/yarn-converter';
+export { initializeFlags, mergeFlagUpdates, validateFlags, getFlagValue } from './lib/flag-manager';
+export * from './utils/node-helpers';
+export * from './utils/feature-flags';

package/dist/esm/lib/flag-manager.d.ts

@@ -0,0 +1,21 @@
+import { GameFlagState } from '../types/game-state';
+import { FlagSchema } from '../types/flags';
+/**
+ * Initialize game flags from schema with default values
+ */
+export declare function initializeFlags(schema: FlagSchema): GameFlagState;
+/**
+ * Merge current flags with updates from dialogue
+ */
+export declare function mergeFlagUpdates(currentFlags: GameFlagState, updates: string[], schema?: FlagSchema): GameFlagState;
+/**
+ * Validate flags against schema
+ */
+export declare function validateFlags(flags: GameFlagState, schema: FlagSchema): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Get flag value with type safety
+ */
+export declare function getFlagValue(flags: GameFlagState, flagId: string, defaultValue?: boolean | number | string): boolean | number | string;

package/dist/esm/lib/flag-manager.js

@@ -0,0 +1,93 @@
+import { FLAG_TYPE, FLAG_VALUE_TYPE } from '../types/constants';
+/**
+ * Initialize game flags from schema with default values
+ */
+export function initializeFlags(schema) {
+    const flags = {};
+    schema.flags.forEach(flag => {
+        if (flag.defaultValue !== undefined) {
+            flags[flag.id] = flag.defaultValue;
+        }
+        else if (flag.valueType === 'number') {
+            flags[flag.id] = 0;
+        }
+        else if (flag.valueType === 'string') {
+            flags[flag.id] = '';
+        }
+        else {
+            flags[flag.id] = false;
+        }
+    });
+    return flags;
+}
+/**
+ * Merge current flags with updates from dialogue
+ */
+export function mergeFlagUpdates(currentFlags, updates, schema) {
+    const newFlags = { ...currentFlags };
+    updates.forEach(flagId => {
+        const flagDef = schema?.flags.find(f => f.id === flagId);
+        if (flagDef) {
+            // Use default value or increment if number
+            if (flagDef.valueType === 'number' && typeof newFlags[flagId] === 'number') {
+                newFlags[flagId] = newFlags[flagId] + 1;
+            }
+            else if (flagDef.valueType === FLAG_VALUE_TYPE.STRING) {
+                // For string flags, use smart defaults based on type
+                if (flagDef.type === FLAG_TYPE.QUEST) {
+                    // Quest flags: if not set, mark as "started", otherwise keep current value
+                    newFlags[flagId] = newFlags[flagId] || 'started';
+                }
+                else {
+                    // Other string flags: use default or empty string
+                    newFlags[flagId] = flagDef.defaultValue !== undefined ? flagDef.defaultValue : '';
+                }
+            }
+            else if (flagDef.defaultValue !== undefined) {
+                newFlags[flagId] = flagDef.defaultValue;
+            }
+            else {
+                newFlags[flagId] = true;
+            }
+        }
+        else {
+            // Default to true if not in schema
+            newFlags[flagId] = true;
+        }
+    });
+    return newFlags;
+}
+/**
+ * Validate flags against schema
+ */
+export function validateFlags(flags, schema) {
+    const errors = [];
+    Object.keys(flags).forEach(flagId => {
+        const flagDef = schema.flags.find(f => f.id === flagId);
+        if (!flagDef) {
+            errors.push(`Unknown flag: ${flagId}`);
+        }
+        else if (flagDef.valueType) {
+            const value = flags[flagId];
+            if (flagDef.valueType === FLAG_VALUE_TYPE.NUMBER && typeof value !== 'number') {
+                errors.push(`Flag ${flagId} should be a number, got ${typeof value}`);
+            }
+            else if (flagDef.valueType === FLAG_VALUE_TYPE.STRING && typeof value !== 'string') {
+                errors.push(`Flag ${flagId} should be a string, got ${typeof value}`);
+            }
+            else if (flagDef.valueType === FLAG_VALUE_TYPE.BOOLEAN && typeof value !== 'boolean') {
+                errors.push(`Flag ${flagId} should be a boolean, got ${typeof value}`);
+            }
+        }
+    });
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+}
+/**
+ * Get flag value with type safety
+ */
+export function getFlagValue(flags, flagId, defaultValue) {
+    return flags[flagId] ?? defaultValue ?? false;
+}

package/dist/esm/lib/yarn-converter/__tests__/round-trip.test.d.ts

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

package/dist/esm/lib/yarn-converter/__tests__/round-trip.test.js

@@ -0,0 +1,169 @@
+import { describe, it, expect } from 'vitest';
+import { importFromYarn, exportToYarn } from '../../yarn-converter';
+/**
+ * Test round-trip conversion: Yarn → DialogueTree → Yarn
+ * This ensures we can import and export without data loss
+ */
+describe('Yarn Round-Trip Conversion', () => {
+    const testCases = [
+        {
+            name: 'Basic dialogue with choices',
+            yarn: `title: start
+---
+NPC: Hello! How can I help you?
+-> Option 1
+    <<jump option1>>
+-> Option 2
+    <<jump option2>>
+===
+
+title: option1
+---
+NPC: You chose option 1!
+===
+
+title: option2
+---
+NPC: You chose option 2!
+===
+`
+        },
+        {
+            name: 'Dialogue with flags',
+            yarn: `title: start
+---
+NPC: Welcome!
+<<set $flag1 = true>>
+<<set $flag2 = true>>
+-> Continue
+    <<set $flag3 = true>>
+    <<jump next>>
+===
+
+title: next
+---
+NPC: Flags have been set!
+===
+`
+        },
+        {
+            name: 'Conditional blocks',
+            yarn: `title: start
+---
+<<if $has_key>>
+    Guard: The door is unlocked.
+<<else>>
+    Guard: The door is locked.
+<<endif>>
+===
+`
+        },
+        {
+            name: 'Variable operations',
+            yarn: `title: merchant
+---
+Merchant: You have {$stat_gold} gold.
+<<set $stat_gold += 100>>
+Merchant: Now you have {$stat_gold} gold!
+-> Buy item
+    <<set $stat_gold -= 50>>
+    <<set $item_sword = true>>
+    Merchant: You bought a sword! You have {$stat_gold} gold left.
+    <<jump end>>
+===
+
+title: end
+---
+===
+`
+        },
+        {
+            name: 'Complex conditional with multiple blocks',
+            yarn: `title: start
+---
+<<if $stat_gold >= 100>>
+    Merchant: You can afford the sword!
+<<elseif $stat_gold >= 50>>
+    Merchant: You can afford the potion!
+<<else>>
+    Merchant: You don't have enough gold.
+<<endif>>
+===
+`
+        }
+    ];
+    testCases.forEach(({ name, yarn }) => {
+        it(`should round-trip: ${name}`, () => {
+            // Import Yarn to DialogueTree
+            const dialogue = importFromYarn(yarn, 'Test Dialogue');
+            // Export DialogueTree back to Yarn
+            const exportedYarn = exportToYarn(dialogue);
+            // Import the exported Yarn again
+            const reimportedDialogue = importFromYarn(exportedYarn, 'Test Dialogue');
+            // Verify structure is preserved
+            expect(reimportedDialogue.nodes).toBeDefined();
+            expect(Object.keys(reimportedDialogue.nodes).length).toBeGreaterThan(0);
+            // Verify all nodes are present
+            const originalNodeIds = Object.keys(dialogue.nodes);
+            const reimportedNodeIds = Object.keys(reimportedDialogue.nodes);
+            expect(reimportedNodeIds.length).toBe(originalNodeIds.length);
+            // Verify node types are preserved
+            originalNodeIds.forEach(nodeId => {
+                const original = dialogue.nodes[nodeId];
+                const reimported = reimportedDialogue.nodes[nodeId];
+                expect(reimported).toBeDefined();
+                expect(reimported.type).toBe(original.type);
+            });
+        });
+    });
+    it('should preserve variable operations', () => {
+        const yarn = `title: test
+---
+NPC: Test
+<<set $stat_gold += 100>>
+<<set $stat_gold -= 50>>
+<<set $stat_strength *= 2>>
+===
+`;
+        const dialogue = importFromYarn(yarn, 'Test');
+        const exported = exportToYarn(dialogue);
+        // Verify operations are in exported Yarn
+        expect(exported).toContain('<<set $stat_gold += 100>>');
+        expect(exported).toContain('<<set $stat_gold -= 50>>');
+        expect(exported).toContain('<<set $stat_strength *= 2>>');
+    });
+    it('should preserve variable interpolation', () => {
+        const yarn = `title: test
+---
+NPC: Hello {$player_name}! You have {$stat_gold} gold.
+===
+`;
+        const dialogue = importFromYarn(yarn, 'Test');
+        const exported = exportToYarn(dialogue);
+        // Variable interpolation should be preserved in content
+        expect(dialogue.nodes.test.content).toContain('{$player_name}');
+        expect(dialogue.nodes.test.content).toContain('{$stat_gold}');
+    });
+    it('should preserve conditional choices', () => {
+        const yarn = `title: start
+---
+<<if $has_key>>
+    -> Use key
+        <<jump unlocked>>
+<<endif>>
+-> Try to force
+    <<jump forced>>
+===
+`;
+        const dialogue = importFromYarn(yarn, 'Test');
+        const exported = exportToYarn(dialogue);
+        // Verify conditional choice structure
+        const playerNode = dialogue.nodes.start;
+        expect(playerNode.type).toBe('player');
+        expect(playerNode.choices).toBeDefined();
+        expect(playerNode.choices.length).toBeGreaterThan(0);
+        // Verify conditions are exported
+        expect(exported).toContain('<<if');
+        expect(exported).toContain('<<endif>>');
+    });
+});

package/dist/esm/lib/yarn-converter.d.ts

@@ -0,0 +1,17 @@
+import { DialogueTree } from '../types';
+/**
+ * Convert DialogueTree to Yarn Spinner format
+ *
+ * Flags are converted to Yarn variables ($variable).
+ * Variables are NOT stored in the .yarn file - they're managed by
+ * Yarn Spinner's Variable Storage at runtime.
+ *
+ * The .yarn file contains commands like:
+ * - <<set $flag_name = value>> - Sets variable in Variable Storage
+ * - <<if $flag_name>> - Checks variable in Variable Storage
+ */
+export declare function exportToYarn(tree: DialogueTree): string;
+/**
+ * Parse Yarn Spinner format to DialogueTree
+ */
+export declare function importFromYarn(yarnContent: string, title?: string): DialogueTree;