@ai-matrx/content-ir 0.12.0 → 0.13.0

package/dist/source.d.cts

@@ -114,20 +114,30 @@ declare function blockAt(blocks: readonly SourceBlock[], offset: number): Source
  *     uses to carry every live anchor through the save
  *     (STORE-DESIGN §3.19 — the ProseMirror / Google Docs position-mapping
  *     model), and
- *   - an integrity report: every island outside the edited ranges must still
+ *   - an integrity guarantee: every island not explicitly replaced must still
  *     be the same island, at its mapped position, in the new text. An edit
- *     that opens an unclosed fence and swallows a kind below it is caught
- *     here instead of being saved silently.
+ *     that opens an unclosed fence and swallows a kind below it is REFUSED.
+ *
+ * ISLANDS CHANGE ONLY THROUGH `islandEdit`. A prose/range edit must hand back
+ * every island inside its range byte-identical and in order (a visual editor
+ * holds them as atoms); if one is altered or dropped the save throws
+ * `SourceSpliceError("island_edit")` naming the island. A kind editor or code
+ * view changes an island with `islandEdit(island, newRaw)`.
  *
  * A no-edit save (or edits whose text equals the original block) returns the
  * original string itself — byte-identical, zero changes.
  */
 
-/** Replace `[start, end)` (UTF-16, on block boundaries) of the original with `text`. */
+/**
+ * Replace `[start, end)` (UTF-16) of the original with `text`. A plain edit
+ * starts and ends on block boundaries; an island edit (`island: true`, made by
+ * `islandEdit`) names exactly one island's span.
+ */
 interface SourceEdit {
     readonly start: number;
     readonly end: number;
     readonly text: string;
+    readonly island?: boolean;
 }
 interface SourceChange {
     /** The block-aligned range the edit named, in the ORIGINAL text. */
@@ -168,7 +178,7 @@ interface SpliceResult {
     /** Tokenization of the new text. */
     readonly blocks: readonly SourceBlock[];
 }
-type SourceSpliceErrorCode = "out_of_range" | "misaligned" | "overlap" | "stale_blocks" | "integrity";
+type SourceSpliceErrorCode = "out_of_range" | "misaligned" | "overlap" | "stale_blocks" | "island_edit" | "integrity";
 declare class SourceSpliceError extends Error {
     readonly code: SourceSpliceErrorCode;
     constructor(code: SourceSpliceErrorCode, message: string);
@@ -176,11 +186,21 @@ declare class SourceSpliceError extends Error {
 interface SpliceOptions {
     /** The tokenization of `original`, when the caller already holds it. */
     readonly blocks?: readonly SourceBlock[];
-    /** Throw `SourceSpliceError("integrity")` instead of reporting a disturbed island. */
+    /**
+     * Default `true`: a save that disturbs any island it did not explicitly
+     * replace throws `SourceSpliceError("integrity")`. `false` is for TOOLING
+     * ONLY (diagnostic scripts that want the report instead of the refusal) —
+     * no editor or persistence path may pass it.
+     */
     readonly requireIntegrity?: boolean;
 }
 /** An edit that replaces one block's raw text. */
 declare function blockEdit(block: SourceBlock, text: string): SourceEdit;
+/** The one door that changes an island: replace exactly its span with `text`. */
+declare function islandEdit(island: {
+    readonly start: number;
+    readonly end: number;
+}, text: string): SourceEdit;
 /** An edit that replaces a contiguous run of blocks `[first, last]`. */
 declare function blockRangeEdit(first: SourceBlock, last: SourceBlock, text: string): SourceEdit;
 /**
@@ -286,7 +306,12 @@ interface ReadXmlTag {
         value: string;
     }>;
 }
-declare function readXmlTag(content: string, start: number): ReadXmlTag | null;
+/**
+ * `find(needle, from)` must behave like `content.indexOf(needle, from)`; the
+ * tokenizer passes a cached occurrence index so a text full of unclosed
+ * attribute quotes stays linear. Behaviour is identical either way.
+ */
+declare function readXmlTag(content: string, start: number, find?: (needle: string, from: number) => number): ReadXmlTag | null;
 /**
  * Balances ONE unknown root tag line by line, ignoring lookalike tags inside
  * fenced code, inline code spans, comments and CDATA. `consumeLine` returns
@@ -303,4 +328,47 @@ declare class XmlContainerTracker {
     consumeLine(line: string, startOffset?: number): number | null;
 }
 
-export { type BlockIslandType, type CodePointIndex, type DisturbedIsland, type InlineIslandType, type IslandMeta, type IslandType, type MapOptions, type MappedPosition, type MappedRange, type ReadXmlTag, type SourceBlock, type SourceBlockKind, type SourceChange, type SourceEdit, type SourceIsland, type SourceSpan, SourceSpliceError, type SourceSpliceErrorCode, type SpliceIntegrity, type SpliceOptions, type SpliceResult, XmlContainerTracker, blockAt, blockEdit, blockRangeEdit, buildCodePointIndex, isSingleDollarMath, joinSource, listIslands, mapPosition, mapRange, readXmlTag, singleDollarMathEnd, spliceSave, splitsSurrogatePair, toCodePointOffset, toUtf16Offset, tokenizeSource };
+/** Fence languages whose body is itself a markdown document. */
+declare const NESTING_FENCE_LANGUAGES: ReadonlySet<string>;
+/** True when a fence opened with this info-string language nests inner fences. */
+declare function fenceNestsInnerFences(language: string | undefined | null): boolean;
+type InnerFenceLine = 
+/** Not a fence line — ordinary content of the outer fence. */
+"content"
+/** ```lang inside a markdown fence — content, and one level deeper. */
+ | "open-nested"
+/** Bare ``` that closes the innermost nested fence — content, one level up. */
+ | "close-nested"
+/** Bare ``` that closes the OUTER fence. */
+ | "close-outer";
+/**
+ * Classify one TRIMMED line inside an open backtick fence.
+ *
+ * @param trimmed     the line with surrounding whitespace removed
+ * @param openTicks   backtick count of the outer fence's opener
+ * @param nests       whether the outer fence follows the nesting rule
+ * @param nestedDepth how many nested fences are open right now
+ */
+declare function classifyInnerFenceLine(trimmed: string, openTicks: number, nests: boolean, nestedDepth: number): InnerFenceLine;
+
+/**
+ * `$$` pairing — the core's rule for which `$$` delimiters are real math.
+ *
+ * Ported from `@ai-matrx/kit/delimiter-guard` (`guardMathDelimiters`), which
+ * every math-capable renderer runs before remark-math. Its decisions:
+ *   - `$$` tokens outside code (``` / ~~~ fences, `inline code`) pair in
+ *     document order, open → close;
+ *   - a pair whose inside reads as prose or carries markdown structure is NOT
+ *     math: the renderer neutralizes its opener and the closer is retried as
+ *     the next opener;
+ *   - an unpaired `$$` is inert — it renders as literal text.
+ * So the tokenizer protects exactly the pairs the renderer shows as math, and
+ * a lone `$$` (a stray closer, or an opener that never closed) never locks
+ * anything. Linear time: one regex pass per code shape, one sweep.
+ */
+/** The guard's `looksLikeMath`, verbatim. */
+declare function looksLikeDisplayMath(inner: string): boolean;
+/** Map of `$$` opener offset → closer offset for every pair the renderer shows as math. */
+declare function pairDisplayMath(text: string): Map<number, number>;
+
+export { type BlockIslandType, type CodePointIndex, type DisturbedIsland, type InlineIslandType, type InnerFenceLine, type IslandMeta, type IslandType, type MapOptions, type MappedPosition, type MappedRange, NESTING_FENCE_LANGUAGES, type ReadXmlTag, type SourceBlock, type SourceBlockKind, type SourceChange, type SourceEdit, type SourceIsland, type SourceSpan, SourceSpliceError, type SourceSpliceErrorCode, type SpliceIntegrity, type SpliceOptions, type SpliceResult, XmlContainerTracker, blockAt, blockEdit, blockRangeEdit, buildCodePointIndex, classifyInnerFenceLine, fenceNestsInnerFences, isSingleDollarMath, islandEdit, joinSource, listIslands, looksLikeDisplayMath, mapPosition, mapRange, pairDisplayMath, readXmlTag, singleDollarMathEnd, spliceSave, splitsSurrogatePair, toCodePointOffset, toUtf16Offset, tokenizeSource };

package/dist/source.d.ts

@@ -114,20 +114,30 @@ declare function blockAt(blocks: readonly SourceBlock[], offset: number): Source
  *     uses to carry every live anchor through the save
  *     (STORE-DESIGN §3.19 — the ProseMirror / Google Docs position-mapping
  *     model), and
- *   - an integrity report: every island outside the edited ranges must still
+ *   - an integrity guarantee: every island not explicitly replaced must still
  *     be the same island, at its mapped position, in the new text. An edit
- *     that opens an unclosed fence and swallows a kind below it is caught
- *     here instead of being saved silently.
+ *     that opens an unclosed fence and swallows a kind below it is REFUSED.
+ *
+ * ISLANDS CHANGE ONLY THROUGH `islandEdit`. A prose/range edit must hand back
+ * every island inside its range byte-identical and in order (a visual editor
+ * holds them as atoms); if one is altered or dropped the save throws
+ * `SourceSpliceError("island_edit")` naming the island. A kind editor or code
+ * view changes an island with `islandEdit(island, newRaw)`.
  *
  * A no-edit save (or edits whose text equals the original block) returns the
  * original string itself — byte-identical, zero changes.
  */
 
-/** Replace `[start, end)` (UTF-16, on block boundaries) of the original with `text`. */
+/**
+ * Replace `[start, end)` (UTF-16) of the original with `text`. A plain edit
+ * starts and ends on block boundaries; an island edit (`island: true`, made by
+ * `islandEdit`) names exactly one island's span.
+ */
 interface SourceEdit {
     readonly start: number;
     readonly end: number;
     readonly text: string;
+    readonly island?: boolean;
 }
 interface SourceChange {
     /** The block-aligned range the edit named, in the ORIGINAL text. */
@@ -168,7 +178,7 @@ interface SpliceResult {
     /** Tokenization of the new text. */
     readonly blocks: readonly SourceBlock[];
 }
-type SourceSpliceErrorCode = "out_of_range" | "misaligned" | "overlap" | "stale_blocks" | "integrity";
+type SourceSpliceErrorCode = "out_of_range" | "misaligned" | "overlap" | "stale_blocks" | "island_edit" | "integrity";
 declare class SourceSpliceError extends Error {
     readonly code: SourceSpliceErrorCode;
     constructor(code: SourceSpliceErrorCode, message: string);
@@ -176,11 +186,21 @@ declare class SourceSpliceError extends Error {
 interface SpliceOptions {
     /** The tokenization of `original`, when the caller already holds it. */
     readonly blocks?: readonly SourceBlock[];
-    /** Throw `SourceSpliceError("integrity")` instead of reporting a disturbed island. */
+    /**
+     * Default `true`: a save that disturbs any island it did not explicitly
+     * replace throws `SourceSpliceError("integrity")`. `false` is for TOOLING
+     * ONLY (diagnostic scripts that want the report instead of the refusal) —
+     * no editor or persistence path may pass it.
+     */
     readonly requireIntegrity?: boolean;
 }
 /** An edit that replaces one block's raw text. */
 declare function blockEdit(block: SourceBlock, text: string): SourceEdit;
+/** The one door that changes an island: replace exactly its span with `text`. */
+declare function islandEdit(island: {
+    readonly start: number;
+    readonly end: number;
+}, text: string): SourceEdit;
 /** An edit that replaces a contiguous run of blocks `[first, last]`. */
 declare function blockRangeEdit(first: SourceBlock, last: SourceBlock, text: string): SourceEdit;
 /**
@@ -286,7 +306,12 @@ interface ReadXmlTag {
         value: string;
     }>;
 }
-declare function readXmlTag(content: string, start: number): ReadXmlTag | null;
+/**
+ * `find(needle, from)` must behave like `content.indexOf(needle, from)`; the
+ * tokenizer passes a cached occurrence index so a text full of unclosed
+ * attribute quotes stays linear. Behaviour is identical either way.
+ */
+declare function readXmlTag(content: string, start: number, find?: (needle: string, from: number) => number): ReadXmlTag | null;
 /**
  * Balances ONE unknown root tag line by line, ignoring lookalike tags inside
  * fenced code, inline code spans, comments and CDATA. `consumeLine` returns
@@ -303,4 +328,47 @@ declare class XmlContainerTracker {
     consumeLine(line: string, startOffset?: number): number | null;
 }
 
-export { type BlockIslandType, type CodePointIndex, type DisturbedIsland, type InlineIslandType, type IslandMeta, type IslandType, type MapOptions, type MappedPosition, type MappedRange, type ReadXmlTag, type SourceBlock, type SourceBlockKind, type SourceChange, type SourceEdit, type SourceIsland, type SourceSpan, SourceSpliceError, type SourceSpliceErrorCode, type SpliceIntegrity, type SpliceOptions, type SpliceResult, XmlContainerTracker, blockAt, blockEdit, blockRangeEdit, buildCodePointIndex, isSingleDollarMath, joinSource, listIslands, mapPosition, mapRange, readXmlTag, singleDollarMathEnd, spliceSave, splitsSurrogatePair, toCodePointOffset, toUtf16Offset, tokenizeSource };
+/** Fence languages whose body is itself a markdown document. */
+declare const NESTING_FENCE_LANGUAGES: ReadonlySet<string>;
+/** True when a fence opened with this info-string language nests inner fences. */
+declare function fenceNestsInnerFences(language: string | undefined | null): boolean;
+type InnerFenceLine = 
+/** Not a fence line — ordinary content of the outer fence. */
+"content"
+/** ```lang inside a markdown fence — content, and one level deeper. */
+ | "open-nested"
+/** Bare ``` that closes the innermost nested fence — content, one level up. */
+ | "close-nested"
+/** Bare ``` that closes the OUTER fence. */
+ | "close-outer";
+/**
+ * Classify one TRIMMED line inside an open backtick fence.
+ *
+ * @param trimmed     the line with surrounding whitespace removed
+ * @param openTicks   backtick count of the outer fence's opener
+ * @param nests       whether the outer fence follows the nesting rule
+ * @param nestedDepth how many nested fences are open right now
+ */
+declare function classifyInnerFenceLine(trimmed: string, openTicks: number, nests: boolean, nestedDepth: number): InnerFenceLine;
+
+/**
+ * `$$` pairing — the core's rule for which `$$` delimiters are real math.
+ *
+ * Ported from `@ai-matrx/kit/delimiter-guard` (`guardMathDelimiters`), which
+ * every math-capable renderer runs before remark-math. Its decisions:
+ *   - `$$` tokens outside code (``` / ~~~ fences, `inline code`) pair in
+ *     document order, open → close;
+ *   - a pair whose inside reads as prose or carries markdown structure is NOT
+ *     math: the renderer neutralizes its opener and the closer is retried as
+ *     the next opener;
+ *   - an unpaired `$$` is inert — it renders as literal text.
+ * So the tokenizer protects exactly the pairs the renderer shows as math, and
+ * a lone `$$` (a stray closer, or an opener that never closed) never locks
+ * anything. Linear time: one regex pass per code shape, one sweep.
+ */
+/** The guard's `looksLikeMath`, verbatim. */
+declare function looksLikeDisplayMath(inner: string): boolean;
+/** Map of `$$` opener offset → closer offset for every pair the renderer shows as math. */
+declare function pairDisplayMath(text: string): Map<number, number>;
+
+export { type BlockIslandType, type CodePointIndex, type DisturbedIsland, type InlineIslandType, type InnerFenceLine, type IslandMeta, type IslandType, type MapOptions, type MappedPosition, type MappedRange, NESTING_FENCE_LANGUAGES, type ReadXmlTag, type SourceBlock, type SourceBlockKind, type SourceChange, type SourceEdit, type SourceIsland, type SourceSpan, SourceSpliceError, type SourceSpliceErrorCode, type SpliceIntegrity, type SpliceOptions, type SpliceResult, XmlContainerTracker, blockAt, blockEdit, blockRangeEdit, buildCodePointIndex, classifyInnerFenceLine, fenceNestsInnerFences, isSingleDollarMath, islandEdit, joinSource, listIslands, looksLikeDisplayMath, mapPosition, mapRange, pairDisplayMath, readXmlTag, singleDollarMathEnd, spliceSave, splitsSurrogatePair, toCodePointOffset, toUtf16Offset, tokenizeSource };