@tangle-network/ui 11.15.0 → 11.15.2

package/src/chat/chat-container.synthetic.test.tsx

@@ -0,0 +1,171 @@
+import { render, renderHook, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import type { SessionMessage } from "../types/message";
+import type { SessionPart, TextPart, ToolPart } from "../types/parts";
+import { useRunGroups } from "../hooks/use-run-groups";
+import { ChatContainer, type ChatContainerProps } from "./chat-container";
+
+// Only the missing browser layout API is stubbed; transcript components are real.
+beforeAll(() => { Element.prototype.scrollIntoView = vi.fn(); });
+
+const messages: SessionMessage[] = [
+  { id: "user", role: "user" },
+  { id: "assistant", role: "assistant" },
+];
+const text = (value: string): TextPart => ({ type: "text", text: value });
+const note = (value: string): TextPart => ({ ...text(value), synthetic: true });
+const read = (id: string, path: string): ToolPart => ({
+  type: "tool", id, tool: "read",
+  state: { status: "completed", input: { path }, output: "File read." },
+});
+const firstTool = read("first", "src/first.ts");
+const secondTool = read("second", "src/second.ts");
+
+function expectOrder(...values: string[]) {
+  const nodes = values.map((value) => screen.getByText(value));
+  for (let i = 1; i < nodes.length; i++) {
+    expect(nodes[i - 1].compareDocumentPosition(nodes[i]) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  }
+}
+
+describe.each(["runs", "timeline"] as const)("synthetic transcript text: %s", (presentation) => {
+  function view(partMap: Record<string, SessionPart[]>, extra: Partial<ChatContainerProps> = {}) {
+    return <ChatContainer messages={messages} partMap={partMap} isStreaming={false} presentation={presentation} {...extra} />;
+  }
+
+  it("keeps mixed user and assistant notes in source order, outside speaker bubbles", () => {
+    const { container } = render(view({
+      user: [text("User before"), note("Delivery receipt"), text("User after")],
+      assistant: [text("Assistant before"), note("Missing trace"), text("Assistant after")],
+    }));
+    expectOrder("User before", "Delivery receipt", "User after", "Assistant before", "Missing trace", "Assistant after");
+    const notes = screen.getAllByRole("note", { name: "Application note" });
+    expect(notes).toHaveLength(2);
+    for (const element of notes) {
+      expect(element.closest('.bg-foreground, .tangle-prose, [class*="rounded-[26px]"]')).toBeNull();
+    }
+    const bubbles = container.querySelectorAll(".bg-foreground.text-background");
+    expect(bubbles).toHaveLength(2);
+    for (const bubble of bubbles) expect(bubble).not.toHaveTextContent("Delivery receipt");
+  });
+
+  it("retains synthetic-only messages without inventing speaker text", () => {
+    const { container } = render(view({ user: [note("Request receipt")], assistant: [note("No response persisted")] }));
+    expectOrder("Request receipt", "No response persisted");
+    expect(screen.getAllByRole("note")).toHaveLength(2);
+    expect(screen.queryByText("Agent")).not.toBeInTheDocument();
+    expect(container.querySelector(".bg-foreground, .tangle-prose")).toBeNull();
+  });
+
+  it("omits blank notes and blank source text", () => {
+    render(view({ user: [note(" \n "), text(" ")], assistant: [note("\t"), text("\n")] }));
+    expect(screen.queryByRole("note")).not.toBeInTheDocument();
+    expect(screen.queryByText("Agent")).not.toBeInTheDocument();
+  });
+
+  it("does not parse application notes as Markdown, HTML, or OpenUI", () => {
+    const literal = '<em>literal</em>\n**not markdown**\n```json\n{"type":"heading","text":"Not a heading"}\n```';
+    render(view({ user: [], assistant: [note(literal)] }));
+    const element = screen.getByRole("note");
+    expect(element.textContent).toContain(literal);
+    expect(element.querySelector("em, strong, h1, h2, h3, button, a")).toBeNull();
+    expect(element.innerHTML).toContain("&lt;em&gt;literal&lt;/em&gt;");
+  });
+
+  it("renders notes even when OpenUI rendering is disabled", () => {
+    render(view({ user: [], assistant: [note("Receipt with OpenUI off")] }, { enableOpenUI: false }));
+    expect(screen.getByRole("note")).toHaveTextContent("Receipt with OpenUI off");
+  });
+
+  it("retains repeated notes and their position rather than deduplicating content", () => {
+    render(view({ user: [], assistant: [note("Same receipt"), text("Between receipts"), note("Same receipt")] }));
+    const notes = screen.getAllByRole("note");
+    expect(notes).toHaveLength(2);
+    const middle = screen.getByText("Between receipts");
+    expect(notes[0].compareDocumentPosition(middle) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(middle.compareDocumentPosition(notes[1]) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  });
+
+  it("preserves tool/note order and original tool callback arguments", async () => {
+    const user = userEvent.setup();
+    const activated = vi.fn();
+    const renderRunTool = vi.fn<NonNullable<ChatContainerProps["renderToolActions"]>>((part, context) => (
+      <button type="button" onClick={() => activated(part, context)}>Inspect {part.id}</button>
+    ));
+    const renderTimelineTool = vi.fn((part: ToolPart) => (
+      <button type="button" onClick={() => activated(part)}>Inspect {part.id}</button>
+    ));
+    render(view({ user: [text("Read files")], assistant: [firstTool, note("Partial trace"), secondTool, text("Source answer")] }, {
+      renderToolActions: renderRunTool,
+      renderTimelineToolActions: renderTimelineTool,
+    }));
+    expectOrder("src/first.ts", "Partial trace", "src/second.ts", "Source answer");
+    await user.click(screen.getByRole("button", { name: "Inspect second" }));
+    expect(activated.mock.calls[0][0]).toBe(secondTool);
+    if (presentation === "runs") {
+      expect(activated.mock.calls[0][1]).toMatchObject({ messageId: "assistant", partIndex: 2 });
+      expect(renderTimelineTool).not.toHaveBeenCalled();
+      expect(screen.getByText("2 tools, 1 response")).toBeInTheDocument();
+    } else {
+      expect(renderRunTool).not.toHaveBeenCalled();
+    }
+  });
+
+  it("does not treat an application receipt as the pending assistant reply", () => {
+    const partMap = { user: [text("Question")], assistant: [note("Request accepted")] };
+    const { rerender } = render(view(partMap, { isStreaming: true }));
+    expect(screen.getByRole("note")).toHaveTextContent("Request accepted");
+    if (presentation === "timeline") {
+      expect(screen.getByRole("status", { name: "Agent is thinking" })).toBeInTheDocument();
+    } else {
+      expect(screen.getByText("Thinking")).toBeInTheDocument();
+    }
+    rerender(view({ ...partMap, assistant: [note("Request accepted"), text("Answer arrived")] }));
+    expect(screen.getByRole("note")).toHaveTextContent("Request accepted");
+    expect(screen.getByText("Answer arrived")).toBeInTheDocument();
+    expect(screen.queryByRole("status", { name: "Agent is thinking" })).not.toBeInTheDocument();
+    expect(screen.queryByText("Thinking")).not.toBeInTheDocument();
+  });
+});
+
+describe("run attribution and manual collapse", () => {
+  it.each([false, true])("excludes notes from response statistics and summaries (only notes: %s)", (onlyNotes) => {
+    const { result } = renderHook(() => useRunGroups({
+      messages,
+      partMap: { user: [text("Question")], assistant: onlyNotes ? [note("App receipt")] : [text("Authored answer"), note("App receipt")] },
+      isStreaming: false,
+    }));
+    const group = result.current.find((entry) => entry.type === "run");
+    expect(group?.type).toBe("run");
+    if (group?.type !== "run") throw new Error("Expected the real run group");
+    expect(group.run.stats.textPartCount).toBe(onlyNotes ? 0 : 1);
+    expect(group.run.summaryText).toBe(onlyNotes ? null : "Authored answer");
+  });
+
+  it("restores note order on keyboard expansion, without quoting notes in the run summary", async () => {
+    const user = userEvent.setup();
+    render(<ChatContainer messages={messages} partMap={{ user: [text("Question")], assistant: [firstTool, note("App-only receipt"), text("Source answer")] }} isStreaming={false} />);
+    expectOrder("src/first.ts", "App-only receipt", "Source answer");
+    const toggle = screen.getByRole("button", { expanded: true, name: /Agent/ });
+    await user.click(toggle);
+    expect(toggle).toHaveAttribute("aria-expanded", "false");
+    expect(toggle).toHaveTextContent("1 tool, 1 response");
+    expect(toggle).not.toHaveTextContent("App-only receipt");
+    expect(screen.queryByRole("note")).not.toBeInTheDocument();
+    toggle.focus();
+    await user.keyboard("{Enter}");
+    expect(toggle).toHaveAttribute("aria-expanded", "true");
+    expectOrder("src/first.ts", "App-only receipt", "Source answer");
+  });
+
+  it("restores notes behind the existing explicit timeline limit", async () => {
+    const user = userEvent.setup();
+    render(<ChatContainer messages={messages} partMap={{ user: [text("Question")], assistant: [firstTool, note("App-only receipt"), text("Source answer")] }} isStreaming={false} presentation="timeline" collapseTimelineAfter={1} />);
+    expect(screen.queryByRole("note")).not.toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "Show 2 more steps" }));
+    expectOrder("src/first.ts", "App-only receipt", "Source answer");
+    await user.click(screen.getByRole("button", { name: "Show less" }));
+    expect(screen.queryByRole("note")).not.toBeInTheDocument();
+  });
+});

package/src/chat/chat-container.tsx

@@ -8,7 +8,7 @@ import { ArrowDown } from "lucide-react";
 import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 import type { SessionMessage } from "../types/message";
-import type { SessionPart, TextPart, ToolPart } from "../types/parts";
+import type { SessionPart, ToolPart } from "../types/parts";
 import type { AgentBranding } from "../types/branding";
 import type { CustomToolRenderer } from "../types/tool-display";
 import type { Run } from "../types/run";
@@ -16,6 +16,7 @@ import { useRunGroups } from "../hooks/use-run-groups";
 import { useRunCollapseState } from "../hooks/use-run-collapse-state";
 import { useAutoScroll } from "../hooks/use-auto-scroll";
 import { MessageList } from "./message-list";
+import { SyntheticText, userTextSegments } from "./synthetic-text";
 import {
   AgentTimeline,
   type AgentTimelineItem,
@@ -219,21 +220,25 @@ function buildTimelineItems(
     const parts = partMap[message.id] ?? [];
 
     if (message.role === "user") {
-      const content = parts
-        .filter((part): part is TextPart => part.type === "text")
-        .map((part) => part.text)
-        .join("\n")
-        .trim();
-
-      if (!content) continue;
-
-      items.push({
-        id: message.id,
-        kind: "message",
-        role: "user",
-        content,
-        timestamp: createdAtFromMessage(message),
-      });
+      const segments = userTextSegments(parts);
+      for (const segment of segments) {
+        const id = segments.length === 1 ? message.id : `${message.id}-user-${segment.index}`;
+        if (segment.synthetic) {
+          items.push({
+            id,
+            kind: "custom",
+            content: <div className="mx-3"><SyntheticText text={segment.text} /></div>,
+          });
+        } else {
+          items.push({
+            id,
+            kind: "message",
+            role: "user",
+            content: segment.text.trim(),
+            timestamp: createdAtFromMessage(message),
+          });
+        }
+      }
       continue;
     }
 
@@ -289,6 +294,18 @@ function buildTimelineItems(
 
       flushToolBuffer(index);
 
+      // A note is neither an assistant reply nor an OpenUI instruction.
+      if (part.type === "text" && part.synthetic) {
+        if (part.text.trim()) {
+          items.push({
+            id: itemId,
+            kind: "custom",
+            content: <div className="mx-3"><SyntheticText text={part.text} /></div>,
+          });
+        }
+        return;
+      }
+
       if (part.type === "text" && !part.synthetic && part.text.trim()) {
         // Check if the text itself contains an OpenUI JSON block
         if (enableOpenUI) {

package/src/chat/synthetic-text.test.tsx

@@ -0,0 +1,80 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import type { SessionPart } from "../types/parts";
+import { SyntheticText, userTextSegments } from "./synthetic-text";
+import { UserMessage } from "./user-message";
+
+const mixed: SessionPart[] = [
+  { type: "text", text: "First" },
+  { type: "text", text: "Second", synthetic: false },
+  { type: "text", text: "Receipt", synthetic: true },
+  { type: "text", text: "Third" },
+  { type: "text", text: "Last receipt", synthetic: true },
+];
+
+describe("user text boundaries", () => {
+  it("joins adjacent authored parts, keeps source indices and does not mutate the input", () => {
+    const before = JSON.stringify(mixed);
+    expect(userTextSegments(mixed)).toEqual([
+      { index: 0, synthetic: false, text: "First\nSecond" },
+      { index: 2, synthetic: true, text: "Receipt" },
+      { index: 3, synthetic: false, text: "Third" },
+      { index: 4, synthetic: true, text: "Last receipt" },
+    ]);
+    expect(JSON.stringify(mixed)).toBe(before);
+  });
+
+  it("skips empty content without merging across a synthetic boundary", () => {
+    expect(userTextSegments([
+      { type: "text", text: "Before" },
+      { type: "text", text: " \n", synthetic: true },
+      { type: "text", text: "After" },
+    ])).toEqual([
+      { index: 0, synthetic: false, text: "Before" },
+      { index: 2, synthetic: false, text: "After" },
+    ]);
+    expect(userTextSegments([])).toEqual([]);
+  });
+
+  it("preserves a single joined bubble when no application note is present", () => {
+    const { container } = render(<UserMessage parts={mixed.slice(0, 2)} />);
+    expect(container.querySelectorAll(".bg-foreground.text-background")).toHaveLength(1);
+    expect(container.querySelector(".whitespace-pre-wrap")?.textContent).toBe("First\nSecond");
+    expect(screen.queryByRole("note")).not.toBeInTheDocument();
+  });
+
+  it.each(["", "Direct content"])("preserves explicit content precedence: %j", (content) => {
+    const { container } = render(<UserMessage content={content} parts={mixed} />);
+    expect(screen.queryByRole("note")).not.toBeInTheDocument();
+    expect(container.textContent).toBe(content);
+  });
+
+  it("renders message actions once after all segments, even after a trailing note", () => {
+    render(<UserMessage parts={mixed} actions={<button type="button">Retry message</button>} />);
+    const action = screen.getByRole("button", { name: "Retry message" });
+    const last = screen.getByText("Last receipt");
+    expect(last.compareDocumentPosition(action) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(screen.getAllByRole("button", { name: "Retry message" })).toHaveLength(1);
+  });
+
+  it("supports a note-only user message with one action and no inverse-theme bubble", () => {
+    const { container } = render(<UserMessage parts={[mixed[2]]} actions={<button type="button">Inspect receipt</button>} />);
+    expect(screen.getByRole("note")).toHaveTextContent("Receipt");
+    expect(screen.getByRole("button", { name: "Inspect receipt" })).toBeInTheDocument();
+    expect(container.querySelector(".bg-foreground")).toBeNull();
+  });
+
+  it("retains direct-content timestamps", () => {
+    const { container } = render(<UserMessage content="Original words" timestamp={new Date("2026-01-01T12:00:00Z")} />);
+    expect(container.querySelectorAll("[data-user-message-time]")).toHaveLength(1);
+    expect(screen.getByText("Original words")).toBeInTheDocument();
+  });
+
+  it("renders a visible, named plain-text note and omits blanks", () => {
+    const { rerender } = render(<SyntheticText text="No trace captured" />);
+    expect(screen.getByRole("note", { name: "Application note" })).toHaveTextContent("No trace captured");
+    expect(screen.getByText("Application note")).toBeVisible();
+    rerender(<SyntheticText text={" \n "} />);
+    expect(screen.queryByRole("note")).not.toBeInTheDocument();
+  });
+});

package/src/chat/synthetic-text.tsx

@@ -0,0 +1,51 @@
+import type { SessionPart } from "../types/parts";
+
+/** Internal transcript chrome, never attributed to a user or model. */
+export function SyntheticText({ text }: { text: string }) {
+  if (!text.trim()) return null;
+  return (
+    <div
+      role="note"
+      aria-label="Application note"
+      data-synthetic-text=""
+      className="min-w-0 rounded-md border border-dashed border-border bg-muted/30 px-3 py-2 text-sm text-muted-foreground"
+    >
+      <div className="mb-1 font-medium">Application note</div>
+      {/* Plain React text: receipts are not Markdown or executable OpenUI. */}
+      <div className="break-words whitespace-pre-wrap">{text}</div>
+    </div>
+  );
+}
+
+export interface UserTextSegment {
+  /** Original part index, so subsequent streamed parts do not change keys. */
+  index: number;
+  synthetic: boolean;
+  text: string;
+}
+
+/** Keep the existing joined user bubble, splitting only at application notes. */
+export function userTextSegments(parts: SessionPart[]): UserTextSegment[] {
+  const segments: UserTextSegment[] = [];
+  let pending: string[] = [];
+  let start = 0;
+  const flush = () => {
+    const text = pending.join("\n");
+    if (text.trim()) segments.push({ index: start, synthetic: false, text });
+    pending = [];
+  };
+  parts.forEach((part, index) => {
+    if (part.type !== "text") return;
+    if (part.synthetic) {
+      flush();
+      if (part.text.trim()) {
+        segments.push({ index, synthetic: true, text: part.text });
+      }
+    } else {
+      if (pending.length === 0) start = index;
+      pending.push(part.text);
+    }
+  });
+  flush();
+  return segments;
+}

package/src/chat/user-message.tsx

@@ -1,6 +1,7 @@
 import { memo, type ReactNode } from "react";
 import type { SessionMessage } from "../types/message";
 import type { SessionPart } from "../types/parts";
+import { SyntheticText, userTextSegments } from "./synthetic-text";
 
 export interface UserMessageProps {
   /** Session-model input: text is derived from these parts. */
@@ -16,47 +17,64 @@ function formatTime(date: Date): string {
   return date.toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" });
 }
 
+function MessageActions({ children }: { children: ReactNode }) {
+  return (
+    <div className="flex flex-wrap items-center justify-end gap-1.5 text-xs text-muted-foreground">
+      {children}
+    </div>
+  );
+}
+
+function UserBubble({ text, timestamp, actions }: {
+  text: string;
+  timestamp?: Date;
+  actions?: ReactNode;
+}) {
+  return (
+    <div className="flex justify-end">
+      <div className="group flex min-w-0 max-w-[78%] flex-col items-end gap-2">
+        <div className="relative w-full min-w-0 rounded-2xl bg-foreground px-4 py-3 text-background">
+          {timestamp ? (
+            <span
+              data-user-message-time=""
+              className="pointer-events-none absolute right-full top-1/2 mr-3 -translate-y-1/2 whitespace-nowrap text-[var(--font-size-xs)] text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100"
+            >
+              {formatTime(timestamp)}
+            </span>
+          ) : null}
+          <div className="break-words whitespace-pre-wrap text-[var(--font-size-base)] leading-[1.5]">
+            {text}
+          </div>
+        </div>
+        {actions ? <MessageActions>{actions}</MessageActions> : null}
+      </div>
+    </div>
+  );
+}
+
 /**
- * The single user message bubble uses inverse theme colors. The timestamp sits
- * beside the bubble and appears on hover, so it costs no height. Used by both
- * the run/message list (session-model `parts`) and AgentTimeline (direct
- * `content`/`timestamp`).
+ * User speech retains the inverse-theme bubble and direct-content contract.
+ * Application notes interrupt the bubble in source order, outside its attribution.
  */
 export const UserMessage = memo(
   ({ message: _message, parts, content, timestamp, actions }: UserMessageProps) => {
-    const text =
-      content ??
-      (parts ?? [])
-        .filter((p) => p.type === "text")
-        .map((p) => (p as { text: string }).text)
-        .join("\n");
-
-    if (!text.trim()) return null;
-
+    // Explicit direct content (including empty content) still overrides parts.
+    if (content != null) {
+      return content.trim() ? <UserBubble text={content} timestamp={timestamp} actions={actions} /> : null;
+    }
+    const segments = userTextSegments(parts ?? []);
+    if (segments.length === 0) return null;
+    if (segments.length === 1 && !segments[0].synthetic) {
+      return <UserBubble text={segments[0].text} timestamp={timestamp} actions={actions} />;
+    }
     return (
-      <div className="flex justify-end">
-        <div className="group flex min-w-0 max-w-[78%] flex-col items-end gap-2">
-          <div
-            className="relative w-full min-w-0 rounded-2xl bg-foreground px-4 py-3 text-background"
-          >
-            {timestamp ? (
-              <span
-                data-user-message-time=""
-                className="pointer-events-none absolute right-full top-1/2 mr-3 -translate-y-1/2 whitespace-nowrap text-[var(--font-size-xs)] text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100"
-              >
-                {formatTime(timestamp)}
-              </span>
-            ) : null}
-            <div className="break-words whitespace-pre-wrap text-[var(--font-size-base)] leading-[1.5]">
-              {text}
-            </div>
-          </div>
-          {actions ? (
-            <div className="flex flex-wrap items-center justify-end gap-1.5 text-xs text-muted-foreground">
-              {actions}
-            </div>
-          ) : null}
-        </div>
+      <div className="space-y-2">
+        {segments.map((segment) => segment.synthetic ? (
+          <SyntheticText key={segment.index} text={segment.text} />
+        ) : (
+          <UserBubble key={segment.index} text={segment.text} timestamp={timestamp} />
+        ))}
+        {actions ? <MessageActions>{actions}</MessageActions> : null}
       </div>
     );
   },

package/src/files/rich-file-tree.test.tsx

@@ -1,7 +1,15 @@
-import { describe, it, expect } from "vitest"
-import { render } from "@testing-library/react"
+import { describe, it, expect, vi } from "vitest"
+import { fireEvent, render, waitFor } from "@testing-library/react"
 import { RichFileTree } from "./rich-file-tree"
 
+function treeRow(container: HTMLElement, path: string): HTMLElement {
+  const host = container.querySelector("file-tree-container");
+  const row = Array.from(host?.shadowRoot?.querySelectorAll("[data-item-path]") ?? [])
+    .find((element) => element.getAttribute("data-item-path") === path);
+  if (!(row instanceof HTMLElement)) throw new Error(`Missing tree row: ${path}`);
+  return row;
+}
+
 describe("RichFileTree", () => {
   it("renders without crashing given a flat path list", () => {
     const { container } = render(
@@ -34,6 +42,46 @@ describe("RichFileTree", () => {
     expect(container.querySelectorAll("*").length).toBeGreaterThan(0)
   })
 
+  it("calls the current selection callback after its owner rerenders", async () => {
+    const original = vi.fn();
+    const current = vi.fn();
+    const paths = ["brief.md", "outreach.md"];
+    const { container, rerender } = render(<RichFileTree paths={paths} onSelect={original} />);
+    rerender(<RichFileTree paths={paths} onSelect={current} />);
+    fireEvent.click(treeRow(container, "outreach.md"));
+    await waitFor(() => expect(current).toHaveBeenCalledWith("outreach.md"));
+    expect(original).not.toHaveBeenCalled();
+  });
+
+  it("clears controlled selection so a closed file can be selected again", async () => {
+    const onSelect = vi.fn();
+    const paths = ["brief.md", "outreach.md"];
+    const { container, rerender } = render(
+      <RichFileTree paths={paths} selectedPath="brief.md" onSelect={onSelect} />,
+    );
+    rerender(<RichFileTree paths={paths} selectedPath={undefined} onSelect={onSelect} />);
+    await waitFor(() => expect(treeRow(container, "brief.md")).toHaveAttribute("aria-selected", "false"));
+    fireEvent.click(treeRow(container, "brief.md"));
+    await waitFor(() => expect(onSelect).toHaveBeenCalledExactlyOnceWith("brief.md"));
+  });
+
+  it("preserves uncontrolled selection when the file listing refreshes", async () => {
+    const { container, rerender } = render(<RichFileTree paths={["brief.md"]} />);
+    fireEvent.click(treeRow(container, "brief.md"));
+    await waitFor(() => expect(treeRow(container, "brief.md")).toHaveAttribute("aria-selected", "true"));
+    rerender(<RichFileTree paths={["brief.md", "outreach.md"]} />);
+    await waitFor(() => expect(treeRow(container, "brief.md")).toHaveAttribute("aria-selected", "true"));
+  });
+
+  it("does not notify the owner when a controlled selection is synchronized", async () => {
+    const onSelect = vi.fn();
+    const paths = ["brief.md", "outreach.md"];
+    const { container, rerender } = render(<RichFileTree paths={paths} selectedPath="brief.md" onSelect={onSelect} />);
+    rerender(<RichFileTree paths={paths} selectedPath="outreach.md" onSelect={onSelect} />);
+    await waitFor(() => expect(treeRow(container, "outreach.md")).toHaveAttribute("aria-selected", "true"));
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+
   it("throws when both root and paths are passed", () => {
     expect(() =>
       render(<RichFileTree root={{ name: "x", path: "x", type: "file" }} paths={["y"]} />),

package/src/files/rich-file-tree.tsx

@@ -27,7 +27,7 @@ import type {
   GitStatus,
   GitStatusEntry,
 } from "@pierre/trees";
-import { useEffect, useMemo, type CSSProperties, type ReactNode } from "react";
+import { useEffect, useMemo, useRef, type CSSProperties, type ReactNode } from "react";
 import type { FileNode } from "./file-tree";
 
 /**
@@ -169,13 +169,22 @@ export function RichFileTree({
     return [];
   }, [paths, root]);
 
+  // Pierre creates its model once; event handlers must read the current owner.
+  const selectionRef = useRef({ selectedPath, onSelect });
+  selectionRef.current = { selectedPath, onSelect };
+  const syncingSelectionRef = useRef(false);
+  const previousSelectedPathRef = useRef(selectedPath);
+
   const { model } = usePierreFileTree({
     paths: flatPaths,
     search,
     initialExpansion,
     onSelectionChange: (selected) => {
-      const next = selected[0]
-      if (next && next !== selectedPath) onSelect?.(next)
+      const next = selected[0];
+      const current = selectionRef.current;
+      if (!syncingSelectionRef.current && next && next !== current.selectedPath) {
+        current.onSelect?.(next);
+      }
     },
   });
 
@@ -192,17 +201,21 @@ export function RichFileTree({
     model.resetPaths(flatPaths);
   }, [model, flatPaths]);
 
-  // Drive selection from props (controlled). Skip when already selected
-  // to avoid an emit loop with onSelectionChange.
+  // Drive controlled selection with Pierre's public item API, including clearing it.
   useEffect(() => {
-    if (!selectedPath) return;
+    const previous = previousSelectedPathRef.current;
+    previousSelectedPathRef.current = selectedPath;
+    if (selectedPath === undefined && previous === undefined) return;
     const current = model.getSelectedPaths();
-    if (current.length === 1 && current[0] === selectedPath) return;
-    // The public API exposes selection via `select` semantics through the
-    // controller — fall back to direct setter when present, no-op otherwise.
-    const m = model as unknown as { setSelectedPaths?: (paths: readonly string[]) => void };
-    m.setSelectedPaths?.([selectedPath]);
-  }, [model, selectedPath]);
+    if (current.length === (selectedPath ? 1 : 0) && current[0] === selectedPath) return;
+    syncingSelectionRef.current = true;
+    try {
+      for (const path of [...current]) model.getItem(path)?.deselect();
+      if (selectedPath) model.getItem(selectedPath)?.select();
+    } finally {
+      syncingSelectionRef.current = false;
+    }
+  }, [model, selectedPath, flatPaths]);
 
   const theme = { ...DEFAULT_THEME, ...themeOverrides };
   const themeStyle = useMemo<CSSProperties>(