@maily-to/migration 2.0.0-beta.1

package/dist/index.cjs

@@ -0,0 +1,709 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _maily_to_shared = require("@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
+	};
+}
+/**
+* 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
+	};
+}
+//#endregion
+//#region src/transforms/button.ts
+const BORDER_RADIUS_MAP = {
+	sharp: 0,
+	smooth: 6,
+	round: 9999
+};
+/**
+* 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.
+*/
+function button(node, warnings) {
+	const attrs = node.attrs ?? {};
+	if (!node.content) {
+		const text = attrs.text ?? "";
+		if (attrs.isTextVariable && text) node.content = [{
+			type: "variable",
+			attrs: { id: text }
+		}];
+		else if (text) node.content = [{
+			type: "text",
+			text
+		}];
+	}
+	if ("text" in attrs) {
+		warnings.push({
+			nodeType: "button",
+			field: "text",
+			message: "Migrated \"text\" → inline content node"
+		});
+		delete attrs.text;
+	}
+	if ("isTextVariable" in attrs) {
+		warnings.push({
+			nodeType: "button",
+			field: "isTextVariable",
+			message: "Migrated \"isTextVariable\" → variable content node"
+		});
+		delete attrs.isTextVariable;
+	}
+	if ("buttonColor" in attrs) {
+		warnings.push({
+			nodeType: "button",
+			field: "buttonColor",
+			message: "Migrated \"buttonColor\" → \"backgroundColor\""
+		});
+		attrs.backgroundColor = attrs.buttonColor;
+		delete attrs.buttonColor;
+	}
+	if ("textColor" in attrs) {
+		warnings.push({
+			nodeType: "button",
+			field: "textColor",
+			message: "Migrated \"textColor\" → \"color\""
+		});
+		attrs.color = attrs.textColor;
+		delete attrs.textColor;
+	}
+	if (attrs.variant === "outline") {
+		warnings.push({
+			nodeType: "button",
+			field: "variant",
+			message: "Migrated \"variant: outline\" → transparent backgroundColor + border properties"
+		});
+		attrs.borderColor = attrs.backgroundColor ?? "#000000";
+		attrs.borderTopWidth = 2;
+		attrs.borderRightWidth = 2;
+		attrs.borderBottomWidth = 2;
+		attrs.borderLeftWidth = 2;
+		attrs.backgroundColor = "transparent";
+	}
+	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"
+		});
+		delete attrs.isUrlVariable;
+	}
+}
+//#endregion
+//#region src/transforms/column.ts
+const DROPPED_COLUMN_ATTRS = [
+	"columnId",
+	"backgroundColor",
+	"borderRadius",
+	"borderWidth",
+	"borderColor",
+	"paddingTop",
+	"paddingRight",
+	"paddingBottom",
+	"paddingLeft",
+	"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.
+*/
+function column(node, warnings) {
+	const attrs = node.attrs ?? {};
+	if (attrs.width === "auto") attrs.width = null;
+	else if (typeof attrs.width === "string") {
+		const parsed = parseFloat(attrs.width);
+		attrs.width = Number.isNaN(parsed) ? null : parsed;
+	}
+	for (const field of DROPPED_COLUMN_ATTRS) if (field in attrs && attrs[field] != null) {
+		warnings.push({
+			nodeType: "column",
+			field,
+			message: `Column attribute "${field}" is not supported in v2 and was dropped`
+		});
+		delete attrs[field];
+	}
+}
+//#endregion
+//#region src/transforms/columns.ts
+/**
+* Migrates a v1 columns node to the v2 schema.
+* In v2, columns tracks its child count and gap explicitly:
+*   - Sets `columnCount` to the number of column children in `content`.
+*   - Sets `gap` to the default value of 8 if not already present.
+*/
+function columns(node, _warnings) {
+	const attrs = node.attrs ?? {};
+	attrs.columnCount ??= node.content?.length ?? 0;
+	attrs.gap ??= 8;
+}
+//#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) {
+		warnings.push({
+			nodeType: "footer",
+			field: "maily-component",
+			message: "v1 marker attribute \"maily-component\" is not needed in v2 and was dropped"
+		});
+		delete attrs["maily-component"];
+	}
+}
+//#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.
+*/
+function global(node, warnings) {
+	if (node.type === "text") return;
+	if (!node.attrs) node.attrs = {};
+	const attrs = node.attrs;
+	if (attrs.showIfKey) {
+		warnings.push({
+			nodeType: node.type,
+			field: "showIfKey",
+			message: "Migrated \"showIfKey\" → \"visibilityRule\""
+		});
+		attrs.visibilityRule = {
+			action: "show",
+			variable: attrs.showIfKey,
+			operator: "is_true",
+			value: ""
+		};
+	}
+	delete attrs.showIfKey;
+	if ("textDirection" in attrs) {
+		if (attrs.textDirection) {
+			warnings.push({
+				nodeType: node.type,
+				field: "textDirection",
+				message: "Migrated \"textDirection\" → \"dir\""
+			});
+			attrs.dir = attrs.textDirection;
+		}
+		delete attrs.textDirection;
+	}
+	if (node.type !== "doc" && !attrs.id) attrs.id = uid();
+}
+//#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;
+	}
+}
+//#endregion
+//#region src/transforms/image.ts
+const DEFAULT_CONTAINER_WIDTH$1 = 600;
+/**
+* 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.
+*/
+function image(node, warnings) {
+	const attrs = node.attrs ?? {};
+	if ("alignment" in attrs) {
+		warnings.push({
+			nodeType: "image",
+			field: "alignment",
+			message: "Migrated \"alignment\" → \"align\""
+		});
+		attrs.align = attrs.alignment;
+		delete attrs.alignment;
+	}
+	if (typeof attrs.borderRadius === "number") {
+		warnings.push({
+			nodeType: "image",
+			field: "borderRadius",
+			message: "Migrated \"borderRadius\" → individual corner radius properties"
+		});
+		Object.assign(attrs, splitBorderRadius(attrs.borderRadius));
+		delete attrs.borderRadius;
+	}
+	const container = attrs._containerWidth ?? DEFAULT_CONTAINER_WIDTH$1;
+	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(_maily_to_shared.MAX_IMAGE_WIDTH_PERCENTAGE, Math.max(_maily_to_shared.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) {
+		warnings.push({
+			nodeType: "image",
+			field,
+			message: `Attribute "${field}" is not supported in v2 and was dropped`
+		});
+		delete attrs[field];
+	}
+}
+//#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) {
+		warnings.push({
+			nodeType: "inlineImage",
+			field,
+			message: `Attribute "${field}" is not supported in v2 and was dropped`
+		});
+		delete attrs[field];
+	}
+}
+//#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) {
+		warnings.push({
+			nodeType: "link",
+			field: "isUrlVariable",
+			message: "Attribute \"isUrlVariable\" is not supported in v2 and was dropped"
+		});
+		delete attrs.isUrlVariable;
+	}
+}
+//#endregion
+//#region src/transforms/logo.ts
+const LOGO_SIZE_MAP = {
+	sm: 40,
+	md: 48,
+	lg: 64
+};
+const DEFAULT_CONTAINER_WIDTH = 600;
+/**
+* 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).
+*   - Renames `alignment` → `align`.
+*   - Sets v2 image border defaults (all radii and widths to 0).
+*   - Drops deprecated `isSrcVariable` flag.
+*/
+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(_maily_to_shared.MAX_IMAGE_WIDTH_PERCENTAGE, Math.max(_maily_to_shared.MIN_IMAGE_WIDTH_PERCENTAGE, Math.round(px / container * 100)));
+		warnings.push({
+			nodeType: "logo",
+			field: "size",
+			message: `Migrated "size: ${attrs.size}" → "width: ${percent}%"`
+		});
+		attrs.width = `${percent}%`;
+		delete attrs.size;
+	}
+	delete attrs._containerWidth;
+	if ("alignment" in attrs) {
+		warnings.push({
+			nodeType: "logo",
+			field: "alignment",
+			message: "Migrated \"alignment\" → \"align\""
+		});
+		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) {
+		warnings.push({
+			nodeType: "logo",
+			field,
+			message: `Attribute "${field}" is not supported in v2 and was dropped`
+		});
+		delete attrs[field];
+	}
+}
+//#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) {
+	const attrs = node.attrs ?? {};
+	if (typeof attrs.each === "string" && attrs.each && !attrs.each.startsWith("{{")) {
+		warnings.push({
+			nodeType: "repeat",
+			field: "each",
+			message: `Migrated "each: ${attrs.each}" → "each: {{${attrs.each}}}"`
+		});
+		attrs.each = `{{${attrs.each}}}`;
+	}
+	if ("isUpdatingKey" in attrs) {
+		warnings.push({
+			nodeType: "repeat",
+			field: "isUpdatingKey",
+			message: "Editor-only attribute \"isUpdatingKey\" is not supported in v2 and was dropped"
+		});
+		delete attrs.isUpdatingKey;
+	}
+}
+//#endregion
+//#region src/transforms/section.ts
+/**
+* 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".
+*/
+function section(node, warnings) {
+	const attrs = node.attrs ?? {};
+	if (typeof attrs.borderRadius === "number") {
+		warnings.push({
+			nodeType: "section",
+			field: "borderRadius",
+			message: "Migrated \"borderRadius\" → individual corner radius properties"
+		});
+		Object.assign(attrs, splitBorderRadius(attrs.borderRadius));
+		delete attrs.borderRadius;
+	}
+	if (typeof attrs.borderWidth === "number") {
+		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";
+}
+//#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.
+*/
+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);
+		warnings.push({
+			nodeType: "spacer",
+			field: "height",
+			message: `Migrated "height" from string enum to number: ${height} → ${spacing?.value}`
+		});
+		height = spacing?.value ?? DEFAULT_SPACER_HEIGHT;
+	}
+	attrs.height = height;
+	attrs.heightMode ??= "uniform";
+}
+//#endregion
+//#region src/utils/container-width.ts
+const ROOT_WIDTH = 600;
+const DEFAULT_COLUMNS_GAP = 8;
+/**
+* Parses a v1 column width attribute.
+* Returns the numeric percentage, or `null` for "auto" / unparseable values.
+*/
+function parseColumnWidth(width) {
+	if (typeof width === "string") {
+		if (width === "auto") return null;
+		const parsed = parseFloat(width);
+		return Number.isNaN(parsed) ? null : parsed;
+	}
+	if (typeof width === "number") return width;
+	return null;
+}
+/**
+* Recursively walks a v1 document tree and stamps `_containerWidth` on every
+* `image` and `logo` node. The value reflects the available content width at
+* that position in the tree, accounting for section padding/border and column
+* percentage widths + gap.
+*
+* Must run **before** the transform walker so the transforms can read
+* `_containerWidth` and convert pixel sizes to accurate percentages.
+*/
+function annotateContainerWidths(node, availableWidth = ROOT_WIDTH) {
+	if (!node) return;
+	const attrs = node.attrs ?? {};
+	if (node.type === "image" || node.type === "logo") {
+		if (!node.attrs) node.attrs = {};
+		node.attrs._containerWidth = availableWidth;
+	}
+	let childWidth = availableWidth;
+	if (node.type === "section") {
+		const paddingLeft = typeof attrs.paddingLeft === "number" ? attrs.paddingLeft : 0;
+		const paddingRight = typeof attrs.paddingRight === "number" ? attrs.paddingRight : 0;
+		const borderWidth = typeof attrs.borderWidth === "number" ? attrs.borderWidth : 0;
+		childWidth = availableWidth - paddingLeft - paddingRight - borderWidth * 2;
+	}
+	if (node.type === "columns" && Array.isArray(node.content)) {
+		const gap = typeof attrs.gap === "number" ? attrs.gap : DEFAULT_COLUMNS_GAP;
+		const columns = node.content;
+		const columnCount = columns.length;
+		let claimedPercent = 0;
+		let autoCount = 0;
+		for (const col of columns) {
+			const colWidth = parseColumnWidth(col.attrs?.width);
+			if (colWidth !== null) claimedPercent += colWidth;
+			else autoCount++;
+		}
+		const remainingPercent = Math.max(0, 100 - claimedPercent);
+		const autoPercent = autoCount > 0 ? remainingPercent / autoCount : 0;
+		for (let i = 0; i < columns.length; i++) {
+			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;
+			const colWidth = childWidth * (colPercent / 100) - gapDeduction;
+			annotateContainerWidths(col, Math.max(0, colWidth));
+		}
+		return;
+	}
+	if (Array.isArray(node.content)) for (const child of node.content) annotateContainerWidths(child, childWidth);
+}
+//#endregion
+//#region src/migrate.ts
+const NODE_TRANSFORMS = {
+	button,
+	htmlCodeBlock,
+	image,
+	logo,
+	section,
+	columns,
+	column,
+	spacer,
+	repeat,
+	footer,
+	inlineImage
+};
+const MARK_TRANSFORMS = { link };
+/**
+* Checks whether a Maily JSON document needs migration.
+* Returns `true` when the document has no `version` attribute
+* or when `version` is less than 2, indicating it is a v1 document
+* that should be passed through `migrate` before use.
+*/
+function requireContentMigration(json) {
+	return !(json.attrs?.version >= 2);
+}
+/**
+* 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).
+*
+* If the document is already v2+ (version >= 2), it is returned as-is
+* with an empty warnings array. Warnings are emitted when v1 attributes
+* are dropped without a v2 equivalent (e.g. column styling attributes).
+*/
+function migrate(json) {
+	if (!requireContentMigration(json)) return {
+		json,
+		warnings: []
+	};
+	const doc = structuredClone(json);
+	const warnings = [];
+	if (!doc.attrs) doc.attrs = {};
+	doc.attrs.version = 2;
+	annotateContainerWidths(doc);
+	const stack = [doc];
+	while (stack.length > 0) {
+		const node = stack.pop();
+		global(node, warnings);
+		const transform = NODE_TRANSFORMS[node.type];
+		if (transform) transform(node, warnings);
+		if (Array.isArray(node.marks)) for (const mark of node.marks) {
+			const markTransform = MARK_TRANSFORMS[mark.type];
+			if (markTransform) markTransform(mark, warnings);
+		}
+		if (Array.isArray(node.content)) for (let i = node.content.length - 1; i >= 0; i--) stack.push(node.content[i]);
+	}
+	return {
+		json: doc,
+		warnings
+	};
+}
+//#endregion
+exports.migrate = migrate;
+exports.requireContentMigration = requireContentMigration;
+
+//# sourceMappingURL=index.cjs.map