@rohal12/twee-ts 1.12.0 → 1.13.1

package/dist/index.cjs

@@ -21,6 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   CONFIG_FILENAME: () => CONFIG_FILENAME,
+  ItemType: () => ItemType,
+  StoryBuilder: () => StoryBuilder,
   TweeLexer: () => TweeLexer,
   TweeTsError: () => TweeTsError,
   applyTagAliases: () => applyTagAliases,
@@ -28,6 +30,7 @@ __export(src_exports, {
   compile: () => compile,
   compileIncremental: () => compileIncremental,
   compileToFile: () => compileToFile,
+  createIFID: () => createIFID,
   decompileHTML: () => decompileHTML,
   discoverCachedFormats: () => discoverCachedFormats,
   discoverFormats: () => discoverFormats,
@@ -64,6 +67,11 @@ var import_node_crypto = require("crypto");
 function generateIFID() {
   return (0, import_node_crypto.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) {
@@ -545,6 +553,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
 var import_node_fs = require("fs");
@@ -968,6 +995,17 @@ function readFormatSource(format) {
 var import_node_path5 = require("path");
 var import_node_fs4 = require("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 = "::";
@@ -1000,10 +1038,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++;
       }
@@ -1024,7 +1068,7 @@ var LexerContext = class {
   }
   errorf(message) {
     this.items.push({
-      type: 0 /* Error */,
+      type: ItemType.Error,
       line: this.line,
       pos: this.start,
       val: message
@@ -1066,7 +1110,7 @@ function lexProlog(ctx) {
     ctx.ignore();
     return lexHeaderDelim;
   }
-  ctx.emit(1 /* EOF */);
+  ctx.emit(ItemType.EOF);
   return null;
 }
 function lexContent(ctx) {
@@ -1076,19 +1120,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) {
@@ -1117,7 +1161,7 @@ function lexName(ctx) {
         break outer;
     }
   }
-  ctx.emit(3 /* Name */);
+  ctx.emit(ItemType.Name);
   switch (r) {
     case 91:
       return lexTags;
@@ -1134,7 +1178,7 @@ function lexName(ctx) {
       ctx.ignore();
       return lexContent;
   }
-  ctx.emit(1 /* EOF */);
+  ctx.emit(ItemType.EOF);
   return null;
 }
 function lexNextOptionalBlock(ctx) {
@@ -1157,7 +1201,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`);
@@ -1177,7 +1221,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 '['`);
@@ -1210,7 +1254,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;
@@ -1240,7 +1284,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 };
   }
@@ -1277,10 +1321,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}.`,
@@ -1288,19 +1332,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) {
@@ -1315,9 +1359,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.`,
@@ -1330,9 +1374,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.`,
@@ -1364,7 +1408,7 @@ function parseTwee(source, options = {}) {
         }
         break;
       }
-      case 6 /* Content */: {
+      case ItemType.Content: {
         if (!current) break;
         if (trim) {
           current.text = item.val.trim();
@@ -4494,21 +4538,22 @@ 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));
+    const name = htmlEscape(story.name);
+    template = template.replaceAll("{{STORY_NAME}}", () => name);
   }
   if (template.includes("{{STORY_DATA}}")) {
-    template = template.replace("{{STORY_DATA}}", getTwine2DataChunk(story, startName, diagnostics, options));
+    const data = getTwine2DataChunk(story, startName, options);
+    template = template.replace("{{STORY_DATA}}", () => data);
   }
   return template;
 }
-function getTwine2DataChunk(story, startName, diagnostics, options) {
-  ensureIFID(story, diagnostics);
+function getTwine2DataChunk(story, startName, options) {
   const parts = [];
   let startID = "";
   let pid = 0;
@@ -4577,23 +4622,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
 var import_node_fs5 = require("fs");
@@ -4604,7 +4632,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 = (0, import_node_path6.dirname)(format.filename);
   const parentDir = (0, import_node_path6.dirname)(formatDir);
   let template = readFormatSource(format);
@@ -4622,10 +4650,11 @@ function toTwine1HTML(story, format, startName, _diagnostics) {
   const displayStart = startName === "Start" ? "" : startName;
   template = template.replace('"VERSION"', `Compiled with ${CREATOR_NAME2}, ${VERSION}`);
   template = template.replace('"TIME"', `Built on ${(/* @__PURE__ */ new Date()).toUTCString()}`);
-  template = template.replace('"START_AT"', `"${jsStringEscape(displayStart)}"`);
+  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);
+    template = template.replace('"STORY"', () => data);
   } else {
     let footer;
     try {
@@ -4661,7 +4690,7 @@ function tryReplaceComponent(template, placeholder, componentPath, required) {
   try {
     let content = (0, import_node_fs5.readFileSync)(componentPath, "utf-8");
     if (content.charCodeAt(0) === 65279) content = content.slice(1);
-    return template.replace(placeholder, content);
+    return template.replace(placeholder, () => content);
   } catch (e) {
     if (required) {
       throw new Error(
@@ -4749,7 +4778,8 @@ function modifyHead(html, modulePaths, headFile, diagnostics) {
   }
   if (parts.length > 0) {
     parts.push("</head>");
-    return html.replace("</head>", parts.join("\n"));
+    const replacement = parts.join("\n");
+    return html.replace("</head>", () => replacement);
   }
   return html;
 }
@@ -5161,6 +5191,7 @@ async function buildOutput(options, cache, changedFiles) {
   if (testMode) {
     story.twine2.options.set("debug", true);
   }
+  ensureIFID(story, diagnostics);
   let output;
   switch (outputMode) {
     case "twee3":
@@ -5168,7 +5199,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);
@@ -5187,7 +5218,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({
@@ -5195,7 +5226,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);
@@ -5212,6 +5243,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 = [];
@@ -5533,6 +5581,8 @@ function scaffoldConfig() {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CONFIG_FILENAME,
+  ItemType,
+  StoryBuilder,
   TweeLexer,
   TweeTsError,
   applyTagAliases,
@@ -5540,6 +5590,7 @@ function scaffoldConfig() {
   compile,
   compileIncremental,
   compileToFile,
+  createIFID,
   decompileHTML,
   discoverCachedFormats,
   discoverFormats,