Stop Auto-Detecting PDF Columns. Use a Zone Model Instead.

TLDR

Relying on X-coverage histogram auto-detection (_detectPageColumns) creates fragile layout failures when BOX regions claim text items before column detection executes or when wide section headers bridge column gaps. Storing explicit zone definitions in HTML data attributes (data-zones='[{"y0":0,"y1":180,"cols":2}]') allows deterministic layout rendering and user-driven toolbar editing without re-running extraction algorithms.

Layout Approach	Configuration Storage	Multi-Column Auto-Recovery	User Customization
X-Coverage Histogram	Implicit / Inferred runtime	Fragile (Fails on BOX claims)	None
Explicit Zone Model	data-zones HTML JSON	100% Deterministic	1 to 4 Column Toolbar Cycling

---

Technical architecture & implementation

1. Explicit zone data attributes

Store explicit Y-ranges and column counts directly on page section container elements:

<!-- Explicit Zone Layout Metadata Attributes -->
<section class="pdf-page-content"
         data-page="3"
         data-page-width="918"
         data-zones='[{"y0":0,"y1":180,"cols":2},{"y0":180,"y1":320,"cols":1},{"y0":320,"y1":99999,"cols":2}]'>
  <!-- Rendered Zone Containers -->
</section>

---

2. User-Driven zone rebuilding engine

Cycle zone column counts (1 to 4) using linear division math without viewport calculations:

// Rebuild zone column groupings using explicit X-ratio division
export function applyZoneColumnShift(zoneElement, newColCount, pageWidth) {
  const regions = Array.from(zoneElement.querySelectorAll('.pdf-region'));
  const colGroups = Array.from({ length: newColCount }, () => []);
for (const region of regions) {     const rx = parseFloat(region.dataset.rx || 0);     // Assign column index using pure ratio division: rx / pageWidth * cols     const colIndex = Math.min(Math.floor((rx / pageWidth) * newColCount), newColCount - 1);     colGroups[colIndex].push(region);   }
// Re-render DOM containers using updated column groups   renderUpdatedZoneGrid(zoneElement, colGroups, newColCount); }

Rule of thumb: Store explicit zone definitions in data-zones HTML attributes to provide user-driven layout editing and deterministic document export.