fix(file-parsers): read side-by-side calendar grids one block at a time

[waleedlatif1]

Summary

• pdf.js streams text in draw order. When a page puts grids side by side (e.g. year-at-a-glance calendar months) and the producer draws one row across every grid, extraction came out interleaved — Su Mo … Sa Su Mo … Sa, then 1 2 3 1 2 3 4 … — so no date could be tied back to its month
• New pdf-layout.ts: groups a page's items into rows, finds bands split by a wide whitespace gutter (1-level XY-cut), and emits each block top to bottom only when all of these hold:
  • every block is a grid cut from one template: same header row near its top (Su Mo Tu We Th Fr Sa), same width and inner column positions
  • the gutter is ≥ 2× any column gap inside the blocks
  • a plain column is allowed only when sparse (a legend); one spanning the band means it's a table
  • the stream actually interleaves the blocks — pages already drawn block by block are untouched
• Everything else (tables, prose, forms, math) keeps stream order exactly as before; reordered bands are spliced back in at their stream position
• Layout analysis buffers up to 20k items per page, then falls back to streaming, so pathological pages cost the same as today
• joinLines treats a reordered block's first line as a paragraph start and no longer rejoins across block boundaries via the wrapped-table-cell lookahead

Type of Change

• Bug fix

Testing

• Unit tests for calendars, legends, account boxes, and the negative cases (evenly spaced tables, label/value lists, wrapped-cell tables, column groups with different shapes, value grids without headers, already block-ordered streams, missing geometry, item cap); end-to-end test through real pdf.js with a pdf-lib calendar. Verified the positive tests fail with the reordering disabled
• Before/after benchmark on 264 real PDFs (94 from the pinned parser-eval corpus + 170 assorted real-world docs): output byte-identical on 263; the one change is a Fed paper whose three side-by-side balance-sheet boxes now read box by box instead of interleaved. 22 real public calendar PDFs of other layouts (month-per-column, month-per-row) are unchanged
• Latency: total 22.2s → 22.7s (+2.2%), median 18 → 18 ms, p99 809 → 816 ms
• Earlier iterations of the heuristic (gutter-only, then structure-only, then header-only) each changed 3–70 real documents for the worse (transposed tables, scrambled equations) — the combined gates above are what got it to zero regressions
• Precedent: XY-cut / whitespace-gutter projection is the standard rule-based reading-order method (pdftotext, pdfminer layout analysis, PyMuPDF's column-boxes recipe); keeping content-stream order by default matches PyMuPDF, pdfplumber use_text_flow, and pdf.js itself
• bun run lint, check:audits (49), docs-manifest:check, type-check, file-parser suite (508) all pass

Already-indexed documents need a re-sync to pick this up. Markers drawn as filled shapes (not text) are still not recoverable from the text layer.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
docs	Skipped		Sep 24, 2026 4:27pm UTC

[cubic-dev-ai]

All reported issues were addressed across 5 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; no outstanding finding or new issue was identified.

Summary

The PR adds conservative layout detection so interleaved side-by-side PDF grids are read block by block, while other content retains stream order.

• It buffers pages up to an item cap and falls back to streaming beyond it.
• It adds block-boundary handling to line joining and unit and PDF integration tests.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Collect PDF page items] --> B{Item cap exceeded?}
  B -- Yes --> C[Stream in draw order]
  B -- No --> D[Group rows and find gutter bands]
  D --> E{Congruent grids with shared headers and interleaved stream?}
  E -- No --> C
  E -- Yes --> F[Emit each block top to bottom]
  F --> G[Mark block boundaries for line joining]

Loading

_{Reviews (6) · Last reviewed commit: "fix(file-parsers): match multi-word head..."}

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 6 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 6 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

1 issue found across 6 files

Confidence score: 3/5

• In apps/sim/lib/file-parsers/pdf-layout.ts, the page-wide tolerance can merge distinct rows in compact, smaller-font grids, causing joined or interleaved output; review row grouping against local item geometry.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/sim/lib/file-parsers/pdf-layout.ts">

<violation number="1" location="apps/sim/lib/file-parsers/pdf-layout.ts:412">
P2: This page-wide tolerance can merge distinct rows in a compact, smaller-font grid; `emitBlock` then joins those rows with spaces, or the grid fails detection and remains interleaved. Base row grouping on local item and row heights so its tolerance matches block emission.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 6 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 6 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}