@lotics/xlsx 0.1.0

package/src/canvas_renderer.ts

@@ -0,0 +1,1010 @@
+// =============================================================================
+// Canvas Spreadsheet Renderer
+// =============================================================================
+//
+// Draws a spreadsheet onto a CanvasRenderingContext2D:
+// - Grid lines and cell backgrounds
+// - Text content with alignment and overflow
+// - Borders
+// - Column/row headers
+// - Frozen panes
+// - Selection highlight (Phase 6)
+//
+// This module is pure TypeScript with no framework dependency.
+// =============================================================================
+
+import type { LayoutEngine } from "./canvas_layout";
+import { ROW_HEADER_WIDTH, COL_HEADER_HEIGHT } from "./canvas_layout";
+import type { CellStyle, MergedCellRange, ParsedImage, RichTextPart } from "./types";
+import type { CfOverlay } from "./excel_cf_evaluate";
+import type { ParsedChart, ParsedDrawing } from "./ooxml_chart_types";
+import { colNumToLetters, colLettersToNum } from "./excel_utils";
+import { drawCellTextAdvanced } from "./canvas_text";
+import { drawDataBar, drawIcon, getIconOffset } from "./canvas_cf";
+import { drawImages } from "./canvas_images";
+import { drawChart } from "./canvas_chart";
+import { drawDrawing } from "./canvas_shape";
+import { createPatternFill, createGradientFill } from "./canvas_fill";
+import type { SparklineRenderInput } from "./canvas_sparkline";
+import { drawSparkline } from "./canvas_sparkline";
+import type { AutoFilterRange } from "./ooxml_chart_types";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface RenderConfig {
+  layout: LayoutEngine;
+  scrollX: number;
+  scrollY: number;
+  viewWidth: number;
+  viewHeight: number;
+  devicePixelRatio: number;
+  /** Get cell data for rendering. Returns undefined for empty cells. */
+  getCell: (row: number, col: number) => CellRenderData | undefined;
+  /** Merged cell ranges. */
+  mergedCells: MergedCellRange[];
+  /** Frozen pane: { row, col }. */
+  freeze?: { row: number; col: number };
+  /** Whether to show grid lines. */
+  showGridLines: boolean;
+  /** Active selection (row, col) for highlight. */
+  activeCell?: { row: number; col: number };
+  /** Selected range for highlight. */
+  selectionRange?: { startRow: number; startCol: number; endRow: number; endCol: number };
+  /** Conditional formatting overlays keyed by "row:col". */
+  cfOverlays?: Map<string, CfOverlay>;
+  /** Embedded images. */
+  images?: ParsedImage[];
+  /** Parsed charts. */
+  charts?: ParsedChart[];
+  /** Parsed drawings (shapes, text boxes, connectors). */
+  drawings?: ParsedDrawing[];
+  /** Resolve rich text parts for a cell. */
+  richText?: (row: number, col: number) => RichTextPart[] | undefined;
+  /** Fill drag target range (dashed border). */
+  fillTarget?: { startRow: number; startCol: number; endRow: number; endCol: number };
+  /** Sparklines keyed by "row:col". */
+  sparklines?: Map<string, SparklineRenderInput>;
+  /** Auto-filter range (for dropdown arrows on header cells). */
+  autoFilter?: AutoFilterRange;
+  /** Row outline levels (grouping). Key = row number, value = level 1-8. */
+  rowOutlineLevels?: Map<number, number>;
+  /** Column outline levels (grouping). Key = col number, value = level 1-8. */
+  colOutlineLevels?: Map<number, number>;
+  /** Collapsed outline groups. Set of "row:endRow:level" or "col:endCol:level" strings. */
+  collapsedGroups?: Set<string>;
+  /** Row page break positions (row numbers where breaks occur). */
+  rowPageBreaks?: number[];
+  /** Column page break positions (col numbers where breaks occur). */
+  colPageBreaks?: number[];
+  /** Cut source range — drawn with marching ants until paste or Escape. */
+  cutRange?: { startRow: number; startCol: number; endRow: number; endCol: number };
+  /** Phase offset for marching-ants animation (0..7 cycles the dash). */
+  cutDashOffset?: number;
+}
+
+export interface CellRenderData {
+  displayValue: string;
+  style: CellStyle;
+  richText?: RichTextPart[];
+  isHyperlink?: boolean;
+}
+
+// =============================================================================
+// Colors
+// =============================================================================
+
+const GRID_COLOR = "#E2E8F0";
+const HEADER_BG = "#F8FAFC";
+const HEADER_BORDER = "#CBD5E1";
+const HEADER_TEXT = "#475569";
+const FROZEN_SEPARATOR = "#94A3B8";
+// Excel/Sheets-style green for the active cell border. Stronger than the prior
+// blue and visually distinct from the lighter blue selection range fill.
+const SELECTION_BORDER = "#137333";
+const SELECTION_FILL = "rgba(37, 99, 235, 0.08)";
+const HEADER_FONT = "12px -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif";
+const OUTLINE_BTN_SIZE = 12;
+const OUTLINE_LEVEL_STEP = 14;
+const OUTLINE_BTN_BG = "#F1F5F9";
+const OUTLINE_BTN_BORDER = "#94A3B8";
+const OUTLINE_BTN_TEXT = "#475569";
+const OUTLINE_BTN_FONT = "bold 10px -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif";
+
+// =============================================================================
+// Main draw function
+// =============================================================================
+
+export function drawSpreadsheet(
+  ctx: CanvasRenderingContext2D,
+  config: RenderConfig,
+): void {
+  const { layout, scrollX, scrollY, viewWidth, viewHeight, devicePixelRatio: dpr } = config;
+  const freezeRow = config.freeze?.row ?? 0;
+  const freezeCol = config.freeze?.col ?? 0;
+
+  // Set up canvas scaling for HiDPI
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+
+  // Clear
+  ctx.fillStyle = "#FFFFFF";
+  ctx.fillRect(0, 0, viewWidth, viewHeight);
+
+  // Compute visible range
+  const visible = layout.getVisibleRange(scrollX, scrollY, viewWidth, viewHeight);
+
+  // Build merge map for fast lookup
+  const mergeMap = buildMergeMap(config.mergedCells);
+
+  // Draw cells in 4 quadrants (for frozen panes):
+  // Q1: frozen rows + frozen cols (top-left)
+  // Q2: frozen rows + scrollable cols (top)
+  // Q3: scrollable rows + frozen cols (left)
+  // Q4: scrollable rows + scrollable cols (main)
+
+  // Q4: Main scrollable area
+  ctx.save();
+  ctx.beginPath();
+  ctx.rect(
+    ROW_HEADER_WIDTH + layout.frozenWidth,
+    COL_HEADER_HEIGHT + layout.frozenHeight,
+    viewWidth - ROW_HEADER_WIDTH - layout.frozenWidth,
+    viewHeight - COL_HEADER_HEIGHT - layout.frozenHeight,
+  );
+  ctx.clip();
+  drawCells(ctx, config, visible.startRow, visible.endRow, visible.startCol, visible.endCol, scrollX, scrollY, mergeMap);
+  ctx.restore();
+
+  // Q2: Frozen rows, scrollable cols
+  if (freezeRow > 0) {
+    ctx.save();
+    ctx.beginPath();
+    ctx.rect(
+      ROW_HEADER_WIDTH + layout.frozenWidth,
+      COL_HEADER_HEIGHT,
+      viewWidth - ROW_HEADER_WIDTH - layout.frozenWidth,
+      layout.frozenHeight,
+    );
+    ctx.clip();
+    drawCells(ctx, config, 1, freezeRow, visible.startCol, visible.endCol, scrollX, 0, mergeMap);
+    ctx.restore();
+  }
+
+  // Q3: Scrollable rows, frozen cols
+  if (freezeCol > 0) {
+    ctx.save();
+    ctx.beginPath();
+    ctx.rect(
+      ROW_HEADER_WIDTH,
+      COL_HEADER_HEIGHT + layout.frozenHeight,
+      layout.frozenWidth,
+      viewHeight - COL_HEADER_HEIGHT - layout.frozenHeight,
+    );
+    ctx.clip();
+    drawCells(ctx, config, visible.startRow, visible.endRow, 1, freezeCol, 0, scrollY, mergeMap);
+    ctx.restore();
+  }
+
+  // Q1: Frozen rows + frozen cols
+  if (freezeRow > 0 && freezeCol > 0) {
+    ctx.save();
+    ctx.beginPath();
+    ctx.rect(ROW_HEADER_WIDTH, COL_HEADER_HEIGHT, layout.frozenWidth, layout.frozenHeight);
+    ctx.clip();
+    drawCells(ctx, config, 1, freezeRow, 1, freezeCol, 0, 0, mergeMap);
+    ctx.restore();
+  }
+
+  // Draw images, charts, and drawings
+  if (config.images) drawImages(ctx, config.images, layout, scrollX, scrollY, viewWidth, viewHeight);
+  if (config.charts) {
+    for (const chart of config.charts) drawChart(ctx, chart, layout, scrollX, scrollY);
+  }
+  if (config.drawings) {
+    for (const d of config.drawings) drawDrawing(ctx, d, layout, scrollX, scrollY);
+  }
+
+  // Draw frozen pane separators
+  if (freezeRow > 0) {
+    ctx.strokeStyle = FROZEN_SEPARATOR;
+    ctx.lineWidth = 2;
+    ctx.beginPath();
+    ctx.moveTo(0, COL_HEADER_HEIGHT + layout.frozenHeight);
+    ctx.lineTo(viewWidth, COL_HEADER_HEIGHT + layout.frozenHeight);
+    ctx.stroke();
+  }
+  if (freezeCol > 0) {
+    ctx.strokeStyle = FROZEN_SEPARATOR;
+    ctx.lineWidth = 2;
+    ctx.beginPath();
+    ctx.moveTo(ROW_HEADER_WIDTH + layout.frozenWidth, 0);
+    ctx.lineTo(ROW_HEADER_WIDTH + layout.frozenWidth, viewHeight);
+    ctx.stroke();
+  }
+
+  // Draw selection highlight
+  if (config.selectionRange) {
+    drawSelection(ctx, config, config.selectionRange, scrollX, scrollY);
+  }
+  if (config.activeCell) {
+    drawActiveCell(ctx, config, config.activeCell, scrollX, scrollY);
+  }
+  // Marching-ants cut border — drawn last so it sits on top of cell content
+  // and selection fill but under modal overlays.
+  if (config.cutRange) {
+    drawCutBorder(ctx, config, config.cutRange, scrollX, scrollY, config.cutDashOffset ?? 0);
+  }
+  if (config.fillTarget) {
+    drawFillTarget(ctx, config, config.fillTarget, scrollX, scrollY);
+  }
+
+  // Draw page break indicators (dashed lines)
+  if (config.rowPageBreaks || config.colPageBreaks) {
+    drawPageBreaks(ctx, config, scrollX, scrollY);
+  }
+
+  // Draw auto-filter dropdown arrows on cells
+  if (config.autoFilter) {
+    drawAutoFilterArrows(ctx, config, config.autoFilter, scrollX, scrollY);
+  }
+
+  // Draw headers on top
+  drawColumnHeaders(ctx, config, visible, scrollX);
+  drawRowHeaders(ctx, config, visible, scrollY);
+  drawCornerCell(ctx);
+
+  // Draw outline grouping buttons over headers
+  if (config.rowOutlineLevels && config.rowOutlineLevels.size > 0) {
+    drawRowOutlineButtons(ctx, config, visible, scrollY);
+  }
+  if (config.colOutlineLevels && config.colOutlineLevels.size > 0) {
+    drawColOutlineButtons(ctx, config, visible, scrollX);
+  }
+}
+
+// =============================================================================
+// Cell drawing
+// =============================================================================
+
+function drawCells(
+  ctx: CanvasRenderingContext2D,
+  config: RenderConfig,
+  startRow: number,
+  endRow: number,
+  startCol: number,
+  endCol: number,
+  offsetX: number,
+  offsetY: number,
+  mergeMap: Map<number, MergedCellRange>,
+): void {
+  const { layout, showGridLines } = config;
+
+  for (let r = startRow; r <= endRow; r++) {
+    for (let c = startCol; c <= endCol; c++) {
+      // Check if this cell is part of a merge (and not the top-left)
+      const mergeKey = r * 100000 + c;
+      const merge = mergeMap.get(mergeKey);
+      if (merge && (merge.startRow !== r || merge.startCol !== c)) continue;
+
+      const cellX = layout.colX[c] - offsetX;
+      const cellY = layout.rowY[r] - offsetY;
+      let cellW = layout.colW[c];
+      let cellH = layout.rowH[r];
+
+      // Expand for merged cells
+      if (merge) {
+        cellW = 0;
+        for (let mc = merge.startCol; mc <= merge.endCol; mc++) cellW += layout.colW[mc];
+        cellH = 0;
+        for (let mr = merge.startRow; mr <= merge.endRow; mr++) cellH += layout.rowH[mr];
+      }
+
+      if (cellW === 0 || cellH === 0) continue;
+
+      const cellData = config.getCell(r, c);
+
+      // Background — gradient, pattern, or solid color
+      const gradData = cellData?.style.gradientData;
+      if (gradData) {
+        ctx.fillStyle = createGradientFill(ctx, gradData, cellX, cellY, cellW, cellH);
+        ctx.fillRect(cellX, cellY, cellW, cellH);
+      } else if (cellData?.style.backgroundPattern) {
+        const pattern = createPatternFill(ctx, cellData.style.backgroundPattern, cellData.style.patternType);
+        if (pattern) {
+          ctx.fillStyle = pattern;
+          ctx.fillRect(cellX, cellY, cellW, cellH);
+        }
+      } else if (cellData?.style.backgroundGradient) {
+        // CSS gradient string — parse as simple linear for canvas
+        ctx.fillStyle = "#F0F0F0";
+        ctx.fillRect(cellX, cellY, cellW, cellH);
+      }
+      const bg = cellData?.style.backgroundColor;
+      if (bg && !gradData && !cellData?.style.backgroundPattern) {
+        ctx.fillStyle = bg;
+        ctx.fillRect(cellX, cellY, cellW, cellH);
+      }
+
+      // Grid lines
+      if (showGridLines) {
+        ctx.strokeStyle = GRID_COLOR;
+        ctx.lineWidth = 0.5;
+        ctx.strokeRect(cellX, cellY, cellW, cellH);
+      }
+
+      // Borders (override grid lines)
+      if (cellData?.style) {
+        drawBorders(ctx, cellData.style, cellX, cellY, cellW, cellH);
+      }
+
+      // Conditional formatting overlays
+      const overlay = config.cfOverlays?.get(r + ":" + c);
+      if (overlay?.backgroundColor) {
+        ctx.fillStyle = overlay.backgroundColor;
+        ctx.fillRect(cellX, cellY, cellW, cellH);
+      }
+      if (overlay?.dataBarWidth !== undefined) {
+        drawDataBar(ctx, overlay, cellX, cellY, cellW, cellH);
+      }
+      if (overlay?.iconSvg) {
+        drawIcon(ctx, overlay, cellX, cellY, cellH);
+      }
+
+      // Text
+      if (cellData && cellData.displayValue) {
+        const iconOff = getIconOffset(overlay, cellH);
+        const rt = cellData.richText ?? config.richText?.(r, c);
+
+        // Hyperlink styling: blue text + underline unless explicit font color is set
+        let textStyle = cellData.style;
+        if (cellData.isHyperlink && !cellData.style.fontColor) {
+          textStyle = { ...cellData.style, fontColor: "#0563C1", fontUnderline: cellData.style.fontUnderline ?? "single" };
+        }
+
+        drawCellTextAdvanced(ctx, {
+          text: cellData.displayValue,
+          richText: rt,
+          style: textStyle,
+          cellX: cellX + iconOff,
+          cellY,
+          cellW: cellW - iconOff,
+          cellH,
+        });
+      }
+
+      // Sparkline
+      const sparkline = config.sparklines?.get(`${r}:${c}`);
+      if (sparkline) {
+        drawSparkline(ctx, { ...sparkline, x: cellX, y: cellY, w: cellW, h: cellH });
+      }
+
+    }
+  }
+}
+
+function drawBorders(
+  ctx: CanvasRenderingContext2D,
+  style: CellStyle,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): void {
+  const drawBorder = (
+    x1: number, y1: number,
+    x2: number, y2: number,
+    border: { width: number; style: string; color?: string },
+  ) => {
+    ctx.strokeStyle = border.color ?? "#000000";
+    ctx.lineWidth = border.width;
+    if (border.style === "dashed") ctx.setLineDash([4, 2]);
+    else if (border.style === "dotted") ctx.setLineDash([1, 1]);
+    else ctx.setLineDash([]);
+    ctx.beginPath();
+    ctx.moveTo(x1, y1);
+    ctx.lineTo(x2, y2);
+    ctx.stroke();
+    ctx.setLineDash([]);
+  };
+
+  if (style.borderTop) drawBorder(x, y, x + w, y, style.borderTop);
+  if (style.borderBottom) drawBorder(x, y + h, x + w, y + h, style.borderBottom);
+  if (style.borderLeft) drawBorder(x, y, x, y + h, style.borderLeft);
+  if (style.borderRight) drawBorder(x + w, y, x + w, y + h, style.borderRight);
+  if (style.borderDiagonal) {
+    if (style.diagonalDown) drawBorder(x, y, x + w, y + h, style.borderDiagonal);
+    if (style.diagonalUp) drawBorder(x, y + h, x + w, y, style.borderDiagonal);
+  }
+}
+
+// =============================================================================
+// Headers
+// =============================================================================
+
+function drawColumnHeaders(
+  ctx: CanvasRenderingContext2D,
+  config: RenderConfig,
+  visible: { startCol: number; endCol: number },
+  scrollX: number,
+): void {
+  const { layout } = config;
+  const freezeCol = config.freeze?.col ?? 0;
+
+  // Header background
+  ctx.fillStyle = HEADER_BG;
+  ctx.fillRect(0, 0, config.viewWidth, COL_HEADER_HEIGHT);
+  ctx.strokeStyle = HEADER_BORDER;
+  ctx.lineWidth = 1;
+  ctx.beginPath();
+  ctx.moveTo(0, COL_HEADER_HEIGHT - 0.5);
+  ctx.lineTo(config.viewWidth, COL_HEADER_HEIGHT - 0.5);
+  ctx.stroke();
+
+  ctx.font = HEADER_FONT;
+  ctx.fillStyle = HEADER_TEXT;
+  ctx.textAlign = "center";
+  ctx.textBaseline = "middle";
+
+  // Frozen columns
+  for (let c = 1; c <= freezeCol; c++) {
+    const x = layout.colX[c];
+    const w = layout.colW[c];
+    if (w === 0) continue;
+    ctx.fillStyle = HEADER_BG;
+    ctx.fillRect(x, 0, w, COL_HEADER_HEIGHT);
+    ctx.strokeStyle = HEADER_BORDER;
+    ctx.strokeRect(x, 0, w, COL_HEADER_HEIGHT);
+    ctx.fillStyle = HEADER_TEXT;
+    ctx.fillText(colNumToLetters(c), x + w / 2, COL_HEADER_HEIGHT / 2);
+  }
+
+  // Scrollable columns
+  for (let c = visible.startCol; c <= visible.endCol; c++) {
+    const x = layout.colX[c] - scrollX;
+    const w = layout.colW[c];
+    if (w === 0) continue;
+    ctx.fillStyle = HEADER_BG;
+    ctx.fillRect(x, 0, w, COL_HEADER_HEIGHT);
+    ctx.strokeStyle = HEADER_BORDER;
+    ctx.strokeRect(x, 0, w, COL_HEADER_HEIGHT);
+    ctx.fillStyle = HEADER_TEXT;
+    ctx.fillText(colNumToLetters(c), x + w / 2, COL_HEADER_HEIGHT / 2);
+  }
+}
+
+function drawRowHeaders(
+  ctx: CanvasRenderingContext2D,
+  config: RenderConfig,
+  visible: { startRow: number; endRow: number },
+  scrollY: number,
+): void {
+  const { layout } = config;
+  const freezeRow = config.freeze?.row ?? 0;
+
+  // Header background
+  ctx.fillStyle = HEADER_BG;
+  ctx.fillRect(0, 0, ROW_HEADER_WIDTH, config.viewHeight);
+  ctx.strokeStyle = HEADER_BORDER;
+  ctx.lineWidth = 1;
+  ctx.beginPath();
+  ctx.moveTo(ROW_HEADER_WIDTH - 0.5, 0);
+  ctx.lineTo(ROW_HEADER_WIDTH - 0.5, config.viewHeight);
+  ctx.stroke();
+
+  ctx.font = HEADER_FONT;
+  ctx.fillStyle = HEADER_TEXT;
+  ctx.textAlign = "center";
+  ctx.textBaseline = "middle";
+
+  // Frozen rows
+  for (let r = 1; r <= freezeRow; r++) {
+    const y = layout.rowY[r];
+    const h = layout.rowH[r];
+    if (h === 0) continue;
+    ctx.fillStyle = HEADER_BG;
+    ctx.fillRect(0, y, ROW_HEADER_WIDTH, h);
+    ctx.strokeStyle = HEADER_BORDER;
+    ctx.strokeRect(0, y, ROW_HEADER_WIDTH, h);
+    ctx.fillStyle = HEADER_TEXT;
+    ctx.fillText(String(r), ROW_HEADER_WIDTH / 2, y + h / 2);
+  }
+
+  // Scrollable rows
+  for (let r = visible.startRow; r <= visible.endRow; r++) {
+    const y = layout.rowY[r] - scrollY;
+    const h = layout.rowH[r];
+    if (h === 0) continue;
+    ctx.fillStyle = HEADER_BG;
+    ctx.fillRect(0, y, ROW_HEADER_WIDTH, h);
+    ctx.strokeStyle = HEADER_BORDER;
+    ctx.strokeRect(0, y, ROW_HEADER_WIDTH, h);
+    ctx.fillStyle = HEADER_TEXT;
+    ctx.fillText(String(r), ROW_HEADER_WIDTH / 2, y + h / 2);
+  }
+}
+
+function drawCornerCell(ctx: CanvasRenderingContext2D): void {
+  ctx.fillStyle = HEADER_BG;
+  ctx.fillRect(0, 0, ROW_HEADER_WIDTH, COL_HEADER_HEIGHT);
+  ctx.strokeStyle = HEADER_BORDER;
+  ctx.strokeRect(0, 0, ROW_HEADER_WIDTH, COL_HEADER_HEIGHT);
+}
+
+// =============================================================================
+// Selection
+// =============================================================================
+
+function drawSelection(
+  ctx: CanvasRenderingContext2D,
+  config: RenderConfig,
+  range: { startRow: number; startCol: number; endRow: number; endCol: number },
+  scrollX: number,
+  scrollY: number,
+): void {
+  const { layout } = config;
+  const x = layout.colX[range.startCol] - scrollX;
+  const y = layout.rowY[range.startRow] - scrollY;
+  let w = 0;
+  for (let c = range.startCol; c <= range.endCol; c++) w += layout.colW[c];
+  let h = 0;
+  for (let r = range.startRow; r <= range.endRow; r++) h += layout.rowH[r];
+
+  ctx.fillStyle = SELECTION_FILL;
+  ctx.fillRect(x, y, w, h);
+}
+
+// Larger fill handle (8x8) with a white border so it reads on busy
+// backgrounds — matches Excel's bottom-right corner affordance.
+const FILL_HANDLE_SIZE = 8;
+
+function drawActiveCell(
+  ctx: CanvasRenderingContext2D,
+  config: RenderConfig,
+  cell: { row: number; col: number },
+  scrollX: number,
+  scrollY: number,
+): void {
+  const { layout } = config;
+  const x = layout.colX[cell.col] - scrollX;
+  const y = layout.rowY[cell.row] - scrollY;
+  const w = layout.colW[cell.col];
+  const h = layout.rowH[cell.row];
+
+  // Active cell: 2.5px solid green border, drawn inset by half-width so it
+  // doesn't bleed into adjacent cell text.
+  ctx.strokeStyle = SELECTION_BORDER;
+  ctx.lineWidth = 2.5;
+  ctx.strokeRect(x + 0.5, y + 0.5, w - 1, h - 1);
+
+  // Fill handle: white-bordered green square at bottom-right corner of the
+  // selection range (or the active cell itself if no range).
+  const range = config.selectionRange;
+  const fhX = range
+    ? layout.colX[range.endCol] - scrollX + layout.colW[range.endCol]
+    : x + w;
+  const fhY = range
+    ? layout.rowY[range.endRow] - scrollY + layout.rowH[range.endRow]
+    : y + h;
+  const hx = fhX - FILL_HANDLE_SIZE / 2 - 1;
+  const hy = fhY - FILL_HANDLE_SIZE / 2 - 1;
+  // White outer ring
+  ctx.fillStyle = "#FFFFFF";
+  ctx.fillRect(hx - 1, hy - 1, FILL_HANDLE_SIZE + 2, FILL_HANDLE_SIZE + 2);
+  // Green core
+  ctx.fillStyle = SELECTION_BORDER;
+  ctx.fillRect(hx, hy, FILL_HANDLE_SIZE, FILL_HANDLE_SIZE);
+}
+
+/**
+ * Marching-ants border for the cut source. The dash phase shifts each frame
+ * (driven by config.cutDashOffset incremented at ~30fps in the React layer)
+ * so the dashes appear to march around the perimeter — Excel's classic
+ * "you cut these cells" indicator.
+ */
+function drawCutBorder(
+  ctx: CanvasRenderingContext2D,
+  config: RenderConfig,
+  range: { startRow: number; startCol: number; endRow: number; endCol: number },
+  scrollX: number,
+  scrollY: number,
+  dashOffset: number,
+): void {
+  const { layout } = config;
+  const x = layout.colX[range.startCol] - scrollX;
+  const y = layout.rowY[range.startRow] - scrollY;
+  let w = 0;
+  for (let c = range.startCol; c <= range.endCol; c++) w += layout.colW[c];
+  let h = 0;
+  for (let r = range.startRow; r <= range.endRow; r++) h += layout.rowH[r];
+
+  ctx.save();
+  ctx.strokeStyle = "#137333";
+  ctx.lineWidth = 1.5;
+  ctx.setLineDash([5, 3]);
+  ctx.lineDashOffset = -dashOffset;
+  ctx.strokeRect(x + 0.5, y + 0.5, w - 1, h - 1);
+  ctx.restore();
+}
+
+function drawFillTarget(
+  ctx: CanvasRenderingContext2D,
+  config: RenderConfig,
+  range: { startRow: number; startCol: number; endRow: number; endCol: number },
+  scrollX: number,
+  scrollY: number,
+): void {
+  const { layout } = config;
+  const x = layout.colX[range.startCol] - scrollX;
+  const y = layout.rowY[range.startRow] - scrollY;
+  let w = 0;
+  for (let c = range.startCol; c <= range.endCol; c++) w += layout.colW[c];
+  let h = 0;
+  for (let r = range.startRow; r <= range.endRow; r++) h += layout.rowH[r];
+
+  ctx.strokeStyle = SELECTION_BORDER;
+  ctx.lineWidth = 1;
+  ctx.setLineDash([4, 3]);
+  ctx.strokeRect(x, y, w, h);
+  ctx.setLineDash([]);
+}
+
+// =============================================================================
+// Auto-filter arrows
+// =============================================================================
+
+function drawAutoFilterArrows(
+  ctx: CanvasRenderingContext2D,
+  config: RenderConfig,
+  autoFilter: AutoFilterRange,
+  scrollX: number,
+  scrollY: number,
+): void {
+  const { layout } = config;
+  const match = autoFilter.ref.match(/^([A-Z]+)(\d+):([A-Z]+)(\d+)$/);
+  if (!match) return;
+
+  const startCol = colLettersToNum(match[1]);
+  const row = parseInt(match[2], 10);
+  const endCol = colLettersToNum(match[3]);
+
+  for (let c = startCol; c <= endCol; c++) {
+    const x = (layout.colX[c] ?? 0) - scrollX;
+    const y = (layout.rowY[row] ?? 0) - scrollY;
+    const w = layout.colW[c] ?? 0;
+    const h = layout.rowH[row] ?? 0;
+
+    if (w === 0 || h === 0) continue;
+
+    // Draw small dropdown triangle in bottom-right corner
+    const arrowSize = 5;
+    const ax = x + w - arrowSize - 3;
+    const ay = y + h - arrowSize - 2;
+
+    ctx.fillStyle = "#6B7280";
+    ctx.beginPath();
+    ctx.moveTo(ax, ay);
+    ctx.lineTo(ax + arrowSize * 2, ay);
+    ctx.lineTo(ax + arrowSize, ay + arrowSize);
+    ctx.closePath();
+    ctx.fill();
+  }
+}
+
+// =============================================================================
+// Page break indicators
+// =============================================================================
+
+const PAGE_BREAK_COLOR = "#94A3B8";
+const PAGE_BREAK_DASH = [6, 3];
+
+function drawPageBreaks(
+  ctx: CanvasRenderingContext2D,
+  config: RenderConfig,
+  scrollX: number,
+  scrollY: number,
+): void {
+  const { layout, viewWidth, viewHeight } = config;
+
+  ctx.strokeStyle = PAGE_BREAK_COLOR;
+  ctx.lineWidth = 1;
+  ctx.setLineDash(PAGE_BREAK_DASH);
+
+  // Row page breaks — horizontal dashed lines
+  if (config.rowPageBreaks) {
+    for (const row of config.rowPageBreaks) {
+      if (row >= layout.rowY.length) continue;
+      const y = layout.rowY[row] - scrollY;
+      if (y < COL_HEADER_HEIGHT || y > viewHeight) continue;
+      ctx.beginPath();
+      ctx.moveTo(ROW_HEADER_WIDTH, y);
+      ctx.lineTo(viewWidth, y);
+      ctx.stroke();
+    }
+  }
+
+  // Column page breaks — vertical dashed lines
+  if (config.colPageBreaks) {
+    for (const col of config.colPageBreaks) {
+      if (col >= layout.colX.length) continue;
+      const x = layout.colX[col] - scrollX;
+      if (x < ROW_HEADER_WIDTH || x > viewWidth) continue;
+      ctx.beginPath();
+      ctx.moveTo(x, COL_HEADER_HEIGHT);
+      ctx.lineTo(x, viewHeight);
+      ctx.stroke();
+    }
+  }
+
+  ctx.setLineDash([]);
+}
+
+// =============================================================================
+// Outline grouping buttons
+// =============================================================================
+
+/** Describes a group boundary where a +/- button should appear. */
+export interface OutlineGroupBoundary {
+  /** "row" or "col" */
+  axis: "row" | "col";
+  /** The row/col number where the group ends (last row/col at this level). */
+  endIndex: number;
+  /** The outline level (1-8). */
+  level: number;
+  /** The first row/col in this group. */
+  startIndex: number;
+}
+
+/**
+ * Find all outline group boundaries for a given axis.
+ * A boundary occurs at the last row/col of a contiguous run at a given level.
+ */
+function findGroupBoundaries(
+  outlineLevels: Map<number, number>,
+  maxIndex: number,
+): OutlineGroupBoundary[] {
+  if (outlineLevels.size === 0) return [];
+
+  const boundaries: OutlineGroupBoundary[] = [];
+  // Determine max level
+  let maxLevel = 0;
+  for (const lvl of outlineLevels.values()) {
+    if (lvl > maxLevel) maxLevel = lvl;
+  }
+
+  // For each level, find contiguous runs
+  for (let level = 1; level <= maxLevel; level++) {
+    let groupStart = -1;
+    for (let i = 1; i <= maxIndex; i++) {
+      const lvl = outlineLevels.get(i) ?? 0;
+      if (lvl >= level) {
+        if (groupStart === -1) groupStart = i;
+      } else {
+        if (groupStart !== -1) {
+          boundaries.push({ axis: "row", endIndex: i - 1, level, startIndex: groupStart });
+          groupStart = -1;
+        }
+      }
+    }
+    if (groupStart !== -1) {
+      boundaries.push({ axis: "row", endIndex: maxIndex, level, startIndex: groupStart });
+    }
+  }
+
+  return boundaries;
+}
+
+function drawRowOutlineButtons(
+  ctx: CanvasRenderingContext2D,
+  config: RenderConfig,
+  visible: { startRow: number; endRow: number },
+  scrollY: number,
+): void {
+  const { layout } = config;
+  const levels = config.rowOutlineLevels!;
+  const collapsed = config.collapsedGroups ?? new Set<string>();
+  const freezeRow = config.freeze?.row ?? 0;
+
+  // Find the maximum row we care about
+  const maxRow = Math.max(visible.endRow, freezeRow);
+  const boundaries = findGroupBoundaries(levels, maxRow);
+
+  // Fix axis for row boundaries
+  for (const b of boundaries) b.axis = "row";
+
+  ctx.font = OUTLINE_BTN_FONT;
+  ctx.textAlign = "center";
+  ctx.textBaseline = "middle";
+
+  for (const b of boundaries) {
+    const isCollapsed = collapsed.has(`row:${b.endIndex}:${b.level}`);
+    // Position the button at the end row of the group
+    const endRow = b.endIndex;
+
+    // Determine if this row is visible (frozen or in scrollable range)
+    let btnY: number;
+    if (endRow <= freezeRow) {
+      btnY = layout.rowY[endRow];
+    } else {
+      if (endRow < visible.startRow || endRow > visible.endRow) continue;
+      btnY = layout.rowY[endRow] - scrollY;
+    }
+
+    const rowH = layout.rowH[endRow] ?? 0;
+    if (rowH === 0 && !isCollapsed) continue;
+
+    const x = 2 + (b.level - 1) * OUTLINE_LEVEL_STEP;
+    const y = isCollapsed
+      ? btnY - OUTLINE_BTN_SIZE / 2
+      : btnY + rowH / 2 - OUTLINE_BTN_SIZE / 2;
+
+    // Draw button background
+    ctx.fillStyle = OUTLINE_BTN_BG;
+    ctx.fillRect(x, y, OUTLINE_BTN_SIZE, OUTLINE_BTN_SIZE);
+    ctx.strokeStyle = OUTLINE_BTN_BORDER;
+    ctx.lineWidth = 1;
+    ctx.strokeRect(x, y, OUTLINE_BTN_SIZE, OUTLINE_BTN_SIZE);
+
+    // Draw +/- symbol
+    ctx.fillStyle = OUTLINE_BTN_TEXT;
+    ctx.fillText(
+      isCollapsed ? "+" : "\u2212",
+      x + OUTLINE_BTN_SIZE / 2,
+      y + OUTLINE_BTN_SIZE / 2 + 0.5,
+    );
+  }
+}
+
+function drawColOutlineButtons(
+  ctx: CanvasRenderingContext2D,
+  config: RenderConfig,
+  visible: { startCol: number; endCol: number },
+  scrollX: number,
+): void {
+  const { layout } = config;
+  const levels = config.colOutlineLevels!;
+  const collapsed = config.collapsedGroups ?? new Set<string>();
+  const freezeCol = config.freeze?.col ?? 0;
+
+  const maxCol = Math.max(visible.endCol, freezeCol);
+
+  // Reuse findGroupBoundaries (it uses "row" axis label, we override to "col")
+  const boundaries = findGroupBoundaries(levels, maxCol);
+  for (const b of boundaries) b.axis = "col";
+
+  ctx.font = OUTLINE_BTN_FONT;
+  ctx.textAlign = "center";
+  ctx.textBaseline = "middle";
+
+  for (const b of boundaries) {
+    const isCollapsed = collapsed.has(`col:${b.endIndex}:${b.level}`);
+    const endCol = b.endIndex;
+
+    let btnX: number;
+    if (endCol <= freezeCol) {
+      btnX = layout.colX[endCol];
+    } else {
+      if (endCol < visible.startCol || endCol > visible.endCol) continue;
+      btnX = layout.colX[endCol] - scrollX;
+    }
+
+    const colW = layout.colW[endCol] ?? 0;
+    if (colW === 0 && !isCollapsed) continue;
+
+    const x = isCollapsed
+      ? btnX - OUTLINE_BTN_SIZE / 2
+      : btnX + colW / 2 - OUTLINE_BTN_SIZE / 2;
+    const y = 2 + (b.level - 1) * OUTLINE_LEVEL_STEP;
+
+    ctx.fillStyle = OUTLINE_BTN_BG;
+    ctx.fillRect(x, y, OUTLINE_BTN_SIZE, OUTLINE_BTN_SIZE);
+    ctx.strokeStyle = OUTLINE_BTN_BORDER;
+    ctx.lineWidth = 1;
+    ctx.strokeRect(x, y, OUTLINE_BTN_SIZE, OUTLINE_BTN_SIZE);
+
+    ctx.fillStyle = OUTLINE_BTN_TEXT;
+    ctx.fillText(
+      isCollapsed ? "+" : "\u2212",
+      x + OUTLINE_BTN_SIZE / 2,
+      y + OUTLINE_BTN_SIZE / 2 + 0.5,
+    );
+  }
+}
+
+/**
+ * Hit-test outline buttons. Returns the boundary that was clicked, or undefined.
+ */
+export function hitTestOutlineButton(
+  config: RenderConfig,
+  px: number,
+  py: number,
+  scrollX: number,
+  scrollY: number,
+): OutlineGroupBoundary | undefined {
+  const { layout } = config;
+  const freezeRow = config.freeze?.row ?? 0;
+  const freezeCol = config.freeze?.col ?? 0;
+  const collapsed = config.collapsedGroups ?? new Set<string>();
+
+  // Row outline buttons: check if click is in the row header area (x < ROW_HEADER_WIDTH)
+  if (px < ROW_HEADER_WIDTH && py > COL_HEADER_HEIGHT && config.rowOutlineLevels && config.rowOutlineLevels.size > 0) {
+    const visible = layout.getVisibleRange(scrollX, scrollY, config.viewWidth, config.viewHeight);
+    const maxRow = Math.max(visible.endRow, freezeRow);
+    const boundaries = findGroupBoundaries(config.rowOutlineLevels, maxRow);
+    for (const b of boundaries) {
+      b.axis = "row";
+      const isCollapsed = collapsed.has(`row:${b.endIndex}:${b.level}`);
+      const endRow = b.endIndex;
+
+      let btnY: number;
+      if (endRow <= freezeRow) {
+        btnY = layout.rowY[endRow];
+      } else {
+        if (endRow < visible.startRow || endRow > visible.endRow) continue;
+        btnY = layout.rowY[endRow] - scrollY;
+      }
+
+      const rowH = layout.rowH[endRow] ?? 0;
+      if (rowH === 0 && !isCollapsed) continue;
+
+      const bx = 2 + (b.level - 1) * OUTLINE_LEVEL_STEP;
+      const by = isCollapsed
+        ? btnY - OUTLINE_BTN_SIZE / 2
+        : btnY + rowH / 2 - OUTLINE_BTN_SIZE / 2;
+
+      if (px >= bx && px <= bx + OUTLINE_BTN_SIZE && py >= by && py <= by + OUTLINE_BTN_SIZE) {
+        return b;
+      }
+    }
+  }
+
+  // Column outline buttons: check if click is in the col header area (y < COL_HEADER_HEIGHT)
+  if (py < COL_HEADER_HEIGHT && px > ROW_HEADER_WIDTH && config.colOutlineLevels && config.colOutlineLevels.size > 0) {
+    const visible = layout.getVisibleRange(scrollX, scrollY, config.viewWidth, config.viewHeight);
+    const maxCol = Math.max(visible.endCol, freezeCol);
+    const boundaries = findGroupBoundaries(config.colOutlineLevels, maxCol);
+    for (const b of boundaries) {
+      b.axis = "col";
+      const isCollapsed = collapsed.has(`col:${b.endIndex}:${b.level}`);
+      const endCol = b.endIndex;
+
+      let btnX: number;
+      if (endCol <= freezeCol) {
+        btnX = layout.colX[endCol];
+      } else {
+        if (endCol < visible.startCol || endCol > visible.endCol) continue;
+        btnX = layout.colX[endCol] - scrollX;
+      }
+
+      const colW = layout.colW[endCol] ?? 0;
+      if (colW === 0 && !isCollapsed) continue;
+
+      const bx = isCollapsed
+        ? btnX - OUTLINE_BTN_SIZE / 2
+        : btnX + colW / 2 - OUTLINE_BTN_SIZE / 2;
+      const by = 2 + (b.level - 1) * OUTLINE_LEVEL_STEP;
+
+      if (px >= bx && px <= bx + OUTLINE_BTN_SIZE && py >= by && py <= by + OUTLINE_BTN_SIZE) {
+        return b;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+// =============================================================================
+// Merge map
+// =============================================================================
+
+function buildMergeMap(mergedCells: MergedCellRange[]): Map<number, MergedCellRange> {
+  const map = new Map<number, MergedCellRange>();
+  for (const mc of mergedCells) {
+    for (let r = mc.startRow; r <= mc.endRow; r++) {
+      for (let c = mc.startCol; c <= mc.endCol; c++) {
+        map.set(r * 100000 + c, mc);
+      }
+    }
+  }
+  return map;
+}