1  /**
  2   * Tutorial Types - Declarative step definitions for MVP onboarding
  3   *
  4   * Design principles:
  5   * - Steps as data, not code (easy to reorder/modify)
  6   * - Each step can have text, golden dot, and actions
  7   * - Segments group related steps for modularity
  8   */
  9  
 10  /**
 11   * A single tutorial step
 12   */
 13  export interface TutorialStep {
 14    /** Unique identifier for this step */
 15    id: string;
 16  
 17    /** Segment this step belongs to */
 18    segment: TutorialSegment;
 19  
 20    /** Text to display via ManimText */
 21    text?: {
 22      content: string;
 23      /** Position in 3D space [x, y, z] */
 24      position: [number, number, number];
 25      /** Font size (default 48) */
 26      fontSize?: number;
 27      /** Duration to show text in ms (before auto-advance) */
 28      duration?: number;
 29    };
 30  
 31    /** Golden dot animation - position-based */
 32    goldenDot?: {
 33      from: [number, number, number];
 34      to: [number, number, number];
 35      /** Optional Bezier control points */
 36      controlPoints?: [number, number, number][];
 37      duration?: number;
 38      easing?: 'linear' | 'easeInOut' | 'easeIn' | 'easeOut';
 39      /** Node IDs to track for hit detection (triggers hover state automatically) */
 40      hitDetectionNodeIds?: string[];
 41    };
 42  
 43    /** Golden dot animation - node-based (resolves positions from store) */
 44    goldenDotNodes?: {
 45      fromNodeId: string;
 46      toNodeId: string;
 47      /** Optional Bezier control points */
 48      controlPoints?: [number, number, number][];
 49      duration?: number;
 50      easing?: 'linear' | 'easeInOut' | 'easeIn' | 'easeOut';
 51      /** Node IDs to track for hit detection (triggers hover state automatically) */
 52      hitDetectionNodeIds?: string[];
 53    };
 54  
 55    /** Node to highlight with golden glow */
 56    highlightNode?: {
 57      /** Node ID to highlight (e.g., 'InterBrain', 'Alice') */
 58      nodeId: string;
 59      /** Duration of highlight in ms */
 60      duration?: number;
 61    };
 62  
 63    /** Action to perform when step starts */
 64    onEnter?: TutorialAction;
 65  
 66    /** Action to perform when step ends */
 67    onExit?: TutorialAction;
 68  
 69    /** How to advance to next step */
 70    advance: {
 71      /** 'auto' = after duration, 'click' = user clicks, 'action' = after action completes */
 72      type: 'auto' | 'click' | 'action';
 73      /** For 'auto': delay in ms after animations complete */
 74      delay?: number;
 75    };
 76  }
 77  
 78  /**
 79   * Tutorial segments - logical groupings of steps
 80   */
 81  export type TutorialSegment =
 82    | 'anchor-point'      // InterBrain introduction
 83    | 'dreamer-nodes'     // Red nodes = people
 84    | 'dreamtalk'         // Symbol/thumbnail side
 85    | 'navigate'          // Click through liminal web
 86    | 'dreamsong'         // Canvas side
 87    | 'edit-canvas'       // Edit mode
 88    | 'relationships'     // Add connections
 89    | 'create-node'       // Drag-drop creation
 90    | 'weaving'           // DreamSong references
 91    | 'copilot'           // Video call intro
 92    | 'invitation';       // Closing message
 93  
 94  /**
 95   * Actions the tutorial can trigger
 96   */
 97  export type TutorialAction =
 98    | { type: 'select-node'; nodeId: string }
 99    | { type: 'focus-node'; nodeId: string }
100    | { type: 'flip-node'; nodeId: string; direction: 'front' | 'back' }
101    | { type: 'set-layout'; layout: 'constellation' | 'liminal-web' }
102    | { type: 'execute-command'; commandId: string }
103    | { type: 'highlight-glow'; nodeId: string; duration: number }
104    | { type: 'wait'; duration: number };
105  
106  /**
107   * Tutorial state for the store
108   */
109  export interface TutorialState {
110    /** Whether tutorial is currently active */
111    isActive: boolean;
112  
113    /** Current step index (-1 if inactive) */
114    currentStepIndex: number;
115  
116    /** Whether tutorial has been completed before */
117    hasCompleted: boolean;
118  
119    /** Current phase: 'download' (Phase 1) or 'personalize' (Phase 2) */
120    phase: 'download' | 'personalize' | null;
121  
122    /** IDs of demo vault nodes (symlinked, removed after tutorial) */
123    demoNodeIds: string[];
124  
125    /** Node currently highlighted with golden glow */
126    highlightedNodeId: string | null;
127  
128    /** Whether the portal overlay is showing (pre-tutorial entry screen) */
129    showPortal: boolean;
130  }
131  
132  /**
133   * Demo vault configuration
134   */
135  export interface DemoVaultConfig {
136    /** Path to bundled demo nodes within plugin */
137    bundlePath: string;
138  
139    /** Node definitions */
140    nodes: DemoNodeConfig[];
141  }
142  
143  export interface DemoNodeConfig {
144    /** Node ID (folder name) */
145    id: string;
146  
147    /** Display name */
148    name: string;
149  
150    /** Node type */
151    type: 'dream' | 'dreamer';
152  
153    /** IDs of connected nodes */
154    connections: string[];
155  
156    /** Whether node has pre-woven DreamSong content */
157    hasDreamSong: boolean;
158  }