@templatical/import-mjml 0.31.0

package/dist/index.js

@@ -0,0 +1,1498 @@
+import { load } from "cheerio";
+import { DEFAULT_TEMPLATE_DEFAULTS, RICH_TEXT_SPACING, SYNTAX_PRESETS, createButtonBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createMenuBlock, createParagraphBlock, createSectionBlock, createSocialIconsBlock, createSpacerBlock, createTableBlock, createTitleBlock, generateId } from "@templatical/types";
+//#region src/attribute-resolver.ts
+/**
+* A node's tag name, lowercased.
+*
+* The parser configuration this package uses (`xmlMode: false`, set in
+* `converter.ts`) already lowercases every tag at parse time, so this call is
+* a no-op on that parser's output. It remains the one place every tag
+* comparison in this package goes through, so a comparison stays correct
+* regardless of the active parser configuration — a bare `$("mj-body")` would
+* otherwise miss a document that shouts its tags.
+*/
+function tagOf(node) {
+	if (!node) return "";
+	return node.tagName?.toLowerCase() ?? "";
+}
+/**
+* Every element with the given tag name, matched case-insensitively.
+*/
+function findByTag($, tag) {
+	const wanted = tag.toLowerCase();
+	return $("*").filter((_, el) => tagOf(el) === wanted);
+}
+/**
+* An element's element children.
+*
+* `.children()` already excludes text and comment nodes; the tag filter here
+* guards against a node whose `tagName` is undefined, not against either of
+* those.
+*/
+function childElements($el, $) {
+	return $el.children().toArray().filter((node) => tagOf(node) !== "").map((node) => $(node));
+}
+function attrsOf($el) {
+	const raw = $el.attr();
+	if (!raw) return {};
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) out[key.toLowerCase()] = value;
+	return out;
+}
+/**
+* Read `mj-head > mj-attributes` into the three buckets the cascade resolves
+* against. Called once per document; `resolveAttributes` is then pure lookup.
+*/
+function buildAttributeCascade($) {
+	const cascade = {
+		all: Object.create(null),
+		byTag: Object.create(null),
+		byClass: Object.create(null)
+	};
+	const containers = findByTag($, "mj-attributes").toArray();
+	for (const container of containers) {
+		const $container = $(container);
+		for (const $child of childElements($container, $)) {
+			const tag = tagOf($child[0]);
+			const attrs = attrsOf($child);
+			if (tag === "mj-all") {
+				Object.assign(cascade.all, attrs);
+				continue;
+			}
+			if (tag === "mj-class") {
+				const { name, ...rest } = attrs;
+				if (!name) continue;
+				cascade.byClass[name] = {
+					...cascade.byClass[name] ?? {},
+					...rest
+				};
+				continue;
+			}
+			cascade.byTag[tag] = {
+				...cascade.byTag[tag] ?? {},
+				...attrs
+			};
+		}
+	}
+	return cascade;
+}
+/**
+* The first two cascade layers alone — `mj-all` then the per-tag default —
+* with neither a named `mj-class` nor the element's own inline attributes on
+* top. This is the ambient value a tag inherits before the element sets
+* anything of its own, which is what {@link ownAttr} compares against.
+*/
+function resolveTagDefaults(tag, cascade) {
+	return {
+		...cascade.all,
+		...cascade.byTag[tag] ?? {}
+	};
+}
+/**
+* An element's effective attributes, highest precedence last:
+* `mj-all` → per-tag default → each named `mj-class` → the element's own
+* inline attributes.
+*
+* MJML's built-in component defaults are deliberately not modelled — the block
+* factories in `@templatical/types` supply that floor instead, which keeps this
+* module from becoming a copy of MJML's component table.
+*/
+function resolveAttributes($el, cascade) {
+	const own = attrsOf($el);
+	const resolved = resolveTagDefaults(tagOf($el[0]), cascade);
+	const classNames = (own["mj-class"] ?? "").trim().split(/\s+/).filter(Boolean);
+	for (const name of classNames) Object.assign(resolved, cascade.byClass[name] ?? {});
+	Object.assign(resolved, own);
+	delete resolved["mj-class"];
+	return resolved;
+}
+/**
+* A resolved attribute value, but only when the element is the reason it has
+* that value — a named `mj-class` counts as the element opting in, but a bare
+* `mj-all`/per-tag cascade default does not.
+*
+* This reverses the renderer's inherit-by-omission convention for `mj-text`'s
+* `color` and `font-family`: `renderers/title.ts`, `table.ts` and `menu.ts`
+* all emit that attribute only when the block sets its own value, otherwise
+* leaving the element to inherit the document default from
+* `<mj-attributes>` (`renderers/title.ts:31`). `resolveAttributes` flattens
+* that default onto every element of the tag regardless, so reading `attrs`
+* directly cannot tell "the block set this" from "the document default
+* reached this element too" — and treating the latter as the former invents
+* a per-block override the source never made.
+*
+* `resolved === ambient` also covers an element that repeats the ambient
+* value on purpose: the two cases render identically, so which one happened
+* is not observable in the output and dropping it costs nothing (the same
+* reasoning as §8.3b's image-width and §8.4b's paragraph-gap defaults).
+*/
+function ownAttr(attrs, key, tag, cascade) {
+	const resolved = attrs[key];
+	if (resolved === void 0) return void 0;
+	return resolved === resolveTagDefaults(tag, cascade)[key] ? void 0 : resolved;
+}
+const HIDE_DESKTOP = "tpl-hide-desktop";
+const HIDE_MOBILE = "tpl-hide-mobile";
+/**
+* Marks a rendered title or paragraph's rich-text spacing — mirrors
+* `RICH_TEXT_CSS_CLASS` in `packages/renderer/src/rich-text.ts`. `title.ts`
+* and `paragraph.ts` are the only two renderers that pass a second argument
+* to `getCssClassAttr`, so every rendered title and paragraph carries this
+* class on `css-class` alongside any visibility markers.
+*/
+const RICH_TEXT_CSS_CLASS = "tpl-rich-text";
+/**
+* Matches the per-block paragraph-gap class the same two renderers append,
+* e.g. `tpl-rich-text-8` (`richTextGapClass` in `rich-text.ts`). The gap
+* accepts a decimal (`tpl-rich-text-8.5`) because `ParagraphBlock.paragraphSpacing`
+* is a plain `number` that a headless caller can set to a fractional value,
+* even though the editor UI clamps it to an integer. Negative gaps are out of
+* scope — the renderer never emits one, so there is nothing here that needs to
+* recognise it.
+*
+* Shared by `readForeignCssClasses` (which classes to exclude) and
+* `readParagraphGap` (which class to decode), so the two can never disagree
+* about what a gap class looks like.
+*/
+const RICH_TEXT_GAP_CLASS = /^tpl-rich-text-(\d+(?:\.\d+)?)$/;
+function cssClasses(attrs) {
+	return (attrs["css-class"] ?? "").trim().split(/\s+/).filter(Boolean);
+}
+/**
+* Reverse of the renderer's `getCssClassAttr` (`packages/renderer/src/visibility.ts`).
+* `css-class` also carries the rich-text markers below (`RICH_TEXT_CSS_CLASS`,
+* `RICH_TEXT_GAP_CLASS`) — this function reads only the two visibility
+* classes off it and leaves those alone.
+*
+* Returns `undefined` when neither class is present — absence means visible
+* everywhere, and writing `{ desktop: true, mobile: true }` instead would put a
+* redundant key in every imported block.
+*/
+function readVisibility(attrs) {
+	const classes = cssClasses(attrs);
+	const hideDesktop = classes.includes(HIDE_DESKTOP);
+	const hideMobile = classes.includes(HIDE_MOBILE);
+	if (!hideDesktop && !hideMobile) return void 0;
+	return {
+		desktop: !hideDesktop,
+		mobile: !hideMobile
+	};
+}
+/**
+* The paragraph gap encoded on a rendered title or paragraph's `css-class` —
+* reverse of `richTextGapClass` (`packages/renderer/src/rich-text.ts`), e.g.
+* `8` from `tpl-rich-text-8`.
+*
+* Returns `null` when no gap class is present. Callers must not confuse that
+* with a gap of `0`, which is a legitimate value in its own right.
+*/
+function readParagraphGap(attrs) {
+	for (const name of cssClasses(attrs)) {
+		const match = RICH_TEXT_GAP_CLASS.exec(name);
+		if (match) return parseFloat(match[1]);
+	}
+	return null;
+}
+/**
+* Classes on `css-class` that carry no Templatical meaning. The caller warns
+* about these rather than dropping them silently: they are consumer CSS with no
+* home in the block model, and a template that relies on them will render
+* differently after import.
+*
+* Excludes the renderer's own rich-text markers alongside the two visibility
+* classes, so importing a template the renderer itself produced does not
+* report a title or paragraph's own spacing class as foreign. A consumer's
+* own `tpl-`-prefixed class is not one of these markers and is still reported.
+*/
+function readForeignCssClasses(attrs) {
+	return cssClasses(attrs).filter((name) => name !== HIDE_DESKTOP && name !== HIDE_MOBILE && name !== RICH_TEXT_CSS_CLASS && !RICH_TEXT_GAP_CLASS.test(name));
+}
+//#endregion
+//#region src/attribute-parser.ts
+/**
+* Parses a px-like MJML attribute value (`"12px"`, `"12"`, `12`) into a rounded
+* integer. Returns 0 for missing or unparseable input, and for units the block
+* model cannot express (em, rem, %) — a caller that needs to tell "absent" from
+* "0" must check the raw attribute itself.
+*/
+function parsePxValue(value) {
+	if (value === void 0 || value === null || value === "") return 0;
+	if (typeof value === "number") return Math.round(value);
+	const match = value.match(/^\s*(-?\d+(?:\.\d+)?)\s*(?:px)?\s*$/);
+	return match ? Math.round(parseFloat(match[1])) : 0;
+}
+const NAMED_COLORS = {
+	black: "#000000",
+	white: "#ffffff",
+	red: "#ff0000",
+	green: "#008000",
+	blue: "#0000ff",
+	yellow: "#ffff00",
+	cyan: "#00ffff",
+	magenta: "#ff00ff",
+	gray: "#808080",
+	grey: "#808080",
+	silver: "#c0c0c0",
+	maroon: "#800000",
+	olive: "#808000",
+	lime: "#00ff00",
+	aqua: "#00ffff",
+	teal: "#008080",
+	navy: "#000080",
+	fuchsia: "#ff00ff",
+	purple: "#800080",
+	orange: "#ffa500",
+	pink: "#ffc0cb"
+};
+function rgbToHex(r, g, b) {
+	const clamp = (n) => Math.max(0, Math.min(255, Math.round(n)));
+	const hex = (n) => clamp(n).toString(16).padStart(2, "0");
+	return `#${hex(r)}${hex(g)}${hex(b)}`;
+}
+/**
+* Normalizes a colour value to a 6-digit lowercase hex string.
+*
+* Returns `""` for transparent/inherit/none and for anything unrecognised.
+* The empty string is the block model's "unset" — the colour pickers clear to
+* it — so returning it is meaningfully different from returning a default.
+*/
+function parseColor(value) {
+	if (!value) return "";
+	const trimmed = value.trim().toLowerCase();
+	if (trimmed === "transparent" || trimmed === "inherit" || trimmed === "none") return "";
+	if (/^#[0-9a-f]{6}$/.test(trimmed)) return trimmed;
+	if (/^#[0-9a-f]{3}$/.test(trimmed)) {
+		const r = trimmed[1];
+		const g = trimmed[2];
+		const b = trimmed[3];
+		return `#${r}${r}${g}${g}${b}${b}`;
+	}
+	const rgbMatch = trimmed.match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*[\d.]+\s*)?\)$/);
+	if (rgbMatch) return rgbToHex(parseInt(rgbMatch[1], 10), parseInt(rgbMatch[2], 10), parseInt(rgbMatch[3], 10));
+	if (NAMED_COLORS[trimmed]) return NAMED_COLORS[trimmed];
+	return "";
+}
+/**
+* Parses an MJML `padding` shorthand (1-4 values, CSS order) into a
+* SpacingValue.
+*/
+function parsePaddingShorthand(value) {
+	if (!value) return {
+		top: 0,
+		right: 0,
+		bottom: 0,
+		left: 0
+	};
+	const values = value.trim().split(/\s+/).map((p) => parsePxValue(p));
+	switch (values.length) {
+		case 1: return {
+			top: values[0],
+			right: values[0],
+			bottom: values[0],
+			left: values[0]
+		};
+		case 2: return {
+			top: values[0],
+			right: values[1],
+			bottom: values[0],
+			left: values[1]
+		};
+		case 3: return {
+			top: values[0],
+			right: values[1],
+			bottom: values[2],
+			left: values[1]
+		};
+		default: return {
+			top: values[0],
+			right: values[1],
+			bottom: values[2],
+			left: values[3]
+		};
+	}
+}
+/**
+* Strips quotes and returns the first font in a font-family stack.
+*/
+function parseFontFamily(value) {
+	if (!value) return "";
+	return value.split(",")[0].trim().replace(/^['"]|['"]$/g, "");
+}
+/**
+* Parses an alignment to one of the three the block model accepts.
+*/
+function parseAlignment(value, fallback = "left") {
+	const v = (value ?? "").trim().toLowerCase();
+	if (v === "left" || v === "center" || v === "right") return v;
+	return fallback;
+}
+/**
+* Reads a percentage value, or `null` when the value is not a percentage.
+*
+* `null` rather than a number, because column-width matching (§8.1) has to tell
+* "no percentage given" from "0%" — the former distributes widths equally, the
+* latter is a real (if degenerate) width.
+*/
+function parsePercent(value) {
+	if (!value) return null;
+	const match = value.trim().match(/^(\d+(?:\.\d+)?)\s*%$/);
+	return match ? parseFloat(match[1]) : null;
+}
+/**
+* Reads a definite px length, or `null` when the value is not one.
+*
+* Unlike `parsePxValue`, which returns `0` for anything unparseable, this
+* tells "no length given" apart from "0px" — column-width recovery (§8.1)
+* needs that distinction for a px `mj-column` width the same way it needs
+* `parsePercent`'s `null` for a percentage one, so the two compose into a
+* single known-or-absent value the matcher can fill around.
+*/
+function parseDefinitePx(value) {
+	if (!value) return null;
+	const match = value.trim().match(/^(-?\d+(?:\.\d+)?)\s*(?:px)?$/);
+	return match ? parseFloat(match[1]) : null;
+}
+/**
+* Narrows a border style to the three `DividerBlock.lineStyle` accepts.
+*/
+function parseBorderStyle(value) {
+	const v = (value ?? "").trim().toLowerCase();
+	if (v === "dashed" || v === "dotted") return v;
+	return "solid";
+}
+//#endregion
+//#region src/block-base.ts
+/**
+* The `styles` and `visibility` every block shares.
+*
+* `placement` mirrors the renderer's own `BgPlacement` split
+* (`packages/renderer/src/utils.ts`): `mj-section` is the one "native"
+* element, whose own `background-color` attribute *is* `styles.backgroundColor`
+* (`renderers/section.ts:32`). Every other block type emits
+* `container-background-color` for that same field, because a plain
+* `background-color` on those tags already means something else of the
+* element's own — a button's fill (`renderers/button.ts:43`), for one — and
+* reading it back as the block's container background would invent a fill
+* the source never had. Defaulting to `"container"` matches every caller but
+* `buildSection`.
+*
+* `visibility` is spread conditionally so an unset block carries no key — the
+* block model treats absence as "visible everywhere".
+*/
+function baseFields(attrs, placement = "container") {
+	const backgroundColor = parseColor(attrs[placement === "native" ? "background-color" : "container-background-color"]);
+	const visibility = readVisibility(attrs);
+	return {
+		styles: {
+			padding: parsePaddingShorthand(attrs.padding),
+			...backgroundColor ? { backgroundColor } : {}
+		},
+		...visibility ? { visibility } : {}
+	};
+}
+function warnForeignClasses(attrs, tag, ctx) {
+	for (const name of readForeignCssClasses(attrs)) ctx.warnings.push(`Dropped CSS class "${name}" on <${tag}> — consumer CSS has no Templatical equivalent.`);
+}
+function isNewTab(attrs) {
+	return (attrs.target ?? "").trim().toLowerCase() === "_blank";
+}
+/**
+* Wrap the element's own markup in an HTML block — the lossless fallback.
+*/
+function convertHtmlFallback($el, ctx, attrs) {
+	const outer = ctx.$.html($el) ?? "";
+	return createHtmlBlock({
+		content: outer,
+		...baseFields(attrs)
+	});
+}
+//#endregion
+//#region src/composite-mapper.ts
+/**
+* Exhaustive over `SocialPlatform` on purpose: adding a member to that union
+* without adding it here is a compile error, so the importer cannot silently
+* fall back to "website" for a platform the block model gained.
+*/
+const KNOWN_PLATFORMS = {
+	facebook: true,
+	twitter: true,
+	instagram: true,
+	linkedin: true,
+	youtube: true,
+	tiktok: true,
+	pinterest: true,
+	email: true,
+	whatsapp: true,
+	telegram: true,
+	discord: true,
+	snapchat: true,
+	reddit: true,
+	github: true,
+	dribbble: true,
+	behance: true,
+	website: true
+};
+const PLATFORM_ALIASES = {
+	x: "twitter",
+	"x-twitter": "twitter"
+};
+function normalizePlatform(raw) {
+	const cleaned = raw.trim().toLowerCase().replace(/-noshare$/, "");
+	if (!cleaned) return null;
+	if (PLATFORM_ALIASES[cleaned]) return PLATFORM_ALIASES[cleaned];
+	return cleaned in KNOWN_PLATFORMS ? cleaned : null;
+}
+/** The `<style>/<platform>.png` tail of the URL `renderers/social.ts:76` builds. */
+function platformFromSrc(src) {
+	const parts = src.split("?")[0].split("/").filter(Boolean);
+	return {
+		platform: (parts.at(-1) ?? "").replace(/\.[a-z0-9]+$/i, ""),
+		style: parts.at(-2) ?? ""
+	};
+}
+const ICON_SIZES = [
+	[24, "small"],
+	[32, "medium"],
+	[48, "large"]
+];
+function nearestIconSize(px) {
+	let best = ICON_SIZES[1];
+	let bestGap = Infinity;
+	for (const candidate of ICON_SIZES) {
+		const gap = Math.abs(candidate[0] - px);
+		if (gap < bestGap) {
+			bestGap = gap;
+			best = candidate;
+		}
+	}
+	return {
+		size: best[1],
+		exact: bestGap === 0
+	};
+}
+const RADIUS_STYLES = {
+	"50%": "circle",
+	"8px": "rounded",
+	"0": "square",
+	"4px": "solid"
+};
+const KNOWN_ICON_STYLES = /* @__PURE__ */ new Set([
+	"solid",
+	"outlined",
+	"rounded",
+	"square",
+	"circle"
+]);
+function convertSocial($el, attrs, ctx) {
+	const elements = childElements($el, ctx.$).filter(($child) => tagOf($child[0]) === "mj-social-element");
+	if (elements.length === 0) return null;
+	const notes = [];
+	const icons = [];
+	let iconStyle = null;
+	let iconSizePx = 0;
+	let spacing = 0;
+	elements.forEach(($child, index) => {
+		const childAttrs = resolveAttributes($child, ctx.cascade);
+		const src = (childAttrs.src ?? "").trim();
+		const fromSrc = src ? platformFromSrc(src) : {
+			platform: "",
+			style: ""
+		};
+		const rawName = (childAttrs.name ?? "").trim() || fromSrc.platform;
+		const platform = normalizePlatform(rawName);
+		if (!platform && rawName) notes.push(`Unrecognised social platform "${rawName}" mapped to "website".`);
+		icons.push({
+			id: generateId(),
+			platform: platform ?? "website",
+			url: (childAttrs.href ?? "").trim()
+		});
+		if (!iconStyle && KNOWN_ICON_STYLES.has(fromSrc.style)) iconStyle = fromSrc.style;
+		if (iconSizePx === 0) iconSizePx = parsePxValue(childAttrs["icon-size"]);
+		if (spacing === 0 && index < elements.length - 1) spacing = parsePxValue((childAttrs.padding ?? "").trim().split(/\s+/)[1]);
+		if (!iconStyle) {
+			const radius = (childAttrs["border-radius"] ?? "").trim().toLowerCase();
+			const mapped = RADIUS_STYLES[radius];
+			if (mapped) {
+				iconStyle = mapped;
+				if (radius === "4px") notes.push("Icon border-radius 4px maps to both \"solid\" and \"outlined\"; resolved to \"solid\".");
+			}
+		}
+	});
+	const declaredSize = parsePxValue(attrs["icon-size"]) || iconSizePx;
+	let iconSize;
+	if (declaredSize > 0) {
+		const resolved = nearestIconSize(declaredSize);
+		iconSize = resolved.size;
+		if (!resolved.exact) notes.push(`Icon size ${declaredSize}px is not one of 24/32/48; resolved to "${resolved.size}".`);
+	}
+	return {
+		block: createSocialIconsBlock({
+			icons,
+			align: parseAlignment(attrs.align, "center"),
+			...iconSize ? { iconSize } : {},
+			...iconStyle ? { iconStyle } : {},
+			...spacing > 0 ? { spacing } : {},
+			...baseFields(attrs)
+		}),
+		entry: {
+			sourceTag: "mj-social",
+			templaticalBlockType: "social",
+			status: notes.length > 0 ? "approximated" : "converted",
+			...notes.length > 0 ? { note: notes.join(" ") } : {}
+		}
+	};
+}
+function convertNavbar($el, attrs, ctx) {
+	const links = childElements($el, ctx.$).filter(($child) => tagOf($child[0]) === "mj-navbar-link");
+	if (links.length === 0) return null;
+	const items = links.map(($link) => {
+		const linkAttrs = resolveAttributes($link, ctx.cascade);
+		const color = parseColor(ownAttr(linkAttrs, "color", "mj-navbar-link", ctx.cascade));
+		return {
+			id: generateId(),
+			text: ($link.text() ?? "").trim(),
+			url: (linkAttrs.href ?? "").trim(),
+			openInNewTab: (linkAttrs.target ?? "").toLowerCase() === "_blank",
+			bold: (linkAttrs["font-weight"] ?? "").toLowerCase() === "bold",
+			underline: (linkAttrs["text-decoration"] ?? "").includes("underline"),
+			...color ? { color } : {}
+		};
+	});
+	const fontSize = parsePxValue(attrs["font-size"]);
+	const fontFamily = parseFontFamily(ownAttr(attrs, "font-family", "mj-navbar", ctx.cascade));
+	return {
+		block: createMenuBlock({
+			items,
+			textAlign: parseAlignment(attrs.align, "center"),
+			...fontSize > 0 ? { fontSize } : {},
+			...fontFamily ? { fontFamily } : {},
+			...baseFields(attrs)
+		}),
+		entry: {
+			sourceTag: "mj-navbar",
+			templaticalBlockType: "menu",
+			status: "converted"
+		}
+	};
+}
+function convertNativeTable($el, attrs, ctx) {
+	const $ = ctx.$;
+	const rowEls = $el.find("tr").toArray().filter((tr) => $(tr).parentsUntil($el, "table").length === 0);
+	if (rowEls.length === 0) return null;
+	const rows = rowEls.map((rowEl) => ({
+		id: generateId(),
+		cells: $(rowEl).children().toArray().map((cellEl) => ({
+			id: generateId(),
+			content: $(cellEl).html() ?? ""
+		}))
+	}));
+	const hasHeaderRow = $(rowEls[0]).children().toArray().some((cell) => tagOf(cell) === "th");
+	const color = parseColor(ownAttr(attrs, "color", "mj-table", ctx.cascade));
+	const fontSize = parsePxValue(attrs["font-size"]);
+	const fontFamily = parseFontFamily(ownAttr(attrs, "font-family", "mj-table", ctx.cascade));
+	return {
+		block: createTableBlock({
+			rows,
+			hasHeaderRow,
+			textAlign: parseAlignment(attrs.align, "left"),
+			...color ? { color } : {},
+			...fontSize > 0 ? { fontSize } : {},
+			...fontFamily ? { fontFamily } : {},
+			...baseFields(attrs)
+		}),
+		entry: {
+			sourceTag: "mj-table",
+			templaticalBlockType: "table",
+			status: "converted"
+		}
+	};
+}
+//#endregion
+//#region src/text-inference.ts
+/**
+* Re-parse an `mj-text`'s inner markup into its own document.
+*
+* The surrounding document already parses void elements correctly (`br`,
+* `img`, … stay void under `converter.ts`'s `xmlMode: false`), so this reparse
+* isn't compensating for a different parser here. It gives each
+* shape-detection helper (title / table / menu) an isolated, freshly
+* queryable document scoped to just this block's own markup — so
+* `$inner("tr")` can only match rows that belong to this table, and
+* `$inner("body")` has a real root to enumerate top-level nodes from. A
+* paragraph's markup needs none of that structure-probing, so it is passed
+* through verbatim and never reparsed.
+*/
+function parseInner(html) {
+	return load(`<body>${html}</body>`);
+}
+function rootElements(html) {
+	const kids = parseInner(html)("body").children().toArray();
+	return {
+		tag: kids.length > 0 ? kids[0].tagName?.toLowerCase() ?? "" : "",
+		count: kids.length
+	};
+}
+const HEADING_LEVELS = {
+	h1: 1,
+	h2: 2,
+	h3: 3,
+	h4: 4,
+	h5: 5,
+	h6: 6
+};
+function convertTitle(html, attrs, sourceLevel, cascade) {
+	const $heading = parseInner(html)("body").children().first();
+	const level = Math.min(sourceLevel, 4);
+	const color = parseColor(ownAttr(attrs, "color", "mj-text", cascade));
+	const fontFamily = parseFontFamily(ownAttr(attrs, "font-family", "mj-text", cascade));
+	const block = createTitleBlock({
+		content: $heading.html() ?? "",
+		level,
+		textAlign: parseAlignment(attrs.align, "left"),
+		...color ? { color } : {},
+		...fontFamily ? { fontFamily } : {},
+		...baseFields(attrs)
+	});
+	const clamped = sourceLevel > 4;
+	return {
+		block,
+		entry: {
+			sourceTag: "mj-text",
+			templaticalBlockType: "title",
+			status: clamped ? "approximated" : "converted",
+			...clamped ? { note: `Heading level h${sourceLevel} clamped to 4 — Templatical titles support h1-h4.` } : {}
+		}
+	};
+}
+function convertTable(html, attrs, cascade) {
+	const $inner = parseInner(html);
+	const $rows = $inner("tr");
+	const rows = $rows.toArray().map((rowEl) => ({
+		id: generateId(),
+		cells: $inner(rowEl).children().toArray().map((cellEl) => ({
+			id: generateId(),
+			content: $inner(cellEl).html() ?? ""
+		}))
+	}));
+	const hasHeaderRow = $rows.length > 0 && $inner($rows[0]).children("th").length > 0;
+	const color = parseColor(ownAttr(attrs, "color", "mj-text", cascade));
+	const fontSize = parsePxValue(attrs["font-size"]);
+	const fontFamily = parseFontFamily(ownAttr(attrs, "font-family", "mj-text", cascade));
+	return {
+		block: createTableBlock({
+			rows,
+			hasHeaderRow,
+			textAlign: parseAlignment(attrs.align, "left"),
+			...color ? { color } : {},
+			...fontSize > 0 ? { fontSize } : {},
+			...fontFamily ? { fontFamily } : {},
+			...baseFields(attrs)
+		}),
+		entry: {
+			sourceTag: "mj-text",
+			templaticalBlockType: "table",
+			status: "converted"
+		}
+	};
+}
+/**
+* A menu is top-level anchors with optional `<span>` separators between them —
+* exactly what `renderers/menu.ts` emits, and deliberately not matched when a
+* `<p>` wrapper is present (that is a paragraph containing links).
+*/
+function looksLikeMenu(html) {
+	const kids = parseInner(html)("body").children().toArray();
+	if (kids.length === 0) return false;
+	let anchors = 0;
+	for (const kid of kids) {
+		const tag = kid.tagName?.toLowerCase() ?? "";
+		if (tag === "a") anchors += 1;
+		else if (tag !== "span") return false;
+	}
+	return anchors > 0;
+}
+function convertMenu(html, attrs, cascade) {
+	const $inner = parseInner(html);
+	const items = $inner("body").children("a").toArray().map((el) => {
+		const $a = $inner(el);
+		const itemColor = parseColor($a.attr("style")?.match(/color\s*:\s*([^;]+)/i)?.[1]);
+		return {
+			id: generateId(),
+			text: ($a.text() ?? "").trim(),
+			url: $a.attr("href") ?? "",
+			openInNewTab: ($a.attr("target") ?? "").toLowerCase() === "_blank",
+			bold: $a.find("strong, b").length > 0,
+			underline: ($a.attr("style") ?? "").includes("underline"),
+			...itemColor ? { color: itemColor } : {}
+		};
+	});
+	const $separator = $inner("body").children("span").first();
+	const separator = ($separator.text() ?? "").trim();
+	const separatorColor = parseColor($separator.attr("style")?.match(/color\s*:\s*([^;]+)/i)?.[1]);
+	const spacing = parsePxValue($separator.attr("style")?.match(/padding\s*:\s*0\s+([\d.]+px)/i)?.[1]);
+	const color = parseColor(ownAttr(attrs, "color", "mj-text", cascade));
+	const fontSize = parsePxValue(attrs["font-size"]);
+	const fontFamily = parseFontFamily(ownAttr(attrs, "font-family", "mj-text", cascade));
+	return {
+		block: createMenuBlock({
+			items,
+			textAlign: parseAlignment(attrs.align, "center"),
+			...separator ? { separator } : {},
+			...separatorColor ? { separatorColor } : {},
+			...spacing > 0 ? { spacing } : {},
+			...color ? { color } : {},
+			...fontSize > 0 ? { fontSize } : {},
+			...fontFamily ? { fontFamily } : {},
+			...baseFields(attrs)
+		}),
+		entry: {
+			sourceTag: "mj-text",
+			templaticalBlockType: "menu",
+			status: "converted"
+		}
+	};
+}
+/**
+* The editor's rich-text blocks assume a block-level wrapper, so bare text gets
+* one. Mirrors `ensureParagraphWrapped` in `@templatical/import-html`.
+*/
+function ensureParagraphWrapped(html) {
+	const trimmed = html.trim();
+	if (trimmed === "") return "<p></p>";
+	if (/^<(p|h[1-6]|ul|ol|blockquote|div)\b/i.test(trimmed)) return trimmed;
+	return `<p>${trimmed}</p>`;
+}
+function convertParagraph(html, attrs) {
+	const gap = readParagraphGap(attrs);
+	const paragraphSpacing = gap !== null && gap !== RICH_TEXT_SPACING.paragraphGap ? gap : void 0;
+	return {
+		block: createParagraphBlock({
+			content: ensureParagraphWrapped(html),
+			...paragraphSpacing !== void 0 ? { paragraphSpacing } : {},
+			...baseFields(attrs)
+		}),
+		entry: {
+			sourceTag: "mj-text",
+			templaticalBlockType: "paragraph",
+			status: "converted"
+		}
+	};
+}
+/**
+* Resolve an `mj-text` to Title, Table, Menu or Paragraph by the shape of its
+* content — the reverse of the four renderers that all emit `mj-text`.
+*
+* A fifth renderer emits it too: `HtmlBlock` (`renderers/html.ts`), whose
+* content is arbitrary, so it has no shape to match and lands on the Paragraph
+* fallback. That is irreducible — nothing in the output marks a block's type —
+* and narrowing the Title/Table shapes to compensate would break the common
+* case to serve the rare one. See §10 of the design.
+*
+* Paragraph is the terminal arm and always reachable, so this is total.
+*/
+function convertTextElement($el, attrs, ctx) {
+	const html = $el.html() ?? "";
+	const root = rootElements(html);
+	if (root.count === 1 && HEADING_LEVELS[root.tag]) return convertTitle(html, attrs, HEADING_LEVELS[root.tag], ctx.cascade);
+	if (root.count === 1 && root.tag === "table") return convertTable(html, attrs, ctx.cascade);
+	if (looksLikeMenu(html)) return convertMenu(html, attrs, ctx.cascade);
+	return convertParagraph(html, attrs);
+}
+//#endregion
+//#region src/block-mapper.ts
+/** Tags handled elsewhere but recognised, so they never hit the unknown-tag arm. */
+const STRUCTURAL_TAGS = /* @__PURE__ */ new Set([
+	"mjml",
+	"mj-head",
+	"mj-body",
+	"mj-wrapper",
+	"mj-section",
+	"mj-column",
+	"mj-group",
+	"mj-attributes",
+	"mj-all",
+	"mj-class",
+	"mj-font",
+	"mj-style",
+	"mj-title",
+	"mj-preview",
+	"mj-breakpoint",
+	"mj-html-attributes",
+	"mj-social-element",
+	"mj-navbar-link"
+]);
+/** Tags with no Templatical equivalent that keep their markup verbatim. */
+const NO_EQUIVALENT_TAGS = /* @__PURE__ */ new Set([
+	"mj-hero",
+	"mj-carousel",
+	"mj-accordion"
+]);
+function convertImage($el, attrs, ctx) {
+	const src = (attrs.src ?? "").trim();
+	if (!src) return null;
+	const decorative = (attrs.role ?? "").trim().toLowerCase() === "presentation";
+	const pxWidth = parsePxValue(attrs.width);
+	const height = parsePxValue(attrs.height);
+	const borderRadius = parsePxValue(attrs["border-radius"]);
+	const href = (attrs.href ?? "").trim();
+	return createImageBlock({
+		src,
+		alt: decorative ? "" : attrs.alt ?? "",
+		width: pxWidth === ctx.containerWidth ? "full" : pxWidth || "full",
+		align: parseAlignment(attrs.align, "center"),
+		...height > 0 ? { height } : {},
+		...borderRadius > 0 ? { borderRadius } : {},
+		...href ? { linkUrl: href } : {},
+		...href && isNewTab(attrs) ? { linkOpenInNewTab: true } : {},
+		...decorative ? { decorative: true } : {},
+		...baseFields(attrs)
+	});
+}
+function convertButton($el, attrs) {
+	const text = ($el.text() ?? "").trim();
+	if (!text) return null;
+	const backgroundColor = parseColor(attrs["background-color"]);
+	const textColor = parseColor(attrs.color);
+	const fontSize = parsePxValue(attrs["font-size"]);
+	return createButtonBlock({
+		text,
+		url: (attrs.href ?? "").trim(),
+		...backgroundColor ? { backgroundColor } : {},
+		...textColor ? { textColor } : {},
+		...fontSize > 0 ? { fontSize } : {},
+		...attrs["border-radius"] !== void 0 ? { borderRadius: parsePxValue(attrs["border-radius"]) } : {},
+		...attrs["inner-padding"] !== void 0 ? { buttonPadding: parsePaddingShorthand(attrs["inner-padding"]) } : {},
+		align: parseAlignment(attrs.align, "center"),
+		...isNewTab(attrs) ? { openInNewTab: true } : {},
+		...baseFields(attrs)
+	});
+}
+function convertDivider(attrs) {
+	const color = parseColor(attrs["border-color"]);
+	const thickness = parsePxValue(attrs["border-width"]);
+	return createDividerBlock({
+		lineStyle: parseBorderStyle(attrs["border-style"]),
+		...color ? { color } : {},
+		...attrs["border-width"] !== void 0 ? { thickness } : {},
+		...baseFields(attrs)
+	});
+}
+function convertSpacer(attrs) {
+	const height = parsePxValue(attrs.height);
+	return createSpacerBlock({
+		...attrs.height !== void 0 ? { height } : {},
+		...baseFields(attrs)
+	});
+}
+/**
+* Convert one MJML element to a Templatical block.
+*
+* Returns `null` for an element that produces nothing *and* warrants no report
+* entry — an image with no `src`, a button with no label. A `Converted` whose
+* `block` is null is a *skip*, which does get an entry.
+*/
+function convertElement($el, ctx) {
+	const tag = tagOf($el[0]);
+	if (!tag) return null;
+	const attrs = resolveAttributes($el, ctx.cascade);
+	warnForeignClasses(attrs, tag, ctx);
+	if (tag === "mj-include") return {
+		block: null,
+		entry: {
+			sourceTag: tag,
+			templaticalBlockType: null,
+			status: "skipped",
+			note: `Cannot resolve <mj-include path="${(attrs.path ?? "").trim()}"> — the importer reads a single string and has no filesystem access. Inline the include before importing.`
+		}
+	};
+	if (tag === "mj-text") return convertTextElement($el, attrs, ctx);
+	if (tag === "mj-social") return convertSocial($el, attrs, ctx);
+	if (tag === "mj-navbar") return convertNavbar($el, attrs, ctx);
+	if (tag === "mj-table") return convertNativeTable($el, attrs, ctx);
+	if (tag === "mj-image") {
+		const block = convertImage($el, attrs, ctx);
+		if (!block) return null;
+		return {
+			block,
+			entry: {
+				sourceTag: tag,
+				templaticalBlockType: "image",
+				status: "converted"
+			}
+		};
+	}
+	if (tag === "mj-button") {
+		const block = convertButton($el, attrs);
+		if (!block) return null;
+		return {
+			block,
+			entry: {
+				sourceTag: tag,
+				templaticalBlockType: "button",
+				status: "converted"
+			}
+		};
+	}
+	if (tag === "mj-divider") return {
+		block: convertDivider(attrs),
+		entry: {
+			sourceTag: tag,
+			templaticalBlockType: "divider",
+			status: "converted"
+		}
+	};
+	if (tag === "mj-spacer") return {
+		block: convertSpacer(attrs),
+		entry: {
+			sourceTag: tag,
+			templaticalBlockType: "spacer",
+			status: "converted"
+		}
+	};
+	if (tag === "mj-raw") return {
+		block: createHtmlBlock({
+			content: $el.html() ?? "",
+			...baseFields(attrs)
+		}),
+		entry: {
+			sourceTag: tag,
+			templaticalBlockType: "html",
+			status: "converted"
+		}
+	};
+	if (NO_EQUIVALENT_TAGS.has(tag)) return {
+		block: convertHtmlFallback($el, ctx, attrs),
+		entry: {
+			sourceTag: tag,
+			templaticalBlockType: "html",
+			status: "html-fallback",
+			note: `<${tag}> has no Templatical block equivalent; the original markup is preserved.`
+		}
+	};
+	if (STRUCTURAL_TAGS.has(tag)) return null;
+	return {
+		block: convertHtmlFallback($el, ctx, attrs),
+		entry: {
+			sourceTag: tag,
+			templaticalBlockType: "html",
+			status: "html-fallback",
+			note: `<${tag}> is not a known MJML element (a custom component?); the original markup is preserved.`
+		}
+	};
+}
+//#endregion
+//#region src/display-condition.ts
+/** Characters kept before an ellipsis is appended; the full condition stays in `before`. */
+const LABEL_MAX = 46;
+const ANCHORED_LOGIC = Object.values(SYNTAX_PRESETS).map((preset) => new RegExp(`^(?:${preset.logic.source})$`, preset.logic.flags.replace("g", "")));
+/**
+* Whether the text is exactly one logic tag and nothing else.
+*
+* Anchored against every registered syntax rather than one, so a mailchimp or
+* ampscript template is recognised as readily as a liquid one. MSO conditionals
+* are HTML comments and match none of them, which is what keeps hand-written
+* `mj-raw` pairs out of this path.
+*/
+function isLogicTagOnly(text) {
+	const trimmed = text.trim();
+	if (trimmed === "") return false;
+	return ANCHORED_LOGIC.some((regex) => regex.test(trimmed));
+}
+function isLogicRaw($el) {
+	return tagOf($el[0]) === "mj-raw" && isLogicTagOnly($el.text() ?? "");
+}
+function synthesizeLabel(before) {
+	const trimmed = before.trim();
+	if (trimmed.length <= LABEL_MAX) return trimmed;
+	return `${trimmed.slice(0, LABEL_MAX)}…`;
+}
+/**
+* Group a run of siblings into units, folding each `logic-raw / element /
+* logic-raw` triple into one unit carrying a `displayCondition`.
+*
+* `label` is synthesised from `before`: it is editor metadata that appears
+* nowhere in the MJML, so it cannot be recovered — only reconstructed. `group`
+* and `description` are left absent for the same reason.
+*
+* Deliberately no check that the two tags pair *semantically*. The renderer
+* emits them only in this arrangement, and matching open/close keywords across
+* four syntaxes would be a table to maintain for no gain.
+*/
+function planSiblings($siblings) {
+	const units = [];
+	let i = 0;
+	while (i < $siblings.length) {
+		const $current = $siblings[i];
+		const $middle = $siblings[i + 1];
+		const $closing = $siblings[i + 2];
+		if (isLogicRaw($current) && $middle !== void 0 && tagOf($middle[0]) !== "mj-raw" && $closing !== void 0 && isLogicRaw($closing)) {
+			const before = ($current.text() ?? "").trim();
+			const after = ($closing.text() ?? "").trim();
+			units.push({
+				$el: $middle,
+				displayCondition: {
+					label: synthesizeLabel(before),
+					before,
+					after
+				}
+			});
+			i += 3;
+			continue;
+		}
+		units.push({ $el: $current });
+		i += 1;
+	}
+	return units;
+}
+//#endregion
+//#region src/head-parser.ts
+/** `mj-head` children this module reads; anything else is warned about. */
+const CONSUMED_HEAD_TAGS = /* @__PURE__ */ new Set([
+	"mj-attributes",
+	"mj-preview",
+	"mj-font",
+	"mj-style",
+	"mj-title"
+]);
+/**
+* `DEFAULT_TEMPLATE_DEFAULTS` is typed `Partial<TemplateSettings>` so a
+* consumer can override any subset of it, but its own literal (see
+* `packages/types/src/defaults.ts`) always sets exactly the six required
+* `TemplateSettings` fields — `linkColor` and `preheaderText` are the two
+* optional ones and are correctly absent from it. Narrowing the type once
+* here, rather than at every read below, is what lets `width`, `fontFamily`
+* and the rest come out as `number`/`string`/`boolean` instead of `| undefined`.
+*/
+const REQUIRED_TEMPLATE_DEFAULTS = DEFAULT_TEMPLATE_DEFAULTS;
+/**
+* Read the `a { … }` declarations out of the concatenated `mj-style` blocks.
+*
+* This is the reverse of how the renderer emits `settings.linkColor` and
+* `settings.linkUnderline` — as a global anchor rule — so a template that
+* round-trips keeps both. A stylesheet with no anchor rule leaves both unset.
+*/
+function readAnchorRule(css) {
+	const rule = {};
+	const cssWithoutComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
+	for (const match of cssWithoutComments.matchAll(/(^|[},])\s*a\s*\{([^}]*)\}/g)) {
+		const body = match[2];
+		const color = body.match(/(?:^|;)\s*color\s*:\s*([^;]+)/i);
+		if (color) {
+			const parsed = parseColor(color[1]);
+			if (parsed) rule.color = parsed;
+		}
+		const decoration = body.match(/(?:^|;)\s*text-decoration\s*:\s*([^;]+)/i);
+		if (decoration) rule.underline = decoration[1].trim().toLowerCase().includes("underline");
+	}
+	return rule;
+}
+/**
+* Build `TemplateSettings` from `mj-body`'s attributes, the attribute cascade
+* and the remaining `mj-head` children.
+*
+* Optional keys (`preheaderText`, `linkColor`) are **omitted** rather than set
+* to `undefined`: an absent key is what the block model means by unset, and a
+* present-but-undefined key serialises into exported JSON.
+*/
+function extractSettings($, cascade, warnings) {
+	const $body = findByTag($, "mj-body").first();
+	const $root = findByTag($, "mjml").first();
+	const width = parsePxValue($body.attr("width")) || REQUIRED_TEMPLATE_DEFAULTS.width;
+	const backgroundColor = parseColor($body.attr("background-color")) || REQUIRED_TEMPLATE_DEFAULTS.backgroundColor;
+	const fontFromCascade = parseFontFamily(cascade.all["font-family"]) || parseFontFamily(cascade.byTag["mj-text"]?.["font-family"]);
+	const fontFromDeclaration = findByTag($, "mj-font").first().attr("name") ?? "";
+	const fontFamily = fontFromCascade || fontFromDeclaration || REQUIRED_TEMPLATE_DEFAULTS.fontFamily;
+	const textColor = parseColor(cascade.byTag["mj-text"]?.color) || REQUIRED_TEMPLATE_DEFAULTS.textColor;
+	const previewText = findByTag($, "mj-preview").first().text().trim();
+	const anchor = readAnchorRule(findByTag($, "mj-style").toArray().map((el) => $(el).text()).join("\n"));
+	const locale = ($root.attr("lang") ?? "").trim() || REQUIRED_TEMPLATE_DEFAULTS.locale;
+	const title = findByTag($, "mj-title").first().text().trim();
+	if (title) warnings.push(`Dropped <mj-title> ("${title}") — Templatical templates have no document-title field.`);
+	const $head = findByTag($, "mj-head").first();
+	if ($head.length > 0) for (const $child of childElements($head, $)) {
+		const tag = tagOf($child[0]);
+		if (!CONSUMED_HEAD_TAGS.has(tag)) warnings.push(`Dropped <${tag}> — it has no Templatical equivalent.`);
+	}
+	return {
+		width,
+		backgroundColor,
+		textColor,
+		linkUnderline: anchor.underline ?? REQUIRED_TEMPLATE_DEFAULTS.linkUnderline,
+		fontFamily,
+		locale,
+		...anchor.color ? { linkColor: anchor.color } : {},
+		...previewText ? { preheaderText: previewText } : {}
+	};
+}
+//#endregion
+//#region src/section-builder.ts
+/** Reverse of `packages/renderer/src/columns.ts`, keyed by column count. */
+const LAYOUT_SHAPES = [
+	{
+		layout: "1",
+		percents: [100]
+	},
+	{
+		layout: "2",
+		percents: [50, 50]
+	},
+	{
+		layout: "1-2",
+		percents: [33.33, 66.67]
+	},
+	{
+		layout: "2-1",
+		percents: [66.67, 33.33]
+	},
+	{
+		layout: "3",
+		percents: [
+			33.33,
+			33.33,
+			33.34
+		]
+	}
+];
+/** Percentage points of drift tolerated per column before a match is inexact. */
+const WIDTH_TOLERANCE = 2;
+/**
+* Resolve MJML column widths to one of the five layouts `ColumnLayout` allows.
+*
+* `exact: false` means the caller must report `approximated` — MJML permits any
+* number of columns at any width and this union permits five shapes, so this is
+* the importer's main irreducible loss (§8.1).
+*/
+function matchColumnLayout(percents) {
+	const count = percents.length;
+	if (count === 0) return {
+		layout: "1",
+		exact: true
+	};
+	if (percents.every((p) => p === null)) {
+		if (count === 1) return {
+			layout: "1",
+			exact: true
+		};
+		if (count === 2) return {
+			layout: "2",
+			exact: true
+		};
+		if (count === 3) return {
+			layout: "3",
+			exact: true
+		};
+		return {
+			layout: "3",
+			exact: false
+		};
+	}
+	const nullCount = percents.filter((p) => p === null).length;
+	const knownSum = percents.reduce((sum, p) => sum + (p ?? 0), 0);
+	const remainder = nullCount > 0 ? Math.max(0, 100 - knownSum) / nullCount : 0;
+	const resolved = percents.map((p) => p ?? remainder);
+	const sameCount = LAYOUT_SHAPES.filter((shape) => shape.percents.length === count);
+	for (const shape of sameCount) if (shape.percents.every((want, i) => Math.abs(want - resolved[i]) <= WIDTH_TOLERANCE)) return {
+		layout: shape.layout,
+		exact: true
+	};
+	const candidates = sameCount.length > 0 ? sameCount : LAYOUT_SHAPES.filter((shape) => shape.layout === "3");
+	let best = candidates[0];
+	let bestError = Infinity;
+	for (const shape of candidates) {
+		const error = shape.percents.reduce((sum, want, i) => sum + Math.abs(want - (resolved[i] ?? 0)), 0);
+		if (error < bestError) {
+			bestError = error;
+			best = shape;
+		}
+	}
+	return {
+		layout: best.layout,
+		exact: false
+	};
+}
+const COLUMN_COUNT = {
+	"1": 1,
+	"2": 2,
+	"3": 3,
+	"2-1": 2,
+	"1-2": 2
+};
+/** Column pixel widths per layout, mirroring `renderer/src/columns.ts`. */
+function columnPixels(layout, containerWidth) {
+	switch (layout) {
+		case "2": return [containerWidth * .5, containerWidth * .5];
+		case "3": return [
+			containerWidth / 3,
+			containerWidth / 3,
+			containerWidth / 3
+		];
+		case "1-2": return [containerWidth / 3, containerWidth * 2 / 3];
+		case "2-1": return [containerWidth * 2 / 3, containerWidth / 3];
+		default: return [containerWidth];
+	}
+}
+/**
+* The `mj-column` elements of a section, in document order: a direct
+* `mj-column` child contributes itself, and an `mj-group` child contributes
+* every `mj-column` it holds at the group's own position — so a section
+* mixing direct columns with one or more groups keeps every column instead
+* of losing all but the first group's. `grouped` is true whenever any
+* `mj-group` child is present, which is what drives `stackOnMobile: false`.
+*/
+function readColumns($el, ctx) {
+	const kids = childElements($el, ctx.$);
+	const columns = [];
+	let grouped = false;
+	for (const $kid of kids) {
+		const tag = tagOf($kid[0]);
+		if (tag === "mj-column") columns.push($kid);
+		else if (tag === "mj-group") {
+			grouped = true;
+			columns.push(...childElements($kid, ctx.$).filter(($k) => tagOf($k[0]) === "mj-column"));
+		}
+	}
+	return {
+		columns,
+		grouped
+	};
+}
+/**
+* A column's children, in document order, one block per unit `planSiblings`
+* groups them into.
+*
+* Routed through `planSiblings` for the same reason `walkBody` is
+* (`converter.ts`): the renderer wraps a conditional block in bracketing
+* `mj-raw` guards inside a column exactly as it does at top level
+* (`renderers/section.ts` calls the same `wrapWithDisplayCondition` helper as
+* `index.ts`), so recovering the condition here needs the identical fold.
+*/
+function convertColumnChildren($column, ctx, entries) {
+	const blocks = [];
+	for (const unit of planSiblings(childElements($column, ctx.$))) {
+		const tag = tagOf(unit.$el[0]);
+		if (tag === "mj-section" || tag === "mj-wrapper") {
+			const attrs = resolveAttributes(unit.$el, ctx.cascade);
+			const fallback = convertHtmlFallback(unit.$el, ctx, attrs);
+			if (unit.displayCondition) fallback.displayCondition = unit.displayCondition;
+			blocks.push(fallback);
+			const noun = tag === "mj-section" ? "section" : "wrapper";
+			entries.push({
+				sourceTag: tag,
+				templaticalBlockType: "html",
+				status: "html-fallback",
+				note: `MJML forbids <${tag}> inside <mj-column>; the nested ${noun}'s markup is preserved as an html block.`
+			});
+			continue;
+		}
+		const converted = convertElement(unit.$el, ctx);
+		if (!converted) continue;
+		entries.push(converted.entry);
+		if (!converted.block) continue;
+		if (unit.displayCondition) converted.block.displayCondition = unit.displayCondition;
+		blocks.push(converted.block);
+	}
+	return blocks;
+}
+/**
+* A column's width as a percentage of the section's container, or `null`
+* when the column carries no definite width of its own.
+*
+* `mj-column` accepts either a percentage or a px length, and a px width is
+* real geometry — converting it here lets it participate in
+* `matchColumnLayout` as a known value instead of falling through to "auto"
+* and losing the author's intended ratio.
+*/
+function columnWidthPercent(value, containerWidth) {
+	const percent = parsePercent(value);
+	if (percent !== null) return percent;
+	const px = parseDefinitePx(value);
+	return px !== null && containerWidth > 0 ? px / containerWidth * 100 : null;
+}
+/**
+* Build a `SectionBlock` (always exactly one) from an `mj-section`.
+*
+* Returns an array so the caller can treat sections and wrappers uniformly.
+*/
+function buildSection($el, ctx, entries, wrapper) {
+	const attrs = resolveAttributes($el, ctx.cascade);
+	const { columns, grouped } = readColumns($el, ctx);
+	const rawWidths = columns.map(($c) => resolveAttributes($c, ctx.cascade).width);
+	const { layout, exact } = matchColumnLayout(rawWidths.map((width) => columnWidthPercent(width, ctx.containerWidth)));
+	const slots = COLUMN_COUNT[layout];
+	const pixels = columnPixels(layout, ctx.containerWidth);
+	const shown = rawWidths.map((w) => w || "auto").join(", ");
+	entries.push({
+		sourceTag: "mj-section",
+		templaticalBlockType: "section",
+		status: exact ? "converted" : "approximated",
+		...exact ? {} : { note: `Column widths ${shown} have no exact Templatical layout; resolved to "${layout}".` }
+	});
+	const children = Array.from({ length: slots }, () => []);
+	columns.forEach(($column, index) => {
+		const slot = Math.min(index, slots - 1);
+		const columnCtx = {
+			...ctx,
+			containerWidth: Math.round(pixels[slot] ?? ctx.containerWidth)
+		};
+		children[slot].push(...convertColumnChildren($column, columnCtx, entries));
+	});
+	const borderRadius = parsePxValue(attrs["border-radius"]);
+	return [createSectionBlock({
+		columns: layout,
+		children,
+		...grouped ? { stackOnMobile: false } : {},
+		...borderRadius > 0 ? { borderRadius } : {},
+		...wrapper ? { wrapper } : {},
+		...baseFields(attrs, "native")
+	})];
+}
+function readWrapper(attrs) {
+	const backgroundColor = parseColor(attrs["background-color"]);
+	const padding = parsePaddingShorthand(attrs.padding);
+	const borderRadius = parsePxValue(attrs["border-radius"]);
+	return {
+		...backgroundColor ? { backgroundColor } : {},
+		padding,
+		...borderRadius > 0 ? { borderRadius } : {}
+	};
+}
+/**
+* Fold an `mj-wrapper` into the `wrapper` field of the section(s) it holds.
+*
+* A wrapper is not a block: `SectionWrapper` is exactly the band the renderer
+* emits an `mj-wrapper` for (`renderer/src/index.ts:223`), so representing it
+* as its own section would double the nesting on every round trip.
+*/
+function buildWrapper($el, ctx, entries) {
+	const wrapper = readWrapper(resolveAttributes($el, ctx.cascade));
+	const sections = childElements($el, ctx.$).filter(($k) => tagOf($k[0]) === "mj-section");
+	if (sections.length === 0) {
+		entries.push({
+			sourceTag: "mj-wrapper",
+			templaticalBlockType: null,
+			status: "skipped",
+			note: "An <mj-wrapper> with no <mj-section> children produces nothing."
+		});
+		return [];
+	}
+	if (sections.length > 1) entries.push({
+		sourceTag: "mj-wrapper",
+		templaticalBlockType: "section",
+		status: "approximated",
+		note: `An <mj-wrapper> holding ${sections.length} sections was applied to each of them — Templatical has no multi-section band.`
+	});
+	return sections.flatMap(($section) => buildSection($section, ctx, entries, wrapper));
+}
+//#endregion
+//#region src/converter.ts
+const EMPTY_DOCUMENT_WARNING = "No convertible content was found in the MJML. Check that the document has an <mj-body> with at least one <mj-section>.";
+/**
+* Wrap blocks that sat directly under `mj-body` in a one-column section.
+*
+* Valid MJML puts every block inside an `mj-section`, but hand-written and
+* machine-mangled documents do not, and the editor canvas has no
+* representation for a block outside a section.
+*/
+function wrapInSection(blocks) {
+	return createSectionBlock({
+		columns: "1",
+		children: [blocks],
+		styles: { padding: {
+			top: 0,
+			right: 0,
+			bottom: 0,
+			left: 0
+		} }
+	});
+}
+function walkBody($body, ctx, entries) {
+	const blocks = [];
+	let loose = [];
+	const flushLoose = () => {
+		if (loose.length > 0) {
+			blocks.push(wrapInSection(loose));
+			loose = [];
+		}
+	};
+	for (const unit of planSiblings(childElements($body, ctx.$))) {
+		const tag = tagOf(unit.$el[0]);
+		if (tag === "mj-wrapper" || tag === "mj-section") {
+			flushLoose();
+			const produced = tag === "mj-wrapper" ? buildWrapper(unit.$el, ctx, entries) : buildSection(unit.$el, ctx, entries);
+			for (const block of produced) {
+				if (unit.displayCondition) block.displayCondition = unit.displayCondition;
+				blocks.push(block);
+			}
+			continue;
+		}
+		const converted = convertElement(unit.$el, ctx);
+		if (!converted) continue;
+		entries.push(converted.entry);
+		if (!converted.block) continue;
+		if (unit.displayCondition) converted.block.displayCondition = unit.displayCondition;
+		if (converted.entry.status === "html-fallback") {
+			flushLoose();
+			blocks.push(converted.block);
+			continue;
+		}
+		loose.push(converted.block);
+	}
+	flushLoose();
+	return blocks;
+}
+/**
+* Convert an MJML document into a Templatical template.
+*
+* @example
+* ```ts
+* const { content, report } = convertMjmlTemplate(mjmlSource);
+*
+* const editor = init({ container: '#editor', content });
+*
+* console.log(report.summary);
+* console.log(report.warnings);
+* ```
+*/
+function convertMjmlTemplate(mjml) {
+	if (typeof mjml !== "string") throw new Error("Invalid MJML template: expected a string. Pass the raw MJML source as a string.");
+	if (mjml.trim().length === 0) throw new Error("Invalid MJML template: input is empty. Pass the raw MJML source of an email.");
+	const $ = load(mjml, { xml: {
+		xmlMode: false,
+		recognizeSelfClosing: true
+	} });
+	const cascade = buildAttributeCascade($);
+	const entries = [];
+	const warnings = [];
+	const settings = extractSettings($, cascade, warnings);
+	const $body = findByTag($, "mj-body").first();
+	const ctx = {
+		$,
+		cascade,
+		containerWidth: settings.width,
+		warnings
+	};
+	const blocks = $body.length > 0 ? walkBody($body, ctx, entries) : [];
+	if (blocks.length === 0) warnings.push(EMPTY_DOCUMENT_WARNING);
+	return {
+		content: {
+			...createDefaultTemplateContent(),
+			blocks,
+			settings
+		},
+		report: {
+			entries,
+			warnings,
+			summary: {
+				total: entries.length,
+				converted: entries.filter((e) => e.status === "converted").length,
+				approximated: entries.filter((e) => e.status === "approximated").length,
+				htmlFallback: entries.filter((e) => e.status === "html-fallback").length,
+				skipped: entries.filter((e) => e.status === "skipped").length
+			}
+		}
+	};
+}
+//#endregion
+export { convertMjmlTemplate };
+
+//# sourceMappingURL=index.js.map