@rohal12/twee-ts 1.18.2 → 2.1.0

package/dist/index.d.cts

@@ -1,333 +1,62 @@
-//#region src/types.d.ts
+
+import { A as StoryFormatInfo, C as RemoteResolveOptions, D as SourceInput, E as SemVer, F as Twine2Metadata, I as WatchOptions, L as WordCountMethod, M as TweeTsErrorCode, N as Twine1Metadata, O as SourceLocation, P as Twine2FormatJSON, S as RemoteFetchOptions, T as SFAIndexEntry, _ as PassageMetadata, a as DecompileOptions, b as ReadonlyPassage, c as FileCacheEntry, d as InspectOptions, f as ItemType, g as Passage, h as OutputMode, i as CompileToFileOptions, j as TweeTsConfig, k as Story, l as IFID, m as OmittingTag, n as CompileResult, o as Diagnostic, p as LexerItem, r as CompileStats, s as ExcludeGlob, t as CompileOptions, u as InlineSource, v as PassageOmission, w as SFAIndex, x as ReadonlyStory, y as PassageOutputTarget } from "./types-BvI6pg2y.cjs";
+//#region src/filesystem.d.ts
 /**
- * All public interfaces for twee-ts.
+ * A watched path that can't be watched: fs.watch failed on it, or on the folder it is
+ * watched through. watchFilesystem passes it to its `onError` and keeps watching the rest.
  */
-type OutputMode = 'html' | 'twee3' | 'twee1' | 'twine2-archive' | 'twine1-archive' | 'json';
-type WordCountMethod = 'tweego' | 'whitespace';
-type InlineSource = {
-  filename: string;
-  content: string | Buffer;
-};
-type SourceInput = string | InlineSource;
-interface CompileOptions {
-  /**
-   * Files, directories, or inline sources to compile. Directories are walked
-   * recursively; inside one, a symbolic link to a file is read, but a link to a
-   * directory is not followed (as in Tweego).
-   */
-  sources: readonly SourceInput[];
-  /**
-   * Glob patterns for files to leave out of `sources`, matched against each file's
-   * path relative to the working directory (as `stats.files` lists it). Modules are not affected.
-   */
-  exclude?: readonly string[];
-  /** Output mode. Default: 'html'. */
-  outputMode?: OutputMode;
-  /** Story format directory ID (e.g. 'sugarcube-2'). */
-  formatId?: string;
-  /** Name of the starting passage. Default: 'Start'. */
-  startPassage?: string;
-  /** Extra directories to search for story formats. */
-  formatPaths?: readonly string[];
-  /** Also search TWEEGO_PATH env for formats. Default: true. */
-  useTweegoPath?: boolean;
-  /** Module files to inject into <head>. */
-  modules?: readonly string[];
-  /** Raw HTML file to append to <head>. */
-  headFile?: string;
-  /** Trim passage whitespace. Default: true. */
-  trim?: boolean;
-  /** Twee2 compatibility mode. Default: false. */
-  twee2Compat?: boolean;
-  /** Enable debug/test mode option. Default: false. */
-  testMode?: boolean;
-  /** URLs to SFA-compatible index.json files for remote format lookup. */
-  formatIndices?: readonly string[];
-  /**
-   * Direct URLs to format.js files. Each URL's download is cached under that URL, and is
-   * looked up before the downloads shared by name and version.
-   */
-  formatUrls?: readonly string[];
-  /** Disable remote format fetching. Default: false. */
-  noRemote?: boolean;
-  /**
-   * Cancels the compile. Story format requests still in progress are aborted, and the compile
-   * rejects with the signal's reason. `watch()` aborts its builds, and stops watching, when it aborts.
-   */
-  signal?: AbortSignal;
-  /**
-   * Milliseconds each story format request (an index or a format.js) may take before it fails
-   * with a warning and the next source is tried. 0 turns the limit off. Default: 30000.
-   */
-  formatFetchTimeout?: number;
-  /** Map alias tags to canonical special tags (e.g. { library: 'script' }). */
-  tagAliases?: Record<string, string>;
-  /** Emit source file and line as data- attributes on passage elements. Default: false. */
-  sourceInfo?: boolean;
-  /** Word counting method. Default: 'tweego'. */
-  wordCountMethod?: WordCountMethod;
-}
-interface CompileToFileOptions extends CompileOptions {
-  /**
-   * Output file path. It is never read as a source, even inside a source folder or
-   * reached through a symbolic link. Naming it as a source, a module or the head
-   * file is a TweeTsError, and nothing is written.
-   */
-  outFile: string;
+export declare class WatchPathError extends Error {
+  readonly path: string;
+  constructor(path: string, cause: unknown);
 }
-interface WatchOptions extends CompileToFileOptions {
-  /**
-   * Called after each build is written, including one whose diagnostics report errors. Builds
-   * run one at a time and are reported in order, each as it finishes, also while changes keep
-   * arriving: the changes made during a build go into one follow-up build after it.
-   */
-  onBuild?: (result: CompileResult) => void;
-  /**
-   * Called when a build fails with a fatal error (nothing is written), when `onBuild` throws,
-   * and when a watched path can't be watched (the other paths are still watched). An exception
-   * thrown here is reported to the console, and watching goes on.
-   */
-  onError?: (error: Error) => void;
-}
-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 (read-only after compilation). */
-  story: ReadonlyStory;
-  /** The format used for compilation (undefined for non-HTML modes). */
-  format?: StoryFormatInfo;
-  /** Collected diagnostics. */
-  diagnostics: Diagnostic[];
-  /** Compilation statistics. */
-  stats: CompileStats;
-}
-interface CompileStats {
-  passages: number;
-  storyPassages: number;
-  words: number;
-  files: string[];
-}
-interface SourceLocation {
-  readonly file: string;
-  readonly line: number;
-}
-interface PassageMetadata {
-  position?: string;
-  size?: string;
-  [key: string]: string | undefined;
-}
-interface Passage {
-  name: string;
-  tags: string[];
-  text: string;
-  metadata?: PassageMetadata;
-  source?: SourceLocation;
-}
-type IFID = string & {
-  readonly __brand: 'IFID';
-};
-interface Twine1Metadata {
-  settings: Map<string, string>;
-}
-interface Twine2Metadata {
-  format: string;
-  formatVersion: string;
-  options: Map<string, boolean>;
-  start: string;
-  tags: string;
-  tagColors: Map<string, string>;
-  zoom: number;
-}
-interface Story {
-  name: string;
-  ifid: IFID;
-  passages: Passage[];
-  legacyIFID: IFID;
-  twine1: Twine1Metadata;
-  twine2: Twine2Metadata;
-}
-type ReadonlyPassage = Readonly<Omit<Passage, 'tags' | 'metadata'>> & {
-  readonly tags: readonly string[];
-  readonly metadata?: Readonly<PassageMetadata>;
-};
-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>;
-  };
-};
-type OmittingTag = 'Twine.private' | 'script' | 'stylesheet';
-type PassageOmission = {
-  readonly kind: 'special-name';
-  readonly name: 'StoryData' | 'StoryTitle';
-} | {
-  readonly kind: 'tag';
-  readonly tag: OmittingTag;
-} | {
-  readonly kind: 'empty-story-settings';
-};
-/** The output whose rules decide which passages a story emits as passages. */
-type PassageOutputTarget = 'twine1' | 'twine2';
-interface DecompileOptions {
-  /**
-   * Trim whitespace at both ends of passage text (and of the Twine 2 story stylesheet and script),
-   * as the Twee lexer does. When false, the stored text is kept exactly. Default: true.
-   */
-  readonly trim?: boolean;
-}
-interface InspectOptions {
-  /**
-   * Check link destinations against this output's passage rules. A link to a passage that the
-   * output leaves out (in Twine 2: `script`, `stylesheet` and `Twine.private` passages,
-   * StoryData, StoryTitle and an empty StorySettings; in Twine 1: `Twine.private` passages) is
-   * then a broken link, and says why. The passages it leaves out also give no links, as their
-   * text never reaches the player, except script passages, which Twine 2 output runs. Without a
-   * target, every source passage gives links, and a link is broken only when no passage has its
-   * name.
-   */
-  readonly target?: PassageOutputTarget;
-}
-interface StoryFormatInfo {
-  id: string;
-  filename: string;
-  isTwine2: boolean;
-  name: string;
-  version: string;
-  proofing: boolean;
-  author?: string;
-  description?: string;
-  image?: string;
-  url?: string;
-  license?: string;
-}
-interface Twine2FormatJSON {
-  name: string;
-  version: string;
-  proofing?: boolean;
-  source: string;
-  author?: string;
-  description?: string;
-  image?: string;
-  url?: string;
-  license?: string;
-}
-export declare const ItemType: {
-  readonly Error: 0;
-  readonly EOF: 1;
-  readonly Header: 2;
-  readonly Name: 3;
-  readonly Tags: 4;
-  readonly Metadata: 5;
-  readonly Content: 6;
-};
-export type ItemType = (typeof ItemType)[keyof typeof ItemType];
-interface LexerItem {
-  type: ItemType;
-  line: number;
-  pos: number;
-  val: string;
-}
-interface SFAIndexEntry {
-  name: string;
-  version: string;
-  proofing: boolean;
-  files: string[];
-  checksums: Record<string, string>;
-}
-interface SFAIndex {
-  twine1: SFAIndexEntry[];
-  twine2: SFAIndexEntry[];
-}
-/** Options for the network requests that fetch story formats and their indices. */
-interface RemoteFetchOptions {
-  /** Aborts the requests; the call then rejects with the signal's reason. */
-  readonly signal?: AbortSignal;
-  /** Milliseconds each request may take before it fails. 0 turns the limit off. Default: 30000. */
-  readonly timeout?: number;
-}
-interface FileCacheEntry {
-  readonly mtimeMs: number;
-  /**
-   * Identity of the parse options (`trim`, `twee2Compat`) the entry was parsed with. An entry is
-   * reused only when this matches the current options; an entry without it is treated as stale
-   * and reparsed. The value is opaque: leave it to twee-ts to set.
-   */
-  readonly parseOptionsKey?: string;
-  readonly passages: readonly Passage[];
+//#endregion
+//#region src/errors.d.ts
+/**
+ * A build that could not run: nothing was built or written. `code` says why (see TweeTsErrorCode),
+ * `diagnostics` holds what the build reported before it stopped, and `cause` the error behind it, if any.
+ */
+export declare class TweeTsError extends Error {
   readonly diagnostics: readonly Diagnostic[];
-}
-interface TweeTsConfig {
-  sources?: string[];
-  exclude?: string[];
-  output?: string;
-  outputMode?: OutputMode;
-  formatId?: string;
-  startPassage?: string;
-  formatPaths?: string[];
-  formatIndices?: string[];
-  formatUrls?: string[];
-  useTweegoPath?: boolean;
-  modules?: string[];
-  headFile?: string;
-  trim?: boolean;
-  twee2Compat?: boolean;
-  testMode?: boolean;
-  noRemote?: boolean;
-  /** Milliseconds each story format request may take. 0 turns the limit off. Default: 30000. */
-  formatFetchTimeout?: number;
-  tagAliases?: Record<string, string>;
-  sourceInfo?: boolean;
-  wordCountMethod?: WordCountMethod;
+  readonly code: TweeTsErrorCode;
+  constructor(message: string, diagnostics?: readonly Diagnostic[], options?: {
+    readonly code?: TweeTsErrorCode;
+    readonly cause?: unknown;
+  });
 }
 //#endregion
 //#region src/compiler.d.ts
-export declare class TweeTsError extends Error {
-  diagnostics: Diagnostic[];
-  constructor(message: string, diagnostics?: Diagnostic[]);
-}
 /**
  * Compile Twee sources to HTML, Twee, or JSON.
  */
 export declare function compile(options: CompileOptions): Promise<CompileResult>;
 /**
- * Compile and write to a file. The file is replaced atomically: a reader sees the previous
- * build or the new one, never part of it, and a failed write leaves the previous build.
+ * Compile and write to a file. How the file is written depends on what is there (see atomic-write.ts): a
+ * regular file is replaced atomically, so a reader sees the previous build or the new one, never part of it,
+ * and a failed write leaves the previous build; a FIFO or a device is written through; a read-only file is
+ * refused. An output that can't be written (a read-only file, a missing folder) fails before the build.
  */
 export declare function compileToFile(options: CompileToFileOptions): Promise<CompileResult>;
 /**
  * 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 is always reparsed, whatever its modification time, and every
+ * Without `changedFiles`, a cached file is reused while its modification time, size, inode and
+ * status-change time are unchanged. With it, a file it names is always reparsed, and every
  * other cached file is reused as it is. A file may be named by an absolute path or by a path
- * relative to the working directory, with or without a leading `./`: entries are matched to
- * the source files by resolved path. A file that fails to load is dropped from the cache, so
- * the next build tries it again.
+ * relative to the working directory, with or without a leading `./`, or through a link: entries are
+ * matched to the source files by identity (see path-identity.ts). A file that fails to load is
+ * dropped from the cache, so the next build tries it again.
  */
 export declare function compileIncremental(options: CompileOptions, cache: Map<string, FileCacheEntry>, changedFiles?: ReadonlySet<string>): Promise<CompileResult>;
 /**
- * Watch for file changes and recompile. Every build is written to `outFile` (replacing it
- * atomically, as compileToFile() does), including one whose diagnostics report errors.
- * Builds run one at a time, and each one is written and reported as it finishes, in order:
- * changes made during a build go into one follow-up build after it. A watched path that
- * can't be watched is passed to `onError`.
+ * Watch for file changes and recompile. Every build is written to `outFile` (as compileToFile()
+ * writes it), including one whose diagnostics report errors. Builds run one at a time, and each
+ * one is written and reported as it finishes, in order: changes made during a build go into one
+ * follow-up build after it. A watched path that can't be watched is passed to `onError`.
+ *
+ * Options that can't work (an output that is also a named input or an authored file in a source or module
+ * folder, an out-of-range option) reject the returned promise before anything is watched. A build that fails for such a reason later (a link
+ * changed to make the output an input) is passed to `onError`, and watching stops.
  *
  * Aborting the returned controller, or the `signal` in the options, stops watching and
  * aborts the story format requests of the build in progress.
@@ -337,48 +66,56 @@ export declare function watch(options: WatchOptions): Promise<AbortController>;
 //#region src/inspect.d.ts
 interface StoryMap {
   /** All passage names, in source order. */
-  passages: string[];
+  readonly passages: readonly string[];
   /** Only story passages (excludes StoryData, StoryTitle, scripts, stylesheets, etc.). */
-  storyPassages: string[];
+  readonly storyPassages: readonly string[];
   /** Only info/special passages. */
-  infoPassages: string[];
+  readonly infoPassages: readonly string[];
   /** All unique tags used across the story, sorted alphabetically. */
-  tags: string[];
+  readonly tags: readonly string[];
   /** Map of tag → passage names that carry that tag, each listed once even if the tag is repeated. */
-  passagesByTag: Map<string, string[]>;
+  readonly passagesByTag: ReadonlyMap<string, readonly string[]>;
   /** Map of passage name → tags on that passage, as written (a repeated tag appears twice). */
-  tagsByPassage: Map<string, string[]>;
+  readonly tagsByPassage: ReadonlyMap<string, readonly string[]>;
   /**
    * Map of passage name → passage names it links to.
    * Parses `[[target]]`, `[[display->target]]`, `[[target<-display]]`, `[[display|target]]`,
-   * each with or without a setter (`[[display|target][$x to 1]]`), and SugarCube's
-   * `<<goto "target">>` / `<<link "display" "target">>`, read as SugarCube 2 reads them
-   * (see `sugarcube-macros.ts`). Links and calls in comments are not read. A script passage is
+   * each with or without a setter (`[[display|target][$x to 1]]`), SugarCube's
+   * `<<goto "target">>` / `<<link "display" "target">>` / `<<button "display" "target">>`, and
+   * elements with a `data-passage="target"` attribute, read as SugarCube 2 reads them
+   * (see "How links are read" in docs/api.md). Links and calls in comments are not read. A script passage is
    * read for links only in its strings; a stylesheet passage (including a loaded `.css` file) is
    * CSS and links to nothing. With a `target` (see `InspectOptions`), a passage that output leaves
    * out links to nothing, except a script passage, which Twine 2 output runs.
    */
-  links: Map<string, string[]>;
+  readonly links: ReadonlyMap<string, readonly string[]>;
   /**
    * Broken links: `{ from, to }` pairs where `to` doesn't exist as a passage, or, with a `target`
    * (see `InspectOptions`), where that output leaves the `to` passage out (`omission` says why).
    */
-  brokenLinks: BrokenLink[];
+  readonly brokenLinks: readonly BrokenLink[];
   /** Story passages with no outgoing links (potential dead ends). */
-  deadEnds: string[];
-  /** Story passages that no other passage links to (excluding the start passage). */
-  orphans: string[];
+  readonly deadEnds: readonly string[];
+  /**
+   * Story passages that the player cannot reach: no chain of links leads to them from the start passage or
+   * from an info passage the story format runs or shows without a link (such as StoryInit, PassageHeader, or a
+   * `script` or `widget` passage). An `annotation` note, a `Twine.` passage (private or media), StoryData,
+   * StorySettings and StoryIncludes are not shown, so links from them count only when a link leads to them. A
+   * passage that links only to itself, or a group that links only among itself, is an orphan. Only the links
+   * `links` lists count, so a passage that is shown only through a macro such as `<<include>>` is listed too.
+   */
+  readonly orphans: readonly string[];
   /** The configured start passage name, if any. */
-  start: string;
+  readonly start: string;
 }
 interface BrokenLink {
-  from: string;
-  to: string;
+  readonly from: string;
+  readonly to: string;
   /**
    * Set when a passage named `to` exists, but the inspected output leaves it out of the story
    * (only with a `target`): why it is left out. Absent when no passage has the name.
    */
-  omission?: PassageOmission;
+  readonly omission?: PassageOmission;
 }
 /**
  * Inspect a story and return its full structural map.
@@ -407,24 +144,53 @@ export declare function storyInspect(story: ReadonlyStory, options?: InspectOpti
 //#endregion
 //#region src/story.d.ts
 /**
- * Builder that separates the mutable construction phase from the immutable consumption phase.
- * During construction, the internal `Story` is mutable via `add()` and direct access: you may
- * push, splice, sort, rename or reassign `story.passages` between calls, and `add()` and `has()`
- * see the passages as they are then.
- * After `build()`, the story is returned as `ReadonlyStory`.
+ * Builds a story from passages, as the compiler does: duplicates replace earlier passages (with a warning),
+ * and the special passages StoryTitle, StoryData and StorySettings decide the story metadata.
+ *
+ * The story is changed only through the builder's methods, so its passage list, its name lookups and its
+ * metadata always agree. Passages are copied in and out: changing a passage object after `add()`, or one that
+ * `get()`, `passages` or `build()` returned, does not change the builder.
  */
 export 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.). */
+  #private;
+  /** Add a passage, handling special passages (StoryData, StoryTitle, etc.) and duplicates. */
   add(passage: Passage, diagnostics: Diagnostic[]): void;
-  /** Check if a passage name exists. */
+  /** Whether a passage has this name. */
   has(name: string): boolean;
-  /** Finalize and return the story as read-only. */
+  /** The passage with this name (a frozen copy), or undefined. */
+  get(name: string): ReadonlyPassage | undefined;
+  /**
+   * Remove the passage with this name, and with it the metadata it decided (removing StoryData clears the
+   * IFID, format and start). Returns false when no passage has the name.
+   */
+  remove(name: string): boolean;
+  /**
+   * Rename a passage, keeping its place in the story. A passage that already has the new name is replaced,
+   * with a warning, as a duplicate would be. Returns false when no passage has the old name.
+   */
+  rename(from: string, to: string, diagnostics: Diagnostic[]): boolean;
+  /** The passages, in order (frozen copies). */
+  get passages(): readonly ReadonlyPassage[];
+  /** The story as it is now, as a frozen copy that later changes to the builder do not reach. */
   build(): ReadonlyStory;
 }
 //#endregion
+//#region src/start-passage.d.ts
+/**
+ * Synchronously check that `startName` names a passage the `target` output emits.
+ * By default, use the story's effective start, falling back to `Start`, and Twine 2 rules.
+ * An explicit name overrides the metadata for this check only; the story is never changed.
+ * Returns the compiler's error diagnostics (empty when the start is usable).
+ */
+export declare function startPassageDiagnostics(story: ReadonlyStory, startName?: string, target?: PassageOutputTarget): readonly Diagnostic[];
+//#endregion
+//#region src/passage-omission.d.ts
+/**
+ * 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).
+ */
+export declare function passageOmission(story: ReadonlyStory, passage: ReadonlyPassage, target: PassageOutputTarget): PassageOmission | undefined;
+//#endregion
 //#region src/html-parser.d.ts
 interface DecompileResult {
   story: Story;
@@ -441,36 +207,40 @@ export declare function decompileHTML(html: string, options?: DecompileOptions):
 //#region src/lint.d.ts
 interface LintResult {
   /** Compilation diagnostics (errors and warnings). */
-  diagnostics: Diagnostic[];
+  readonly diagnostics: readonly Diagnostic[];
   /** Compilation statistics. */
-  stats: CompileStats;
+  readonly stats: CompileStats;
   /** Story format name from StoryData (e.g. "SugarCube"). */
-  formatName: string;
+  readonly formatName: string;
   /** Story format version from StoryData (e.g. "2.37.3"). */
-  formatVersion: string;
+  readonly formatVersion: string;
   /** The configured start passage name. */
-  start: string;
+  readonly start: string;
   /** Total passage count. */
-  passages: number;
+  readonly passages: number;
   /** Story passage count (excludes StoryData, StoryTitle, scripts, etc.). */
-  storyPassages: number;
+  readonly storyPassages: number;
   /** Info/special passage count. */
-  infoPassages: number;
+  readonly infoPassages: number;
   /**
    * Broken links: link targets that don't exist as passages, or that Twine 2 output leaves out
    * (script, stylesheet and `Twine.private` passages, StoryData, StoryTitle, an empty
    * StorySettings); for those, `omission` says why.
    */
-  brokenLinks: BrokenLink[];
+  readonly brokenLinks: readonly BrokenLink[];
   /** Story passages with no outgoing links. */
-  deadEnds: string[];
-  /** Story passages that no other passage links to. */
-  orphans: string[];
+  readonly deadEnds: readonly string[];
+  /**
+   * Story passages the player cannot reach: no chain of links leads to them from the start passage or from
+   * an info passage the story format runs or shows without a link (see `StoryMap.orphans`).
+   */
+  readonly orphans: readonly string[];
 }
 /**
  * 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. Link
+ * the starting passage itself, against the Twine 2 passage rules, and adds
+ * what Twine 2 HTML output reports about the story's own data. 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.
@@ -483,11 +253,15 @@ export declare function formatLintReport(result: LintResult): string;
 //#endregion
 //#region src/passage.d.ts
 /**
- * Apply tag aliases: for each passage carrying an alias tag, add the canonical
- * tag if not already present. Returns new passage objects where tags changed;
- * unchanged passages are returned as-is. Idempotent — safe to call multiple times.
+ * Apply tag aliases: for each passage carrying an alias tag, add the canonical tag if not already present. A
+ * canonical tag that is itself an alias is followed (`{ a: 'b', b: 'c' }` adds `b` and `c` to a passage tagged
+ * `a`), until no mapping adds anything, so cycles and self-mappings end too. Authored tags are kept as written (a
+ * tag written twice stays twice, as in Tweego), whether or not an alias applies; added tags follow in the order they
+ * were reached, and none repeats a tag already there. Returns new passage objects where tags changed; unchanged
+ * passages are returned as-is. Idempotent: the result carries every tag the mappings reach, so applying the same
+ * aliases again adds nothing.
  */
-export declare function applyTagAliases(passages: readonly Passage[], aliases: Record<string, string>): Passage[];
+export declare function applyTagAliases(passages: readonly Passage[], aliases: Readonly<Record<string, string>>): Passage[];
 //#endregion
 //#region src/lexer.d.ts
 /**
@@ -511,11 +285,14 @@ export declare class TweeLexer {
 //#region src/parser.d.ts
 interface ParseOptions {
   /** Filename for diagnostics. */
-  filename?: string;
-  /** Trim whitespace from passage content. Default: true. */
-  trim?: boolean;
+  filename?: string | undefined;
+  /**
+   * Trim white space at both ends of passage content. Default: true. When false, the content is kept as
+   * written except for its trailing blank lines, which the Twee 3 specification requires a reader to drop.
+   */
+  trim?: boolean | undefined;
   /** Enable Twee2 compatibility. Default: false. */
-  twee2Compat?: boolean;
+  twee2Compat?: boolean | undefined;
 }
 interface ParseResult {
   passages: Passage[];
@@ -524,25 +301,20 @@ interface ParseResult {
 /**
  * Parse Twee source text into passages.
  *
- * The source is normalized first, as files are when they are read: a leading UTF-8 BOM is
- * removed and CRLF and bare CR line endings become LF. A BOM at the start of a later line,
- * directly before `::` (left there by concatenating files), is removed too, so that line
- * stays a passage header.
+ * The source is normalized first (see `normalizeTweeSource`): a leading UTF-8 BOM is removed, CRLF and bare CR
+ * line endings become LF, and a BOM at the start of a later line, directly before `::` (left there by
+ * concatenating files), is removed too, so that line stays a passage header.
+ *
+ * Names and tags are read as Tweego reads them: unescaped, then the name trimmed and the tags split at white
+ * space, where white space is Go's `unicode.IsSpace` (see `isTweeSpace`).
  */
 export declare function parseTwee(source: string, options?: ParseOptions): ParseResult;
 //#endregion
 //#region src/formats.d.ts
-/**
- * Parse the Twine 2 format.js JSON chunk; null when it cannot be used ({@link decodeFormatJSON}
- * gives the reason).
- *
- * @param _formatId No longer used; kept so existing callers keep compiling.
- */
-export declare function parseFormatJSON(source: string, _formatId?: string): Twine2FormatJSON | null;
 /**
  * Discover all story formats in the given search directories, pruned by SemVer: within each
- * (name, major) group only the highest version survives. See {@link discoverAllFormats} for the
- * directory ranking and {@link pruneFormats} for pruning.
+ * (name, major) group only the highest version survives. A later search directory outranks an earlier one,
+ * and a format in it replaces one of the same name and version from an earlier directory.
  */
 export declare function discoverFormats(searchDirs: readonly string[]): Map<string, StoryFormatInfo>;
 /**
@@ -553,20 +325,27 @@ export declare function discoverFormats(searchDirs: readonly string[]): Map<stri
  * Tweego.
  */
 export declare function getFormatSearchDirs(extraPaths?: readonly string[], useTweegoPath?: boolean): string[];
+//#endregion
+//#region src/semver.d.ts
+/** Parse a version string, or return null when it is not a version (see the module comment). */
+export declare function parseVersion(text: string): SemVer | null;
+/** Compare two versions by SemVer precedence: negative when `a` ranks lower, 0 when equal, positive when higher. */
+export declare function compareVersions(a: SemVer, b: SemVer): number;
+//#endregion
+//#region src/format-decode.d.ts
 /**
- * Parse a version string into [major, minor, patch]. Accepts what {@link parseVersion} accepts
- * (`v1.2.3`, `1.2`, `2.0.0-beta.1`); the prerelease and build metadata are dropped.
+ * Read the format object of a Twine 2 `format.js` (the object literal passed to its `storyFormat()` call);
+ * null when the file holds no usable format. Compiling reports why a format cannot be used.
  */
-export declare function parseSemver(v: string): [number, number, number] | null;
-/** Compare [major, minor, patch] tuples. Use {@link compareVersions} to take prereleases into account. */
-export declare function semverCompare(a: [number, number, number], b: [number, number, number]): number;
+export declare function parseFormatJSON(source: string): Twine2FormatJSON | null;
 //#endregion
 //#region src/ifid.d.ts
 /** Generate a new IFID (UUID v4, uppercase). */
 export declare function generateIFID(): IFID;
 /**
  * Validate and brand an IFID string. Throws on invalid input.
- * Returns the IFID in its stored form (see `normalizeIFID`).
+ * Returns the IFID in the form the story model stores: the uppercase bare UUID (a `UUID://…//` wrapper is
+ * removed).
  */
 export declare function createIFID(value: string): IFID;
 /**
@@ -579,19 +358,24 @@ export declare function validateIFID(ifid: string): string | null;
 //#region src/config.d.ts
 export declare const CONFIG_FILENAME = "twee-ts.config.json";
 /**
- * Load a config file from the given directory (default: cwd). Returns null if not found.
+ * Load a config file from the given directory (default: cwd). Returns null when nothing is at its path.
  *
  * @param diagnostics Receives warnings that do not stop the config from loading: keys the config does not
  *   define, and a file that is not valid UTF-8 (it is read as Windows-1252).
- * @throws When the file exists but cannot be read, is not valid JSON or fails {@link validateConfig}.
+ * @throws A TweeTsError when something is at the path but cannot be read (a dangling symbolic link, a link loop,
+ *   a folder that can't be searched, a file it may not read), is not valid JSON or fails {@link validateConfig}.
  */
 export declare function loadConfig(dir?: string, diagnostics?: Diagnostic[]): TweeTsConfig | null;
 /**
  * Load a config from a specific file path.
  *
+ * The paths in it (`sources`, `output`, `modules`, `headFile`, `formatPaths`) are relative to the folder
+ * that holds the config file, and so are the `exclude` globs: the config is returned with them rebased onto
+ * the working directory (or absolute, when that folder is outside it).
+ *
  * @param diagnostics Receives warnings that do not stop the config from loading: keys the config does not
  *   define, and a file that is not valid UTF-8 (it is read as Windows-1252).
- * @throws When the file cannot be read, is not valid JSON or fails {@link validateConfig}.
+ * @throws A TweeTsError when the file cannot be read, is not valid JSON or fails {@link validateConfig}.
  */
 export declare function loadConfigFile(filePath: string, diagnostics?: Diagnostic[]): TweeTsConfig;
 /**
@@ -607,59 +391,67 @@ export declare function validateConfig(data: unknown): string[];
  * an object, which {@link validateConfig} reports.
  */
 export declare function unknownConfigKeyWarnings(data: unknown): string[];
-/** Return a default config JSON string for --init scaffolding. */
-export declare function scaffoldConfig(): string;
+/** Return a default config JSON string for --init scaffolding, naming the schema of `version` (this twee-ts). */
+export declare function scaffoldConfig(version?: string): string;
 //#endregion
-//#region src/remote-formats.d.ts
-/** Get the cache directory for downloaded story formats. */
-export declare function getCacheDir(): string;
-/**
- * Download a format, verify its checksum, check that it is the format the entry names, write it to
- * the cache shared by name and version, and return its StoryFormatInfo. Concurrent calls for one
- * download URL share one request for the bytes; each call then verifies them against its own
- * entry, within its own timeout.
- */
-export declare function fetchAndCacheFormat(entry: SFAIndexEntry, downloadUrl: string, options?: RemoteFetchOptions): Promise<StoryFormatInfo>;
-/**
- * Download a direct format.js URL, parse its JSON, cache it under that URL (apart from the
- * downloads shared by name and version), and return its StoryFormatInfo. Concurrent calls for
- * one URL share one request.
- */
-export declare function fetchDirectFormat(url: string, options?: RemoteFetchOptions): Promise<StoryFormatInfo>;
+//#region src/format-resolution.d.ts
 /**
- * Try to resolve a remote story format by name and version.
- * 1. Try direct format URLs (each one's cached copy, else a download)
- * 2. Use an exactly matching download from the shared cache, without touching the network
- * 3. Try custom index URLs, then the default SFA indices
- * 4. Fall back to a compatible download from the shared cache (e.g. when offline)
+ * Resolve a story format by name and version from format URLs and format indices only (no local
+ * folders), by the same policy as a compile: `options.urls` first, then `options.indices`, then the
+ * Story Formats Archive. Returns undefined when no source has the format.
  *
  * `options.signal` aborts the lookup, which then rejects with the signal's reason;
- * `options.timeout` limits each request (default {@link DEFAULT_FORMAT_FETCH_TIMEOUT} ms).
+ * `options.timeout` limits each request (default 30000 ms), and `options.resolutionTimeout` the
+ * whole lookup (default 120000 ms); `options.useDefaultIndices: false` leaves the Story Formats
+ * Archive out.
+ *
+ * @throws A TweeTsError: `INVALID_OPTIONS` for a URL or time limit that cannot be used, before any
+ *   request; `FORMAT_UNAVAILABLE`, listing every failure (also in its `diagnostics`), when no source
+ *   has the format and some source failed.
  */
-export declare function resolveRemoteFormat(name: string, version: string, indices?: readonly string[], urls?: readonly string[], options?: RemoteFetchOptions): Promise<StoryFormatInfo | undefined>;
-/** Discover all cached remote formats. Returns a Map like discoverFormats(). */
-export declare function discoverCachedFormats(): Map<string, StoryFormatInfo>;
+export declare function resolveRemoteFormat(name: string, version: string, options?: RemoteResolveOptions): Promise<StoryFormatInfo | undefined>;
+//#endregion
+//#region src/format-cache.d.ts
+/** Get the cache directory for downloaded story formats. */
+export declare function getCacheDir(): string;
 /** Info about a cached format entry with size and modification date. */
 interface CachedFormatEntry {
+  /** The format's name and version. */
   readonly name: string;
   readonly version: string;
+  /** Where it was downloaded from: a format index or a format URL. */
+  readonly source: 'index' | 'url';
+  /** The format index URL or the format URL. */
+  readonly origin: string;
   readonly sizeBytes: number;
+  /** When it was downloaded. */
   readonly modifiedAt: Date;
 }
-/** List all cached formats with size and modification date. */
+/** List all cached formats (downloads from format indices and from format URLs), in a stable order. */
 export declare function listCachedFormats(): readonly CachedFormatEntry[];
 /**
- * Clear all cached formats, or only those matching a given name. Returns the number of entries removed.
- * Clearing all also removes the downloads from direct format URLs; a name clears only the
- * downloads shared by name and version.
- * A name must be a single cache entry name (as `listCachedFormats()` reports it); anything with a
- * path separator or `.`/`..` throws instead of deleting outside the format's own directory.
+ * Every cached format whose files are intact, keyed by cache entry (so two downloads of the same
+ * name and version from different origins are both listed).
+ */
+export declare function discoverCachedFormats(): Map<string, StoryFormatInfo>;
+/**
+ * Clear all cached formats (no name given), or only those with a given name (matched as format names are, without
+ * regard to letter case; an empty name matches none). Returns the number of cached formats removed. Clearing all also removes
+ * the directories older twee-ts versions wrote.
  */
 export declare function clearCachedFormats(name?: string): number;
 /** Get total cache size in bytes and format count. */
 export declare function getCacheSize(): {
-  totalBytes: number;
-  count: number;
+  readonly totalBytes: number;
+  readonly count: number;
 };
 //#endregion
-export type { BrokenLink, CachedFormatEntry, CompileOptions, CompileResult, CompileStats, CompileToFileOptions, DecompileOptions, DecompileResult, Diagnostic, FileCacheEntry, IFID, InlineSource, InspectOptions, LexerItem, LintResult, OmittingTag, OutputMode, Passage, PassageMetadata, PassageOmission, PassageOutputTarget, ReadonlyPassage, ReadonlyStory, RemoteFetchOptions, SFAIndex, SFAIndexEntry, SourceInput, SourceLocation, Story, StoryFormatInfo, StoryMap, TweeTsConfig, WatchOptions, WordCountMethod };
+//#region src/remote-formats.d.ts
+/**
+ * Download a direct format.js URL (or confirm that its cached copy is current), cache it under
+ * that URL, and return its StoryFormatInfo. Concurrent calls for one URL share one request.
+ * Throws when the URL is not usable, the download fails, or the cache cannot be written.
+ */
+export declare function fetchDirectFormat(url: string, options?: RemoteFetchOptions): Promise<StoryFormatInfo>;
+//#endregion
+export { type BrokenLink, type CachedFormatEntry, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type DecompileOptions, type DecompileResult, type Diagnostic, type ExcludeGlob, type FileCacheEntry, type IFID, type InlineSource, type InspectOptions, ItemType, type LexerItem, type LintResult, type OmittingTag, type OutputMode, type ParseOptions, type ParseResult, type Passage, type PassageMetadata, type PassageOmission, type PassageOutputTarget, type ReadonlyPassage, type ReadonlyStory, type RemoteFetchOptions, type RemoteResolveOptions, type SFAIndex, type SFAIndexEntry, type SemVer, type SourceInput, type SourceLocation, type Story, type StoryFormatInfo, type StoryMap, type TweeTsConfig, type TweeTsErrorCode, type Twine1Metadata, type Twine2FormatJSON, type Twine2Metadata, type WatchOptions, type WordCountMethod };