@templatical/import-html 0.46.0 → 0.48.0

package/dist/index.js

@@ -4,12 +4,14 @@ import { isTag, isText } from "domhandler";
 //#region src/style-parser.ts
 /**
 * Parses a CSS `style="..."` attribute string into a flat key/value record.
-* Keys are lowercased; values are trimmed. Quotes around values are not stripped.
+* Keys are lowercased; values are trimmed. Quotes around values are not
+* stripped. A semicolon inside quotes or parentheses — `url("a;b")`,
+* `url(data:image/png;base64,…)` — belongs to its value.
 */
 function parseStyleAttribute(styleAttr) {
 	const result = {};
 	if (!styleAttr) return result;
-	for (const decl of styleAttr.split(";")) {
+	for (const decl of splitTopLevel(styleAttr, ";")) {
 		const idx = decl.indexOf(":");
 		if (idx === -1) continue;
 		const key = decl.slice(0, idx).trim().toLowerCase();
@@ -19,6 +21,35 @@ function parseStyleAttribute(styleAttr) {
 	return result;
 }
 /**
+* Split `value` at each `separator` that sits outside quotes and parentheses.
+* A value whose quote or parenthesis never closes is split at every
+* `separator` instead, so a malformed declaration costs only itself and the
+* ones after it still read.
+*/
+function splitTopLevel(value, separator) {
+	const parts = [];
+	let depth = 0;
+	let quote = "";
+	let start = 0;
+	for (let i = 0; i < value.length; i++) {
+		const char = value[i];
+		if (quote) {
+			if (char === quote) quote = "";
+			continue;
+		}
+		if (char === "\"" || char === "'") quote = char;
+		else if (char === "(") depth++;
+		else if (char === ")") depth = Math.max(0, depth - 1);
+		else if (char === separator && depth === 0) {
+			parts.push(value.slice(start, i));
+			start = i + 1;
+		}
+	}
+	if (quote || depth > 0) return value.split(separator);
+	parts.push(value.slice(start));
+	return parts;
+}
+/**
 * Serializes a flat key/value record back to a `style` attribute string.
 */
 function serializeStyleAttribute(styles) {
@@ -233,6 +264,376 @@ function parseBorderShorthand(value) {
 		color
 	};
 }
+const X_GRID = [
+	"left",
+	"center",
+	"right"
+];
+const Y_GRID = [
+	"top",
+	"center",
+	"bottom"
+];
+const PERCENT = /^(-?(?:\d+(?:\.\d+)?|\.\d+))%$/;
+const LENGTH = /^-?(?:\d+(?:\.\d+)?|\.\d+)[a-z]*$/;
+/**
+* `background-size` as a keyword. A size with a side at 100%, or a px width
+* spanning the box, fills it as `cover` does; any other length or percentage
+* draws the image at a size of its own, which `auto` is closest to.
+*/
+function backgroundSizeKeyword(raw, boxWidth) {
+	const parts = raw.toLowerCase().split(/\s+/);
+	const [first] = parts;
+	if (parts.length === 1 && (first === "cover" || first === "contain")) return {
+		size: first,
+		exact: true
+	};
+	if (parts.every((part) => part === "auto")) return {
+		size: "auto",
+		exact: true
+	};
+	const px = /^(\d+(?:\.\d+)?|\.\d+)px$/.exec(first);
+	return {
+		size: parts.includes("100%") || px !== null && boxWidth !== void 0 && Number(px[1]) >= boxWidth ? "cover" : "auto",
+		exact: false
+	};
+}
+/**
+* `background-position` split into x and y the way MJML and CSS read it: a
+* lone `top` / `bottom` names y and centres x, any other lone value is x
+* with y centred, and a pair is x then y unless it leads with `top` /
+* `bottom` (or with `center` before `left` / `right`). Three- and four-value
+* edge offsets keep their edge keywords only.
+*/
+function splitBackgroundPosition(raw) {
+	const parts = raw.toLowerCase().split(/\s+/);
+	if (parts.length === 1) {
+		const [only] = parts;
+		return only === "top" || only === "bottom" ? {
+			x: "center",
+			y: only,
+			exact: true
+		} : {
+			x: only,
+			y: "center",
+			exact: true
+		};
+	}
+	if (parts.length === 2) {
+		const [a, b] = parts;
+		return a === "top" || a === "bottom" || a === "center" && (b === "left" || b === "right") ? {
+			x: b,
+			y: a,
+			exact: true
+		} : {
+			x: a,
+			y: b,
+			exact: true
+		};
+	}
+	return {
+		x: parts.find((part) => part === "left" || part === "right") ?? "center",
+		y: parts.find((part) => part === "top" || part === "bottom") ?? "center",
+		exact: false
+	};
+}
+/**
+* One axis as a grid point: its keyword; the point nearest a percentage,
+* ties going to the centre; or the start edge for a length, which is an
+* offset from it. `null` when the token is unreadable.
+*/
+function backgroundAxisPoint(token, grid) {
+	const keyword = grid.find((point) => point === token);
+	if (keyword) return {
+		point: keyword,
+		exact: true
+	};
+	const percent = PERCENT.exec(token);
+	if (percent) {
+		const n = Number(percent[1]);
+		return {
+			point: n < 25 ? grid[0] : n > 75 ? grid[2] : grid[1],
+			exact: n === 0 || n === 50 || n === 100
+		};
+	}
+	if (LENGTH.test(token)) return {
+		point: grid[0],
+		exact: parseFloat(token) === 0
+	};
+	return null;
+}
+/**
+* `background-repeat`: unrepeated only when every axis is `no-repeat`.
+* Anything but plain `repeat` tiles too, inexactly.
+*/
+function backgroundRepeatFlag(raw) {
+	const parts = raw.toLowerCase().split(/\s+/);
+	if (parts.every((part) => part === "no-repeat")) return {
+		repeat: false,
+		exact: true
+	};
+	return {
+		repeat: true,
+		exact: parts.every((part) => part === "repeat")
+	};
+}
+/** CSS's initial values: what a browser paints for a longhand the source leaves out. */
+const CSS_BACKGROUND_DEFAULTS = {
+	size: "auto",
+	x: "left",
+	y: "top",
+	repeat: true
+};
+const IMAGE_FUNCTION = /^(?:url|[a-z-]*gradient|image-set)\(/;
+const REPEAT_TOKENS = /* @__PURE__ */ new Set([
+	"repeat",
+	"no-repeat",
+	"repeat-x",
+	"repeat-y",
+	"round",
+	"space"
+]);
+const POSITION_TOKENS = /* @__PURE__ */ new Set([
+	"left",
+	"right",
+	"top",
+	"bottom",
+	"center"
+]);
+const NON_COLOR_TOKENS = /* @__PURE__ */ new Set([
+	"none",
+	"scroll",
+	"fixed",
+	"local",
+	"border-box",
+	"padding-box",
+	"content-box",
+	"text",
+	"cover",
+	"contain",
+	"auto"
+]);
+const MEASURE = /^-?(?:\d+(?:\.\d+)?|\.\d+)(?:%|[a-z]+)?$/i;
+/**
+* The URL inside the first CSS `url(…)`, unquoted and trimmed; "" when there
+* is none or it is malformed. A forward scan rather than a regex, so a long
+* run of unclosed `url(` can't make it backtrack.
+*/
+function cssUrl(value) {
+	const text = value ?? "";
+	const start = text.search(/url\(/i);
+	if (start === -1) return "";
+	let i = start + 4;
+	while (i < text.length && /\s/.test(text[i])) i++;
+	const quote = text[i];
+	if (quote === "\"" || quote === "'") {
+		const close = text.indexOf(quote, i + 1);
+		if (close === -1) return "";
+		let j = close + 1;
+		while (j < text.length && /\s/.test(text[j])) j++;
+		return text[j] === ")" ? text.slice(i + 1, close).trim() : "";
+	}
+	const close = text.indexOf(")", i);
+	if (close === -1) return "";
+	const inner = text.slice(i, close);
+	return /["']/.test(inner) ? "" : inner.trim();
+}
+/**
+* Whitespace-separated tokens, keeping a function's arguments together and
+* making the `/` between position and size a token of its own.
+*/
+function cssTokens(value) {
+	const tokens = [];
+	let depth = 0;
+	let quote = "";
+	let current = "";
+	const push = () => {
+		if (current) tokens.push(current);
+		current = "";
+	};
+	for (const char of value) {
+		if (quote) {
+			current += char;
+			if (char === quote) quote = "";
+			continue;
+		}
+		if (char === "\"" || char === "'") {
+			quote = char;
+			current += char;
+			continue;
+		}
+		if (char === "(") depth++;
+		if (char === ")") depth = Math.max(0, depth - 1);
+		if (depth === 0 && /\s/.test(char)) {
+			push();
+			continue;
+		}
+		if (depth === 0 && char === "/") {
+			push();
+			tokens.push("/");
+			continue;
+		}
+		current += char;
+	}
+	push();
+	return tokens;
+}
+function isColorToken(token) {
+	const lower = token.toLowerCase();
+	if (lower === "/" || IMAGE_FUNCTION.test(lower)) return false;
+	return !REPEAT_TOKENS.has(lower) && !POSITION_TOKENS.has(lower) && !NON_COLOR_TOKENS.has(lower) && !MEASURE.test(lower);
+}
+/**
+* The parts of a `background` shorthand. The colour comes from the last
+* layer, the only one CSS lets carry it; the image and its size, position
+* and repeat come from the first layer with a `url()`.
+*/
+function parseBackgroundShorthand(value) {
+	const layers = splitTopLevel(value, ",").map((layer) => layer.trim()).filter(Boolean);
+	const color = cssTokens(layers[layers.length - 1] ?? "").find(isColorToken) ?? "";
+	const imageLayer = layers.find((layer) => cssUrl(layer) !== "");
+	if (!imageLayer) return {
+		color,
+		url: "",
+		size: "",
+		position: "",
+		repeat: "",
+		layers: layers.length
+	};
+	const tokens = cssTokens(imageLayer);
+	const slash = tokens.indexOf("/");
+	const before = slash === -1 ? tokens : tokens.slice(0, slash);
+	const after = slash === -1 ? [] : tokens.slice(slash + 1);
+	const size = [];
+	for (const token of after) {
+		const lower = token.toLowerCase();
+		const isSize = lower === "cover" || lower === "contain" || lower === "auto" || MEASURE.test(lower);
+		if (size.length === 2 || !isSize) break;
+		size.push(token);
+	}
+	const rest = [...before, ...after.slice(size.length)];
+	return {
+		color,
+		url: cssUrl(imageLayer),
+		size: size.join(" "),
+		position: before.filter((token) => POSITION_TOKENS.has(token.toLowerCase()) || MEASURE.test(token)).join(" "),
+		repeat: rest.filter((token) => REPEAT_TOKENS.has(token.toLowerCase())).join(" "),
+		layers: layers.length
+	};
+}
+/**
+* The colour a `background` shorthand paints, as written (`parseColor` it);
+* "" when it states none. `background: #222 url(x) …` paints `#222`.
+*/
+function backgroundShorthandColor(value) {
+	return value ? parseBackgroundShorthand(value).color : "";
+}
+/**
+* A background image from a URL and its longhands. A longhand left out takes
+* CSS's initial value; a value with no exact keyword takes the nearest one
+* and adds a note naming it. `null` for a blank URL.
+*/
+function buildBackgroundImage(url, longhands, label, boxWidth) {
+	const trimmedUrl = url.trim();
+	if (!trimmedUrl) return null;
+	const notes = [];
+	const lossy = (name, raw, shown) => {
+		notes.push(`${label} ${name} "${raw}" has no exact Templatical equivalent; imported as "${shown}".`);
+	};
+	let size = CSS_BACKGROUND_DEFAULTS.size;
+	const rawSize = longhands.size?.trim();
+	if (rawSize) {
+		const parsed = backgroundSizeKeyword(rawSize, boxWidth);
+		size = parsed.size;
+		if (!parsed.exact) lossy("background-size", rawSize, size);
+	}
+	let x = CSS_BACKGROUND_DEFAULTS.x;
+	let y = CSS_BACKGROUND_DEFAULTS.y;
+	let lossyX = false;
+	let lossyY = false;
+	const rawPosition = longhands.position?.trim();
+	if (rawPosition) {
+		const split = splitBackgroundPosition(rawPosition);
+		const readX = backgroundAxisPoint(split.x, X_GRID);
+		const readY = backgroundAxisPoint(split.y, Y_GRID);
+		x = readX?.point ?? x;
+		y = readY?.point ?? y;
+		lossyX = !split.exact || !readX?.exact;
+		lossyY = !split.exact || !readY?.exact;
+	}
+	const rawX = longhands.positionX?.trim();
+	const overrideX = rawX ? backgroundAxisPoint(rawX.toLowerCase(), X_GRID) : null;
+	if (overrideX) {
+		x = overrideX.point;
+		lossyX = false;
+	}
+	const rawY = longhands.positionY?.trim();
+	const overrideY = rawY ? backgroundAxisPoint(rawY.toLowerCase(), Y_GRID) : null;
+	if (overrideY) {
+		y = overrideY.point;
+		lossyY = false;
+	}
+	if (rawPosition && (lossyX || lossyY)) lossy("background-position", rawPosition, `${x} ${y}`);
+	if (rawX && !overrideX?.exact) lossy("background-position-x", rawX, x);
+	if (rawY && !overrideY?.exact) lossy("background-position-y", rawY, y);
+	let repeat = CSS_BACKGROUND_DEFAULTS.repeat;
+	const rawRepeat = longhands.repeat?.trim();
+	if (rawRepeat) {
+		const parsed = backgroundRepeatFlag(rawRepeat);
+		repeat = parsed.repeat;
+		if (!parsed.exact) lossy("background-repeat", rawRepeat, repeat ? "repeat" : "no-repeat");
+	}
+	return {
+		image: {
+			url: trimmedUrl,
+			size,
+			position: {
+				x,
+				y
+			},
+			repeat
+		},
+		notes
+	};
+}
+/**
+* A background image from CSS declarations: `background-image`, else the
+* `background` shorthand's image, with the size, position and repeat
+* longhands winning over the shorthand's. A style map keeps no declaration
+* order, so a longhand is taken to follow the shorthand, as it usually does.
+* Of several layers the first image is kept, and a note says so. `null`
+* when the declarations paint no image.
+*/
+function readCssBackground(styles, label, boxWidth) {
+	const shorthand = styles.background !== void 0 ? parseBackgroundShorthand(styles.background) : null;
+	const imageLayers = styles["background-image"] !== void 0 ? splitTopLevel(styles["background-image"], ",").map((layer) => layer.trim()) : null;
+	const index = imageLayers ? imageLayers.findIndex((layer) => cssUrl(layer) !== "") : -1;
+	const url = imageLayers ? index === -1 ? "" : cssUrl(imageLayers[index]) : shorthand?.url ?? "";
+	if (!url) return null;
+	const layer = (value) => {
+		if (value === void 0) return void 0;
+		const parts = splitTopLevel(value, ",").map((part) => part.trim());
+		return parts[Math.max(index, 0)] ?? parts[0];
+	};
+	const read = buildBackgroundImage(url, {
+		size: layer(styles["background-size"]) ?? shorthand?.size,
+		position: layer(styles["background-position"]) ?? shorthand?.position,
+		positionX: styles["background-position-x"],
+		positionY: styles["background-position-y"],
+		repeat: layer(styles["background-repeat"]) ?? shorthand?.repeat
+	}, label, boxWidth);
+	const layers = imageLayers?.length ?? shorthand?.layers ?? 1;
+	if (read && layers > 1) read.notes.unshift(`${label} background has ${layers} layers; only the image "${url}" was imported.`);
+	return read;
+}
+/**
+* The legacy `background="…"` attribute of a table, cell or body: a URL
+* alone, tiled from the top left at the image's own size, as a browser
+* draws it.
+*/
+function readLegacyBackground(value, label, boxWidth) {
+	return buildBackgroundImage(value ?? "", {}, label, boxWidth);
+}
 //#endregion
 //#region src/css-resolver.ts
 /**
@@ -277,11 +678,12 @@ function stripAtRules(css) {
 }
 /**
 * Parses a CSS declarations block (`color: red; font-size: 14px`) into
-* a flat record. `!important` markers are dropped.
+* a flat record. `!important` markers are dropped. A semicolon inside quotes
+* or parentheses — `url(data:image/png;base64,…)` — belongs to its value.
 */
 function parseDeclarations(text) {
 	const result = {};
-	for (const decl of text.split(";")) {
+	for (const decl of splitTopLevel(text, ";")) {
 		const idx = decl.indexOf(":");
 		if (idx === -1) continue;
 		const key = decl.slice(0, idx).trim().toLowerCase();
@@ -821,29 +1223,77 @@ function convertInlineRun(nodes, $cell, $) {
 	};
 }
 /**
-* <img> → Image block.
+* An `<img>`'s shown width as `ImageBlock.width`: the `width` attribute, else
+* the `width` style. No width, or `100%`, is `"full"`, as is a px width that
+* reaches `room`, the column less the image's side padding, when the caller
+* knows it. A percentage under 100% becomes px of `room` and pushes a note,
+* since a px width keeps its size on a phone where a percentage shrinks with
+* the column; with no `room` to resolve against it is `"full"`.
+*/
+function resolveImageWidth(values, room, notes) {
+	for (const raw of values) {
+		const value = (raw ?? "").trim();
+		if (!value) continue;
+		const percent = value.match(/^(\d+(?:\.\d+)?)\s*%$/);
+		if (percent) {
+			const share = parseFloat(percent[1]);
+			if (share <= 0 || share >= 100) return "full";
+			if (room === void 0) {
+				notes.push(`Image width ${value} has no known column to resolve against; imported as full width.`);
+				return "full";
+			}
+			const px = Math.round(room * share / 100);
+			if (px >= room) return "full";
+			notes.push(`Image width ${value} imported as ${px}px, which keeps its size on a phone.`);
+			return px;
+		}
+		const px = parsePxValue(value);
+		if (px > 0) return room !== void 0 && px >= room ? "full" : px;
+	}
+	return "full";
+}
+/**
+* <img> → Image block. `room` is the width its column leaves a line, when the
+* caller knows it.
 */
-function convertImage($el, link) {
+function convertImage($el, room, link) {
 	const styles = getStyles$1($el);
 	const src = $el.attr("src") ?? "";
 	const alt = $el.attr("alt") ?? "";
-	const widthAttr = $el.attr("width");
-	const widthStyle = styles.width;
-	const readWidth = parsePxValue(widthAttr) || parsePxValue(widthStyle) || void 0;
-	const width = readWidth ?? 600;
-	const height = parsePxValue($el.attr("height")) || parsePxValue(styles.height) || void 0;
+	const padding = readPaddingFromStyles(styles);
+	const imageRoom = room === void 0 ? void 0 : room - padding.left - padding.right;
+	const notes = [];
+	const width = resolveImageWidth([$el.attr("width"), styles.width], imageRoom, notes);
+	const heightStyle = (styles.height ?? "").trim();
+	const height = (heightStyle ? parsePxValue(heightStyle) : parsePxValue($el.attr("height"))) || void 0;
 	const href = (link?.url ?? "").trim();
-	return createImageBlock({
-		src,
-		alt,
-		width,
-		height,
-		borderRadius: parseImageBorderRadius(styles["border-radius"], readWidth, height),
-		align: parseAlignment(styles["text-align"], "center"),
-		styles: { padding: readPaddingFromStyles(styles) },
-		...href ? { linkUrl: href } : {},
-		...href && link?.openInNewTab ? { linkOpenInNewTab: true } : {}
-	});
+	const stated = Boolean(($el.attr("width") ?? "").trim() || (styles.width ?? "").trim());
+	const shownWidth = width === "full" ? imageRoom : width;
+	return {
+		block: createImageBlock({
+			src,
+			alt,
+			width,
+			height,
+			borderRadius: parseImageBorderRadius(styles["border-radius"], stated ? shownWidth : void 0, height),
+			align: parseAlignment(styles["text-align"], "center"),
+			styles: { padding },
+			...href ? { linkUrl: href } : {},
+			...href && link?.openInNewTab ? { linkOpenInNewTab: true } : {}
+		}),
+		notes
+	};
+}
+/**
+* The report entry for an image `convertImage` produced from `sourceTag`.
+*/
+function imageEntry(sourceTag, notes) {
+	return {
+		sourceTag,
+		templaticalBlockType: "image",
+		status: notes.length > 0 ? "approximated" : "converted",
+		...notes.length > 0 ? { note: notes.join(" ") } : {}
+	};
 }
 /**
 * Whether an `<a>` wraps an image. An anchor wrapping only an image carries
@@ -858,17 +1308,14 @@ function isImageAnchor($el) {
 function isImageOnlyAnchor($el) {
 	return isImageAnchor($el) && ($el.text() ?? "").trim() === "";
 }
-function convertLinkedImage($anchor, $img) {
+function convertLinkedImage($anchor, $img, room) {
+	const { block, notes } = convertImage($img, room, {
+		url: $anchor.attr("href") ?? "",
+		openInNewTab: $anchor.attr("target") === "_blank"
+	});
 	return {
-		block: convertImage($img, {
-			url: $anchor.attr("href") ?? "",
-			openInNewTab: $anchor.attr("target") === "_blank"
-		}),
-		entry: {
-			sourceTag: "a",
-			templaticalBlockType: "image",
-			status: "converted"
-		}
+		block,
+		entry: imageEntry("a", notes)
 	};
 }
 /**
@@ -879,7 +1326,7 @@ function convertLinkedImage($anchor, $img) {
 */
 function splitMixedImageAnchor($anchor, $host, $) {
 	const results = [];
-	for (const img of $anchor.find("img").toArray()) results.push(convertLinkedImage($anchor, $(img)));
+	for (const img of $anchor.find("img").toArray()) results.push(convertLinkedImage($anchor, $(img), void 0));
 	const $clone = $anchor.clone();
 	$clone.find("img").remove();
 	if (($clone.text() ?? "").trim() === "") return results;
@@ -1213,8 +1660,8 @@ function isButtonCell($el, $) {
 * styles are what `styles` already holds.
 *
 * `room` is the width, in px, that a line in the element's column can span
-* before the element's own padding, when the caller knows it. Only a divider
-* reads it.
+* before the element's own padding, when the caller knows it. A divider and an
+* image read it.
 *
 * Returns `null` for elements that do not contain any meaningful content
 * (the caller should skip them).
@@ -1231,16 +1678,15 @@ function convertElement($el, $, room) {
 			status: "converted"
 		}
 	};
-	if (tag === "img") return {
-		block: convertImage($target),
-		entry: {
-			sourceTag: tag,
-			templaticalBlockType: "image",
-			status: "converted"
-		}
-	};
+	if (tag === "img") {
+		const { block, notes } = convertImage($target, room);
+		return {
+			block,
+			entry: imageEntry(tag, notes)
+		};
+	}
 	if (tag === "a") {
-		if (isImageOnlyAnchor($target)) return convertLinkedImage($target, $($target.find("img")[0]));
+		if (isImageOnlyAnchor($target)) return convertLinkedImage($target, $($target.find("img")[0]), room);
 		if (looksLikeButton(styles)) return {
 			block: convertButton($target),
 			entry: {
@@ -1533,11 +1979,12 @@ function readHostPadding($el) {
 }
 /**
 * The colour an element paints behind its content: its CSS background, then
-* its legacy `bgcolor` attribute, which CSS overrides.
+* its legacy `bgcolor` attribute, which CSS overrides. A `background`
+* shorthand contributes its colour token, image or not.
 */
 function fillOf($el) {
 	const styles = getStyles($el);
-	return parseColor(styles["background-color"]) || parseColor(styles.background) || parseLegacyColor($el.attr("bgcolor"));
+	return parseColor(styles["background-color"]) || parseColor(backgroundShorthandColor(styles.background)) || parseLegacyColor($el.attr("bgcolor"));
 }
 /**
 * Insets columns by the padding of the element that holds them, where that
@@ -1802,19 +2249,20 @@ function packagingTablesOf($cell, $) {
 *
 * - 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's style must set no background and no padding. The section it
-*   emits is the carrier for those, so descending past a styled row would
-*   drop the band it paints.
+* - The row's style must set no background (colour or image) and no padding.
+*   The section it emits is the carrier for those, so descending past a
+*   styled row would drop the band it paints.
 *
-* A fill the descent does pass — the row's `bgcolor`, its cell's, its
-* table's — is not lost: `processTable` hands it to the tables below, whose
-* sections take it when nothing nearer paints them. Section counts depend on
-* this gate, so a fill is carried down rather than made a reason to stop.
+* A fill or image the descent does pass — the row's `bgcolor`, its cell's,
+* its table's — is not lost: `processTable` hands it to the tables below,
+* whose sections take it when nothing nearer paints them. Section counts
+* depend on this gate, so a fill is carried down rather than made a reason
+* to stop.
 */
 function packagingRowTables($row, cells, $) {
 	if (cells.length !== 1) return null;
 	const rowStyles = getStyles($row);
-	if (parseColor(rowStyles["background-color"]) || parseColor(rowStyles.background)) return null;
+	if (parseColor(rowStyles["background-color"]) || parseColor(backgroundShorthandColor(rowStyles.background)) || readCssBackground(rowStyles, "Section", void 0)) return null;
 	const padding = readPaddingFromStyles(rowStyles);
 	if (padding.top || padding.right || padding.bottom || padding.left) return null;
 	return packagingTablesOf(cells[0], $);
@@ -1841,13 +2289,15 @@ function packagingRowTables($row, cells, $) {
 * three-into-one merge for a row that always stated one column.
 *
 * A background the section could not keep adds its own note after the
-* layout's, so one entry names every loss the row had.
+* layout's, and so does a background-image value or column image it could not
+* keep, so one entry names every loss the row had.
 */
-function sectionEntry(columnCount, slotCount, ratioNote, fillNote) {
+function sectionEntry(columnCount, slotCount, ratioNote, fillNote, imageNotes = []) {
 	const notes = [];
 	if (slotCount !== columnCount) notes.push(`Row of ${columnCount} columns was merged into a single column. Templatical sections hold at most 3 columns.`);
 	else if (ratioNote) notes.push(ratioNote);
 	if (fillNote) notes.push(fillNote);
+	notes.push(...imageNotes);
 	if (notes.length === 0) return {
 		sourceTag: "tr",
 		templaticalBlockType: "section",
@@ -1887,6 +2337,76 @@ function sectionFill($row, layoutCells, tableFill, $) {
 	};
 }
 /**
+* The image an element paints: its CSS background, else the legacy
+* `background` attribute of a table or cell. A `background-image` or
+* `background` declaration overrides the attribute; a `background-color`
+* doesn't.
+*/
+function imageOf($el, room) {
+	const styles = getStyles($el);
+	if (styles["background-image"] !== void 0 || styles.background !== void 0) return readCssBackground(styles, "Section", room);
+	return $el.is("table, td, th") ? readLegacyBackground($el.attr("background"), "Section", room) : null;
+}
+function sameImage(a, b) {
+	return a.url === b.url && a.size === b.size && a.repeat === b.repeat && a.position.x === b.position.x && a.position.y === b.position.y;
+}
+/** Each section gets its own image object, so editing one leaves the others alone. */
+function copyImage(image) {
+	return {
+		...image,
+		position: { ...image.position }
+	};
+}
+function droppedColumnsNote(columns) {
+	return columns.length === 1 ? `The background image on column ${columns[0]} was dropped. A Templatical section has one background image.` : `Background images on columns ${columns.join(", ")} were dropped. A Templatical section has one background image.`;
+}
+/**
+* The image a row's section paints, nearest first, as `sectionFill` reads
+* colour: the `<tr>`, or the cell around a column set, which spans the row;
+* then the columns' own images, moved up when there is one column or every
+* column shares the same image; then `carried`, the image of the table
+* holding the row or of the wrappers around it. Column images the section
+* can't keep are named in a note. A button cell's background is the
+* button's, so it is never read as a column image.
+*/
+function sectionImage($row, layoutCells, hosts, carried, room, $) {
+	const own = imageOf($row, room) ?? (hosts[0]?.kind === "container" ? imageOf(layoutCells[0], room) : null);
+	const columns = hosts.map((host) => host.kind === "cell" && isButtonCell(host.$el, $).match ? null : imageOf(host.$el, room));
+	const withImage = columns.flatMap((read, index) => read ? [index + 1] : []);
+	const first = columns[0] ?? null;
+	const shared = first !== null && columns.every((read) => read !== null && sameImage(read.image, first.image));
+	const notes = [];
+	let picked = own;
+	if (withImage.length > 0) {
+		if (!own && shared) picked = first;
+		else notes.push(droppedColumnsNote(withImage));
+	}
+	if (picked) return {
+		image: copyImage(picked.image),
+		notes: [...picked.notes, ...notes],
+		carried: null
+	};
+	if (carried) return {
+		image: copyImage(carried.read.image),
+		notes: [...carried.read.notes, ...notes],
+		carried
+	};
+	return {
+		image: void 0,
+		notes,
+		carried: null
+	};
+}
+/** Note on each section a carried image was copied onto, once it spans more than one. */
+function noteSpread(carried) {
+	if (carried.entries.length < 2) return;
+	const note = `A background image behind ${carried.entries.length} sections was applied to each of them — Templatical has no multi-section band.`;
+	for (const entry of carried.entries) {
+		entry.status = "approximated";
+		entry.note = entry.note ? `${entry.note} ${note}` : note;
+	}
+}
+/**
 * The report entry for a nested row whose section wrapper was dropped, or
 * `null` when dropping it lost nothing.
 *
@@ -2048,8 +2568,11 @@ function hostRooms(rowRoom, layout, hostCount, setPadding) {
 *   land: the template body's width for a table whose rows become sections,
 *   the surrounding column's for a flattened one. Unknown, a divider keeps a
 *   px width as stated.
+* @param enclosingImage - The image of the wrapper cells and tables this
+*   table was reached through, which its sections take when nothing nearer
+*   paints one.
 */
-function processTable($table, $, entries, warnings, flattenInline = false, enclosingFill = "", room) {
+function processTable($table, $, entries, warnings, flattenInline = false, enclosingFill = "", room, enclosingImage = null) {
 	if (!isLayoutTable($table, $)) {
 		entries.push({
 			sourceTag: "table",
@@ -2062,6 +2585,11 @@ function processTable($table, $, entries, warnings, flattenInline = false, enclo
 	const rows = getDirectRows($table, $);
 	if (rows.length === 0) return [];
 	const tableFill = fillOf($table) || enclosingFill;
+	const ownTableImage = imageOf($table, room);
+	const tableImage = ownTableImage ? {
+		read: ownTableImage,
+		entries: []
+	} : enclosingImage;
 	const sections = [];
 	for (const $row of rows) {
 		const cells = getDirectCells($row, $);
@@ -2069,10 +2597,16 @@ function processTable($table, $, entries, warnings, flattenInline = false, enclo
 		const packaging = packagingRowTables($row, cells, $);
 		if (packaging) {
 			const carried = fillOf($row) || fillOf(cells[0]) || tableFill;
+			const cellImage = imageOf(cells[0], room);
+			const carriedImage = cellImage ? {
+				read: cellImage,
+				entries: []
+			} : tableImage;
 			const wrapperPadding = readHostPadding(cells[0]);
 			const innerRoom = flattenInline ? narrow(room, wrapperPadding) : room;
 			const descended = [];
-			for (const $inner of packaging) descended.push(...processTable($inner, $, entries, warnings, flattenInline, carried, innerRoom));
+			for (const $inner of packaging) descended.push(...processTable($inner, $, entries, warnings, flattenInline, carried, innerRoom, carriedImage));
+			if (cellImage && carriedImage) noteSpread(carriedImage);
 			if (flattenInline) insetColumns([descended], wrapperPadding);
 			sections.push(...descended);
 			continue;
@@ -2104,16 +2638,21 @@ function processTable($table, $, entries, warnings, flattenInline = false, enclo
 			continue;
 		}
 		const fill = sectionFill($row, layoutCells, tableFill, $);
-		entries.push(sectionEntry(hosts.length, columnsBlocks.length, ratio.note, fill.note));
+		const image = sectionImage($row, layoutCells, hosts, tableImage, room, $);
+		const entry = sectionEntry(hosts.length, columnsBlocks.length, ratio.note, fill.note, image.notes);
+		entries.push(entry);
+		image.carried?.entries.push(entry);
 		sections.push(createSectionBlock({
 			columns: ratio.layout,
 			children: columnsBlocks,
 			styles: {
 				padding,
 				...fill.color ? { backgroundColor: fill.color } : {}
-			}
+			},
+			...image.image ? { backgroundImage: image.image } : {}
 		}));
 	}
+	if (ownTableImage && tableImage) noteSpread(tableImage);
 	return sections;
 }
 //#endregion
@@ -2142,7 +2681,7 @@ function extractSettings($, linkUnderline) {
 	const $body = $("body");
 	const bodyStyles = parseStyleAttribute($body.attr("style"));
 	const fontFamily = canonicalFontStack(bodyStyles["font-family"]) || "Arial";
-	const backgroundColor = parseColor(bodyStyles["background-color"]) || parseColor(bodyStyles.background) || "#ffffff";
+	const backgroundColor = parseColor(bodyStyles["background-color"]) || parseColor(backgroundShorthandColor(bodyStyles.background)) || "#ffffff";
 	const $outerTable = $body.find("table").first();
 	const widthAttr = parsePxValue($outerTable.attr("width"));
 	const widthStyle = parsePxValue(parseStyleAttribute($outerTable.attr("style")).width);
@@ -2265,6 +2804,16 @@ function processBody($, entries, warnings, bodyWidth) {
 	return blocks;
 }
 /**
+* The page's background image, which has no Templatical equivalent: the
+* body's CSS background, else its legacy `background` attribute.
+*/
+function pageImageWarning($) {
+	const $body = $("body");
+	const styles = parseStyleAttribute($body.attr("style"));
+	const read = styles["background-image"] !== void 0 || styles.background !== void 0 ? readCssBackground(styles, "Body", void 0) : readLegacyBackground($body.attr("background"), "Body", void 0);
+	return read ? `The email background image "${read.image.url}" was dropped; Templatical has no email-level background image.` : null;
+}
+/**
 * Converts an HTML email template to Templatical TemplateContent.
 *
 * Designed for table-based marketing email HTML (output of MJML, Mailchimp,
@@ -2297,6 +2846,8 @@ function convertHtmlTemplate(html) {
 	const entries = [];
 	const warnings = [];
 	const settings = extractSettings($, linkUnderline);
+	const pageImage = pageImageWarning($);
+	if (pageImage) warnings.push(pageImage);
 	const blocks = processBody($, entries, warnings, settings.width);
 	if (blocks.length === 0) warnings.push("No convertible content was found in the HTML. The email may use a non-table layout — modern HTML support is limited.");
 	return {