@stream-mdx/react 0.4.0 → 0.5.0

package/dist/renderer.mjs

@@ -81,7 +81,7 @@ var init_mdx_client = __esm({
         if (block.type !== "mdx") {
           throw new Error("Block is not MDX type");
         }
-        const cacheKey = block.id;
+        const cacheKey = `${block.id}\0${block.payload.raw ?? ""}`;
         const cachedPromise = this.cache.get(cacheKey);
         if (cachedPromise) {
           return cachedPromise;
@@ -921,7 +921,11 @@ var defaultInlineComponents = {
     const n = number ?? "?";
     const href = number ? `#fn:${n}` : void 0;
     const id = number ? `fnref:${n}` : void 0;
-    return React4.createElement("sup", { className: "footnote-ref" }, React4.createElement("a", { href, id, "data-label": label }, String(n)));
+    return React4.createElement(
+      "sup",
+      { className: "footnote-ref" },
+      React4.createElement("a", { href, id, "data-label": label, style: { color: "var(--foreground)", textDecoration: "underline" } }, String(n))
+    );
   }
 };
 var defaultBlockComponents = {
@@ -1064,7 +1068,7 @@ var defaultBlockComponents = {
       dangerouslySetInnerHTML: { __html: htmlString }
     });
   },
-  mdx: ({ compiledRef, compiledModule, status, errorMessage, raw }) => {
+  mdx: ({ compiledRef, compiledModule, status, errorMessage }) => {
     const [Comp, setComp] = React4.useState(null);
     const [internalError, setInternalError] = React4.useState(null);
     const [renderError, setRenderError] = React4.useState(null);
@@ -1165,7 +1169,6 @@ var defaultBlockComponents = {
     const waitingForVisibility = deferHydration && !shouldHydrate && Boolean(resolvedId);
     const pendingLabel = waitingForVisibility ? "MDX ready (hydrate on view)\u2026" : compileMode === "worker" ? "Compiling MDX (client)\u2026" : "Compiling MDX (server)\u2026";
     const message = failureMessage ?? (compileMode === "worker" ? "MDX compilation failed in client mode. Try switching back to server rendering or restarting the stream." : "MDX compilation failed. Try restarting the stream.");
-    const rawFallback = typeof raw === "string" && raw.trim().length > 0 ? React4.createElement("pre", { className: "markdown-mdx-fallback" }, raw) : null;
     const allowRetry = Boolean(internalError || renderError);
     const retryButton = allowRetry ? React4.createElement(
       "button",
@@ -1177,9 +1180,10 @@ var defaultBlockComponents = {
       "Retry hydration"
     ) : null;
     const errorPanel = React4.createElement(
-      "div",
-      { className: "markdown-mdx-error" },
-      React4.createElement(React4.Fragment, null, React4.createElement("strong", null, "MDX failed"), React4.createElement("div", null, message))
+      React4.Fragment,
+      null,
+      React4.createElement("strong", null, "MDX failed"),
+      React4.createElement("div", null, message)
     );
     if (Comp && !failureMessage) {
       return React4.createElement(
@@ -1202,14 +1206,13 @@ var defaultBlockComponents = {
       return React4.createElement(
         "div",
         {
-          className: "markdown-mdx",
+          className: "markdown-mdx error",
           ref: containerRef,
           "data-mdx-ref": pendingId,
           "data-mdx-status": "error",
           "data-mdx-mode": compileMode
         },
         errorPanel,
-        rawFallback,
         retryButton
       );
     }
@@ -1236,7 +1239,16 @@ var defaultBlockComponents = {
         { key: item.number, id: `fn:${item.number}` },
         renderInlineNodes(item.inlines, defaultInlineComponents),
         " ",
-        React4.createElement("a", { href: `#fnref:${item.number}`, className: "footnote-backref", "aria-label": "Back to content" }, "\u21A9")
+        React4.createElement(
+          "a",
+          {
+            href: `#fnref:${item.number}`,
+            className: "footnote-backref",
+            "aria-label": "Back to content",
+            style: { color: "var(--foreground)", textDecoration: "underline" }
+          },
+          "\u21A9"
+        )
       )
     );
     return React4.createElement("section", { className: "footnotes" }, React4.createElement("hr", {}), React4.createElement("ol", {}, listItems));
@@ -1782,7 +1794,10 @@ function useCodeHighlightRequester() {
 }
 
 // src/renderer/patch-batching.ts
-import { isHeavyPatch, splitPatchBatch } from "@stream-mdx/core/perf/patch-batching";
+import { getPatchKind, isHeavyPatch, splitPatchBatch } from "@stream-mdx/core/perf/patch-batching";
+
+// src/renderer/patch-commit-scheduler.ts
+import { getPatchKind as getPatchKind2 } from "@stream-mdx/core/perf/patch-batching";
 
 // src/renderer/patch-coalescing.ts
 import {
@@ -1800,6 +1815,9 @@ var COALESCING_DURATION_ACTIVATE_MS = 6;
 var COALESCING_DURATION_DEACTIVATE_MS = 4;
 var RETAIN_TOUCHED_IN_HISTORY = typeof process !== "undefined" && process.env ? process.env.NODE_ENV !== "production" : true;
 var EMPTY_TOUCHED_SET = /* @__PURE__ */ new Set();
+function shouldSkipCoalescing(patches) {
+  return patches.length <= 1;
+}
 function getDefaultNow() {
   if (typeof performance !== "undefined" && typeof performance.now === "function") {
     return () => performance.now();
@@ -1826,8 +1844,9 @@ function getDefaultCancelRaf() {
 }
 var PatchCommitScheduler = class {
   constructor(params) {
-    this.highQueue = [];
-    this.lowQueue = [];
+    this.semanticQueue = [];
+    this.enrichmentHighQueue = [];
+    this.enrichmentLowQueue = [];
     this.scheduled = false;
     this.flushing = false;
     this.scheduledHandle = null;
@@ -1839,6 +1858,7 @@ var PatchCommitScheduler = class {
     this.scheduleToken = 0;
     this.coalescingDurationSamples = [];
     this.adaptiveBudgetActive = false;
+    this.flushCount = 0;
     this.store = params.store;
     this.onFlush = params.onFlush;
     this.frameBudgetMs = Math.max(1, params.options?.frameBudgetMs ?? 10);
@@ -1854,6 +1874,8 @@ var PatchCommitScheduler = class {
     this.maxLowPriorityBatchesPerFlush = params.options?.maxLowPriorityBatchesPerFlush ?? 2;
     this.urgentQueueThreshold = Math.max(1, params.options?.urgentQueueThreshold ?? 4);
     this.historyLimit = Math.max(1, params.options?.historyLimit ?? 200);
+    this.startupMicrotaskFlushes = Math.max(0, Math.floor(params.options?.startupMicrotaskFlushes ?? 0));
+    this.adaptiveBudgeting = params.options?.adaptiveBudgeting ?? true;
     const requestedBatch = params.options?.batch;
     if (requestedBatch === "microtask") {
       this.batchStrategy = "microtask";
@@ -1880,19 +1902,23 @@ var PatchCommitScheduler = class {
       patches: input.patches,
       meta: input.meta ?? {},
       receivedAt: input.meta?.receivedAt ?? this.now(),
+      kind: input.meta?.kind === "semantic" || input.meta?.kind === "enrichment" ? input.meta.kind : input.patches.some((patch) => getPatchKind2(patch) === "semantic") ? "semantic" : "enrichment",
       priority: input.meta?.priority === "low" ? "low" : "high"
     };
-    if (batch.priority === "low") {
-      this.lowQueue.push(batch);
+    if (batch.kind === "semantic") {
+      batch.priority = "high";
+      this.semanticQueue.push(batch);
+    } else if (batch.priority === "low") {
+      this.enrichmentLowQueue.push(batch);
     } else {
-      this.highQueue.push(batch);
+      this.enrichmentHighQueue.push(batch);
     }
     if (!this.paused) {
       this.schedule();
     }
   }
   flushAll() {
-    if (this.highQueue.length === 0 && this.lowQueue.length === 0 && !this.flushing) {
+    if (this.semanticQueue.length === 0 && this.enrichmentHighQueue.length === 0 && this.enrichmentLowQueue.length === 0 && !this.flushing) {
       return null;
     }
     this.cancelScheduled();
@@ -1902,9 +1928,11 @@ var PatchCommitScheduler = class {
   }
   clear() {
     this.cancelScheduled();
-    this.highQueue = [];
-    this.lowQueue = [];
+    this.semanticQueue = [];
+    this.enrichmentHighQueue = [];
+    this.enrichmentLowQueue = [];
     this.flushing = false;
+    this.flushCount = 0;
     this.coalescingDurationSamples = [];
     this.adaptiveBudgetActive = false;
     this.adaptiveHighBatchCap = void 0;
@@ -1912,10 +1940,10 @@ var PatchCommitScheduler = class {
     this.maybeResolveIdle();
   }
   getPendingCount() {
-    return this.highQueue.length + this.lowQueue.length;
+    return this.semanticQueue.length + this.enrichmentHighQueue.length + this.enrichmentLowQueue.length;
   }
   isIdle() {
-    return !this.flushing && !this.scheduled && this.highQueue.length === 0 && this.lowQueue.length === 0;
+    return !this.flushing && !this.scheduled && this.semanticQueue.length === 0 && this.enrichmentHighQueue.length === 0 && this.enrichmentLowQueue.length === 0;
   }
   awaitIdle() {
     if (this.isIdle()) {
@@ -1955,7 +1983,8 @@ var PatchCommitScheduler = class {
       this.runFlush(this.frameBudgetMs, false);
       this.maybeResolveIdle();
     };
-    if (this.batchStrategy === "microtask" && typeof queueMicrotask === "function") {
+    const useStartupMicrotask = this.batchStrategy !== "microtask" && this.startupMicrotaskFlushes > 0 && this.flushCount < this.startupMicrotaskFlushes && typeof queueMicrotask === "function";
+    if ((this.batchStrategy === "microtask" || useStartupMicrotask) && typeof queueMicrotask === "function") {
       this.scheduledViaRaf = false;
       this.scheduledHandle = token;
       queueMicrotask(execute);
@@ -1985,12 +2014,14 @@ var PatchCommitScheduler = class {
     if (this.paused && !manual) {
       return null;
     }
-    if (this.highQueue.length === 0 && this.lowQueue.length === 0) {
+    if (this.semanticQueue.length === 0 && this.enrichmentHighQueue.length === 0 && this.enrichmentLowQueue.length === 0) {
       return null;
     }
     this.flushing = true;
     const startedAt = this.now();
-    const initialQueueSize = this.highQueue.length + this.lowQueue.length;
+    const initialSemanticQueueSize = this.semanticQueue.length;
+    const initialEnrichmentQueueSize = this.enrichmentHighQueue.length + this.enrichmentLowQueue.length;
+    const initialQueueSize = initialSemanticQueueSize + initialEnrichmentQueueSize;
     const batches = [];
     let totalInputPatches = 0;
     let totalAppliedPatches = 0;
@@ -2005,7 +2036,15 @@ var PatchCommitScheduler = class {
         consumed += 1;
         const applyStart = this.now();
         const queueDelayMs = Math.max(0, applyStart - next.receivedAt);
-        const { patches: coalesced, metrics: coalescingMetrics } = coalescePatchesWithMetrics(next.patches, DEFAULT_COALESCE_CONFIG);
+        let coalesced;
+        let coalescingMetrics;
+        if (shouldSkipCoalescing(next.patches)) {
+          coalesced = next.patches;
+        } else {
+          const result = coalescePatchesWithMetrics(next.patches, DEFAULT_COALESCE_CONFIG);
+          coalesced = result.patches;
+          coalescingMetrics = result.metrics;
+        }
         const touched = this.store.applyPatches(coalesced, {
           coalesced: true,
           metrics: coalescingMetrics
@@ -2025,6 +2064,7 @@ var PatchCommitScheduler = class {
           receivedAt: next.receivedAt,
           appliedAt: applyStart,
           priority: next.priority,
+          kind: next.kind,
           coalescing: coalescingMetrics
         });
         if (maxBatches && batches.length - startingBatchCount >= maxBatches) {
@@ -2041,27 +2081,32 @@ var PatchCommitScheduler = class {
         queue.splice(0, consumed);
       }
     };
-    const initialHighQueueSize = this.highQueue.length;
+    processQueue(this.semanticQueue, void 0, Number.POSITIVE_INFINITY);
+    const initialHighQueueSize = this.enrichmentHighQueue.length;
     const configuredHighLimit = manual || !this.maxBatchesPerFlush ? void 0 : initialHighQueueSize > this.maxBatchesPerFlush ? void 0 : this.maxBatchesPerFlush;
-    const highBatchLimit = this.adaptiveHighBatchCap ?? configuredHighLimit;
-    processQueue(this.highQueue, highBatchLimit, budgetMs);
+    const highBatchLimit = this.adaptiveBudgeting ? this.adaptiveHighBatchCap ?? configuredHighLimit : configuredHighLimit;
+    processQueue(this.enrichmentHighQueue, highBatchLimit, budgetMs);
     if (manual) {
-      processQueue(this.lowQueue, void 0, Number.POSITIVE_INFINITY);
-    } else if (this.lowQueue.length > 0) {
+      processQueue(this.enrichmentLowQueue, void 0, Number.POSITIVE_INFINITY);
+    } else if (this.enrichmentLowQueue.length > 0) {
       elapsed = this.now() - startedAt;
       const budgetForLow = Math.max(0, this.lowPriorityFrameBudgetMs - elapsed);
-      if (budgetForLow > 0) {
-        const initialLowQueueSize = this.lowQueue.length;
+      const processedHigherPriorityWork = batches.length > 0;
+      if (budgetForLow > 0 || !processedHigherPriorityWork) {
+        const initialLowQueueSize = this.enrichmentLowQueue.length;
         const configuredLowLimit = manual || !this.maxLowPriorityBatchesPerFlush ? void 0 : initialLowQueueSize > this.maxLowPriorityBatchesPerFlush ? void 0 : this.maxLowPriorityBatchesPerFlush;
-        const lowBatchLimit = this.adaptiveLowBatchCap ?? configuredLowLimit;
-        processQueue(this.lowQueue, lowBatchLimit, budgetForLow);
+        const lowBatchLimit = this.adaptiveBudgeting ? this.adaptiveLowBatchCap ?? configuredLowLimit : configuredLowLimit;
+        processQueue(this.enrichmentLowQueue, lowBatchLimit, budgetForLow);
       }
     }
     this.flushing = false;
     const completedAt = this.now();
     const totalDurationMs = completedAt - startedAt;
-    const remaining = this.highQueue.length + this.lowQueue.length;
+    const remainingSemantic = this.semanticQueue.length;
+    const remainingEnrichment = this.enrichmentHighQueue.length + this.enrichmentLowQueue.length;
+    const remaining = remainingSemantic + remainingEnrichment;
     if (batches.length > 0) {
+      this.flushCount += 1;
       try {
         this.onFlush({
           batches,
@@ -2069,7 +2114,11 @@ var PatchCommitScheduler = class {
           totalAppliedPatches,
           totalDurationMs,
           remainingQueueSize: remaining,
+          remainingSemanticQueueSize: remainingSemantic,
+          remainingEnrichmentQueueSize: remainingEnrichment,
           queueDepthBefore: initialQueueSize,
+          semanticQueueDepthBefore: initialSemanticQueueSize,
+          enrichmentQueueDepthBefore: initialEnrichmentQueueSize,
           flushStartedAt: startedAt,
           flushCompletedAt: completedAt
         });
@@ -2080,21 +2129,27 @@ var PatchCommitScheduler = class {
     if (remaining > 0 && !this.paused) {
       this.schedule();
     }
-    const coalescingStats = this.computeCoalescingDurationStats();
-    this.updateAdaptiveBudget(coalescingStats.p95);
-    const adaptiveState = this.snapshotAdaptiveBudget(coalescingStats.p95 ?? null);
+    const coalescingStats = this.adaptiveBudgeting ? this.computeCoalescingDurationStats() : { sampleCount: this.coalescingDurationSamples.length, p95: null };
+    if (this.adaptiveBudgeting) {
+      this.updateAdaptiveBudget(coalescingStats.p95);
+    }
+    const adaptiveState = this.adaptiveBudgeting ? this.snapshotAdaptiveBudget(coalescingStats.p95 ?? null) : void 0;
     const flushResult = batches.length > 0 ? {
       batches,
       totalPatches: totalInputPatches,
       totalAppliedPatches,
       totalDurationMs,
       remainingQueueSize: remaining,
+      remainingSemanticQueueSize: remainingSemantic,
+      remainingEnrichmentQueueSize: remainingEnrichment,
       queueDepthBefore: initialQueueSize,
+      semanticQueueDepthBefore: initialSemanticQueueSize,
+      enrichmentQueueDepthBefore: initialEnrichmentQueueSize,
       flushStartedAt: startedAt,
       flushCompletedAt: completedAt,
       coalescingDurationP95: coalescingStats.p95 ?? void 0,
       coalescingDurationSampleCount: coalescingStats.sampleCount,
-      adaptiveBudgetActive: adaptiveState.active,
+      adaptiveBudgetActive: adaptiveState?.active,
       adaptiveBudgetState: adaptiveState
     } : null;
     if (flushResult) {
@@ -2130,6 +2185,9 @@ var PatchCommitScheduler = class {
     };
   }
   updateAdaptiveBudget(p95) {
+    if (!this.adaptiveBudgeting) {
+      return;
+    }
     if (p95 !== null && p95 > COALESCING_DURATION_ACTIVATE_MS) {
       if (!this.adaptiveBudgetActive) {
         this.adaptiveBudgetActive = true;
@@ -2203,11 +2261,13 @@ var PatchCommitScheduler = class {
   }
   restart() {
     this.cancelScheduled();
-    this.highQueue = [];
-    this.lowQueue = [];
+    this.semanticQueue = [];
+    this.enrichmentHighQueue = [];
+    this.enrichmentLowQueue = [];
     this.flushing = false;
     this.sequence = 0;
     this.history = [];
+    this.flushCount = 0;
     this.scheduleToken++;
     this.paused = false;
     this.coalescingDurationSamples = [];
@@ -2254,6 +2314,12 @@ var PatchCommitScheduler = class {
     if (typeof options.historyLimit !== "undefined") {
       this.setHistoryLimit(options.historyLimit);
     }
+    if (typeof options.startupMicrotaskFlushes !== "undefined") {
+      this.startupMicrotaskFlushes = Math.max(0, Math.floor(options.startupMicrotaskFlushes));
+    }
+    if (typeof options.adaptiveBudgeting !== "undefined") {
+      this.adaptiveBudgeting = options.adaptiveBudgeting;
+    }
     if (typeof options.batch !== "undefined") {
       const requestedBatch = options.batch;
       if (requestedBatch === "microtask") {
@@ -2288,6 +2354,7 @@ import {
   sanitizeHTML as sanitizeHTML2,
   PATCH_ROOT_ID
 } from "@stream-mdx/core";
+import { getPatchKind as getPatchKind3 } from "@stream-mdx/core/perf/patch-batching";
 
 // src/renderer/list-utils.ts
 function updateNodeDepth(node, depth) {
@@ -2383,12 +2450,28 @@ function snapshotToBlock(node) {
   }
   return null;
 }
-var nodeSnapshotCache = /* @__PURE__ */ new Map();
-var childrenSnapshotCache = /* @__PURE__ */ new Map();
+var nodeSnapshotCacheByMap = /* @__PURE__ */ new WeakMap();
+var childrenSnapshotCacheByMap = /* @__PURE__ */ new WeakMap();
 var NODE_SNAPSHOT_CACHE_LIMIT = 5e4;
 var CHILDREN_SNAPSHOT_CACHE_LIMIT = 5e4;
 var NODE_SNAPSHOT_CACHE_BUFFER = Math.max(200, Math.floor(NODE_SNAPSHOT_CACHE_LIMIT * 0.1));
 var CHILDREN_SNAPSHOT_CACHE_BUFFER = Math.max(200, Math.floor(CHILDREN_SNAPSHOT_CACHE_LIMIT * 0.1));
+function getNodeSnapshotCacheForMap(map) {
+  let cache = nodeSnapshotCacheByMap.get(map);
+  if (!cache) {
+    cache = /* @__PURE__ */ new Map();
+    nodeSnapshotCacheByMap.set(map, cache);
+  }
+  return cache;
+}
+function getChildrenSnapshotCacheForMap(map) {
+  let cache = childrenSnapshotCacheByMap.get(map);
+  if (!cache) {
+    cache = /* @__PURE__ */ new Map();
+    childrenSnapshotCacheByMap.set(map, cache);
+  }
+  return cache;
+}
 function pruneCache(cache, max, buffer) {
   if (cache.size <= max + buffer) return;
   let remaining = cache.size - max;
@@ -2398,6 +2481,14 @@ function pruneCache(cache, max, buffer) {
     if (remaining <= 0) break;
   }
 }
+function deleteSnapshotCacheEntry(map, id) {
+  getNodeSnapshotCacheForMap(map).delete(id);
+  getChildrenSnapshotCacheForMap(map).delete(id);
+}
+function clearSnapshotCaches(map) {
+  getNodeSnapshotCacheForMap(map).clear();
+  getChildrenSnapshotCacheForMap(map).clear();
+}
 var EMPTY_CHILDREN = Object.freeze([]);
 var EMPTY_NODE_SNAPSHOT = Object.freeze({ version: -1, node: void 0 });
 var EMPTY_CHILDREN_SNAPSHOT = Object.freeze({
@@ -2565,9 +2656,57 @@ function createRootRecord() {
     parentId: null,
     children: [],
     props: {},
-    version: 0
+    version: 0,
+    blockEpoch: 0
   };
 }
+function readNumericEpoch(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return void 0;
+  }
+  return value;
+}
+function readSnapshotBlockEpoch(snapshot) {
+  return readNumericEpoch(snapshot.meta?.blockEpoch);
+}
+function readPatchBlockEpoch(patch) {
+  if (patch.op === "setHTML") {
+    return readNumericEpoch(patch.patchMeta?.blockEpoch);
+  }
+  return readNumericEpoch(patch.meta?.blockEpoch);
+}
+function readPatchParseEpoch(patch) {
+  if (patch.op === "setHTML") {
+    return readNumericEpoch(patch.patchMeta?.parseEpoch);
+  }
+  return readNumericEpoch(patch.meta?.parseEpoch);
+}
+function readPatchTx(patch) {
+  if (patch.op === "setHTML") {
+    return readNumericEpoch(patch.patchMeta?.tx);
+  }
+  return readNumericEpoch(patch.meta?.tx);
+}
+function assignSubtreeBlockEpoch(map, rootId, blockEpoch, touched) {
+  const root = map.get(rootId);
+  if (!root) return;
+  const stack = [root];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (!node) continue;
+    if (node.blockEpoch !== blockEpoch) {
+      node.blockEpoch = blockEpoch;
+      node.version += 1;
+      touched?.add(node.id);
+    }
+    for (const childId of node.children) {
+      const child = map.get(childId);
+      if (child) {
+        stack.push(child);
+      }
+    }
+  }
+}
 function ensureArray(value) {
   return Array.isArray(value) ? value : [];
 }
@@ -2627,7 +2766,7 @@ function escapeHtml2(value) {
 }
 function stripOuterLineSpan(html) {
   if (!html) return null;
-  const openTagMatch = html.match(/<span[^>]*>/i);
+  const openTagMatch = html.match(/<span[^>]*class="[^"]*\bline\b[^"]*"[^>]*>/i);
   if (!openTagMatch) {
     return null;
   }
@@ -2676,8 +2815,7 @@ function normalizeCodeBlockChildren(nodes, parent, touched) {
     if (node.type !== "code-line") {
       anomalies.push(`type-mismatch:${node.id}:${node.type}`);
       nodes.delete(node.id);
-      nodeSnapshotCache.delete(node.id);
-      childrenSnapshotCache.delete(node.id);
+      deleteSnapshotCacheEntry(nodes, node.id);
       touched.add(node.id);
       continue;
     }
@@ -2721,16 +2859,14 @@ function normalizeCodeBlockChildren(nodes, parent, touched) {
     const existing = nodes.get(desiredId);
     if (existing && existing !== node) {
       nodes.delete(desiredId);
-      nodeSnapshotCache.delete(desiredId);
-      childrenSnapshotCache.delete(desiredId);
+      deleteSnapshotCacheEntry(nodes, desiredId);
       touched.add(desiredId);
       mutated = true;
     }
     if (node.id !== desiredId) {
       const previousId = node.id;
       nodes.delete(node.id);
-      nodeSnapshotCache.delete(previousId);
-      childrenSnapshotCache.delete(previousId);
+      deleteSnapshotCacheEntry(nodes, previousId);
       node.id = desiredId;
       nodes.set(desiredId, node);
       touched.add(desiredId);
@@ -2761,8 +2897,7 @@ function normalizeCodeBlockChildren(nodes, parent, touched) {
   for (const [id, record] of nodes) {
     if (record.parentId === parent.id && record.type === "code-line" && !allowed.has(id)) {
       nodes.delete(id);
-      nodeSnapshotCache.delete(id);
-      childrenSnapshotCache.delete(id);
+      deleteSnapshotCacheEntry(nodes, id);
       touched.add(id);
       mutated = true;
     }
@@ -2846,8 +2981,10 @@ function normalizeCodeLineProps(incoming, previous) {
 }
 function createCodeLineProps(index, text, highlight, tokens) {
   const safeText = typeof text === "string" ? text : "";
-  const sanitized = sanitizeLineInnerHtml(highlight, safeText);
-  const html = sanitized && sanitized.length >= safeText.length ? sanitized : escapeHtml2(safeText);
+  const hasIncomingHighlight = typeof highlight === "string" && highlight.trim().length > 0;
+  const sanitized = hasIncomingHighlight ? sanitizeLineInnerHtml(highlight, safeText) : null;
+  const hasRenderableTokens = tokens !== void 0 && tokens !== null;
+  const html = sanitized && sanitized.length >= safeText.length ? sanitized : hasRenderableTokens ? null : escapeHtml2(safeText);
   const props = {
     index,
     text: safeText,
@@ -2958,6 +3095,18 @@ function validateCodeBlockChildren(nodes, parent) {
       issues.push({ kind: "dangling-node", id });
     }
   }
+  if (parent.block?.isFinalized) {
+    const snapshot = createBlockSnapshot(cloneBlock(parent.block));
+    const expectedChildren = ensureArray(snapshot.children).filter((child) => child.type === "code-line");
+    if (expectedChildren.length !== parent.children.length) {
+      issues.push({
+        kind: "line-count-mismatch",
+        id: parent.id,
+        expected: expectedChildren.length,
+        actual: parent.children.length
+      });
+    }
+  }
   return { ok: issues.length === 0, issues };
 }
 function rebuildCodeBlockFromSnapshot(nodes, parent, touched, issues) {
@@ -2974,7 +3123,7 @@ function rebuildCodeBlockFromSnapshot(nodes, parent, touched, issues) {
   }
   const snapshot = createBlockSnapshot(cloneBlock(parent.block));
   removeSubtree(nodes, parent.id, touched);
-  const inserted = insertSnapshotAt(nodes, ancestor, index, snapshot);
+  const inserted = insertSnapshotAt(nodes, ancestor, index, snapshot, touched, parent.blockEpoch);
   if (!inserted) {
     return false;
   }
@@ -2997,7 +3146,55 @@ function arraysEqual(a, b) {
   }
   return true;
 }
-function buildNodeFromSnapshot(map, snapshot, parentId) {
+function expectedCodeLineId(parentId, index) {
+  return `${parentId}::line:${index}`;
+}
+function collectStoreInvariantViolations(nodes) {
+  const violations = [];
+  for (const [id, node] of nodes) {
+    if (node.type === "__root__") continue;
+    if (node.children.length > 1) {
+      const seen = /* @__PURE__ */ new Set();
+      for (const childId of node.children) {
+        if (seen.has(childId)) {
+          violations.push(`duplicate child id:${id}:${childId}`);
+        } else {
+          seen.add(childId);
+        }
+      }
+    }
+    if (node.type === "list") {
+      const parent = node.parentId ? nodes.get(node.parentId) : void 0;
+      if (parent?.type === "list-item" && node.children.length === 0) {
+        violations.push(`empty nested list:${id}`);
+      }
+    }
+    if (node.type === "code") {
+      for (let index = 0; index < node.children.length; index += 1) {
+        const childId = node.children[index];
+        const child = nodes.get(childId);
+        if (!child) {
+          violations.push(`missing code-line node:${node.id}:${childId}`);
+          continue;
+        }
+        if (child.type !== "code-line") {
+          violations.push(`non-code child in code block:${node.id}:${child.id}:${child.type}`);
+          continue;
+        }
+        const expectedId = expectedCodeLineId(node.id, index);
+        if (child.id !== expectedId) {
+          violations.push(`code-line id mismatch:${node.id}:${child.id}:${expectedId}`);
+        }
+        const indexProp = typeof child.props?.index === "number" ? child.props.index : null;
+        if (indexProp !== index) {
+          violations.push(`code-line index mismatch:${node.id}:${child.id}:${indexProp}:${index}`);
+        }
+      }
+    }
+  }
+  return violations;
+}
+function buildNodeFromSnapshot(map, snapshot, parentId, blockEpoch) {
   const record = {
     id: snapshot.id,
     type: snapshot.type,
@@ -3007,6 +3204,7 @@ function buildNodeFromSnapshot(map, snapshot, parentId) {
     meta: snapshot.meta ? { ...snapshot.meta } : void 0,
     range: snapshot.range ? { ...snapshot.range } : void 0,
     version: 0,
+    blockEpoch,
     block: snapshotToBlock(snapshot) ?? void 0
   };
   if (record.type === "code") {
@@ -3015,7 +3213,7 @@ function buildNodeFromSnapshot(map, snapshot, parentId) {
   map.set(record.id, record);
   const childSnapshots = ensureArray(snapshot.children);
   for (const child of childSnapshots) {
-    const childRecord = buildNodeFromSnapshot(map, child, record.id);
+    const childRecord = buildNodeFromSnapshot(map, child, record.id, blockEpoch);
     record.children.push(childRecord.id);
   }
   return record;
@@ -3043,8 +3241,7 @@ function removeSubtree(map, id, touched) {
       }
     }
     map.delete(node.id);
-    nodeSnapshotCache.delete(node.id);
-    childrenSnapshotCache.delete(node.id);
+    deleteSnapshotCacheEntry(map, node.id);
     touched.add(node.id);
     for (const childId of node.children) {
       const child = map.get(childId);
@@ -3076,13 +3273,13 @@ function resolveParent(map, path) {
   }
   return map.get(path.blockId);
 }
-function insertSnapshotAt(map, parent, index, snapshot, touched) {
+function insertSnapshotAt(map, parent, index, snapshot, touched, blockEpoch) {
   if (!parent) return null;
   const existingIndex = parent.children.indexOf(snapshot.id);
   if (existingIndex !== -1) {
     removeSubtree(map, parent.children[existingIndex], touched ?? /* @__PURE__ */ new Set());
   }
-  const record = buildNodeFromSnapshot(map, snapshot, parent.id);
+  const record = buildNodeFromSnapshot(map, snapshot, parent.id, blockEpoch ?? readSnapshotBlockEpoch(snapshot) ?? parent.blockEpoch);
   const insertedIds = [];
   const queue = [record];
   while (queue.length > 0) {
@@ -3100,13 +3297,13 @@ function insertSnapshotAt(map, parent, index, snapshot, touched) {
   ensureUniqueChildren(parent, touched);
   return { record, insertedIds };
 }
-function replaceSnapshotAt(map, parent, index, snapshot, touched) {
+function replaceSnapshotAt(map, parent, index, snapshot, touched, blockEpoch) {
   if (!parent) return;
   if (index < 0 || index >= parent.children.length) return;
   const targetId = parent.children[index];
   parent.children.splice(index, 1);
   removeSubtree(map, targetId, touched);
-  const inserted = insertSnapshotAt(map, parent, index, snapshot, touched);
+  const inserted = insertSnapshotAt(map, parent, index, snapshot, touched, blockEpoch);
   if (inserted) {
     for (const id of inserted.insertedIds) {
       touched.add(id);
@@ -3126,6 +3323,24 @@ function createRendererStore(initialBlocks = []) {
   const listeners = /* @__PURE__ */ new Set();
   let notifyScheduled = false;
   let lastCoalescingMetrics = null;
+  let invariantViolations = [];
+  let transientDiagnostics = [];
+  let nextBlockEpoch = 1;
+  const debugCounters = {
+    appendLineGuardRejected: 0,
+    staleEpochRejected: 0,
+    storeInvariantViolationCount: 0
+  };
+  const allocateBlockEpoch = (preferred) => {
+    const resolved = readNumericEpoch(preferred);
+    if (resolved !== void 0) {
+      nextBlockEpoch = Math.max(nextBlockEpoch, resolved + 1);
+      return resolved;
+    }
+    const epoch = nextBlockEpoch;
+    nextBlockEpoch += 1;
+    return epoch;
+  };
   const getRaf = () => {
     if (typeof globalThis !== "undefined" && typeof globalThis.requestAnimationFrame === "function") {
       return globalThis.requestAnimationFrame;
@@ -3157,9 +3372,12 @@ function createRendererStore(initialBlocks = []) {
       }
     }
   }
+  function appendDiagnostic(message) {
+    transientDiagnostics = [...transientDiagnostics, message];
+    invariantViolations = [...invariantViolations, message];
+  }
   function rebuildFromBlocks(blocks) {
-    nodeSnapshotCache.clear();
-    childrenSnapshotCache.clear();
+    clearSnapshotCaches(nodes);
     nodes = /* @__PURE__ */ new Map();
     const root = createRootRecord();
     nodes.set(root.id, root);
@@ -3168,9 +3386,12 @@ function createRendererStore(initialBlocks = []) {
     for (let i = 0; i < blocks.length; i++) {
       const block = cloneBlock(blocks[i]);
       const snapshot = createBlockSnapshot(block);
-      insertSnapshotAt(nodes, root, root.children.length, snapshot);
+      insertSnapshotAt(nodes, root, root.children.length, snapshot, void 0, allocateBlockEpoch(readSnapshotBlockEpoch(snapshot)));
     }
     normalizeAllListDepths(nodes, /* @__PURE__ */ new Set(), PATCH_ROOT_ID);
+    transientDiagnostics = [];
+    invariantViolations = collectStoreInvariantViolations(nodes);
+    debugCounters.storeInvariantViolationCount += invariantViolations.length;
     version++;
     blocksDirty = true;
     scheduleNotify();
@@ -3235,11 +3456,57 @@ function createRendererStore(initialBlocks = []) {
           listDepthDirty = true;
         }
       };
-      const applyPropsUpdate = (at, props) => {
+      const semanticTxEpochs = /* @__PURE__ */ new Map();
+      const resolveBlockEpochTarget = (patch, at) => {
+        if ((patch.op === "insertChild" || patch.op === "replaceChild") && at.blockId === PATCH_ROOT_ID) {
+          const nodeId = patch.node?.id;
+          return nodeId ? nodes.get(nodeId) : void 0;
+        }
+        return nodes.get(at.blockId) ?? (at.nodeId ? nodes.get(at.nodeId) : void 0);
+      };
+      const rejectStaleEpochPatch = (patch, at) => {
+        const expectedBlockEpoch = readPatchBlockEpoch(patch);
+        const patchTx = readPatchTx(patch);
+        if (expectedBlockEpoch === void 0) {
+          return false;
+        }
+        if (getPatchKind3(patch) !== "semantic" || !at) {
+          return false;
+        }
+        const target = resolveBlockEpochTarget(patch, at);
+        if (!target || target.blockEpoch === expectedBlockEpoch) {
+          return false;
+        }
+        const txEpoch = at.blockId && patchTx !== void 0 ? semanticTxEpochs.get(at.blockId) : void 0;
+        if (txEpoch && txEpoch.tx === patchTx && txEpoch.blockEpoch === target.blockEpoch) {
+          return false;
+        }
+        debugCounters.staleEpochRejected += 1;
+        appendDiagnostic(
+          `stale epoch rejected:${patch.op}:${target.id}:expected=${expectedBlockEpoch}:actual=${target.blockEpoch}`
+        );
+        return true;
+      };
+      const advanceBlockEpoch = (blockId, touchedSet, preferredEpoch, tx) => {
+        if (!blockId || blockId === PATCH_ROOT_ID) {
+          return null;
+        }
+        const blockRoot = nodes.get(blockId);
+        if (!blockRoot) {
+          return null;
+        }
+        const nextEpoch = allocateBlockEpoch(preferredEpoch);
+        assignSubtreeBlockEpoch(nodes, blockRoot.id, nextEpoch, touchedSet);
+        if (tx !== void 0) {
+          semanticTxEpochs.set(blockRoot.id, { tx, blockEpoch: nextEpoch });
+        }
+        return nextEpoch;
+      };
+      const applyPropsUpdate = (at, props, preferredEpoch, tx, semanticUpdate = false) => {
         const perfStartLocal = perfEnabled ? getPerfNow() : 0;
         const targetId = at.nodeId ?? at.blockId;
         if (!targetId) return;
-        const target = nodes.get(targetId);
+        let target = nodes.get(targetId);
         if (!target) return;
         const parentType = target.parentId ? nodes.get(target.parentId)?.type : void 0;
         if (debugListPatches && (isListRelated(target.type) || isListRelated(parentType))) {
@@ -3266,6 +3533,9 @@ function createRendererStore(initialBlocks = []) {
             propsChanged = true;
           }
           if (propsChanged) {
+            if (semanticUpdate) {
+              advanceBlockEpoch(at.blockId, touched, preferredEpoch, tx);
+            }
             target.version++;
             touched.add(target.id);
             const parent = target.parentId ? nodes.get(target.parentId) : void 0;
@@ -3329,16 +3599,56 @@ function createRendererStore(initialBlocks = []) {
           }
         }
         let blockChanged = false;
+        let typeChanged = false;
+        let rebuiltFromFinalizedBlock = false;
+        let blockEpochAdvanced = false;
         const incomingBlock = props?.block;
         if (incomingBlock && typeof incomingBlock === "object") {
           target.block = cloneBlock(incomingBlock);
+          const previousType = target.type;
+          const incomingType = typeof target.block.type === "string" ? target.block.type : target.type;
+          if (incomingType !== target.type) {
+            target.type = incomingType;
+            typeChanged = true;
+            if (isListRelated(previousType) || isListRelated(target.type)) {
+              markListDepthDirty(target.id);
+            }
+          }
           if (target.type === "code") {
             applyCodeBlockMetadata(target);
           }
+          if (semanticUpdate) {
+            advanceBlockEpoch(at.blockId, touched, preferredEpoch, tx);
+            blockEpochAdvanced = true;
+          }
+          const shouldRebuildFinalizedTree = !at.nodeId && target.id === at.blockId && Boolean(target.block?.isFinalized) && target.type !== "code" && Boolean(target.parentId);
+          if (shouldRebuildFinalizedTree) {
+            const parent = target.parentId ? nodes.get(target.parentId) : void 0;
+            const index = parent ? parent.children.indexOf(target.id) : -1;
+            if (parent && index !== -1) {
+              const snapshot = createBlockSnapshot(cloneBlock(target.block));
+              replaceSnapshotAt(nodes, parent, index, snapshot, touched, target.blockEpoch);
+              mutatedBlocks = true;
+              blockChanged = true;
+              rebuiltFromFinalizedBlock = true;
+              const rebuilt = nodes.get(target.id);
+              if (isListRelated(previousType) || isListRelated(rebuilt?.type)) {
+                markListDepthDirty(target.id);
+              }
+              target = rebuilt ?? target;
+            }
+          }
           mutatedBlocks = true;
           blockChanged = true;
         }
-        if (propsChanged || blockChanged) {
+        if (rebuiltFromFinalizedBlock) {
+          return;
+        }
+        if (propsChanged || blockChanged || typeChanged) {
+          if (semanticUpdate && !blockEpochAdvanced) {
+            advanceBlockEpoch(at.blockId, touched, preferredEpoch, tx);
+            blockEpochAdvanced = true;
+          }
           target.version++;
           touched.add(target.id);
           let parentForNormalization;
@@ -3381,13 +3691,22 @@ function createRendererStore(initialBlocks = []) {
       const applyPatch = (patch) => {
         switch (patch.op) {
           case "insertChild": {
+            if (rejectStaleEpochPatch(patch, patch.at)) break;
             const parent = resolveParent(nodes, patch.at);
-            const inserted = insertSnapshotAt(nodes, parent, patch.index, patch.node, touched);
+            const inserted = insertSnapshotAt(
+              nodes,
+              parent,
+              patch.index,
+              patch.node,
+              touched,
+              allocateBlockEpoch(readPatchParseEpoch(patch) ?? readSnapshotBlockEpoch(patch.node))
+            );
             if (inserted) {
               for (const id of inserted.insertedIds) {
                 touched.add(id);
               }
               mutatedBlocks = true;
+              advanceBlockEpoch(patch.at.blockId, touched, readPatchParseEpoch(patch), readPatchTx(patch));
               if (isListRelated(inserted.record.type) || isListRelated(parent?.type)) {
                 markListDepthDirty(inserted.record.id);
                 if (parent) {
@@ -3407,6 +3726,7 @@ function createRendererStore(initialBlocks = []) {
             break;
           }
           case "deleteChild": {
+            if (rejectStaleEpochPatch(patch, patch.at)) break;
             const parent = resolveParent(nodes, patch.at);
             if (!parent) break;
             if (patch.index < 0 || patch.index >= parent.children.length) break;
@@ -3418,6 +3738,7 @@ function createRendererStore(initialBlocks = []) {
               touched.add(parent.id);
               ensureUniqueChildren(parent, touched);
               mutatedBlocks = true;
+              advanceBlockEpoch(patch.at.blockId, touched, readPatchParseEpoch(patch), readPatchTx(patch));
               if (isListRelated(parent.type) || isListRelated(removedNode?.type)) {
                 markListDepthDirty(parent.id);
               }
@@ -3434,11 +3755,20 @@ function createRendererStore(initialBlocks = []) {
             break;
           }
           case "replaceChild": {
+            if (rejectStaleEpochPatch(patch, patch.at)) break;
             const parent = resolveParent(nodes, patch.at);
             if (!parent) break;
-            replaceSnapshotAt(nodes, parent, patch.index, patch.node, touched);
+            replaceSnapshotAt(
+              nodes,
+              parent,
+              patch.index,
+              patch.node,
+              touched,
+              allocateBlockEpoch(readPatchParseEpoch(patch) ?? readSnapshotBlockEpoch(patch.node))
+            );
             touched.add(parent.id);
             mutatedBlocks = true;
+            advanceBlockEpoch(patch.at.blockId, touched, readPatchParseEpoch(patch), readPatchTx(patch));
             if (isListRelated(parent.type)) {
               markListDepthDirty(parent.id);
             }
@@ -3452,18 +3782,33 @@ function createRendererStore(initialBlocks = []) {
             break;
           }
           case "setProps": {
-            applyPropsUpdate(patch.at, patch.props);
+            if (rejectStaleEpochPatch(patch, patch.at)) break;
+            applyPropsUpdate(patch.at, patch.props, readPatchParseEpoch(patch), readPatchTx(patch), getPatchKind3(patch) === "semantic");
             break;
           }
           case "setPropsBatch": {
             const entries2 = Array.isArray(patch.entries) ? patch.entries : [];
             for (const entry of entries2) {
               if (!entry || !entry.at) continue;
-              applyPropsUpdate(entry.at, entry.props);
+              const entryPatch = {
+                op: "setProps",
+                at: entry.at,
+                props: entry.props,
+                meta: entry.meta ?? patch.meta
+              };
+              if (rejectStaleEpochPatch(entryPatch, entry.at)) continue;
+              applyPropsUpdate(
+                entry.at,
+                entry.props,
+                readPatchParseEpoch(entryPatch),
+                readPatchTx(entryPatch),
+                getPatchKind3(entryPatch) === "semantic"
+              );
             }
             break;
           }
           case "finalize": {
+            if (rejectStaleEpochPatch(patch, patch.at)) break;
             const target = nodes.get(patch.at.nodeId ?? patch.at.blockId);
             if (!target || !target.block) break;
             if (!target.block.isFinalized) {
@@ -3472,6 +3817,17 @@ function createRendererStore(initialBlocks = []) {
               target.version++;
               touched.add(target.id);
               mutatedBlocks = true;
+              if (!patch.at.nodeId && target.id === patch.at.blockId && target.type !== "code" && target.parentId) {
+                const parent = nodes.get(target.parentId);
+                const index = parent ? parent.children.indexOf(target.id) : -1;
+                if (parent && index !== -1) {
+                  const snapshot = createBlockSnapshot(cloneBlock(target.block));
+                  replaceSnapshotAt(nodes, parent, index, snapshot, touched, target.blockEpoch);
+                  if (isListRelated(target.type) || isListRelated(snapshot.type)) {
+                    markListDepthDirty(target.id);
+                  }
+                }
+              }
             }
             if (isListRelated(target.type)) {
               markListDepthDirty(target.id);
@@ -3485,6 +3841,7 @@ function createRendererStore(initialBlocks = []) {
             break;
           }
           case "reorder": {
+            if (rejectStaleEpochPatch(patch, patch.at)) break;
             const parent = resolveParent(nodes, patch.at);
             if (!parent) break;
             const length = parent.children.length;
@@ -3499,6 +3856,9 @@ function createRendererStore(initialBlocks = []) {
             parent.children.splice(to, 0, ...moved);
             parent.version++;
             touched.add(parent.id);
+            if (getPatchKind3(patch) === "semantic") {
+              advanceBlockEpoch(patch.at.blockId, touched, readPatchParseEpoch(patch), readPatchTx(patch));
+            }
             if (isListRelated(parent.type)) {
               markListDepthDirty(parent.id);
             }
@@ -3514,15 +3874,31 @@ function createRendererStore(initialBlocks = []) {
             break;
           }
           case "appendLines": {
+            if (rejectStaleEpochPatch(patch, patch.at)) break;
             const parent = resolveParent(nodes, patch.at);
             if (!parent) break;
-            const startIndex = Math.max(0, Math.min(patch.startIndex, parent.children.length));
+            if (parent.type !== "code") {
+              debugCounters.appendLineGuardRejected += 1;
+              appendDiagnostic(`appendLines target not code:${parent.id}:${parent.type}`);
+              break;
+            }
+            const requestedStartIndex = Math.max(0, patch.startIndex);
+            const startIndex = Math.max(0, Math.min(requestedStartIndex, parent.children.length));
             const lineCount = patch.lines?.length ?? 0;
             if (lineCount === 0) break;
+            const prefixMatches = parent.children.every((childId, index) => childId === expectedCodeLineId(parent.id, index));
+            const isStrictTailAppend = requestedStartIndex === parent.children.length;
+            if (!isStrictTailAppend || !prefixMatches) {
+              debugCounters.appendLineGuardRejected += 1;
+              appendDiagnostic(
+                `appendLines guard rejected:${parent.id}:requestedStart=${requestedStartIndex}:childCount=${parent.children.length}:prefixMatches=${prefixMatches}`
+              );
+              break;
+            }
             const originalChildren = parent.children.slice();
             const insertedIds = [];
             const insertedSet = /* @__PURE__ */ new Set();
-            const isTrailingAppend = startIndex >= originalChildren.length;
+            const isTrailingAppend = true;
             let parentChildrenChanged = false;
             let codeLinesMutated = false;
             for (let offset = 0; offset < lineCount; offset++) {
@@ -3564,7 +3940,8 @@ function createRendererStore(initialBlocks = []) {
                   parentId: parent.id,
                   children: [],
                   props: nextLineProps,
-                  version: 0
+                  version: 0,
+                  blockEpoch: parent.blockEpoch
                 };
                 nodes.set(lineId, record);
                 touched.add(lineId);
@@ -3614,6 +3991,7 @@ function createRendererStore(initialBlocks = []) {
             break;
           }
           case "setHTML": {
+            if (rejectStaleEpochPatch(patch, patch.at)) break;
             const target = nodes.get(patch.at.nodeId ?? patch.at.blockId);
             if (!target) break;
             const sanitized = patch.sanitized ? patch.html : sanitizeHTML2(patch.html);
@@ -3656,6 +4034,30 @@ function createRendererStore(initialBlocks = []) {
           applyPatch(patch);
         }
       }
+      const finalizedTableRoots = /* @__PURE__ */ new Set();
+      for (const touchedId of touched) {
+        let cursor = nodes.get(touchedId);
+        while (cursor && cursor.id !== PATCH_ROOT_ID) {
+          if (cursor.type === "table" && cursor.block?.isFinalized && cursor.parentId) {
+            finalizedTableRoots.add(cursor.id);
+            break;
+          }
+          cursor = cursor.parentId ? nodes.get(cursor.parentId) : void 0;
+        }
+      }
+      if (finalizedTableRoots.size > 0) {
+        for (const tableId of finalizedTableRoots) {
+          const tableNode = nodes.get(tableId);
+          if (!tableNode || !tableNode.block || !tableNode.parentId) continue;
+          const parent = nodes.get(tableNode.parentId);
+          if (!parent) continue;
+          const index = parent.children.indexOf(tableNode.id);
+          if (index === -1) continue;
+          const snapshot = createBlockSnapshot(cloneBlock(tableNode.block));
+          replaceSnapshotAt(nodes, parent, index, snapshot, touched, tableNode.blockEpoch);
+          mutatedBlocks = true;
+        }
+      }
       if (mutatedBlocks) {
         blocksDirty = true;
       }
@@ -3676,6 +4078,8 @@ function createRendererStore(initialBlocks = []) {
           normalizeListDepthsForIds(nodes, touched, listDepthDirtyNodes, PATCH_ROOT_ID);
         }
       }
+      invariantViolations = [...collectStoreInvariantViolations(nodes), ...transientDiagnostics];
+      debugCounters.storeInvariantViolationCount += invariantViolations.length;
       if (touched.size > 0 || mutatedBlocks) {
         version++;
         scheduleNotify();
@@ -3724,6 +4128,7 @@ function createRendererStore(initialBlocks = []) {
       if (!record) {
         return EMPTY_NODE_SNAPSHOT;
       }
+      const nodeSnapshotCache = getNodeSnapshotCacheForMap(nodes);
       const cached = nodeSnapshotCache.get(id);
       if (cached && cached.version === record.version && cached.node === record) {
         return cached;
@@ -3743,6 +4148,7 @@ function createRendererStore(initialBlocks = []) {
       if (!record) {
         return EMPTY_CHILDREN_SNAPSHOT;
       }
+      const childrenSnapshotCache = getChildrenSnapshotCacheForMap(nodes);
       const cached = childrenSnapshotCache.get(id);
       if (cached && cached.version === record.version) {
         return cached;
@@ -3752,6 +4158,12 @@ function createRendererStore(initialBlocks = []) {
       pruneCache(childrenSnapshotCache, CHILDREN_SNAPSHOT_CACHE_LIMIT, CHILDREN_SNAPSHOT_CACHE_BUFFER);
       return snapshot;
     },
+    getInvariantViolations() {
+      return invariantViolations.slice();
+    },
+    getDebugCounters() {
+      return { ...debugCounters };
+    },
     getLastCoalescingMetrics() {
       return lastCoalescingMetrics;
     },
@@ -3787,7 +4199,7 @@ function useRendererChildren(store, id) {
 }
 
 // src/renderer/node-views.tsx
-import { stripCodeFence } from "@stream-mdx/core";
+import { getDefaultCodeWrapperAttributes as getDefaultCodeWrapperAttributes2, stripCodeFence } from "@stream-mdx/core";
 import React7 from "react";
 
 // src/renderer/deferred-render-context.tsx
@@ -4229,8 +4641,10 @@ var ListBlockView = React7.memo(
         isFinalized: block?.isFinalized ?? false
       });
     }, [listDebugEnabled, blockId, depth, ordered, childIds, listItemIds, store, block?.isFinalized]);
-    const listStyle = React7.useMemo(() => {
-      if (!ordered || listItemIds.length === 0) return void 0;
+    const { listStyle, markerDigits } = React7.useMemo(() => {
+      if (!ordered || listItemIds.length === 0) {
+        return { listStyle: void 0, markerDigits: 1 };
+      }
       let maxDigits = 1;
       listItemIds.forEach((childId, index) => {
         const childNode = store.getNode(childId);
@@ -4242,9 +4656,14 @@ var ListBlockView = React7.memo(
         const digits = digitMatch ? digitMatch.length : text.length;
         if (digits > maxDigits) maxDigits = digits;
       });
-      const baseIndent = depth === 0 ? "2.5rem" : depth === 1 ? "2rem" : "1.5rem";
+      const baseIndent = depth === 0 ? "2rem" : depth === 1 ? "1.75rem" : "1.5rem";
+      const extraDigits = Math.max(0, maxDigits - 1);
       return {
-        ["--list-indent"]: `calc(${baseIndent} + ${maxDigits}ch)`
+        markerDigits: maxDigits,
+        listStyle: {
+          ["--list-indent"]: extraDigits > 0 ? `calc(${baseIndent} + ${extraDigits}ch)` : baseIndent,
+          ["--list-marker-digits"]: String(maxDigits)
+        }
       };
     }, [ordered, listItemIds, store, depth]);
     if (listItemIds.length === 0) return null;
@@ -4253,6 +4672,7 @@ var ListBlockView = React7.memo(
       {
         className: `markdown-list ${ordered ? "ordered" : "unordered"}`,
         "data-list-depth": depth,
+        "data-marker-digits": ordered ? markerDigits : void 0,
         "data-list-id": listDebugEnabled ? blockId : void 0,
         style: listStyle,
         children: listItemIds.map((childId, index) => /* @__PURE__ */ jsx(
@@ -4434,6 +4854,7 @@ var CodeBlockView = React7.memo(({ store, blockId, registry }) => {
     deferredConfig ? { ...deferredConfig, enabled: true } : { enabled: false }
   );
   if (!node || !node.block) return null;
+  const blockIsFinalized = node.block.isFinalized;
   const nodeVersion = node.version;
   const lines = React7.useMemo(() => {
     const seenIds = /* @__PURE__ */ new Set();
@@ -4464,13 +4885,25 @@ var CodeBlockView = React7.memo(({ store, blockId, registry }) => {
   const lang = typeof node.props?.lang === "string" ? node.props?.lang : node.block.payload.meta?.lang;
   const preAttrs = node.props?.preAttrs ?? void 0;
   const codeAttrs = node.props?.codeAttrs ?? void 0;
+  const blockMeta = node.block.payload.meta ?? void 0;
+  const lazyEnabled = Boolean(blockMeta?.lazyTokenization);
+  const lazyTokenizedUntil = typeof blockMeta?.lazyTokenizedUntil === "number" ? blockMeta.lazyTokenizedUntil : 0;
+  const lazyHighlightedLines = Array.isArray(blockMeta?.highlightedLines) ? blockMeta.highlightedLines.length : 0;
+  const lazyTokenLines = Array.isArray(blockMeta?.tokenLines) ? blockMeta.tokenLines.length : 0;
+  const lazySourceTextLineCount = React7.useMemo(() => {
+    const raw = typeof node.block?.payload.raw === "string" ? node.block.payload.raw : "";
+    const metaCode = typeof blockMeta?.code === "string" ? blockMeta.code : null;
+    const sourceText = resolveCodeSourceText(raw, metaCode);
+    if (sourceText.length === 0) return 0;
+    return sourceText.split("\n").length;
+  }, [blockMeta, node.block?.payload.raw]);
+  const totalLazyLineCount = Math.max(lines.length, lazyHighlightedLines, lazyTokenLines, lazySourceTextLineCount);
   const virtualizationConfig = DEFAULT_VIRTUALIZED_CODE_CONFIG;
   const virtualizationDisabled = typeof process !== "undefined" && typeof process.env === "object" && process.env.STREAM_MDX_DISABLE_VIRTUALIZED_CODE === "true";
-  const shouldVirtualize = !virtualizationDisabled && virtualizationConfig.enabled && lines.length >= virtualizationConfig.virtualizeThreshold;
+  const canVirtualize = node.block.isFinalized && !lazyEnabled;
+  const shouldVirtualize = canVirtualize && !virtualizationDisabled && virtualizationConfig.enabled && lines.length >= virtualizationConfig.virtualizeThreshold;
   const virtualization = useVirtualizedCode(lines, shouldVirtualize ? virtualizationConfig : { ...virtualizationConfig, enabled: false });
   const highlightRequester = useCodeHighlightRequester();
-  const lazyEnabled = Boolean(node.block.payload.meta?.lazyTokenization);
-  const lazyTokenizedUntil = typeof node.block.payload.meta?.lazyTokenizedUntil === "number" ? node.block.payload.meta.lazyTokenizedUntil : 0;
   const lastRangeRef = React7.useRef(null);
   const rafRef = React7.useRef(null);
   const idleRef = React7.useRef(null);
@@ -4551,29 +4984,111 @@ var CodeBlockView = React7.memo(({ store, blockId, registry }) => {
     virtualization.window.startIndex,
     virtualization.window.endIndex
   ]);
-  const highlightedHtml = React7.useMemo(() => {
-    if (!shouldVirtualize && node.block?.payload.highlightedHtml) {
-      return node.block.payload.highlightedHtml;
+  React7.useEffect(() => {
+    if (shouldVirtualize || !blockIsFinalized || !lazyEnabled || !highlightRequester) return;
+    if (totalLazyLineCount <= 0 || lazyTokenizedUntil >= totalLazyLineCount) return;
+    const nextRange = {
+      visibleStart: 0,
+      visibleEnd: totalLazyLineCount,
+      prefetchStart: 0,
+      prefetchEnd: totalLazyLineCount,
+      tokenizedUntil: lazyTokenizedUntil
+    };
+    const last = lastRangeRef.current;
+    if (last && last.visibleStart === nextRange.visibleStart && last.visibleEnd === nextRange.visibleEnd && last.prefetchStart === nextRange.prefetchStart && last.prefetchEnd === nextRange.prefetchEnd && last.tokenizedUntil === nextRange.tokenizedUntil) {
+      return;
+    }
+    lastRangeRef.current = nextRange;
+    if (rafRef.current !== null && typeof cancelAnimationFrame === "function") {
+      cancelAnimationFrame(rafRef.current);
     }
+    const requestFullHighlight = () => {
+      highlightRequester({
+        blockId,
+        startLine: 0,
+        endLine: totalLazyLineCount,
+        priority: "visible",
+        reason: "finalize-full"
+      });
+      rafRef.current = null;
+    };
+    if (typeof requestAnimationFrame === "function") {
+      rafRef.current = requestAnimationFrame(requestFullHighlight);
+    } else {
+      requestFullHighlight();
+    }
+  }, [blockId, blockIsFinalized, highlightRequester, lazyEnabled, lazyTokenizedUntil, shouldVirtualize, totalLazyLineCount]);
+  const highlightedHtml = React7.useMemo(() => {
+    const blockHtml = node.block?.payload.highlightedHtml ?? "";
+    const raw = typeof node.block?.payload.raw === "string" ? node.block.payload.raw : "";
+    const metaCode = typeof node.block?.payload.meta?.code === "string" ? (node.block?.payload.meta).code : null;
+    const sourceText = resolveCodeSourceText(raw, metaCode);
+    const sourceEndsWithNewline = sourceText.endsWith("\n");
+    const sourceLines = sourceText.length > 0 ? sourceText.split("\n") : [];
+    const rawFallbackLines = buildCodeFallbackLines(raw);
+    const deterministicWrapperAttrs = getDefaultCodeWrapperAttributes2(lang);
+    const composedPreAttrs = deterministicWrapperAttrs.preAttrs;
+    const composedCodeAttrs = deterministicWrapperAttrs.codeAttrs;
+    const shouldAppendTerminalNewline = (renderedLines) => {
+      if (!sourceEndsWithNewline || renderedLines.length === 0 || lines.length === 0) {
+        return false;
+      }
+      const lastRendered = renderedLines[renderedLines.length - 1];
+      const lastKnown = lines[lines.length - 1];
+      if (!lastRendered || !lastKnown || lastRendered.index !== lastKnown.index || lastRendered.text === "") {
+        return false;
+      }
+      const expectedRenderedLineCount = Math.max(0, sourceLines.length - 1);
+      const expectedLastRenderedLine = sourceLines.length >= 2 ? sourceLines[sourceLines.length - 2] ?? "" : "";
+      return renderedLines.length === expectedRenderedLineCount && lastRendered.text === expectedLastRenderedLine;
+    };
     if (lines.length > 0) {
       const hasLineHtml = lines.some((line) => typeof line.html === "string" && line.html.length > 0);
-      if (!hasLineHtml && node.block?.payload.highlightedHtml) {
-        return node.block.payload.highlightedHtml;
+      if (!hasLineHtml && blockHtml) {
+        return blockHtml;
       }
       if (shouldVirtualize) {
-        return composeHighlightedHtml(virtualization.window.visibleLines, preAttrs, codeAttrs);
+        return composeHighlightedHtml(
+          virtualization.window.visibleLines,
+          composedPreAttrs,
+          composedCodeAttrs,
+          shouldAppendTerminalNewline(virtualization.window.visibleLines)
+        );
+      }
+      return composeHighlightedHtml(lines, composedPreAttrs, composedCodeAttrs, shouldAppendTerminalNewline(lines));
+    }
+    if (!shouldVirtualize && blockHtml) {
+      const hasHighlightedLines = blockHtml.includes('class="line"');
+      if (!hasHighlightedLines && rawFallbackLines.length > 0) {
+        return composeHighlightedHtml(
+          rawFallbackLines,
+          composedPreAttrs,
+          composedCodeAttrs,
+          sourceEndsWithNewline && rawFallbackLines[rawFallbackLines.length - 1]?.text !== ""
+        );
       }
-      return composeHighlightedHtml(lines, preAttrs, codeAttrs);
+      return blockHtml;
     }
-    const blockHtml = node.block?.payload.highlightedHtml ?? "";
     if (blockHtml?.trim().match(/^```[\w-]*\s*$/)) {
-      const raw = node.block?.payload.raw ?? "";
-      if (raw.trim().length > 0) {
-        return composeHighlightedHtml([{ index: 0, text: raw, html: null, id: "temp" }], preAttrs, codeAttrs);
+      if (rawFallbackLines.length > 0) {
+        return composeHighlightedHtml(
+          rawFallbackLines,
+          composedPreAttrs,
+          composedCodeAttrs,
+          sourceEndsWithNewline && rawFallbackLines[rawFallbackLines.length - 1]?.text !== ""
+        );
       }
     }
+    if (!blockHtml && rawFallbackLines.length > 0) {
+      return composeHighlightedHtml(
+        rawFallbackLines,
+        composedPreAttrs,
+        composedCodeAttrs,
+        sourceEndsWithNewline && rawFallbackLines[rawFallbackLines.length - 1]?.text !== ""
+      );
+    }
     return blockHtml;
-  }, [shouldVirtualize, node.block?.payload.highlightedHtml, lines, preAttrs, codeAttrs, virtualization.window.visibleLines, node.block?.payload.raw]);
+  }, [blockIsFinalized, shouldVirtualize, node.block?.payload.highlightedHtml, node.block?.payload.meta, lines, lang, virtualization.window.visibleLines, node.block?.payload.raw]);
   const rendered = /* @__PURE__ */ jsx(
     CodeComponent,
     {
@@ -4585,13 +5100,19 @@ var CodeBlockView = React7.memo(({ store, blockId, registry }) => {
       codeAttrs
     }
   );
+  const effectiveLineCount = React7.useMemo(() => {
+    if (lines.length > 0) {
+      return lines.length;
+    }
+    return 1;
+  }, [lines.length]);
   const codeFrameClass = "not-prose flex flex-col rounded-lg border border-input pt-1 font-mono text-sm";
   const codeMetricsAttrs = {
     "data-code-block": "true",
     "data-block-id": blockId,
     "data-code-virtualized": shouldVirtualize ? "true" : "false",
-    "data-code-total-lines": String(lines.length),
-    "data-code-mounted-lines": String(shouldVirtualize ? virtualization.window.mountedLines : lines.length),
+    "data-code-total-lines": String(effectiveLineCount),
+    "data-code-mounted-lines": String(shouldVirtualize ? virtualization.window.mountedLines : effectiveLineCount),
     "data-code-window-size": String(virtualization.config.windowSize)
   };
   const codeView = shouldVirtualize ? (() => {
@@ -4637,21 +5158,152 @@ var CodeBlockView = React7.memo(({ store, blockId, registry }) => {
   return codeView;
 });
 CodeBlockView.displayName = "CodeBlockView";
-function composeHighlightedHtml(lines, preAttrs, codeAttrs) {
+function composeHighlightedHtml(lines, preAttrs, codeAttrs, appendTerminalNewline = false) {
   const lineMarkup = lines.map((line) => {
-    const content = line.html ?? escapeHtml3(line.text);
+    const content = line.html ?? renderTokenLineHtml(line.tokens) ?? escapeHtml3(line.text);
     const dataLine = Number.isFinite(line.index) ? ` data-line="${line.index + 1}"` : "";
     return `<span class="line"${dataLine}>${content}</span>`;
   }).join("\n");
   const preAttr = attrsToString(preAttrs);
   const codeAttr = attrsToString(codeAttrs);
-  return `<pre${preAttr}><code${codeAttr}>${lineMarkup}
-</code></pre>`;
+  return `<pre${preAttr}><code${codeAttr}>${lineMarkup}${appendTerminalNewline ? "\n" : ""}</code></pre>`;
+}
+var TOKEN_FONT_STYLE_ITALIC = 1;
+var TOKEN_FONT_STYLE_BOLD = 2;
+var TOKEN_FONT_STYLE_UNDERLINE = 4;
+var TOKEN_FONT_STYLE_STRIKETHROUGH = 8;
+function renderTokenLineHtml(tokens) {
+  if (!tokens || !Array.isArray(tokens.spans)) {
+    return null;
+  }
+  return mergeRenderableTokenSpans(tokens.spans).map((span) => renderTokenSpanHtml(span)).join("");
+}
+function renderTokenSpanHtml(span) {
+  const dark = span.v?.dark;
+  const light = span.v?.light;
+  const single = span.s;
+  const styles = [];
+  if (dark?.fg) {
+    styles.push(`--shiki-dark:${dark.fg}`);
+  }
+  if (light?.fg) {
+    styles.push(`--shiki-light:${light.fg}`);
+  }
+  if (!light?.fg && !dark?.fg && single?.fg) {
+    styles.push(`color:${single.fg}`);
+  }
+  const fontStyle = light?.fs ?? dark?.fs ?? single?.fs;
+  if (typeof fontStyle === "number" && fontStyle > 0) {
+    if (fontStyle & TOKEN_FONT_STYLE_ITALIC) {
+      styles.push("font-style: italic");
+    }
+    if (fontStyle & TOKEN_FONT_STYLE_BOLD) {
+      styles.push("font-weight: bold");
+    }
+    const decorations = [];
+    if (fontStyle & TOKEN_FONT_STYLE_UNDERLINE) {
+      decorations.push("underline");
+    }
+    if (fontStyle & TOKEN_FONT_STYLE_STRIKETHROUGH) {
+      decorations.push("line-through");
+    }
+    if (decorations.length > 0) {
+      styles.push(`text-decoration: ${decorations.join(" ")}`);
+    }
+  }
+  const content = escapeHtml3(span.t ?? "");
+  if (styles.length === 0) {
+    return content;
+  }
+  return `<span style="${styles.join(";")}">${content}</span>`;
+}
+function mergeRenderableTokenSpans(spans) {
+  if (spans.length <= 1) {
+    return spans.slice();
+  }
+  const merged = [];
+  let pendingWhitespace = "";
+  for (const span of spans) {
+    const text = typeof span.t === "string" ? span.t : "";
+    if (/^[\t ]+$/.test(text)) {
+      pendingWhitespace += text;
+      continue;
+    }
+    const nextSpan = pendingWhitespace ? { ...span, t: `${pendingWhitespace}${text}` } : span;
+    pendingWhitespace = "";
+    const previous = merged[merged.length - 1];
+    if (previous && sameTokenSpanStyle(previous, nextSpan)) {
+      previous.t += nextSpan.t;
+    } else {
+      merged.push({ ...nextSpan });
+    }
+  }
+  if (pendingWhitespace) {
+    const previous = merged[merged.length - 1];
+    if (previous) {
+      previous.t += pendingWhitespace;
+    } else {
+      merged.push({ t: pendingWhitespace });
+    }
+  }
+  return merged;
+}
+function sameTokenSpanStyle(a, b) {
+  const variantKeys = /* @__PURE__ */ new Set([
+    ...Object.keys(a.v ?? {}),
+    ...Object.keys(b.v ?? {})
+  ]);
+  for (const key of variantKeys) {
+    const aStyle = a.v?.[key];
+    const bStyle = b.v?.[key];
+    if ((aStyle?.fg ?? null) !== (bStyle?.fg ?? null)) return false;
+    if ((aStyle?.bg ?? null) !== (bStyle?.bg ?? null)) return false;
+    if ((aStyle?.fs ?? null) !== (bStyle?.fs ?? null)) return false;
+  }
+  if ((a.s?.fg ?? null) !== (b.s?.fg ?? null)) return false;
+  if ((a.s?.bg ?? null) !== (b.s?.bg ?? null)) return false;
+  if ((a.s?.fs ?? null) !== (b.s?.fs ?? null)) return false;
+  return true;
+}
+function resolveCodeSourceText(raw, metaCode) {
+  if (metaCode !== null) {
+    return metaCode.replace(/\r\n?/g, "\n");
+  }
+  if (!raw) return "";
+  const normalized = raw.replace(/\r\n?/g, "\n");
+  const fenced = stripCodeFence(normalized);
+  return fenced.hadFence ? fenced.code : normalized;
 }
 function attrsToString(attrs) {
   if (!attrs) return "";
   return Object.entries(attrs).map(([key, value]) => ` ${key}="${escapeAttribute(value)}"`).join("");
 }
+function buildCodeFallbackLines(raw) {
+  const normalized = normalizeCodeFallbackRaw(raw);
+  if (normalized.length === 0) {
+    if (/^\s*```[^\n]*\n?\s*$/.test(raw)) {
+      return [{ id: "temp-0", index: 0, text: "", html: null }];
+    }
+    return [];
+  }
+  return normalized.split("\n").map((line, index) => ({
+    id: `temp-${index}`,
+    index,
+    text: line,
+    html: null
+  }));
+}
+function normalizeCodeFallbackRaw(raw) {
+  if (!raw) return "";
+  const normalized = raw.replace(/\r\n?/g, "\n");
+  const fenced = stripCodeFence(normalized);
+  if (!fenced.hadFence) {
+    return normalized.replace(/\n+$/, "");
+  }
+  let code = fenced.code;
+  code = code.replace(/\n+$/, "");
+  return code;
+}
 function escapeHtml3(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
@@ -4775,7 +5427,9 @@ var MarkdownRenderer = class {
         lowPriorityFrameBudgetMs: this.config.performance?.lowPriorityFrameBudgetMs,
         urgentQueueThreshold: this.config.performance?.urgentQueueThreshold,
         batch: this.config.performance?.batch,
-        historyLimit: this.config.performance?.historyLimit
+        historyLimit: this.config.performance?.historyLimit,
+        startupMicrotaskFlushes: this.config.performance?.startupMicrotaskFlushes,
+        adaptiveBudgeting: this.config.performance?.adaptiveBudgeting
       }
     });
   }
@@ -4969,18 +5623,8 @@ var MarkdownRenderer = class {
           const receivedAt = typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
           const batches = splitPatchBatch(message.patches);
           batches.forEach((batch, index) => {
-            const hasStructural = batch.some((patch) => {
-              switch (patch.op) {
-                case "insertChild":
-                case "replaceChild":
-                case "deleteChild":
-                case "reorder":
-                  return true;
-                default:
-                  return false;
-              }
-            });
-            const priority = hasStructural ? "high" : batch.some(isHeavyPatch) ? "low" : "high";
+            const hasSemantic = batch.some((patch) => getPatchKind(patch) === "semantic");
+            const priority = hasSemantic ? "high" : batch.some(isHeavyPatch) ? "low" : "high";
             this.patchScheduler.enqueue({
               patches: batch,
               meta: {