DEV Community: Bonzai2Carn

Why Web Workers Swallow Your Stacktraces (And How to Write Specs to Fix It)

Bonzai2Carn — Tue, 07 Jul 2026 14:30:00 +0000

TLDR: A spec that says "the function checks r.bbox.x < pageWidth / 2" without saying where pageWidth comes from is not a spec. It is a description of behavior with a hidden dependency. Every architecture document I have written with that pattern has produced at least one ReferenceError in implementation.

The Pattern That Keeps Failing

Architecture documents are good at describing what code should do. They are bad at describing where values come from and which function boundaries they cross.

The page assembly refactor spec said:

Check for FEATURE_LAYOUT: 2 cols, left is all visual, right is text. Compare each region's r.bbox.x against pageWidth / 2.

That is a correct behavioral description. It says nothing about execution context. The implementer writes it into _detectAutoZones, a module-level function, and references pageWidth by name. The spec did not say pageWidth needed to be passed as a parameter. The spec did not say _detectAutoZones was a module-level function. Both facts were implicit.

The result: ReferenceError: pageWidth is not defined on every PDF load, with a stacktrace that points at the worker message handler instead of the actual line.

Why This Keeps Happening

Architecture documents are written in prose. Prose does not have a type system. A sentence like "the function uses pageWidth" can mean:

The function receives pageWidth as a parameter.
The function reads pageWidth from a module-level variable.
The function is nested inside a caller that defines pageWidth and closes over it.
The function reads pageWidth from an object passed in.

All four are syntactically valid JavaScript. The prose does not distinguish between them. The implementer picks one and moves on.

When the spec is written by the same person who will implement it, option 3 is tempting because it is the least-friction path. The value is just "there" without needing to thread it through function signatures. It works when the function is actually nested. It throws when the function ends up at module level for any reason (extracted for reuse, moved for readability, placed outside the call site by default).

What Correct Specs Look Like

A spec that is actually implementable names the function signature:

_detectAutoZones(regions, numCols, pageWidth): pageWidth is viewport.width || 612, passed from assemblePage.

That is two extra words. It removes all ambiguity. The implementer knows the parameter needs to exist. The reviewer can check that the call site passes it. The bug does not happen.

The discipline: any time you write "the function uses X" in an architecture document, immediately write where X comes from. If it is a parameter, name it in the signature. If it is a module constant, name the constant. If it is a derived value, show the derivation.

The Stacktrace Problem

ReferenceErrors in Web Workers have a specific failure mode: the worker's error handler catches the error, serializes err.message (a string), and posts it to the main thread. The stack is not forwarded. The main thread reconstructs a new Error from the message string and throws it. DevTools shows the main thread throw, not the worker's.

This means a ReferenceError in a worker looks like an error in the worker message handler, not in the actual throwing function. The real location is invisible. You find it by grepping for the identifier named in the error message.

This is a general problem with any architecture that serializes errors across execution boundaries (workers, iframes, service workers, error-catching middleware). The message string is preserved. The stack is not. Every ReferenceError in such a system requires a grep rather than a stacktrace to locate.

The Uncomfortable Implication

If your architecture document has not specified where every value used by every function comes from, your implementation will have bugs that grep finds faster than debuggers. That is not a criticism of the implementer. It is a criticism of the spec.

The solution is not more thorough prose. It is specifying function signatures explicitly, the same way you would in TypeScript or a statically-typed language. Write the types. Write the parameter names. Write where the values come from. Three lines of explicit signature beats three paragraphs of behavioral description every time.

Web Components vs. Iframes: A Hard Lesson in DOM Isolation Barriers

Bonzai2Carn — Sat, 04 Jul 2026 14:30:00 +0000

TLDR

A custom element that fetched a canonical app's HTML and swapped document.body.innerHTML looked clean on the surface. It worked until it didn't: the swap raced with the existing app's event handlers, producing a tool that rendered correctly but did nothing. The correct pattern, an iframe pointing at the canonical URL with ?view=, was already in use by the VS Code extension. It took three weeks to apply the same answer to the web.

Ginexys

The Assumption That Seemed Reasonable

Ten SEO landing pages need unique <head> metadata but should load the same tool. A custom element that fetches the canonical tool HTML and injects it into the current page would deduplicate the tool code while keeping per-page metadata. One component, ten thin wrapper pages. Fewer moving parts.

How It Broke

The custom element ran document.body.innerHTML = canonicalBody.innerHTML. This replaced the body after the scripts that loaded the tool had already attached their event handlers to the original DOM.

The app init pattern was DOMContentLoaded → attach handlers → ready. After the innerHTML swap, the DOM the handlers were attached to was gone. The new DOM from the canonical body had no handlers attached. Sometimes the app's deferred script loaded against the old body and ran to completion. Sometimes it ran against the new body. Sometimes it ran twice. The outcome was non-deterministic.

Symptoms: tabs switched. File dialogs opened. Buttons were visually interactive. But clicking "process file" extracted nothing. Clicking "export" produced nothing. Clicking a gated feature opened nothing. No console errors. Everything looked correct and did nothing.

Why It Was Hard to Find

The canonical URL was always used for testing. /tools/pdf-processor/ loaded fine, worked correctly, passed every test.

A Vite plugin had been added to redirect the root canonical URL to /editor/ to prevent a PDF.js worker from hitting the root URL and receiving HTML instead of JavaScript. This redirect routed all user traffic through the wrapper. The standalone test path stopped existing. The bug only appeared on the path users actually took, and that path looked correct visually.

What Was Thrown Away

Three web component files, 8KB of code. The approach was not wrong in principle. It was wrong for an app that does imperative DOM initialization. A custom element that injects static HTML into a page is fine. A custom element that injects a running app into a page, with scripts that have already begun attaching handlers, is not.

Also discarded: the assumption that "deduplicate HTML" means "inject HTML". Deduplication of a running app means isolation, not injection.

What Replaced It

Each SEO landing page became a thin HTML with unique metadata and a single full-viewport iframe:

<iframe src="/tools/pdf-processor/?view=editor"
        style="width:100%;height:100vh;border:none;"
        allow="..."></iframe>

The canonical app loads inside its own document. Its scripts initialize against its own DOM. Nothing races. The ?view=editor query parameter activates the right tab. No DOM swap, no event handler collision.

The VS Code extension had been doing this correctly since the beginning: load the canonical index.html into a webview, inject a global for mode selection, let the app init normally. Three weeks later, the web followed the same pattern.

The Lesson

When you need to embed an app inside another document, use an isolation boundary that the browser already provides. The iframe is the answer. Web components are for components, meaning UI elements that render within the host document's DOM. An existing running app with its own initialization sequence is not a component. Load it at its own origin and talk to it via postMessage or URL parameters.

The sign that you are solving the wrong problem: when your custom element needs to replace document.body.innerHTML, you are trying to do iframe isolation without the isolation.

Seven Table Parsers, One Interface: Designing a Table Formatter and Node Editor (TAFNE)

Bonzai2Carn — Thu, 02 Jul 2026 14:30:00 +0000

Table Formatter
Repo

The first question most people ask when they see TAFNE accept HTML, CSV, TSV, Markdown, JSON, ASCII art tables, and SQL INSERT statements from the same input field is: how does it know which one you pasted?

The short answer: it doesn't always. You tell it. Or the file extension tells it. Or for unknown text files, it makes a content-based guess.

The longer answer is that each of these seven formats requires a genuinely different parsing approach, and the differences are interesting.

The Dispatcher

The entry point is a switch statement in parseInput():

switch (inputType) {
    case 'html':     tableHtml = parseHtmlInput(inputData); break;
    case 'ascii':    tableHtml = parseAsciiInput(inputData); break;
    case 'csv':      tableHtml = parseCsvInput(inputData); break;
    case 'text':     tableHtml = parseTextInput(inputData); break;
    case 'markdown': tableHtml = parseMarkdownInput(inputData); break;
    case 'json':     tableHtml = parseJsonInput(inputData); break;
    case 'sql':      tableHtml = parseSqlInput(inputData); break;
}

Every branch takes the same input: a raw text string. Every branch produces the same output: an HTML table string. What happens in between is completely different.

Two Parsing Strategies

The seven parsers split into two fundamental camps.

Semantic parsers rely on explicit structure. The format declares its own structure using tags, keys, or reserved keywords. The parser just has to read that declaration.

Heuristic parsers rely on pattern recognition. The format is a convention, not a formal specification. The parser makes educated guesses based on what it sees.

HTML and JSON are semantic. CSV, TSV, and ASCII are heuristic. Markdown and SQL sit in the middle.

The Semantic Parsers

The HTML parser uses a regex to find table elements:

const tablePattern = /<table[\s\S]*?<\/table>/gi;
const matches = html.match(tablePattern);

The structure is already there. The parser's job is to extract and normalize it, not reconstruct it.

The JSON parser reads explicit keys and values:

let data;
try { data = JSON.parse(json); } catch (e) { ... }
const headers = Object.keys(data[0]);

The column names are the object keys. The rows are the array elements. No guessing involved. If the input is valid JSON, the structure is unambiguous.

The JSON parser also handles a common real-world case: JSON that wraps the array in an outer object. If JSON.parse returns an object rather than an array, the parser looks for the first key whose value is a non-empty array:

const arrayKey = Object.keys(data).find(k => Array.isArray(data[k]) && data[k].length > 0);
data = arrayKey ? data[arrayKey] : [];

This handles API responses that return { "results": [...] } or { "data": [...] } without requiring the user to drill into the JSON manually.

The Heuristic Parsers

The CSV parser assumes commas separate columns and newlines separate rows. That's it.

const cells = line.split(',').map(cell => cell.trim().replace(/^"|"$/g, ''));

Quotes are stripped from around cells. The first row is assumed to be headers. This works for the vast majority of real CSV files, but it will fail on CSV files that contain commas inside quoted fields (a common edge case in RFC 4180-compliant CSV). The current parser treats every comma as a delimiter regardless of quoting context. For most practical use cases, this is fine.

The ASCII parser skips separator lines:

if (line.includes('+---') || line.includes('+===')) return;
const cells = line.split('|').filter(cell => cell.trim());

ASCII tables use +---+---+ for horizontal separators and | val | val | for data rows. The parser identifies separators by looking for the +--- pattern, skips them, and splits data rows on pipes.

The State Machine: Markdown

Markdown tables have three types of lines: the header row, the separator row, and data rows. The separator row is syntactically distinct but carries no data.

if (/^\|?[\s|:\-]+\|?$/.test(line)) return; // separator

const headerDone = false;
// ...
tableHtml += headerDone ? `<td>${cell}</td>` : `<th>${cell}</th>`;
headerDone = true;

The headerDone flag is a minimal state machine. Before processing the first data row, cells become <th>. After, they become <td>. The separator line is identified by a regex that matches lines containing only pipes, spaces, colons, and dashes.

The Hunter: SQL

The SQL parser is the most technically specific. It uses a capturing regex to scan for INSERT statements:

const insertRe = /INSERT\s+INTO\s+\S+\s*\(([^)]+)\)\s*VALUES\s*\(([^)]+)\)/gi;
let match;
while ((match = insertRe.exec(sql)) !== null) {
    if (!headers) {
        headers = match[1].split(',').map(c => c.trim().replace(/[`"']/g, ''));
    }
    const vals = match[2].split(',').map(v => v.trim().replace(/^'|'$/g, ''));
    rows.push(vals);
}

The exec method called in a loop advances the regex cursor after each match. Column names come from the first match's first capture group. Values come from every match's second group.

Single quotes around values are stripped. Escaped single quotes ('') are converted back to single quotes. The result is clean cell values, one row per INSERT.

Auto-Detection for File Loads

When a file is loaded instead of pasted, the format is detected from the extension. For .txt files and unknowns:

if (text.includes('\t')) {
    tableHtml = parseTextInput(text);
} else if (text.includes(',')) {
    tableHtml = parseCsvInput(text);
} else {
    tableHtml = parseTextInput(text);
}

Tabs win over commas. If neither is present, the tab-delimited parser handles it anyway, which will at least produce a single-column table from the line breaks.

Seven formats. One interface. The parsers are the wall between "raw text someone pasted" and "a table you can edit."

Source: github.com/carnworkstudios/TAFNE

Why We Treat HTML as a CAD Format for PDF (And Why It Works)

Bonzai2Carn — Tue, 30 Jun 2026 04:00:00 +0000

Most PDF-to-HTML tools stop at extraction. You get a dump of text, maybe some tables, and a "download HTML" button. That's the end of the story.

We didn't stop there. And the reason is simple: extracted HTML is not a document you're done with. It's a document you're about to edit.

PDF Processor
Repo

The problem with "extracted output"

When you extract a PDF, you get a structural snapshot of the original. That snapshot is close to what you want, but rarely exactly what you want. Tables have merged cells that should be split. Headings got classified as paragraphs. A two-column layout that made sense in print looks wrong on a screen. A numbered list starts at 3 because the PDF had a callout box in between.

Most tools hand you this output and say: open it in Word, fix it there.

That's a context switch. Every context switch is friction. Friction compounds.

HTML is already a spatial document format

Here's what most people don't realize: HTML rendered in a browser is a box model. Every element (every heading, paragraph, table, callout) is a box with dimensions, position, and CSS-computed layout. The browser calculates all of this automatically.

That box model is essentially a CAD coordinate system. You already have:

Positioned containers (zones, columns, regions)
Reflowable layout (CSS Grid)
Semantic element types (headings, paragraphs, lists, tables)
A full editing surface (contenteditable)

What was missing was the interaction layer to treat it like one.

Two modes, one surface

The Doc tab in Ginexys PDF Processor has two modes on the same surface:

Edit Mode: the existing contenteditable surface. Click into text, type, use the formatting toolbar. The browser handles all the text editing mechanics. This is what you use when you're making content corrections.

Selection Mode: a layout editing layer. Click "Select" in the toolbar. Now every extracted zone and region gets a drag handle. You can:

Drag zones to reorder sections of the page
Drag individual regions (headings, paragraphs, tables) within or across zones
Marquee-select multiple regions and group them into a new zone
Right-click any element and choose "Edit Code" to see and edit its raw HTML in a Monaco editor

Switch back to Edit Mode with the same button. The two modes share the same DOM, with no conversion and no re-render.

Why not absolute positioning?

The obvious CAD metaphor is Figma: drag elements freely, place them anywhere. We explicitly chose not to do this.

The reason is that our output is HTML, and HTML in a browser is a flow document. Absolute positioning breaks that. An absolutely-positioned element is outside the flow: it doesn't affect other elements, doesn't respond to container resizes, and doesn't export correctly to Markdown or XML or DOC.

Drag-to-reorder in document flow is more useful than drag-to-anywhere. You're reorganizing a document, not designing a poster.

Edit Code: the escape hatch

Every extracted element has a "Edit Code" option in the right-click menu. This opens a Monaco editor dialog with the element's raw outerHTML. You can:

Add a CSS class
Change the tag from <h4> to <h3>
Rewrite a paragraph's content entirely
Fix a table cell that parsed incorrectly
Add an attribute

Click Apply. The element is replaced in the live DOM. The change propagates to the Monaco source editor and the Visual Diff tab automatically.

This is the escape hatch that makes the higher-level tools trustworthy. If the drag handles can't express what you need, the code editor can.

The export chain closes the loop

Selection Mode and Edit Code aren't decorative. Every change you make in the Doc tab flows through the same sync coordinator (applyHtmlEverywhere) that the Monaco source editor uses. When you export:

HTML: the edited DOM, with images inlined as base64
Markdown: converted from the live DOM structure (real GFM: pipe tables, ### headings, - bullets)
XML: semantic tree (<heading level="3">, <table><row><cell>)
DOC: Office Open XML envelope, opens in Word/LibreOffice/Google Docs
PDF: browser print dialog, scoped to the Doc content

What you see is what you export.

SiaS: the tool works without the service

This is the SiaS (Software-in-a-Service) model applied. The offline tool, which includes geometry extraction, Doc editing, Selection Mode, Edit Code, and all five export formats, works entirely without an account, without a server, without any network connection.

The AI layer (Docling-powered extraction, GINEX schema analysis) sits on top. It makes the tool smarter. But the tool is already useful without it.

The CAD layer is part of the base tool. It always will be.

Ginexys PDF Processor is available at ginexys.com. Free, offline, no account required.

Debugging Mobile Drag & CSS Specificity in a Real-Time PDF Diff Tool

Bonzai2Carn — Sat, 27 Jun 2026 14:30:00 +0000

TLDR: Three UI problems, three different root causes. The column detection fix was algorithmic. The mobile drag was an axis-detection oversight. The CSS specificity bug was a cascade law I already know but applied wrong under time pressure.

PDF Processor
Repo

What We Set Out To Do

Four tasks entered this session:

Fix raiko-aistats: 0 column splits on all 9 pages of a two-column LaTeX PDF.
Fix visual-diff mobile drag: stacked layout (< 1024px) used horizontal clientX even though the divider was now vertical.
Add touch support to the compare diff resizer: mouse-only, no mobile drag.
Redesign the diff tab chrome: two rows of controls eating 82px before any content appeared.

The column detection fix was already covered in its own post-mortem. This one is about everything else.

The Mobile Drag Problem

The visual-diff layout switches to flex-direction: column at 1024px. The original initDividerResize() always read clientX and called outerWidth() on the first pane. Neither is meaningful when the axis is vertical.

The fix sounds simple: detect which axis the layout is using. The trap was how to detect it. You cannot use a window width check because the breakpoint is a CSS media query and can be overridden. The correct source of truth is:

getComputedStyle($layout[0]).flexDirection === 'column'

Computed style reads what CSS actually applied, not what the JavaScript thinks the breakpoint should be. This check runs at drag start, not at init, so it handles viewport resizes between page load and drag attempt.

The same pattern drives cursor choice: row-resize vs col-resize, and whether to write flex: 0 0 ${topPct}% to height or width.

The Diff Tab Redesign

Two problems with the original design:

Two separate rows of controls (mode tabs + a toolbar row) consumed ~82px before any content.
The layout and precision controls were visually grouped but semantically separated.

The redesign collapses everything into a single 36px bar. Three pill groups (Rich/Plain, Split/Unified, Word/Char) sit left-aligned in a flex row. Stats (N added, N removed) sit right-aligned. The pill group uses a container background with a raised active-pill shadow, which is the standard segmented control pattern.

This required no HTML restructuring of the diff panels themselves. Only the chrome above them changed.

The CSS Specificity Disaster

After the redesign, #view-diff started rendering on top of every other tab. The panels were supposed to be display: none when inactive. The diff panel was always visible.

Initial read of the user's report: "It's not the height. It's either you rename it view-diff where the name that is being referred to is probably compare-diff or something like that."

That sentence is about an ID mismatch hypothesis. I checked the IDs. They matched. The real culprit was in the CSS cascade.

The .view-panel rule sets display: none on all panels. A later rule .diff-layout set display: flex. These are both single-class selectors with equal specificity. Source order breaks the tie. .diff-layout appears later in the file. It wins. Every .view-panel.diff-layout element gets display: flex whether it is the active tab or not.

The fix is two characters wide: add .view-panel to the diff-layout rule.

/* Before: overrides display:none for all panels */
.diff-layout {
    display: flex;
    flex-direction: column;
}

/* After: only sets flex direction, never fights display:none */
.view-panel.diff-layout {
    flex-direction: column;
}

Two-class specificity (0,2,0) beats the single-class .view-panel rule (0,1,0), so the active-tab rule wins when it needs to. The inactive tabs keep display: none.

What Failed

Wrong hypothesis first. The user's wording pointed toward an ID mismatch. I checked IDs first. That was the wrong tree. The cascade investigation was second. In hindsight: "always visible" is a specificity smell, not a naming smell.

The display: flex on a layout helper class. Adding layout properties to a semantic class that gets applied alongside view-panel is the setup for this exact problem. A layout class should set layout properties (direction, wrap, gap). It should not set display unless it is the element that owns the display decision. .view-panel owns the display decision here. .diff-layout does not.

What Survived

Pill group segmented controls are a permanent pattern in this codebase now.
Axis-detecting drag via getComputedStyle is the correct approach for responsive dividers.
Touch support via { passive: false } and e.touches?.[0] ?? e is now consistent across both dividers.

The session closed with a clean build. The four items that entered finished as fixed.

Under the Hood: Drag, Touch, and CSS Cascade in a Real Diff UI

Bonzai2Carn — Thu, 25 Jun 2026 14:30:00 +0000

TLDR: Three interconnected UI problems reveal how layout-aware drag detection, unified touch/mouse event handling, and CSS specificity interact when you redesign a panel that lives inside a visibility-toggled tab system.

Schema Editor
Repo

The Responsive Drag Problem

The visual-diff layout uses flex-direction: row on wide screens and flex-direction: column on mobile (< 1024px). The divider between the two panes needs to do different things depending on which axis is active.

Naive approach and why it fails

A window-width check:

if (window.innerWidth <= 1024) { /* vertical */ } else { /* horizontal */ }

This breaks if the user resizes the window after the divider was initialized. It also breaks if the breakpoint is overridden by a more specific CSS rule. Window width is not the source of truth here. CSS is.

Correct approach: read computed flex direction

function isStacked() {
    return getComputedStyle($layout[0]).flexDirection === 'column';
}

getComputedStyle returns the resolved value after all cascades and media queries have applied. Reading it inside startDrag() means it reflects the layout at the moment the user puts a finger or pointer on the divider, not the layout at page load.

Unified event position extraction

function getEventPos(e) {
    const src = e.touches?.[0] ?? e;
    return isStacked() ? src.clientY : src.clientX;
}

Mouse events and touch events have the same coordinate fields once you extract the first touch from the list. The optional chaining ?.[0] safely returns undefined for mouse events, which then falls through to ?? e (the event itself). This is equivalent to a ternary but shorter and avoids importing lodash or a touch-helper library.

Dimension tracking

At drag start, capture the current first-pane dimension:

const $first = $layout.find('.vd-pane').first();
startSize = isStacked() ? $first.outerHeight() : $first.outerWidth();

During drag, compute the new size clamped to a min and max to prevent panes from collapsing:

const totalH = $layout.outerHeight();
const newH = Math.max(120, Math.min(totalH - 120, startSize + delta));
const topPct = (newH / totalH) * 100;
$panes.eq(0).css('flex', `0 0 ${topPct}%`);
$panes.eq(1).css('flex', `0 0 ${100 - topPct}%`);

Using flex: 0 0 N% instead of width: N% or height: N% works on both axis orientations because the flex shorthand sets the flex-basis. The browser maps flex-basis to the main axis automatically, using width in row layouts and height in column layouts.

Touch Event Registration

The dragging pattern requires three event pairs:

Phase	Mouse	Touch
Start	`mousedown`	`touchstart`
Move	`mousemove`	`touchmove`
End	`mouseup`	`touchend`

Why `{ passive: false }` matters

The browser defaults touchmove to passive to enable smooth scrolling. A passive listener cannot call e.preventDefault(). Without preventDefault() on touchmove, the browser scrolls the page instead of running the drag handler.

Registering touch events with { passive: false } tells the browser this listener may prevent default:

$divider[0].addEventListener('touchstart', startDrag, { passive: false });
document.addEventListener('touchmove', doDrag, { passive: false });
document.addEventListener('touchend', endDrag);

Note: touchend does not need { passive: false } because we never prevent default on it.

Why touchmove goes on document, not the divider

If the user's finger moves faster than the browser can process drag events, the pointer position can leave the divider element. If the listener is only on the divider, you lose the event mid-drag. Attaching touchmove and touchend to document ensures the drag completes correctly even if the pointer drifts off the handle.

The Diff Tab CSS Architecture

The 36px diff bar

The original diff chrome had two rows: a tab row (Rich/Plain) and a toolbar row (Split/Unified, Word/Char, stats). Total height: ~82px.

The redesign collapses this into a single div.diff-bar at height: 36px. The bar is a flex container:

.diff-bar {
    display: flex;
    align-items: center;
    justify-content: space-between;
    height: 36px;
    flex-shrink: 0;
    background: var(--toolbar-bg);
    border-bottom: 1px solid var(--border-dark);
}

flex-shrink: 0 prevents the bar from compressing when the diff workspace below it is larger than the available height. height: 36px is an explicit ceiling, not min-height, because the bar should never grow.

Pill group segmented control

.diff-pill-group {
    display: flex;
    align-items: center;
    background: var(--border);
    border-radius: 6px;
    padding: 2px;
    gap: 1px;
}
.diff-pill {
    height: 22px;
    padding: 0 8px;
    border-radius: 4px;
    background: transparent;
    color: var(--text-muted);
    font-size: 11px;
    font-weight: 500;
    transition: background .1s, color .1s;
}
.diff-pill.active {
    background: var(--surface);
    color: var(--accent-dark);
    box-shadow: 0 1px 3px rgba(0,0,0,.10);
}

The container background: var(--border) serves as the "track" color. The active pill lifts out of it with background: var(--surface) and a shadow. This is the same pattern Apple uses for segmented controls in UIKit: it reads as a single control, not a group of buttons.

The Specificity Bug

Setup

The tab visibility system works like this:

/* line ~645 in styles.css */
.view-panel {
    display: none;
}

/* active panel overrides per JS */
.view-panel.active {
    display: flex;
}

The diff layout helper class was added to make the diff panel a column-direction flex container:

/* line ~888 in styles.css: WRONG */
.diff-layout {
    display: flex;
    flex-direction: column;
}

Why it overwrote `display: none`

CSS specificity score for .view-panel is (0, 1, 0). CSS specificity score for .diff-layout is (0, 1, 0). Equal specificity. Source order breaks the tie. .diff-layout appears later in the file. It wins. Every element with class diff-layout gets display: flex regardless of any earlier display: none.

Fix

/* CORRECT */
.view-panel.diff-layout {
    flex-direction: column;
}

Two-class specificity score is (0, 2, 0). This beats the single-class .view-panel rule when both apply. More importantly: removing display: flex from this rule means it never fights the visibility system at all. .view-panel.diff-layout now only sets direction, which does nothing unless the element is already displayed.

The .view-panel.active rule (also (0, 2, 0)) fires when JS adds the active class and sets display: flex correctly. Source order then resolves the two (0, 2, 0) rules in favor of .active because it was written after .view-panel.diff-layout.

The lesson

Layout helper classes should not set display. The element that controls visibility owns the display property. A class that sets layout direction on a visibility-toggled element must either match specificity exactly or remove display from its rule.

Most PDF Extractors Use the Wrong API: Here’s What We Built Instead

Bonzai2Carn — Tue, 23 Jun 2026 14:30:00 +0000

TLDR: PDF.js exposes three data sources at three fidelity levels. The industry default is the one that was built as a convenience wrapper for the other two. This is not laziness, because there are real reasons it happened, but it is the root cause of why most frontend PDF extraction breaks on academic papers, publications, and anything that isn't a corporate report.

PDF Processor
Repo

The Hierarchy Nobody Talks About

When people say "PDF extraction," they mean getTextContent(). Text items, positions, advance widths. This is what pdfplumber, PyMuPDF, pdf-parse, and almost every browser-side PDF tool reads.

Here is what getTextContent() actually is: a derived, post-processed view of getOperatorList(). PDF.js collects text paint operators from the raw operator stream, applies the current CTM, and packages the results. It is not reading a different part of the PDF. It is giving you a processed version of data that is already available in a more complete form.

Above that: getStructTree(). Not derived from the paint stream at all. It reads the logical structure tree from the PDF cross-reference table. Tables, paragraphs, headings, figures, formulas. Every glyph run tagged with its semantic role, linked to the paint stream via Marked Content IDs.

The hierarchy is:

getStructTree()     # what the document means
getOperatorList()   # what the document draws
getTextContent()    # a filtered view of what the document draws

Most tools use the third one.

Why This Happened

There are real reasons getTextContent() became the default:

It is good enough for 80% of documents. Corporate reports, legal briefs, and simple technical manuals have straightforward text flows. getTextContent() gives you positioned text items and that is enough to reconstruct paragraphs and headers.

The struct tree is frequently wrong. Word exports tag table cells as <P>. InDesign creates arbitrary nesting that reflects layer creation order, not reading order. A tool that trusts the struct tree on arbitrary input will fail on a significant fraction of documents.

The MCID join is not automatic. PDF.js does not give you "text item → struct tree node" in one call. You have to walk the operator list, maintain a MCID stack at each BMC/BDC open/close, record the current MCID for each text paint op, and join that to the struct tree. That is non-trivial to implement correctly.

Toolchain inertia. PDFBox, pdfminer, and the other foundational tools are 10–15 years old. They prioritized the text content API. Everything built on top of them inherited the same priority.

These are valid reasons. They are also not the same as "getTextContent() is correct."

What You Miss

When you use only getTextContent(), you miss:

Table structure. The struct tree gives you Table → TR → TD directly. getTextContent() gives you positioned text items that happen to be inside table cells. You have to infer the table grid from item positions, which requires heuristics, thresholds, and fails on borderless tables.

Display-math blocks. LaTeX equation environments produce glyph runs that PDF.js collapses into single items in getTextContent(). The full equation arrives as one item whose width spans the display block. Individual characters are not surfaced. Trying to detect column boundaries on a LaTeX paper using item X-extents will find that display equations bridge every candidate column gap.

Column geometry. Multi-column layouts in publishing tools often include explicit vertical rules, which are path operators drawing a line at the column boundary. These are in getOperatorList(). They are not in getTextContent(). Column detection from text positions is an inference. Column detection from an explicit vertical rule at the same X is a fact.

Reading order. getTextContent() returns items in paint order, not reading order. For a 2-column document, that might be reading order, or it might not, depending on how the PDF was authored. The struct tree, for well-tagged documents, returns leaves in reading order by design.

The Cascade Is Not Optional

The correct architecture is a cascade:

Try getStructTree(). If table regions are present, extract them directly. No column detection needed.
Try getOperatorList() geometry: full-height vertical rules, clip stack. If column rules are present, use them directly. No text-based inference needed.
Fall through to getTextContent() with geometric inference (bipartite partition, stream detection). This is correct for untagged documents with minimal path geometry.

This is not three times the work. Tiers 1 and 2 are fast exits. If the struct tree has tables, you skip all the geometry inference for those zones. If a vertical rule is present, you skip the bipartite algorithm. The fallback (Tier 3) only runs when no higher-fidelity signal is available, which is most documents today, but not most well-authored documents.

The Uncomfortable Part

Running the cascade as a diagnostic on three test PDFs found that all three PDFs fall through to Tier 3. No struct tree, no vertical column rules, in any of them.

This could be read as: the cascade doesn't help for documents people actually use.

The correct reading is: the test suite is three PDFs, and all three happen to be untagged. Amazon earnings releases, Siemens engineering manuals, and LaTeX preprints produce no struct tree output by default. But a PDF exported from Microsoft Word with the "Create bookmarks" option, or from Adobe Acrobat with the accessibility features enabled, or from InDesign with the tagging export, all produce struct trees.

The cascade will be exercised when the document population expands. The diagnostic confirms the fallback is correct. The architecture is in place. The next step is the display-math filter: two lines in the fallback scan that make the LaTeX failure case work without touching anything else.

Why Splitting a 2,500-Line File Broke Our Architecture

Bonzai2Carn — Sat, 20 Jun 2026 14:30:00 +0000

TLDR

A single 2500-line index.html with all JS inline worked. Splitting it into modules surfaced three classes of bugs: arrow functions with broken $(this), initialization order errors from circular-looking imports, and implicit state dependencies that were invisible inside a shared closure. The bugs were not created by the split. They were revealed by it.

Schema CAD Editor

The Assumption That Seemed Reasonable

A large single-file codebase is a starting point. You iterate fast, everything is in one place, there are no import errors, no build steps. When the codebase is ready for production, you split it into proper modules. Splitting is a cleanup task, not a risky refactor.

This assumption is correct about the first part: monolith development is fast. It is wrong about the second: splitting is not cleanup. It is a refactor that must handle every bug the monolith hid.

When It Failed

The first failure was the trace wire button. The click handler used an arrow function with $(this):

$('#traceWireBtn').on('click', () => {
    const mode = $(this).data('mode'); // arrow function: 'this' is not the button
    self.setMode(mode);
});

In the monolith, $(this) in an arrow function refers to the outer this, which was the window-level module object. The data('mode') attribute happened to exist on the module object from a previous assignment. The handler worked.

After the split, the module object no longer had data('mode'). The attribute was on the button element. mode was undefined. The trace wire button silently did nothing.

The second failure was accordion panels. Their toggle logic was:

$('.accordion-header').on('click', function() {
    $(this).next('.accordion-body').slideToggle();
    // 'this' needed to be the clicked header
});

This used a regular function correctly. But the CSS for .active state was in a different section of the monolith that was moved to a separate CSS file during the split. The toggle added .active to the element; the CSS for .active was in a file that was not loaded at that point in the HTML. The panels visually appeared broken.

The third failure was theme initialization. The dark mode toggle set a class on document.body. After the split, the toggle module loaded before the theme initialization module. The theme module read localStorage.getItem('theme') and set the class. The toggle module read the current class from document.body to set its initial state. Because initialization order was not guaranteed, the toggle sometimes read the class before the theme module set it.

What Was Actually Wrong

Shared closure scope in the monolith masked three categories of problems:

this binding: Arrow functions used $(this) and happened to work because the outer this contained the expected data. The coincidence ended when modules changed what this referred to.
Load order: The monolith was a single script block. Everything initialized in order. Modules loaded in any order the HTML specified. Implicit dependencies on load order became explicit failures.
CSS scope: CSS was inline in the same file as the JS. After extraction to separate CSS files, rules needed to be included in the right order. Two rules in the monolith with accidental order-dependency broke when they were in different files with different load positions.

What Got Deleted

The monolith itself. 2500 lines of HTML/CSS/JS became 11 files: 2 CSS files and 9 JS modules organized into core/, canvas/, and features/ directories.

The deletion also cleared the test surface for the three bug classes: the broken arrow functions, the initialization race, and the CSS load-order issues were all visible and fixable once isolated into their own files.

What Replaced It

Module files with explicit exports and imports. Each module owns its state. Imports are explicit. The initialization order is determined by a top-level init function in core/svgEditor.js that calls each module's init in the correct sequence.

The arrow function handlers were converted to regular function declarations. The CSS was loaded in a fixed order by the HTML. The initialization race was resolved by explicit sequencing.

The Lesson

A monolith does not hide bugs by preventing them. It hides them by providing the environment they need to not manifest. When the environment changes (a module split), the bugs become visible. Splitting is not the cause. The delay is.

Building a High-Performance CAD Engine in Vanilla JavaScript (No Frameworks)

Bonzai2Carn — Thu, 18 Jun 2026 14:30:00 +0000

The modern web is built on frameworks. React, Vue, Svelte—they’ve made building UI easier, but they’ve also made us comfortable with a certain amount of "abstraction tax."

When I started building the Schema Editor, a browser-native tool for electrical and architectural schematics, I hit a wall with that tax almost immediately.

CAD tools are different from standard CRUD apps. You aren't just clicking buttons; you're manipulating thousands of SVG elements, running real-time pathfinding algorithms, and handling complex coordinate transformations (Tilt, Yaw, Perspective) all at once.

The Bottleneck of Re-rendering

In a framework-based app, state changes trigger a re-render. If I move a component in a diagram, I have to update its position, recalculate all its connected "Manhattan" wires, and re-draw the selection handles.

Doing this through a virtual DOM or a reactive dependency graph adds milliseconds of latency per frame. On a complex diagram, that’s the difference between 60fps and a stuttering mess.

The Solution: Direct DOM & Specialized Kernels

I decided to build the engine with Zero Dependencies. Just pure Vanilla JS and the SVG DOM.

Direct Manipulation: Instead of waiting for a framework to batch updates, we update SVG attributes (x, y, d) directly in the mousemove handler.
Spatial Indexing: To handle "hit detection" (knowing which wire you're clicking), we don't iterate through every element. We use a custom KD-Tree spatial index that allows us to query the canvas in O(log n) time.
Geometry Pipeline: We built a 4-phase geometry pipeline that handles everything from coordinate snapping to 3D perspective transformations before the data even touches the DOM.

The Result

The result is an editor that feels like a native desktop application. It’s light (under 100KB gzipped), starts instantly, and works perfectly on mobile browsers where CPU resources are limited.

It also makes the code incredibly approachable for contributors. You don’t need to learn a specific framework’s lifecycle or build system to add a new symbol to our Electrical, Software, or Construction kits. You just need to know JavaScript.

Join the Project

Schema Editor is free and open source. We're building a tool that respects the performance requirements of engineering while embracing the accessibility of the web.

Check out the code and the live demo here:
github.com/carnworkstudios/schema-editor

Stop Parsing PDFs at Render Time: A Better Architecture for Structured Extraction

Bonzai2Carn — Tue, 16 Jun 2026 14:30:00 +0000

TLDR: The reason most frontend PDF extraction is wrong is that developers try to infer document structure from the rendered visual output instead of from the operator stream. De Casteljau subdivision, pixel-based column detection, and raster-scan zone boundaries are workarounds for not reading the data correctly in the first place.

PDF Processor

The Industry Default Is Backwards

Here is what most frontend PDF tools do: render the page to a canvas at some scale, read text positions from getTextContent(), optionally run a computer vision model over the canvas, then try to infer whether those text positions form columns, tables, or lists based on pixel proximity.

This is backwards. The PDF already contains explicit structural information in the operator stream. The table you are trying to infer from pixel columns is drawn with literal path operators: moveTo, lineTo, rectangle, stroke. The zone boundaries you are trying to detect from text Y-positions are encoded in the CTM stack and fill operations. You are trying to reconstruct from the rendered artifact what was always explicit in the source.

The De Casteljau Example

I proposed de Casteljau subdivision for Bezier bounding boxes in my own architecture document and then rejected it during stress testing.

De Casteljau is a subdivision algorithm. You split the curve at its midpoint, recursively subdivide both halves, and stop when the control point hull is small enough. Then you use that hull as an approximation of the bounding box.

This is the right algorithm when you need to render the curve or find the nearest point on it. It is the wrong algorithm for bounding boxes because:

You choose a stopping tolerance. Too loose and the bbox is wrong for diagonal curves. Too tight and you recurse deeply on every curve, including simple arcs.
The segments you produce go through downstream filtering. A minLen guard eats the short segments from the recursion tail. Now your bbox is even more wrong.
There is no reason for any of this. The analytical solution is one application of the quadratic formula. It is exact. It does not recurse. It does not allocate segments.

The correct algorithm has been in every graphics textbook for 40 years. We still reach for subdivision because it feels intuitive: you can watch it work visually, you can tune the tolerance, it feels like you understand what it is doing. But "feels intuitive" is not a correctness argument.

The Zone Boundary Example

The page assembly design philosophy document I updated this session contains three zone detection bugs. One of them: _detectAutoZones computes zone boundaries as midpoints between yCenter values of adjacent region groups.

The yCenter of a region is the midpoint of its bounding box. The midpoint between two region yCenter values is some coordinate inside the gap between them, maybe. But a region's ry (used in the zone filter) is Math.round(region.yCenter), not the region's top edge. Sub-pixel rounding can place a region in the wrong zone.

The fix is simple: use bbox.y (the region's actual top edge) for zone boundaries, and compare against rBboxY (the region's top edge rounded to pixel) in the filter. Every region's top edge is the natural zone membership criterion, because it is where the region starts.

The midpoint heuristic exists because it sounds reasonable: "put the boundary halfway between the two groups." But zone membership should be determined by where content starts, not by a geometric midpoint between content centers. The former is structural. The latter is visual.

What the Correct Approach Requires

It requires reading the operator stream correctly, not just getTextContent(). It requires building a CTM stack and tracking matrix state per subpath. It requires classifying subpaths geometrically (RECT vs FREE_PATH) before doing any analysis. It requires emitting canonical segments with provenance, not just (x1, y1, x2, y2) tuples.

This is more work than pixel-based heuristics. But it produces deterministic output for the same PDF across renders, across scale factors, across pdfjs versions. Pixel-based output is not deterministic: it depends on anti-aliasing, subpixel positioning, font hinting.

A PDF extractor that gives you different columns on the same document at 100% and 150% zoom is not extracting structure. It is pattern-matching visual artifacts and calling it structure.

The Uncomfortable Implication

If you are building a PDF extraction tool for production use and you are not parsing the operator stream, you are building a demo. You can get it to work on the 20 PDFs in your test suite. You cannot get it to work reliably on the PDFs your users will upload.

The path through the operator stream is harder. It requires understanding the CTM, the fill/stroke state machine, the constructPath compound op, the difference between setFillRGBColor and setFillColorN, the fact that curveTo2 and curveTo3 are shorthand variants with implicit control points. These are not documented anywhere obvious; you read the PDF spec and the pdfjs source.

But you only have to understand it once. Then it works for every PDF, not just the ones you tested on.

The Empty Quadrant: Mapping the Design Space of Frontend PDF Extraction

Bonzai2Carn — Thu, 14 May 2026 13:30:00 +0000

A user asked me a sharp question yesterday:

Looking at your extraction pipeline, pdfjs + geometryWorker + lattice + visualGridMapper, what makes this any different from any other extraction approach for frontend only, no backend or compiled engine?

It's the right question to ask any author of a tool. So I sat down and surveyed the space honestly. What I found was more interesting than my gut answer.

The pipeline isn't different because of clever algorithms. The lattice reconstruction is the same lattice reconstruction every server-side tool uses. The KD-tree proximity is a textbook nearest-neighbor query. Y-band paragraph clustering is in a 1996 paper. The math is borrowed.

What's different is the quadrant of the design space the pipeline occupies, and the architectural commitments it took to land there.

This post maps that design space. It catalogs what's already in each cell, identifies the empty one, and explains why it stayed empty long enough for a niche to form.

1. The 2×2 grid

Two axes describe almost every PDF extraction project I've encountered:

Approach axis: deterministic vs. ML-based.
Output axis: visual fidelity vs. semantic structure.

Plot them and you get four cells.

                 DETERMINISTIC                 ML-BASED
                ───────────────                ────────
  SEMANTIC      pdfplumber, Tabula,            Adobe Extract API,
  STRUCTURE     Camelot, PyMuPDF               Textract, Azure DI,
  (backend)                                     transformers.js + layout
                                                models (frontend)

  VISUAL        pdf2htmlEX                     —
  FIDELITY      (frontend WASM)
  (frontend)

  TEXT-ONLY     pdfreader, pdf-extract,        tesseract.js
  STREAM        the naive getTextContent()     (OCR over rendered canvas)
                recipe

Three observations fall out of this map immediately.

Backend dominates the deterministic-structural cell. Everything serious about extracting structure from PDFs without ML lives on a server. pdfplumber, Tabula, Camelot, PyMuPDF — all Python, all backend, all decades of accumulated implementation knowledge.

Frontend is well-represented but compromised. Each frontend project gives up something significant. pdf2htmlEX reproduces visual appearance perfectly but ships zero semantic structure. tesseract.js works on scanned PDFs but throws away the native text layer that digital PDFs hand you for free. The transformers.js + layout-model approach handles weird documents but ships multi-megabyte model weights and opaque failure modes. The naive getTextContent() recipe and its Y-clustering descendants give you a flat blob and don't read the operator list at all.

There's a frontend cell that's empty. Deterministic. Structural. No ML weights. No raster step. No backend.

That empty cell is where this pipeline sits.

2. The naive 95 percent

Before we look at what fills the four occupied cells, it's worth establishing the baseline. Roughly 95 percent of frontend PDF extraction code in the wild does this:

const pdf = await pdfjsLib.getDocument(bytes).promise;
let text = '';
for (let i = 1; i <= pdf.numPages; i++) {
  const page = await pdf.getPage(i);
  const content = await page.getTextContent();
  text += content.items.map(it => it.str).join(' ') + '\n';
}

This works on a memo. It collapses on a two-column research paper. It liquefies on a table. It can't tell a heading from a paragraph. It has no concept of reading order on a complex page.

Everything beyond this baseline is a project trying harder. There are four serious such projects. None of them sits in the deterministic-structural-frontend cell.

3. The four occupied frontend cells

Cell A: `pdf2htmlEX` — visual fidelity, no semantics

pdf2htmlEX is a WASM port of an old C++ project. It walks the PDF and emits absolutely-positioned <div>s that visually reproduce the source.

<div style="position:absolute; top:124px; left:88px; font-size:11pt">A table cell</div>
<div style="position:absolute; top:124px; left:240px; font-size:11pt">Another</div>
<div style="position:absolute; top:124px; left:392px; font-size:11pt">Cell</div>

If you want to render the PDF in a browser and let the user select text, this is unbeatable. If you want any semantic structure (a <table>, an <h1>, a paragraph block), you're back to scraping divs by their bounding boxes — the same problem the user started with.

Cell B: `tesseract.js` — OCR

Render each page to canvas. Run OCR on the canvas. Get text + bounding boxes back.

This is the right answer for scanned PDFs that have no native text layer. It's the wrong answer for digital PDFs that already have perfect text. You're feeding selectable text through an image-to-text model and getting a degraded copy of what was already there. Plus a 2MB WASM payload, plus seconds-per-page latency.

Cell C: `transformers.js` + layout models — ML-based structural

Load a layout-aware model (DocLayout-YOLO, LayoutLM, or similar) into the browser via ONNX or transformers.js. Render each page to canvas. Run inference. Get back labeled regions: TABLE, TEXT, FIGURE.

This is where the modern industry is heading. It works on weird, varied document types. It generalizes. But:

The model weights are megabytes (DocLayout-YOLO Nano alone is ~6MB ONNX).
First inference takes seconds.
Failure modes are opaque — when the model misclassifies, you have no levers.
You're shipping an ML inference engine to do something that, for digital PDFs, can be done with pure geometry.

Cell D: `pdfreader`, `pdf-extract`, and friends — text-only Y-clustering

These libraries take getTextContent() items, cluster them by Y position, sort by X, and produce slightly more structured output than the flat-blob recipe.

The fundamental limit: they only consume the text content. They never call getOperatorList(). They cannot see vector lines. They cannot detect a table border, distinguish an underline from a horizontal rule, or recognize a chart axis. Their world is text and only text.

For prose-heavy documents, that's fine. For anything with tables, they degrade to row-smashing.

4. The empty cell, and what fills it

The deterministic-structural-frontend cell asks for a tool that:

Runs entirely in the browser. No server.
Ships no ML model weights. Determinism via geometry.
Reads the operator list, not just the text content. Vector-aware.
Outputs semantic structure: tables with topology, headings, paragraphs, lists, reading order.

To fill it, this pipeline does the following:

4.1 CTM-baked vector segments

// ctmAdapter.js (simplified)
for (let i = 0; i < fnArray.length; i++) {
  if (fnArray[i] === OPS.save)    ctmStack.push(ctm.slice());
  if (fnArray[i] === OPS.restore) ctm = ctmStack.pop();
  if (fnArray[i] === OPS.transform) ctm = mulMatrix(ctm, argsArray[i]);
  if (fnArray[i] === OPS.constructPath) {
    // Walk subpaths, transform each point through CTM × viewport.transform,
    // emit normalized H/V segment records.
  }
}

This is the move that puts the pipeline in a different category from cells B and D. We don't just consume text. We consume the operator list and reconstruct the page's vector skeleton in viewport coordinates. We can see the table borders before any text math runs.

4.2 Region-typed classification before extraction

Most pipelines run sequential passes: find tables, find paragraphs, find lists. Each pass works against the full text pool. Then you deduplicate at the end and hope the passes didn't disagree.

This pipeline does the opposite. Classify regions first, then route scoped text into each region's specialist extractor. The mechanism is a single assignedTextIndices set:

for (const lattice of lattices) {
  const tableTextIndices = [];
  for (const tm of textMeta) {
    if (assignedTextIndices.has(tm.idx)) continue; // skip consumed
    if (insideBBox(tm.vx, tm.vy, lattice.bbox, tablePad)) {
      tableTextIndices.push(tm.idx);
      assignedTextIndices.add(tm.idx); // mark as consumed
    }
  }
  regions.push({ type: TABLE, lattice, textItemIndices: tableTextIndices });
}
// later: paragraph/heading/list passes only see un-consumed text

The invariant is: a text item belongs to exactly one region. No leakage by construction. The bug class of "table text accidentally in a paragraph" is preempted, not patched.

4.3 Underline-vs-border discrimination

A naive lattice reconstructor sees every horizontal line and tries to use it as a table border. This produces phantom 1×1 tables under every underlined heading.

We classify each H-segment against the text baselines using KD-tree-style proximity:

for (const h of hSegs) {
  const hY = (h.y1 + h.y2) / 2;
  for (const tm of textMeta) {
    const yDist = hY - tm.vy;
    if (yDist >= -1 && yDist <= 5 &&
        tm.vx <= hXMax + 2 && (tm.vx + tm.vWidth) >= hXMin - 2 &&
        hLen < tm.vWidth * 2.5) {
      underlineSegIds.add(h.id);
      break;
    }
  }
}

If a horizontal line sits 0–5px below a text baseline with overlapping X-span, it's an underline. Tag it. Remove from the table-detection pool. ~99% of phantom tables disappear.

I have not seen another browser-side PDF extractor that does this. Tabula has equivalents on the backend. On the frontend, every other tool I've audited just hands all H-lines to the lattice and lives with phantom tables.

4.4 Topological cell-merge inference

Naive table extractors detect cell merges by visual whitespace heuristics ("if these two cells have no visible boundary between their text, they're merged"). This is unreliable. Tables with thin internal borders look unmerged but are; tables with wide cell padding look merged but aren't.

This pipeline asks the geometry directly:

function vLinePresent(vLines, x, yA, yB, eps) {
  return vLines.some(l =>
    Math.abs(l.x - x) <= eps &&
    l.yMin <= yA + eps &&
    l.yMax >= yB - eps
  );
}

Is there an actual merged vertical-line record at this X position spanning [yA, yB]? If yes, the cell boundary exists; the cells are separate. If no, extend the colspan. Topological, not visual.

4.5 Nearest-cell Euclidean snap

Strict point-in-box assignment drops text whose origin is 0.1px outside a cell, which is common because PDF rendering coordinates have jitter. We use Euclidean distance to the nearest cell center with a 15px snap threshold:

let bestR = -1, bestC = -1, minDist = Infinity;
for (let ri = 0; ri < numRows; ri++) {
  for (let ci = 0; ci < numCols; ci++) {
    const dx = Math.max(cols[ci] - sx, 0, sx - cols[ci+1]);
    const dy = Math.max(rows[ri] - sy, 0, sy - rows[ri+1]);
    const dist = Math.sqrt(dx*dx + dy*dy);
    if (dist < minDist) { minDist = dist; bestR = ri; bestC = ci; }
  }
}
if (minDist < 15) cells[bestR][bestC].push(...);

Magnetic, not literal. Coordinate jitter doesn't drop data.

4.6 Worker-isolated full pipeline

Most browser PDF extractors run on the main thread. The geometry pipeline here loads PDF.js as a nested worker inside the geometry worker. CTM baking, lattice reconstruction, classification, assembly — all off the main thread. The UI stays responsive on a 200-page document.

4.7 Per-page streaming

Naive extractors accumulate the whole document into one structured-clone payload at the end. That dies on large PDFs with stack-overflow errors in postMessage. We emit per-page 'page' messages from the worker, the main thread accumulates incrementally, and the UI can show progressive results.

self.postMessage({
  type: 'page',
  page: p,
  html: result.html,
  text: result.text.trim(),
  tables: result.tableCount,
});

Not algorithmic novelty. Engineering discipline that lets the architecture survive 76-page technical manuals.

4.8 VisualGridMapper as a downstream operator

The output isn't a dead <table> string. It's a live HTML table that we can immediately remap into a Cartesian array using VisualGridMapper:

const mapper = new VisualGridMapper(table);
// mapper.grid[row][col] now holds origin/spanned cell metadata.
// Transposes, merges, splits all become matrix operations.

This is the bridge into the table-formatter half of the platform. Other extractors stop at "here's a <table>." We hand the user something they can keep manipulating mathematically.

5. What's borrowed and what's new

Worth being honest about which pieces of this are original engineering versus academic standard:

Borrowed:

The lattice algorithm itself — intersection clustering, row/column projection. Same as Tabula, Camelot, pdfplumber.
Y-band paragraph clustering — pdfminer-style, in academic literature since the 90s.
XY-cut column detection — known since the 80s.
KD-tree spatial indexing — textbook.
DOMPurify, jQuery, Monaco — off-the-shelf.

Original to this pipeline (or unusual in the niche):

The full assembly running in a Web Worker on top of PDF.js as a nested worker.
The non-overlapping-region invariant via assignedTextIndices.
The underline-discrimination heuristic with the specific 0–5px / 2.5×-width thresholds.
The coordinate-space discipline: storing both vWidth/vFont (viewport) and width/fontSize (PDF points) on every text-meta record, with explicit comments about which to use where.
The per-page streaming pattern that survives 100+ page documents.
The integration with VisualGridMapper for downstream mathematical manipulation.

The pipeline is a composition. The composition is the contribution.

6. Why this cell stayed empty

If the deterministic-structural-frontend cell is valuable, why hadn't anyone filled it?

Three reasons, in order of how convincing each one is.

Economics push toward backend. If you have a use case that needs structural PDF extraction, you almost certainly have a server. The serious tools live in Python and have for a decade. There's no incentive to port them unless you specifically need data to stay on the client device — which is a real but niche requirement.

Existing frontend tools are anchored to other quadrants. pdf2htmlEX is committed to visual fidelity. tesseract.js is committed to OCR. The transformers.js camp is committed to ML generalization. Each is well-architected for its quadrant and would require an architectural rewrite to drift into the deterministic-structural cell. Nobody had a reason to do that work.

The pieces are scattered. PDF.js gives you the operator list but assumes you'll use it for rendering. Lattice algorithms are described in papers, not packaged as npm modules. KD-tree libraries assume preformatted data. Web Worker isolation has its own ergonomic learning curve. Climbing the staircase to assemble all of these is real engineering work, and unless you have a strong reason to be in this exact cell, the cost-benefit doesn't pencil.

We had a reason. The platform we're building is browser-native by commitment, not accident. Every other tool in our pipeline runs in the browser. Sending PDFs to a server for structural extraction would have broken the architectural model. So we climbed.

7. The lesson above the niche

There's a generalization worth saying out loud, because it applies far beyond PDF tooling.

When you wonder whether you're reinventing a wheel, do the survey. But ask the right question. The question is not "has anyone solved this problem?" — the answer to that is almost always yes, somewhere. The question is:

What set of constraints does my version satisfy that nobody else's version satisfies?

Constraints are commitments. No backend. No model weights. Worker isolation. Deterministic output. Per-page streaming. Open source. Each one is a deliberate refusal of a path other people took.

The intersection of constraints is where new niches live. The math you use inside that intersection is often the same math everyone else uses. That's fine. The originality isn't in the math. It's in the negative space; the things you said no to.

The pipeline isn't different because the algorithms are different. It's different because of where it runs and what it refuses to be.

The full pipeline is open source as part of the GINEXYS project. If you find a fifth camp I missed, or if you've built something that fills the empty quadrant differently, the issue tracker is open. I'm specifically curious whether anyone else has implemented in-browser CTM baking against pdfjs-dist's operator list — that piece felt the loneliest in my survey.

How to Stop PDF Parsers from Hallucinating Tables out of Thin Air

Bonzai2Carn — Tue, 12 May 2026 15:54:05 +0000

PDF extraction is usually blind.

If you've ever tried to write a script to scrape a PDF, you know exactly what I mean. You run the PDF through a generic text extractor, and instead of a clean table, you get a jammed wall of text where the columns are violently shoved into a single vertical stack.

Or worse, you try to use a table extractor, and it hallucinates tables everywhere. See a bold heading with an underline? The parser thinks that's a 1x1 table. See a horizontal divider between paragraphs? Boom, phantom table.

Why does this happen? Because most PDF parsers process the document in a strict, sequential pipeline. They look at all the lines. They look at all the text. And they just smash them together.

I got tired of this. So I re-engineered the extraction pipeline in our PDF processor to stop reading the document like a machine, and start seeing it like a human.

Here is the math behind Context-Aware PDF Extraction.

1. The Blind Extraction Problem

Previously, our extraction pipeline worked like this:

Find all horizontal and vertical line segments (H-segs and V-segs).
Run them through a LatticeReconstructor to find intersecting grids.
Treat every grid as a table.
Dump all the text in the document into those grids using a strict "is this point inside this box" check.

This was a disaster for documents that mixed paragraphs with tables.

If a paragraph had a decorative underline, the LatticeReconstructor would see the H-line, panic, and try to build a table out of it.
If text was slightly offset inside a table cell due to coordinate jitter, the "point-in-box" check would fail, and the text would just vanish from the output.

I needed the parser to understand context.

2. Enter the Context Classifier

To fix this, I built the contextClassifier.

Instead of treating the PDF as a bucket of shapes and text, the contextClassifier walks the document and groups every single item into spatially bounded, typed regions: TABLE, PARAGRAPH, HEADING, LIST, and IMAGE.

But how do you tell a machine the difference between a table border and a decorative underline?

You use proximity math.

// KD-tree style proximity: check if text sits exactly on top of an H-line
for (const h of hSegs) {
    const hY = (h.y1 + h.y2) / 2;
    for (const tm of textMeta) {
        const yDist = hY - tm.vy; 

        // Underline: line is 0–5px below the text baseline
        if (yDist >= -1 && yDist <= 5 && overlappingXSpan(tm, h)) {
            underlineSegIds.add(h.id);
            break; 
        }
    }
}

If a horizontal line is exactly 0 to 5 pixels below a text baseline, and its width roughly matches the text width, it's not a table border. It's an underline.

By tagging and removing these underlines before we run the table reconstruction, we eliminate 99% of phantom tables.

3. Scoping the Text (No More Collisions)

Once the tables are detected, we calculate the exact bounding box of the table grid.

Instead of throwing all the document's text at the table builder, the classifier scoops up only the text items that physically live inside that bounding box.

const tableTextIndices = [];
for (const tm of textMeta) {
    if (insideBBox(tm.vx, tm.vy, bbox)) {
        tableTextIndices.push(tm.idx);
        assignedTextIndices.add(tm.idx); // Mark as consumed!
    }
}

This does two things:

It guarantees that table text doesn't accidentally leak into paragraphs.
It guarantees that paragraph text doesn't get sucked into table cells.

Once a text item is claimed by a region, it's marked as consumed.

4. The Nearest-Cell Proximity Assignment

Even with scoped text, getting the text into the correct table cell was still failing due to PDF rendering quirks. A cell might be at x: 10.5, but the text was at x: 10.4. A strict bounding box check would drop the text.

I ripped out the strict containment checks and replaced them with a nearest-neighbor proximity model.

For every piece of text, we find its nearest cell center using Euclidean distance. If it's within a 15px threshold, it snaps into place. No more jitter. No more dropped data.

5. The Page Assembler

Finally, the pageAssembler takes over.

It receives an array of perfectly classified, non-overlapping regions. It sorts them top-to-bottom based on their Y-coordinates.

Then, it just iterates through them and calls the right extractor:

If it's a TABLE, it sends the scoped text to the tableBuilder.
If it's a HEADING, it wraps it in an <h3> or <h4>.
If it's a LIST, it strips the bullet points and outputs clean <ul><li> tags.
If it's a PARAGRAPH, it sends it to the textRebuilder.

The result? True document reading order.

You upload a messy, complex PDF filled with tables, paragraphs, and lists. The pipeline classifies it, scopes the data, and spits out clean, semantically correct HTML.

No backend processing. No AI hallucination. Just pure, deterministic math running directly in your browser using pdfjs-dist and vanilla JS.

The PDF is finally readable.

You can find the repo at doc-extractor or give it a try at Ginexys

DEV Community: Bonzai2Carn

Why Web Workers Swallow Your Stacktraces (And How to Write Specs to Fix It)

The Pattern That Keeps Failing

Why This Keeps Happening

What Correct Specs Look Like

The Stacktrace Problem

The Uncomfortable Implication

Web Components vs. Iframes: A Hard Lesson in DOM Isolation Barriers

TLDR

The Assumption That Seemed Reasonable

How It Broke

Why It Was Hard to Find

What Was Thrown Away

What Replaced It

The Lesson

Seven Table Parsers, One Interface: Designing a Table Formatter and Node Editor (TAFNE)

The Dispatcher

Two Parsing Strategies

The Semantic Parsers

The Heuristic Parsers

The State Machine: Markdown

The Hunter: SQL

Auto-Detection for File Loads

Why We Treat HTML as a CAD Format for PDF (And Why It Works)

The problem with "extracted output"

HTML is already a spatial document format

Two modes, one surface

Why not absolute positioning?

Edit Code: the escape hatch

The export chain closes the loop

SiaS: the tool works without the service

Debugging Mobile Drag & CSS Specificity in a Real-Time PDF Diff Tool

What We Set Out To Do

The Mobile Drag Problem

The Diff Tab Redesign

The CSS Specificity Disaster

What Failed

What Survived

Under the Hood: Drag, Touch, and CSS Cascade in a Real Diff UI

The Responsive Drag Problem

Naive approach and why it fails

Correct approach: read computed flex direction

Unified event position extraction

Dimension tracking

Touch Event Registration

Why { passive: false } matters

Why touchmove goes on document, not the divider

The Diff Tab CSS Architecture

The 36px diff bar

Pill group segmented control

The Specificity Bug

Setup

Why it overwrote display: none

Fix

The lesson

Most PDF Extractors Use the Wrong API: Here’s What We Built Instead

The Hierarchy Nobody Talks About

Why This Happened

What You Miss

The Cascade Is Not Optional

The Uncomfortable Part

Why Splitting a 2,500-Line File Broke Our Architecture

TLDR

The Assumption That Seemed Reasonable

When It Failed

What Was Actually Wrong

What Got Deleted

What Replaced It

The Lesson

Building a High-Performance CAD Engine in Vanilla JavaScript (No Frameworks)

The Bottleneck of Re-rendering

The Solution: Direct DOM & Specialized Kernels

The Result

Join the Project

Stop Parsing PDFs at Render Time: A Better Architecture for Structured Extraction

The Industry Default Is Backwards

The De Casteljau Example

The Zone Boundary Example

What the Correct Approach Requires

The Uncomfortable Implication

Why `{ passive: false }` matters

Why it overwrote `display: none`

Cell A: `pdf2htmlEX` — visual fidelity, no semantics

Cell B: `tesseract.js` — OCR

Cell C: `transformers.js` + layout models — ML-based structural

Cell D: `pdfreader`, `pdf-extract`, and friends — text-only Y-clustering