codesummary 1.2.1 → 1.2.2

package/src/pdfGenerator.js

@@ -1,8 +1,9 @@
-import PDFDocument from 'pdfkit';
+import PDFDocument from 'pdfkit-table';
 import fs from 'fs-extra';
 import path from 'path';
 import chalk from 'chalk';
 import ErrorHandler from './errorHandler.js';
+import PDFThemeRenderer from './renderers/pdfThemeRenderer.js';
 import { getExtensionDescription, resolveVersionedPath } from './utils.js';
 
 /**
@@ -11,62 +12,63 @@ import { getExtensionDescription, resolveVersionedPath } from './utils.js';
  */
 export class PDFGenerator {
   constructor(config) {
-    this.config = config;
-    this.doc = null;
-    this.pageHeight = 842; // A4 height (595 x 842 points)
-    this.pageWidth = 595;  // A4 width
+    this.config          = config;
+    this.doc             = null;
+    this.themeRenderer   = new PDFThemeRenderer();
+    this.pageHeight      = 842;
+    this.pageWidth       = 595;
+    this._isCoverPage    = true;
+    this._projectName    = '';
+    this._pageCount      = 0;
+    this._sectionCounter = 0;
+
+    // ── Colour tokens for direct use in this file ─────────────────────── //
+    this.t = null; // set after themeRenderer is ready (tokens reference)
   }
 
-  /**
-   * Calculate available content width
-   * @returns {number} Available width for content
-   */
   getContentWidth() {
+    if (this.doc?.page?.margins) {
+      return this.doc.page.width - (this.doc.page.margins.left + this.doc.page.margins.right);
+    }
     return this.pageWidth - (this.config.styles.layout.marginLeft + this.config.styles.layout.marginRight);
   }
 
-  /**
-   * Generate PDF from scanned files
-   * @param {object} filesByExtension - Files grouped by extension
-   * @param {Array} selectedExtensions - Extensions selected by user
-   * @param {string} outputPath - Output file path
-   * @param {string} projectName - Name of the project
-   * @returns {Promise<object>} Object with outputPath and pageCount
-   */
-  async generatePDF(filesByExtension, selectedExtensions, outputPath, projectName) {
+  // ═══════════════════════════════════════════════════════════════════════ //
+  // Public API
+  // ═══════════════════════════════════════════════════════════════════════ //
+
+  async generatePDF(filesByExtension, selectedExtensions, outputPath, projectName, pdfOptions = {}) {
     console.log(chalk.gray('Generating PDF...'));
+    this._projectName = projectName;
 
-    // Initialize PDF document with A4 size and optimized margins
     this.doc = new PDFDocument({
+      bufferPages: true,
       size: 'A4',
       margins: {
-        top: this.config.styles.layout.marginTop,
-        bottom: this.config.styles.layout.marginTop,
-        left: this.config.styles.layout.marginLeft,
-        right: this.config.styles.layout.marginRight
+        top:    Math.max(this.config.styles.layout.marginTop,    50),
+        bottom: Math.max(this.config.styles.layout.marginTop,    50),
+        left:   Math.max(this.config.styles.layout.marginLeft,   50),
+        right:  Math.max(this.config.styles.layout.marginRight,  50)
       }
     });
 
-    // Register cleanup for PDF document
+    this.doc.info.Title    = `${projectName} - Code Summary`;
+    this.doc.info.Author   = 'CodeSummary';
+    this.doc.info.Subject  = 'Code and architecture documentation';
+    this.doc.info.Keywords = 'code summary, architecture, documentation';
+
     ErrorHandler.registerCleanup(() => {
-      if (this.doc && !this.doc.closed) {
-        this.doc.end();
-      }
+      if (this.doc && !this.doc.closed) this.doc.end();
     }, 'PDF document cleanup');
 
-
-    // Setup output stream with error handling for files in use
     let finalOutputPath = outputPath;
     let outputStream;
-    
+
     try {
       outputStream = fs.createWriteStream(outputPath);
       this.doc.pipe(outputStream);
-
       ErrorHandler.registerCleanup(() => {
-        if (outputStream && !outputStream.destroyed) {
-          outputStream.destroy();
-        }
+        if (outputStream && !outputStream.destroyed) outputStream.destroy();
       }, 'PDF output stream cleanup');
     } catch (error) {
       if (error.code === 'EBUSY' || error.code === 'EACCES') {
@@ -79,331 +81,1243 @@ export class PDFGenerator {
       }
     }
 
-    // PDFKit handles positioning automatically
-
     try {
-      // Generate the three main sections
-      await this.generateTitleSection(selectedExtensions, projectName);
-      await this.generateFileStructureSection(filesByExtension, selectedExtensions);
-      await this.generateFileContentSection(filesByExtension, selectedExtensions);
+      // Register fonts and set base styles
+      this.themeRenderer.applyBaseTheme(this.doc);
+      this.t = this.themeRenderer.tokens;
+
+      // Page decoration — runs on every new page
+      this._isCoverPage = true;
+      this.doc.on('pageAdded', () => {
+        this._pageCount++;
+        this._isCoverPage = false;
+        this.applyPageDecor();
+      });
+      // Decorate the first page (cover)
+      this.applyPageDecor();
+
+      const includeFileTree   = pdfOptions?.includeFileTree   !== false;
+      const includeSourceCode = pdfOptions?.includeSourceCode !== false;
 
-      // No page numbers - content only
+      this._totalFiles = selectedExtensions.reduce(
+        (s, e) => s + (filesByExtension[e]?.length || 0), 0
+      );
+
+      await this.generateTitleSection(selectedExtensions, projectName, pdfOptions);
+      await this.generateAiInsightsSection(pdfOptions);
+
+      if (includeFileTree) {
+        await this.generateFileStructureSection(filesByExtension, selectedExtensions);
+      }
+      if (includeSourceCode) {
+        await this.generateFileContentSection(filesByExtension, selectedExtensions);
+      }
 
-      // Finalize document
+      this.renderPageNumbers();
+      const pageRange = this.doc.bufferedPageRange();
       this.doc.end();
 
-      // Wait for file write to complete
       await new Promise((resolve, reject) => {
         outputStream.on('finish', resolve);
         outputStream.on('error', reject);
       });
 
       console.log(chalk.green('SUCCESS: PDF generation completed'));
-      return { outputPath: finalOutputPath, pageCount: 'N/A' };
+      return { outputPath: finalOutputPath, pageCount: pageRange.count };
 
     } catch (error) {
       ErrorHandler.handlePDFError(error, finalOutputPath || outputPath);
     }
   }
 
-  /**
-   * Generate the title/overview section
-   * @param {Array} selectedExtensions - Selected file extensions
-   * @param {string} projectName - Project name
-   */
-  async generateTitleSection(selectedExtensions, projectName) {
-    // Title
-    this.doc
-      .fontSize(20)
-      .fillColor(this.config.styles.colors.title)
-      .font('Helvetica-Bold')
-      .text(this.config.settings.documentTitle, {
-        align: 'center',
-        width: this.getContentWidth()
-      })
-      .moveDown(1);
-    
-    // Subtitle
-    this.doc
-      .fontSize(14)
-      .fillColor(this.config.styles.colors.section)
-      .font('Helvetica')
-      .text(`Project: ${projectName}`, {
-        align: 'center',
-        width: this.getContentWidth()
-      })
-      .moveDown(1);
-    
-    // Generation timestamp
+  // ═══════════════════════════════════════════════════════════════════════ //
+  // Page decoration
+  // ═══════════════════════════════════════════════════════════════════════ //
+
+  applyPageDecor() {
+    if (this._isCoverPage) {
+      this._drawCoverBackground();
+    } else {
+      this._drawContentPageBackground();
+    }
+  }
+
+  _drawCoverBackground() {
+    const w = this.pageWidth, h = this.pageHeight;
+    const t = this.t || this.themeRenderer.tokens;
+
+    // Full dark background
+    this.doc.save();
+    this.doc.rect(0, 0, w, h);
+    this.doc.fillColor(t.coverBg);
+    this.doc.fill();
+    this.doc.restore();
+
+    // Ambient background glows
+    this.doc.save();
+    this.doc.circle(w * 0.72, h * 0.42, 270);
+    this.doc.fillColor(t.primary, 0.055);
+    this.doc.fill();
+    this.doc.restore();
+
+    this.doc.save();
+    this.doc.circle(w * 0.18, h * 0.80, 200);
+    this.doc.fillColor(t.cyan, 0.048);
+    this.doc.fill();
+    this.doc.restore();
+
+    // Decorative circles (top-right corner, partially off-page for drama)
+    this.themeRenderer.drawDecorCircles(this.doc, w - 45, 72);
+
+    // Left accent bar (full height, gradient indigo)
+    this.themeRenderer.drawGradientRect(this.doc, 0, 3, 3, h - 31, t.primary, t.primaryDark, 14);
+
+    // Bottom accent strip
+    this.doc.save();
+    this.doc.rect(0, h - 28, w, 28);
+    this.doc.fillColor('#0A0C14');
+    this.doc.fill();
+    this.doc.restore();
+
+    // Multi-color gradient top edge (3px)
+    this.themeRenderer.drawGradientRect(this.doc, 0, 0, w, 3, t.primary, t.cyan);
+  }
+
+  _drawContentPageBackground() {
+    const t = this.t || this.themeRenderer.tokens;
+    const margins = this.doc.page.margins;
+    const left   = margins.left;
+    const top    = margins.top;
+    const right  = this.pageWidth  - margins.right;
+    const bottom = this.pageHeight - margins.bottom;
+
+    // Off-white page background
+    this.doc.save()
+      .roundedRect(left - 10, top - 16, (right - left) + 20, (bottom - top) + 20, 8)
+      .fillColor(t.pageBackground)
+      .fill()
+      .restore();
+
+    // Running page header strip
+    this.themeRenderer.renderPageHeader(this.doc, this._projectName, this._pageCount);
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════ //
+  // Cover / title page
+  // ═══════════════════════════════════════════════════════════════════════ //
+
+  async generateTitleSection(selectedExtensions, projectName, pdfOptions = {}) {
+    const t    = this.t || this.themeRenderer.tokens;
+    const left = this.doc.page.margins.left;
+    const w    = this.getContentWidth();
+
+    // ── "Code Documentation" category pill ──
+    this.doc.y = 52;
+    const catLabel = 'CODE DOCUMENTATION';
+    const catFont  = 7.5;
+    const catPadX  = 9, catPadY = 3.5;
+    this.doc.font(this.themeRenderer.fontNames.bold).fontSize(catFont);
+    const catW = this.doc.widthOfString(catLabel) + catPadX * 2;
+    const catH = catFont + catPadY * 2;
+    const catY = this.doc.y;
+
+    this.doc.save();
+    this.doc.roundedRect(left, catY, catW, catH, catH / 2);
+    this.doc.fillColor(t.primary, 0.22);
+    this.doc.fill();
+    this.doc.restore();
+
+    this.doc.save();
+    this.doc.roundedRect(left, catY, catW, catH, catH / 2);
+    this.doc.lineWidth(0.8);
+    this.doc.strokeColor(t.primaryMid);
+    this.doc.stroke();
+    this.doc.restore();
+
+    this.doc.font(this.themeRenderer.fontNames.bold).fontSize(catFont)
+      .fillColor(t.primaryMid)
+      .text(catLabel, left + catPadX, catY + catPadY, { lineBreak: false });
+
+    this.doc.y = catY + catH + 20;
+
+    // ── Project name (large, white) ──
+    const title = this.config.settings.documentTitle || `${projectName} — Code Summary`;
+    this.doc.font(this.themeRenderer.fontNames.bold)
+      .fontSize(34)
+      .fillColor(t.coverTitle)
+      .text(title, left, this.doc.y, { width: w * 0.78 });
+
+    // ── Subtitle ──
+    this.doc.font(this.themeRenderer.fontNames.bold)
+      .fontSize(13)
+      .fillColor(t.coverSub)
+      .text(`Project: ${projectName}`, left, this.doc.y + 3, { width: w });
+    this.doc.y += 5;
+
+    // ── Timestamp ──
     const timestamp = new Date().toLocaleString();
-    this.doc
-      .fontSize(10)
-      .fillColor(this.config.styles.colors.footer)
-      .font('Helvetica')
-      .text(`Generated on: ${timestamp}`, {
-        width: this.getContentWidth()
-      })
-      .moveDown(2);
-
-    // Included file types section
-    this.doc
-      .fontSize(16)
-      .fillColor(this.config.styles.colors.section)
-      .font('Helvetica-Bold')
-      .text('Included File Types', {
-        width: this.getContentWidth()
-      })
-      .moveDown(0.5);
+    this.doc.font(this.themeRenderer.fontNames.regular)
+      .fontSize(9)
+      .fillColor(t.coverMuted)
+      .text(`Generated: ${timestamp}`, left, this.doc.y + 2, { width: w });
+    this.doc.y += 20;
 
-    selectedExtensions.forEach(ext => {
-      const description = getExtensionDescription(ext);
-      this.doc
-        .fontSize(11)
-        .fillColor(this.config.styles.colors.text)
-        .font('Helvetica')
-        .text(`- ${ext} -> ${description}`, {
-          width: this.getContentWidth()
+    // ── Gradient divider ──
+    const divY = this.doc.y;
+    this.themeRenderer.drawGradientRect(this.doc, left, divY, w, 1.5, t.primary, '#1A2040');
+    this.doc.y = divY + 20;
+
+    // ── Metric cards (replaces tiny pills) ──
+    this._drawCoverMetricCards(selectedExtensions, pdfOptions);
+
+    // ── File type table (2-column, staircase fixed) ──
+    const extChunks = [];
+    for (let i = 0; i < selectedExtensions.length; i += 2) {
+      extChunks.push([selectedExtensions[i], selectedExtensions[i + 1]]);
+    }
+
+    this.doc.font(this.themeRenderer.fontNames.bold)
+      .fontSize(8)
+      .fillColor(t.coverSub)
+      .text('INCLUDED FILE TYPES', left, this.doc.y + 4, { lineBreak: false });
+    this.doc.y += 20;
+
+    const tagW = 40, colGap = 14;
+    const colW = w / 2 - colGap / 2;
+
+    for (const row of extChunks) {
+      const rowY = this.doc.y;  // FIX: capture before column loop
+      for (let col = 0; col < 2; col++) {
+        const ext = row[col];
+        if (!ext) continue;
+        const desc = getExtensionDescription(ext);
+        const colX = left + col * (w / 2 + colGap / 2);
+
+        this.doc.save()
+          .roundedRect(colX, rowY, tagW, 16, 3)
+          .fillColor('#141830')
+          .fill()
+          .restore();
+        this.doc.font(this.themeRenderer.fontNames.bold)
+          .fontSize(7.5)
+          .fillColor(t.primaryMid)
+          .text(ext, colX + 4, rowY + 4, { width: tagW - 8, lineBreak: false });
+        this.doc.font(this.themeRenderer.fontNames.regular)
+          .fontSize(8)
+          .fillColor(t.coverMuted)
+          .text(desc || 'Source file', colX + tagW + 6, rowY + 4, {
+            width: colW - tagW - 8, lineBreak: false
+          });
+      }
+      this.doc.y = rowY + 22;  // FIX: fixed advance after both columns
+    }
+
+    this.doc.y += 24;
+
+    // ── Feature highlights (fills lower portion of cover) ──
+    this._drawCoverFeatureRow();
+
+    // ── Decorative dot grid filling remaining space ──
+    this._drawCoverDotGrid(left, w);
+
+    // ── Bottom credit ──
+    const botY = this.pageHeight - 22;
+    this.doc.font(this.themeRenderer.fontNames.bold)
+      .fontSize(7.5)
+      .fillColor('#3A4558')
+      .text('CodeSummary  •  Code Documentation Tool', left, botY, {
+        width: w, align: 'center', lineBreak: false
+      });
+
+    this.addPageIfContentExists();
+  }
+
+  /** Three large metric cards on cover (file types, files, AI status). */
+  _drawCoverMetricCards(selectedExtensions, pdfOptions) {
+    const t     = this.t || this.themeRenderer.tokens;
+    const left  = this.doc.page.margins.left;
+    const w     = this.getContentWidth();
+    const cardH = 64;
+    const gap   = 10;
+    const count = 3;
+    const cardW = (w - gap * (count - 1)) / count;
+    const y     = this.doc.y;
+
+    const aiOn = Boolean(pdfOptions?.aiProjectContext);
+    const metrics = [
+      { value: String(selectedExtensions.length), label: 'FILE TYPES',    color: t.primary },
+      { value: String(this._totalFiles || '—'),   label: 'FILES SCANNED', color: t.cyan    },
+      { value: aiOn ? 'ON' : 'OFF',               label: 'AI ENRICHED',   color: aiOn ? t.green : '#3D4A62' }
+    ];
+
+    for (let i = 0; i < metrics.length; i++) {
+      const { value, label, color } = metrics[i];
+      const x = left + i * (cardW + gap);
+
+      // Card background
+      this.doc.save();
+      this.doc.roundedRect(x, y, cardW, cardH, 6);
+      this.doc.fillColor('#141728');
+      this.doc.fill();
+      this.doc.restore();
+
+      // Top accent bar
+      this.doc.save();
+      this.doc.roundedRect(x, y, cardW, 3, 2);
+      this.doc.fillColor(color);
+      this.doc.fill();
+      this.doc.restore();
+
+      // Big value
+      this.doc.font(this.themeRenderer.fontNames.bold).fontSize(26)
+        .fillColor('#FFFFFF')
+        .text(value, x, y + 14, { width: cardW, align: 'center', lineBreak: false });
+
+      // Label
+      this.doc.font(this.themeRenderer.fontNames.bold).fontSize(7.5)
+        .fillColor(color)
+        .text(label, x, y + 44, { width: cardW, align: 'center', lineBreak: false });
+    }
+
+    this.doc.y = y + cardH + 20;
+  }
+
+  /** Three feature highlight cards on the cover's lower section. */
+  _drawCoverFeatureRow() {
+    const t    = this.t || this.themeRenderer.tokens;
+    const left = this.doc.page.margins.left;
+    const w    = this.getContentWidth();
+
+    // Section label + divider line
+    const labelY = this.doc.y;
+    this.doc.font(this.themeRenderer.fontNames.bold).fontSize(7.5)
+      .fillColor('#2D3748')
+      .text('CAPABILITIES', left, labelY, { lineBreak: false });
+    this.doc.save()
+      .moveTo(left + 70, labelY + 4)
+      .lineTo(left + w, labelY + 4)
+      .lineWidth(0.4)
+      .strokeColor('#1E2A3A')
+      .stroke()
+      .restore();
+    this.doc.y = labelY + 18;
+
+    const features = [
+      {
+        title:  'Professional PDF',
+        desc:   'A4 cover with AI executive brief, syntax-highlighted source & file tree',
+        points: ['Project stats & metrics', 'Architecture overview', 'Risk hotspot analysis'],
+        color: t.primary
+      },
+      {
+        title:  'LLM-Optimized RAG',
+        desc:   'Semantic chunks with byte-accurate offsets and per-chunk token estimates',
+        points: ['Byte-accurate offsets', 'Token count per chunk', 'Semantic boundaries'],
+        color: t.cyan
+      },
+      {
+        title:  'Graph Analysis',
+        desc:   'Dependency graphs, centrality scoring, hotspot detection & semantic clusters',
+        points: ['Dependency mapping', 'Hotspot detection', 'Semantic clusters'],
+        color: t.green
+      }
+    ];
+
+    const gap   = 8;
+    const cardW = (w - gap * 2) / 3;
+    const cardH = 112;
+    const y     = this.doc.y;
+
+    for (let i = 0; i < features.length; i++) {
+      const { title, desc, points, color } = features[i];
+      const x = left + i * (cardW + gap);
+
+      // Card
+      this.doc.save();
+      this.doc.roundedRect(x, y, cardW, cardH, 6);
+      this.doc.fillColor('#0F1322');
+      this.doc.fill();
+      this.doc.restore();
+
+      // Left accent bar
+      this.doc.save();
+      this.doc.roundedRect(x, y, 3, cardH, 2);
+      this.doc.fillColor(color);
+      this.doc.fill();
+      this.doc.restore();
+
+      // Color indicator dot
+      this.doc.save();
+      this.doc.circle(x + 20, y + 20, 11);
+      this.doc.fillColor(color, 0.18);
+      this.doc.fill();
+      this.doc.restore();
+      this.doc.save();
+      this.doc.circle(x + 20, y + 20, 5);
+      this.doc.fillColor(color);
+      this.doc.fill();
+      this.doc.restore();
+
+      // Title
+      this.doc.font(this.themeRenderer.fontNames.bold).fontSize(9.5)
+        .fillColor('#D0D8E8')
+        .text(title, x + 13, y + 38, { width: cardW - 18, lineBreak: false });
+
+      // Description
+      this.doc.font(this.themeRenderer.fontNames.regular).fontSize(7.5)
+        .fillColor('#5A7090')
+        .text(desc, x + 13, y + 52, { width: cardW - 18, lineGap: 1.5 });
+
+      // Bullet points
+      for (let j = 0; j < points.length; j++) {
+        const bulletY = y + 72 + j * 13;
+        this.doc.save().circle(x + 16, bulletY + 3.5, 2).fillColor(color, 0.7).fill().restore();
+        this.doc.font(this.themeRenderer.fontNames.regular).fontSize(7)
+          .fillColor('#3F5470')
+          .text(points[j], x + 22, bulletY, { width: cardW - 28, lineBreak: false });
+      }
+    }
+
+    this.doc.y = y + cardH + 28;
+
+    // Centered divider + tagline
+    const tagY = this.doc.y;
+    this.themeRenderer.drawGradientRect(this.doc, left + w * 0.25, tagY, w * 0.5, 1.5, t.primary, t.cyan);
+    this.doc.y = tagY + 14;
+    this.doc.font(this.themeRenderer.fontNames.regular).fontSize(10)
+      .fillColor('#304560')
+      .text('From code to documentation.  Automatically.', left, this.doc.y, {
+        width: w, align: 'center', lineBreak: false
+      });
+    this.doc.y += 14;
+  }
+
+  /** Fills remaining cover space with a subtle dot-grid pattern. */
+  _drawCoverDotGrid(left, w) {
+    const gridTop = this.doc.y + 8;
+    const gridBot = this.pageHeight - 36; // above bottom strip
+    if (gridBot - gridTop < 20) return;
+
+    const spacingX = 16, spacingY = 13;
+    const cols = Math.floor(w / spacingX);
+    const rows = Math.floor((gridBot - gridTop) / spacingY);
+    const t    = this.t || this.themeRenderer.tokens;
+    const colors = [t.primary, t.cyan, t.green, t.purple];
+
+    for (let row = 0; row < rows; row++) {
+      for (let col = 0; col < cols; col++) {
+        const dotX    = left + col * spacingX + spacingX * 0.5;
+        const dotY    = gridTop + row * spacingY + spacingY * 0.5;
+        const sum     = row + col;
+        // Large bright accent at prime-ish intervals
+        const bigAccent  = sum % 13 === 0;
+        const midAccent  = sum % 7  === 0 && !bigAccent;
+        const color  = bigAccent ? colors[(row * cols + col) % colors.length]
+                     : midAccent ? '#2D4A70'
+                     : '#182130';
+        const opacity = bigAccent ? 0.80 : midAccent ? 0.55 : 0.40;
+        const radius  = bigAccent ? 1.8  : midAccent ? 1.1  : 0.7;
+        this.doc.save().circle(dotX, dotY, radius).fillColor(color, opacity).fill().restore();
+      }
+    }
+    this.doc.y = gridBot + 4;
+  }
+
+  /** Small key-value list on cover (used for intro context). */
+  _renderCoverInfoBlock(heading, items) {
+    const t    = this.t || this.themeRenderer.tokens;
+    const left = this.doc.page.margins.left;
+    const w    = this.getContentWidth();
+
+    this.doc.font(this.themeRenderer.fontNames.bold)
+      .fontSize(9)
+      .fillColor(t.coverSub)
+      .text(heading.toUpperCase(), left, this.doc.y)
+      .moveDown(0.3);
+
+    for (const { label, value } of items) {
+      this.ensureSpace(18);
+      this.doc.font(this.themeRenderer.fontNames.bold)
+        .fontSize(9)
+        .fillColor('#637598')
+        .text(`${label}: `, left, this.doc.y, { continued: true, width: w });
+      this.doc.font(this.themeRenderer.fontNames.regular)
+        .fillColor(t.coverMuted)
+        .text(value, { width: w });
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════ //
+  // AI Insights section
+  // ═══════════════════════════════════════════════════════════════════════ //
+
+  async generateAiInsightsSection(pdfOptions = {}) {
+    const aiContext = pdfOptions?.aiProjectContext;
+    if (!aiContext || typeof aiContext !== 'object') return;
+
+    if (aiContext.executiveBrief) {
+      await this.generateExecutiveBriefSection(aiContext.executiveBrief);
+      return;
+    }
+
+    const { architecture, operations, maintenanceAndSecurity, visualizations, applicability } = aiContext;
+    if (!architecture && !operations && !maintenanceAndSecurity && !visualizations && !applicability) return;
+
+    this.renderSectionHeader('AI-Assisted Architecture Documentation');
+
+    if (architecture) {
+      this.renderSectionHeader('Architecture & Design Patterns');
+      this.renderListSection('Structural Patterns',              architecture.structuralPatterns);
+      this.renderListSection('Implementation Paradigm',          architecture.implementationParadigm);
+      this.renderListSection('Coupling Points (Potential SPOFs)', architecture.couplingPoints);
+      this.doc.moveDown(0.4);
+    }
+
+    if (operations) {
+      const { dataAndStateLifecycle: lc = {}, configurationAndEnvironmentStrategy: cs = {}, languageSpecificBreakdown: lb = {} } = operations;
+      this.renderSectionHeader('Data & State Lifecycle');
+      this.renderListSection('Inbound / Outbound',      lc.inboundOutbound);
+      this.renderListSection('Critical Transformations', lc.criticalTransformations);
+      this.renderListSection('State Management',         lc.stateManagement);
+      this.renderSectionHeader('Configuration & Environment Strategy');
+      this.renderListSection('Configuration Hierarchy',     cs.configurationHierarchy);
+      this.renderListSection('Infrastructure Dependencies', cs.infrastructureDependencies);
+      this.renderSectionHeader('Language-Specific Breakdown');
+      this.renderListSection('Responsibility Distribution', lb.responsibilityDistribution);
+      this.renderListSection('Interoperability',            lb.interoperability);
+    }
+
+    if (maintenanceAndSecurity) {
+      const { onboardingAndMaintenanceGuide: og = {}, securityAndComplianceSurface: sc = {} } = maintenanceAndSecurity;
+      this.renderSectionHeader('Onboarding & Maintenance Guide');
+      this.renderListSection('Complexity Hotspots', og.complexityHotspots);
+      this.renderListSection('Modification Guide',  og.modificationGuide);
+      this.renderListSection('Domain Glossary',     og.domainGlossary);
+      this.renderSectionHeader('Security & Compliance Surface');
+      this.renderListSection('Exposure Surface',          sc.exposureSurface);
+      this.renderListSection('Sensitive Data Handling', sc.sensitiveDataHandling);
+    }
+
+    if (visualizations) {
+      this.renderSectionHeader('Visualisations (Text-Based)');
+      await this.renderMonospaceList('Semantic Directory Tree', visualizations.semanticDirectoryTree);
+      await this.renderMonospaceList('Dependency Text Graph',   visualizations.dependencyTextGraph);
+    }
+
+    if (applicability?.whyItHelpsAcrossProjects) {
+      const by = applicability.whyItHelpsAcrossProjects;
+      this.renderSectionHeader('Why This Is Beneficial Across Project Types');
+      this.renderListSection('Infrastructure as Code',   by.infrastructureAsCode);
+      this.renderListSection('Data Platforms',           by.dataPlatforms);
+      this.renderListSection('Frontend Applications',    by.frontendApplications);
+      this.renderListSection('Backend Services',         by.backendServices);
+      this.renderListSection('Generic Transferable Value', by.genericTransferableValue);
+    }
+  }
+
+  async generateExecutiveBriefSection(executiveBrief) {
+    const t    = this.t || this.themeRenderer.tokens;
+    const left = this.doc.page.margins.left;
+    const w    = this.getContentWidth();
+
+    const summary    = executiveBrief.executiveSummary    || {};
+    const dataFlow   = executiveBrief.dataFlow            || {};
+
+    // ── Page banner ──
+    this.ensureSpace(60);
+    this.themeRenderer.renderPageBanner(
+      this.doc,
+      'AI Executive Brief',
+      'Auto-generated architecture analysis powered by LLM'
+    );
+
+    // ── Executive Summary ──
+    this.renderSectionHeader('Executive Summary');
+    if (summary.purpose) {
+      this.doc.font(this.themeRenderer.fontNames.regular)
+        .fontSize(10.5)
+        .fillColor(t.text)
+        .text(summary.purpose, left, this.doc.y, { width: w, align: 'justify', lineGap: 3 })
+        .moveDown(1.5);
+    }
+    this._renderKillerFeatures(summary.killerFeatures || []);
+    this.doc.moveDown(0.5);
+
+    // ── Architecture Blueprint ──
+    this.renderSectionHeader('Architecture Blueprint');
+    const archRows = (executiveBrief.architectureBlueprint || []).map(item => [
+      item.pattern || '', item.primaryModule || '', item.value || ''
+    ]);
+    await this.themeRenderer.renderZebraTable(
+      this.doc, 'Top Design Patterns',
+      ['Pattern', 'Primary Module', 'Why It Matters'],
+      archRows
+    );
+    this.doc.moveDown(1.0);
+
+    // ── Data Flow ──
+    this.renderSectionHeader('Data Flow');
+    if (dataFlow.primaryFlow) {
+      this.themeRenderer.renderFlowStrip(this.doc, this.sanitizeFlowText(dataFlow.primaryFlow));
+    }
+    this.doc.moveDown(0.3);
+    this.renderListSection('Key Flows', dataFlow.keyFlows || []);
+    this.doc.moveDown(0.5);
+
+    // ── Onboarding Quick Guide ──
+    this.renderSectionHeader('Onboarding Quick Guide');
+    const ogRows = (executiveBrief.onboardingQuickGuide || []).map(item => [
+      item.goal || '', item.modify || ''
+    ]);
+    await this.themeRenderer.renderZebraTable(
+      this.doc, 'Action Map',
+      ['If You Want To', 'Modify'],
+      ogRows
+    );
+    this.doc.moveDown(1.0);
+
+    // ── Risk & Hotspots ──
+    this.renderSectionHeader('Risk & Hotspots');
+    this.themeRenderer.renderRiskCards(this.doc, executiveBrief.riskHotspots || []);
+  }
+
+  /** Render killer features as numbered, colored cards in a grid. */
+  _renderKillerFeatures(features) {
+    if (!features?.length) return;
+    const t      = this.t || this.themeRenderer.tokens;
+    const left   = this.doc.page.margins.left;
+    const w      = this.getContentWidth();
+    const cols   = 2;
+    const colW   = (w - 10) / cols;
+    const pX     = 12, pY = 9;
+    const colors = [t.primary, t.cyan, t.green, t.orange, t.purple, t.red];
+
+    // Extra breathing room above the label (not a section header, so manually added)
+    if (this.doc.y > this.doc.page.margins.top + 10) this.doc.y += 10;
+    this.doc.font(this.themeRenderer.fontNames.bold)
+      .fontSize(this.themeRenderer.typeScale.small)
+      .fillColor(t.muted)
+      .text('KILLER FEATURES', left)
+      .moveDown(0.4);
+
+    let rowStartY = this.doc.y;
+
+    for (let i = 0; i < features.length; i++) {
+      const col   = i % cols;
+      const x     = left + col * (colW + 10);
+      const text  = features[i];
+      const color = colors[i % colors.length];
+
+      this.doc.font(this.themeRenderer.fontNames.regular).fontSize(9.5);
+      const textH = this.doc.heightOfString(text, { width: colW - pX * 2 - 26, lineGap: 1.8 });
+      const cardH = Math.max(textH + pY * 2, 36);
+
+      if (col === 0) {
+        this.ensureSpace(cardH + 6);
+        rowStartY = this.doc.y;  // FIX: capture row baseline when starting new row
+      }
+
+      const y = rowStartY;  // FIX: both columns in the same row share the same y
+
+      // Card background
+      this.doc.save();
+      this.doc.roundedRect(x, y, colW, cardH, 5);
+      this.doc.fillColor(t.cardBackground);
+      this.doc.fill();
+      this.doc.restore();
+
+      // Left accent bar
+      this.doc.save();
+      this.doc.roundedRect(x, y, 3, cardH, 2);
+      this.doc.fillColor(color);
+      this.doc.fill();
+      this.doc.restore();
+
+      // Number badge — circle + centered number
+      const circCX = x + colW - 18;
+      const circCY = y + cardH / 2;
+      this.doc.save();
+      this.doc.circle(circCX, circCY, 11);
+      this.doc.fillColor(color, 0.12);
+      this.doc.fill();
+      this.doc.restore();
+      // Center text in circle: text area width 22, left edge = circCX - 11
+      this.doc.font(this.themeRenderer.fontNames.bold).fontSize(9).fillColor(color)
+        .text(`${i + 1}`, circCX - 11, circCY - 4.5, {
+          width: 22, align: 'center', lineBreak: false
         });
-    });
-    
-    this.doc.moveDown(2);
+
+      // Feature text
+      this.doc.font(this.themeRenderer.fontNames.regular).fontSize(9.5).fillColor(t.text)
+        .text(text, x + pX + 3, y + pY, { width: colW - pX * 2 - 26, lineGap: 1.8 });
+
+      if (col === cols - 1 || i === features.length - 1) {
+        this.doc.y = rowStartY + cardH + 8;  // FIX: advance from saved row baseline
+      }
+    }
+    this.doc.moveDown(0.7);
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════ //
+  // File structure section
+  // ═══════════════════════════════════════════════════════════════════════ //
+
+  /** Build an ASCII tree from flat relative paths. */
+  _buildFileTree(relativePaths) {
+    // Build nested tree object
+    const tree = {};
+    for (const p of relativePaths) {
+      const parts = p.replace(/\\/g, '/').split('/').filter(Boolean);
+      let node = tree;
+      for (const part of parts) {
+        if (!node[part]) node[part] = {};
+        node = node[part];
+      }
+    }
+
+    // Render tree to lines
+    const lines = [];
+    const renderNode = (node, prefix) => {
+      const entries = Object.entries(node);
+      // Directories first, then files, alphabetical within each group
+      entries.sort(([aKey, aVal], [bKey, bVal]) => {
+        const aDir = Object.keys(aVal).length > 0;
+        const bDir = Object.keys(bVal).length > 0;
+        if (aDir && !bDir) return -1;
+        if (!aDir && bDir) return 1;
+        return aKey.localeCompare(bKey);
+      });
+      for (let i = 0; i < entries.length; i++) {
+        const [name, children] = entries[i];
+        const isLast     = i === entries.length - 1;
+        const hasChildren = Object.keys(children).length > 0;
+        const connector  = isLast ? '`-- ' : '+-- ';
+        const childPfx   = prefix + (isLast ? '    ' : '|   ');
+        lines.push(prefix + connector + name + (hasChildren ? '/' : ''));
+        if (hasChildren) renderNode(children, childPfx);
+      }
+    };
+    renderNode(tree, '');
+    return lines.join('\n');
   }
 
-  /**
-   * Generate the file structure section
-   * @param {object} filesByExtension - Files grouped by extension
-   * @param {Array} selectedExtensions - Selected extensions
-   */
   async generateFileStructureSection(filesByExtension, selectedExtensions) {
-    // Section header
-    this.doc
-      .fontSize(16)
-      .fillColor(this.config.styles.colors.section)
-      .font('Helvetica-Bold')
-      .text('Project File Structure', {
-        width: this.getContentWidth()
-      })
-      .moveDown(1);
-
-    // Collect all files from selected extensions
     const allFiles = [];
     selectedExtensions.forEach(ext => {
-      if (filesByExtension[ext]) {
-        allFiles.push(...filesByExtension[ext]);
-      }
+      if (filesByExtension[ext]) allFiles.push(...filesByExtension[ext]);
     });
+    if (allFiles.length === 0) return;
+
+    // Only force a new page if a substantial amount of content already sits on this page.
+    // A single trailing card (doc.y not far below margins.top) can share the page.
+    const minContentY = this.doc.page.margins.top + 120;
+    if (this.doc.y > minContentY) this.doc.addPage();
+    this.renderSectionHeader('Project File Structure');
 
-    // Sort files by path
     allFiles.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    const treeContent = this._buildFileTree(allFiles.map(f => f.relativePath));
+    await this.addCodeContent(treeContent, { compact: true, filename: 'repository root' });
+
+    // Footer summary
+    const t2   = this.t || this.themeRenderer.tokens;
+    const left = this.doc.page.margins.left;
+    const fw   = this.getContentWidth();
+    this.doc.moveDown(0.6);
+    this.themeRenderer.drawDivider(this.doc, this.doc.y);
+    this.doc.y += 8;
+    this.doc.font(this.themeRenderer.fontNames.regular).fontSize(9)
+      .fillColor(t2.muted)
+      .text(
+        `${allFiles.length} files  ·  ${selectedExtensions.length} file types  ·  ${selectedExtensions.join(', ')}`,
+        left, this.doc.y, { width: fw, align: 'center', lineBreak: false }
+      );
+    this.doc.moveDown(0.4);
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════ //
+  // File content section
+  // ═══════════════════════════════════════════════════════════════════════ //
 
-    // Add file list as continuous text
-    const fileList = allFiles.map(file => file.relativePath).join('\n');
-    
-    this.doc
-      .fontSize(10)
-      .fillColor(this.config.styles.colors.text)
-      .font('Courier')
-      .text(fileList, {
-        width: this.getContentWidth()
-      })
-      .moveDown(2);
-  }
-
-  /**
-   * Generate the file content section
-   * @param {object} filesByExtension - Files grouped by extension
-   * @param {Array} selectedExtensions - Selected extensions
-   */
   async generateFileContentSection(filesByExtension, selectedExtensions) {
-    // Section header
-    this.doc
-      .fontSize(16)
-      .fillColor(this.config.styles.colors.section)
-      .font('Helvetica-Bold')
-      .text('Project File Content', {
-        width: this.getContentWidth()
-      })
-      .moveDown(2);
-
-    for (const extension of selectedExtensions) {
-      if (!filesByExtension[extension]) continue;
-
-      const files = filesByExtension[extension];
-      
-      for (const file of files) {
-        await this.addFileContent(file);
-      }
+    const filesToRender = [];
+    for (const ext of selectedExtensions) {
+      if (!filesByExtension[ext]) continue;
+      filesToRender.push(...filesByExtension[ext]);
+    }
+    if (filesToRender.length === 0) return;
+
+    const minContentY2 = this.doc.page.margins.top + 120;
+    if (this.doc.y > minContentY2) this.doc.addPage();
+    this.renderSectionHeader('Project File Content');
+    this.doc.moveDown(0.5);
+
+    for (const file of filesToRender) {
+      await this.addFileContent(file);
     }
   }
 
-  /**
-   * Add content of a single file to the PDF
-   * @param {object} file - File object with path and metadata
-   */
   async addFileContent(file) {
-    // Add file header
-    this.addFileHeader(file.relativePath);
-
     try {
-      // Read and validate file content
       const contentBuffer = await fs.readFile(file.absolutePath);
-      
-      // Validate content before processing
       if (!ErrorHandler.validateFileContent(file.relativePath, contentBuffer)) {
         this.addErrorContent('File appears to contain binary data');
         return;
       }
-      
+
       const content = contentBuffer.toString('utf8');
-      
-      // Memory and size limits for large files
-      const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50MB
-      const MAX_LINES = 10000; // Maximum lines per file
-      const MAX_LINE_LENGTH = 2000; // Maximum characters per line
-      
+      const MAX_FILE_SIZE  = 50 * 1024 * 1024;
+      const MAX_LINES      = 10000;
+      const MAX_LINE_LEN   = 2000;
+
       if (contentBuffer.length > MAX_FILE_SIZE) {
         this.addErrorContent(`File too large (${Math.round(contentBuffer.length / 1024 / 1024)}MB). Limit: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
         return;
       }
-      
+
       const lines = content.split('\n');
       let processedContent = content;
       let wasModified = false;
-      
-      // Limit number of lines
+
       if (lines.length > MAX_LINES) {
-        const truncatedLines = lines.slice(0, MAX_LINES);
-        truncatedLines.push(`\n... [TRUNCATED: ${lines.length - MAX_LINES} more lines] ...`);
-        processedContent = truncatedLines.join('\n');
+        const truncated = lines.slice(0, MAX_LINES);
+        truncated.push(`\n... [TRUNCATED: ${lines.length - MAX_LINES} more lines] ...`);
+        processedContent = truncated.join('\n');
         wasModified = true;
         console.log(chalk.yellow(`WARNING: File truncated from ${lines.length} to ${MAX_LINES} lines: ${file.relativePath}`));
       }
-      
-      // Limit line length
+
       const limitedLines = processedContent.split('\n').map(line => {
-        if (line.length > MAX_LINE_LENGTH) {
-          wasModified = true;
-          return line.substring(0, MAX_LINE_LENGTH) + '... [TRUNCATED]';
-        }
+        if (line.length > MAX_LINE_LEN) { wasModified = true; return line.substring(0, MAX_LINE_LEN) + '... [TRUNCATED]'; }
         return line;
       });
-      
-      if (wasModified) {
-        processedContent = limitedLines.join('\n');
-      }
-      
-      // Log processing info for large files
+      if (wasModified) processedContent = limitedLines.join('\n');
+
       if (lines.length > 1000 || contentBuffer.length > 1024 * 1024) {
         console.log(chalk.gray(`Processing large file: ${file.relativePath} (${lines.length} lines, ${Math.round(contentBuffer.length / 1024)}KB)`));
       }
-      
-      await this.addCodeContent(processedContent);
-      
+
+      // Ensure space for header + at least the first 15 lines of code (or the whole file if small)
+      // This prevents the header from being orphaned on the previous page
+      const minLinesToStart = Math.min(processedContent.split('\n').length, 15);
+      const firstChunkLines = processedContent.split('\n').slice(0, minLinesToStart);
+      this.doc.font(this.themeRenderer.fontNames.mono).fontSize(9);
+      const h1 = this.doc.heightOfString('X', {});
+      const h2 = this.doc.heightOfString('X\nX', { lineGap: 1.8 });
+      const firstChunkH = (firstChunkLines.length - 1) * (h2 - h1) + h1 + 16; // text + padding
+      this.ensureSpace(42 + firstChunkH + 10);
+
+      await this.addCodeContent(processedContent, { filename: file.relativePath });
+
     } catch (error) {
-      // Handle unreadable files with appropriate error messages
-      let errorMessage = 'Could not read file';
-      
-      if (error.code === 'EACCES') {
-        errorMessage = 'Permission denied';
-      } else if (error.code === 'ENOENT') {
-        errorMessage = 'File not found';
-      } else if (error.code === 'EISDIR') {
-        errorMessage = 'Path is a directory';
-      } else if (error.message) {
-        errorMessage = error.message;
-      }
-      
-      this.addErrorContent(errorMessage);
+      const msg =
+        error.code === 'EACCES' ? 'Permission denied' :
+        error.code === 'ENOENT' ? 'File not found' :
+        error.code === 'EISDIR' ? 'Path is a directory' :
+        error.message || 'Could not read file';
+      this.addErrorContent(msg);
     }
   }
 
-  /**
-   * Add file header
-   * @param {string} filePath - Relative file path
-   */
+  // ═══════════════════════════════════════════════════════════════════════ //
+  // File header (used in source code section)
+  // ═══════════════════════════════════════════════════════════════════════ //
+
   addFileHeader(filePath) {
-    this.doc
-      .moveDown(1)
-      .fontSize(12)
-      .fillColor(this.config.styles.colors.section)
-      .font('Helvetica-Bold')
-      .text(`File: ${filePath}`, {
-        width: this.getContentWidth()
-      })
-      .moveDown(0.5);
+    this.ensureSpace(30);
+    const t    = this.t || this.themeRenderer.tokens;
+    const x    = this.doc.page.margins.left;
+    const topM = this.doc.page.margins.top;
+    const y    = Math.max(this.doc.y, topM);
+    const w    = this.getContentWidth();
+
+    // Header tab — same dark as code background
+    this.doc.save()
+      .roundedRect(x, y, w, 22, 5)
+      .fillColor(t.codeTabBg)
+      .fill()
+      .restore();
+
+    // Decorative 3-dot traffic lights
+    const dotY = y + 11;
+    const dots = [{ x: x + 10, color: '#FF5F57' }, { x: x + 22, color: '#FEBC2E' }, { x: x + 34, color: '#28C840' }];
+    for (const d of dots) {
+      this.doc.save().circle(d.x, dotY, 3.5).fillColor(d.color).fill().restore();
+    }
+
+    // Language badge (right side)
+    const badge   = this._langBadge(filePath);
+    const bFs     = 7;
+    const bPadX   = 6, bPadY = 2.5;
+    this.doc.font(this.themeRenderer.fontNames.bold).fontSize(bFs);
+    const bTextW  = this.doc.widthOfString(badge.label);
+    const bW      = bTextW + bPadX * 2;
+    const bH      = bFs + bPadY * 2;
+    const bX      = x + w - bW - 6;
+    const bY      = y + (22 - bH) / 2;
+    this.doc.save().roundedRect(bX, bY, bW, bH, 3).fillColor(badge.color).fill().restore();
+    this.doc.font(this.themeRenderer.fontNames.bold).fontSize(bFs)
+      .fillColor(badge.text)
+      .text(badge.label, bX + bPadX, bY + bPadY, { lineBreak: false });
+
+    // File path text (leave room for badge)
+    this.doc.font(this.themeRenderer.fontNames.mono)
+      .fontSize(8.5)
+      .fillColor(t.codeTabText)
+      .text(filePath, x + 48, y + 6.5, { width: w - bW - 58, lineBreak: false });
+
+    this.doc.y = y + 22;
   }
 
-  /**
-   * Add code content with proper formatting
-   * @param {string} content - File content
-   */
-  async addCodeContent(content) {
-    // Clean and prepare content
-    const cleanContent = this.prepareContent(content);
-    
-    this.doc
-      .fontSize(9)
-      .fillColor(this.config.styles.colors.text)
-      .font('Courier')
-      .text(cleanContent, {
-        width: this.getContentWidth(),
-        align: 'left'
-      });
-    
-    // Add some spacing after code block
-    this.doc.moveDown(1);
+  /** Returns { label, color, text } for a file extension badge. */
+  _langBadge(filePath) {
+    const ext = path.extname(filePath).toLowerCase().slice(1);
+    const MAP = {
+      js:     { label: 'JS',      color: '#F7DF1E', text: '#1A1A1A' },
+      mjs:    { label: 'MJS',     color: '#F7DF1E', text: '#1A1A1A' },
+      cjs:    { label: 'CJS',     color: '#F7DF1E', text: '#1A1A1A' },
+      ts:     { label: 'TS',      color: '#3178C6', text: '#FFFFFF' },
+      tsx:    { label: 'TSX',     color: '#61DAFB', text: '#1A1A1A' },
+      jsx:    { label: 'JSX',     color: '#61DAFB', text: '#1A1A1A' },
+      py:     { label: 'PY',      color: '#3776AB', text: '#FFFFFF' },
+      json:   { label: 'JSON',    color: '#F59E0B', text: '#1A1A1A' },
+      md:     { label: 'MD',      color: '#6B7280', text: '#FFFFFF' },
+      yaml:   { label: 'YAML',    color: '#CB171E', text: '#FFFFFF' },
+      yml:    { label: 'YML',     color: '#CB171E', text: '#FFFFFF' },
+      toml:   { label: 'TOML',    color: '#9C4121', text: '#FFFFFF' },
+      css:    { label: 'CSS',     color: '#1572B6', text: '#FFFFFF' },
+      scss:   { label: 'SCSS',    color: '#CC6699', text: '#FFFFFF' },
+      html:   { label: 'HTML',    color: '#E34F26', text: '#FFFFFF' },
+      rs:     { label: 'RS',      color: '#F74C00', text: '#FFFFFF' },
+      go:     { label: 'GO',      color: '#00ADD8', text: '#FFFFFF' },
+      java:   { label: 'JAVA',    color: '#ED8B00', text: '#FFFFFF' },
+      kt:     { label: 'KT',      color: '#7F52FF', text: '#FFFFFF' },
+      swift:  { label: 'SWIFT',   color: '#F05138', text: '#FFFFFF' },
+      rb:     { label: 'RB',      color: '#CC342D', text: '#FFFFFF' },
+      php:    { label: 'PHP',     color: '#777BB4', text: '#FFFFFF' },
+      sh:     { label: 'SH',      color: '#4EAA25', text: '#FFFFFF' },
+      sql:    { label: 'SQL',     color: '#336791', text: '#FFFFFF' },
+      graphql:{ label: 'GQL',     color: '#E10098', text: '#FFFFFF' },
+      vue:    { label: 'VUE',     color: '#4FC08D', text: '#FFFFFF' },
+      svelte: { label: 'SVELTE',  color: '#FF3E00', text: '#FFFFFF' },
+      dart:   { label: 'DART',    color: '#00B4AB', text: '#FFFFFF' },
+      c:      { label: 'C',       color: '#A8B9CC', text: '#1A1A1A' },
+      cpp:    { label: 'C++',     color: '#00599C', text: '#FFFFFF' },
+      cs:     { label: 'C#',      color: '#178600', text: '#FFFFFF' },
+    };
+    return MAP[ext] || { label: ext.toUpperCase() || 'TXT', color: '#4A5568', text: '#FFFFFF' };
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════ //
+  // Code content block
+  // ═══════════════════════════════════════════════════════════════════════ //
+
+  // Draw a rectangle with selective corner rounding (top/bottom independently).
+  // Returns doc for chaining (e.g. .clip()).
+  _selectiveRoundRect(x, y, w, h, r, roundTop, roundBottom) {
+    const doc = this.doc;
+    const k = 0.5523; // bezier approximation constant for 90° circular arc
+    if (roundTop && roundBottom) {
+      doc.roundedRect(x, y, w, h, r);
+    } else if (!roundTop && !roundBottom) {
+      doc.rect(x, y, w, h);
+    } else if (roundTop) {
+      // Rounded top corners, flat bottom
+      doc.moveTo(x + r, y)
+         .lineTo(x + w - r, y)
+         .bezierCurveTo(x + w - r * (1 - k), y, x + w, y + r * (1 - k), x + w, y + r)
+         .lineTo(x + w, y + h)
+         .lineTo(x, y + h)
+         .lineTo(x, y + r)
+         .bezierCurveTo(x, y + r * (1 - k), x + r * (1 - k), y, x + r, y)
+         .closePath();
+    } else {
+      // Flat top, rounded bottom corners
+      doc.moveTo(x, y)
+         .lineTo(x + w, y)
+         .lineTo(x + w, y + h - r)
+         .bezierCurveTo(x + w, y + h - r * (1 - k), x + w - r * (1 - k), y + h, x + w - r, y + h)
+         .lineTo(x + r, y + h)
+         .bezierCurveTo(x + r * (1 - k), y + h, x, y + h - r * (1 - k), x, y + h - r)
+         .lineTo(x, y)
+         .closePath();
+    }
+    return doc;
+  }
+
+  async addCodeContent(content, options = {}) {
+    const t          = this.t || this.themeRenderer.tokens;
+    const clean      = this.prepareContent(content);
+    const allLines   = clean.split('\n');
+    const compact    = options.compact || false;
+    const lineStart  = options.lineStart || 1;
+    const showHeader = Boolean(options.filename) && !compact;
+    const CHUNK_LIMIT = compact ? 120 : 100;
+    const GUTTER_W    = compact ? 0 : 50;
+    const fontSize    = compact ? 8.5 : 9;
+    const LINE_GAP    = 1.8;
+    const RADIUS      = 5;
+
+    // Pre-compute metrics
+    this.doc.font(this.themeRenderer.fontNames.mono).fontSize(fontSize);
+    const _h1 = this.doc.heightOfString('X', {});
+    const _h2 = this.doc.heightOfString('X\nX', { lineGap: LINE_GAP });
+    const lineStride = _h2 - _h1;
+
+    if (showHeader) {
+      // First chunk check: header (22) + padding (16) + 10 lines + buffer
+      const minFirstChunkH = 22 + (9 * lineStride + _h1) + 16 + 10;
+      this.ensureSpace(minFirstChunkH);
+      this.addFileHeader(options.filename);
+    }
+
+    const totalLines = allLines.length;
+    let isFirstChunk = true;
+
+    for (let start = 0; start < allLines.length;) {
+      const footerReserve = 32;
+      const bottomLimit = this.doc.page.height - this.doc.page.margins.bottom - footerReserve;
+      const padX = 12, padY = 8;
+
+      // If we don't even have room for 5 lines of code (plus header buffer), skip to next page
+      // For the last few lines, allow a smaller minimum height so they
+      // don't get orphaned onto a nearly-empty next page unnecessarily.
+      const remainingLines = allLines.length - start;
+      const minH = remainingLines <= 4
+        ? padY * 2 + _h1 + Math.max(0, remainingLines - 1) * lineStride
+        : 80;
+      if (this.doc.y + minH > bottomLimit) this.doc.addPage();
+
+      const y      = this.doc.y;
+      const availH = bottomLimit - y;
+      const x      = this.doc.page.margins.left;
+      const w      = this.getContentWidth();
+      const codeX  = x + GUTTER_W + padX;
+      const codeW  = w - GUTTER_W - padX * 2;
+      const txtOpts = { width: codeW, align: 'left', lineGap: LINE_GAP };
+
+      // Determine how many lines fit on this page (initial estimate)
+      let n = Math.floor((availH - padY * 2 - _h1) / lineStride) + 1;
+      n = Math.max(1, Math.min(n, CHUNK_LIMIT, allLines.length - start));
+
+      let chunkLines = allLines.slice(start, start + n);
+      let chunk = chunkLines.join('\n');
+
+      // Calculate real height (handles wrapping accurately)
+      let textH = this.doc.heightOfString(chunk, txtOpts);
+      let boxH  = textH + padY * 2;
+
+      // Final overflow guard: if box exceeds availH (likely due to wrapping), back off lines
+      while (boxH > availH && chunkLines.length > 1) {
+        chunkLines = chunkLines.slice(0, chunkLines.length - 1);
+        chunk = chunkLines.join('\n');
+        textH = this.doc.heightOfString(chunk, txtOpts);
+        boxH  = textH + padY * 2;
+      }
+
+      const isLastChunk  = start + chunkLines.length >= totalLines;
+      const roundTop     = isFirstChunk;
+      const roundBottom  = isLastChunk;
+
+      // ── Backgrounds ──
+      this.doc.save();
+      this._selectiveRoundRect(x, y, w, boxH, RADIUS, roundTop, roundBottom).clip();
+      this.doc.rect(x, y, w, boxH).fillColor(t.codeBg).fill();
+      if (GUTTER_W > 0) {
+        this.doc.rect(x, y, GUTTER_W, boxH).fillColor(t.codeGutter).fill();
+        this.doc.save().moveTo(x + GUTTER_W, y).lineTo(x + GUTTER_W, y + boxH)
+          .lineWidth(0.3).strokeColor(t.codeBorder).stroke().restore();
+      }
+      this.doc.restore();
+
+      // ── Text ──
+      this.doc.font(this.themeRenderer.fontNames.mono).fontSize(fontSize).fillColor(t.codeFg)
+        .text(chunk, codeX, y + padY, { ...txtOpts, height: textH + 2 });
+
+      if (GUTTER_W > 0) {
+        // Build line number block
+        const nums = [];
+        for (let i = 0; i < chunkLines.length; i++) nums.push(String(start + i + lineStart));
+
+        this.doc.font(this.themeRenderer.fontNames.mono).fontSize(fontSize - 1).fillColor(t.codeGutterText)
+          .text(nums.join('\n'), x + 2, y + padY, {
+            width: GUTTER_W - 8,
+            align: 'right',
+            lineGap: lineStride - (fontSize - 1) * 1.15 // heuristic for mono leading
+          });
+      }
+
+      // No vertical gap between continuation chunks — seamless split visual
+      this.doc.y = y + boxH + (isLastChunk ? 4 : 0);
+      start += chunkLines.length;
+      isFirstChunk = false;
+    }
+
+    // Bottom accent line
+    const bX = this.doc.page.margins.left;
+    const bW = this.getContentWidth();
+    this.doc.save()
+      .moveTo(bX, this.doc.y - 4).lineTo(bX + bW, this.doc.y - 4)
+      .lineWidth(0.4).strokeColor(t.codeBorder).stroke()
+      .restore();
+
+    this.doc.x = this.doc.page.margins.left;
+    this.doc.moveDown(0.2);
   }
 
-  /**
-   * Add error content for unreadable files
-   * @param {string} errorMessage - Error message to display
-   */
   addErrorContent(errorMessage) {
-    this.doc
-      .fontSize(10)
-      .fillColor(this.config.styles.colors.error)
-      .font('Helvetica-Oblique')
-      .text(`ERROR: ${errorMessage}`, {
-        width: this.getContentWidth()
-      })
+    this.ensureSpace(28);
+    const t = this.t || this.themeRenderer.tokens;
+    this.doc.fontSize(10)
+      .fillColor(t.red)
+      .font(this.themeRenderer.fontNames.regular)
+      .text(`ERROR: ${errorMessage}`, { width: this.getContentWidth() })
       .moveDown(0.5);
   }
 
-  /**
-   * Prepare content for PDF rendering
-   * @param {string} content - Raw file content
-   * @returns {string} Cleaned content
-   */
+  // ═══════════════════════════════════════════════════════════════════════ //
+  // Utilities
+  // ═══════════════════════════════════════════════════════════════════════ //
+
   prepareContent(content) {
     return content
-      .replace(/\r\n/g, '\n')  // Normalize line endings
-      .replace(/\r/g, '\n')    // Handle old Mac line endings
-      .replace(/\t/g, '    ')  // Replace tabs with 4 spaces for better alignment
-      .replace(/[^\x20-\x7E\n\u00A0-\uFFFF]/g, ''); // Remove control chars, keep Unicode text
+      .replace(/\r\n/g, '\n')
+      .replace(/\r/g, '\n')
+      .replace(/\t/g, '    ')
+      .replace(/[^\x20-\x7E\n\u00A0-\uFFFF]/g, '');
+  }
+
+  sanitizeFlowText(flowRaw) {
+    if (typeof flowRaw !== 'string') return '';
+    return flowRaw
+      .replace(/[→➜➝➞➟➠]/g, '->')
+      .replace(/âž"/g, '->')
+      .split(/\s*->\s*/g)
+      .map(p => p.trim())
+      .filter(Boolean)
+      .join(' -> ');
+  }
+
+  renderSectionHeader(title) {
+    // Breathing room between sections — only when content is already on the page
+    if (this.doc.y > this.doc.page.margins.top + 10) this.doc.y += 18;
+    this.ensureSpace(52);
+    this.themeRenderer.renderSectionHeader(this.doc, title);
+  }
+
+  renderInfoRow(label, value) {
+    this.ensureSpace(18);
+    const t = this.t || this.themeRenderer.tokens;
+    this.doc
+      .font(this.themeRenderer.fontNames.bold).fontSize(10.5).fillColor(t.textSecond)
+      .text(label, { continued: true, width: this.getContentWidth() })
+      .font(this.themeRenderer.fontNames.regular).fillColor(t.text)
+      .text(`  ${value}`, { width: this.getContentWidth() });
+  }
+
+  renderInfoParagraph(label, value) {
+    if (!value) return;
+    this.ensureSpace(26);
+    const t = this.t || this.themeRenderer.tokens;
+    this.doc.font(this.themeRenderer.fontNames.bold).fontSize(10.5).fillColor(t.textSecond)
+      .text(`${label}:`, { width: this.getContentWidth() });
+    this.doc.font(this.themeRenderer.fontNames.regular).fontSize(10.3).fillColor(t.text)
+      .text(value, { width: this.getContentWidth(), lineGap: 1.5 })
+      .moveDown(0.3);
   }
 
-  // All text methods removed - using direct PDFKit calls for simplicity
+  renderListSection(label, items = []) {
+    if (!Array.isArray(items) || items.length === 0) return;
+    const t = this.t || this.themeRenderer.tokens;
+    this.ensureSpace(24);
+    this.doc.font(this.themeRenderer.fontNames.bold).fontSize(10.5).fillColor(t.textSecond)
+      .text(`${label}:`, { width: this.getContentWidth() });
 
-  // Page numbering removed to prevent duplicate pages
+    for (const item of items) {
+      this.ensureSpace(16);
+      const dotX = this.doc.page.margins.left;
+      const dotY = this.doc.y + 4;
+      this.doc.save().circle(dotX + 4, dotY, 2).fillColor(t.primaryMid).fill().restore();
+      this.doc.font(this.themeRenderer.fontNames.regular).fontSize(10).fillColor(t.text)
+        .text(item, dotX + 12, this.doc.y, { width: this.getContentWidth() - 12, lineGap: 1.5 });
+    }
+    this.doc.moveDown(0.35);
+  }
+
+  async renderMonospaceList(label, items = []) {
+    if (!Array.isArray(items) || items.length === 0) return;
+    const t = this.t || this.themeRenderer.tokens;
+    this.ensureSpace(20);
+    this.doc.font(this.themeRenderer.fontNames.bold).fontSize(10.5).fillColor(t.textSecond)
+      .text(`${label}:`, { width: this.getContentWidth() });
+    const text = items.join('\n');
+    await this.addCodeContent(text, { compact: true });
+  }
+
+  ensureSpace(minHeight) {
+    // Reserve 24px above margins.bottom for the footer separator + text
+    const footerReserve = 24;
+    const bottomLimit = this.pageHeight - this.doc.page.margins.bottom - footerReserve;
+    if (this.doc.y + minHeight >= bottomLimit) this.doc.addPage();
+  }
+
+  addPageIfContentExists() {
+    if (this.doc.y > this.doc.page.margins.top + 10) this.doc.addPage();
+  }
+
+  renderPageNumbers() {
+    const range = this.doc.bufferedPageRange();
+    const t     = this.themeRenderer.tokens;
+
+    // Collect only pages with real content.
+    // Threshold: doc.y must be well above margins.top (pdfkit-table blank-overflow pages
+    // may advance doc.y by ~30–50px for a table header row, so use +80 threshold).
+    const contentPages = [];
+    for (let i = range.start; i < range.start + range.count; i++) {
+      if (i === range.start) continue; // skip cover
+      this.doc.switchToPage(i);
+      const threshold = this.doc.page.margins.top + 80;
+      if (this.doc.y >= threshold) {
+        contentPages.push(i);
+      }
+    }
+
+    const total = contentPages.length;
+    for (let idx = 0; idx < total; idx++) {
+      const i = contentPages[idx];
+      this.doc.switchToPage(i);
+      const left    = this.doc.page.margins.left;
+      const w       = this.getContentWidth();
+      // Must be inside the printable area (< page.height - margins.bottom)
+      const footerY = this.doc.page.height - this.doc.page.margins.bottom - 12;
+
+      // Subtle separator line above footer
+      this.doc.save()
+        .moveTo(left, footerY - 3).lineTo(left + w, footerY - 3)
+        .lineWidth(0.25).strokeColor(t.divider).stroke()
+        .restore();
+
+      // Project name on the left
+      this.doc.font(this.themeRenderer.fontNames.regular).fontSize(7.5)
+        .fillColor(t.faint)
+        .text(this._projectName, left, footerY, { width: w * 0.6, lineBreak: false });
+
+      // Page number on the right
+      this.doc.font(this.themeRenderer.fontNames.bold).fontSize(7.5)
+        .fillColor(t.muted)
+        .text(`${idx + 1}  /  ${total}`, left, footerY, {
+          width: w, align: 'right', lineBreak: false
+        });
+    }
+  }
 
-  /**
-   * Generate output file path with timestamp fallback if file is in use
-   * @param {string} projectName - Project name
-   * @param {string} outputDir - Output directory
-   * @returns {string} Complete output file path
-   */
   static generateOutputPath(projectName, outputDir) {
     const basePath = path.join(outputDir, `${projectName.toUpperCase()}_code.pdf`);
     return resolveVersionedPath(basePath);
   }
 
-  /**
-   * Ensure output directory exists
-   * @param {string} outputDir - Output directory path
-   */
   static async ensureOutputDirectory(outputDir) {
     await fs.ensureDir(outputDir);
   }
 }
 
-export default PDFGenerator;
+export default PDFGenerator;