@rohal12/twee-ts 1.15.3 → 1.16.0

package/dist/index.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, watch as watch$1, writeFileSync } from "node:fs";
+import * as nodePath from "node:path";
+import { basename, dirname, extname, join, parse, relative, resolve, sep } from "node:path";
 import { randomUUID } from "node:crypto";
-import { basename, dirname, extname, join, parse, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 //#region src/ifid.ts
@@ -631,11 +632,25 @@ function fontFormatHint(ext) {
 * Ported from filesystem.go.
 */
 /**
+* Whether `filename` matches one of the `exclude` globs. The globs are matched
+* against the file's path relative to the working directory, the path
+* getFilenames reports; an absolute `filename` is made relative first. A leading
+* `./` in a glob is dropped. Matching is Node's `path.matchesGlob`.
+*/
+function isExcluded(filename, exclude) {
+	if (exclude.length === 0) return false;
+	const { matchesGlob } = nodePath;
+	if (typeof matchesGlob !== "function") throw new Error(`The exclude option needs Node.js 22.5 or newer (found ${process.version}).`);
+	const rel = relative(process.cwd(), resolve(filename)) || filename;
+	return exclude.some((pattern) => matchesGlob(rel, pattern.replace(/^\.\//, "")));
+}
+/**
 * Recursively walk directories, collecting regular file paths.
-* Filters out the output file to prevent circular compilation.
+* Filters out the output file to prevent circular compilation, and the files
+* that match an `exclude` glob (see isExcluded).
 * Like Tweego, a path that cannot be read is reported as a warning and skipped.
 */
-function getFilenames(pathnames, outFilename) {
+function getFilenames(pathnames, outFilename, exclude = []) {
 	const filenames = [];
 	const diagnostics = [];
 	const absOutFile = outFilename ? resolve(outFilename) : "";
@@ -657,6 +672,7 @@ function getFilenames(pathnames, outFilename) {
 			const abs = resolve(pathname);
 			if (abs === absOutFile) return;
 			const rel = relative(process.cwd(), abs);
+			if (isExcluded(rel || abs, exclude)) return;
 			filenames.push(rel || abs);
 		} else if (stat.isDirectory()) {
 			let entries;
@@ -677,9 +693,11 @@ function getFilenames(pathnames, outFilename) {
 }
 /**
 * Watch paths for changes, calling the build callback on known file type changes.
+* A change to a file `ignore` returns true for (given the path relative to the
+* working directory) schedules no build.
 * Uses debouncing to avoid rapid rebuilds.
 */
-function watchFilesystem(pathnames, outFilename, callback) {
+function watchFilesystem(pathnames, outFilename, callback, ignore = () => false) {
 	const absOutFile = resolve(outFilename);
 	const watchers = [];
 	let buildTimer = null;
@@ -700,7 +718,10 @@ function watchFilesystem(pathnames, outFilename, callback) {
 			if (!filename) return;
 			const abs = resolve(pathname, filename);
 			if (abs === absOutFile) return;
-			if (isKnownFileType(filename)) scheduleBuild(relative(process.cwd(), abs) || abs);
+			if (isKnownFileType(filename)) {
+				const rel = relative(process.cwd(), abs);
+				if (!ignore(rel || abs)) scheduleBuild(rel || abs);
+			}
 		});
 		watchers.push(watcher);
 	} catch {}
@@ -5171,14 +5192,22 @@ async function watch(options) {
 	const cache = /* @__PURE__ */ new Map();
 	const filePaths = options.sources.filter((s) => typeof s === "string");
 	const modulePaths = options.modules ?? [];
-	const handle = watchFilesystem([...filePaths, ...modulePaths], options.outFile, (changedFiles) => {
+	const allPaths = [...filePaths, ...modulePaths];
+	const exclude = options.exclude ?? [];
+	const moduleRoots = modulePaths.map((p) => resolve(p));
+	const ignore = (filename) => {
+		if (!isExcluded(filename, exclude)) return false;
+		const abs = resolve(filename);
+		return !moduleRoots.some((root) => abs === root || abs.startsWith(root + sep));
+	};
+	const handle = watchFilesystem(allPaths, options.outFile, (changedFiles) => {
 		buildOutput(options, cache, changedFiles).then((result) => {
 			writeFileSync(options.outFile, result.output, "utf-8");
 			options.onBuild?.(result);
 		}).catch((e) => {
 			options.onError?.(e instanceof Error ? e : new Error(String(e)));
 		});
-	});
+	}, ignore);
 	controller.signal.addEventListener("abort", () => handle.close());
 	return controller;
 }
@@ -5195,7 +5224,7 @@ async function buildOutput(options, cache, changedFiles) {
 	const inlineSources = [];
 	for (const source of options.sources) if (typeof source === "string") filePaths.push(source);
 	else inlineSources.push(source);
-	const { filenames: sourceFilenames, diagnostics: sourcePathDiagnostics } = getFilenames(filePaths);
+	const { filenames: sourceFilenames, diagnostics: sourcePathDiagnostics } = getFilenames(filePaths, void 0, options.exclude);
 	diagnostics.push(...sourcePathDiagnostics);
 	const story = createStory();
 	const processedFiles = /* @__PURE__ */ new Set();
@@ -5348,6 +5377,1101 @@ function storyToJSON(story) {
 	obj.passages = storyPassages;
 	return JSON.stringify(obj, null, 2);
 }
+const SINGLE_ESCAPES = /* @__PURE__ */ new Map([
+	["b", "\b"],
+	["f", "\f"],
+	["n", "\n"],
+	["r", "\r"],
+	["t", "	"],
+	["v", "\v"]
+]);
+const HEX_RE = /^[0-9A-Fa-f]+$/;
+const DIGIT_RE = /^[0-9]$/;
+const LINE_TERMINATORS = "\n\r\u2028\u2029";
+/**
+* The value of a quoted JavaScript string literal (quotes included), as strict-mode JavaScript
+* evaluates it: `\"`, `\'`, `\\`, `\n`, `\xHH`, `\uHHHH`, `\u{H…}`, line continuations, and a
+* backslash before any other character gives that character. Returns `undefined` for what
+* strict mode rejects, such as `\1` or a raw carriage return.
+*/
+function evalStringLiteral(literal) {
+	const quote = literal[0];
+	const last = literal.length - 1;
+	if (quote !== "\"" && quote !== "'" || last < 1 || literal[last] !== quote) return;
+	return cookEscapes(literal.slice(1, last), quote);
+}
+/**
+* Decodes the body of a string literal, given its quote, or a piece of a template literal
+* (`quote` undefined), as strict-mode JavaScript does. A string may not hold its own quote or a
+* raw line feed or carriage return; a template piece may, and turns `\r\n` and `\r` into `\n`.
+*/
+function cookEscapes(body, quote) {
+	let value = "";
+	let i = 0;
+	while (i < body.length) {
+		const ch = body.charAt(i);
+		if (ch !== "\\") {
+			if (quote !== void 0 && (ch === quote || ch === "\n" || ch === "\r")) return;
+			if (ch === "\r") {
+				value += "\n";
+				i += body.charAt(i + 1) === "\n" ? 2 : 1;
+			} else {
+				value += ch;
+				i += 1;
+			}
+			continue;
+		}
+		if (i + 1 >= body.length) return;
+		const escaped = body.charAt(i + 1);
+		i += 2;
+		const single = SINGLE_ESCAPES.get(escaped);
+		if (single !== void 0) {
+			value += single;
+			continue;
+		}
+		switch (escaped) {
+			case "0":
+				if (DIGIT_RE.test(body.charAt(i))) return;
+				value += "\0";
+				break;
+			case "1":
+			case "2":
+			case "3":
+			case "4":
+			case "5":
+			case "6":
+			case "7":
+			case "8":
+			case "9": return;
+			case "x": {
+				const hex = body.slice(i, i + 2);
+				if (hex.length !== 2 || !HEX_RE.test(hex)) return;
+				value += String.fromCharCode(parseInt(hex, 16));
+				i += 2;
+				break;
+			}
+			case "u": {
+				const unicode = readUnicodeEscape(body, i);
+				if (unicode === void 0) return;
+				value += unicode.char;
+				i = unicode.end;
+				break;
+			}
+			case "\r":
+				if (body[i] === "\n") i += 1;
+				break;
+			case "\n":
+			case "\u2028":
+			case "\u2029": break;
+			default: value += escaped;
+		}
+	}
+	return value;
+}
+/** Reads the part of `\uHHHH` or `\u{H…}` after the `u`. */
+function readUnicodeEscape(body, from) {
+	if (body[from] === "{") {
+		const close = body.indexOf("}", from + 1);
+		if (close === -1) return;
+		const hex = body.slice(from + 1, close);
+		if (!HEX_RE.test(hex)) return;
+		const codePoint = parseInt(hex, 16);
+		return codePoint > 1114111 ? void 0 : {
+			char: String.fromCodePoint(codePoint),
+			end: close + 1
+		};
+	}
+	const hex = body.slice(from, from + 4);
+	if (hex.length !== 4 || !HEX_RE.test(hex)) return;
+	return {
+		char: String.fromCharCode(parseInt(hex, 16)),
+		end: from + 4
+	};
+}
+const REGEX_KEYWORDS = /* @__PURE__ */ new Set([
+	"await",
+	"case",
+	"delete",
+	"do",
+	"else",
+	"in",
+	"instanceof",
+	"new",
+	"of",
+	"return",
+	"throw",
+	"typeof",
+	"void",
+	"yield"
+]);
+const WORD_RE = /[$\p{ID_Continue}\u200c\u200d]+/uy;
+const WHITESPACE_RE = /\s/;
+const LINE_TERMINATOR_RE$1 = /[\n\r\u2028\u2029]/g;
+/**
+* The values of the string and template literals in JavaScript source. A template literal's
+* value keeps its text and has `SUBSTITUTION` where each `${…}` was; the strings inside a
+* substitution are values of their own. Comments and regular expression literals are skipped;
+* whether a `/` starts a regular expression is judged from the token before it. Malformed
+* source is read on as far as it can be.
+*/
+function javaScriptStrings(source) {
+	const strings = [];
+	const frames = [{
+		kind: "code",
+		braces: 0
+	}];
+	let regexAllowed = true;
+	let afterDot = false;
+	const failedUntil = /* @__PURE__ */ new Map();
+	let i = 0;
+	while (i < source.length) {
+		const frame = frames[frames.length - 1];
+		if (frame === void 0) break;
+		const ch = source.charAt(i);
+		const next = source.charAt(i + 1);
+		if (frame.kind === "template") {
+			if (ch === "`" || ch === "$" && next === "{") {
+				const piece = cookEscapes(source.slice(frame.pieceStart, i), void 0);
+				const value = frame.value + (piece ?? "");
+				const valid = frame.valid && piece !== void 0;
+				frames.pop();
+				if (ch === "`") {
+					if (valid) strings.push(value);
+					i += 1;
+					regexAllowed = false;
+					afterDot = false;
+				} else {
+					frames.push({
+						kind: "template",
+						value: value + "﷐",
+						pieceStart: -1,
+						valid
+					});
+					frames.push({
+						kind: "code",
+						braces: 0
+					});
+					i += 2;
+					regexAllowed = true;
+					afterDot = false;
+				}
+			} else i += ch === "\\" ? 2 : 1;
+			continue;
+		}
+		if (ch === "/" && next === "/") {
+			const lineEnd = searchFrom$1(LINE_TERMINATOR_RE$1, source, i + 2);
+			i = lineEnd === -1 ? source.length : lineEnd;
+			continue;
+		}
+		if (ch === "/" && next === "*") {
+			const close = source.indexOf("*/", i + 2);
+			i = close === -1 ? source.length : close + 2;
+			continue;
+		}
+		if (ch === "/" && regexAllowed && i >= (failedUntil.get("/") ?? 0)) {
+			const end = endOfRegularExpression(source, i);
+			if (end.end !== void 0) {
+				i = end.end;
+				regexAllowed = false;
+				afterDot = false;
+				continue;
+			}
+			failedUntil.set("/", end.stop);
+		}
+		if ((ch === "\"" || ch === "'") && i >= (failedUntil.get(ch) ?? 0)) {
+			const end = endOfJavaScriptString(source, i);
+			if (end.end !== void 0) {
+				const value = evalStringLiteral(source.slice(i, end.end));
+				if (value !== void 0) strings.push(value);
+				i = end.end;
+				regexAllowed = false;
+				afterDot = false;
+				continue;
+			}
+			failedUntil.set(ch, end.stop);
+		}
+		if (ch === "`") {
+			frames.push({
+				kind: "template",
+				value: "",
+				pieceStart: i + 1,
+				valid: true
+			});
+			i += 1;
+			continue;
+		}
+		const word = wordAt(source, i);
+		if (word !== null) {
+			regexAllowed = !afterDot && REGEX_KEYWORDS.has(word[0]);
+			afterDot = false;
+			i += word[0].length;
+			continue;
+		}
+		if ((ch === "+" || ch === "-") && next === ch) {
+			regexAllowed = false;
+			afterDot = false;
+			i += 2;
+			continue;
+		}
+		if (frame.kind === "code" && frames.length > 1 && (ch === "{" || ch === "}")) {
+			if (ch === "{") frames[frames.length - 1] = {
+				kind: "code",
+				braces: frame.braces + 1
+			};
+			else if (frame.braces > 0) frames[frames.length - 1] = {
+				kind: "code",
+				braces: frame.braces - 1
+			};
+			else {
+				frames.pop();
+				const template = frames.pop();
+				if (template?.kind === "template") frames.push({
+					...template,
+					pieceStart: i + 1
+				});
+				i += 1;
+				continue;
+			}
+		}
+		if (!WHITESPACE_RE.test(ch)) {
+			regexAllowed = !")]}".includes(ch);
+			afterDot = ch === ".";
+		}
+		i += 1;
+	}
+	return strings;
+}
+/** The name, keyword or number that starts at `pos`, if one does. */
+function wordAt(source, pos) {
+	const code = source.charCodeAt(pos);
+	if (code < 128 && !(code >= 48 && code <= 57 || (code | 32) >= 97 && (code | 32) <= 122 || code === 95 || code === 36)) return null;
+	WORD_RE.lastIndex = pos;
+	return WORD_RE.exec(source);
+}
+/** Index of the first match of a global `re` at or after `from`, or -1. */
+function searchFrom$1(re, text, from) {
+	re.lastIndex = from;
+	const m = re.exec(text);
+	return m === null ? -1 : m.index;
+}
+/**
+* Where a string literal that opens at `pos` ends, or, if it doesn't close on its line, where
+* the scan stopped. A string with the same quote that starts before that stop, inside this one,
+* doesn't close either.
+*/
+function endOfJavaScriptString(source, pos) {
+	const quote = source.charAt(pos);
+	let i = pos + 1;
+	while (i < source.length) {
+		const ch = source.charAt(i);
+		if (ch === quote) return {
+			end: i + 1,
+			stop: i
+		};
+		if (ch === "\n" || ch === "\r") return {
+			end: void 0,
+			stop: i
+		};
+		if (ch === "\\") i += source.startsWith("\r\n", i + 1) ? 3 : 2;
+		else i += 1;
+	}
+	return {
+		end: void 0,
+		stop: source.length
+	};
+}
+/**
+* Where a regular expression literal that opens at `pos` ends, flags included, or, if none
+* closes on the line, where the line ends. A `/` before that is then read as a division.
+*/
+function endOfRegularExpression(source, pos) {
+	let inClass = false;
+	let i = pos + 1;
+	while (i < source.length) {
+		const ch = source.charAt(i);
+		if (LINE_TERMINATORS.includes(ch)) return {
+			end: void 0,
+			stop: i
+		};
+		if (ch === "\\") {
+			const escaped = source.charAt(i + 1);
+			if (escaped === "" || LINE_TERMINATORS.includes(escaped)) return {
+				end: void 0,
+				stop: i + 1
+			};
+			i += 2;
+			continue;
+		}
+		if (ch === "[") inClass = true;
+		else if (ch === "]") inClass = false;
+		else if (ch === "/" && !inClass) {
+			WORD_RE.lastIndex = i + 1;
+			const flags = WORD_RE.exec(source);
+			return {
+				end: i + 1 + (flags === null ? 0 : flags[0].length),
+				stop: i
+			};
+		}
+		i += 1;
+	}
+	return {
+		end: void 0,
+		stop: source.length
+	};
+}
+//#endregion
+//#region src/sugarcube-macros.ts
+/**
+* Reads SugarCube 2 macro calls the way SugarCube 2.37.3 does, so the link check sees the same
+* passage names that `<<link>>` and `<<goto>>` use when the story plays.
+*
+* Each step follows a part of SugarCube's macro parser:
+* - `findMacroTags` finds where a tag starts and ends (the parser's `lookahead` pattern);
+* - `parseMacroArgs` splits the text after the macro name into arguments (`parseArgs`);
+* - quoted arguments are evaluated as strict-mode JavaScript strings (`evalStringLiteral`).
+*
+* Of the rest of the wikifier, only comments, `<script>` elements and `<<script>>` bodies are
+* told apart; other markup, such as verbatim text, is read as markup (see
+* `findMacroPassageLinks`).
+*/
+const NAME_RE = /\/?[A-Za-z][\w-]*|[=-]/y;
+const SPACES_RE = /\s*/y;
+const LINE_TERMINATOR_RE = /[\n\r\u2028\u2029]/g;
+const SQUARE_BRACKET_OPEN_RE = /\[(?:[<>]?[Ii][Mm][Gg])?\[/y;
+const SPACE_RE = /[\s\u180e]/g;
+const NOT_SPACE_RE = /[^\s\u180e]/g;
+const VARIABLE_RE = /^[$_][$A-Z_a-z][$0-9A-Z_a-z]*/;
+const SETTINGS_OR_SETUP_RE = /^(?:settings|setup)[.[]/;
+const IMAGE_MARKUP_CHARS = "<>IiMmGg";
+/**
+* Macros that SugarCube doesn't split into arguments (`skipArgs` in 2.37.3), with their child
+* tags that do the same: `<<elseif>>` and `<<else>>` of `<<if>>`, and `<<optionsfrom>>` of
+* `<<cycle>>` and `<<listbox>>`. Their argument text is TwineScript, or for `<<capture>>`,
+* `<<unset>>` and `<<for>>` a syntax of their own; either way its strings are JavaScript strings.
+*/
+const RAW_ARGUMENT_MACROS = /* @__PURE__ */ new Set([
+	"break",
+	"capture",
+	"continue",
+	"done",
+	"else",
+	"elseif",
+	"for",
+	"if",
+	"nobr",
+	"optionsfrom",
+	"print",
+	"=",
+	"-",
+	"run",
+	"set",
+	"silent",
+	"silently",
+	"stop",
+	"switch",
+	"unset",
+	"waitforaudio"
+]);
+/**
+* How deep strings inside macro arguments are read for further calls. Stories nest two or three
+* levels; the limit keeps the work linear in the size of the text on any input.
+*/
+const MAX_STRING_DEPTH = 10;
+/** A context for reading `text`: the closer search may read four times it, plus an allowance. */
+function readContext(text) {
+	return {
+		depth: 0,
+		budget: { left: 4 * text.length + 1e5 }
+	};
+}
+function deeper(context) {
+	return {
+		depth: context.depth + 1,
+		budget: context.budget
+	};
+}
+/** Index of the first match of a global `re` at or after `from`, or -1. */
+function searchFrom(re, text, from) {
+	re.lastIndex = from;
+	const m = re.exec(text);
+	return m === null ? -1 : m.index;
+}
+/**
+* Finds the macro tags in text, in order, trying a tag at every `<<` as SugarCube's macro
+* parser does. A tag that doesn't parse is skipped, and the search goes on after its `<<`.
+*
+* Gives the same tags as SugarCube's pattern, without its backtracking: that pattern takes
+* exponential time when no `>>` follows a `<<name`, which a script passage can contain (`1<<n`).
+*/
+function findMacroTags(text) {
+	return scanTags(text).map((scanned) => scanned.tag);
+}
+function scanTags(text) {
+	const matchTagAt = tagMatcher(text);
+	const tags = [];
+	let start = text.indexOf("<<");
+	while (start !== -1) {
+		const scanned = matchTagAt(start);
+		if (scanned === void 0) start = text.indexOf("<<", start + 2);
+		else {
+			tags.push(scanned);
+			start = text.indexOf("<<", scanned.tag.end);
+		}
+	}
+	return tags;
+}
+/**
+* Returns a function that matches a tag at a `<<` in `text`. It must be called for positions in
+* increasing order.
+*
+* The arguments may contain comments, backquoted expressions, quoted strings and link markup,
+* whose `>>` doesn't end the tag. SugarCube's pattern treats such a part as a unit only if a
+* `>>` still follows it, and otherwise as plain characters; `lastClose`, the last `>>` in the
+* text, answers that in constant time. Once a part is read as plain characters, a part of the
+* same kind that starts inside it can't end before `lastClose` either, in this tag or a later
+* one, so it isn't scanned again: `scanFrom` records where each kind may next be scanned. This
+* keeps the search linear. `onWork` is told how many characters each step reads. (Exported for
+* tests; the module is not part of the package's API.)
+*/
+function tagMatcher(text, lastClose = text.lastIndexOf(">>"), onWork = () => {}) {
+	const scanFrom = /* @__PURE__ */ new Map();
+	return (start) => {
+		NAME_RE.lastIndex = start + 2;
+		const nameMatch = NAME_RE.exec(text);
+		if (nameMatch === null) {
+			onWork(2);
+			return;
+		}
+		SPACES_RE.lastIndex = NAME_RE.lastIndex;
+		SPACES_RE.exec(text);
+		const argsStart = SPACES_RE.lastIndex;
+		onWork(argsStart - start);
+		let innerCall;
+		let pos = argsStart;
+		while (pos <= lastClose) {
+			if (text.startsWith(">>", pos)) return {
+				tag: {
+					name: nameMatch[0],
+					args: text.slice(argsStart, pos),
+					start,
+					end: pos + 2
+				},
+				innerCall
+			};
+			const kind = argumentPartKindAt(text, pos);
+			const from = kind === void 0 ? void 0 : scanFrom.get(kind);
+			if (kind !== void 0 && (from === void 0 || pos >= from)) {
+				const part = scanArgumentPart(text, pos, kind);
+				onWork(part.stop - pos);
+				if (part.end !== void 0 && part.end <= lastClose) {
+					pos = part.end;
+					continue;
+				}
+				scanFrom.set(kind, part.stop);
+			}
+			if (innerCall === void 0 && startsPassageLinkCall(text, pos)) innerCall = pos;
+			onWork(1);
+			pos += 1;
+		}
+	};
+}
+/** Whether a `<<link` or `<<goto` tag, and not a longer macro name, starts at `pos`. */
+function startsPassageLinkCall(text, pos) {
+	if (!text.startsWith("<<", pos)) return false;
+	NAME_RE.lastIndex = pos + 2;
+	const name = NAME_RE.exec(text)?.[0];
+	return name === "link" || name === "goto";
+}
+/** The kind of argument part that opens at `pos`, if one does. */
+function argumentPartKindAt(text, pos) {
+	const ch = text[pos];
+	switch (ch) {
+		case "/": {
+			const next = text[pos + 1];
+			return next === "*" ? "/*" : next === "/" ? "//" : void 0;
+		}
+		case "`":
+		case "\"":
+		case "'":
+		case "[": return ch;
+		default: return;
+	}
+}
+function scanArgumentPart(text, pos, kind) {
+	switch (kind) {
+		case "/*": {
+			const close = text.indexOf("*/", pos + 2);
+			return close === -1 ? {
+				end: void 0,
+				stop: text.length
+			} : {
+				end: close + 2,
+				stop: close
+			};
+		}
+		case "//": {
+			const lineEnd = searchFrom(LINE_TERMINATOR_RE, text, pos + 2);
+			if (lineEnd === -1) return {
+				end: void 0,
+				stop: text.length
+			};
+			return {
+				end: text[lineEnd] === "\n" ? lineEnd + 1 : void 0,
+				stop: lineEnd
+			};
+		}
+		case "`":
+		case "\"":
+		case "'": return scanQuoted(text, pos, kind);
+		case "[": return scanSquareBracketed(text, pos);
+		default: throw new Error(`unhandled argument part: ${String(kind)}`);
+	}
+}
+/** A quoted part of a tag: a backslash escapes any character except a line terminator. */
+function scanQuoted(text, pos, quote) {
+	let i = pos + 1;
+	while (i < text.length) {
+		const ch = text[i];
+		if (ch === quote) return {
+			end: i + 1,
+			stop: i
+		};
+		if (ch === "\\") {
+			const next = text[i + 1];
+			if (next === void 0 || "\n\r\u2028\u2029".includes(next)) return {
+				end: void 0,
+				stop: i
+			};
+			i += 2;
+		} else i += 1;
+	}
+	return {
+		end: void 0,
+		stop: text.length
+	};
+}
+/** Link or image markup in a tag: up to the first `]]` on the same line, plus any further `]`. */
+function scanSquareBracketed(text, pos) {
+	SQUARE_BRACKET_OPEN_RE.lastIndex = pos;
+	if (!SQUARE_BRACKET_OPEN_RE.test(text)) return {
+		end: void 0,
+		stop: pos + 1
+	};
+	for (let i = SQUARE_BRACKET_OPEN_RE.lastIndex; i < text.length; i++) {
+		const ch = text[i];
+		if (ch === "\n" || ch === "\r") return {
+			end: void 0,
+			stop: i
+		};
+		if (ch === "]" && text[i + 1] === "]") {
+			let end = i + 2;
+			while (text[end] === "]") end += 1;
+			return {
+				end,
+				stop: i
+			};
+		}
+	}
+	return {
+		end: void 0,
+		stop: text.length
+	};
+}
+function lexMacroArgs(raw) {
+	const args = [];
+	let pos = searchFrom(NOT_SPACE_RE, raw, 0);
+	while (pos !== -1) {
+		const lexed = lexArgument(raw, pos);
+		if (lexed === void 0) return;
+		args.push(lexed.arg);
+		pos = searchFrom(NOT_SPACE_RE, raw, lexed.end);
+	}
+	return args;
+}
+function lexArgument(raw, pos) {
+	const first = raw[pos];
+	switch (first) {
+		case "`": {
+			const end = slurpQuote(raw, pos + 1, "`");
+			return end === void 0 ? void 0 : {
+				arg: {
+					kind: "expression",
+					code: raw.slice(pos + 1, end - 1)
+				},
+				end
+			};
+		}
+		case "\"":
+		case "'": {
+			const end = slurpQuote(raw, pos + 1, first);
+			if (end === void 0) return;
+			const value = evalStringLiteral(raw.slice(pos, end));
+			return value === void 0 ? void 0 : {
+				arg: {
+					kind: "string",
+					value
+				},
+				end
+			};
+		}
+		case "[": {
+			const end = lexSquareBracketed(raw, pos + 1);
+			return end === void 0 ? void 0 : {
+				arg: { kind: "markup" },
+				end
+			};
+		}
+		default: {
+			const space = searchFrom(SPACE_RE, raw, pos + 1);
+			const end = space === -1 ? raw.length : space;
+			return {
+				arg: {
+					kind: "word",
+					text: raw.slice(pos, end)
+				},
+				end
+			};
+		}
+	}
+}
+/**
+* Reads a quoted argument from just after its opening quote. A newline, or a backslash before a
+* newline, ends it unterminated. Returns the index after the closing quote.
+*/
+function slurpQuote(raw, from, endQuote) {
+	let i = from;
+	while (i < raw.length) {
+		const ch = raw[i];
+		if (ch === endQuote) return i + 1;
+		if (ch === "\n") return;
+		if (ch === "\\") {
+			const next = raw[i + 1];
+			if (next === void 0 || next === "\n") return;
+			i += 2;
+		} else i += 1;
+	}
+}
+/**
+* Reads link or image markup from just after its first `[`, counting nested brackets.
+* Returns the index after the closing `]]`.
+*/
+function lexSquareBracketed(raw, from) {
+	let i = from;
+	while (i < raw.length && IMAGE_MARKUP_CHARS.includes(raw.charAt(i))) i += 1;
+	if (raw[i] !== "[") return;
+	i += 1;
+	let depth = 2;
+	while (i < raw.length) {
+		const ch = raw[i];
+		i += 1;
+		switch (ch) {
+			case "\\": {
+				const next = raw[i];
+				if (next === void 0 || next === "\n") return;
+				i += 1;
+				break;
+			}
+			case "\n": return;
+			case "[":
+				depth += 1;
+				break;
+			case "]":
+				depth -= 1;
+				if (depth < 0) return;
+				if (depth === 1 && raw[i] === "]") return i + 1;
+		}
+	}
+}
+/** An argument's value, following SugarCube's conversions. */
+function argValue(arg) {
+	switch (arg.kind) {
+		case "string": return {
+			type: "string",
+			value: arg.value
+		};
+		case "expression": return { type: "other" };
+		case "markup": return { type: "markup" };
+		case "word": return bareWord(arg.text);
+		default: throw new Error(`unhandled macro argument: ${JSON.stringify(arg)}`);
+	}
+}
+/** A bare word's value, following SugarCube's conversions. */
+function bareWord(word) {
+	if (VARIABLE_RE.test(word) || SETTINGS_OR_SETUP_RE.test(word)) return { type: "other" };
+	switch (word) {
+		case "null": return { type: "null" };
+		case "undefined":
+		case "true":
+		case "false": return { type: "other" };
+		case "NaN": return {
+			type: "number",
+			value: NaN
+		};
+		default: {
+			const value = Number(word);
+			return Number.isNaN(value) ? {
+				type: "string",
+				value: word
+			} : {
+				type: "number",
+				value
+			};
+		}
+	}
+}
+/** The passage name an argument gives, if it can be known without playing the story. */
+function passageName(arg) {
+	switch (arg.type) {
+		case "string": return arg.value.includes("﷐") ? void 0 : arg.value;
+		case "number": return String(arg.value);
+		case "markup":
+		case "null":
+		case "other": return;
+		default: throw new Error(`unhandled macro argument: ${JSON.stringify(arg)}`);
+	}
+}
+/**
+* The argument that names the passage in a `<<link>>` or `<<goto>>` call:
+* - `<<link linkText [passageName]>>`, unless the first argument is link or image markup, which
+*   then names the passage itself and any further argument is ignored;
+* - `<<goto passageName>>`.
+*
+* In text built from a template literal, a bare word with a `${…}` in it may become several
+* words in play, so no argument after it is known.
+*/
+function passageArgument(macro, lexed) {
+	const index = macro === "link" ? 1 : 0;
+	if (lexed.slice(0, index + 1).some((arg) => arg.kind === "word" && arg.text.includes("﷐"))) return;
+	const args = lexed.map(argValue);
+	switch (macro) {
+		case "link": {
+			const [label, passage] = args;
+			return label === void 0 || label.type === "markup" || label.type === "null" ? void 0 : passage;
+		}
+		case "goto": return args[0];
+		default: throw new Error(`unhandled macro: ${String(macro)}`);
+	}
+}
+function isPassageLinkMacro(name) {
+	return name === "goto" || name === "link";
+}
+/** The passage a `<<link>>` or `<<goto>>` tag names itself, if it can be known before play. */
+function ownPassageLink(tag, lexed) {
+	if (!isPassageLinkMacro(tag.name)) return;
+	const arg = passageArgument(tag.name, lexed);
+	const passage = arg === void 0 ? void 0 : passageName(arg);
+	return passage === void 0 ? void 0 : {
+		macro: tag.name,
+		passage
+	};
+}
+/**
+* The passages a tag names: its own, if it is a `<<link>>` or `<<goto>>` call, then those of the
+* calls inside the strings of its arguments, which the macro may print or pass on
+* (`<<set _out to '<<link "Go" "Room">><</link>>'>>`). The arguments of the macros SugarCube
+* doesn't split are read as JavaScript; in others, a backquoted expression is.
+*/
+function tagPassageLinks(tag, context) {
+	if (RAW_ARGUMENT_MACROS.has(tag.name)) return javaScriptPassageLinks(tag.args, context);
+	const lexed = lexMacroArgs(tag.args);
+	if (lexed === void 0) return [];
+	const own = ownPassageLink(tag, lexed);
+	const inner = lexed.flatMap((arg) => {
+		switch (arg.kind) {
+			case "string": return markupPassageLinks(arg.value, deeper(context));
+			case "expression": return javaScriptPassageLinks(arg.code, context);
+			case "markup":
+			case "word": return [];
+			default: throw new Error(`unhandled macro argument: ${JSON.stringify(arg)}`);
+		}
+	});
+	return own === void 0 ? inner : [own, ...inner];
+}
+/**
+* The passage named by a `<<link>>` or `<<goto>>` that appears unquoted inside another tag's
+* arguments, at `start`. SugarCube never sees such an outer "tag" when its `<<` lies in text it
+* reads as something else, such as link markup (`[[<<-- Back|Prev]]`); the call inside it then
+* runs. The call ends where the outer tag ends.
+*/
+function innerPassageLink(matchTagAt, start) {
+	const inner = matchTagAt(start)?.tag;
+	const lexed = inner === void 0 ? void 0 : lexMacroArgs(inner.args);
+	return inner === void 0 || lexed === void 0 ? void 0 : ownPassageLink(inner, lexed);
+}
+const REGION_OPEN_RE = /\/\/|\/\*|\/%|<!--|<[Ss][Cc][Rr][Ii][Pp][Tt]/g;
+const HAS_SCRIPT_OPEN_RE = /<[Ss][Cc][Rr][Ii][Pp][Tt]/;
+const SCRIPT_CLOSE_RE = /<\/[Ss][Cc][Rr][Ii][Pp][Tt]>|[\r\u2028\u2029]/g;
+const COMMENT_CLOSE_RES = {
+	"/*": /\*\/|[\r\u2028\u2029]/g,
+	"/%": /%\/|[\r\u2028\u2029]/g,
+	"<!--": /-->|[\r\u2028\u2029]/g
+};
+/**
+* Returns a function that finds where a comment that opens at `start` ends, as SugarCube's
+* `commentByBlock` parser reads it, or `undefined` if it isn't closed. Calls of one kind must come
+* in increasing order: a search that fails stops at a line terminator or the end, and a later one
+* of the same kind that starts before that stop fails too, so it isn't made.
+*/
+function commentReader(text) {
+	const failedUntil = /* @__PURE__ */ new Map();
+	return (kind, start) => {
+		if (start < (failedUntil.get(kind) ?? -1)) return;
+		const re = COMMENT_CLOSE_RES[kind];
+		re.lastIndex = start + kind.length;
+		const m = re.exec(text);
+		if (m !== null && m[0].length > 1) return m.index + m[0].length;
+		failedUntil.set(kind, m === null ? text.length : m.index);
+	};
+}
+/**
+* Returns a function that reads a `<script>` element whose opener starts at a position, as
+* SugarCube's `verbatimScriptTag` parser reads it: the opener up to its `>`, then the content
+* up to the first `<\/script>`. Calls must come in increasing order; each part of the text is
+* searched once.
+*/
+function scriptElementReader(text) {
+	let angle = -1;
+	let noAngleAfter = Infinity;
+	let failedBefore = -1;
+	let noCloseAfter = Infinity;
+	return (start) => {
+		if (start + 7 >= noAngleAfter) return {
+			openerEnd: void 0,
+			close: void 0
+		};
+		if (angle < start + 7) {
+			angle = text.indexOf(">", start + 7);
+			if (angle === -1) {
+				noAngleAfter = start + 7;
+				return {
+					openerEnd: void 0,
+					close: void 0
+				};
+			}
+		}
+		const openerEnd = angle + 1;
+		if (openerEnd < failedBefore || openerEnd >= noCloseAfter) return {
+			openerEnd,
+			close: void 0
+		};
+		SCRIPT_CLOSE_RE.lastIndex = openerEnd;
+		const m = SCRIPT_CLOSE_RE.exec(text);
+		if (m === null) {
+			noCloseAfter = openerEnd;
+			return {
+				openerEnd,
+				close: void 0
+			};
+		}
+		if (m[0].length === 1) {
+			failedBefore = m.index;
+			return {
+				openerEnd,
+				close: void 0
+			};
+		}
+		return {
+			openerEnd,
+			close: m.index
+		};
+	};
+}
+/**
+* Returns a function that finds the tag closing the `<<script>>` body that `opener` opens, as
+* SugarCube's `parseBody` finds it: scanning tags from every `<<` after the opener, without
+* skipping anything, for the first `<<\/script>>` or `<<endscript>>` that isn't matched by a
+* later `<<script>>`. (It doesn't reproduce parseBody's rejection of a closing tag with
+* arguments, nor its resuming inside the arguments of a tag whose name starts with `/` or
+* `end`.)
+*
+* The tags found from the start of the text are those parseBody finds from any opener among
+* them, so for such an opener the answer takes constant time. An opener the walk reached after
+* a comment may not be among them, when a tag that starts in the comment runs over it; then the
+* scan starts at the body and goes on until it finds the closer or reaches a tag of that list,
+* whose answers it then uses. All such scans in one reading of a passage, strings included, stop
+* once they have read four times as many characters as the passage has, plus a fixed allowance
+* (`budget`, see `readContext`); on input built to make them read more, the openers after that
+* are taken as unclosed. That keeps the time linear. (Exported for tests; the module is not part
+* of the package's API.)
+*/
+function scriptBodyCloser(text, budget) {
+	const tags = findMacroTags(text);
+	const indexByStart = new Map(tags.map((tag, index) => [tag.start, index]));
+	const lastClose = text.lastIndexOf(">>");
+	const spend = (characters) => {
+		budget.left -= characters;
+	};
+	const step = (tag) => tag.name === "script" ? 1 : tag.name === "/script" || tag.name === "endscript" ? -1 : 0;
+	const balance = [0];
+	tags.forEach((tag, k) => balance.push((balance[k] ?? 0) + step(tag)));
+	const firstBelow = [];
+	const candidates = [];
+	for (let k = balance.length - 1; k >= 0; k--) {
+		const here = balance[k] ?? 0;
+		let top = candidates[candidates.length - 1];
+		while (top !== void 0 && (balance[top] ?? 0) >= here) {
+			candidates.pop();
+			top = candidates[candidates.length - 1];
+		}
+		firstBelow[k] = top;
+		candidates.push(k);
+	}
+	/**
+	* The closer when `open` bodies are open just before `tags[index]`: each hop to
+	* `firstBelow` closes one. `open` is at most one more than the openers scanned to get here.
+	*/
+	const closeFrom = (index, open) => {
+		let k = index;
+		for (let left = open; left > 0 && k !== void 0; left--) k = firstBelow[k];
+		return k === void 0 ? void 0 : tags[k - 1];
+	};
+	return (opener) => {
+		const index = indexByStart.get(opener.start);
+		if (index !== void 0) return closeFrom(index + 1, 1);
+		const matchTagAt = tagMatcher(text, lastClose, spend);
+		let open = 1;
+		let from = opener.end;
+		while (budget.left >= 0) {
+			const start = text.indexOf("<<", from);
+			spend((start === -1 ? text.length : start) - from);
+			if (start === -1) return;
+			const known = indexByStart.get(start);
+			if (known !== void 0) return closeFrom(known, open);
+			const tag = matchTagAt(start)?.tag;
+			if (tag === void 0) {
+				from = start + 2;
+				continue;
+			}
+			open += step(tag);
+			if (open === 0) return tag;
+			from = tag.end;
+		}
+	};
+}
+/** Adds `more` to the end of `links`, without spreading, which fails for very long lists. */
+function append(links, more) {
+	for (const link of more) links.push(link);
+}
+/**
+* The passages that `<<link>>` and `<<goto>>` calls in passage markup name. Calls whose passage
+* is known only in play (a variable or an expression) are left out. A tag's own passage comes
+* before those of the calls inside its arguments' strings.
+*
+* The markup is walked in order, as SugarCube's wikifier walks it, with a tag tried at each
+* `<<` the walk reaches. Of the wikifier's other parsers, only those whose text holds no call
+* are told apart: comments (`/* … *` + `/`, `/% … %/`, `<!-- … -->`), whose calls never run,
+* and `<script>` elements and `<<script>>` bodies, which are JavaScript: only the calls in their
+* strings are read (see `findJavaScriptPassageLinks`). Everything else, verbatim text included,
+* is read as markup.
+*
+* Where this differs from SugarCube:
+* - a comment or a `<<script>>` body is skipped whole, even where `parseBody` ends a container
+*   such as `<<if>>` at a closing tag inside it and the rest then runs;
+* - a `/*`, `<!--` or `<script` inside other markup that holds no call, such as link markup or a
+*   `<style>` element, still starts a comment or an element;
+* - a `<<` in such other markup still starts a tag. When that tag runs over a `<<link` or
+*   `<<goto` outside the parts of its arguments that the tag pattern reads as units, that call
+*   is still read (see `innerPassageLink`), even where the tag's arguments would be JavaScript,
+*   as the check always read it. One that such a part covers is lost: a quoted string, or a `//`
+*   part up to a line feed (italics, a URL) when a `>>` follows later; and a `<<script>>` body
+*   the tag runs over is read as markup. The same recovery also reads a call inside a stray tag
+*   that SugarCube does see, and rejects as an unknown macro (`<<Back <<goto R>>`);
+* - a `<<script>>` body's end is found as `parseBody` finds it, except that parseBody rejects a
+*   closing tag with arguments, and resumes inside the arguments of a tag whose name starts with
+*   `/` or `end`;
+* - the lines of a `<<nobr>>` body, and of every passage when a story sets
+*   `Config.passages.nobr`, are not joined before they are read (see `storyInspect` for passages
+*   tagged `nobr`).
+*/
+function findMacroPassageLinks(text) {
+	return markupPassageLinks(text, readContext(text));
+}
+function markupPassageLinks(text, context) {
+	if (context.depth > MAX_STRING_DEPTH || !text.includes("<<") && !HAS_SCRIPT_OPEN_RE.test(text)) return [];
+	const matchTagAt = tagMatcher(text);
+	const matchInnerTagAt = tagMatcher(text);
+	const readComment = commentReader(text);
+	const readScriptElement = scriptElementReader(text);
+	let findScriptCloser;
+	const links = [];
+	/** Reads the region `opener` opens, adding the calls in a `<script>` element; returns where the walk goes on. */
+	const regionEnd = (opener) => {
+		const start = opener.index;
+		const kind = opener[0];
+		switch (kind) {
+			case "//": return start + 2;
+			case "/*":
+			case "/%":
+			case "<!--": return readComment(kind, start) ?? start + kind.length;
+			default: {
+				const element = readScriptElement(start);
+				if (element.openerEnd === void 0) return start + 1;
+				if (element.close === void 0) return element.openerEnd;
+				append(links, javaScriptPassageLinks(text.slice(element.openerEnd, element.close), context));
+				return element.close + 9;
+			}
+		}
+	};
+	let macro = -2;
+	let region;
+	let pos = 0;
+	for (;;) {
+		if (macro !== -1 && macro < pos) macro = text.indexOf("<<", pos);
+		if (region !== null && (region === void 0 || region.index < pos)) {
+			REGION_OPEN_RE.lastIndex = pos;
+			region = REGION_OPEN_RE.exec(text);
+		}
+		if (region !== null && (macro === -1 || region.index < macro)) {
+			pos = regionEnd(region);
+			continue;
+		}
+		if (macro === -1) return links;
+		const scanned = matchTagAt(macro);
+		if (scanned === void 0) {
+			pos = macro + 2;
+			continue;
+		}
+		const { tag, innerCall } = scanned;
+		append(links, tagPassageLinks(tag, context));
+		if (innerCall !== void 0) {
+			const inner = innerPassageLink(matchInnerTagAt, innerCall);
+			if (inner !== void 0) links.push(inner);
+		}
+		pos = tag.end;
+		if (tag.name === "script") {
+			findScriptCloser ??= scriptBodyCloser(text, context.budget);
+			const closer = findScriptCloser(tag);
+			if (closer !== void 0) {
+				append(links, javaScriptPassageLinks(text.slice(tag.end, closer.start), context));
+				pos = closer.end;
+			}
+		}
+	}
+}
+/**
+* The passages that `<<link>>` and `<<goto>>` calls in the strings of JavaScript source name,
+* such as a script passage or a `<<script>>` body: `$.wiki('<<goto "Room">>')`. Code outside
+* the strings isn't markup, so a call put together while the story plays, such as
+* `'<<goto "' + target + '">>'`, names no passage here.
+*/
+function findJavaScriptPassageLinks(source) {
+	return javaScriptPassageLinks(source, readContext(source));
+}
+/**
+* What JavaScript source must contain for one of its string or template literals to hold a call
+* that is read. A value holding `<<`: each `<` in it is written as `<`, `\<`, `\x3c`, `\u003c` or
+* `\u{…}`, two can be next to each other with only line continuations between, and the first
+* is `<` or `\<` (then the source holds `<<` or `<\`) or one of the others. Or a value holding a
+* `<script>` element, whose own strings can make `<<` from escapes the outer string encodes.
+*/
+const MAY_HOLD_MACRO_RE = /<<|<\\|\\x3c|\\u003c|\\u\{|<script/i;
+function javaScriptPassageLinks(source, context) {
+	if (context.depth >= MAX_STRING_DEPTH || !MAY_HOLD_MACRO_RE.test(source)) return [];
+	const inner = deeper(context);
+	const links = [];
+	for (const value of javaScriptStrings(source)) append(links, markupPassageLinks(value, inner));
+	return links;
+}
 //#endregion
 //#region src/inspect.ts
 /**
@@ -5359,8 +6483,15 @@ function storyToJSON(story) {
 * - `[[Display Text|PassageName]]`   (Twine 1 / Harlowe pipe)
 * - `<<goto "PassageName">>`         (SugarCube macro)
 * - `<<link "Display" "PassageName">>`  (SugarCube macro)
+*
+* SugarCube macro arguments may be double- or single-quoted, with backslash escapes, or bare
+* words; a passage named by a variable or an expression is known only in play and is skipped.
+* Macro calls are also read inside the quoted strings of other macros' arguments, and inside the
+* strings of `<<script>>` bodies and `<script>` elements; calls in comments are not read. A
+* script passage (`isScript`) is JavaScript, so its macro calls are read only inside its strings.
+* See `sugarcube-macros.ts` for the details and the known differences from SugarCube.
 */
-function extractLinksFromText(text) {
+function extractLinksFromText(text, isScript) {
 	const targets = /* @__PURE__ */ new Set();
 	const wikiLinkRe = /\[\[([^\]]+)\]\]/g;
 	let m;
@@ -5378,12 +6509,36 @@ function extractLinksFromText(text) {
 		}
 		targets.add(content.trim());
 	}
-	const gotoRe = /<<goto\s+["']([^"']+)["']\s*>>/g;
-	while ((m = gotoRe.exec(text)) !== null) targets.add(m[1]);
-	const linkMacroRe = /<<link\s+["'][^"']*["']\s+["']([^"']+)["']\s*>>/g;
-	while ((m = linkMacroRe.exec(text)) !== null) targets.add(m[1]);
+	const macroLinks = isScript ? findJavaScriptPassageLinks(text) : findMacroPassageLinks(text);
+	for (const macro of ["goto", "link"]) for (const link of macroLinks) if (link.macro === macro) targets.add(link.passage);
 	return [...targets];
 }
+/** Passages SugarCube runs from their raw text, never joining their lines. */
+const RAW_TEXT_PASSAGES = /* @__PURE__ */ new Set([
+	"StoryInit",
+	"PassageReady",
+	"PassageDone"
+]);
+/**
+* A passage's text as SugarCube reads it for its links. A passage tagged `nobr` has its line
+* breaks joined (`Passage.processText`): leading and trailing ones removed, each run inside made
+* one space. Script passages, `init`-tagged passages, StoryInit, PassageReady and PassageDone are
+* run from their raw text, so they keep theirs.
+*/
+function textAsRead(p) {
+	return hasTag(p, "nobr") && !hasTag(p, "script") && !hasTag(p, "init") && !RAW_TEXT_PASSAGES.has(p.name) ? joinLines(p.text) : p.text;
+}
+/**
+* What SugarCube's `text.replace(/^\n+|\n+$/g, '').replace(/\n+/g, ' ')` gives, without that
+* pattern's backtracking, which takes quadratic time on a long run of line feeds.
+*/
+function joinLines(text) {
+	let start = 0;
+	while (text[start] === "\n") start += 1;
+	let end = text.length;
+	while (end > start && text[end - 1] === "\n") end -= 1;
+	return text.slice(start, end).replace(/\n+/g, " ");
+}
 /**
 * Inspect a story and return its full structural map.
 *
@@ -5423,7 +6578,7 @@ function storyInspect(story) {
 			}
 			list.push(p.name);
 		}
-		const targets = extractLinksFromText(p.text);
+		const targets = extractLinksFromText(textAsRead(p), hasTag(p, "script"));
 		links.set(p.name, targets);
 	}
 	const brokenLinks = [];
@@ -5594,6 +6749,7 @@ function validateConfig(data) {
 	]) if (key in obj && typeof obj[key] !== "boolean") errors.push(`"${key}" must be a boolean.`);
 	for (const key of [
 		"sources",
+		"exclude",
 		"formatPaths",
 		"formatIndices",
 		"formatUrls",