@stream-mdx/core 0.3.0 → 0.5.0

package/dist/perf/patch-batching.mjs

@@ -80,23 +80,59 @@ function isHeavyPatch(patch) {
       return false;
   }
 }
+function getPatchKind(patch) {
+  const explicitKind = patch.op === "setHTML" ? patch.patchMeta?.kind : patch.meta?.kind;
+  if (explicitKind === "semantic" || explicitKind === "enrichment") {
+    return explicitKind;
+  }
+  switch (patch.op) {
+    case "insertChild":
+    case "deleteChild":
+    case "replaceChild":
+    case "finalize":
+    case "reorder":
+    case "appendLines":
+    case "setHTML":
+      return "semantic";
+    case "setProps":
+    case "setPropsBatch":
+      return "semantic";
+    default:
+      return "semantic";
+  }
+}
 function splitPatchBatch(patches, maxLightChunk = DEFAULT_MAX_LIGHT_PATCHES_PER_CHUNK) {
   if (patches.length === 0) return [];
   const groups = [];
   let current = [];
+  let currentMode = null;
   const flush = () => {
     if (current.length > 0) {
       groups.push(current);
       current = [];
+      currentMode = null;
     }
   };
   for (const patch of patches) {
+    const kind = getPatchKind(patch);
     const heavy = isHeavyPatch(patch);
+    if (kind === "semantic") {
+      if (currentMode !== "semantic") {
+        flush();
+        currentMode = "semantic";
+      }
+      current.push(patch);
+      continue;
+    }
     if (heavy) {
       flush();
       groups.push([patch]);
       continue;
     }
+    if (currentMode !== "enrichment") {
+      flush();
+      currentMode = "enrichment";
+    }
     current.push(patch);
     if (current.length >= maxLightChunk) {
       flush();
@@ -106,6 +142,7 @@ function splitPatchBatch(patches, maxLightChunk = DEFAULT_MAX_LIGHT_PATCHES_PER_
   return groups;
 }
 export {
+  getPatchKind,
   isHeavyPatch,
   splitPatchBatch
 };

package/dist/perf/patch-coalescing.cjs

@@ -289,7 +289,8 @@ function collectSetProps(window, startIndex) {
     }
     entries.push({
       at: cloneNodePath(current.at),
-      props: mergedProps
+      props: mergedProps,
+      meta: current.meta ? { ...current.meta } : void 0
     });
     j = k;
   }
@@ -307,7 +308,8 @@ function collectSetProps(window, startIndex) {
   }
   const batchPatch = {
     op: "setPropsBatch",
-    entries
+    entries,
+    meta: first.meta ? { ...first.meta } : void 0
   };
   return { patches: [batchPatch], nextIndex: j };
 }
@@ -402,7 +404,8 @@ function coalescePatchesQuadratic(patches, config = DEFAULT_COALESCE_CONFIG) {
       const batchEntries = [
         {
           at: cloneNodePath(current.at),
-          props: mergedProps
+          props: mergedProps,
+          meta: current.meta ? { ...current.meta } : void 0
         }
       ];
       let k = j;
@@ -426,14 +429,16 @@ function coalescePatchesQuadratic(patches, config = DEFAULT_COALESCE_CONFIG) {
         }
         batchEntries.push({
           at: cloneNodePath(candidate.at),
-          props: candidateMergedProps
+          props: candidateMergedProps,
+          meta: candidate.meta ? { ...candidate.meta } : void 0
         });
         k = m;
       }
       if (batchEntries.length > 1) {
         coalesced.push({
           op: "setPropsBatch",
-          entries: batchEntries
+          entries: batchEntries,
+          meta: current.meta ? { ...current.meta } : void 0
         });
         i = k;
         continue;

package/dist/perf/patch-coalescing.mjs

@@ -261,7 +261,8 @@ function collectSetProps(window, startIndex) {
     }
     entries.push({
       at: cloneNodePath(current.at),
-      props: mergedProps
+      props: mergedProps,
+      meta: current.meta ? { ...current.meta } : void 0
     });
     j = k;
   }
@@ -279,7 +280,8 @@ function collectSetProps(window, startIndex) {
   }
   const batchPatch = {
     op: "setPropsBatch",
-    entries
+    entries,
+    meta: first.meta ? { ...first.meta } : void 0
   };
   return { patches: [batchPatch], nextIndex: j };
 }
@@ -374,7 +376,8 @@ function coalescePatchesQuadratic(patches, config = DEFAULT_COALESCE_CONFIG) {
       const batchEntries = [
         {
           at: cloneNodePath(current.at),
-          props: mergedProps
+          props: mergedProps,
+          meta: current.meta ? { ...current.meta } : void 0
         }
       ];
       let k = j;
@@ -398,14 +401,16 @@ function coalescePatchesQuadratic(patches, config = DEFAULT_COALESCE_CONFIG) {
         }
         batchEntries.push({
           at: cloneNodePath(candidate.at),
-          props: candidateMergedProps
+          props: candidateMergedProps,
+          meta: candidate.meta ? { ...candidate.meta } : void 0
         });
         k = m;
       }
       if (batchEntries.length > 1) {
         coalesced.push({
           op: "setPropsBatch",
-          entries: batchEntries
+          entries: batchEntries,
+          meta: current.meta ? { ...current.meta } : void 0
         });
         i = k;
         continue;

package/dist/streaming/inline-streaming.cjs

@@ -65,6 +65,13 @@ function prepareInlineStreamingContent(content, options) {
   };
   let mathDisplayOpen = false;
   let mathDisplayCrossedNewline = false;
+  const shouldOpenInlineMath = (index) => {
+    const next = content[index + 1] ?? "";
+    if (/\d/.test(next)) {
+      return false;
+    }
+    return true;
+  };
   for (let i = 0; i < content.length; i++) {
     const code = content.charCodeAt(i);
     if (code === 10 || code === 13) {
@@ -103,7 +110,10 @@ function prepareInlineStreamingContent(content, options) {
         }
         i += 1;
       } else {
-        toggleToken("math-inline");
+        const mathInlineOpen = stack.includes("math-inline");
+        if (mathInlineOpen || shouldOpenInlineMath(i)) {
+          toggleToken("math-inline");
+        }
       }
     }
   }
@@ -115,7 +125,7 @@ function prepareInlineStreamingContent(content, options) {
     if (hasIncompleteMathInline && !enableMathInlineAnticipation) {
       return { kind: "raw", status: "raw", reason: "incomplete-math" };
     }
-    if (hasIncompleteMathDisplay && (!enableMathBlockAnticipation || mathDisplayCrossedNewline)) {
+    if (hasIncompleteMathDisplay && !enableMathBlockAnticipation) {
       return { kind: "raw", status: "raw", reason: "incomplete-math" };
     }
   }
@@ -138,7 +148,10 @@ function prepareInlineStreamingContent(content, options) {
       case "math-inline":
         return "$";
       case "math-display":
-        return "$$";
+        if (!mathDisplayCrossedNewline) {
+          return "$$";
+        }
+        return content.endsWith("\n") || content.endsWith("\r") ? "$$" : "\n$$";
       default:
         return "";
     }

package/dist/streaming/inline-streaming.mjs

@@ -40,6 +40,13 @@ function prepareInlineStreamingContent(content, options) {
   };
   let mathDisplayOpen = false;
   let mathDisplayCrossedNewline = false;
+  const shouldOpenInlineMath = (index) => {
+    const next = content[index + 1] ?? "";
+    if (/\d/.test(next)) {
+      return false;
+    }
+    return true;
+  };
   for (let i = 0; i < content.length; i++) {
     const code = content.charCodeAt(i);
     if (code === 10 || code === 13) {
@@ -78,7 +85,10 @@ function prepareInlineStreamingContent(content, options) {
         }
         i += 1;
       } else {
-        toggleToken("math-inline");
+        const mathInlineOpen = stack.includes("math-inline");
+        if (mathInlineOpen || shouldOpenInlineMath(i)) {
+          toggleToken("math-inline");
+        }
       }
     }
   }
@@ -90,7 +100,7 @@ function prepareInlineStreamingContent(content, options) {
     if (hasIncompleteMathInline && !enableMathInlineAnticipation) {
       return { kind: "raw", status: "raw", reason: "incomplete-math" };
     }
-    if (hasIncompleteMathDisplay && (!enableMathBlockAnticipation || mathDisplayCrossedNewline)) {
+    if (hasIncompleteMathDisplay && !enableMathBlockAnticipation) {
       return { kind: "raw", status: "raw", reason: "incomplete-math" };
     }
   }
@@ -113,7 +123,10 @@ function prepareInlineStreamingContent(content, options) {
       case "math-inline":
         return "$";
       case "math-display":
-        return "$$";
+        if (!mathDisplayCrossedNewline) {
+          return "$$";
+        }
+        return content.endsWith("\n") || content.endsWith("\r") ? "$$" : "\n$$";
       default:
         return "";
     }

package/dist/types.d.cts

@@ -189,6 +189,8 @@ type WorkerIn = {
     type: "FINALIZE";
 } | {
     type: "DEBUG_STATE";
+} | {
+    type: "DUMP_BLOCKS";
 } | {
     type: "TOKENIZE_RANGE";
     blockId: string;
@@ -199,10 +201,12 @@ type WorkerIn = {
     type: "MDX_COMPILED";
     blockId: string;
     compiledId: string;
+    rawSignature?: string;
 } | {
     type: "MDX_ERROR";
     blockId: string;
     error?: string;
+    rawSignature?: string;
 } | {
     type: "SET_CREDITS";
     credits: number;
@@ -216,6 +220,8 @@ interface WorkerErrorPayload {
 type WorkerOut = {
     type: "INITIALIZED";
     blocks: Block[];
+} | {
+    type: "FINALIZED";
 } | {
     type: "PATCH";
     tx: number;
@@ -227,6 +233,10 @@ type WorkerOut = {
 } | {
     type: "METRICS";
     metrics: PerformanceMetrics;
+} | {
+    type: "DUMP_BLOCKS";
+    blocks: Block[];
+    tocHeadings?: TocHeading[];
 } | {
     type: "DEBUG_STATE";
     state: {
@@ -348,36 +358,68 @@ interface NodePath {
     nodeId?: string;
     indexPath?: number[];
 }
+type PatchKind = "semantic" | "enrichment";
+interface PatchMeta {
+    /**
+     * Explicit correctness class for this patch.
+     * - `semantic`: changes visible meaning, structure, ordering, or finalized content
+     * - `enrichment`: decorates already-correct semantic output
+     *
+     * Ambiguous patches should default to `semantic`.
+     */
+    kind?: PatchKind;
+    /**
+     * Reserved for epoch-aware targeting and stale-patch rejection.
+     * These fields are optional until the semantic-envelope workstream is complete.
+     */
+    streamSeq?: number;
+    parseEpoch?: number;
+    tx?: number;
+    blockEpoch?: number;
+}
+interface TocHeading {
+    id: string;
+    text: string;
+    level: number;
+    blockId: string;
+}
 type Patch = {
     op: "insertChild";
     at: NodePath;
     index: number;
     node: NodeSnapshot;
+    meta?: PatchMeta;
 } | {
     op: "deleteChild";
     at: NodePath;
     index: number;
+    meta?: PatchMeta;
 } | {
     op: "replaceChild";
     at: NodePath;
     index: number;
     node: NodeSnapshot;
+    meta?: PatchMeta;
 } | {
     op: "setProps";
     at: NodePath;
     props: Record<string, unknown>;
+    meta?: PatchMeta;
 } | {
     op: "setPropsBatch";
     entries: SetPropsBatchEntry[];
+    meta?: PatchMeta;
 } | {
     op: "finalize";
     at: NodePath;
+    meta?: PatchMeta;
 } | {
     op: "reorder";
     at: NodePath;
     from: number;
     to: number;
     count: number;
+    meta?: PatchMeta;
 } | {
     op: "appendLines";
     at: NodePath;
@@ -388,6 +430,7 @@ type Patch = {
     diffKind?: Array<DiffKind | null>;
     oldNo?: Array<number | null>;
     newNo?: Array<number | null>;
+    meta?: PatchMeta;
 } | {
     op: "setHTML";
     at: NodePath;
@@ -396,6 +439,7 @@ type Patch = {
     block?: Block;
     meta?: Record<string, unknown>;
     sanitized?: boolean;
+    patchMeta?: PatchMeta;
 };
 interface PatchMetrics {
     patchCount: number;
@@ -412,6 +456,7 @@ interface PatchMetrics {
 interface SetPropsBatchEntry {
     at: NodePath;
     props: Record<string, unknown>;
+    meta?: PatchMeta;
 }
 interface CoalescingMetrics {
     inputPatchCount: number;
@@ -423,4 +468,4 @@ interface CoalescingMetrics {
     insertChildCoalesced: number;
 }
 
-export { type ASTInlinePlugin, type Block, type CoalescingMetrics, type CodeHighlightOutputMode, type CodeHighlightingMode, type CompiledMdxModule, type DiffBlock, type DiffKind, type DiffLine, type DiffLineKind, type FormatAnticipationConfig, type InlineHtmlDescriptor, type InlineNode, type InlinePlugin, LANGUAGE_ALIASES, type LazyTokenizationPriority, type MixedContentSegment, type NodePath, type NodeSnapshot, PATCH_ROOT_ID, type Patch, type PatchMetrics, type PerformanceMetrics, type ProtectedRange, type ProtectedRangeKind, type RegexAnticipationPattern, type RegexInlinePlugin, type SetPropsBatchEntry, type ThemedLine, type ThemedToken, type TokenLineV1, type TokenSpan, type TokenStyle, type WorkerErrorPayload, type WorkerIn, type WorkerOut, type WorkerPhase };
+export { type ASTInlinePlugin, type Block, type CoalescingMetrics, type CodeHighlightOutputMode, type CodeHighlightingMode, type CompiledMdxModule, type DiffBlock, type DiffKind, type DiffLine, type DiffLineKind, type FormatAnticipationConfig, type InlineHtmlDescriptor, type InlineNode, type InlinePlugin, LANGUAGE_ALIASES, type LazyTokenizationPriority, type MixedContentSegment, type NodePath, type NodeSnapshot, PATCH_ROOT_ID, type Patch, type PatchKind, type PatchMeta, type PatchMetrics, type PerformanceMetrics, type ProtectedRange, type ProtectedRangeKind, type RegexAnticipationPattern, type RegexInlinePlugin, type SetPropsBatchEntry, type ThemedLine, type ThemedToken, type TocHeading, type TokenLineV1, type TokenSpan, type TokenStyle, type WorkerErrorPayload, type WorkerIn, type WorkerOut, type WorkerPhase };

package/dist/types.d.ts

@@ -189,6 +189,8 @@ type WorkerIn = {
     type: "FINALIZE";
 } | {
     type: "DEBUG_STATE";
+} | {
+    type: "DUMP_BLOCKS";
 } | {
     type: "TOKENIZE_RANGE";
     blockId: string;
@@ -199,10 +201,12 @@ type WorkerIn = {
     type: "MDX_COMPILED";
     blockId: string;
     compiledId: string;
+    rawSignature?: string;
 } | {
     type: "MDX_ERROR";
     blockId: string;
     error?: string;
+    rawSignature?: string;
 } | {
     type: "SET_CREDITS";
     credits: number;
@@ -216,6 +220,8 @@ interface WorkerErrorPayload {
 type WorkerOut = {
     type: "INITIALIZED";
     blocks: Block[];
+} | {
+    type: "FINALIZED";
 } | {
     type: "PATCH";
     tx: number;
@@ -227,6 +233,10 @@ type WorkerOut = {
 } | {
     type: "METRICS";
     metrics: PerformanceMetrics;
+} | {
+    type: "DUMP_BLOCKS";
+    blocks: Block[];
+    tocHeadings?: TocHeading[];
 } | {
     type: "DEBUG_STATE";
     state: {
@@ -348,36 +358,68 @@ interface NodePath {
     nodeId?: string;
     indexPath?: number[];
 }
+type PatchKind = "semantic" | "enrichment";
+interface PatchMeta {
+    /**
+     * Explicit correctness class for this patch.
+     * - `semantic`: changes visible meaning, structure, ordering, or finalized content
+     * - `enrichment`: decorates already-correct semantic output
+     *
+     * Ambiguous patches should default to `semantic`.
+     */
+    kind?: PatchKind;
+    /**
+     * Reserved for epoch-aware targeting and stale-patch rejection.
+     * These fields are optional until the semantic-envelope workstream is complete.
+     */
+    streamSeq?: number;
+    parseEpoch?: number;
+    tx?: number;
+    blockEpoch?: number;
+}
+interface TocHeading {
+    id: string;
+    text: string;
+    level: number;
+    blockId: string;
+}
 type Patch = {
     op: "insertChild";
     at: NodePath;
     index: number;
     node: NodeSnapshot;
+    meta?: PatchMeta;
 } | {
     op: "deleteChild";
     at: NodePath;
     index: number;
+    meta?: PatchMeta;
 } | {
     op: "replaceChild";
     at: NodePath;
     index: number;
     node: NodeSnapshot;
+    meta?: PatchMeta;
 } | {
     op: "setProps";
     at: NodePath;
     props: Record<string, unknown>;
+    meta?: PatchMeta;
 } | {
     op: "setPropsBatch";
     entries: SetPropsBatchEntry[];
+    meta?: PatchMeta;
 } | {
     op: "finalize";
     at: NodePath;
+    meta?: PatchMeta;
 } | {
     op: "reorder";
     at: NodePath;
     from: number;
     to: number;
     count: number;
+    meta?: PatchMeta;
 } | {
     op: "appendLines";
     at: NodePath;
@@ -388,6 +430,7 @@ type Patch = {
     diffKind?: Array<DiffKind | null>;
     oldNo?: Array<number | null>;
     newNo?: Array<number | null>;
+    meta?: PatchMeta;
 } | {
     op: "setHTML";
     at: NodePath;
@@ -396,6 +439,7 @@ type Patch = {
     block?: Block;
     meta?: Record<string, unknown>;
     sanitized?: boolean;
+    patchMeta?: PatchMeta;
 };
 interface PatchMetrics {
     patchCount: number;
@@ -412,6 +456,7 @@ interface PatchMetrics {
 interface SetPropsBatchEntry {
     at: NodePath;
     props: Record<string, unknown>;
+    meta?: PatchMeta;
 }
 interface CoalescingMetrics {
     inputPatchCount: number;
@@ -423,4 +468,4 @@ interface CoalescingMetrics {
     insertChildCoalesced: number;
 }
 
-export { type ASTInlinePlugin, type Block, type CoalescingMetrics, type CodeHighlightOutputMode, type CodeHighlightingMode, type CompiledMdxModule, type DiffBlock, type DiffKind, type DiffLine, type DiffLineKind, type FormatAnticipationConfig, type InlineHtmlDescriptor, type InlineNode, type InlinePlugin, LANGUAGE_ALIASES, type LazyTokenizationPriority, type MixedContentSegment, type NodePath, type NodeSnapshot, PATCH_ROOT_ID, type Patch, type PatchMetrics, type PerformanceMetrics, type ProtectedRange, type ProtectedRangeKind, type RegexAnticipationPattern, type RegexInlinePlugin, type SetPropsBatchEntry, type ThemedLine, type ThemedToken, type TokenLineV1, type TokenSpan, type TokenStyle, type WorkerErrorPayload, type WorkerIn, type WorkerOut, type WorkerPhase };
+export { type ASTInlinePlugin, type Block, type CoalescingMetrics, type CodeHighlightOutputMode, type CodeHighlightingMode, type CompiledMdxModule, type DiffBlock, type DiffKind, type DiffLine, type DiffLineKind, type FormatAnticipationConfig, type InlineHtmlDescriptor, type InlineNode, type InlinePlugin, LANGUAGE_ALIASES, type LazyTokenizationPriority, type MixedContentSegment, type NodePath, type NodeSnapshot, PATCH_ROOT_ID, type Patch, type PatchKind, type PatchMeta, type PatchMetrics, type PerformanceMetrics, type ProtectedRange, type ProtectedRangeKind, type RegexAnticipationPattern, type RegexInlinePlugin, type SetPropsBatchEntry, type ThemedLine, type ThemedToken, type TocHeading, type TokenLineV1, type TokenSpan, type TokenStyle, type WorkerErrorPayload, type WorkerIn, type WorkerOut, type WorkerPhase };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stream-mdx/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Core types, snapshot utilities, and perf helpers for the Streaming Markdown V2 stack",
   "license": "MIT",
   "repository": {