Skip to main content

​
Timeline Navigation

Chronicle’s signature feature is the draggable immersive document timeline. This guide explains how to use it.

​
Concept

The timeline treats document history as a navigable dimension. Instead of traditional “version history” with discrete snapshots, Chronicle shows you a continuous timeline of all changes, allowing you to:
  • Scrub through time like a video
  • Jump to specific moments
  • Filter by user or operation type
  • Preview historical states
  • Compare different points in time

​
Using the Timeline Panel

The timeline panel appears on the right side of the editor: 
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   Document Content                     │ Timeline              │
│                                        │                       │
│   Your document text here...           │ ◉ Alice added para    │
│                                        │ ◉ Bob made bold       │
│                                        │ ◉ Alice removed note  │
│                                        │                       │
│                                        │ [━━━━━━━━━●━━━]       │
│                                        │ 24h ago        Now    │
│                                        │                       │
└─────────────────────────────────────────────────────────────────┘

​
Scrubbing

Drag the slider to move through time. The document content updates in real-time to show the state at that moment.

​
Clicking Entries

Click any entry in the timeline to jump directly to that point. The entry will be highlighted and the document will show the state immediately after that operation.

​
Back to Present

When viewing historical state, a “Back to Present” button appears. Click it to return to the current document state.

​
Code Integration

​
Using TimelinePlugin

import { TimelinePlugin } from '@chronicle-hq/editor/plugins';

const timeline = new TimelinePlugin({
  scrubbing: true,
  onTimeChange: (hlcTimestamp) => {
    // Called when user navigates
    console.log('Viewing:', new Date(hlcTimestamp));
  },
  onViewHistorical: (isHistorical) => {
    if (isHistorical) {
      // Show "historical mode" indicator
      showHistoricalBanner();
    } else {
      hideHistoricalBanner();
    }
  },
});

​
Programmatic Navigation

// Jump to specific time
await timeline.goToTime(1708780800000);

// Get state at that time
const historicalState = timeline.getState(editorState);
console.log(historicalState.isViewingHistorical); // true

// Return to present
await timeline.goToPresent();

​
Querying History

// Get entries in time range
const entries = await timeline.getEntriesInRange({
  from: Date.now() - 86400000, // 24h ago
  to: Date.now(),
});

// Get entries by specific user
const aliceEdits = await timeline.getEntriesByUser('alice-id');

// Get diff between two points
const diff = await timeline.getDiff(
  timestamp1,
  timestamp2
);

​
Timeline Store (React)

In the app, use the Zustand store: 
import { useTimelineStore } from '@/stores/timeline';

function TimelineControls() {
  const { 
    currentTime, 
    isViewingHistorical, 
    entries,
    goToTime,
    goToPresent 
  } = useTimelineStore();

  return (
    <div>
      {isViewingHistorical && (
        <button onClick={goToPresent}>
          Back to Present
        </button>
      )}
      
      <input
        type="range"
        min={Date.now() - 86400000}
        max={Date.now()}
        value={currentTime ?? Date.now()}
        onChange={(e) => goToTime(Number(e.target.value))}
      />
    </div>
  );
}

​
Best Practices

  1. Indicate Historical Mode - Always clearly show when viewing historical state
  2. Disable Editing - Prevent edits when viewing history (read-only mode)
  3. Show User Colors - Use consistent colors for each collaborator
  4. Batch Operations - Group rapid edits (typing) into single entries
  5. Performance - Virtualize long timelines for smooth scrolling