@rohal12/twee-ts 1.12.0 → 1.13.0

package/dist/index.d.cts

@@ -54,17 +54,23 @@ interface WatchOptions extends CompileToFileOptions {
     /** Called on build errors. */
     onError?: (error: Error) => void;
 }
-interface Diagnostic {
-    level: 'warning' | 'error';
+type Diagnostic = {
+    level: 'warning';
     message: string;
     file?: string;
     line?: number;
-}
+} | {
+    level: 'error';
+    message: string;
+    file?: string;
+    line?: number;
+    fatal?: boolean;
+};
 interface CompileResult {
     /** The compiled output string (HTML, Twee, JSON, etc.). */
     output: string;
-    /** The parsed story model. */
-    story: Story;
+    /** The parsed story model (read-only after compilation). */
+    story: ReadonlyStory;
     /** The format used for compilation (undefined for non-HTML modes). */
     format?: StoryFormatInfo;
     /** Collected diagnostics. */
@@ -94,6 +100,9 @@ interface Passage {
     metadata?: PassageMetadata;
     source?: SourceLocation;
 }
+type IFID = string & {
+    readonly __brand: 'IFID';
+};
 interface Twine1Metadata {
     settings: Map<string, string>;
 }
@@ -108,12 +117,25 @@ interface Twine2Metadata {
 }
 interface Story {
     name: string;
-    ifid: string;
+    ifid: IFID;
     passages: Passage[];
-    legacyIFID: string;
+    legacyIFID: IFID;
     twine1: Twine1Metadata;
     twine2: Twine2Metadata;
 }
+type ReadonlyPassage = Readonly<Passage> & {
+    readonly tags: readonly string[];
+};
+type ReadonlyStory = Readonly<Omit<Story, 'passages' | 'twine1' | 'twine2'>> & {
+    readonly passages: readonly ReadonlyPassage[];
+    readonly twine1: Readonly<Omit<Twine1Metadata, 'settings'>> & {
+        readonly settings: ReadonlyMap<string, string>;
+    };
+    readonly twine2: Readonly<Omit<Twine2Metadata, 'options' | 'tagColors'>> & {
+        readonly options: ReadonlyMap<string, boolean>;
+        readonly tagColors: ReadonlyMap<string, string>;
+    };
+};
 interface StoryFormatInfo {
     id: string;
     filename: string;
@@ -138,15 +160,16 @@ interface Twine2FormatJSON {
     url?: string;
     license?: string;
 }
-declare const enum ItemType {
-    Error = 0,
-    EOF = 1,
-    Header = 2,
-    Name = 3,
-    Tags = 4,
-    Metadata = 5,
-    Content = 6
-}
+declare const ItemType: {
+    readonly Error: 0;
+    readonly EOF: 1;
+    readonly Header: 2;
+    readonly Name: 3;
+    readonly Tags: 4;
+    readonly Metadata: 5;
+    readonly Content: 6;
+};
+type ItemType = (typeof ItemType)[keyof typeof ItemType];
 interface LexerItem {
     type: ItemType;
     line: number;
@@ -273,7 +296,29 @@ interface BrokenLink {
  * expect(map.deadEnds).not.toContain('Start');
  * ```
  */
-declare function storyInspect(story: Story): StoryMap;
+declare function storyInspect(story: ReadonlyStory): StoryMap;
+
+/**
+ * Story model + StoryData JSON marshal/unmarshal.
+ * Ported from story.go + storydata.go.
+ */
+
+/**
+ * Builder that separates the mutable construction phase from the immutable consumption phase.
+ * During construction, the internal `Story` is mutable via `add()` and direct access.
+ * After `build()`, the story is returned as `ReadonlyStory`.
+ */
+declare class StoryBuilder {
+    /** The mutable story, accessible during construction for loader functions. */
+    readonly story: Story;
+    constructor();
+    /** Add a passage, handling special passages (StoryData, StoryTitle, etc.). */
+    add(passage: Passage, diagnostics: Diagnostic[]): void;
+    /** Check if a passage name exists. */
+    has(name: string): boolean;
+    /** Finalize and return the story as read-only. */
+    build(): ReadonlyStory;
+}
 
 interface DecompileResult {
     story: Story;
@@ -401,7 +446,9 @@ declare function parseSemver(v: string): [number, number, number] | null;
 declare function semverCompare(a: [number, number, number], b: [number, number, number]): number;
 
 /** Generate a new IFID (UUID v4, uppercase). */
-declare function generateIFID(): string;
+declare function generateIFID(): IFID;
+/** Validate and brand an IFID string. Throws on invalid input. */
+declare function createIFID(value: string): IFID;
 /**
  * Validate an IFID string.
  * Accepts both bare UUIDs and UUID://...// wrapped format.
@@ -451,4 +498,4 @@ declare function getCacheSize(): {
     count: number;
 };
 
-export { type BrokenLink, CONFIG_FILENAME, type CachedFormatEntry, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type DecompileResult, type Diagnostic, type FileCacheEntry, type InlineSource, ItemType, type LexerItem, type LintResult, type OutputMode, type Passage, type PassageMetadata, type SFAIndex, type SFAIndexEntry, type SourceInput, type SourceLocation, type Story, type StoryFormatInfo, type StoryMap, TweeLexer, type TweeTsConfig, TweeTsError, type WatchOptions, type WordCountMethod, applyTagAliases, clearCachedFormats, compile, compileIncremental, compileToFile, decompileHTML, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getCacheSize, getFormatSearchDirs, lint, listCachedFormats, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };
+export { type BrokenLink, CONFIG_FILENAME, type CachedFormatEntry, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type DecompileResult, type Diagnostic, type FileCacheEntry, type IFID, type InlineSource, ItemType, type LexerItem, type LintResult, type OutputMode, type Passage, type PassageMetadata, type ReadonlyPassage, type ReadonlyStory, type SFAIndex, type SFAIndexEntry, type SourceInput, type SourceLocation, type Story, StoryBuilder, type StoryFormatInfo, type StoryMap, TweeLexer, type TweeTsConfig, TweeTsError, type WatchOptions, type WordCountMethod, applyTagAliases, clearCachedFormats, compile, compileIncremental, compileToFile, createIFID, decompileHTML, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getCacheSize, getFormatSearchDirs, lint, listCachedFormats, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };

package/dist/index.d.ts

@@ -54,17 +54,23 @@ interface WatchOptions extends CompileToFileOptions {
     /** Called on build errors. */
     onError?: (error: Error) => void;
 }
-interface Diagnostic {
-    level: 'warning' | 'error';
+type Diagnostic = {
+    level: 'warning';
     message: string;
     file?: string;
     line?: number;
-}
+} | {
+    level: 'error';
+    message: string;
+    file?: string;
+    line?: number;
+    fatal?: boolean;
+};
 interface CompileResult {
     /** The compiled output string (HTML, Twee, JSON, etc.). */
     output: string;
-    /** The parsed story model. */
-    story: Story;
+    /** The parsed story model (read-only after compilation). */
+    story: ReadonlyStory;
     /** The format used for compilation (undefined for non-HTML modes). */
     format?: StoryFormatInfo;
     /** Collected diagnostics. */
@@ -94,6 +100,9 @@ interface Passage {
     metadata?: PassageMetadata;
     source?: SourceLocation;
 }
+type IFID = string & {
+    readonly __brand: 'IFID';
+};
 interface Twine1Metadata {
     settings: Map<string, string>;
 }
@@ -108,12 +117,25 @@ interface Twine2Metadata {
 }
 interface Story {
     name: string;
-    ifid: string;
+    ifid: IFID;
     passages: Passage[];
-    legacyIFID: string;
+    legacyIFID: IFID;
     twine1: Twine1Metadata;
     twine2: Twine2Metadata;
 }
+type ReadonlyPassage = Readonly<Passage> & {
+    readonly tags: readonly string[];
+};
+type ReadonlyStory = Readonly<Omit<Story, 'passages' | 'twine1' | 'twine2'>> & {
+    readonly passages: readonly ReadonlyPassage[];
+    readonly twine1: Readonly<Omit<Twine1Metadata, 'settings'>> & {
+        readonly settings: ReadonlyMap<string, string>;
+    };
+    readonly twine2: Readonly<Omit<Twine2Metadata, 'options' | 'tagColors'>> & {
+        readonly options: ReadonlyMap<string, boolean>;
+        readonly tagColors: ReadonlyMap<string, string>;
+    };
+};
 interface StoryFormatInfo {
     id: string;
     filename: string;
@@ -138,15 +160,16 @@ interface Twine2FormatJSON {
     url?: string;
     license?: string;
 }
-declare const enum ItemType {
-    Error = 0,
-    EOF = 1,
-    Header = 2,
-    Name = 3,
-    Tags = 4,
-    Metadata = 5,
-    Content = 6
-}
+declare const ItemType: {
+    readonly Error: 0;
+    readonly EOF: 1;
+    readonly Header: 2;
+    readonly Name: 3;
+    readonly Tags: 4;
+    readonly Metadata: 5;
+    readonly Content: 6;
+};
+type ItemType = (typeof ItemType)[keyof typeof ItemType];
 interface LexerItem {
     type: ItemType;
     line: number;
@@ -273,7 +296,29 @@ interface BrokenLink {
  * expect(map.deadEnds).not.toContain('Start');
  * ```
  */
-declare function storyInspect(story: Story): StoryMap;
+declare function storyInspect(story: ReadonlyStory): StoryMap;
+
+/**
+ * Story model + StoryData JSON marshal/unmarshal.
+ * Ported from story.go + storydata.go.
+ */
+
+/**
+ * Builder that separates the mutable construction phase from the immutable consumption phase.
+ * During construction, the internal `Story` is mutable via `add()` and direct access.
+ * After `build()`, the story is returned as `ReadonlyStory`.
+ */
+declare class StoryBuilder {
+    /** The mutable story, accessible during construction for loader functions. */
+    readonly story: Story;
+    constructor();
+    /** Add a passage, handling special passages (StoryData, StoryTitle, etc.). */
+    add(passage: Passage, diagnostics: Diagnostic[]): void;
+    /** Check if a passage name exists. */
+    has(name: string): boolean;
+    /** Finalize and return the story as read-only. */
+    build(): ReadonlyStory;
+}
 
 interface DecompileResult {
     story: Story;
@@ -401,7 +446,9 @@ declare function parseSemver(v: string): [number, number, number] | null;
 declare function semverCompare(a: [number, number, number], b: [number, number, number]): number;
 
 /** Generate a new IFID (UUID v4, uppercase). */
-declare function generateIFID(): string;
+declare function generateIFID(): IFID;
+/** Validate and brand an IFID string. Throws on invalid input. */
+declare function createIFID(value: string): IFID;
 /**
  * Validate an IFID string.
  * Accepts both bare UUIDs and UUID://...// wrapped format.
@@ -451,4 +498,4 @@ declare function getCacheSize(): {
     count: number;
 };
 
-export { type BrokenLink, CONFIG_FILENAME, type CachedFormatEntry, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type DecompileResult, type Diagnostic, type FileCacheEntry, type InlineSource, ItemType, type LexerItem, type LintResult, type OutputMode, type Passage, type PassageMetadata, type SFAIndex, type SFAIndexEntry, type SourceInput, type SourceLocation, type Story, type StoryFormatInfo, type StoryMap, TweeLexer, type TweeTsConfig, TweeTsError, type WatchOptions, type WordCountMethod, applyTagAliases, clearCachedFormats, compile, compileIncremental, compileToFile, decompileHTML, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getCacheSize, getFormatSearchDirs, lint, listCachedFormats, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };
+export { type BrokenLink, CONFIG_FILENAME, type CachedFormatEntry, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type DecompileResult, type Diagnostic, type FileCacheEntry, type IFID, type InlineSource, ItemType, type LexerItem, type LintResult, type OutputMode, type Passage, type PassageMetadata, type ReadonlyPassage, type ReadonlyStory, type SFAIndex, type SFAIndexEntry, type SourceInput, type SourceLocation, type Story, StoryBuilder, type StoryFormatInfo, type StoryMap, TweeLexer, type TweeTsConfig, TweeTsError, type WatchOptions, type WordCountMethod, applyTagAliases, clearCachedFormats, compile, compileIncremental, compileToFile, createIFID, decompileHTML, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getCacheSize, getFormatSearchDirs, lint, listCachedFormats, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };

package/dist/index.js

@@ -6,6 +6,11 @@ import { randomUUID } from "crypto";
 function generateIFID() {
   return randomUUID().toUpperCase();
 }
+function createIFID(value) {
+  const err = validateIFID(value);
+  if (err) throw new Error(`Invalid IFID: ${err}`);
+  return value.toUpperCase();
+}
 function validateIFID(ifid) {
   let uuid = ifid;
   switch (ifid.length) {
@@ -487,6 +492,25 @@ function getStoryStats(story, wordCountMethod = "tweego") {
   }
   return { passages: story.passages.length, storyPassages, words };
 }
+var StoryBuilder = class {
+  /** The mutable story, accessible during construction for loader functions. */
+  story;
+  constructor() {
+    this.story = createStory();
+  }
+  /** Add a passage, handling special passages (StoryData, StoryTitle, etc.). */
+  add(passage, diagnostics) {
+    storyAdd(this.story, passage, diagnostics);
+  }
+  /** Check if a passage name exists. */
+  has(name) {
+    return storyHas(this.story, name);
+  }
+  /** Finalize and return the story as read-only. */
+  build() {
+    return this.story;
+  }
+};
 
 // src/filesystem.ts
 import { readdirSync, statSync, watch as fsWatch } from "fs";
@@ -910,6 +934,17 @@ function readFormatSource(format) {
 import { basename } from "path";
 import { statSync as statSync3 } from "fs";
 
+// src/types.ts
+var ItemType = {
+  Error: 0,
+  EOF: 1,
+  Header: 2,
+  Name: 3,
+  Tags: 4,
+  Metadata: 5,
+  Content: 6
+};
+
 // src/lexer.ts
 var EOF = -1;
 var HEADER_DELIM = "::";
@@ -942,10 +977,16 @@ var LexerContext = class {
       throw new Error("backup would leave pos < start");
     }
   }
+  // Line-counting invariant: next() increments this.line for each newline during
+  // character-by-character scanning. However, Content items are produced by jumping
+  // this.pos directly (e.g. via indexOf) without calling next(), so those newlines
+  // haven't been counted yet. emit() re-counts newlines in [start, pos) for Content
+  // items to compensate. This is safe because this.start is reset to this.pos after
+  // every emit(), so no range is ever counted twice.
   emit(type) {
     const val = this.input.slice(this.start, this.pos);
     this.items.push({ type, line: this.line, pos: this.start, val });
-    if (type === 6 /* Content */) {
+    if (type === ItemType.Content) {
       for (let i = this.start; i < this.pos; i++) {
         if (this.input.charCodeAt(i) === 10) this.line++;
       }
@@ -966,7 +1007,7 @@ var LexerContext = class {
   }
   errorf(message) {
     this.items.push({
-      type: 0 /* Error */,
+      type: ItemType.Error,
       line: this.line,
       pos: this.start,
       val: message
@@ -1008,7 +1049,7 @@ function lexProlog(ctx) {
     ctx.ignore();
     return lexHeaderDelim;
   }
-  ctx.emit(1 /* EOF */);
+  ctx.emit(ItemType.EOF);
   return null;
 }
 function lexContent(ctx) {
@@ -1018,19 +1059,19 @@ function lexContent(ctx) {
   const i = ctx.input.indexOf(NEWLINE_HEADER_DELIM, ctx.pos);
   if (i > -1) {
     ctx.pos = i + 1;
-    ctx.emit(6 /* Content */);
+    ctx.emit(ItemType.Content);
     return lexHeaderDelim;
   }
   ctx.pos = ctx.input.length;
   if (ctx.pos > ctx.start) {
-    ctx.emit(6 /* Content */);
+    ctx.emit(ItemType.Content);
   }
-  ctx.emit(1 /* EOF */);
+  ctx.emit(ItemType.EOF);
   return null;
 }
 function lexHeaderDelim(ctx) {
   ctx.pos += HEADER_DELIM.length;
-  ctx.emit(2 /* Header */);
+  ctx.emit(ItemType.Header);
   return lexName;
 }
 function lexName(ctx) {
@@ -1059,7 +1100,7 @@ function lexName(ctx) {
         break outer;
     }
   }
-  ctx.emit(3 /* Name */);
+  ctx.emit(ItemType.Name);
   switch (r) {
     case 91:
       return lexTags;
@@ -1076,7 +1117,7 @@ function lexName(ctx) {
       ctx.ignore();
       return lexContent;
   }
-  ctx.emit(1 /* EOF */);
+  ctx.emit(ItemType.EOF);
   return null;
 }
 function lexNextOptionalBlock(ctx) {
@@ -1099,7 +1140,7 @@ function lexNextOptionalBlock(ctx) {
       ctx.ignore();
       return lexContent;
     case EOF:
-      ctx.emit(1 /* EOF */);
+      ctx.emit(ItemType.EOF);
       return null;
   }
   return ctx.errorf(`illegal character '${String.fromCharCode(r)}' amid the optional blocks`);
@@ -1119,7 +1160,7 @@ function lexTags(ctx) {
         if (r === 10) ctx.backup();
         return ctx.errorf("unterminated tag block");
       case 93:
-        if (ctx.pos > ctx.start) ctx.emit(4 /* Tags */);
+        if (ctx.pos > ctx.start) ctx.emit(ItemType.Tags);
         return lexNextOptionalBlock;
       case 91:
         return ctx.errorf(`unexpected left square bracket '['`);
@@ -1152,7 +1193,7 @@ function lexMetadata(ctx) {
       case 125:
         depth--;
         if (depth === 0) {
-          if (ctx.pos > ctx.start) ctx.emit(5 /* Metadata */);
+          if (ctx.pos > ctx.start) ctx.emit(ItemType.Metadata);
           return lexNextOptionalBlock;
         }
         break;
@@ -1182,7 +1223,7 @@ var TweeLexer = class {
   nextItem() {
     const result = this.gen.next();
     if (result.done) {
-      return { item: { type: 1 /* EOF */, line: 0, pos: 0, val: "" }, done: true };
+      return { item: { type: ItemType.EOF, line: 0, pos: 0, val: "" }, done: true };
     }
     return { item: result.value, done: false };
   }
@@ -1219,10 +1260,10 @@ function parseTwee(source, options = {}) {
   const passages = [];
   let current = null;
   let pCount = 0;
-  let lastType = 1 /* EOF */;
+  let lastType = ItemType.EOF;
   for (const item of tweeLexer(source)) {
     switch (item.type) {
-      case 0 /* Error */:
+      case ItemType.Error:
         diagnostics.push({
           level: "error",
           message: `line ${item.line}: Malformed twee source; ${item.val}.`,
@@ -1230,19 +1271,19 @@ function parseTwee(source, options = {}) {
           line: item.line
         });
         return { passages, diagnostics };
-      case 1 /* EOF */:
+      case ItemType.EOF:
         if (pCount > 0 && current) {
           passages.push(current);
         }
         return { passages, diagnostics };
-      case 2 /* Header */:
+      case ItemType.Header:
         pCount++;
         if (pCount > 1 && current) {
           passages.push(current);
         }
         current = { name: "", tags: [], text: "", source: { file: filename, line: item.line } };
         break;
-      case 3 /* Name */: {
+      case ItemType.Name: {
         if (!current) break;
         const name = tweeUnescape(item.val).trim();
         if (name.length === 0) {
@@ -1257,9 +1298,9 @@ function parseTwee(source, options = {}) {
         current.name = name;
         break;
       }
-      case 4 /* Tags */: {
+      case ItemType.Tags: {
         if (!current) break;
-        if (lastType !== 3 /* Name */) {
+        if (lastType !== ItemType.Name) {
           diagnostics.push({
             level: "error",
             message: `line ${item.line}: Malformed twee source; optional tags block must immediately follow the passage name.`,
@@ -1272,9 +1313,9 @@ function parseTwee(source, options = {}) {
         current.tags = tweeUnescape(inner).split(/\s+/).filter(Boolean);
         break;
       }
-      case 5 /* Metadata */: {
+      case ItemType.Metadata: {
         if (!current) break;
-        if (lastType !== 3 /* Name */ && lastType !== 4 /* Tags */) {
+        if (lastType !== ItemType.Name && lastType !== ItemType.Tags) {
           diagnostics.push({
             level: "error",
             message: `line ${item.line}: Malformed twee source; optional metadata block must immediately follow the passage name or tags block.`,
@@ -1306,7 +1347,7 @@ function parseTwee(source, options = {}) {
         }
         break;
       }
-      case 6 /* Content */: {
+      case ItemType.Content: {
         if (!current) break;
         if (trim) {
           current.text = item.val.trim();
@@ -4436,21 +4477,20 @@ var VERSION = "1.2.0";
 
 // src/output-twine2.ts
 var CREATOR_NAME = "Twee-ts";
-function toTwine2Archive(story, startName, diagnostics, options) {
-  return getTwine2DataChunk(story, startName, diagnostics, options) + "\n";
+function toTwine2Archive(story, startName, options) {
+  return getTwine2DataChunk(story, startName, options) + "\n";
 }
-function toTwine2HTML(story, format, startName, diagnostics, options) {
+function toTwine2HTML(story, format, startName, options) {
   let template = readFormatSource(format);
   if (template.includes("{{STORY_NAME}}")) {
     template = template.replaceAll("{{STORY_NAME}}", htmlEscape(story.name));
   }
   if (template.includes("{{STORY_DATA}}")) {
-    template = template.replace("{{STORY_DATA}}", getTwine2DataChunk(story, startName, diagnostics, options));
+    template = template.replace("{{STORY_DATA}}", getTwine2DataChunk(story, startName, options));
   }
   return template;
 }
-function getTwine2DataChunk(story, startName, diagnostics, options) {
-  ensureIFID(story, diagnostics);
+function getTwine2DataChunk(story, startName, options) {
   const parts = [];
   let startID = "";
   let pid = 0;
@@ -4519,23 +4559,6 @@ function getTwine2DataChunk(story, startName, diagnostics, options) {
   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(optionsStr)}" tags="${attrEscape(story.twine2.tags)}" hidden>`;
   return wrapper + parts.join("") + "</tw-storydata>";
 }
-function ensureIFID(story, diagnostics) {
-  if (story.ifid !== "") return;
-  if (story.legacyIFID !== "") {
-    story.ifid = story.legacyIFID;
-    diagnostics.push({
-      level: "warning",
-      message: 'Story IFID not found; reusing "ifid" entry from the "StorySettings" special passage.'
-    });
-  } else {
-    const ifid = generateIFID();
-    story.ifid = ifid;
-    diagnostics.push({
-      level: "error",
-      message: `Story IFID not found. Add an IFID to your story: {"ifid":"${ifid}"}`
-    });
-  }
-}
 
 // src/output-twine1.ts
 import { readFileSync as readFileSync2 } from "fs";
@@ -4546,7 +4569,7 @@ function toTwine1Archive(story, _startName) {
   return `<div id="storeArea" data-size="${count}">${data}</div>
 `;
 }
-function toTwine1HTML(story, format, startName, _diagnostics) {
+function toTwine1HTML(story, format, startName) {
   const formatDir = dirname(format.filename);
   const parentDir = dirname(formatDir);
   let template = readFormatSource(format);
@@ -5103,6 +5126,7 @@ async function buildOutput(options, cache, changedFiles) {
   if (testMode) {
     story.twine2.options.set("debug", true);
   }
+  ensureIFID(story, diagnostics);
   let output;
   switch (outputMode) {
     case "twee3":
@@ -5110,7 +5134,7 @@ async function buildOutput(options, cache, changedFiles) {
       output = toTwee(story, outputMode);
       break;
     case "twine2-archive":
-      output = toTwine2Archive(story, startName, diagnostics, { sourceInfo });
+      output = toTwine2Archive(story, startName, { sourceInfo });
       break;
     case "twine1-archive":
       output = toTwine1Archive(story, startName);
@@ -5129,7 +5153,7 @@ async function buildOutput(options, cache, changedFiles) {
         throw new TweeTsError("No story format available for HTML output.", diagnostics);
       }
       if (format.isTwine2) {
-        output = toTwine2HTML(story, format, startName, diagnostics, { sourceInfo });
+        output = toTwine2HTML(story, format, startName, { sourceInfo });
       } else {
         if (story.name === "" && !storyHas(story, "StoryTitle")) {
           diagnostics.push({
@@ -5137,7 +5161,7 @@ async function buildOutput(options, cache, changedFiles) {
             message: 'Special passage "StoryTitle" not found.'
           });
         }
-        output = toTwine1HTML(story, format, startName, diagnostics);
+        output = toTwine1HTML(story, format, startName);
       }
       const modulePaths = options.modules ? getFilenames(options.modules) : [];
       output = modifyHead(output, modulePaths, options.headFile, diagnostics);
@@ -5154,6 +5178,23 @@ async function buildOutput(options, cache, changedFiles) {
   };
   return { output, story, format, diagnostics, stats };
 }
+function ensureIFID(story, diagnostics) {
+  if (story.ifid !== "") return;
+  if (story.legacyIFID !== "") {
+    story.ifid = story.legacyIFID;
+    diagnostics.push({
+      level: "warning",
+      message: 'Story IFID not found; reusing "ifid" entry from the "StorySettings" special passage.'
+    });
+  } else {
+    const ifid = generateIFID();
+    story.ifid = ifid;
+    diagnostics.push({
+      level: "error",
+      message: `Story IFID not found. Add an IFID to your story: {"ifid":"${ifid}"}`
+    });
+  }
+}
 function storyToJSON(story) {
   const scripts = [];
   const stylesheets = [];
@@ -5474,6 +5515,8 @@ function scaffoldConfig() {
 }
 export {
   CONFIG_FILENAME,
+  ItemType,
+  StoryBuilder,
   TweeLexer,
   TweeTsError,
   applyTagAliases,
@@ -5481,6 +5524,7 @@ export {
   compile,
   compileIncremental,
   compileToFile,
+  createIFID,
   decompileHTML,
   discoverCachedFormats,
   discoverFormats,