test(app): capture Android terminal keyboard frame drops

Retain a real-device diagnostic for #4811 while its cost owner remains unconfirmed. The caller supplies the comparison budget; this does not add a release performance guarantee or a production fix.

nix/npm-deps.hash

@@ -1 +1 @@
-sha256-1WmrHvE68Lzyil4On7xtsPMQTODXZ3Jb3/juUg3nHi4=
+sha256-O8sNh6oXFIddUljYiC6RbVZF5/7a7A7W9UWrOd0tIV4=

packages/app/e2e/browser/chat-find.spec.ts

@@ -5,6 +5,7 @@ import {
   seedMockAgentWorkspace,
   type MockAgentWorkspace,
 } from "../support/helpers/mock-agent";
+import { waitForTimelineGeometryToSettle } from "../support/helpers/timeline-pagination";
 import { installDaemonWebSocketGate } from "../support/helpers/daemon-websocket-gate";
 import {
   expectReconnectingToastGone,
@@ -19,6 +20,10 @@ import {
 } from "../support/helpers/composer";
 
 import { openCommandCenter, closeCommandCenter } from "../support/helpers/command-center";
+import {
+  expectPromptsDrawnByPlugin,
+  withPromptTimelinePlugin,
+} from "../support/helpers/plugin-timeline";
 
 const MAC_USER_AGENT =
   "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36";
@@ -120,6 +125,49 @@ async function closeFind(page: Page) {
     .toEqual([]);
 }
 
+async function expectChatKeyboardScroll(page: Page, key: "PageUp" | "PageDown") {
+  // The scrolling surface has no accessible name; use its existing test id.
+  const viewport = page.getByTestId("agent-chat-scroll");
+  await waitForTimelineGeometryToSettle(page);
+  const before = await viewport.evaluate((element) => element.scrollTop);
+  await page.keyboard.press(key);
+  const direction = key === "PageUp" ? -1 : 1;
+  await expect
+    .poll(
+      async () => direction * ((await viewport.evaluate((element) => element.scrollTop)) - before),
+    )
+    .toBeGreaterThan(100);
+}
+
+test("keeps keyboard scrolling the chat after closing Find", async ({ page }, testInfo) => {
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "chat-find-scroll-focus-",
+    title: "Chat Find keyboard scrolling",
+    initialPrompt: "Render the response",
+    featureValues: { mockAssistantResponse: TALL_RESPONSE },
+  });
+  try {
+    await agent.client.waitForFinish(agent.agentId, 15_000);
+    await openAgentRoute(page, agent);
+    await expect(page.getByTestId("assistant-message").first()).toBeVisible();
+    await searchChat(page, "Closing paragraph");
+    await expectHighlight(page, "Closing paragraph");
+    await waitForTimelineGeometryToSettle(page);
+    await closeFind(page);
+    await expectChatKeyboardScroll(page, "PageUp");
+    await page.screenshot({ path: testInfo.outputPath("chat-after-find-page-up.png") });
+    await expectChatKeyboardScroll(page, "PageDown");
+    await searchChat(page, "Closing paragraph");
+    await expectHighlight(page, "Closing paragraph");
+    await waitForTimelineGeometryToSettle(page);
+    await page.getByRole("button", { name: "Close Find", exact: true }).click();
+    await expect(query(page)).toHaveCount(0);
+    await expectChatKeyboardScroll(page, "PageUp");
+  } finally {
+    await agent.cleanup();
+  }
+});
+
 test("loads older history through prompt navigation and finds repeated rendered Markdown", async ({
   page,
 }, testInfo) => {
@@ -174,7 +222,7 @@ async function highlightedMessage(page: Page) {
     const range = entry && Array.from(entry[1])[0];
     if (!(range instanceof Range)) return null;
     const message = range.startContainer.parentElement?.closest<HTMLElement>(
-      '[data-testid="user-message"], [data-testid="assistant-message"]',
+      '[data-testid="user-message"], [data-testid="plugin-prompt"], [data-testid="assistant-message"]',
     );
     return message?.dataset.testid ?? null;
   });
@@ -219,6 +267,34 @@ test("counts and steps through every match in the chat, not just the selected me
   }
 });
 
+test("finds text in a prompt a timeline plugin draws", async ({ page }, testInfo) => {
+  testInfo.setTimeout(120_000);
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "chat-find-plugin-prompt-",
+    title: "Chat Find plugin prompt",
+    initialPrompt: ACROSS_PROMPT,
+    featureValues: { mockAssistantResponse: ACROSS_RESPONSE },
+  });
+  try {
+    await agent.client.waitForFinish(agent.agentId, 15_000);
+    await withPromptTimelinePlugin(async () => {
+      await openAgentRoute(page, agent);
+      await expectPromptsDrawnByPlugin(page);
+      await openChatFind(page);
+      await query(page).fill("scope-needle");
+      await expect(status(page)).toHaveText("1 of 3");
+      await expectHighlight(page, "scope-needle");
+      await expectHighlightedMessage(page, "plugin-prompt");
+      await page.screenshot({ path: testInfo.outputPath("chat-find-plugin-prompt.png") });
+      await expectNextMatch(page, "2 of 3", "scope-needle");
+      await expectHighlightedMessage(page, "assistant-message");
+      await closeFind(page);
+    });
+  } finally {
+    await agent.cleanup();
+  }
+});
+
 test("rejects invisible source matches and ignores a late reply after closing", async ({
   page,
 }) => {

packages/app/e2e/mobile/terminal-keyboard/STUTTER.md

@@ -0,0 +1,16 @@
+# Android terminal keyboard diagnostic
+
+This is a device diagnostic for #4811, not a CI test or an established release performance budget. It measures the real native terminal and real software keyboard through agent-device. It does not inject keyboard frames or replace the terminal.
+
+Open a terminal against an isolated daemon, hide its keyboard, and leave Android animations enabled. Use an existing agent-device session bound to the app and device being measured. For example, from the repository root:
+
+```sh
+PASEO_AGENT_DEVICE_SESSION=terminal-keyboard-stutter \
+  node packages/app/e2e/mobile/terminal-keyboard/stutter.android.mjs 20
+```
+
+Pass a maximum median janky-frame percentage explicitly. The example's 20% is a diagnostic comparison threshold, not an agreed product requirement. The script warms one complete cycle, measures five opening/closing cycles, saves raw Android frame metrics to `.dev/agent-device-artifacts/terminal-keyboard-stutter/frames.json`, then fails if either median exceeds the supplied threshold. `AGENT_DEVICE_STATE_DIR` and `ANDROID_SERIAL` are honored.
+
+Each opening uses the terminal keyboard toggle, and each closing uses Android Back. Accessibility is read only before opening, because real-IME accessibility snapshots stalled during investigation. The script verifies that the real keyboard changes visibility, waits for three stable samples, and includes another 500 ms for delayed terminal refits. It leaves the keyboard hidden and keeps the caller's session open.
+
+Compare the same app build mode, terminal contents, device, animation settings, and threshold. Development-build and emulator numbers do not establish release or physical-device performance. A failure reproduces frame drops; it does not identify their cause or prove a proposed fix.

packages/app/e2e/mobile/terminal-keyboard/stutter.android.mjs

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+// Start an agent-device Android session on an idle terminal with its keyboard hidden.
+// The explicit budget is a diagnostic comparison parameter, not a shipped performance guarantee.
+const maxJankPercent = Number(process.argv[2]);
+assert(
+  process.argv[2] &&
+    Number.isFinite(maxJankPercent) &&
+    maxJankPercent >= 0 &&
+    maxJankPercent <= 100,
+  "Pass the maximum median janky-frame percentage, for example: node stutter.android.mjs 20",
+);
+const session = process.env.PASEO_AGENT_DEVICE_SESSION ?? "terminal-keyboard-stutter";
+const serial = process.env.ANDROID_SERIAL ?? "emulator-5554";
+const artifacts = resolve(".dev/agent-device-artifacts/terminal-keyboard-stutter");
+mkdirSync(artifacts, { recursive: true });
+
+function ad(...args) {
+  return execFileSync("agent-device", [...args, "--session", session], {
+    encoding: "utf8",
+    timeout: 20_000,
+  });
+}
+
+function keyboardShown() {
+  return /^  mInputShown=true$/m.test(
+    execFileSync("adb", ["-s", serial, "shell", "dumpsys", "input_method"], {
+      encoding: "utf8",
+      timeout: 10_000,
+    }),
+  );
+}
+
+async function waitForKeyboard(shown) {
+  const deadline = Date.now() + 5000;
+  let stableSamples = 0;
+  while (Date.now() < deadline) {
+    stableSamples = keyboardShown() === shown ? stableSamples + 1 : 0;
+    if (stableSamples === 3) {
+      // Include the pane's delayed refits after the keyboard animation ends.
+      await delay(500);
+      return;
+    }
+    await delay(100);
+  }
+  throw new Error(`Keyboard did not settle at shown=${shown}`);
+}
+
+function frames() {
+  const result = JSON.parse(ad("perf", "frames", "--json"));
+  const sample = result.data.metrics.fps;
+  assert(sample.available, "Android frame metrics must be available");
+  return sample;
+}
+
+function keyboardTogglePoint() {
+  const { data } = JSON.parse(ad("snapshot", "-i", "--json"));
+  const toggle = data.nodes.find((node) => node.identifier === "terminal-keyboard-toggle");
+  const input = data.nodes.find((node) => node.identifier === "terminal-native-input");
+  assert(input && toggle?.rect, "Open a native terminal before running this diagnostic");
+  return {
+    x: String(Math.round(toggle.rect.x + toggle.rect.width / 2)),
+    y: String(Math.round(toggle.rect.y + toggle.rect.height / 2)),
+  };
+}
+
+async function keyboardCycle(point) {
+  ad("press", point.x, point.y);
+  await waitForKeyboard(true);
+  const open = frames();
+  ad("back");
+  await waitForKeyboard(false);
+  const close = frames();
+  return { open, close };
+}
+
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)];
+}
+
+async function captureKeyboardCycles() {
+  assert.equal(keyboardShown(), false, "Start with the software keyboard hidden");
+  const point = keyboardTogglePoint();
+  frames();
+  await keyboardCycle(point); // Warm the keyboard and terminal before measuring.
+  const samples = [];
+  for (let cycle = 0; cycle < 5; cycle += 1) {
+    samples.push(await keyboardCycle(point));
+  }
+  return samples;
+}
+
+const samples = await captureKeyboardCycles();
+const open = median(samples.map((sample) => sample.open.droppedFramePercent));
+const close = median(samples.map((sample) => sample.close.droppedFramePercent));
+const result = { maxJankPercent, medianJankPercent: { open, close }, samples };
+writeFileSync(resolve(artifacts, "frames.json"), JSON.stringify(result, null, 2));
+console.log(JSON.stringify({ maxJankPercent, medianJankPercent: { open, close } }));
+assert(open <= maxJankPercent, `Keyboard opening: ${open}% exceeds ${maxJankPercent}%`);
+assert(close <= maxJankPercent, `Keyboard closing: ${close}% exceeds ${maxJankPercent}%`);

packages/app/src/agent-stream/chat-find/index.web.tsx

@@ -118,8 +118,8 @@ export function ChatFind({
   }, [active, isInteractive, model]);
   const close = useCallback(() => {
     model.close();
-    root.current?.focus({ preventScroll: true });
-  }, [model]);
+    viewportRef.current?.focus?.();
+  }, [model, viewportRef]);
   let status = "";
   if (state.phase === "searching") status = t("paneFind.searching");
   else if (state.phase === "loading") status = t("paneFind.loading");

packages/app/src/agent-stream/chat-find/ranges.browser.test.ts

@@ -76,3 +76,49 @@ it("keeps semantic Markdown paragraphs separate while finding inline matches", (
   ]);
   expect(findRenderedMatches(row, ".another")).toEqual([]);
 });
+
+function pluginRow(html: string) {
+  const row = document.createElement("div");
+  row.dataset.pluginRow = "true";
+  row.dataset.messageId = "message-1";
+  row.innerHTML = html;
+  document.body.append(row);
+  return row;
+}
+
+it("searches a plugin row that sets no text marker, bounding matches by view", () => {
+  const row = pluginRow(
+    "<div><div>Prompt</div><div>find <span>this</span> needle</div><div>needle</div><button>needle</button></div>",
+  );
+  expect(findRenderedMatches(row, "needle").map((range) => range.toString())).toEqual([
+    "needle",
+    "needle",
+  ]);
+  expect(findRenderedMatches(row, "Promptfind")).toEqual([]);
+  expect(findRenderedMatches(row, "find this needle")).toHaveLength(1);
+  expect(findMessageMatches(row.parentElement, "message-1", "needle")).toHaveLength(2);
+});
+
+it("leaves rows without the plugin marker limited to marked message text", () => {
+  const row = document.createElement("div");
+  row.innerHTML = "<div>needle</div>";
+  document.body.append(row);
+  expect(findRenderedMatches(row, "needle")).toEqual([]);
+});
+
+it("counts only drawn text in a plugin row, including an opened popover", () => {
+  const row = pluginRow(
+    '<div><span>visible needle</span><div hidden>hidden needle</div><div style="display:none">display needle</div><span style="visibility:hidden">visibility needle</span><span style="opacity:0">transparent needle</span><div popover="manual">popover needle</div></div>',
+  );
+  expect(findRenderedMatches(row, "needle").map((range) => range.toString())).toEqual(["needle"]);
+  row.querySelector<HTMLElement>("[popover]")!.showPopover();
+  expect(findRenderedMatches(row, "needle")).toHaveLength(2);
+});
+
+it("keeps text around nested plugin blocks in separate occurrences", () => {
+  const row = pluginRow("<div>alpha <div>details</div>beta</div><div>gamma <div></div>delta</div>");
+  expect(findRenderedMatches(row, "alpha beta")).toEqual([]);
+  expect(findRenderedMatches(row, "gamma delta")).toEqual([]);
+  expect(findRenderedMatches(row, "details").map((range) => range.toString())).toEqual(["details"]);
+  expect(findRenderedMatches(row, "beta").map((range) => range.toString())).toEqual(["beta"]);
+});

packages/app/src/agent-stream/chat-find/ranges.web.ts

@@ -21,28 +21,55 @@ export function findMessageMatches(
   return findMessageRows(root, messageId).flatMap((row) => findRenderedMatches(row, query));
 }
 
+function renderedTextGroups(row: HTMLElement): Text[][] {
+  const groups: Text[][] = [];
+  // A plugin renderer owns the DOM of the message it replaced and sets no markers, so the
+  // whole row is searched and each div (a React Native View or Text) bounds a match.
+  const pluginRow = row.dataset.pluginRow === "true";
+  const blocks = pluginRow ? `${BLOCKS},div` : BLOCKS;
+  const contents = pluginRow
+    ? [row]
+    : row.querySelectorAll<HTMLElement>('[data-message-text="true"]');
+  for (const content of contents) {
+    let group: { block: Element; texts: Text[] } | undefined;
+    const walker = document.createTreeWalker(
+      content,
+      NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT,
+    );
+    let node: Node | null;
+    while ((node = walker.nextNode())) {
+      if (node instanceof Element) {
+        // Even an empty nested block separates the text before and after it.
+        if (node.matches(blocks)) group = undefined;
+        continue;
+      }
+      if (!(node instanceof Text) || node.parentElement?.closest(IGNORED)) continue;
+      if (
+        pluginRow &&
+        !node.parentElement?.checkVisibility({ opacityProperty: true, visibilityProperty: true })
+      )
+        continue;
+      const block = node.parentElement?.closest(blocks) ?? content;
+      if (group?.block !== block) {
+        group = { block, texts: [] };
+        groups.push(group.texts);
+      }
+      group.texts.push(node);
+    }
+  }
+  return groups;
+}
+
 /** Local offsets belong to the DOM that supplied the text, never to a host parser. */
 export function findRenderedMatches(row: HTMLElement, query: string): Range[] {
   if (!query.trim()) return [];
-  const groups = new Map<Element, Text[]>();
-  for (const content of row.querySelectorAll<HTMLElement>('[data-message-text="true"]')) {
-    const walker = document.createTreeWalker(content, NodeFilter.SHOW_TEXT);
-    let node: Node | null;
-    while ((node = walker.nextNode())) {
-      if (!(node instanceof Text) || node.parentElement?.closest(IGNORED)) continue;
-      const block = node.parentElement?.closest(BLOCKS) ?? content;
-      const texts = groups.get(block) ?? [];
-      texts.push(node);
-      groups.set(block, texts);
-    }
-  }
   const pattern = query
     .trim()
     .split(/\s+/)
     .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
     .join("\\s+");
   const ranges: Range[] = [];
-  for (const texts of groups.values()) {
+  for (const texts of renderedTextGroups(row)) {
     const points = texts.map((node) => ({ node, start: 0, end: 0 }));
     let text = "";
     for (const point of points) {

packages/app/src/agent-stream/strategy-web.tsx

@@ -1162,6 +1162,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
 
   useEffect(() => {
     const handle: StreamViewportHandle = {
+      focus: () => scrollContainerRef.current?.focus({ preventScroll: true }),
       scrollToBottom: () => {
         setFollowOutput(true);
         cancelPendingStickToBottom();
@@ -1250,6 +1251,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
         key={item.id}
         data-history-row-id={item.id}
         data-message-id={getStreamItemMessageId(item)}
+        data-plugin-row={item.kind === "plugin" ? "true" : undefined}
         style={streamRowStyle}
       >
         <StreamRowContent
@@ -1267,6 +1269,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
         key={item.id}
         data-history-row-id={item.id}
         data-message-id={getStreamItemMessageId(item)}
+        data-plugin-row={item.kind === "plugin" ? "true" : undefined}
         style={streamRowStyle}
       >
         <StreamRowContent
@@ -1329,6 +1332,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
                     data-index={virtualRow.index}
                     data-history-row-id={item.id}
                     data-message-id={getStreamItemMessageId(item)}
+                    data-plugin-row={item.kind === "plugin" ? "true" : undefined}
                     ref={measureVirtualizedRowElement}
                     style={renderVirtualRowStyle(virtualRow.start)}
                   >

packages/app/src/agent-stream/strategy.ts

@@ -51,6 +51,8 @@ export interface ScrollToMessageOccurrence {
 }
 
 export interface StreamViewportHandle {
+  /** Give keyboard navigation back to the scrolling surface on web. */
+  focus?: () => void;
   scrollToBottom: (reason?: BottomAnchorLocalRequest["reason"]) => void;
   prepareForViewportChange: () => void;
   scrollToMessage?: (messageId: string, occurrence?: ScrollToMessageOccurrence) => void;

packages/app/src/terminal/native-renderer/terminal-selection.test.ts

@@ -41,6 +41,93 @@ function rowWithText(
 }
 
 describe("native terminal selection", () => {
+  it.each([
+    { startCol: 1, endCol: 8, expected: "한글 문장" },
+    { startCol: 3, endCol: 8, expected: "글 문장" },
+    { startCol: 1, endCol: 1, expected: "한" },
+    { startCol: 0, endCol: 0, expected: "한" },
+    { startCol: 0, endCol: 1, expected: "한" },
+    { startCol: 4, endCol: 6, expected: " 문" },
+  ])(
+    "copies complete wide characters for selected columns $startCol through $endCol",
+    async ({ startCol, endCol, expected }) => {
+      const terminal = createNativeHeadlessTerminal({ rows: 3, cols: 30 });
+      const copied: string[] = [];
+      try {
+        await terminal.write("한글 문장");
+        const bounds = terminal.getBufferBounds();
+        const selection = createTerminalSelectionModel();
+        selection.begin({
+          coordinate: { row: bounds.cursorRow, col: endCol },
+          bounds,
+        });
+        selection.update({
+          coordinate: { row: bounds.cursorRow, col: startCol },
+          bounds,
+        });
+
+        await copyTerminalSelection({
+          terminal,
+          selection: selection.getSnapshot().range,
+          clipboard: {
+            writeText: async (text) => {
+              copied.push(text);
+            },
+          },
+        });
+
+        expect(copied).toEqual([expected]);
+      } finally {
+        terminal.dispose();
+      }
+    },
+  );
+
+  it("copies Korean output without adding spaces for continuation cells", async () => {
+    const terminal = createNativeHeadlessTerminal({ rows: 3, cols: 30 });
+    const copied: string[] = [];
+    try {
+      await terminal.write("한글 문장");
+      const bounds = terminal.getBufferBounds();
+      await copyTerminalSelection({
+        terminal,
+        selection: {
+          start: { row: bounds.cursorRow, col: 0 },
+          end: { row: bounds.cursorRow, col: bounds.cursorCol - 1 },
+          coordinateEpoch: bounds.coordinateEpoch,
+        },
+        clipboard: {
+          writeText: async (text) => {
+            copied.push(text);
+          },
+        },
+      });
+      expect(copied).toEqual(["한글 문장"]);
+    } finally {
+      terminal.dispose();
+    }
+  });
+
+  it("copies Korean text and real spaces without wide-character continuation spaces", async () => {
+    const terminal = createNativeHeadlessTerminal({ rows: 3, cols: 30 });
+    try {
+      await terminal.write("한글 문장 | 성공");
+      const bounds = terminal.getBufferBounds();
+      expect(
+        extractTerminalSelectedText({
+          terminal,
+          selection: {
+            start: { row: bounds.cursorRow, col: 0 },
+            end: { row: bounds.cursorRow, col: bounds.cursorCol - 1 },
+            coordinateEpoch: bounds.coordinateEpoch,
+          },
+        }),
+      ).toBe("한글 문장 | 성공");
+    } finally {
+      terminal.dispose();
+    }
+  });
+
   it("expands a long-press coordinate to the whole terminal word", async () => {
     const terminal = createNativeHeadlessTerminal({ rows: 4, cols: 32, scrollbackLines: 20 });
     await terminal.write("before PASEO_TARGET after\r\n");

packages/app/src/terminal/native-renderer/terminal-selection.ts

@@ -324,10 +324,17 @@ export function extractTerminalSelectedText(input: TerminalSelectedTextInput): s
     const cells = window.rows[offset] ?? [];
     const startsOnThisRow = row === selection.start.row;
     const endsOnThisRow = row === selection.end.row;
-    const startCol = startsOnThisRow ? selection.start.col : 0;
+    let startCol = Math.max(0, startsOnThisRow ? selection.start.col : 0);
+    // Selecting either half highlights the whole wide character, so copy its leading cell too.
+    if (startCol > 0 && cells[startCol]?.width === 0) {
+      startCol -= 1;
+    }
     const endCol = endsOnThisRow ? selection.end.col : cells.length - 1;
-    const selectedCells = cells.slice(Math.max(0, startCol), Math.max(0, endCol) + 1);
-    const line = selectedCells.map((cell) => cell.char || " ").join("");
+    const selectedCells = cells.slice(startCol, Math.max(0, endCol) + 1);
+    const line = selectedCells
+      .filter((cell) => cell.width !== 0)
+      .map((cell) => cell.char)
+      .join("");
     if (offset > 0 && window.wrappedRows[offset] !== true) {
       text += "\n";
     }

packages/app/src/timeline/replica.test.ts

@@ -77,6 +77,90 @@ function applySynced(agentId: string, seq: number): void {
 afterEach(() => useSessionStore.getState().clearSession(SERVER_ID));
 
 describe("viewed timeline persistence", () => {
+  it("keeps one complete reply when live chunks arrive before a cached chat catches up", async () => {
+    useSessionStore.getState().initializeSession(SERVER_ID, null);
+    const partial = "Paragraph 1. Paragraph 2.";
+    const complete = `${partial} Paragraph 3. END`;
+    const owner = createOwner({
+      readTimeline: async () => ({
+        agentId: AGENT_ID,
+        items: [{ ...item("reply-1", partial, 4), messageId: "reply-1" }],
+        range: { epoch: "epoch-1", startSeq: 1, endSeq: 4 },
+        hasOlder: false,
+      }),
+      commitTimeline: () => undefined,
+    });
+    try {
+      owner.replaceVisibleAgentIds("test", [AGENT_ID]);
+      await expect
+        .poll(
+          () =>
+            selectAgentTimelineState(useSessionStore.getState().sessions[SERVER_ID], AGENT_ID)
+              .status,
+        )
+        .toBe("painted");
+      owner.enqueueStreamEvent(AGENT_ID, {
+        event: {
+          type: "timeline",
+          provider: "codex",
+          item: { type: "assistant_message", text: " Paragraph 3.", messageId: "reply-1" },
+        } as AgentStreamEventPayload,
+        seq: 5,
+        epoch: "epoch-1",
+        timestamp: new Date("2026-08-26T10:00:01.000Z"),
+      });
+      owner.flushStreamAgent(AGENT_ID);
+      owner.applyTimelineResponse({
+        requestId: "resume",
+        agentId: AGENT_ID,
+        agent: null,
+        direction: "after",
+        projection: "projected",
+        reset: false,
+        epoch: "epoch-1",
+        window: { minSeq: 1, maxSeq: 6, nextSeq: 7 },
+        startCursor: { epoch: "epoch-1", seq: 5 },
+        endCursor: { epoch: "epoch-1", seq: 6 },
+        entries: [
+          {
+            provider: "codex",
+            item: { type: "assistant_message", text: complete, messageId: "reply-1" },
+            timestamp: "2026-08-26T10:00:02.000Z",
+            seqStart: 2,
+            seqEnd: 6,
+            sourceSeqRanges: [{ startSeq: 2, endSeq: 6 }],
+            collapsed: ["assistant_merge"],
+          },
+        ],
+        error: null,
+        hasNewer: false,
+        hasOlder: false,
+        staleCursor: false,
+        gap: false,
+      });
+      const replyTexts = () => {
+        const session = useSessionStore.getState().sessions[SERVER_ID];
+        return [
+          ...(session?.agentStreamTail.get(AGENT_ID) ?? []),
+          ...(session?.agentStreamHead.get(AGENT_ID) ?? []),
+        ]
+          .filter((entry) => entry.kind === "assistant_message")
+          .map((entry) => entry.text);
+      };
+      expect.soft(replyTexts()).toEqual([complete]);
+      owner.enqueueStreamEvent(AGENT_ID, {
+        event: { type: "turn_completed", provider: "codex" } as AgentStreamEventPayload,
+        seq: 7,
+        epoch: "epoch-1",
+        timestamp: new Date("2026-08-26T10:00:03.000Z"),
+      });
+      owner.flushStreamAgent(AGENT_ID);
+      expect.soft(replyTexts()).toEqual([complete]);
+    } finally {
+      owner.dispose();
+    }
+  });
+
   it("shares an in-flight cache preparation with the viewed owner", async () => {
     useSessionStore.getState().initializeSession(SERVER_ID, null);
     let release!: (value: CachedTimeline) => void;

packages/app/src/timeline/session-stream-reducers.ts

@@ -811,7 +811,7 @@ function reconcileOverlappingProjectedAssistant(params: {
   };
 
   const headMatch = findMatch(params.head);
-  const tailMatch = headMatch ? null : findMatch(params.tail);
+  const tailMatch = findMatch(params.tail);
   const match = headMatch ?? tailMatch;
   if (!match) {
     return { tail: params.tail, head: params.head, reconciled: false };
@@ -833,8 +833,20 @@ function reconcileOverlappingProjectedAssistant(params: {
   };
 
   if (headMatch) {
+    const tailCursor = tailMatch?.current.timelineCursor;
+    const replacesCachedPrefix =
+      tailMatch !== null &&
+      tailCursor?.epoch === params.epoch &&
+      unit.sourceSeqRanges.some(
+        (range) => range.startSeq <= tailCursor.seq && tailCursor.seq <= range.endSeq,
+      );
     return {
-      tail: params.tail,
+      // Live chunks can arrive before catch-up while their cached prefix is still painted.
+      // The projected reply owns both copies; keeping the prefix would duplicate it and
+      // cause completion to discard the updated head as an already-committed item.
+      tail: replacesCachedPrefix
+        ? [...params.tail.slice(0, tailMatch.index), ...params.tail.slice(tailMatch.index + 1)]
+        : params.tail,
       head: replaceMatch(params.head, headMatch.index),
       reconciled: true,
     };

public-docs/plugins/reference.md

@@ -1318,6 +1318,13 @@ the source row, so updates to one streaming item do not remount its renderer. Us
 `useRevealedText(text, phase)` hook when a renderer should pace streaming text like Paseo's built-in
 assistant rows.
 
+Chat find (Ctrl or Cmd+F) finds and highlights text in replacement rows when the query also
+matches the original message. The host searches the original prompt text or the assistant reply
+with Markdown syntax removed, then the app counts matches in the text your renderer draws.
+Text added only by your renderer is not independently indexed. Matches stay within a rendered
+block, and find skips buttons, icons, and anything with `aria-hidden="true"`. Find only runs on
+the web and desktop apps.
+
 ### Append a timeline row from the daemon
 
 A server handler can add a plugin-owned row to canonical history: