webpack 5.111.1 → 5.112.1

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 `number` there).
+ * @template R
+ * @template {Record<number, number>} M
+ * @template D
+ * @typedef {number extends (R & { readonly __nodeType: number })["__nodeType"] ? D : M[(R & { readonly __nodeType: number })["__nodeType"]]} 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,35 @@ 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, DeferredWrite[keyof DeferredWrite]>} */ (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 +333,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+/";
@@ -262,10 +405,13 @@ class PrintContext {
 		this._printer = printer;
 		// Printed text by node handle, in two columns rather than one `Map`: the
 		// handles are dense integers, and `_moveEpoch` keeps the live set small.
-		/** @type {string[]} each finished node's printed text */
+		/** @type {(string | null)[]} each finished node's printed text */
 		this._storeText = [];
 		/** @type {Int32Array} the epoch each slot was written in */
 		this._storeGen = new Int32Array(0);
+		// A slot holding `null` prints as its source, read only once asked for.
+		/** @type {((node: TNode) => string) | undefined} reads a `null` slot's text */
+		this._sourceText = undefined;
 		/** @type {number} current epoch; a slot from an older one reads as absent */
 		this._gen = 1;
 		/** @type {number} lowest slot written since the epoch last moved */
@@ -277,21 +423,23 @@ class PrintContext {
 		// for retractable text alone, so no other emit pays for that ability.
 		/** @type {string[]} pieces already cut off, in output order */
 		this._chunks = [];
+		/** @type {Map<number, { readonly text: string }> | null} pieces whose text is read only once the output is */
+		this._deferred = null;
 		/** @type {string} output after the last cut piece */
 		this._tail = "";
 		/** @type {number} characters in `_tail`, so its length is not read off a rope */
 		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 */
@@ -453,6 +601,7 @@ class PrintContext {
 	 * @param {number} charCode the character to drop
 	 */
 	dropTrailing(from, charCode) {
+		this._settleDeferred();
 		const chunks = this._chunks;
 		for (let i = chunks.length; i >= from; i--) {
 			let text = i === chunks.length ? this._tail : chunks[i];
@@ -473,6 +622,43 @@ 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._settleDeferred();
+		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`.
@@ -480,8 +666,17 @@ class PrintContext {
 	 * @param {TPath} path the language accessor, positioned on `node`
 	 */
 	printNode(node, path) {
-		const text = this._printer(path, this);
-		const n = /** @type {EXPECTED_ANY} */ (node);
+		this.printedAs(node, this._printer(path, this));
+	}
+
+	/**
+	 * Store `text` as what `node` printed, where the grammar already knows what
+	 * the node printer would return and so does not call it.
+	 * @param {TNode} node the finished node
+	 * @param {string} text its printed text
+	 */
+	printedAs(node, text) {
+		const n = /** @type {number} */ (node);
 		if (n >= this._storeText.length) this._growStore(n + 1);
 		this._storeText[n] = text;
 		this._storeGen[n] = this._gen;
@@ -489,6 +684,22 @@ class PrintContext {
 		if (n > this._storeHigh) this._storeHigh = n;
 	}
 
+	/**
+	 * Store that `node` printed as its source, which `sourceText` reads only once
+	 * something asks for its text.
+	 * @param {TNode} node the finished node
+	 * @param {(node: TNode) => string} sourceText reads a node's source
+	 */
+	printedSource(node, sourceText) {
+		const n = /** @type {number} */ (node);
+		if (n >= this._storeText.length) this._growStore(n + 1);
+		this._sourceText = sourceText;
+		this._storeText[n] = null;
+		this._storeGen[n] = this._gen;
+		if (n < this._storeLow) this._storeLow = n;
+		if (n > this._storeHigh) this._storeHigh = n;
+	}
+
 	/**
 	 * Print one node and hand its text straight back — for a node inside one being
 	 * printed in pieces, whose text is emitted as it is printed, so the store
@@ -505,10 +716,17 @@ class PrintContext {
 	 * @returns {string} its printed text
 	 */
 	get(node) {
-		const n = /** @type {EXPECTED_ANY} */ (node);
-		return /** @type {string} */ (
-			this._storeGen[n] === this._gen ? this._storeText[n] : undefined
+		const n = /** @type {number} */ (node);
+		if (this._storeGen[n] !== this._gen) {
+			return /** @type {string} */ (/** @type {unknown} */ (undefined));
+		}
+		const text = this._storeText[n];
+		if (text !== null) return text;
+		const source = /** @type {(node: TNode) => string} */ (this._sourceText)(
+			node
 		);
+		this._storeText[n] = source;
+		return source;
 	}
 
 	/**
@@ -566,12 +784,32 @@ class PrintContext {
 	 * @param {number} index the piece's index, from {@link emitRetractable}
 	 */
 	retract(index) {
+		if (this._deferred !== null) this._deferred.delete(index);
 		this._chunks[index] = "";
 		if (this._retractableMappings === null) return;
 		const mapping = this._retractableMappings[index];
 		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) {
+		this._settleDeferred();
+		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
@@ -582,6 +820,7 @@ class PrintContext {
 	 * @param {string} text what to fold in, its own closer included
 	 */
 	foldIntoRetractable(index, text) {
+		this._settleDeferred();
 		const piece = this._chunks[index];
 		this._chunks[index] = `${piece.slice(0, -1)}${text}`;
 	}
@@ -594,9 +833,31 @@ class PrintContext {
 	 * @param {string} text what the piece says now
 	 */
 	rewriteRetractable(index, text) {
+		if (this._deferred !== null) this._deferred.delete(index);
 		this._chunks[index] = text;
 	}
 
+	/**
+	 * {@link rewriteRetractable} with text that is asked for only once the output
+	 * is read: a piece rewritten many times over is then built once, not each time.
+	 * @param {number} index the piece's index, from {@link emitRetractable}
+	 * @param {{ readonly text: string }} source what holds the piece's text
+	 */
+	deferRetractable(index, source) {
+		if (this._deferred === null) this._deferred = new Map();
+		this._deferred.set(index, source);
+	}
+
+	/**
+	 * Write every deferred piece's text in, before anything reads the pieces.
+	 */
+	_settleDeferred() {
+		const deferred = this._deferred;
+		if (deferred === null) return;
+		this._deferred = null;
+		for (const [index, source] of deferred) this._chunks[index] = source.text;
+	}
+
 	/**
 	 * {@link take} for a top-level node a later sibling may still make dead — the
 	 * unprefixed twin of a vendor-prefixed rule, which can stand anywhere after
@@ -759,6 +1020,7 @@ class PrintContext {
 	 * @returns {SourceMap} the input->output source map
 	 */
 	sourceMap(options, code) {
+		this._settleDeferred();
 		let out = "";
 		let genLine = 0;
 		let genCol = 0;
@@ -830,6 +1092,7 @@ class PrintContext {
 	 * @returns {void}
 	 */
 	substitute(resolve, infix) {
+		this._settleDeferred();
 		const chunks = this._chunks;
 		const mappings = this._mappings;
 		// Both pieces and mappings are output-ordered, so one cursor walks them
@@ -892,6 +1155,7 @@ class PrintContext {
 	 * @param {string} text the output to keep instead
 	 */
 	replaceAll(text) {
+		this._deferred = null;
 		this._chunks.length = 0;
 		this._tail = text;
 		this._tailLength = text.length;
@@ -903,6 +1167,7 @@ class PrintContext {
 	}
 
 	result() {
+		this._settleDeferred();
 		// Trailing kept comments (after the last top-level node) flush here.
 		if (this._insertIdx < this._inserts.length) this._flushBefore(Infinity);
 		// Nothing was ever cut into its own piece, so there is nothing to join.
@@ -919,29 +1184,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} */
@@ -949,32 +1223,101 @@ 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
+	 */
+	/**
+	 * @param {number[] | TVisitors | VisitorMap<TPath>} map visitor map, or the node types `bucket` visits
+	 * @param {VisitorBucket<TypedNodePath<TPath, TNode, TParts, number, TState>>=} bucket the visitor, with an array of types
+	 * @returns {SourceProcessor<TPath, TNode, TProcessOptions, TPrintOptions, TParts, TState, TVisitors>} `this`, for chaining
 	 */
-	use(map) {
+	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],
+					/** @type {VisitorBucket<TPath>} */ (
+						/** @type {VisitorBucket<TPath> | VisitorBucket<TypedNodePath<TPath, TNode, TParts, number, TState>>} */ (
+							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)) {
+		for (const type of Object.keys(/** @type {VisitorMap<TPath>} */ (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, /** @type {VisitorMap<TPath>} */ (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
@@ -987,31 +1330,40 @@ 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 entries are
@@ -1019,11 +1371,11 @@ class SourceProcessor {
 		// 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 {typeof opts | (PrintOptions & TPrintOptions)} */ (opts)
 			),
-			/** @type {NodePrinter<TPath, TNode, TPrintOptions>} */ (this._printer)
+			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();
@@ -1061,7 +1413,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) {
@@ -1071,7 +1423,10 @@ class SourceProcessor {
 		// renderer's answer widened, which `Omit` cannot say and nothing reads.
 		const opts =
 			/** @type {TProcessOptions & { mode: PrintOptions["mode"] }} */
-			(/** @type {unknown} */ (options));
+			(
+				/** @type {typeof options | (TProcessOptions & { mode: PrintOptions["mode"] })} */
+				(options)
+			);
 
 		if (render === undefined) {
 			return /** @type {{ code: string, map: SourceMap | undefined }} */ (
@@ -1079,7 +1434,7 @@ class SourceProcessor {
 			);
 		}
 
-		/** @type {DeferredWrite[]} */
+		/** @type {DeferredEmbeddedSource[]} */
 		const deferred = [];
 		const { finish } = this._processDeferred(input, {
 			...opts,
@@ -1094,10 +1449,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));
 		});
 	}
 
@@ -1108,7 +1496,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) {