@rohal12/twee-ts 1.17.0 → 1.18.0

package/dist/{diagnostics-DZNS7W41.js → paths-DgO9oo6G.js}

@@ -1,7 +1,7 @@
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import * as nodePath from "node:path";
 import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
-import { randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 //#region src/ifid.ts
@@ -13,6 +13,19 @@ import { fileURLToPath } from "node:url";
 function generateIFID() {
 	return randomUUID().toUpperCase();
 }
+/** Length of the `UUID://...//` wrapper around a 36-character UUID. */
+const WRAPPED_LENGTH = 45;
+/**
+* Bring an IFID into the form the story model stores and every output writes: the uppercase
+* bare UUID. A valid `UUID://...//` wrapped IFID loses its wrapper; outputs that need the wrapper
+* (the Treaty of Babel comment) add exactly one. Twine 2 IFIDs use only capital letters, so the
+* value is uppercased, as Tweego does. An invalid value is only uppercased, so that validation
+* reports it as written.
+*/
+function normalizeIFID(value) {
+	const upper = value.toUpperCase();
+	return upper.length === WRAPPED_LENGTH && validateIFID(upper) === null ? upper.slice(7, 43) : upper;
+}
 /**
 * Validate an IFID string.
 * Accepts both bare UUIDs and UUID://...// wrapped format.
@@ -91,18 +104,44 @@ function tweeEscape(s) {
 	if (s.length === 0) return s;
 	return s.replace(/[\\[\]{}]/g, (ch) => "\\" + ch);
 }
-/** Escape a string for safe inclusion in a JavaScript string literal. */
+const JS_STRING_ESCAPES = {
+	"\\": "\\\\",
+	"\"": "\\\"",
+	"'": "\\'",
+	"\n": "\\n",
+	"\r": "\\r",
+	"	": "\\t",
+	"<": "\\x3C",
+	"\u2028": "\\u2028",
+	"\u2029": "\\u2029"
+};
+/**
+* Escape a string for the inside of a single- or double-quoted JavaScript string literal, including one written
+* into an HTML `<script>` element. Besides backslashes, quotes and line breaks (with U+2028 and U+2029, which end
+* a string literal in JavaScript before ES2019), every `<` becomes `\x3C`, so the literal holds no `<\/script`
+* that would end the element and no `<!--` or `<script` that would change where it ends. The string's value is
+* unchanged.
+*/
 function jsStringEscape(s) {
 	if (s.length === 0) return s;
-	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+	return s.replace(/[\\"'\n\r\t<\u2028\u2029]/g, (ch) => JS_STRING_ESCAPES[ch] ?? ch);
+}
+/**
+* Escape a string for the inside of a double-quoted CSS string (such as a `font-family` name): `\` and `"` get
+* a backslash, and line breaks and other control characters become hex escapes followed by a space (`\a ` for a
+* line feed), since a raw line break ends a CSS string and a backslash before one is a line continuation.
+*/
+function cssStringEscape(s) {
+	if (s.length === 0) return s;
+	return s.replace(/[\\"\u0000-\u001f\u007f]/g, (ch) => ch === "\\" || ch === "\"" ? `\\${ch}` : `\\${ch.charCodeAt(0).toString(16)} `);
 }
 /** Sanitize a string for safe inclusion in a CSS or JS block comment. */
 function commentSanitize(s) {
 	return s.replace(/\*\//g, "* /");
 }
-/** Sanitize a string for safe inclusion in an HTML comment. */
+/** Sanitize a string for safe inclusion in an HTML comment: break up `-->` and `--!>`, which both end one. */
 function htmlCommentSanitize(s) {
-	return s.replace(/-->/g, "-- >");
+	return s.replace(/--(!?)>/g, "--$1 >");
 }
 /**
 * Escape JavaScript for the content of an HTML `<script>` element, so that the HTML parser reads all of it as
@@ -279,7 +318,19 @@ function passageToPassagedata(p, pid, options) {
 	if (options?.sourceInfo && p.source) attrs += ` data-source-file=${quote(attrEscape(p.source.file))} data-source-line="${p.source.line}"`;
 	return `${attrs}>${htmlEscape(p.text)}</tw-passagedata>`;
 }
-/** Generate `<div tiddler>` HTML for Twine 1. */
+/**
+* Whether Twine 1 `obfuscate:rot13` encodes a tiddler: every one but `StorySettings` and those tagged `Twine.image`
+* (Twine 1.4 `Tiddler.isObfuscateable()`). Its engine tests the stored name and tags, which these tiddlers keep
+* unencoded, so the decompiler tests them the same way.
+*/
+function isObfuscatable(p) {
+	return p.name !== "StorySettings" && !p.tags.includes("Twine.image");
+}
+/**
+* Generate `<div tiddler>` HTML for Twine 1. With `obfuscateRot13`, an obfuscatable tiddler (see
+* `isObfuscatable()`) has its name, each tag and its text ROT13-encoded, as Twine 1.4 writes it
+* (`Tiddler.toHtml()`), and as its engine.js decodes it.
+*/
 function passageToTiddler(p, pid, obfuscateRot13 = false) {
 	let position;
 	if (hasMetadataPosition(p)) position = p.metadata?.position ?? "";
@@ -291,9 +342,10 @@ function passageToTiddler(p, pid, obfuscateRot13 = false) {
 		position = `${xp * 140 - 130},${yp * 140 - 130}`;
 	}
 	const created = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:T]/g, "").slice(0, 12);
-	const content = obfuscateRot13 && p.name !== "StorySettings" ? tiddlerEscape(rot13(p.text)) : tiddlerEscape(p.text);
-	const nameComment = obfuscateRot13 ? `<!-- ${commentSanitize(p.name)} -->` : "";
-	return `<div tiddler=${quote(attrEscape(p.name))} tags=${quote(attrEscape(p.tags.join(" ")))} created=${quote(created)} modifier=${quote("twee")} twine-position=${quote(attrEscape(position))}>${nameComment}${content}</div>`;
+	const encode = obfuscateRot13 && isObfuscatable(p) ? rot13 : (s) => s;
+	const name = attrEscape(encode(p.name));
+	const tags = attrEscape(p.tags.map(encode).join(" "));
+	return `<div tiddler=${quote(name)} tags=${quote(tags)} created=${quote(created)} modifier=${quote("twee")} twine-position=${quote(attrEscape(position))}>${tiddlerEscape(encode(p.text))}</div>`;
 }
 /**
 * Count words in a passage.
@@ -346,19 +398,128 @@ function quote(s) {
 }
 //#endregion
 //#region src/story.ts
-/** Module-level index: maps passage names to their array indices for O(1) lookups. */
 const passageIndex = /* @__PURE__ */ new WeakMap();
-function getIndex(story) {
-	let index = passageIndex.get(story);
-	if (!index) {
-		index = /* @__PURE__ */ new Map();
-		for (let i = 0; i < story.passages.length; i++) {
-			const passage = story.passages[i];
-			if (passage) index.set(passage.name, i);
+function buildIndex(story) {
+	const names = story.passages.map((p) => p.name);
+	const index = {
+		passages: story.passages,
+		names,
+		positions: new Map(names.map((name, i) => [name, i]))
+	};
+	passageIndex.set(story, index);
+	return index;
+}
+/**
+* The index, rebuilt if `story.passages` was reassigned or changed length. O(1); `position()`
+* also checks every hit. A change that keeps the length, such as replacing an element, can still
+* hide a passage from a lookup, so `storyVerifyIndex()` checks every position.
+*/
+function currentIndex(story) {
+	const index = passageIndex.get(story);
+	return index !== void 0 && index.passages === story.passages && index.names.length === story.passages.length ? index : buildIndex(story);
+}
+/** The position of the passage named `name`, or -1. */
+function position(story, name) {
+	const i = currentIndex(story).positions.get(name);
+	if (i === void 0) return -1;
+	if (story.passages[i]?.name === name) return i;
+	return buildIndex(story).positions.get(name) ?? -1;
+}
+/** Add a passage whose name no passage has yet at the end. */
+function push(story, p) {
+	const index = currentIndex(story);
+	index.positions.set(p.name, story.passages.length);
+	index.names.push(p.name);
+	story.passages.push(p);
+}
+/** Put a passage at position `i`, in place of the passage there. */
+function replaceAt(story, i, p) {
+	const renamed = story.passages[i]?.name !== p.name;
+	story.passages[i] = p;
+	if (renamed) buildIndex(story);
+}
+/** Names of compiler special passages, which storyAdd() reads into the story model. */
+const SPECIAL_PASSAGE_NAMES = /* @__PURE__ */ new Set([
+	"StoryData",
+	"StoryIncludes",
+	"StorySettings",
+	"StoryTitle"
+]);
+/** Passages whose names were generated, kept by identity so that cached passages keep the mark. */
+const generatedNames = /* @__PURE__ */ new WeakMap();
+/**
+* Mark a passage's name as generated (from a file name, or for imported story code) and return
+* the passage. `origin.base` is the name that free names are numbered from: `base`, `base 2`, ….
+*/
+function withGeneratedName(p, origin) {
+	generatedNames.set(p, origin);
+	return p;
+}
+/** The first of `base`, `base 2`, `base 3`, … that `isFree` accepts. */
+function freeName(base, isFree) {
+	if (isFree(base)) return base;
+	for (let n = 2;; n++) {
+		const candidate = `${base} ${n}`;
+		if (isFree(candidate)) return candidate;
+	}
+}
+/** Whether a generated name may take `name`: no passage has it and it is no special name. */
+function isFreeForGenerated(story, name) {
+	return !SPECIAL_PASSAGE_NAMES.has(name) && position(story, name) === -1;
+}
+function reportRename(origin, from, to, diagnostics) {
+	switch (origin.kind) {
+		case "code": return;
+		case "media": {
+			const reason = SPECIAL_PASSAGE_NAMES.has(from) ? `"${from}" is a compiler special passage name` : `another passage has the name "${from}"`;
+			diagnostics.push({
+				level: "warning",
+				message: `Passage "${from}" from "${origin.file}" renamed to "${to}"; ${reason}.`
+			});
+			return;
 		}
-		passageIndex.set(story, index);
+		default: throw new Error(`unhandled generated name: ${JSON.stringify(origin)}`);
 	}
-	return index;
+}
+/** Add a passage with a generated name, under the first free name if its own is taken. */
+function addGenerated(story, p, origin, diagnostics) {
+	if (isFreeForGenerated(story, p.name)) {
+		push(story, p);
+		return;
+	}
+	const name = freeName(origin.base, (n) => isFreeForGenerated(story, n));
+	reportRename(origin, p.name, name, diagnostics);
+	push(story, withGeneratedName({
+		...p,
+		name
+	}, origin));
+}
+/**
+* If a passage with a generated name has `name`, give it the first free name, in its place in the
+* passage list, so that a passage from the sources can take the name.
+*/
+function moveGeneratedAside(story, name, diagnostics) {
+	const i = position(story, name);
+	const existing = i === -1 ? void 0 : story.passages[i];
+	const origin = existing === void 0 ? void 0 : generatedNames.get(existing);
+	if (existing === void 0 || origin === void 0) return;
+	const free = freeName(origin.base, (n) => isFreeForGenerated(story, n));
+	reportRename(origin, name, free, diagnostics);
+	replaceAt(story, i, withGeneratedName({
+		...existing,
+		name: free
+	}, origin));
+}
+function defaultTwine2Metadata() {
+	return {
+		format: "",
+		formatVersion: "",
+		options: /* @__PURE__ */ new Map(),
+		start: "",
+		tags: "",
+		tagColors: /* @__PURE__ */ new Map(),
+		zoom: 1
+	};
 }
 function createStory() {
 	const story = {
@@ -367,52 +528,37 @@ function createStory() {
 		passages: [],
 		legacyIFID: "",
 		twine1: { settings: /* @__PURE__ */ new Map() },
-		twine2: {
-			format: "",
-			formatVersion: "",
-			options: /* @__PURE__ */ new Map(),
-			start: "",
-			tags: "",
-			tagColors: /* @__PURE__ */ new Map(),
-			zoom: 1
-		}
+		twine2: defaultTwine2Metadata()
 	};
-	passageIndex.set(story, /* @__PURE__ */ new Map());
+	buildIndex(story);
 	return story;
 }
 function storyHas(story, name) {
-	return getIndex(story).has(name);
+	return position(story, name) !== -1;
 }
 function storyAppend(story, p, diagnostics) {
-	const index = getIndex(story);
-	const i = index.get(p.name) ?? -1;
-	if (i === -1) {
-		index.set(p.name, story.passages.length);
-		story.passages.push(p);
-	} else {
+	const i = position(story, p.name);
+	if (i === -1) push(story, p);
+	else {
 		diagnostics.push({
 			level: "warning",
 			message: `Replacing existing passage "${p.name}" with duplicate.`
 		});
-		story.passages[i] = p;
+		replaceAt(story, i, p);
 	}
 }
 function storyPrepend(story, p, diagnostics) {
-	const index = getIndex(story);
-	const i = index.get(p.name) ?? -1;
+	moveGeneratedAside(story, p.name, diagnostics);
+	const i = position(story, p.name);
 	if (i === -1) {
 		story.passages.unshift(p);
-		index.clear();
-		for (let j = 0; j < story.passages.length; j++) {
-			const passage = story.passages[j];
-			if (passage) index.set(passage.name, j);
-		}
+		buildIndex(story);
 	} else {
 		diagnostics.push({
 			level: "warning",
 			message: `Replacing existing passage "${p.name}" with duplicate.`
 		});
-		story.passages[i] = p;
+		replaceAt(story, i, p);
 	}
 }
 function marshalStoryData(story) {
@@ -438,18 +584,20 @@ function unmarshalStoryData(story, json) {
 	}
 	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return "Cannot unmarshal \"StoryData\"; expected a JSON object";
 	const data = raw;
-	if (typeof data.ifid === "string" && data.ifid) story.ifid = data.ifid.toUpperCase();
-	if (typeof data.format === "string" && data.format) story.twine2.format = data.format;
-	if (typeof data["format-version"] === "string" && data["format-version"]) story.twine2.formatVersion = data["format-version"];
+	const twine2 = defaultTwine2Metadata();
+	story.ifid = typeof data.ifid === "string" ? normalizeIFID(data.ifid) : "";
+	if (typeof data.format === "string") twine2.format = data.format;
+	if (typeof data["format-version"] === "string") twine2.formatVersion = data["format-version"];
 	if (Array.isArray(data.options)) {
-		for (const opt of data.options) if (typeof opt === "string") story.twine2.options.set(opt, true);
+		for (const opt of data.options) if (typeof opt === "string") twine2.options.set(opt, true);
 	}
-	if (typeof data.start === "string" && data.start) story.twine2.start = data.start;
-	if (typeof data.tags === "string") story.twine2.tags = data.tags;
+	if (typeof data.start === "string") twine2.start = data.start;
+	if (typeof data.tags === "string") twine2.tags = data.tags;
 	if (typeof data["tag-colors"] === "object" && data["tag-colors"] !== null && !Array.isArray(data["tag-colors"])) {
-		for (const [tag, color] of Object.entries(data["tag-colors"])) if (typeof color === "string") story.twine2.tagColors.set(tag, color);
+		for (const [tag, color] of Object.entries(data["tag-colors"])) if (typeof color === "string") twine2.tagColors.set(tag, color);
 	}
-	if (typeof data.zoom === "number" && data.zoom !== 0) story.twine2.zoom = data.zoom;
+	if (typeof data.zoom === "number" && data.zoom !== 0) twine2.zoom = data.zoom;
+	story.twine2 = twine2;
 	return null;
 }
 function unmarshalStorySettings(story, text, diagnostics) {
@@ -469,7 +617,7 @@ function unmarshalStorySettings(story, text, diagnostics) {
 		const val = line.slice(colonIdx + 1).trim().toLowerCase();
 		switch (key) {
 			case "ifid":
-				if (validateIFID(val) === null) story.legacyIFID = val.toUpperCase();
+				if (validateIFID(val) === null) story.legacyIFID = normalizeIFID(val);
 				obsolete.push("\"ifid\"");
 				continue;
 			case "zoom":
@@ -490,8 +638,20 @@ function unmarshalStorySettings(story, text, diagnostics) {
 /**
 * Process a passage and add it to the story, handling special passages.
 * Creates new passage objects where text is modified rather than mutating the input.
+*
+* A passage replaces an earlier one with the same name, except where either name was generated
+* (see `withGeneratedName()`): a generated name never replaces a passage and is never replaced.
+* A passage with a generated name takes the first free name of `base`, `base 2`, … when its own
+* is taken or is a compiler special name. A passage with a name from the sources that a generated
+* name holds takes it over, and the generated one moves to the first free name in its place.
 */
 function storyAdd(story, p, diagnostics) {
+	const origin = generatedNames.get(p);
+	if (origin !== void 0) {
+		addGenerated(story, p, origin, diagnostics);
+		return;
+	}
+	moveGeneratedAside(story, p.name, diagnostics);
 	let processed = p;
 	switch (p.name) {
 		case "StoryIncludes":
@@ -625,53 +785,413 @@ function isExcluded(filename, exclude) {
 	const rel = relative(process.cwd(), resolve(filename)) || filename;
 	return exclude.some((pattern) => matchesGlob(rel, pattern.replace(/^\.\//, "")));
 }
+/** A build that writes nothing: `compile()`, or output to stdout. */
+const NO_BUILD_OUTPUTS = {
+	files: [],
+	dirs: []
+};
+/** The outputs of a build that writes the one file `outFile`, or none without it. */
+function toBuildOutputs(outputs) {
+	if (outputs === void 0) return NO_BUILD_OUTPUTS;
+	return typeof outputs === "string" ? {
+		files: [outputs],
+		dirs: []
+	} : outputs;
+}
+/**
+* The path outputs are compared by: absolute, with every symbolic link in it
+* resolved, so two paths that reach the same file through different links (a
+* symlinked project folder, an alias of the output folder) compare equal. A
+* path that doesn't exist yet, such as the output before the first build, is
+* its nearest existing folder's real path joined with the rest.
+*/
+function realPathOf(path) {
+	const abs = resolve(path);
+	try {
+		return realpathSync.native(abs);
+	} catch {}
+	const parent = dirname(abs);
+	return parent === abs ? abs : join(realPathOf(parent), basename(abs));
+}
+/** Whether the path `inner` is `outer` or inside it. */
+function isSameOrInside(inner, outer) {
+	return inner === outer || inner.startsWith(outer.endsWith(sep) ? outer : outer + sep);
+}
+function outputPaths(outputs) {
+	const files = new Set(outputs.files.map(realPathOf));
+	const dirs = new Set(outputs.dirs.map(realPathOf));
+	const all = [...files, ...dirs];
+	return {
+		isFile: (real) => files.has(real),
+		isDir: (real) => dirs.has(real),
+		holds: (real) => dirs.has(real) || all.some((output) => output !== real && isSameOrInside(output, real)),
+		isOutput(path, roots) {
+			const real = realPathOf(path);
+			if (files.has(real)) return true;
+			const owners = [...dirs].filter((dir) => isSameOrInside(real, dir));
+			if (owners.length === 0) return false;
+			return roots.map(realPathOf).filter((root) => isSameOrInside(real, root)).every((root) => owners.some((dir) => dir !== root && isSameOrInside(dir, root)));
+		}
+	};
+}
+/**
+* A folder entry as source discovery walks it, found at `pathname` with the real
+* path `real` when it is no link: a link to a file counts as that file, and a
+* link to anything else (a folder above all) as nothing, undefined. Throws when
+* the entry or a link's target can't be read.
+*/
+function walkedEntry(pathname, real) {
+	const stat = lstatSync(pathname);
+	if (!stat.isSymbolicLink()) return {
+		stat,
+		real
+	};
+	const target = statSync(pathname);
+	return target.isFile() ? {
+		stat: target,
+		real: realPathOf(pathname)
+	} : void 0;
+}
 /**
 * Recursively walk directories, collecting regular file paths.
-* Filters out the output file to prevent circular compilation, and the files
-* that match an `exclude` glob (see isExcluded).
+*
+* Leaves out what the build writes (`outputs`, compared by real path, see
+* realPathOf) so its last output is never read back, and the files that match an
+* `exclude` glob (see isExcluded). A path given that is itself an output file is
+* not walked but listed in `outputSources`.
+*
+* Symbolic links: a path given is followed wherever it leads. Inside a folder, a
+* link to a file is read, but a link to a folder is not followed, as Tweego's walk
+* doesn't follow one. A link back to its own folder or a parent would otherwise
+* walk the same files again at every depth.
+*
 * Like Tweego, a path that cannot be read is reported as a warning and skipped.
 */
-function getFilenames(pathnames, outFilename, exclude = []) {
+function getFilenames(pathnames, outputs, exclude = []) {
 	const filenames = [];
 	const diagnostics = [];
-	const absOutFile = outFilename ? resolve(outFilename) : "";
+	const outputSources = [];
+	const output = outputPaths(toBuildOutputs(outputs));
 	function warn(pathname, e) {
 		diagnostics.push({
 			level: "warning",
 			message: `path ${pathname}: ${e instanceof Error ? e.message : String(e)}`
 		});
 	}
-	function walk(pathname) {
+	function addFile(pathname) {
+		const abs = resolve(pathname);
+		const rel = relative(process.cwd(), abs);
+		if (isExcluded(rel || abs, exclude)) return;
+		filenames.push(rel || abs);
+	}
+	function walkDir(pathname, real) {
+		let entries;
+		try {
+			entries = readdirSync(pathname);
+		} catch (e) {
+			warn(pathname, e);
+			return;
+		}
+		for (const entry of entries) walkEntry(join(pathname, entry), join(real, entry));
+	}
+	function walkEntry(pathname, real) {
+		let entry;
+		try {
+			entry = walkedEntry(pathname, real);
+		} catch (e) {
+			warn(pathname, e);
+			return;
+		}
+		if (entry === void 0) return;
+		if (entry.stat.isFile()) {
+			if (!output.isFile(entry.real)) addFile(pathname);
+		} else if (entry.stat.isDirectory() && !output.isDir(entry.real)) walkDir(pathname, entry.real);
+	}
+	for (const pathname of pathnames) {
 		let stat;
 		try {
 			stat = statSync(pathname);
 		} catch (e) {
 			warn(pathname, e);
-			return;
+			continue;
 		}
+		const real = realPathOf(pathname);
 		if (stat.isFile()) {
-			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;
-			try {
-				entries = readdirSync(pathname);
-			} catch (e) {
-				warn(pathname, e);
-				return;
+			if (output.isFile(real)) outputSources.push(pathname);
+			else addFile(pathname);
+		} else if (stat.isDirectory()) walkDir(pathname, real);
+	}
+	return {
+		filenames,
+		diagnostics,
+		outputSources
+	};
+}
+//#endregion
+//#region src/relaxed-json.ts
+/**
+* A parser for the object literal a Twine 2 `format.js` passes to `window.storyFormat()`.
+*
+* The story formats spec does not require that object to be strict JSON, and Twine 2 runs
+* `format.js` as JavaScript. This parser accepts JSON plus the JavaScript literal syntax formats
+* use in practice: single-quoted strings, unquoted (identifier) and numeric keys, trailing commas,
+* comments, JavaScript string escapes, and hexadecimal, octal and binary numbers.
+*
+* It reads string literals token by token, so their contents come back exactly as JavaScript
+* evaluation gives them: text that only looks like structure (`a, }`, `word:`, an apostrophe) is
+* never touched. Anything outside that subset, such as a function or a variable, is a syntax error.
+*/
+const IDENTIFIER = /[A-Za-z_$][\w$]*/y;
+const NUMBER = /[+-]?(?:0[xX][0-9a-fA-F]+|0[oO][0-7]+|0[bB][01]+|(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)/y;
+const IDENTIFIER_PART = /[\w$]/;
+const WHITESPACE = /[\s]/;
+const HEX = /^[0-9a-fA-F]+$/;
+/** Simple single-character escapes and the characters they stand for. */
+const SIMPLE_ESCAPES = {
+	b: "\b",
+	f: "\f",
+	n: "\n",
+	r: "\r",
+	t: "	",
+	v: "\v"
+};
+/**
+* Parse a JavaScript object, array or primitive literal: all of `text`, or the part from `start` to
+* `end`. Error positions count from the start of `text`, so they point into the file it came from.
+*
+* @throws SyntaxError naming the line and column of the first thing it cannot parse.
+*/
+function parseRelaxedJSON(text, start = 0, end = text.length) {
+	let pos = start;
+	function fail(message, at = pos) {
+		const before = text.slice(0, at);
+		const line = before.split("\n").length;
+		const column = at - before.lastIndexOf("\n");
+		throw new SyntaxError(`${message} at line ${line}, column ${column}`);
+	}
+	/** The character at `pos`, or '' at the end of the input. */
+	const peek = () => pos < end ? text[pos] ?? "" : "";
+	const describeChar = (at) => at >= end ? "end of input" : JSON.stringify(text[at]);
+	/** Skip whitespace and comments. */
+	const skipTrivia = () => {
+		while (pos < end) {
+			const ch = peek();
+			if (WHITESPACE.test(ch)) pos++;
+			else if (text.startsWith("//", pos)) {
+				const lineEnd = text.slice(pos, end).search(/[\n\r\u2028\u2029]/);
+				pos = lineEnd === -1 ? end : pos + lineEnd;
+			} else if (text.startsWith("/*", pos)) {
+				const commentEnd = text.indexOf("*/", pos + 2);
+				if (commentEnd === -1 || commentEnd + 2 > end) fail("Unterminated comment");
+				pos = commentEnd + 2;
+			} else return;
+		}
+	};
+	const consume = (ch) => {
+		skipTrivia();
+		if (peek() !== ch) fail(`Expected ${JSON.stringify(ch)} but found ${describeChar(pos)}`);
+		pos++;
+	};
+	/** Read exactly `count` hex digits and return their value. */
+	const readHex = (count) => {
+		const digits = text.slice(pos, Math.min(pos + count, end));
+		if (digits.length !== count || !HEX.test(digits)) fail("Invalid hexadecimal escape sequence");
+		pos += count;
+		return parseInt(digits, 16);
+	};
+	/** Decode the escape sequence after a backslash; `pos` is just past the backslash. */
+	const readEscape = () => {
+		const ch = peek();
+		const simple = SIMPLE_ESCAPES[ch];
+		if (simple !== void 0) {
+			pos++;
+			return simple;
+		}
+		switch (ch) {
+			case "": return fail("Unterminated string");
+			case "x":
+				pos++;
+				return String.fromCharCode(readHex(2));
+			case "u": {
+				pos++;
+				if (peek() !== "{") return String.fromCharCode(readHex(4));
+				const close = text.indexOf("}", pos);
+				if (close === -1 || close >= end) fail("Invalid Unicode escape sequence");
+				pos++;
+				const codePoint = readHex(close - pos);
+				if (codePoint > 1114111) fail("Undefined Unicode code-point");
+				pos = close + 1;
+				return String.fromCodePoint(codePoint);
 			}
-			for (const entry of entries) walk(join(pathname, entry));
+			case "\r":
+				pos += text[pos + 1] === "\n" ? 2 : 1;
+				return "";
+			case "\n":
+			case "\u2028":
+			case "\u2029":
+				pos++;
+				return "";
+			case "0":
+				if (/[0-9]/.test(text[pos + 1] ?? "")) fail("Octal escape sequences are not supported");
+				pos++;
+				return "\0";
+			default:
+				if (/[1-9]/.test(ch)) fail("Octal escape sequences are not supported");
+				pos++;
+				return ch;
 		}
+	};
+	const readString = () => {
+		const quote = peek();
+		pos++;
+		let out = "";
+		let chunkStart = pos;
+		for (;;) {
+			if (pos >= end) fail("Unterminated string");
+			const ch = peek();
+			if (ch === quote) {
+				out += text.slice(chunkStart, pos);
+				pos++;
+				return out;
+			}
+			if (ch === "\n" || ch === "\r") fail("Unterminated string");
+			if (ch === "\\") {
+				out += text.slice(chunkStart, pos);
+				pos++;
+				out += readEscape();
+				chunkStart = pos;
+			} else pos++;
+		}
+	};
+	/** Read a match of a sticky regular expression at `pos`, or return undefined. */
+	const readToken = (pattern) => {
+		pattern.lastIndex = pos;
+		const m = pattern.exec(text);
+		if (!m || pattern.lastIndex > end) return void 0;
+		pos = pattern.lastIndex;
+		return m[0];
+	};
+	const readNumber = () => {
+		const tokenStart = pos;
+		const token = readToken(NUMBER);
+		if (token === void 0) return void 0;
+		if (IDENTIFIER_PART.test(peek())) fail("Invalid number", tokenStart);
+		return (token.startsWith("-") ? -1 : 1) * Number(/^[+-]/.test(token) ? token.slice(1) : token);
+	};
+	const readKey = () => {
+		skipTrivia();
+		const ch = peek();
+		if (ch === "\"" || ch === "'") return readString();
+		const identifier = readToken(IDENTIFIER);
+		if (identifier !== void 0) return identifier;
+		const number = readNumber();
+		if (number !== void 0) return String(number);
+		return fail(`Expected a property name but found ${describeChar(pos)}`);
+	};
+	const readObject = () => {
+		pos++;
+		const out = {};
+		for (;;) {
+			skipTrivia();
+			if (peek() === "}") {
+				pos++;
+				return out;
+			}
+			const key = readKey();
+			consume(":");
+			Object.defineProperty(out, key, {
+				value: readValue(),
+				enumerable: true,
+				writable: true,
+				configurable: true
+			});
+			skipTrivia();
+			if (peek() === ",") pos++;
+			else if (peek() !== "}") fail(`Expected "," or "}" but found ${describeChar(pos)}`);
+		}
+	};
+	const readArray = () => {
+		pos++;
+		const out = [];
+		for (;;) {
+			skipTrivia();
+			if (peek() === "]") {
+				pos++;
+				return out;
+			}
+			out.push(readValue());
+			skipTrivia();
+			if (peek() === ",") pos++;
+			else if (peek() !== "]") fail(`Expected "," or "]" but found ${describeChar(pos)}`);
+		}
+	};
+	function readValue() {
+		skipTrivia();
+		const ch = peek();
+		if (ch === "{") return readObject();
+		if (ch === "[") return readArray();
+		if (ch === "\"" || ch === "'") return readString();
+		const tokenStart = pos;
+		const identifier = readToken(IDENTIFIER);
+		if (identifier !== void 0) {
+			if (identifier === "true") return true;
+			if (identifier === "false") return false;
+			if (identifier === "null") return null;
+			return fail(`Unexpected identifier ${JSON.stringify(identifier)}`, tokenStart);
+		}
+		const number = readNumber();
+		if (number !== void 0) return number;
+		return fail(`Unexpected ${describeChar(pos)}`);
 	}
-	for (const pathname of pathnames) walk(pathname);
+	const value = readValue();
+	skipTrivia();
+	if (pos < end) fail(`Unexpected ${describeChar(pos)} after the value`);
+	return value;
+}
+//#endregion
+//#region src/semver.ts
+const IDENTIFIERS = String.raw`[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*`;
+const VERSION$1 = new RegExp(String.raw`^[vV]?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-(${IDENTIFIERS}))?(?:\+${IDENTIFIERS})?$`);
+const NUMERIC = /^\d+$/;
+/** Parse a version string, or return null when it is not a version. */
+function parseVersion(text) {
+	const m = VERSION$1.exec(text);
+	if (!m) return null;
 	return {
-		filenames,
-		diagnostics
+		major: Number(m[1]),
+		minor: Number(m[2] ?? 0),
+		patch: Number(m[3] ?? 0),
+		prerelease: m[4] === void 0 ? [] : m[4].split(".")
 	};
 }
+/** Compare two prerelease identifiers: numeric ones numerically and below alphanumeric ones, which compare as ASCII. */
+function compareIdentifiers(a, b) {
+	const aNumeric = NUMERIC.test(a);
+	const bNumeric = NUMERIC.test(b);
+	if (aNumeric && bNumeric) return Math.sign(Number(a) - Number(b));
+	if (aNumeric !== bNumeric) return aNumeric ? -1 : 1;
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Compare prerelease identifier lists. An empty list (a release) ranks above any prerelease. */
+function comparePrerelease(a, b) {
+	if (a.length === 0 || b.length === 0) return Math.sign(b.length - a.length);
+	const shared = Math.min(a.length, b.length);
+	for (let i = 0; i < shared; i++) {
+		const order = compareIdentifiers(a[i] ?? "", b[i] ?? "");
+		if (order !== 0) return order;
+	}
+	return Math.sign(a.length - b.length);
+}
+/** Compare two versions by SemVer precedence: negative when `a` ranks lower, 0 when equal, positive when higher. */
+function compareVersions(a, b) {
+	return Math.sign(a.major - b.major) || Math.sign(a.minor - b.minor) || Math.sign(a.patch - b.patch) || comparePrerelease(a.prerelease, b.prerelease);
+}
+/** Whether two version strings name the same version (prerelease included, build metadata ignored). */
+function sameVersion(a, b) {
+	const left = parseVersion(a);
+	const right = parseVersion(b);
+	return left !== null && right !== null && compareVersions(left, right) === 0;
+}
 //#endregion
 //#region src/source-text.ts
 /**
@@ -684,14 +1204,119 @@ function getFilenames(pathnames, outFilename, exclude = []) {
 function normalizeSourceText(text) {
 	return (text.charCodeAt(0) === 65279 ? text.slice(1) : text).replace(/\r\n?/g, "\n");
 }
+/** Byte order marks at the start of a line, directly before a passage header's `::`. */
+const BOMS_BEFORE_HEADER = /(?<=^|\n)\uFEFF+(?=::)/g;
+/**
+* Normalize Twee source text: {@link normalizeSourceText}, and also remove byte order marks at the start of
+* a line that are directly followed by `::`. Concatenating files (`cat a.tw b.tw`) leaves the BOM of every
+* later file in front of its first passage header, which would otherwise not be recognised as a header.
+* A U+FEFF anywhere else is passage text and kept. Idempotent.
+*/
+function normalizeTweeSourceText(text) {
+	return normalizeSourceText(text).replace(BOMS_BEFORE_HEADER, "");
+}
 //#endregion
 //#region src/util.ts
 /**
 * Shared file I/O utilities.
 */
-/** Read a file as UTF-8 with BOM stripping and line ending normalization. */
-function readUTF8(filename) {
-	return normalizeSourceText(readFileSync(filename, "utf-8"));
+/** The charset assumed for text that is not valid UTF-8, as Tweego assumes it. */
+const FALLBACK_CHARSET = "windows-1252";
+/**
+* Throws on invalid UTF-8 instead of replacing bytes with U+FFFD. `ignoreBOM` keeps a leading BOM in the
+* text, as `readFileSync(file, 'utf-8')` did, so {@link normalizeSourceText} strips exactly one.
+*/
+const utf8Decoder = new TextDecoder("utf-8", {
+	fatal: true,
+	ignoreBOM: true
+});
+/**
+* The code points of the Windows-1252 bytes 0x80 to 0x9F, from the WHATWG Encoding Standard. The five bytes
+* Windows-1252 leaves undefined map to the C1 control with the same number, as the standard and Go's charmap
+* do. Every other byte is the code point with the same number.
+*
+* Decoded by hand, because Node's `TextDecoder('windows-1252')` decodes as ISO-8859-1 in some releases
+* (Node 22.18 turns 0x80 into U+0080 instead of €), and builds without ICU lack it.
+*/
+const WINDOWS_1252_C1 = [
+	8364,
+	129,
+	8218,
+	402,
+	8222,
+	8230,
+	8224,
+	8225,
+	710,
+	8240,
+	352,
+	8249,
+	338,
+	141,
+	381,
+	143,
+	144,
+	8216,
+	8217,
+	8220,
+	8221,
+	8226,
+	8211,
+	8212,
+	732,
+	8482,
+	353,
+	8250,
+	339,
+	157,
+	382,
+	376
+];
+function decodeWindows1252(bytes) {
+	const chunks = [];
+	for (let start = 0; start < bytes.length; start += 8192) {
+		const codes = Array.from(bytes.subarray(start, start + 8192), (b) => b >= 128 && b <= 159 ? WINDOWS_1252_C1[b - 128] ?? b : b);
+		chunks.push(String.fromCharCode(...codes));
+	}
+	return chunks.join("");
+}
+/**
+* Decode bytes read from `filename` as UTF-8. Bytes that are not valid UTF-8 are decoded as Windows-1252
+* instead, with a warning naming the file, as Tweego does (`fileReadAllWithEncoding` in io.go), so a legacy
+* file keeps its non-ASCII characters instead of losing them to U+FFFD.
+*
+* The text is returned as decoded: a leading BOM and CR line endings are kept (see {@link normalizeSourceText}).
+*/
+function decodeText(bytes, filename) {
+	try {
+		return {
+			text: utf8Decoder.decode(bytes),
+			diagnostics: []
+		};
+	} catch {
+		return {
+			text: decodeWindows1252(bytes),
+			diagnostics: [{
+				level: "warning",
+				message: `read ${filename}: Invalid UTF-8; assuming charset is ${FALLBACK_CHARSET}.`,
+				file: filename
+			}]
+		};
+	}
+}
+/**
+* Read a text file: decode it with {@link decodeText} (UTF-8, or Windows-1252 when it is not valid UTF-8),
+* strip a leading BOM and convert CRLF and bare CR line endings to LF. This is the one path every file read
+* as text goes through: sources, modules, the head file, story formats and the config file.
+*
+* @param diagnostics Receives the warning when the file is not valid UTF-8. Without it, the file is decoded
+*   the same way and the warning is dropped.
+* @throws When the file cannot be read.
+*/
+function readUTF8(filename, diagnostics) {
+	const decoded = decodeText(readFileSync(filename), filename);
+	diagnostics?.push(...decoded.diagnostics);
+	return normalizeSourceText(decoded.text);
 }
 /** Read a file as base64. */
 function readBase64(filename) {
@@ -707,20 +1332,11 @@ function baseNameWithoutExt(filename) {
 /**
 * Story format discovery, loading, and SemVer matching.
 * Ported from formats.go + config.go.
+*
+* Every lookup (local folders here, the download cache and remote indices in remote-formats.ts)
+* goes through the same version parsing ({@link parseVersion}) and the same matching rules
+* ({@link selectFormatCandidate}).
 */
-/**
-* Attempt to fix non-strict JSON (trailing commas, single quotes, unquoted keys).
-*/
-function relaxedJSONParse(json) {
-	try {
-		return JSON.parse(json);
-	} catch {}
-	let fixed = json;
-	fixed = fixed.replace(/'([^'\\]*(?:\\.[^'\\]*)*)'/g, "\"$1\"");
-	fixed = fixed.replace(/(?<=^|[{,]\s*)([A-Za-z_$][A-Za-z0-9_$]*)\s*:/gm, "\"$1\":");
-	fixed = fixed.replace(/,\s*([}\]])/g, "$1");
-	return JSON.parse(fixed);
-}
 /** A `"setup": function` property, which Harlowe appends to its otherwise-JSON format object. */
 const SETUP_FUNCTION_PROPERTY = /,\s*"setup"\s*:\s*function\b/g;
 /** Drop a trailing `"setup": function(){…}` property from a format object, if it has one. */
@@ -730,151 +1346,239 @@ function stripSetupFunction(chunk) {
 	return lastIndex === -1 ? void 0 : chunk.slice(0, lastIndex) + "}";
 }
 /**
-* Parse the Twine 2 format.js JSON chunk.
-* Handles Harlowe's malformed JSON by stripping the "setup" function property. The workaround
-* keys on the property itself, so the same bytes parse whether they come from a `harlowe-3`
-* directory or a direct download.
-* Per spec, the name key is Optional.
+* 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`.
+*/
+function parseFormatObject(text, start, end) {
+	try {
+		return {
+			ok: true,
+			value: JSON.parse(text.slice(start, end))
+		};
+	} catch {}
+	try {
+		return {
+			ok: true,
+			value: parseRelaxedJSON(text, start, end)
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			error: e instanceof Error ? e.message : String(e)
+		};
+	}
+}
+/** Check a parsed format object's fields. Per spec, `name` is optional; `version` and `source` are required. */
+function toFormatJSON(raw) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {
+		ok: false,
+		reason: "Story format JSON chunk is not an object."
+	};
+	const obj = raw;
+	if (typeof obj.version !== "string") return {
+		ok: false,
+		reason: "Story format has no \"version\" string."
+	};
+	if (typeof obj.source !== "string") return {
+		ok: false,
+		reason: "Story format has no \"source\" string."
+	};
+	if (!parseVersion(obj.version)) return {
+		ok: false,
+		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",
+		version: obj.version,
+		source: obj.source,
+		proofing: obj.proofing === true
+	};
+	if (typeof obj.author === "string") data.author = obj.author;
+	if (typeof obj.description === "string") data.description = obj.description;
+	if (typeof obj.image === "string") data.image = obj.image;
+	if (typeof obj.url === "string") data.url = obj.url;
+	if (typeof obj.license === "string") data.license = obj.license;
+	return {
+		ok: true,
+		data
+	};
+}
+/**
+* Read the metadata of a Twine 2 format.js, or say why it cannot be used.
 *
-* @param _formatId No longer used; kept so existing callers keep compiling.
+* The object passed to `window.storyFormat()` may be strict JSON or a JavaScript object literal
+* (single quotes, unquoted keys, trailing commas, comments). String values come back exactly as
+* JavaScript evaluation gives them. Harlowe's function-valued `setup` property is dropped; the
+* workaround keys on the property itself, so the same bytes parse whether they come from a
+* `harlowe-3` directory or a direct download.
 */
-function parseFormatJSON(source, _formatId) {
+function decodeFormatJSON(source) {
 	const first = source.indexOf("{");
 	const last = source.lastIndexOf("}");
-	if (first === -1 || last === -1) return null;
-	const chunk = source.slice(first, last + 1);
-	const parse = (json) => {
-		const raw = relaxedJSONParse(json);
-		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
-		const obj = raw;
-		if (typeof obj.version !== "string" || typeof obj.source !== "string") return null;
-		if (!parseSemver(obj.version)) return null;
-		const result = {
-			name: typeof obj.name === "string" ? obj.name : "Untitled Story Format",
-			version: obj.version,
-			source: obj.source,
-			proofing: obj.proofing === true
-		};
-		if (typeof obj.author === "string") result.author = obj.author;
-		if (typeof obj.description === "string") result.description = obj.description;
-		if (typeof obj.image === "string") result.image = obj.image;
-		if (typeof obj.url === "string") result.url = obj.url;
-		if (typeof obj.license === "string") result.license = obj.license;
-		return result;
+	if (first === -1 || last < first) return {
+		ok: false,
+		reason: "Could not find Twine 2 style story format JSON chunk."
+	};
+	const parsed = parseFormatObject(source, first, last + 1);
+	if (parsed.ok) return toFormatJSON(parsed.value);
+	const stripped = stripSetupFunction(source.slice(first, last + 1));
+	const retried = stripped === void 0 ? void 0 : parseFormatObject(stripped, 0, stripped.length);
+	if (retried?.ok) return toFormatJSON(retried.value);
+	return {
+		ok: false,
+		reason: `Could not decode story format JSON chunk: ${parsed.error}`
 	};
+}
+/**
+* Parse the Twine 2 format.js JSON chunk; null when it cannot be used ({@link decodeFormatJSON}
+* gives the reason).
+*
+* @param _formatId No longer used; kept so existing callers keep compiling.
+*/
+function parseFormatJSON(source, _formatId) {
+	const result = decodeFormatJSON(source);
+	return result.ok ? result.data : null;
+}
+/** A directory's entries in a stable order, or none when it cannot be read. */
+function listDirectory(dir) {
 	try {
-		return parse(chunk);
+		return readdirSync(dir).sort();
 	} catch {
-		const stripped = stripSetupFunction(chunk);
-		if (stripped === void 0) return null;
-		try {
-			return parse(stripped);
-		} catch {
-			return null;
-		}
+		return [];
+	}
+}
+function isDirectory(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function isFile(path) {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
 	}
 }
 /**
-* Discover all story formats in the given search directories.
-* Implements SemVer-based version pruning: within each (name, major) group,
-* only the highest minor.patch survives.
+* Load the format in one folder: its format.js (Twine 2), else its header.html (Twine 1).
+* A format.js that cannot be used is reported as a warning, as Tweego does.
 */
-function discoverFormats(searchDirs) {
-	const formats = /* @__PURE__ */ new Map();
-	const baseFilenames = ["format.js", "header.html"];
-	for (const searchDir of searchDirs) {
+function loadFormatDir(searchDir, id, diagnostics) {
+	const formatDir = join(searchDir, id);
+	if (!isDirectory(formatDir)) return void 0;
+	for (const baseFilename of ["format.js", "header.html"]) {
+		const filename = join(formatDir, baseFilename);
+		if (!isFile(filename)) continue;
+		if (baseFilename === "header.html") return {
+			id,
+			filename,
+			isTwine2: false,
+			name: id,
+			version: "",
+			proofing: false
+		};
+		const encoding = [];
+		let decoded;
 		try {
-			if (!statSync(searchDir).isDirectory()) continue;
-		} catch {
-			continue;
+			decoded = decodeFormatJSON(readUTF8(filename, encoding));
+		} catch (e) {
+			decoded = {
+				ok: false,
+				reason: `Could not read ${filename}: ${e instanceof Error ? e.message : String(e)}`
+			};
 		}
-		let entries;
-		try {
-			entries = readdirSync(searchDir);
-		} catch {
+		if (!decoded.ok) {
+			diagnostics?.push(...encoding);
+			diagnostics?.push({
+				level: "warning",
+				message: `format ${id}: Skipping format; ${decoded.reason} (${filename})`
+			});
 			continue;
 		}
-		for (const entry of entries) {
-			const formatDir = join(searchDir, entry);
-			try {
-				if (!statSync(formatDir).isDirectory()) continue;
-			} catch {
-				continue;
-			}
-			for (const baseFilename of baseFilenames) {
-				const formatFilename = join(formatDir, baseFilename);
-				try {
-					if (!statSync(formatFilename).isFile()) continue;
-				} catch {
-					continue;
-				}
-				const isTwine2 = baseFilename === "format.js";
-				const format = {
-					id: entry,
-					filename: formatFilename,
-					isTwine2,
-					name: "",
-					version: "",
-					proofing: false
-				};
-				if (isTwine2) try {
-					const data = parseFormatJSON(readUTF8(formatFilename), entry);
-					if (!data) continue;
-					format.name = data.name;
-					format.version = data.version;
-					format.proofing = data.proofing ?? false;
-					if (data.author) format.author = data.author;
-					if (data.description) format.description = data.description;
-					if (data.image) format.image = data.image;
-					if (data.url) format.url = data.url;
-					if (data.license) format.license = data.license;
-				} catch {
-					continue;
-				}
-				else format.name = entry;
-				formats.set(entry, format);
-				break;
-			}
-		}
+		const { data } = decoded;
+		const format = {
+			id,
+			filename,
+			isTwine2: true,
+			name: data.name,
+			version: data.version,
+			proofing: data.proofing ?? false
+		};
+		if (data.author) format.author = data.author;
+		if (data.description) format.description = data.description;
+		if (data.image) format.image = data.image;
+		if (data.url) format.url = data.url;
+		if (data.license) format.license = data.license;
+		return format;
+	}
+}
+/**
+* Discover every story format in the search directories, keyed by folder name (the format ID),
+* without version pruning.
+*
+* Directories are searched in order, and a later directory outranks an earlier one: when two hold
+* the same folder name, the later one's format is kept. The map iterates in that order too, lowest
+* rank first. Formats that cannot be used are left out, with a warning in `diagnostics`.
+*/
+function discoverAllFormats(searchDirs, diagnostics) {
+	const formats = /* @__PURE__ */ new Map();
+	for (const searchDir of searchDirs) for (const entry of listDirectory(searchDir)) {
+		const format = loadFormatDir(searchDir, entry, diagnostics);
+		if (!format) continue;
+		formats.delete(entry);
+		formats.set(entry, format);
 	}
-	pruneFormats(formats);
 	return formats;
 }
+/** The version a format is pruned and selected by, or null for one outside SemVer pruning. */
+function prunableVersion(format) {
+	return format.isTwine2 && format.name ? parseVersion(format.version) : null;
+}
+/** The search directory a discovered format was found in. */
+function searchDirOf(format) {
+	return dirname(dirname(format.filename));
+}
 /**
-* Prune formats by SemVer: within each (name, major) group,
-* keep only the highest version. First-found wins for same name+version.
+* Prune formats by SemVer: within each (name, major) group, keep only the version with the highest
+* precedence (a release outranks its prereleases). Between equal versions, the folder in the
+* higher-ranked search directory wins, and within one directory the first folder name in sort
+* order. Returns a new map in the same order.
+*
+* Pruning serves name-based selection and listings. An explicit format ID is looked up in the
+* unpruned map, so a pinned folder is used even when another folder holds a newer version.
 */
 function pruneFormats(formats) {
-	const bestByNameMajor = /* @__PURE__ */ new Map();
-	const seenNameVersion = /* @__PURE__ */ new Set();
-	for (const [id, f] of formats) {
-		if (!f.isTwine2 || !f.name || !f.version) continue;
-		const v = parseSemver(f.version);
-		if (!v) continue;
-		const nameVersionKey = `${f.name}@${f.version}`;
-		if (seenNameVersion.has(nameVersionKey)) {
-			formats.delete(id);
-			continue;
-		}
-		seenNameVersion.add(nameVersionKey);
-		const groupKey = `${f.name}@${v[0]}`;
-		const existing = bestByNameMajor.get(groupKey);
-		if (!existing || semverCompare(v, existing.version) > 0) bestByNameMajor.set(groupKey, {
-			id,
-			version: v
+	const dirRank = /* @__PURE__ */ new Map();
+	for (const format of formats.values()) {
+		const dir = searchDirOf(format);
+		if (!dirRank.has(dir)) dirRank.set(dir, dirRank.size);
+	}
+	const rankOf = (format) => dirRank.get(searchDirOf(format)) ?? 0;
+	const best = /* @__PURE__ */ new Map();
+	for (const format of formats.values()) {
+		const version = prunableVersion(format);
+		if (!version) continue;
+		const group = `${format.name}@${version.major}`;
+		const current = best.get(group);
+		const order = current ? compareVersions(version, current.version) : 1;
+		if (order > 0 || order === 0 && current && rankOf(format) > rankOf(current.format)) best.set(group, {
+			format,
+			version
 		});
 	}
-	for (const [id, f] of [...formats]) {
-		if (!f.isTwine2 || !f.name || !f.version) continue;
-		const v = parseSemver(f.version);
-		if (!v) continue;
-		const groupKey = `${f.name}@${v[0]}`;
-		const best = bestByNameMajor.get(groupKey);
-		if (best && best.id !== id) formats.delete(id);
-	}
+	return new Map([...formats].filter(([id, format]) => {
+		const version = prunableVersion(format);
+		return version === null || best.get(`${format.name}@${version.major}`)?.format.id === id;
+	}));
 }
 /**
-* Get the default format search directories.
+* Get the format search directories, lowest rank first: the story format subdirectories of the
+* home directory, then of the working directory, then each `TWEEGO_PATH` entry, then `extraPaths`
+* (`formatPaths`). A later directory outranks an earlier one for the same format folder name, so
+* `formatPaths` override `TWEEGO_PATH`, which overrides the home and working directories, as in
+* Tweego.
 */
 function getFormatSearchDirs(extraPaths = [], useTweegoPath = true) {
 	const subdirNames = [
@@ -889,41 +1593,27 @@ function getFormatSearchDirs(extraPaths = [], useTweegoPath = true) {
 		basePaths.add(homedir());
 	} catch {}
 	basePaths.add(process.cwd());
-	const dirs = [];
-	for (const base of basePaths) for (const sub of subdirNames) {
-		const dir = join(base, sub);
-		try {
-			if (statSync(dir).isDirectory()) dirs.push(dir);
-		} catch {}
-	}
+	const dirs = [...basePaths].flatMap((base) => subdirNames.map((sub) => join(base, sub))).filter(isDirectory);
+	const tweegoPath = useTweegoPath ? process.env.TWEEGO_PATH : void 0;
+	if (tweegoPath) dirs.push(...tweegoPath.split(process.platform === "win32" ? ";" : ":"));
 	dirs.push(...extraPaths);
-	if (useTweegoPath) {
-		const tweegoPath = process.env.TWEEGO_PATH;
-		if (tweegoPath) dirs.push(...tweegoPath.split(process.platform === "win32" ? ";" : ":"));
-	}
 	return dirs;
 }
-/** Parse a simple semver string into [major, minor, patch]. */
+/**
+* Parse a version string into [major, minor, patch]. Accepts what {@link parseVersion} accepts
+* (`v1.2.3`, `1.2`, `2.0.0-beta.1`); the prerelease and build metadata are dropped.
+*/
 function parseSemver(v) {
-	const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
-	if (!m) return null;
-	return [
-		Number(m[1]),
-		Number(m[2]),
-		Number(m[3])
-	];
-}
-function semverCompare(a, b) {
-	const [aMajor, aMinor, aPatch] = a;
-	const [bMajor, bMinor, bPatch] = b;
-	if (aMajor !== bMajor) return aMajor - bMajor;
-	if (aMinor !== bMinor) return aMinor - bMinor;
-	if (aPatch !== bPatch) return aPatch - bPatch;
-	return 0;
+	const parsed = parseVersion(v);
+	return parsed ? [
+		parsed.major,
+		parsed.minor,
+		parsed.patch
+	] : null;
 }
 /** Build a directory-style format ID from a name and version, e.g. ('SugarCube', '2.37.3') → 'sugarcube-2'. */
 function makeFormatId(name, version) {
-	const major = parseSemver(version)?.[0] ?? 0;
+	const major = parseVersion(version)?.major ?? 0;
 	return `${name.toLowerCase().replace(/\s+/g, "-")}-${major}`;
 }
 /** Describe a format request for diagnostics. */
@@ -934,81 +1624,164 @@ function describeFormatRequest(request) {
 		default: throw new Error(`unhandled format request: ${JSON.stringify(request)}`);
 	}
 }
-/**
-* Pick the candidate that best answers a format request.
-*
-* - An ID request ('sugarcube-2') matches a candidate whose name and major version build that ID,
-*   and takes the greatest such version.
-* - A name request matches the name case-insensitively. An exact version wins outright; otherwise
-*   the greatest version with the same major that is not older than the one asked for (or, with
-*   `allowOlder`, the greatest same-major version). An unparseable requested version takes the
-*   greatest version of any major.
-*/
-function selectFormatCandidate(request, candidates, describe, options = {}) {
-	const allowOlder = options.allowOlder ?? false;
-	const wanted = request.kind === "name" ? parseSemver(request.version) : null;
+/** {@link selectFormatCandidate} over one set of candidates, matching names without regard to case. */
+function pickFormatCandidate(request, candidates, describe, allowOlder) {
+	const wanted = request.kind === "name" ? parseVersion(request.version) : null;
 	let best;
 	for (const candidate of candidates) {
 		const { name, version } = describe(candidate);
-		const have = parseSemver(version);
+		const have = parseVersion(version);
 		if (!have) continue;
 		if (request.kind === "id") {
 			if (makeFormatId(name, version) !== request.id.toLowerCase()) continue;
 		} else {
 			if (name.toLowerCase() !== request.name.toLowerCase()) continue;
 			if (wanted) {
-				if (semverCompare(have, wanted) === 0) return candidate;
-				if (have[0] !== wanted[0]) continue;
-				if (!allowOlder && semverCompare(have, wanted) < 0) continue;
+				const order = compareVersions(have, wanted);
+				if (order === 0) return candidate;
+				if (have.major !== wanted.major) continue;
+				if (!allowOlder && order < 0) continue;
 			}
 		}
-		if (!best || semverCompare(have, best.version) > 0) best = {
+		if (!best || compareVersions(have, best.version) > 0) best = {
 			candidate,
 			version: have
 		};
 	}
 	return best?.candidate;
 }
-/** Get format ID from Twine 2 name and version, using SemVer major matching. */
-function getFormatIdByNameAndVersion(formats, name, version) {
-	const wanted = parseSemver(version);
-	let bestVersion = null;
-	let bestId;
-	for (const [id, f] of formats) {
-		if (!f.isTwine2 || f.name !== name) continue;
-		const have = parseSemver(f.version);
-		if (!have) continue;
-		if (wanted === null || have[0] === wanted[0] && semverCompare(have, wanted) >= 0) {
-			if (!bestVersion || semverCompare(have, bestVersion) > 0) {
-				bestVersion = have;
-				bestId = id;
-			}
-		}
+/**
+* Pick the candidate that best answers a format request. Local folders, the download cache and
+* remote indices all select through this one function.
+*
+* - An ID request ('sugarcube-2') matches, without regard to case, a candidate whose name and
+*   major version build that ID, and takes the greatest such version.
+* - A name request matches the name without regard to case, but a candidate whose name matches in
+*   case too is preferred when one answers the request. An exact version (prerelease included)
+*   wins outright; otherwise the greatest version with the same major that is not older than the
+*   one asked for (or, with `allowOlder`, the greatest same-major version). An unparseable
+*   requested version takes the greatest version of any major.
+*
+* Versions compare by SemVer precedence ({@link compareVersions}), so a release outranks its
+* prereleases. Between equal versions, the earlier candidate wins.
+*/
+function selectFormatCandidate(request, candidates, describe, options = {}) {
+	const allowOlder = options.allowOlder ?? false;
+	if (request.kind === "name") {
+		const preferred = pickFormatCandidate(request, candidates.filter((c) => describe(c).name === request.name), describe, allowOlder);
+		if (preferred !== void 0) return preferred;
 	}
-	return bestId;
+	return pickFormatCandidate(request, candidates, describe, allowOlder);
+}
+/** The Twine 2 formats of a discovered map, those from higher-ranked search directories first. */
+function rankedTwine2Formats(formats) {
+	return [...formats.values()].filter((f) => f.isTwine2).reverse();
+}
+/**
+* Look a format ID up among discovered folders. The ID matches a folder name without regard to
+* case; an exact-case folder is preferred, then the highest-ranked one.
+*/
+function findFormatById(formats, id) {
+	const exact = formats.get(id);
+	if (exact) return exact;
+	const wanted = id.toLowerCase();
+	return [...formats.values()].reverse().find((f) => f.id.toLowerCase() === wanted);
+}
+/**
+* Read the story format source (for Twine 2, extract the `source` property from JSON).
+* `diagnostics` receives a warning when the format file is not valid UTF-8 (it is read as Windows-1252).
+*/
+function readFormatSource(format, diagnostics) {
+	const source = readUTF8(format.filename, diagnostics);
+	if (!format.isTwine2) return source;
+	const decoded = decodeFormatJSON(source);
+	if (!decoded.ok) throw new Error(`Cannot parse format ${format.id} JSON: ${decoded.reason}`);
+	return decoded.data.source;
 }
-/** Read the story format source (for Twine 2, extract the `source` property from JSON). */
-function readFormatSource(format) {
-	const source = readUTF8(format.filename);
-	if (format.isTwine2) {
-		const data = parseFormatJSON(source, format.id);
-		if (!data) throw new Error(`Cannot parse format ${format.id} JSON`);
-		return data.source;
+//#endregion
+//#region src/atomic-write.ts
+/**
+* Atomic file replacement, for every file twee-ts writes that something else may read
+* meanwhile: build output (which live-reload servers read on each change) and downloaded
+* story formats (which other twee-ts processes share).
+*/
+/**
+* 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.
+*
+* 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`);
+	try {
+		writeFileSync(temp, data, {
+			encoding: "utf-8",
+			flag: "wx"
+		});
+		keepPermissions(target, temp);
+		renameSync(temp, target);
+	} catch (e) {
+		rmSync(temp, { force: true });
+		throw writeError(path, e);
 	}
-	return source;
+}
+/** 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;
+	}
+}
+/**
+* Gives `temp` the permission bits of `target`, when `target` exists. Best effort: on a file
+* system without Unix permissions chmod can fail, and writing in place never kept them there either.
+*/
+function keepPermissions(target, temp) {
+	const existing = statSync(target, { throwIfNoEntry: false });
+	if (existing === void 0) return;
+	try {
+		chmodSync(temp, existing.mode & 4095);
+	} catch {}
+}
+/** `cause` as an error that names `path` and keeps the original error code. */
+function writeError(path, cause) {
+	const message = cause instanceof Error ? cause.message : String(cause);
+	const error = new Error(`Cannot write ${path}: ${message}`, { cause });
+	if (cause instanceof Error && "code" in cause) error.code = cause.code;
+	return error;
 }
 //#endregion
 //#region src/remote-formats.ts
 /**
 * Remote story format fetching, caching, and checksum verification.
 * Uses the Story Formats Archive (SFA) as the default source.
+*
+* Two caches hold downloads. Formats found through an index are shared by name and version
+* (`<cache>/<name>/<version>/format.js`). A format downloaded from a direct URL is kept under
+* that URL instead, so one project's copy never answers another project's request.
+* Cache files are replaced atomically, so another process never reads a partly written one.
 */
 const DEFAULT_SFA_INDICES = ["https://videlais.github.io/story-formats-archive/official/index.json", "https://videlais.github.io/story-formats-archive/unofficial/index.json"];
+/** The longest delay a timer accepts; a longer timeout means no limit. */
+const MAX_TIMER_DELAY = 2147483647;
 /** Get the cache directory for downloaded story formats. */
 function getCacheDir() {
 	const base = process.env["XDG_CACHE_HOME"] || join(homedir(), ".cache");
 	return join(base, "twee-ts", "storyformats");
 }
+/** The cache directory for formats downloaded from direct URLs, beside {@link getCacheDir}. */
+function getUrlCacheDir() {
+	return join(dirname(getCacheDir()), "storyformat-urls");
+}
+/** The name of one direct URL's cache entry: a hash of the URL, so each URL has its own. */
+function urlCacheKey(url) {
+	return createHash("sha256").update(url).digest("hex");
+}
 /**
 * Whether a string can serve as one directory name inside the cache: not empty, not `.` or `..`,
 * and free of path separators. Format names and versions come from downloaded metadata, so they
@@ -1018,7 +1791,7 @@ function isSafeSegment(segment) {
 	return segment !== "" && segment !== "." && segment !== ".." && !/[/\\\0]/.test(segment);
 }
 /** Whether absolute path `target` lies strictly inside absolute path `root`. */
-function isInside(root, target) {
+function isInside$1(root, target) {
 	const rel = relative(root, target);
 	return rel !== "" && !isAbsolute(rel) && rel.split(sep)[0] !== "..";
 }
@@ -1028,28 +1801,41 @@ function cachedFormatDir(name, version) {
 	if (!isSafeSegment(version) || !parseSemver(version)) throw new Error(`Refusing to cache story format "${name}" with an unsafe version: ${JSON.stringify(version)}`);
 	const root = resolve(getCacheDir());
 	const dir = resolve(root, name, version);
-	if (!isInside(root, dir)) throw new Error(`Refusing to cache a story format outside the cache directory ${root}: ${dir}`);
+	if (!isInside$1(root, dir)) throw new Error(`Refusing to cache a story format outside the cache directory ${root}: ${dir}`);
 	return dir;
 }
-/** Create `dir` as a plain directory, or check that it already is one (a symlink could lead out of the cache). */
+/** Whether `e` is a Node.js system error with the given code. */
+function hasErrorCode(e, code) {
+	return e instanceof Error && "code" in e && e.code === code;
+}
+/**
+* Create `dir` as a plain directory, or check that it already is one (a symlink could lead out of the cache).
+* A directory another process creates between the check and the mkdir is fine.
+*/
 function ensurePlainDirectory(dir) {
-	const stat = lstatSync(dir, { throwIfNoEntry: false });
-	if (stat === void 0) {
+	if (lstatSync(dir, { throwIfNoEntry: false }) === void 0) try {
 		mkdirSync(dir);
 		return;
+	} catch (e) {
+		if (!hasErrorCode(e, "EEXIST")) throw e;
 	}
-	if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`Refusing to write a story format outside the cache directory: ${dir} is not a plain directory`);
+	const stat = lstatSync(dir, { throwIfNoEntry: false });
+	if (stat === void 0 || stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`Refusing to write a story format outside the cache directory: ${dir} is not a plain directory`);
 }
-/** Write a downloaded format.js to `<cache>/<name>/<version>/format.js` and return its path. */
-function writeCachedFormat(name, version, text) {
-	const dir = cachedFormatDir(name, version);
-	const root = resolve(getCacheDir());
+/**
+* Write a downloaded format.js to `<root>/<...segments>/format.js`, replacing any earlier copy
+* atomically, and return its path. Every directory below `root` must be a plain one.
+*/
+function writeCacheEntry(root, segments, text) {
 	mkdirSync(root, { recursive: true });
-	ensurePlainDirectory(join(root, name));
-	ensurePlainDirectory(dir);
+	const dir = segments.reduce((parent, segment) => {
+		const child = join(parent, segment);
+		ensurePlainDirectory(child);
+		return child;
+	}, root);
 	const formatPath = join(dir, "format.js");
 	if (lstatSync(formatPath, { throwIfNoEntry: false })?.isSymbolicLink()) throw new Error(`Refusing to write a story format outside the cache directory: ${formatPath} is a symlink`);
-	writeFileSync(formatPath, text, "utf-8");
+	writeFileAtomic(formatPath, text);
 	return formatPath;
 }
 /** In-memory index cache, keyed by URL. Cleared each compile. */
@@ -1058,6 +1844,78 @@ const indexCache = /* @__PURE__ */ new Map();
 function clearIndexCache() {
 	indexCache.clear();
 }
+/** 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.
+*/
+function shareRequest(key, signal, 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;
+		const stopWaiting = () => {
+			if (!waiting) return;
+			waiting = false;
+			signal?.removeEventListener("abort", onAbort);
+			request.waiters--;
+		};
+		const onAbort = () => {
+			stopWaiting();
+			if (request.waiters === 0) {
+				if (sharedRequests.get(key) === request) sharedRequests.delete(key);
+				request.controller.abort(signal?.reason);
+			}
+			reject(signal?.reason);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+		request.promise.then((value) => {
+			stopWaiting();
+			resolve(value);
+		}, (e) => {
+			stopWaiting();
+			reject(e);
+		});
+	});
+}
+function startSharedRequest(key, start) {
+	const controller = new AbortController();
+	const request = {
+		promise: start(controller.signal),
+		controller,
+		waiters: 0
+	};
+	sharedRequests.set(key, request);
+	const forget = () => {
+		if (sharedRequests.get(key) === request) sharedRequests.delete(key);
+	};
+	request.promise.then(forget, forget);
+	return request;
+}
+/** The time limit for each request, from the caller's options. */
+function requestTimeout(options) {
+	const timeout = options.timeout ?? 3e4;
+	if (!(timeout >= 0)) throw new RangeError(`A story format request timeout must be 0 or more milliseconds, not ${timeout}`);
+	return timeout;
+}
+/**
+* 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>".
+*/
+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;
+	}
+}
 /** Validate that a JSON value is a valid SFAIndexEntry. */
 function isValidEntry(val) {
 	if (typeof val !== "object" || val === null || Array.isArray(val)) return false;
@@ -1073,15 +1931,18 @@ function validateSFAIndex(json) {
 		twine2: Array.isArray(obj["twine2"]) ? obj["twine2"].filter(isValidEntry) : []
 	};
 }
-/** Fetch and parse an SFA index.json, with in-memory caching. */
-async function fetchIndex(url) {
+/** Fetch and parse an SFA index.json, with in-memory caching. Concurrent calls for one URL share a request. */
+async function fetchIndex(url, options = {}) {
+	options.signal?.throwIfAborted();
 	const cached = indexCache.get(url);
 	if (cached) return cached;
-	const res = await fetch(url);
-	if (!res.ok) throw new Error(`Failed to fetch format index from ${url}: ${res.status} ${res.statusText}`);
-	const data = validateSFAIndex(await res.json());
-	indexCache.set(url, data);
-	return data;
+	const timeout = requestTimeout(options);
+	return shareRequest(`index\0${url}`, options.signal, async (signal) => {
+		const text = await fetchText(url, "fetch format index", signal, timeout);
+		const data = validateSFAIndex(JSON.parse(text));
+		indexCache.set(url, data);
+		return data;
+	});
 }
 /** Find the best matching entry in an SFA index for a name or ID request (twine2 entries first). */
 function findEntryForRequest(index, request) {
@@ -1102,84 +1963,138 @@ async function verifySHA256(content, expectedHex) {
 function getDownloadUrl(indexUrl, entry, formatType) {
 	return `${indexUrl.replace(/\/index\.json$/, "")}/${formatType}/${entry.name}/${entry.version}/format.js`;
 }
-/** Download a format, verify its checksum, write to cache, and return StoryFormatInfo. */
-async function fetchAndCacheFormat(entry, downloadUrl) {
-	cachedFormatDir(entry.name, entry.version);
-	const res = await fetch(downloadUrl);
-	if (!res.ok) throw new Error(`Failed to download format from ${downloadUrl}: ${res.status} ${res.statusText}`);
-	const text = await res.text();
-	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}`);
+/** The StoryFormatInfo of a Twine 2 format.js cached at `filename`. */
+function cachedFormatInfo(id, filename, data) {
 	return {
 		id,
-		filename: writeCachedFormat(entry.name, entry.version, text),
+		filename,
 		isTwine2: true,
 		name: data.name,
 		version: data.version,
 		proofing: data.proofing ?? false
 	};
 }
-/** Download a direct format.js URL, parse its JSON, cache it, and return StoryFormatInfo. */
-async function fetchDirectFormat(url) {
-	const res = await fetch(url);
-	if (!res.ok) throw new Error(`Failed to download format from ${url}: ${res.status} ${res.statusText}`);
-	const text = await res.text();
-	const data = parseFormatJSON(text);
-	if (!data) throw new Error(`Failed to parse format JSON from ${url}`);
-	return {
-		id: makeFormatId(data.name, data.version),
-		filename: writeCachedFormat(data.name, data.version, text),
-		isTwine2: true,
-		name: data.name,
-		version: data.version,
-		proofing: data.proofing ?? false
-	};
+/**
+* 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.
+*/
+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);
+	});
+}
+/**
+* Download a direct format.js URL, parse its JSON, cache it under that URL (apart from the
+* downloads shared by name and version), and return its StoryFormatInfo. Concurrent calls for
+* 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);
+	});
+}
+/** The copy of a direct format URL in the download cache, if it has been downloaded before. */
+function getCachedDirectFormat(url) {
+	const formatPath = join(getUrlCacheDir(), urlCacheKey(url), "format.js");
+	try {
+		if (!existsSync(formatPath)) return void 0;
+		const data = parseFormatJSON(readUTF8(formatPath));
+		if (!data) return void 0;
+		return cachedFormatInfo(makeFormatId(data.name, data.version), formatPath, data);
+	} catch {
+		return;
+	}
+}
+/**
+* Look a request up among direct format URLs, in order, and return the first format that
+* answers it. A URL downloaded before is answered by its cached copy without the network;
+* any other is downloaded (unless `offline`). When none answers and a download failed, the
+* last failure is thrown. An aborted signal rejects with its reason and tries no further URL.
+*
+* Internal, for format resolution; not part of the public API.
+*/
+async function resolveFormatUrls(request, urls, options = {}) {
+	let lastError;
+	for (const url of urls) {
+		const cached = getCachedDirectFormat(url);
+		if (cached) {
+			if (answers(request, cached)) return cached;
+			continue;
+		}
+		if (options.offline) continue;
+		try {
+			const info = await fetchDirectFormat(url, options);
+			if (answers(request, info)) return info;
+		} catch (e) {
+			if (options.signal?.aborted) throw options.signal.reason;
+			lastError = toError(e);
+		}
+	}
+	if (lastError) throw lastError;
+}
+/** Whether `info` is a format the request accepts. */
+function answers(request, info) {
+	return selectFormatCandidate(request, [info], (f) => f) !== void 0;
+}
+function toError(e) {
+	return e instanceof Error ? e : new Error(String(e));
 }
 /**
 * Resolve a story format request remotely, in the same order as {@link resolveRemoteFormat}.
 * An ID request such as 'sugarcube-2' matches the format whose name and major version build that ID
 * (SugarCube 2.x), taking the greatest version available.
 */
-async function resolveRemoteFormatRequest(request, indices, urls) {
+async function resolveRemoteFormatRequest(request, indices, urls, options = {}) {
+	options.signal?.throwIfAborted();
 	let lastError;
-	const cached = findCachedFormat(request);
-	if (cached && request.kind === "name" && isExactVersion(cached.version, request.version)) return cached;
-	for (const url of urls ?? []) try {
-		const info = await fetchDirectFormat(url);
-		if (selectFormatCandidate(request, [info], (f) => f)) return info;
+	try {
+		const direct = await resolveFormatUrls(request, urls ?? [], options);
+		if (direct) return direct;
 	} catch (e) {
-		lastError = e instanceof Error ? e : new Error(String(e));
+		if (options.signal?.aborted) throw options.signal.reason;
+		lastError = toError(e);
 	}
+	const cached = findCachedFormat(request);
+	if (cached && request.kind === "name" && sameVersion(cached.version, request.version)) return cached;
 	const allIndices = [...indices ?? [], ...DEFAULT_SFA_INDICES];
 	for (const indexUrl of allIndices) try {
-		const result = findEntryForRequest(await fetchIndex(indexUrl), request);
+		const result = findEntryForRequest(await fetchIndex(indexUrl, options), request);
 		if (result) {
 			const hit = getCachedFormat(result.entry.name, result.entry.version);
 			if (hit) return hit;
 			const downloadUrl = getDownloadUrl(indexUrl, result.entry, result.formatType);
-			return await fetchAndCacheFormat(result.entry, downloadUrl);
+			return await fetchAndCacheFormat(result.entry, downloadUrl, options);
 		}
 	} catch (e) {
-		lastError = e instanceof Error ? e : new Error(String(e));
+		if (options.signal?.aborted) throw options.signal.reason;
+		lastError = toError(e);
 	}
 	if (cached) return cached;
 	if (lastError) throw lastError;
 }
-/** Whether two version strings name the same SemVer version. */
-function isExactVersion(have, wanted) {
-	const a = parseSemver(have);
-	const b = parseSemver(wanted);
-	return a !== null && b !== null && a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
-}
 /**
 * Find the cached download that best answers a format request, without network access.
+* Only the downloads shared by name and version are searched, not those from direct URLs.
 * Matching follows {@link selectFormatCandidate}.
 */
 function findCachedFormat(request, options = {}) {
@@ -1191,18 +2106,11 @@ function getCachedFormat(name, version) {
 	const formatPath = join(getCacheDir(), name, version, "format.js");
 	try {
 		if (!existsSync(formatPath)) return void 0;
-		const source = readFileSync(formatPath, "utf-8");
+		const source = readUTF8(formatPath);
 		const id = makeFormatId(name, version);
 		const data = parseFormatJSON(source, id);
 		if (!data) return void 0;
-		return {
-			id,
-			filename: formatPath,
-			isTwine2: true,
-			name: data.name,
-			version: data.version,
-			proofing: data.proofing ?? false
-		};
+		return cachedFormatInfo(id, formatPath, data);
 	} catch {
 		return;
 	}
@@ -1260,44 +2168,65 @@ function formatRequestFor(formatId, storyFormat, storyFormatVersion, defaultId)
 		id: defaultId
 	};
 }
-/** Look a request up among the formats found in local format directories. */
-function findLocalFormat(formats, request) {
+/**
+* Look a request up among the formats found in local format directories. An ID names a folder, so
+* it is looked up among all of them; a name request selects by SemVer among the pruned formats.
+*/
+function findLocalFormat(all, pruned, request) {
 	switch (request.kind) {
-		case "id": return formats.get(request.id);
-		case "name": {
-			const id = getFormatIdByNameAndVersion(formats, request.name, request.version);
-			return id === void 0 ? void 0 : formats.get(id);
-		}
+		case "id": return findFormatById(all, request.id);
+		case "name": return selectFormatCandidate(request, rankedTwine2Formats(pruned), (f) => f);
 		default: throw new Error(`unhandled format request: ${JSON.stringify(request)}`);
 	}
 }
 /**
 * Resolve a format request to a story format.
 *
-* Order: local format directories, then the download cache, then remote sources (unless
-* `noRemote`). When a StoryData request names a version that none of them has, an older version of
+* Order: local format directories, then the project's direct format URLs (each one's cached
+* copy, else a download unless `noRemote`), then the download cache shared by name and version,
+* 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,
 * and the result is `undefined`.
 */
 async function resolveStoryFormat(request, options, diagnostics) {
 	const noRemote = options.noRemote ?? false;
-	const formats = discoverFormats(getFormatSearchDirs(options.formatPaths, options.useTweegoPath ?? true));
+	const all = discoverAllFormats(getFormatSearchDirs(options.formatPaths, options.useTweegoPath ?? true), diagnostics);
+	const pruned = pruneFormats(all);
 	const wanted = describeFormatRequest(request);
-	const local = findLocalFormat(formats, request);
+	const local = findLocalFormat(all, pruned, request);
 	if (local) return local;
+	const fetchOptions = {
+		signal: options.signal,
+		timeout: options.formatFetchTimeout
+	};
+	const warnOnFailure = async (lookup) => {
+		try {
+			return await lookup();
+		} catch (e) {
+			if (options.signal?.aborted) throw options.signal.reason;
+			diagnostics.push({
+				level: "warning",
+				message: `Remote format fetch failed for ${wanted}: ${e instanceof Error ? e.message : String(e)}`
+			});
+			return;
+		}
+	};
+	const direct = await warnOnFailure(() => resolveFormatUrls(request, options.formatUrls ?? [], {
+		...fetchOptions,
+		offline: noRemote
+	}));
+	if (direct) return direct;
 	const cached = findCachedFormat(request);
 	if (cached) return cached;
-	if (!noRemote) try {
-		const remote = await resolveRemoteFormatRequest(request, options.formatIndices, options.formatUrls);
+	if (!noRemote) {
+		const remote = await warnOnFailure(() => resolveRemoteFormatRequest(request, options.formatIndices, [], fetchOptions));
 		if (remote) return remote;
-	} catch (e) {
-		diagnostics.push({
-			level: "warning",
-			message: `Remote format fetch failed for ${wanted}: ${e instanceof Error ? e.message : String(e)}`
-		});
 	}
 	if (request.kind === "name") {
-		const older = selectFormatCandidate(request, [...formats.values()].filter((f) => f.isTwine2), (f) => f, { allowOlder: true }) ?? findCachedFormat(request, { allowOlder: true });
+		const older = selectFormatCandidate(request, rankedTwine2Formats(pruned), (f) => f, { allowOlder: true }) ?? findCachedFormat(request, { allowOlder: true });
 		if (older) {
 			diagnostics.push({
 				level: "warning",
@@ -1309,7 +2238,7 @@ async function resolveStoryFormat(request, options, diagnostics) {
 	const reason = noRemote ? " (remote fetching disabled)" : "";
 	diagnostics.push({
 		level: "error",
-		message: `Story format ${wanted} is not available${reason}. Found: ${[...formats.keys()].join(", ") || "none"}`
+		message: `Story format ${wanted} is not available${reason}. Found: ${[...all.keys()].join(", ") || "none"}`
 	});
 }
 //#endregion
@@ -1578,12 +2507,14 @@ function twee2ToV3(s) {
 * Parse Twee source text into passages.
 *
 * The source is normalized first, as files are when they are read: a leading UTF-8 BOM is
-* removed and CRLF and bare CR line endings become LF.
+* removed and CRLF and bare CR line endings become LF. A BOM at the start of a later line,
+* directly before `::` (left there by concatenating files), is removed too, so that line
+* stays a passage header.
 */
 function parseTwee(source, options = {}) {
 	const { filename = "<inline>", trim = true, twee2Compat = false } = options;
 	const diagnostics = [];
-	const normalized = normalizeSourceText(source);
+	const normalized = normalizeTweeSourceText(source);
 	const tweeSource = twee2Compat ? twee2ToV3(normalized) : normalized;
 	const passages = [];
 	let current = null;
@@ -4418,17 +5349,21 @@ function parseDocument(data, options) {
 * Ported from storyload.go:loadHTML().
 */
 /**
-* Parse a Twine 2 or Twine 1 compiled HTML file back into a Story model.
-* Tweego always trims passage text; here `trim: false` keeps it exactly, as for Twee sources.
+* `decompileHTML()` for loading an HTML file into a compile. The importer's StoryData passage is
+* checked when it is added to the story being compiled, which reports a missing or invalid IFID,
+* so the IFID is not reported here as well.
 */
-function decompileHTML(html, options = {}) {
+function decompileHTMLForImport(html, options = {}) {
+	return decompile(html, options, { ifid: false });
+}
+function decompile(html, options, checks) {
 	const diagnostics = [];
 	const story = createStory();
 	const passageText = options.trim === false ? (text) => text : (text) => text.trim();
 	const doc = parseDocument(html);
 	const twine2Data = findElement(doc, "tw-storydata");
 	if (twine2Data) {
-		decompileTwine2(twine2Data, story, passageText, diagnostics);
+		decompileTwine2(twine2Data, story, passageText, checks, diagnostics);
 		return {
 			story,
 			diagnostics
@@ -4451,7 +5386,7 @@ function decompileHTML(html, options = {}) {
 		diagnostics
 	};
 }
-function decompileTwine2(storyData, story, passageText, diagnostics) {
+function decompileTwine2(storyData, story, passageText, checks, diagnostics) {
 	let startnode = 0;
 	const attrs = storyData.attribs ?? {};
 	if (attrs["name"]) story.name = attrs["name"];
@@ -4463,7 +5398,8 @@ function decompileTwine2(storyData, story, passageText, diagnostics) {
 		});
 		else startnode = parsed;
 	}
-	if (attrs["ifid"]) story.ifid = attrs["ifid"].toUpperCase();
+	if (attrs["ifid"]) story.ifid = normalizeIFID(attrs["ifid"]);
+	if (checks.ifid) diagnostics.push(...storyDataIFIDDiagnostics(attrs["ifid"] ?? ""));
 	if (attrs["zoom"]) {
 		const parsed = parseFloat(attrs["zoom"]);
 		if (Number.isNaN(parsed)) diagnostics.push({
@@ -4476,7 +5412,9 @@ function decompileTwine2(storyData, story, passageText, diagnostics) {
 	if (attrs["format"]) story.twine2.format = attrs["format"];
 	if (attrs["format-version"]) story.twine2.formatVersion = attrs["format-version"];
 	if (attrs["options"]) for (const opt of attrs["options"].split(/\s+/).filter((s) => s.length > 0)) story.twine2.options.set(opt, true);
-	for (const node of storyData.children ?? []) {
+	const children = storyData.children ?? [];
+	const takenNames = new Set(children.filter((node) => node.type === "tag" && node.name === "tw-passagedata").map(passageDataName));
+	for (const node of children) {
 		if (node.type !== "tag" && node.type !== "style" && node.type !== "script") continue;
 		switch (node.name) {
 			case "style":
@@ -4484,11 +5422,17 @@ function decompileTwine2(storyData, story, passageText, diagnostics) {
 				const content = getTextContent(node);
 				if (content.trim().length === 0) continue;
 				const text = passageText(content);
-				storyAdd(story, {
-					name: node.name === "style" ? "Story Stylesheet" : "Story JavaScript",
+				const base = node.name === "style" ? "Story Stylesheet" : "Story JavaScript";
+				const name = freeName(base, (n) => !takenNames.has(n));
+				takenNames.add(name);
+				storyAdd(story, withGeneratedName({
+					name,
 					tags: node.name === "style" ? ["stylesheet"] : ["script"],
 					text
-				}, diagnostics);
+				}, {
+					kind: "code",
+					base
+				}), diagnostics);
 				break;
 			}
 			case "tw-tag": {
@@ -4501,7 +5445,7 @@ function decompileTwine2(storyData, story, passageText, diagnostics) {
 			case "tw-passagedata": {
 				let pid = 0;
 				const pAttrs = node.attribs ?? {};
-				const name = pAttrs["name"] ?? "";
+				const name = passageDataName(node);
 				const tags = pAttrs["tags"] ? pAttrs["tags"].split(/\s+/).filter((s) => s.length > 0) : [];
 				const metadata = {};
 				if (pAttrs["pid"]) {
@@ -4532,11 +5476,29 @@ function decompileTwine2(storyData, story, passageText, diagnostics) {
 		text: marshalStoryData(story)
 	}, diagnostics);
 }
+function passageDataName(node) {
+	return node.attribs?.["name"] ?? "";
+}
+/** Diagnostics for the `ifid` attribute of `tw-storydata`; `value` is empty when it is missing. */
+function storyDataIFIDDiagnostics(value) {
+	if (value === "") return [{
+		level: "warning",
+		message: "Story IFID not found; the \"tw-storydata\" content attribute \"ifid\" is missing or empty."
+	}];
+	const err = validateIFID(value);
+	if (err === null) return [];
+	return [{
+		level: "warning",
+		message: `Cannot parse "tw-storydata" content attribute "ifid" as an IFID; value "${value}" (${err}).`
+	}];
+}
 function decompileTwine1(storeArea, story, passageText, diagnostics) {
 	const passages = (storeArea.children ?? []).filter(isTiddler).map((node) => tiddlerToPassage(node, passageText));
 	const obfuscated = isRot13Obfuscated(passages);
-	for (const p of passages) storyAdd(story, obfuscated && p.name !== "StorySettings" ? {
+	for (const p of passages) storyAdd(story, obfuscated && isObfuscatable(p) ? {
 		...p,
+		name: rot13(p.name),
+		tags: p.tags.map(rot13),
 		text: rot13(p.text)
 	} : p, diagnostics);
 }
@@ -4681,7 +5643,12 @@ function loadSources(story, filenames, opts, diagnostics, processedFiles) {
 function loadInlineSources(story, sources, opts, diagnostics) {
 	for (const source of sources) {
 		if (typeof source === "string") continue;
-		const content = normalizeSourceText(typeof source.content === "string" ? source.content : source.content.toString("utf-8"));
+		const decoded = typeof source.content === "string" ? {
+			text: source.content,
+			diagnostics: []
+		} : decodeText(source.content, source.filename);
+		diagnostics.push(...decoded.diagnostics);
+		const content = normalizeSourceText(decoded.text);
 		const ext = normalizedFileExt(source.filename);
 		switch (ext) {
 			case "":
@@ -4700,18 +5667,10 @@ function loadInlineSources(story, sources, opts, diagnostics) {
 				break;
 			}
 			case "css":
-				storyAdd(story, {
-					name: basename(source.filename),
-					tags: ["stylesheet"],
-					text: content
-				}, diagnostics);
+				storyAdd(story, codePassage(basename(source.filename), "stylesheet", content), diagnostics);
 				break;
 			case "js":
-				storyAdd(story, {
-					name: basename(source.filename),
-					tags: ["script"],
-					text: content
-				}, diagnostics);
+				storyAdd(story, codePassage(basename(source.filename), "script", content), diagnostics);
 				break;
 			default: diagnostics.push({
 				level: "warning",
@@ -4721,35 +5680,60 @@ function loadInlineSources(story, sources, opts, diagnostics) {
 	}
 }
 function parseTweeFile(filename, opts) {
-	const result = parseTwee(readUTF8(filename), {
+	const readDiagnostics = [];
+	const result = parseTwee(readUTF8(filename, readDiagnostics), {
 		filename,
 		trim: opts.trim ?? true,
 		twee2Compat: opts.twee2Compat ?? false
 	});
 	return {
 		passages: result.passages,
-		diagnostics: [...result.diagnostics]
+		diagnostics: [...readDiagnostics, ...result.diagnostics]
 	};
 }
+/**
+* A stylesheet or script passage named after its file, as Tweego names it. The name only labels
+* the code, so when another passage has it, the passage takes a free one (see `storyAdd()`).
+*/
+function codePassage(name, tag, text) {
+	return withGeneratedName({
+		name,
+		tags: [tag],
+		text
+	}, {
+		kind: "code",
+		base: name
+	});
+}
+/** Mark every passage of a parse result as a code passage named after its file. */
+function codeNames(result) {
+	for (const p of result.passages) withGeneratedName(p, {
+		kind: "code",
+		base: p.name
+	});
+	return result;
+}
 function parseTaggedFile(tag, filename) {
-	const source = readUTF8(filename);
+	const diagnostics = [];
+	const source = readUTF8(filename, diagnostics);
 	return {
-		passages: [{
-			name: basename(filename),
-			tags: [tag],
-			text: source
-		}],
-		diagnostics: []
+		passages: [codePassage(basename(filename), tag, source)],
+		diagnostics
 	};
 }
 function parseMediaFile(tag, filename) {
 	const source = readBase64(filename);
+	const name = baseNameWithoutExt(filename);
 	return {
-		passages: [{
-			name: baseNameWithoutExt(filename),
+		passages: [withGeneratedName({
+			name,
 			tags: [tag],
 			text: `data:${mediaTypeFromFilename(filename)};base64,${source}`
-		}],
+		}, {
+			kind: "media",
+			base: name,
+			file: filename
+		})],
 		diagnostics: []
 	};
 }
@@ -4758,24 +5742,27 @@ function parseFontFile(filename) {
 	const name = basename(filename);
 	const family = baseNameWithoutExt(filename);
 	const ext = normalizedFileExt(filename);
-	return {
+	const mediaType = mediaTypeFromExt(ext);
+	const hint = fontFormatHint(ext);
+	return codeNames({
 		passages: [{
 			name,
 			tags: ["stylesheet"],
-			text: `@font-face {\n\tfont-family: "${family}";\n\tsrc: url("data:${mediaTypeFromExt(ext)};base64,${source}") format("${fontFormatHint(ext)}");\n}`
+			text: `@font-face {\n\tfont-family: "${cssStringEscape(family)}";\n\tsrc: url("data:${mediaType};base64,${source}") format("${hint}");\n}`
 		}],
 		diagnostics: []
-	};
+	});
 }
 function parseHTMLFile(filename, opts) {
-	const { story, diagnostics } = decompileHTML(readUTF8(filename), { trim: opts.trim ?? true });
+	const readDiagnostics = [];
+	const { story, diagnostics } = decompileHTMLForImport(readUTF8(filename, readDiagnostics), { trim: opts.trim ?? true });
 	return {
 		passages: story.name !== "" && !storyHas(story, "StoryTitle") ? [{
 			name: "StoryTitle",
 			tags: [],
 			text: story.name
 		}, ...story.passages] : story.passages,
-		diagnostics: [...diagnostics]
+		diagnostics: [...readDiagnostics, ...diagnostics]
 	};
 }
 /**
@@ -4848,6 +5835,7 @@ function loadTwee(story, filename, opts, diagnostics) {
 }
 function loadTagged(story, tag, filename, diagnostics) {
 	const result = parseTaggedFile(tag, filename);
+	diagnostics.push(...result.diagnostics);
 	for (const p of result.passages) storyAdd(story, p, diagnostics);
 }
 function loadMedia(story, tag, filename, diagnostics) {
@@ -4864,6 +5852,7 @@ function loadFont(story, filename, diagnostics) {
 */
 function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles, cache, changedFiles) {
 	const currentFiles = /* @__PURE__ */ new Set();
+	const changedPaths = changedFiles === void 0 ? void 0 : new Set([...changedFiles].map((f) => resolve(f)));
 	for (const filename of filenames) {
 		if (processedFiles.has(filename)) {
 			diagnostics.push({
@@ -4876,8 +5865,8 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 		const optionsKey = parseOptionsKey(filename, opts);
 		const entry = cache.get(filename);
 		const cached = entry?.parseOptionsKey === optionsKey ? entry : void 0;
-		const changed = changedFiles?.has(filename) ?? false;
-		if (changedFiles && cached && !changed) {
+		const changed = changedPaths?.has(resolve(filename)) ?? false;
+		if (changedPaths && cached && !changed) {
 			diagnostics.push(...cached.diagnostics);
 			for (const p of cached.passages) storyAdd(story, p, diagnostics);
 			processedFiles.add(filename);
@@ -4887,6 +5876,7 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 		try {
 			mtimeMs = statSync(filename).mtimeMs;
 		} catch {
+			cache.delete(filename);
 			continue;
 		}
 		if (cached && !changed && cached.mtimeMs === mtimeMs) {
@@ -4907,6 +5897,7 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 			diagnostics.push(...result.diagnostics);
 			for (const p of result.passages) storyAdd(story, p, diagnostics);
 		} catch (e) {
+			cache.delete(filename);
 			diagnostics.push({
 				level: "error",
 				message: `load ${filename}: ${e instanceof Error ? e.message : String(e)}`,
@@ -4924,6 +5915,164 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 	}, diagnostics);
 }
 //#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, "\\$&");
+}
+/** Replace the `slots` placeholders found in `template`, without scanning inserted text. */
+function fillTemplate(template, slots) {
+	return fillTemplateParts([{
+		kind: "scan",
+		text: template,
+		slots
+	}]);
+}
+/**
+* Fill the parts of a template in order, joined. A `'first'` slot replaced in one part is not replaced again in a
+* later part that lists the same slot object.
+*/
+function fillTemplateParts(parts) {
+	const filled = /* @__PURE__ */ new Set();
+	return parts.map((part) => {
+		if (part.kind === "verbatim" || part.slots.length === 0) return part.text;
+		const { slots } = part;
+		const pattern = new RegExp(slots.map((slot) => `(${slot.pattern})`).join("|"), "g");
+		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;
+			filled.add(slot);
+			return slot.replacement(match);
+		});
+	}).join("");
+}
+//#endregion
+//#region src/modules.ts
+/**
+* Load modules and return HTML tags to inject before the closing head tag. `diagnostics` receives a warning for
+* each module that is not valid UTF-8 (it is read as Windows-1252).
+*/
+function loadModules(filenames, diagnostics) {
+	const processed = /* @__PURE__ */ new Set();
+	const headTags = [];
+	for (const filename of filenames) {
+		if (processed.has(filename)) continue;
+		const ext = normalizedFileExt(filename);
+		let tag = null;
+		switch (ext) {
+			case "css":
+				tag = loadModuleTagged("style", filename, diagnostics);
+				break;
+			case "js":
+				tag = loadModuleTagged("script", filename, diagnostics);
+				break;
+			case "otf":
+			case "ttf":
+			case "woff":
+			case "woff2":
+				tag = loadModuleFont(filename);
+				break;
+			default: continue;
+		}
+		if (tag) headTags.push(tag);
+		processed.add(filename);
+	}
+	return headTags.join("\n");
+}
+function loadModuleTagged(tag, filename, diagnostics) {
+	const source = readUTF8(filename, diagnostics).trim();
+	if (source.length === 0) return null;
+	return `<${tag} id="${`${tag}-module-${slugify(baseNameWithoutExt(filename))}`}" type="${tag === "script" ? "text/javascript" : "text/css"}">${tag === "script" ? scriptContentEscape(source) : styleContentEscape(source)}</${tag}>`;
+}
+function loadModuleFont(filename) {
+	const source = readBase64(filename);
+	const family = baseNameWithoutExt(filename);
+	const idSlug = `style-module-${slugify(family)}`;
+	const ext = normalizedFileExt(filename);
+	const mediaType = mediaTypeFromExt(ext);
+	const hint = fontFormatHint(ext);
+	return `<style id="${idSlug}" type="text/css">@font-face {\n\tfont-family: "${cssStringEscape(family)}";\n\tsrc: url("data:${mediaType};base64,${source}") format("${hint}");\n}</style>`;
+}
+/**
+* Load the module tags and head file content to inject into the head (see `placeHead()`), joined by newlines,
+* or `''` when there is nothing to inject.
+*/
+function loadHeadContent(modulePaths, headFile, diagnostics) {
+	const parts = [];
+	if (modulePaths.length > 0) {
+		const modules = loadModules(modulePaths, diagnostics).trim();
+		if (modules.length > 0) parts.push(modules);
+	}
+	if (headFile) try {
+		const source = readUTF8(headFile, diagnostics).trim();
+		if (source.length > 0) parts.push(source);
+	} catch (e) {
+		diagnostics?.push({
+			level: "warning",
+			message: `Failed to read head file "${headFile}": ${e instanceof Error ? e.message : String(e)}`
+		});
+	}
+	return parts.join("\n");
+}
+/**
+* Place `content` in a template, given the texts that `fillTemplateParts()` scans for the slot (the template, and
+* the footer of a pre-1.4 Twine 1 format):
+*
+* - on its own line before the first closing head tag, as Tweego does; the tag may use any letter case and
+*   whitespace before its `>`, and is kept as written;
+* - in a template with no closing head tag (HTML lets a document leave it out), on its own line before the first
+*   body start tag, where the HTML parser still puts it in the head, with a warning (Tweego drops it);
+* - in a template with neither, nowhere, with a warning.
+*
+* `owner` names the template in the warnings. Empty `content` needs no slot and gets no warning.
+*/
+function placeHead(content, texts, owner) {
+	if (content.length === 0) return {
+		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),
+		diagnostics: []
+	};
+	if (found("<[Bb][Oo][Dd][Yy](?=[\\t\\n\\f\\r />])")) {
+		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),
+			diagnostics: [{
+				level: "warning",
+				message
+			}]
+		};
+	}
+	return {
+		slot: void 0,
+		diagnostics: [{
+			level: "warning",
+			message: `${owner} has no closing head tag and no body start tag; the modules and head file were not injected.`
+		}]
+	};
+}
+/** The slot that inserts `content` on its own line before the first match of `tag`, which is kept as written. */
+function beforeTag(tag, content) {
+	return {
+		pattern: tag,
+		occurrences: "first",
+		replacement: (match) => `${content}\n${match}`
+	};
+}
+//#endregion
 //#region src/version.ts
 /**
 * The twee-ts version, read at runtime from the package's own package.json.
@@ -4957,24 +6106,42 @@ const CREATOR_NAME$2 = "Twee-ts";
 function toTwine2Archive(story, startName, options) {
 	return getTwine2DataChunk(story, startName, options) + "\n";
 }
+/**
+* Fill the Twine 2 format template: every `{{STORY_NAME}}` gets the escaped story name and the first
+* `{{STORY_DATA}}` the story data (as Tweego does), and `head` goes before the first closing head tag (or, with a
+* warning, the body start tag; see `placeHead()`). All three are found in the template in one pass, so a story
+* name, passage text or head content holding a placeholder or a closing head tag stays literal.
+* `options.diagnostics` receives a warning when the format file is not valid UTF-8, and any warning about where
+* `head` went.
+*/
 function toTwine2HTML(story, format, startName, options) {
-	let template = readFormatSource(format);
-	if (template.includes("{{STORY_NAME}}")) {
-		const name = htmlEscape(story.name);
-		template = template.replaceAll("{{STORY_NAME}}", () => name);
-	}
-	if (template.includes("{{STORY_DATA}}")) {
-		const data = getTwine2DataChunk({
-			...story,
-			twine2: {
-				...story.twine2,
-				format: format.name,
-				formatVersion: format.version
+	const name = htmlEscape(story.name);
+	const template = readFormatSource(format, options?.diagnostics);
+	const placement = placeHead(options?.head ?? "", [template], `Story format "${format.name}" ${format.version}`);
+	options?.diagnostics?.push(...placement.diagnostics);
+	const head = placement.slot;
+	return fillTemplate(template, [
+		{
+			pattern: literal("{{STORY_NAME}}"),
+			occurrences: "all",
+			replacement: () => name
+		},
+		{
+			pattern: literal("{{STORY_DATA}}"),
+			occurrences: "first",
+			replacement: () => {
+				return getTwine2DataChunk({
+					...story,
+					twine2: {
+						...story.twine2,
+						format: format.name,
+						formatVersion: format.version
+					}
+				}, startName, options);
 			}
-		}, startName, options);
-		template = template.replace("{{STORY_DATA}}", () => data);
-	}
-	return template;
+		},
+		...head === void 0 ? [] : [head]
+	]);
 }
 const OMITTING_TAGS = [
 	"Twine.private",
@@ -5067,39 +6234,83 @@ function toTwine1Archive(story, _startName) {
 	const { data, count } = getTwine1PassageChunk(story);
 	return `<div id="storeArea" data-size="${count}">${data}</div>\n`;
 }
-function toTwine1HTML(story, format, startName) {
+/**
+* Fill the Twine 1 format template. The format's components are inserted first, one after another, as Tweego and
+* Twine 1 do. Then the first of each story placeholder (`"VERSION"`, `"TIME"`, `"START_AT"`, `"STORY_SIZE"`,
+* `"STORY"`), the IFID comment and `head` (before the first closing head tag or, with a warning, the body start
+* tag; see `placeHead()`) are found in one pass, so a start passage name or story data holding a placeholder or a
+* closing head tag stays literal. `options.diagnostics` receives a warning for each format file that is not valid
+* UTF-8, and any warning about where `head` went.
+*/
+function toTwine1HTML(story, format, startName, options) {
 	const formatDir = dirname(format.filename);
 	const parentDir = dirname(formatDir);
-	let template = readFormatSource(format);
+	const diagnostics = options?.diagnostics;
+	let template = readFormatSource(format, diagnostics);
 	const { data, count } = getTwine1PassageChunk(story);
-	template = tryReplaceComponent(template, "\"USER_LIB\"", join(formatDir, "userlib.js"), false);
-	template = tryReplaceComponent(template, "\"ENGINE\"", join(parentDir, "engine.js"), true);
-	template = tryReplaceComponent(template, "\"SUGARCANE\"", join(formatDir, "code.js"), true);
-	template = tryReplaceComponent(template, "\"JONAH\"", join(formatDir, "code.js"), true);
-	if (story.twine1.settings.get("jquery") === "on") template = tryReplaceComponent(template, "\"JQUERY\"", join(parentDir, "jquery.js"), true);
-	if (story.twine1.settings.get("modernizr") === "on") template = tryReplaceComponent(template, "\"MODERNIZR\"", join(parentDir, "modernizr.js"), true);
+	template = tryReplaceComponent(template, "\"USER_LIB\"", join(formatDir, "userlib.js"), false, diagnostics);
+	template = tryReplaceComponent(template, "\"ENGINE\"", join(parentDir, "engine.js"), true, diagnostics);
+	template = tryReplaceComponent(template, "\"SUGARCANE\"", join(formatDir, "code.js"), true, diagnostics);
+	template = tryReplaceComponent(template, "\"JONAH\"", join(formatDir, "code.js"), true, diagnostics);
+	if (story.twine1.settings.get("jquery") === "on") template = tryReplaceComponent(template, "\"JQUERY\"", join(parentDir, "jquery.js"), true, diagnostics);
+	if (story.twine1.settings.get("modernizr") === "on") template = tryReplaceComponent(template, "\"MODERNIZR\"", join(parentDir, "modernizr.js"), true, diagnostics);
+	const isPre14 = !template.includes("\"STORY\"");
+	const footer = isPre14 ? readFooter(formatDir, diagnostics) : "";
+	const storeArea = (template + footer).includes("<div id=\"store-area\"") ? "<div id=\"store-area\"" : "<div id=\"storeArea\"";
+	const safeIfid = htmlCommentSanitize(story.ifid);
+	const ifid = story.ifid ? {
+		pattern: literal(storeArea),
+		occurrences: "first",
+		replacement: (div) => `<!-- UUID://${safeIfid}// -->${div}`
+	} : void 0;
+	const placement = placeHead(options?.head ?? "", isPre14 ? [template, footer] : [template], `Story format "${format.name}"`);
+	diagnostics?.push(...placement.diagnostics);
+	const late = [ifid, placement.slot].filter((slot) => slot !== void 0);
 	const displayStart = startName === "Start" ? "" : startName;
-	template = template.replace("\"VERSION\"", `Compiled with ${CREATOR_NAME$1}, ${VERSION}`);
-	template = template.replace("\"TIME\"", `Built on ${(/* @__PURE__ */ new Date()).toUTCString()}`);
-	const startAtValue = `"${jsStringEscape(displayStart)}"`;
-	template = template.replace("\"START_AT\"", () => startAtValue);
-	template = template.replace("\"STORY_SIZE\"", `"${count}"`);
-	if (template.includes("\"STORY\"")) template = template.replace("\"STORY\"", () => data);
-	else {
-		let footer;
-		try {
-			footer = readFileSync(join(formatDir, "footer.html"), "utf-8");
-		} catch {
-			footer = "</div>\n</body>\n</html>\n";
+	const slots = [
+		firstSlot("\"VERSION\"", `Compiled with ${CREATOR_NAME$1}, ${VERSION}`),
+		firstSlot("\"TIME\"", `Built on ${(/* @__PURE__ */ new Date()).toUTCString()}`),
+		firstSlot("\"START_AT\"", `"${jsStringEscape(displayStart)}"`),
+		firstSlot("\"STORY_SIZE\"", `"${count}"`),
+		firstSlot("\"STORY\"", data),
+		...late
+	];
+	return fillTemplateParts(isPre14 ? [
+		{
+			kind: "scan",
+			text: template,
+			slots
+		},
+		{
+			kind: "verbatim",
+			text: data
+		},
+		{
+			kind: "scan",
+			text: footer,
+			slots: late
 		}
-		template += data + footer;
-	}
-	if (story.ifid) {
-		const safeIfid = htmlCommentSanitize(story.ifid);
-		if (template.includes("<div id=\"store-area\"")) template = template.replace("<div id=\"store-area\"", `<!-- UUID://${safeIfid}// --><div id="store-area"`);
-		else template = template.replace("<div id=\"storeArea\"", `<!-- UUID://${safeIfid}// --><div id="storeArea"`);
+	] : [{
+		kind: "scan",
+		text: template,
+		slots
+	}]);
+}
+/** A slot replacing the first `token` with `value`. */
+function firstSlot(token, value) {
+	return {
+		pattern: literal(token),
+		occurrences: "first",
+		replacement: () => value
+	};
+}
+/** The footer of a pre-1.4 format, or the default one when the format has none. */
+function readFooter(formatDir, diagnostics) {
+	try {
+		return readUTF8(join(formatDir, "footer.html"), diagnostics);
+	} catch {
+		return "</div>\n</body>\n</html>\n";
 	}
-	return template;
 }
 /**
 * Why Twine 1 output leaves a passage out of its tiddlers, or `undefined` when the passage is emitted.
@@ -5124,11 +6335,10 @@ function getTwine1PassageChunk(story) {
 		count
 	};
 }
-function tryReplaceComponent(template, placeholder, componentPath, required) {
+function tryReplaceComponent(template, placeholder, componentPath, required, diagnostics) {
 	if (!template.includes(placeholder)) return template;
 	try {
-		let content = readFileSync(componentPath, "utf-8");
-		if (content.charCodeAt(0) === 65279) content = content.slice(1);
+		const content = readUTF8(componentPath, diagnostics);
 		return template.replace(placeholder, () => content);
 	} catch (e) {
 		if (required) throw new Error(`Required format component not found: ${componentPath}: ${e instanceof Error ? e.message : String(e)}`);
@@ -5142,11 +6352,16 @@ function tryReplaceComponent(template, placeholder, componentPath, required) {
 * from its loaded text, so changes made after loading (a start passage override, test mode) are kept.
 * Tweego writes the loaded text; its own normalization makes the two the same for an unchanged story.
 *
+* Twee cannot write every passage so that it reads back the same (see `tweeRoundTrip()`); `diagnostics`
+* receives a warning for each passage that will not. Tweego writes the same Twee without one.
+*
 * `addStoryData`: add a StoryData passage when the story has none, so that StoryData fields the
 * compile options set are recorded. Default: false.
 */
 function toTwee(story, outMode, options = {}) {
-	return withEffectiveStoryData(story, options.addStoryData ?? false).map((p) => passageToTwee(p, outMode)).join("");
+	const written = withEffectiveStoryData(story, options.addStoryData ?? false).map((p) => tweeRoundTrip(p, outMode));
+	options.diagnostics?.push(...written.flatMap(({ diagnostics }) => diagnostics));
+	return written.map(({ passage }) => passageToTwee(passage, outMode)).join("");
 }
 function withEffectiveStoryData(story, addStoryData) {
 	const storyData = {
@@ -5171,74 +6386,63 @@ function withEffectiveStoryData(story, addStoryData) {
 function isStoryDataJSON(text) {
 	return unmarshalStoryData(createStory(), text) === null;
 }
-//#endregion
-//#region src/modules.ts
-/**
-* Load modules and return HTML tags to inject before </head>.
-*/
-function loadModules(filenames) {
-	const processed = /* @__PURE__ */ new Set();
-	const headTags = [];
-	for (const filename of filenames) {
-		if (processed.has(filename)) continue;
-		const ext = normalizedFileExt(filename);
-		let tag = null;
-		switch (ext) {
-			case "css":
-				tag = loadModuleTagged("style", filename);
-				break;
-			case "js":
-				tag = loadModuleTagged("script", filename);
-				break;
-			case "otf":
-			case "ttf":
-			case "woff":
-			case "woff2":
-				tag = loadModuleFont(filename);
-				break;
-			default: continue;
-		}
-		if (tag) headTags.push(tag);
-		processed.add(filename);
-	}
-	return headTags.join("\n");
-}
-function loadModuleTagged(tag, filename) {
-	const source = readUTF8(filename).trim();
-	if (source.length === 0) return null;
-	return `<${tag} id="${`${tag}-module-${slugify(baseNameWithoutExt(filename))}`}" type="${tag === "script" ? "text/javascript" : "text/css"}">${tag === "script" ? scriptContentEscape(source) : styleContentEscape(source)}</${tag}>`;
-}
-function loadModuleFont(filename) {
-	const source = readBase64(filename);
-	const family = baseNameWithoutExt(filename);
-	const idSlug = `style-module-${slugify(family)}`;
-	const ext = normalizedFileExt(filename);
-	return `<style id="${idSlug}" type="text/css">@font-face {\n\tfont-family: "${family}";\n\tsrc: url("data:${mediaTypeFromExt(ext)};base64,${source}") format("${fontFormatHint(ext)}");\n}</style>`;
-}
+/** Characters Twee 3 escapes in names and tags, and Twee 1 cannot write there at all. */
+const TWEE1_UNWRITABLE = /[[\]{}\\]/;
 /**
-* Inject modules and head file content before </head>.
+* Check that Twee reads `p` back as written, and say what it will not. Twee has no way to escape passage text,
+* and its parser trims names and splits tags at whitespace, so these do not survive:
+*
+* - a text line that starts with `::`, which reads as a new passage header. In stylesheet and script passages such
+*   a line is indented by one space, which keeps the CSS or JavaScript working (only a template literal or a
+*   string continued across lines, in either, would see the space); the warning says so. Other passages' text is
+*   written as it is.
+* - a name that is empty, has leading or trailing whitespace, or holds a line break;
+* - a tag that is empty or holds whitespace;
+* - in Twee 1, which escapes nothing, a name or tag holding `[`, `]`, `{`, `}` or `\`.
 */
-function modifyHead(html, modulePaths, headFile, diagnostics) {
-	const parts = [];
-	if (modulePaths.length > 0) {
-		const modules = loadModules(modulePaths).trim();
-		if (modules.length > 0) parts.push(modules);
-	}
-	if (headFile) try {
-		const source = readUTF8(headFile).trim();
-		if (source.length > 0) parts.push(source);
-	} catch (e) {
-		diagnostics?.push({
+function tweeRoundTrip(p, outMode) {
+	const label = `Passage ${JSON.stringify(p.name)}`;
+	const diagnostics = [];
+	const warn = (problem) => {
+		diagnostics.push({
 			level: "warning",
-			message: `Failed to read head file "${headFile}": ${e instanceof Error ? e.message : String(e)}`
+			message: `${label} cannot be written as Twee that reads back the same: ${problem}.`
 		});
+	};
+	if (p.name.trim() === "") warn("its name is empty");
+	else if (p.name.trim() !== p.name) warn("its name has leading or trailing whitespace, which Twee drops");
+	if (/[\r\n]/.test(p.name)) warn("its name has a line break, which ends a Twee passage header");
+	if (outMode === "twee1" && TWEE1_UNWRITABLE.test(p.name)) warn("its name has \"[\", \"]\", \"{\", \"}\" or \"\\\", which Twee 1 cannot escape");
+	for (const tag of p.tags) {
+		if (tag === "" || /\s/.test(tag)) warn(`its tag ${JSON.stringify(tag)} is empty or has whitespace, which splits tags in Twee`);
+		if (outMode === "twee1" && TWEE1_UNWRITABLE.test(tag)) warn(`its tag ${JSON.stringify(tag)} has "[", "]", "{", "}" or "\\", which Twee 1 cannot escape`);
+	}
+	const lines = p.text.split(/(\r\n?|\n)/);
+	const headerLines = lines.flatMap((line, i) => i % 2 === 0 && line.startsWith("::") ? [i / 2 + 1] : []);
+	if (headerLines.length === 0) return {
+		passage: p,
+		diagnostics
+	};
+	const where = `${headerLines.length === 1 ? "line" : "lines"} ${headerLines.join(", ")} of its text start${headerLines.length === 1 ? "s" : ""} with "::", which Twee reads as a passage header`;
+	if (!p.tags.some((tag) => tag === "stylesheet" || tag === "script")) {
+		warn(where);
+		return {
+			passage: p,
+			diagnostics
+		};
 	}
-	if (parts.length > 0) {
-		parts.push("</head>");
-		const replacement = parts.join("\n");
-		return html.replace("</head>", () => replacement);
-	}
-	return html;
+	diagnostics.push({
+		level: "warning",
+		message: `${label}: ${where}; ${headerLines.length === 1 ? "it was" : "they were"} written indented by one space.`
+	});
+	const text = lines.map((line, i) => i % 2 === 0 && line.startsWith("::") ? ` ${line}` : line).join("");
+	return {
+		passage: {
+			...p,
+			text
+		},
+		diagnostics
+	};
 }
 //#endregion
 //#region src/passage-omission.ts
@@ -5295,28 +6499,28 @@ var TweeTsError = class extends Error {
 	}
 };
 /**
-* Compile Twee sources to HTML, Twee, or JSON.
-*/
-async function compile(options) {
-	return buildOutput(options);
-}
-/**
-* Compile with incremental caching support.
-* Plugins and advanced users can manage their own cache and changed-file tracking.
+* Builds as compileToFile() does for `outputs`, without writing them: an output may sit
+* inside a source folder, so its last build is left out of the sources and modules and
+* never read back. `outputs` is the one file the CLI writes, or every path a bundler's
+* build writes (see BuildOutputs). The caller decides whether the result is written.
+* With no outputs (output to stdout, or none), this is compile(). With `cache`, files
+* are cached as compileIncremental() caches them.
+*
+* Throws a TweeTsError when a source, module or head file named directly is an output.
 *
-* Without `changedFiles`, a cached file is reused while its modification time is unchanged.
-* With it, a file it names (by the path source discovery gives it, relative to the working
-* directory) is always reparsed, whatever its modification time, and every other cached
-* file is reused as it is.
+* Internal, for the CLI and the bundler plugins; not part of the public API.
 */
-async function compileIncremental(options, cache, changedFiles) {
-	return buildOutput(options, cache, changedFiles);
+async function compileForOutputFile(options, outputs, cache) {
+	return buildOutput(options, cache, void 0, outputs);
 }
 /**
-* `outFile`: the file the build is written to, which source and module discovery
-* skip (as Tweego does), so an output inside a source folder is never loaded back.
+* `outputs`: what the build writes (an output file's path, or a bundler's outputs),
+* which source and module discovery skip, so an output inside a source folder is
+* never loaded back. A source, module or head file named directly that is an output
+* is a TweeTsError, as in Tweego: writing the build would overwrite it.
 */
-async function buildOutput(options, cache, changedFiles, outFile) {
+async function buildOutput(options, cache, changedFiles, outputs) {
+	const written = toBuildOutputs(outputs);
 	const diagnostics = [];
 	const outputMode = options.outputMode ?? "html";
 	const trim = options.trim ?? true;
@@ -5324,13 +6528,18 @@ async function buildOutput(options, cache, changedFiles, outFile) {
 	const testMode = options.testMode ?? false;
 	const noRemote = options.noRemote ?? false;
 	const sourceInfo = options.sourceInfo ?? false;
+	options.signal?.throwIfAborted();
+	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 { filenames: sourceFilenames, diagnostics: sourcePathDiagnostics } = getFilenames(filePaths, outFile, options.exclude);
-	diagnostics.push(...sourcePathDiagnostics);
+	const sourcePaths = getFilenames(filePaths, written, options.exclude);
+	diagnostics.push(...sourcePaths.diagnostics);
+	rejectOutputSources(sourcePaths.outputSources, diagnostics);
+	const sourceFilenames = sourcePaths.filenames;
 	const story = createStory();
 	const processedFiles = /* @__PURE__ */ new Set();
 	if (cache) loadSourcesCached(story, sourceFilenames, {
@@ -5359,7 +6568,10 @@ async function buildOutput(options, cache, changedFiles, outFile) {
 	switch (outputMode) {
 		case "twee3":
 		case "twee1":
-			output = toTwee(story, outputMode, { addStoryData: Boolean(options.startPassage) || testMode });
+			output = toTwee(story, outputMode, {
+				addStoryData: Boolean(options.startPassage) || testMode,
+				diagnostics
+			});
 			break;
 		case "twine2-archive":
 			output = toTwine2Archive(story, startName, { sourceInfo });
@@ -5373,17 +6585,24 @@ async function buildOutput(options, cache, changedFiles, outFile) {
 		case "html": {
 			diagnostics.push(...startPassageDiagnostics(story, startName, format?.isTwine2 === false ? "twine1" : "twine2"));
 			if (!format) throw new TweeTsError("No story format available for HTML output.", diagnostics);
-			if (format.isTwine2) output = toTwine2HTML(story, format, startName, { sourceInfo });
-			else {
-				if (story.name === "" && !storyHas(story, "StoryTitle")) diagnostics.push({
-					level: "error",
-					message: "Special passage \"StoryTitle\" not found."
-				});
-				output = toTwine1HTML(story, format, startName);
-			}
-			const modules = getFilenames(options.modules ?? [], outFile);
+			if (!format.isTwine2 && story.name === "" && !storyHas(story, "StoryTitle")) diagnostics.push({
+				level: "error",
+				message: "Special passage \"StoryTitle\" not found."
+			});
+			const modules = getFilenames(options.modules ?? [], written);
 			diagnostics.push(...modules.diagnostics);
-			output = modifyHead(output, modules.filenames, options.headFile, diagnostics);
+			const { headFile } = options;
+			const headIsOutput = headFile !== void 0 && outputPaths(written).isFile(realPathOf(headFile));
+			rejectOutputSources([...modules.outputSources, ...headIsOutput ? [headFile] : []], diagnostics);
+			const head = loadHeadContent(modules.filenames, options.headFile, diagnostics);
+			output = format.isTwine2 ? toTwine2HTML(story, format, startName, {
+				sourceInfo,
+				head,
+				diagnostics
+			}) : toTwine1HTML(story, format, startName, {
+				head,
+				diagnostics
+			});
 			break;
 		}
 		default: throw new TweeTsError(`Unhandled output mode: ${outputMode}`, diagnostics);
@@ -5400,6 +6619,16 @@ async function buildOutput(options, cache, changedFiles, outFile) {
 		stats
 	};
 }
+/**
+* Throws for the first of `paths`, inputs named directly that are also an output:
+* writing the build would overwrite them. An output found while walking a source
+* folder is skipped instead (see getFilenames).
+*/
+function rejectOutputSources(paths, diagnostics) {
+	const [first] = paths;
+	if (first === void 0) return;
+	throw new TweeTsError(`path ${first}: Output file cannot be an input source.`, [...diagnostics]);
+}
 function ensureIFID(story, diagnostics) {
 	if (story.ifid !== "") return;
 	if (story.legacyIFID !== "") {
@@ -5488,6 +6717,79 @@ function fatalError(e) {
 	return e instanceof Error ? e : new Error(String(e));
 }
 //#endregion
-export { compileIncremental as a, mediaTypeFromFilename as c, compile as i, formatDiagnostic as n, getFilenames as o, splitDiagnostics as r, isExcluded as s, fatalError as t };
+//#region src/plugins/paths.ts
+/**
+* Path helpers for the bundler plugins. Vite reports module ids with forward
+* slashes on every platform, while node:path gives backslashes on Windows, so
+* the Vite plugin compares paths in forward-slash form only. Paths a build
+* writes are compared by real path instead (see filesystem.ts).
+*/
+/**
+* The absolute path a bundle writes the file it emits as `fileName` to: inside
+* `output.dir`, or next to `output.file`, either resolved against the working
+* directory, as the bundler resolves them. Undefined when the output names
+* neither, as for a bundle only generated in memory.
+*/
+function emittedFilePath(output, fileName) {
+	const dir = output.dir ?? (output.file === void 0 ? void 0 : dirname(output.file));
+	return dir === void 0 ? void 0 : resolve(dir, fileName);
+}
+/**
+* The locations a bundler's `output` option names: one output's settings or an
+* array of them, as a config gives them. Outputs that name neither `dir` nor
+* `file`, and anything that isn't an output's settings, are left out.
+*/
+function outputLocations(option) {
+	return (Array.isArray(option) ? option : [option]).flatMap((output) => {
+		if (typeof output !== "object" || output === null) return [];
+		const { dir, file } = output;
+		const location = {
+			...typeof dir === "string" ? { dir } : {},
+			...typeof file === "string" ? { file } : {}
+		};
+		return location.dir === void 0 && location.file === void 0 ? [] : [location];
+	});
+}
+/** An empty OutputRecord for a plugin that writes its story as `storyFileName`. */
+function createOutputRecord(storyFileName) {
+	const files = /* @__PURE__ */ new Set();
+	const dirs = /* @__PURE__ */ new Set();
+	const addFiles = (output, fileNames) => {
+		for (const fileName of fileNames) {
+			const path = emittedFilePath(output, fileName);
+			if (path !== void 0) files.add(path);
+		}
+	};
+	return {
+		addLocation(output) {
+			if (output.dir !== void 0) dirs.add(resolve(output.dir));
+			if (output.file !== void 0) files.add(resolve(output.file));
+			addFiles(output, [storyFileName]);
+		},
+		addFiles,
+		outputs: () => ({
+			files: [...files],
+			dirs: [...dirs]
+		})
+	};
+}
+/** The path with Windows separators turned into forward slashes. */
+function toPosix(path) {
+	return path.replace(/\\/g, "/");
+}
+/** Whether `file` is one of `dirs` or inside one of them. All paths in forward-slash form. */
+function isInside(file, dirs) {
+	return dirs.some((dir) => file === dir || file.startsWith(dir.endsWith("/") ? dir : `${dir}/`));
+}
+/**
+* Whether `file` is a temporary copy of a Vite config file. Vite writes one next
+* to the config file each time it loads it (when no node_modules folder is
+* above the config, and always under Deno), then deletes it.
+*/
+function isViteConfigTemp(file) {
+	return /\.timestamp-\d+-[0-9a-f]*\.mjs$/.test(file);
+}
+//#endregion
+export { toPosix as a, splitDiagnostics as c, isExcluded as d, outputPaths as f, mediaTypeFromFilename as h, outputLocations as i, compileForOutputFile as l, walkedEntry as m, isInside as n, fatalError as o, realPathOf as p, isViteConfigTemp as r, formatDiagnostic as s, createOutputRecord as t, getFilenames as u };
 
-//# sourceMappingURL=diagnostics-DZNS7W41.js.map
+//# sourceMappingURL=paths-DgO9oo6G.js.map