@git-stunts/git-warp 10.3.2 → 10.7.0

package/src/visualization/layouts/elkAdapter.js

@@ -2,6 +2,16 @@
  * ELK adapter: converts normalised graph data into ELK JSON input.
  */
 
+/**
+ * @typedef {{ id: string, label: string, props?: Record<string, any> }} GraphDataNode
+ * @typedef {{ from: string, to: string, label?: string }} GraphDataEdge
+ * @typedef {{ nodes: GraphDataNode[], edges: GraphDataEdge[] }} GraphData
+ * @typedef {{ text: string }} ElkLabel
+ * @typedef {{ id: string, sources: string[], targets: string[], labels?: ElkLabel[] }} ElkEdge
+ * @typedef {{ id: string, width: number, height: number, labels: ElkLabel[] }} ElkChild
+ * @typedef {{ id: string, layoutOptions: Record<string, string>, children: ElkChild[], edges: ElkEdge[] }} ElkGraph
+ */
+
 const LAYOUT_PRESETS = {
   query: {
     'elk.algorithm': 'layered',
@@ -29,7 +39,7 @@ const DEFAULT_PRESET = LAYOUT_PRESETS.query;
  * Returns ELK layout options for a given visualisation type.
  *
  * @param {'query'|'path'|'slice'} type
- * @returns {Object} ELK layout options
+ * @returns {Record<string, string>} ELK layout options
  */
 export function getDefaultLayoutOptions(type) {
   return LAYOUT_PRESETS[type] ?? DEFAULT_PRESET;
@@ -38,6 +48,8 @@ export function getDefaultLayoutOptions(type) {
 /**
  * Estimates pixel width for a node label.
  * Approximates monospace glyph width at ~9px with 24px padding.
+ * @param {string | undefined} label
+ * @returns {number}
  */
 function estimateNodeWidth(label) {
   const charWidth = 9;
@@ -51,9 +63,9 @@ const NODE_HEIGHT = 30;
 /**
  * Converts normalised graph data to an ELK graph JSON object.
  *
- * @param {{ nodes: Array, edges: Array }} graphData
- * @param {{ type?: string, layoutOptions?: Object }} [options]
- * @returns {Object} ELK-format graph
+ * @param {GraphData} graphData
+ * @param {{ type?: 'query'|'path'|'slice', layoutOptions?: Record<string, string> }} [options]
+ * @returns {ElkGraph} ELK-format graph
  */
 export function toElkGraph(graphData, options = {}) {
   const { type = 'query', layoutOptions } = options;
@@ -66,6 +78,7 @@ export function toElkGraph(graphData, options = {}) {
   }));
 
   const edges = (graphData.edges ?? []).map((e, i) => {
+    /** @type {ElkEdge} */
     const edge = {
       id: `e${i}`,
       sources: [e.from],

package/src/visualization/layouts/elkLayout.js

@@ -5,11 +5,22 @@
  * a layout is actually requested, keeping normal CLI startup fast.
  */
 
+/**
+ * @typedef {{ id: string, x?: number, y?: number, width?: number, height?: number, labels?: Array<{ text: string }> }} ElkResultChild
+ * @typedef {{ id: string, sources?: string[], targets?: string[], labels?: Array<{ text: string }>, sections?: any[] }} ElkResultEdge
+ * @typedef {{ children?: ElkResultChild[], edges?: ElkResultEdge[], width?: number, height?: number }} ElkResult
+ * @typedef {{ id: string, x: number, y: number, width: number, height: number, label: string }} PosNode
+ * @typedef {{ id: string, source: string, target: string, label?: string, sections: any[] }} PosEdge
+ * @typedef {{ nodes: PosNode[], edges: PosEdge[], width: number, height: number }} PositionedGraph
+ * @typedef {{ id: string, children?: Array<{ id: string, width?: number, height?: number, labels?: Array<{ text: string }> }>, edges?: Array<{ id: string, sources?: string[], targets?: string[], labels?: Array<{ text: string }> }>, layoutOptions?: Record<string, string> }} ElkGraphInput
+ */
+
+/** @type {Promise<any> | null} */
 let elkPromise = null;
 
 /**
  * Returns (or creates) a singleton ELK instance.
- * @returns {Promise<Object>} ELK instance
+ * @returns {Promise<any>} ELK instance
  */
 function getElk() {
   if (!elkPromise) {
@@ -21,10 +32,11 @@ function getElk() {
 /**
  * Runs ELK layout on a graph and returns a PositionedGraph.
  *
- * @param {Object} elkGraph - ELK-format graph from toElkGraph()
- * @returns {Promise<Object>} PositionedGraph
+ * @param {ElkGraphInput} elkGraph - ELK-format graph from toElkGraph()
+ * @returns {Promise<PositionedGraph>} PositionedGraph
  */
 export async function runLayout(elkGraph) {
+  /** @type {ElkResult | undefined} */
   let result;
   try {
     const elk = await getElk();
@@ -37,9 +49,11 @@ export async function runLayout(elkGraph) {
 
 /**
  * Converts ELK output to a PositionedGraph.
+ * @param {ElkResult | undefined} result
+ * @returns {PositionedGraph}
  */
 function toPositionedGraph(result) {
-  const nodes = (result.children ?? []).map((c) => ({
+  const nodes = (result?.children ?? []).map((c) => ({
     id: c.id,
     x: c.x ?? 0,
     y: c.y ?? 0,
@@ -48,7 +62,7 @@ function toPositionedGraph(result) {
     label: c.labels?.[0]?.text ?? c.id,
   }));
 
-  const edges = (result.edges ?? []).map((e) => ({
+  const edges = (result?.edges ?? []).map((e) => ({
     id: e.id,
     source: e.sources?.[0] ?? '',
     target: e.targets?.[0] ?? '',
@@ -59,13 +73,15 @@ function toPositionedGraph(result) {
   return {
     nodes,
     edges,
-    width: result.width ?? 0,
-    height: result.height ?? 0,
+    width: result?.width ?? 0,
+    height: result?.height ?? 0,
   };
 }
 
 /**
  * Fallback: line nodes up horizontally when ELK fails.
+ * @param {ElkGraphInput} elkGraph
+ * @returns {PositionedGraph}
  */
 function fallbackLayout(elkGraph) {
   let x = 20;

package/src/visualization/layouts/index.js

@@ -19,9 +19,9 @@ import { runLayout } from './elkLayout.js';
 /**
  * Full pipeline: graphData → PositionedGraph.
  *
- * @param {{ nodes: Array, edges: Array }} graphData - Normalised graph data
- * @param {{ type?: string, layoutOptions?: Object }} [options]
- * @returns {Promise<Object>} PositionedGraph
+ * @param {{ nodes: Array<{ id: string, label: string }>, edges: Array<{ from: string, to: string, label?: string }> }} graphData - Normalised graph data
+ * @param {{ type?: 'query'|'path'|'slice', layoutOptions?: Record<string, string> }} [options]
+ * @returns {Promise<{ nodes: any[], edges: any[], width: number, height: number }>} PositionedGraph
  */
 export async function layoutGraph(graphData, options = {}) {
   const elkGraph = toElkGraph(graphData, options);

package/src/visualization/renderers/ascii/check.js

@@ -12,6 +12,18 @@ import { colors } from './colors.js';
 import { padRight } from '../../utils/unicode.js';
 import { formatAge } from './formatters.js';
 
+/**
+ * @typedef {{ cachedState?: string, tombstoneRatio?: number, patchesSinceCheckpoint?: number }} CheckStatus
+ * @typedef {{ writerId?: string, sha?: string }} WriterHead
+ * @typedef {{ sha?: string, ageSeconds?: number | null }} CheckpointInfo
+ * @typedef {{ installed?: boolean, foreign?: boolean, current?: boolean, version?: string }} HookInfo
+ * @typedef {{ sha?: string, missingWriters?: string[] }} CoverageInfo
+ * @typedef {{ status?: string }} HealthInfo
+ * @typedef {{ tombstoneRatio?: number }} GCInfo
+ * @typedef {{ heads?: WriterHead[] }} WritersInfo
+ * @typedef {{ graph: string, health: HealthInfo, status: CheckStatus, writers: WritersInfo, checkpoint: CheckpointInfo, coverage: CoverageInfo, gc: GCInfo, hook: HookInfo | null }} CheckPayload
+ */
+
 // Health thresholds
 const TOMBSTONE_HEALTHY_MAX = 0.15;     // < 15% tombstones = healthy
 const TOMBSTONE_WARNING_MAX = 0.30;     // < 30% tombstones = warning
@@ -19,7 +31,7 @@ const CACHE_STALE_PENALTY = 20;         // Reduce "freshness" score for stale ca
 
 /**
  * Get cache freshness percentage and state.
- * @param {Object} status - The status object from check payload
+ * @param {CheckStatus | null} status - The status object from check payload
  * @returns {{ percent: number, label: string }}
  */
 function getCacheFreshness(status) {
@@ -78,7 +90,7 @@ function tombstoneBar(percent, width = 20) {
 
 /**
  * Format writer information for display.
- * @param {Object[]} heads - Writer heads array
+ * @param {WriterHead[] | undefined} heads - Writer heads array
  * @returns {string}
  */
 function formatWriters(heads) {
@@ -94,7 +106,7 @@ function formatWriters(heads) {
 
 /**
  * Format checkpoint status line.
- * @param {Object} checkpoint - Checkpoint info
+ * @param {CheckpointInfo | null} checkpoint - Checkpoint info
  * @returns {string}
  */
 function formatCheckpoint(checkpoint) {
@@ -103,13 +115,14 @@ function formatCheckpoint(checkpoint) {
   }
 
   const sha = colors.muted(checkpoint.sha.slice(0, 7));
-  const age = formatAge(checkpoint.ageSeconds);
+  const ageSeconds = checkpoint.ageSeconds ?? null;
+  const age = formatAge(ageSeconds);
 
   // Add checkmark for recent checkpoints (< 5 min), warning for older
   let status;
-  if (checkpoint.ageSeconds !== null && checkpoint.ageSeconds < 300) {
+  if (ageSeconds !== null && ageSeconds < 300) {
     status = colors.success('\u2713');
-  } else if (checkpoint.ageSeconds !== null && checkpoint.ageSeconds < 3600) {
+  } else if (ageSeconds !== null && ageSeconds < 3600) {
     status = colors.warning('\u2713');
   } else {
     status = colors.muted('\u2713');
@@ -120,7 +133,7 @@ function formatCheckpoint(checkpoint) {
 
 /**
  * Format hook status line.
- * @param {Object|null} hook - Hook status
+ * @param {HookInfo|null} hook - Hook status
  * @returns {string}
  */
 function formatHook(hook) {
@@ -145,7 +158,7 @@ function formatHook(hook) {
 
 /**
  * Format coverage status line.
- * @param {Object} coverage - Coverage info
+ * @param {CoverageInfo | null} coverage - Coverage info
  * @returns {string}
  */
 function formatCoverage(coverage) {
@@ -164,7 +177,7 @@ function formatCoverage(coverage) {
 
 /**
  * Get overall health status with color and symbol.
- * @param {Object} health - Health object
+ * @param {HealthInfo | null} health - Health object
  * @returns {{ text: string, symbol: string, color: Function }}
  */
 function getOverallHealth(health) {
@@ -190,8 +203,8 @@ function getOverallHealth(health) {
 
 /**
  * Build the state section lines (cache, tombstones, patches).
- * @param {Object} status - Status object
- * @param {Object} gc - GC metrics
+ * @param {CheckStatus | null} status - Status object
+ * @param {GCInfo | null} gc - GC metrics
  * @returns {string[]}
  */
 function buildStateLines(status, gc) {
@@ -215,10 +228,10 @@ function buildStateLines(status, gc) {
 /**
  * Build the metadata section lines (writers, checkpoint, coverage, hooks).
  * @param {Object} opts - Metadata options
- * @param {Object} opts.writers - Writers info
- * @param {Object} opts.checkpoint - Checkpoint info
- * @param {Object} opts.coverage - Coverage info
- * @param {Object} opts.hook - Hook status
+ * @param {WritersInfo} opts.writers - Writers info
+ * @param {CheckpointInfo} opts.checkpoint - Checkpoint info
+ * @param {CoverageInfo} opts.coverage - Coverage info
+ * @param {HookInfo | null} opts.hook - Hook status
  * @returns {string[]}
  */
 function buildMetadataLines({ writers, checkpoint, coverage, hook }) {
@@ -232,7 +245,7 @@ function buildMetadataLines({ writers, checkpoint, coverage, hook }) {
 
 /**
  * Determine border color based on health status.
- * @param {Object} overall - Overall health info
+ * @param {{ text: string, symbol: string, color: Function }} overall - Overall health info
  * @returns {string}
  */
 function getBorderColor(overall) {
@@ -243,7 +256,7 @@ function getBorderColor(overall) {
 
 /**
  * Render the check view dashboard.
- * @param {Object} payload - The check command payload
+ * @param {CheckPayload} payload - The check command payload
  * @returns {string} Formatted dashboard string
  */
 export function renderCheckView(payload) {

package/src/visualization/renderers/ascii/graph.js

@@ -11,6 +11,14 @@ import { createBox } from './box.js';
 import { colors } from './colors.js';
 import { ARROW } from './symbols.js';
 
+/**
+ * @typedef {{ x: number, y: number }} Point
+ * @typedef {{ startPoint?: Point, endPoint?: Point, bendPoints?: Point[] }} Section
+ * @typedef {{ id: string, x: number, y: number, width: number, height: number, label?: string }} PositionedNode
+ * @typedef {{ id: string, source: string, target: string, label?: string, sections?: Section[] }} PositionedEdge
+ * @typedef {{ nodes: PositionedNode[], edges: PositionedEdge[], width: number, height: number }} PositionedGraph
+ */
+
 // ── Scaling constants ────────────────────────────────────────────────────────
 
 const CELL_W = 10;
@@ -30,23 +38,33 @@ const BOX = {
 
 // ── Grid helpers ─────────────────────────────────────────────────────────────
 
+/** @param {number} px */
 function toCol(px) {
   return Math.round(px / CELL_W) + MARGIN;
 }
 
+/** @param {number} px */
 function toRow(px) {
   return Math.round(px / CELL_H) + MARGIN;
 }
 
+/** @param {number} px */
 function scaleW(px) {
   return Math.round(px / CELL_W);
 }
 
+/** @param {number} px */
 function scaleH(px) {
   return Math.round(px / CELL_H);
 }
 
+/**
+ * @param {number} rows
+ * @param {number} cols
+ * @returns {string[][]}
+ */
 function createGrid(rows, cols) {
+  /** @type {string[][]} */
   const grid = [];
   for (let r = 0; r < rows; r++) {
     grid.push(new Array(cols).fill(' '));
@@ -54,12 +72,24 @@ function createGrid(rows, cols) {
   return grid;
 }
 
+/**
+ * @param {string[][]} grid
+ * @param {number} r
+ * @param {number} c
+ * @param {string} ch
+ */
 function writeChar(grid, r, c, ch) {
   if (r >= 0 && r < grid.length && c >= 0 && c < grid[0].length) {
     grid[r][c] = ch;
   }
 }
 
+/**
+ * @param {string[][]} grid
+ * @param {number} r
+ * @param {number} c
+ * @returns {string}
+ */
 function readChar(grid, r, c) {
   if (r >= 0 && r < grid.length && c >= 0 && c < grid[0].length) {
     return grid[r][c];
@@ -67,6 +97,12 @@ function readChar(grid, r, c) {
   return ' ';
 }
 
+/**
+ * @param {string[][]} grid
+ * @param {number} r
+ * @param {number} c
+ * @param {string} str
+ */
 function writeString(grid, r, c, str) {
   for (let i = 0; i < str.length; i++) {
     writeChar(grid, r, c + i, str[i]);
@@ -75,6 +111,10 @@ function writeString(grid, r, c, str) {
 
 // ── Node stamping ────────────────────────────────────────────────────────────
 
+/**
+ * @param {string[][]} grid
+ * @param {PositionedNode} node
+ */
 function stampNode(grid, node) {
   const r = toRow(node.y);
   const c = toCol(node.x);
@@ -112,6 +152,11 @@ function stampNode(grid, node) {
 
 // ── Edge tracing ─────────────────────────────────────────────────────────────
 
+/**
+ * @param {string[][]} grid
+ * @param {PositionedEdge} edge
+ * @param {Set<string>} nodeSet
+ */
 function traceEdge(grid, edge, nodeSet) {
   const { sections } = edge;
   if (!sections || sections.length === 0) {
@@ -136,6 +181,7 @@ function traceEdge(grid, edge, nodeSet) {
   }
 }
 
+/** @param {Section} section @returns {Point[]} */
 function buildPointList(section) {
   const points = [];
   if (section.startPoint) {
@@ -150,6 +196,11 @@ function buildPointList(section) {
   return points;
 }
 
+/**
+ * @param {string[][]} grid
+ * @param {Point[]} points
+ * @param {Set<string>} nodeSet
+ */
 function drawSegments(grid, points, nodeSet) {
   for (let i = 0; i < points.length - 1; i++) {
     const r1 = toRow(points[i].y);
@@ -160,6 +211,14 @@ function drawSegments(grid, points, nodeSet) {
   }
 }
 
+/**
+ * @param {string[][]} grid
+ * @param {number} r1
+ * @param {number} c1
+ * @param {number} r2
+ * @param {number} c2
+ * @param {Set<string>} nodeSet
+ */
 function drawLine(grid, r1, c1, r2, c2, nodeSet) {
   if (r1 === r2) {
     drawHorizontal(grid, r1, c1, c2, nodeSet);
@@ -172,6 +231,13 @@ function drawLine(grid, r1, c1, r2, c2, nodeSet) {
   }
 }
 
+/**
+ * @param {string[][]} grid
+ * @param {number} row
+ * @param {number} c1
+ * @param {number} c2
+ * @param {Set<string>} nodeSet
+ */
 function drawHorizontal(grid, row, c1, c2, nodeSet) {
   const start = Math.min(c1, c2);
   const end = Math.max(c1, c2);
@@ -187,6 +253,13 @@ function drawHorizontal(grid, row, c1, c2, nodeSet) {
   }
 }
 
+/**
+ * @param {string[][]} grid
+ * @param {number} col
+ * @param {number} r1
+ * @param {number} r2
+ * @param {Set<string>} nodeSet
+ */
 function drawVertical(grid, col, r1, r2, nodeSet) {
   const start = Math.min(r1, r2);
   const end = Math.max(r1, r2);
@@ -202,6 +275,11 @@ function drawVertical(grid, col, r1, r2, nodeSet) {
   }
 }
 
+/**
+ * @param {string[][]} grid
+ * @param {Section} section
+ * @param {Set<string>} nodeSet
+ */
 function drawArrowhead(grid, section, nodeSet) {
   const ep = section.endPoint;
   if (!ep) {
@@ -250,6 +328,12 @@ function drawArrowhead(grid, section, nodeSet) {
   }
 }
 
+/**
+ * @param {string[][]} grid
+ * @param {Section[]} sections
+ * @param {string} label
+ * @param {Set<string>} nodeSet
+ */
 function placeEdgeLabel(grid, sections, label, nodeSet) {
   // Find midpoint of the full path
   const allPoints = [];
@@ -292,6 +376,7 @@ function placeEdgeLabel(grid, sections, label, nodeSet) {
 
 // ── Node occupancy set ───────────────────────────────────────────────────────
 
+/** @param {PositionedNode[]} nodes @returns {Set<string>} */
 function buildNodeSet(nodes) {
   const set = new Set();
   for (const node of nodes) {
@@ -308,6 +393,12 @@ function buildNodeSet(nodes) {
   return set;
 }
 
+/**
+ * @param {Set<string>} nodeSet
+ * @param {number} r
+ * @param {number} c
+ * @returns {boolean}
+ */
 function isNodeCell(nodeSet, r, c) {
   return nodeSet.has(`${r},${c}`);
 }
@@ -317,7 +408,7 @@ function isNodeCell(nodeSet, r, c) {
 /**
  * Renders a PositionedGraph (from ELK) as an ASCII box-drawing string.
  *
- * @param {Object} positionedGraph - PositionedGraph from runLayout()
+ * @param {PositionedGraph} positionedGraph - PositionedGraph from runLayout()
  * @param {{ title?: string }} [options]
  * @returns {string} Rendered ASCII art wrapped in a box
  */

package/src/visualization/renderers/ascii/history.js

@@ -9,13 +9,17 @@ import { padRight, padLeft } from '../../utils/unicode.js';
 import { TIMELINE } from './symbols.js';
 import { OP_DISPLAY, EMPTY_OP_SUMMARY, summarizeOps, formatOpSummary } from './opSummary.js';
 
+/**
+ * @typedef {{ sha?: string, lamport?: number, writerId?: string, opSummary?: Record<string, number>, ops?: Array<{ type: string }> }} PatchEntry
+ */
+
 // Default pagination settings
 const DEFAULT_PAGE_SIZE = 20;
 
 /**
  * Ensures entry has an opSummary, computing one if needed.
- * @param {Object} entry - Patch entry
- * @returns {Object} Operation summary
+ * @param {PatchEntry} entry - Patch entry
+ * @returns {Record<string, number>} Operation summary
  */
 function ensureOpSummary(entry) {
   if (entry.opSummary) {
@@ -29,10 +33,10 @@ function ensureOpSummary(entry) {
 
 /**
  * Paginates entries, returning display entries and truncation info.
- * @param {Object[]} entries - All entries
+ * @param {PatchEntry[]} entries - All entries
  * @param {number} pageSize - Page size
  * @param {boolean} showAll - Whether to show all
- * @returns {{displayEntries: Object[], truncated: boolean, hiddenCount: number}}
+ * @returns {{displayEntries: PatchEntry[], truncated: boolean, hiddenCount: number}}
  */
 function paginateEntries(entries, pageSize, showAll) {
   if (showAll || entries.length <= pageSize) {
@@ -64,17 +68,22 @@ function renderTruncationIndicator(truncated, hiddenCount) {
 /**
  * Renders a single patch entry line.
  * @param {Object} params - Entry parameters
+ * @param {PatchEntry} params.entry - Patch entry
+ * @param {boolean} params.isLast - Whether this is the last entry
+ * @param {number} params.lamportWidth - Width for lamport timestamp padding
+ * @param {string} [params.writerStr] - Writer string
+ * @param {number} [params.maxWriterIdLen] - Max writer ID length for padding
  * @returns {string} Formatted entry line
  */
 function renderEntryLine({ entry, isLast, lamportWidth, writerStr, maxWriterIdLen }) {
   const connector = isLast ? TIMELINE.end : TIMELINE.connector;
   const shortSha = (entry.sha || '').slice(0, 7);
-  const lamportStr = padLeft(String(entry.lamport), lamportWidth);
+  const lamportStr = padLeft(String(entry.lamport ?? 0), lamportWidth);
   const opSummary = ensureOpSummary(entry);
   const opSummaryStr = formatOpSummary(opSummary, writerStr ? 30 : 40);
 
   if (writerStr) {
-    const paddedWriter = padRight(writerStr, maxWriterIdLen);
+    const paddedWriter = padRight(writerStr, maxWriterIdLen ?? 6);
     return `  ${connector}${TIMELINE.dot} ${colors.muted(`L${lamportStr}`)} ${colors.primary(paddedWriter)}:${colors.muted(shortSha)} ${opSummaryStr}`;
   }
   return `  ${connector}${TIMELINE.dot} ${colors.muted(`L${lamportStr}`)} ${colors.primary(shortSha)}  ${opSummaryStr}`;
@@ -101,8 +110,8 @@ function renderSingleWriterFooter(totalCount) {
 
 /**
  * Renders single-writer timeline view.
- * @param {Object} payload - History payload
- * @param {Object} options - Rendering options
+ * @param {{ entries: PatchEntry[], writer: string }} payload - History payload
+ * @param {{ pageSize?: number, showAll?: boolean }} options - Rendering options
  * @returns {string[]} Lines for the timeline
  */
 function renderSingleWriterTimeline(payload, options) {
@@ -121,7 +130,7 @@ function renderSingleWriterTimeline(payload, options) {
     lines.push(colors.muted('  (no patches)'));
     return lines;
   }
-  const maxLamport = Math.max(...displayEntries.map((e) => e.lamport));
+  const maxLamport = Math.max(...displayEntries.map((e) => e.lamport ?? 0));
   const lamportWidth = String(maxLamport).length;
 
   lines.push(...renderTruncationIndicator(truncated, hiddenCount));
@@ -137,8 +146,8 @@ function renderSingleWriterTimeline(payload, options) {
 
 /**
  * Merges and sorts entries from all writers by lamport timestamp.
- * @param {Object} writers - Map of writerId to entries
- * @returns {Object[]} Sorted entries with writerId attached
+ * @param {Record<string, PatchEntry[]>} writers - Map of writerId to entries
+ * @returns {PatchEntry[]} Sorted entries with writerId attached
  */
 function mergeWriterEntries(writers) {
   const allEntries = [];
@@ -147,7 +156,7 @@ function mergeWriterEntries(writers) {
       allEntries.push({ ...entry, writerId });
     }
   }
-  allEntries.sort((a, b) => a.lamport - b.lamport || a.writerId.localeCompare(b.writerId));
+  allEntries.sort((a, b) => (a.lamport ?? 0) - (b.lamport ?? 0) || (a.writerId ?? '').localeCompare(b.writerId ?? ''));
   return allEntries;
 }
 
@@ -178,8 +187,8 @@ function renderMultiWriterFooter(totalCount, writerCount) {
 
 /**
  * Renders multi-writer timeline view with parallel columns.
- * @param {Object} payload - History payload with allWriters data
- * @param {Object} options - Rendering options
+ * @param {{ writers: Record<string, PatchEntry[]>, graph: string }} payload - History payload with allWriters data
+ * @param {{ pageSize?: number, showAll?: boolean }} options - Rendering options
  * @returns {string[]} Lines for the timeline
  */
 function renderMultiWriterTimeline(payload, options) {
@@ -206,7 +215,7 @@ function renderMultiWriterTimeline(payload, options) {
     lines.push(colors.muted('  (no patches)'));
     return lines;
   }
-  const maxLamport = Math.max(...displayEntries.map((e) => e.lamport));
+  const maxLamport = Math.max(...displayEntries.map((e) => e.lamport ?? 0));
   const lamportWidth = String(maxLamport).length;
   const maxWriterIdLen = Math.max(...writerIds.map((id) => id.length), 6);
 
@@ -230,15 +239,8 @@ function renderMultiWriterTimeline(payload, options) {
 
 /**
  * Renders the history view with ASCII timeline.
- * @param {Object} payload - History payload from handleHistory
- * @param {string} payload.graph - Graph name
- * @param {string} [payload.writer] - Writer ID (single writer mode)
- * @param {string|null} [payload.nodeFilter] - Node filter if applied
- * @param {Object[]} [payload.entries] - Array of patch entries (single writer mode)
- * @param {Object} [payload.writers] - Map of writerId to entries (multi-writer mode)
- * @param {Object} [options] - Rendering options
- * @param {number} [options.pageSize=20] - Number of patches to show per page
- * @param {boolean} [options.showAll=false] - Show all patches (no pagination)
+ * @param {{ graph: string, writer?: string, nodeFilter?: string | null, entries?: PatchEntry[], writers?: Record<string, PatchEntry[]> }} payload - History payload from handleHistory
+ * @param {{ pageSize?: number, showAll?: boolean }} [options] - Rendering options
  * @returns {string} Formatted ASCII output
  */
 export function renderHistoryView(payload, options = {}) {
@@ -248,8 +250,8 @@ export function renderHistoryView(payload, options = {}) {
 
   const isMultiWriter = payload.writers && typeof payload.writers === 'object';
   const contentLines = isMultiWriter
-    ? renderMultiWriterTimeline(payload, options)
-    : renderSingleWriterTimeline(payload, options);
+    ? renderMultiWriterTimeline(/** @type {{ writers: Record<string, PatchEntry[]>, graph: string }} */ (payload), options)
+    : renderSingleWriterTimeline(/** @type {{ entries: PatchEntry[], writer: string }} */ (payload), options);
 
   // Add node filter indicator if present
   if (payload.nodeFilter) {