@stigmer/react 3.1.1 → 3.1.3

package/src/internal/ResizableSplit.tsx

@@ -9,29 +9,67 @@ import {
 } from "react";
 import { cn } from "@stigmer/theme";
 
+/** Which pane carries the drag-controlled pixel width; its sibling flexes. */
+export type ResizablePane = "primary" | "secondary";
+
+/**
+ * Which pane (if any) collapses below the `lg` breakpoint, leaving its sibling
+ * full-width. Use this to hide the pixel-sized pane on narrow screens — always
+ * pair it with {@link ResizableSplitProps.resizablePane} (hide the fixed pane so
+ * the visible sibling is the flexing one and fills the row). `"none"` keeps both
+ * panes at every width.
+ */
+export type ResizableCollapse = "primary" | "secondary" | "none";
+
 /** Props for {@link ResizableSplit}. */
 export interface ResizableSplitProps {
-  /** Content rendered in the flexible (left) region. */
+  /** Content rendered in the first (left) region. */
   readonly primary: ReactNode;
-  /** Content rendered in the resizable (right) panel. */
+  /** Content rendered in the second (right) region. */
   readonly secondary: ReactNode;
   /**
-   * Default width of the secondary panel in pixels.
+   * Which pane is pixel-sized and drag-resizable; the other flexes to fill.
+   * Child render order is fixed (`primary` then `secondary`) regardless of this
+   * value, so flipping it re-flows the layout without remounting either child.
+   * @default "secondary"
+   */
+  readonly resizablePane?: ResizablePane;
+  /**
+   * Default width of the resizable pane in pixels.
    * Overridden by a persisted value when `storageKey` is set.
    * @default 384
    */
   readonly defaultSize?: number;
-  /** Minimum width of the secondary panel in pixels. @default 280 */
+  /** Minimum width of the resizable pane in pixels. @default 280 */
   readonly minSize?: number;
-  /** Maximum width of the secondary panel in pixels. @default 800 */
+  /** Maximum width of the resizable pane in pixels. @default 800 */
   readonly maxSize?: number;
   /**
-   * `localStorage` key for persisting the panel width across sessions.
-   * When omitted, the panel width resets to `defaultSize` on remount.
+   * `localStorage` key for persisting the pane width across sessions.
+   * When omitted, the pane width resets to `defaultSize` on remount.
+   * Changing this key (or `resizablePane`) re-initializes the width from the
+   * new key without remounting — the mechanism the session layout uses to keep
+   * a distinct persisted width per mode.
    */
   readonly storageKey?: string;
+  /** Which pane collapses below the `lg` breakpoint. @default "none" */
+  readonly responsiveCollapse?: ResizableCollapse;
+  /**
+   * Which pane (if any) is collapsed at every width, hiding the drag handle and
+   * letting the sibling fill the row. Unlike conditional rendering at the call
+   * site, collapsing through this prop keeps both children mounted at stable
+   * tree positions — the session panel uses it so opening/closing the panel
+   * never remounts the conversation. The persisted width survives a collapse
+   * and applies again on expand.
+   * @default "none"
+   */
+  readonly collapsedPane?: ResizableCollapse;
+  /**
+   * Accessible label for the drag separator. @default "Resize panel"
+   */
+  readonly ariaLabel?: string;
   /**
-   * Called whenever the secondary panel width changes (during drag
+   * Called whenever the resizable pane width changes (during drag
    * and on initial mount from persisted state). Consumers use this
    * to thread the width into layout-dependent calculations like
    * `WorkflowExecutionGraph.panelOffsetPx`.
@@ -44,62 +82,111 @@ export interface ResizableSplitProps {
 const KEYBOARD_STEP_PX = 20;
 
 /**
- * Horizontal split layout with a drag-resizable right panel.
+ * Read the initial pane width for a given storage key, falling back to
+ * `defaultSize` when there is no valid persisted value. Pure of React state so
+ * it can seed `useState` and re-seed on a key/pane change.
+ */
+function readInitialWidth(
+  storageKey: string | undefined,
+  defaultSize: number,
+  minSize: number,
+  maxSize: number,
+): number {
+  if (storageKey) {
+    try {
+      const stored = localStorage.getItem(storageKey);
+      if (stored) {
+        const parsed = Number(stored);
+        if (Number.isFinite(parsed) && parsed >= minSize && parsed <= maxSize) {
+          return parsed;
+        }
+      }
+    } catch {
+      /* localStorage may be unavailable */
+    }
+  }
+  return defaultSize;
+}
+
+/**
+ * Horizontal split layout with one drag-resizable pixel-sized pane and one
+ * flexible pane.
  *
- * The left region (`primary`) fills remaining space via `flex: 1`.
- * The right region (`secondary`) has a pixel-based width controlled
- * by a draggable divider.
+ * By default the right region (`secondary`) is pixel-sized and the left
+ * (`primary`) flexes. Set `resizablePane="primary"` to flip which side carries
+ * the width — the session layout uses this to invert between a chat-dominant
+ * layout (inspector on the right, fixed) and a workspace-dominant layout (chat
+ * on the left, fixed). Render order never changes, so flipping re-flows the row
+ * without remounting either child (preserving streaming/scroll state).
  *
  * Design:
  * - Pointer-based drag with `setPointerCapture` for reliable tracking
  * - `requestAnimationFrame` coalescing during drag (DD-009 pattern)
- * - Keyboard accessible: Left/Right arrows nudge by {@link KEYBOARD_STEP_PX}
- * - Optional `localStorage` persistence via `storageKey`
+ * - Keyboard accessible: arrow keys nudge by {@link KEYBOARD_STEP_PX}, oriented
+ *   so the pane always grows toward its own side
+ * - Optional `localStorage` persistence via `storageKey`, re-initialized when
+ *   the key or resizable side changes (no remount required)
+ * - Optional responsive collapse of the pixel pane below `lg`
  * - Styled with `--stgm-*` tokens; no hardcoded colors
  *
  * @example
  * ```tsx
+ * // Chat-dominant: inspector fixed on the right (default)
+ * <ResizableSplit
+ *   primary={<Conversation />}
+ *   secondary={<Inspector />}
+ *   storageKey="stgm-session-inspector-width"
+ *   responsiveCollapse="secondary"
+ * />
+ *
+ * // Workspace-dominant: chat fixed on the left
  * <ResizableSplit
- *   primary={<WorkflowGraph />}
- *   secondary={<InspectorPanel />}
- *   defaultSize={384}
- *   minSize={280}
- *   maxSize={800}
- *   storageKey="wf-exec-inspector-width"
- *   onResize={setPanelWidth}
+ *   resizablePane="primary"
+ *   primary={<Conversation />}
+ *   secondary={<WorkspaceSurface />}
+ *   storageKey="stgm-session-chat-width"
+ *   responsiveCollapse="primary"
  * />
  * ```
  */
 export function ResizableSplit({
   primary,
   secondary,
+  resizablePane = "secondary",
   defaultSize = 384,
   minSize = 280,
   maxSize = 800,
   storageKey,
+  responsiveCollapse = "none",
+  collapsedPane = "none",
+  ariaLabel = "Resize panel",
   onResize,
   className,
 }: ResizableSplitProps) {
-  const [panelWidth, setPanelWidth] = useState(() => {
-    if (storageKey) {
-      try {
-        const stored = localStorage.getItem(storageKey);
-        if (stored) {
-          const parsed = Number(stored);
-          if (Number.isFinite(parsed) && parsed >= minSize && parsed <= maxSize) {
-            return parsed;
-          }
-        }
-      } catch { /* localStorage may be unavailable */ }
-    }
-    return defaultSize;
-  });
+  const isPrimaryResizable = resizablePane === "primary";
+  const isCollapsed = collapsedPane !== "none";
+
+  const [panelWidth, setPanelWidth] = useState(() =>
+    readInitialWidth(storageKey, defaultSize, minSize, maxSize),
+  );
+
+  // Re-initialize the width when the storage key or resizable side changes —
+  // the session layout swaps both together on a mode flip and expects the width
+  // to come from the new key, not carry over. Adjust-state-during-render
+  // (matching `useSessionPanel`) so it lands before paint without a remount.
+  const [prevStorageKey, setPrevStorageKey] = useState(storageKey);
+  const [prevResizablePane, setPrevResizablePane] = useState(resizablePane);
+  if (storageKey !== prevStorageKey || resizablePane !== prevResizablePane) {
+    setPrevStorageKey(storageKey);
+    setPrevResizablePane(resizablePane);
+    setPanelWidth(readInitialWidth(storageKey, defaultSize, minSize, maxSize));
+  }
 
   const containerRef = useRef<HTMLDivElement>(null);
   const rafRef = useRef(0);
   const isDraggingRef = useRef(false);
 
-  // Notify consumer of initial width on mount
+  // Notify consumer of the current width whenever it changes (incl. on re-init).
   const onResizeRef = useRef(onResize);
   onResizeRef.current = onResize;
   useEffect(() => {
@@ -116,7 +203,9 @@ export function ResizableSplit({
       if (!storageKey) return;
       try {
         localStorage.setItem(storageKey, String(width));
-      } catch { /* quota or security error */ }
+      } catch {
+        /* quota or security error */
+      }
     },
     [storageKey],
   );
@@ -140,11 +229,15 @@ export function ResizableSplit({
         const container = containerRef.current;
         if (!container) return;
         const rect = container.getBoundingClientRect();
-        const newWidth = clampWidth(rect.right - clientX);
-        setPanelWidth(newWidth);
+        // The resizable pane's width is the distance from its own edge to the
+        // pointer: left edge for a primary pane, right edge for a secondary one.
+        const raw = isPrimaryResizable
+          ? clientX - rect.left
+          : rect.right - clientX;
+        setPanelWidth(clampWidth(raw));
       });
     },
-    [clampWidth],
+    [clampWidth, isPrimaryResizable],
   );
 
   const handlePointerUp = useCallback(
@@ -160,9 +253,11 @@ export function ResizableSplit({
 
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
+      // Arrow keys grow the pane toward its own side: a primary (left) pane
+      // grows on ArrowRight, a secondary (right) pane grows on ArrowLeft.
       let delta = 0;
-      if (e.key === "ArrowLeft") delta = KEYBOARD_STEP_PX;
-      else if (e.key === "ArrowRight") delta = -KEYBOARD_STEP_PX;
+      if (e.key === "ArrowLeft") delta = isPrimaryResizable ? -KEYBOARD_STEP_PX : KEYBOARD_STEP_PX;
+      else if (e.key === "ArrowRight") delta = isPrimaryResizable ? KEYBOARD_STEP_PX : -KEYBOARD_STEP_PX;
       if (delta === 0) return;
 
       e.preventDefault();
@@ -172,26 +267,57 @@ export function ResizableSplit({
         return next;
       });
     },
-    [clampWidth, persist],
+    [clampWidth, persist, isPrimaryResizable],
   );
 
   // Cleanup rAF on unmount
   useEffect(() => () => cancelAnimationFrame(rafRef.current), []);
 
+  const fixedPaneClass = "shrink-0 overflow-hidden";
+  const flexPaneClass = "min-w-0 flex-1";
+
+  // A collapsed pane hides entirely and its sibling flexes to fill the row,
+  // overriding the fixed/flex split. Width state is untouched, so expanding
+  // restores the previous size.
+  const primaryPaneClass =
+    collapsedPane === "primary"
+      ? "hidden"
+      : collapsedPane === "secondary" || !isPrimaryResizable
+        ? flexPaneClass
+        : fixedPaneClass;
+  const secondaryPaneClass =
+    collapsedPane === "secondary"
+      ? "hidden"
+      : collapsedPane === "primary" || isPrimaryResizable
+        ? flexPaneClass
+        : fixedPaneClass;
+
   return (
     <div ref={containerRef} className={cn("flex min-h-0 flex-1", className)}>
-      {/* Primary region (flexible) */}
-      <div className="min-w-0 flex-1">{primary}</div>
+      {/* Primary region (first child, order-stable across flips/collapses) */}
+      <div
+        className={cn(
+          primaryPaneClass,
+          responsiveCollapse === "primary" && "max-lg:hidden",
+        )}
+        style={
+          isPrimaryResizable && !isCollapsed ? { width: panelWidth } : undefined
+        }
+      >
+        {primary}
+      </div>
 
-      {/* Drag handle */}
+      {/* Drag handle — CSS-hidden (not unmounted) while collapsed so all three
+          children keep stable tree positions across a collapse toggle. */}
       <div
         role="separator"
         aria-orientation="vertical"
         aria-valuenow={panelWidth}
         aria-valuemin={minSize}
         aria-valuemax={maxSize}
-        aria-label="Resize inspector panel"
-        tabIndex={0}
+        aria-label={ariaLabel}
+        aria-hidden={isCollapsed || undefined}
+        tabIndex={isCollapsed ? -1 : 0}
         onPointerDown={handlePointerDown}
         onPointerMove={handlePointerMove}
         onPointerUp={handlePointerUp}
@@ -203,16 +329,23 @@ export function ResizableSplit({
           "focus-visible:bg-[var(--stgm-primary,#6366f1)] focus-visible:outline-none",
           "active:bg-[var(--stgm-primary,#6366f1)]",
           "transition-colors duration-100",
+          responsiveCollapse !== "none" && "max-lg:hidden",
+          isCollapsed && "hidden",
         )}
       >
         {/* Wider invisible hit target (12px) for easier grabbing */}
         <div className="absolute inset-y-0 -left-1.5 -right-1.5" />
       </div>
 
-      {/* Secondary region (resizable, fixed width) */}
+      {/* Secondary region (second child, order-stable across flips/collapses) */}
       <div
-        className="shrink-0 overflow-hidden"
-        style={{ width: panelWidth }}
+        className={cn(
+          secondaryPaneClass,
+          responsiveCollapse === "secondary" && "max-lg:hidden",
+        )}
+        style={
+          !isPrimaryResizable && !isCollapsed ? { width: panelWidth } : undefined
+        }
       >
         {secondary}
       </div>

package/src/internal/VirtualizedThread.tsx

@@ -14,7 +14,9 @@ import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution
 import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import {
   ThreadItemRenderer,
+  threadContentColumnClass,
   type ThreadItem,
+  type ThreadContentColumn,
 } from "../execution/MessageThread.js";
 import { FilePathContext, type FilePathContextValue } from "../execution/FilePathContext.js";
 import { SandboxContext, type SandboxContextValue } from "../execution/SandboxContext.js";
@@ -45,9 +47,11 @@ export interface VirtualizedThreadProps {
   readonly fileReviewCtx: FileReviewContextValue;
   readonly unresolvedApprovalCount: number;
   readonly onBuildFromPlan?: () => void;
+  readonly onOpenPlan?: (executionId: string) => void;
   readonly org?: string;
   readonly planActionsDisabled?: boolean;
-  readonly centerContent?: boolean;
+  readonly planBuildPending?: boolean;
+  readonly contentColumn?: ThreadContentColumn;
   readonly onRetrySend?: () => void;
   readonly onRetryExecution?: (message: string) => void;
   readonly onEditMessage?: (text: string) => void;
@@ -112,9 +116,11 @@ export function VirtualizedThread({
   fileReviewCtx,
   unresolvedApprovalCount,
   onBuildFromPlan,
+  onOpenPlan,
   org,
   planActionsDisabled,
-  centerContent,
+  planBuildPending,
+  contentColumn,
   onRetrySend,
   onRetryExecution,
   onEditMessage,
@@ -148,13 +154,15 @@ export function VirtualizedThread({
       submittingApprovalIds,
       approvalErrors,
       onBuildFromPlan,
+      onOpenPlan,
       org,
       planActionsDisabled,
+      planBuildPending,
       onRetrySend,
       onRetryExecution,
       onEditMessage,
     }),
-    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, approvalErrors, onBuildFromPlan, org, planActionsDisabled, onRetrySend, onRetryExecution, onEditMessage],
+    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, approvalErrors, onBuildFromPlan, onOpenPlan, org, planActionsDisabled, planBuildPending, onRetrySend, onRetryExecution, onEditMessage],
   );
 
   return (
@@ -177,7 +185,7 @@ export function VirtualizedThread({
           className="h-full"
           components={{ Scroller: ScrollerWithA11y }}
           itemContent={(index, item) => (
-            <div className={cn("pb-4 pt-0 first:pt-6", centerContent && "mx-auto w-full max-w-3xl px-4")}>
+            <div className={cn("pb-4 pt-0 first:pt-6", threadContentColumnClass(contentColumn))}>
               <ThreadItemWrapper animate={index >= items.length - 2}>
                 <ThreadItemRenderer
                   item={item}

package/src/internal/__tests__/ResizableSplit.test.tsx

@@ -72,6 +72,67 @@ describe("ResizableSplit", () => {
     });
   });
 
+  describe("collapsedPane", () => {
+    /** The pane wrapper div for a rendered probe. */
+    function paneOf(testId: string): HTMLElement {
+      return screen.getByTestId(testId).parentElement as HTMLElement;
+    }
+
+    it("hides the collapsed pane and the separator; the sibling flexes", () => {
+      renderSplit({ collapsedPane: "secondary" });
+      expect(paneOf("secondary").className).toContain("hidden");
+      expect(paneOf("primary").className).toContain("flex-1");
+      const separator = screen.getByRole("separator", { hidden: true });
+      expect(separator.className).toContain("hidden");
+      expect(separator.getAttribute("tabindex")).toBe("-1");
+    });
+
+    it("overrides the resizable pane's fixed width while collapsed", () => {
+      renderSplit({ resizablePane: "primary", collapsedPane: "secondary" });
+      // Primary is normally pixel-sized; with its sibling collapsed it flexes.
+      expect(paneOf("primary").style.width).toBe("");
+      expect(paneOf("primary").className).toContain("flex-1");
+    });
+
+    it("keeps both children mounted (same DOM nodes) across a collapse toggle", () => {
+      const { rerender } = render(
+        <ResizableSplit
+          resizablePane="primary"
+          collapsedPane="secondary"
+          primary={<div data-testid="primary">Primary</div>}
+          secondary={<div data-testid="secondary">Secondary</div>}
+        />,
+      );
+      const primaryBefore = screen.getByTestId("primary");
+      const secondaryBefore = screen.getByTestId("secondary");
+      rerender(
+        <ResizableSplit
+          resizablePane="primary"
+          collapsedPane="none"
+          primary={<div data-testid="primary">Primary</div>}
+          secondary={<div data-testid="secondary">Secondary</div>}
+        />,
+      );
+      // Identical node references — expanding never remounted either pane.
+      expect(screen.getByTestId("primary")).toBe(primaryBefore);
+      expect(screen.getByTestId("secondary")).toBe(secondaryBefore);
+      expect(paneOf("primary").style.width).toBe("384px");
+    });
+
+    it("restores the persisted width when expanding after a collapse", () => {
+      localStorage.setItem("collapse-key", "451");
+      renderSplit({
+        resizablePane: "primary",
+        collapsedPane: "secondary",
+        storageKey: "collapse-key",
+        minSize: 300,
+        maxSize: 600,
+      });
+      const separator = screen.getByRole("separator", { hidden: true });
+      expect(separator.getAttribute("aria-valuenow")).toBe("451");
+    });
+  });
+
   describe("keyboard interaction", () => {
     it("increases panel width on ArrowLeft", () => {
       renderSplit({ defaultSize: 400 });
@@ -145,11 +206,72 @@ describe("ResizableSplit", () => {
       expect(separator.getAttribute("tabindex")).toBe("0");
     });
 
-    it("has accessible label", () => {
+    it("has a default accessible label", () => {
       renderSplit();
       const separator = screen.getByRole("separator");
-      expect(separator.getAttribute("aria-label")).toBe(
-        "Resize inspector panel",
+      expect(separator.getAttribute("aria-label")).toBe("Resize panel");
+    });
+
+    it("uses a custom accessible label", () => {
+      renderSplit({ ariaLabel: "Resize file explorer" });
+      const separator = screen.getByRole("separator");
+      expect(separator.getAttribute("aria-label")).toBe("Resize file explorer");
+    });
+  });
+
+  describe("resizablePane", () => {
+    it("grows a primary pane on ArrowRight (toward its own side)", () => {
+      renderSplit({ resizablePane: "primary", defaultSize: 400 });
+      const separator = screen.getByRole("separator");
+
+      fireEvent.keyDown(separator, { key: "ArrowRight" });
+
+      expect(separator.getAttribute("aria-valuenow")).toBe("420");
+    });
+
+    it("shrinks a primary pane on ArrowLeft", () => {
+      renderSplit({ resizablePane: "primary", defaultSize: 400 });
+      const separator = screen.getByRole("separator");
+
+      fireEvent.keyDown(separator, { key: "ArrowLeft" });
+
+      expect(separator.getAttribute("aria-valuenow")).toBe("380");
+    });
+  });
+
+  describe("width re-initialization on key change", () => {
+    it("reloads the width from the new storageKey without remounting", () => {
+      localStorage.setItem("key-a", "300");
+      localStorage.setItem("key-b", "520");
+      const { rerender } = render(
+        <ResizableSplit
+          primary={<div data-testid="primary">Primary</div>}
+          secondary={<div data-testid="secondary">Secondary</div>}
+          storageKey="key-a"
+          minSize={200}
+          maxSize={600}
+        />,
+      );
+      const primary = screen.getByTestId("primary");
+      expect(screen.getByRole("separator").getAttribute("aria-valuenow")).toBe(
+        "300",
+      );
+
+      rerender(
+        <ResizableSplit
+          primary={<div data-testid="primary">Primary</div>}
+          secondary={<div data-testid="secondary">Secondary</div>}
+          storageKey="key-b"
+          resizablePane="primary"
+          minSize={200}
+          maxSize={600}
+        />,
+      );
+
+      // Same DOM node — the child was re-flowed, not remounted.
+      expect(screen.getByTestId("primary")).toBe(primary);
+      expect(screen.getByRole("separator").getAttribute("aria-valuenow")).toBe(
+        "520",
       );
     });
   });

package/src/internal/__tests__/markdown-components.test.tsx

@@ -3,6 +3,7 @@ import { render, cleanup } from "@testing-library/react";
 import type { ComponentType, ReactNode } from "react";
 import {
   MARKDOWN_COMPONENTS,
+  extractLeadingH1,
   unwrapEnclosingMarkdownFence,
 } from "../markdown-components";
 
@@ -63,6 +64,73 @@ describe("unwrapEnclosingMarkdownFence", () => {
     const once = unwrapEnclosingMarkdownFence(wrapped);
     expect(unwrapEnclosingMarkdownFence(once)).toBe(once);
   });
+
+  describe("allowBareFence (plan-document surfaces)", () => {
+    it.each([
+      ["a bare whole-body fence", "```\n# Plan\n- step\n```", "# Plan\n- step"],
+      [
+        "a bare fence with surrounding whitespace",
+        "\n```\n# Plan\n```\n",
+        "# Plan",
+      ],
+      [
+        "still unwraps the tagged form",
+        "```markdown\n# Plan\n```",
+        "# Plan",
+      ],
+    ])("unwraps %s", (_label, input, expected) => {
+      expect(unwrapEnclosingMarkdownFence(input, true)).toBe(expected);
+    });
+
+    it.each([
+      ["a language-tagged code block", "```python\nprint('hi')\n```"],
+      ["an unclosed bare fence (mid-stream)", "```\n# Plan in progr"],
+      ["trailing content after the fence", "```\n# Plan\n```\nthen more"],
+      ["leading content before the fence", "intro\n```\n# Plan\n```"],
+      ["plain markdown (no fence)", "# Plan\n\n- step"],
+    ])("leaves %s untouched even with allowBareFence", (_label, input) => {
+      expect(unwrapEnclosingMarkdownFence(input, true)).toBe(input);
+    });
+  });
+});
+
+describe("extractLeadingH1", () => {
+  it("splits a leading # heading into title and body", () => {
+    expect(extractLeadingH1("# The Plan\n\nFirst paragraph.")).toEqual({
+      title: "The Plan",
+      body: "First paragraph.",
+    });
+  });
+
+  it("handles a document that is only a heading", () => {
+    expect(extractLeadingH1("# Just a Title")).toEqual({
+      title: "Just a Title",
+      body: "",
+    });
+  });
+
+  it("ignores leading whitespace before the heading", () => {
+    expect(extractLeadingH1("\n\n# The Plan\nBody")).toEqual({
+      title: "The Plan",
+      body: "Body",
+    });
+  });
+
+  it("returns null title when the document does not open with an H1", () => {
+    const doc = "Intro paragraph.\n\n# Later Heading\nBody";
+    expect(extractLeadingH1(doc)).toEqual({ title: null, body: doc });
+  });
+
+  it("does not treat deeper headings as the title", () => {
+    const doc = "## Section\nBody";
+    expect(extractLeadingH1(doc)).toEqual({ title: null, body: doc });
+  });
+
+  it("trims trailing whitespace from the title", () => {
+    expect(extractLeadingH1("#  Spaced Title  \nBody").title).toBe(
+      "Spaced Title",
+    );
+  });
 });
 
 describe("MARKDOWN_COMPONENTS.code (shared highlight seam)", () => {