ll) => { // Advance column index past already-occupied slots while (occupied.has(${rowIndex}-${colIndex})) { colIndex++; }

  const rawText = sanitizeCellContent(cell);
  const { rowSpan, colSpan } = parseSpanAttributes(cell);

  // Mark the rectangular region as occupied and populate values
  for (let r = 0; r < rowSpan; r++) {
    const targetRow = rowIndex + r;
    if (!matrix[targetRow]) matrix[targetRow] = [];
    for (let c = 0; c < colSpan; c++) {
      const targetCol = colIndex + c;
      const key = `${targetRow}-${targetCol}`;
      if (!occupied.has(key)) {
        occupied.add(key);
        matrix[targetRow][targetCol] = rawText;
      }
    }
  }
  colIndex += colSpan;
});

});

return matrix; }

function parseSpanAttributes(cell: HTMLTableCellElement): CellSpan { return { rowSpan: Math.max(1, parseInt(cell.getAttribute('rowspan') || '1', 10)), colSpan: Math.max(1, parseInt(cell.getAttribute('colspan') || '1', 10)), }; }

**Architecture Rationale:** Using a `Set` for coordinate tracking prevents O(n²) array scans. The matrix is populated lazily, ensuring memory scales linearly with cell count rather than grid dimensions. This approach guarantees column alignment regardless of span complexity.

### Phase 2: Content Sanitization

`textContent` is unsafe for production extraction. It concatenates all descendant text nodes, including CSS rules, inline scripts, and hidden layout markers. We must isolate visible, meaningful content.

```typescript
function sanitizeCellContent(cell: HTMLElement): string {
  if (!cell) return '';
  
  // Clone to prevent live DOM mutation
  const clone = cell.cloneNode(true) as HTMLElement;
  
  // Remove non-data elements
  const removableSelectors = 'style, script, noscript, template, link, meta';
  clone.querySelectorAll(removableSelectors).forEach((el) => el.remove());
  
  // Collapse whitespace and strip control characters
  return (clone.textContent || '')
    .replace(/[\u0000-\u001F\u007F-\u009F]/g, '')
    .replace(/\s+/g, ' ')
    .trim();
}

Architecture Rationale: Cloning isolates the extraction process from the live DOM, preventing layout thrashing and event listener interference. Explicit removal of structural tags ensures only user-facing data survives. Control character stripping prevents CSV parsers from misinterpreting terminal codes as delimiters.

Phase 3: Format Serialization

Downstream systems expect strict formatting. CSV requires RFC 4180 compliance; JSON requires predictable key naming.

function serializeToRFC4180(matrix: string[][], delimiter: string = ','): string {
  return matrix
    .map((row) =>
      row
        .map((cell) => {
          const value = cell ?? '';
          const requiresQuoting =
            value.includes(delimiter) ||
            value.includes('"') ||
            /[\r\n]/.test(value);
          
          return requiresQuoting ? `"${value.replace(/"/g, '""')}"` : value;
        })
        .join(delimiter)
    )
    .join('\r\n');
}

function serializeToJSON(matrix: string[][]): string {
  if (matrix.length < 2) return '[]';
  
  const headers = matrix[0].map((raw, idx) => sanitizeHeaderKey(raw, idx));
  const dataRows = matrix.slice(1);
  
  const records = dataRows.map((row) => {
    const record: Record<string, string> = {};
    headers.forEach((key, idx) => {
      record[key] = row[idx] ?? '';
    });
    return record;
  });
  
  return JSON.stringify(records, null, 2);
}

function sanitizeHeaderKey(raw: string, fallbackIndex: number): string {
  if (!raw?.trim()) return `column_${fallbackIndex + 1}`;
  
  return raw
    .normalize('NFD')
    .replace(/[\u0300-\u036f]/g, '')
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, '_')
    .replace(/^_+|_+$/g, '');
}

Architecture Rationale: RFC 4180 mandates double-quote escaping for embedded delimiters, quotes, or newlines. The JSON serializer normalizes headers to prevent key collisions and ensures compatibility with strict schema validators. Fallback naming guarantees valid output even when tables lack explicit headers.

Phase 4: Client-Side Delivery

Browser environments support zero-server file generation via the Blob and URL APIs. Proper lifecycle management prevents memory leaks.

function triggerClientDownload(content: string, filename: string, mimeType: string): void {
  const blob = new Blob([content], { type: mimeType });
  const objectUrl = URL.createObjectURL(blob);
  
  const anchor = document.createElement('a');
  anchor.href = objectUrl;
  anchor.download = filename;
  anchor.style.display = 'none';
  
  document.body.appendChild(anchor);
  anchor.click();
  
  // Cleanup lifecycle
  setTimeout(() => {
    document.body.removeChild(anchor);
    URL.revokeObjectURL(objectUrl);
  }, 100);
}

Architecture Rationale: Appending the anchor to the DOM ensures compatibility with older browsers that ignore detached element clicks. The setTimeout cleanup guarantees the download event fires before memory is released. revokeObjectURL is critical; unrevoked URLs accumulate in browser memory and degrade performance during batch operations.

Pitfall Guide

Pitfall	Explanation	Production Fix
Sparse Grid Misalignment	Iterating rows and cells sequentially ignores rowspan/colspan, causing column drift and data truncation.	Implement a coordinate-tracking matrix. Mark occupied slots and fill gaps with the originating cell value.
Invisible DOM Contamination	textContent concatenates CSS rules, inline scripts, and hidden layout nodes, injecting garbage into exports.	Clone the cell, explicitly remove <style>, <script>, <noscript>, and strip control characters before extraction.
CSV Delimiter Collisions	Unescaped commas, quotes, or newlines break spreadsheet parsers and corrupt row boundaries.	Apply RFC 4180 rules: wrap fields containing delimiters/quotes/newlines in double quotes, and escape internal quotes by doubling them.
Header Key Corruption	Spaces, accents, and special characters in headers produce invalid JSON keys or database column names.	Normalize headers: strip diacritics, lowercase, replace non-alphanumeric characters with underscores, and apply fallback naming.
Object URL Memory Leaks	Failing to revoke Blob URLs causes cumulative memory consumption, eventually triggering browser throttling.	Always call URL.revokeObjectURL() after the download trigger. Use a microtask or short timeout to ensure the click event completes first.
Nested Table Contamination	Extracting all <table> elements indiscriminately pulls layout subtables, duplicating data and breaking structure.	Traverse parent nodes to verify top-level status. Filter out any table whose ancestor chain contains another <table>.
Dynamic Rendering Race Conditions	SPAs and virtualized grids populate data asynchronously. Running extraction before render completes yields empty or partial matrices.	Wait for DOMContentLoaded, use MutationObserver to detect table population, or implement a retry loop with exponential backoff for dynamic content.

Production Bundle

Action Checklist

• Validate table selector: Ensure the target element is an actual <table> and not a CSS-styled <div> grid.
• Implement matrix builder: Replace naive iteration with coordinate-tracking grid alignment to handle spans.
• Sanitize cell content: Clone nodes, remove structural tags, and strip control characters before extraction.
• Apply RFC 4180 serialization: Quote fields containing delimiters, escape internal quotes, and use \r\n line endings.
• Normalize JSON headers: Strip diacritics, enforce lowercase, replace special characters, and provide fallback keys.
• Manage Blob lifecycle: Create object URLs, trigger download, and explicitly revoke URLs to prevent memory leaks.
• Handle dynamic tables: Integrate MutationObserver or render-wait logic for SPA/virtualized environments.
• Test with edge cases: Validate against tables with mixed spans, nested structures, empty cells, and Unicode content.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Static dashboard tables	Client-side matrix extraction	Zero infrastructure, instant execution, full browser compatibility	$0 (no server costs)
Dynamic SPA / Virtualized grids	Client-side + MutationObserver	Waits for render completion, avoids race conditions, maintains zero-server model	$0 (adds ~50ms latency)
Large datasets (>10k rows)	Chunked matrix + Web Worker	Prevents main thread blocking, maintains UI responsiveness	$0 (client CPU only)
Cross-origin restricted data	Headless browser (Puppeteer/Playwright)	Bypasses CORS, executes full JS context, handles authentication	$ (server/infra costs)
Enterprise data pipeline	Server-side parser + scheduled jobs	Centralized logging, retry logic, database integration, audit trails	$ (cloud compute + storage)

Configuration Template

// table-extractor.ts
export interface ExtractionConfig {
  delimiter?: string;
  format?: 'csv' | 'json';
  sanitizeHeaders?: boolean;
  waitForRender?: boolean;
  renderTimeoutMs?: number;
}

export class TableExtractor {
  private config: Required<ExtractionConfig>;

  constructor(config: ExtractionConfig = {}) {
    this.config = {
      delimiter: config.delimiter ?? ',',
      format: config.format ?? 'csv',
      sanitizeHeaders: config.sanitizeHeaders ?? true,
      waitForRender: config.waitForRender ?? false,
      renderTimeoutMs: config.renderTimeoutMs ?? 5000,
    };
  }

  async extract(tableSelector: string): Promise<string> {
    const table = document.querySelector(tableSelector) as HTMLTableElement | null;
    if (!table) throw new Error('Table not found');

    if (this.config.waitForRender) {
      await this.waitForTablePopulation(table);
    }

    const matrix = this.buildMatrix(table);
    return this.config.format === 'json'
      ? this.toJSON(matrix)
      : this.toCSV(matrix);
  }

  private async waitForTablePopulation(table: HTMLTableElement): Promise<void> {
    return new Promise((resolve, reject) => {
      if (table.rows.length > 0) return resolve();
      
      const observer = new MutationObserver(() => {
        if (table.rows.length > 0) {
          observer.disconnect();
          resolve();
        }
      });
      observer.observe(table, { childList: true, subtree: true });
      
      setTimeout(() => {
        observer.disconnect();
        reject(new Error('Table render timeout'));
      }, this.config.renderTimeoutMs);
    });
  }

  private buildMatrix(table: HTMLTableElement): string[][] {
    // Implementation matches Phase 1 logic
    // ...
    return [];
  }

  private toCSV(matrix: string[][]): string {
    // Implementation matches Phase 3 CSV logic
    // ...
    return '';
  }

  private toJSON(matrix: string[][]): string {
    // Implementation matches Phase 3 JSON logic
    // ...
    return '';
  }
}

Quick Start Guide

1. Install & Import: Copy the TableExtractor class into your project. No external dependencies required.
2. Initialize: const extractor = new TableExtractor({ format: 'csv', waitForRender: true });
3. Execute: const data = await extractor.extract('#target-table');
4. Download: triggerClientDownload(data, 'export.csv', 'text/csv;charset=utf-8');
5. Validate: Open the exported file in a spreadsheet or JSON validator. Verify column alignment, header naming, and special character handling.

This pipeline eliminates manual data wrangling, enforces strict formatting standards, and runs entirely within the browser. It scales from single-page dashboards to recurring extraction workflows without infrastructure overhead.