codesummary 1.2.1 → 1.2.2

package/src/renderers/llmSummaryRenderer.js

@@ -0,0 +1,14 @@
+import fs from 'fs-extra';
+
+/**
+ * Renderer for structured repository context artifact (.llmsummary.json).
+ */
+export default class LlmSummaryRenderer {
+  async render(outputPath, summaryData) {
+    await fs.writeJson(outputPath, summaryData, { spaces: 2 });
+    return {
+      outputPath
+    };
+  }
+}
+

package/src/renderers/pdfThemeRenderer.js

@@ -0,0 +1,685 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * PDFThemeRenderer
+ * Shared high-end visual primitives for PDFKit reports.
+ */
+export default class PDFThemeRenderer {
+  constructor(options = {}) {
+    const defaultFontsDir = path.resolve(__dirname, '../../fonts');
+    this.fontsDir = options.fontsDir || defaultFontsDir;
+
+    // ── Design tokens ─────────────────────────────────────────────────────── //
+    this.tokens = {
+      // Text hierarchy
+      text:         '#1A202C',
+      textSecond:   '#4A5568',
+      muted:        '#718096',
+      faint:        '#A0AEC0',
+      inverse:      '#FFFFFF',
+
+      // Brand palette — vibrant indigo + cyan
+      primary:      '#5B50F0',
+      primaryDark:  '#4338CA',
+      primaryLight: '#EEF2FF',
+      primaryMid:   '#818CF8',
+      cyan:         '#06B6D4',
+      cyanLight:    '#ECFEFF',
+      green:        '#10B981',
+      greenLight:   '#D1FAE5',
+      orange:       '#F59E0B',
+      orangeLight:  '#FEF3C7',
+      red:          '#EF4444',
+      redLight:     '#FEE2E2',
+      purple:       '#8B5CF6',
+      purpleLight:  '#EDE9FE',
+
+      // Cover page
+      coverBg:      '#0D0F1A',
+      coverBg2:     '#1A0D3D',
+      coverTitle:   '#FFFFFF',
+      coverSub:     '#A5B4FC',
+      coverMuted:   '#4A5568',
+
+      // Surfaces
+      pageBackground:   '#F7F8FC',
+      headerStrip:      '#0D0F1A',
+      headerStripText:  '#94A3B8',
+      cardBackground:   '#FFFFFF',
+      divider:          '#E2E8F0',
+
+      // Code editor (Catppuccin Mocha)
+      codeBg:           '#1E1E2E',
+      codeFg:           '#CDD6F4',
+      codeGutter:       '#313244',
+      codeGutterText:   '#6C7086',
+      codeTabBg:        '#181825',
+      codeTabText:      '#89B4FA',
+      codeBorder:       '#45475A',
+
+      // Tables
+      tableHeaderBg:    '#1E293B',
+      tableHeaderText:  '#F1F5F9',
+      tableStripe:      '#F8FAFC',
+      tableRowBorder:   '#E2E8F0',
+
+      // Callouts
+      calloutInfoBg:     '#EEF2FF',
+      calloutInfoBorder: '#818CF8',
+      calloutRiskBg:     '#FEF2F2',
+      calloutRiskBorder: '#FCA5A5',
+      calloutRiskText:   '#B91C1C',
+      calloutSuccessBg:  '#F0FDF4',
+      calloutSuccessBorder: '#6EE7B7',
+      calloutWarningBg:  '#FFFBEB',
+      calloutWarningBorder: '#FCD34D'
+    };
+
+    this.typeScale = {
+      display: 30,
+      h1:      22,
+      h2:      14,
+      h3:      11.5,
+      body:    10,
+      small:   8.5,
+      micro:   7.5
+    };
+
+    this.fontNames = {
+      regular: 'Inter-Regular',
+      bold:    'Inter-Bold',
+      mono:    'FiraCode'
+    };
+  }
+
+  // ── Font registration ─────────────────────────────────────────────────── //
+
+  applyBaseTheme(doc) {
+    const regular = path.join(this.fontsDir, 'Inter-Regular.ttf');
+    const bold    = path.join(this.fontsDir, 'Inter-Bold.ttf');
+    const mono    = path.join(this.fontsDir, 'FiraCode.ttf');
+
+    const hasRegular = fs.existsSync(regular);
+    const hasBold    = fs.existsSync(bold);
+    const hasMono    = fs.existsSync(mono);
+
+    if (hasRegular) doc.registerFont(this.fontNames.regular, regular);
+    if (hasBold)    doc.registerFont(this.fontNames.bold, bold);
+    if (hasMono)    doc.registerFont(this.fontNames.mono, mono);
+
+    if (!hasRegular) this.fontNames.regular = 'Helvetica';
+    if (!hasBold)    this.fontNames.bold    = 'Helvetica-Bold';
+    if (!hasMono)    this.fontNames.mono    = 'Courier';
+
+    if (!doc.page?.margins) return;
+    doc.font(this.fontNames.regular).fontSize(this.typeScale.body).fillColor(this.tokens.text);
+  }
+
+  // ── Low-level primitives ──────────────────────────────────────────────── //
+
+  /** Subtle horizontal rule. */
+  drawDivider(doc, y = doc.y, color = null) {
+    const left  = doc.page.margins.left;
+    const right = doc.page.width - doc.page.margins.right;
+    doc.save()
+      .moveTo(left, y).lineTo(right, y)
+      .lineWidth(0.4)
+      .strokeColor(color || this.tokens.divider)
+      .stroke()
+      .restore();
+  }
+
+  /** Filled rounded pill. Returns pill width. */
+  drawPill(doc, x, y, label, bgColor, textColor, fontSize = 7) {
+    const padX = 7, padY = 3;
+    doc.font(this.fontNames.bold).fontSize(fontSize);
+    const textW = doc.widthOfString(label);
+    const pillW = textW + padX * 2;
+    const pillH = fontSize + padY * 2;
+    doc.save();
+    doc.roundedRect(x, y, pillW, pillH, pillH / 2);
+    doc.fillColor(bgColor);
+    doc.fill();
+    doc.restore();
+    doc.font(this.fontNames.bold).fontSize(fontSize).fillColor(textColor)
+      .text(label, x + padX, y + padY + 0.5, { lineBreak: false });
+    return pillW;
+  }
+
+  /** Decorative overlapping circles (for cover). */
+  drawDecorCircles(doc, cx, cy) {
+    const circles = [
+      { r: 190, color: '#5B50F0', opacity: 0.07 },
+      { r: 128, color: '#06B6D4', opacity: 0.11 },
+      { r:  72, color: '#10B981', opacity: 0.20 },
+      { r:  32, color: '#8B5CF6', opacity: 0.42 }
+    ];
+    for (const { r, color, opacity } of circles) {
+      doc.save();
+      doc.circle(cx, cy, r);
+      doc.fillColor(color, opacity);
+      doc.fill();
+      doc.restore();
+    }
+  }
+
+  /** Draw a horizontal gradient approximation using N thin rect slices. */
+  drawGradientRect(doc, x, y, w, h, colorA, colorB, steps = 24) {
+    const rA = parseInt(colorA.slice(1, 3), 16);
+    const gA = parseInt(colorA.slice(3, 5), 16);
+    const bA = parseInt(colorA.slice(5, 7), 16);
+    const rB = parseInt(colorB.slice(1, 3), 16);
+    const gB = parseInt(colorB.slice(3, 5), 16);
+    const bB = parseInt(colorB.slice(5, 7), 16);
+    const sliceW = w / steps;
+    for (let i = 0; i < steps; i++) {
+      const t = i / (steps - 1);
+      const r = Math.round(rA + (rB - rA) * t);
+      const g = Math.round(gA + (gB - gA) * t);
+      const b = Math.round(bA + (bB - bA) * t);
+      const hex = `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
+      doc.save().rect(x + i * sliceW, y, sliceW + 0.5, h).fillColor(hex).fill().restore();
+    }
+  }
+
+  // ── Section header ────────────────────────────────────────────────────── //
+
+  /**
+   * Vibrant section header with left accent pill and bold label.
+   */
+  renderSectionHeader(doc, title) {
+    const left      = doc.page.margins.left;
+    const available = doc.page.width - doc.page.margins.left - doc.page.margins.right;
+    const y         = Math.max(doc.y, doc.page.margins.top);
+
+    const barW = 4;
+    const lineH = 20;
+
+    // Left accent bar (slightly wider for more visual weight)
+    doc.save();
+    doc.roundedRect(left, y, barW, lineH, 2);
+    doc.fillColor(this.tokens.primary);
+    doc.fill();
+    doc.restore();
+
+    doc.font(this.fontNames.bold)
+      .fontSize(this.typeScale.h2)
+      .fillColor(this.tokens.text)
+      .text(title, left + barW + 10, y + 2, { width: available - barW - 12 });
+
+    const divY = doc.y + 4;
+    this.drawDivider(doc, divY);
+    doc.y = divY + 6;
+    // Reset cursor to left margin so downstream elements (tables, text) start at the correct x
+    doc.x = left;
+    doc.font(this.fontNames.regular).fontSize(this.typeScale.body).fillColor(this.tokens.text);
+  }
+
+  // ── Page banner (AI section title) ───────────────────────────────────── //
+
+  /**
+   * Full-width dark banner (used as a page-level section hero).
+   */
+  renderPageBanner(doc, title, subtitle = '') {
+    const left  = doc.page.margins.left;
+    const top   = Math.max(doc.y, doc.page.margins.top);
+    const width = doc.page.width - doc.page.margins.left - doc.page.margins.right;
+    const h     = subtitle ? 46 : 34;
+
+    // Banner background
+    doc.save()
+      .roundedRect(left, top, width, h, 6)
+      .fillColor(this.tokens.coverBg)
+      .fill()
+      .restore();
+
+    // Accent gradient strip on left edge
+    doc.save()
+      .roundedRect(left, top, 4, h, 3)
+      .fillColor(this.tokens.primary)
+      .fill()
+      .restore();
+
+    // AI badge on right
+    const badgeLabel = 'AI-POWERED';
+    const bPad = 6, bFont = 7;
+    doc.save().font(this.fontNames.bold).fontSize(bFont);
+    const bW = doc.widthOfString(badgeLabel) + bPad * 2;
+    const bH = bFont + bPad - 1;
+    const bX = left + width - bW - 10;
+    const bY = top + (h - bH) / 2;
+    doc.restore();
+    doc.save()
+      .roundedRect(bX, bY, bW, bH, bH / 2)
+      .fillColor(this.tokens.cyan)
+      .fill()
+      .restore();
+    doc.font(this.fontNames.bold).fontSize(bFont).fillColor(this.tokens.coverBg)
+      .text(badgeLabel, bX + bPad, bY + (bH - bFont) / 2 + 0.5, { lineBreak: false });
+
+    // Title text
+    doc.font(this.fontNames.bold).fontSize(this.typeScale.h3 + 1).fillColor(this.tokens.inverse)
+      .text(title, left + 16, top + (subtitle ? 8 : (h - this.typeScale.h3 - 1) / 2), {
+        width: width - bW - 32,
+        lineBreak: false
+      });
+
+    if (subtitle) {
+      doc.font(this.fontNames.regular).fontSize(this.typeScale.small).fillColor(this.tokens.faint)
+        .text(subtitle, left + 16, top + 26, { width: width - bW - 32, lineBreak: false });
+    }
+
+    doc.y = top + h + 18;
+    doc.x = left;
+    doc.font(this.fontNames.regular).fontSize(this.typeScale.body).fillColor(this.tokens.text);
+  }
+
+  // ── Callout box ───────────────────────────────────────────────────────── //
+
+  renderCalloutBox(doc, text, type = 'info', width = null) {
+    const left     = doc.page.margins.left;
+    const boxWidth = width || (doc.page.width - doc.page.margins.left - doc.page.margins.right);
+    const paddingX = 14, paddingY = 10;
+    const y        = doc.y;
+
+    const palette = {
+      info:    { bg: this.tokens.calloutInfoBg,     border: this.tokens.calloutInfoBorder, bar: this.tokens.primary, text: this.tokens.text },
+      risk:    { bg: this.tokens.calloutRiskBg,     border: this.tokens.calloutRiskBorder, bar: this.tokens.red,     text: this.tokens.calloutRiskText },
+      success: { bg: this.tokens.calloutSuccessBg,  border: this.tokens.calloutSuccessBorder, bar: this.tokens.green, text: '#065F46' },
+      warning: { bg: this.tokens.calloutWarningBg,  border: this.tokens.calloutWarningBorder, bar: this.tokens.orange, text: '#92400E' }
+    };
+    const { bg, bar, text: textColor } = palette[type] || palette.info;
+
+    doc.font(this.fontNames.regular).fontSize(this.typeScale.body);
+    const textH  = doc.heightOfString(text, { width: boxWidth - paddingX * 2 - 4, lineGap: 1.5 });
+    const boxH   = textH + paddingY * 2;
+
+    doc.save().roundedRect(left, y, boxWidth, boxH, 6).fillColor(bg).fill().restore();
+    doc.save().roundedRect(left, y, 4, boxH, 3).fillColor(bar).fill().restore();
+
+    doc.font(this.fontNames.regular).fontSize(this.typeScale.body).fillColor(textColor)
+      .text(text, left + paddingX + 2, y + paddingY, { width: boxWidth - paddingX * 2 - 4, lineGap: 1.5 });
+
+    doc.y = y + boxH + 8;
+    doc.x = left;
+    doc.font(this.fontNames.regular).fontSize(this.typeScale.body).fillColor(this.tokens.text);
+  }
+
+  // ── Data flow arrow row ───────────────────────────────────────────────── //
+
+  /**
+   * Renders a visual data-flow strip: A -> B -> C with colored pills.
+   */
+  renderFlowStrip(doc, flowText) {
+    if (!flowText) return;
+    const parts = flowText.split(/\s*->\s*/).map(p => p.trim()).filter(Boolean);
+    if (parts.length < 2) {
+      doc.font(this.fontNames.regular).fontSize(this.typeScale.body)
+        .fillColor(this.tokens.primary).text(flowText, { width: doc.page.width - doc.page.margins.left - doc.page.margins.right });
+      doc.moveDown(0.5);
+      return;
+    }
+
+    const left   = doc.page.margins.left;
+    const width  = doc.page.width - doc.page.margins.left - doc.page.margins.right;
+    const pillH  = 26;
+    const arrowW = 20;
+    const colors = [this.tokens.primary, this.tokens.cyan, this.tokens.green, this.tokens.orange, this.tokens.purple];
+    const fontSize = 8;
+    let hPad = 12;
+
+    doc.font(this.fontNames.bold).fontSize(fontSize);
+
+    // 1. Calculate items and their required widths
+    let items = parts.map(label => ({
+      label,
+      pW: doc.widthOfString(label) + hPad * 2
+    }));
+
+    // Strategy: If we only slightly overflow (up to 15%), reduce padding to fit
+    const totalRawW = items.reduce((s, it) => s + it.pW, 0) + (items.length - 1) * arrowW;
+    if (totalRawW > width && totalRawW < width * 1.15) {
+      hPad = 8;
+      items = parts.map(label => ({
+        label,
+        pW: doc.widthOfString(label) + hPad * 2
+      }));
+    }
+
+    // 2. Group into rows
+    const rows = [];
+    let currentRow = [];
+    let currentRowW = 0;
+
+    items.forEach((item, i) => {
+      const neededW = item.pW + (currentRow.length > 0 ? arrowW : 0);
+      
+      if (currentRowW + neededW > width && currentRow.length > 0) {
+        rows.push(currentRow);
+        currentRow = [];
+        currentRowW = 0;
+      }
+      
+      currentRow.push(item);
+      currentRowW += (currentRow.length === 1 ? item.pW : item.pW + arrowW);
+    });
+    if (currentRow.length > 0) rows.push(currentRow);
+
+    // 3. Render rows
+    let currentY = doc.y;
+    let globalIndex = 0;
+    const bottomReserve = 40;
+
+    rows.forEach((row, rowIndex) => {
+      // Page-break guard: if this row doesn't fit, start a new page
+      const bottomLimit = doc.page.height - doc.page.margins.bottom - bottomReserve;
+      if (currentY + pillH > bottomLimit) {
+        doc.addPage();
+        currentY = doc.page.margins.top + 10;
+        doc.x = left;
+      }
+
+      // Sync PDFKit cursor to our explicit Y before rendering this row.
+      // Without this, PDFKit's auto-page logic fires on the next .text() call
+      // and silently inserts a blank page mid-strip.
+      doc.y = currentY;
+
+      const rowPillsW = row.reduce((s, it) => s + it.pW, 0);
+      const rowArrowsW = (row.length - 1) * arrowW;
+      const rowTotalW = rowPillsW + rowArrowsW;
+
+      let x = left + (width - rowTotalW) / 2;
+
+      row.forEach((item, colIndex) => {
+        const color = colors[globalIndex % colors.length];
+
+        // Pill background
+        doc.save().roundedRect(x, currentY, item.pW, pillH, 6).fillColor(color).fill().restore();
+
+        // Vertical center calculation: (PillHeight - TextHeight) / 2
+        const textH = doc.heightOfString(item.label, { width: item.pW - hPad * 2 });
+        const textY = currentY + (pillH - textH) / 2 + 0.5;
+
+        doc.font(this.fontNames.bold).fontSize(fontSize).fillColor('#FFFFFF')
+          .text(item.label, x + hPad, textY, {
+            width: item.pW - hPad * 2,
+            align: 'center',
+            lineBreak: true
+          });
+
+        // Restore cursor after .text() to prevent drift / spurious auto-page
+        doc.y = currentY;
+        doc.x = left;
+
+        x += item.pW;
+        globalIndex++;
+
+        // Draw arrow if not last in this row
+        if (colIndex < row.length - 1) {
+          const arrowY = currentY + pillH / 2;
+          doc.save()
+            .moveTo(x + 4, arrowY).lineTo(x + arrowW - 4, arrowY)
+            .lineWidth(1.5).strokeColor(this.tokens.muted).stroke()
+            .restore();
+          doc.save()
+            .polygon([x + arrowW - 6, arrowY - 3], [x + arrowW - 2, arrowY], [x + arrowW - 6, arrowY + 3])
+            .fillColor(this.tokens.muted).fill()
+            .restore();
+          x += arrowW;
+        }
+      });
+
+      // If there's a next row, draw a vertical continuation line/arrow
+      if (rowIndex < rows.length - 1) {
+        const lastInRowX = x - row[row.length - 1].pW / 2;
+        const connY = currentY + pillH;
+        doc.save()
+          .moveTo(lastInRowX, connY + 1).lineTo(lastInRowX, connY + 5)
+          .lineWidth(1).strokeColor(this.tokens.faint).dash(2, { space: 2 }).stroke()
+          .restore();
+      }
+
+      currentY += pillH + 12; // Space between rows
+    });
+
+    doc.y = currentY;
+    doc.x = left;
+    doc.font(this.fontNames.regular).fontSize(this.typeScale.body).fillColor(this.tokens.text);
+  }
+
+  // ── Table ─────────────────────────────────────────────────────────────── //
+
+  async renderZebraTable(doc, titleOrHeaders, headersOrRows, maybeRows) {
+    const hasTitle = typeof titleOrHeaders === 'string';
+    const title    = hasTitle ? titleOrHeaders : '';
+    const headers  = hasTitle ? headersOrRows : titleOrHeaders;
+    const rows     = hasTitle ? maybeRows : headersOrRows;
+
+    if (!Array.isArray(headers) || headers.length === 0) return;
+    if (!Array.isArray(rows)    || rows.length    === 0) return;
+
+    const tableWidth = doc.page.width - doc.page.margins.left - doc.page.margins.right;
+    const rowValues  = rows.map(row =>
+      Array.isArray(row) ? row.map(v => String(v ?? '')) : headers.map(k => String(row?.[k] ?? ''))
+    );
+
+    const left = doc.page.margins.left;
+    doc.x = left;
+
+    if (title) {
+      doc.font(this.fontNames.bold).fontSize(this.typeScale.small)
+        .fillColor(this.tokens.muted)
+        .text(title.toUpperCase(), { width: tableWidth })
+        .moveDown(1.5);
+      doc.x = left; // guard: reset cursor after text
+    }
+
+    // Build header column objects so pdfkit-table applies the background colour
+    const headerDefs = headers.map(h => ({
+      label:         String(h ?? ''),
+      headerColor:   this.tokens.tableHeaderBg,
+      headerOpacity: 1
+    }));
+
+    doc.x = left;
+    await doc.table({ headers: headerDefs, rows: rowValues }, {
+      x:     left,
+      width: tableWidth,
+      columnSpacing: 8,
+      padding: [7, 10, 7, 10],
+      prepareHeader: () => {
+        doc.font(this.fontNames.bold).fontSize(this.typeScale.body).fillColor(this.tokens.tableHeaderText);
+      },
+      prepareRow: (row, indexColumn, indexRow, rectRow) => {
+        doc.font(this.fontNames.regular).fontSize(this.typeScale.body).fillColor(this.tokens.text);
+        if (indexColumn === 0 && indexRow % 2 !== 0 && rectRow) {
+          doc.addBackground(rectRow, this.tokens.tableStripe, 1);
+        }
+      },
+      divider: {
+        header:     { disabled: false, width: 0.5, opacity: 1,   color: this.tokens.tableHeaderBg },
+        horizontal: { disabled: false, width: 0.4, opacity: 0.6, color: this.tokens.divider },
+        vertical:   { disabled: true }
+      }
+    });
+  }
+
+  // ── Risk / hotspot cards ──────────────────────────────────────────────── //
+
+  /**
+   * Binary-search the last word boundary where text still fits within availH.
+   * Returns [firstPart, remainingPart].
+   */
+  _splitTextToFit(doc, text, textWidth, availH, fontName, fontSize, lineGap = 0) {
+    doc.font(fontName).fontSize(fontSize);
+    if (availH <= 0) return ['', text];
+    if (doc.heightOfString(text, { width: textWidth, lineGap }) <= availH) return [text, ''];
+    const words = text.split(' ');
+    if (words.length <= 1) return ['', text];
+    let lo = 1, hi = words.length - 1;
+    while (lo < hi) {
+      const mid = Math.floor((lo + hi + 1) / 2);
+      const h = doc.heightOfString(words.slice(0, mid).join(' '), { width: textWidth, lineGap });
+      if (h <= availH) lo = mid; else hi = mid - 1;
+    }
+    return [words.slice(0, lo).join(' '), words.slice(lo).join(' ')];
+  }
+
+  renderRiskCards(doc, hotspots = []) {
+    if (!hotspots?.length) return;
+
+    const left  = doc.page.margins.left;
+    const width = doc.page.width - doc.page.margins.left - doc.page.margins.right;
+    const FOOTER_RESERVE = 16;
+    // Offset from card top (after pY) where the reason text starts on first segment
+    const HEADER_H = 12;
+
+    for (const risk of hotspots) {
+      const severity = String(risk?.severity || 'HIGH').toUpperCase();
+      const isHigh   = severity === 'HIGH' || severity === 'CRITICAL';
+      const isMed    = severity === 'MEDIUM' || severity === 'MED';
+
+      let bgColor, barColor, titleColor, badgeBg;
+      if (isHigh)      { bgColor = '#FEF2F2'; barColor = '#EF4444'; titleColor = '#B91C1C'; badgeBg = '#EF4444'; }
+      else if (isMed)  { bgColor = '#FFFBEB'; barColor = '#F59E0B'; titleColor = '#92400E'; badgeBg = '#F59E0B'; }
+      else             { bgColor = '#F0FDF4'; barColor = '#10B981'; titleColor = '#065F46'; badgeBg = '#10B981'; }
+
+      const file  = risk?.file   || 'Unknown file';
+      const pX = 14, pY = 6, barW = 4;
+      const textW = width - pX * 2 - barW - 2;
+
+      // Pre-measure badge width
+      doc.save().font(this.fontNames.bold).fontSize(7);
+      const bW = doc.widthOfString(severity) + 12;
+      doc.restore();
+
+      let remainingReason = risk?.reason || 'No reason provided.';
+      let isFirst = true;
+
+      while (true) {
+        const bottomLimit = doc.page.height - doc.page.margins.bottom - FOOTER_RESERVE;
+        const availH = bottomLimit - doc.y;
+
+        doc.font(this.fontNames.regular).fontSize(this.typeScale.body);
+        const oneLineH = doc.currentLineHeight(true);
+        // Minimum height to start a card segment: padding + optional header + one line + padding
+        const minH = pY + (isFirst ? HEADER_H : 0) + oneLineH + pY;
+
+        if (availH < minH) { doc.addPage(); continue; }
+
+        const fullReasonH = remainingReason
+          ? doc.heightOfString(remainingReason, { width: textW, lineGap: 1.4 })
+          : 0;
+        const totalH = pY + (isFirst ? HEADER_H : 0) + fullReasonH + pY;
+        const y = doc.y;
+
+        let renderReason = remainingReason;
+        let nextReason   = '';
+
+        if (totalH > availH) {
+          const textAvailH = availH - pY - (isFirst ? HEADER_H : 0) - pY;
+          [renderReason, nextReason] = this._splitTextToFit(
+            doc, remainingReason, textW, textAvailH,
+            this.fontNames.regular, this.typeScale.body, 1.4
+          );
+          // If the split didn't yield any text (e.g. first word is too long), jump to next page
+          if (!renderReason.trim()) { doc.addPage(); continue; }
+        }
+
+        doc.font(this.fontNames.regular).fontSize(this.typeScale.body);
+        const segReasonH = renderReason
+          ? doc.heightOfString(renderReason, { width: textW, lineGap: 1.4 })
+          : 0;
+        const segH = pY + (isFirst ? HEADER_H : 0) + segReasonH + pY;
+
+        // Draw card background + severity bar
+        doc.save().roundedRect(left, y, width, segH, 5).fillColor(bgColor).fill().restore();
+        doc.save().roundedRect(left, y, barW, segH, 3).fillColor(barColor).fill().restore();
+
+        if (isFirst) {
+          // Severity badge
+          const bH = 14, bX = left + width - bW - 8, bY2 = y + pY - 1;
+          doc.save().roundedRect(bX, bY2, bW, bH, 4).fillColor(badgeBg).fill().restore();
+          doc.font(this.fontNames.bold).fontSize(7).fillColor('#FFFFFF')
+            .text(severity, bX, bY2 + 3.5, { width: bW, align: 'center', lineBreak: false });
+
+          // File path
+          doc.font(this.fontNames.bold).fontSize(this.typeScale.body).fillColor(titleColor)
+            .text(file, left + barW + pX, y + pY, { width: width - pX * 2 - barW - bW - 14, lineBreak: false });
+        }
+
+        // Reason text
+        if (renderReason) {
+          doc.font(this.fontNames.regular).fontSize(this.typeScale.body).fillColor(this.tokens.text)
+            .text(renderReason, left + barW + pX, y + pY + (isFirst ? HEADER_H : 0), { width: textW, lineGap: 1.4 });
+        }
+
+        doc.y = y + segH + 4;
+        doc.x = left;
+
+        if (!nextReason.trim()) break;
+
+        remainingReason = nextReason;
+        isFirst = false;
+        doc.addPage();
+      }
+    }
+    doc.moveDown(1.5);
+    doc.font(this.fontNames.regular).fontSize(this.typeScale.body).fillColor(this.tokens.text);
+  }
+
+  // ── Running page header ───────────────────────────────────────────────── //
+
+  /**
+   * Thin dark strip at the very top of a content page (not cover).
+   */
+  renderPageHeader(doc, projectName, pageNum) {
+    const w = doc.page.width;
+    const h = 28;
+
+    // Full-width strip
+    doc.save().rect(0, 0, w, h).fillColor(this.tokens.headerStrip).fill().restore();
+
+    // Accent gradient line at bottom edge of strip
+    const rA = parseInt(this.tokens.primary.slice(1, 3), 16);
+    const gA = parseInt(this.tokens.primary.slice(3, 5), 16);
+    const bA = parseInt(this.tokens.primary.slice(5, 7), 16);
+    const rB = parseInt(this.tokens.cyan.slice(1, 3), 16);
+    const gB = parseInt(this.tokens.cyan.slice(3, 5), 16);
+    const bB = parseInt(this.tokens.cyan.slice(5, 7), 16);
+    const steps = 32;
+    const sliceW = w / steps;
+    for (let i = 0; i < steps; i++) {
+      const t2 = i / (steps - 1);
+      const r = Math.round(rA + (rB - rA) * t2);
+      const g = Math.round(gA + (gB - gA) * t2);
+      const b = Math.round(bA + (bB - bA) * t2);
+      const hex = `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
+      doc.save().rect(i * sliceW, h - 1.5, sliceW + 0.5, 1.5).fillColor(hex).fill().restore();
+    }
+
+    // Project name — vertically centered in strip
+    const leftFontSize = 7.5;
+    const leftY = (h - leftFontSize) / 2 - 0.5;
+    doc.font(this.fontNames.bold).fontSize(leftFontSize).fillColor(this.tokens.headerStripText)
+      .text(projectName.toUpperCase(), doc.page.margins.left, leftY, {
+        width: 200, lineBreak: false
+      });
+
+    // Breadcrumb on right — vertically centered
+    const rightFontSize = 7;
+    const rightY = (h - rightFontSize) / 2 - 0.5;
+    doc.font(this.fontNames.regular).fontSize(rightFontSize).fillColor(this.tokens.primaryMid)
+      .text('Code Documentation', w - doc.page.margins.right - 100, rightY, {
+        width: 100, align: 'right', lineBreak: false
+      });
+    const left = doc.page.margins.left;
+    doc.x = left;
+    doc.y = Math.max(doc.page.margins.top, h + 12);
+  }
+}