@mrhenry/prettier-twig 0.1.0

package/src/printer.js

@@ -0,0 +1,1145 @@
+// @ts-check
+/**
+ * The Prettier doc printer for the hybrid HTML+Twig AST.
+ *
+ * Style rules (deduced from the sample themes):
+ *  - tabs for indentation, one level per HTML/twig nesting;
+ *  - elements with a single attribute stay on one line, elements with several
+ *    attributes (or conditional attributes) go multi-line with one attribute
+ *    per line and the closing `>` on its own line at the opening `<` indent;
+ *  - twig blocks indent their bodies;
+ *  - twig spans are printed verbatim from their raw source;
+ *  - text content layout (inline vs expanded) is preserved from the source;
+ *  - blank lines between siblings are preserved.
+ *
+ * The printer descends through Prettier's `print` callback (via `path.call`
+ * and `print(selector)`), so Prettier can map original source offsets onto the
+ * printed output. That is what makes range formatting and `cursorOffset`
+ * tracking accurate; every AST node carries exact `rawStart`/`rawEnd` offsets.
+ *
+ * @module prettier-twig
+ */
+import { doc } from 'prettier';
+
+const { group, indent, align, line, softline, hardline, join, ifBreak } = doc.builders;
+
+/**
+ * Prints a container's children: one per line at the container's indent,
+ * preserving blank lines between siblings.
+ *
+ * @param {any} path
+ * @param {(selector: any, ...rest: any[]) => any} printCallback
+ * @param {string} source
+ * @param {boolean} [leadingHardline]
+ * @param {any} [options]
+ * @returns {any[]} Prettier docs.
+ */
+function printChildren(path, printCallback, source, leadingHardline = true, options = {}) {
+	const node = path.node;
+	const children = node.children ?? [];
+	/** @type {any[]} */
+	let docs = [];
+	// blank-line detection measures the source between the end of the previous
+	// non-whitespace sibling (or the container's opening) and the current one
+	let previousEnd = node.startTagEnd ?? node.rawStart;
+	let previousWasInline = false;
+	let first = true;
+	let danglingAt;
+	let danglingIndent = '';
+	for (let i = 0; i < children.length; i += 1) {
+		const child = children[i];
+		const isWs = isWhitespaceOnly(child);
+		const { start, end } = contentBounds(child);
+		const blankBefore = hasBlankLine(source, previousEnd, start);
+		const gap = source.slice(previousEnd, start);
+		if (isWs) {
+			continue;
+		}
+		previousEnd = end;
+		const childDoc = path.call(printCallback, 'children', i);
+		const inline = isInlineChild(child);
+		if (node.type === 'root' && danglingAt === undefined && child.type === 'text') {
+			const indent2 = danglingEndIndent(child.raw);
+			if (indent2 !== null) {
+				danglingAt = docs.length;
+				danglingIndent = indent2;
+			}
+		}
+		if (first && !leadingHardline) {
+			// the document must not start with a blank line
+			docs.push(childDoc);
+		} else if (blankBefore) {
+			docs.push([hardline, hardline, childDoc]);
+		} else if (!gap.includes('\n') && previousWasInline && inline) {
+			// consecutive inline expressions on one source line stay together
+			docs.push([gap === '' ? '' : ' ', childDoc]);
+		} else {
+			docs.push([hardline, childDoc]);
+		}
+		previousWasInline = inline;
+		first = false;
+	}
+	if (danglingAt !== undefined && danglingAt > 0) {
+		// Content that precedes a dangling end tag belongs inside the element
+		// that tag closes, so it sits one level below the tag's own indent.
+		const unit = options.useTabs === false ? ' '.repeat(options.tabWidth ?? 4) : '\t';
+		const prefix = danglingIndent + unit;
+		const head = docs.slice(0, danglingAt);
+		const tail = docs.slice(danglingAt);
+		docs = leadingHardline ? [align(prefix, head), ...tail] : [prefix, align(prefix, head), ...tail];
+	}
+	return docs;
+}
+
+/**
+ * The leading whitespace of the first dangling end tag in a text node, or
+ * `null` when the text holds no end tag.
+ *
+ * @param {string} raw
+ * @returns {string | null}
+ */
+function danglingEndIndent(raw) {
+	for (const rawLine of raw.split(/\r?\n/)) {
+		const match = rawLine.match(/^([ \t]*)<\//);
+		if (match) {
+			return match[1];
+		}
+	}
+	return null;
+}
+
+/**
+ * Whether a node is inline content (a `{{ … }}` expression or text) that may
+ * share a line with adjacent content when the source has no line break between
+ * them.
+ *
+ * @param {any} node
+ * @returns {boolean}
+ */
+function isInlineChild(node) {
+	if (node.type === 'text') {
+		return node.raw.trim() !== '';
+	}
+	if (node.type === 'twig') {
+		return Boolean(node.atom.isPrint);
+	}
+	return node.type === 'element' && INLINE_ELEMENTS.has(node.name);
+}
+
+/** Phrasing (inline) elements that may share a line with neighbouring text. */
+const INLINE_ELEMENTS = new Set([
+	'a', 'abbr', 'b', 'bdi', 'bdo', 'br', 'cite', 'code', 'data', 'dfn', 'em',
+	'i', 'img', 'kbd', 'mark', 'q', 'rp', 'rt', 'ruby', 's', 'samp', 'small',
+	'span', 'strong', 'sub', 'sup', 'time', 'u', 'var', 'wbr',
+]);
+
+/**
+ * @param {any} node
+ * @returns {boolean} Whether the node is whitespace-only text.
+ */
+function isWhitespaceOnly(node) {
+	return node.type === 'text' && node.raw.trim() === '';
+}
+
+/**
+ * The bounds of a node's own content. Comments carry their leading whitespace
+ * in `rawStart`/`rawEnd`, so the atom's offsets are used when present to avoid
+ * treating that trivia as part of the gap between siblings.
+ *
+ * @param {any} node
+ * @returns {{start: number, end: number}}
+ */
+function contentBounds(node) {
+	// A twig block's raw span may start before its `{%` when the previous tag
+	// trimmed whitespace; use the open/close atoms so the trimmed gap stays
+	// visible to blank-line detection.
+	if (node.type === 'twigBlock' && node.open && node.close) {
+		return {
+			start: node.open.atom.rawStart ?? node.rawStart,
+			end: node.close.atom.rawEnd ?? node.rawEnd,
+		};
+	}
+	if (node.type === 'text') {
+		const raw = node.raw;
+		const leading = raw.length - raw.trimStart().length;
+		const trailing = raw.length - raw.trimEnd().length;
+		return { start: node.rawStart + leading, end: node.rawEnd - trailing };
+	}
+	const atom = node.atom;
+	return {
+		start: atom?.rawStart ?? node.rawStart,
+		end: atom?.rawEnd ?? node.rawEnd,
+	};
+}
+
+/**
+ * @param {string} source
+ * @param {number} from
+ * @param {number} to
+ * @returns {boolean} Whether the source between `from` and `to` contains a
+ *   blank line (two or more newlines).
+ */
+function hasBlankLine(source, from, to) {
+	const between = source.slice(Math.max(0, from), Math.max(0, to));
+	const count = (between.match(/\n/g) ?? []).length;
+	return count >= 2;
+}
+
+/**
+ * Collapses runs of whitespace in a twig construct's body to single spaces,
+ * leaving the contents of string literals untouched.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function collapseWhitespace(text) {
+	let out = '';
+	let quote = '';
+	let pendingSpace = false;
+	for (let i = 0; i < text.length; i += 1) {
+		const ch = text[i];
+		if (quote !== '') {
+			out += ch;
+			if (ch === '\\') {
+				out += text[i + 1] ?? '';
+				i += 1;
+			} else if (ch === quote) {
+				quote = '';
+			}
+			continue;
+		}
+		if (ch === '"' || ch === "'") {
+			if (pendingSpace && out !== '') {
+				out += ' ';
+			}
+			pendingSpace = false;
+			quote = ch;
+			out += ch;
+			continue;
+		}
+		if (/\s/.test(ch)) {
+			pendingSpace = true;
+			continue;
+		}
+		const previous = out[out.length - 1] ?? '';
+		if (pendingSpace && out !== '' && !'([{'.includes(previous) && !')]},'.includes(ch)) {
+			out += ' ';
+		}
+		pendingSpace = false;
+		out += ch;
+	}
+	return out;
+}
+
+/**
+ * Splits a `{% … %}` / `{{ … }}` construct into its delimiters (including any
+ * whitespace-trim markers) and its body.
+ *
+ * @param {string} raw
+ * @returns {{open: string, close: string, body: string}}
+ */
+function twigDelimiters(raw) {
+	let open = '{%';
+	if (raw.startsWith('{%-')) {
+		open = '{%-';
+	} else if (raw.startsWith('{%~')) {
+		open = '{%~';
+	} else if (raw.startsWith('{{-')) {
+		open = '{{-';
+	} else if (raw.startsWith('{{~')) {
+		open = '{{~';
+	} else if (raw.startsWith('{{')) {
+		open = '{{';
+	}
+	let close = '%}';
+	if (raw.endsWith('-%}')) {
+		close = '-%}';
+	} else if (raw.endsWith('~%}')) {
+		close = '~%}';
+	} else if (raw.endsWith('-}}')) {
+		close = '-}}';
+	} else if (raw.endsWith('~}}')) {
+		close = '~}}';
+	} else if (raw.endsWith('}}')) {
+		close = '}}';
+	}
+	return { open, close, body: raw.slice(open.length, raw.length - close.length) };
+}
+
+/**
+ * Normalizes a `{% … %}` / `{{ … }}` construct to a single line: the opening
+ * and closing delimiters (including whitespace-trim markers) are preserved and
+ * the body's whitespace is collapsed.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeTwigTag(raw) {
+	const { open, close, body } = twigDelimiters(raw);
+	const normalized = collapseWhitespace(body).trim();
+	return normalized === '' ? `${open}${close}` : `${open} ${normalized} ${close}`;
+}
+
+/**
+ * Whether a mapping/sequence was written multi-line in the source (a newline
+ * between the opening delimiter and the first entry). Such containers stay
+ * expanded even when they would fit on one line, mirroring Prettier.
+ *
+ * @param {string} text The container including its delimiters.
+ * @returns {boolean}
+ */
+function isMultilineContainer(text) {
+	return new RegExp(`^\\${text[0]}[\\t ]*\\r?\\n`).test(text);
+}
+
+/**
+ * Collects, in pre-order, whether each `{ … }` / `[ … ]` container of `text`
+ * was multi-line in the source. They are consumed in the same order while
+ * formatting.
+ *
+ * @param {string} text
+ * @returns {boolean[]}
+ */
+function collectMultilineStructures(text) {
+	/** @type {boolean[]} */
+	const result = [];
+	let quote = '';
+	let i = 0;
+	while (i < text.length) {
+		const ch = text[i];
+		if (quote !== '') {
+			if (ch === '\\') {
+				i += 2;
+				continue;
+			}
+			if (ch === quote) {
+				quote = '';
+			}
+			i += 1;
+			continue;
+		}
+		if (ch === '"' || ch === "'") {
+			quote = ch;
+			i += 1;
+			continue;
+		}
+		if (ch === '{' || ch === '[') {
+			const close = findMatchingBrace(text, i);
+			if (close !== -1) {
+				result.push(isMultilineContainer(text.slice(i, close + 1)));
+				result.push(...collectMultilineStructures(text.slice(i + 1, close)));
+				i = close + 1;
+				continue;
+			}
+		}
+		i += 1;
+	}
+	return result;
+}
+
+/**
+ * Formats the mapping/sequence literals in a twig construct body. Each `{ … }`
+ * / `[ … ]` becomes a Prettier group: it stays on one line when it fits,
+ * otherwise one entry per line with a trailing comma. Containers that were
+ * multi-line in the source are kept expanded.
+ *
+ * @param {string} text The already whitespace-normalized body.
+ * @param {boolean} forceBreak Whether every container must expand.
+ * @param {boolean[]} [multiline] Queue of source multi-line flags, in order.
+ * @param {boolean} [trailingComma] Whether expanded containers get a trailing comma.
+ * @returns {any} A Prettier doc.
+ */
+function formatStructures(text, forceBreak, multiline = [], trailingComma = true) {
+	/** @type {any[]} */
+	const docs = [];
+	let quote = '';
+	let start = 0;
+	let i = 0;
+	while (i < text.length) {
+		const ch = text[i];
+		if (quote !== '') {
+			if (ch === '\\') {
+				i += 2;
+				continue;
+			}
+			if (ch === quote) {
+				quote = '';
+			}
+			i += 1;
+			continue;
+		}
+		if (ch === '"' || ch === "'") {
+			quote = ch;
+			i += 1;
+			continue;
+		}
+		if (ch === '{' || ch === '[') {
+			const close = findMatchingBrace(text, i);
+			if (close !== -1) {
+				if (i > start) {
+					docs.push(text.slice(start, i));
+				}
+				const sourceMultiline = multiline.shift() ?? false;
+				docs.push(
+					formatContainer(text.slice(i, close + 1), forceBreak || sourceMultiline, multiline, trailingComma),
+				);
+				i = close + 1;
+				start = i;
+				continue;
+			}
+		}
+		i += 1;
+	}
+	if (start < text.length) {
+		docs.push(text.slice(start));
+	}
+	return docs.length === 0 ? '' : docs;
+}
+
+/**
+ * @param {string} text A single `{ … }` mapping or `[ … ]` sequence.
+ * @param {boolean} forceBreak Whether the container must expand.
+ * @param {boolean[]} [multiline] Queue of source multi-line flags, in order.
+ * @param {boolean} [trailingComma] Whether an expanded container gets a trailing comma.
+ * @returns {any} A Prettier doc.
+ */
+function formatContainer(text, forceBreak, multiline = [], trailingComma = true) {
+	const open = text[0];
+	const close = open === '{' ? '}' : ']';
+	const entries = splitTopLevel(text.slice(1, -1));
+	if (entries.length === 0) {
+		return `${open}${close}`;
+	}
+	const parts = entries.map((entry) => formatStructures(entry, false, multiline, trailingComma));
+	const trailing = trailingComma ? ifBreak(',') : '';
+	// mappings get inner spaces (`{ a: 1 }`), sequences do not (`[1, 2]`)
+	const edge = open === '{' ? line : softline;
+	return group(
+		[open, indent([edge, join([',', line], parts), trailing]), edge, close],
+		{ shouldBreak: forceBreak },
+	);
+}
+
+/**
+ * Formats a `{% … %}` / `{{ … }}` construct: delimiters and whitespace are
+ * normalized and mappings/sequences are laid out by Prettier.
+ *
+ * @param {string} raw
+ * @param {boolean} [forceBreakStructures]
+ * @param {boolean} [trailingComma] Whether expanded containers get a trailing comma.
+ * @returns {any} A Prettier doc.
+ */
+function formatTwigTag(raw, forceBreakStructures = false, trailingComma = true) {
+	const { open, close, body } = twigDelimiters(raw);
+	const normalized = collapseWhitespace(body).trim();
+	if (normalized === '') {
+		return `${open}${close}`;
+	}
+	const multiline = collectMultilineStructures(body);
+	return [open, ' ', formatStructures(normalized, forceBreakStructures, multiline, trailingComma), ' ', close];
+}
+
+/**
+ * Prints an element's start tag.
+ *
+ * @param {any} node
+ * @param {any[]} attrDocs
+ * @param {string} source
+ * @returns {any} A Prettier doc.
+ */
+function printOpenTag(node, attrDocs, source) {
+	const attrs = node.attrs ?? [];
+	const realAttrs = attrs.filter(
+		(/** @type {any} */ a) => a.type !== 'twig' && a.type !== 'twigBlock' && a.type !== 'twigComment',
+	);
+	const hasConditional = attrs.some((/** @type {any} */ a) => a.type === 'twig' || a.type === 'twigBlock');
+	const hasComplexValue = realAttrs.some((/** @type {any} */ a) =>
+		a.valueChunks.some((/** @type {any} */ c) =>
+			c.type === 'twig'
+				? Boolean(c.atom.tag) || /[\r\n]/.test(c.atom.raw)
+				: /[\r\n]/.test(c.text),
+		),
+	);
+	const forcedSingleLine = FORCE_SINGLE_LINE.has(node.name);
+	const singleLineTag = forcedSingleLine || (realAttrs.length <= 1 && !hasConditional && !hasComplexValue);
+	return forcedSingleLine
+		? // `html`, `link` and `meta` are never broken across lines
+		collapseWhitespace(source.slice(node.rawStart, node.startTagEnd)).replace(
+			/\s*\/?>$/,
+			node.selfClosing ? ' />' : '>',
+		)
+		: singleLineTag
+			? ['<', node.nameRaw, ...attrDocs.map((/** @type {any} */ d) => [' ', d]), node.selfClosing ? ' />' : '>']
+			: ['<', node.nameRaw, indent([hardline, join(hardline, attrDocs)]), hardline, node.selfClosing ? '/>' : '>'];
+}
+
+/**
+ * Prints an element.
+ *
+ * @param {any} path
+ * @param {(selector: any, ...rest: any[]) => any} printCallback
+ * @param {string} source
+ * @returns {any} A Prettier doc.
+ */
+function printElement(path, printCallback, source) {
+	const node = path.node;
+	const attrs = node.attrs ?? [];
+	const attrDocs = attrs.map((/** @type {any} */ _, /** @type {number} */ i) => path.call(printCallback, 'attrs', i));
+	const openDoc = printOpenTag(node, attrDocs, source);
+
+	if (node.selfClosing || VOID_ELEMENTS.has(node.name)) {
+		return group(openDoc);
+	}
+
+	// Twig partials may be open-ended (e.g. a template that starts with
+	// `<html><body>` and is closed by another template). When the source has no
+	// end tag, never add one: doing so would break template composition.
+	if (node.endTagStart === undefined) {
+		const children = (node.children ?? []).filter((/** @type {any} */ c) => !isWhitespaceOnly(c));
+		return children.length === 0
+			? group(openDoc)
+			: group([openDoc, indent(printChildren(path, printCallback, source))]);
+	}
+
+	const closeDoc = ['</', node.nameRaw, '>'];
+	const inner = source.slice(node.startTagEnd, node.endTagStart ?? node.rawEnd);
+
+	// Raw-text / whitespace-significant elements (`<script>`, `<style>`,
+	// `<textarea>`, `<title>`, `<pre>`) keep their inner source verbatim: their
+	// content is not HTML to reflow and collapsing it would change meaning.
+	if (RAWTEXT_ELEMENTS.has(node.name)) {
+		return group([openDoc, inner, closeDoc]);
+	}
+
+	const hasLineBreak = /[\r\n]/.test(inner);
+
+	// Text content with no surrounding line break: its exact whitespace is
+	// significant, so the element is reproduced verbatim.
+	if (!hasLineBreak && hasTextContent(node)) {
+		return group([openDoc, inner, closeDoc]);
+	}
+
+	// Content made only of text, prints and comments is "phrasing" content.
+	// With no line break it is reproduced verbatim; when it already spans lines
+	// and is pure text, the indentation may be normalized while the closing tag
+	// stays put. Phrasing content that contains twig is printed structurally so
+	// multi-line tags (e.g. `include ... with { … }`) are laid out correctly.
+	if (isPhrasingContent(node, source)) {
+		if (!hasLineBreak) {
+			return group([openDoc, inner, closeDoc]);
+		}
+		if (isTextOnly(node)) {
+			return group([openDoc, printInlineText(inner), closeDoc]);
+		}
+	}
+
+	// An element without content closes on the same line as the opening tag's
+	// `>`, even when its attributes are laid out over several lines.
+	if ((node.children ?? []).length === 0) {
+		return group([openDoc, closeDoc]);
+	}
+
+	return group([openDoc, indent(printChildren(path, printCallback, source)), hardline, closeDoc]);
+}
+
+/**
+ * Whether an element has non-whitespace text content.
+ *
+ * @param {any} node
+ * @returns {boolean}
+ */
+function hasTextContent(node) {
+	return (node.children ?? []).some(
+		(/** @type {any} */ c) => c.type === 'text' && c.raw.trim() !== '',
+	);
+}
+
+/**
+ * Whether an element's content is only text (including whitespace-only text).
+ *
+ * @param {any} node
+ * @returns {boolean}
+ */
+function isTextOnly(node) {
+	const children = node.children ?? [];
+	return children.length > 0 && children.every((/** @type {any} */ c) => c.type === 'text');
+}
+
+/**
+ * Whether an element's non-empty content is only phrasing content (text,
+ * prints, comments and inline twig blocks).
+ *
+ * @param {any} node
+ * @param {string} source
+ * @returns {boolean}
+ */
+function isPhrasingContent(node, source) {
+	const children = node.children ?? [];
+	if (children.length === 0) {
+		return false;
+	}
+	return children.every(
+		(/** @type {any} */ c) =>
+			c.type === 'text' ||
+			c.type === 'twig' ||
+			c.type === 'comment' ||
+			c.type === 'twigComment' ||
+			(c.type === 'twigBlock' && isInlineTwigBlock(c, source)),
+	);
+}
+
+/**
+ * Re-indents the inner text of a phrasing element that already spans lines.
+ * A leading / trailing line break is preserved so the closing tag stays where
+ * the source put it.
+ *
+ * @param {string} inner
+ * @returns {any} A Prettier doc.
+ */
+function printInlineText(inner) {
+	const leading = /^[ \t]*\r?\n/.test(inner);
+	const trailing = /\r?\n[ \t]*$/.test(inner);
+	const lines = inner
+		.split(/\r?\n/)
+		.map((/** @type {string} */ text) => text.trim())
+		.filter((/** @type {string} */ text) => text !== '');
+	if (lines.length === 0) {
+		return hardline;
+	}
+	const rest = lines.slice(1);
+	let content;
+	if (leading) {
+		content = indent([hardline, join(hardline, lines)]);
+	} else if (rest.length > 0) {
+		content = [lines[0], indent([hardline, join(hardline, rest)])];
+	} else {
+		content = lines[0];
+	}
+	return trailing ? [content, hardline] : content;
+}
+
+/** Elements whose start tag must always stay on a single line. */
+const FORCE_SINGLE_LINE = new Set(['html', 'link', 'meta']);
+
+/** Void elements that never have an end tag. */
+const VOID_ELEMENTS = new Set([
+	'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link',
+	'meta', 'param', 'source', 'track', 'wbr',
+]);
+
+/** Elements whose inner content must be preserved verbatim. */
+const RAWTEXT_ELEMENTS = new Set(['script', 'style', 'textarea', 'title', 'pre']);
+
+/**
+ * Prints an attribute.
+ *
+ * @param {any} attr
+ * @returns {any} A Prettier doc.
+ */
+function printAttribute(attr) {
+	if (attr.quote === null && attr.valueChunks.length === 0) {
+		return attr.nameRaw;
+	}
+	// Event-handler attributes hold opaque script and must not be reformatted.
+	// Control structures inside a value manage their own indentation, so they
+	// are printed verbatim; plain multi-line values are re-indented so every
+	// line sits at the same level.
+	const isEventHandler = /^on./i.test(attr.nameRaw);
+	const hasControlFlow = attr.valueChunks.some(
+		(/** @type {any} */ c) => c.type === 'twig' && c.atom.tag,
+	);
+	const rawValue = attr.valueChunks
+		.map((/** @type {any} */ c) => (c.type === 'twig' ? c.atom.raw : c.text))
+		.join('');
+	const value = isEventHandler || hasControlFlow ? rawValue : printAttributeValue(rawValue);
+	if (attr.quote === null) {
+		return [attr.nameRaw, '=', value];
+	}
+	return [attr.nameRaw, '=', attr.quote, value, attr.quote];
+}
+
+/**
+ * Re-indents a multi-line attribute value so all content lines share one indent
+ * level, with the closing quote back at the attribute's indent. A value with a
+ * leading/trailing line break keeps those breaks.
+ *
+ * @param {string} raw The value text (quotes excluded).
+ * @returns {any} A Prettier doc.
+ */
+function printAttributeValue(raw) {
+	if (!/[\r\n]/.test(raw)) {
+		return raw;
+	}
+	const lines = raw.split(/\r?\n/).map((/** @type {string} */ text) => text.trim());
+	const leadingBreak = lines[0] === '';
+	const trailingBreak = lines[lines.length - 1] === '';
+	let content = lines;
+	if (leadingBreak) {
+		content = content.slice(1);
+	}
+	if (trailingBreak) {
+		content = content.slice(0, -1);
+	}
+	content = content.filter((/** @type {string} */ text) => text !== '');
+	if (content.length === 0) {
+		return '';
+	}
+	let body;
+	if (leadingBreak) {
+		body = indent([hardline, join(hardline, content)]);
+	} else {
+		const [first, ...rest] = content;
+		body = rest.length > 0 ? [first, indent([hardline, join(hardline, rest)])] : first;
+	}
+	return trailingBreak ? [body, hardline] : body;
+}
+
+/**
+ * Prints a twig block (text position or inside a start tag).
+ *
+ * @param {any} path
+ * @param {(selector: any, ...rest: any[]) => any} printCallback
+ * @param {string} source
+ * @returns {any} A Prettier doc.
+ */
+function printTwigBlock(path, printCallback, source) {
+	const node = path.node;
+	const open = normalizeTwigTag(node.open.atom.raw);
+	const close = normalizeTwigTag(node.close.atom.raw);
+	/** @type {any[]} */
+	const docs = [];
+	// `node.children` is the flattened concatenation of every section body, so a
+	// running index maps body items back onto the path for position tracking.
+	let bodyIndex = 0;
+	// blank-line detection measures the source between the end of the previous
+	// non-whitespace item (or the opening / section head) and the current one
+	let previousEnd = node.open.atom.rawEnd;
+	for (const section of node.sections ?? []) {
+		if (section.head) {
+			// mid tags (`{% else %}`, `{% elseif %}`) sit at the block's own indent
+			const head = normalizeTwigTag(section.head.atom.raw);
+			docs.push(hasBlankLine(source, previousEnd, section.head.atom.rawStart) ? [hardline, hardline, head] : [hardline, head]);
+			previousEnd = section.head.atom.rawEnd;
+		}
+		/** @type {any[]} */
+		const bodyDocs = [];
+		for (const child of section.body) {
+			const i = bodyIndex;
+			bodyIndex += 1;
+			if (isWhitespaceOnly(child)) {
+				continue;
+			}
+			const childDoc = path.call(printCallback, 'children', i);
+			const { start, end } = contentBounds(child);
+			bodyDocs.push(hasBlankLine(source, previousEnd, start) ? [hardline, hardline, childDoc] : [hardline, childDoc]);
+			previousEnd = end;
+		}
+		if (bodyDocs.length > 0) {
+			docs.push(indent(bodyDocs));
+		}
+	}
+	return group([open, docs, hardline, close]);
+}
+
+/**
+ * Prints a twig tag. Object literals are laid out by Prettier; `include` is
+ * special-cased because its `with` mapping is always expanded, one entry per
+ * line, rather than kept as a single-line object notation.
+ *
+ * @param {any} node
+ * @param {any} options
+ * @returns {any} A Prettier doc.
+ */
+function printTwig(node, options) {
+	const forceBreak = node.atom.tag === 'include';
+	return formatTwigTag(node.atom.raw, forceBreak, options.trailingComma !== 'none');
+}
+
+/**
+ * Finds the offset of the delimiter matching the `{` or `[` at `openIndex`.
+ *
+ * @param {string} text
+ * @param {number} openIndex
+ * @returns {number} The matching delimiter offset, or `-1`.
+ */
+function findMatchingBrace(text, openIndex) {
+	const open = text[openIndex];
+	const close = open === '{' ? '}' : ']';
+	let depth = 0;
+	let quote = '';
+	for (let i = openIndex; i < text.length; i += 1) {
+		const ch = text[i];
+		if (quote !== '') {
+			if (ch === '\\') {
+				i += 1;
+			} else if (ch === quote) {
+				quote = '';
+			}
+			continue;
+		}
+		if (ch === '"' || ch === "'") {
+			quote = ch;
+		} else if (ch === open) {
+			depth += 1;
+		} else if (ch === close) {
+			depth -= 1;
+			if (depth === 0) {
+				return i;
+			}
+		}
+	}
+	return -1;
+}
+
+/**
+ * Splits a mapping body on top-level commas (ignoring commas nested in braces,
+ * brackets, parentheses and string literals).
+ *
+ * @param {string} text
+ * @returns {string[]} The trimmed entries.
+ */
+function splitTopLevel(text) {
+	/** @type {string[]} */
+	const parts = [];
+	let depth = 0;
+	let quote = '';
+	let start = 0;
+	for (let i = 0; i < text.length; i += 1) {
+		const ch = text[i];
+		if (quote !== '') {
+			if (ch === '\\') {
+				i += 1;
+			} else if (ch === quote) {
+				quote = '';
+			}
+			continue;
+		}
+		if (ch === '"' || ch === "'") {
+			quote = ch;
+		} else if (ch === '{' || ch === '[' || ch === '(') {
+			depth += 1;
+		} else if (ch === '}' || ch === ']' || ch === ')') {
+			depth -= 1;
+		} else if (ch === ',' && depth === 0) {
+			parts.push(text.slice(start, i).trim());
+			start = i + 1;
+		}
+	}
+	const last = text.slice(start).trim();
+	if (last !== '') {
+		parts.push(last);
+	}
+	return parts;
+}
+
+/**
+ * Prints a twig comment, normalizing its whitespace. Single-line comments are
+ * collapsed; multi-line comments keep one trimmed content line per line with
+ * the `{#` / `#}` delimiters on their own lines.
+ *
+ * @param {any} node
+ * @returns {any} A Prettier doc.
+ */
+function printTwigComment(node) {
+	const raw = node.atom.raw;
+	let open = '{#';
+	if (raw.startsWith('{##')) {
+		open = '{##';
+	} else if (raw.startsWith('{#-')) {
+		open = '{#-';
+	} else if (raw.startsWith('{#~')) {
+		open = '{#~';
+	}
+	let close = '#}';
+	if (raw.endsWith('##}')) {
+		close = '##}';
+	} else if (raw.endsWith('-#}')) {
+		close = '-#}';
+	} else if (raw.endsWith('~#}')) {
+		close = '~#}';
+	}
+	const body = raw.slice(open.length, raw.length - close.length);
+	if (!/[\r\n]/.test(body)) {
+		const content = collapseWhitespace(body).trim();
+		return content === '' ? `${open}${close}` : `${open} ${content} ${close}`;
+	}
+	const lines = body.split('\n').map((/** @type {string} */ text) => collapseWhitespace(text).trim());
+	while (lines.length > 0 && lines[0] === '') {
+		lines.shift();
+	}
+	while (lines.length > 0 && lines[lines.length - 1] === '') {
+		lines.pop();
+	}
+	if (lines.length === 0) {
+		return `${open}${close}`;
+	}
+	return [open, indent([hardline, join(hardline, lines)]), hardline, close];
+}
+
+/**
+ * Whether a twig block sits inline in its source and contains only inline
+ * content, so it can be printed verbatim without reflowing.
+ *
+ * @param {any} node
+ * @param {string} source
+ * @returns {boolean}
+ */
+function isInlineTwigBlock(node, source) {
+	const raw = source.slice(node.rawStart, node.rawEnd);
+	if (raw.includes('\n')) {
+		return false;
+	}
+	const children = (node.children ?? []).filter((/** @type {any} */ c) => !isWhitespaceOnly(c));
+	return children.every(
+		(/** @type {any} */ c) =>
+			c.type === 'text' || c.type === 'twig' || c.type === 'comment' || c.type === 'twigComment',
+	);
+}
+
+/**
+ * Prints a text node.
+ *
+ * @param {any} node
+ * @returns {any} A Prettier doc.
+ */
+function printText(node) {
+	const text = node.raw.trim();
+	if (text === '') {
+		return '';
+	}
+	if (/<\/[A-Za-z]/.test(text)) {
+		const lines = node.raw
+			.split(/\r?\n/)
+			.map((/** @type {string} */ rawLine) => rawLine.replace(/[ \t]+$/, ''));
+		while (lines.length > 0 && lines[0].trim() === '') {
+			lines.shift();
+		}
+		while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
+			lines.pop();
+		}
+		return lines.join('\n');
+	}
+	return text.replace(/[ \t]+/g, ' ').replace(/ *\n */g, '\n');
+}
+
+/** Elements whose content is delegated to an embedded Prettier parser. */
+const EMBEDDED_ELEMENTS = new Map([
+	['script', 'babel'],
+	['style', 'css'],
+]);
+
+/** Placeholders that stand in for twig constructs during embedded formatting. */
+const PLACEHOLDER_PATTERN = /_Tw(\d+)/g;
+
+/**
+ * Extracts a script/style element's body as text, replacing every twig
+ * construct with a placeholder so the body parses as plain JavaScript or CSS.
+ * The printed twig docs are returned alongside, indexed by placeholder.
+ *
+ * @param {any} node
+ * @param {(selector: any, ...rest: any[]) => any} printChild
+ * @param {string} source
+ * @returns {{text: string, docs: any[]}}
+ */
+function collectEmbeddedContent(node, printChild, source) {
+	const start = node.startTagEnd;
+	const end = node.endTagStart ?? node.rawEnd;
+	const children = node.children ?? [];
+	/** @type {any[]} */
+	const docs = [];
+	/** @type {Array<{start: number, end: number, placeholder: string}>} */
+	const edits = [];
+	for (let i = 0; i < children.length; i += 1) {
+		const child = children[i];
+		if (
+			child.type !== 'twig' &&
+			child.type !== 'twigBlock' &&
+			child.type !== 'twigComment' &&
+			child.type !== 'comment'
+		) {
+			continue;
+		}
+		const { start: childStart, end: childEnd } = contentBounds(child);
+		const index = docs.length;
+		docs.push(printChild(['children', i]));
+		edits.push({
+			start: childStart - start,
+			end: childEnd - start,
+			placeholder: `_Tw${index}`,
+		});
+	}
+	let text = source.slice(start, end);
+	for (let i = edits.length - 1; i >= 0; i -= 1) {
+		const edit = edits[i];
+		text = text.slice(0, edit.start) + edit.placeholder + text.slice(edit.end);
+	}
+	return { text, docs };
+}
+
+/**
+ * Adds a line's indentation to the continuation lines of inserted text, so a
+ * multi-line twig construct stays aligned with the line it replaces.
+ *
+ * @param {string} text
+ * @param {string} lineIndent
+ * @returns {string}
+ */
+function indentContinuation(text, lineIndent) {
+	if (lineIndent === '' || !text.includes('\n')) {
+		return text;
+	}
+	const [first, ...rest] = text.split('\n');
+	return [first, ...rest.map((/** @type {string} */ textLine) => (textLine === '' ? textLine : lineIndent + textLine))].join(
+		'\n',
+	);
+}
+
+/**
+ * Renders a doc to text, leaving strings untouched.
+ *
+ * @param {any} value
+ * @param {any} options
+ * @returns {string}
+ */
+function docToString(value, options) {
+	if (typeof value === 'string') {
+		return value;
+	}
+	return doc.printer.printDocToString(value, {
+		printWidth: options.printWidth,
+		useTabs: options.useTabs,
+		tabWidth: options.tabWidth,
+	}).formatted;
+}
+
+/**
+ * Formats a `<script>` / `<style>` element by delegating its body to the
+ * embedded JavaScript or CSS parser.
+ *
+ * @param {any} path
+ * @param {(text: string, options: any) => Promise<any>} textToDoc
+ * @param {(selector: any, ...rest: any[]) => any} printChild
+ * @param {any} options
+ * @returns {Promise<any>} A Prettier doc, or `undefined` to fall back.
+ */
+async function printEmbeddedElement(path, textToDoc, printChild, options) {
+	const node = path.node;
+	const source = options.originalText ?? '';
+	const parser = EMBEDDED_ELEMENTS.get(node.name);
+	const attrDocs = (node.attrs ?? []).map((/** @type {any} */ _, /** @type {number} */ i) =>
+		printChild(['attrs', i]),
+	);
+	const openDoc = printOpenTag(node, attrDocs, source);
+	if (node.selfClosing || node.endTagStart === undefined) {
+		return group(openDoc);
+	}
+	const closeDoc = ['</', node.nameRaw, '>'];
+	const children = (node.children ?? []).filter((/** @type {any} */ c) => !isWhitespaceOnly(c));
+	if (children.length === 0) {
+		return group([openDoc, closeDoc]);
+	}
+	const { text, docs } = collectEmbeddedContent(node, printChild, source);
+	/** @type {any} */
+	const embedOptions = { parser };
+	if (parser === 'babel') {
+		// trailing commas are dropped in embedded JavaScript; twig constructs and
+		// embedded CSS are unaffected
+		embedOptions.trailingComma = 'none';
+	}
+	let body;
+	try {
+		body = await textToDoc(text, embedOptions);
+	} catch {
+		return undefined;
+	}
+	// Layout is decided while twig constructs are still short placeholders, so a
+	// long twig expression never forces its surrounding code to wrap. The body
+	// is rendered to text, then the placeholders are substituted.
+	const rendered = doc.printer.printDocToString(body, {
+		printWidth: options.printWidth,
+		useTabs: options.useTabs,
+		tabWidth: options.tabWidth,
+	}).formatted;
+	const withTwig = rendered.replace(PLACEHOLDER_PATTERN, (match, index, offset) => {
+		const twigDoc = docs[Number(index)];
+		if (twigDoc === undefined) {
+			return match;
+		}
+		const lineStart = rendered.lastIndexOf('\n', offset) + 1;
+		const lineIndent = rendered.slice(lineStart).match(/^[ \t]*/)?.[0] ?? '';
+		return indentContinuation(docToString(twigDoc, options), lineIndent);
+	});
+	return group([openDoc, indent([hardline, join(hardline, withTwig.split('\n'))]), hardline, closeDoc]);
+}
+
+/**
+ * The Prettier embed callback: hands `<script>` and `<style>` bodies to the
+ * embedded language parsers.
+ *
+ * @param {any} path
+ * @param {any} options
+ * @returns {any} An embed function, or `undefined`.
+ */
+export function embed(path, options) {
+	const node = path.node;
+	if (node?.type !== 'element' || !EMBEDDED_ELEMENTS.has(node.name)) {
+		return undefined;
+	}
+	return (
+		/** @type {any} */ textToDoc,
+		/** @type {(selector: any, ...rest: any[]) => any} */ printChild,
+		/** @type {any} */ innerPath,
+		/** @type {any} */ innerOptions,
+	) => printEmbeddedElement(innerPath, textToDoc, printChild, innerOptions ?? options);
+}
+
+/**
+ * The Prettier print callback.
+ *
+ * @param {any} path
+ * @param {any} options
+ * @param {(selector: any, ...rest: any[]) => any} printCallback
+ * @returns {any} A Prettier doc.
+ */
+export function print(path, options, printCallback) {
+	const node = path.node;
+	const source = options.originalText ?? '';
+	switch (node.type) {
+		case 'root':
+			// finish the document with exactly one newline (Prettier convention)
+			return [printChildren(path, printCallback, source, false, options), hardline];
+		case 'element':
+			return printElement(path, printCallback, source);
+		case 'twigBlock':
+			return isInlineTwigBlock(node, source)
+				? source.slice(node.rawStart, node.rawEnd)
+				: printTwigBlock(path, printCallback, source);
+		default:
+			return printNode(node, options);
+	}
+}
+
+/**
+ * Prints a leaf node.
+ *
+ * @param {any} node
+ * @param {any} options
+ * @returns {any} A Prettier doc.
+ */
+function printNode(node, options) {
+	switch (node.type) {
+		case 'twig':
+			return printTwig(node, options);
+		case 'twigComment':
+			return printTwigComment(node);
+		case 'attr':
+			return printAttribute(node);
+		case 'text':
+			return printText(node);
+		case 'comment':
+		case 'doctype':
+			return node.raw;
+		default:
+			return '';
+	}
+}