@rohal12/twee-ts 1.16.1 → 1.17.1

package/dist/index.js

@@ -13,11 +13,27 @@ import { fileURLToPath } from "node:url";
 function generateIFID() {
 	return randomUUID().toUpperCase();
 }
-/** Validate and brand an IFID string. Throws on invalid input. */
+/**
+* Validate and brand an IFID string. Throws on invalid input.
+* Returns the IFID in its stored form (see `normalizeIFID`).
+*/
 function createIFID(value) {
 	const err = validateIFID(value);
 	if (err) throw new Error(`Invalid IFID: ${err}`);
-	return value.toUpperCase();
+	return normalizeIFID(value);
+}
+/** Length of the `UUID://...//` wrapper around a 36-character UUID. */
+const WRAPPED_LENGTH = 45;
+/**
+* Bring an IFID into the form the story model stores and every output writes: the uppercase
+* bare UUID. A valid `UUID://...//` wrapped IFID loses its wrapper; outputs that need the wrapper
+* (the Treaty of Babel comment) add exactly one. Twine 2 IFIDs use only capital letters, so the
+* value is uppercased, as Tweego does. An invalid value is only uppercased, so that validation
+* reports it as written.
+*/
+function normalizeIFID(value) {
+	const upper = value.toUpperCase();
+	return upper.length === WRAPPED_LENGTH && validateIFID(upper) === null ? upper.slice(7, 43) : upper;
 }
 /**
 * Validate an IFID string.
@@ -447,7 +463,7 @@ function unmarshalStoryData(story, json) {
 	}
 	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return "Cannot unmarshal \"StoryData\"; expected a JSON object";
 	const data = raw;
-	if (typeof data.ifid === "string" && data.ifid) story.ifid = data.ifid.toUpperCase();
+	if (typeof data.ifid === "string" && data.ifid) story.ifid = normalizeIFID(data.ifid);
 	if (typeof data.format === "string" && data.format) story.twine2.format = data.format;
 	if (typeof data["format-version"] === "string" && data["format-version"]) story.twine2.formatVersion = data["format-version"];
 	if (Array.isArray(data.options)) {
@@ -478,7 +494,7 @@ function unmarshalStorySettings(story, text, diagnostics) {
 		const val = line.slice(colonIdx + 1).trim().toLowerCase();
 		switch (key) {
 			case "ifid":
-				if (validateIFID(val) === null) story.legacyIFID = val.toUpperCase();
+				if (validateIFID(val) === null) story.legacyIFID = normalizeIFID(val);
 				obsolete.push("\"ifid\"");
 				continue;
 			case "zoom":
@@ -4696,14 +4712,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
@@ -4711,7 +4729,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
@@ -4726,7 +4744,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"];
@@ -4738,7 +4756,7 @@ function decompileTwine2(storyData, story, diagnostics) {
 		});
 		else startnode = parsed;
 	}
-	if (attrs["ifid"]) story.ifid = attrs["ifid"].toUpperCase();
+	if (attrs["ifid"]) story.ifid = normalizeIFID(attrs["ifid"]);
 	if (attrs["zoom"]) {
 		const parsed = parseFloat(attrs["zoom"]);
 		if (Number.isNaN(parsed)) diagnostics.push({
@@ -4751,15 +4769,20 @@ function decompileTwine2(storyData, story, diagnostics) {
 	if (attrs["format"]) story.twine2.format = attrs["format"];
 	if (attrs["format-version"]) story.twine2.formatVersion = attrs["format-version"];
 	if (attrs["options"]) for (const opt of attrs["options"].split(/\s+/).filter((s) => s.length > 0)) story.twine2.options.set(opt, true);
-	for (const node of storyData.children ?? []) {
+	const children = storyData.children ?? [];
+	const takenNames = new Set(children.filter((node) => node.type === "tag" && node.name === "tw-passagedata").map(passageDataName));
+	for (const node of children) {
 		if (node.type !== "tag" && node.type !== "style" && node.type !== "script") continue;
 		switch (node.name) {
 			case "style":
 			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);
+				const name = freeName(node.name === "style" ? "Story Stylesheet" : "Story JavaScript", takenNames);
+				takenNames.add(name);
 				storyAdd(story, {
-					name: node.name === "style" ? "Story Stylesheet" : "Story JavaScript",
+					name,
 					tags: node.name === "style" ? ["stylesheet"] : ["script"],
 					text
 				}, diagnostics);
@@ -4775,7 +4798,7 @@ function decompileTwine2(storyData, story, diagnostics) {
 			case "tw-passagedata": {
 				let pid = 0;
 				const pAttrs = node.attribs ?? {};
-				const name = pAttrs["name"] ?? "";
+				const name = passageDataName(node);
 				const tags = pAttrs["tags"] ? pAttrs["tags"].split(/\s+/).filter((s) => s.length > 0) : [];
 				const metadata = {};
 				if (pAttrs["pid"]) {
@@ -4792,7 +4815,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);
@@ -4806,8 +4829,19 @@ function decompileTwine2(storyData, story, diagnostics) {
 		text: marshalStoryData(story)
 	}, diagnostics);
 }
-function decompileTwine1(storeArea, story, diagnostics) {
-	const passages = (storeArea.children ?? []).filter(isTiddler).map(tiddlerToPassage);
+function passageDataName(node) {
+	return node.attribs?.["name"] ?? "";
+}
+/** The first of `base`, `base 2`, `base 3`, … that is not in `taken`. */
+function freeName(base, taken) {
+	if (!taken.has(base)) return base;
+	for (let n = 2;; n++) {
+		const candidate = `${base} ${n}`;
+		if (!taken.has(candidate)) return candidate;
+	}
+}
+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,
@@ -4817,12 +4851,12 @@ function decompileTwine1(storeArea, story, diagnostics) {
 function isTiddler(node) {
 	return node.type === "tag" && node.name === "div" && node.attribs !== void 0 && "tiddler" in node.attribs;
 }
-function tiddlerToPassage(node) {
+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: tiddlerUnescape(getTextContent(node)).trim()
+		text: passageText(tiddlerUnescape(getTextContent(node)))
 	};
 	const position = nodeAttrs["twine-position"];
 	if (position) passage.metadata = { position };
@@ -4887,7 +4921,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);
@@ -5041,8 +5075,8 @@ function parseFontFile(filename) {
 		diagnostics: []
 	};
 }
-function parseHTMLFile(filename) {
-	const { story, diagnostics } = decompileHTML(readUTF8(filename));
+function parseHTMLFile(filename, opts) {
+	const { story, diagnostics } = decompileHTML(readUTF8(filename), { trim: opts.trim ?? true });
 	return {
 		passages: story.name !== "" && !storyHas(story, "StoryTitle") ? [{
 			name: "StoryTitle",
@@ -5054,14 +5088,17 @@ function parseHTMLFile(filename) {
 }
 /**
 * Identity of the options that affect how a file parses, stored on its cache entry.
-* Only Twee files depend on them; every other file type yields the same key for all options.
+* 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: opts.trim ?? true,
+		trim,
 		twee2Compat: twee2File || (opts.twee2Compat ?? false)
 	});
 }
@@ -5075,7 +5112,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":
@@ -5107,8 +5144,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);
 }
@@ -5147,7 +5184,8 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 		const optionsKey = parseOptionsKey(filename, opts);
 		const entry = cache.get(filename);
 		const cached = entry?.parseOptionsKey === optionsKey ? entry : void 0;
-		if (changedFiles && cached && !changedFiles.has(filename)) {
+		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);
@@ -5159,7 +5197,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);
@@ -5194,6 +5232,121 @@ function loadSourcesCached(story, filenames, opts, diagnostics, processedFiles,
 	}, diagnostics);
 }
 //#endregion
+//#region src/template.ts
+/**
+* An HTML closing head tag: `</head` in any letter case, followed by whitespace, `/` or `>`, up to the next `>`.
+* This is how the HTML tokenizer reads an end tag; it ignores whatever sits between the tag name and the `>`.
+*/
+const CLOSING_HEAD_TAG = "<\\/[Hh][Ee][Aa][Dd](?=[\\t\\n\\f\\r />])[^>]*>";
+/** The regular expression source matching exactly `text`. */
+function literal(text) {
+	return text.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+}
+/** Replace the `slots` placeholders found in `template`, without scanning inserted text. */
+function fillTemplate(template, slots) {
+	return fillTemplateParts([{
+		kind: "scan",
+		text: template,
+		slots
+	}]);
+}
+/**
+* Fill the parts of a template in order, joined. A `'first'` slot replaced in one part is not replaced again in a
+* later part that lists the same slot object.
+*/
+function fillTemplateParts(parts) {
+	const filled = /* @__PURE__ */ new Set();
+	return parts.map((part) => {
+		if (part.kind === "verbatim" || part.slots.length === 0) return part.text;
+		const { slots } = part;
+		const pattern = new RegExp(slots.map((slot) => `(${slot.pattern})`).join("|"), "g");
+		return part.text.replace(pattern, (match, ...groups) => {
+			const slot = slots.find((_, i) => groups[i] !== void 0);
+			if (slot === void 0 || slot.occurrences === "first" && filled.has(slot)) return match;
+			filled.add(slot);
+			return slot.replacement(match);
+		});
+	}).join("");
+}
+//#endregion
+//#region src/modules.ts
+/**
+* Load modules and return HTML tags to inject before the closing head tag.
+*/
+function loadModules(filenames) {
+	const processed = /* @__PURE__ */ new Set();
+	const headTags = [];
+	for (const filename of filenames) {
+		if (processed.has(filename)) continue;
+		const ext = normalizedFileExt(filename);
+		let tag = null;
+		switch (ext) {
+			case "css":
+				tag = loadModuleTagged("style", filename);
+				break;
+			case "js":
+				tag = loadModuleTagged("script", filename);
+				break;
+			case "otf":
+			case "ttf":
+			case "woff":
+			case "woff2":
+				tag = loadModuleFont(filename);
+				break;
+			default: continue;
+		}
+		if (tag) headTags.push(tag);
+		processed.add(filename);
+	}
+	return headTags.join("\n");
+}
+function loadModuleTagged(tag, filename) {
+	const source = readUTF8(filename).trim();
+	if (source.length === 0) return null;
+	return `<${tag} id="${`${tag}-module-${slugify(baseNameWithoutExt(filename))}`}" type="${tag === "script" ? "text/javascript" : "text/css"}">${tag === "script" ? scriptContentEscape(source) : styleContentEscape(source)}</${tag}>`;
+}
+function loadModuleFont(filename) {
+	const source = readBase64(filename);
+	const family = baseNameWithoutExt(filename);
+	const idSlug = `style-module-${slugify(family)}`;
+	const ext = normalizedFileExt(filename);
+	return `<style id="${idSlug}" type="text/css">@font-face {\n\tfont-family: "${family}";\n\tsrc: url("data:${mediaTypeFromExt(ext)};base64,${source}") format("${fontFormatHint(ext)}");\n}</style>`;
+}
+/**
+* Load the module tags and head file content to inject before the closing head tag, joined by newlines,
+* or `''` when there is nothing to inject.
+*/
+function loadHeadContent(modulePaths, headFile, diagnostics) {
+	const parts = [];
+	if (modulePaths.length > 0) {
+		const modules = loadModules(modulePaths).trim();
+		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 parts.join("\n");
+}
+/**
+* The template slot that inserts `content` on its own line before the first closing head tag (as Tweego does),
+* or `undefined` when `content` is empty. The tag may use any letter case and whitespace before its `>`, and is
+* kept as written.
+*/
+function headSlot(content) {
+	if (content.length === 0) return void 0;
+	return {
+		pattern: CLOSING_HEAD_TAG,
+		occurrences: "first",
+		replacement: (tag) => `${content}\n${tag}`
+	};
+}
+//#endregion
 //#region src/version.ts
 /**
 * The twee-ts version, read at runtime from the package's own package.json.
@@ -5227,24 +5380,38 @@ const CREATOR_NAME$2 = "Twee-ts";
 function toTwine2Archive(story, startName, options) {
 	return getTwine2DataChunk(story, startName, options) + "\n";
 }
+/**
+* Fill the Twine 2 format template: every `{{STORY_NAME}}` gets the escaped story name and the first
+* `{{STORY_DATA}}` the story data (as Tweego does), and `head` goes before the first closing head tag. All three are
+* found in the template in one pass, so a story name, passage text or head content holding a placeholder or a
+* closing head tag stays literal.
+*/
 function toTwine2HTML(story, format, startName, options) {
-	let template = readFormatSource(format);
-	if (template.includes("{{STORY_NAME}}")) {
-		const name = htmlEscape(story.name);
-		template = template.replaceAll("{{STORY_NAME}}", () => name);
-	}
-	if (template.includes("{{STORY_DATA}}")) {
-		const data = getTwine2DataChunk({
-			...story,
-			twine2: {
-				...story.twine2,
-				format: format.name,
-				formatVersion: format.version
+	const name = htmlEscape(story.name);
+	const head = headSlot(options?.head ?? "");
+	const slots = [
+		{
+			pattern: literal("{{STORY_NAME}}"),
+			occurrences: "all",
+			replacement: () => name
+		},
+		{
+			pattern: literal("{{STORY_DATA}}"),
+			occurrences: "first",
+			replacement: () => {
+				return getTwine2DataChunk({
+					...story,
+					twine2: {
+						...story.twine2,
+						format: format.name,
+						formatVersion: format.version
+					}
+				}, startName, options);
 			}
-		}, startName, options);
-		template = template.replace("{{STORY_DATA}}", () => data);
-	}
-	return template;
+		},
+		...head === void 0 ? [] : [head]
+	];
+	return fillTemplate(readFormatSource(format), slots);
 }
 const OMITTING_TAGS = [
 	"Twine.private",
@@ -5337,7 +5504,13 @@ function toTwine1Archive(story, _startName) {
 	const { data, count } = getTwine1PassageChunk(story);
 	return `<div id="storeArea" data-size="${count}">${data}</div>\n`;
 }
-function toTwine1HTML(story, format, startName) {
+/**
+* Fill the Twine 1 format template. The format's components are inserted first, one after another, as Tweego and
+* Twine 1 do. Then the first of each story placeholder (`"VERSION"`, `"TIME"`, `"START_AT"`, `"STORY_SIZE"`,
+* `"STORY"`), the IFID comment and `head` (before the first closing head tag) are found in one pass, so a start
+* passage name or story data holding a placeholder or a closing head tag stays literal.
+*/
+function toTwine1HTML(story, format, startName, options) {
 	const formatDir = dirname(format.filename);
 	const parentDir = dirname(formatDir);
 	let template = readFormatSource(format);
@@ -5348,28 +5521,60 @@ function toTwine1HTML(story, format, startName) {
 	template = tryReplaceComponent(template, "\"JONAH\"", join(formatDir, "code.js"), true);
 	if (story.twine1.settings.get("jquery") === "on") template = tryReplaceComponent(template, "\"JQUERY\"", join(parentDir, "jquery.js"), true);
 	if (story.twine1.settings.get("modernizr") === "on") template = tryReplaceComponent(template, "\"MODERNIZR\"", join(parentDir, "modernizr.js"), true);
+	const isPre14 = !template.includes("\"STORY\"");
+	const footer = isPre14 ? readFooter(formatDir) : "";
+	const storeArea = (template + footer).includes("<div id=\"store-area\"") ? "<div id=\"store-area\"" : "<div id=\"storeArea\"";
+	const safeIfid = htmlCommentSanitize(story.ifid);
+	const late = [story.ifid ? {
+		pattern: literal(storeArea),
+		occurrences: "first",
+		replacement: (div) => `<!-- UUID://${safeIfid}// -->${div}`
+	} : void 0, headSlot(options?.head ?? "")].filter((slot) => slot !== void 0);
 	const displayStart = startName === "Start" ? "" : startName;
-	template = template.replace("\"VERSION\"", `Compiled with ${CREATOR_NAME$1}, ${VERSION}`);
-	template = template.replace("\"TIME\"", `Built on ${(/* @__PURE__ */ new Date()).toUTCString()}`);
-	const startAtValue = `"${jsStringEscape(displayStart)}"`;
-	template = template.replace("\"START_AT\"", () => startAtValue);
-	template = template.replace("\"STORY_SIZE\"", `"${count}"`);
-	if (template.includes("\"STORY\"")) template = template.replace("\"STORY\"", () => data);
-	else {
-		let footer;
-		try {
-			footer = readFileSync(join(formatDir, "footer.html"), "utf-8");
-		} catch {
-			footer = "</div>\n</body>\n</html>\n";
-		}
-		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"`);
+	const slots = [
+		firstSlot("\"VERSION\"", `Compiled with ${CREATOR_NAME$1}, ${VERSION}`),
+		firstSlot("\"TIME\"", `Built on ${(/* @__PURE__ */ new Date()).toUTCString()}`),
+		firstSlot("\"START_AT\"", `"${jsStringEscape(displayStart)}"`),
+		firstSlot("\"STORY_SIZE\"", `"${count}"`),
+		firstSlot("\"STORY\"", data),
+		...late
+	];
+	return fillTemplateParts(isPre14 ? [
+		{
+			kind: "scan",
+			text: template,
+			slots
+		},
+		{
+			kind: "verbatim",
+			text: data
+		},
+		{
+			kind: "scan",
+			text: footer,
+			slots: late
+		}
+	] : [{
+		kind: "scan",
+		text: template,
+		slots
+	}]);
+}
+/** A slot replacing the first `token` with `value`. */
+function firstSlot(token, value) {
+	return {
+		pattern: literal(token),
+		occurrences: "first",
+		replacement: () => value
+	};
+}
+/** The footer of a pre-1.4 format, or the default one when the format has none. */
+function readFooter(formatDir) {
+	try {
+		return readFileSync(join(formatDir, "footer.html"), "utf-8");
+	} catch {
+		return "</div>\n</body>\n</html>\n";
 	}
-	return template;
 }
 /**
 * Why Twine 1 output leaves a passage out of its tiddlers, or `undefined` when the passage is emitted.
@@ -5407,82 +5612,54 @@ 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;
-}
-//#endregion
-//#region src/modules.ts
 /**
-* Load modules and return HTML tags to inject before </head>.
+* 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 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 toTwee(story, outMode, options = {}) {
+	return withEffectiveStoryData(story, options.addStoryData ?? false).map((p) => passageToTwee(p, outMode)).join("");
 }
-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 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)
+	];
 }
-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>`;
+/** 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/passage-omission.ts
 /**
-* Inject modules and head file content before </head>.
+* 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 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)}`
-		});
-	}
-	if (parts.length > 0) {
-		parts.push("</head>");
-		const replacement = parts.join("\n");
-		return html.replace("</head>", () => replacement);
+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 html;
 }
-//#endregion
-//#region src/start-passage.ts
+/** 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`;
@@ -5491,13 +5668,8 @@ function describeOmission(omission) {
 		default: throw new Error(`unhandled passage omission: ${JSON.stringify(omission)}`);
 	}
 }
-function omissionFor(story, passage, target) {
-	switch (target) {
-		case "twine2": return twine2PassageOmission(story, passage);
-		case "twine1": return twine1PassageOmission(passage);
-		default: throw new Error(`unhandled start passage target: ${String(target)}`);
-	}
-}
+//#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).
@@ -5508,7 +5680,7 @@ function startPassageDiagnostics(story, startName, target) {
 		level: "error",
 		message: `Starting passage "${startName}" not found.`
 	}];
-	const omission = omissionFor(story, passage, target);
+	const omission = passageOmission(story, passage, target);
 	if (omission === void 0) return [];
 	return [{
 		level: "error",
@@ -5543,21 +5715,51 @@ async function compile(options) {
 * Compile and write to a file.
 */
 async function compileToFile(options) {
-	const result = await buildOutput(options, void 0, void 0, options.outFile);
+	const result = await compileForOutputFile(options, options.outFile);
 	writeFileSync(options.outFile, result.output, "utf-8");
 	return result;
 }
 /**
+* 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(). With `cache`, files are cached as
+* compileIncremental() caches them.
+*
+* Internal, for the CLI and the bundler plugins; not part of the public API.
+*/
+async function compileForOutputFile(options, outFile, cache) {
+	return buildOutput(options, cache, void 0, outFile);
+}
+/**
 * 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);
 }
 /**
-* Watch for file changes and recompile.
+* Watch for file changes and recompile. Every build is written to `outFile`, including
+* one whose diagnostics report errors. Builds run one at a time: changes made during a
+* build go into one follow-up build after it, and the superseded build is neither
+* written nor reported.
 */
 async function watch(options) {
+	return watchWithWriteFilter(options, () => true);
+}
+/**
+* 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 watchWithWriteFilter(options, shouldWrite) {
 	const controller = new AbortController();
 	const cache = /* @__PURE__ */ new Map();
 	const filePaths = options.sources.filter((s) => typeof s === "string");
@@ -5575,17 +5777,62 @@ async function watch(options) {
 		const abs = resolve(filename);
 		return !notExcludable.some((root) => abs === root || abs.startsWith(root + sep));
 	};
+	let building = false;
+	let queued;
+	const deliver = (outcome) => {
+		try {
+			if (!outcome.ok) throw outcome.error;
+			if (shouldWrite(outcome.result)) writeFileSync(options.outFile, outcome.result.output, "utf-8");
+			options.onBuild?.(outcome.result);
+		} catch (e) {
+			options.onError?.(toError(e));
+		}
+	};
+	const drain = async (first) => {
+		building = true;
+		try {
+			let request = first;
+			while (request !== void 0) {
+				const current = request;
+				const outcome = await buildOutput(options, cache, current.changedFiles, options.outFile).then((result) => ({
+					ok: true,
+					result
+				}), (e) => ({
+					ok: false,
+					error: toError(e)
+				}));
+				if (controller.signal.aborted) return;
+				request = queued === void 0 ? void 0 : mergeBuildRequests(current, queued);
+				queued = void 0;
+				if (request === void 0) deliver(outcome);
+			}
+		} finally {
+			building = false;
+		}
+	};
 	const handle = watchFilesystem(allPaths, options.outFile, (changedFiles) => {
-		buildOutput(options, cache, changedFiles, options.outFile).then((result) => {
-			writeFileSync(options.outFile, result.output, "utf-8");
-			options.onBuild?.(result);
-		}).catch((e) => {
-			options.onError?.(e instanceof Error ? e : new Error(String(e)));
-		});
+		if (controller.signal.aborted) return;
+		const request = { changedFiles };
+		if (building) {
+			queued = queued === void 0 ? request : mergeBuildRequests(queued, request);
+			return;
+		}
+		drain(request);
 	}, ignore);
-	controller.signal.addEventListener("abort", () => handle.close());
+	controller.signal.addEventListener("abort", () => {
+		queued = void 0;
+		handle.close();
+	});
 	return controller;
 }
+/** One build covering both requests: a full build if either is one, else every changed file. */
+function mergeBuildRequests(a, b) {
+	if (a.changedFiles === void 0 || b.changedFiles === void 0) return { changedFiles: void 0 };
+	return { changedFiles: /* @__PURE__ */ new Set([...a.changedFiles, ...b.changedFiles]) };
+}
+function toError(e) {
+	return e instanceof Error ? e : new Error(String(e));
+}
 /**
 * `outFile`: the file the build is written to, which source and module discovery
 * skip (as Tweego does), so an output inside a source folder is never loaded back.
@@ -5633,7 +5880,7 @@ async function buildOutput(options, cache, changedFiles, outFile) {
 	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 });
@@ -5647,17 +5894,17 @@ async function buildOutput(options, cache, changedFiles, outFile) {
 		case "html": {
 			diagnostics.push(...startPassageDiagnostics(story, startName, format?.isTwine2 === false ? "twine1" : "twine2"));
 			if (!format) throw new TweeTsError("No story format available for HTML output.", diagnostics);
-			if (format.isTwine2) output = toTwine2HTML(story, format, startName, { sourceInfo });
-			else {
-				if (story.name === "" && !storyHas(story, "StoryTitle")) diagnostics.push({
-					level: "error",
-					message: "Special passage \"StoryTitle\" not found."
-				});
-				output = toTwine1HTML(story, format, startName);
-			}
+			if (!format.isTwine2 && story.name === "" && !storyHas(story, "StoryTitle")) diagnostics.push({
+				level: "error",
+				message: "Special passage \"StoryTitle\" not found."
+			});
 			const modules = getFilenames(options.modules ?? [], outFile);
 			diagnostics.push(...modules.diagnostics);
-			output = modifyHead(output, modules.filenames, options.headFile, diagnostics);
+			const head = loadHeadContent(modules.filenames, options.headFile, diagnostics);
+			output = format.isTwine2 ? toTwine2HTML(story, format, startName, {
+				sourceInfo,
+				head
+			}) : toTwine1HTML(story, format, startName, { head });
 			break;
 		}
 		default: throw new TweeTsError(`Unhandled output mode: ${outputMode}`, diagnostics);
@@ -6076,6 +6323,11 @@ 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).
@@ -6083,15 +6335,17 @@ function endOfRegularExpression(source, pos) {
 * `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.
+* 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))
+		limit: Math.min(text.length, start + Math.max(budget.left, 0)),
+		scanned: start
 	};
 	const markup = readMarkup(reader, start);
-	budget.left -= (markup?.end ?? reader.limit) - start;
+	budget.left -= Math.max(reader.scanned, markup?.end ?? start) - start;
 	return markup;
 }
 function readMarkup(reader, start) {
@@ -6167,7 +6421,7 @@ function readCoreComponents(reader, from) {
 		const ch = text[pos];
 		pos += 1;
 		switch (ch) {
-			case "\n": return;
+			case "\n": return readTo(reader, pos, void 0);
 			case "\"": {
 				const end = readQuoted(reader, pos, "\"");
 				if (end === void 0) return;
@@ -6201,7 +6455,7 @@ function readCoreComponents(reader, from) {
 			case "]":
 				depth -= 1;
 				if (depth === 1) {
-					const end = componentEnd(text, pos);
+					const end = componentEnd(reader, pos);
 					if (end === void 0) return;
 					return {
 						link: link ?? text.slice(componentStart, end.textEnd),
@@ -6210,6 +6464,7 @@ function readCoreComponents(reader, from) {
 				}
 		}
 	}
+	return readTo(reader, pos, void 0);
 }
 /**
 * Reads a component after `][` that holds no delimiter: an image's link (`setter` false) or a
@@ -6223,7 +6478,7 @@ function readComponent(reader, from, setter) {
 		const ch = text[pos];
 		pos += 1;
 		switch (ch) {
-			case "\n": return;
+			case "\n": return readTo(reader, pos, void 0);
 			case "\"":
 			case "'": {
 				if (ch === "'" && !setter) break;
@@ -6237,9 +6492,10 @@ function readComponent(reader, from, setter) {
 				break;
 			case "]":
 				depth -= 1;
-				if (depth === 1) return componentEnd(text, pos);
+				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) {
@@ -6247,19 +6503,19 @@ function readSetter(reader, from) {
 	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(text, pos) {
-	switch (text[pos]) {
-		case "[": return {
+function componentEnd(reader, pos) {
+	switch (reader.text[pos]) {
+		case "[": return readTo(reader, pos + 1, {
 			textEnd: pos - 1,
 			next: pos + 1,
 			last: false
-		};
-		case "]": return {
+		});
+		case "]": return readTo(reader, pos + 1, {
 			textEnd: pos - 1,
 			next: pos + 1,
 			last: true
-		};
-		default: return;
+		});
+		default: return readTo(reader, pos + 1, void 0);
 	}
 }
 /**
@@ -6274,12 +6530,13 @@ function readQuoted(reader, from, quote) {
 		const ch = text[pos];
 		pos += 1;
 		if (ch === quote) return pos;
-		if (ch === "\n") return;
+		if (ch === "\n") return readTo(reader, pos, void 0);
 		if (ch === "\\") {
-			if (pos >= reader.limit || text[pos] === "\n") return;
+			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
@@ -7137,6 +7394,39 @@ function extractLinksFromText(text, isScript) {
 	].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);
+}
+/**
+* Whether the `target` output keeps the links in `p`: always without a target, which describes
+* every source passage. With one, a passage the output leaves out never reaches the player, so it
+* links nowhere, except a script passage, which Twine 2 output leaves out as a passage but runs.
+*/
+function readsLinks(story, p, { target }) {
+	if (target === void 0) return true;
+	const omission = passageOmission(story, p, target);
+	return omission === void 0 || omission.kind === "tag" && omission.tag === "script";
+}
+/**
+* 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);
+	}
+	return omissions;
+}
 /** Passages SugarCube runs from their raw text, never joining their lines. */
 const RAW_TEXT_PASSAGES = /* @__PURE__ */ new Set([
 	"StoryInit",
@@ -7178,9 +7468,16 @@ function joinLines(text) {
 * expect(map.brokenLinks).toEqual([]);
 * expect(map.deadEnds).not.toContain('Start');
 * ```
-*/
-function storyInspect(story) {
-	const allNames = new Set(story.passages.map((p) => p.name));
+*
+* 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. With a target, passages that output leaves out also give no links (script passages
+* excepted, as Twine 2 output runs them), so they report no broken links and keep no passage from
+* being an orphan.
+*/
+function storyInspect(story, options = {}) {
+	const destinations = destinationOmissions(story, options);
 	const passages = [];
 	const storyPassages = [];
 	const infoPassages = [];
@@ -7202,14 +7499,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, readsLinks(story, p, options) ? 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);
@@ -7239,14 +7546,27 @@ function storyInspect(story) {
 /**
 * Lint a story: compile without output rendering, then inspect structure.
 * Uses JSON output mode internally to avoid format resolution, so it checks
-* the starting passage itself, against the Twine 2 passage rules.
+* the starting passage itself, against the Twine 2 passage rules. Link
+* destinations are checked against the same rules: a link to a passage that
+* Twine 2 output leaves out is broken, and a passage it leaves out (other than
+* a script passage) gives no links.
 */
 async function lint(options) {
-	const result = await compile({
+	return lintForOutputFile(options, void 0);
+}
+/**
+* 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 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, ...startPassageDiagnostics(result.story, map.start, "twine2")],
 		stats: result.stats,
@@ -7273,7 +7593,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("");