@rohal12/twee-ts 1.17.1 → 1.18.0

package/dist/index.js

@@ -1,7 +1,7 @@
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, watch as watch$1, 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 { accessSync, chmodSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, watch as watch$1, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 //#region src/ifid.ts
@@ -113,18 +113,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
@@ -304,7 +330,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 ?? "";
@@ -316,9 +354,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.
@@ -371,19 +410,136 @@ 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);
+}
+/**
+* Rebuild the index unless it matches `story.passages` at every position. O(n): for entry points
+* that run after code outside the compiler may have changed the passages, such as StoryBuilder.
+*/
+function storyVerifyIndex(story) {
+	const index = currentIndex(story);
+	if (!story.passages.every((p, i) => p.name === index.names[i])) 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 = {
@@ -392,52 +548,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) {
@@ -463,18 +604,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 = normalizeIFID(data.ifid);
-	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) {
@@ -515,8 +658,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":
@@ -576,7 +731,9 @@ function getStoryStats(story, wordCountMethod = "tweego") {
 }
 /**
 * Builder that separates the mutable construction phase from the immutable consumption phase.
-* During construction, the internal `Story` is mutable via `add()` and direct access.
+* During construction, the internal `Story` is mutable via `add()` and direct access: you may
+* push, splice, sort, rename or reassign `story.passages` between calls, and `add()` and `has()`
+* see the passages as they are then.
 * After `build()`, the story is returned as `ReadonlyStory`.
 */
 var StoryBuilder = class {
@@ -587,10 +744,13 @@ var StoryBuilder = class {
 	}
 	/** Add a passage, handling special passages (StoryData, StoryTitle, etc.). */
 	add(passage, diagnostics) {
+		if (generatedNames.has(passage) || !storyHas(this.story, passage.name)) storyVerifyIndex(this.story);
 		storyAdd(this.story, passage, diagnostics);
 	}
 	/** Check if a passage name exists. */
 	has(name) {
+		if (storyHas(this.story, name)) return true;
+		storyVerifyIndex(this.story);
 		return storyHas(this.story, name);
 	}
 	/** Finalize and return the story as read-only. */
@@ -715,131 +875,579 @@ 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;
-			}
-			for (const entry of entries) walk(join(pathname, entry));
-		}
+			if (output.isFile(real)) outputSources.push(pathname);
+			else addFile(pathname);
+		} else if (stat.isDirectory()) walkDir(pathname, real);
 	}
-	for (const pathname of pathnames) walk(pathname);
 	return {
 		filenames,
-		diagnostics
+		diagnostics,
+		outputSources
 	};
 }
-/** Whether the absolute path `file` is the absolute path `dir` or inside it. */
-function isInsideDir(file, dir) {
-	return file === dir || file.startsWith(dir.endsWith(sep) ? dir : dir + sep);
-}
 /**
-* The watched paths split into folders (as given) and files (absolute). A path
-* that cannot be read counts as a folder, which fs.watch then fails to watch.
+* A watched path that can't be watched: fs.watch failed on it, or on the folder it is
+* watched through. watchFilesystem passes it to its `onError` and keeps watching the rest.
 */
-function splitWatchRoots(pathnames) {
-	const dirs = [];
-	const files = /* @__PURE__ */ new Set();
-	for (const pathname of pathnames) {
-		let isFile = false;
-		try {
-			isFile = statSync(pathname).isFile();
-		} catch {}
-		if (isFile) files.add(resolve(pathname));
-		else dirs.push(pathname);
+var WatchPathError = class extends Error {
+	path;
+	constructor(path, cause) {
+		super(`Cannot watch ${path}: ${cause instanceof Error ? cause.message : String(cause)}`);
+		this.path = path;
+		this.name = "WatchPathError";
+	}
+};
+function pathKind(path) {
+	try {
+		const stats = statSync(path);
+		return stats.isDirectory() ? {
+			kind: "dir",
+			id: `${stats.dev}:${stats.ino}`
+		} : { kind: "file" };
+	} catch {
+		return { kind: "missing" };
 	}
+}
+function rootState(abs) {
 	return {
-		dirs,
-		files
+		anchor: nearestFolderAbove(abs),
+		self: pathKind(abs)
 	};
 }
+function nearestFolderAbove(abs) {
+	for (let dir = dirname(abs), below = abs; dir !== below; below = dir, dir = dirname(dir)) {
+		const kind = pathKind(dir);
+		if (kind.kind === "dir") return {
+			path: dir,
+			id: kind.id
+		};
+	}
+}
+/** Whether two states need the same watches: the same anchor folder, and the same watched folder if any. */
+function sameWatches(a, b) {
+	const selfId = (s) => s.self.kind === "dir" ? s.self.id : void 0;
+	return a.anchor?.path === b.anchor?.path && a.anchor?.id === b.anchor?.id && selfId(a) === selfId(b);
+}
 /**
 * Watch paths for changes, calling the build callback on known file type changes.
 * A folder is watched recursively; a file is watched on its own and counts
 * whatever its type (a head file, say). A change to a file `ignore` returns true
 * for (given the path relative to the working directory) schedules no build.
 * Uses debouncing to avoid rapid rebuilds.
-*/
-function watchFilesystem(pathnames, outFilename, callback, ignore = () => false) {
-	const absOutFile = resolve(outFilename);
-	const watchers = [];
+*
+* A watched path that doesn't exist yet is waited for, and one that is deleted, or renamed
+* away and replaced, is followed to the new folder or file at its path: each path is also
+* watched through the folder above it. When that sets up a path's watches again, the next
+* build is a full one (`changedFiles` undefined), since changes made in between went unseen.
+* A path that can't be watched is passed to `onError` as a WatchPathError, once while the
+* failure persists; the other paths are still watched.
+*/
+function watchFilesystem(pathnames, outFilename, callback, ignore = () => false, onError = () => {}) {
+	const output = outputPaths(toBuildOutputs(outFilename));
 	let buildTimer = null;
 	const BUILD_DEBOUNCE = 500;
 	const pendingFiles = /* @__PURE__ */ new Set();
+	let pendingFullBuild = false;
+	let closed = false;
 	function scheduleBuild(changedFile) {
-		if (changedFile) pendingFiles.add(changedFile);
+		if (changedFile === void 0) pendingFullBuild = true;
+		else pendingFiles.add(changedFile);
 		if (buildTimer) clearTimeout(buildTimer);
 		buildTimer = setTimeout(() => {
 			buildTimer = null;
-			const files = pendingFiles.size > 0 ? new Set(pendingFiles) : void 0;
+			const files = pendingFullBuild || pendingFiles.size === 0 ? void 0 : new Set(pendingFiles);
 			pendingFiles.clear();
+			pendingFullBuild = false;
 			callback(files);
 		}, BUILD_DEBOUNCE);
 	}
+	const roots = pathnames.map((path) => {
+		const abs = resolve(path);
+		return {
+			path,
+			abs,
+			state: rootState(abs),
+			watchers: [],
+			failed: false,
+			lastReport: void 0
+		};
+	});
+	const isNamedFile = (abs) => roots.some((r) => r.abs === abs && r.state.self.kind === "file");
 	function fileChanged(abs, named) {
-		if (abs === absOutFile) return;
 		if (!named && !isKnownFileType(abs)) return;
+		if (output.isFile(realPathOf(abs))) return;
 		const rel = relative(process.cwd(), abs);
 		if (!ignore(rel || abs)) scheduleBuild(rel || abs);
 	}
-	function watchPath(pathname, recursive, listener) {
+	function report(root, cause) {
+		const error = new WatchPathError(root.path, cause);
+		if (error.message === root.lastReport) return;
+		root.lastReport = error.message;
+		onError(error);
+	}
+	function startWatch(root, path, recursive, listener) {
 		try {
-			watchers.push(watch$1(pathname, { recursive }, (_event, filename) => {
-				if (filename) listener(filename);
-			}));
-		} catch {}
+			if (recursive) accessSync(path, constants.R_OK | constants.X_OK);
+			const watcher = watch$1(path, { recursive }, (_event, filename) => {
+				if (!closed) listener(filename ?? "");
+			});
+			watcher.on("error", (e) => {
+				watcher.close();
+				root.watchers = root.watchers.filter((w) => w !== watcher);
+				root.failed = true;
+				if (!closed && !recheck(root, false)) report(root, e);
+			});
+			root.watchers.push(watcher);
+		} catch (e) {
+			root.failed = true;
+			report(root, e);
+		}
+	}
+	function arm(root) {
+		for (const w of root.watchers) w.close();
+		root.watchers = [];
+		root.failed = false;
+		const { anchor, self } = root.state;
+		if (anchor) startWatch(root, anchor.path, false, (filename) => {
+			const before = root.state.self.kind;
+			recheck(root, true);
+			if ((before === "file" || isNamedFile(root.abs)) && filename !== "" && resolve(anchor.path, filename) === root.abs) fileChanged(root.abs, true);
+		});
+		if (self.kind === "dir") startWatch(root, root.path, true, (filename) => {
+			if (filename === "") recheck(root, true);
+			else {
+				const abs = resolve(root.abs, filename);
+				fileChanged(abs, isNamedFile(abs));
+			}
+		});
+		if (!root.failed) root.lastReport = void 0;
 	}
-	const { dirs, files } = splitWatchRoots(pathnames);
-	const absDirs = dirs.map((dir) => resolve(dir));
-	for (const dir of dirs) watchPath(dir, true, (filename) => {
-		const abs = resolve(dir, filename);
-		fileChanged(abs, files.has(abs));
-	});
-	const fileDirs = new Set([...files].filter((file) => !absDirs.some((dir) => isInsideDir(file, dir))).map((file) => dirname(file)));
-	for (const dir of fileDirs) watchPath(dir, false, (filename) => {
-		const abs = resolve(dir, filename);
-		if (files.has(abs)) fileChanged(abs, true);
-	});
+	/**
+	* Sets up `root`'s watches again when its path, or the folder above it, is no longer the
+	* one they were started on (or, with `retry`, when one of them failed), and then schedules a
+	* full build. Returns whether its state changed.
+	*/
+	function recheck(root, retry) {
+		const before = root.state;
+		const after = rootState(root.abs);
+		const changed = !sameWatches(before, after);
+		const wasFailed = root.failed;
+		if (!changed && !(retry && wasFailed)) {
+			root.state = after;
+			return false;
+		}
+		root.state = after;
+		arm(root);
+		const recovered = wasFailed && !root.failed;
+		if ((changed || recovered) && (before.self.kind !== "missing" || after.self.kind !== "missing")) scheduleBuild();
+		return changed;
+	}
+	for (const root of roots) arm(root);
 	callback();
 	return { close() {
+		closed = true;
 		if (buildTimer) clearTimeout(buildTimer);
-		for (const w of watchers) w.close();
+		for (const root of roots) for (const w of root.watchers) w.close();
 	} };
 }
 //#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);
+			}
+			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)}`);
+	}
+	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 {
+		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
 /**
 * Source text normalization shared by every input path (files, in-memory sources, `parseTwee`).
@@ -851,14 +1459,119 @@ function watchFilesystem(pathnames, outFilename, callback, ignore = () => false)
 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) {
@@ -874,20 +1587,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. */
@@ -897,151 +1601,247 @@ 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.
+* Discover all story formats in the given search directories, pruned by SemVer: within each
+* (name, major) group only the highest version survives. See {@link discoverAllFormats} for the
+* directory ranking and {@link pruneFormats} for pruning.
+*/
+function discoverFormats(searchDirs) {
+	return pruneFormats(discoverAllFormats(searchDirs));
+}
+/**
+* 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 = [
@@ -1056,30 +1856,25 @@ 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])
-	];
-}
+	const parsed = parseVersion(v);
+	return parsed ? [
+		parsed.major,
+		parsed.minor,
+		parsed.patch
+	] : null;
+}
+/** Compare [major, minor, patch] tuples. Use {@link compareVersions} to take prereleases into account. */
 function semverCompare(a, b) {
 	const [aMajor, aMinor, aPatch] = a;
 	const [bMajor, bMinor, bPatch] = b;
@@ -1090,7 +1885,7 @@ function semverCompare(a, b) {
 }
 /** 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. */
@@ -1099,83 +1894,166 @@ function describeFormatRequest(request) {
 		case "id": return `"${request.id}"`;
 		case "name": return request.version ? `"${request.name}" at version "${request.version}"` : `"${request.name}"`;
 		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 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;
+}
+//#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 bestId;
 }
-/** 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;
+/** 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;
 	}
-	return source;
+}
+/**
+* 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
@@ -1198,25 +2076,38 @@ function cachedFormatDir(name, version) {
 	if (!isInside(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. */
@@ -1225,6 +2116,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;
@@ -1240,15 +2203,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) {
@@ -1269,99 +2235,155 @@ 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$1(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$1(e) {
+	return e instanceof Error ? e : new Error(String(e));
 }
 /**
 * Try to resolve a remote story format by name and version.
-* 0. Use an exactly matching cached download, without touching the network
-* 1. Try direct format URLs
-* 2. Try custom index URLs
-* 3. Try default SFA indices
-* 4. Fall back to a compatible cached download (e.g. when offline)
+* 1. Try direct format URLs (each one's cached copy, else a download)
+* 2. Use an exactly matching download from the shared cache, without touching the network
+* 3. Try custom index URLs, then the default SFA indices
+* 4. Fall back to a compatible download from the shared cache (e.g. when offline)
+*
+* `options.signal` aborts the lookup, which then rejects with the signal's reason;
+* `options.timeout` limits each request (default {@link DEFAULT_FORMAT_FETCH_TIMEOUT} ms).
 */
-async function resolveRemoteFormat(name, version, indices, urls) {
+async function resolveRemoteFormat(name, version, indices, urls, options = {}) {
 	return resolveRemoteFormatRequest({
 		kind: "name",
 		name,
 		version
-	}, indices, urls);
+	}, indices, urls, options);
 }
 /**
 * 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$1(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$1(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 = {}) {
@@ -1373,18 +2395,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;
 	}
@@ -1469,21 +2484,27 @@ function listCachedFormats() {
 }
 /**
 * Clear all cached formats, or only those matching a given name. Returns the number of entries removed.
+* Clearing all also removes the downloads from direct format URLs; a name clears only the
+* downloads shared by name and version.
 * A name must be a single cache entry name (as `listCachedFormats()` reports it); anything with a
 * path separator or `.`/`..` throws instead of deleting outside the format's own directory.
 */
 function clearCachedFormats(name) {
 	if (name && !isSafeSegment(name)) throw new Error(`Refusing to clear ${JSON.stringify(name)}: it is not a cached format name. Use a name as "cache list" shows it.`);
 	const cacheDir = getCacheDir();
-	if (!existsSync(cacheDir)) return 0;
 	if (!name) {
-		const count = listCachedFormats().length;
+		const count = listCachedFormats().length + countUrlCacheEntries();
 		rmSync(cacheDir, {
 			recursive: true,
 			force: true
 		});
+		rmSync(getUrlCacheDir(), {
+			recursive: true,
+			force: true
+		});
 		return count;
 	}
+	if (!existsSync(cacheDir)) return 0;
 	const root = resolve(cacheDir);
 	const nameDir = resolve(root, name);
 	if (!isInside(root, nameDir)) throw new Error(`Refusing to clear ${JSON.stringify(name)}: it is not a cached format name.`);
@@ -1501,6 +2522,15 @@ function clearCachedFormats(name) {
 	});
 	return count;
 }
+/** The number of direct format URLs with a download in the cache. */
+function countUrlCacheEntries() {
+	const dir = getUrlCacheDir();
+	try {
+		return readdirSync(dir).filter((key) => existsSync(join(dir, key, "format.js"))).length;
+	} catch {
+		return 0;
+	}
+}
 /** Get total cache size in bytes and format count. */
 function getCacheSize() {
 	const entries = listCachedFormats();
@@ -1527,44 +2557,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",
@@ -1576,7 +2627,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
@@ -1871,12 +2922,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;
@@ -4713,15 +5766,28 @@ function parseDocument(data, options) {
 /**
 * 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.
+* A missing or invalid `tw-storydata` IFID is reported as a warning; an invalid one is kept as
+* written (uppercased), a missing one stays empty.
 */
 function decompileHTML(html, options = {}) {
+	return decompile(html, options, { ifid: true });
+}
+/**
+* `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 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
@@ -4744,7 +5810,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"];
@@ -4757,6 +5823,7 @@ function decompileTwine2(storyData, story, passageText, diagnostics) {
 		else startnode = parsed;
 	}
 	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({
@@ -4779,13 +5846,17 @@ function decompileTwine2(storyData, story, passageText, diagnostics) {
 				const content = getTextContent(node);
 				if (content.trim().length === 0) continue;
 				const text = passageText(content);
-				const name = freeName(node.name === "style" ? "Story Stylesheet" : "Story JavaScript", takenNames);
+				const base = node.name === "style" ? "Story Stylesheet" : "Story JavaScript";
+				const name = freeName(base, (n) => !takenNames.has(n));
 				takenNames.add(name);
-				storyAdd(story, {
+				storyAdd(story, withGeneratedName({
 					name,
 					tags: node.name === "style" ? ["stylesheet"] : ["script"],
 					text
-				}, diagnostics);
+				}, {
+					kind: "code",
+					base
+				}), diagnostics);
 				break;
 			}
 			case "tw-tag": {
@@ -4832,19 +5903,26 @@ function decompileTwine2(storyData, story, passageText, diagnostics) {
 function passageDataName(node) {
 	return node.attribs?.["name"] ?? "";
 }
-/** The first of `base`, `base 2`, `base 3`, … that is not in `taken`. */
-function freeName(base, taken) {
-	if (!taken.has(base)) return base;
-	for (let n = 2;; n++) {
-		const candidate = `${base} ${n}`;
-		if (!taken.has(candidate)) return candidate;
-	}
+/** 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);
 }
@@ -4989,7 +6067,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 "":
@@ -5008,18 +6091,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",
@@ -5029,35 +6104,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: []
 	};
 }
@@ -5066,24 +6166,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]
 	};
 }
 /**
@@ -5156,6 +6259,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) {
@@ -5172,6 +6276,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({
@@ -5184,8 +6289,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);
@@ -5195,6 +6300,7 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 		try {
 			mtimeMs = statSync(filename).mtimeMs;
 		} catch {
+			cache.delete(filename);
 			continue;
 		}
 		if (cached && !changed && cached.mtimeMs === mtimeMs) {
@@ -5215,6 +6321,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)}`,
@@ -5238,6 +6345,11 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 * 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, "\\$&");
@@ -5271,9 +6383,10 @@ function fillTemplateParts(parts) {
 //#endregion
 //#region src/modules.ts
 /**
-* Load modules and return HTML tags to inject before the closing head tag.
+* 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) {
+function loadModules(filenames, diagnostics) {
 	const processed = /* @__PURE__ */ new Set();
 	const headTags = [];
 	for (const filename of filenames) {
@@ -5282,10 +6395,10 @@ function loadModules(filenames) {
 		let tag = null;
 		switch (ext) {
 			case "css":
-				tag = loadModuleTagged("style", filename);
+				tag = loadModuleTagged("style", filename, diagnostics);
 				break;
 			case "js":
-				tag = loadModuleTagged("script", filename);
+				tag = loadModuleTagged("script", filename, diagnostics);
 				break;
 			case "otf":
 			case "ttf":
@@ -5300,8 +6413,8 @@ function loadModules(filenames) {
 	}
 	return headTags.join("\n");
 }
-function loadModuleTagged(tag, filename) {
-	const source = readUTF8(filename).trim();
+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}>`;
 }
@@ -5310,20 +6423,22 @@ function loadModuleFont(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>`;
+	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 before the closing head tag, joined by newlines,
+* 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).trim();
+		const modules = loadModules(modulePaths, diagnostics).trim();
 		if (modules.length > 0) parts.push(modules);
 	}
 	if (headFile) try {
-		const source = readUTF8(headFile).trim();
+		const source = readUTF8(headFile, diagnostics).trim();
 		if (source.length > 0) parts.push(source);
 	} catch (e) {
 		diagnostics?.push({
@@ -5334,16 +6449,51 @@ function loadHeadContent(modulePaths, headFile, diagnostics) {
 	return parts.join("\n");
 }
 /**
-* The template slot that inserts `content` on its own line before the first closing head tag (as Tweego does),
-* or `undefined` when `content` is empty. The tag may use any letter case and whitespace before its `>`, and is
-* kept as written.
+* 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 headSlot(content) {
-	if (content.length === 0) return void 0;
+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: CLOSING_HEAD_TAG,
+		pattern: tag,
 		occurrences: "first",
-		replacement: (tag) => `${content}\n${tag}`
+		replacement: (match) => `${content}\n${match}`
 	};
 }
 //#endregion
@@ -5382,14 +6532,19 @@ function toTwine2Archive(story, startName, options) {
 }
 /**
 * 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. 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.
+* `{{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) {
 	const name = htmlEscape(story.name);
-	const head = headSlot(options?.head ?? "");
-	const slots = [
+	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",
@@ -5410,8 +6565,7 @@ function toTwine2HTML(story, format, startName, options) {
 			}
 		},
 		...head === void 0 ? [] : [head]
-	];
-	return fillTemplate(readFormatSource(format), slots);
+	]);
 }
 const OMITTING_TAGS = [
 	"Twine.private",
@@ -5507,29 +6661,35 @@ function toTwine1Archive(story, _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) are found in one pass, so a start
-* passage name or story data holding a placeholder or a closing head tag stays literal.
+* `"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) : "";
+	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 late = [story.ifid ? {
+	const ifid = story.ifid ? {
 		pattern: literal(storeArea),
 		occurrences: "first",
 		replacement: (div) => `<!-- UUID://${safeIfid}// -->${div}`
-	} : void 0, headSlot(options?.head ?? "")].filter((slot) => slot !== void 0);
+	} : 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;
 	const slots = [
 		firstSlot("\"VERSION\"", `Compiled with ${CREATOR_NAME$1}, ${VERSION}`),
@@ -5569,9 +6729,9 @@ function firstSlot(token, value) {
 	};
 }
 /** The footer of a pre-1.4 format, or the default one when the format has none. */
-function readFooter(formatDir) {
+function readFooter(formatDir, diagnostics) {
 	try {
-		return readFileSync(join(formatDir, "footer.html"), "utf-8");
+		return readUTF8(join(formatDir, "footer.html"), diagnostics);
 	} catch {
 		return "</div>\n</body>\n</html>\n";
 	}
@@ -5599,11 +6759,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)}`);
@@ -5617,11 +6776,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 = {
@@ -5646,6 +6810,64 @@ function withEffectiveStoryData(story, addStoryData) {
 function isStoryDataJSON(text) {
 	return unmarshalStoryData(createStory(), text) === null;
 }
+/** Characters Twee 3 escapes in names and tags, and Twee 1 cannot write there at all. */
+const TWEE1_UNWRITABLE = /[[\]{}\\]/;
+/**
+* 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 tweeRoundTrip(p, outMode) {
+	const label = `Passage ${JSON.stringify(p.name)}`;
+	const diagnostics = [];
+	const warn = (problem) => {
+		diagnostics.push({
+			level: "warning",
+			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
+		};
+	}
+	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
 /**
@@ -5712,42 +6934,52 @@ async function compile(options) {
 	return buildOutput(options);
 }
 /**
-* Compile and write to a file.
+* Compile and write to a file. The file is replaced atomically: a reader sees the previous
+* build or the new one, never part of it, and a failed write leaves the previous build.
 */
 async function compileToFile(options) {
 	const result = await compileForOutputFile(options, options.outFile);
-	writeFileSync(options.outFile, result.output, "utf-8");
+	writeFileAtomic(options.outFile, result.output);
 	return result;
 }
 /**
-* Builds as compileToFile() does for `outFile`, without writing it: the output may sit
+* 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. The caller decides whether the result is written. With no `outFile`
-* (output to stdout, or none), this is compile(). With `cache`, files are cached as
-* compileIncremental() caches them.
+* 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.
 *
 * Internal, for the CLI and the bundler plugins; not part of the public API.
 */
-async function compileForOutputFile(options, outFile, cache) {
-	return buildOutput(options, cache, void 0, outFile);
+async function compileForOutputFile(options, outputs, cache) {
+	return buildOutput(options, cache, void 0, outputs);
 }
 /**
 * Compile with incremental caching support.
 * Plugins and advanced users can manage their own cache and changed-file tracking.
 *
 * 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.
+* With it, a file it names is always reparsed, whatever its modification time, and every
+* other cached file is reused as it is. A file may be named by an absolute path or by a path
+* relative to the working directory, with or without a leading `./`: entries are matched to
+* the source files by resolved path. A file that fails to load is dropped from the cache, so
+* the next build tries it again.
 */
 async function compileIncremental(options, cache, changedFiles) {
 	return buildOutput(options, cache, changedFiles);
 }
 /**
-* Watch for file changes and recompile. Every build is written to `outFile`, including
-* one whose diagnostics report errors. Builds run one at a time: changes made during a
-* build go into one follow-up build after it, and the superseded build is neither
-* written nor reported.
+* Watch for file changes and recompile. Every build is written to `outFile` (replacing it
+* atomically, as compileToFile() does), including one whose diagnostics report errors.
+* Builds run one at a time, and each one is written and reported as it finishes, in order:
+* changes made during a build go into one follow-up build after it. A watched path that
+* can't be watched is passed to `onError`.
+*
+* Aborting the returned controller, or the `signal` in the options, stops watching and
+* aborts the story format requests of the build in progress.
 */
 async function watch(options) {
 	return watchWithWriteFilter(options, () => true);
@@ -5759,9 +6991,13 @@ async function watch(options) {
 * Internal, for the CLI, which keeps the last good output when a rebuild reports errors;
 * not part of the public API.
 */
-async function watchWithWriteFilter(options, shouldWrite) {
+async function watchWithWriteFilter(options, shouldWrite, hooks = {}) {
 	const controller = new AbortController();
 	const cache = /* @__PURE__ */ new Map();
+	const buildOptions = {
+		...options,
+		signal: controller.signal
+	};
 	const filePaths = options.sources.filter((s) => typeof s === "string");
 	const modulePaths = options.modules ?? [];
 	const headPaths = options.headFile ? [options.headFile] : [];
@@ -5779,13 +7015,20 @@ async function watchWithWriteFilter(options, shouldWrite) {
 	};
 	let building = false;
 	let queued;
+	const reportError = (error) => {
+		try {
+			options.onError?.(error);
+		} catch (e) {
+			console.error(`twee-ts watch: onError threw while handling "${error.message}": ${toError(e).message}`);
+		}
+	};
 	const deliver = (outcome) => {
 		try {
 			if (!outcome.ok) throw outcome.error;
-			if (shouldWrite(outcome.result)) writeFileSync(options.outFile, outcome.result.output, "utf-8");
+			if (shouldWrite(outcome.result)) writeFileAtomic(options.outFile, outcome.result.output);
 			options.onBuild?.(outcome.result);
 		} catch (e) {
-			options.onError?.(toError(e));
+			reportError(toError(e));
 		}
 	};
 	const drain = async (first) => {
@@ -5793,8 +7036,7 @@ async function watchWithWriteFilter(options, shouldWrite) {
 		try {
 			let request = first;
 			while (request !== void 0) {
-				const current = request;
-				const outcome = await buildOutput(options, cache, current.changedFiles, options.outFile).then((result) => ({
+				const outcome = await buildOutput(buildOptions, cache, request.changedFiles, options.outFile).then((result) => ({
 					ok: true,
 					result
 				}), (e) => ({
@@ -5802,12 +7044,13 @@ async function watchWithWriteFilter(options, shouldWrite) {
 					error: toError(e)
 				}));
 				if (controller.signal.aborted) return;
-				request = queued === void 0 ? void 0 : mergeBuildRequests(current, queued);
+				deliver(outcome);
+				request = queued;
 				queued = void 0;
-				if (request === void 0) deliver(outcome);
 			}
 		} finally {
 			building = false;
+			hooks.onIdle?.();
 		}
 	};
 	const handle = watchFilesystem(allPaths, options.outFile, (changedFiles) => {
@@ -5817,12 +7060,17 @@ async function watchWithWriteFilter(options, shouldWrite) {
 			queued = queued === void 0 ? request : mergeBuildRequests(queued, request);
 			return;
 		}
-		drain(request);
-	}, ignore);
+		drain(request).catch((e) => reportError(toError(e)));
+	}, ignore, reportError);
+	const outer = options.signal;
+	const onOuterAbort = () => controller.abort(outer?.reason);
 	controller.signal.addEventListener("abort", () => {
 		queued = void 0;
 		handle.close();
+		outer?.removeEventListener("abort", onOuterAbort);
 	});
+	if (outer?.aborted) onOuterAbort();
+	else outer?.addEventListener("abort", onOuterAbort, { once: true });
 	return controller;
 }
 /** One build covering both requests: a full build if either is one, else every changed file. */
@@ -5834,10 +7082,13 @@ function toError(e) {
 	return e instanceof Error ? e : new Error(String(e));
 }
 /**
-* `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;
@@ -5845,13 +7096,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, {
@@ -5880,7 +7136,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 });
@@ -5898,13 +7157,20 @@ async function buildOutput(options, cache, changedFiles, outFile) {
 				level: "error",
 				message: "Special passage \"StoryTitle\" not found."
 			});
-			const modules = getFilenames(options.modules ?? [], outFile);
+			const modules = getFilenames(options.modules ?? [], written);
 			diagnostics.push(...modules.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
-			}) : toTwine1HTML(story, format, startName, { head });
+				head,
+				diagnostics
+			}) : toTwine1HTML(story, format, startName, {
+				head,
+				diagnostics
+			});
 			break;
 		}
 		default: throw new TweeTsError(`Unhandled output mode: ${outputMode}`, diagnostics);
@@ -5921,6 +7187,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 !== "") {
@@ -7490,7 +8766,7 @@ function storyInspect(story, options = {}) {
 		if (isStoryPassage(p)) storyPassages.push(p.name);
 		if (isInfoPassage(p)) infoPassages.push(p.name);
 		tagsByPassage.set(p.name, [...p.tags]);
-		for (const tag of p.tags) {
+		for (const tag of new Set(p.tags)) {
 			tagSet.add(tag);
 			let list = passagesByTag.get(tag);
 			if (!list) {
@@ -7634,46 +8910,100 @@ const VALID_OUTPUT_MODES = [
 	"json"
 ];
 const VALID_WORD_COUNT_METHODS = ["tweego", "whitespace"];
-/** Load a config file from the given directory (default: cwd). Returns null if not found. */
-function loadConfig(dir) {
+/** One entry per {@link TweeTsConfig} key: the compiler rejects a missing or an extra key here. */
+const CONFIG_KEY_SET = {
+	sources: true,
+	exclude: true,
+	output: true,
+	outputMode: true,
+	formatId: true,
+	startPassage: true,
+	formatPaths: true,
+	formatIndices: true,
+	formatUrls: true,
+	useTweegoPath: true,
+	modules: true,
+	headFile: true,
+	trim: true,
+	twee2Compat: true,
+	testMode: true,
+	noRemote: true,
+	formatFetchTimeout: true,
+	tagAliases: true,
+	sourceInfo: true,
+	wordCountMethod: true
+};
+/** The keys a config file may hold besides `$schema`; the JSON schema's `properties` list the same keys. */
+const CONFIG_KEYS = Object.keys(CONFIG_KEY_SET);
+/** The key that only references the JSON schema, for editors. */
+const SCHEMA_KEY = "$schema";
+/** A key folded so that spellings differing only in letter case, `-` or `_` compare equal. */
+const foldKey = (key) => key.toLowerCase().replace(/[-_]/g, "");
+/**
+* Load a config file from the given directory (default: cwd). Returns null if not found.
+*
+* @param diagnostics Receives warnings that do not stop the config from loading: keys the config does not
+*   define, and a file that is not valid UTF-8 (it is read as Windows-1252).
+* @throws When the file is not valid JSON or fails {@link validateConfig}.
+*/
+function loadConfig(dir, diagnostics) {
 	const base = dir ?? process.cwd();
 	const configPath = join(base, CONFIG_FILENAME);
 	if (!existsSync(configPath)) return null;
+	const readDiagnostics = [];
 	let raw;
 	try {
-		raw = readFileSync(configPath, "utf-8");
+		raw = readUTF8(configPath, readDiagnostics);
 	} catch {
 		return null;
 	}
-	let data;
-	try {
-		data = JSON.parse(raw);
-	} catch (e) {
-		throw new Error(`Invalid JSON in ${configPath}: ${e instanceof Error ? e.message : String(e)}`);
-	}
-	const errors = validateConfig(data);
-	if (errors.length > 0) throw new Error(`Invalid config in ${configPath}:\n  ${errors.join("\n  ")}`);
-	return data;
+	const config = parseConfig(raw, configPath, readDiagnostics);
+	diagnostics?.push(...readDiagnostics);
+	return config;
 }
-/** Load a config from a specific file path. */
-function loadConfigFile(filePath) {
+/**
+* Load a config from a specific file path.
+*
+* @param diagnostics Receives warnings that do not stop the config from loading: keys the config does not
+*   define, and a file that is not valid UTF-8 (it is read as Windows-1252).
+* @throws When the file cannot be read, is not valid JSON or fails {@link validateConfig}.
+*/
+function loadConfigFile(filePath, diagnostics) {
+	const readDiagnostics = [];
 	let raw;
 	try {
-		raw = readFileSync(filePath, "utf-8");
+		raw = readUTF8(filePath, readDiagnostics);
 	} catch (e) {
 		throw new Error(`Cannot read config file ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
 	}
+	const config = parseConfig(raw, filePath, readDiagnostics);
+	diagnostics?.push(...readDiagnostics);
+	return config;
+}
+/**
+* Parse and validate the text of the config file at `path`. Unknown keys are added to `diagnostics` as
+* warnings, so a config with a stray key keeps loading.
+*/
+function parseConfig(raw, path, diagnostics) {
 	let data;
 	try {
 		data = JSON.parse(raw);
 	} catch (e) {
-		throw new Error(`Invalid JSON in ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+		throw new Error(`Invalid JSON in ${path}: ${e instanceof Error ? e.message : String(e)}`);
 	}
 	const errors = validateConfig(data);
-	if (errors.length > 0) throw new Error(`Invalid config in ${filePath}:\n  ${errors.join("\n  ")}`);
+	if (errors.length > 0) throw new Error(`Invalid config in ${path}:\n  ${errors.join("\n  ")}`);
+	diagnostics.push(...unknownConfigKeyWarnings(data).map((message) => ({
+		level: "warning",
+		message: `${path}: ${message}`,
+		file: path
+	})));
 	return data;
 }
-/** Validate a config object. Returns an array of error strings (empty = valid). */
+/**
+* Validate a config object. Returns an array of error strings (empty = valid).
+* Keys the config does not define are not errors; {@link unknownConfigKeyWarnings} reports them.
+*/
 function validateConfig(data) {
 	const errors = [];
 	if (typeof data !== "object" || data === null || Array.isArray(data)) {
@@ -7706,6 +9036,10 @@ function validateConfig(data) {
 		if (!Array.isArray(obj[key])) errors.push(`"${key}" must be an array.`);
 		else if (!obj[key].every((v) => typeof v === "string")) errors.push(`"${key}" must be an array of strings.`);
 	}
+	if ("formatFetchTimeout" in obj) {
+		const timeout = obj["formatFetchTimeout"];
+		if (typeof timeout !== "number" || !(timeout >= 0)) errors.push("\"formatFetchTimeout\" must be a number of milliseconds, 0 or more.");
+	}
 	if ("tagAliases" in obj) {
 		if (typeof obj["tagAliases"] !== "object" || obj["tagAliases"] === null || Array.isArray(obj["tagAliases"])) errors.push("\"tagAliases\" must be an object.");
 		else {
@@ -7721,6 +9055,20 @@ function validateConfig(data) {
 	}
 	return errors;
 }
+/**
+* Warnings for the keys of a config object that the config does not define (the JSON schema's
+* `additionalProperties: false`), other than `$schema`. twee-ts ignores such a key, so a misspelt one would
+* otherwise leave its option at the default without a word. A key that differs from a defined one only in
+* letter case, `-` or `_` (`formatID`, `output-mode`) gets a suggestion. Returns `[]` for anything that is not
+* an object, which {@link validateConfig} reports.
+*/
+function unknownConfigKeyWarnings(data) {
+	if (typeof data !== "object" || data === null || Array.isArray(data)) return [];
+	return Object.keys(data).filter((key) => key !== SCHEMA_KEY && !Object.hasOwn(CONFIG_KEY_SET, key)).map((key) => {
+		const suggestion = CONFIG_KEYS.find((known) => foldKey(known) === foldKey(key));
+		return `Unknown config key "${key}"${suggestion === void 0 ? "" : ` (did you mean "${suggestion}"?)`}; it is ignored.`;
+	});
+}
 /** Return a default config JSON string for --init scaffolding. */
 function scaffoldConfig() {
 	return JSON.stringify({
@@ -7730,6 +9078,6 @@ function scaffoldConfig() {
 	}, null, 2) + "\n";
 }
 //#endregion
-export { CONFIG_FILENAME, ItemType, StoryBuilder, TweeLexer, TweeTsError, applyTagAliases, clearCachedFormats, compile, compileIncremental, compileToFile, createIFID, decompileHTML, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getCacheSize, getFormatSearchDirs, lint, listCachedFormats, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };
+export { CONFIG_FILENAME, ItemType, StoryBuilder, TweeLexer, TweeTsError, applyTagAliases, clearCachedFormats, compile, compileIncremental, compileToFile, createIFID, decompileHTML, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getCacheSize, getFormatSearchDirs, lint, listCachedFormats, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, unknownConfigKeyWarnings, validateConfig, validateIFID, watch };
 
 //# sourceMappingURL=index.js.map