webpack 5.111.0 → 5.112.0

package/lib/util/SourceProcessor.js

@@ -38,6 +38,8 @@ const chooseDeferredInfix = (input) => {
 };
 
 const DEFERRED_ID_RE = /^\d+$/;
+// A character a stylesheet's bytes cannot spell without naming an encoding.
+const NON_ASCII_RE = /[^\0-\u007F]/;
 
 /**
  * Read the deferred write standing at `start`, if one does.
@@ -117,10 +119,10 @@ const declineDeferredWrites = (text, writes) =>
 	);
 
 /**
- * Babel-style visitor map keyed by a numeric node-type discriminator; a bucket
+ * Visitor map keyed by a numeric node-type discriminator; a bucket
  * is a function (enter-only) or `{ enter?, exit? }`.
  *
- * A visitor receives a single `path` argument (the Babel `path` shape): the
+ * A visitor receives a single `path` argument: the
  * language's AST accessor with the current position on it — `path.node`,
  * `path.parent` (null at a root) — plus `path.skipChildren()` (enter only)
  * to stop the walk descending, and every field-read method (which defaults
@@ -130,6 +132,122 @@ const declineDeferredWrites = (text, writes) =>
  * @template TPath
  * @typedef {(path: TPath) => void} VisitorFn
  */
+/**
+ * The members every language's `path` has under the same name and meaning, so
+ * a visitor written against it reads any grammar; see `docs/syntax.md`.
+ * @template TNode
+ * @template [TValue=unknown]
+ * @typedef {NodePathReads<TNode, TValue> & NodePathFields<TNode>} NodePath
+ */
+/**
+ * @template TNode
+ * @template [TValue=unknown]
+ * @typedef {object} NodePathReads
+ * @property {TNode} node the current node
+ * @property {TNode | null} parent the enclosing node (null at a root)
+ * @property {number} index the current node's index among its siblings
+ * @property {() => void} skipChildren stop the walk descending into the current node (enter only)
+ * @property {() => void} stop end the walk: no visitor fires after the current one returns, and a print still completes
+ * @property {unknown} state the run's state, as `process` was given it
+ * @property {(n?: TNode) => number} type the node's `NodeType`
+ * @property {(n?: TNode) => [number, number]} range start and end offsets in the input
+ * @property {(n?: TNode) => number} start where the node starts in the input
+ * @property {(n?: TNode) => number} end where the node ends in the input
+ * @property {(n?: TNode) => [number, number, number, number]} loc start line and column, end line and column (lines from 1, columns from 0)
+ * @property {(n?: TNode | number, end?: number) => string} source the node's source text, or the input between two offsets
+ * @property {(n?: TNode) => string} name the node's name as the language defines it, decoded ("" when it has none)
+ * @property {(n?: TNode) => TValue} value the node's value as the language defines it, decoded
+ * @property {(n?: TNode) => number} childCount number of children
+ * @property {(i: number, n?: TNode) => TNode} child the i-th child
+ * @property {(n?: TNode) => TNode[]} children every child as a new array
+ */
+/**
+ * Structure read through a language's `Field`, `Flag` and `Part`. Declared as
+ * methods so a language's path may accept only the parts each node type has.
+ * @template TNode
+ * @typedef {{
+ * field(i: number, field: number, n?: TNode): TNode,
+ * fieldCount(field: number, n?: TNode): number,
+ * fieldNamed(field: number, name: string, n?: TNode): TNode,
+ * flag(flag: number, n?: TNode): boolean,
+ * rangeOf(part: number, n?: TNode): [number, number] | null,
+ * startOf(part: number, n?: TNode): number,
+ * endOf(part: number, n?: TNode): number,
+ * textOf(part: number, n?: TNode): string | null,
+ * within(type: number): boolean,
+ * }} NodePathFields
+ */
+/**
+ * A node that also says which `NodeType` it is, so reading a part that type
+ * lacks fails to type-check; a plain `TNode` can be any node.
+ * @template TNode
+ * @template T
+ * @typedef {TNode & { readonly __nodeType: T }} TypedNode
+ */
+/**
+ * What part `M` gives the node type `R` says it is; every part `D` when `R`
+ * says none (a plain node reads `unknown` there).
+ * @template R
+ * @template {Record<number, number>} M
+ * @template D
+ * @typedef {number extends (R & { readonly __nodeType: unknown })["__nodeType"] ? D : M[(R & { readonly __nodeType: unknown })["__nodeType"] & number]} PartOf
+ */
+/**
+ * A language's parts, by node type: what its `Field`s and `Flag`s apply to.
+ * @typedef {object} NodeParts
+ * @property {number} types every `NodeType` member
+ * @property {number} field every `Field`
+ * @property {number} flag every `Flag`
+ * @property {number} part every `Part` with a position
+ * @property {number} text every `Part` with text beyond the name and value
+ * @property {Record<number, number>} fields the `Field`s of each node type
+ * @property {Record<number, number>} flags the `Flag`s of each node type
+ * @property {Record<number, number>} parts the `Part`s with a position, by node type
+ * @property {Record<number, number>} texts the `Part`s with text, by node type
+ * @property {Record<number, number>} items the node type of each `Field`'s items
+ */
+/**
+ * The path a visitor of node type `T` receives: its structure reads take only
+ * the parts that type has, and its `state` is the run's.
+ * @template TPath
+ * @template TNode
+ * @template {NodeParts} P
+ * @template T
+ * @template [S=unknown]
+ * @typedef {Omit<TPath, "node" | "state" | "within" | "field" | "fieldCount" | "fieldNamed" | "flag" | "rangeOf" | "startOf" | "endOf" | "textOf"> & {
+ *   readonly node: TypedNode<TNode, T>,
+ *   readonly state: S,
+ *   within(type: P["types"]): boolean,
+ *   field<R extends TNode = TypedNode<TNode, T>, F extends number = number>(i: number, field: F & PartOf<R, P["fields"], P["field"]>, n?: R): TypedNode<TNode, P["items"][F]>,
+ *   fieldCount<R extends TNode = TypedNode<TNode, T>>(field: PartOf<R, P["fields"], P["field"]>, n?: R): number,
+ *   fieldNamed<R extends TNode = TypedNode<TNode, T>, F extends number = number>(field: F & PartOf<R, P["fields"], P["field"]>, name: string, n?: R): TypedNode<TNode, P["items"][F]>,
+ *   flag<R extends TNode = TypedNode<TNode, T>>(flag: PartOf<R, P["flags"], P["flag"]>, n?: R): boolean,
+ *   rangeOf<R extends TNode = TypedNode<TNode, T>>(part: PartOf<R, P["parts"], P["part"]>, n?: R): [number, number] | null,
+ *   startOf<R extends TNode = TypedNode<TNode, T>>(part: PartOf<R, P["parts"], P["part"]>, n?: R): number,
+ *   endOf<R extends TNode = TypedNode<TNode, T>>(part: PartOf<R, P["parts"], P["part"]>, n?: R): number,
+ *   textOf<R extends TNode = TypedNode<TNode, T>>(part: PartOf<R, P["texts"], P["text"]>, n?: R): string | null
+ * }} TypedNodePath
+ */
+/**
+ * The parts of a language that names none: every node type has every part.
+ * @typedef {{
+ * types: number,
+ * field: number,
+ * flag: number,
+ * part: number,
+ * text: number,
+ * fields: Record<number, number>,
+ * flags: Record<number, number>,
+ * parts: Record<number, number>,
+ * texts: Record<number, number>,
+ * items: Record<number, number>,
+ * }} AnyParts
+ */
+/**
+ * @template S
+ * @typedef {{ state?: S }} RunState what a run hands its visitors as `path.state`
+ */
+
 /**
  * @template TPath
  * @typedef {VisitorFn<TPath> | { enter?: VisitorFn<TPath>, exit?: VisitorFn<TPath> }} VisitorBucket
@@ -154,15 +272,32 @@ const declineDeferredWrites = (text, writes) =>
  * typedef HTML also depends on.
  * @typedef {{ mode: "minify" | "beautify" }} PrintOptions
  */
+/**
+ * What names one offer whatever print made it: every field but the functions,
+ * so the second print of `processAsync` finds the first one's answer by it.
+ * @param {Omit<DeferredWrite, "build">} offer an offer, `build` and all or without it
+ * @returns {string} its key
+ */
+const deferredKey = (offer) => {
+	let key = "";
+	for (const name of Object.keys(offer).sort()) {
+		const value = /** @type {Record<string, unknown>} */ (offer)[name];
+		if (typeof value !== "function") key += `${name}\0${value}\0`;
+	}
+	return key;
+};
+
 /**
  * One write the print left a marker for, collected into the `deferEmbeddedSource`
  * print option by whichever grammar offered it — the other half of
- * {@link deferredWrite}. `source` is the text offered and `build` spells what is
- * printed around the answer, an untapped run's spelling where there is none. A
- * grammar carries whatever else describes the offer (`type`, `hostType`, `as`,
+ * {@link deferredWrite}. `source` is the text offered, `build` spells what is
+ * printed around the answer (an untapped run's spelling where there is none), and
+ * `decides` says whether the answer overturns a choice the print made without it.
+ * A grammar carries whatever else describes the offer (`type`, `hostType`, `as`,
  * …) on the same object.
- * @typedef {{ source: string, build: (answer: string | undefined) => string }} DeferredWrite
+ * @typedef {{ source: string, build: (answer: string | undefined) => string, decides?: (answer: string | undefined) => boolean }} DeferredWrite
  */
+/** @import { DeferredEmbeddedSource } from "./dataURL" */
 /**
  * A version-3 source map. Written structurally (with the `3` literal) so it
  * satisfies both `webpack-sources` and the minimizer plugin's map types without
@@ -195,6 +330,11 @@ const _makeMap = (options, mappings) => ({
 // small enough that the un-flattened fragments behind it stay bounded.
 const FLATTEN_BLOCK = 64 * 1024;
 
+// Most prints do not ask for a source map. Sharing their permanently empty
+// mapping column avoids allocating an array for every inline CSS/HTML body.
+/** @type {[number, number, number, number][]} */
+const EMPTY_MAPPINGS = [];
+
 // Base64 VLQ, the source-map `mappings` encoding. Hand-rolled so producing a map
 // pulls in no dependency (`source-map` is not a webpack dep).
 const _B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
@@ -272,12 +412,9 @@ class PrintContext {
 		this._storeLow = 0x7fffffff;
 		/** @type {number} highest slot written since the epoch last moved */
 		this._storeHigh = -1;
-		// Output accumulates into `_tail`, a plain string append, so printing that
-		// never takes anything back costs exactly what appending to one string
-		// costs. A piece is cut off into `_chunks` only for text that may still be
-		// taken back ({@link emitRetractable}) — that is what lets a printer emit
-		// before it knows a later sibling overrides it, without every other emit
-		// paying for the ability. The output is `_chunks` joined, then `_tail`.
+		// Output is `_chunks` joined, then `_tail`. Printing that never takes
+		// anything back only appends to `_tail`; a piece is cut off into `_chunks`
+		// for retractable text alone, so no other emit pays for that ability.
 		/** @type {string[]} pieces already cut off, in output order */
 		this._chunks = [];
 		/** @type {string} output after the last cut piece */
@@ -286,23 +423,22 @@ class PrintContext {
 		this._tailLength = 0;
 		/** @type {number} scratch for the flattening read in {@link _cutTail} */
 		this._flattened = 0;
-		/** @type {[number, number, number, number][]} `[chunkIndex, offsetInChunk, srcLine, srcCol]`, output-ordered; a `srcLine` of -1 is one {@link retract} took back with its piece */
-		this._mappings = [];
-		/** @type {number[] | null} by retractable piece index, the mapping anchored to it, so taking the piece back takes its mapping too */
-		this._retractableMappings = null;
 		// A map is built only for a caller that named the input, and that is known
 		// before printing — so a print nobody asks a map of collects none.
 		/** @type {boolean} whether {@link sourceMap} can still be asked for one */
 		this.mapWanted =
 			/** @type {{ source?: string }} */ (options).source !== undefined;
+		/** @type {[number, number, number, number][]} `[chunkIndex, offsetInChunk, srcLine, srcCol]`, output-ordered; a `srcLine` of -1 is one {@link retract} took back with its piece */
+		this._mappings = this.mapWanted ? [] : EMPTY_MAPPINGS;
+		/** @type {number[] | null} by retractable piece index, the mapping anchored to it, so taking the piece back takes its mapping too */
+		this._retractableMappings = null;
 		/** @type {[number, string][]} source-anchored literals to keep (comments), source-ordered */
 		this._inserts = [];
 		/** @type {number} next `_inserts` entry not yet flushed */
 		this._insertIdx = 0;
-		// Openers of the nodes being printed in pieces, innermost last, held back
-		// until one of them turns out to have content: a node whose children all
-		// print to nothing can then still be dropped whole, which is the one thing
-		// emitting an opener eagerly would give up.
+		// Openers of the nodes printed in pieces, innermost last, held back until
+		// one has content — which is what lets a node whose children all print to
+		// nothing still be dropped whole.
 		/** @type {string[]} openers not yet emitted, outermost first */
 		this._pending = [];
 		/** @type {[number | undefined, number | undefined, number | undefined] | null} anchor for the first pending opener */
@@ -477,6 +613,42 @@ class PrintContext {
 		}
 	}
 
+	/**
+	 * Stand `text` in place of the output's end, where that is `printed` followed
+	 * only by `closer`s — what the printer wrote after a value the input ran out in.
+	 * @param {string} printed the text the output must end with, before the closers
+	 * @param {string} text what to write in place of it and them
+	 * @param {number} closer the character that may follow `printed`
+	 * @returns {boolean} true when the output ended that way and was rewritten
+	 */
+	replaceEnd(printed, text, closer) {
+		this._cutTail();
+		const chunks = this._chunks;
+		// Joined once: this runs only where a value ran into the end of the input.
+		const output = chunks.join("");
+		let end = output.length;
+		while (end > 0 && output.charCodeAt(end - 1) === closer) end--;
+		// The closers the printed text wrote itself are its own, not the blocks'.
+		let own = printed.length;
+		while (own > 0 && printed.charCodeAt(own - 1) === closer) own--;
+		end += printed.length - own;
+		if (end > output.length || !output.slice(0, end).endsWith(printed)) {
+			return false;
+		}
+		let remove = output.length - end + printed.length;
+		for (let i = chunks.length - 1; remove > 0; i--) {
+			const kept = Math.max(0, chunks[i].length - remove);
+			remove -= chunks[i].length - kept;
+			chunks[i] = chunks[i].slice(0, kept);
+			// A mapping into what went would point past its piece.
+			this._mappings = this._mappings.filter(
+				([chunk, offset]) => chunk !== i || offset <= kept
+			);
+		}
+		this._emit(text);
+		return true;
+	}
+
 	/**
 	 * Run the node printer for `node` and store what it returns (the grammar calls
 	 * this once the node's visitors and children are done). `path` is on `node`.
@@ -485,7 +657,7 @@ class PrintContext {
 	 */
 	printNode(node, path) {
 		const text = this._printer(path, this);
-		const n = /** @type {EXPECTED_ANY} */ (node);
+		const n = /** @type {number} */ (node);
 		if (n >= this._storeText.length) this._growStore(n + 1);
 		this._storeText[n] = text;
 		this._storeGen[n] = this._gen;
@@ -509,7 +681,7 @@ class PrintContext {
 	 * @returns {string} its printed text
 	 */
 	get(node) {
-		const n = /** @type {EXPECTED_ANY} */ (node);
+		const n = /** @type {number} */ (node);
 		return /** @type {string} */ (
 			this._storeGen[n] === this._gen ? this._storeText[n] : undefined
 		);
@@ -524,14 +696,12 @@ class PrintContext {
 	_emit(text) {
 		this._tail += text;
 		this._tailLength += text.length;
-		// A printer returns its text as a rope of its children's pieces, and
-		// appending a rope onto a rope keeps every fragment of every node reachable
-		// until the output is finally flattened — on a stylesheet of many top-level
-		// rules, a second copy of the whole output. So cut the tail off once it has
-		// grown past a block and force that block flat, which drops every fragment
-		// behind it. Per block rather than per piece: the flattening copy is one
-		// the result would have paid for anyway, but paying it per piece means an
-		// allocation for each, and the pieces are small.
+		// WHY: A printer returns a rope of its children's pieces, and appending a
+		// rope onto a rope keeps every fragment reachable until the output is
+		// flattened — a second copy of a large stylesheet. Cutting the tail once it
+		// passes a block forces that block flat and drops the fragments behind it.
+		// Per block rather than per piece: the copy is one the result pays anyway,
+		// while per piece it would be an allocation each, and the pieces are small.
 		if (this._tailLength >= FLATTEN_BLOCK) this._cutTail();
 	}
 
@@ -578,6 +748,24 @@ class PrintContext {
 		if (mapping !== undefined) this._mappings[mapping][2] = -1;
 	}
 
+	/**
+	 * Whether the output after a piece holds a character outside ASCII, the
+	 * comments still waiting to be placed included.
+	 * @param {number} index the piece's index, from {@link emitRetractable}
+	 * @returns {boolean} true when it does
+	 */
+	writesNonAscii(index) {
+		const chunks = this._chunks;
+		for (let i = index + 1; i < chunks.length; i++) {
+			if (NON_ASCII_RE.test(chunks[i])) return true;
+		}
+		const inserts = this._inserts;
+		for (let i = this._insertIdx; i < inserts.length; i++) {
+			if (NON_ASCII_RE.test(inserts[i][1])) return true;
+		}
+		return NON_ASCII_RE.test(this._tail);
+	}
+
 	/**
 	 * Fold `text` into an already-emitted piece, in front of the character it ends
 	 * with — a later sibling whose body belongs inside that piece, as a repeated
@@ -925,29 +1113,38 @@ class PrintContext {
  * Visitor coordinator: owns the visitor registry and drives a language
  * `grammar` over the source. Language-agnostic — each syntax (CSS, HTML, …)
  * binds its own grammar, node-type enum and (optionally) node printer.
- * Babel-style usage:
+ * Usage:
  *
  * ```
  * processor.use({ [NodeType.X]: (path) => {}, [NodeType.Y]: { enter, exit } });
  * processor.process(source);
  * ```
- * @template TPath
+ * @template {NodePath<TNode>} TPath
  * @template TNode
  * @template [TProcessOptions=object]
  * @template [TPrintOptions=object]
+ * @template {NodeParts} [TParts=AnyParts] the language's parts, which type each visitor's path by node type
+ * @template [TState=unknown] what `process` hands every visitor as `path.state`
+ * @template [TVisitors=VisitorMap<TPath>] the language's visitor map, each path typed by its key and with `TState`
  */
 class SourceProcessor {
 	/**
 	 * @param {Grammar<TPath, TNode, TProcessOptions, TPrintOptions>} grammar the grammar to drive over the source
 	 * @param {NodePrinter<TPath, TNode, TPrintOptions>=} printer the node printer, fired per node once its visitors and children are done; the same `path` a visitor gets plus the print context as its writer. Required to print (e.g. `mode`); a future API can let a developer supply their own
+	 * @param {(() => NodePrinter<TPath, TNode, TPrintOptions>)=} loadPrinter asked for the printer the first time something prints, for a language that keeps its printer in a module of its own — so a walk that never prints never loads it
+	 * @param {TPath=} path the path the grammar hands its visitors, whose `state` a run sets
 	 */
-	constructor(grammar, printer) {
+	constructor(grammar, printer, loadPrinter, path) {
 		/** @type {Grammar<TPath, TNode, TProcessOptions, TPrintOptions>} */
 		this._grammar = grammar;
 		/** @type {CompiledVisitorMap<TPath>} */
 		this._visitors = [];
 		/** @type {NodePrinter<TPath, TNode, TPrintOptions> | undefined} */
 		this._printer = printer;
+		/** @type {(() => NodePrinter<TPath, TNode, TPrintOptions>) | undefined} */
+		this._loadPrinter = loadPrinter;
+		/** @type {TPath | undefined} */
+		this._path = path;
 		// Set for the one print {@link processDeferred} holds open, so `process`
 		// hands it the context instead of building the output straight away.
 		/** @type {((ctx: PrintContext<TPath, TNode, TPrintOptions>, build: () => { code: string, map: SourceMap | undefined }) => void) | null} */
@@ -955,32 +1152,92 @@ class SourceProcessor {
 	}
 
 	/**
-	 * Register a Babel-style visitor map; calls accumulate per node type.
+	 * Register one bucket for several node types, as a map naming each would;
+	 * its path takes only the parts those types have.
+	 * @template {number} T
+	 * @overload
+	 * @param {T[]} types the node types the bucket visits
+	 * @param {VisitorBucket<TypedNodePath<TPath, TNode, TParts, T, TState>>} bucket the visitor
+	 * @returns {SourceProcessor<TPath, TNode, TProcessOptions, TPrintOptions, TParts, TState, TVisitors>} `this`, for chaining
+	 */
+	/**
+	 * Register a visitor map; calls accumulate per node type, and each
+	 * visitor's path takes only its type's parts.
 	 * A bucket is a function (= `{ enter }`) or `{ enter?, exit? }`.
+	 * @overload
+	 * @param {TVisitors} map visitor map keyed by node type
+	 * @returns {SourceProcessor<TPath, TNode, TProcessOptions, TPrintOptions, TParts, TState, TVisitors>} `this`, for chaining
+	 */
+	/**
+	 * Register a visitor map built at runtime, keyed by any node type.
+	 * @overload
 	 * @param {VisitorMap<TPath>} map visitor map keyed by node type
-	 * @returns {SourceProcessor<TPath, TNode, TProcessOptions, TPrintOptions>} `this`, for chaining
+	 * @returns {SourceProcessor<TPath, TNode, TProcessOptions, TPrintOptions, TParts, TState, TVisitors>} `this`, for chaining
 	 */
-	use(map) {
+	/**
+	 * @param {EXPECTED_ANY} map visitor map, or the node types `bucket` visits
+	 * @param {VisitorBucket<EXPECTED_ANY>=} bucket the visitor, with an array of types
+	 * @returns {SourceProcessor<TPath, TNode, TProcessOptions, TPrintOptions, TParts, TState, TVisitors>} `this`, for chaining
+	 */
+	use(map, bucket) {
+		if (Array.isArray(map)) {
+			if (bucket === undefined) {
+				throw new TypeError(
+					"SourceProcessor.use(types, bucket): a visitor is required"
+				);
+			}
+			for (let i = 0; i < map.length; i++) this._add(map[i], bucket);
+			return this;
+		}
 		// `map`'s keys are node-type enum members; `Object.keys` stringifies them,
 		// so index the compiled array by the number to match the numeric `node.type`.
 		for (const type of Object.keys(map)) {
 			const key = Number(type);
-			const v = map[key];
-			let bucket = this._visitors[key];
-			if (!bucket) {
-				bucket = { enter: [], exit: [] };
-				this._visitors[key] = bucket;
-			}
-			if (typeof v === "function") {
-				bucket.enter.push(v);
-			} else {
-				if (v.enter) bucket.enter.push(v.enter);
-				if (v.exit) bucket.exit.push(v.exit);
-			}
+			this._add(key, map[key]);
 		}
 		return this;
 	}
 
+	/**
+	 * @param {number} type node type
+	 * @param {VisitorBucket<TPath>} visitor its visitor
+	 */
+	_add(type, visitor) {
+		let compiled = this._visitors[type];
+		if (!compiled) {
+			compiled = { enter: [], exit: [] };
+			this._visitors[type] = compiled;
+		}
+		if (typeof visitor === "function") {
+			compiled.enter.push(visitor);
+		} else {
+			if (visitor.enter) compiled.enter.push(visitor.enter);
+			if (visitor.exit) compiled.exit.push(visitor.exit);
+		}
+	}
+
+	/**
+	 * Run the grammar with the path's `state` set to the run's, put back after so
+	 * a run nested in a visitor leaves its caller's.
+	 * @param {string} input the source
+	 * @param {PrintContext<TPath, TNode, TPrintOptions> | undefined} ctx the print context, when printing
+	 * @param {TProcessOptions} opts process options
+	 */
+	_run(input, ctx, opts) {
+		const path = this._path;
+		if (path === undefined) {
+			this._grammar(input, this._visitors, ctx, opts);
+			return;
+		}
+		const outer = path.state;
+		path.state = /** @type {RunState<TState>} */ (opts).state;
+		try {
+			this._grammar(input, this._visitors, ctx, opts);
+		} finally {
+			path.state = outer;
+		}
+	}
+
 	/**
 	 * Parse `input` once and fire the visitors in source order. Asking for output
 	 * — `mode`, the one thing that names it — makes the same walk print, given a
@@ -993,44 +1250,52 @@ class SourceProcessor {
 	 * never re-parses; all configuration is per-call.
 	 * @overload
 	 * @param {string} input the source
-	 * @param {TProcessOptions & { mode: PrintOptions["mode"] } & { source: string, content?: string }} options process options, naming the input so a map is built
+	 * @param {TProcessOptions & RunState<TState> & { mode: PrintOptions["mode"] } & { source: string, content?: string }} options process options, naming the input so a map is built
 	 * @returns {{ code: string, map: SourceMap }} the output and its map
 	 */
 	/**
 	 * @overload
 	 * @param {string} input the source
-	 * @param {TProcessOptions & { mode: PrintOptions["mode"] }} options process options, asking for output but no map
+	 * @param {TProcessOptions & RunState<TState> & { mode: PrintOptions["mode"] }} options process options, asking for output but no map
 	 * @returns {{ code: string, map: undefined }} the output alone
 	 */
 	/**
 	 * @overload
 	 * @param {string} input the source
-	 * @param {TProcessOptions=} options process options, asking for no output
+	 * @param {(TProcessOptions & RunState<TState>)=} options process options, asking for no output
 	 * @returns {undefined} nothing — the walk alone
 	 */
 	/**
 	 * @param {string} input source text
-	 * @param {TProcessOptions=} options grammar-specific options (`skip`, …) plus `mode` and, for the map, `source` / `content`
-	 * @returns {EXPECTED_ANY} `{ code, map }` when printing, else `undefined` — see the overloads
+	 * @param {(TProcessOptions & RunState<TState>)=} options grammar-specific options (`skip`, …) plus `mode`, for the map `source` / `content`, and the visitors' `state`
+	 * @returns {{ code: string, map: SourceMap | undefined } | undefined} `{ code, map }` when printing, else `undefined` — see the overloads
 	 */
 	process(input, options) {
 		const opts = options || /** @type {TProcessOptions} */ ({});
 		const asked = /** @type {{ mode?: PrintOptions["mode"] }} */ (opts).mode;
+		// Asked for once per `process` and never per node, which is what lets a
+		// language hold its printer back until something actually prints.
+		if (
+			this._printer === undefined &&
+			asked !== undefined &&
+			this._loadPrinter
+		) {
+			this._printer = this._loadPrinter();
+		}
 		if (this._printer === undefined || asked === undefined) {
-			this._grammar(input, this._visitors, undefined, opts);
+			this._run(input, undefined, opts);
 			return undefined;
 		}
-		// Handed over whole rather than copied entry by entry: which of them are
-		// print options is the language's to say, and listing them here is what
-		// made every new one an edit to this file. A grammar-only entry riding
-		// along is inert — a printer reads only what its own type declares.
+		// Handed over whole rather than copied entry by entry: which entries are
+		// print options is the language's to say, and a grammar-only one riding
+		// along is inert, since a printer reads only what its own type declares.
 		const ctx = new PrintContext(
 			/** @type {PrintOptions & TPrintOptions} */ (
-				/** @type {unknown} */ ({ ...opts, mode: asked })
+				/** @type {unknown} */ (opts)
 			),
 			/** @type {NodePrinter<TPath, TNode, TPrintOptions>} */ (this._printer)
 		);
-		this._grammar(input, this._visitors, ctx, opts);
+		this._run(input, ctx, opts);
 		const name = /** @type {{ source?: string, content?: string }} */ (opts);
 		const build = () => {
 			const code = ctx.result();
@@ -1068,7 +1333,7 @@ class SourceProcessor {
 	 * This is the shape `process` itself takes once it is async: how the answers
 	 * are waited for is this method's business, so nothing above it changes.
 	 * @param {string} input the source
-	 * @param {Omit<TProcessOptions, "renderEmbeddedSource"> & { mode: PrintOptions["mode"] } & { source?: string, content?: string, renderEmbeddedSource?: (source: string, hole: EXPECTED_ANY) => Promise<string | undefined> | string | undefined }} options process options; a print, so `mode` names which one, and naming the input builds a map. `renderEmbeddedSource` is the grammar's own option with a wider answer — it may answer asynchronously, and is handed each {@link DeferredWrite} whole. Absent, this is `process` with a promise around it
+	 * @param {Omit<TProcessOptions, "renderEmbeddedSource"> & RunState<TState> & { mode: PrintOptions["mode"] } & { source?: string, content?: string, renderEmbeddedSource?: (source: string, hole: DeferredEmbeddedSource) => Promise<string | undefined> | string | undefined }} options process options; a print, so `mode` names which one, and naming the input builds a map. `renderEmbeddedSource` is the grammar's own option with a wider answer — it may answer asynchronously, and is handed each {@link DeferredWrite} whole. Absent, this is `process` with a promise around it
 	 * @returns {Promise<{ code: string, map: SourceMap | undefined }>} the output and its map
 	 */
 	async processAsync(input, options) {
@@ -1086,7 +1351,7 @@ class SourceProcessor {
 			);
 		}
 
-		/** @type {DeferredWrite[]} */
+		/** @type {DeferredEmbeddedSource[]} */
 		const deferred = [];
 		const { finish } = this._processDeferred(input, {
 			...opts,
@@ -1101,10 +1366,43 @@ class SourceProcessor {
 			deferred.map((hole) => render(hole.source, hole))
 		);
 
-		return finish((id) => {
-			const hole = deferred[id];
+		if (
+			!deferred.some(
+				(hole, id) => hole.decides !== undefined && hole.decides(answers[id])
+			)
+		) {
+			return finish((id) => {
+				const hole = deferred[id];
+
+				return hole === undefined ? undefined : hole.build(answers[id]);
+			});
+		}
+
+		// An answer overturned a choice the print made on the source, so it runs
+		// again with every answer in hand. Nothing is asked twice: this print offers
+		// a subset of the first's, and an offer it alone made is left as written.
+		/** @type {Map<string, string | undefined>} */
+		const known = new Map();
+		for (let id = 0; id < deferred.length; id++) {
+			known.set(deferredKey(deferred[id]), answers[id]);
+		}
+		/**
+		 * @param {Omit<DeferredWrite, "build">} offer an offer, `build` and all or without it
+		 * @returns {string | undefined} what the first print was answered for it
+		 */
+		const embeddedAnswers = (offer) => known.get(deferredKey(offer));
+		/** @type {DeferredWrite[]} */
+		const again = [];
+		const reprint = this._processDeferred(input, {
+			...opts,
+			renderEmbeddedSource: undefined,
+			deferEmbeddedSource: again,
+			embeddedAnswers
+		});
+		return reprint.finish((id) => {
+			const hole = again[id];
 
-			return hole === undefined ? undefined : hole.build(answers[id]);
+			return hole === undefined ? undefined : hole.build(embeddedAnswers(hole));
 		});
 	}
 
@@ -1115,7 +1413,7 @@ class SourceProcessor {
 	 * {@link processAsync} is built on, and private for that reason: a caller
 	 * asks for an asynchronous print, not for the way one is arranged.
 	 * @param {string} input the source
-	 * @param {TProcessOptions & { mode: PrintOptions["mode"] } & { source?: string, content?: string }} options process options; a print, so `mode` names which one, and naming the input builds a map
+	 * @param {TProcessOptions & RunState<TState> & { mode: PrintOptions["mode"] } & { source?: string, content?: string }} options process options; a print, so `mode` names which one, and naming the input builds a map
 	 * @returns {{ finish: (resolve: (id: number) => string | undefined) => { code: string, map: SourceMap | undefined } }} the deferred print
 	 */
 	_processDeferred(input, options) {