Split a streaming heading into its own settled renderer instead of switching block modes

The previous fix set internalBlockMode to "top-level" on the transcript's
MarkdownRenderable, which does give a heading real stability, but it also
routes lists through the top-level layout path: a 10+ item ordered list gets
its markers padded for alignment, and a list with no blank line before it
gains one anyway, both changes to how non-heading markdown renders during
live streaming.

Render the row's markdown body as two stacked renderers instead: a "frozen"
one holding everything through the last heading that already has content
behind it, and a "live" one holding the still-streaming tail. Both halves use
the library's default block mode untouched, so paragraphs, lists and tables
inside either one lay out exactly as an unsplit body would — the split only
ever falls at a settled heading boundary, never at a list or paragraph
boundary. The frozen half is marked non-streaming and, once written, is never
handed new content while the tail keeps growing, so it is never asked to
re-highlight.

Adds a mid-stream span-sampling test (no settle wait) that reproduces the
literal shake — the heading's painted text reverting to "### Title" on a
delta — against the unfixed renderer, plus regression tests pinning list
spacing and ordered-list marker width across the change.

Author: TheGreatAxios

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

@@ -4,7 +4,7 @@
  */
 
 import { describe, expect, test } from "bun:test"
-import { MarkdownRenderable, BoxRenderable } from "@opentui/core"
+import { MarkdownRenderable, BoxRenderable, type CapturedSpan } from "@opentui/core"
 import { withTestRenderer, type Harness } from "./harness"
 import { appendStreamRow, createAppShell, createStreamRowRenderable, replaceStreamRowAt } from "./shell"
 import { isMarkdownRow } from "./stream"
@@ -152,14 +152,14 @@ describe("markdown transcript rows", () => {
     }, 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
+  test("a closed heading renders in its own settled renderer, separate from the prose after it", async () => {
+    // The library's default block mode merges 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.
+    // message keeps streaming in. Splitting the body at the heading gives it
+    // its own renderer, marked non-streaming, that the live (still-growing)
+    // half never shares — so it is never asked to re-highlight again.
     await withTestRenderer(async (h) => {
       const shell = createAppShell(h.renderer, shellOpts)
       const node = createStreamRowRenderable(shell, {
@@ -169,10 +169,120 @@ describe("markdown transcript rows", () => {
       })
       expect(node).toBeInstanceOf(BoxRenderable)
       const [, bodyNode] = (node as BoxRenderable).getChildren()
-      expect(bodyNode).toBeInstanceOf(MarkdownRenderable)
-      expect((bodyNode as MarkdownRenderable).internalBlockMode).toBe(
-        "top-level",
-      )
+      expect(bodyNode).toBeInstanceOf(BoxRenderable)
+      const [frozenNode, liveNode] = (bodyNode as BoxRenderable).getChildren()
+      expect(frozenNode).toBeInstanceOf(MarkdownRenderable)
+      expect(liveNode).toBeInstanceOf(MarkdownRenderable)
+      expect((frozenNode as MarkdownRenderable).content).toContain("### Title")
+      expect((frozenNode as MarkdownRenderable).streaming).toBe(false)
+      expect((liveNode as MarkdownRenderable).content).toBe("Some body text.")
+      expect((liveNode as MarkdownRenderable).streaming).toBe(true)
+    }, WIDE)
+  })
+
+  test("the settled heading renderer is never rewritten while the prose after it keeps streaming", async () => {
+    await withTestRenderer(async (h) => {
+      const shell = createAppShell(h.renderer, shellOpts)
+      appendStreamRow(shell, {
+        role: "assistant",
+        streaming: true,
+        text: ["### Title", "", "Some"].join("\n"),
+      })
+      const children = shell.transcript.getChildren().slice(1)
+      const [, bodyNode] = (children[0] as BoxRenderable).getChildren()
+      const [frozenNode] = (bodyNode as BoxRenderable).getChildren()
+      const before = (frozenNode as MarkdownRenderable).content
+
+      replaceStreamRowAt(shell, shell.streamLog.length - 1, {
+        role: "assistant",
+        streaming: true,
+        text: ["### Title", "", "Some body text that keeps growing and growing."].join("\n"),
+      })
+      const childrenAfter = shell.transcript.getChildren().slice(1)
+      const [, bodyNodeAfter] = (childrenAfter[0] as BoxRenderable).getChildren()
+      const [frozenNodeAfter] = (bodyNodeAfter as BoxRenderable).getChildren()
+
+      expect(frozenNodeAfter).toBe(frozenNode)
+      expect((frozenNodeAfter as MarkdownRenderable).content).toBe(before)
+    }, WIDE)
+  })
+
+  test("a list directly under a paragraph, with no blank line, keeps that shape after the split", async () => {
+    // Regression guard: the split must never fall at a list boundary — only
+    // at a settled heading — so paragraph/list spacing stays byte-identical
+    // to the unsplit renderer's own default layout.
+    await withTestRenderer(async (h) => {
+      const shell = createAppShell(h.renderer, shellOpts)
+      appendStreamRow(shell, {
+        role: "assistant",
+        text: ["### Title", "", "Here is the list:", "- alpha", "- beta"].join("\n"),
+      })
+      const frame = await settle(h)
+      const lines = frame.split("\n").map((line) => line.trimEnd())
+      const listLine = lines.findIndex((line) => line.includes("Here is the list:"))
+      expect(listLine).toBeGreaterThan(-1)
+      // No blank row inserted between the paragraph and the list beneath it.
+      expect(lines[listLine + 1]).toContain("alpha")
+    }, WIDE)
+  })
+
+  test("a ten-item ordered list under a heading keeps unpadded markers", async () => {
+    await withTestRenderer(async (h) => {
+      const shell = createAppShell(h.renderer, shellOpts)
+      const items = Array.from({ length: 10 }, (_, i) => `${i + 1}. item ${i + 1}`)
+      appendStreamRow(shell, {
+        role: "assistant",
+        text: ["### Steps", "", ...items].join("\n"),
+      })
+      const frame = await settle(h)
+      expect(frame).toContain("1. item 1")
+      expect(frame).toContain("10. item 10")
+    }, WIDE)
+  })
+
+  /** The heading's own painted span, wherever it lands in the current frame. */
+  function headingSpan(h: Harness): CapturedSpan | null {
+    for (const line of h.captureSpans().lines) {
+      for (const span of line.spans) {
+        if (span.text.includes("Title")) return span
+      }
+    }
+    return null
+  }
+
+  test("a settled heading's painted span never changes while the prose after it keeps streaming", async () => {
+    // The shake this fixes is a transient re-highlight, not a settled-frame
+    // difference — a snapshot taken only after several idle ticks (as every
+    // other test in this file does) cannot see it, because the async
+    // highlight pass has always finished by then. This test instead samples
+    // the heading's span on every delta, immediately after a single render
+    // with no settle wait, which is the one place the flicker would show up.
+    await withTestRenderer(async (h) => {
+      const shell = createAppShell(h.renderer, shellOpts)
+      const full = "Some body text that keeps growing and growing more and more and even more."
+      appendStreamRow(shell, {
+        role: "assistant",
+        streaming: true,
+        text: ["### Title", "", full.slice(0, 1)].join("\n"),
+      })
+      // Warm up once: the first highlight pass in a process loads the
+      // tree-sitter grammar and is not itself part of what this test samples.
+      const baseline = await settle(h).then(() => headingSpan(h))
+      expect(baseline).not.toBeNull()
+
+      for (let i = 2; i <= full.length; i += 1) {
+        replaceStreamRowAt(shell, shell.streamLog.length - 1, {
+          role: "assistant",
+          streaming: true,
+          text: ["### Title", "", full.slice(0, i)].join("\n"),
+        })
+        await h.renderOnce()
+        const span = headingSpan(h)
+        expect(span).not.toBeNull()
+        expect(span!.text).toBe(baseline!.text)
+        expect(span!.fg).toEqual(baseline!.fg)
+        expect(span!.attributes).toBe(baseline!.attributes)
+      }
     }, WIDE)
   })
 })

src/tui-opentui/shell.ts

@@ -2091,18 +2091,26 @@ function retextStreamRowBody(
 
   if (!(node instanceof BoxRenderable) || !isMarkdownRow(row)) return false
   const [gutterNode, bodyNode] = node.getChildren()
-  if (
-    !(gutterNode instanceof TextRenderable) ||
-    !(bodyNode instanceof MarkdownRenderable)
-  ) {
+  if (!(gutterNode instanceof TextRenderable) || !(bodyNode instanceof BoxRenderable)) {
+    return false
+  }
+  const [frozenNode, liveNode] = bodyNode.getChildren()
+  if (!(frozenNode instanceof MarkdownRenderable) || !(liveNode instanceof MarkdownRenderable)) {
     return false
   }
   const gutter = streamRowGutter(row, layout)
   gutterNode.content = gutter.content
   gutterNode.width = stringWidth(gutter.content)
-  bodyNode.width = markdownBodyColumns(gutter, layout)
-  bodyNode.content = markdownContent(row)
-  bodyNode.streaming = row.streaming === true
+  const width = markdownBodyColumns(gutter, layout)
+  bodyNode.width = width
+  const content = markdownContent(row)
+  const split = splitAtSettledHeading(content)
+  frozenNode.width = width
+  frozenNode.content = split?.frozen ?? ""
+  liveNode.width = width
+  liveNode.content = split?.live ?? content
+  liveNode.streaming = row.streaming === true
+  liveNode.marginTop = split?.gapRows ?? 0
   return true
 }
 
@@ -2231,9 +2239,6 @@ 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
 
 /**
@@ -2250,6 +2255,50 @@ function markdownContent(row: StreamRow): string {
   return row.text.replace(/(^|\n)#{1,6}[ \t]*$/, "$1")
 }
 
+/** An ATX heading line (`#` through `######`) with a title, not a bare marker. */
+const HEADING_LINE_RE = /^#{1,6}[ \t]+\S.*$/
+
+/**
+ * A markdown body split at the last heading that already has content behind
+ * it: everything through that heading, and everything after it.
+ *
+ * The renderer's own incremental parser only reuses a block whose raw text is
+ * unchanged; the default block mode merges a heading into the same raw chunk
+ * as the paragraph that follows it, so every keystroke of that paragraph
+ * changes the merged chunk's raw text and forces the heading's already-settled
+ * markup to re-highlight too — visibly flickering while the rest of the
+ * message keeps streaming in. Rendering the two halves as separate
+ * `MarkdownRenderable`s keeps the heading's renderer untouched once it is no
+ * longer the one growing, without changing how paragraphs, lists or tables
+ * inside either half are laid out (both halves still use the library's
+ * default block mode).
+ */
+export type MarkdownSplit = {
+  readonly frozen: string
+  readonly live: string
+  /** Blank source lines between the heading and what follows it (0 or 1). */
+  readonly gapRows: number
+}
+
+export function splitAtSettledHeading(text: string): MarkdownSplit | null {
+  const lines = text.split("\n")
+  let boundary = -1
+  for (let i = 0; i < lines.length; i += 1) {
+    if (HEADING_LINE_RE.test(lines[i]!)) boundary = i
+  }
+  // No heading, or the last one is still the open tail: nothing to freeze.
+  if (boundary === -1 || boundary >= lines.length - 1) return null
+  const rest = lines.slice(boundary + 1)
+  const firstContent = rest.findIndex((line) => line.trim().length > 0)
+  // Heading closed but nothing has started under it yet.
+  if (firstContent === -1) return null
+  return {
+    frozen: lines.slice(0, boundary + 1).join("\n"),
+    live: rest.slice(firstContent).join("\n"),
+    gapRows: firstContent > 0 ? 1 : 0,
+  }
+}
+
 /**
  * Build the row-shaped paint node: a MarkdownRenderable body next to a plain
  * gutter for markdown-bearing rows (assistant replies), a TextTableRenderable
@@ -2318,28 +2367,59 @@ function buildRowNode(
   const gutter = streamRowGutter(row, layout)
   const wrapper = new BoxRenderable(ctx, { flexDirection: "row", width: "100%" })
   wrapper.add(gutterNode(ctx, gutter))
-  wrapper.add(
+  wrapper.add(createMarkdownBody(ctx, row, gutter, layout))
+  return wrapper
+}
+
+/** Shared construction options for a transcript markdown body's renderer. */
+function markdownBodyOptions(gutter: PaintedStreamLine, width: number) {
+  return {
+    syntaxStyle: transcriptSyntaxStyle(),
+    fg: gutter.fg,
+    width,
+    flexShrink: 0,
+    tableOptions: TRANSCRIPT_TABLE_OPTIONS,
+  } as const
+}
+
+/**
+ * A markdown row's body: a settled `frozen` renderer stacked above the still
+ * `live` one. `frozen` is empty (and so, zero height) until a heading closes;
+ * from then on it holds everything through the last closed heading and never
+ * streams, so it is never asked to re-highlight once written. `live` carries
+ * the row's own streaming flag. Both halves still use the library's default
+ * block mode, so paragraphs, lists and tables inside either one lay out
+ * exactly as a single unsplit body would. Always building both — the empty
+ * case is just an empty renderer — keeps the shape constant, so
+ * `retextStreamRowBody` can update in place without telling one shape of row
+ * body from another.
+ */
+function createMarkdownBody(
+  ctx: CliRenderer,
+  row: StreamRow,
+  gutter: PaintedStreamLine,
+  layout: RowLayout,
+): BoxRenderable {
+  const width = markdownBodyColumns(gutter, layout)
+  const split = splitAtSettledHeading(markdownContent(row))
+  const column = new BoxRenderable(ctx, { flexDirection: "column", width })
+  column.add(
     new MarkdownRenderable(ctx, {
-      content: markdownContent(row),
-      syntaxStyle: transcriptSyntaxStyle(),
-      fg: gutter.fg,
-      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",
+      ...markdownBodyOptions(gutter, width),
+      content: split?.frozen ?? "",
+      streaming: false,
+    }),
+  )
+  column.add(
+    new MarkdownRenderable(ctx, {
+      ...markdownBodyOptions(gutter, width),
+      content: split?.live ?? markdownContent(row),
       // Native incremental block stability: only the trailing block is unstable.
       streaming: row.streaming === true,
+      marginTop: split?.gapRows ?? 0,
     }),
   )
-  return wrapper
+  return column
 }
 
 /**