[Codex review] fix: hold pending streaming markers and preserve empty lists

.changeset/quiet-streaming-markers.md

@@ -0,0 +1,6 @@
+---
+"remend": patch
+"streamdown": patch
+---
+
+Preserve whitespace after empty list markers and add opt-in `pendingInlineMarkers` handling to hold ambiguous emphasis openers during streaming. Streamdown reveals remaining literal markers when `isAnimating` becomes false.

apps/website/content/docs/termination.mdx

@@ -444,3 +444,16 @@ With `linkMode: 'text-only'`:
 2. `` `const foo = `` → Renders as `const foo =`
 3. `` `const foo = "bar"` `` → Renders as `const foo = "bar"`
 
+
+## Holding pending emphasis markers
+
+To avoid a flash of raw emphasis markers before their text arrives, enable
+`remend={{ pendingInlineMarkers: true }}` and set `isAnimating` to your stream's
+running state. For example, `my name is **` holds the trailing markers until the
+next token arrives. Streamdown reveals any remaining literal markers when
+`isAnimating` becomes `false`, including when a stream is stopped.
+
+This option defaults to `false` because a trailing marker is ambiguous. It only
+holds whitespace-delimited inline emphasis openers; it does not buffer arbitrary
+Markdown, links, code fences, or mathematical expressions. When calling `remend`
+directly, turn the option off for the final render.

packages/remend/__tests__/pending-markers.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import remend from "../src";
+
+describe("pending inline markers", () => {
+  it.each([
+    "*",
+    "**",
+    "_",
+    "__",
+    "~~",
+  ])("holds %s only when opted in", (marker) => {
+    const text = `my name is ${marker}`;
+    expect(remend(text)).toBe(text);
+    expect(remend(text, { pendingInlineMarkers: true })).toBe("my name is");
+    expect(remend(text, { pendingInlineMarkers: false })).toBe(text);
+  });
+
+  it("completes bold when the first content token arrives", () => {
+    expect(remend("my name is **A", { pendingInlineMarkers: true })).toBe(
+      "my name is **A**"
+    );
+    expect(remend("my name is **Ada**", { pendingInlineMarkers: true })).toBe(
+      "my name is **Ada**"
+    );
+  });
+
+  it.each([
+    "**Ada**",
+    "text **\n",
+    "snake_",
+    "2*",
+    "***",
+    "\\**",
+    "`literal **",
+    "```\n**",
+    "~~~\n**",
+    "    **",
+    "$$ x **",
+    "[link](https://example.com/ **",
+  ])("preserves non-pending syntax in %j", (text) => {
+    expect(remend(text, { pendingInlineMarkers: true })).toBe(remend(text));
+  });
+
+  it.each([
+    "- ",
+    "- item\n - ",
+    "+ ",
+    "* ",
+    "1. ",
+    "2) ",
+  ])("retains whitespace that makes %j a list marker", (text) => {
+    expect(remend(text)).toBe(text.includes("\n") ? `${text}\u200B` : text);
+  });
+});

packages/remend/__tests__/setext-heading.test.ts

@@ -59,7 +59,7 @@ describe("setext heading handling", () => {
     // Simulate streaming where list items come in one by one
     const scenarios = [
       { input: "here is a list\n-", expected: "here is a list\n-\u200B" },
-      { input: "here is a list\n- ", expected: "here is a list\n-\u200B" }, // Trailing space removed, then zero-width joiner added
+      { input: "here is a list\n- ", expected: "here is a list\n- \u200B" }, // Keep list whitespace while preventing a setext heading
       {
         input: "here is a list\n- list item 1",
         expected: "here is a list\n- list item 1",
@@ -107,8 +107,8 @@ describe("setext heading handling", () => {
   it("should handle mixed whitespace and dashes", () => {
     const text = "Some text\n- ";
     const result = remend(text);
-    // Trailing single space is removed, then zero-width joiner is added to prevent setext heading interpretation
-    expect(result).toBe("Some text\n-\u200B");
+    // Keep the marker whitespace so the parser produces a list item, not literal text.
+    expect(result).toBe("Some text\n- \u200B");
   });
 
   it("should handle the original issue example precisely", () => {

packages/remend/src/index.ts

@@ -17,6 +17,7 @@ import {
   INCOMPLETE_IMAGE_PLACEHOLDER,
   type LinkMode,
 } from "./link-image-handler";
+import { holdPendingInlineMarkers } from "./pending-inline-markers";
 import { handleIncompleteSetextHeading } from "./setext-heading-handler";
 import { handleSingleTildeEscape } from "./single-tilde-handler";
 import { handleIncompleteStrikethrough } from "./strikethrough-handler";
@@ -82,6 +83,12 @@ export interface RemendOptions {
   linkMode?: "protocol" | "text-only";
   /** Complete links and images (e.g., `[text](url` → `[text](streamdown:incomplete-link)`) */
   links?: boolean;
+  /**
+   * Hold trailing, whitespace-delimited emphasis markers until content arrives.
+   * Opt-in because a trailing marker can also be literal text. Disable after
+   * streaming ends to reveal any remaining literal markers. Defaults to false.
+   */
+  pendingInlineMarkers?: boolean;
   /** Handle incomplete setext headings to prevent misinterpretation */
   setextHeadings?: boolean;
   /** Escape single ~ between word characters to prevent false strikethrough (e.g., `20~25` → `20\~25`) */
@@ -90,6 +97,8 @@ export interface RemendOptions {
   strikethrough?: boolean;
 }
 
+const emptyListMarker = /^[ \t]*(?:[-+*]|\d+[.)])[ \t]+$/;
+
 // Helper to check if an option is enabled (defaults to true)
 const isEnabled = (option: boolean | undefined): boolean => option !== false;
 
@@ -283,8 +292,16 @@ const remend = (text: string, options?: RemendOptions): string => {
   }
 
   // Remove trailing whitespace if it's not a double space
+  const input = options?.pendingInlineMarkers
+    ? holdPendingInlineMarkers(text)
+    : text;
+  const lastLine = input.slice(input.lastIndexOf("\n") + 1);
   let result =
-    text.endsWith(" ") && !text.endsWith("  ") ? text.slice(0, -1) : text;
+    input.endsWith(" ") &&
+    !input.endsWith("  ") &&
+    !emptyListMarker.test(lastLine)
+      ? input.slice(0, -1)
+      : input;
 
   // Get enabled built-in handlers
   const enabledBuiltIns = getEnabledBuiltInHandlers(options);

packages/remend/src/pending-inline-markers.ts

@@ -0,0 +1,32 @@
+import { isInsideCodeBlock } from "./code-block-utils";
+import {
+  isWithinHtmlTag,
+  isWithinLinkOrImageUrl,
+  isWithinMathBlock,
+} from "./utils";
+
+const pendingMarker = /(?:^|\s)(\*{1,2}|_{1,2}|~~)$/;
+
+const indentedCode = /^(?: {4}|\t)/;
+
+export const holdPendingInlineMarkers = (text: string): string => {
+  const match = pendingMarker.exec(text);
+  if (!match || match.index + match[0].length !== text.length) {
+    return text;
+  }
+  const start = text.length - match[1].length;
+  const line = text.slice(text.lastIndexOf("\n", start - 1) + 1);
+  // Tilde fences and indented code are deliberately left alone until the
+  // shared code scanner can distinguish them from prose.
+  if (
+    text.includes("~~~") ||
+    indentedCode.test(line) ||
+    isInsideCodeBlock(text, start) ||
+    isWithinMathBlock(text, start) ||
+    isWithinHtmlTag(text, start) ||
+    isWithinLinkOrImageUrl(text, start)
+  ) {
+    return text;
+  }
+  return text.slice(0, start);
+};

packages/remend/src/setext-heading-handler.ts

@@ -5,6 +5,7 @@
 // Regex patterns defined at top level for performance
 const DASH_ONLY_PATTERN = /^-{1,2}$/;
 const DASH_WITH_SPACE_PATTERN = /^[\s]*-{1,2}[\s]+$/;
+const EMPTY_DASH_LIST_PATTERN = /^[ \t]*-[ \t]+$/;
 const EQUALS_ONLY_PATTERN = /^={1,2}$/;
 const EQUALS_WITH_SPACE_PATTERN = /^[\s]*={1,2}[\s]+$/;
 
@@ -28,6 +29,10 @@ export const handleIncompleteSetextHeading = (text: string): string => {
   const lastLine = text.substring(lastNewlineIndex + 1);
   const previousContent = text.substring(0, lastNewlineIndex);
 
+  if (EMPTY_DASH_LIST_PATTERN.test(lastLine) && previousContent.trim()) {
+    return `${text}\u200B`;
+  }
+
   // Check if last line is only dashes or equals (potential setext heading underline)
   // We need to check for patterns like: "-", "--", "=", "=="
   // But NOT "---" or "===" (which are valid horizontal rules / setext headings)

packages/streamdown/__tests__/pending-markers.test.tsx

@@ -0,0 +1,34 @@
+import { render } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Streamdown } from "../index";
+
+describe("pending inline markers", () => {
+  it("hides pending bold markers while streaming and flushes literal markers on completion", () => {
+    const { container, rerender } = render(
+      <Streamdown isAnimating remend={{ pendingInlineMarkers: true }}>
+        {"my name is **"}
+      </Streamdown>
+    );
+    expect(container.textContent).toBe("my name is");
+    rerender(
+      <Streamdown isAnimating remend={{ pendingInlineMarkers: true }}>
+        {"my name is **Ada"}
+      </Streamdown>
+    );
+    expect(
+      container.querySelector('[data-streamdown="strong"]')?.textContent
+    ).toBe("Ada");
+    rerender(
+      <Streamdown isAnimating={false} remend={{ pendingInlineMarkers: true }}>
+        {"my name is **"}
+      </Streamdown>
+    );
+    expect(container.textContent).toBe("my name is **");
+  });
+
+  it("does not reinterpret an empty nested list marker as literal text", () => {
+    const { container } = render(<Streamdown>{"- item\n - "}</Streamdown>);
+    expect(container.textContent).not.toContain("-");
+    expect(container.querySelectorAll("li")).toHaveLength(2);
+  });
+});

packages/streamdown/index.tsx

@@ -675,7 +675,11 @@ export const Streamdown = memo(
       }
       let result =
         mode === "streaming" && shouldParseIncompleteMarkdown
-          ? remend(children, remendOptions)
+          ? remend(children, {
+              ...remendOptions,
+              pendingInlineMarkers:
+                isAnimating && remendOptions?.pendingInlineMarkers,
+            })
           : children;
 
       // Escape markdown metacharacters inside literal-tag-content tags so that
@@ -699,6 +703,7 @@ export const Streamdown = memo(
       mode,
       shouldParseIncompleteMarkdown,
       remendOptions,
+      isAnimating,
       allowedTagNames,
       literalTagContent,
     ]);