@templatical/import-html 0.33.0 → 0.34.0

package/dist/index.js

@@ -1,5 +1,6 @@
 import { load } from "cheerio";
 import { createButtonBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createParagraphBlock, createSectionBlock, createSpacerBlock, createTitleBlock } from "@templatical/types";
+import { isTag, isText } from "domhandler";
 //#region src/style-parser.ts
 /**
 * Parses a CSS `style="..."` attribute string into a flat key/value record.
@@ -385,6 +386,147 @@ const TEXT_TAGS = /* @__PURE__ */ new Set([
 	"span",
 	"div"
 ]);
+/**
+* Wrapper tags that carry layout rather than content. One of these is worth
+* descending into when it holds a table somewhere below it.
+*/
+const CONTAINER_TAGS = /* @__PURE__ */ new Set([
+	"div",
+	"center",
+	"main"
+]);
+/**
+* Decides whether an element is a layout container worth descending into: a
+* wrapper tag that holds a table somewhere below it.
+*
+* The table test is what keeps the descent from widening into "descend every
+* div". `div` is in `TEXT_TAGS` above, so a container holding only copy must
+* keep that mapping and become one paragraph rather than being split into a
+* block per child.
+*
+* Lives here, with the other predicates both traversal modules consult,
+* because the body walk and the cell walk have to agree on what a container
+* is. A second copy answers the question differently the moment either is
+* edited, and the divergence shows up as a table swallowed into a paragraph
+* on whichever surface was missed.
+*/
+function isTableContainer($el, tag) {
+	return CONTAINER_TAGS.has(tag) && $el.find("table").length > 0;
+}
+/**
+* Whether an element is laid out beside its siblings rather than stacked above
+* them: `display: inline-block`.
+*
+* This is the property that *makes* a set of divs a set of columns — an email
+* that wants side-by-side divs has no other way to say so, since a block-level
+* div stacks — so requiring it is the definition of the shape and not a
+* heuristic about it. Two plain divs stack vertically, and reading those as
+* columns would invent a layout the source never stated.
+*/
+function isSideBySide($el) {
+	return (getStyles$1($el).display ?? "").trim().toLowerCase() === "inline-block";
+}
+/**
+* The sibling containers that make up a cell's column set, or `null` when the
+* cell is not one.
+*
+* This is the one column shape with no cell count to read: a single `<td>`
+* holding one inline-block `<div>` per column. Cerberus's hybrid template
+* states four layouts this way and compiled MJML states every one of them —
+* mjml puts a whole section's columns into one cell as sibling
+* `div.mj-column-per-*` — so a row's cell count reports one column for a
+* layout that has two or three. Counting the divs is still *counting*: the
+* number of columns comes from the number of elements, and a width is only
+* ever consulted afterwards to choose between layouts of that same count.
+*
+* Four conditions, each of them a hazard a relaxed version would reintroduce:
+*
+* - Every element child must be a container. A cell mixing a column set with
+*   anything else has no column any other element belongs to.
+* - Every one must be laid out side by side (`isSideBySide`), which is what
+*   distinguishes columns from stacked content.
+* - None may be blank. A multi-column section with an empty slot is worse
+*   than the single column a cell count already gives, and the source's own
+*   spacer chrome is exactly what would fill one.
+* - No text of the cell's own may survive, for the same reason as the first
+*   condition — a bare sentence beside the columns belongs to none of them.
+*
+* Deliberately structural: it reads no width, so a column set with no declared
+* width still becomes one, and a `width:100%` — which every real column div
+* carries — can never make or break the decision.
+*/
+function columnDivsOf($cell, $) {
+	const columns = [];
+	let inlineText = "";
+	for (const node of $cell.contents().toArray()) {
+		if (isInlineContent(node)) {
+			inlineText += $(node).text();
+			continue;
+		}
+		if (!isTag(node)) continue;
+		const tag = node.tagName.toLowerCase();
+		if (!CONTAINER_TAGS.has(tag)) return null;
+		const $child = $(node);
+		if (!isSideBySide($child)) return null;
+		if (isBlankCell($child)) return null;
+		columns.push($child);
+	}
+	if (columns.length < 2) return null;
+	if (inlineText.trim() !== "") return null;
+	return columns;
+}
+/**
+* Block-level elements a container may be unwrapped down to. Only a heading:
+* a container wrapping one is the single case where mapping the container
+* gets the block's *type* wrong.
+*
+* A tag qualifies only if unwrapping it loses nothing, and `p` is the one that
+* looks like it belongs and does not. `convertParagraph` reads an element's
+* inner HTML, so unwrapping `<div><p class="lead">…</p></div>` drops the `<p>`
+* and every attribute on it, where mapping the container keeps that markup
+* inside the paragraph's content. Nothing is bought in exchange: a wrapped
+* `<p>` already maps to a paragraph, which is the right type. A heading has no
+* such cost, because `convertHeading` stores the level and the inner HTML —
+* so unwrapping routes it to the same converter a bare `<h3>` already reaches.
+*
+* `img`, `hr` and `table` stay out for the same "nothing to fix" reason: a
+* table belongs to the container descent the two traversals run, and the other
+* two would widen a heading-typing rule into image and divider mapping.
+*
+* The set is also what keeps the styling below correct — `convertHeading` is
+* the only converter reached with a container's styles, so admitting a tag it
+* does not handle would silently drop them.
+*/
+const UNWRAPPABLE_BLOCK_TAGS = HEADING_TAGS;
+/**
+* Inline formatting tags, which carry no block of their own. One of these
+* reaching a block position means the parent's text extraction stopped short —
+* it does not mean the element has no mapping, so it must never fall through
+* to the html-fallback arm.
+*
+* The hazard that keeps them listed here: a cell's inline markup and the bare
+* text nodes around it are one run of rich text. Dispatching an inline element
+* on its own emits a block whose entire content is `<br>` AND deletes every
+* text node beside it, because a walk over element children never visits
+* those. That is silent content loss — text visible in the source email never
+* reaches the template.
+*
+* `a` is excluded on purpose: whether an anchor belongs to a run depends on
+* how the source styled it, so the cell walk asks `isProseAnchor` per anchor
+* instead. Reading every `<a>` as inline here would fold a styled call to
+* action into the sentence beside it and lose the button.
+*/
+const INLINE_FORMATTING_TAGS = /* @__PURE__ */ new Set([
+	"br",
+	"em",
+	"strong",
+	"i",
+	"b",
+	"u",
+	"small",
+	"sub",
+	"sup"
+]);
 function emptyPadding$2() {
 	return {
 		top: 0,
@@ -401,6 +543,124 @@ function getStyles$1($el) {
 	return parseStyleAttribute($el.attr("style"));
 }
 /**
+* Whether an element carries anything a reader would see: text, or an element
+* that renders without text of its own.
+*
+* One rule with two readers, which is the point: it decides both whether a
+* text container is worth a block at all and whether a wrapper is worth
+* unwrapping. Two copies would let `<div><h3></h3></div>` be skipped by one
+* and turned into an empty title by the other.
+*/
+function hasRenderedContent($el) {
+	if (($el.text() ?? "").trim() !== "") return true;
+	return $el.find("img, a").length > 0;
+}
+/**
+* The single element a container's whole content consists of, or `null` when
+* the container holds anything else.
+*
+* Whitespace and comments are incidental — the same reading `extractContentBlocks`
+* gives them — and `trim` counts `&nbsp;` among them, which is how the rest of
+* this module reads it (`normalizeCellText`, and through it `isBlankCell`).
+* Everything else is content: a second element, a bare word, or a rendering
+* `<br>` all mean the container holds more than one thing, and unwrapping it
+* would drop whatever was not unwrapped.
+*/
+function soleElementChild($el) {
+	let found = null;
+	for (const node of $el.contents().toArray()) {
+		if (isText(node)) {
+			if (node.data.trim() !== "") return null;
+			continue;
+		}
+		if (!isTag(node)) continue;
+		if (found) return null;
+		found = node;
+	}
+	return found;
+}
+/**
+* The styles the innermost element of a wrapper chain renders with: each
+* container's own declarations, overridden by those of the element inside it.
+*
+* The container's styles have to travel, because the wrapper is where
+* table-based email puts the colour, size, font and alignment — a plain
+* `getStyles` on the unwrapped element trades a typing defect for a styling
+* loss.
+*
+* A declaration of `inherit` states nothing of its own, so it must not shadow
+* the container's value. That is load-bearing rather than pedantic: mjml@5
+* puts every visual property on the wrapper div and writes `color: inherit` on
+* the heading inside it, so honouring the keyword literally drops the colour
+* the email actually renders with.
+*/
+function inheritedStyles(chain) {
+	const merged = { ...getStyles$1(chain[0]) };
+	for (const $node of chain.slice(1)) for (const [property, value] of Object.entries(getStyles$1($node))) {
+		if (value.trim().toLowerCase() === "inherit") continue;
+		merged[property] = value;
+	}
+	return merged;
+}
+/**
+* The element that takes a container's place when the container's entire
+* meaningful content is one block-level element, together with the styles that
+* element renders with. Returns the element handed in when there is nothing to
+* unwrap.
+*
+* Generator-produced email wraps each text block in a plain `<div>` holding a
+* single block-level element — compiled MJML puts one `<h3>` inside an
+* `mj-text` body that rendered a heading. That `<div>` holds no table, so it
+* is correctly not a container to descend, and `div` is a text tag here:
+* mapping it emits a paragraph with the heading buried in its content, which
+* loses the heading's semantics, its own styling and any downstream treatment
+* of titles.
+*
+* Three constraints, each a hazard a relaxed version would reintroduce:
+*
+* - The chain must *end* on an `UNWRAPPABLE_BLOCK_TAGS` element. That is what
+*   keeps a `div.mj-column-per-*` out: its sole child is a `<table>`, and
+*   handing that to the dispatch below would html-fallback the whole column.
+*   It also leaves a chain of containers bottoming out in bare text alone, so
+*   `<div><div>copy</div></div>` keeps mapping as it did.
+* - A container holding a table is refused outright, through the same
+*   `isTableContainer` predicate the two traversals use. This decides the one
+*   case the tag test cannot — a sole child that *is* a heading, with the
+*   table below it — and both traversals descend such a container, so the
+*   subtree is theirs rather than this dispatch's.
+* - An empty wrapper is refused, so a container whose sole child renders
+*   nothing stays skipped rather than becoming an empty title.
+*
+* Bounded by DOM depth: each step moves to a child.
+*/
+function resolveWrappedBlock($el, $) {
+	const unwrapped = {
+		$el,
+		styles: getStyles$1($el)
+	};
+	const chain = [$el];
+	let $current = $el;
+	for (;;) {
+		const tag = tagOf($current[0]);
+		if (!CONTAINER_TAGS.has(tag)) break;
+		if (isTableContainer($current, tag)) break;
+		const child = soleElementChild($current);
+		if (!child) break;
+		const childTag = tagOf(child);
+		if (!CONTAINER_TAGS.has(childTag) && !UNWRAPPABLE_BLOCK_TAGS.has(childTag)) break;
+		$current = $(child);
+		chain.push($current);
+	}
+	if (chain.length === 1) return unwrapped;
+	const $target = chain[chain.length - 1];
+	if (!UNWRAPPABLE_BLOCK_TAGS.has(tagOf($target[0]))) return unwrapped;
+	if (!hasRenderedContent($target)) return unwrapped;
+	return {
+		$el: $target,
+		styles: inheritedStyles(chain)
+	};
+}
+/**
 * Returns the inner HTML of `$el`.
 */
 function getInnerHtml($el) {
@@ -416,11 +676,12 @@ function safeHtmlComment(message, raw) {
 }
 /**
 * Heading element (h1-h6) → Title block.
+*
+* `styles` is the element's own by default and the wrapper chain's when the
+* heading was unwrapped out of a container — see `resolveWrappedBlock`.
 */
-function convertHeading($el) {
-	const tag = tagOf($el[0]);
-	const styles = getStyles$1($el);
-	const levelMatch = tag.match(/^h(\d)$/);
+function convertHeading($el, styles = getStyles$1($el)) {
+	const levelMatch = tagOf($el[0]).match(/^h(\d)$/);
 	const rawLevel = levelMatch ? Number(levelMatch[1]) : 2;
 	const level = rawLevel >= 1 && rawLevel <= 4 ? rawLevel : Math.min(rawLevel, 4);
 	const innerHtml = getInnerHtml($el);
@@ -453,11 +714,11 @@ function applyTextAlignToParagraphs(html, textAlign) {
 	});
 }
 /**
-* Paragraph or block-level text container → Paragraph block.
+* Builds a Paragraph block from a fragment of inline markup, styled by the
+* element that supplied `styles`.
 */
-function convertParagraph($el) {
-	const styles = getStyles$1($el);
-	const wrapped = ensureParagraphWrapped(getInnerHtml($el));
+function buildParagraph(innerHtml, styles) {
+	const wrapped = ensureParagraphWrapped(innerHtml);
 	const fontParts = [];
 	const fontSize = parsePxValue(styles["font-size"]);
 	if (fontSize && fontSize !== 16) fontParts.push(`font-size: ${fontSize}px`);
@@ -480,6 +741,44 @@ function convertParagraph($el) {
 	});
 }
 /**
+* Paragraph or block-level text container → Paragraph block.
+*/
+function convertParagraph($el) {
+	return buildParagraph(getInnerHtml($el), getStyles$1($el));
+}
+/**
+* Decides whether a child node of a table cell belongs to a run of inline
+* text rather than to a block of its own: a bare text node, or one of the
+* inline formatting tags.
+*/
+function isInlineContent(node) {
+	if (isText(node)) return true;
+	return isTag(node) && INLINE_FORMATTING_TAGS.has(node.tagName.toLowerCase());
+}
+/**
+* Converts a run of consecutive inline nodes lifted out of a table cell into
+* one Paragraph block, keeping their markup inside the paragraph's content.
+*
+* `$cell` supplies the styling: a bare run has no element of its own to read
+* a colour, size or alignment from, and table-based email puts all three on
+* the cell.
+*
+* Returns `null` for a run carrying no text — a cell holding nothing but
+* `&nbsp;` and `<br>` has no content, the same reading `convertElement`
+* gives an empty `<p>`.
+*/
+function convertInlineRun(nodes, $cell, $) {
+	if (!nodes.map((node) => $(node).text()).join("").trim()) return null;
+	return {
+		block: buildParagraph(nodes.map((node) => $.html(node)).join(""), getStyles$1($cell)),
+		entry: {
+			sourceTag: tagOf($cell[0]),
+			templaticalBlockType: "paragraph",
+			status: "converted"
+		}
+	};
+}
+/**
 * <img> → Image block.
 */
 function convertImage($el) {
@@ -516,6 +815,81 @@ function looksLikeButton(styles) {
 	return false;
 }
 /**
+* Decides whether an `<a>` belongs to the run of prose around it rather than
+* to a block of its own: a link the source did not style as a button, whose
+* own text is what the reader sees.
+*
+* A link inside a sentence is prose, so folding it keeps the sentence in one
+* editable block — and keeps the anchor's markup, `href` included, which the
+* per-element path drops (`convertParagraph` reads inner HTML, so the element
+* itself never reaches the block).
+*
+* Two constraints, both hazards a relaxed version would reintroduce:
+*
+* - `looksLikeButton` is the same predicate `convertElement` and
+*   `isButtonCell` use to tell a call to action from a link, so a styled
+*   anchor is never absorbed into a sentence and keeps becoming a button.
+* - The anchor must carry text. `convertInlineRun` reads a run with no text
+*   as empty and emits nothing, so an anchor whose content is an image has to
+*   keep the block it already gets; folding it would delete the image.
+*/
+function isProseAnchor($el) {
+	if (looksLikeButton(getStyles$1($el))) return false;
+	return ($el.text() ?? "").trim() !== "";
+}
+/**
+* Walks an element's child *nodes*, grouping consecutive inline content into
+* runs and handing every other element to the caller.
+*
+* A bare text node between two elements is content, and a walk over
+* `children()` never visits it — so `Hello<br>World` loses both words while
+* emitting a block holding nothing but `<br>`. Consecutive inline nodes
+* therefore accumulate into one run and become a single paragraph, which is
+* what makes a bare line agree with the same line wrapped in a `<p>`.
+*
+* One walker for all three content traversals — the body walk, the layout
+* container walk and the cell walk — because a bare text node is content
+* wherever it sits and the three have to read it identically. A second copy
+* of this classification is the hazard: fixing it on one surface leaves the
+* others silently dropping copy the source email displays, and nothing fails
+* to say so. What differs between the three is only what a *block-level*
+* element becomes, which is why that half is the caller's.
+*
+* `$host` is what a run reads its styling and source tag from: a bare run has
+* no element of its own, and the nearest enclosing element is the one carrying
+* the colour, size and alignment it renders with.
+*
+* A run never reaches across `$host`'s own children into a descendant's:
+* `onElement` is called with the run already flushed, so a caller that
+* recurses keeps the text before a block-level child ahead of it.
+*/
+function walkContentNodes($host, $, onRun, onElement) {
+	let inlineRun = [];
+	const flushInlineRun = () => {
+		if (inlineRun.length === 0) return;
+		const run = inlineRun;
+		inlineRun = [];
+		const converted = convertInlineRun(run, $host, $);
+		if (converted) onRun(converted);
+	};
+	for (const node of $host.contents().toArray()) {
+		if (isInlineContent(node)) {
+			inlineRun.push(node);
+			continue;
+		}
+		if (!isTag(node)) continue;
+		const $child = $(node);
+		const tag = node.tagName.toLowerCase();
+		if (tag === "a" && isProseAnchor($child)) {
+			inlineRun.push(node);
+			continue;
+		}
+		flushInlineRun();
+		onElement($child, tag);
+	}
+	flushInlineRun();
+}
+/**
 * Reads a button's placement from the cell that wraps it. An anchor styled as
 * a button is sized to its own content, so its `text-align` says nothing about
 * where it sits — table-based email puts that on the containing `<td>`, as
@@ -577,23 +951,70 @@ function convertHtmlFallback($el, $, note) {
 	});
 }
 /**
-* Decides whether a `<td>` looks like a vertical spacer:
-* empty (or only `&nbsp;`) AND has an explicit height.
+* Decides whether a `<td>` / `<th>` carries nothing a reader would see: no
+* text once source whitespace and `&nbsp;` are collapsed, and no element that
+* renders on its own.
+*
+* Text alone is not the test. An image or a link carries no text and is
+* content all the same, so a cell holding one is never blank — reading it as
+* blank would make a picture-only column disappear.
+*
+* Lives here, with the other predicates both traversal modules consult,
+* because a spacer cell and a row's gutter cells are one fact read for two
+* purposes: `isSpacerCell` adds a stated height to it, and the section
+* builder reads a row's blank cells as chrome rather than as columns. A
+* second copy would let one cell be a spacer in one traversal and a column
+* in the other.
+*/
+function isBlankCell($el) {
+	if (normalizeCellText($el.text() ?? "") !== "") return false;
+	return $el.find("img, a, hr").length === 0;
+}
+/**
+* Decides whether a `<td>` looks like a vertical spacer: blank, and carrying
+* an explicit height.
 */
 function isSpacerCell($el) {
-	if (($el.text() ?? "").replace(/\s| /g, "") !== "") return false;
-	if ($el.find("img, a, hr").length > 0) return false;
+	if (!isBlankCell($el)) return false;
 	const styles = getStyles$1($el);
 	return parsePxValue($el.attr("height")) > 0 || parsePxValue(styles.height) > 0 || parsePxValue(styles["line-height"]) > 0;
 }
 /**
-* Decides whether a `<td>` is a button container — i.e. has exactly one
-* `<a>` inside that itself looks like a button.
+* Collapses every run of whitespace — `&nbsp;` included — to one space and
+* trims. Source indentation and nested tags introduce whitespace that never
+* renders, so a text comparison has to normalise both sides.
+*/
+function normalizeCellText(value) {
+	return value.replace(/[\s\u00a0]+/g, " ").trim();
+}
+/**
+* Whether the anchor *is* the cell rather than sitting inside its content.
+*
+* The hazard this guards: `buildCellButton` labels the button with the
+* anchor's text and drops every other node in the cell, so classifying a
+* sentence that merely contains a link as a button deletes the sentence. The
+* constraint is that a cell only reads as a button when the link is its
+* entire content — and `find("a")` matches at any depth, so an outer callout
+* cell wrapping a real CTA reaches the same test.
+*/
+function isWholeCellAnchor($el, $anchor) {
+	return normalizeCellText($el.text() ?? "") === normalizeCellText($anchor.text() ?? "");
+}
+/**
+* Decides whether a `<td>` is a button container — i.e. its entire content is
+* one `<a>`, styled as a button either on the anchor or on the cell.
+*
+* Both arms require the anchor to be the cell's whole content. The anchor's
+* own styling is the stronger signal that a link is *a button*, but it says
+* nothing about whether the link is *the cell*, and `find("a")` matches at
+* any depth — so a callout cell holding a paragraph plus a self-styled CTA
+* satisfies the anchor arm exactly as it does the cell arm.
 */
 function isButtonCell($el, $) {
 	const anchors = $el.find("a");
 	if (anchors.length !== 1) return { match: false };
 	const anchor = $(anchors[0]);
+	if (!isWholeCellAnchor($el, anchor)) return { match: false };
 	if (looksLikeButton(getStyles$1(anchor))) return {
 		match: true,
 		anchor
@@ -610,14 +1031,22 @@ function isButtonCell($el, $) {
 * Converts a single content-bearing element (heading / paragraph / image /
 * anchor-as-button / divider) to a Templatical block.
 *
+* A container whose entire meaningful content is one block-level element is
+* unwrapped first, so the element inside is what gets mapped and named in the
+* report — see `resolveWrappedBlock`. Only a heading can come back from that,
+* which is why the heading branch is the only one taking the resolved styles:
+* for every other branch the resolved element is the one handed in, so its own
+* styles are what `styles` already holds.
+*
 * Returns `null` for elements that do not contain any meaningful content
 * (the caller should skip them).
 */
 function convertElement($el, $) {
-	const tag = tagOf($el[0]);
+	const { $el: $target, styles } = resolveWrappedBlock($el, $);
+	const tag = tagOf($target[0]);
 	if (!tag) return null;
 	if (HEADING_TAGS.has(tag)) return {
-		block: convertHeading($el),
+		block: convertHeading($target, styles),
 		entry: {
 			sourceTag: tag,
 			templaticalBlockType: "title",
@@ -625,7 +1054,7 @@ function convertElement($el, $) {
 		}
 	};
 	if (tag === "img") return {
-		block: convertImage($el),
+		block: convertImage($target),
 		entry: {
 			sourceTag: tag,
 			templaticalBlockType: "image",
@@ -633,8 +1062,8 @@ function convertElement($el, $) {
 		}
 	};
 	if (tag === "a") {
-		if (looksLikeButton(getStyles$1($el))) return {
-			block: convertButton($el),
+		if (looksLikeButton(styles)) return {
+			block: convertButton($target),
 			entry: {
 				sourceTag: tag,
 				templaticalBlockType: "button",
@@ -642,7 +1071,7 @@ function convertElement($el, $) {
 			}
 		};
 		return {
-			block: convertParagraph($el),
+			block: convertParagraph($target),
 			entry: {
 				sourceTag: tag,
 				templaticalBlockType: "paragraph",
@@ -652,7 +1081,7 @@ function convertElement($el, $) {
 		};
 	}
 	if (tag === "hr") return {
-		block: convertDivider($el),
+		block: convertDivider($target),
 		entry: {
 			sourceTag: tag,
 			templaticalBlockType: "divider",
@@ -660,9 +1089,9 @@ function convertElement($el, $) {
 		}
 	};
 	if (TEXT_TAGS.has(tag)) {
-		if (!($el.text() ?? "").trim() && $el.find("img, a").length === 0) return null;
+		if (!hasRenderedContent($target)) return null;
 		return {
-			block: convertParagraph($el),
+			block: convertParagraph($target),
 			entry: {
 				sourceTag: tag,
 				templaticalBlockType: "paragraph",
@@ -671,7 +1100,7 @@ function convertElement($el, $) {
 		};
 	}
 	return {
-		block: convertHtmlFallback($el, $, `Unsupported element <${tag}>: preserved as raw HTML`),
+		block: convertHtmlFallback($target, $, `Unsupported element <${tag}>: preserved as raw HTML`),
 		entry: {
 			sourceTag: tag,
 			templaticalBlockType: "html",
@@ -681,6 +1110,211 @@ function convertElement($el, $) {
 	};
 }
 //#endregion
+//#region src/column-ratio.ts
+/**
+* The share of a section's width each column of a layout occupies.
+*
+* These are the percentages `@templatical/renderer` emits for the same layout
+* (`getWidthPercentages`), and they have to stay equal to them: this table is
+* what a declared ratio is snapped *to*, so a divergence would have the
+* importer choose `2-1` for a row the renderer then renders at some other
+* split — a silent disagreement with no failing surface between the two
+* packages. `@templatical/renderer` is a devDependency of this package and
+* must stay one (the importer has no runtime need of it), so the values are
+* copied rather than imported, and the agreement is asserted by the
+* renderer-agreement test in `column-ratio.test.ts`.
+*
+* Keyed by every `ColumnLayout`, so a new layout has to appear here before it
+* can be snapped to — and the candidate list below is derived from this table
+* rather than from a hand-written map of count to layouts, so adding one is a
+* single edit.
+*
+* Exported for that agreement test alone, which compares it against
+* `getWidthPercentages` value by value. Going through `resolveColumnRatio`
+* instead cannot do the job: a drift smaller than the snap tolerance still
+* snaps to the same layout, so a 50/50 target quietly moved to 55/45 passes
+* every behavioural case.
+*/
+const LAYOUT_SHARES = {
+	"1": [100],
+	"2": [50, 50],
+	"3": [
+		33.33,
+		33.33,
+		33.34
+	],
+	"1-2": [33.33, 66.67],
+	"2-1": [66.67, 33.33]
+};
+/**
+* How far, in percentage points on the worst column, a declared ratio may sit
+* from a layout and still be read as that layout.
+*
+* Measured against the corpus rather than chosen for roundness. The widest
+* real match is mailchimp's `width="350"` / `width="190"` sidebar row at
+* 64.8 / 35.2, **1.9pp** from `2-1`; the nearest declared ratio that must
+* *not* match is an 80 / 20 split at **13.3pp** from the same layout. Six sits
+* 3.2x above the first and 2.2x below the second.
+*
+* It also has to stay under 8.33, which is half the 16.67pp gap between the
+* two closest two-column layouts (`2` at 50/50 and `2-1` at 66.67/33.33):
+* above that the snap windows overlap and one ratio matches two layouts.
+*/
+const SNAP_TOLERANCE_PP = 6;
+/**
+* `mj-column-per-66-67` → 66.67%, `mj-column-per-50` → 50%. Compiled MJML
+* carries a column's share in its class name and nowhere else — every column
+* div also gets `style="width:100%"` — so this signal has to outrank the
+* inline style or every MJML layout reads as an equal split.
+*/
+const MJ_COLUMN_PERCENT = /(?:^|\s)mj-column-per-(\d+)(?:-(\d+))?(?=\s|$)/;
+/** `mj-column-px-350` → 350px, MJML's fixed-width column variant. */
+const MJ_COLUMN_PIXELS = /(?:^|\s)mj-column-px-(\d+)(?=\s|$)/;
+function parseColumnClass(className) {
+	if (!className) return null;
+	const percent = className.match(MJ_COLUMN_PERCENT);
+	if (percent) {
+		const fraction = percent[2] ? `.${percent[2]}` : "";
+		return usableWidth({
+			unit: "%",
+			value: parseFloat(`${percent[1]}${fraction}`)
+		});
+	}
+	const pixels = className.match(MJ_COLUMN_PIXELS);
+	if (pixels) return usableWidth({
+		unit: "px",
+		value: parseFloat(pixels[1])
+	});
+	return null;
+}
+/**
+* A length that states a share of its row, or `null`.
+*
+* A bare number is px, which is what a legacy `width="350"` attribute means.
+* Anything else — `auto`, a calc, an em length — states no share.
+*/
+function parseWidth(raw) {
+	if (raw === void 0) return null;
+	const match = raw.trim().match(/^(\d+(?:\.\d+)?)\s*(px|%)?$/);
+	if (!match) return null;
+	return usableWidth({
+		unit: match[2] === "%" ? "%" : "px",
+		value: parseFloat(match[1])
+	});
+}
+/**
+* Drops a width that cannot express a share of its row.
+*
+* `100%` is the trap this exists for: every compiled-MJML column div and every
+* Cerberus stack column carries `width:100%` beside its real cap, and a cell
+* claiming the whole row while sharing it with another cell is stating "fill
+* what is left" rather than a ratio. Normalising it reads two such columns as
+* an equal split, and one such column beside a 200px one as 33/67 — a ratio
+* the source never declared. A `100px` width is a real one, so the rule is on
+* the percentage unit alone.
+*/
+function usableWidth(width) {
+	if (!(width.value > 0)) return null;
+	if (width.unit === "%" && width.value >= 100) return null;
+	return width;
+}
+/**
+* The width a column host declares, read from the strongest signal it carries.
+*
+* Priority is by how specifically each signal states a *column's* share: an
+* `mj-column-*` class names it outright; `max-width` is the cap that decides
+* an inline-block column's rendered width and so wins over the `width:100%`
+* sitting beside it; a `width` style and the legacy `width` attribute come
+* last, style before attribute because CSS beats a presentational attribute in
+* every browser.
+*
+* Takes primitives rather than a Cheerio node so the whole ratio decision is
+* testable without a DOM.
+*/
+function readColumnWidth(className, styles, widthAttr) {
+	return parseColumnClass(className) ?? parseWidth(styles["max-width"]) ?? parseWidth(styles.width) ?? parseWidth(widthAttr);
+}
+/**
+* The declared widths as percentages of their row, or `null` when the row
+* declares no ratio at all.
+*
+* Every column must carry a width, in one unit: a single share of an unknown
+* total states no ratio, and neither does a px width beside a percentage. Both
+* are refused rather than guessed, because the fallback — the layout the
+* column count already gives — is correct, and a guess is not.
+*/
+function normalizeShares(widths) {
+	if (widths.length === 0) return null;
+	const first = widths[0];
+	if (!first) return null;
+	if (widths.some((width) => !width || width.unit !== first.unit)) return null;
+	const values = widths.map((width) => width.value);
+	const total = values.reduce((sum, value) => sum + value, 0);
+	if (!(total > 0)) return null;
+	return values.map((value) => value / total * 100);
+}
+/** The layouts that hold exactly this many columns. */
+function candidateLayouts(count) {
+	return Object.keys(LAYOUT_SHARES).filter((layout) => LAYOUT_SHARES[layout].length === count);
+}
+/** How far the worst column of `shares` sits from `layout`, in points. */
+function deviation(shares, layout) {
+	const target = LAYOUT_SHARES[layout];
+	return Math.max(...shares.map((share, i) => Math.abs(share - target[i])));
+}
+/** The layout `shares` states, or `null` when none is within tolerance. */
+function snapToLayout(shares) {
+	let best = null;
+	let bestDeviation = Number.POSITIVE_INFINITY;
+	for (const layout of candidateLayouts(shares.length)) {
+		const distance = deviation(shares, layout);
+		if (distance < bestDeviation) {
+			best = layout;
+			bestDeviation = distance;
+		}
+	}
+	return best !== null && bestDeviation <= SNAP_TOLERANCE_PP ? best : null;
+}
+function formatShare(share) {
+	return `${Math.round(share * 10) / 10}%`;
+}
+/**
+* What snapping could not express, named as the reader sees it.
+*
+* "equal columns" is true because the layouts a count alone produces — `2` and
+* `3` — are both equal splits; `resolveColumnRatio` is the only caller and
+* never reaches here for any other. Naming the layout's own percentages
+* instead would leak the renderer's 33.34 rounding column into a report.
+*/
+function describeRatioLoss(shares) {
+	return `Column widths ${shares.map(formatShare).join(" / ")} have no Templatical equivalent. The section was imported as ${shares.length} equal columns.`;
+}
+/**
+* The layout a row's declared widths choose, given the layout its column count
+* already produced.
+*
+* Widths decide the *ratio* and never the count: `counted` fixes how many
+* columns there are, and the only layouts considered are the ones holding
+* exactly that many. A row declaring nothing, declaring only some of its
+* columns, or mixing units keeps `counted` and reports nothing — there is no
+* observed ratio to have lost. A ratio outside tolerance keeps `counted` too,
+* and names itself in a note, which is the only outcome that is a downgrade.
+*
+* Call it only for a `counted` that has columns to choose between. A merged
+* row (`"1"`) has none, and describing the ratio of columns the section no
+* longer has would contradict the merge note that row already carries.
+*/
+function resolveColumnRatio(widths, counted) {
+	const shares = normalizeShares(widths);
+	if (!shares) return { layout: counted };
+	const snapped = snapToLayout(shares);
+	if (snapped) return { layout: snapped };
+	return {
+		layout: counted,
+		note: describeRatioLoss(shares)
+	};
+}
+//#endregion
 //#region src/section-builder.ts
 function emptyPadding$1() {
 	return {
@@ -763,6 +1397,262 @@ function resolveColumnLayout(cellCount, warnings) {
 	warnings.push(`Row with ${cellCount} columns was flattened to a single column. Templatical supports up to 3 columns per section.`);
 	return "1";
 }
+/**
+* The one cell a row's content sits in, when every other cell of that row is
+* chrome rather than a column — or `null` when the row is a layout row in its
+* own right.
+*
+* Table-based email centres a fixed-width body by flanking it with blank
+* cells, and Foundation-derived markup pads a row out with a blank `expander`
+* cell. Counting cells reads both as columns: leemunroe's template, the
+* most-copied table email there is, imported as a three-column section with
+* the entire email crushed into the middle third and two empty columns beside
+* it. That is worse than the single column a cell count could never have
+* produced, so it is the one place a row's cell count is not the column count.
+*
+* The signal is content, never width: a cell is chrome when it holds nothing
+* a reader sees (`isBlankCell`), which covers a `&nbsp;` gutter and an empty
+* `expander` alike, and covers a blank cell stating a height — a horizontal
+* gutter's height says nothing about the row.
+*
+* Two constraints, both hazards a relaxed version would reintroduce:
+*
+* - Exactly one cell may carry content. Two filled cells and a blank third
+*   is a grid with an empty slot, and collapsing it would re-flow the filled
+*   columns from thirds to halves.
+* - A row with content in no cell at all is left alone. Its cells sit side by
+*   side, so it states one gap per column rather than a stack of them, and
+*   merging them would add their heights and invent vertical space.
+*
+* This rule is coupled to the container descent in `packagingTablesOf`, and
+* neither is complete without the other: the descent reaches Foundation's
+* layout rows, whose blank `expander` cell then reads as a second column
+* holding nothing but a spacer. Removing this rule turns every one of those
+* rows into a phantom two-column section.
+*/
+function centringCells(cells) {
+	if (cells.length < 2) return null;
+	const withContent = cells.filter(($cell) => !isBlankCell($cell));
+	return withContent.length === 1 ? withContent : null;
+}
+/**
+* Whether the markup below a layout container states columns anywhere: a row
+* with two or more cells carrying content.
+*
+* This gates the container descent below, and only there — the two content
+* walks descend a container unconditionally, which is right for them because
+* they convert its children in place. The packaging descent *promotes* the
+* rows it reaches to sections of their own, so it needs evidence that those
+* rows are layout rather than stacked content.
+*
+* Without the evidence test the descent shatters a section into one section
+* per block, wherever a single cell holds one container per column instead of
+* one cell per column. Measured on compiled MJML — a `div.mj-column-per-*`
+* per column inside one `<td>` — a five-section email imported as thirteen
+* one-block sections, and Cerberus's hybrid template went from 14 sections to
+* 24. Neither loses text; both lose the grouping the source stated, and a
+* cell holding parallel containers has no column count below it to recover in
+* exchange.
+*
+* Content-bearing cells, not cells: a blank-flanked row is one column, which
+* is what `centringCells` reads it as. Counting bare cells here would make
+* this the second answer in the file to "is this row a set of columns?".
+*/
+function declaresColumnsBelow($el, $) {
+	let found = false;
+	$el.find("tr").each((_, row) => {
+		if (found) return;
+		if (getDirectCells($(row), $).filter(($cell) => !isBlankCell($cell)).length > 1) found = true;
+	});
+	return found;
+}
+/**
+* The tables that make up a cell's entire meaningful content, or `null` when
+* the cell holds anything else.
+*
+* Anything that is not a table has to leave nothing behind for the cell to
+* count as packaging: whitespace, comments, and inline formatting carrying no
+* text all produce no block, so a cell holding tables and a bare `<br>`
+* qualifies while one holding a heading beside its table does not.
+*
+* A layout container is descended rather than refused, through the same
+* `isTableContainer` predicate the two content walks use — plus the evidence
+* test above, which is what keeps the descent from shattering a section whose
+* columns are sibling containers in one cell. Refusing a container outright
+* made a `<div>` or a `<center>` between the cell and the layout table enough
+* to defeat the descent, and the cell walk then flattened the whole subtree
+* into one column: ZURB Inky's output, which wraps every email in a
+* `<center>`, imported as a single one-column section.
+*
+* The recursion is what keeps the guard below intact through the wrapper: a
+* container holding prose beside its table answers `null`, which propagates,
+* and the row keeps the section that carries that prose.
+*
+* Bounded by DOM depth — a container is descended only when it holds a table,
+* and each step moves to a child.
+*/
+function packagingTablesOf($cell, $) {
+	const tables = [];
+	let inlineText = "";
+	for (const node of $cell.contents().toArray()) {
+		if (isInlineContent(node)) {
+			inlineText += $(node).text();
+			continue;
+		}
+		if (!isTag(node)) continue;
+		const tag = node.tagName.toLowerCase();
+		const $child = $(node);
+		if (tag === "table") {
+			tables.push($child);
+			continue;
+		}
+		if (isTableContainer($child, tag) && declaresColumnsBelow($child, $)) {
+			const nested = packagingTablesOf($child, $);
+			if (nested === null) return null;
+			tables.push(...nested);
+			continue;
+		}
+		return null;
+	}
+	if (tables.length === 0) return null;
+	if (inlineText.trim() !== "") return null;
+	return tables;
+}
+/**
+* The tables a row is merely packaging for, or `null` when the row is layout
+* in its own right.
+*
+* Table-based email buries the row that states the real column count under
+* one-cell wrapper tables, and a section emitted for a wrapper resolves
+* `columns` from that single cell — reporting one column for a row that has
+* two or three. Descending to the table inside reads the count off the row
+* that actually declares it, which is counting cells rather than inferring a
+* layout from widths or class names.
+*
+* Two conditions keep the descent from losing anything, and both are hazards
+* a future edit would reintroduce by relaxing them:
+*
+* - The cell's meaningful content must *be* the tables. Descending discards
+*   the row, so a heading or an image beside the table would be dropped.
+* - The row must carry no background and no padding. The section it emits is
+*   the only carrier for those, so descending past a styled row would drop
+*   the band it paints.
+*/
+function packagingRowTables($row, cells, $) {
+	if (cells.length !== 1) return null;
+	const rowStyles = getStyles($row);
+	if (parseColor(rowStyles["background-color"]) || parseColor(rowStyles.background)) return null;
+	const padding = readPaddingFromStyles(rowStyles);
+	if (padding.top || padding.right || padding.bottom || padding.left) return null;
+	return packagingTablesOf(cells[0], $);
+}
+/**
+* The report entry for the section a layout row produces.
+*
+* Whether the row was downgraded is read off the slots that were actually
+* built: one slot per cell means every cell kept its own column, while fewer
+* slots than cells means `resolveColumnLayout` merged them. Deciding it by
+* comparing the cell count against the column ceiling instead would be a
+* second source of truth for that ceiling and would start lying the moment
+* the resolver changed. The ceiling appears only in the note's wording, where
+* it explains the merge to a reader rather than driving the branch.
+*
+* A faithful row gets no `note` at all. Attaching one unconditionally makes
+* "nothing was lost" indistinguishable from a downgrade for a caller that
+* filters on `note`, which is the whole reason the field is optional.
+*
+* `cellCount` is the row's column-bearing cells, not every cell it has: a
+* centring row's gutters were never columns, so counting them would report a
+* three-into-one merge for a row that always stated one column.
+*/
+function sectionEntry(cellCount, slotCount, ratioNote) {
+	if (slotCount !== cellCount) return {
+		sourceTag: "tr",
+		templaticalBlockType: "section",
+		status: "approximated",
+		note: `Row of ${cellCount} cells was merged into a single column. Templatical sections hold at most 3 columns.`
+	};
+	if (ratioNote) return {
+		sourceTag: "tr",
+		templaticalBlockType: "section",
+		status: "approximated",
+		note: ratioNote
+	};
+	return {
+		sourceTag: "tr",
+		templaticalBlockType: "section",
+		status: "converted"
+	};
+}
+/**
+* The report entry for a nested row whose section wrapper was dropped, or
+* `null` when dropping it lost nothing.
+*
+* `packages/core/src/editor.ts` forbids a section inside a column because MJML
+* forbids `mj-section` there, so a layout table reached from a cell has to
+* flatten — the columns are gone regardless. One cell has no columns to lose,
+* and reporting that as a downgrade would fill the report with entries for a
+* non-event.
+*
+* The count is the row's column-bearing cells, for the same reason
+* `sectionEntry`'s is: a centring row flattened into a parent column lost
+* nothing, so it must report nothing.
+*/
+function flattenedRowEntry(cellCount) {
+	if (cellCount <= 1) return null;
+	return {
+		sourceTag: "tr",
+		templaticalBlockType: null,
+		status: "approximated",
+		note: `Nested row of ${cellCount} cells lost its columns. A Templatical section cannot nest inside a column, so its cells were merged into the surrounding column.`
+	};
+}
+/**
+* The elements that each carry one of the row's columns.
+*
+* A cell holding a column set is replaced by that set, so the count comes from
+* the divs rather than from the one cell around them. Only a single layout
+* cell is considered: columns inside a column are not representable, so a
+* multi-cell row keeps its cells and can never have its count *reduced* by
+* this rule.
+*
+* Asked after `centringCells`, which is what lets a gutter-flanked row whose
+* middle cell holds a column set still be read as that set.
+*/
+function columnHostsOf(layoutCells, $) {
+	if (layoutCells.length === 1) {
+		const containers = columnDivsOf(layoutCells[0], $);
+		if (containers) return containers.map(($el) => ({
+			$el,
+			kind: "container"
+		}));
+	}
+	return layoutCells.map(($el) => ({
+		$el,
+		kind: "cell"
+	}));
+}
+/**
+* The blocks a column host contributes.
+*
+* A promoted container takes the content walk rather than the cell walk,
+* which is the same walk a container reached from inside a cell already gets
+* — so promoting one changes which slot its blocks land in and nothing about
+* how they convert. The two early returns the cell walk adds are about cells
+* specifically — `isSpacerCell` reads a `<td height>`, and `isButtonCell`
+* reads the cell-level styling table-based email wraps a call to action in —
+* and `looksLikeButton` answers true for `display: inline-block`, which every
+* column container carries. Handing a container to the cell walk would turn a
+* column whose content is one link into a single button block and drop
+* everything the column's own table holds.
+*/
+function extractHostBlocks(host, $, entries, warnings) {
+	return host.kind === "cell" ? extractCellBlocks(host.$el, $, entries, warnings) : extractContentBlocks(host.$el, $, entries, warnings);
+}
+/** The width an element declares, from the strongest signal it carries. */
+function readDeclaredWidth($el) {
+	return readColumnWidth($el.attr("class"), getStyles($el), $el.attr("width"));
+}
 function extractCellBlocks($cell, $, entries, warnings) {
 	if (isSpacerCell($cell)) {
 		entries.push({
@@ -781,24 +1671,34 @@ function extractCellBlocks($cell, $, entries, warnings) {
 		});
 		return [buildCellButton($cell, btn.anchor)];
 	}
+	return extractContentBlocks($cell, $, entries, warnings);
+}
+/**
+* The blocks an element's child nodes produce, for an element that holds
+* content rather than being content itself: a table cell, or a layout
+* container descended from one.
+*
+* Node classification — bare text and inline markup grouped into runs, a
+* prose anchor folded into the run around it, comments passed over without
+* splitting one — is `walkContentNodes`' half, shared with the body walk in
+* `converter.ts`. What is left here is the half that differs: inside a cell a
+* nested table flattens into the surrounding column, where at body level it
+* becomes a section of its own.
+*/
+function extractContentBlocks($host, $, entries, warnings) {
 	const blocks = [];
-	const childEls = $cell.children().toArray();
-	if (childEls.length === 0) {
-		if (!($cell.text() ?? "").trim()) return [];
-		const r = convertElement($cell, $);
-		if (r) {
-			entries.push(r.entry);
-			blocks.push(r.block);
-		}
-		return blocks;
-	}
-	for (const childEl of childEls) {
-		const $child = $(childEl);
-		const tag = childEl.tagName?.toLowerCase() ?? "";
+	walkContentNodes($host, $, ({ block, entry }) => {
+		entries.push(entry);
+		blocks.push(block);
+	}, ($child, tag) => {
 		if (tag === "table") {
 			const inner = processTable($child, $, entries, warnings, true);
 			blocks.push(...inner);
-			continue;
+			return;
+		}
+		if (isTableContainer($child, tag)) {
+			blocks.push(...extractContentBlocks($child, $, entries, warnings));
+			return;
 		}
 		if (tag === "a" && looksLikeButton(getStyles($child))) {
 			const r = convertElement($child, $);
@@ -806,14 +1706,14 @@ function extractCellBlocks($cell, $, entries, warnings) {
 				entries.push(r.entry);
 				blocks.push(r.block);
 			}
-			continue;
+			return;
 		}
 		const r = convertElement($child, $);
 		if (r) {
 			entries.push(r.entry);
 			blocks.push(r.block);
 		}
-	}
+	});
 	return blocks;
 }
 /**
@@ -839,22 +1739,35 @@ function processTable($table, $, entries, warnings, flattenInline = false) {
 	for (const $row of rows) {
 		const cells = getDirectCells($row, $);
 		if (cells.length === 0) continue;
-		const layout = resolveColumnLayout(cells.length, warnings);
+		const packaging = packagingRowTables($row, cells, $);
+		if (packaging) {
+			for (const $inner of packaging) sections.push(...processTable($inner, $, entries, warnings, flattenInline));
+			continue;
+		}
+		const hosts = columnHostsOf(centringCells(cells) ?? cells, $);
+		const countedLayout = resolveColumnLayout(hosts.length, warnings);
 		let columnsBlocks;
-		if (layout === "1") {
+		if (countedLayout === "1") {
 			const merged = [];
-			for (const $cell of cells) merged.push(...extractCellBlocks($cell, $, entries, warnings));
+			for (const host of hosts) merged.push(...extractHostBlocks(host, $, entries, warnings));
 			columnsBlocks = [merged];
-		} else columnsBlocks = cells.map(($cell) => extractCellBlocks($cell, $, entries, warnings));
+		} else columnsBlocks = hosts.map((host) => extractHostBlocks(host, $, entries, warnings));
 		if (flattenInline) {
+			const dropped = flattenedRowEntry(hosts.length);
+			if (dropped) entries.push(dropped);
 			for (const col of columnsBlocks) sections.push(...col);
 			continue;
 		}
+		const ratio = countedLayout === "1" ? {
+			layout: countedLayout,
+			note: void 0
+		} : resolveColumnRatio(hosts.map((host) => readDeclaredWidth(host.$el)), countedLayout);
 		const rowStyles = getStyles($row);
 		const bgColor = parseColor(rowStyles["background-color"]) || parseColor(rowStyles.background);
 		const padding = readPaddingFromStyles(rowStyles);
+		entries.push(sectionEntry(hosts.length, columnsBlocks.length, ratio.note));
 		sections.push(createSectionBlock({
-			columns: layout,
+			columns: ratio.layout,
 			children: columnsBlocks,
 			styles: {
 				padding,
@@ -903,9 +1816,21 @@ function extractSettings($) {
 }
 /**
 * Wrap a list of free-floating blocks (those produced by top-level non-table
-* elements) in a single one-column section.
+* elements) in a single one-column section, and report the section.
+*
+* The section corresponds to no source element, so the report names `body` and
+* says the section is synthetic — otherwise a caller counting sections against
+* the rows it can see in the source finds one it cannot account for. Nothing is
+* lost on this path: every loose block keeps its order inside the one column,
+* which is why the status is `converted` rather than an approximation.
 */
-function wrapInSection(blocks) {
+function wrapInSection(blocks, entries) {
+	entries.push({
+		sourceTag: "body",
+		templaticalBlockType: "section",
+		status: "converted",
+		note: "Loose top-level content was grouped into a synthetic single-column section."
+	});
 	return createSectionBlock({
 		columns: "1",
 		children: [blocks],
@@ -913,53 +1838,82 @@ function wrapInSection(blocks) {
 	});
 }
 /**
-* Walk top-level body children. Tables become sections; loose content
-* elements are accumulated and wrapped in a single one-column section.
+* Walk the body's child nodes. Tables become sections; loose content is
+* accumulated and wrapped in a single one-column section.
+*
+* Both walks below go through `walkContentNodes`, the same node
+* classification the cell walk uses, so bare text and inline markup at body
+* level and inside a layout container reach a rich-text block. A walk over
+* `children()` visits neither, which drops copy the source email displays —
+* `Lead<h2>H</h2>Trailing` imported as the heading alone.
 */
 function processBody($, entries, warnings) {
 	const blocks = [];
-	const children = $("body").children().toArray();
+	const $body = $("body");
 	let pendingLoose = [];
 	const flushLoose = () => {
 		if (pendingLoose.length > 0) {
-			blocks.push(wrapInSection(pendingLoose));
+			blocks.push(wrapInSection(pendingLoose, entries));
 			pendingLoose = [];
 		}
 	};
-	for (const childEl of children) {
-		const tag = childEl.tagName?.toLowerCase() ?? "";
-		const $child = $(childEl);
+	const collectLoose = ({ block, entry }) => {
+		entries.push(entry);
+		pendingLoose.push(block);
+	};
+	/**
+	* Descend a layout container, taking its tables as sections and everything
+	* else as loose content. A container holding another container descends
+	* again, so a table reaches `processTable` at whatever depth the wrapper
+	* markup buries it — MJML nests an outer body div around one div per
+	* section around the section's table, and a single-level walk sees only the
+	* middle div, which the block mapper turns into one paragraph swallowing
+	* the entire table subtree.
+	*
+	* Bounded by DOM depth: a container is descended only when it holds a
+	* table, and each step moves to a child.
+	*
+	* Declared here so every depth shares `pendingLoose` and `flushLoose`. A
+	* per-level accumulator flushes at the wrong point and reorders the
+	* document: content sitting before a nested table lands after it.
+	*/
+	const walkContainer = ($container) => {
+		walkContentNodes($container, $, collectLoose, ($inner, innerTag) => {
+			if (innerTag === "table") {
+				flushLoose();
+				blocks.push(...processTable($inner, $, entries, warnings, false));
+				return;
+			}
+			if (isTableContainer($inner, innerTag)) {
+				walkContainer($inner);
+				return;
+			}
+			const r = convertElement($inner, $);
+			if (r) {
+				entries.push(r.entry);
+				pendingLoose.push(r.block);
+			}
+		});
+	};
+	walkContentNodes($body, $, collectLoose, ($child, tag) => {
 		if (tag === "table") {
 			flushLoose();
 			blocks.push(...processTable($child, $, entries, warnings, false));
-			continue;
+			return;
 		}
-		if ((parseStyleAttribute($child.attr("style")).display ?? "").toLowerCase() === "none") continue;
-		if ((tag === "div" || tag === "center" || tag === "main") && $child.find("table").length > 0) {
+		if ((parseStyleAttribute($child.attr("style")).display ?? "").toLowerCase() === "none") return;
+		if (isTableContainer($child, tag)) {
 			flushLoose();
-			$child.children().each((_, innerEl) => {
-				const innerTag = innerEl.tagName?.toLowerCase() ?? "";
-				const $inner = $(innerEl);
-				if (innerTag === "table") {
-					flushLoose();
-					blocks.push(...processTable($inner, $, entries, warnings, false));
-				} else {
-					const r = convertElement($inner, $);
-					if (r) {
-						entries.push(r.entry);
-						pendingLoose.push(r.block);
-					}
-				}
-			});
+			walkContainer($child);
 			flushLoose();
-			continue;
+			return;
 		}
 		const r = convertElement($child, $);
 		if (r) {
 			entries.push(r.entry);
 			pendingLoose.push(r.block);
 		}
-	}
+	});
 	flushLoose();
 	return blocks;
 }