constellation-analyzer/docs/UX_CONCEPT_MULTI_VERSION_GRAPH.md

Multi-Version Graph Feature - UX Concept Document

Executive Summary

This document outlines a comprehensive UX design for adding multi-version graph support to Constellation Analyzer. The feature enables users to maintain multiple versions of a constellation graph within a single document, with a branching model similar to version control systems but adapted for visual graph editing.

Design Philosophy: Balance power-user capabilities with approachable, intuitive interactions for users unfamiliar with traditional version control.

---

1. User Mental Model

Core Metaphor: "Snapshots with Branches"

Primary Terminology (domain-specific, not git-like):

• Snapshot - A saved state of the graph at a specific point in time
• Branch - A diverging path of development from a snapshot
• Timeline - The visual representation of snapshot history
• Active Snapshot - The currently displayed and editable version

Why Not Git Terminology? While the underlying model resembles git, using terms like "commit," "branch," and "merge" may intimidate users unfamiliar with version control. Our target users are analysts and researchers, not developers.

User Mental Model Narrative:

"I'm working on a constellation analysis. As I explore different scenarios, I can create snapshots of my work. Each snapshot preserves the exact state of actors and relations at that moment. Later, I can branch off from any snapshot to explore alternative arrangements without losing my original work. The timeline shows me the evolution of my analysis."

Key Mental Model Principles:

1. Non-destructive editing - Creating a new snapshot never destroys previous work
2. Exploration-friendly - Easy to try alternative configurations
3. Clear lineage - Visual representation shows how snapshots relate
4. Lightweight snapshots - Creating a snapshot is quick and low-friction
5. Safety first - Difficult to accidentally delete work

---

2. Bottom Panel Design

2.1 Layout & Positioning

Position: Bottom edge of the graph editor (below the ReactFlow canvas)

Dimensions:

• Default height: 200px
• Minimum height: 120px (collapsed state showing only controls)
• Maximum height: 50% of viewport height
• Resizable via drag handle at top edge

States:

1. Fully Visible (200px) - Timeline graph fully visible with snapshot details
2. Collapsed (120px) - Timeline visible but compressed, minimal details
3. Hidden (0px, optional) - Panel completely hidden, toggle via View menu or keyboard

Behavior:

• Panel remains visible by default when document has multiple snapshots
• For documents with single snapshot, panel auto-hides but can be shown
• Resize handle appears on hover at top edge (3px hit area, visual indicator)
• Double-click resize handle to toggle between default and collapsed heights

2.2 Visual Structure

┌─────────────────────────────────────────────────────────────────┐
│ ┌─┐ Snapshot Timeline        [Search] [?]  [Filter▾] [−] [×]   │ ← Header (32px)
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│     ◯───◯───◯───┬───◯                                         │
│     │   │   │   │   │                                         │ ← Timeline Graph
│     S1  S2  S3  │   S5 (Active)                               │   (Variable height)
│                 │                                              │
│                 └───◯                                          │
│                     S4                                          │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│ Snapshot S5: "Exploring team structure" • Modified 2 min ago   │ ← Details Footer (36px)
│ [Create Snapshot] [Branch from S3▾] [⋮ More Actions]          │
└─────────────────────────────────────────────────────────────────┘

2.3 Header Controls

Left side:

• Timeline icon + "Snapshot Timeline" title
• Subtle visual indicator of total snapshot count (e.g., "(7 snapshots)")

Right side controls:

• Search field - Filter snapshots by name/description
• Help icon (?) - Opens tooltip explaining snapshot concepts
• Filter dropdown - Show/hide specific branches, date ranges
• Collapse button (−) - Collapses panel to minimal height
• Hide button (×) - Hides panel completely

2.4 Timeline Visualization

Layout: Horizontal flow, left to right (earliest to newest)

Visual Elements:

Snapshot Node:

     ◯  ← Hollow circle (16px) for inactive snapshots
     ●  ← Filled circle (20px) for active snapshot

   Colors:
   - Default: Gray (#94a3b8)
   - Active: Blue (#3b82f6)
   - Hover: Darker shade
   - Selected: Ring around node

Connection Lines:

• Solid lines (2px) connecting parent to child
• Bezier curves for branching paths
• Color matches the branch (subtle color coding)

Labels:

• Snapshot name appears below node (truncated to 20 chars)
• Timestamp on secondary line (relative: "2h ago", "3 days ago")
• Custom label text wraps to 2 lines max

Interactive States:

1. Default - Snapshot visible, clickable
2. Hover - Node enlarges slightly (scale 1.1), shows preview tooltip
3. Active - Larger node, blue color, subtle glow effect
4. Selected - Blue ring around node, details shown in footer
5. Dimmed - Snapshots filtered out (opacity 0.3)

2.5 Snapshot Preview Tooltip (on hover)

┌────────────────────────────────┐
│ Snapshot: Feature Analysis     │
│ Created: Oct 11, 2025 2:30 PM │
│ Branch: main                   │
│ ─────────────────────────────  │
│ [Thumbnail preview]            │ ← 200x120px graph preview
│ 12 actors • 18 relations       │
│ ─────────────────────────────  │
│ Click to view                  │
│ Double-click to switch         │
└────────────────────────────────┘

Preview generation:

• Cached thumbnail of graph state (rendered on snapshot creation)
• Shows miniature view of node layout
• Updates only when snapshot is modified (if editable)

2.6 Details Footer

Displays information about selected/active snapshot:

Content:

• Snapshot name (editable inline on click)
• Description text (if set)
• Last modified timestamp
• Statistics: actor count, relation count
• Branch indicator (if multiple branches exist)

Action Buttons:

1. "Create Snapshot" - Create new snapshot from current active state
2. "Branch from..." - Dropdown to select any snapshot to branch from
3. "More Actions" (⋮) - Overflow menu for:
   • Rename snapshot
   • Edit description
   • Delete snapshot
   • Compare with another snapshot
   • Export snapshot
   • View snapshot history

2.7 Handling Large Version Graphs

Performance Optimizations (for 100+ snapshots):

1. Virtual Scrolling:

   • Render only visible snapshot nodes (viewport + buffer)
   • Smooth horizontal scrolling with momentum

2. Timeline Zoom Levels:

   • Zoomed out - Dots only, no labels (fit more on screen)
   • Default - Nodes with names, condensed timestamps
   • Zoomed in - Full details, larger nodes, preview thumbnails
   • Zoom controls: +/− buttons or Ctrl+Scroll

3. Minimap (appears when >20 snapshots):

   ┌─────────────────────────────────────┐
   │ Timeline Minimap:   [====····]      │ ← Shows full timeline
   │                      ^current view^  │
   └─────────────────────────────────────┘
   

4. Branch Folding:

   • Collapse inactive branches to single node
   • "Show 5 hidden snapshots" expandable indicator
   • Focus mode: Show only active branch + ancestors

5. Search & Filter:

   • Filter by date range slider
   • Filter by branch name
   • Search by snapshot name/description
   • Tag-based filtering (if tags implemented)

6. Lazy Loading:

   • Load snapshot metadata only
   • Graph data loaded on-demand when switching
   • Thumbnail previews loaded progressively

---

3. Version Navigation

3.1 Switching Between Snapshots

Primary Interaction: Double-click on snapshot node in timeline

Rationale:

• Single-click selects/previews (low commitment)
• Double-click activates (deliberate action)
• Familiar pattern from file explorers

Alternative Methods:

1. Select snapshot → Press Enter
2. Select snapshot → Click "Switch to This Snapshot" button
3. Keyboard shortcuts: Ctrl+[ / Ctrl+] to navigate chronologically
4. Right-click context menu → "Switch to Snapshot"

3.2 Unsaved Changes Handling

When attempting to switch with unsaved changes:

Modal Dialog:

┌──────────────────────────────────────────────┐
│  ⚠ Unsaved Changes                           │
│                                              │
│  You have unsaved changes in this snapshot.  │
│  What would you like to do?                  │
│                                              │
│  ○ Create new snapshot with changes          │
│  ○ Discard changes and switch                │
│  ○ Cancel (stay on current snapshot)         │
│                                              │
│           [Cancel]  [Proceed →]              │
└──────────────────────────────────────────────┘

Auto-snapshot Option (in Settings):

• "Automatically create snapshot when switching versions"
• Prompts for name if enabled, or uses auto-generated name
• Default: OFF (to avoid clutter)

3.3 Visual Feedback During Switch

Loading State:

1. Timeline panel: Active node animates to new position
2. Graph editor: Fade out → Brief loading indicator → Fade in new graph
3. Duration: 200-400ms for smooth transition
4. Preserve viewport position if possible (or fit view)

Confirmation:

• Toast notification: "Switched to snapshot: [Name]"
• Active snapshot highlighted in timeline
• Document title updates with snapshot indicator

3.4 Keyboard Navigation

Shortcuts:

• Ctrl+[ - Previous snapshot (chronologically)
• Ctrl+] - Next snapshot
• Ctrl+Shift+S - Create new snapshot
• Ctrl+B - Toggle timeline panel visibility
• Ctrl+/ - Focus timeline search
• Arrow keys - Navigate between snapshots in timeline (when focused)
• Enter - Switch to selected snapshot
• Escape - Deselect snapshot, return to active view

---

4. Version Creation

4.1 Creating New Snapshots

Trigger Methods:

1. Manual Creation:

   • Click "Create Snapshot" button in timeline footer
   • Menu: Edit → Create Snapshot
   • Keyboard: Ctrl+Shift+S
   • Toolbar: Snapshot icon button (camera icon)

2. Quick Snapshot Dialog:

┌──────────────────────────────────────────┐
│  Create Snapshot                         │
│                                          │
│  Name: [Exploring team dynamics______]  │
│                                          │
│  Description (optional):                 │
│  [Added marketing team actors and___]   │
│  [their relations to product team___]   │
│                                          │
│  ☐ Create as new branch                 │
│                                          │
│        [Cancel]  [Create Snapshot]       │
└──────────────────────────────────────────┘

Auto-naming:

• If name left empty, generate: "Snapshot [number]" or "Untitled [timestamp]"
• Show placeholder: "e.g., After adding finance team"
• Timestamp automatically attached to metadata

Description field:

• Optional but encouraged
• Multi-line textarea (3 rows)
• Character limit: 500 chars
• Used in search and timeline tooltips

4.2 Auto-save vs Manual Snapshots

Recommended Approach: Manual Only (initially)

Rationale:

• Users maintain control over what constitutes a meaningful version
• Prevents timeline clutter from every minor edit
• More intentional version management

Future Enhancement: Auto-snapshot options (in Settings):

• "Auto-snapshot every N minutes" (disabled by default)
• "Auto-snapshot on significant changes" (e.g., >10 actors added/removed)
• Auto-snapshots marked visually different (hollow squares instead of circles)
• Can be cleaned up via "Compress Timeline" action

4.3 Branching UX

Creating a Branch:

Scenario: User wants to explore alternative from Snapshot 3 while keeping current work

Method 1 - Context Menu:

1. Right-click snapshot in timeline
2. Select "Create Branch from Here"
3. Name branch dialog appears

Method 2 - Branch Button:

1. Select snapshot (single-click)
2. Click "Branch from..." dropdown in footer
3. Shows list of all snapshots with thumbnails
4. Select source snapshot
5. Name dialog appears

Branch Naming Dialog:

┌──────────────────────────────────────────┐
│  Create Branch from Snapshot 3           │
│                                          │
│  New snapshot will be created from:      │
│  "Initial actor layout" (Oct 11, 2:15pm) │
│                                          │
│  Branch name: [Alternative structure_]   │
│                                          │
│  Start with:                             │
│  ● Exact copy of source snapshot         │
│  ○ Empty graph (keep only types)         │
│                                          │
│        [Cancel]  [Create Branch]         │
└──────────────────────────────────────────┘

Visual Branching Indicator:

• Branch lines diverge with bezier curve from parent
• Different subtle background colors for different branches
• Branch labels in timeline (collapsible)

Branch Management:

• Branches are implicit (no explicit branch objects)
• Branches identified by diverging paths in snapshot graph
• "Main" branch is simply the linear path from first snapshot
• Can rename branches by editing the divergence point snapshot

---

5. Version Graph Editing

5.1 Deletion Operations

Delete Snapshot:

Trigger:

• Select snapshot → More Actions (⋮) → Delete Snapshot
• Right-click → Delete
• Select + Delete key

Safety Rules:

1. Cannot delete active snapshot - Must switch to another first
2. Orphan prevention - If snapshot has children, show warning
3. Confirmation required - Always prompt before deletion

Confirmation Dialog:

┌──────────────────────────────────────────┐
│  ⚠ Delete Snapshot?                      │
│                                          │
│  This will permanently delete:           │
│  "Feature Analysis v2"                   │
│                                          │
│  ⚠ Warning: This snapshot has 3 children │
│  What should happen to child snapshots?  │
│                                          │
│  ● Re-parent to previous snapshot        │
│  ○ Delete entire branch (4 snapshots)    │
│                                          │
│  ☑ Don't ask again for simple deletions  │
│                                          │
│        [Cancel]  [Delete Snapshot]       │
└──────────────────────────────────────────┘

Re-parenting:

• Children automatically connect to deleted snapshot's parent
• Visual animation shows line reconnecting
• Toast: "Snapshot deleted, 3 children re-parented"

5.2 Re-parenting Operations

Use Case: Change the parent of a snapshot (move it to different branch point)

Interaction:

1. Right-click snapshot → "Change Parent..."
2. Timeline enters "re-parent mode"
3. All valid parent snapshots highlight (must be chronologically earlier)
4. Click new parent snapshot
5. Confirmation dialog shows before/after visualization

Constraints:

• New parent must be chronologically before the snapshot being moved
• Cannot create cycles
• Moving a snapshot moves all its descendants

Visual Feedback:

• Dotted line from snapshot to cursor during selection
• Valid drop targets pulse gently
• Invalid targets dimmed with "not allowed" cursor

5.3 Merge Operations (Advanced)

Note: Merging is complex and should be a later phase feature

If implemented, merge UX:

Trigger:

1. Select two snapshots (Ctrl+Click)
2. Right-click → "Merge Snapshots..."
3. Merge wizard opens

Merge Wizard:

Step 1: Select merge strategy
  ● Manual conflict resolution
  ○ Keep all actors from both (auto-merge)
  ○ Prefer snapshot A
  ○ Prefer snapshot B

Step 2: Resolve conflicts (if manual)
  [Side-by-side diff view]
  - Actors only in A (5) → [Keep] [Discard]
  - Actors only in B (3) → [Keep] [Discard]
  - Modified actors (2) → [Use A] [Use B] [Edit]

Step 3: Name merged snapshot
  Name: [Merged: A + B_________]

Step 4: Review & Create
  [Preview merged graph]
  [Create Merged Snapshot]

Complexity Warning:

• Merging graphs is semantically ambiguous
• Better to support "Compare" feature first
• Allow manual recreation by viewing two snapshots side-by-side

5.4 Reordering & Reorganization

Timeline Reorganization:

• Drag-and-drop to reorder snapshots within a linear branch (no re-parenting)
• Useful for organizing exploration snapshots
• Does not change parent-child relationships
• Visual-only reorganization for cleaner timeline

Compact View:

• "Compress Timeline" action in More menu
• Automatically removes auto-snapshots older than X days
• Consolidates linear sequences with no branching
• Shows "Compressed 15 snapshots" indicator

---

6. Integration with Existing UI

6.1 Top-Level Current Snapshot Indicator

Location: Document tab bar OR below menu bar

Option A - In Document Tab (Recommended):

┌────────────────────────────────────────────┐
│ [Document 1 ▾] [Document 2] [+]            │
│  └─ Snapshot: Feature Analysis v2          │
└────────────────────────────────────────────┘

Option B - Breadcrumb Header:

┌────────────────────────────────────────────┐
│ Home > Team Analysis > Snapshot: v2.3      │
└────────────────────────────────────────────┘

Option C - Status Bar (below tabs, above toolbar):

┌────────────────────────────────────────────┐
│ [Document 1 ▾] [Document 2] [+]            │
├────────────────────────────────────────────┤
│ 📸 Active: Feature Analysis v2 • Oct 11... │
└────────────────────────────────────────────┘

Interaction:

• Click indicator → Opens snapshot selector dropdown
• Dropdown shows recent snapshots with quick-switch
• "Manage Snapshots..." option at bottom opens timeline panel

6.2 Left Panel Integration

New Section: "Snapshots" (collapsible, like "Add Actors"):

┌─────────────────────────┐
│ ▼ Snapshots             │
├─────────────────────────┤
│ Current:                │
│ Feature Analysis v2     │
│ Modified 5 min ago      │
│                         │
│ [Create Snapshot]       │
│ [View Timeline]         │
│                         │
│ Recent:                 │
│ • Initial layout        │
│ • Team structure v1     │
│ • Alternative view      │
└─────────────────────────┘

Benefits:

• Quick access without opening timeline panel
• Shows current state at a glance
• Recent list for fast switching
• Minimal space when collapsed

6.3 Right Panel Integration

When Snapshot Selected (in timeline, not graph element):

Right panel shows snapshot metadata:

┌─────────────────────────┐
│ Snapshot Properties     │
├─────────────────────────┤
│ Name:                   │
│ [Feature Analysis v2__] │
│                         │
│ Description:            │
│ [Added finance team...] │
│                         │
│ Created:                │
│ Oct 11, 2025 2:30 PM    │
│                         │
│ Statistics:             │
│ • 12 actors             │
│ • 18 relations          │
│ • Branch: main          │
│                         │
│ Actions:                │
│ [Switch to Snapshot]    │
│ [Branch from Here]      │
│ [Compare with Current]  │
│ [Export Snapshot]       │
│ [Delete Snapshot]       │
└─────────────────────────┘

6.4 Document-Level Operations

Save Behavior:

• Ctrl+S saves changes to active snapshot (creates new state)
• Snapshots are immutable after creation (for history integrity)
• "Save" updates the active snapshot's graph data
• Dirty indicator shows unsaved changes in current snapshot

Export Behavior:

Export Active Snapshot:

• File → Export → Current Snapshot
• Exports only active snapshot's graph

Export All Snapshots:

• File → Export → All Snapshots (with timeline)
• Creates .constellation-multi file or ZIP
• Includes full snapshot history and lineage

Export Snapshot Range:

• File → Export → Selected Snapshots...
• Choose snapshots in timeline (multi-select)
• Exports selected portion of timeline

Import Behavior:

• Importing a multi-version file creates new document
• Preserves all snapshot history and relationships
• Can import into existing document as new branch (advanced)

6.5 Menu Bar Updates

New Menu Items:

File Menu:

File
├─ New Document
├─ Open Document...
├─ Save Document             Ctrl+S
├─ ───────────────
├─ Import...
├─ Export ►
│  ├─ Current Snapshot...
│  ├─ All Snapshots...
│  └─ Selected Snapshots...
├─ ───────────────
├─ Document Manager...

Edit Menu:

Edit
├─ Undo                      Ctrl+Z
├─ Redo                      Ctrl+Shift+Z
├─ ───────────────
├─ Create Snapshot           Ctrl+Shift+S
├─ Switch Snapshot ►
│  ├─ Feature Analysis v2    ✓
│  ├─ Initial layout
│  ├─ Team structure v1
│  └─ ───────────────
│     └─ Show All...
├─ ───────────────
├─ Select All                Ctrl+A

View Menu:

View
├─ Zoom In                   Ctrl++
├─ Zoom Out                  Ctrl+-
├─ Fit View                  Ctrl+0
├─ ───────────────
├─ Show Left Panel           Ctrl+1
├─ Show Right Panel          Ctrl+2
├─ Show Timeline Panel       Ctrl+B
├─ ───────────────
├─ Toggle Snapshot Minimap

---

7. Edge Cases & Considerations

7.1 Very Large Version Graphs (100+ snapshots)

Addressed by:

1. Virtual scrolling in timeline (Section 2.7)
2. Zoom levels for timeline density
3. Branch folding to hide inactive development
4. Search and filtering capabilities
5. Minimap for navigation
6. "Focus mode" showing only active branch

Additional Mitigations:

• Lazy-load snapshot data (metadata only until needed)
• Paginated snapshot list in dropdown menus
• Archive old branches to separate storage
• "Compact timeline" action to consolidate

7.2 Performance Considerations

Switching Between Snapshots:

Challenge: Loading large graphs (500+ nodes) is slow

Solutions:

1. Incremental Loading:

   • Load nodes first, edges second
   • Render in viewport first, off-screen later
   • Progress indicator for large graphs

2. Snapshot Diff Loading:

   • Store deltas between snapshots
   • Apply changes incrementally when switching similar snapshots
   • Full load only when necessary

3. Caching Strategy:

   • Keep previous 3 snapshots in memory
   • LRU cache for frequently accessed snapshots
   • Clear cache on memory pressure

4. Background Pre-loading:

   • Pre-load adjacent snapshots in background
   • Predict likely next navigation (temporal, branching)

Timeline Rendering:

• Canvas-based rendering for large timelines (>50 snapshots)
• SVG for smaller timelines (better quality, easier interaction)
• Virtual scrolling for snapshot list views

7.3 Snapshot Comparison (Diff View)

Feature: Compare two snapshots side-by-side

Trigger:

• Select snapshot → More Actions → Compare with...
• Select second snapshot from dropdown

Comparison View:

┌─────────────────────────────────────────────────────┐
│ Compare Snapshots                              [×]  │
├─────────────────────────────────────────────────────┤
│ [Snapshot A: v1 ▾]          [Snapshot B: v2 ▾]     │
├──────────────────────────┬──────────────────────────┤
│                          │                          │
│    [Graph View A]        │     [Graph View B]       │
│                          │                          │
├──────────────────────────┴──────────────────────────┤
│ Differences:                                        │
│ ✓ Actors: +3 new, -1 removed, 2 modified          │
│ ✓ Relations: +5 new, -2 removed, 1 modified       │
│                                                     │
│ [Show only differences] [Highlight changes]         │
└─────────────────────────────────────────────────────┘

Diff Highlighting:

• Added actors: Green border
• Removed actors: Red border with strikethrough
• Modified actors: Yellow border
• Similar visual treatment for relations

Diff Summary Panel:

• List of all changes with drill-down
• Export diff as report
• "Apply changes to active snapshot" action

7.4 Conflict Handling (if merging implemented)

Types of Conflicts:

1. Actor Conflicts:

   • Same actor ID with different properties
   • Different actors at same position
   • Actor type changes

2. Relation Conflicts:

   • Same relation with different types
   • Relations to deleted actors
   • Conflicting directionality

Resolution UI:

• Side-by-side conflict view
• "Keep mine" / "Keep theirs" / "Keep both" / "Manually edit"
• Preview of resolution before applying
• Save resolution as new snapshot

Recommendation: Defer merge functionality to v2, focus on:

• Clear separation of branches
• Easy comparison tools
• Manual integration workflows

7.5 Collaborative Editing (Future)

Consideration: If multiple users edit same document

Challenges:

• Snapshot creation conflicts
• Active snapshot synchronization
• Real-time collaboration on same snapshot

Potential Solutions:

1. Snapshot-level Locking:

   • Only one user can edit a snapshot at a time
   • Others can view or create branches

2. Per-User Branches:

   • Each user works on their own branch
   • Manual merging when ready

3. Operational Transform:

   • Real-time collaborative editing
   • Automatic conflict resolution
   • Very complex, future consideration

Initial Approach:

• Single-user focus
• Export/import for sharing
• Cloud sync preserves all snapshots

7.6 Undo/Redo Interaction

Question: How does undo/redo interact with snapshots?

Recommended Behavior:

1. Undo/Redo operates within active snapshot:

   • Each snapshot has its own undo history
   • Switching snapshots preserves undo stack
   • Undo stack cleared when switching snapshots (configurable)

2. Snapshot Creation in Undo Stack:

   • Creating a snapshot is an undoable action
   • Undo after snapshot creation deletes the snapshot
   • Redo recreates the snapshot

3. Switching Snapshots:

   • Not in undo stack (separate navigation)
   • Use snapshot history for navigation
   • Prevents undo/redo confusion

Settings Option:

• "Preserve undo history when switching snapshots" (default: OFF)
• When ON, each snapshot maintains separate undo stack
• Increases memory usage

7.7 Data Model Implications

Snapshot Storage Structure:

interface Snapshot {
  id: string;
  parentId: string | null;          // null for root snapshot
  name: string;
  description?: string;
  createdAt: string;
  updatedAt: string;

  // Graph state
  graphState: {
    nodes: Actor[];
    edges: Relation[];
    viewport?: { x: number; y: number; zoom: number };
  };

  // Metadata
  metadata: {
    actorCount: number;
    relationCount: number;
    thumbnail?: string;             // Base64 encoded preview
    tags?: string[];
    branch?: string;                // Optional branch label
  };

  // For delta storage (optimization)
  isDelta?: boolean;
  deltaFrom?: string;               // Parent snapshot ID
  deltaOperations?: DeltaOp[];      // Add/remove/modify operations
}

interface SnapshotGraph {
  snapshots: Map<string, Snapshot>;
  rootSnapshotId: string;
  activeSnapshotId: string;

  // Computed properties
  branches?: SnapshotBranch[];
  timeline?: SnapshotNode[];
}

Storage Strategy:

1. Full Storage (simple, initial approach):

   • Each snapshot stores complete graph state
   • Larger file size, but simpler logic
   • Good for <50 snapshots

2. Delta Storage (optimization):

   • Store only differences from parent
   • Reduces storage for large histories
   • Reconstruction required when loading
   • Good for >50 snapshots

3. Hybrid Approach:

   • Store full state every N snapshots (keyframes)
   • Deltas in between
   • Balance speed and size

---

8. User Workflows & Task Flows

8.1 Common Task: Exploring Alternative Scenarios

Scenario: User wants to try different team structures without losing original

Workflow:

1. User creates initial constellation with 20 actors
2. Clicks "Create Snapshot" → Names it "Initial team structure"
3. Makes modifications (adds 5 actors, removes 2)
4. Realizes this doesn't work well
5. In timeline, double-clicks "Initial team structure"
6. System prompts about unsaved changes → User discards
7. User is back at initial state
8. Right-clicks "Initial team structure" → "Create Branch from Here"
9. Names new branch "Alternative hierarchy"
10. Makes different changes
11. Now has two parallel versions to compare

Success Metrics:

• No confusion about current state
• Easy navigation between versions
• Clear visual representation of branches
• No accidental data loss

8.2 Common Task: Reviewing Evolution Over Time

Scenario: User wants to see how analysis evolved over a week

Workflow:

1. User opens document with 30 snapshots
2. Clicks timeline panel to expand
3. Uses timeline zoom to see all snapshots at once
4. Identifies key milestones visually
5. Clicks through snapshots to see changes
6. Uses comparison view to see specific differences
7. Exports progression as presentation

Enhancements:

• "Playback" mode: Auto-advance through snapshots
• Export as animated GIF or video
• Slide show mode for presentations

8.3 Common Task: Cleaning Up Old Work

Scenario: User has 100+ snapshots, wants to consolidate

Workflow:

1. Opens timeline panel
2. Clicks More Actions → "Compact Timeline"
3. System shows preview of compaction:
   • "Will remove 40 auto-snapshots older than 30 days"
   • "Will consolidate 15 sequential snapshots with no branches"
4. User confirms
5. Timeline now shows 45 snapshots (much cleaner)
6. Important milestones preserved

Safety:

• Preview before compaction
• Undo compaction (keep deleted snapshots in "trash" for 30 days)
• Never auto-compact without user action

8.4 Common Task: Collaborating with Team Member

Scenario: User wants to share work-in-progress with colleague

Workflow:

1. User exports document with all snapshots
2. Colleague imports document
3. Colleague creates branch "Sarah's suggestions"
4. Makes changes in new branch
5. Exports back to user
6. User imports, sees new branch in timeline
7. User reviews changes, manually integrates good ideas

Future Enhancement:

• Cloud sync with branch visibility
• Comments on snapshots
• Suggested changes workflow

---

9. Visual Design Recommendations

9.1 Color Palette

Timeline Panel:

• Background: #ffffff (white)
• Panel border: #e5e7eb (gray-200)
• Header background: #f9fafb (gray-50)

Snapshot Nodes:

• Inactive: #94a3b8 (slate-400)
• Active: #3b82f6 (blue-500)
• Hover: #64748b (slate-500)
• Selected: #2563eb (blue-600)

Connection Lines:

• Default: #cbd5e1 (slate-300)
• Active path: #3b82f6 (blue-500)
• Hover: #94a3b8 (slate-400)

Branch Color Coding (subtle):

• Branch 1: #3b82f6 (blue) - main branch
• Branch 2: #10b981 (green)
• Branch 3: #f59e0b (amber)
• Branch 4: #8b5cf6 (purple)
• Branch 5+: Rotate through palette

9.2 Typography

Timeline Panel:

• Panel title: 12px, font-weight: 600, color: #374151
• Snapshot names: 11px, font-weight: 500, color: #1f2937
• Timestamps: 10px, font-weight: 400, color: #6b7280
• Details footer: 11px, font-weight: 400

Snapshot Tooltips:

• Title: 13px, font-weight: 600
• Body text: 11px, font-weight: 400
• Metadata: 10px, font-weight: 400, color: #6b7280

9.3 Iconography

Timeline Controls:

• Create snapshot: Camera icon (📸)
• Branch: Git branch icon (🔀)
• Compare: Side-by-side icon (⚖️)
• Delete: Trash icon (🗑️)
• More actions: Vertical ellipsis (⋮)

Snapshot States:

• Active: Filled circle with subtle glow
• Inactive: Hollow circle
• Auto-snapshot: Small square
• Milestone: Star or flag icon overlay

9.4 Animation & Transitions

Snapshot Switching:

• Fade out current graph (150ms)
• Show loading indicator (if >200ms load time)
• Fade in new graph (200ms)
• Timeline node moves with ease-in-out (300ms)

Timeline Interactions:

• Node hover: Scale 1.1, duration 100ms
• Connection line hover: Opacity 1.0, width +1px, duration 150ms
• Branch expand/collapse: Height transition 250ms

Panel Resize:

• Smooth height transition (200ms)
• Snap to collapsed/expanded states

9.5 Accessibility

Keyboard Navigation:

• All timeline controls accessible via keyboard
• Focus indicators clearly visible
• Logical tab order through controls

Screen Reader Support:

• Snapshot nodes: "Snapshot: [name], created [timestamp], [active/inactive]"
• Timeline: "Snapshot timeline with [N] snapshots"
• Actions: Clear button labels and ARIA descriptions

Visual Accessibility:

• Color not sole indicator (use shapes, labels, icons)
• High contrast mode support
• Sufficient text size (minimum 11px)
• Focus indicators: 2px blue outline

---

10. Implementation Phases

Phase 1: Core Foundation (MVP)

Goal: Basic multi-version support with linear timeline

Features:

• Create snapshots manually
• Switch between snapshots
• Linear timeline visualization (no branching)
• Basic snapshot metadata (name, timestamp)
• Unsaved changes handling
• Timeline panel (bottom, resizable)

Scope: Single linear sequence of snapshots, no branching yet

Phase 2: Branching Support

Goal: Enable parallel exploration paths

Features:

• Create branches from any snapshot
• Branching timeline visualization
• Branch labels and organization
• Re-parenting operations
• Branch color coding

Phase 3: Enhanced Navigation

Goal: Improve large timeline handling

Features:

• Virtual scrolling for 100+ snapshots
• Timeline zoom levels
• Minimap navigation
• Search and filtering
• Branch folding
• Quick switcher dropdown

Phase 4: Comparison & Analysis

Goal: Tools for analyzing snapshot differences

Features:

• Side-by-side comparison view
• Diff highlighting
• Export comparison reports
• Snapshot playback mode
• Evolution animations

Phase 5: Advanced Features

Goal: Power-user capabilities

Features:

• Merge operations (if feasible)
• Timeline compaction
• Snapshot tagging
• Advanced filtering
• Collaborative features (cloud sync)

---

11. Success Metrics

Usability Metrics:

• Time to create first snapshot: <30 seconds
• Time to switch between snapshots: <3 seconds (perceived)
• Error rate when branching: <5%
• User comprehension score: >80% understand snapshot concept after 5 minutes

Adoption Metrics:

• % of users creating >1 snapshot: Target 60%
• Average snapshots per document: Target 5-10
• % of users using branching: Target 30%

Performance Metrics:

• Timeline rendering for 50 snapshots: <500ms
• Snapshot switch time: <1 second for 200-node graph
• Memory usage: <50MB additional for snapshot metadata

Quality Metrics:

• Accidental data loss reports: 0
• Confusion-related support tickets: <5% of total
• User satisfaction with feature: >4.0/5.0

---

12. Open Questions & Future Considerations

Open Questions:

1. Should snapshots be immutable after creation?

   • Pro: Preserves history integrity
   • Con: Can't fix mistakes in past snapshots
   • Recommendation: Immutable, but allow "amend" for last snapshot

2. How to handle node type / edge type changes across snapshots?

   • If types are modified, do old snapshots update?
   • Recommendation: Types versioned with snapshots (each snapshot has its own type definitions)

3. Should viewport position be saved per snapshot?

   • Pro: Contextual viewing
   • Con: Can be disorienting
   • Recommendation: Configurable, default to "fit view" on switch

4. Maximum snapshots per document?

   • Technical limit to prevent performance issues
   • Recommendation: 500 snapshots hard limit, warning at 100

Future Enhancements:

1. Snapshot Templates:

   • Save snapshot as reusable template
   • Apply template structure to new snapshot

2. Conditional Snapshots:

   • Auto-create snapshot when specific conditions met
   • E.g., "snapshot when >50 actors"

3. Snapshot Metadata:

   • Add tags, categories, colors
   • Custom metadata fields
   • Link to external documentation

4. Timeline Views:

   • Calendar view (snapshots by date)
   • Tree view (hierarchical)
   • Graph view (current visualization)
   • List view (table with metadata)

5. Export Formats:

   • Export timeline as image
   • Export snapshot progression as slides
   • Export as git repository (for version control enthusiasts)

6. AI-Assisted Features:

   • Auto-suggest snapshot names based on changes
   • Detect significant changes warranting snapshot
   • Recommend consolidation opportunities

---

Appendix A: Terminology Glossary

Term	Definition	User-Facing?
Snapshot	A saved state of the graph at a specific moment	Yes
Timeline	Visual representation of snapshot history	Yes
Branch	A diverging path from a snapshot	Yes
Active Snapshot	The currently displayed and editable version	Yes
Parent Snapshot	The snapshot from which another was created	Partially (internal)
Re-parenting	Changing the parent of a snapshot	No (action-based)
Keyframe	Full snapshot stored for performance (not delta)	No (internal)
Delta	Incremental changes from parent snapshot	No (internal)
Lineage	The ancestral path of a snapshot	Partially (visual only)

---

Appendix B: Sample User Scenarios

Scenario 1: Academic Researcher

User: Dr. Emily, analyzing organizational networks

Goal: Track evolution of team dynamics over semester

Usage Pattern:

• Creates snapshot at start of each week (16 total)
• Reviews progression at end of semester
• Exports timeline as part of research paper
• Branches at week 8 to explore "what if" reorganization

Key Features Used:

• Manual snapshot creation
• Timeline playback
• Comparison view
• Export functionality

Scenario 2: Business Analyst

User: Marcus, mapping stakeholder relationships

Goal: Present multiple strategic options to leadership

Usage Pattern:

• Creates initial stakeholder map
• Branches into 3 scenarios: "Status Quo", "Reorganization", "External Partnership"
• Develops each branch independently
• Uses comparison to highlight differences
• Exports each branch as separate presentation

Key Features Used:

• Branching
• Branch management
• Comparison
• Export per branch

Scenario 3: Software Architect

User: Priya, designing system architecture

Goal: Document architectural evolution and decision points

Usage Pattern:

• Creates snapshot for each major design iteration
• Adds detailed descriptions explaining rationale
• Uses tags: "approved", "prototype", "rejected"
• Keeps rejected options for future reference
• Shares with team via exported timeline

Key Features Used:

• Snapshots with descriptions
• Tagging (future feature)
• Historical preservation
• Team sharing

---

Conclusion

This UX concept provides a comprehensive foundation for implementing multi-version graph support in Constellation Analyzer. The design balances:

• Simplicity for casual users who want basic versioning
• Power for advanced users exploring complex scenarios
• Clarity through visual timeline representation
• Safety via non-destructive editing and confirmations
• Performance through optimizations for large version graphs

The phased implementation approach allows for iterative development and user feedback integration. Starting with a simple linear timeline (Phase 1) establishes the foundation, while later phases add sophisticated branching and comparison capabilities.

Next Steps:

1. Review and validate concept with stakeholders
2. Create high-fidelity mockups for Phase 1
3. Develop data model and storage strategy
4. Build Phase 1 prototype
5. Conduct usability testing
6. Iterate based on feedback

---

Document Version: 1.0 Date: October 11, 2025 Author: UX Design Team Status: Proposal for Review