@maily-to/migration 2.0.0-beta.7 → 2.0.0-beta.8

package/dist/index.mjs

@@ -1,65 +1,67 @@
-import { MAX_IMAGE_WIDTH_PERCENTAGE, MIN_IMAGE_WIDTH_PERCENTAGE } from "@maily-to/shared";
-//#region src/utils/border.ts
-/**
-* Expands a single border-radius value into the four individual
-* corner properties used by v2 nodes: borderTopLeftRadius,
-* borderTopRightRadius, borderBottomRightRadius, borderBottomLeftRadius.
-* In v1, border radius was stored as a single number; v2 stores
-* each corner independently to support non-uniform rounding.
-*/
-function splitBorderRadius(radius) {
-	return {
-		borderTopLeftRadius: radius,
-		borderTopRightRadius: radius,
-		borderBottomRightRadius: radius,
-		borderBottomLeftRadius: radius
-	};
+import { BOX_SIDES, DEFAULT_BUTTON_KIND, DEFAULT_CONTAINER_WIDTH_PIXELS, DEFAULT_VARIABLE_END_TRIGGER, DEFAULT_VARIABLE_START_TRIGGER, MAILY_NODE_TYPES, TEXT_ALIGNMENTS, clampImageWidthPercentage, parseInlineStyles, stringifyInlineStyles } from "@maily-to/shared";
+//#region src/utils/style.ts
+function getStyleAttribute(declarations) {
+	const rest = {};
+	for (const [property, value] of Object.entries(declarations)) {
+		if (value === null || value === void 0 || value === "") continue;
+		rest[property] = value;
+	}
+	return stringifyInlineStyles(rest) || null;
 }
-/**
-* Expands a single border-width value into the four individual
-* side properties used by v2 nodes: borderTopWidth, borderRightWidth,
-* borderBottomWidth, borderLeftWidth. In v1, border width was stored
-* as a single number; v2 stores each side independently to support
-* non-uniform borders.
-*/
-function splitBorderWidth(width) {
-	return {
-		borderTopWidth: width,
-		borderRightWidth: width,
-		borderBottomWidth: width,
-		borderLeftWidth: width
+function getPixelValue(value) {
+	return `${value}px`;
+}
+const BOX_SIDE_SUFFIXES = {
+	bottom: "Bottom",
+	left: "Left",
+	right: "Right",
+	top: "Top"
+};
+function getBoxDeclarations(options) {
+	const { bottom, left, property, right, top } = options;
+	const values = {
+		bottom,
+		left,
+		right,
+		top
 	};
+	const declarations = {};
+	for (const side of BOX_SIDES) {
+		const value = values[side];
+		if (typeof value === "number") declarations[`${property}${BOX_SIDE_SUFFIXES[side]}`] = getPixelValue(value);
+	}
+	return declarations;
+}
+//#endregion
+//#region src/utils/variable.ts
+const LINK_PROTOCOL_REGEX = /https?:\/\//;
+function getVariableReference(value) {
+	const name = value.replace(LINK_PROTOCOL_REGEX, "");
+	if (name.startsWith(DEFAULT_VARIABLE_START_TRIGGER)) return name;
+	return `${DEFAULT_VARIABLE_START_TRIGGER}${name}${DEFAULT_VARIABLE_END_TRIGGER}`;
 }
 //#endregion
 //#region src/transforms/button.ts
-const BORDER_RADIUS_MAP = {
-	sharp: 0,
-	smooth: 6,
-	round: 9999
+const BORDER_RADIUS_VALUES = {
+	sharp: "0px",
+	smooth: "6px",
+	round: "9999px"
 };
-/**
-* Migrates a v1 button node to the v2 schema.
-* Performs the following conversions:
-*   - Moves `attrs.text` into `content` as a text node (or a variable
-*     node when `isTextVariable` is true).
-*   - Renames `buttonColor` → `backgroundColor`, `textColor` → `color`.
-*   - Converts `variant: 'outline'` to `backgroundColor: 'transparent'`.
-*   - Converts the `borderRadius` string enum (sharp/smooth/round) into
-*     four numeric corner properties via splitBorderRadius.
-*   - Sets v2 defaults: kind "tight", paddingMode "mixed",
-*     borderRadiusMode/borderWidthMode "uniform", borderStyle "solid".
-*   - Drops deprecated flags: isTextVariable, isUrlVariable, variant.
-*/
+const FALLBACK_BORDER_RADIUS = "9999px";
+const FALLBACK_OUTLINE_COLOR = "#000000";
+const OUTLINE_VARIANT = "outline";
+const V1_DEFAULT_ALIGN = TEXT_ALIGNMENTS.LEFT;
 function button(node, warnings) {
-	const attrs = node.attrs ?? {};
+	node.attrs ??= {};
+	const attrs = node.attrs;
 	if (!node.content) {
 		const text = attrs.text ?? "";
 		if (attrs.isTextVariable && text) node.content = [{
-			type: "variable",
+			type: MAILY_NODE_TYPES.VARIABLE,
 			attrs: { id: text }
 		}];
 		else if (text) node.content = [{
-			type: "text",
+			type: MAILY_NODE_TYPES.TEXT,
 			text
 		}];
 	}
@@ -79,90 +81,170 @@ function button(node, warnings) {
 		});
 		delete attrs.isTextVariable;
 	}
-	if ("buttonColor" in attrs) {
+	if (attrs.isUrlVariable === true) {
+		warnings.push({
+			nodeType: "button",
+			field: "isUrlVariable",
+			message: "Migrated \"isUrlVariable\" → variable reference in \"url\""
+		});
+		attrs.url = getVariableReference(attrs.url ?? "");
+	}
+	delete attrs.isUrlVariable;
+	if ("alignment" in attrs) {
+		if (attrs.alignment) {
+			warnings.push({
+				nodeType: "button",
+				field: "alignment",
+				message: "Migrated \"alignment\" → \"align\""
+			});
+			attrs.align = attrs.alignment;
+		}
+		delete attrs.alignment;
+	}
+	attrs.align ??= V1_DEFAULT_ALIGN;
+	const declarations = parseInlineStyles(attrs.style ?? "");
+	if (attrs.buttonColor != null && attrs.variant !== OUTLINE_VARIANT) {
 		warnings.push({
 			nodeType: "button",
 			field: "buttonColor",
-			message: "Migrated \"buttonColor\" → \"backgroundColor\""
+			message: "Migrated \"buttonColor\" → \"style\""
 		});
-		attrs.backgroundColor = attrs.buttonColor;
-		delete attrs.buttonColor;
+		declarations.backgroundColor = attrs.buttonColor;
 	}
-	if ("textColor" in attrs) {
+	if (attrs.textColor != null) {
 		warnings.push({
 			nodeType: "button",
 			field: "textColor",
-			message: "Migrated \"textColor\" → \"color\""
+			message: "Migrated \"textColor\" → \"style\""
 		});
-		attrs.color = attrs.textColor;
-		delete attrs.textColor;
+		declarations.color = attrs.textColor;
 	}
-	if (attrs.variant === "outline") {
+	if (attrs.variant === OUTLINE_VARIANT) {
 		warnings.push({
 			nodeType: "button",
 			field: "variant",
-			message: "Migrated \"variant: outline\" → transparent backgroundColor + border properties"
+			message: "Migrated \"variant: outline\" → transparent background + border in \"style\""
 		});
-		attrs.borderColor = attrs.backgroundColor ?? "#000000";
-		attrs.borderTopWidth = 2;
-		attrs.borderRightWidth = 2;
-		attrs.borderBottomWidth = 2;
-		attrs.borderLeftWidth = 2;
-		attrs.backgroundColor = "transparent";
+		declarations.backgroundColor = "transparent";
+		declarations.borderWidth = "2px";
+		declarations.borderStyle = "solid";
+		declarations.borderColor = attrs.buttonColor ?? FALLBACK_OUTLINE_COLOR;
 	}
 	delete attrs.variant;
 	if (typeof attrs.borderRadius === "string") {
 		warnings.push({
 			nodeType: "button",
 			field: "borderRadius",
-			message: "Migrated \"borderRadius\" enum → individual corner radius properties"
-		});
-		const radius = BORDER_RADIUS_MAP[attrs.borderRadius] ?? 9999;
-		Object.assign(attrs, splitBorderRadius(radius));
-		delete attrs.borderRadius;
-	}
-	attrs.kind ??= "tight";
-	attrs.paddingMode ??= "mixed";
-	attrs.borderRadiusMode ??= "uniform";
-	attrs.borderWidthMode ??= "uniform";
-	attrs.borderStyle ??= "solid";
-	attrs.borderColor ??= "#000000";
-	attrs.borderTopWidth ??= 0;
-	attrs.borderRightWidth ??= 0;
-	attrs.borderBottomWidth ??= 0;
-	attrs.borderLeftWidth ??= 0;
-	if ("isUrlVariable" in attrs) {
-		warnings.push({
-			nodeType: "button",
-			field: "isUrlVariable",
-			message: "Attribute \"isUrlVariable\" is not supported in v2 and was dropped"
+			message: "Migrated \"borderRadius\" enum → \"style\""
 		});
-		delete attrs.isUrlVariable;
-	}
+		declarations.borderRadius = BORDER_RADIUS_VALUES[attrs.borderRadius] ?? FALLBACK_BORDER_RADIUS;
+	}
+	delete attrs.borderRadius;
+	Object.assign(declarations, getBoxDeclarations({
+		bottom: attrs.paddingBottom,
+		left: attrs.paddingLeft,
+		property: "padding",
+		right: attrs.paddingRight,
+		top: attrs.paddingTop
+	}));
+	delete attrs.paddingTop;
+	delete attrs.paddingRight;
+	delete attrs.paddingBottom;
+	delete attrs.paddingLeft;
+	const style = getStyleAttribute(declarations);
+	if (style) attrs.style = style;
+	attrs.kind ??= DEFAULT_BUTTON_KIND;
+	delete attrs.buttonColor;
+	delete attrs.textColor;
 }
 //#endregion
-//#region src/transforms/column.ts
-const DROPPED_COLUMN_ATTRS = [
-	"columnId",
-	"backgroundColor",
-	"borderRadius",
-	"borderWidth",
-	"borderColor",
+//#region src/utils/box-style.ts
+const DEFAULT_BORDER_COLOR = "#e2e2e2";
+const BORDER_FIELDS = ["borderWidth", "borderColor"];
+const PADDING_FIELDS = [
 	"paddingTop",
 	"paddingRight",
 	"paddingBottom",
-	"paddingLeft",
-	"visibilityRule"
+	"paddingLeft"
 ];
+function getBorderDeclarations(options) {
+	const { color, width } = options;
+	if (typeof width !== "number" || width <= 0) return {};
+	return {
+		borderColor: color ?? DEFAULT_BORDER_COLOR,
+		borderStyle: "solid",
+		borderWidth: getPixelValue(width)
+	};
+}
+function getBorderRadiusDeclarations(radius) {
+	if (typeof radius !== "number" || radius <= 0) return {};
+	return { borderRadius: getPixelValue(radius) };
+}
+function getBoxStyleDeclarations(options) {
+	const { attrs, nodeType, warnings } = options;
+	const declarations = {};
+	if (attrs.backgroundColor) {
+		warnings.push({
+			nodeType,
+			field: "backgroundColor",
+			message: "Migrated \"backgroundColor\" → \"style\""
+		});
+		declarations.backgroundColor = attrs.backgroundColor;
+	}
+	delete attrs.backgroundColor;
+	const border = getBorderDeclarations({
+		color: attrs.borderColor,
+		width: attrs.borderWidth
+	});
+	if (Object.keys(border).length > 0) {
+		for (const field of BORDER_FIELDS) if (attrs[field] != null) warnings.push({
+			nodeType,
+			field,
+			message: `Migrated "${field}" → "style"`
+		});
+		Object.assign(declarations, border);
+	}
+	for (const field of BORDER_FIELDS) delete attrs[field];
+	const radius = getBorderRadiusDeclarations(attrs.borderRadius);
+	if (Object.keys(radius).length > 0) {
+		warnings.push({
+			nodeType,
+			field: "borderRadius",
+			message: "Migrated \"borderRadius\" → \"style\""
+		});
+		Object.assign(declarations, radius);
+	}
+	delete attrs.borderRadius;
+	const padding = getBoxDeclarations({
+		bottom: attrs.paddingBottom,
+		left: attrs.paddingLeft,
+		property: "padding",
+		right: attrs.paddingRight,
+		top: attrs.paddingTop
+	});
+	if (Object.keys(padding).length > 0) {
+		warnings.push({
+			nodeType,
+			field: "padding",
+			message: "Migrated \"padding*\" → \"style\""
+		});
+		Object.assign(declarations, padding);
+	}
+	for (const field of PADDING_FIELDS) delete attrs[field];
+	return declarations;
+}
+//#endregion
+//#region src/transforms/column.ts
+const DROPPED_COLUMN_ATTRS = ["columnId", "visibilityRule"];
 /**
 * Migrates a v1 column node to the v2 schema.
 * Performs the following conversions:
 *   - Converts `width: 'auto'` → `null` (v2 uses null for equal-space columns).
 *   - Converts percentage width strings (e.g. "50%") to numbers (e.g. 50).
-*   - Drops v1 styling attributes that are not supported on columns in v2:
-*     columnId, backgroundColor, borderRadius, borderWidth, borderColor,
-*     paddingTop/Right/Bottom/Left, and visibilityRule (converted from showIfKey
-*     by the global transform). Each dropped attribute emits a warning.
+*   - Converts the v1 styling attributes backgroundColor, borderRadius,
+*     borderWidth/borderColor and paddingTop/Right/Bottom/Left into `style`.
+*   - Drops columnId and visibilityRule, neither of which a v2 column
+*     supports. Each dropped attribute emits a warning.
 */
 function column(node, warnings) {
 	const attrs = node.attrs ?? {};
@@ -171,6 +253,15 @@ function column(node, warnings) {
 		const parsed = parseFloat(attrs.width);
 		attrs.width = Number.isNaN(parsed) ? null : parsed;
 	}
+	const style = getStyleAttribute({
+		...parseInlineStyles(attrs.style ?? ""),
+		...getBoxStyleDeclarations({
+			attrs,
+			nodeType: "column",
+			warnings
+		})
+	});
+	if (style) attrs.style = style;
 	for (const field of DROPPED_COLUMN_ATTRS) if (field in attrs && attrs[field] != null) {
 		warnings.push({
 			nodeType: "column",
@@ -182,6 +273,7 @@ function column(node, warnings) {
 }
 //#endregion
 //#region src/transforms/columns.ts
+const DEFAULT_COLUMNS_GAP$1 = 8;
 /**
 * Migrates a v1 columns node to the v2 schema.
 * In v2, columns tracks its child count and gap explicitly:
@@ -191,16 +283,10 @@ function column(node, warnings) {
 function columns(node, _warnings) {
 	const attrs = node.attrs ?? {};
 	attrs.columnCount ??= node.content?.length ?? 0;
-	attrs.gap ??= 8;
+	attrs.gap ??= DEFAULT_COLUMNS_GAP$1;
 }
 //#endregion
 //#region src/transforms/footer.ts
-/**
-* Migrates a v1 footer node to the v2 schema.
-* Removes the `maily-component` attribute which was used in v1
-* as a marker to identify the footer node. In v2, the node type
-* alone is sufficient for identification.
-*/
 function footer(node, warnings) {
 	const attrs = node.attrs ?? {};
 	if ("maily-component" in attrs) {
@@ -213,30 +299,22 @@ function footer(node, warnings) {
 	}
 }
 //#endregion
-//#region src/utils/id.ts
-/**
-* Generates a unique identifier for a node.
-* Uses the Web Crypto API to produce a v4 UUID string,
-* e.g. "3b241101-e2bb-4d7a-8613-e4d4e2f1b9c1".
-*/
-function uid() {
-	return crypto.randomUUID();
-}
-//#endregion
 //#region src/transforms/global.ts
-/**
-* Applies transforms common to every node in the document tree.
-* Handles three conversions that apply regardless of node type:
-*   1. showIfKey → visibilityRule: converts the v1 conditional
-*      visibility string into a structured v2 VisibilityRule object
-*      with action "show", operator "is_true".
-*   2. textDirection → dir: renames the attribute to match the v2
-*      schema (mirrors the HTML `dir` attribute).
-*   3. id generation: assigns a crypto UUID to any node that lacks
-*      an id, except for `doc` and `text` nodes which don't use ids.
-*/
+const ID_NODE_TYPES = [
+	MAILY_NODE_TYPES.HEADING,
+	MAILY_NODE_TYPES.PARAGRAPH,
+	MAILY_NODE_TYPES.SECTION,
+	MAILY_NODE_TYPES.REPEAT,
+	MAILY_NODE_TYPES.COLUMNS,
+	MAILY_NODE_TYPES.COLUMN,
+	MAILY_NODE_TYPES.BULLET_LIST,
+	MAILY_NODE_TYPES.ORDERED_LIST,
+	MAILY_NODE_TYPES.LIST_ITEM,
+	MAILY_NODE_TYPES.HORIZONTAL_RULE,
+	MAILY_NODE_TYPES.BLOCKQUOTE
+];
 function global(node, warnings) {
-	if (node.type === "text") return;
+	if (node.type === MAILY_NODE_TYPES.TEXT) return;
 	if (!node.attrs) node.attrs = {};
 	const attrs = node.attrs;
 	if (attrs.showIfKey) {
@@ -264,39 +342,44 @@ function global(node, warnings) {
 		}
 		delete attrs.textDirection;
 	}
-	if (node.type !== "doc" && !attrs.id) attrs.id = uid();
+	if ("textAlign" in attrs) {
+		if (attrs.textAlign && attrs.textAlign !== "left") {
+			warnings.push({
+				nodeType: node.type,
+				field: "textAlign",
+				message: "Migrated \"textAlign\" → \"style\""
+			});
+			const declarations = parseInlineStyles(attrs.style ?? "");
+			declarations.textAlign = attrs.textAlign;
+			attrs.style = stringifyInlineStyles(declarations);
+		}
+		delete attrs.textAlign;
+	}
+	if (ID_NODE_TYPES.includes(node.type) && !attrs.id) attrs.id = crypto.randomUUID();
 }
 //#endregion
-//#region src/transforms/html-code-block.ts
-/**
-* Migrates a v1 htmlCodeBlock node to the v2 schema.
-* Strips the `activeTab` attribute which was editor-only UI state
-* persisted into the document JSON.
-*/
-function htmlCodeBlock(node, warnings) {
-	const attrs = node.attrs ?? {};
-	if ("activeTab" in attrs) {
-		warnings.push({
-			nodeType: "htmlCodeBlock",
-			field: "activeTab",
-			message: "Editor-only attribute \"activeTab\" is not supported in v2 and was dropped"
-		});
-		delete attrs.activeTab;
-	}
+//#region src/utils/image-width.ts
+function getWidthPercentage(options) {
+	const { containerWidth, pixels } = options;
+	return clampImageWidthPercentage(Math.round(pixels / containerWidth * 100));
 }
 //#endregion
 //#region src/transforms/image.ts
-const DEFAULT_CONTAINER_WIDTH$1 = 600;
+const DROPPED_IMAGE_ATTRS = [
+	"height",
+	"lockAspectRatio",
+	"aspectRatio"
+];
 /**
 * Migrates a v1 image node to the v2 schema.
 * Performs the following conversions:
 *   - Renames `alignment` → `align` to match the v2 attribute name.
-*   - Splits the single `borderRadius` number into four corner properties.
-*   - Converts `width: 'auto'` → `'100%'` (v2 uses percentage strings).
-*   - Sets v2 border defaults: borderRadiusMode/borderWidthMode "uniform",
-*     borderStyle "solid", all border widths to 0.
-*   - Drops deprecated attrs: height, isSrcVariable, isExternalLinkVariable,
-*     lockAspectRatio, aspectRatio.
+*   - Moves the `borderRadius` number into the `style` attribute.
+*   - Converts `width` to a percentage string, using the container width
+*     stamped by `annotateContainerWidths` to scale pixel values.
+*   - Resolves `isSrcVariable` / `isExternalLinkVariable` into variable
+*     references inside `src` / `externalLink`.
+*   - Drops deprecated attrs: height, lockAspectRatio, aspectRatio.
 */
 function image(node, warnings) {
 	const attrs = node.attrs ?? {};
@@ -309,37 +392,45 @@ function image(node, warnings) {
 		attrs.align = attrs.alignment;
 		delete attrs.alignment;
 	}
-	if (typeof attrs.borderRadius === "number") {
+	const declarations = {};
+	if (typeof attrs.borderRadius === "number" && attrs.borderRadius > 0) {
 		warnings.push({
 			nodeType: "image",
 			field: "borderRadius",
-			message: "Migrated \"borderRadius\" → individual corner radius properties"
+			message: "Migrated \"borderRadius\" → \"style\""
 		});
-		Object.assign(attrs, splitBorderRadius(attrs.borderRadius));
-		delete attrs.borderRadius;
+		declarations.borderRadius = getPixelValue(attrs.borderRadius);
 	}
-	const container = attrs._containerWidth ?? DEFAULT_CONTAINER_WIDTH$1;
+	delete attrs.borderRadius;
+	const containerWidth = attrs._containerWidth ?? DEFAULT_CONTAINER_WIDTH_PIXELS;
 	delete attrs._containerWidth;
 	if (attrs.width === "auto") attrs.width = "100%";
 	else if (typeof attrs.width === "number" || typeof attrs.width === "string" && !attrs.width.endsWith("%")) {
-		const px = Number(attrs.width);
-		if (!Number.isNaN(px) && px > 0) attrs.width = `${Math.min(MAX_IMAGE_WIDTH_PERCENTAGE, Math.max(MIN_IMAGE_WIDTH_PERCENTAGE, Math.round(px / container * 100)))}%`;
-	}
-	attrs.borderRadiusMode ??= "uniform";
-	attrs.borderWidthMode ??= "uniform";
-	attrs.borderStyle ??= "solid";
-	attrs.borderColor ??= "#000000";
-	attrs.borderTopWidth ??= 0;
-	attrs.borderRightWidth ??= 0;
-	attrs.borderBottomWidth ??= 0;
-	attrs.borderLeftWidth ??= 0;
-	for (const field of [
-		"height",
-		"isSrcVariable",
-		"isExternalLinkVariable",
-		"lockAspectRatio",
-		"aspectRatio"
-	]) if (field in attrs) {
+		const pixels = Number(attrs.width);
+		if (!Number.isNaN(pixels) && pixels > 0) attrs.width = `${getWidthPercentage({
+			containerWidth,
+			pixels
+		})}%`;
+	}
+	if (attrs.isSrcVariable === true) {
+		warnings.push({
+			nodeType: "image",
+			field: "isSrcVariable",
+			message: "Migrated \"isSrcVariable\" → variable reference in \"src\""
+		});
+		attrs.src = getVariableReference(attrs.src);
+	}
+	delete attrs.isSrcVariable;
+	if (attrs.isExternalLinkVariable === true && attrs.externalLink) {
+		warnings.push({
+			nodeType: "image",
+			field: "isExternalLinkVariable",
+			message: "Migrated \"isExternalLinkVariable\" → variable reference in \"externalLink\""
+		});
+		attrs.externalLink = getVariableReference(attrs.externalLink);
+	}
+	delete attrs.isExternalLinkVariable;
+	for (const field of DROPPED_IMAGE_ATTRS) if (field in attrs) {
 		warnings.push({
 			nodeType: "image",
 			field,
@@ -347,80 +438,118 @@ function image(node, warnings) {
 		});
 		delete attrs[field];
 	}
+	const style = getStyleAttribute({
+		...parseInlineStyles(attrs.style ?? ""),
+		...declarations
+	});
+	if (style) attrs.style = style;
 }
 //#endregion
 //#region src/transforms/inline-image.ts
-/**
-* Migrates a v1 inlineImage node to the v2 schema.
-* Performs the following conversions:
-*   - Converts `src: null` or `src: undefined` to an empty string,
-*     since v2 expects src to always be a string.
-*   - Drops deprecated flags: isSrcVariable, isExternalLinkVariable.
-*/
 function inlineImage(node, warnings) {
 	const attrs = node.attrs ?? {};
 	if (attrs.src == null) attrs.src = "";
-	for (const field of ["isSrcVariable", "isExternalLinkVariable"]) if (field in attrs) {
+	if (attrs.isSrcVariable === true) {
 		warnings.push({
 			nodeType: "inlineImage",
-			field,
-			message: `Attribute "${field}" is not supported in v2 and was dropped`
+			field: "isSrcVariable",
+			message: "Migrated \"isSrcVariable\" → variable reference in \"src\""
 		});
-		delete attrs[field];
+		attrs.src = getVariableReference(attrs.src);
 	}
+	delete attrs.isSrcVariable;
+	if (attrs.isExternalLinkVariable === true && attrs.externalLink) {
+		warnings.push({
+			nodeType: "inlineImage",
+			field: "isExternalLinkVariable",
+			message: "Migrated \"isExternalLinkVariable\" → variable reference in \"externalLink\""
+		});
+		attrs.externalLink = getVariableReference(attrs.externalLink);
+	}
+	delete attrs.isExternalLinkVariable;
 }
 //#endregion
 //#region src/transforms/link.ts
-/**
-* Migrates a v1 link mark to the v2 schema.
-* Removes the `isUrlVariable` flag from the mark attrs.
-* In v1, this boolean indicated whether the href was a variable
-* reference; v2 handles variable detection differently and no
-* longer needs this flag.
-*/
 function link(mark, warnings) {
 	const attrs = mark.attrs ?? {};
-	if ("isUrlVariable" in attrs) {
+	if (attrs.isUrlVariable === true) {
 		warnings.push({
 			nodeType: "link",
 			field: "isUrlVariable",
-			message: "Attribute \"isUrlVariable\" is not supported in v2 and was dropped"
+			message: "Migrated \"isUrlVariable\" → variable reference in \"href\""
 		});
-		delete attrs.isUrlVariable;
+		attrs.href = getVariableReference(attrs.href ?? "");
+	}
+	delete attrs.isUrlVariable;
+}
+//#endregion
+//#region src/transforms/link-card.ts
+function linkCard(node, warnings) {
+	const attrs = node.attrs ?? {};
+	if ("mailyComponent" in attrs) {
+		warnings.push({
+			nodeType: "linkCard",
+			field: "mailyComponent",
+			message: "v1 marker attribute \"mailyComponent\" is not needed in v2 and was dropped"
+		});
+		delete attrs.mailyComponent;
+	}
+}
+//#endregion
+//#region src/transforms/list-item.ts
+function listItem(node, warnings) {
+	const attrs = node.attrs ?? {};
+	if (attrs.color != null) {
+		const style = getStyleAttribute({ color: attrs.color });
+		if (style) {
+			warnings.push({
+				nodeType: "listItem",
+				field: "color",
+				message: "Migrated \"color\" → \"style\""
+			});
+			attrs.style = stringifyInlineStyles({
+				...parseInlineStyles(attrs.style ?? ""),
+				...parseInlineStyles(style)
+			});
+		}
 	}
+	delete attrs.color;
 }
 //#endregion
 //#region src/transforms/logo.ts
-const LOGO_SIZE_MAP = {
+const LOGO_SIZE_PIXELS = {
 	sm: 40,
 	md: 48,
 	lg: 64
 };
-const DEFAULT_CONTAINER_WIDTH = 600;
+const DEFAULT_LOGO_SIZE_PIXELS = 48;
 /**
 * Migrates a v1 logo node by converting it into a v2 image node.
 * The logo node type was removed in v2 — logos are now just images.
 * Performs the following conversions:
 *   - Changes `type: 'logo'` → `type: 'image'`.
-*   - Maps the `size` enum (sm/md/lg) to a numeric `width` string
-*     (40/48/64 pixels respectively).
+*   - Maps the `size` enum (sm/md/lg → 40/48/64 pixels) to a percentage
+*     `width`, scaled against the container width stamped by
+*     `annotateContainerWidths`.
 *   - Renames `alignment` → `align`.
-*   - Sets v2 image border defaults (all radii and widths to 0).
-*   - Drops deprecated `isSrcVariable` flag.
+*   - Resolves `isSrcVariable` into a variable reference inside `src`.
+*   - Drops the `maily-component` marker.
 */
 function logo(node, warnings) {
 	node.type = "image";
 	const attrs = node.attrs ?? {};
 	if ("size" in attrs) {
-		const px = LOGO_SIZE_MAP[attrs.size] ?? 48;
-		const container = attrs._containerWidth ?? DEFAULT_CONTAINER_WIDTH;
-		const percent = Math.min(MAX_IMAGE_WIDTH_PERCENTAGE, Math.max(MIN_IMAGE_WIDTH_PERCENTAGE, Math.round(px / container * 100)));
+		const pixels = LOGO_SIZE_PIXELS[attrs.size] ?? DEFAULT_LOGO_SIZE_PIXELS;
+		const percentage = getWidthPercentage({
+			containerWidth: attrs._containerWidth ?? DEFAULT_CONTAINER_WIDTH_PIXELS,
+			pixels
+		});
 		warnings.push({
 			nodeType: "logo",
 			field: "size",
-			message: `Migrated "size: ${attrs.size}" → "width: ${percent}%"`
+			message: `Migrated "size: ${attrs.size}" → "width: ${percentage}%"`
 		});
-		attrs.width = `${percent}%`;
+		attrs.width = `${percentage}%`;
 		delete attrs.size;
 	}
 	delete attrs._containerWidth;
@@ -433,37 +562,35 @@ function logo(node, warnings) {
 		attrs.align = attrs.alignment;
 		delete attrs.alignment;
 	}
-	attrs.borderRadiusMode ??= "uniform";
-	attrs.borderWidthMode ??= "uniform";
-	attrs.borderStyle ??= "solid";
-	attrs.borderColor ??= "#000000";
-	attrs.borderTopWidth ??= 0;
-	attrs.borderRightWidth ??= 0;
-	attrs.borderBottomWidth ??= 0;
-	attrs.borderLeftWidth ??= 0;
-	attrs.borderTopLeftRadius ??= 0;
-	attrs.borderTopRightRadius ??= 0;
-	attrs.borderBottomRightRadius ??= 0;
-	attrs.borderBottomLeftRadius ??= 0;
-	for (const field of ["isSrcVariable", "maily-component"]) if (field in attrs) {
+	if (attrs.isSrcVariable === true) {
 		warnings.push({
 			nodeType: "logo",
-			field,
-			message: `Attribute "${field}" is not supported in v2 and was dropped`
+			field: "isSrcVariable",
+			message: "Migrated \"isSrcVariable\" → variable reference in \"src\""
 		});
-		delete attrs[field];
+		attrs.src = getVariableReference(attrs.src);
+	}
+	delete attrs.isSrcVariable;
+	if ("maily-component" in attrs) {
+		warnings.push({
+			nodeType: "logo",
+			field: "maily-component",
+			message: "Attribute \"maily-component\" is not supported in v2 and was dropped"
+		});
+		delete attrs["maily-component"];
 	}
 }
 //#endregion
 //#region src/transforms/repeat.ts
-/**
-* Migrates a v1 repeat node to the v2 schema.
-* Wraps the `each` attribute value in Handlebars-style template syntax
-* if it isn't already wrapped. For example, `'items'` becomes `'{{items}}'`.
-* In v2, the each value must be a template expression; v1 allowed
-* bare variable names without delimiters.
-*/
 function repeat(node, warnings) {
+	if (node.type === "for") {
+		warnings.push({
+			nodeType: "for",
+			field: "type",
+			message: "Migrated deprecated \"for\" node → \"repeat\""
+		});
+		node.type = "repeat";
+	}
 	const attrs = node.attrs ?? {};
 	if (typeof attrs.each === "string" && attrs.each && !attrs.each.startsWith("{{")) {
 		warnings.push({
@@ -484,92 +611,92 @@ function repeat(node, warnings) {
 }
 //#endregion
 //#region src/transforms/section.ts
+const MARGIN_FIELDS = [
+	"marginTop",
+	"marginRight",
+	"marginBottom",
+	"marginLeft"
+];
 /**
 * Migrates a v1 section node to the v2 schema.
-* Performs the following conversions:
-*   - Splits the single `borderRadius` number into four corner properties.
-*   - Splits the single `borderWidth` number into four side properties.
-*   - Sets v2 mode defaults: borderRadiusMode/borderWidthMode "uniform",
-*     paddingMode "uniform", marginMode "mixed", borderStyle "solid".
+* v1 stored its look as separate attributes and rendered them verbatim, so
+* every one of them becomes an explicit declaration in `style`:
+*   - backgroundColor, borderWidth/borderColor and borderRadius.
+*   - paddingTop/Right/Bottom/Left and marginTop/Right/Bottom/Left, zeros
+*     included, because the v2 section theme otherwise adds 8px of padding.
+*   - align → text-align, unless it is the v1 default "left".
 */
 function section(node, warnings) {
 	const attrs = node.attrs ?? {};
-	if (typeof attrs.borderRadius === "number") {
+	const declarations = {
+		...parseInlineStyles(attrs.style ?? ""),
+		...getBoxStyleDeclarations({
+			attrs,
+			nodeType: "section",
+			warnings
+		})
+	};
+	const margin = getBoxDeclarations({
+		bottom: attrs.marginBottom,
+		left: attrs.marginLeft,
+		property: "margin",
+		right: attrs.marginRight,
+		top: attrs.marginTop
+	});
+	if (Object.keys(margin).length > 0) {
 		warnings.push({
 			nodeType: "section",
-			field: "borderRadius",
-			message: "Migrated \"borderRadius\" → individual corner radius properties"
+			field: "margin",
+			message: "Migrated \"margin*\" → \"style\""
 		});
-		Object.assign(attrs, splitBorderRadius(attrs.borderRadius));
-		delete attrs.borderRadius;
+		Object.assign(declarations, margin);
 	}
-	if (typeof attrs.borderWidth === "number") {
+	for (const field of MARGIN_FIELDS) delete attrs[field];
+	if (attrs.align && attrs.align !== "left") {
 		warnings.push({
 			nodeType: "section",
-			field: "borderWidth",
-			message: "Migrated \"borderWidth\" → individual side width properties"
-		});
-		Object.assign(attrs, splitBorderWidth(attrs.borderWidth));
-		delete attrs.borderWidth;
-	}
-	attrs.borderRadiusMode ??= "uniform";
-	attrs.borderWidthMode ??= "uniform";
-	attrs.paddingMode ??= "uniform";
-	attrs.marginMode ??= "mixed";
-	attrs.borderStyle ??= "solid";
-	attrs.borderColor ??= "#000000";
+			field: "align",
+			message: "Migrated \"align\" → \"style\""
+		});
+		declarations.textAlign = attrs.align;
+	}
+	delete attrs.align;
+	const style = getStyleAttribute(declarations);
+	if (style) attrs.style = style;
 }
 //#endregion
 //#region src/transforms/spacer.ts
 const DEFAULT_SPACER_HEIGHT = 8;
-const SPACING = [
-	{
-		name: "Extra Small",
-		short: "xs",
-		value: 4
-	},
-	{
-		name: "Small",
-		short: "sm",
-		value: 8
-	},
-	{
-		name: "Medium",
-		short: "md",
-		value: 16
-	},
-	{
-		name: "Large",
-		short: "lg",
-		value: 32
-	},
-	{
-		name: "Extra Large",
-		short: "xl",
-		value: 64
-	}
-];
-const ALLOWED_SPACING_SHORT_NAMES = SPACING.map((s) => s.short);
-/**
-* Migrates a v1 spacer node to the v2 schema.
-* Sets `heightMode` to "uniform" if not already present.
-* In v2, spacers support per-side height control via heightMode;
-* v1 spacers only had a single uniform height value.
-*/
+const SPACER_ENUM_HEIGHTS = {
+	xs: 4,
+	sm: 8,
+	md: 16,
+	lg: 32,
+	xl: 64
+};
 function spacer(node, warnings) {
 	const attrs = node.attrs ?? {};
-	let height = node.attrs?.height;
-	if (typeof height === "string" && ALLOWED_SPACING_SHORT_NAMES.includes(height)) {
-		const spacing = SPACING.find((s) => s.short === height);
+	const height = attrs.height;
+	if (typeof height === "number") return;
+	if (typeof height === "string" && height in SPACER_ENUM_HEIGHTS) {
+		const value = SPACER_ENUM_HEIGHTS[height];
 		warnings.push({
 			nodeType: "spacer",
 			field: "height",
-			message: `Migrated "height" from string enum to number: ${height} → ${spacing?.value}`
+			message: `Migrated "height" from string enum to number: ${height} → ${value}`
 		});
-		height = spacing?.value ?? DEFAULT_SPACER_HEIGHT;
+		attrs.height = value;
+		return;
 	}
-	attrs.height = height;
-	attrs.heightMode ??= "uniform";
+	attrs.height = DEFAULT_SPACER_HEIGHT;
+}
+//#endregion
+//#region src/transforms/variable.ts
+function variable(node) {
+	const attrs = node.attrs;
+	if (!attrs || !("hideDefaultValue" in attrs)) return;
+	attrs.isDefaultEditable = attrs.hideDefaultValue !== true;
+	delete attrs.hideDefaultValue;
 }
 //#endregion
 //#region src/utils/container-width.ts
@@ -628,8 +755,10 @@ function annotateContainerWidths(node, availableWidth = ROOT_WIDTH) {
 			const col = columns[i];
 			const colPercent = parseColumnWidth(col.attrs?.width) ?? autoPercent;
 			let gapDeduction = 0;
-			if (columnCount > 1) if (i === 0 || i === columnCount - 1) gapDeduction = gap / 2;
-			else gapDeduction = gap;
+			if (columnCount > 1) {
+				if (i === 0 || i === columnCount - 1) gapDeduction = gap / 2;
+				else gapDeduction = gap;
+			}
 			const colWidth = childWidth * (colPercent / 100) - gapDeduction;
 			annotateContainerWidths(col, Math.max(0, colWidth));
 		}
@@ -641,7 +770,6 @@ function annotateContainerWidths(node, availableWidth = ROOT_WIDTH) {
 //#region src/migrate.ts
 const NODE_TRANSFORMS = {
 	button,
-	htmlCodeBlock,
 	image,
 	logo,
 	section,
@@ -649,8 +777,12 @@ const NODE_TRANSFORMS = {
 	column,
 	spacer,
 	repeat,
+	for: repeat,
 	footer,
-	inlineImage
+	inlineImage,
+	linkCard,
+	listItem,
+	variable
 };
 const MARK_TRANSFORMS = { link };
 /**
@@ -666,9 +798,9 @@ function requireContentMigration(json) {
 * Converts a Maily v1 JSON document to the v2 schema.
 * Deep-clones the input so the original is never mutated, then
 * walks the tree iteratively (stack-based) applying global transforms
-* (showIfKey → visibilityRule, textDirection → dir, id generation)
-* followed by node-specific transforms (button, image, section, etc.)
-* and mark transforms (link).
+* (showIfKey → visibilityRule, textDirection → dir, textAlign → style,
+* id generation) followed by node-specific transforms (button, image,
+* section, etc.) and mark transforms (link).
 *
 * If the document is already v2+ (version >= 2), it is returned as-is
 * with an empty warnings array. Warnings are emitted when v1 attributes