@rohal12/twee-ts 1.1.1 → 1.2.0

package/dist/index.js

@@ -69,13 +69,26 @@ function tweeEscape(s) {
   if (s.length === 0) return s;
   return s.replace(/[\\[\]{}]/g, (ch) => "\\" + ch);
 }
+function jsStringEscape(s) {
+  if (s.length === 0) return s;
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+}
+function commentSanitize(s) {
+  return s.replace(/\*\//g, "* /");
+}
+function htmlCommentSanitize(s) {
+  return s.replace(/-->/g, "-- >");
+}
 function tweeUnescape(s) {
   if (s.length === 0) return s;
   let result = "";
   for (let i = 0; i < s.length; i++) {
     if (s[i] === "\\") {
       i++;
-      if (i >= s.length) break;
+      if (i >= s.length) {
+        result += "\\";
+        break;
+      }
     }
     result += s[i];
   }
@@ -168,16 +181,16 @@ function passageToPassagedata(p, pid) {
   let position;
   let size;
   if (hasMetadataPosition(p)) {
-    position = p.metadata.position;
+    position = p.metadata?.position ?? "";
   } else {
     const x = pid % 10;
-    let y = Math.floor(pid / 10);
+    const y = Math.floor(pid / 10);
     const xp = x === 0 ? 10 : x;
     const yp = x === 0 ? y : y + 1;
     position = `${xp * 125 - 25},${yp * 125 - 25}`;
   }
   if (hasMetadataSize(p)) {
-    size = p.metadata.size;
+    size = p.metadata?.size ?? "";
   } else {
     size = "100,100";
   }
@@ -186,10 +199,10 @@ function passageToPassagedata(p, pid) {
 function passageToTiddler(p, pid) {
   let position;
   if (hasMetadataPosition(p)) {
-    position = p.metadata.position;
+    position = p.metadata?.position ?? "";
   } else {
     const x = pid % 10;
-    let y = Math.floor(pid / 10);
+    const y = Math.floor(pid / 10);
     const xp = x === 0 ? 10 : x;
     const yp = x === 0 ? y : y + 1;
     position = `${xp * 140 - 130},${yp * 140 - 130}`;
@@ -208,15 +221,17 @@ function countWords(p) {
 }
 function applyTagAliases(passages, aliases) {
   const entries = Object.entries(aliases);
-  if (entries.length === 0) return;
-  for (const p of passages) {
-    const original = [...p.tags];
+  if (entries.length === 0) return [...passages];
+  return passages.map((p) => {
+    const original = p.tags;
+    const added = [];
     for (const [alias, canonical] of entries) {
-      if (original.includes(alias) && !p.tags.includes(canonical)) {
-        p.tags.push(canonical);
+      if (original.includes(alias) && !original.includes(canonical) && !added.includes(canonical)) {
+        added.push(canonical);
       }
     }
-  }
+    return added.length > 0 ? { ...p, tags: [...original, ...added] } : p;
+  });
 }
 function quote(s) {
   return `"${s}"`;
@@ -288,27 +303,32 @@ function marshalStoryData(story) {
   return JSON.stringify(data, null, "	");
 }
 function unmarshalStoryData(story, json) {
-  let data;
+  let raw;
   try {
-    data = JSON.parse(json);
+    raw = JSON.parse(json);
   } catch (e) {
     return `Cannot unmarshal "StoryData"; ${e instanceof Error ? e.message : String(e)}`;
   }
-  if (data.ifid) story.ifid = data.ifid.toUpperCase();
-  if (data.format) story.twine2.format = data.format;
-  if (data["format-version"]) story.twine2.formatVersion = data["format-version"];
-  if (data.options) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return 'Cannot unmarshal "StoryData"; expected a JSON object';
+  }
+  const data = raw;
+  if (typeof data.ifid === "string" && data.ifid) story.ifid = data.ifid.toUpperCase();
+  if (typeof data.format === "string" && data.format) story.twine2.format = data.format;
+  if (typeof data["format-version"] === "string" && data["format-version"])
+    story.twine2.formatVersion = data["format-version"];
+  if (Array.isArray(data.options)) {
     for (const opt of data.options) {
-      story.twine2.options.set(opt, true);
+      if (typeof opt === "string") story.twine2.options.set(opt, true);
     }
   }
-  if (data.start) story.twine2.start = data.start;
-  if (data["tag-colors"]) {
+  if (typeof data.start === "string" && data.start) story.twine2.start = data.start;
+  if (typeof data["tag-colors"] === "object" && data["tag-colors"] !== null && !Array.isArray(data["tag-colors"])) {
     for (const [tag, color] of Object.entries(data["tag-colors"])) {
-      story.twine2.tagColors.set(tag, color);
+      if (typeof color === "string") story.twine2.tagColors.set(tag, color);
     }
   }
-  if (data.zoom != null && data.zoom !== 0) story.twine2.zoom = data.zoom;
+  if (typeof data.zoom === "number" && data.zoom !== 0) story.twine2.zoom = data.zoom;
   return null;
 }
 function unmarshalStorySettings(story, text, diagnostics) {
@@ -351,6 +371,7 @@ function unmarshalStorySettings(story, text, diagnostics) {
   }
 }
 function storyAdd(story, p, diagnostics) {
+  let processed = p;
   switch (p.name) {
     case "StoryIncludes":
       diagnostics.push({
@@ -370,7 +391,7 @@ function storyAdd(story, p, diagnostics) {
             });
           }
         }
-        p.text = marshalStoryData(story);
+        processed = { ...p, text: marshalStoryData(story) };
       } else {
         diagnostics.push({
           level: "error",
@@ -382,12 +403,14 @@ function storyAdd(story, p, diagnostics) {
     case "StorySettings":
       unmarshalStorySettings(story, p.text, diagnostics);
       break;
-    case "StoryTitle":
-      p.text = p.text.trim();
-      story.name = p.text;
+    case "StoryTitle": {
+      const trimmed = p.text.trim();
+      processed = { ...p, text: trimmed };
+      story.name = trimmed;
       break;
+    }
   }
-  storyAppend(story, p, diagnostics);
+  storyAppend(story, processed, diagnostics);
 }
 function getStoryStats(story) {
   let storyPassages = 0;
@@ -441,7 +464,7 @@ var MEDIA_TYPE_MAP = {
   webm: "video/webm"
 };
 function mediaTypeFromExt(ext) {
-  return MEDIA_TYPE_MAP[ext] ?? "";
+  return MEDIA_TYPE_MAP[ext] ?? "application/octet-stream";
 }
 function mediaTypeFromFilename(filename) {
   return mediaTypeFromExt(normalizedFileExt(filename));
@@ -463,8 +486,6 @@ var KNOWN_EXTENSIONS = /* @__PURE__ */ new Set([
   "twee",
   "tw2",
   "twee2",
-  "htm",
-  "html",
   "css",
   "js",
   "otf",
@@ -574,23 +595,49 @@ function watchFilesystem(pathnames, outFilename, callback) {
 }
 
 // src/formats.ts
-import { readFileSync, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { readdirSync as readdirSync2, statSync as statSync2 } from "fs";
 import { join as join2 } from "path";
 import { homedir } from "os";
+
+// src/util.ts
+import { readFileSync } from "fs";
+import { parse as parsePath } from "path";
+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;
+}
+function readBase64(filename) {
+  return readFileSync(filename).toString("base64");
+}
+function baseNameWithoutExt(filename) {
+  const { name, ext } = parsePath(filename);
+  return name || ext;
+}
+
+// src/formats.ts
 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 parse = (json) => {
+    const raw = JSON.parse(json);
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+    const obj = raw;
+    if (typeof obj.name !== "string" || typeof obj.version !== "string" || typeof obj.source !== "string") return null;
+    return { name: obj.name, version: obj.version, source: obj.source, proofing: obj.proofing === true };
+  };
   try {
-    return JSON.parse(chunk);
+    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 JSON.parse(chunk);
+          return parse(chunk);
         } catch {
         }
       }
@@ -598,12 +645,6 @@ function parseFormatJSON(source, formatId) {
     return null;
   }
 }
-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;
-}
 function discoverFormats(searchDirs) {
   const formats = /* @__PURE__ */ new Map();
   const baseFilenames = ["format.js", "header.html"];
@@ -698,9 +739,11 @@ function parseSemver(v) {
   return [Number(m[1]), Number(m[2]), Number(m[3])];
 }
 function semverCompare(a, b) {
-  for (let i = 0; i < 3; i++) {
-    if (a[i] !== b[i]) return a[i] - b[i];
-  }
+  const [aMajor, aMinor, aPatch] = a;
+  const [bMajor, bMinor, bPatch] = b;
+  if (aMajor !== bMajor) return aMajor - bMajor;
+  if (aMinor !== bMinor) return aMinor - bMinor;
+  if (aPatch !== bPatch) return aPatch - bPatch;
   return 0;
 }
 function getFormatIdByNameAndVersion(formats, name, version) {
@@ -731,7 +774,6 @@ function readFormatSource(format) {
 }
 
 // src/loader.ts
-import { readFileSync as readFileSync2 } from "fs";
 import { basename } from "path";
 
 // src/lexer.ts
@@ -1024,13 +1066,13 @@ function hasTwee2Syntax(s) {
 }
 function twee2ToV3(s) {
   if (!hasTwee2Syntax(s)) return s;
-  s = s.replace(twee2HeaderRe, (_, p1, p2, p3) => {
+  let result = s.replace(twee2HeaderRe, (_, p1, p2, p3) => {
     const tags = p2 ?? "";
     const pos = p3 ?? "";
     return `${p1}${tags} {"position":"${pos}"}`;
   });
-  s = s.replace(twee2BadPosRe, "$1");
-  return s;
+  result = result.replace(twee2BadPosRe, "$1");
+  return result;
 }
 
 // src/parser.ts
@@ -1108,7 +1150,11 @@ function parseTwee(source, options = {}) {
           return { passages, diagnostics };
         }
         try {
-          const parsed = JSON.parse(item.val);
+          const raw = JSON.parse(item.val);
+          if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            throw new Error("expected a JSON object");
+          }
+          const parsed = raw;
           const meta = {};
           if (typeof parsed.position === "string") meta.position = parsed.position;
           if (typeof parsed.size === "string") meta.size = parsed.size;
@@ -1128,6 +1174,16 @@ function parseTwee(source, options = {}) {
         current.text = trim ? item.val.trim() : item.val;
         break;
       }
+      default: {
+        const _exhaustive = item.type;
+        diagnostics.push({
+          level: "error",
+          message: `line ${item.line}: Unhandled lexer item type: ${_exhaustive}.`,
+          file: filename,
+          line: item.line
+        });
+        return { passages, diagnostics };
+      }
     }
     lastType = item.type;
   }
@@ -1138,15 +1194,6 @@ function parseTwee(source, options = {}) {
 }
 
 // src/loader.ts
-function readUTF82(filename) {
-  let content = readFileSync2(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;
-}
-function readBase64(filename) {
-  return readFileSync2(filename).toString("base64");
-}
 function loadSources(story, filenames, opts, diagnostics, processedFiles) {
   for (const filename of filenames) {
     if (processedFiles.has(filename)) {
@@ -1245,7 +1292,7 @@ function loadInlineSources(story, sources, opts, diagnostics) {
   }
 }
 function loadTwee(story, filename, opts, diagnostics) {
-  const source = readUTF82(filename);
+  const source = readUTF8(filename);
   const result = parseTwee(source, {
     filename,
     trim: opts.trim ?? true,
@@ -1257,38 +1304,48 @@ function loadTwee(story, filename, opts, diagnostics) {
   }
 }
 function loadTagged(story, tag, filename, diagnostics) {
-  const source = readUTF82(filename);
+  const source = readUTF8(filename);
   storyAdd(story, { name: basename(filename), tags: [tag], text: source }, diagnostics);
 }
 function loadMedia(story, tag, filename, diagnostics) {
   const source = readBase64(filename);
-  const name = basename(filename).split(".")[0];
-  storyAdd(story, {
-    name,
-    tags: [tag],
-    text: `data:${mediaTypeFromFilename(filename)};base64,${source}`
-  }, diagnostics);
+  const name = baseNameWithoutExt(filename);
+  storyAdd(
+    story,
+    {
+      name,
+      tags: [tag],
+      text: `data:${mediaTypeFromFilename(filename)};base64,${source}`
+    },
+    diagnostics
+  );
 }
 function loadFont(story, filename, diagnostics) {
   const source = readBase64(filename);
   const name = basename(filename);
-  const family = name.split(".")[0];
+  const family = baseNameWithoutExt(filename);
   const ext = normalizedFileExt(filename);
   const mediaType = mediaTypeFromExt(ext);
   const hint = fontFormatHint(ext);
-  storyAdd(story, {
-    name,
-    tags: ["stylesheet"],
-    text: `@font-face {
+  storyAdd(
+    story,
+    {
+      name,
+      tags: ["stylesheet"],
+      text: `@font-face {
 	font-family: "${family}";
 	src: url("data:${mediaType};base64,${source}") format("${hint}");
 }`
-  }, diagnostics);
+    },
+    diagnostics
+  );
 }
 
+// src/version.ts
+var VERSION = "1.2.0";
+
 // src/output-twine2.ts
 var CREATOR_NAME = "Twee-ts";
-var CREATOR_VERSION = "0.1.0";
 function toTwine2Archive(story, startName, diagnostics) {
   return getTwine2DataChunk(story, startName, diagnostics) + "\n";
 }
@@ -1316,12 +1373,12 @@ function getTwine2DataChunk(story, startName, diagnostics) {
   }
   let styleContent = "";
   if (stylesheets.length === 1) {
-    styleContent = stylesheets[0].text;
+    styleContent = stylesheets[0]?.text ?? "";
   } else if (stylesheets.length > 1) {
     let pidS = 1;
     for (const p of stylesheets) {
       if (pidS > 1 && !styleContent.endsWith("\n")) styleContent += "\n";
-      styleContent += `/* twine-user-stylesheet #${pidS}: "${p.name}" */
+      styleContent += `/* twine-user-stylesheet #${pidS}: "${commentSanitize(p.name)}" */
 `;
       styleContent += p.text;
       pidS++;
@@ -1330,12 +1387,12 @@ function getTwine2DataChunk(story, startName, diagnostics) {
   parts.push(`<style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css">${styleContent}</style>`);
   let scriptContent = "";
   if (scripts.length === 1) {
-    scriptContent = scripts[0].text;
+    scriptContent = scripts[0]?.text ?? "";
   } else if (scripts.length > 1) {
     let pidS = 1;
     for (const p of scripts) {
       if (pidS > 1 && !scriptContent.endsWith("\n")) scriptContent += "\n";
-      scriptContent += `/* twine-user-script #${pidS}: "${p.name}" */
+      scriptContent += `/* twine-user-script #${pidS}: "${commentSanitize(p.name)}" */
 `;
       scriptContent += p.text;
       pidS++;
@@ -1365,7 +1422,7 @@ function getTwine2DataChunk(story, startName, diagnostics) {
   }
   const options = opts.join(" ");
   const zoom = story.twine2.zoom === Math.floor(story.twine2.zoom) ? story.twine2.zoom.toString() : story.twine2.zoom.toFixed(1);
-  const wrapper = `<!-- UUID://${story.ifid}// --><tw-storydata name="${attrEscape(story.name)}" startnode="${startID}" creator="${attrEscape(CREATOR_NAME)}" creator-version="${attrEscape(CREATOR_VERSION)}" ifid="${attrEscape(story.ifid)}" zoom="${attrEscape(zoom)}" format="${attrEscape(story.twine2.format)}" format-version="${attrEscape(story.twine2.formatVersion)}" options="${attrEscape(options)}" hidden>`;
+  const wrapper = `<!-- UUID://${htmlCommentSanitize(story.ifid)}// --><tw-storydata name="${attrEscape(story.name)}" startnode="${attrEscape(startID)}" creator="${attrEscape(CREATOR_NAME)}" creator-version="${attrEscape(VERSION)}" ifid="${attrEscape(story.ifid)}" zoom="${attrEscape(zoom)}" format="${attrEscape(story.twine2.format)}" format-version="${attrEscape(story.twine2.formatVersion)}" options="${attrEscape(options)}" hidden>`;
   return wrapper + parts.join("") + "</tw-storydata>";
 }
 function ensureIFID(story, diagnostics) {
@@ -1386,10 +1443,9 @@ function ensureIFID(story, diagnostics) {
 }
 
 // src/output-twine1.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync2 } from "fs";
 import { join as join3, dirname } from "path";
 var CREATOR_NAME2 = "twee-ts";
-var CREATOR_VERSION2 = "0.1.0";
 function toTwine1Archive(story, _startName) {
   const { data, count } = getTwine1PassageChunk(story);
   return `<div id="storeArea" data-size="${count}" hidden>${data}</div>
@@ -1411,26 +1467,27 @@ function toTwine1HTML(story, format, startName, _diagnostics) {
     template = tryReplaceComponent(template, '"MODERNIZR"', join3(parentDir, "modernizr.js"), true);
   }
   const displayStart = startName === "Start" ? "" : startName;
-  template = template.replace('"VERSION"', `Compiled with ${CREATOR_NAME2}, ${CREATOR_VERSION2}`);
+  template = template.replace('"VERSION"', `Compiled with ${CREATOR_NAME2}, ${VERSION}`);
   template = template.replace('"TIME"', `Built on ${(/* @__PURE__ */ new Date()).toUTCString()}`);
-  template = template.replace('"START_AT"', `"${displayStart}"`);
+  template = template.replace('"START_AT"', `"${jsStringEscape(displayStart)}"`);
   template = template.replace('"STORY_SIZE"', `"${count}"`);
   if (template.includes('"STORY"')) {
     template = template.replace('"STORY"', data);
   } else {
     let footer;
     try {
-      footer = readFileSync3(join3(formatDir, "footer.html"), "utf-8");
+      footer = readFileSync2(join3(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://${story.ifid}// --><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://${story.ifid}// --><div id="storeArea"`);
+      template = template.replace('<div id="storeArea"', `<!-- UUID://${safeIfid}// --><div id="storeArea"`);
     }
   }
   return template;
@@ -1445,13 +1502,18 @@ function getTwine1PassageChunk(story) {
   }
   return { data, count };
 }
-function tryReplaceComponent(template, placeholder, componentPath, _required) {
+function tryReplaceComponent(template, placeholder, componentPath, required) {
   if (!template.includes(placeholder)) return template;
   try {
-    let content = readFileSync3(componentPath, "utf-8");
+    let content = readFileSync2(componentPath, "utf-8");
     if (content.charCodeAt(0) === 65279) content = content.slice(1);
     return template.replace(placeholder, content);
-  } catch {
+  } catch (e) {
+    if (required) {
+      throw new Error(
+        `Required format component not found: ${componentPath}: ${e instanceof Error ? e.message : String(e)}`
+      );
+    }
     return template;
   }
 }
@@ -1466,16 +1528,6 @@ function toTwee(story, outMode) {
 }
 
 // src/modules.ts
-import { readFileSync as readFileSync4 } from "fs";
-import { basename as basename2 } from "path";
-function readUTF83(filename) {
-  let content = readFileSync4(filename, "utf-8");
-  if (content.charCodeAt(0) === 65279) content = content.slice(1);
-  return content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-}
-function readBase642(filename) {
-  return readFileSync4(filename).toString("base64");
-}
 function loadModules(filenames) {
   const processed = /* @__PURE__ */ new Set();
   const headTags = [];
@@ -1505,16 +1557,16 @@ function loadModules(filenames) {
   return headTags.join("\n");
 }
 function loadModuleTagged(tag, filename) {
-  const source = readUTF83(filename).trim();
+  const source = readUTF8(filename).trim();
   if (source.length === 0) return null;
-  const family = basename2(filename).split(".")[0];
+  const family = baseNameWithoutExt(filename);
   const idSlug = `${tag}-module-${slugify(family)}`;
   const mimeType = tag === "script" ? "text/javascript" : "text/css";
   return `<${tag} id="${idSlug}" type="${mimeType}">${source}</${tag}>`;
 }
 function loadModuleFont(filename) {
-  const source = readBase642(filename);
-  const family = basename2(filename).split(".")[0];
+  const source = readBase64(filename);
+  const family = baseNameWithoutExt(filename);
   const idSlug = `style-module-${slugify(family)}`;
   const ext = normalizedFileExt(filename);
   const mediaType = mediaTypeFromExt(ext);
@@ -1524,7 +1576,7 @@ function loadModuleFont(filename) {
 	src: url("data:${mediaType};base64,${source}") format("${hint}");
 }</style>`;
 }
-function modifyHead(html, modulePaths, headFile) {
+function modifyHead(html, modulePaths, headFile, diagnostics) {
   const parts = [];
   if (modulePaths.length > 0) {
     const modules = loadModules(modulePaths).trim();
@@ -1532,9 +1584,13 @@ function modifyHead(html, modulePaths, headFile) {
   }
   if (headFile) {
     try {
-      const source = readUTF83(headFile).trim();
+      const source = readUTF8(headFile).trim();
       if (source.length > 0) parts.push(source);
-    } catch {
+    } catch (e) {
+      diagnostics?.push({
+        level: "warning",
+        message: `Failed to read head file "${headFile}": ${e instanceof Error ? e.message : String(e)}`
+      });
     }
   }
   if (parts.length > 0) {
@@ -1545,7 +1601,7 @@ function modifyHead(html, modulePaths, headFile) {
 }
 
 // src/remote-formats.ts
-import { mkdirSync, readFileSync as readFileSync5, writeFileSync, existsSync, readdirSync as readdirSync3, statSync as statSync3 } from "fs";
+import { mkdirSync, readFileSync as readFileSync3, writeFileSync, existsSync, readdirSync as readdirSync3, statSync as statSync3 } from "fs";
 import { join as join4 } from "path";
 import { homedir as homedir2 } from "os";
 var DEFAULT_SFA_INDICES = [
@@ -1561,6 +1617,24 @@ var indexCache = /* @__PURE__ */ new Map();
 function clearIndexCache() {
   indexCache.clear();
 }
+function isValidEntry(val) {
+  if (typeof val !== "object" || val === null || Array.isArray(val)) return false;
+  const obj = val;
+  return typeof obj.name === "string" && typeof obj.version === "string" && typeof obj.checksums === "object" && obj.checksums !== null && !Array.isArray(obj.checksums);
+}
+function validateSFAIndex(json) {
+  if (typeof json !== "object" || json === null) {
+    throw new Error("SFA index is not an object");
+  }
+  const obj = json;
+  const twine1 = Array.isArray(obj["twine1"]) ? obj["twine1"].filter(isValidEntry) : [];
+  const twine2 = Array.isArray(obj["twine2"]) ? obj["twine2"].filter(isValidEntry) : [];
+  return { twine1, twine2 };
+}
+function makeFormatId(name, version) {
+  const major = parseSemver(version)?.[0] ?? "0";
+  return `${name.toLowerCase().replace(/\s+/g, "-")}-${major}`;
+}
 async function fetchIndex(url) {
   const cached = indexCache.get(url);
   if (cached) return cached;
@@ -1568,37 +1642,42 @@ async function fetchIndex(url) {
   if (!res.ok) {
     throw new Error(`Failed to fetch format index from ${url}: ${res.status} ${res.statusText}`);
   }
-  const data = await res.json();
+  const data = validateSFAIndex(await res.json());
   indexCache.set(url, data);
   return data;
 }
 function findEntry(index, name, version) {
   const wanted = parseSemver(version);
-  const entries = [...index.twine2 ?? [], ...index.twine1 ?? []];
-  let bestEntry;
+  const searchArrays = [
+    { entries: index.twine2 ?? [], formatType: "twine2" },
+    { entries: index.twine1 ?? [], formatType: "twine1" }
+  ];
+  let bestResult;
   let bestVersion = null;
-  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;
-    if (wanted === null || have[0] === wanted[0] && semverCompare(have, wanted) >= 0) {
-      if (!bestVersion || semverCompare(have, bestVersion) > 0) {
-        bestVersion = have;
-        bestEntry = entry;
+  for (const { entries, formatType } of searchArrays) {
+    for (const entry of entries) {
+      if (entry.name.toLowerCase() !== name.toLowerCase()) continue;
+      const have = parseSemver(entry.version);
+      if (!have) continue;
+      if (wanted && semverCompare(have, wanted) === 0) return { entry, formatType };
+      if (wanted === null || have[0] === wanted[0] && semverCompare(have, wanted) >= 0) {
+        if (!bestVersion || semverCompare(have, bestVersion) > 0) {
+          bestVersion = have;
+          bestResult = { entry, formatType };
+        }
       }
     }
   }
-  return bestEntry;
+  return bestResult;
 }
 async function verifySHA256(content, expectedHex) {
   const digest = await crypto.subtle.digest("SHA-256", content);
   const hex = Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
   return hex === expectedHex.toLowerCase();
 }
-function getDownloadUrl(indexUrl, entry) {
+function getDownloadUrl(indexUrl, entry, formatType) {
   const base = indexUrl.replace(/\/index\.json$/, "");
-  return `${base}/twine2/${entry.name}/${entry.version}/format.js`;
+  return `${base}/${formatType}/${entry.name}/${entry.version}/format.js`;
 }
 async function fetchAndCacheFormat(entry, downloadUrl) {
   const res = await fetch(downloadUrl);
@@ -1609,13 +1688,14 @@ async function fetchAndCacheFormat(entry, downloadUrl) {
   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}"`);
     const encoder = new TextEncoder();
     const valid = await verifySHA256(encoder.encode(text), expected);
     if (!valid) {
       throw new Error(`Checksum verification failed for ${entry.name} ${entry.version}`);
     }
   }
-  const id = `${entry.name.toLowerCase().replace(/\s+/g, "-")}-${parseSemver(entry.version)?.[0] ?? "0"}`;
+  const id = makeFormatId(entry.name, entry.version);
   const data = parseFormatJSON(text, id);
   if (!data) {
     throw new Error(`Failed to parse format JSON from ${downloadUrl}`);
@@ -1645,7 +1725,7 @@ async function fetchDirectFormat(url) {
   if (!data) {
     throw new Error(`Failed to parse format JSON from ${url}`);
   }
-  const id = `${data.name.toLowerCase().replace(/\s+/g, "-")}-${parseSemver(data.version)?.[0] ?? "0"}`;
+  const id = makeFormatId(data.name, data.version);
   const cacheDir = getCacheDir();
   const formatDir = join4(cacheDir, data.name, data.version);
   mkdirSync(formatDir, { recursive: true });
@@ -1661,6 +1741,7 @@ async function fetchDirectFormat(url) {
   };
 }
 async function resolveRemoteFormat(name, version, indices, urls) {
+  let lastError;
   if (urls) {
     for (const url of urls) {
       try {
@@ -1672,7 +1753,8 @@ async function resolveRemoteFormat(name, version, indices, urls) {
             return info;
           }
         }
-      } catch {
+      } catch (e) {
+        lastError = e instanceof Error ? e : new Error(String(e));
       }
     }
   }
@@ -1680,24 +1762,26 @@ async function resolveRemoteFormat(name, version, indices, urls) {
   for (const indexUrl of allIndices) {
     try {
       const index = await fetchIndex(indexUrl);
-      const entry = findEntry(index, name, version);
-      if (entry) {
-        const cached = getCachedFormat(entry.name, entry.version);
+      const result = findEntry(index, name, version);
+      if (result) {
+        const cached = getCachedFormat(result.entry.name, result.entry.version);
         if (cached) return cached;
-        const downloadUrl = getDownloadUrl(indexUrl, entry);
-        return await fetchAndCacheFormat(entry, downloadUrl);
+        const downloadUrl = getDownloadUrl(indexUrl, result.entry, result.formatType);
+        return await fetchAndCacheFormat(result.entry, downloadUrl);
       }
-    } catch {
+    } catch (e) {
+      lastError = e instanceof Error ? e : new Error(String(e));
     }
   }
+  if (lastError) throw lastError;
   return void 0;
 }
 function getCachedFormat(name, version) {
   const formatPath = join4(getCacheDir(), name, version, "format.js");
   try {
     if (!existsSync(formatPath)) return void 0;
-    const source = readFileSync5(formatPath, "utf-8");
-    const id = `${name.toLowerCase().replace(/\s+/g, "-")}-${parseSemver(version)?.[0] ?? "0"}`;
+    const source = readFileSync3(formatPath, "utf-8");
+    const id = makeFormatId(name, version);
     const data = parseFormatJSON(source, id);
     if (!data) return void 0;
     return {
@@ -1806,18 +1890,12 @@ async function buildOutput(options) {
   loadSources(story, sourceFilenames, { trim, twee2Compat }, diagnostics, processedFiles);
   loadInlineSources(story, inlineSources, { trim, twee2Compat }, diagnostics);
   if (options.tagAliases) {
-    applyTagAliases(story.passages, options.tagAliases);
-  }
-  const fatalErrors = diagnostics.filter((d) => d.level === "error");
-  if (fatalErrors.length > 0 && outputMode === "html") {
+    story.passages = applyTagAliases(story.passages, options.tagAliases);
   }
   let format;
   let formatId = options.formatId ?? "";
   if (outputMode === "html") {
-    const formatSearchDirs = getFormatSearchDirs(
-      options.formatPaths,
-      options.useTweegoPath ?? true
-    );
+    const formatSearchDirs = getFormatSearchDirs(options.formatPaths, options.useTweegoPath ?? true);
     const formats = discoverFormats(formatSearchDirs);
     if (!formatId && story.twine2.format) {
       formatId = getFormatIdByNameAndVersion(formats, story.twine2.format, story.twine2.formatVersion) ?? "";
@@ -1830,13 +1908,12 @@ async function buildOutput(options) {
       const remoteName = story.twine2.format || formatId;
       const remoteVersion = story.twine2.formatVersion || "";
       try {
-        format = await resolveRemoteFormat(
-          remoteName,
-          remoteVersion,
-          options.formatIndices,
-          options.formatUrls
-        );
-      } catch {
+        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) {
@@ -1847,14 +1924,7 @@ async function buildOutput(options) {
       });
     }
   }
-  let startName;
-  if (options.startPassage) {
-    startName = options.startPassage;
-  } else if (story.twine2.start) {
-    startName = story.twine2.start;
-  } else {
-    startName = DEFAULT_START_NAME;
-  }
+  const startName = options.startPassage || story.twine2.start || DEFAULT_START_NAME;
   if (testMode) {
     story.twine2.options.set("debug", true);
   }
@@ -1873,8 +1943,7 @@ async function buildOutput(options) {
     case "json":
       output = storyToJSON(story);
       break;
-    case "html":
-    default: {
+    case "html": {
       if (!storyHas(story, startName)) {
         diagnostics.push({
           level: "error",
@@ -1896,9 +1965,13 @@ async function buildOutput(options) {
         output = toTwine1HTML(story, format, startName, diagnostics);
       }
       const modulePaths = options.modules ? getFilenames(options.modules) : [];
-      output = modifyHead(output, modulePaths, options.headFile);
+      output = modifyHead(output, modulePaths, options.headFile, diagnostics);
       break;
     }
+    default: {
+      const _exhaustive = outputMode;
+      throw new TweeTsError(`Unhandled output mode: ${_exhaustive}`, diagnostics);
+    }
   }
   const stats = {
     ...getStoryStats(story),
@@ -1907,24 +1980,28 @@ async function buildOutput(options) {
   return { output, story, format, diagnostics, stats };
 }
 function storyToJSON(story) {
-  return JSON.stringify({
-    name: story.name,
-    ifid: story.ifid,
-    passages: story.passages.map((p) => ({
-      name: p.name,
-      tags: p.tags,
-      text: p.text,
-      metadata: p.metadata ?? null
-    })),
-    twine2: {
-      format: story.twine2.format,
-      formatVersion: story.twine2.formatVersion,
-      start: story.twine2.start,
-      tagColors: Object.fromEntries(story.twine2.tagColors),
-      options: Object.fromEntries(story.twine2.options),
-      zoom: story.twine2.zoom
-    }
-  }, null, 2);
+  return JSON.stringify(
+    {
+      name: story.name,
+      ifid: story.ifid,
+      passages: story.passages.map((p) => ({
+        name: p.name,
+        tags: p.tags,
+        text: p.text,
+        metadata: p.metadata ?? null
+      })),
+      twine2: {
+        format: story.twine2.format,
+        formatVersion: story.twine2.formatVersion,
+        start: story.twine2.start,
+        tagColors: Object.fromEntries(story.twine2.tagColors),
+        options: Object.fromEntries(story.twine2.options),
+        zoom: story.twine2.zoom
+      }
+    },
+    null,
+    2
+  );
 }
 
 // src/inspect.ts
@@ -2030,7 +2107,7 @@ function storyInspect(story) {
 }
 
 // src/config.ts
-import { readFileSync as readFileSync6, existsSync as existsSync2 } from "fs";
+import { readFileSync as readFileSync4, existsSync as existsSync2 } from "fs";
 import { join as join5 } from "path";
 var CONFIG_FILENAME = "twee-ts.config.json";
 var VALID_OUTPUT_MODES = ["html", "twee3", "twee1", "twine2-archive", "twine1-archive", "json"];
@@ -2040,7 +2117,7 @@ function loadConfig(dir) {
   if (!existsSync2(configPath)) return null;
   let raw;
   try {
-    raw = readFileSync6(configPath, "utf-8");
+    raw = readFileSync4(configPath, "utf-8");
   } catch {
     return null;
   }
@@ -2060,7 +2137,7 @@ function loadConfig(dir) {
 function loadConfigFile(filePath) {
   let raw;
   try {
-    raw = readFileSync6(filePath, "utf-8");
+    raw = readFileSync4(filePath, "utf-8");
   } catch (e) {
     throw new Error(`Cannot read config file ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
   }