@rohal12/twee-ts 1.16.0 → 1.17.0

package/dist/bin/twee-ts.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import * as nodePath from "node:path";
-import { basename, dirname, extname, join, parse, relative, resolve, sep } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -106,6 +106,61 @@ function commentSanitize(s) {
 function htmlCommentSanitize(s) {
 	return s.replace(/-->/g, "-- >");
 }
+/**
+* Escape JavaScript for the content of an HTML `<script>` element, so that the HTML parser reads all of it as
+* the element's text and ends the element at the end tag written after it.
+*
+* - Every `<\/script` (in any letter case) becomes `<\/script`. HTML ends a script element at the first
+*   `<\/script` followed by whitespace, `/` or `>`, wherever it is in the JavaScript, even inside a string.
+* - Every `<!--` becomes `<\!--`, but only if the text would otherwise end in the HTML tokenizer's "script
+*   data double escaped" state: after a `<!--` and then a `<script` start tag with no `-->` between them, the
+*   end tag after the text would not end the element.
+*
+* Inserting a backslash after `<` keeps the value of every string, template, and regular expression literal
+* and every comment where these sequences can be written (`\/` and `\!` are identity escapes; a backslash
+* already before the `<` escapes the `<`, as it did before); `<\/script` is also how minifiers such as Terser
+* write inline scripts. It only changes code that uses them outside literals (`a <\/script/ b`, an HTML-like `<!--`
+* comment that is escaped because of a later `<script`), the raw text of a tagged template, and a `<!--` in a
+* regular expression with the `u` or `v` flag. The result is unchanged by escaping it again.
+*/
+function scriptContentEscape(s) {
+	const escaped = s.replace(/<(?=\/script)/gi, "<\\");
+	return endsDoubleEscaped(escaped) ? escaped.replace(/<(?=!--)/g, "<\\") : escaped;
+}
+/**
+* Whether the HTML tokenizer, reading `s` as script element content with no `<\/script` in it, ends in the
+* "script data double escaped" state, where an end tag after `s` would not end the element.
+* See https://html.spec.whatwg.org/multipage/parsing.html#script-data-escaped-state.
+*/
+function endsDoubleEscaped(s) {
+	const scriptStartTag = /<script[\t\n\f\r />]/gi;
+	let pos = 0;
+	for (;;) {
+		const open = s.indexOf("<!--", pos);
+		if (open === -1) return false;
+		const escapedFrom = open + 2;
+		const close = s.indexOf("-->", escapedFrom);
+		scriptStartTag.lastIndex = escapedFrom;
+		const start = scriptStartTag.exec(s);
+		if (start === null || close !== -1 && close < start.index) {
+			if (close === -1) return false;
+			pos = close + 3;
+			continue;
+		}
+		const end = s.indexOf("-->", start.index + start[0].length);
+		if (end === -1) return true;
+		pos = end + 3;
+	}
+}
+/**
+* Escape CSS for the content of an HTML `<style>` element: every `</style` (in any letter case) becomes
+* `<\/style`, since HTML ends a style element at the first `</style` followed by whitespace, `/` or `>`.
+* `\/` stands for `/` in CSS strings and URLs, and comments don't matter; `</style` anywhere else isn't valid
+* CSS anyway.
+*/
+function styleContentEscape(s) {
+	return s.replace(/<(?=\/style)/gi, "<\\");
+}
 /** Apply ROT13 encoding to a string (only affects [A-Za-z]). */
 function rot13(s) {
 	if (s.length === 0) return s;
@@ -663,10 +718,35 @@ function getFilenames(pathnames, outFilename, exclude = []) {
 		diagnostics
 	};
 }
+/** 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.
+*/
+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);
+	}
+	return {
+		dirs,
+		files
+	};
+}
 /**
 * Watch paths for changes, calling the build callback on known file type changes.
-* A change to a file `ignore` returns true for (given the path relative to the
-* working directory) schedules no build.
+* 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) {
@@ -685,18 +765,30 @@ function watchFilesystem(pathnames, outFilename, callback, ignore = () => false)
 			callback(files);
 		}, BUILD_DEBOUNCE);
 	}
-	for (const pathname of pathnames) try {
-		const watcher = watch(pathname, { recursive: true }, (_event, filename) => {
-			if (!filename) return;
-			const abs = resolve(pathname, filename);
-			if (abs === absOutFile) return;
-			if (isKnownFileType(filename)) {
-				const rel = relative(process.cwd(), abs);
-				if (!ignore(rel || abs)) scheduleBuild(rel || abs);
-			}
-		});
-		watchers.push(watcher);
-	} catch {}
+	function fileChanged(abs, named) {
+		if (abs === absOutFile) return;
+		if (!named && !isKnownFileType(abs)) return;
+		const rel = relative(process.cwd(), abs);
+		if (!ignore(rel || abs)) scheduleBuild(rel || abs);
+	}
+	function watchPath(pathname, recursive, listener) {
+		try {
+			watchers.push(watch(pathname, { recursive }, (_event, filename) => {
+				if (filename) listener(filename);
+			}));
+		} catch {}
+	}
+	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);
+	});
 	callback();
 	return { close() {
 		if (buildTimer) clearTimeout(buildTimer);
@@ -704,16 +796,25 @@ function watchFilesystem(pathnames, outFilename, callback, ignore = () => false)
 	} };
 }
 //#endregion
+//#region src/source-text.ts
+/**
+* Source text normalization shared by every input path (files, in-memory sources, `parseTwee`).
+*/
+/**
+* Strip a leading UTF-8 byte order mark and convert CRLF and bare CR line endings to LF.
+* Idempotent, so text that is already normalized passes through unchanged.
+*/
+function normalizeSourceText(text) {
+	return (text.charCodeAt(0) === 65279 ? text.slice(1) : text).replace(/\r\n?/g, "\n");
+}
+//#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) {
-	let content = readFileSync(filename, "utf-8");
-	if (content.charCodeAt(0) === 65279) content = content.slice(1);
-	content = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-	return content;
+	return normalizeSourceText(readFileSync(filename, "utf-8"));
 }
 /** Read a file as base64. */
 function readBase64(filename) {
@@ -743,16 +844,28 @@ function relaxedJSONParse(json) {
 	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. */
+function stripSetupFunction(chunk) {
+	let lastIndex = -1;
+	for (const match of chunk.matchAll(SETUP_FUNCTION_PROPERTY)) lastIndex = match.index;
+	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.
+* 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.
+*
+* @param _formatId No longer used; kept so existing callers keep compiling.
 */
-function parseFormatJSON(source, formatId) {
+function parseFormatJSON(source, _formatId) {
 	const first = source.indexOf("{");
 	const last = source.lastIndexOf("}");
 	if (first === -1 || last === -1) return null;
-	let chunk = source.slice(first, last + 1);
+	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;
@@ -775,16 +888,13 @@ function parseFormatJSON(source, formatId) {
 	try {
 		return parse(chunk);
 	} catch {
-		if (formatId.toLowerCase().startsWith("harlowe")) {
-			const setupIdx = chunk.lastIndexOf(",\"setup\": function");
-			if (setupIdx !== -1) {
-				chunk = chunk.slice(0, setupIdx) + "}";
-				try {
-					return parse(chunk);
-				} catch {}
-			}
+		const stripped = stripSetupFunction(chunk);
+		if (stripped === void 0) return null;
+		try {
+			return parse(stripped);
+		} catch {
+			return null;
 		}
-		return null;
 	}
 }
 /**
@@ -934,6 +1044,54 @@ function semverCompare(a, b) {
 	if (aPatch !== bPatch) return aPatch - bPatch;
 	return 0;
 }
+/** 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;
+	return `${name.toLowerCase().replace(/\s+/g, "-")}-${major}`;
+}
+/** Describe a format request for diagnostics. */
+function describeFormatRequest(request) {
+	switch (request.kind) {
+		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;
+	let best;
+	for (const candidate of candidates) {
+		const { name, version } = describe(candidate);
+		const have = parseSemver(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;
+			}
+		}
+		if (!best || semverCompare(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);
@@ -963,171 +1121,571 @@ function readFormatSource(format) {
 	return source;
 }
 //#endregion
-//#region src/types.ts
-const ItemType = {
-	Error: 0,
-	EOF: 1,
-	Header: 2,
-	Name: 3,
-	Tags: 4,
-	Metadata: 5,
-	Content: 6
-};
-//#endregion
-//#region src/lexer.ts
-const EOF = -1;
-const HEADER_DELIM = "::";
-const NEWLINE_HEADER_DELIM = "\n::";
-var LexerContext = class {
-	input;
-	line = 1;
-	start = 0;
-	pos = 0;
-	items = [];
-	constructor(input) {
-		this.input = input;
-	}
-	next() {
-		if (this.pos >= this.input.length) return EOF;
-		const ch = this.input.charCodeAt(this.pos);
-		this.pos++;
-		if (ch === 10) this.line++;
-		return ch;
-	}
-	peek() {
-		if (this.pos >= this.input.length) return EOF;
-		return this.input.charCodeAt(this.pos);
-	}
-	backup() {
-		if (this.pos > this.start) {
-			this.pos--;
-			if (this.input.charCodeAt(this.pos) === 10) this.line--;
-		} else throw new Error("backup would leave pos < start");
-	}
-	emit(type) {
-		const val = this.input.slice(this.start, this.pos);
-		this.items.push({
-			type,
-			line: this.line,
-			pos: this.start,
-			val
-		});
-		if (type === ItemType.Content) {
-			for (let i = this.start; i < this.pos; i++) if (this.input.charCodeAt(i) === 10) this.line++;
-		}
-		this.start = this.pos;
-	}
-	ignore() {
-		for (let i = this.start; i < this.pos; i++) if (this.input.charCodeAt(i) === 10) this.line++;
-		this.start = this.pos;
-	}
-	acceptRun(valid) {
-		let ch;
-		for (ch = this.next(); ch !== EOF && valid.includes(String.fromCharCode(ch)); ch = this.next());
-		if (ch !== EOF) this.backup();
-	}
-	errorf(message) {
-		this.items.push({
-			type: ItemType.Error,
-			line: this.line,
-			pos: this.start,
-			val: message
-		});
-		return null;
-	}
-	/** Drain all pending items and return them. */
-	drainItems() {
-		const result = this.items;
-		this.items = [];
-		return result;
-	}
-};
-function acceptQuoted(ctx, quote) {
-	for (;;) {
-		const ch = ctx.next();
-		switch (ch) {
-			case 92: {
-				const r = ctx.next();
-				if (r !== 10 && r !== EOF) break;
-			}
-			case 10:
-			case EOF: return "unterminated quoted string";
-			default: if (ch === quote) return null;
-		}
-	}
+//#region src/remote-formats.ts
+/**
+* Remote story format fetching, caching, and checksum verification.
+* Uses the Story Formats Archive (SFA) as the default source.
+*/
+const DEFAULT_SFA_INDICES = ["https://videlais.github.io/story-formats-archive/official/index.json", "https://videlais.github.io/story-formats-archive/unofficial/index.json"];
+/** 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");
 }
-function lexProlog(ctx) {
-	if (ctx.input.startsWith(HEADER_DELIM, ctx.pos)) return lexHeaderDelim;
-	const i = ctx.input.indexOf(NEWLINE_HEADER_DELIM, ctx.pos);
-	if (i > -1) {
-		ctx.pos = i + 1;
-		ctx.ignore();
-		return lexHeaderDelim;
+/**
+* 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
+* are untrusted path input.
+*/
+function isSafeSegment(segment) {
+	return segment !== "" && segment !== "." && segment !== ".." && !/[/\\\0]/.test(segment);
+}
+/** Whether absolute path `target` lies strictly inside absolute path `root`. */
+function isInside(root, target) {
+	const rel = relative(root, target);
+	return rel !== "" && !isAbsolute(rel) && rel.split(sep)[0] !== "..";
+}
+/** The cache directory for one format version. Throws when the name or version could leave the cache. */
+function cachedFormatDir(name, version) {
+	if (!isSafeSegment(name)) throw new Error(`Refusing to cache a story format with an unsafe name: ${JSON.stringify(name)}`);
+	if (!isSafeSegment(version) || !parseSemver(version)) throw new Error(`Refusing to cache story format "${name}" with an unsafe version: ${JSON.stringify(version)}`);
+	const root = resolve(getCacheDir());
+	const dir = resolve(root, name, version);
+	if (!isInside(root, dir)) throw new Error(`Refusing to cache a story format outside the cache directory ${root}: ${dir}`);
+	return dir;
+}
+/** Create `dir` as a plain directory, or check that it already is one (a symlink could lead out of the cache). */
+function ensurePlainDirectory(dir) {
+	const stat = lstatSync(dir, { throwIfNoEntry: false });
+	if (stat === void 0) {
+		mkdirSync(dir);
+		return;
 	}
-	ctx.emit(ItemType.EOF);
-	return null;
+	if (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());
+	mkdirSync(root, { recursive: true });
+	ensurePlainDirectory(join(root, name));
+	ensurePlainDirectory(dir);
+	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");
+	return formatPath;
 }
-function lexContent(ctx) {
-	if (ctx.input.startsWith(HEADER_DELIM, ctx.pos)) return lexHeaderDelim;
-	const i = ctx.input.indexOf(NEWLINE_HEADER_DELIM, ctx.pos);
-	if (i > -1) {
-		ctx.pos = i + 1;
-		ctx.emit(ItemType.Content);
-		return lexHeaderDelim;
-	}
-	ctx.pos = ctx.input.length;
-	if (ctx.pos > ctx.start) ctx.emit(ItemType.Content);
-	ctx.emit(ItemType.EOF);
-	return null;
+/** In-memory index cache, keyed by URL. Cleared each compile. */
+const indexCache = /* @__PURE__ */ new Map();
+/** Clear the in-memory index cache. */
+function clearIndexCache() {
+	indexCache.clear();
 }
-function lexHeaderDelim(ctx) {
-	ctx.pos += 2;
-	ctx.emit(ItemType.Header);
-	return lexName;
+/** Validate that a JSON value is a valid SFAIndexEntry. */
+function isValidEntry(val) {
+	if (typeof val !== "object" || val === null || Array.isArray(val)) return false;
+	const obj = val;
+	return typeof obj.name === "string" && typeof obj.version === "string" && typeof obj.checksums === "object" && obj.checksums !== null && !Array.isArray(obj.checksums);
 }
-function lexName(ctx) {
-	let r;
-	outer: for (;;) {
-		r = ctx.next();
-		switch (r) {
-			case 92: {
-				const next = ctx.next();
-				if (next !== 10 && next !== EOF) break;
-				r = next;
-			}
-			case 91:
-			case 93:
-			case 123:
-			case 125:
-			case 10:
-			case EOF:
-				if (r !== EOF) ctx.backup();
-				break outer;
-		}
-	}
-	ctx.emit(ItemType.Name);
-	switch (r) {
-		case 91: return lexTags;
-		case 93: return ctx.errorf(`unexpected right square bracket ']'`);
-		case 123: return lexMetadata;
-		case 125: return ctx.errorf(`unexpected right curly brace '}'`);
-		case 10:
-			ctx.pos++;
-			ctx.ignore();
-			return lexContent;
-	}
-	ctx.emit(ItemType.EOF);
-	return null;
+/** Validate that a JSON value conforms to the SFAIndex shape. */
+function validateSFAIndex(json) {
+	if (typeof json !== "object" || json === null) throw new Error("SFA index is not an object");
+	const obj = json;
+	return {
+		twine1: Array.isArray(obj["twine1"]) ? obj["twine1"].filter(isValidEntry) : [],
+		twine2: Array.isArray(obj["twine2"]) ? obj["twine2"].filter(isValidEntry) : []
+	};
 }
-function lexNextOptionalBlock(ctx) {
-	ctx.acceptRun(" 	");
-	ctx.ignore();
-	const r = ctx.peek();
-	switch (r) {
-		case 91: return lexTags;
-		case 93: return ctx.errorf(`unexpected right square bracket ']'`);
-		case 123: return lexMetadata;
-		case 125: return ctx.errorf(`unexpected right curly brace '}'`);
+/** Fetch and parse an SFA index.json, with in-memory caching. */
+async function fetchIndex(url) {
+	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;
+}
+/** Find the best matching entry in an SFA index for a name or ID request (twine2 entries first). */
+function findEntryForRequest(index, request) {
+	return selectFormatCandidate(request, [...(index.twine2 ?? []).map((entry) => ({
+		entry,
+		formatType: "twine2"
+	})), ...(index.twine1 ?? []).map((entry) => ({
+		entry,
+		formatType: "twine1"
+	}))], (c) => c.entry);
+}
+/** Verify SHA-256 checksum using Web Crypto API (Node 22 built-in). */
+async function verifySHA256(content, expectedHex) {
+	const digest = await crypto.subtle.digest("SHA-256", content);
+	return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("") === expectedHex.toLowerCase();
+}
+/** Derive the download URL for a format.js from the index URL and entry. */
+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}`);
+	return {
+		id,
+		filename: writeCachedFormat(entry.name, entry.version, text),
+		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
+	};
+}
+/**
+* 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) {
+	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;
+	} catch (e) {
+		lastError = e instanceof Error ? e : new Error(String(e));
+	}
+	const allIndices = [...indices ?? [], ...DEFAULT_SFA_INDICES];
+	for (const indexUrl of allIndices) try {
+		const result = findEntryForRequest(await fetchIndex(indexUrl), 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);
+		}
+	} catch (e) {
+		lastError = e instanceof Error ? e : new Error(String(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.
+* Matching follows {@link selectFormatCandidate}.
+*/
+function findCachedFormat(request, options = {}) {
+	return selectFormatCandidate(request, [...discoverCachedFormats().values()], (f) => f, options);
+}
+/** Check if a format is already in the local cache. */
+function getCachedFormat(name, version) {
+	if (!isSafeSegment(name) || !isSafeSegment(version)) return void 0;
+	const formatPath = join(getCacheDir(), name, version, "format.js");
+	try {
+		if (!existsSync(formatPath)) return void 0;
+		const source = readFileSync(formatPath, "utf-8");
+		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
+		};
+	} catch {
+		return;
+	}
+}
+/** Discover all cached remote formats. Returns a Map like discoverFormats(). */
+function discoverCachedFormats() {
+	const formats = /* @__PURE__ */ new Map();
+	const cacheDir = getCacheDir();
+	try {
+		if (!existsSync(cacheDir)) return formats;
+	} catch {
+		return formats;
+	}
+	let names;
+	try {
+		names = readdirSync(cacheDir);
+	} catch {
+		return formats;
+	}
+	for (const name of names) {
+		const nameDir = join(cacheDir, name);
+		try {
+			if (!statSync(nameDir).isDirectory()) continue;
+		} catch {
+			continue;
+		}
+		let versions;
+		try {
+			versions = readdirSync(nameDir);
+		} catch {
+			continue;
+		}
+		for (const version of versions) {
+			const info = getCachedFormat(name, version);
+			if (info) formats.set(`${info.id}-${version}`, info);
+		}
+	}
+	return formats;
+}
+/** List all cached formats with size and modification date. */
+function listCachedFormats() {
+	const cacheDir = getCacheDir();
+	const entries = [];
+	try {
+		if (!existsSync(cacheDir)) return entries;
+	} catch {
+		return entries;
+	}
+	let names;
+	try {
+		names = readdirSync(cacheDir);
+	} catch {
+		return entries;
+	}
+	for (const name of names) {
+		const nameDir = join(cacheDir, name);
+		try {
+			if (!statSync(nameDir).isDirectory()) continue;
+		} catch {
+			continue;
+		}
+		let versions;
+		try {
+			versions = readdirSync(nameDir);
+		} catch {
+			continue;
+		}
+		for (const version of versions) {
+			const formatPath = join(nameDir, version, "format.js");
+			try {
+				const stat = statSync(formatPath);
+				entries.push({
+					name,
+					version,
+					sizeBytes: stat.size,
+					modifiedAt: stat.mtime
+				});
+			} catch {}
+		}
+	}
+	return entries;
+}
+/**
+* Clear all cached formats, or only those matching a given name. Returns the number of entries removed.
+* 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;
+		rmSync(cacheDir, {
+			recursive: true,
+			force: true
+		});
+		return count;
+	}
+	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.`);
+	if (!lstatSync(nameDir, { throwIfNoEntry: false })?.isDirectory()) return 0;
+	let versions;
+	try {
+		versions = readdirSync(nameDir);
+	} catch {
+		return 0;
+	}
+	const count = versions.length;
+	rmSync(nameDir, {
+		recursive: true,
+		force: true
+	});
+	return count;
+}
+/** Get total cache size in bytes and format count. */
+function getCacheSize() {
+	const entries = listCachedFormats();
+	return {
+		totalBytes: entries.reduce((sum, e) => sum + e.sizeBytes, 0),
+		count: entries.length
+	};
+}
+//#endregion
+//#region src/format-resolution.ts
+/** Choose the format request: explicit format ID > StoryData format > default ID. */
+function formatRequestFor(formatId, storyFormat, storyFormatVersion, defaultId) {
+	if (formatId) return {
+		kind: "id",
+		id: formatId
+	};
+	if (storyFormat) return {
+		kind: "name",
+		name: storyFormat,
+		version: storyFormatVersion
+	};
+	return {
+		kind: "id",
+		id: defaultId
+	};
+}
+/** Look a request up among the formats found in local format directories. */
+function findLocalFormat(formats, 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);
+		}
+		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
+* 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 wanted = describeFormatRequest(request);
+	const local = findLocalFormat(formats, request);
+	if (local) return local;
+	const cached = findCachedFormat(request);
+	if (cached) return cached;
+	if (!noRemote) try {
+		const remote = await resolveRemoteFormatRequest(request, options.formatIndices, options.formatUrls);
+		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 });
+		if (older) {
+			diagnostics.push({
+				level: "warning",
+				message: `Story format ${wanted} is not available; using ${older.name} ${older.version} instead.`
+			});
+			return older;
+		}
+	}
+	const reason = noRemote ? " (remote fetching disabled)" : "";
+	diagnostics.push({
+		level: "error",
+		message: `Story format ${wanted} is not available${reason}. Found: ${[...formats.keys()].join(", ") || "none"}`
+	});
+}
+//#endregion
+//#region src/types.ts
+const ItemType = {
+	Error: 0,
+	EOF: 1,
+	Header: 2,
+	Name: 3,
+	Tags: 4,
+	Metadata: 5,
+	Content: 6
+};
+//#endregion
+//#region src/lexer.ts
+const EOF = -1;
+const HEADER_DELIM = "::";
+const NEWLINE_HEADER_DELIM = "\n::";
+var LexerContext = class {
+	input;
+	line = 1;
+	start = 0;
+	pos = 0;
+	items = [];
+	constructor(input) {
+		this.input = input;
+	}
+	next() {
+		if (this.pos >= this.input.length) return EOF;
+		const ch = this.input.charCodeAt(this.pos);
+		this.pos++;
+		if (ch === 10) this.line++;
+		return ch;
+	}
+	peek() {
+		if (this.pos >= this.input.length) return EOF;
+		return this.input.charCodeAt(this.pos);
+	}
+	backup() {
+		if (this.pos > this.start) {
+			this.pos--;
+			if (this.input.charCodeAt(this.pos) === 10) this.line--;
+		} else throw new Error("backup would leave pos < start");
+	}
+	emit(type) {
+		const val = this.input.slice(this.start, this.pos);
+		this.items.push({
+			type,
+			line: this.line,
+			pos: this.start,
+			val
+		});
+		if (type === ItemType.Content) {
+			for (let i = this.start; i < this.pos; i++) if (this.input.charCodeAt(i) === 10) this.line++;
+		}
+		this.start = this.pos;
+	}
+	ignore() {
+		for (let i = this.start; i < this.pos; i++) if (this.input.charCodeAt(i) === 10) this.line++;
+		this.start = this.pos;
+	}
+	acceptRun(valid) {
+		let ch;
+		for (ch = this.next(); ch !== EOF && valid.includes(String.fromCharCode(ch)); ch = this.next());
+		if (ch !== EOF) this.backup();
+	}
+	errorf(message) {
+		this.items.push({
+			type: ItemType.Error,
+			line: this.line,
+			pos: this.start,
+			val: message
+		});
+		return null;
+	}
+	/** Drain all pending items and return them. */
+	drainItems() {
+		const result = this.items;
+		this.items = [];
+		return result;
+	}
+};
+function acceptQuoted(ctx, quote) {
+	for (;;) {
+		const ch = ctx.next();
+		switch (ch) {
+			case 92: {
+				const r = ctx.next();
+				if (r !== 10 && r !== EOF) break;
+			}
+			case 10:
+			case EOF: return "unterminated quoted string";
+			default: if (ch === quote) return null;
+		}
+	}
+}
+function lexProlog(ctx) {
+	if (ctx.input.startsWith(HEADER_DELIM, ctx.pos)) return lexHeaderDelim;
+	const i = ctx.input.indexOf(NEWLINE_HEADER_DELIM, ctx.pos);
+	if (i > -1) {
+		ctx.pos = i + 1;
+		ctx.ignore();
+		return lexHeaderDelim;
+	}
+	ctx.emit(ItemType.EOF);
+	return null;
+}
+function lexContent(ctx) {
+	if (ctx.input.startsWith(HEADER_DELIM, ctx.pos)) return lexHeaderDelim;
+	const i = ctx.input.indexOf(NEWLINE_HEADER_DELIM, ctx.pos);
+	if (i > -1) {
+		ctx.pos = i + 1;
+		ctx.emit(ItemType.Content);
+		return lexHeaderDelim;
+	}
+	ctx.pos = ctx.input.length;
+	if (ctx.pos > ctx.start) ctx.emit(ItemType.Content);
+	ctx.emit(ItemType.EOF);
+	return null;
+}
+function lexHeaderDelim(ctx) {
+	ctx.pos += 2;
+	ctx.emit(ItemType.Header);
+	return lexName;
+}
+function lexName(ctx) {
+	let r;
+	outer: for (;;) {
+		r = ctx.next();
+		switch (r) {
+			case 92: {
+				const next = ctx.next();
+				if (next !== 10 && next !== EOF) break;
+				r = next;
+			}
+			case 91:
+			case 93:
+			case 123:
+			case 125:
+			case 10:
+			case EOF:
+				if (r !== EOF) ctx.backup();
+				break outer;
+		}
+	}
+	ctx.emit(ItemType.Name);
+	switch (r) {
+		case 91: return lexTags;
+		case 93: return ctx.errorf(`unexpected right square bracket ']'`);
+		case 123: return lexMetadata;
+		case 125: return ctx.errorf(`unexpected right curly brace '}'`);
+		case 10:
+			ctx.pos++;
+			ctx.ignore();
+			return lexContent;
+	}
+	ctx.emit(ItemType.EOF);
+	return null;
+}
+function lexNextOptionalBlock(ctx) {
+	ctx.acceptRun(" 	");
+	ctx.ignore();
+	const r = ctx.peek();
+	switch (r) {
+		case 91: return lexTags;
+		case 93: return ctx.errorf(`unexpected right square bracket ']'`);
+		case 123: return lexMetadata;
+		case 125: return ctx.errorf(`unexpected right curly brace '}'`);
 		case 10:
 			ctx.pos++;
 			ctx.ignore();
@@ -1226,16 +1784,20 @@ function twee2ToV3(s) {
 //#region src/parser.ts
 /**
 * 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.
 */
 function parseTwee(source, options = {}) {
 	const { filename = "<inline>", trim = true, twee2Compat = false } = options;
 	const diagnostics = [];
-	if (twee2Compat) source = twee2ToV3(source);
+	const normalized = normalizeSourceText(source);
+	const tweeSource = twee2Compat ? twee2ToV3(normalized) : normalized;
 	const passages = [];
 	let current = null;
 	let pCount = 0;
 	let lastType = ItemType.EOF;
-	for (const item of tweeLexer(source)) {
+	for (const item of tweeLexer(tweeSource)) {
 		switch (item.type) {
 			case ItemType.Error:
 				diagnostics.push({
@@ -4065,14 +4627,16 @@ 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.
 */
-function decompileHTML(html) {
+function decompileHTML(html, options = {}) {
 	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, diagnostics);
+		decompileTwine2(twine2Data, story, passageText, diagnostics);
 		return {
 			story,
 			diagnostics
@@ -4080,7 +4644,7 @@ function decompileHTML(html) {
 	}
 	const twine1Data = findElementByIdPattern(doc, /^store(?:-a|A)rea$/);
 	if (twine1Data) {
-		decompileTwine1(twine1Data, story, diagnostics);
+		decompileTwine1(twine1Data, story, passageText, diagnostics);
 		return {
 			story,
 			diagnostics
@@ -4095,7 +4659,7 @@ function decompileHTML(html) {
 		diagnostics
 	};
 }
-function decompileTwine2(storyData, story, diagnostics) {
+function decompileTwine2(storyData, story, passageText, diagnostics) {
 	let startnode = 0;
 	const attrs = storyData.attribs ?? {};
 	if (attrs["name"]) story.name = attrs["name"];
@@ -4116,6 +4680,7 @@ function decompileTwine2(storyData, story, diagnostics) {
 		});
 		else story.twine2.zoom = parsed;
 	}
+	if (attrs["tags"]) story.twine2.tags = attrs["tags"];
 	if (attrs["format"]) story.twine2.format = attrs["format"];
 	if (attrs["format-version"]) story.twine2.formatVersion = attrs["format-version"];
 	if (attrs["options"]) for (const opt of attrs["options"].split(/\s+/).filter((s) => s.length > 0)) story.twine2.options.set(opt, true);
@@ -4124,8 +4689,9 @@ function decompileTwine2(storyData, story, diagnostics) {
 		switch (node.name) {
 			case "style":
 			case "script": {
-				const text = getTextContent(node).trim();
-				if (text.length === 0) continue;
+				const content = getTextContent(node);
+				if (content.trim().length === 0) continue;
+				const text = passageText(content);
 				storyAdd(story, {
 					name: node.name === "style" ? "Story Stylesheet" : "Story JavaScript",
 					tags: node.name === "style" ? ["stylesheet"] : ["script"],
@@ -4160,7 +4726,7 @@ function decompileTwine2(storyData, story, diagnostics) {
 				const passage = {
 					name,
 					tags,
-					text: getTextContent(node).trim()
+					text: passageText(getTextContent(node))
 				};
 				if (metadata.position || metadata.size) passage.metadata = metadata;
 				storyAdd(story, passage, diagnostics);
@@ -4174,23 +4740,33 @@ function decompileTwine2(storyData, story, diagnostics) {
 		text: marshalStoryData(story)
 	}, diagnostics);
 }
-function decompileTwine1(storeArea, story, diagnostics) {
-	for (const node of storeArea.children ?? []) {
-		if (node.type !== "tag" || node.name !== "div") continue;
-		const nodeAttrs = node.attribs ?? {};
-		if (!("tiddler" in nodeAttrs)) continue;
-		const name = nodeAttrs["tiddler"] ?? "";
-		const tags = nodeAttrs["tags"] ? nodeAttrs["tags"].split(/\s+/).filter((s) => s.length > 0) : [];
-		const metadata = {};
-		if (nodeAttrs["twine-position"]) metadata.position = nodeAttrs["twine-position"];
-		const passage = {
-			name,
-			tags,
-			text: tiddlerUnescape(getTextContent(node)).trim()
-		};
-		if (metadata.position) passage.metadata = metadata;
-		storyAdd(story, passage, diagnostics);
-	}
+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" ? {
+		...p,
+		text: rot13(p.text)
+	} : p, diagnostics);
+}
+function isTiddler(node) {
+	return node.type === "tag" && node.name === "div" && node.attribs !== void 0 && "tiddler" in node.attribs;
+}
+function tiddlerToPassage(node, passageText) {
+	const nodeAttrs = node.attribs ?? {};
+	const passage = {
+		name: nodeAttrs["tiddler"] ?? "",
+		tags: nodeAttrs["tags"] ? nodeAttrs["tags"].split(/\s+/).filter((s) => s.length > 0) : [],
+		text: passageText(tiddlerUnescape(getTextContent(node)))
+	};
+	const position = nodeAttrs["twine-position"];
+	if (position) passage.metadata = { position };
+	return passage;
+}
+/** Whether the StorySettings tiddlers turn on ROT13 obfuscation, read the way the writer reads them. */
+function isRot13Obfuscated(passages) {
+	const settings = createStory();
+	for (const p of passages) if (p.name === "StorySettings") unmarshalStorySettings(settings, p.text, []);
+	return settings.twine1.settings.get("obfuscate") === "rot13";
 }
 function findElement(node, tagName) {
 	if (node.type === "tag" && node.name === tagName) return node;
@@ -4245,7 +4821,7 @@ function loadSources(story, filenames, opts, diagnostics, processedFiles) {
 					break;
 				case "htm":
 				case "html":
-					loadHTML(story, filename, diagnostics);
+					loadHTML(story, filename, opts, diagnostics);
 					break;
 				case "css":
 					loadTagged(story, "stylesheet", filename, diagnostics);
@@ -4313,7 +4889,7 @@ 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 = typeof source.content === "string" ? source.content : source.content.toString("utf-8");
+		const content = normalizeSourceText(typeof source.content === "string" ? source.content : source.content.toString("utf-8"));
 		const ext = normalizedFileExt(source.filename);
 		switch (ext) {
 			case "":
@@ -4399,13 +4975,33 @@ function parseFontFile(filename) {
 		diagnostics: []
 	};
 }
-function parseHTMLFile(filename) {
-	const result = decompileHTML(readUTF8(filename));
+function parseHTMLFile(filename, opts) {
+	const { story, diagnostics } = decompileHTML(readUTF8(filename), { trim: opts.trim ?? true });
 	return {
-		passages: result.story.passages,
-		diagnostics: [...result.diagnostics]
+		passages: story.name !== "" && !storyHas(story, "StoryTitle") ? [{
+			name: "StoryTitle",
+			tags: [],
+			text: story.name
+		}, ...story.passages] : story.passages,
+		diagnostics: [...diagnostics]
 	};
 }
+/**
+* Identity of the options that affect how a file parses, stored on its cache entry.
+* Twee files depend on `trim` and `twee2Compat`, HTML files on `trim`; every other file type
+* yields the same key for all options.
+*/
+function parseOptionsKey(filename, opts) {
+	const ext = normalizedFileExt(filename);
+	const trim = opts.trim ?? true;
+	if (ext === "htm" || ext === "html") return JSON.stringify({ trim });
+	const twee2File = ext === "tw2" || ext === "twee2";
+	if (!twee2File && ext !== "tw" && ext !== "twee") return "";
+	return JSON.stringify({
+		trim,
+		twee2Compat: twee2File || (opts.twee2Compat ?? false)
+	});
+}
 function parseFile(filename, opts) {
 	switch (normalizedFileExt(filename)) {
 		case "tw":
@@ -4416,7 +5012,7 @@ function parseFile(filename, opts) {
 			twee2Compat: true
 		});
 		case "htm":
-		case "html": return parseHTMLFile(filename);
+		case "html": return parseHTMLFile(filename, opts);
 		case "css": return parseTaggedFile("stylesheet", filename);
 		case "js": return parseTaggedFile("script", filename);
 		case "otf":
@@ -4448,8 +5044,8 @@ function parseFile(filename, opts) {
 		default: return;
 	}
 }
-function loadHTML(story, filename, diagnostics) {
-	const result = parseHTMLFile(filename);
+function loadHTML(story, filename, opts, diagnostics) {
+	const result = parseHTMLFile(filename, opts);
 	diagnostics.push(...result.diagnostics);
 	for (const p of result.passages) storyAdd(story, p, diagnostics);
 }
@@ -4485,8 +5081,11 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 			continue;
 		}
 		currentFiles.add(filename);
-		const cached = cache.get(filename);
-		if (changedFiles && cached && !changedFiles.has(filename)) {
+		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) {
 			diagnostics.push(...cached.diagnostics);
 			for (const p of cached.passages) storyAdd(story, p, diagnostics);
 			processedFiles.add(filename);
@@ -4498,7 +5097,7 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 		} catch {
 			continue;
 		}
-		if (cached && cached.mtimeMs === mtimeMs) {
+		if (cached && !changed && cached.mtimeMs === mtimeMs) {
 			diagnostics.push(...cached.diagnostics);
 			for (const p of cached.passages) storyAdd(story, p, diagnostics);
 			processedFiles.add(filename);
@@ -4509,6 +5108,7 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 			if (!result) continue;
 			cache.set(filename, {
 				mtimeMs,
+				parseOptionsKey: optionsKey,
 				passages: result.passages,
 				diagnostics: result.diagnostics
 			});
@@ -4572,11 +5172,39 @@ function toTwine2HTML(story, format, startName, options) {
 		template = template.replaceAll("{{STORY_NAME}}", () => name);
 	}
 	if (template.includes("{{STORY_DATA}}")) {
-		const data = getTwine2DataChunk(story, startName, options);
+		const data = getTwine2DataChunk({
+			...story,
+			twine2: {
+				...story.twine2,
+				format: format.name,
+				formatVersion: format.version
+			}
+		}, startName, options);
 		template = template.replace("{{STORY_DATA}}", () => data);
 	}
 	return template;
 }
+const OMITTING_TAGS = [
+	"Twine.private",
+	"script",
+	"stylesheet"
+];
+/**
+* Why Twine 2 output leaves a passage out of its `<tw-passagedata>` elements,
+* or `undefined` when the passage is emitted (and so can be the starting passage).
+*/
+function twine2PassageOmission(story, p) {
+	if (p.name === "StoryTitle" || p.name === "StoryData") return {
+		kind: "special-name",
+		name: p.name
+	};
+	const tag = OMITTING_TAGS.find((t) => hasTag(p, t));
+	if (tag !== void 0) return {
+		kind: "tag",
+		tag
+	};
+	if (p.name === "StorySettings" && story.twine1.settings.size === 0) return { kind: "empty-story-settings" };
+}
 function getTwine2DataChunk(story, startName, options) {
 	const parts = [];
 	let startID = "";
@@ -4599,7 +5227,7 @@ function getTwine2DataChunk(story, startName, options) {
 			pidS++;
 		}
 	}
-	parts.push(`<style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css">${styleContent}</style>`);
+	parts.push(`<style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css">${styleContentEscape(styleContent)}</style>`);
 	let scriptContent = "";
 	if (scripts.length === 1) scriptContent = scripts[0]?.text ?? "";
 	else if (scripts.length > 1) {
@@ -4611,7 +5239,7 @@ function getTwine2DataChunk(story, startName, options) {
 			pidS++;
 		}
 	}
-	parts.push(`<script role="script" id="twine-user-script" type="text/twine-javascript">${scriptContent}<\/script>`);
+	parts.push(`<script role="script" id="twine-user-script" type="text/twine-javascript">${scriptContentEscape(scriptContent)}<\/script>`);
 	const validTagColors = /* @__PURE__ */ new Set([
 		"gray",
 		"red",
@@ -4625,8 +5253,7 @@ function getTwine2DataChunk(story, startName, options) {
 	for (const [tag, color] of story.twine2.tagColors) if (validTagColors.has(color) || hexColorPattern.test(color)) parts.push(`<tw-tag name="${attrEscape(tag)}" color="${attrEscape(color)}"></tw-tag>`);
 	pid = 1;
 	for (const p of story.passages) {
-		if (p.name === "StoryTitle" || p.name === "StoryData" || hasAnyTag(p, "script", "stylesheet", "Twine.private")) continue;
-		if (p.name === "StorySettings" && story.twine1.settings.size === 0) continue;
+		if (twine2PassageOmission(story, p) !== void 0) continue;
 		parts.push(passageToPassagedata(p, pid, options));
 		if (startName === p.name) startID = String(pid);
 		pid++;
@@ -4673,423 +5300,194 @@ function toTwine1HTML(story, format, startName) {
 		} catch {
 			footer = "</div>\n</body>\n</html>\n";
 		}
-		template += data + footer;
-	}
-	if (story.ifid) {
-		const safeIfid = htmlCommentSanitize(story.ifid);
-		if (template.includes("<div id=\"store-area\"")) template = template.replace("<div id=\"store-area\"", `<!-- UUID://${safeIfid}// --><div id="store-area"`);
-		else template = template.replace("<div id=\"storeArea\"", `<!-- UUID://${safeIfid}// --><div id="storeArea"`);
-	}
-	return template;
-}
-function getTwine1PassageChunk(story) {
-	const obfuscateRot13 = story.twine1.settings.get("obfuscate") === "rot13";
-	let data = "";
-	let count = 0;
-	for (const p of story.passages) {
-		if (hasTag(p, "Twine.private")) continue;
-		count++;
-		data += passageToTiddler(p, count, obfuscateRot13);
-	}
-	return {
-		data,
-		count
-	};
-}
-function tryReplaceComponent(template, placeholder, componentPath, required) {
-	if (!template.includes(placeholder)) return template;
-	try {
-		let content = readFileSync(componentPath, "utf-8");
-		if (content.charCodeAt(0) === 65279) content = content.slice(1);
-		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)}`);
-		return template;
-	}
-}
-//#endregion
-//#region src/output-twee.ts
-function toTwee(story, outMode) {
-	let data = "";
-	for (const p of story.passages) data += passageToTwee(p, outMode);
-	return data;
-}
-//#endregion
-//#region src/modules.ts
-/**
-* Load modules and return HTML tags to inject before </head>.
-*/
-function loadModules(filenames) {
-	const processed = /* @__PURE__ */ new Set();
-	const headTags = [];
-	for (const filename of filenames) {
-		if (processed.has(filename)) continue;
-		const ext = normalizedFileExt(filename);
-		let tag = null;
-		switch (ext) {
-			case "css":
-				tag = loadModuleTagged("style", filename);
-				break;
-			case "js":
-				tag = loadModuleTagged("script", filename);
-				break;
-			case "otf":
-			case "ttf":
-			case "woff":
-			case "woff2":
-				tag = loadModuleFont(filename);
-				break;
-			default: continue;
-		}
-		if (tag) headTags.push(tag);
-		processed.add(filename);
-	}
-	return headTags.join("\n");
-}
-function loadModuleTagged(tag, filename) {
-	const source = readUTF8(filename).trim();
-	if (source.length === 0) return null;
-	return `<${tag} id="${`${tag}-module-${slugify(baseNameWithoutExt(filename))}`}" type="${tag === "script" ? "text/javascript" : "text/css"}">${source}</${tag}>`;
-}
-function loadModuleFont(filename) {
-	const source = readBase64(filename);
-	const family = baseNameWithoutExt(filename);
-	const idSlug = `style-module-${slugify(family)}`;
-	const ext = normalizedFileExt(filename);
-	return `<style id="${idSlug}" type="text/css">@font-face {\n\tfont-family: "${family}";\n\tsrc: url("data:${mediaTypeFromExt(ext)};base64,${source}") format("${fontFormatHint(ext)}");\n}</style>`;
-}
-/**
-* Inject modules and head file content before </head>.
-*/
-function modifyHead(html, modulePaths, headFile, diagnostics) {
-	const parts = [];
-	if (modulePaths.length > 0) {
-		const modules = loadModules(modulePaths).trim();
-		if (modules.length > 0) parts.push(modules);
-	}
-	if (headFile) try {
-		const source = readUTF8(headFile).trim();
-		if (source.length > 0) parts.push(source);
-	} catch (e) {
-		diagnostics?.push({
-			level: "warning",
-			message: `Failed to read head file "${headFile}": ${e instanceof Error ? e.message : String(e)}`
-		});
+		template += data + footer;
 	}
-	if (parts.length > 0) {
-		parts.push("</head>");
-		const replacement = parts.join("\n");
-		return html.replace("</head>", () => replacement);
+	if (story.ifid) {
+		const safeIfid = htmlCommentSanitize(story.ifid);
+		if (template.includes("<div id=\"store-area\"")) template = template.replace("<div id=\"store-area\"", `<!-- UUID://${safeIfid}// --><div id="store-area"`);
+		else template = template.replace("<div id=\"storeArea\"", `<!-- UUID://${safeIfid}// --><div id="storeArea"`);
 	}
-	return html;
+	return template;
 }
-//#endregion
-//#region src/remote-formats.ts
 /**
-* Remote story format fetching, caching, and checksum verification.
-* Uses the Story Formats Archive (SFA) as the default source.
+* Why Twine 1 output leaves a passage out of its tiddlers, or `undefined` when the passage is emitted.
 */
-const DEFAULT_SFA_INDICES = ["https://videlais.github.io/story-formats-archive/official/index.json", "https://videlais.github.io/story-formats-archive/unofficial/index.json"];
-/** 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");
-}
-/** In-memory index cache, keyed by URL. Cleared each compile. */
-const indexCache = /* @__PURE__ */ new Map();
-/** Clear the in-memory index cache. */
-function clearIndexCache() {
-	indexCache.clear();
-}
-/** Validate that a JSON value is a valid SFAIndexEntry. */
-function isValidEntry(val) {
-	if (typeof val !== "object" || val === null || Array.isArray(val)) return false;
-	const obj = val;
-	return typeof obj.name === "string" && typeof obj.version === "string" && typeof obj.checksums === "object" && obj.checksums !== null && !Array.isArray(obj.checksums);
+function twine1PassageOmission(p) {
+	return hasTag(p, "Twine.private") ? {
+		kind: "tag",
+		tag: "Twine.private"
+	} : void 0;
 }
-/** Validate that a JSON value conforms to the SFAIndex shape. */
-function validateSFAIndex(json) {
-	if (typeof json !== "object" || json === null) throw new Error("SFA index is not an object");
-	const obj = json;
+function getTwine1PassageChunk(story) {
+	const obfuscateRot13 = story.twine1.settings.get("obfuscate") === "rot13";
+	let data = "";
+	let count = 0;
+	for (const p of story.passages) {
+		if (twine1PassageOmission(p) !== void 0) continue;
+		count++;
+		data += passageToTiddler(p, count, obfuscateRot13);
+	}
 	return {
-		twine1: Array.isArray(obj["twine1"]) ? obj["twine1"].filter(isValidEntry) : [],
-		twine2: Array.isArray(obj["twine2"]) ? obj["twine2"].filter(isValidEntry) : []
+		data,
+		count
 	};
 }
-/** Generate a format ID from name and version. */
-function makeFormatId(name, version) {
-	const major = parseSemver(version)?.[0] ?? "0";
-	return `${name.toLowerCase().replace(/\s+/g, "-")}-${major}`;
-}
-/** Fetch and parse an SFA index.json, with in-memory caching. */
-async function fetchIndex(url) {
-	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;
+function tryReplaceComponent(template, placeholder, componentPath, required) {
+	if (!template.includes(placeholder)) return template;
+	try {
+		let content = readFileSync(componentPath, "utf-8");
+		if (content.charCodeAt(0) === 65279) content = content.slice(1);
+		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)}`);
+		return template;
+	}
 }
+//#endregion
+//#region src/output-twee.ts
 /**
-* Find the best matching entry in an SFA index.
-* Exact version preferred, then highest version with same major.
+* Serialize the story as Twee. The StoryData passage is written from the story model rather than
+* 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.
+*
+* `addStoryData`: add a StoryData passage when the story has none, so that StoryData fields the
+* compile options set are recorded. Default: false.
 */
-function findEntry(index, name, version) {
-	const wanted = parseSemver(version);
-	const searchArrays = [{
-		entries: index.twine2 ?? [],
-		formatType: "twine2"
-	}, {
-		entries: index.twine1 ?? [],
-		formatType: "twine1"
-	}];
-	let bestResult;
-	let bestVersion = null;
-	for (const { entries, formatType } of searchArrays) for (const entry of entries) {
-		if (entry.name.toLowerCase() !== name.toLowerCase()) continue;
-		const have = parseSemver(entry.version);
-		if (!have) continue;
-		if (wanted && semverCompare(have, wanted) === 0) return {
-			entry,
-			formatType
-		};
-		if (wanted === null || have[0] === wanted[0] && semverCompare(have, wanted) >= 0) {
-			if (!bestVersion || semverCompare(have, bestVersion) > 0) {
-				bestVersion = have;
-				bestResult = {
-					entry,
-					formatType
-				};
-			}
-		}
-	}
-	return bestResult;
-}
-/** Verify SHA-256 checksum using Web Crypto API (Node 22 built-in). */
-async function verifySHA256(content, expectedHex) {
-	const digest = await crypto.subtle.digest("SHA-256", content);
-	return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("") === expectedHex.toLowerCase();
-}
-/** Derive the download URL for a format.js from the index URL and entry. */
-function getDownloadUrl(indexUrl, entry, formatType) {
-	return `${indexUrl.replace(/\/index\.json$/, "")}/${formatType}/${entry.name}/${entry.version}/format.js`;
+function toTwee(story, outMode, options = {}) {
+	return withEffectiveStoryData(story, options.addStoryData ?? false).map((p) => passageToTwee(p, outMode)).join("");
 }
-/** Download a format, verify its checksum, write to cache, and return StoryFormatInfo. */
-async function fetchAndCacheFormat(entry, downloadUrl) {
-	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}`);
-	const cacheDir = getCacheDir();
-	const formatDir = join(cacheDir, entry.name, entry.version);
-	mkdirSync(formatDir, { recursive: true });
-	const formatPath = join(formatDir, "format.js");
-	writeFileSync(formatPath, text, "utf-8");
-	return {
-		id,
-		filename: formatPath,
-		isTwine2: true,
-		name: data.name,
-		version: data.version,
-		proofing: data.proofing ?? false
+function withEffectiveStoryData(story, addStoryData) {
+	const storyData = {
+		name: "StoryData",
+		tags: [],
+		text: marshalStoryData(story)
 	};
+	const index = story.passages.findIndex((p) => p.name === "StoryData");
+	if (index !== -1) return story.passages.map((p, i) => i === index && isStoryDataJSON(p.text) ? {
+		...p,
+		text: storyData.text
+	} : p);
+	if (!addStoryData) return story.passages;
+	const at = story.passages[0]?.name === "StoryTitle" ? 1 : 0;
+	return [
+		...story.passages.slice(0, at),
+		storyData,
+		...story.passages.slice(at)
+	];
 }
-/** 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, "direct-url");
-	if (!data) throw new Error(`Failed to parse format JSON from ${url}`);
-	const id = makeFormatId(data.name, data.version);
-	const cacheDir = getCacheDir();
-	const formatDir = join(cacheDir, data.name, data.version);
-	mkdirSync(formatDir, { recursive: true });
-	const formatPath = join(formatDir, "format.js");
-	writeFileSync(formatPath, text, "utf-8");
-	return {
-		id,
-		filename: formatPath,
-		isTwine2: true,
-		name: data.name,
-		version: data.version,
-		proofing: data.proofing ?? false
-	};
+/** Whether the text loaded as StoryData. Text that did not is kept as written, for the author to fix. */
+function isStoryDataJSON(text) {
+	return unmarshalStoryData(createStory(), text) === null;
 }
+//#endregion
+//#region src/modules.ts
 /**
-* Try to resolve a remote story format by name and version.
-* 1. Try direct format URLs
-* 2. Try custom index URLs
-* 3. Try default SFA indices
+* Load modules and return HTML tags to inject before </head>.
 */
-async function resolveRemoteFormat(name, version, indices, urls) {
-	let lastError;
-	if (urls) for (const url of urls) try {
-		const info = await fetchDirectFormat(url);
-		if (info.name.toLowerCase() === name.toLowerCase()) {
-			const wanted = parseSemver(version);
-			const have = parseSemver(info.version);
-			if (!wanted || have && have[0] === wanted[0] && semverCompare(have, wanted) >= 0) return info;
-		}
-	} catch (e) {
-		lastError = e instanceof Error ? e : new Error(String(e));
-	}
-	const allIndices = [...indices ?? [], ...DEFAULT_SFA_INDICES];
-	for (const indexUrl of allIndices) try {
-		const result = findEntry(await fetchIndex(indexUrl), name, version);
-		if (result) {
-			const cached = getCachedFormat(result.entry.name, result.entry.version);
-			if (cached) return cached;
-			const downloadUrl = getDownloadUrl(indexUrl, result.entry, result.formatType);
-			return await fetchAndCacheFormat(result.entry, downloadUrl);
-		}
-	} catch (e) {
-		lastError = e instanceof Error ? e : new Error(String(e));
-	}
-	if (lastError) throw lastError;
-}
-/** Check if a format is already in the local cache. */
-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 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
-		};
-	} catch {
-		return;
-	}
-}
-/** Discover all cached remote formats. Returns a Map like discoverFormats(). */
-function discoverCachedFormats() {
-	const formats = /* @__PURE__ */ new Map();
-	const cacheDir = getCacheDir();
-	try {
-		if (!existsSync(cacheDir)) return formats;
-	} catch {
-		return formats;
-	}
-	let names;
-	try {
-		names = readdirSync(cacheDir);
-	} catch {
-		return formats;
-	}
-	for (const name of names) {
-		const nameDir = join(cacheDir, name);
-		try {
-			if (!statSync(nameDir).isDirectory()) continue;
-		} catch {
-			continue;
-		}
-		let versions;
-		try {
-			versions = readdirSync(nameDir);
-		} catch {
-			continue;
-		}
-		for (const version of versions) {
-			const info = getCachedFormat(name, version);
-			if (info) formats.set(`${info.id}-${version}`, info);
-		}
-	}
-	return formats;
-}
-/** List all cached formats with size and modification date. */
-function listCachedFormats() {
-	const cacheDir = getCacheDir();
-	const entries = [];
-	try {
-		if (!existsSync(cacheDir)) return entries;
-	} catch {
-		return entries;
-	}
-	let names;
-	try {
-		names = readdirSync(cacheDir);
-	} catch {
-		return entries;
-	}
-	for (const name of names) {
-		const nameDir = join(cacheDir, name);
-		try {
-			if (!statSync(nameDir).isDirectory()) continue;
-		} catch {
-			continue;
-		}
-		let versions;
-		try {
-			versions = readdirSync(nameDir);
-		} catch {
-			continue;
-		}
-		for (const version of versions) {
-			const formatPath = join(nameDir, version, "format.js");
-			try {
-				const stat = statSync(formatPath);
-				entries.push({
-					name,
-					version,
-					sizeBytes: stat.size,
-					modifiedAt: stat.mtime
-				});
-			} catch {}
+function loadModules(filenames) {
+	const processed = /* @__PURE__ */ new Set();
+	const headTags = [];
+	for (const filename of filenames) {
+		if (processed.has(filename)) continue;
+		const ext = normalizedFileExt(filename);
+		let tag = null;
+		switch (ext) {
+			case "css":
+				tag = loadModuleTagged("style", filename);
+				break;
+			case "js":
+				tag = loadModuleTagged("script", filename);
+				break;
+			case "otf":
+			case "ttf":
+			case "woff":
+			case "woff2":
+				tag = loadModuleFont(filename);
+				break;
+			default: continue;
 		}
+		if (tag) headTags.push(tag);
+		processed.add(filename);
 	}
-	return entries;
+	return headTags.join("\n");
 }
-/** Clear all cached formats, or only those matching a given name. Returns the number of entries removed. */
-function clearCachedFormats(name) {
-	const cacheDir = getCacheDir();
-	if (!existsSync(cacheDir)) return 0;
-	if (!name) {
-		const count = listCachedFormats().length;
-		rmSync(cacheDir, {
-			recursive: true,
-			force: true
+function loadModuleTagged(tag, filename) {
+	const source = readUTF8(filename).trim();
+	if (source.length === 0) return null;
+	return `<${tag} id="${`${tag}-module-${slugify(baseNameWithoutExt(filename))}`}" type="${tag === "script" ? "text/javascript" : "text/css"}">${tag === "script" ? scriptContentEscape(source) : styleContentEscape(source)}</${tag}>`;
+}
+function loadModuleFont(filename) {
+	const source = readBase64(filename);
+	const family = baseNameWithoutExt(filename);
+	const idSlug = `style-module-${slugify(family)}`;
+	const ext = normalizedFileExt(filename);
+	return `<style id="${idSlug}" type="text/css">@font-face {\n\tfont-family: "${family}";\n\tsrc: url("data:${mediaTypeFromExt(ext)};base64,${source}") format("${fontFormatHint(ext)}");\n}</style>`;
+}
+/**
+* Inject modules and head file content before </head>.
+*/
+function modifyHead(html, modulePaths, headFile, diagnostics) {
+	const parts = [];
+	if (modulePaths.length > 0) {
+		const modules = loadModules(modulePaths).trim();
+		if (modules.length > 0) parts.push(modules);
+	}
+	if (headFile) try {
+		const source = readUTF8(headFile).trim();
+		if (source.length > 0) parts.push(source);
+	} catch (e) {
+		diagnostics?.push({
+			level: "warning",
+			message: `Failed to read head file "${headFile}": ${e instanceof Error ? e.message : String(e)}`
 		});
-		return count;
 	}
-	const nameDir = join(cacheDir, name);
-	if (!existsSync(nameDir)) return 0;
-	let versions;
-	try {
-		versions = readdirSync(nameDir);
-	} catch {
-		return 0;
+	if (parts.length > 0) {
+		parts.push("</head>");
+		const replacement = parts.join("\n");
+		return html.replace("</head>", () => replacement);
 	}
-	const count = versions.length;
-	rmSync(nameDir, {
-		recursive: true,
-		force: true
-	});
-	return count;
+	return html;
 }
-/** Get total cache size in bytes and format count. */
-function getCacheSize() {
-	const entries = listCachedFormats();
-	return {
-		totalBytes: entries.reduce((sum, e) => sum + e.sizeBytes, 0),
-		count: entries.length
-	};
+//#endregion
+//#region src/passage-omission.ts
+/**
+* Why the `target` output leaves `passage` out of its passage elements, or `undefined` when it
+* emits the passage (and so a link or the start can name it).
+*/
+function passageOmission(story, passage, target) {
+	switch (target) {
+		case "twine2": return twine2PassageOmission(story, passage);
+		case "twine1": return twine1PassageOmission(passage);
+		default: throw new Error(`unhandled passage output target: ${String(target)}`);
+	}
+}
+/** Why a passage is left out, as a predicate: `Passage "X" ${describeOmission(o)}`. */
+function describeOmission(omission) {
+	switch (omission.kind) {
+		case "special-name": return `is the special "${omission.name}" passage`;
+		case "tag": return `is tagged "${omission.tag}"`;
+		case "empty-story-settings": return "is an empty \"StorySettings\" passage";
+		default: throw new Error(`unhandled passage omission: ${JSON.stringify(omission)}`);
+	}
+}
+//#endregion
+//#region src/start-passage.ts
+/**
+* Check that `startName` names a passage the `target` output emits.
+* Returns the error diagnostics to report (empty when the start is usable).
+*/
+function startPassageDiagnostics(story, startName, target) {
+	const passage = story.passages.find((p) => p.name === startName);
+	if (passage === void 0) return [{
+		level: "error",
+		message: `Starting passage "${startName}" not found.`
+	}];
+	const omission = passageOmission(story, passage, target);
+	if (omission === void 0) return [];
+	return [{
+		level: "error",
+		message: `Starting passage "${startName}" ${describeOmission(omission)}, so it is left out of the story data. Choose a story passage.`
+	}];
 }
 //#endregion
 //#region src/compiler.ts
@@ -5110,38 +5508,44 @@ var TweeTsError = class extends Error {
 	}
 };
 /**
-* Compile Twee sources to HTML, Twee, or JSON.
-*/
-async function compile(options) {
-	return buildOutput(options);
-}
-/**
-* Compile and write to a file.
+* Builds as compileToFile() does for `outFile`, without writing it: the 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().
+*
+* Internal, for the CLI; not part of the public API.
 */
-async function compileToFile(options) {
-	const result = await compile(options);
-	writeFileSync(options.outFile, result.output, "utf-8");
-	return result;
+async function compileForOutputFile(options, outFile) {
+	return buildOutput(options, void 0, void 0, outFile);
 }
 /**
-* Watch for file changes and recompile.
+* watch(), writing to `outFile` only the builds `shouldWrite` accepts. A rejected build
+* leaves the output file as it was; `onBuild` receives every build either way.
+*
+* Internal, for the CLI, which keeps the last good output when a rebuild reports errors;
+* not part of the public API.
 */
-async function watch$1(options) {
+async function watchWithWriteFilter(options, shouldWrite) {
 	const controller = new AbortController();
 	const cache = /* @__PURE__ */ new Map();
 	const filePaths = options.sources.filter((s) => typeof s === "string");
 	const modulePaths = options.modules ?? [];
-	const allPaths = [...filePaths, ...modulePaths];
+	const headPaths = options.headFile ? [options.headFile] : [];
+	const allPaths = [
+		...filePaths,
+		...modulePaths,
+		...headPaths
+	];
 	const exclude = options.exclude ?? [];
-	const moduleRoots = modulePaths.map((p) => resolve(p));
+	const notExcludable = [...modulePaths, ...headPaths].map((p) => resolve(p));
 	const ignore = (filename) => {
 		if (!isExcluded(filename, exclude)) return false;
 		const abs = resolve(filename);
-		return !moduleRoots.some((root) => abs === root || abs.startsWith(root + sep));
+		return !notExcludable.some((root) => abs === root || abs.startsWith(root + sep));
 	};
 	const handle = watchFilesystem(allPaths, options.outFile, (changedFiles) => {
-		buildOutput(options, cache, changedFiles).then((result) => {
-			writeFileSync(options.outFile, result.output, "utf-8");
+		buildOutput(options, cache, changedFiles, options.outFile).then((result) => {
+			if (shouldWrite(result)) writeFileSync(options.outFile, result.output, "utf-8");
 			options.onBuild?.(result);
 		}).catch((e) => {
 			options.onError?.(e instanceof Error ? e : new Error(String(e)));
@@ -5150,7 +5554,11 @@ async function watch$1(options) {
 	controller.signal.addEventListener("abort", () => handle.close());
 	return controller;
 }
-async function buildOutput(options, cache, changedFiles) {
+/**
+* `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.
+*/
+async function buildOutput(options, cache, changedFiles, outFile) {
 	const diagnostics = [];
 	const outputMode = options.outputMode ?? "html";
 	const trim = options.trim ?? true;
@@ -5163,7 +5571,7 @@ async function buildOutput(options, cache, changedFiles) {
 	const inlineSources = [];
 	for (const source of options.sources) if (typeof source === "string") filePaths.push(source);
 	else inlineSources.push(source);
-	const { filenames: sourceFilenames, diagnostics: sourcePathDiagnostics } = getFilenames(filePaths, void 0, options.exclude);
+	const { filenames: sourceFilenames, diagnostics: sourcePathDiagnostics } = getFilenames(filePaths, outFile, options.exclude);
 	diagnostics.push(...sourcePathDiagnostics);
 	const story = createStory();
 	const processedFiles = /* @__PURE__ */ new Set();
@@ -5181,40 +5589,19 @@ async function buildOutput(options, cache, changedFiles) {
 	}, diagnostics);
 	if (options.tagAliases) story.passages = applyTagAliases(story.passages, options.tagAliases);
 	let format;
-	let formatId = options.formatId ?? "";
-	if (outputMode === "html") {
-		const formats = discoverFormats(getFormatSearchDirs(options.formatPaths, options.useTweegoPath ?? true));
-		if (!formatId && story.twine2.format) formatId = getFormatIdByNameAndVersion(formats, story.twine2.format, story.twine2.formatVersion) ?? "";
-		if (!formatId) formatId = DEFAULT_FORMAT_ID;
-		format = formats.get(formatId);
-		if (!format && !noRemote) {
-			const remoteName = story.twine2.format || formatId;
-			const remoteVersion = story.twine2.formatVersion || "";
-			try {
-				format = await resolveRemoteFormat(remoteName, remoteVersion, options.formatIndices, options.formatUrls);
-			} catch (e) {
-				diagnostics.push({
-					level: "warning",
-					message: `Remote format fetch failed for "${remoteName}": ${e instanceof Error ? e.message : String(e)}`
-				});
-			}
-		}
-		if (!format) {
-			const reason = noRemote ? " (remote fetching disabled)" : "";
-			diagnostics.push({
-				level: "error",
-				message: `Story format "${formatId}" is not available${reason}. Found: ${[...formats.keys()].join(", ") || "none"}`
-			});
-		}
-	}
-	const startName = options.startPassage || story.twine2.start || DEFAULT_START_NAME;
+	if (outputMode === "html") format = await resolveStoryFormat(formatRequestFor(options.formatId, story.twine2.format, story.twine2.formatVersion, DEFAULT_FORMAT_ID), {
+		...options,
+		noRemote
+	}, diagnostics);
+	if (options.startPassage) story.twine2.start = options.startPassage;
+	const startName = story.twine2.start || DEFAULT_START_NAME;
 	if (testMode) story.twine2.options.set("debug", true);
 	ensureIFID(story, diagnostics);
 	let output;
 	switch (outputMode) {
 		case "twee3":
 		case "twee1":
-			output = toTwee(story, outputMode);
+			output = toTwee(story, outputMode, { addStoryData: Boolean(options.startPassage) || testMode });
 			break;
 		case "twine2-archive":
 			output = toTwine2Archive(story, startName, { sourceInfo });
@@ -5226,10 +5613,7 @@ async function buildOutput(options, cache, changedFiles) {
 			output = storyToJSON(story);
 			break;
 		case "html": {
-			if (!storyHas(story, startName)) diagnostics.push({
-				level: "error",
-				message: `Starting passage "${startName}" not found.`
-			});
+			diagnostics.push(...startPassageDiagnostics(story, startName, format?.isTwine2 === false ? "twine1" : "twine2"));
 			if (!format) throw new TweeTsError("No story format available for HTML output.", diagnostics);
 			if (format.isTwine2) output = toTwine2HTML(story, format, startName, { sourceInfo });
 			else {
@@ -5239,7 +5623,7 @@ async function buildOutput(options, cache, changedFiles) {
 				});
 				output = toTwine1HTML(story, format, startName);
 			}
-			const modules = getFilenames(options.modules ?? []);
+			const modules = getFilenames(options.modules ?? [], outFile);
 			diagnostics.push(...modules.diagnostics);
 			output = modifyHead(output, modules.filenames, options.headFile, diagnostics);
 			break;
@@ -5659,19 +6043,237 @@ function endOfRegularExpression(source, pos) {
 	};
 }
 //#endregion
+//#region src/link-markup.ts
+/** Records that the reading has looked at the characters before `pos`, and returns `result`. */
+function readTo(reader, pos, result) {
+	reader.scanned = Math.max(reader.scanned, pos);
+	return result;
+}
+/**
+* Reads link or image markup that starts at `start` in `text`, or returns `undefined` where
+* SugarCube rejects it (and so prints the text instead).
+*
+* `budget.left`, if given, is how many characters the reading may look at; it is reduced by as
+* many as were read, and once it runs out, every reading fails. Unclosed markup is read to the end
+* of its line, so reading every `[[` of a long line that never closes one would otherwise take
+* quadratic time. A reading is charged for the characters it looked at, up to where it ended or
+* failed (a line feed, say), and no more, so markup left unclosed on short lines costs little.
+*/
+function readSquareBracketedMarkup(text, start, budget = { left: Infinity }) {
+	const reader = {
+		text,
+		limit: Math.min(text.length, start + Math.max(budget.left, 0)),
+		scanned: start
+	};
+	const markup = readMarkup(reader, start);
+	budget.left -= Math.max(reader.scanned, markup?.end ?? start) - start;
+	return markup;
+}
+function readMarkup(reader, start) {
+	const { text } = reader;
+	if (text[start] !== "[") return;
+	let pos = start + 1;
+	let type;
+	if (text[pos] === "[") {
+		type = "link";
+		pos += 1;
+	} else {
+		if (text[pos] === "<" || text[pos] === ">") pos += 1;
+		if (!/^[Ii][Mm][Gg]\[/.test(text.slice(pos, pos + 4))) return;
+		type = "image";
+		pos += 4;
+	}
+	const core = readCoreComponents(reader, pos);
+	if (core === void 0) return;
+	if (type === "link") {
+		if (!core.end.last) {
+			const setterEnd = readSetter(reader, core.end.next);
+			if (setterEnd === void 0) return;
+			return {
+				type,
+				link: linkName(core.link),
+				end: setterEnd
+			};
+		}
+		return {
+			type,
+			link: linkName(core.link),
+			end: core.end.next
+		};
+	}
+	if (core.end.last) return {
+		type,
+		link: void 0,
+		end: core.end.next
+	};
+	const linkEnd = readComponent(reader, core.end.next, false);
+	if (linkEnd === void 0) return;
+	const link = linkName(text.slice(core.end.next, linkEnd.textEnd));
+	if (linkEnd.last) return {
+		type,
+		link,
+		end: linkEnd.next
+	};
+	const setterEnd = readSetter(reader, linkEnd.next);
+	return setterEnd === void 0 ? void 0 : {
+		type,
+		link,
+		end: setterEnd
+	};
+}
+/** The link component as SugarCube keeps it: trimmed, and without a leading `~`. */
+function linkName(component) {
+	const trimmed = component.trim();
+	return trimmed.startsWith("~") ? trimmed.slice(1) : trimmed;
+}
+/**
+* Reads the first components: the text and the link of link markup, or the title and the source
+* of image markup, divided by the first delimiter. `link` is the text of the link (or source)
+* component, untrimmed.
+*/
+function readCoreComponents(reader, from) {
+	const { text } = reader;
+	let delimiter = "none";
+	let componentStart = from;
+	let link;
+	let depth = 2;
+	let pos = from;
+	while (pos < reader.limit) {
+		const ch = text[pos];
+		pos += 1;
+		switch (ch) {
+			case "\n": return readTo(reader, pos, void 0);
+			case "\"": {
+				const end = readQuoted(reader, pos, "\"");
+				if (end === void 0) return;
+				pos = end;
+				break;
+			}
+			case "|":
+				if (delimiter === "none") {
+					delimiter = "ltr";
+					componentStart = pos;
+				}
+				break;
+			case "-":
+				if (delimiter === "none" && text[pos] === ">") {
+					delimiter = "ltr";
+					pos += 1;
+					componentStart = pos;
+				}
+				break;
+			case "<":
+				if (delimiter === "none" && text[pos] === "-") {
+					delimiter = "rtl";
+					link = text.slice(componentStart, pos - 1);
+					pos += 1;
+					componentStart = pos;
+				}
+				break;
+			case "[":
+				depth += 1;
+				break;
+			case "]":
+				depth -= 1;
+				if (depth === 1) {
+					const end = componentEnd(reader, pos);
+					if (end === void 0) return;
+					return {
+						link: link ?? text.slice(componentStart, end.textEnd),
+						end
+					};
+				}
+		}
+	}
+	return readTo(reader, pos, void 0);
+}
+/**
+* Reads a component after `][` that holds no delimiter: an image's link (`setter` false) or a
+* setter, in which single quotes also quote.
+*/
+function readComponent(reader, from, setter) {
+	const { text } = reader;
+	let depth = 2;
+	let pos = from;
+	while (pos < reader.limit) {
+		const ch = text[pos];
+		pos += 1;
+		switch (ch) {
+			case "\n": return readTo(reader, pos, void 0);
+			case "\"":
+			case "'": {
+				if (ch === "'" && !setter) break;
+				const end = readQuoted(reader, pos, ch);
+				if (end === void 0) return;
+				pos = end;
+				break;
+			}
+			case "[":
+				depth += 1;
+				break;
+			case "]":
+				depth -= 1;
+				if (depth === 1) return componentEnd(reader, pos);
+		}
+	}
+	return readTo(reader, pos, void 0);
+}
+/** Reads a setter, the last component; returns the index after its closing `]]`. */
+function readSetter(reader, from) {
+	const end = readComponent(reader, from, true);
+	return end?.last === true ? end.next : void 0;
+}
+/** What the `]` just before `pos`, which brings the depth back to one, ends; `undefined` if malformed. */
+function componentEnd(reader, pos) {
+	switch (reader.text[pos]) {
+		case "[": return readTo(reader, pos + 1, {
+			textEnd: pos - 1,
+			next: pos + 1,
+			last: false
+		});
+		case "]": return readTo(reader, pos + 1, {
+			textEnd: pos - 1,
+			next: pos + 1,
+			last: true
+		});
+		default: return readTo(reader, pos + 1, void 0);
+	}
+}
+/**
+* Reads a quoted string from just after its opening quote; a backslash escapes the character
+* after it. A line feed, or the end of the text, ends it unterminated. Returns the index after the
+* closing quote.
+*/
+function readQuoted(reader, from, quote) {
+	const { text } = reader;
+	let pos = from;
+	while (pos < reader.limit) {
+		const ch = text[pos];
+		pos += 1;
+		if (ch === quote) return pos;
+		if (ch === "\n") return readTo(reader, pos, void 0);
+		if (ch === "\\") {
+			if (pos >= reader.limit || text[pos] === "\n") return readTo(reader, Math.min(pos + 1, reader.limit), void 0);
+			pos += 1;
+		}
+	}
+	return readTo(reader, pos, void 0);
+}
+//#endregion
 //#region src/sugarcube-macros.ts
 /**
-* Reads SugarCube 2 macro calls the way SugarCube 2.37.3 does, so the link check sees the same
-* passage names that `<<link>>` and `<<goto>>` use when the story plays.
+* Reads SugarCube 2 macro calls and link markup the way SugarCube 2.37.3 does, so the link check
+* sees the same passage names that `[[…]]` links, `<<link>>` and `<<goto>>` use when the story
+* plays.
 *
 * Each step follows a part of SugarCube's macro parser:
 * - `findMacroTags` finds where a tag starts and ends (the parser's `lookahead` pattern);
 * - `parseMacroArgs` splits the text after the macro name into arguments (`parseArgs`);
 * - quoted arguments are evaluated as strict-mode JavaScript strings (`evalStringLiteral`).
 *
+* Link and image markup is read as `parseSquareBracketedMarkup` reads it (see `link-markup.ts`).
 * Of the rest of the wikifier, only comments, `<script>` elements and `<<script>>` bodies are
-* told apart; other markup, such as verbatim text, is read as markup (see
-* `findMacroPassageLinks`).
+* told apart; other markup, such as verbatim text, is read as markup (see `findPassageLinks`).
 */
 const NAME_RE = /\/?[A-Za-z][\w-]*|[=-]/y;
 const SPACES_RE = /\s*/y;
@@ -5716,17 +6318,22 @@ const RAW_ARGUMENT_MACROS = /* @__PURE__ */ new Set([
 * levels; the limit keeps the work linear in the size of the text on any input.
 */
 const MAX_STRING_DEPTH = 10;
-/** A context for reading `text`: the closer search may read four times it, plus an allowance. */
+/**
+* A context for reading `text`: the closer search, and the markup reading, may each read four
+* times it, plus an allowance.
+*/
 function readContext(text) {
+	const allowance = () => ({ left: 4 * text.length + 1e5 });
 	return {
 		depth: 0,
-		budget: { left: 4 * text.length + 1e5 }
+		budget: allowance(),
+		markupBudget: allowance()
 	};
 }
 function deeper(context) {
 	return {
-		depth: context.depth + 1,
-		budget: context.budget
+		...context,
+		depth: context.depth + 1
 	};
 }
 /** Index of the first match of a global `re` at or after `from`, or -1. */
@@ -5956,7 +6563,10 @@ function lexArgument(raw, pos) {
 		case "[": {
 			const end = lexSquareBracketed(raw, pos + 1);
 			return end === void 0 ? void 0 : {
-				arg: { kind: "markup" },
+				arg: {
+					kind: "markup",
+					text: raw.slice(pos, end)
+				},
 				end
 			};
 		}
@@ -6100,13 +6710,44 @@ function ownPassageLink(tag, lexed) {
 	const arg = passageArgument(tag.name, lexed);
 	const passage = arg === void 0 ? void 0 : passageName(arg);
 	return passage === void 0 ? void 0 : {
-		macro: tag.name,
+		via: tag.name,
 		passage
 	};
 }
 /**
-* The passages a tag names: its own, if it is a `<<link>>` or `<<goto>>` call, then those of the
-* calls inside the strings of its arguments, which the macro may print or pass on
+* The passage a link's destination names. SugarCube evaluates a destination that no passage is
+* named by, and a quoted string gives its value (`[[Go|"Room"]]`), unless that is blank.
+*/
+function linkDestination(link) {
+	const value = evalStringLiteral(link);
+	return value === void 0 || value.trim() === "" ? link : value;
+}
+/**
+* The passage that link markup from `start` in `text` names, and where the markup ends, or
+* `undefined` where SugarCube rejects the markup. Image markup names none here, nor does markup
+* with a template literal's `${…}` in it, whose passage is known only in play.
+*/
+function linkMarkupAt(text, start, budget) {
+	const markup = readSquareBracketedMarkup(text, start, budget);
+	if (markup === void 0) return;
+	const passage = markup.type === "link" && !text.slice(start, markup.end).includes("﷐") ? markup.link : void 0;
+	return {
+		link: passage === void 0 ? void 0 : {
+			via: "markup",
+			passage: linkDestination(passage)
+		},
+		end: markup.end
+	};
+}
+/** The passage that a link markup argument names, if SugarCube reads the whole argument as markup. */
+function markupArgumentLinks(raw) {
+	const markup = linkMarkupAt(raw, 0);
+	return markup?.link === void 0 || markup.end !== raw.length ? [] : [markup.link];
+}
+/**
+* The passages a tag names: its own, if it is a `<<link>>` or `<<goto>>` call, then those of its
+* link markup arguments (`<<button [[Go|Room]]>>`), and those of the links and calls inside the
+* strings of its arguments, which the macro may print or pass on
 * (`<<set _out to '<<link "Go" "Room">><</link>>'>>`). The arguments of the macros SugarCube
 * doesn't split are read as JavaScript; in others, a backquoted expression is.
 */
@@ -6119,7 +6760,7 @@ function tagPassageLinks(tag, context) {
 		switch (arg.kind) {
 			case "string": return markupPassageLinks(arg.value, deeper(context));
 			case "expression": return javaScriptPassageLinks(arg.code, context);
-			case "markup":
+			case "markup": return markupArgumentLinks(arg.text);
 			case "word": return [];
 			default: throw new Error(`unhandled macro argument: ${JSON.stringify(arg)}`);
 		}
@@ -6129,16 +6770,26 @@ function tagPassageLinks(tag, context) {
 /**
 * The passage named by a `<<link>>` or `<<goto>>` that appears unquoted inside another tag's
 * arguments, at `start`. SugarCube never sees such an outer "tag" when its `<<` lies in text it
-* reads as something else, such as link markup (`[[<<-- Back|Prev]]`); the call inside it then
-* runs. The call ends where the outer tag ends.
+* reads as something else, such as verbatim text (`{{{<<if}}}`); the call inside it then runs.
+* The call ends where the outer tag ends.
 */
 function innerPassageLink(matchTagAt, start) {
 	const inner = matchTagAt(start)?.tag;
 	const lexed = inner === void 0 ? void 0 : lexMacroArgs(inner.args);
 	return inner === void 0 || lexed === void 0 ? void 0 : ownPassageLink(inner, lexed);
 }
-const REGION_OPEN_RE = /\/\/|\/\*|\/%|<!--|<[Ss][Cc][Rr][Ii][Pp][Tt]/g;
+const REGION_OPEN_RE = /\[\[[^[]|\[[<>]?[Ii][Mm][Gg]\[|\/\/|\/\*|\/%|<!--|<[Ss][Cc][Rr][Ii][Pp][Tt]/g;
 const HAS_SCRIPT_OPEN_RE = /<[Ss][Cc][Rr][Ii][Pp][Tt]/;
+function regionKind(opener) {
+	if (opener.startsWith("[")) return "markup";
+	switch (opener) {
+		case "//":
+		case "/*":
+		case "/%":
+		case "<!--": return opener;
+		default: return "script";
+	}
+}
 const SCRIPT_CLOSE_RE = /<\/[Ss][Cc][Rr][Ii][Pp][Tt]>|[\r\u2028\u2029]/g;
 const COMMENT_CLOSE_RES = {
 	"/*": /\*\/|[\r\u2028\u2029]/g,
@@ -6292,22 +6943,31 @@ function append(links, more) {
 	for (const link of more) links.push(link);
 }
 /**
-* The passages that `<<link>>` and `<<goto>>` calls in passage markup name. Calls whose passage
-* is known only in play (a variable or an expression) are left out. A tag's own passage comes
-* before those of the calls inside its arguments' strings.
+* The passages that link markup (`[[…]]`) and `<<link>>` and `<<goto>>` calls in passage markup
+* name, in the order they come. Calls whose passage is known only in play (a variable or an
+* expression) are left out. A tag's own passage comes before those that its arguments name, as
+* link markup or inside strings.
 *
 * The markup is walked in order, as SugarCube's wikifier walks it, with a tag tried at each
-* `<<` the walk reaches. Of the wikifier's other parsers, only those whose text holds no call
-* are told apart: comments (`/* … *` + `/`, `/% … %/`, `<!-- … -->`), whose calls never run,
-* and `<script>` elements and `<<script>>` bodies, which are JavaScript: only the calls in their
-* strings are read (see `findJavaScriptPassageLinks`). Everything else, verbatim text included,
-* is read as markup.
+* `<<` the walk reaches, and link or image markup read at each `[[` or `[img[`; markup SugarCube
+* rejects is read on from just after its opener, and so is markup after a limit on how much
+* markup a reading may scan, which only input built to take quadratic time reaches (see
+* `readSquareBracketedMarkup`). Image markup names no passage here. Of the wikifier's other
+* parsers, only those whose text holds no link or call are told apart: comments (`/* … *` + `/`,
+* `/% … %/`, `<!-- … -->`), whose links and calls never run, and `<script>` elements and
+* `<<script>>` bodies, which are JavaScript: only the links and calls in their strings are read
+* (see `findJavaScriptPassageLinks`). Everything else, verbatim text included, is read as markup.
 *
 * Where this differs from SugarCube:
+* - a link whose passage SugarCube evaluates, because no passage has its name, is taken by its
+*   name, `[[Go|$next]]` naming the passage `$next`, unless it is a quoted string, which is taken
+*   by its value even when a passage has the name with the quotes;
+* - a link SugarCube takes for a URL, because no passage has its name and it looks like one or
+*   holds a `/`, `.`, `?` or `#`, is still read as naming a passage;
 * - a comment or a `<<script>>` body is skipped whole, even where `parseBody` ends a container
 *   such as `<<if>>` at a closing tag inside it and the rest then runs;
-* - a `/*`, `<!--` or `<script` inside other markup that holds no call, such as link markup or a
-*   `<style>` element, still starts a comment or an element;
+* - a `[[`, `/*`, `<!--` or `<script` inside other markup that holds no call, such as verbatim
+*   text or a `<style>` element, still starts link markup, a comment or an element;
 * - a `<<` in such other markup still starts a tag. When that tag runs over a `<<link` or
 *   `<<goto` outside the parts of its arguments that the tag pattern reads as units, that call
 *   is still read (see `innerPassageLink`), even where the tag's arguments would be JavaScript,
@@ -6322,33 +6982,43 @@ function append(links, more) {
 *   `Config.passages.nobr`, are not joined before they are read (see `storyInspect` for passages
 *   tagged `nobr`).
 */
-function findMacroPassageLinks(text) {
+function findPassageLinks(text) {
 	return markupPassageLinks(text, readContext(text));
 }
 function markupPassageLinks(text, context) {
-	if (context.depth > MAX_STRING_DEPTH || !text.includes("<<") && !HAS_SCRIPT_OPEN_RE.test(text)) return [];
+	if (context.depth > MAX_STRING_DEPTH || !text.includes("<<") && !text.includes("[[") && !HAS_SCRIPT_OPEN_RE.test(text)) return [];
 	const matchTagAt = tagMatcher(text);
 	const matchInnerTagAt = tagMatcher(text);
 	const readComment = commentReader(text);
 	const readScriptElement = scriptElementReader(text);
 	let findScriptCloser;
 	const links = [];
-	/** Reads the region `opener` opens, adding the calls in a `<script>` element; returns where the walk goes on. */
+	/**
+	* Reads the region `opener` opens, adding the passage that link markup names and the links and
+	* calls in a `<script>` element; returns where the walk goes on.
+	*/
 	const regionEnd = (opener) => {
 		const start = opener.index;
-		const kind = opener[0];
+		const kind = regionKind(opener[0]);
 		switch (kind) {
+			case "markup": {
+				const markup = linkMarkupAt(text, start, context.markupBudget);
+				if (markup === void 0) return start + opener[0].length;
+				if (markup.link !== void 0) links.push(markup.link);
+				return markup.end;
+			}
 			case "//": return start + 2;
 			case "/*":
 			case "/%":
 			case "<!--": return readComment(kind, start) ?? start + kind.length;
-			default: {
+			case "script": {
 				const element = readScriptElement(start);
 				if (element.openerEnd === void 0) return start + 1;
 				if (element.close === void 0) return element.openerEnd;
 				append(links, javaScriptPassageLinks(text.slice(element.openerEnd, element.close), context));
 				return element.close + 9;
 			}
+			default: throw new Error(`unhandled region: ${String(kind)}`);
 		}
 	};
 	let macro = -2;
@@ -6388,24 +7058,26 @@ function markupPassageLinks(text, context) {
 	}
 }
 /**
-* The passages that `<<link>>` and `<<goto>>` calls in the strings of JavaScript source name,
-* such as a script passage or a `<<script>>` body: `$.wiki('<<goto "Room">>')`. Code outside
-* the strings isn't markup, so a call put together while the story plays, such as
-* `'<<goto "' + target + '">>'`, names no passage here.
+* The passages that link markup and `<<link>>` and `<<goto>>` calls in the strings of JavaScript
+* source name, such as a script passage or a `<<script>>` body: `$.wiki('<<goto "Room">>')`.
+* Code outside the strings isn't markup, so a call put together while the story plays, such as
+* `'<<goto "' + target + '">>'`, names no passage here, nor does an array of arrays (`[[0, 1]]`).
 */
 function findJavaScriptPassageLinks(source) {
 	return javaScriptPassageLinks(source, readContext(source));
 }
 /**
 * What JavaScript source must contain for one of its string or template literals to hold a call
-* that is read. A value holding `<<`: each `<` in it is written as `<`, `\<`, `\x3c`, `\u003c` or
-* `\u{…}`, two can be next to each other with only line continuations between, and the first
-* is `<` or `\<` (then the source holds `<<` or `<\`) or one of the others. Or a value holding a
-* `<script>` element, whose own strings can make `<<` from escapes the outer string encodes.
+* or link markup that is read. A value holding `<<`: each `<` in it is written as `<`, `\<`,
+* `\x3c`, `\u003c` or `\u{…}`, two can be next to each other with only line continuations
+* between, and the first is `<` or `\<` (then the source holds `<<` or `<\`) or one of the others.
+* A value holding `[[`, likewise: the source holds `[[`, a `[` before `\[` or a line continuation,
+* `\x5b`, `\u005b` or `\u{`. Or a value holding a `<script>` element, whose own strings can make
+* `<<` or `[[` from escapes the outer string encodes.
 */
-const MAY_HOLD_MACRO_RE = /<<|<\\|\\x3c|\\u003c|\\u\{|<script/i;
+const MAY_HOLD_LINK_RE = /<<|<\\|\\x3c|\\u003c|\\u\{|<script|\[\[|\[\\[[\n\r\u2028\u2029]|\\x5b|\\u005b/i;
 function javaScriptPassageLinks(source, context) {
-	if (context.depth >= MAX_STRING_DEPTH || !MAY_HOLD_MACRO_RE.test(source)) return [];
+	if (context.depth >= MAX_STRING_DEPTH || !MAY_HOLD_LINK_RE.test(source)) return [];
 	const inner = deeper(context);
 	const links = [];
 	for (const value of javaScriptStrings(source)) append(links, markupPassageLinks(value, inner));
@@ -6414,43 +7086,57 @@ function javaScriptPassageLinks(source, context) {
 //#endregion
 //#region src/inspect.ts
 /**
-* Extract all [[wiki-style links]] from passage text.
+* Extract the passages that passage text links to, read as SugarCube 2 reads them.
 *
 * Supported syntaxes:
 * - `[[PassageName]]`
-* - `[[Display Text->PassageName]]`  (Twine 2 / SugarCube arrow)
-* - `[[Display Text|PassageName]]`   (Twine 1 / Harlowe pipe)
-* - `<<goto "PassageName">>`         (SugarCube macro)
+* - `[[Display Text|PassageName]]`
+* - `[[Display Text->PassageName]]`
+* - `[[PassageName<-Display Text]]`
+* - any of those with a setter: `[[Display Text|PassageName][$x to 1]]`
+* - `<<goto "PassageName">>`            (SugarCube macro)
 * - `<<link "Display" "PassageName">>`  (SugarCube macro)
 *
-* SugarCube macro arguments may be double- or single-quoted, with backslash escapes, or bare
-* words; a passage named by a variable or an expression is known only in play and is skipped.
-* Macro calls are also read inside the quoted strings of other macros' arguments, and inside the
-* strings of `<<script>>` bodies and `<script>` elements; calls in comments are not read. A
-* script passage (`isScript`) is JavaScript, so its macro calls are read only inside its strings.
-* See `sugarcube-macros.ts` for the details and the known differences from SugarCube.
+* In link markup, the first `|`, `->` or `<-` divides the text from the passage name; image
+* markup (`[img[…][PassageName]]`) is not read. SugarCube macro arguments may be double- or
+* single-quoted, with backslash escapes, or bare words; a passage named by a variable or an
+* expression is known only in play and is skipped. Links and macro calls are also read inside the
+* quoted strings of macros' arguments, and inside the strings of `<<script>>` bodies and
+* `<script>` elements; links and calls in comments are not read. A script passage (`isScript`) is
+* JavaScript, so its links and calls are read only inside its strings. See `sugarcube-macros.ts`
+* for the details and the known differences from SugarCube.
 */
 function extractLinksFromText(text, isScript) {
-	const targets = /* @__PURE__ */ new Set();
-	const wikiLinkRe = /\[\[([^\]]+)\]\]/g;
-	let m;
-	while ((m = wikiLinkRe.exec(text)) !== null) {
-		const content = m[1];
-		const arrowIdx = content.indexOf("->");
-		if (arrowIdx !== -1) {
-			targets.add(content.slice(arrowIdx + 2).trim());
-			continue;
-		}
-		const pipeIdx = content.indexOf("|");
-		if (pipeIdx !== -1) {
-			targets.add(content.slice(pipeIdx + 1).trim());
-			continue;
-		}
-		targets.add(content.trim());
+	const found = isScript ? findJavaScriptPassageLinks(text) : findPassageLinks(text);
+	const ordered = [
+		"markup",
+		"goto",
+		"link"
+	].flatMap((via) => found.filter((link) => link.via === via).map((link) => link.passage));
+	return [...new Set(ordered)];
+}
+/**
+* The passages that `p` links to. A script passage is JavaScript, read for links only in its
+* strings. A stylesheet is CSS, which the story puts in a style element and never wikifies, so it
+* links nowhere; a passage tagged both is a script, as Twine 2 output takes it.
+*/
+function passageLinks(p) {
+	if (hasTag(p, "script")) return extractLinksFromText(textAsRead(p), true);
+	if (hasTag(p, "stylesheet")) return [];
+	return extractLinksFromText(textAsRead(p), false);
+}
+/**
+* Each passage name, mapped to why the `target` output leaves that passage out, or to `undefined`
+* when a link can reach it: always without a target, and otherwise when the output emits a
+* passage of that name.
+*/
+function destinationOmissions(story, { target }) {
+	const omissions = /* @__PURE__ */ new Map();
+	for (const p of story.passages) {
+		const omission = target === void 0 ? void 0 : passageOmission(story, p, target);
+		if (!omissions.has(p.name) || omission === void 0) omissions.set(p.name, omission);
 	}
-	const macroLinks = isScript ? findJavaScriptPassageLinks(text) : findMacroPassageLinks(text);
-	for (const macro of ["goto", "link"]) for (const link of macroLinks) if (link.macro === macro) targets.add(link.passage);
-	return [...targets];
+	return omissions;
 }
 /** Passages SugarCube runs from their raw text, never joining their lines. */
 const RAW_TEXT_PASSAGES = /* @__PURE__ */ new Set([
@@ -6493,9 +7179,14 @@ function joinLines(text) {
 * expect(map.brokenLinks).toEqual([]);
 * expect(map.deadEnds).not.toContain('Start');
 * ```
+*
+* By default, a link is broken only when no passage has its name. Pass a `target` to check links
+* against what that output emits: `storyInspect(result.story, { target: 'twine2' })` also reports
+* links to passages Twine 2 output leaves out, such as script, stylesheet and `Twine.private`
+* passages.
 */
-function storyInspect(story) {
-	const allNames = new Set(story.passages.map((p) => p.name));
+function storyInspect(story, options = {}) {
+	const destinations = destinationOmissions(story, options);
 	const passages = [];
 	const storyPassages = [];
 	const infoPassages = [];
@@ -6517,14 +7208,24 @@ function storyInspect(story) {
 			}
 			list.push(p.name);
 		}
-		const targets = extractLinksFromText(textAsRead(p), hasTag(p, "script"));
-		links.set(p.name, targets);
+		links.set(p.name, passageLinks(p));
 	}
 	const brokenLinks = [];
-	for (const [from, targets] of links) for (const to of targets) if (!allNames.has(to)) brokenLinks.push({
-		from,
-		to
-	});
+	for (const [from, targets] of links) for (const to of targets) {
+		if (!destinations.has(to)) {
+			brokenLinks.push({
+				from,
+				to
+			});
+			continue;
+		}
+		const omission = destinations.get(to);
+		if (omission !== void 0) brokenLinks.push({
+			from,
+			to,
+			omission
+		});
+	}
 	const deadEnds = [];
 	for (const name of storyPassages) {
 		const targets = links.get(name);
@@ -6552,17 +7253,20 @@ function storyInspect(story) {
 //#endregion
 //#region src/lint.ts
 /**
-* Lint a story: compile without output rendering, then inspect structure.
-* Uses JSON output mode internally to avoid format resolution.
+* lint() for a project whose builds are written to `outFile`: like a build for that file,
+* it leaves `outFile` out of the sources and modules, so an earlier build inside a source
+* folder is not linted as a source.
+*
+* Internal, for the CLI; not part of the public API.
 */
-async function lint(options) {
-	const result = await compile({
+async function lintForOutputFile(options, outFile) {
+	const result = await compileForOutputFile({
 		...options,
 		outputMode: "json"
-	});
-	const map = storyInspect(result.story);
+	}, outFile);
+	const map = storyInspect(result.story, { target: "twine2" });
 	return {
-		diagnostics: result.diagnostics,
+		diagnostics: [...result.diagnostics, ...startPassageDiagnostics(result.story, map.start, "twine2")],
 		stats: result.stats,
 		formatName: result.story.twine2.format,
 		formatVersion: result.story.twine2.formatVersion,
@@ -6587,7 +7291,10 @@ function formatLintReport(result) {
 	if (result.brokenLinks.length > 0) {
 		lines.push("");
 		lines.push(`Broken links (${result.brokenLinks.length}):`);
-		for (const link of result.brokenLinks) lines.push(`  ${link.from} -> ${link.to} (passage "${link.to}" does not exist)`);
+		for (const link of result.brokenLinks) {
+			const why = link.omission === void 0 ? "does not exist" : `${describeOmission(link.omission)}, so it is left out of the story data`;
+			lines.push(`  ${link.from} -> ${link.to} (passage "${link.to}" ${why})`);
+		}
 	}
 	if (result.deadEnds.length > 0) {
 		lines.push("");
@@ -6870,8 +7577,10 @@ async function main() {
 		}
 		return raw;
 	})();
+	const outFile = values.output ?? config?.output ?? "-";
+	const outPath = outFile === "-" ? void 0 : outFile;
 	if (values.lint) {
-		const lintResult = await lint({
+		const lintResult = await lintForOutputFile({
 			sources,
 			exclude: values.exclude ?? config?.exclude,
 			formatId: values.format ?? config?.formatId,
@@ -6888,7 +7597,7 @@ async function main() {
 			tagAliases,
 			sourceInfo: values["source-info"] ?? config?.sourceInfo ?? false,
 			wordCountMethod
-		});
+		}, outPath);
 		console.log(formatLintReport(lintResult));
 		const hasErrors = lintResult.brokenLinks.length > 0 || lintResult.diagnostics.some((d) => d.level === "error");
 		process.exit(hasErrors ? 1 : 0);
@@ -6913,39 +7622,44 @@ async function main() {
 		sourceInfo: values["source-info"] ?? config?.sourceInfo ?? false,
 		wordCountMethod
 	};
-	const outFile = values.output ?? config?.output ?? "-";
 	if (values.watch) {
-		if (outFile === "-") {
+		if (outPath === void 0) {
 			console.error("Error: Watch mode requires an output file (-o).");
 			process.exit(1);
 		}
 		console.log("Watch mode started. Press CTRL+C to stop.");
-		await watch$1({
+		await watchWithWriteFilter({
 			...compileOptions,
-			outFile,
+			outFile: outPath,
 			onBuild(result) {
 				console.log(`Built: ${result.stats.passages} passages, ${result.stats.words} words`);
 				logDiagnostics(result.diagnostics);
+				const errors = countErrors(result.diagnostics);
+				if (errors > 0) console.error(`Build has ${pluralize(errors, "error")}; output not written. Still watching for changes.`);
 			},
 			onError(error) {
 				console.error(`Build error: ${error.message}`);
 			}
-		});
-	} else if (outFile === "-") {
-		const result = await compile(compileOptions);
-		process.stdout.write(result.output);
-		logDiagnostics(result.diagnostics);
-		if (values["log-stats"]) logStats(result);
+		}, (result) => countErrors(result.diagnostics) === 0);
 	} else {
-		const result = await compileToFile({
-			...compileOptions,
-			outFile
-		});
+		const result = await compileForOutputFile(compileOptions, outPath);
 		logDiagnostics(result.diagnostics);
-		if (values["log-files"]) console.log(`\nFiles: ${result.stats.files.join(", ")}`);
+		const errors = countErrors(result.diagnostics);
+		if (errors > 0) {
+			console.error(`Compilation failed with ${pluralize(errors, "error")}; output not written.`);
+			process.exitCode = 1;
+		} else if (outPath === void 0) process.stdout.write(result.output);
+		else writeFileSync(outPath, result.output, "utf-8");
+		if (outPath !== void 0 && values["log-files"]) console.log(`\nFiles: ${result.stats.files.join(", ")}`);
 		if (values["log-stats"]) logStats(result);
 	}
 }
+function countErrors(diagnostics) {
+	return diagnostics.filter((d) => d.level === "error").length;
+}
+function pluralize(count, noun) {
+	return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
 function listFormats() {
 	const formats = discoverFormats(getFormatSearchDirs());
 	console.log("Local story formats:");
@@ -6971,26 +7685,56 @@ function logStats(result) {
 	console.log(`  Words: ${s.words}`);
 	console.log(`  Files: ${s.files.length}`);
 }
-function runInit() {
-	console.log("Initializing new twee-ts project...");
-	mkdirSync("src", { recursive: true });
-	writeFileSync(join("src", "StoryData.tw"), `:: StoryData
+const SCAFFOLD_FILES = [
+	{
+		path: CONFIG_FILENAME,
+		content: scaffoldConfig
+	},
+	{
+		path: "src/StoryData.tw",
+		content: () => `:: StoryData
 {
 \t"ifid": "${crypto.randomUUID().toUpperCase()}"
 }
-`);
-	writeFileSync(join("src", "Start.tw"), `:: Start
+`
+	},
+	{
+		path: "src/Start.tw",
+		content: () => `:: Start
 Welcome to your new Twine story!
 
 This is the starting passage. Edit this file to begin writing your story.
-`);
-	if (!existsSync("twee-ts.config.json")) {
-		writeFileSync(CONFIG_FILENAME, scaffoldConfig());
-		console.log(`Created: ${CONFIG_FILENAME}`);
-	}
-	console.log("Created:");
-	console.log("  src/StoryData.tw");
-	console.log("  src/Start.tw");
+`
+	}
+];
+/**
+* Writes `content` to `path` unless the file already exists.
+* The exclusive flag makes the check and the write one step, so an existing file is never truncated.
+* Returns false when the file was already there.
+*/
+function writeNewFile(path, content) {
+	try {
+		writeFileSync(path, content, { flag: "wx" });
+		return true;
+	} catch (e) {
+		if (e instanceof Error && "code" in e && e.code === "EEXIST") return false;
+		throw new Error(`Cannot create ${path}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+	}
+}
+function runInit() {
+	console.log("Initializing new twee-ts project...");
+	mkdirSync("src", { recursive: true });
+	const results = SCAFFOLD_FILES.map((file) => ({
+		path: file.path,
+		created: writeNewFile(file.path, file.content())
+	}));
+	const created = results.filter((r) => r.created).map((r) => r.path);
+	const skipped = results.filter((r) => !r.created).map((r) => r.path);
+	if (created.length > 0) {
+		console.log("Created:");
+		for (const path of created) console.log(`  ${path}`);
+	}
+	for (const path of skipped) console.log(`Skipped (already exists): ${path}`);
 	console.log("\nRun: npx @rohal12/twee-ts");
 }
 function formatBytes(bytes) {