@rohal12/twee-ts 1.16.0 → 1.17.0

package/dist/{compiler-BiDNwR9q.js → diagnostics-DZNS7W41.js}

@@ -1,6 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import * as nodePath from "node:path";
-import { basename, dirname, extname, join, parse, relative, resolve } 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";
@@ -104,6 +104,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;
@@ -618,16 +673,25 @@ function getFilenames(pathnames, outFilename, exclude = []) {
 	};
 }
 //#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) {
@@ -657,16 +721,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;
@@ -689,16 +765,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;
 	}
 }
 /**
@@ -848,6 +921,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);
@@ -877,6 +998,321 @@ function readFormatSource(format) {
 	return source;
 }
 //#endregion
+//#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");
+}
+/**
+* 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;
+	}
+	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;
+}
+/** 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);
+}
+/** 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) : []
+	};
+}
+/** 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;
+}
+//#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,
@@ -1140,16 +1576,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({
@@ -3979,14 +4419,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
@@ -3994,7 +4436,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
@@ -4009,7 +4451,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"];
@@ -4030,6 +4472,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);
@@ -4038,8 +4481,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"],
@@ -4074,7 +4518,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);
@@ -4088,23 +4532,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;
@@ -4159,7 +4613,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);
@@ -4227,7 +4681,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 "":
@@ -4313,13 +4767,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":
@@ -4330,7 +4804,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":
@@ -4362,8 +4836,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);
 }
@@ -4399,8 +4873,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);
@@ -4412,7 +4889,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);
@@ -4423,6 +4900,7 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 			if (!result) continue;
 			cache.set(filename, {
 				mtimeMs,
+				parseOptionsKey: optionsKey,
 				passages: result.passages,
 				diagnostics: result.diagnostics
 			});
@@ -4486,11 +4964,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 = "";
@@ -4513,7 +5019,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) {
@@ -4525,7 +5031,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",
@@ -4539,8 +5045,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++;
@@ -4596,12 +5101,21 @@ function toTwine1HTML(story, format, startName) {
 	}
 	return template;
 }
+/**
+* Why Twine 1 output leaves a passage out of its tiddlers, or `undefined` when the passage is emitted.
+*/
+function twine1PassageOmission(p) {
+	return hasTag(p, "Twine.private") ? {
+		kind: "tag",
+		tag: "Twine.private"
+	} : void 0;
+}
 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;
+		if (twine1PassageOmission(p) !== void 0) continue;
 		count++;
 		data += passageToTiddler(p, count, obfuscateRot13);
 	}
@@ -4623,10 +5137,39 @@ function tryReplaceComponent(template, placeholder, componentPath, required) {
 }
 //#endregion
 //#region src/output-twee.ts
-function toTwee(story, outMode) {
-	let data = "";
-	for (const p of story.passages) data += passageToTwee(p, outMode);
-	return data;
+/**
+* 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 toTwee(story, outMode, options = {}) {
+	return withEffectiveStoryData(story, options.addStoryData ?? false).map((p) => passageToTwee(p, outMode)).join("");
+}
+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)
+	];
+}
+/** 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
@@ -4663,7 +5206,7 @@ function loadModules(filenames) {
 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}>`;
+	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);
@@ -4698,199 +5241,45 @@ function modifyHead(html, modulePaths, headFile, diagnostics) {
 	return html;
 }
 //#endregion
-//#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");
-}
-/** 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);
-}
-/** 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) : []
-	};
-}
-/** 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;
-}
+//#region src/passage-omission.ts
 /**
-* Find the best matching entry in an SFA index.
-* Exact version preferred, then highest version with same major.
+* 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 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
-				};
-			}
-		}
+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)}`);
 	}
-	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`;
 }
-/** 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}`);
+/** 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)}`);
 	}
-	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
-	};
-}
-/** 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
-	};
 }
+//#endregion
+//#region src/start-passage.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
+* Check that `startName` names a passage the `target` output emits.
+* Returns the error diagnostics to report (empty when the start is usable).
 */
-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;
-	}
+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
@@ -4914,11 +5303,20 @@ async function compile(options) {
 /**
 * Compile with incremental caching support.
 * Plugins and advanced users can manage their own cache and changed-file tracking.
+*
+* Without `changedFiles`, a cached file is reused while its modification time is unchanged.
+* With it, a file it names (by the path source discovery gives it, relative to the working
+* directory) is always reparsed, whatever its modification time, and every other cached
+* file is reused as it is.
 */
 async function compileIncremental(options, cache, changedFiles) {
 	return buildOutput(options, cache, changedFiles);
 }
-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;
@@ -4931,7 +5329,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();
@@ -4949,40 +5347,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 });
@@ -4994,10 +5371,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 {
@@ -5007,7 +5381,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;
@@ -5085,6 +5459,35 @@ function storyToJSON(story) {
 	return JSON.stringify(obj, null, 2);
 }
 //#endregion
-export { isExcluded as a, getFilenames as i, compile as n, mediaTypeFromFilename as o, compileIncremental as r, TweeTsError as t };
+//#region src/plugins/diagnostics.ts
+function formatDiagnostic(d) {
+	return `${d.file ? `${d.file}${d.line ? `:${d.line}` : ""}: ` : ""}${d.file && d.line ? d.message.replace(/^line \d+: /, "") : d.message}`;
+}
+/** Returns the warnings; throws a LocatedError when the compile reported errors. */
+function splitDiagnostics(result) {
+	const errors = result.diagnostics.filter((d) => d.level === "error");
+	if (errors.length === 0) return result.diagnostics.filter((d) => d.level === "warning");
+	const error = new Error(errors.map(formatDiagnostic).join("\n"));
+	const [first] = errors;
+	if (first?.file) {
+		error.id = first.file;
+		error.loc = {
+			file: first.file,
+			line: first.line ?? 1,
+			column: 1
+		};
+	}
+	throw error;
+}
+/** An error thrown by the compiler or bundler, with a TweeTsError's error diagnostics folded into its message. */
+function fatalError(e) {
+	if (e instanceof TweeTsError) {
+		const errors = e.diagnostics.filter((d) => d.level === "error").map(formatDiagnostic);
+		return new Error([...errors, e.message].join("\n"));
+	}
+	return e instanceof Error ? e : new Error(String(e));
+}
+//#endregion
+export { compileIncremental as a, mediaTypeFromFilename as c, compile as i, formatDiagnostic as n, getFilenames as o, splitDiagnostics as r, isExcluded as s, fatalError as t };
 
-//# sourceMappingURL=compiler-BiDNwR9q.js.map
+//# sourceMappingURL=diagnostics-DZNS7W41.js.map