Keep transcript headings from re-highlighting while the paragraph below them streams

The default markdown block mode merges a heading into the same raw chunk as
the prose that follows it, so every keystroke of that prose re-highlights
the heading's already-settled markers and styling too. Switching the
transcript's MarkdownRenderable to "top-level" block mode gives a heading
its own block, so once it falls behind the streaming tail it is never
recomputed again. Pin the table style to "grid" alongside it, since that is
the other default the block mode switch would otherwise change.

Author: TheGreatAxios

src/tui-opentui/markdown-rows.test.ts

@@ -4,8 +4,9 @@
  */
 
 import { describe, expect, test } from "bun:test"
+import { MarkdownRenderable, BoxRenderable } from "@opentui/core"
 import { withTestRenderer, type Harness } from "./harness"
-import { appendStreamRow, createAppShell, replaceStreamRowAt } from "./shell"
+import { appendStreamRow, createAppShell, createStreamRowRenderable, replaceStreamRowAt } from "./shell"
 import { isMarkdownRow } from "./stream"
 
 const WIDE = { width: 80, height: 24 } as const
@@ -15,11 +16,17 @@ const shellOpts = {
   wireKeys: false,
 } as const
 
-/** Markdown blocks highlight asynchronously; settle before capturing a frame. */
+/**
+ * Markdown blocks highlight asynchronously; settle before capturing a frame.
+ * A row with several top-level blocks (heading, list, fence, link) resolves
+ * its highlight promises one render at a time, so a fixed couple of ticks
+ * that was enough for one block is not enough for several.
+ */
 async function settle(h: Harness): Promise<string> {
-  await new Promise((resolve) => setTimeout(resolve, 250))
-  await h.renderOnce()
-  await h.renderOnce()
+  for (let i = 0; i < 8; i += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 50))
+    await h.renderOnce()
+  }
   return h.captureCharFrame()
 }
 
@@ -144,4 +151,28 @@ describe("markdown transcript rows", () => {
       expect(next).not.toContain("#### Title")
     }, WIDE)
   })
+
+  test("a heading renders as its own top-level block, not merged with the prose after it", async () => {
+    // The default ("coalesced") block mode folds a heading into the same raw
+    // chunk as the paragraph that follows it, so every keystroke of that
+    // paragraph re-highlights the heading's already-settled text too — the
+    // heading's markers and styling visibly flicker while the rest of the
+    // message keeps streaming in. "top-level" mode keeps the heading its own
+    // block so, once it is behind the streaming tail, it is never
+    // recomputed again.
+    await withTestRenderer(async (h) => {
+      const shell = createAppShell(h.renderer, shellOpts)
+      const node = createStreamRowRenderable(shell, {
+        role: "assistant",
+        streaming: true,
+        text: ["### Title", "", "Some body text."].join("\n"),
+      })
+      expect(node).toBeInstanceOf(BoxRenderable)
+      const [, bodyNode] = (node as BoxRenderable).getChildren()
+      expect(bodyNode).toBeInstanceOf(MarkdownRenderable)
+      expect((bodyNode as MarkdownRenderable).internalBlockMode).toBe(
+        "top-level",
+      )
+    }, WIDE)
+  })
 })

src/tui-opentui/shell.ts

@@ -2231,6 +2231,9 @@ function markdownBodyColumns(gutter: PaintedStreamLine, layout: RowLayout): numb
 const TRANSCRIPT_TABLE_OPTIONS = {
   wrapMode: "word",
   columnFitter: "proportional",
+  // "columns" is the top-level-mode default; pin "grid" so switching
+  // internalBlockMode below does not also change how tables are framed.
+  style: "grid",
 } as const
 
 /**
@@ -2323,6 +2326,15 @@ function buildRowNode(
       width: markdownBodyColumns(gutter, layout),
       flexShrink: 0,
       tableOptions: TRANSCRIPT_TABLE_OPTIONS,
+      // Native incremental block stability only tracks stable blocks in
+      // "top-level" mode; the default coalesces a heading into the same raw
+      // chunk as the prose that follows it, so appending to that prose
+      // re-highlights the heading's already-settled text too — visible as
+      // the heading's markers and styling flickering while the paragraph
+      // beneath it keeps streaming in. "top-level" keeps the heading its own
+      // block, so once it is behind the trailing streaming block it never
+      // needs to be recomputed again.
+      internalBlockMode: "top-level",
       // Native incremental block stability: only the trailing block is unstable.
       streaming: row.streaming === true,
     }),