@rohal12/twee-ts 1.16.0 → 1.16.1

package/dist/index.d.cts

@@ -195,6 +195,12 @@ interface SFAIndex {
 }
 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[];
   readonly diagnostics: readonly Diagnostic[];
 }
@@ -259,9 +265,10 @@ interface StoryMap {
   tagsByPassage: Map<string, string[]>;
   /**
    * Map of passage name → passage names it links to.
-   * Parses `[[target]]`, `[[display->target]]`, `[[display|target]]`,
-   * and SugarCube's `<<goto "target">>` / `<<link "display" "target">>`,
-   * whose arguments are read as SugarCube 2 reads them (see `sugarcube-macros.ts`).
+   * 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.
    */
   links: Map<string, string[]>;
   /** Broken links: `{ from, to }` pairs where `to` doesn't exist as a passage. */
@@ -350,7 +357,8 @@ interface LintResult {
 }
 /**
  * Lint a story: compile without output rendering, then inspect structure.
- * Uses JSON output mode internally to avoid format resolution.
+ * Uses JSON output mode internally to avoid format resolution, so it checks
+ * the starting passage itself, against the Twine 2 passage rules.
  */
 export declare function lint(options: Omit<CompileOptions, 'outputMode'>): Promise<LintResult>;
 /**
@@ -400,16 +408,23 @@ 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.
  */
 export declare function parseTwee(source: string, options?: ParseOptions): ParseResult;
 //#endregion
 //#region src/formats.d.ts
 /**
  * Parse the Twine 2 format.js JSON chunk.
- * Handles Harlowe's malformed JSON by stripping the "setup" function property.
+ * Handles Harlowe's malformed JSON by stripping the "setup" function property. The workaround
+ * keys on the property itself, so the same bytes parse whether they come from a `harlowe-3`
+ * directory or a direct download.
  * Per spec, the name key is Optional.
+ *
+ * @param _formatId No longer used; kept so existing callers keep compiling.
  */
-export declare function parseFormatJSON(source: string, formatId: string): Twine2FormatJSON | null;
+export declare function parseFormatJSON(source: string, _formatId?: string): Twine2FormatJSON | null;
 /**
  * Discover all story formats in the given search directories.
  * Implements SemVer-based version pruning: within each (name, major) group,
@@ -456,9 +471,11 @@ export declare function fetchAndCacheFormat(entry: SFAIndexEntry, downloadUrl: s
 export declare function fetchDirectFormat(url: string): Promise<StoryFormatInfo>;
 /**
  * Try to resolve a remote story format by name and version.
+ * 0. Use an exactly matching cached download, without touching the network
  * 1. Try direct format URLs
  * 2. Try custom index URLs
  * 3. Try default SFA indices
+ * 4. Fall back to a compatible cached download (e.g. when offline)
  */
 export declare function resolveRemoteFormat(name: string, version: string, indices?: string[], urls?: string[]): Promise<StoryFormatInfo | undefined>;
 /** Discover all cached remote formats. Returns a Map like discoverFormats(). */
@@ -472,7 +489,11 @@ interface CachedFormatEntry {
 }
 /** List all cached formats with size and modification date. */
 export declare function listCachedFormats(): readonly CachedFormatEntry[];
-/** Clear all cached formats, or only those matching a given name. Returns the number of entries removed. */
+/**
+ * Clear all cached formats, or only those matching a given name. Returns the number of entries removed.
+ * 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.
+ */
 export declare function clearCachedFormats(name?: string): number;
 /** Get total cache size in bytes and format count. */
 export declare function getCacheSize(): {

package/dist/index.d.ts

@@ -195,6 +195,12 @@ interface SFAIndex {
 }
 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[];
   readonly diagnostics: readonly Diagnostic[];
 }
@@ -259,9 +265,10 @@ interface StoryMap {
   tagsByPassage: Map<string, string[]>;
   /**
    * Map of passage name → passage names it links to.
-   * Parses `[[target]]`, `[[display->target]]`, `[[display|target]]`,
-   * and SugarCube's `<<goto "target">>` / `<<link "display" "target">>`,
-   * whose arguments are read as SugarCube 2 reads them (see `sugarcube-macros.ts`).
+   * 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.
    */
   links: Map<string, string[]>;
   /** Broken links: `{ from, to }` pairs where `to` doesn't exist as a passage. */
@@ -350,7 +357,8 @@ interface LintResult {
 }
 /**
  * Lint a story: compile without output rendering, then inspect structure.
- * Uses JSON output mode internally to avoid format resolution.
+ * Uses JSON output mode internally to avoid format resolution, so it checks
+ * the starting passage itself, against the Twine 2 passage rules.
  */
 export declare function lint(options: Omit<CompileOptions, 'outputMode'>): Promise<LintResult>;
 /**
@@ -400,16 +408,23 @@ 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.
  */
 export declare function parseTwee(source: string, options?: ParseOptions): ParseResult;
 //#endregion
 //#region src/formats.d.ts
 /**
  * Parse the Twine 2 format.js JSON chunk.
- * Handles Harlowe's malformed JSON by stripping the "setup" function property.
+ * Handles Harlowe's malformed JSON by stripping the "setup" function property. The workaround
+ * keys on the property itself, so the same bytes parse whether they come from a `harlowe-3`
+ * directory or a direct download.
  * Per spec, the name key is Optional.
+ *
+ * @param _formatId No longer used; kept so existing callers keep compiling.
  */
-export declare function parseFormatJSON(source: string, formatId: string): Twine2FormatJSON | null;
+export declare function parseFormatJSON(source: string, _formatId?: string): Twine2FormatJSON | null;
 /**
  * Discover all story formats in the given search directories.
  * Implements SemVer-based version pruning: within each (name, major) group,
@@ -456,9 +471,11 @@ export declare function fetchAndCacheFormat(entry: SFAIndexEntry, downloadUrl: s
 export declare function fetchDirectFormat(url: string): Promise<StoryFormatInfo>;
 /**
  * Try to resolve a remote story format by name and version.
+ * 0. Use an exactly matching cached download, without touching the network
  * 1. Try direct format URLs
  * 2. Try custom index URLs
  * 3. Try default SFA indices
+ * 4. Fall back to a compatible cached download (e.g. when offline)
  */
 export declare function resolveRemoteFormat(name: string, version: string, indices?: string[], urls?: string[]): Promise<StoryFormatInfo | undefined>;
 /** Discover all cached remote formats. Returns a Map like discoverFormats(). */
@@ -472,7 +489,11 @@ interface CachedFormatEntry {
 }
 /** List all cached formats with size and modification date. */
 export declare function listCachedFormats(): readonly CachedFormatEntry[];
-/** Clear all cached formats, or only those matching a given name. Returns the number of entries removed. */
+/**
+ * Clear all cached formats, or only those matching a given name. Returns the number of entries removed.
+ * 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.
+ */
 export declare function clearCachedFormats(name?: string): number;
 /** Get total cache size in bytes and format count. */
 export declare function getCacheSize(): {