@rohal12/twee-ts 1.18.0 → 1.18.2

package/dist/index.js

@@ -1,7 +1,7 @@
 import * as nodePath from "node:path";
 import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { accessSync, chmodSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, watch as watch$1, writeFileSync } from "node:fs";
+import { accessSync, chmodSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, watch as watch$1, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 //#region src/ifid.ts
@@ -1577,10 +1577,9 @@ function readUTF8(filename, diagnostics) {
 function readBase64(filename) {
 	return readFileSync(filename).toString("base64");
 }
-/** Get the filename without extension, falling back to the full basename for dotfiles. */
+/** Get the filename without extension, a dotfile keeps its whole name. */
 function baseNameWithoutExt(filename) {
-	const { name, ext } = parse(filename);
-	return name || ext;
+	return parse(filename).name;
 }
 //#endregion
 //#region src/formats.ts
@@ -1600,6 +1599,89 @@ function stripSetupFunction(chunk) {
 	for (const match of chunk.matchAll(SETUP_FUNCTION_PROPERTY)) lastIndex = match.index;
 	return lastIndex === -1 ? void 0 : chunk.slice(0, lastIndex) + "}";
 }
+/** Index after the whitespace and `//` or block comments starting at `i`. */
+function skipTrivia(text, i) {
+	let pos = i;
+	for (;;) {
+		const ch = text[pos];
+		if (ch !== void 0 && /\s/.test(ch)) pos++;
+		else if (text.startsWith("//", pos)) {
+			const newline = text.indexOf("\n", pos);
+			pos = newline === -1 ? text.length : newline + 1;
+		} else if (text.startsWith("/*", pos)) {
+			const close = text.indexOf("*/", pos + 2);
+			pos = close === -1 ? text.length : close + 2;
+		} else return pos;
+	}
+}
+/** Index after the quoted string starting at `i` (a quote character); template literals nest `${…}`. */
+function skipString(text, i) {
+	const quote = text[i];
+	let pos = i + 1;
+	while (pos < text.length) {
+		const ch = text[pos];
+		if (ch === "\\") pos += 2;
+		else if (ch === quote) return pos + 1;
+		else if (quote === "`" && ch === "$" && text[pos + 1] === "{") {
+			const close = findClosingBrace(text, pos + 1);
+			if (close === -1) return text.length;
+			pos = close + 1;
+		} else pos++;
+	}
+	return text.length;
+}
+function startsComment(text, pos) {
+	return text[pos] === "/" && (text[pos + 1] === "/" || text[pos + 1] === "*");
+}
+function startsString(text, pos) {
+	const ch = text[pos];
+	return ch === "\"" || ch === "'" || ch === "`";
+}
+/** Index of the `}` matching the `{` at `open`, skipping comments and strings; -1 when unbalanced. */
+function findClosingBrace(text, open) {
+	let depth = 0;
+	let pos = open;
+	while (pos < text.length) if (startsComment(text, pos)) pos = skipTrivia(text, pos);
+	else if (startsString(text, pos)) pos = skipString(text, pos);
+	else {
+		if (text[pos] === "{") depth++;
+		else if (text[pos] === "}" && --depth === 0) return pos;
+		pos++;
+	}
+	return -1;
+}
+const STORY_FORMAT = "storyFormat";
+const IDENTIFIER_CHAR = /[\w$]/;
+/**
+* Locate the object literal passed to `storyFormat(` as `[start, end)` offsets, ignoring comments and
+* strings outside it and never evaluating anything. Without such a call, the first `{` outside comments
+* and strings starts the object. When its closing brace cannot be matched (a Harlowe setup function can
+* hold regular expression literals), the last `}` of the file ends it.
+*/
+function locateFormatObject(text) {
+	let start = -1;
+	let firstBrace = -1;
+	let pos = 0;
+	while (pos < text.length && start === -1) if (startsComment(text, pos)) pos = skipTrivia(text, pos);
+	else if (startsString(text, pos)) pos = skipString(text, pos);
+	else if (text[pos] === "{") {
+		if (firstBrace === -1) firstBrace = pos;
+		pos++;
+	} else if (text.startsWith(STORY_FORMAT, pos) && !IDENTIFIER_CHAR.test(text[pos - 1] ?? "")) {
+		const paren = skipTrivia(text, pos + 11);
+		const brace = text[paren] === "(" ? skipTrivia(text, paren + 1) : -1;
+		if (text[brace] === "{") start = brace;
+		pos += 11;
+	} else pos++;
+	if (start === -1) start = firstBrace;
+	if (start === -1) return void 0;
+	const close = findClosingBrace(text, start);
+	const end = close === -1 ? text.lastIndexOf("}") : close;
+	return end < start ? void 0 : {
+		start,
+		end: end + 1
+	};
+}
 /**
 * Parse the format object at `start`–`end` of `text`: strict JSON first (fast), then the
 * JavaScript literal subset formats use. Error positions point into `text`.
@@ -1624,6 +1706,8 @@ function parseFormatObject(text, start, end) {
 	}
 }
 /** Check a parsed format object's fields. Per spec, `name` is optional; `version` and `source` are required. */
+/** The name given to a format.js that names no format. */
+const UNNAMED_FORMAT_NAME = "Untitled Story Format";
 function toFormatJSON(raw) {
 	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {
 		ok: false,
@@ -1643,7 +1727,7 @@ function toFormatJSON(raw) {
 		reason: `Story format version ${JSON.stringify(obj.version)} is not a SemVer version.`
 	};
 	const data = {
-		name: typeof obj.name === "string" ? obj.name : "Untitled Story Format",
+		name: typeof obj.name === "string" ? obj.name : UNNAMED_FORMAT_NAME,
 		version: obj.version,
 		source: obj.source,
 		proofing: obj.proofing === true
@@ -1668,15 +1752,14 @@ function toFormatJSON(raw) {
 * `harlowe-3` directory or a direct download.
 */
 function decodeFormatJSON(source) {
-	const first = source.indexOf("{");
-	const last = source.lastIndexOf("}");
-	if (first === -1 || last < first) return {
+	const located = locateFormatObject(source);
+	if (located === void 0) return {
 		ok: false,
 		reason: "Could not find Twine 2 style story format JSON chunk."
 	};
-	const parsed = parseFormatObject(source, first, last + 1);
+	const parsed = parseFormatObject(source, located.start, located.end);
 	if (parsed.ok) return toFormatJSON(parsed.value);
-	const stripped = stripSetupFunction(source.slice(first, last + 1));
+	const stripped = stripSetupFunction(source.slice(located.start, located.end));
 	const retried = stripped === void 0 ? void 0 : parseFormatObject(stripped, 0, stripped.length);
 	if (retried?.ok) return toFormatJSON(retried.value);
 	return {
@@ -1980,16 +2063,17 @@ function readFormatSource(format, diagnostics) {
 /**
 * Writes `data` to `path` so that a reader sees either the previous file or the complete new
 * one, never a partly written file. The data goes to a temporary file in the same folder,
-* which is then renamed over `path`. When `path` is a symlink, the file it points to is
-* replaced, and an existing file keeps its permissions.
+* which is then renamed over `path`. When `path` is a symlink (even a dangling one, or a chain of links), the file it
+* finally points to is replaced or created and the link stays, and an existing file keeps its permissions.
 *
 * On failure (a full disk, a missing folder) the temporary file is removed, `path` is left
 * as it was, and the error is thrown with `path` in its message and its original `code`.
 */
 function writeFileAtomic(path, data) {
-	const target = followSymlink(path);
-	const temp = join(dirname(target), `.${basename(target)}.${process.pid}-${randomBytes(6).toString("hex")}.tmp`);
+	let temp;
 	try {
+		const target = resolveWriteTarget(path);
+		temp = join(dirname(target), `.${basename(target)}.${process.pid}-${randomBytes(6).toString("hex")}.tmp`);
 		writeFileSync(temp, data, {
 			encoding: "utf-8",
 			flag: "wx"
@@ -1997,17 +2081,25 @@ function writeFileAtomic(path, data) {
 		keepPermissions(target, temp);
 		renameSync(temp, target);
 	} catch (e) {
-		rmSync(temp, { force: true });
+		if (temp !== void 0) rmSync(temp, { force: true });
 		throw writeError(path, e);
 	}
 }
-/** The file a symlink at `path` points to, or `path` itself (also when it doesn't exist yet). */
-function followSymlink(path) {
-	try {
-		return realpathSync(path);
-	} catch {
-		return path;
+/** Links followed before a path counts as a cycle (Linux stops at 40 as well). */
+const MAX_LINK_DEPTH = 40;
+/**
+* The file a symlink at `path` finally points to, or `path` itself when it is no link. Links are
+* followed one by one, so a link whose target does not exist yet (absolute, relative, or a chain
+* of them) still resolves to the file that should be created. A cycle or an unreadable link throws.
+*/
+function resolveWriteTarget(path) {
+	let current = path;
+	for (let depth = 0; depth <= MAX_LINK_DEPTH; depth++) {
+		const stat = lstatSync(current, { throwIfNoEntry: false });
+		if (stat === void 0 || !stat.isSymbolicLink()) return current;
+		current = resolve(dirname(current), readlinkSync(current));
 	}
+	throw Object.assign(/* @__PURE__ */ new Error(`ELOOP: too many levels of symbolic links, ${path}`), { code: "ELOOP" });
 }
 /**
 * Gives `temp` the permission bits of `target`, when `target` exists. Best effort: on a file
@@ -2119,31 +2211,37 @@ function clearIndexCache() {
 /** Requests in progress, by what they fetch, so concurrent compiles make each request once. */
 const sharedRequests = /* @__PURE__ */ new Map();
 /**
-* Runs `start` once for all callers that ask for `key` while it is in progress. A caller whose
-* `signal` aborts stops waiting at once and rejects with the signal's reason; the request
-* itself is aborted (through the signal `start` receives) once no caller waits on it.
+* Runs `start` once for all callers that ask for `key` while it is in progress. Each caller waits
+* under its own limits: a caller whose `signal` aborts, or whose `timeout` passes, stops waiting
+* at once and rejects, while the others keep waiting. The request itself is aborted (through
+* the signal `start` receives) once no caller waits on it. `start` must not depend on any one
+* caller: what differs between callers belongs after the shared result.
 */
-function shareRequest(key, signal, start) {
+function shareRequest(key, { signal, timeout, timedOut }, start) {
 	if (signal?.aborted) return Promise.reject(signal.reason);
 	const request = sharedRequests.get(key) ?? startSharedRequest(key, start);
 	request.waiters++;
 	return new Promise((resolve, reject) => {
 		let waiting = true;
+		let timer;
 		const stopWaiting = () => {
 			if (!waiting) return;
 			waiting = false;
 			signal?.removeEventListener("abort", onAbort);
+			clearTimeout(timer);
 			request.waiters--;
 		};
-		const onAbort = () => {
+		const giveUp = (reason) => {
 			stopWaiting();
 			if (request.waiters === 0) {
 				if (sharedRequests.get(key) === request) sharedRequests.delete(key);
-				request.controller.abort(signal?.reason);
+				request.controller.abort(reason);
 			}
-			reject(signal?.reason);
+			reject(reason);
 		};
+		const onAbort = () => giveUp(signal?.reason);
 		signal?.addEventListener("abort", onAbort, { once: true });
+		if (timeout > 0 && timeout <= MAX_TIMER_DELAY) timer = setTimeout(() => giveUp(timedOut()), timeout);
 		request.promise.then((value) => {
 			stopWaiting();
 			resolve(value);
@@ -2173,20 +2271,32 @@ function requestTimeout(options) {
 	if (!(timeout >= 0)) throw new RangeError(`A story format request timeout must be 0 or more milliseconds, not ${timeout}`);
 	return timeout;
 }
+/** How one caller waits for `url`: under its own signal and timeout. `what` names the request in errors. */
+function waitOptions(options, what, url) {
+	const timeout = requestTimeout(options);
+	return {
+		signal: options.signal,
+		timeout,
+		timedOut: () => /* @__PURE__ */ new Error(`Failed to ${what} from ${url}: timed out after ${timeout} ms`)
+	};
+}
 /**
-* Fetch `url` as text, aborting when `signal` does or after `timeout` milliseconds (0: no limit).
-* `what` names the request in errors, as in "Failed to <what> from <url>".
+* Fetch `url` as bytes, aborting when `signal` does. `what` names the request in errors, as in
+* "Failed to <what> from <url>". The bytes are returned undecoded, so checksums cover what was served.
 */
-async function fetchText(url, what, signal, timeout) {
-	const limit = timeout > 0 && timeout <= MAX_TIMER_DELAY ? AbortSignal.timeout(timeout) : void 0;
-	try {
-		const res = await fetch(url, { signal: limit ? AbortSignal.any([signal, limit]) : signal });
-		if (!res.ok) throw new Error(`Failed to ${what} from ${url}: ${res.status} ${res.statusText}`);
-		return await res.text();
-	} catch (e) {
-		if (limit?.aborted && !signal.aborted) throw new Error(`Failed to ${what} from ${url}: timed out after ${timeout} ms`, { cause: e });
-		throw e;
-	}
+async function fetchBytes(url, what, signal) {
+	const res = await fetch(url, { signal });
+	if (!res.ok) throw new Error(`Failed to ${what} from ${url}: ${res.status} ${res.statusText}`);
+	return new Uint8Array(await res.arrayBuffer());
+}
+/** Download a format.js once for every caller in this process that asks for `url` meanwhile. */
+function shareDownload(url, options) {
+	return shareRequest(`download\0${url}`, waitOptions(options, "download format", url), (signal) => fetchBytes(url, "download format", signal));
+}
+/** Decode a downloaded format.js as local ones are (UTF-8, else Windows-1252), without a leading BOM. */
+function decodeDownload(bytes, url) {
+	const { text } = decodeText(bytes, url);
+	return text.charCodeAt(0) === 65279 ? text.slice(1) : text;
 }
 /** Validate that a JSON value is a valid SFAIndexEntry. */
 function isValidEntry(val) {
@@ -2208,9 +2318,8 @@ async function fetchIndex(url, options = {}) {
 	options.signal?.throwIfAborted();
 	const cached = indexCache.get(url);
 	if (cached) return cached;
-	const timeout = requestTimeout(options);
-	return shareRequest(`index\0${url}`, options.signal, async (signal) => {
-		const text = await fetchText(url, "fetch format index", signal, timeout);
+	return shareRequest(`index\0${url}`, waitOptions(options, "fetch format index", url), async (signal) => {
+		const text = decodeDownload(await fetchBytes(url, "fetch format index", signal), url);
 		const data = validateSFAIndex(JSON.parse(text));
 		indexCache.set(url, data);
 		return data;
@@ -2247,26 +2356,37 @@ function cachedFormatInfo(id, filename, data) {
 	};
 }
 /**
-* Download a format, verify its checksum, write it to the cache shared by name and version, and
-* return its StoryFormatInfo. Concurrent calls for one download URL share one request.
+* Check that a downloaded format is the one the index entry promised. The name matches without
+* regard to case, as format requests do, and the version by SemVer precedence, so "1.0" and "v1.0.0"
+* agree. A format.js that names no format ({@link UNNAMED_FORMAT_NAME}) is allowed: such formats
+* exist, and the index entry then supplies the name it is cached under.
+*/
+function checkFormatIdentity(entry, data, downloadUrl) {
+	if ((data.name === "Untitled Story Format" || data.name.toLowerCase() === entry.name.toLowerCase()) && sameVersion(data.version, entry.version)) return;
+	throw new Error(`Story format mismatch for ${downloadUrl}: the index lists ${entry.name} ${entry.version}, but the download is ${data.name} ${data.version}`);
+}
+/**
+* Download a format, verify its checksum, check that it is the format the entry names, write it to
+* the cache shared by name and version, and return its StoryFormatInfo. Concurrent calls for one
+* download URL share one request for the bytes; each call then verifies them against its own
+* entry, within its own timeout.
 */
 async function fetchAndCacheFormat(entry, downloadUrl, options = {}) {
 	cachedFormatDir(entry.name, entry.version);
-	const timeout = requestTimeout(options);
-	return shareRequest(`format\0${getCacheDir()}\0${downloadUrl}`, options.signal, async (signal) => {
-		const text = await fetchText(downloadUrl, "download format", signal, timeout);
-		const checksumKey = Object.keys(entry.checksums ?? {}).find((k) => k.endsWith("format.js"));
-		if (checksumKey) {
-			const expected = entry.checksums[checksumKey];
-			if (!expected) throw new Error(`Missing checksum value for key "${checksumKey}"`);
-			if (!await verifySHA256(new TextEncoder().encode(text), expected)) throw new Error(`Checksum verification failed for ${entry.name} ${entry.version}`);
-		}
-		const id = makeFormatId(entry.name, entry.version);
-		const data = parseFormatJSON(text, id);
-		if (!data) throw new Error(`Failed to parse format JSON from ${downloadUrl}`);
-		signal.throwIfAborted();
-		return cachedFormatInfo(id, writeCacheEntry(resolve(getCacheDir()), [entry.name, entry.version], text), data);
-	});
+	const bytes = await shareDownload(downloadUrl, options);
+	const checksumKey = Object.keys(entry.checksums ?? {}).find((k) => k.endsWith("format.js"));
+	if (checksumKey) {
+		const expected = entry.checksums[checksumKey];
+		if (!expected) throw new Error(`Missing checksum value for key "${checksumKey}"`);
+		if (!await verifySHA256(bytes, expected)) throw new Error(`Checksum verification failed for ${entry.name} ${entry.version}`);
+	}
+	const text = decodeDownload(bytes, downloadUrl);
+	const id = makeFormatId(entry.name, entry.version);
+	const data = parseFormatJSON(text, id);
+	if (!data) throw new Error(`Failed to parse format JSON from ${downloadUrl}`);
+	checkFormatIdentity(entry, data, downloadUrl);
+	options.signal?.throwIfAborted();
+	return cachedFormatInfo(id, writeCacheEntry(resolve(getCacheDir()), [entry.name, entry.version], text), data);
 }
 /**
 * Download a direct format.js URL, parse its JSON, cache it under that URL (apart from the
@@ -2274,16 +2394,13 @@ async function fetchAndCacheFormat(entry, downloadUrl, options = {}) {
 * one URL share one request.
 */
 async function fetchDirectFormat(url, options = {}) {
-	const timeout = requestTimeout(options);
-	return shareRequest(`url\0${getUrlCacheDir()}\0${url}`, options.signal, async (signal) => {
-		const text = await fetchText(url, "download format", signal, timeout);
-		const data = parseFormatJSON(text);
-		if (!data) throw new Error(`Failed to parse format JSON from ${url}`);
-		cachedFormatDir(data.name, data.version);
-		signal.throwIfAborted();
-		const formatPath = writeCacheEntry(getUrlCacheDir(), [urlCacheKey(url)], text);
-		return cachedFormatInfo(makeFormatId(data.name, data.version), formatPath, data);
-	});
+	const text = decodeDownload(await shareDownload(url, options), url);
+	const data = parseFormatJSON(text);
+	if (!data) throw new Error(`Failed to parse format JSON from ${url}`);
+	cachedFormatDir(data.name, data.version);
+	options.signal?.throwIfAborted();
+	const formatPath = writeCacheEntry(getUrlCacheDir(), [urlCacheKey(url)], text);
+	return cachedFormatInfo(makeFormatId(data.name, data.version), formatPath, data);
 }
 /** The copy of a direct format URL in the download cache, if it has been downloaded before. */
 function getCachedDirectFormat(url) {
@@ -2324,6 +2441,16 @@ async function resolveFormatUrls(request, urls, options = {}) {
 	}
 	if (lastError) throw lastError;
 }
+/**
+* Find the best format among the cached copies of direct format URLs, without network access.
+* Matching follows {@link selectFormatCandidate}, so `allowOlder` admits a same-major older version.
+* Each URL keeps its own copy; the shared name and version downloads are never consulted.
+*
+* Internal, for format resolution; not part of the public API.
+*/
+function findCachedUrlFormat(request, urls, options = {}) {
+	return selectFormatCandidate(request, urls.flatMap((url) => getCachedDirectFormat(url) ?? []), (f) => f, options);
+}
 /** Whether `info` is a format the request accepts. */
 function answers(request, info) {
 	return selectFormatCandidate(request, [info], (f) => f) !== void 0;
@@ -2576,8 +2703,8 @@ function findLocalFormat(all, pruned, request) {
 * then format indices (unless `noRemote`). Names and IDs match the same way in each (see
 * `selectFormatCandidate`), so a request that a local format answers never reaches the cache or the
 * network. Local formats that cannot be used are reported as warnings. When a StoryData request
-* names a version that none of them has, an older version of
-* the same format and major version is used with a warning. Anything else is an error diagnostic,
+* names a version that none of them has, an older version of the same format and major version
+* is used with a warning, from local formats, the project's cached format URLs, or the shared cache. Anything else is an error diagnostic,
 * and the result is `undefined`.
 */
 async function resolveStoryFormat(request, options, diagnostics) {
@@ -2615,7 +2742,7 @@ async function resolveStoryFormat(request, options, diagnostics) {
 		if (remote) return remote;
 	}
 	if (request.kind === "name") {
-		const older = selectFormatCandidate(request, rankedTwine2Formats(pruned), (f) => f, { allowOlder: true }) ?? findCachedFormat(request, { allowOlder: true });
+		const older = selectFormatCandidate(request, rankedTwine2Formats(pruned), (f) => f, { allowOlder: true }) ?? findCachedUrlFormat(request, options.formatUrls ?? [], { allowOlder: true }) ?? findCachedFormat(request, { allowOlder: true });
 		if (older) {
 			diagnostics.push({
 				level: "warning",
@@ -2864,8 +2991,6 @@ function* tweeLexer(input) {
 		const items = ctx.drainItems();
 		for (const item of items) yield item;
 	}
-	const remaining = ctx.drainItems();
-	for (const item of remaining) yield item;
 }
 /** Convenience class wrapper for the lexer generator. */
 var TweeLexer = class {
@@ -3018,9 +3143,7 @@ function parseTwee(source, options = {}) {
 					};
 				}
 				try {
-					const raw = JSON.parse(item.val);
-					if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new Error("expected a JSON object");
-					const parsed = raw;
+					const parsed = JSON.parse(item.val);
 					const meta = {};
 					for (const [key, value] of Object.entries(parsed)) if (typeof value === "string") meta[key] = value;
 					current.metadata = meta;
@@ -6274,8 +6397,8 @@ function loadFont(story, filename, diagnostics) {
 * Load sources with mtime-based caching for incremental rebuilds.
 * Always creates a fresh Story; cached passages are replayed via storyAdd().
 */
-function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles, cache, changedFiles) {
-	const currentFiles = /* @__PURE__ */ new Set();
+function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles, cache, changedFiles, buildFiles) {
+	const currentFiles = new Set(buildFiles);
 	const changedPaths = changedFiles === void 0 ? void 0 : new Set([...changedFiles].map((f) => resolve(f)));
 	for (const filename of filenames) {
 		if (processedFiles.has(filename)) {
@@ -6340,16 +6463,6 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 }
 //#endregion
 //#region src/template.ts
-/**
-* An HTML closing head tag: `</head` in any letter case, followed by whitespace, `/` or `>`, up to the next `>`.
-* This is how the HTML tokenizer reads an end tag; it ignores whatever sits between the tag name and the `>`.
-*/
-const CLOSING_HEAD_TAG = "<\\/[Hh][Ee][Aa][Dd](?=[\\t\\n\\f\\r />])[^>]*>";
-/**
-* The start of an HTML body start tag: `<body` in any letter case, followed by whitespace, `/` or `>` (so not
-* `<bodyx>`). Only the `<body` is matched; the attributes and `>` after it are left alone.
-*/
-const BODY_START_TAG = "<[Bb][Oo][Dd][Yy](?=[\\t\\n\\f\\r />])";
 /** The regular expression source matching exactly `text`. */
 function literal(text) {
 	return text.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
@@ -6375,6 +6488,8 @@ function fillTemplateParts(parts) {
 		return part.text.replace(pattern, (match, ...groups) => {
 			const slot = slots.find((_, i) => groups[i] !== void 0);
 			if (slot === void 0 || slot.occurrences === "first" && filled.has(slot)) return match;
+			const offset = groups[slots.length];
+			if (slot.accepts !== void 0 && typeof offset === "number" && !slot.accepts(part.text, offset)) return match;
 			filled.add(slot);
 			return slot.replacement(match);
 		});
@@ -6465,15 +6580,18 @@ function placeHead(content, texts, owner) {
 		slot: void 0,
 		diagnostics: []
 	};
-	const found = (tag) => texts.some((text) => new RegExp(tag).test(text));
-	if (found("<\\/[Hh][Ee][Aa][Dd](?=[\\t\\n\\f\\r />])[^>]*>")) return {
-		slot: beforeTag(CLOSING_HEAD_TAG, content),
+	const scans = texts.map((text) => ({
+		text,
+		tags: scanHeadTags(text)
+	}));
+	if (scans.some(({ tags }) => tags.closingHead !== void 0)) return {
+		slot: beforeTag(CLOSING_HEAD_PREFIX, "closingHead", content),
 		diagnostics: []
 	};
-	if (found("<[Bb][Oo][Dd][Yy](?=[\\t\\n\\f\\r />])")) {
+	if (scans.some(({ tags }) => tags.bodyStart !== void 0)) {
 		const message = `${owner} has no closing head tag; the modules and head file were injected before its body start tag.`;
 		return {
-			slot: beforeTag(BODY_START_TAG, content),
+			slot: beforeTag(BODY_START_PREFIX, "bodyStart", content),
 			diagnostics: [{
 				level: "warning",
 				message
@@ -6488,12 +6606,108 @@ function placeHead(content, texts, owner) {
 		}]
 	};
 }
-/** The slot that inserts `content` on its own line before the first match of `tag`, which is kept as written. */
-function beforeTag(tag, content) {
+/** `</head` in any letter case, followed by whitespace, `/` or `>`; the rest of the tag is left alone. */
+const CLOSING_HEAD_PREFIX = "<\\/[Hh][Ee][Aa][Dd](?=[\\t\\n\\f\\r />])";
+/** `<body` in any letter case, followed by whitespace, `/` or `>` (so not `<bodyx>`). */
+const BODY_START_PREFIX = "<[Bb][Oo][Dd][Yy](?=[\\t\\n\\f\\r />])";
+/** Elements whose content is text, so a tag written there is not a tag. */
+const RAW_TEXT_ELEMENTS = /* @__PURE__ */ new Set([
+	"script",
+	"style",
+	"textarea",
+	"title"
+]);
+const isSpace = (c) => c === " " || c === "	" || c === "\n" || c === "\f" || c === "\r";
+const isLetter = (c) => c !== void 0 && /^[A-Za-z]$/.test(c);
+/**
+* Find the first closing head tag and body start tag that HTML would read as tags: not those in a comment, in
+* the text of a script, style, textarea or title element, or in a quoted attribute value. A small scanner, not
+* a full HTML tokenizer; it needs no more than the tags and where they end.
+*/
+function scanHeadTags(html) {
+	const { closingHead, bodyStart } = scanTags$1(html);
+	return {
+		closingHead,
+		bodyStart
+	};
+}
+function scanTags$1(html) {
+	let closingHead;
+	let bodyStart;
+	let headStartEnd;
+	let i = 0;
+	while (i < html.length) {
+		const lt = html.indexOf("<", i);
+		if (lt === -1) break;
+		const next = html[lt + 1];
+		if (html.startsWith("<!--", lt)) {
+			const end = html.indexOf("-->", lt + 4);
+			i = end === -1 ? html.length : end + 3;
+		} else if (next === "!" || next === "?") {
+			const end = html.indexOf(">", lt);
+			i = end === -1 ? html.length : end + 1;
+		} else if (next === "/" && isLetter(html[lt + 2])) {
+			const { name, end } = readTag(html, lt + 2);
+			if (name === "head" && closingHead === void 0) closingHead = lt;
+			i = end;
+		} else if (isLetter(next)) {
+			const { name, end } = readTag(html, lt + 1);
+			if (name === "body" && bodyStart === void 0) bodyStart = lt;
+			if (name === "head" && headStartEnd === void 0) headStartEnd = end;
+			i = RAW_TEXT_ELEMENTS.has(name) ? rawTextEnd(html, name, end) : end;
+		} else i = lt + 1;
+		if (closingHead !== void 0 && bodyStart !== void 0) break;
+	}
+	return {
+		closingHead,
+		bodyStart,
+		headStartEnd
+	};
+}
+/** Read a tag whose name starts at `from`: its lowercase name, and the offset after its `>` (or the end). */
+function readTag(html, from) {
+	let i = from;
+	while (i < html.length && !isSpace(html[i]) && html[i] !== "/" && html[i] !== ">") i++;
+	const name = html.slice(from, i).toLowerCase();
+	while (i < html.length && html[i] !== ">") {
+		if (html[i] !== "=") {
+			i++;
+			continue;
+		}
+		i++;
+		while (isSpace(html[i])) i++;
+		const quote = html[i];
+		if (quote === "\"" || quote === "'") {
+			const close = html.indexOf(quote, i + 1);
+			i = close === -1 ? html.length : close + 1;
+		}
+	}
 	return {
-		pattern: tag,
+		name,
+		end: Math.min(i + 1, html.length)
+	};
+}
+/** The offset of the end tag that closes a raw text element, given where its text starts (or the end). */
+function rawTextEnd(html, name, from) {
+	const close = new RegExp(`</${name}(?=[\\t\\n\\f\\r />])`, "gi");
+	close.lastIndex = from;
+	return close.exec(html)?.index ?? html.length;
+}
+/**
+* The slot that inserts `content` on its own line before the first real tag of the kind `which` names (see
+* `scanHeadTags()`), which is kept as written. A look-alike inside a script or comment is left alone.
+*/
+function beforeTag(pattern, which, content) {
+	const cache = /* @__PURE__ */ new Map();
+	const offsetIn = (text) => {
+		if (!cache.has(text)) cache.set(text, scanHeadTags(text)[which]);
+		return cache.get(text);
+	};
+	return {
+		pattern,
 		occurrences: "first",
-		replacement: (match) => `${content}\n${match}`
+		replacement: (match) => `${content}\n${match}`,
+		accepts: (text, offset) => offsetIn(text) === offset
 	};
 }
 //#endregion
@@ -6939,6 +7153,7 @@ async function compile(options) {
 */
 async function compileToFile(options) {
 	const result = await compileForOutputFile(options, options.outFile);
+	options.signal?.throwIfAborted();
 	writeFileAtomic(options.outFile, result.output);
 	return result;
 }
@@ -7100,34 +7315,61 @@ async function buildOutput(options, cache, changedFiles, outputs) {
 	const timeout = options.formatFetchTimeout;
 	if (timeout !== void 0 && !(timeout >= 0)) throw new TweeTsError(`formatFetchTimeout must be 0 or more milliseconds, not ${timeout}.`);
 	clearIndexCache();
-	const filePaths = [];
-	const inlineSources = [];
-	for (const source of options.sources) if (typeof source === "string") filePaths.push(source);
-	else inlineSources.push(source);
-	const sourcePaths = getFilenames(filePaths, written, options.exclude);
-	diagnostics.push(...sourcePaths.diagnostics);
-	rejectOutputSources(sourcePaths.outputSources, diagnostics);
-	const sourceFilenames = sourcePaths.filenames;
+	const groups = [];
+	const outputSources = [];
+	for (const source of options.sources) {
+		const last = groups[groups.length - 1];
+		if (typeof source === "string") {
+			if (last?.kind === "paths") last.paths.push(source);
+			else groups.push({
+				kind: "paths",
+				paths: [source]
+			});
+		} else if (last?.kind === "inline") last.sources.push(source);
+		else groups.push({
+			kind: "inline",
+			sources: [source]
+		});
+	}
+	const walked = groups.map((group) => {
+		if (group.kind === "inline") return group;
+		const found = getFilenames(group.paths, written, options.exclude);
+		diagnostics.push(...found.diagnostics);
+		outputSources.push(...found.outputSources);
+		return {
+			kind: "files",
+			filenames: found.filenames
+		};
+	});
+	rejectOutputSources(outputSources, diagnostics);
+	const buildFiles = new Set(walked.flatMap((group) => group.kind === "files" ? group.filenames : []));
 	const story = createStory();
 	const processedFiles = /* @__PURE__ */ new Set();
-	if (cache) loadSourcesCached(story, sourceFilenames, {
+	for (const group of walked) if (group.kind === "inline") loadInlineSources(story, group.sources, {
 		trim,
 		twee2Compat
-	}, diagnostics, processedFiles, cache, changedFiles);
-	else loadSources(story, sourceFilenames, {
+	}, diagnostics);
+	else if (cache) loadSourcesCached(story, group.filenames, {
+		trim,
+		twee2Compat
+	}, diagnostics, processedFiles, cache, changedFiles, buildFiles);
+	else loadSources(story, group.filenames, {
 		trim,
 		twee2Compat
 	}, diagnostics, processedFiles);
-	loadInlineSources(story, inlineSources, {
+	if (cache && buildFiles.size === 0) loadSourcesCached(story, [], {
 		trim,
 		twee2Compat
-	}, diagnostics);
+	}, diagnostics, processedFiles, cache, changedFiles);
 	if (options.tagAliases) story.passages = applyTagAliases(story.passages, options.tagAliases);
 	let format;
-	if (outputMode === "html") format = await resolveStoryFormat(formatRequestFor(options.formatId, story.twine2.format, story.twine2.formatVersion, DEFAULT_FORMAT_ID), {
-		...options,
-		noRemote
-	}, diagnostics);
+	if (outputMode === "html") {
+		format = await resolveStoryFormat(formatRequestFor(options.formatId, story.twine2.format, story.twine2.formatVersion, DEFAULT_FORMAT_ID), {
+			...options,
+			noRemote
+		}, diagnostics);
+		options.signal?.throwIfAborted();
+	}
 	if (options.startPassage) story.twine2.start = options.startPassage;
 	const startName = story.twine2.start || DEFAULT_START_NAME;
 	if (testMode) story.twine2.options.set("debug", true);
@@ -7179,6 +7421,7 @@ async function buildOutput(options, cache, changedFiles, outputs) {
 		...getStoryStats(story, options.wordCountMethod),
 		files: [...processedFiles]
 	};
+	options.signal?.throwIfAborted();
 	return {
 		output,
 		story,
@@ -8944,22 +9187,13 @@ const foldKey = (key) => key.toLowerCase().replace(/[-_]/g, "");
 *
 * @param diagnostics Receives warnings that do not stop the config from loading: keys the config does not
 *   define, and a file that is not valid UTF-8 (it is read as Windows-1252).
-* @throws When the file is not valid JSON or fails {@link validateConfig}.
+* @throws When the file exists but cannot be read, is not valid JSON or fails {@link validateConfig}.
 */
 function loadConfig(dir, diagnostics) {
 	const base = dir ?? process.cwd();
 	const configPath = join(base, CONFIG_FILENAME);
 	if (!existsSync(configPath)) return null;
-	const readDiagnostics = [];
-	let raw;
-	try {
-		raw = readUTF8(configPath, readDiagnostics);
-	} catch {
-		return null;
-	}
-	const config = parseConfig(raw, configPath, readDiagnostics);
-	diagnostics?.push(...readDiagnostics);
-	return config;
+	return loadConfigFile(configPath, diagnostics);
 }
 /**
 * Load a config from a specific file path.