Pentimento Writing Process Telemetry

Telemetry Architecture & Op Coalescing #

Pentimento records the microscopic physical act of writing without bogging down disk I/O. Instead of logging every raw keydown event to SQLite individually, Pentimento uses an in-memory Run Coalescer (src/renderer/src/utils/pentimentoRecorder.js) listening directly to ProseMirror transactions:

{
  "timestamp": "2026-08-30T18:40:00.000Z",
  "op_type": "insert",          // "insert" | "paste" | "delete" | "pause"
  "para_index": 4,              // Target paragraph index (resolved via doc.resolve)
  "char_offset": 142,           // In-paragraph character offset
  "length": 48,                 // Deleted or inserted size in characters
  "text_content": "The cold wind sliced through the castle gate.",
  "duration_ms": 3400           // Accumulated wall-clock duration of the burst
}

Coalescing & Batch Flushing Rules

A "run" accumulates same-type edits within a single paragraph and only flushes when:

• Paragraph Boundary: The author moves their cursor to a different paragraph.
• Edit Type Inversion: The author switches from typing (insert) to backspacing (delete).
• Pause Threshold: Inactivity exceeding PAUSE_MS = 2500ms triggers a standalone pause op (capped at PAUSE_CAP_MS = 10 min).
• Run Limits: A single run reaches RUN_MAX_CHARS = 80 chars or spans RUN_MAX_MS = 20,000ms.
• Disk Batch Flushing: Buffered ops are posted to POST /api/project/pentimento/ops every FLUSH_COUNT = 40 ops or every FLUSH_MS = 12,000ms.

This keeps an entire 120,000-word novel's keystroke-level revision history in the low tens of megabytes while remaining 100% non-blocking.

Cryptographic Session Sealing (SHA-256 Hash Chain)

When an author stops writing for more than 10 minutes or manually switches chapters, the active session is sealed into the pentimento_sessions table with an immutable cryptographic block hash:

session_hash = SHA256(previous_session_hash + chapter_id + word_delta + ops_root_hash + end_timestamp)

Paragraph Effort Heatmap #

The Effort Heatmap visualizes the invisible toil behind every section of prose. It calculates the Revision-to-Length Ratio (RLR) per paragraph:

effort_density = (deleted_character_count + inserted_character_count) / final_paragraph_length

Paragraphs that flowed effortlessly in a single draft appear in a cool amber hue, while heavily edited, rewritten, and agonized-over passages glow in intense fiery crimson.

Prose Snapshots & History Rollback Panel #

At every session boundary, the system takes an immutable full-text prose snapshot stored in prose_snapshots. The right-side History Panel (src/renderer/src/components/HistoryPanel.jsx) allows authors to:

• Inspect Unified Diffs: Compare any past session directly against the current draft with word-level insertions (green) and deletions (red).
• Pin Milestones: Name and freeze major drafting milestones (e.g. "First Draft Complete", "Post-Beta Reader Revisions").
• Non-Destructive Rollback: Restore any historical snapshot. Restoring creates a new forward snapshot, ensuring no work is ever lost.

Process Replay Simulation Engine #

The Replay Engine reconstructs the creation of a chapter from blank canvas to finished manuscript. It paces the simulation using the stored duration and keystroke cadence of coalesced ops, featuring speed multiplier controls (1x, 5x, 20x, 100x).