From 2d410d17b2d1473bb04e90801bcaed76abdc857e Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 19:40:43 -0500
Subject: [PATCH 01/32] =?UTF-8?q?=F0=9F=A4=96=20feat:=20sticky=20table=20o?=
 =?UTF-8?q?f=20contents=20next=20to=20plans=20in=20chat=20transcript?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a sticky 'Contents' navigation alongside propose_plan tool cards in the
chat transcript when the chat pane has enough horizontal room. Click any
entry to jump to that section in the plan; the TOC follows the user while
the plan is on screen and scrolls away naturally once the plan exits the
viewport.

Visibility is CSS-only (a container query on the transcript scrollport plus
an opt-in class), so toggling the plan tool expanded/collapsed never produces
a layout flash. The transcript scroll container is a named CSS container, so
the gate tracks actual chat-pane width and stays correct when sidebars open
or close.
---
 .storybook/preview.tsx                        |   7 +
 src/browser/components/ChatPane/ChatPane.tsx  |  12 +-
 .../ProposePlan/PlanTableOfContents.test.tsx  | 108 +++++++++++
 .../Tools/ProposePlan/PlanTableOfContents.tsx | 100 +++++++++++
 .../ProposePlanToolCall.stories.tsx           |  99 +++++++++++
 .../ProposePlan/extractPlanHeadings.test.ts   | 114 ++++++++++++
 .../Tools/ProposePlan/extractPlanHeadings.ts  | 141 +++++++++++++++
 .../Tools/ProposePlanToolCall.test.tsx        |  55 ++++++
 .../features/Tools/ProposePlanToolCall.tsx    |  29 ++-
 src/browser/styles/globals.css                | 168 ++++++++++++++++++
 10 files changed, 829 insertions(+), 4 deletions(-)
 create mode 100644 src/browser/features/Tools/ProposePlan/PlanTableOfContents.test.tsx
 create mode 100644 src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
 create mode 100644 src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
 create mode 100644 src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts

diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
index 60c3553ee3..45cd070c34 100644
--- a/.storybook/preview.tsx
+++ b/.storybook/preview.tsx
@@ -199,6 +199,13 @@ const preview: Preview = {
           styles: { width: "1280px", height: "800px" },
           type: "mobile",
         },
+        wide: {
+          // Wide enough to trigger the @container query that reveals the
+          // sticky plan TOC next to a centered max-w-4xl transcript.
+          name: "Desktop wide",
+          styles: { width: "1600px", height: "900px" },
+          type: "desktop",
+        },
       },
     },
     chromatic: {
diff --git a/src/browser/components/ChatPane/ChatPane.tsx b/src/browser/components/ChatPane/ChatPane.tsx
index b907b7e74d..2679a4ae17 100644
--- a/src/browser/components/ChatPane/ChatPane.tsx
+++ b/src/browser/components/ChatPane/ChatPane.tsx
@@ -1065,11 +1065,19 @@ const ChatPaneContent: React.FC<ChatPaneContentProps> = (props) => {
             // In manual reading mode, anchoring should preserve the user's viewport
             // when async highlights/diagrams above the fold settle.
             style={autoScroll ? AUTO_SCROLL_TRANSCRIPT_STYLE : undefined}
-            className="h-full overflow-x-hidden overflow-y-auto p-[15px] leading-[1.5] break-words whitespace-pre-wrap"
+            // The named `transcript` container is what the sticky plan TOC queries
+            // for visibility — using a container query rather than a viewport media
+            // query means sidebars opening/closing correctly hide the TOC even when
+            // the viewport width is unchanged. See `.plan-toc-aside` in globals.css.
+            className="@container/transcript h-full overflow-x-hidden overflow-y-auto p-[15px] leading-[1.5] break-words whitespace-pre-wrap"
           >
             <div
               className={cn(
-                chatTranscriptFullWidth ? "w-full" : "max-w-4xl mx-auto",
+                // `plan-toc-aware` opts only the centered max-w transcript into the
+                // sticky plan TOC layout. In `chatTranscriptFullWidth` mode the plan
+                // already fills the available width, so the TOC would either
+                // overlap content or get clipped by `overflow-x-hidden`.
+                chatTranscriptFullWidth ? "w-full" : "plan-toc-aware max-w-4xl mx-auto",
                 (showTranscriptHydrationPlaceholder || showEmptyTranscriptPlaceholder) && "h-full"
               )}
             >
diff --git a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.test.tsx b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.test.tsx
new file mode 100644
index 0000000000..49fc4e9256
--- /dev/null
+++ b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.test.tsx
@@ -0,0 +1,108 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { useRef } from "react";
+import { cleanup, fireEvent, render } from "@testing-library/react";
+
+import { installDom } from "../../../../../tests/ui/dom";
+import { PlanTableOfContents } from "./PlanTableOfContents";
+import type { PlanHeading } from "./extractPlanHeadings";
+
+/**
+ * Renders the PlanTableOfContents against a hand-rolled DOM that contains real
+ * <h1>/<h2>/<h3> elements. We test the click → scrollIntoView wiring here
+ * (instead of inside ProposePlanToolCall.test.tsx) because sibling test files
+ * mock MarkdownCore at file scope; those mocks make Streamdown render plain text
+ * without heading tags, which would break index-based DOM lookups.
+ */
+function HarnessRenderer({ entries }: { entries: PlanHeading[] }) {
+  const ref = useRef<HTMLDivElement>(null);
+  return (
+    <div>
+      <PlanTableOfContents entries={entries} contentRef={ref} />
+      <div ref={ref} data-testid="plan-body">
+        <h1>Intro</h1>
+        <p>...</p>
+        <h2>First section</h2>
+        <p>...</p>
+        <h2>Second section</h2>
+        <p>...</p>
+        <h3>Nested</h3>
+      </div>
+    </div>
+  );
+}
+
+describe("PlanTableOfContents", () => {
+  let cleanupDom: (() => void) | null = null;
+
+  beforeEach(() => {
+    cleanupDom = installDom();
+  });
+
+  afterEach(() => {
+    cleanup();
+    cleanupDom?.();
+    cleanupDom = null;
+  });
+
+  test("returns null when given fewer than two visible headings", () => {
+    const view = render(<HarnessRenderer entries={[{ renderIndex: 0, level: 1, text: "Only" }]} />);
+    expect(view.queryByTestId("plan-toc")).toBeNull();
+  });
+
+  test("ignores deeply nested headings (h5/h6) for display", () => {
+    const view = render(
+      <HarnessRenderer
+        entries={[
+          { renderIndex: 0, level: 5, text: "Too deep one" },
+          { renderIndex: 1, level: 6, text: "Too deep two" },
+        ]}
+      />
+    );
+    // Both entries are filtered out as too-deep, leaving 0 visible — TOC hidden.
+    expect(view.queryByTestId("plan-toc")).toBeNull();
+  });
+
+  test("scrolls the correct rendered heading into view when an entry is clicked", () => {
+    const entries: PlanHeading[] = [
+      { renderIndex: 0, level: 1, text: "Intro" },
+      { renderIndex: 1, level: 2, text: "First section" },
+      { renderIndex: 2, level: 2, text: "Second section" },
+      { renderIndex: 3, level: 3, text: "Nested" },
+    ];
+
+    const view = render(<HarnessRenderer entries={entries} />);
+
+    const headings = Array.from(view.container.querySelectorAll<HTMLElement>("h1, h2, h3"));
+    expect(headings).toHaveLength(4);
+
+    const scrollCalls: Array<{ target: HTMLElement; options: ScrollIntoViewOptions }> = [];
+    for (const heading of headings) {
+      heading.scrollIntoView = ((options: ScrollIntoViewOptions) => {
+        scrollCalls.push({ target: heading, options });
+      }) as HTMLElement["scrollIntoView"];
+    }
+
+    fireEvent.click(view.getByRole("button", { name: "Second section" }));
+
+    expect(scrollCalls).toHaveLength(1);
+    expect(scrollCalls[0].target).toBe(headings[2]);
+    // Top alignment ensures the heading lands just below the scrollport edge.
+    expect(scrollCalls[0].options.block).toBe("start");
+  });
+
+  test("normalizes indentation so the shallowest level sits at the leftmost column", () => {
+    // All entries are h3/h4 — they should render flush-left even though level is 3+.
+    const view = render(
+      <HarnessRenderer
+        entries={[
+          { renderIndex: 0, level: 3, text: "Outer" },
+          { renderIndex: 1, level: 4, text: "Inner" },
+        ]}
+      />
+    );
+
+    const items = view.container.querySelectorAll<HTMLElement>(".plan-toc-item");
+    expect(items[0].dataset.level).toBe("1");
+    expect(items[1].dataset.level).toBe("2");
+  });
+});
diff --git a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
new file mode 100644
index 0000000000..90af23ac53
--- /dev/null
+++ b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
@@ -0,0 +1,100 @@
+import React from "react";
+import { cn } from "@/common/lib/utils";
+import { TooltipIfPresent } from "@/browser/components/Tooltip/Tooltip";
+import type { PlanHeading } from "./extractPlanHeadings";
+
+/**
+ * Sticky table of contents rendered alongside a plan in the chat transcript.
+ *
+ * Layout:
+ * - The outer `<aside>` is absolutely positioned to the right of the plan via
+ *   `left: 100%` (see `.plan-toc-aside` in globals.css). It is hidden by default
+ *   and only revealed by a container query when the chat transcript has enough
+ *   horizontal room beside the centered `max-w-4xl` plan.
+ * - The inner `<nav>` uses `position: sticky` so it floats with the user while
+ *   the plan is on screen, then naturally scrolls away once the plan exits the
+ *   viewport (sticky is constrained to the parent's vertical bounds).
+ *
+ * Heading navigation is index-based: each entry stores its position among ALL
+ * h1..h6 elements the plan renders, so clicking a TOC item does
+ * `container.querySelectorAll("h1,h2,h3,h4,h5,h6")[renderIndex].scrollIntoView()`.
+ * This avoids touching the shared markdown rehype pipeline just for plan TOC.
+ */
+export interface PlanTableOfContentsProps {
+  /** Heading entries extracted from the plan markdown, in document order. */
+  entries: PlanHeading[];
+  /**
+   * Ref to a DOM container whose subtree owns the rendered plan headings.
+   * Must be a stable ancestor of the markdown output for `scrollIntoView` to
+   * locate the right element.
+   */
+  contentRef: React.RefObject<HTMLElement | null>;
+  className?: string;
+}
+
+const HEADING_SELECTOR = "h1, h2, h3, h4, h5, h6";
+
+export const PlanTableOfContents: React.FC<PlanTableOfContentsProps> = (props) => {
+  // Hide deep nesting (h5/h6) — they add visual noise without aiding navigation
+  // in plan content. They still take a renderIndex so DOM lookup stays aligned.
+  const visibleEntries = props.entries.filter((entry) => entry.level <= 4);
+  if (visibleEntries.length < 2) {
+    // A TOC with 0 or 1 entries adds visual chrome without navigation value.
+    return null;
+  }
+
+  // Normalize indentation: anchor the smallest visible level at column 0 so a
+  // plan that starts at "##" doesn't look uniformly indented.
+  const minLevel = Math.min(...visibleEntries.map((entry) => entry.level));
+
+  const handleNavigate = (renderIndex: number) => {
+    const container = props.contentRef.current;
+    if (!container) return;
+    const headings = container.querySelectorAll<HTMLElement>(HEADING_SELECTOR);
+    const target = headings.item(renderIndex);
+    // `scrollIntoView` is not implemented by happy-dom in unit tests; the guard
+    // keeps tests from crashing while still exercising the lookup path.
+    if (target && typeof target.scrollIntoView === "function") {
+      target.scrollIntoView({ block: "start" });
+    }
+  };
+
+  return (
+    <aside
+      className={cn("plan-toc-aside", props.className)}
+      aria-label="Plan contents"
+      // The aside itself receives no pointer events; only the inner nav does.
+      // This keeps the aside from interfering with text selection in margins
+      // when the TOC happens to render above other transcript chrome.
+      data-testid="plan-toc"
+    >
+      <nav className="plan-toc">
+        <div className="plan-toc-heading">Contents</div>
+        <ul className="plan-toc-list">
+          {visibleEntries.map((entry) => (
+            <li
+              key={entry.renderIndex}
+              className="plan-toc-item"
+              data-level={entry.level - minLevel + 1}
+            >
+              {/*
+               * Wrap with TooltipIfPresent so users can see the full heading
+               * text when it's truncated by the toc's narrow column width
+               * (long titles get `text-overflow: ellipsis` via CSS).
+               */}
+              <TooltipIfPresent tooltip={entry.text} side="left" align="start">
+                <button
+                  type="button"
+                  className="plan-toc-link"
+                  onClick={() => handleNavigate(entry.renderIndex)}
+                >
+                  {entry.text}
+                </button>
+              </TooltipIfPresent>
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </aside>
+  );
+};
diff --git a/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx b/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx
index be85905d3d..ad3c604389 100644
--- a/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx
+++ b/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx
@@ -180,6 +180,105 @@ export const ProposePlanMobile: AppStory = {
   },
 };
 
+/**
+ * Wide-viewport story that exercises the sticky plan TOC.
+ *
+ * The TOC lives in an absolutely-positioned `<aside>` outside the centered
+ * `max-w-4xl` transcript column, and is gated by a container query on the
+ * transcript scrollport. At desktop (1280px) viewport the gate stays closed;
+ * the `wide` viewport (1600px) gives the scrollport enough room to reveal
+ * the TOC alongside the plan.
+ */
+export const ProposePlanWithTableOfContents: AppStory = {
+  render: () => (
+    <AppWithMocks
+      setup={() =>
+        setupSimpleChatStory({
+          workspaceId: "ws-plan-toc",
+          messages: [
+            createUserMessage("msg-1", "Plan a multi-section refactor with deep structure.", {
+              historySequence: 1,
+              timestamp: STABLE_TIMESTAMP - 300000,
+            }),
+            createAssistantMessage("msg-2", "Here is the plan with a navigable outline:", {
+              historySequence: 2,
+              timestamp: STABLE_TIMESTAMP - 290000,
+              toolCalls: [
+                createProposePlanTool(
+                  "call-plan-toc",
+                  `# Authentication Module Refactor
+
+## Overview
+
+Refactor the auth system to improve security, maintainability, and observability.
+
+## Tasks
+
+### Extract JWT utilities
+
+Move token generation and validation to a dedicated module.
+
+### Add refresh token support
+
+Implement secure refresh token rotation.
+
+### Improve password hashing
+
+Upgrade to Argon2id with proper salt rounds.
+
+### Add rate limiting
+
+Implement per-IP and per-user rate limits.
+
+## Implementation Order
+
+\`\`\`mermaid
+graph TD
+    A[Extract JWT utils] --> B[Add refresh tokens]
+    B --> C[Improve hashing]
+    C --> D[Add rate limiting]
+\`\`\`
+
+## Rollout
+
+### Staging soak
+
+Two-week staging soak with synthetic traffic.
+
+### Production cutover
+
+Blue/green cutover with automatic rollback on auth-error spikes.
+
+## Success Criteria
+
+- All existing tests pass
+- New tests for refresh token flow
+- Security audit passes
+- Performance benchmarks maintained`
+                ),
+              ],
+            }),
+          ],
+        })
+      }
+    />
+  ),
+  parameters: {
+    viewport: { defaultViewport: "wide" },
+    docs: {
+      description: {
+        story:
+          "Wide-viewport rendering of a multi-section plan. The sticky " +
+          '"Contents" navigation appears in the right gutter beside the plan ' +
+          "card, anchored to the plan's vertical bounds via `position: sticky` " +
+          "inside an absolutely-positioned `<aside>`. " +
+          "Visibility is purely CSS-driven (container query + visibility class) " +
+          "so toggling the plan tool expanded/collapsed produces no layout jank.",
+      },
+    },
+  },
+};
+
 /**
  * Story showing a propose_plan with a code block containing long horizontal content.
  * Tests that code blocks wrap correctly instead of overflowing the container.
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
new file mode 100644
index 0000000000..390fa3f29f
--- /dev/null
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -0,0 +1,114 @@
+import { describe, expect, test } from "bun:test";
+import { extractPlanHeadings } from "./extractPlanHeadings";
+
+describe("extractPlanHeadings", () => {
+  test("returns empty array for empty input", () => {
+    expect(extractPlanHeadings("")).toEqual([]);
+  });
+
+  test("extracts ATX headings with correct level + text", () => {
+    const md = `# Title\n\nintro\n\n## Section A\n\nbody\n\n### Subsection\n\nmore`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Title" },
+      { renderIndex: 1, level: 2, text: "Section A" },
+      { renderIndex: 2, level: 3, text: "Subsection" },
+    ]);
+  });
+
+  test("accepts trailing closing # markers on ATX headings", () => {
+    const md = `# Title #\n## With trailing ##`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Title" },
+      { renderIndex: 1, level: 2, text: "With trailing" },
+    ]);
+  });
+
+  test("strips inline formatting in heading text", () => {
+    const md = `# **Bold** and _italic_\n## With \`code\` inline\n### [Linked](https://example.com) heading\n#### ~~strike~~ through`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Bold and italic" },
+      { renderIndex: 1, level: 2, text: "With code inline" },
+      { renderIndex: 2, level: 3, text: "Linked heading" },
+      { renderIndex: 3, level: 4, text: "strike through" },
+    ]);
+  });
+
+  test("ignores hashtags without space after the markers", () => {
+    const md = `#nothashtag\n# Real heading`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 1, text: "Real heading" }]);
+  });
+
+  test("skips ATX-looking lines inside fenced code blocks", () => {
+    const md = `# Real heading\n\n\`\`\`markdown\n# Not a heading\n## Also not\n\`\`\`\n\n## After code`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Real heading" },
+      { renderIndex: 1, level: 2, text: "After code" },
+    ]);
+  });
+
+  test("handles tilde-fenced code blocks too", () => {
+    const md = `# Outer\n\n~~~\n# Not a heading\n~~~\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Outer" },
+      { renderIndex: 1, level: 2, text: "After" },
+    ]);
+  });
+
+  test("does not treat tilde fence as closing a backtick fence", () => {
+    // The tilde line is content inside the backtick fence, not a closer.
+    const md = `\`\`\`\n# Hidden\n~~~\n# Still hidden\n\`\`\`\n\n# Visible`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 1, text: "Visible" }]);
+  });
+
+  test("recognizes setext h1 and h2 underlines", () => {
+    const md = `Title One\n=========\n\nbody\n\nTitle Two\n---------\n\nmore`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Title One" },
+      { renderIndex: 1, level: 2, text: "Title Two" },
+    ]);
+  });
+
+  test("does not confuse thematic breaks with setext underlines", () => {
+    const md = `Some intro paragraph.\n\n---\n\n# Heading`;
+    // The `---` here is preceded by a blank line, so it's a thematic break, not
+    // a setext underline. The TOC should only contain the ATX heading.
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 1, text: "Heading" }]);
+  });
+
+  test("counts raw HTML headings so renderIndex stays aligned", () => {
+    const md = `# Markdown one\n\n<h2>Inline HTML two</h2>\n\n### Markdown three`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Markdown one" },
+      { renderIndex: 1, level: 2, text: "Inline HTML two" },
+      { renderIndex: 2, level: 3, text: "Markdown three" },
+    ]);
+  });
+
+  test("preserves stable render indices across mixed content", () => {
+    const md = [
+      "# A",
+      "",
+      "para",
+      "",
+      "## B",
+      "",
+      "```",
+      "# inside-fence",
+      "```",
+      "",
+      "### C",
+      "",
+      "<h4>D</h4>",
+      "",
+      "##### E",
+    ].join("\n");
+
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "A" },
+      { renderIndex: 1, level: 2, text: "B" },
+      { renderIndex: 2, level: 3, text: "C" },
+      { renderIndex: 3, level: 4, text: "D" },
+      { renderIndex: 4, level: 5, text: "E" },
+    ]);
+  });
+});
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
new file mode 100644
index 0000000000..63c2b82970
--- /dev/null
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -0,0 +1,141 @@
+/**
+ * A heading entry extracted from a plan's markdown source.
+ *
+ * `renderIndex` is the position of this heading among ALL h1..h6 elements
+ * Streamdown will render for the same content. We use it to look up the matching
+ * DOM node via `container.querySelectorAll("h1,h2,h3,h4,h5,h6")[renderIndex]`.
+ * Keeping the index aligned to the rendered DOM (rather than slug IDs) avoids
+ * mutating the shared markdown rehype pipeline just for plan TOC scrolling.
+ */
+export interface PlanHeading {
+  renderIndex: number;
+  /** 1-6, matching the rendered hN tag. */
+  level: number;
+  /** Plain text (markdown formatting stripped) shown in the TOC. */
+  text: string;
+}
+
+/**
+ * Extract heading entries from a plan's markdown source.
+ *
+ * Supports ATX headings (`# Heading`, with optional trailing `#` markers), setext
+ * headings (a text line followed by `===` or `---`), and raw HTML headings on
+ * their own line (`<h2>...</h2>`). Skips lines inside fenced code blocks
+ * (``` or ~~~) so example markdown inside code samples never shows up in the TOC.
+ *
+ * The output indices line up with what Streamdown / remark-gfm will render so
+ * `renderIndex` can be used to locate the matching DOM element by order.
+ */
+export function extractPlanHeadings(markdown: string): PlanHeading[] {
+  if (!markdown) {
+    return [];
+  }
+
+  const lines = markdown.split("\n");
+  const headings: PlanHeading[] = [];
+
+  let inFence = false;
+  let fenceChar: "`" | "~" | null = null;
+  let fenceLength = 0;
+  let renderIndex = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Track fenced code blocks. The closing fence must use the same char and
+    // be at least as long as the opening fence (CommonMark rule).
+    const fenceMatch = /^(`{3,}|~{3,})/.exec(trimmed);
+    if (fenceMatch) {
+      const marker = fenceMatch[1];
+      const ch = marker[0] as "`" | "~";
+      const len = marker.length;
+      if (!inFence) {
+        inFence = true;
+        fenceChar = ch;
+        fenceLength = len;
+      } else if (ch === fenceChar && len >= fenceLength && /^[`~]+\s*$/.test(trimmed)) {
+        inFence = false;
+        fenceChar = null;
+        fenceLength = 0;
+      }
+      continue;
+    }
+
+    if (inFence) {
+      continue;
+    }
+
+    // ATX heading: leading 1-6 `#`s followed by whitespace and the heading text.
+    const atxMatch = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+    if (atxMatch) {
+      const level = atxMatch[1].length;
+      const text = stripMarkdownFormatting(atxMatch[2]);
+      if (text) {
+        headings.push({ renderIndex, level, text });
+        renderIndex += 1;
+      }
+      continue;
+    }
+
+    // Setext heading: text line followed by === (h1) or --- (h2). Skip blank
+    // text lines so we don't mistake a thematic break for a setext underline.
+    if (i + 1 < lines.length && trimmed.length > 0 && !/^[#>\-*+`~]/.test(trimmed)) {
+      const nextTrimmed = lines[i + 1].trim();
+      if (/^=+$/.test(nextTrimmed)) {
+        const text = stripMarkdownFormatting(trimmed);
+        if (text) {
+          headings.push({ renderIndex, level: 1, text });
+          renderIndex += 1;
+          i += 1; // consume the underline
+          continue;
+        }
+      }
+      if (/^-{2,}$/.test(nextTrimmed)) {
+        const text = stripMarkdownFormatting(trimmed);
+        if (text) {
+          headings.push({ renderIndex, level: 2, text });
+          renderIndex += 1;
+          i += 1; // consume the underline
+          continue;
+        }
+      }
+    }
+
+    // Raw HTML heading on its own line (`<h2>Hello</h2>`). Streamdown emits these
+    // through rehype-raw, so we count them too to keep `renderIndex` aligned.
+    const htmlMatch = /^<h([1-6])\b[^>]*>(.*?)<\/h\1>\s*$/i.exec(trimmed);
+    if (htmlMatch) {
+      const level = parseInt(htmlMatch[1], 10);
+      const text = stripMarkdownFormatting(htmlMatch[2].replace(/<[^>]+>/g, ""));
+      if (text) {
+        headings.push({ renderIndex, level, text });
+        renderIndex += 1;
+      }
+      continue;
+    }
+  }
+
+  return headings;
+}
+
+/**
+ * Lightweight inline-formatting stripper used only for TOC display text. Not a
+ * full markdown parser — we trade exhaustive correctness for predictable output
+ * on the small subset of inline syntax that shows up in heading lines.
+ */
+function stripMarkdownFormatting(text: string): string {
+  return text
+    .replace(/\\([\\`*_{}[\]()#+\-.!|~])/g, "$1") // unescape \*  \[ etc.
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1") // ![alt](src)
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") // [label](href)
+    .replace(/`([^`]+)`/g, "$1") // `code`
+    .replace(/\*\*([^*]+)\*\*/g, "$1") // **bold**
+    .replace(/__([^_]+)__/g, "$1") // __bold__
+    .replace(/\*([^*]+)\*/g, "$1") // *italic*
+    .replace(/(?<!\w)_([^_]+)_(?!\w)/g, "$1") // _italic_ (avoid mid-word matches)
+    .replace(/~~([^~]+)~~/g, "$1") // ~~strike~~
+    .replace(/<[^>]+>/g, "") // stray inline HTML tags
+    .replace(/\s+/g, " ")
+    .trim();
+}
diff --git a/src/browser/features/Tools/ProposePlanToolCall.test.tsx b/src/browser/features/Tools/ProposePlanToolCall.test.tsx
index 7d9d38b8d5..c1b1a3e160 100644
--- a/src/browser/features/Tools/ProposePlanToolCall.test.tsx
+++ b/src/browser/features/Tools/ProposePlanToolCall.test.tsx
@@ -569,4 +569,59 @@ describe("ProposePlanToolCall", () => {
     expect(summaryMessage.parts?.[0]?.text).toContain("*Plan file preserved at:*");
     expect(summaryMessage.parts?.[0]?.text).toContain(PLAN_PATH);
   });
+
+  test("renders a plan table of contents derived from the plan's markdown headings", () => {
+    // Note: we deliberately don't assert against rendered <h1>/<h2> elements here
+    // because some sibling test files mock MarkdownCore at file scope (file-scope
+    // module mocks persist across files in this runner). The TOC's source of truth
+    // is the markdown TEXT, not the rendered DOM, so this assertion stays robust.
+    const planContent = [
+      "# Title",
+      "",
+      "intro paragraph",
+      "",
+      "## Section A",
+      "",
+      "body",
+      "",
+      "## Section B",
+      "",
+      "more",
+    ].join("\n");
+
+    const view = renderCompletedPlan({
+      result: { success: true, planPath: PLAN_PATH, planContent },
+    });
+
+    const toc = view.getByTestId("plan-toc");
+    expect(toc.textContent).toContain("Title");
+    expect(toc.textContent).toContain("Section A");
+    expect(toc.textContent).toContain("Section B");
+
+    // Each entry is a real <button>, so the user can drive navigation with the
+    // keyboard. The dedicated PlanTableOfContents.test.tsx verifies the
+    // scrollIntoView wiring directly.
+    expect(view.getByRole("button", { name: "Section A" })).toBeDefined();
+    expect(view.getByRole("button", { name: "Section B" })).toBeDefined();
+  });
+
+  test("does not render a plan TOC for plans with fewer than two visible headings", () => {
+    // PLAN_CONTENT only has one heading ("# My Plan"), so the TOC should not appear.
+    const view = renderCompletedPlan();
+    expect(view.queryByTestId("plan-toc")).toBeNull();
+  });
+
+  test("does not render a plan TOC while annotate mode is active", () => {
+    const planContent = "# A\n\nbody\n\n## B\n\nmore";
+    const view = renderCompletedPlan({
+      result: { success: true, planPath: PLAN_PATH, planContent },
+    });
+
+    // Sanity: TOC is visible before annotate mode.
+    expect(view.queryByTestId("plan-toc")).not.toBeNull();
+
+    fireEvent.click(view.getByRole("button", { name: "Annotate" }));
+
+    expect(view.queryByTestId("plan-toc")).toBeNull();
+  });
 });
diff --git a/src/browser/features/Tools/ProposePlanToolCall.tsx b/src/browser/features/Tools/ProposePlanToolCall.tsx
index e4c1765e69..dbea935b58 100644
--- a/src/browser/features/Tools/ProposePlanToolCall.tsx
+++ b/src/browser/features/Tools/ProposePlanToolCall.tsx
@@ -17,6 +17,8 @@ import {
 import { useToolExpansion, getStatusDisplay, type ToolStatus } from "./Shared/toolUtils";
 import { MarkdownRenderer } from "../Messages/MarkdownRenderer";
 import { PlanAnnotationView } from "./PlanAnnotationView";
+import { extractPlanHeadings } from "./ProposePlan/extractPlanHeadings";
+import { PlanTableOfContents } from "./ProposePlan/PlanTableOfContents";
 import { Button } from "@/browser/components/Button/Button";
 import { Tooltip, TooltipTrigger, TooltipContent } from "@/browser/components/Tooltip/Tooltip";
 import { IconActionButton, type ButtonConfig } from "../Messages/MessageWindow";
@@ -178,6 +180,10 @@ export const ProposePlanToolCall: React.FC<ProposePlanToolCallProps> = (props) =
   const isImplementingRef = useRef(false);
   const isContinuingInAutoRef = useRef(false);
   const isMountedRef = useRef(true);
+  // Anchors the plan body so PlanTableOfContents can `querySelectorAll("h1,h2,h3...")`
+  // and `scrollIntoView` the matching rendered heading. Pointing at `plan-surface`
+  // also implicitly scopes lookups away from neighbouring tool calls/transcripts.
+  const planContentRef = useRef<HTMLDivElement>(null);
   const { api } = useAPI();
   const { agentId: currentAgentId } = useAgent();
   const isAutoMode = currentAgentId === "auto";
@@ -796,9 +802,16 @@ export const ProposePlanToolCall: React.FC<ProposePlanToolCallProps> = (props) =
     <div className={planBodyClassName}>{planContentBody}</div>
   );
 
+  // Show the table of contents only for normal markdown content. Annotate mode,
+  // raw text, and error states either have no headings or use a custom renderer,
+  // so a TOC there would be either empty or misleading.
+  const showToc = !errorMessage && !annotateMode && !showRaw && hasPlanContentInChat;
+  const tocEntries = showToc ? extractPlanHeadings(planContent) : [];
+
   // Shared plan UI content (used in both tool call and ephemeral preview modes)
   const planUI = (
     <div
+      ref={planContentRef}
       className={cn(
         "plan-surface rounded-md p-3 shadow-md",
         annotateMode && "ring-accent/30 ring-1"
@@ -902,11 +915,23 @@ export const ProposePlanToolCall: React.FC<ProposePlanToolCallProps> = (props) =
     </div>
   );
 
+  // Layout container that positions the sticky TOC alongside the plan. The
+  // `plan-toc-layout` class establishes `position: relative` so the TOC's
+  // absolutely-positioned aside (`left: 100%`) can break out of the centered
+  // `max-w-4xl` transcript column into the unused right gutter. CSS container
+  // queries on the transcript scrollport keep it hidden until there's room.
+  const planLayout = (
+    <div className="plan-toc-layout">
+      {planUI}
+      {showToc && <PlanTableOfContents entries={tocEntries} contentRef={planContentRef} />}
+    </div>
+  );
+
   // Ephemeral preview mode: simple wrapper without tool container
   if (isEphemeralPreview) {
     return (
       <>
-        <div className={cn("px-4 py-2", className)}>{planUI}</div>
+        <div className={cn("px-4 py-2", className)}>{planLayout}</div>
         <PopoverError error={editorError.error} prefix="Failed to open editor" />
       </>
     );
@@ -922,7 +947,7 @@ export const ProposePlanToolCall: React.FC<ProposePlanToolCallProps> = (props) =
           <StatusIndicator status={status}>{statusDisplay}</StatusIndicator>
         </ToolHeader>
 
-        {expanded && <ToolDetails text={errorMessage ?? planContent}>{planUI}</ToolDetails>}
+        {expanded && <ToolDetails text={errorMessage ?? planContent}>{planLayout}</ToolDetails>}
 
         {modal}
       </ToolContainer>
diff --git a/src/browser/styles/globals.css b/src/browser/styles/globals.css
index e26e21db98..a8f8ae945d 100644
--- a/src/browser/styles/globals.css
+++ b/src/browser/styles/globals.css
@@ -1519,6 +1519,174 @@ code {
   border-radius: 0 4px 4px 0;
 }
 
+/* -----------------------------------------------------------------------------
+ * Plan Table of Contents
+ *
+ * `.plan-toc-layout` wraps the plan card so an absolutely-positioned `aside`
+ * (`.plan-toc-aside`) can break out to the right of the centered `max-w-4xl`
+ * transcript column. The aside is `display: none` by default; a container
+ * query on the `transcript` scrollport in ChatPane reveals it only when:
+ *
+ *   1. the chat is in centered (not full-width) mode — opted in by the
+ *      `.plan-toc-aware` class on the transcript's inner column, and
+ *   2. the transcript scrollport is wide enough to hold the centered plan
+ *      plus a TOC gutter on both sides (we need symmetric margins so the
+ *      centered plan doesn't visually drift to the left).
+ *
+ * Using a container query (rather than viewport `min-width`) is what makes
+ * the TOC behave correctly when sidebars open/close without the viewport
+ * changing — and using CSS-only visibility (no JS resize listener) is what
+ * prevents flashing/tearing when the plan toggles expanded.
+ * --------------------------------------------------------------------------- */
+
+.plan-toc-layout {
+  position: relative;
+}
+
+.plan-toc-aside {
+  display: none;
+  /* The toc lives outside the plan card's bounding box, so we anchor it to
+     the plan's right edge and let it occupy a fixed-width strip in the
+     transcript's right gutter.
+     Width + padding-left are tuned so the visibility threshold below matches:
+       max-w-4xl (56rem) + 2 × (width 10rem + gap 1.25rem) ≈ 78.5rem
+     Keeping it compact lets the toc show on common desktop widths (1440px+
+     viewports with standard mux sidebars) instead of only on ultra-wide
+     monitors. */
+  position: absolute;
+  inset: 0 auto 0 100%;
+  width: 10rem;
+  padding-left: 1.25rem;
+  /* Margin clicks should fall through to the underlying transcript chrome;
+     only the inner <nav> is interactive. */
+  pointer-events: none;
+}
+
+.plan-toc-aside > * {
+  pointer-events: auto;
+}
+
+.plan-toc {
+  /* Sticky inside the aside keeps the toc anchored while the plan is on
+     screen. Once the user scrolls past the plan, the sticky bottoms out at
+     the aside's lower edge (which matches the plan's lower edge), so the
+     toc naturally scrolls away with the plan instead of trailing forever. */
+  position: sticky;
+  top: 1rem;
+  /* Bound the toc to the visible viewport so even very tall plans never push
+     it off-screen, and let it scroll internally for huge plans. */
+  max-height: calc(100dvh - 2rem);
+  overflow-y: auto;
+  font-family: var(--font-primary);
+  font-size: 11px;
+  line-height: 1.4;
+  color: var(--color-muted-foreground);
+  border-left: 1px solid var(--surface-plan-divider);
+  padding: 4px 0 4px 12px;
+}
+
+.plan-toc-heading {
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-size: 10px;
+  font-weight: 600;
+  color: color-mix(in srgb, var(--color-plan-mode) 70%, var(--color-foreground) 30%);
+  margin-bottom: 6px;
+}
+
+.plan-toc-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.plan-toc-item {
+  /* Per-level indentation. The component normalizes `data-level` so the
+     shallowest visible heading sits at 1, regardless of whether the plan
+     starts with h1 or h2. */
+  --plan-toc-indent: 0;
+}
+
+.plan-toc-item[data-level="1"] {
+  --plan-toc-indent: 0;
+}
+.plan-toc-item[data-level="2"] {
+  --plan-toc-indent: 10px;
+}
+.plan-toc-item[data-level="3"] {
+  --plan-toc-indent: 20px;
+}
+.plan-toc-item[data-level="4"] {
+  --plan-toc-indent: 30px;
+}
+
+.plan-toc-link {
+  /* Render as a flush text link rather than a chunky button. */
+  appearance: none;
+  background: transparent;
+  border: 0;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+  display: block;
+  width: 100%;
+  padding: 2px 4px 2px calc(4px + var(--plan-toc-indent));
+  border-radius: 3px;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  transition:
+    color 120ms ease,
+    background-color 120ms ease;
+}
+
+.plan-toc-item[data-level="1"] .plan-toc-link {
+  font-weight: 600;
+  color: color-mix(in srgb, var(--color-foreground) 80%, var(--color-plan-mode) 20%);
+}
+
+.plan-toc-link:hover {
+  color: var(--color-foreground);
+  background: color-mix(in srgb, var(--color-plan-mode), transparent 90%);
+}
+
+.plan-toc-link:focus-visible {
+  outline: 2px solid color-mix(in srgb, var(--color-plan-mode), transparent 40%);
+  outline-offset: 1px;
+}
+
+/* Give plan headings breathing room so scrollIntoView({block:"start"}) lands
+   them just below the transcript's top padding rather than flush against the
+   scrollport edge. Applies to the markdown render inside `.plan-content`. */
+.plan-content h1,
+.plan-content h2,
+.plan-content h3,
+.plan-content h4,
+.plan-content h5,
+.plan-content h6 {
+  scroll-margin-top: 1rem;
+}
+
+/*
+ * Visibility gate. The transcript container is queried at its CONTENT box
+ * inline-size (padding excluded). We need:
+ *   max-w-4xl (56rem) + 2 × (toc width 10rem + gap 1.25rem) = 78.5rem
+ * of content-box width before there's enough room for the toc gutter on both
+ * sides while keeping the plan visually centered. This works out to roughly
+ * a 1440px viewport with standard mux sidebars open; narrower laptops keep
+ * the toc hidden so the plan card never overlaps the right gutter or gets
+ * clipped by the transcript's overflow-x-hidden.
+ */
+@container transcript (min-width: 78.5rem) {
+  .plan-toc-aware .plan-toc-aside {
+    display: block;
+  }
+}
+
 [title]:hover::before {
   content: "";
   position: absolute;

From 9b70cd43d282a18f2636ea0db8194e22ac8be590 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 19:55:17 -0500
Subject: [PATCH 02/32] Use plan title as TOC heading; tighten indents

- Promote the plan title to be the TOC's heading instead of a static
  "CONTENTS" label plus a separate h1 list entry. Saves vertical space and
  tightens the visual hierarchy: the title sits at column 0, h2 entries
  align flush with it, and h3+ get a small indent step per level.
- Filter h1 entries out of the navigation list since they're represented by
  the heading. h1 still consumes a renderIndex so DOM lookups stay aligned.
- When the plan markdown contains an h1, the TOC heading becomes a button
  that scrolls to that h1 (the natural "top of plan" target). With no h1,
  the heading is a static label.
- Reduce indent steps from 10/20/30px to 6/12/18px to keep the TOC usable
  in the narrow left-gutter column.
- Drop the uppercase/letter-spaced eyebrow styling on the heading since
  real plan titles are sentences, not labels.
---
 .../ProposePlan/PlanTableOfContents.test.tsx  |  69 ++++++++++--
 .../Tools/ProposePlan/PlanTableOfContents.tsx |  53 +++++++--
 .../Tools/ProposePlanToolCall.test.tsx        |   4 +-
 .../features/Tools/ProposePlanToolCall.tsx    |   4 +-
 src/browser/styles/globals.css                | 103 ++++++++++++------
 5 files changed, 184 insertions(+), 49 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.test.tsx b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.test.tsx
index 49fc4e9256..b98963b636 100644
--- a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.test.tsx
+++ b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.test.tsx
@@ -13,11 +13,11 @@ import type { PlanHeading } from "./extractPlanHeadings";
  * mock MarkdownCore at file scope; those mocks make Streamdown render plain text
  * without heading tags, which would break index-based DOM lookups.
  */
-function HarnessRenderer({ entries }: { entries: PlanHeading[] }) {
+function HarnessRenderer({ entries, title }: { entries: PlanHeading[]; title?: string }) {
   const ref = useRef<HTMLDivElement>(null);
   return (
     <div>
-      <PlanTableOfContents entries={entries} contentRef={ref} />
+      <PlanTableOfContents entries={entries} contentRef={ref} title={title} />
       <div ref={ref} data-testid="plan-body">
         <h1>Intro</h1>
         <p>...</p>
@@ -44,7 +44,9 @@ describe("PlanTableOfContents", () => {
     cleanupDom = null;
   });
 
-  test("returns null when given fewer than two visible headings", () => {
+  test("returns null when there are fewer than two visible (h2-h4) entries", () => {
+    // A lone h1 produces zero list entries (h1 is reserved for the heading)
+    // and would leave a TOC with only a title — useless for navigation.
     const view = render(<HarnessRenderer entries={[{ renderIndex: 0, level: 1, text: "Only" }]} />);
     expect(view.queryByTestId("plan-toc")).toBeNull();
   });
@@ -62,6 +64,56 @@ describe("PlanTableOfContents", () => {
     expect(view.queryByTestId("plan-toc")).toBeNull();
   });
 
+  test("filters h1 entries out of the navigation list (they live in the heading)", () => {
+    const entries: PlanHeading[] = [
+      { renderIndex: 0, level: 1, text: "Intro" },
+      { renderIndex: 1, level: 2, text: "First section" },
+      { renderIndex: 2, level: 2, text: "Second section" },
+    ];
+
+    const view = render(<HarnessRenderer entries={entries} title="My Plan" />);
+
+    // h2 entries remain as navigable buttons; h1 does not.
+    expect(view.getByRole("button", { name: "First section" })).toBeDefined();
+    expect(view.getByRole("button", { name: "Second section" })).toBeDefined();
+    expect(view.queryByRole("button", { name: "Intro" })).toBeNull();
+  });
+
+  test("renders the supplied title as the TOC heading", () => {
+    const entries: PlanHeading[] = [
+      { renderIndex: 0, level: 2, text: "A" },
+      { renderIndex: 1, level: 2, text: "B" },
+    ];
+
+    const view = render(<HarnessRenderer entries={entries} title="My Plan Title" />);
+    const toc = view.getByTestId("plan-toc");
+    expect(toc.textContent).toContain("My Plan Title");
+    // Without any h1 in entries, the heading should NOT be a clickable button.
+    expect(view.queryByRole("button", { name: "My Plan Title" })).toBeNull();
+  });
+
+  test("clicking the TOC heading scrolls to the plan's h1 when one exists", () => {
+    const entries: PlanHeading[] = [
+      { renderIndex: 0, level: 1, text: "Plan Title From Markdown" },
+      { renderIndex: 1, level: 2, text: "First section" },
+      { renderIndex: 2, level: 2, text: "Second section" },
+    ];
+
+    const view = render(<HarnessRenderer entries={entries} title="Plan Title From Markdown" />);
+
+    const headings = Array.from(view.container.querySelectorAll<HTMLElement>("h1, h2, h3"));
+    const scrollCalls: Array<{ target: HTMLElement; options: ScrollIntoViewOptions }> = [];
+    for (const heading of headings) {
+      heading.scrollIntoView = ((options: ScrollIntoViewOptions) => {
+        scrollCalls.push({ target: heading, options });
+      }) as HTMLElement["scrollIntoView"];
+    }
+
+    fireEvent.click(view.getByRole("button", { name: "Plan Title From Markdown" }));
+    expect(scrollCalls).toHaveLength(1);
+    expect(scrollCalls[0].target).toBe(headings[0]); // the h1
+  });
+
   test("scrolls the correct rendered heading into view when an entry is clicked", () => {
     const entries: PlanHeading[] = [
       { renderIndex: 0, level: 1, text: "Intro" },
@@ -90,18 +142,21 @@ describe("PlanTableOfContents", () => {
     expect(scrollCalls[0].options.block).toBe("start");
   });
 
-  test("normalizes indentation so the shallowest level sits at the leftmost column", () => {
-    // All entries are h3/h4 — they should render flush-left even though level is 3+.
+  test("normalizes indentation so the shallowest visible level sits at column 0", () => {
+    // With h1 reserved for the heading, h2 (the shallowest visible) should
+    // render at data-level=1, and h3 at data-level=2.
     const view = render(
       <HarnessRenderer
         entries={[
-          { renderIndex: 0, level: 3, text: "Outer" },
-          { renderIndex: 1, level: 4, text: "Inner" },
+          { renderIndex: 0, level: 1, text: "Title" },
+          { renderIndex: 1, level: 2, text: "Section" },
+          { renderIndex: 2, level: 3, text: "Subsection" },
         ]}
       />
     );
 
     const items = view.container.querySelectorAll<HTMLElement>(".plan-toc-item");
+    expect(items).toHaveLength(2);
     expect(items[0].dataset.level).toBe("1");
     expect(items[1].dataset.level).toBe("2");
   });
diff --git a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
index 90af23ac53..49a8d2b7ef 100644
--- a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
+++ b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
@@ -29,22 +29,36 @@ export interface PlanTableOfContentsProps {
    * locate the right element.
    */
   contentRef: React.RefObject<HTMLElement | null>;
+  /**
+   * Heading rendered at the top of the TOC. Defaults to "Contents".
+   *
+   * The plan title is the natural label for a plan TOC, so we let the host
+   * surface it here — that conserves vertical space (no separate "CONTENTS"
+   * label *and* an h1 list entry) and tightens the visual hierarchy: the
+   * title sits at column 0, h2 entries align with it, and h3+ are minimally
+   * indented under their parent h2.
+   */
+  title?: string;
   className?: string;
 }
 
 const HEADING_SELECTOR = "h1, h2, h3, h4, h5, h6";
+const DEFAULT_HEADING = "Contents";
 
 export const PlanTableOfContents: React.FC<PlanTableOfContentsProps> = (props) => {
-  // Hide deep nesting (h5/h6) — they add visual noise without aiding navigation
-  // in plan content. They still take a renderIndex so DOM lookup stays aligned.
-  const visibleEntries = props.entries.filter((entry) => entry.level <= 4);
+  // h1 is reserved for the TOC's heading (the plan title), so it never appears
+  // as a list entry — but it still consumes a renderIndex because the rendered
+  // DOM still contains an <h1>. h5/h6 are also hidden as visual noise.
+  const visibleEntries = props.entries.filter((entry) => entry.level >= 2 && entry.level <= 4);
   if (visibleEntries.length < 2) {
     // A TOC with 0 or 1 entries adds visual chrome without navigation value.
+    // (Note: this check intentionally excludes the title, since the title is
+    // a single label, not a navigable destination on its own.)
     return null;
   }
 
-  // Normalize indentation: anchor the smallest visible level at column 0 so a
-  // plan that starts at "##" doesn't look uniformly indented.
+  // Normalize indentation: anchor the shallowest visible level at column 0 so
+  // a plan that starts at "###" doesn't look uniformly indented.
   const minLevel = Math.min(...visibleEntries.map((entry) => entry.level));
 
   const handleNavigate = (renderIndex: number) => {
@@ -59,6 +73,16 @@ export const PlanTableOfContents: React.FC<PlanTableOfContentsProps> = (props) =
     }
   };
 
+  // Use the supplied title when non-blank; fall back to "Contents" otherwise.
+  // Treat "  " as blank — a whitespace-only title would render as an empty
+  // heading line and look broken.
+  const trimmedTitle = props.title?.trim();
+  const headingText = trimmedTitle && trimmedTitle.length > 0 ? trimmedTitle : DEFAULT_HEADING;
+  // If the plan's source markdown begins with an h1, clicking the TOC heading
+  // jumps to that h1 (the natural "top of plan" target). Otherwise the heading
+  // is a static label — there's nothing meaningful to scroll to.
+  const titleHeadingEntry = props.entries.find((entry) => entry.level === 1);
+
   return (
     <aside
       className={cn("plan-toc-aside", props.className)}
@@ -69,7 +93,19 @@ export const PlanTableOfContents: React.FC<PlanTableOfContentsProps> = (props) =
       data-testid="plan-toc"
     >
       <nav className="plan-toc">
-        <div className="plan-toc-heading">Contents</div>
+        {titleHeadingEntry ? (
+          <TooltipIfPresent tooltip={headingText} side="right" align="start">
+            <button
+              type="button"
+              className="plan-toc-heading plan-toc-heading-link"
+              onClick={() => handleNavigate(titleHeadingEntry.renderIndex)}
+            >
+              {headingText}
+            </button>
+          </TooltipIfPresent>
+        ) : (
+          <div className="plan-toc-heading">{headingText}</div>
+        )}
         <ul className="plan-toc-list">
           {visibleEntries.map((entry) => (
             <li
@@ -81,8 +117,11 @@ export const PlanTableOfContents: React.FC<PlanTableOfContentsProps> = (props) =
                * Wrap with TooltipIfPresent so users can see the full heading
                * text when it's truncated by the toc's narrow column width
                * (long titles get `text-overflow: ellipsis` via CSS).
+               *
+               * `side="right"` keeps the tooltip from drifting off the left
+               * edge of the transcript — the toc lives in the left gutter.
                */}
-              <TooltipIfPresent tooltip={entry.text} side="left" align="start">
+              <TooltipIfPresent tooltip={entry.text} side="right" align="start">
                 <button
                   type="button"
                   className="plan-toc-link"
diff --git a/src/browser/features/Tools/ProposePlanToolCall.test.tsx b/src/browser/features/Tools/ProposePlanToolCall.test.tsx
index c1b1a3e160..a7748e6288 100644
--- a/src/browser/features/Tools/ProposePlanToolCall.test.tsx
+++ b/src/browser/features/Tools/ProposePlanToolCall.test.tsx
@@ -612,7 +612,9 @@ describe("ProposePlanToolCall", () => {
   });
 
   test("does not render a plan TOC while annotate mode is active", () => {
-    const planContent = "# A\n\nbody\n\n## B\n\nmore";
+    // Need at least two h2+ entries; h1 is reserved for the TOC's heading
+    // (the plan title) and never shows up as a list item.
+    const planContent = "# A\n\nbody\n\n## B\n\nmore\n\n## C\n\nmore";
     const view = renderCompletedPlan({
       result: { success: true, planPath: PLAN_PATH, planContent },
     });
diff --git a/src/browser/features/Tools/ProposePlanToolCall.tsx b/src/browser/features/Tools/ProposePlanToolCall.tsx
index dbea935b58..8708ecb122 100644
--- a/src/browser/features/Tools/ProposePlanToolCall.tsx
+++ b/src/browser/features/Tools/ProposePlanToolCall.tsx
@@ -923,7 +923,9 @@ export const ProposePlanToolCall: React.FC<ProposePlanToolCallProps> = (props) =
   const planLayout = (
     <div className="plan-toc-layout">
       {planUI}
-      {showToc && <PlanTableOfContents entries={tocEntries} contentRef={planContentRef} />}
+      {showToc && (
+        <PlanTableOfContents entries={tocEntries} contentRef={planContentRef} title={planTitle} />
+      )}
     </div>
   );
 
diff --git a/src/browser/styles/globals.css b/src/browser/styles/globals.css
index a8f8ae945d..386e87c3ae 100644
--- a/src/browser/styles/globals.css
+++ b/src/browser/styles/globals.css
@@ -1523,15 +1523,17 @@ code {
  * Plan Table of Contents
  *
  * `.plan-toc-layout` wraps the plan card so an absolutely-positioned `aside`
- * (`.plan-toc-aside`) can break out to the right of the centered `max-w-4xl`
+ * (`.plan-toc-aside`) can break out to the LEFT of the centered `max-w-4xl`
  * transcript column. The aside is `display: none` by default; a container
  * query on the `transcript` scrollport in ChatPane reveals it only when:
  *
  *   1. the chat is in centered (not full-width) mode — opted in by the
  *      `.plan-toc-aware` class on the transcript's inner column, and
  *   2. the transcript scrollport is wide enough to hold the centered plan
- *      plus a TOC gutter on both sides (we need symmetric margins so the
- *      centered plan doesn't visually drift to the left).
+ *      plus a TOC gutter on both sides. The plan is centered via `mx-auto`,
+ *      so the TOC's left edge cannot extend past the scrollport without
+ *      being clipped by `overflow-x-hidden` — both gutters must be at least
+ *      `toc width + gap` wide.
  *
  * Using a container query (rather than viewport `min-width`) is what makes
  * the TOC behave correctly when sidebars open/close without the viewport
@@ -1545,18 +1547,16 @@ code {
 
 .plan-toc-aside {
   display: none;
-  /* The toc lives outside the plan card's bounding box, so we anchor it to
-     the plan's right edge and let it occupy a fixed-width strip in the
-     transcript's right gutter.
-     Width + padding-left are tuned so the visibility threshold below matches:
-       max-w-4xl (56rem) + 2 × (width 10rem + gap 1.25rem) ≈ 78.5rem
-     Keeping it compact lets the toc show on common desktop widths (1440px+
-     viewports with standard mux sidebars) instead of only on ultra-wide
-     monitors. */
+  /* Anchor the toc's right edge to the plan card's left edge so it extends
+     leftward into the transcript's left gutter.
+     Width + padding-right are tuned to keep the visibility threshold reachable
+     on common desktop widths (1440px+ with mux sidebars) rather than only on
+     ultra-wide monitors:
+       max-w-4xl (56rem) + 2 × (width 9rem + gap 1rem) = 76rem */
   position: absolute;
-  inset: 0 auto 0 100%;
-  width: 10rem;
-  padding-left: 1.25rem;
+  inset: 0 100% 0 auto;
+  width: 9rem;
+  padding-right: 1rem;
   /* Margin clicks should fall through to the underlying transcript chrome;
      only the inner <nav> is interactive. */
   pointer-events: none;
@@ -1581,17 +1581,51 @@ code {
   font-size: 11px;
   line-height: 1.4;
   color: var(--color-muted-foreground);
-  border-left: 1px solid var(--surface-plan-divider);
-  padding: 4px 0 4px 12px;
+  padding: 4px 0;
 }
 
 .plan-toc-heading {
-  text-transform: uppercase;
-  letter-spacing: 0.06em;
-  font-size: 10px;
+  /* The plan title sits at the top of the TOC, in place of a separate
+     "CONTENTS" label. We don't uppercase or letter-space it because real plan
+     titles ("Authentication Module Refactor", etc.) are sentences, not eyebrow
+     labels, and would look forced in all-caps. */
+  font-size: 12px;
   font-weight: 600;
   color: color-mix(in srgb, var(--color-plan-mode) 70%, var(--color-foreground) 30%);
-  margin-bottom: 6px;
+  margin: 0 0 6px 0;
+  padding: 2px 4px;
+  /* Ellipsis-truncate long titles so the TOC never grows horizontally; the
+     hover tooltip surfaces the full text. */
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  /* Match the .plan-toc-link reset for the clickable variant. */
+  text-align: left;
+}
+
+.plan-toc-heading-link {
+  appearance: none;
+  background: transparent;
+  border: 0;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  display: block;
+  width: 100%;
+  border-radius: 3px;
+  transition:
+    color 120ms ease,
+    background-color 120ms ease;
+}
+
+.plan-toc-heading-link:hover {
+  color: var(--color-foreground);
+  background: color-mix(in srgb, var(--color-plan-mode), transparent 90%);
+}
+
+.plan-toc-heading-link:focus-visible {
+  outline: 2px solid color-mix(in srgb, var(--color-plan-mode), transparent 40%);
+  outline-offset: 1px;
 }
 
 .plan-toc-list {
@@ -1605,8 +1639,11 @@ code {
 
 .plan-toc-item {
   /* Per-level indentation. The component normalizes `data-level` so the
-     shallowest visible heading sits at 1, regardless of whether the plan
-     starts with h1 or h2. */
+     shallowest visible heading sits at 1.
+     With the plan title acting as the TOC heading (h1), h2 entries align flush
+     with the title (data-level=1 → 0 indent) and deeper headings get a small
+     step per level. We deliberately keep steps tight (6px) so the TOC stays
+     useful in the narrow left-gutter column. */
   --plan-toc-indent: 0;
 }
 
@@ -1614,13 +1651,13 @@ code {
   --plan-toc-indent: 0;
 }
 .plan-toc-item[data-level="2"] {
-  --plan-toc-indent: 10px;
+  --plan-toc-indent: 6px;
 }
 .plan-toc-item[data-level="3"] {
-  --plan-toc-indent: 20px;
+  --plan-toc-indent: 12px;
 }
 .plan-toc-item[data-level="4"] {
-  --plan-toc-indent: 30px;
+  --plan-toc-indent: 18px;
 }
 
 .plan-toc-link {
@@ -1673,15 +1710,15 @@ code {
 
 /*
  * Visibility gate. The transcript container is queried at its CONTENT box
- * inline-size (padding excluded). We need:
- *   max-w-4xl (56rem) + 2 × (toc width 10rem + gap 1.25rem) = 78.5rem
- * of content-box width before there's enough room for the toc gutter on both
- * sides while keeping the plan visually centered. This works out to roughly
- * a 1440px viewport with standard mux sidebars open; narrower laptops keep
- * the toc hidden so the plan card never overlaps the right gutter or gets
- * clipped by the transcript's overflow-x-hidden.
+ * inline-size (padding excluded). The plan is centered via `mx-auto`, so the
+ * left gutter holding the TOC and the right gutter mirror each other:
+ *   max-w-4xl (56rem) + 2 × (toc width 9rem + gap 1rem) = 76rem
+ * of content-box width before there's enough room for the toc in the left
+ * gutter without the right side of the plan getting visually crowded. This
+ * works out to roughly a 1376px viewport with both mux sidebars open, so the
+ * TOC shows on common laptop+ widths; narrower configurations keep it hidden.
  */
-@container transcript (min-width: 78.5rem) {
+@container transcript (min-width: 76rem) {
   .plan-toc-aware .plan-toc-aside {
     display: block;
   }

From 42205bce7ca573ba4fbe43b380ef7ecbd3034197 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 20:07:11 -0500
Subject: [PATCH 03/32] Refine plan TOC layout

---
 .../Tools/ProposePlan/PlanTableOfContents.tsx |  23 +--
 .../ProposePlan/extractPlanHeadings.test.ts   |  17 +++
 .../Tools/ProposePlan/extractPlanHeadings.ts  |  20 ++-
 .../features/Tools/ProposePlanToolCall.tsx    |   9 +-
 src/browser/styles/globals.css                | 144 ++++++++++++------
 5 files changed, 141 insertions(+), 72 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
index 49a8d2b7ef..405562c103 100644
--- a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
+++ b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
@@ -7,13 +7,12 @@ import type { PlanHeading } from "./extractPlanHeadings";
  * Sticky table of contents rendered alongside a plan in the chat transcript.
  *
  * Layout:
- * - The outer `<aside>` is absolutely positioned to the right of the plan via
- *   `left: 100%` (see `.plan-toc-aside` in globals.css). It is hidden by default
- *   and only revealed by a container query when the chat transcript has enough
- *   horizontal room beside the centered `max-w-4xl` plan.
- * - The inner `<nav>` uses `position: sticky` so it floats with the user while
- *   the plan is on screen, then naturally scrolls away once the plan exits the
- *   viewport (sticky is constrained to the parent's vertical bounds).
+ * - At intermediate widths the left gutter shows only sideways hint text so
+ *   users can discover that widening the transcript reveals the TOC.
+ * - When the transcript container is wide enough, CSS reveals the same sticky
+ *   left-gutter nav (see `.plan-toc-aside` in globals.css). The sticky container
+ *   follows the user while the plan is on screen, then naturally scrolls away
+ *   once the plan exits the viewport.
  *
  * Heading navigation is index-based: each entry stores its position among ALL
  * h1..h6 elements the plan renders, so clicking a TOC item does
@@ -87,11 +86,15 @@ export const PlanTableOfContents: React.FC<PlanTableOfContentsProps> = (props) =
     <aside
       className={cn("plan-toc-aside", props.className)}
       aria-label="Plan contents"
-      // The aside itself receives no pointer events; only the inner nav does.
-      // This keeps the aside from interfering with text selection in margins
-      // when the TOC happens to render above other transcript chrome.
+      // At intermediate widths CSS shows only the sideways hint; at wide widths
+      // it hides the hint and reveals the sticky nav in the same left gutter.
+      // The aside itself stays pointer-events:none so margin clicks fall through
+      // to transcript chrome; only the inner nav becomes interactive.
       data-testid="plan-toc"
     >
+      <div className="plan-toc-compact-hint" aria-hidden="true">
+        Expand to see ToC
+      </div>
       <nav className="plan-toc">
         {titleHeadingEntry ? (
           <TooltipIfPresent tooltip={headingText} side="right" align="start">
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 390fa3f29f..dfb62ee39e 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -23,6 +23,23 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("accepts ATX headings indented by up to three spaces", () => {
+    const md = ` ## One space\n  ### Two spaces\n   #### Three spaces\n    ##### Four-space code\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "One space" },
+      { renderIndex: 1, level: 3, text: "Two spaces" },
+      { renderIndex: 2, level: 4, text: "Three spaces" },
+      { renderIndex: 3, level: 2, text: "After" },
+    ]);
+  });
+
+  test("counts empty ATX headings so later renderIndex values stay aligned", () => {
+    const md = `#\n\n## Visible after blank heading`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 1, level: 2, text: "Visible after blank heading" },
+    ]);
+  });
+
   test("strips inline formatting in heading text", () => {
     const md = `# **Bold** and _italic_\n## With \`code\` inline\n### [Linked](https://example.com) heading\n#### ~~strike~~ through`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 63c2b82970..86fef85dd7 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -43,9 +43,10 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
     const line = lines[i];
     const trimmed = line.trim();
 
-    // Track fenced code blocks. The closing fence must use the same char and
-    // be at least as long as the opening fence (CommonMark rule).
-    const fenceMatch = /^(`{3,}|~{3,})/.exec(trimmed);
+    // Track fenced code blocks. CommonMark allows up to three leading spaces
+    // before a fence; four spaces are indented code, not a fence. The closing
+    // fence must use the same char and be at least as long as the opening fence.
+    const fenceMatch = /^ {0,3}(`{3,}|~{3,})/.exec(line);
     if (fenceMatch) {
       const marker = fenceMatch[1];
       const ch = marker[0] as "`" | "~";
@@ -66,15 +67,20 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       continue;
     }
 
-    // ATX heading: leading 1-6 `#`s followed by whitespace and the heading text.
-    const atxMatch = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+    // ATX heading: up to three leading spaces, then 1-6 `#`s. Four leading
+    // spaces are indented code, so matching them would drift from markdown's
+    // rendered h1..h6 order.
+    const atxMatch = /^ {0,3}(#{1,6})(?:[ \t]+(.*)|[ \t]*)$/.exec(line);
     if (atxMatch) {
       const level = atxMatch[1].length;
-      const text = stripMarkdownFormatting(atxMatch[2]);
+      const rawText = (atxMatch[2] ?? "").replace(/[ \t]+#+[ \t]*$/, "");
+      const text = stripMarkdownFormatting(rawText);
       if (text) {
         headings.push({ renderIndex, level, text });
-        renderIndex += 1;
       }
+      // Empty headings still render as hN elements, so they must consume a
+      // renderIndex even though they are not useful TOC entries.
+      renderIndex += 1;
       continue;
     }
 
diff --git a/src/browser/features/Tools/ProposePlanToolCall.tsx b/src/browser/features/Tools/ProposePlanToolCall.tsx
index 8708ecb122..80c8b7dfd7 100644
--- a/src/browser/features/Tools/ProposePlanToolCall.tsx
+++ b/src/browser/features/Tools/ProposePlanToolCall.tsx
@@ -915,11 +915,10 @@ export const ProposePlanToolCall: React.FC<ProposePlanToolCallProps> = (props) =
     </div>
   );
 
-  // Layout container that positions the sticky TOC alongside the plan. The
-  // `plan-toc-layout` class establishes `position: relative` so the TOC's
-  // absolutely-positioned aside (`left: 100%`) can break out of the centered
-  // `max-w-4xl` transcript column into the unused right gutter. CSS container
-  // queries on the transcript scrollport keep it hidden until there's room.
+  // Layout container that positions the TOC affordances alongside the plan. The
+  // `plan-toc-layout` class establishes `position: relative` so CSS can place a
+  // compact hint or sticky TOC in the left gutter when the transcript container
+  // has enough horizontal room.
   const planLayout = (
     <div className="plan-toc-layout">
       {planUI}
diff --git a/src/browser/styles/globals.css b/src/browser/styles/globals.css
index 386e87c3ae..76889d6436 100644
--- a/src/browser/styles/globals.css
+++ b/src/browser/styles/globals.css
@@ -1524,49 +1524,70 @@ code {
  *
  * `.plan-toc-layout` wraps the plan card so an absolutely-positioned `aside`
  * (`.plan-toc-aside`) can break out to the LEFT of the centered `max-w-4xl`
- * transcript column. The aside is `display: none` by default; a container
- * query on the `transcript` scrollport in ChatPane reveals it only when:
+ * transcript column. The aside has three width states controlled by container
+ * queries on the `transcript` scrollport in ChatPane:
  *
- *   1. the chat is in centered (not full-width) mode — opted in by the
- *      `.plan-toc-aware` class on the transcript's inner column, and
- *   2. the transcript scrollport is wide enough to hold the centered plan
- *      plus a TOC gutter on both sides. The plan is centered via `mx-auto`,
- *      so the TOC's left edge cannot extend past the scrollport without
- *      being clipped by `overflow-x-hidden` — both gutters must be at least
- *      `toc width + gap` wide.
+ *   1. hidden on narrow/mobile widths where even a hint would crowd content,
+ *   2. a small sideways "Expand to see ToC" hint when there is some gutter but
+ *      not enough for the full nav, and
+ *   3. the full sticky TOC once the gutter can fit it.
  *
- * Using a container query (rather than viewport `min-width`) is what makes
- * the TOC behave correctly when sidebars open/close without the viewport
- * changing — and using CSS-only visibility (no JS resize listener) is what
- * prevents flashing/tearing when the plan toggles expanded.
+ * In the full state we shift the whole plan+toc group right by half of the TOC
+ * column. That keeps the OVERALL component centered in the transcript instead
+ * of keeping only the plan card centered and leaving the TOC visually heavier on
+ * the left than the empty right gutter.
  * --------------------------------------------------------------------------- */
 
 .plan-toc-layout {
   position: relative;
+  --plan-toc-compact-column: 1.75rem;
+  --plan-toc-wide-column: 10rem;
+  left: 0;
 }
 
 .plan-toc-aside {
   display: none;
   /* Anchor the toc's right edge to the plan card's left edge so it extends
-     leftward into the transcript's left gutter.
-     Width + padding-right are tuned to keep the visibility threshold reachable
-     on common desktop widths (1440px+ with mux sidebars) rather than only on
-     ultra-wide monitors:
-       max-w-4xl (56rem) + 2 × (width 9rem + gap 1rem) = 76rem */
+     leftward into the transcript's left gutter. The compact width only shows a
+     discoverability hint; the wide container query below expands this to the
+     full navigation column. */
   position: absolute;
   inset: 0 100% 0 auto;
-  width: 9rem;
-  padding-right: 1rem;
+  width: var(--plan-toc-compact-column);
+  padding-right: 0.375rem;
   /* Margin clicks should fall through to the underlying transcript chrome;
-     only the inner <nav> is interactive. */
+     only the inner <nav> is interactive when the full TOC is visible. */
   pointer-events: none;
 }
 
-.plan-toc-aside > * {
+.plan-toc-aside > .plan-toc {
   pointer-events: auto;
 }
 
+.plan-toc-compact-hint {
+  position: sticky;
+  top: 1rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 8.5rem;
+  width: 1.375rem;
+  padding: 0.5rem 0.25rem;
+  border: 1px solid var(--surface-plan-border-subtle);
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--color-surface-secondary) 90%, transparent);
+  color: var(--color-muted-foreground);
+  font-size: 10px;
+  font-weight: 500;
+  letter-spacing: 0.03em;
+  line-height: 1;
+  text-transform: uppercase;
+  writing-mode: vertical-rl;
+  transform: rotate(180deg);
+}
+
 .plan-toc {
+  display: none;
   /* Sticky inside the aside keeps the toc anchored while the plan is on
      screen. Once the user scrolls past the plan, the sticky bottoms out at
      the aside's lower edge (which matches the plan's lower edge), so the
@@ -1580,20 +1601,19 @@ code {
   font-family: var(--font-primary);
   font-size: 11px;
   line-height: 1.4;
-  color: var(--color-muted-foreground);
+  color: color-mix(in srgb, var(--color-muted-foreground) 88%, var(--color-foreground) 12%);
   padding: 4px 0;
 }
 
 .plan-toc-heading {
   /* The plan title sits at the top of the TOC, in place of a separate
-     "CONTENTS" label. We don't uppercase or letter-space it because real plan
-     titles ("Authentication Module Refactor", etc.) are sentences, not eyebrow
-     labels, and would look forced in all-caps. */
+     "CONTENTS" label. Keep it neutral (not plan-blue) so the side nav reads as
+     quiet structure instead of competing with the plan card itself. */
   font-size: 12px;
   font-weight: 600;
-  color: color-mix(in srgb, var(--color-plan-mode) 70%, var(--color-foreground) 30%);
+  color: var(--color-foreground);
   margin: 0 0 6px 0;
-  padding: 2px 4px;
+  padding: 2px 0;
   /* Ellipsis-truncate long titles so the TOC never grows horizontally; the
      hover tooltip surfaces the full text. */
   overflow: hidden;
@@ -1608,7 +1628,7 @@ code {
   background: transparent;
   border: 0;
   font: inherit;
-  color: inherit;
+  color: var(--color-foreground);
   cursor: pointer;
   display: block;
   width: 100%;
@@ -1620,11 +1640,11 @@ code {
 
 .plan-toc-heading-link:hover {
   color: var(--color-foreground);
-  background: color-mix(in srgb, var(--color-plan-mode), transparent 90%);
+  background: var(--color-hover);
 }
 
 .plan-toc-heading-link:focus-visible {
-  outline: 2px solid color-mix(in srgb, var(--color-plan-mode), transparent 40%);
+  outline: 2px solid color-mix(in srgb, var(--color-accent) 60%, transparent);
   outline-offset: 1px;
 }
 
@@ -1642,8 +1662,7 @@ code {
      shallowest visible heading sits at 1.
      With the plan title acting as the TOC heading (h1), h2 entries align flush
      with the title (data-level=1 → 0 indent) and deeper headings get a small
-     step per level. We deliberately keep steps tight (6px) so the TOC stays
-     useful in the narrow left-gutter column. */
+     step per level. */
   --plan-toc-indent: 0;
 }
 
@@ -1651,17 +1670,18 @@ code {
   --plan-toc-indent: 0;
 }
 .plan-toc-item[data-level="2"] {
-  --plan-toc-indent: 6px;
+  --plan-toc-indent: 8px;
 }
 .plan-toc-item[data-level="3"] {
-  --plan-toc-indent: 12px;
+  --plan-toc-indent: 16px;
 }
 .plan-toc-item[data-level="4"] {
-  --plan-toc-indent: 18px;
+  --plan-toc-indent: 24px;
 }
 
 .plan-toc-link {
-  /* Render as a flush text link rather than a chunky button. */
+  /* Render as a flush text link rather than a chunky button. Using the same
+     zero left padding as the title is what keeps h1 and h2 visually aligned. */
   appearance: none;
   background: transparent;
   border: 0;
@@ -1671,7 +1691,7 @@ code {
   cursor: pointer;
   display: block;
   width: 100%;
-  padding: 2px 4px 2px calc(4px + var(--plan-toc-indent));
+  padding: 2px 0 2px var(--plan-toc-indent);
   border-radius: 3px;
   overflow: hidden;
   white-space: nowrap;
@@ -1682,17 +1702,17 @@ code {
 }
 
 .plan-toc-item[data-level="1"] .plan-toc-link {
-  font-weight: 600;
-  color: color-mix(in srgb, var(--color-foreground) 80%, var(--color-plan-mode) 20%);
+  font-weight: 500;
+  color: var(--color-foreground);
 }
 
 .plan-toc-link:hover {
   color: var(--color-foreground);
-  background: color-mix(in srgb, var(--color-plan-mode), transparent 90%);
+  background: var(--color-hover);
 }
 
 .plan-toc-link:focus-visible {
-  outline: 2px solid color-mix(in srgb, var(--color-plan-mode), transparent 40%);
+  outline: 2px solid color-mix(in srgb, var(--color-accent) 60%, transparent);
   outline-offset: 1px;
 }
 
@@ -1709,17 +1729,41 @@ code {
 }
 
 /*
- * Visibility gate. The transcript container is queried at its CONTENT box
- * inline-size (padding excluded). The plan is centered via `mx-auto`, so the
- * left gutter holding the TOC and the right gutter mirror each other:
- *   max-w-4xl (56rem) + 2 × (toc width 9rem + gap 1rem) = 76rem
- * of content-box width before there's enough room for the toc in the left
- * gutter without the right side of the plan getting visually crowded. This
- * works out to roughly a 1376px viewport with both mux sidebars open, so the
- * TOC shows on common laptop+ widths; narrower configurations keep it hidden.
+ * Hint visibility. The transcript container is queried at its CONTENT box
+ * inline-size (padding excluded). The compact hint needs only a tiny mirrored
+ * gutter around the centered max-w-4xl plan:
+ *   max-w-4xl (56rem) + a little scrollport padding for the compact rail.
+ * We intentionally start at 58rem so the hint appears in constrained desktop
+ * layouts where the full 76rem TOC would still be hidden.
+ */
+@container transcript (min-width: 58rem) {
+  .plan-toc-aware .plan-toc-aside {
+    display: block;
+  }
+}
+
+/*
+ * Full TOC visibility. The plan is centered via `mx-auto`, so the left gutter
+ * holding the TOC and the right gutter mirror each other:
+ *   max-w-4xl (56rem) + 2 × wide column (10rem) = 76rem
+ * Once the full TOC is visible, offset the plan+toc group right by 5rem so the
+ * overall component (TOC + plan card) remains centered in the transcript.
  */
 @container transcript (min-width: 76rem) {
+  .plan-toc-aware .plan-toc-layout {
+    left: calc(var(--plan-toc-wide-column) / 2);
+  }
+
   .plan-toc-aware .plan-toc-aside {
+    width: var(--plan-toc-wide-column);
+    padding-right: 1rem;
+  }
+
+  .plan-toc-aware .plan-toc-compact-hint {
+    display: none;
+  }
+
+  .plan-toc-aware .plan-toc {
     display: block;
   }
 }

From 0817d5512746dd606e9a5819efb4351c6f926fcd Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 20:13:39 -0500
Subject: [PATCH 04/32] Keep plan TOC in gutter

---
 .../Tools/ProposePlan/PlanTableOfContents.tsx |  8 ++--
 .../ProposePlan/extractPlanHeadings.test.ts   |  5 +++
 .../Tools/ProposePlan/extractPlanHeadings.ts  | 10 ++++-
 src/browser/styles/globals.css                | 42 ++++++++-----------
 4 files changed, 34 insertions(+), 31 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
index 405562c103..41e8c9ad34 100644
--- a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
+++ b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
@@ -34,8 +34,8 @@ export interface PlanTableOfContentsProps {
    * The plan title is the natural label for a plan TOC, so we let the host
    * surface it here — that conserves vertical space (no separate "CONTENTS"
    * label *and* an h1 list entry) and tightens the visual hierarchy: the
-   * title sits at column 0, h2 entries align with it, and h3+ are minimally
-   * indented under their parent h2.
+   * title sits at column 0, h2 entries align with it, and h3+ are indented
+   * under their parent h2.
    */
   title?: string;
   className?: string;
@@ -118,8 +118,8 @@ export const PlanTableOfContents: React.FC<PlanTableOfContentsProps> = (props) =
             >
               {/*
                * Wrap with TooltipIfPresent so users can see the full heading
-               * text when it's truncated by the toc's narrow column width
-               * (long titles get `text-overflow: ellipsis` via CSS).
+               * in one place even when the side TOC wraps long text across
+               * multiple lines in the gutter.
                *
                * `side="right"` keeps the tooltip from drifting off the left
                * edge of the transcript — the toc lives in the left gutter.
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index dfb62ee39e..1de3449ed5 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -92,6 +92,11 @@ describe("extractPlanHeadings", () => {
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 1, text: "Heading" }]);
   });
 
+  test("does not treat ordered-list items followed by rules as setext headings", () => {
+    const md = `1. Step one\n---\n\n2) Step two\n---\n\n## Actual heading`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Actual heading" }]);
+  });
+
   test("counts raw HTML headings so renderIndex stays aligned", () => {
     const md = `# Markdown one\n\n<h2>Inline HTML two</h2>\n\n### Markdown three`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 86fef85dd7..10c3daec89 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -85,8 +85,14 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
     }
 
     // Setext heading: text line followed by === (h1) or --- (h2). Skip blank
-    // text lines so we don't mistake a thematic break for a setext underline.
-    if (i + 1 < lines.length && trimmed.length > 0 && !/^[#>\-*+`~]/.test(trimmed)) {
+    // text lines and list/fence/thematic-break starters so we don't invent a
+    // heading where markdown renders a list item or horizontal rule instead.
+    if (
+      i + 1 < lines.length &&
+      trimmed.length > 0 &&
+      !/^[#>\-*+`~]/.test(trimmed) &&
+      !/^\d{1,9}[.)][ \t]/.test(trimmed)
+    ) {
       const nextTrimmed = lines[i + 1].trim();
       if (/^=+$/.test(nextTrimmed)) {
         const text = stripMarkdownFormatting(trimmed);
diff --git a/src/browser/styles/globals.css b/src/browser/styles/globals.css
index 76889d6436..54b0ad8002 100644
--- a/src/browser/styles/globals.css
+++ b/src/browser/styles/globals.css
@@ -1532,17 +1532,16 @@ code {
  *      not enough for the full nav, and
  *   3. the full sticky TOC once the gutter can fit it.
  *
- * In the full state we shift the whole plan+toc group right by half of the TOC
- * column. That keeps the OVERALL component centered in the transcript instead
- * of keeping only the plan card centered and leaving the TOC visually heavier on
- * the left than the empty right gutter.
+ * The full TOC stays entirely in the existing left gutter; it must not shift
+ * the plan card away from the transcript's centered column. The width is derived
+ * from the transcript container so wider gutters give the TOC more room instead
+ * of leaving unused space while headings wrap/truncate too early.
  * --------------------------------------------------------------------------- */
 
 .plan-toc-layout {
   position: relative;
   --plan-toc-compact-column: 1.75rem;
-  --plan-toc-wide-column: 10rem;
-  left: 0;
+  --plan-toc-wide-column: 12rem;
 }
 
 .plan-toc-aside {
@@ -1614,11 +1613,10 @@ code {
   color: var(--color-foreground);
   margin: 0 0 6px 0;
   padding: 2px 0;
-  /* Ellipsis-truncate long titles so the TOC never grows horizontally; the
-     hover tooltip surfaces the full text. */
-  overflow: hidden;
-  white-space: nowrap;
-  text-overflow: ellipsis;
+  /* Let long plan titles wrap inside the gutter instead of wasting available
+     horizontal space and hiding useful context behind an ellipsis. */
+  white-space: normal;
+  overflow-wrap: anywhere;
   /* Match the .plan-toc-link reset for the clickable variant. */
   text-align: left;
 }
@@ -1693,9 +1691,8 @@ code {
   width: 100%;
   padding: 2px 0 2px var(--plan-toc-indent);
   border-radius: 3px;
-  overflow: hidden;
-  white-space: nowrap;
-  text-overflow: ellipsis;
+  white-space: normal;
+  overflow-wrap: anywhere;
   transition:
     color 120ms ease,
     background-color 120ms ease;
@@ -1743,20 +1740,15 @@ code {
 }
 
 /*
- * Full TOC visibility. The plan is centered via `mx-auto`, so the left gutter
- * holding the TOC and the right gutter mirror each other:
- *   max-w-4xl (56rem) + 2 × wide column (10rem) = 76rem
- * Once the full TOC is visible, offset the plan+toc group right by 5rem so the
- * overall component (TOC + plan card) remains centered in the transcript.
+ * Full TOC visibility. The plan stays centered in the transcript; the TOC uses
+ * the left gutter beside that centered column. A 12rem column fills most of the
+ * practical gutter at this breakpoint without stealing space from the plan.
  */
-@container transcript (min-width: 76rem) {
-  .plan-toc-aware .plan-toc-layout {
-    left: calc(var(--plan-toc-wide-column) / 2);
-  }
-
+@container transcript (min-width: 78.5rem) {
   .plan-toc-aware .plan-toc-aside {
+    box-sizing: border-box;
     width: var(--plan-toc-wide-column);
-    padding-right: 1rem;
+    padding-right: 0.75rem;
   }
 
   .plan-toc-aware .plan-toc-compact-hint {

From 3ee1c330b203d9c8af170e14b95968a869a5e9a9 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 20:21:40 -0500
Subject: [PATCH 05/32] Center plan TOC gutter affordance

---
 .../ProposePlan/extractPlanHeadings.test.ts   | 23 ++++++
 .../Tools/ProposePlan/extractPlanHeadings.ts  | 70 +++++++++++++++----
 src/browser/styles/globals.css                | 51 ++++++++------
 3 files changed, 109 insertions(+), 35 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 1de3449ed5..e2d672cc1a 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -77,6 +77,21 @@ describe("extractPlanHeadings", () => {
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 1, text: "Visible" }]);
   });
 
+  test("counts headings inside blockquote and list containers", () => {
+    const md = `> # Quoted\n\n- ## Listed\n\n## Real\n\n## Next`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Quoted" },
+      { renderIndex: 1, level: 2, text: "Listed" },
+      { renderIndex: 2, level: 2, text: "Real" },
+      { renderIndex: 3, level: 2, text: "Next" },
+    ]);
+  });
+
+  test("skips headings inside container-prefixed fenced code blocks", () => {
+    const md = `> \`\`\`markdown\n> # Hidden quoted heading\n> \`\`\`\n\n- \`\`\`markdown\n  ## Hidden list heading\n  \`\`\`\n\n## Visible`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Visible" }]);
+  });
+
   test("recognizes setext h1 and h2 underlines", () => {
     const md = `Title One\n=========\n\nbody\n\nTitle Two\n---------\n\nmore`;
     expect(extractPlanHeadings(md)).toEqual([
@@ -85,6 +100,14 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("recognizes setext headings inside blockquotes", () => {
+    const md = `> Quoted title\n> ===\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 1, text: "Quoted title" },
+      { renderIndex: 1, level: 2, text: "After" },
+    ]);
+  });
+
   test("does not confuse thematic breaks with setext underlines", () => {
     const md = `Some intro paragraph.\n\n---\n\n# Heading`;
     // The `---` here is preceded by a blank line, so it's a thematic break, not
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 10c3daec89..5c9d8afc88 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -41,12 +41,16 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    const trimmed = line.trim();
+    const structuralLine = stripAtxContainerPrefixes(line);
+    const structuralTrimmed = structuralLine.trim();
+    const blockquoteLine = stripBlockquotePrefixes(line);
+    const blockquoteTrimmed = blockquoteLine.trim();
 
     // Track fenced code blocks. CommonMark allows up to three leading spaces
-    // before a fence; four spaces are indented code, not a fence. The closing
-    // fence must use the same char and be at least as long as the opening fence.
-    const fenceMatch = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    // before a fence; four spaces are indented code, not a fence. We also strip
+    // container markers so quoted/list-contained fences suppress headings inside
+    // them the same way the markdown renderer does.
+    const fenceMatch = /^ {0,3}(`{3,}|~{3,})/.exec(structuralLine);
     if (fenceMatch) {
       const marker = fenceMatch[1];
       const ch = marker[0] as "`" | "~";
@@ -55,7 +59,7 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
         inFence = true;
         fenceChar = ch;
         fenceLength = len;
-      } else if (ch === fenceChar && len >= fenceLength && /^[`~]+\s*$/.test(trimmed)) {
+      } else if (ch === fenceChar && len >= fenceLength && /^[`~]+\s*$/.test(structuralTrimmed)) {
         inFence = false;
         fenceChar = null;
         fenceLength = 0;
@@ -70,7 +74,7 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
     // ATX heading: up to three leading spaces, then 1-6 `#`s. Four leading
     // spaces are indented code, so matching them would drift from markdown's
     // rendered h1..h6 order.
-    const atxMatch = /^ {0,3}(#{1,6})(?:[ \t]+(.*)|[ \t]*)$/.exec(line);
+    const atxMatch = /^ {0,3}(#{1,6})(?:[ \t]+(.*)|[ \t]*)$/.exec(structuralLine);
     if (atxMatch) {
       const level = atxMatch[1].length;
       const rawText = (atxMatch[2] ?? "").replace(/[ \t]+#+[ \t]*$/, "");
@@ -89,13 +93,13 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
     // heading where markdown renders a list item or horizontal rule instead.
     if (
       i + 1 < lines.length &&
-      trimmed.length > 0 &&
-      !/^[#>\-*+`~]/.test(trimmed) &&
-      !/^\d{1,9}[.)][ \t]/.test(trimmed)
+      blockquoteTrimmed.length > 0 &&
+      !/^[#>\-*+`~]/.test(blockquoteTrimmed) &&
+      !/^\d{1,9}[.)][ \t]/.test(blockquoteTrimmed)
     ) {
-      const nextTrimmed = lines[i + 1].trim();
+      const nextTrimmed = stripBlockquotePrefixes(lines[i + 1]).trim();
       if (/^=+$/.test(nextTrimmed)) {
-        const text = stripMarkdownFormatting(trimmed);
+        const text = stripMarkdownFormatting(blockquoteTrimmed);
         if (text) {
           headings.push({ renderIndex, level: 1, text });
           renderIndex += 1;
@@ -104,7 +108,7 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
         }
       }
       if (/^-{2,}$/.test(nextTrimmed)) {
-        const text = stripMarkdownFormatting(trimmed);
+        const text = stripMarkdownFormatting(blockquoteTrimmed);
         if (text) {
           headings.push({ renderIndex, level: 2, text });
           renderIndex += 1;
@@ -116,7 +120,7 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
 
     // Raw HTML heading on its own line (`<h2>Hello</h2>`). Streamdown emits these
     // through rehype-raw, so we count them too to keep `renderIndex` aligned.
-    const htmlMatch = /^<h([1-6])\b[^>]*>(.*?)<\/h\1>\s*$/i.exec(trimmed);
+    const htmlMatch = /^<h([1-6])\b[^>]*>(.*?)<\/h\1>\s*$/i.exec(structuralTrimmed);
     if (htmlMatch) {
       const level = parseInt(htmlMatch[1], 10);
       const text = stripMarkdownFormatting(htmlMatch[2].replace(/<[^>]+>/g, ""));
@@ -131,6 +135,46 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
   return headings;
 }
 
+function stripAtxContainerPrefixes(line: string): string {
+  let remaining = line;
+  let changed = true;
+  while (changed) {
+    changed = false;
+
+    const blockquoteMatch = /^ {0,3}>[ \t]?/.exec(remaining);
+    if (blockquoteMatch) {
+      remaining = remaining.slice(blockquoteMatch[0].length);
+      changed = true;
+      continue;
+    }
+
+    const unorderedListMatch = /^ {0,3}[-+*][ \t]+/.exec(remaining);
+    if (unorderedListMatch) {
+      remaining = remaining.slice(unorderedListMatch[0].length);
+      changed = true;
+      continue;
+    }
+
+    const orderedListMatch = /^ {0,3}\d{1,9}[.)][ \t]+/.exec(remaining);
+    if (orderedListMatch) {
+      remaining = remaining.slice(orderedListMatch[0].length);
+      changed = true;
+    }
+  }
+  return remaining;
+}
+
+function stripBlockquotePrefixes(line: string): string {
+  let remaining = line;
+  while (true) {
+    const blockquoteMatch = /^ {0,3}>[ \t]?/.exec(remaining);
+    if (!blockquoteMatch) {
+      return remaining;
+    }
+    remaining = remaining.slice(blockquoteMatch[0].length);
+  }
+}
+
 /**
  * Lightweight inline-formatting stripper used only for TOC display text. Not a
  * full markdown parser — we trade exhaustive correctness for predictable output
diff --git a/src/browser/styles/globals.css b/src/browser/styles/globals.css
index 54b0ad8002..80e6a56357 100644
--- a/src/browser/styles/globals.css
+++ b/src/browser/styles/globals.css
@@ -1533,15 +1533,16 @@ code {
  *   3. the full sticky TOC once the gutter can fit it.
  *
  * The full TOC stays entirely in the existing left gutter; it must not shift
- * the plan card away from the transcript's centered column. The width is derived
- * from the transcript container so wider gutters give the TOC more room instead
- * of leaving unused space while headings wrap/truncate too early.
+ * the plan card away from the transcript's centered column. The aside spans the
+ * current gutter and centers the nav inside it so wider gutters give the TOC
+ * more room instead of leaving unused space while headings wrap too early.
  * --------------------------------------------------------------------------- */
 
 .plan-toc-layout {
   position: relative;
-  --plan-toc-compact-column: 1.75rem;
-  --plan-toc-wide-column: 12rem;
+  --plan-toc-plan-column: 54.5rem;
+  --plan-toc-compact-column: 0.875rem;
+  --plan-toc-wide-column: 11rem;
 }
 
 .plan-toc-aside {
@@ -1552,8 +1553,13 @@ code {
      full navigation column. */
   position: absolute;
   inset: 0 100% 0 auto;
-  width: var(--plan-toc-compact-column);
-  padding-right: 0.375rem;
+  box-sizing: border-box;
+  width: clamp(
+    var(--plan-toc-compact-column),
+    calc((100cqw - var(--plan-toc-plan-column)) / 2),
+    4rem
+  );
+  padding-inline: 0.125rem;
   /* Margin clicks should fall through to the underlying transcript chrome;
      only the inner <nav> is interactive when the full TOC is visible. */
   pointer-events: none;
@@ -1569,14 +1575,15 @@ code {
   display: flex;
   align-items: center;
   justify-content: center;
-  min-height: 8.5rem;
-  width: 1.375rem;
-  padding: 0.5rem 0.25rem;
+  min-height: 7.5rem;
+  width: 0.75rem;
+  margin-inline: auto;
+  padding: 0.4rem 0.0625rem;
   border: 1px solid var(--surface-plan-border-subtle);
   border-radius: 999px;
   background: color-mix(in srgb, var(--color-surface-secondary) 90%, transparent);
   color: var(--color-muted-foreground);
-  font-size: 10px;
+  font-size: 9px;
   font-weight: 500;
   letter-spacing: 0.03em;
   line-height: 1;
@@ -1587,6 +1594,8 @@ code {
 
 .plan-toc {
   display: none;
+  width: min(100%, var(--plan-toc-wide-column));
+  margin-inline: auto;
   /* Sticky inside the aside keeps the toc anchored while the plan is on
      screen. Once the user scrolls past the plan, the sticky bottoms out at
      the aside's lower edge (which matches the plan's lower edge), so the
@@ -1727,13 +1736,10 @@ code {
 
 /*
  * Hint visibility. The transcript container is queried at its CONTENT box
- * inline-size (padding excluded). The compact hint needs only a tiny mirrored
- * gutter around the centered max-w-4xl plan:
- *   max-w-4xl (56rem) + a little scrollport padding for the compact rail.
- * We intentionally start at 58rem so the hint appears in constrained desktop
- * layouts where the full 76rem TOC would still be hidden.
+ * inline-size (padding excluded). The compact rail is intentionally thin so it
+ * can appear as soon as a small mirrored gutter exists.
  */
-@container transcript (min-width: 58rem) {
+@container transcript (min-width: 56.25rem) {
   .plan-toc-aware .plan-toc-aside {
     display: block;
   }
@@ -1741,14 +1747,15 @@ code {
 
 /*
  * Full TOC visibility. The plan stays centered in the transcript; the TOC uses
- * the left gutter beside that centered column. A 12rem column fills most of the
- * practical gutter at this breakpoint without stealing space from the plan.
+ * the left gutter beside that centered column. `100cqw` is the transcript
+ * content-box width; `--plan-toc-plan-column` mirrors the rendered plan card
+ * width so the aside spans the actual gutter instead of shifting the plan to
+ * manufacture room.
  */
 @container transcript (min-width: 78.5rem) {
   .plan-toc-aware .plan-toc-aside {
-    box-sizing: border-box;
-    width: var(--plan-toc-wide-column);
-    padding-right: 0.75rem;
+    width: clamp(12rem, calc((100cqw - var(--plan-toc-plan-column)) / 2), 18rem);
+    padding-inline: 0.375rem;
   }
 
   .plan-toc-aware .plan-toc-compact-hint {

From f54f01bb4866979204082368fdc58f23c4d651de Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 20:24:23 -0500
Subject: [PATCH 06/32] Align setext extraction with markdown indentation

---
 .../Tools/ProposePlan/extractPlanHeadings.test.ts        | 5 +++++
 .../features/Tools/ProposePlan/extractPlanHeadings.ts    | 9 ++++++---
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index e2d672cc1a..79f2602cca 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -108,6 +108,11 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("does not trim four-space-indented setext underlines into headings", () => {
+    const md = `Title\n    ---\n\n> Quoted title\n>     ===\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "After" }]);
+  });
+
   test("does not confuse thematic breaks with setext underlines", () => {
     const md = `Some intro paragraph.\n\n---\n\n# Heading`;
     // The `---` here is preceded by a blank line, so it's a thematic break, not
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 5c9d8afc88..ad7f8731a2 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -91,14 +91,17 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
     // Setext heading: text line followed by === (h1) or --- (h2). Skip blank
     // text lines and list/fence/thematic-break starters so we don't invent a
     // heading where markdown renders a list item or horizontal rule instead.
+    // Preserve underline indentation: a 4-space-indented underline is code, not
+    // a heading marker, so trimming it would create phantom headings.
     if (
       i + 1 < lines.length &&
+      /^ {0,3}\S/.test(blockquoteLine) &&
       blockquoteTrimmed.length > 0 &&
       !/^[#>\-*+`~]/.test(blockquoteTrimmed) &&
       !/^\d{1,9}[.)][ \t]/.test(blockquoteTrimmed)
     ) {
-      const nextTrimmed = stripBlockquotePrefixes(lines[i + 1]).trim();
-      if (/^=+$/.test(nextTrimmed)) {
+      const nextSetextLine = stripBlockquotePrefixes(lines[i + 1]);
+      if (/^ {0,3}=+[ \t]*$/.test(nextSetextLine)) {
         const text = stripMarkdownFormatting(blockquoteTrimmed);
         if (text) {
           headings.push({ renderIndex, level: 1, text });
@@ -107,7 +110,7 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
           continue;
         }
       }
-      if (/^-{2,}$/.test(nextTrimmed)) {
+      if (/^ {0,3}-{2,}[ \t]*$/.test(nextSetextLine)) {
         const text = stripMarkdownFormatting(blockquoteTrimmed);
         if (text) {
           headings.push({ renderIndex, level: 2, text });

From ebfda4820d83e957346e808436e460649e7b1b8b Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 20:31:18 -0500
Subject: [PATCH 07/32] Handle HTML heading edge cases in plan TOC

---
 .../Tools/ProposePlan/extractPlanHeadings.test.ts    | 12 ++++++++++++
 .../Tools/ProposePlan/extractPlanHeadings.ts         |  6 ++++--
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 79f2602cca..0b0f9095ad 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -113,6 +113,11 @@ describe("extractPlanHeadings", () => {
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "After" }]);
   });
 
+  test("does not treat raw HTML blocks followed by rules as setext headings", () => {
+    const md = `<div>Intro</div>\n---\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "After" }]);
+  });
+
   test("does not confuse thematic breaks with setext underlines", () => {
     const md = `Some intro paragraph.\n\n---\n\n# Heading`;
     // The `---` here is preceded by a blank line, so it's a thematic break, not
@@ -134,6 +139,13 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("counts empty raw HTML headings so later renderIndex values stay aligned", () => {
+    const md = `<h2></h2>\n\n## After empty HTML heading`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 1, level: 2, text: "After empty HTML heading" },
+    ]);
+  });
+
   test("preserves stable render indices across mixed content", () => {
     const md = [
       "# A",
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index ad7f8731a2..93362d0205 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -97,7 +97,7 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       i + 1 < lines.length &&
       /^ {0,3}\S/.test(blockquoteLine) &&
       blockquoteTrimmed.length > 0 &&
-      !/^[#>\-*+`~]/.test(blockquoteTrimmed) &&
+      !/^[#>\-*+`~<]/.test(blockquoteTrimmed) &&
       !/^\d{1,9}[.)][ \t]/.test(blockquoteTrimmed)
     ) {
       const nextSetextLine = stripBlockquotePrefixes(lines[i + 1]);
@@ -129,8 +129,10 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       const text = stripMarkdownFormatting(htmlMatch[2].replace(/<[^>]+>/g, ""));
       if (text) {
         headings.push({ renderIndex, level, text });
-        renderIndex += 1;
       }
+      // Empty raw HTML headings still render as hN elements, so they consume
+      // an index even when they do not produce a useful TOC entry.
+      renderIndex += 1;
       continue;
     }
   }

From 19e6500ef57d5f87e562e0835104baa5e8df7c15 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 20:36:53 -0500
Subject: [PATCH 08/32] Simplify constrained plan TOC hint

---
 src/browser/styles/globals.css | 41 +++++++++++++++-------------------
 1 file changed, 18 insertions(+), 23 deletions(-)

diff --git a/src/browser/styles/globals.css b/src/browser/styles/globals.css
index 80e6a56357..250101bf18 100644
--- a/src/browser/styles/globals.css
+++ b/src/browser/styles/globals.css
@@ -1540,9 +1540,9 @@ code {
 
 .plan-toc-layout {
   position: relative;
-  --plan-toc-plan-column: 54.5rem;
-  --plan-toc-compact-column: 0.875rem;
+  --plan-toc-compact-column: 2.5rem;
   --plan-toc-wide-column: 11rem;
+  --plan-toc-wide-gutter: 13rem;
 }
 
 .plan-toc-aside {
@@ -1554,12 +1554,8 @@ code {
   position: absolute;
   inset: 0 100% 0 auto;
   box-sizing: border-box;
-  width: clamp(
-    var(--plan-toc-compact-column),
-    calc((100cqw - var(--plan-toc-plan-column)) / 2),
-    4rem
-  );
-  padding-inline: 0.125rem;
+  width: var(--plan-toc-compact-column);
+  padding-inline: 0;
   /* Margin clicks should fall through to the underlying transcript chrome;
      only the inner <nav> is interactive when the full TOC is visible. */
   pointer-events: none;
@@ -1575,14 +1571,13 @@ code {
   display: flex;
   align-items: center;
   justify-content: center;
-  min-height: 7.5rem;
+  min-height: 7.25rem;
   width: 0.75rem;
-  margin-inline: auto;
-  padding: 0.4rem 0.0625rem;
-  border: 1px solid var(--surface-plan-border-subtle);
-  border-radius: 999px;
-  background: color-mix(in srgb, var(--color-surface-secondary) 90%, transparent);
-  color: var(--color-muted-foreground);
+  margin-left: calc((var(--plan-toc-compact-column) - 0.75rem) / 2);
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: color-mix(in srgb, var(--color-muted-foreground) 85%, transparent);
   font-size: 9px;
   font-weight: 500;
   letter-spacing: 0.03em;
@@ -1736,8 +1731,9 @@ code {
 
 /*
  * Hint visibility. The transcript container is queried at its CONTENT box
- * inline-size (padding excluded). The compact rail is intentionally thin so it
- * can appear as soon as a small mirrored gutter exists.
+ * inline-size (padding excluded). The rail itself is a narrow text-only cue, but
+ * its invisible column is wider so the text sits in the gutter instead of
+ * touching the plan border.
  */
 @container transcript (min-width: 56.25rem) {
   .plan-toc-aware .plan-toc-aside {
@@ -1747,15 +1743,14 @@ code {
 
 /*
  * Full TOC visibility. The plan stays centered in the transcript; the TOC uses
- * the left gutter beside that centered column. `100cqw` is the transcript
- * content-box width; `--plan-toc-plan-column` mirrors the rendered plan card
- * width so the aside spans the actual gutter instead of shifting the plan to
- * manufacture room.
+ * the left gutter beside that centered column. The gutter width is fixed at the
+ * reveal breakpoint so the nav can be centered in the available lane without
+ * relying on container-relative units that resolve inconsistently here.
  */
 @container transcript (min-width: 78.5rem) {
   .plan-toc-aware .plan-toc-aside {
-    width: clamp(12rem, calc((100cqw - var(--plan-toc-plan-column)) / 2), 18rem);
-    padding-inline: 0.375rem;
+    width: var(--plan-toc-wide-gutter);
+    padding-inline: 0;
   }
 
   .plan-toc-aware .plan-toc-compact-hint {

From 7286841a5dfac24223cdb1814d697963db33c749 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 20:41:47 -0500
Subject: [PATCH 09/32] Ignore raw HTML blocks in plan TOC extraction

---
 .../ProposePlan/extractPlanHeadings.test.ts   |  8 ++
 .../Tools/ProposePlan/extractPlanHeadings.ts  | 95 ++++++++++++++++---
 2 files changed, 88 insertions(+), 15 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 0b0f9095ad..0d31c36ac7 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -113,6 +113,14 @@ describe("extractPlanHeadings", () => {
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "After" }]);
   });
 
+  test("ignores markdown-looking headings inside raw HTML blocks", () => {
+    const md = `<div>\n# Hidden ATX\n\nAfter html\n---\n\n<section>\nTitle inside section\n---\n</section>\n\n## Visible`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "After html" },
+      { renderIndex: 1, level: 2, text: "Visible" },
+    ]);
+  });
+
   test("does not treat raw HTML blocks followed by rules as setext headings", () => {
     const md = `<div>Intro</div>\n---\n\n## After`;
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "After" }]);
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 93362d0205..d299cfdd83 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -37,6 +37,7 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
   let inFence = false;
   let fenceChar: "`" | "~" | null = null;
   let fenceLength = 0;
+  let htmlBlockState: HtmlBlockState | null = null;
   let renderIndex = 0;
 
   for (let i = 0; i < lines.length; i++) {
@@ -71,6 +72,36 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       continue;
     }
 
+    if (htmlBlockState) {
+      if (htmlBlockTerminates(htmlBlockState, structuralTrimmed)) {
+        htmlBlockState = null;
+      }
+      continue;
+    }
+
+    // Raw HTML heading on its own line (`<h2>Hello</h2>`). Streamdown emits these
+    // through rehype-raw, so we count them too to keep `renderIndex` aligned.
+    const htmlMatch = /^<h([1-6])\b[^>]*>(.*?)<\/h\1>\s*$/i.exec(structuralTrimmed);
+    if (htmlMatch) {
+      const level = parseInt(htmlMatch[1], 10);
+      const text = stripMarkdownFormatting(htmlMatch[2].replace(/<[^>]+>/g, ""));
+      if (text) {
+        headings.push({ renderIndex, level, text });
+      }
+      // Empty raw HTML headings still render as hN elements, so they consume
+      // an index even when they do not produce a useful TOC entry.
+      renderIndex += 1;
+      continue;
+    }
+
+    const htmlBlockStart = getHtmlBlockStart(structuralTrimmed);
+    if (htmlBlockStart) {
+      if (!htmlBlockTerminates(htmlBlockStart, structuralTrimmed)) {
+        htmlBlockState = htmlBlockStart;
+      }
+      continue;
+    }
+
     // ATX heading: up to three leading spaces, then 1-6 `#`s. Four leading
     // spaces are indented code, so matching them would drift from markdown's
     // rendered h1..h6 order.
@@ -120,26 +151,60 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
         }
       }
     }
-
-    // Raw HTML heading on its own line (`<h2>Hello</h2>`). Streamdown emits these
-    // through rehype-raw, so we count them too to keep `renderIndex` aligned.
-    const htmlMatch = /^<h([1-6])\b[^>]*>(.*?)<\/h\1>\s*$/i.exec(structuralTrimmed);
-    if (htmlMatch) {
-      const level = parseInt(htmlMatch[1], 10);
-      const text = stripMarkdownFormatting(htmlMatch[2].replace(/<[^>]+>/g, ""));
-      if (text) {
-        headings.push({ renderIndex, level, text });
-      }
-      // Empty raw HTML headings still render as hN elements, so they consume
-      // an index even when they do not produce a useful TOC entry.
-      renderIndex += 1;
-      continue;
-    }
   }
 
   return headings;
 }
 
+interface HtmlBlockState {
+  closingPattern?: RegExp;
+  terminatesOnBlank: boolean;
+}
+
+const HTML_BLOCK_TAGS =
+  "address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|search|section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul";
+const HTML_BLOCK_TAG_PATTERN = new RegExp(`^</?(?:${HTML_BLOCK_TAGS})(?=[\\s>/])`, "i");
+
+function getHtmlBlockStart(trimmedLine: string): HtmlBlockState | null {
+  const pairedTagMatch = /^<(script|pre|style)(?=[\s>])/i.exec(trimmedLine);
+  if (pairedTagMatch) {
+    return { closingPattern: new RegExp(`</${pairedTagMatch[1]}>`, "i"), terminatesOnBlank: false };
+  }
+
+  if (trimmedLine.startsWith("<!--")) {
+    return { closingPattern: /-->/, terminatesOnBlank: false };
+  }
+  if (trimmedLine.startsWith("<?")) {
+    return { closingPattern: /\?>/, terminatesOnBlank: false };
+  }
+  if (/^<![A-Z]/.test(trimmedLine)) {
+    return { closingPattern: />/, terminatesOnBlank: false };
+  }
+  if (trimmedLine.startsWith("<![CDATA[")) {
+    return { closingPattern: /\]\]>/, terminatesOnBlank: false };
+  }
+
+  if (HTML_BLOCK_TAG_PATTERN.test(trimmedLine)) {
+    return { terminatesOnBlank: true };
+  }
+
+  // CommonMark also treats a complete open/closing HTML tag on its own line as
+  // an HTML block. Raw h1-h6 lines are handled above so they still count toward
+  // renderIndex.
+  if (/^<\/?[A-Za-z][A-Za-z0-9-]*(?:\s+[^<>]*)?>\s*$/.test(trimmedLine)) {
+    return { terminatesOnBlank: true };
+  }
+
+  return null;
+}
+
+function htmlBlockTerminates(state: HtmlBlockState, trimmedLine: string): boolean {
+  if (state.closingPattern) {
+    return state.closingPattern.test(trimmedLine);
+  }
+  return state.terminatesOnBlank && trimmedLine.length === 0;
+}
+
 function stripAtxContainerPrefixes(line: string): string {
   let remaining = line;
   let changed = true;

From a9206c1f5b4170f74b1bb5e3e1cd3983ba5d86f0 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 20:47:22 -0500
Subject: [PATCH 10/32] Count HTML headings inside raw plan blocks

---
 .../ProposePlan/extractPlanHeadings.test.ts      |  8 ++++++++
 .../Tools/ProposePlan/extractPlanHeadings.ts     | 16 +++++++++-------
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 0d31c36ac7..acb63bbb44 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -138,6 +138,14 @@ describe("extractPlanHeadings", () => {
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Actual heading" }]);
   });
 
+  test("counts raw HTML headings nested inside raw HTML blocks", () => {
+    const md = `<div>\n<h2>Inner HTML heading</h2>\n</div>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Inner HTML heading" },
+      { renderIndex: 1, level: 2, text: "Outside" },
+    ]);
+  });
+
   test("counts raw HTML headings so renderIndex stays aligned", () => {
     const md = `# Markdown one\n\n<h2>Inline HTML two</h2>\n\n### Markdown three`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index d299cfdd83..1168661f55 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -72,15 +72,10 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       continue;
     }
 
-    if (htmlBlockState) {
-      if (htmlBlockTerminates(htmlBlockState, structuralTrimmed)) {
-        htmlBlockState = null;
-      }
-      continue;
-    }
-
     // Raw HTML heading on its own line (`<h2>Hello</h2>`). Streamdown emits these
     // through rehype-raw, so we count them too to keep `renderIndex` aligned.
+    // Check this even while inside another raw HTML block (`<div>...</div>`),
+    // because nested h1-h6 tags still render into the same heading NodeList.
     const htmlMatch = /^<h([1-6])\b[^>]*>(.*?)<\/h\1>\s*$/i.exec(structuralTrimmed);
     if (htmlMatch) {
       const level = parseInt(htmlMatch[1], 10);
@@ -94,6 +89,13 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       continue;
     }
 
+    if (htmlBlockState) {
+      if (htmlBlockTerminates(htmlBlockState, structuralTrimmed)) {
+        htmlBlockState = null;
+      }
+      continue;
+    }
+
     const htmlBlockStart = getHtmlBlockStart(structuralTrimmed);
     if (htmlBlockStart) {
       if (!htmlBlockTerminates(htmlBlockStart, structuralTrimmed)) {

From 8c96573c66cb71f9623eca2b3817189fcd0d8c1a Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 20:53:30 -0500
Subject: [PATCH 11/32] Skip script style headings in plan TOC extraction

---
 .../ProposePlan/extractPlanHeadings.test.ts   |  5 ++++
 .../Tools/ProposePlan/extractPlanHeadings.ts  | 26 ++++++++++++++-----
 2 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index acb63bbb44..4d9c5d545e 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -138,6 +138,11 @@ describe("extractPlanHeadings", () => {
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Actual heading" }]);
   });
 
+  test("does not count HTML-looking headings inside script or style blocks", () => {
+    const md = `<script>\n<h2>Hidden script heading</h2>\n</script>\n\n<style>\n<h3>Hidden style heading</h3>\n</style>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
+  });
+
   test("counts raw HTML headings nested inside raw HTML blocks", () => {
     const md = `<div>\n<h2>Inner HTML heading</h2>\n</div>\n\n## Outside`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 1168661f55..7f7965763c 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -72,6 +72,13 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       continue;
     }
 
+    if (htmlBlockState && !htmlBlockState.countsNestedHeadings) {
+      if (htmlBlockTerminates(htmlBlockState, structuralTrimmed)) {
+        htmlBlockState = null;
+      }
+      continue;
+    }
+
     // Raw HTML heading on its own line (`<h2>Hello</h2>`). Streamdown emits these
     // through rehype-raw, so we count them too to keep `renderIndex` aligned.
     // Check this even while inside another raw HTML block (`<div>...</div>`),
@@ -161,6 +168,7 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
 interface HtmlBlockState {
   closingPattern?: RegExp;
   terminatesOnBlank: boolean;
+  countsNestedHeadings: boolean;
 }
 
 const HTML_BLOCK_TAGS =
@@ -170,31 +178,35 @@ const HTML_BLOCK_TAG_PATTERN = new RegExp(`^</?(?:${HTML_BLOCK_TAGS})(?=[\\s>/])
 function getHtmlBlockStart(trimmedLine: string): HtmlBlockState | null {
   const pairedTagMatch = /^<(script|pre|style)(?=[\s>])/i.exec(trimmedLine);
   if (pairedTagMatch) {
-    return { closingPattern: new RegExp(`</${pairedTagMatch[1]}>`, "i"), terminatesOnBlank: false };
+    return {
+      closingPattern: new RegExp(`</${pairedTagMatch[1]}>`, "i"),
+      terminatesOnBlank: false,
+      countsNestedHeadings: false,
+    };
   }
 
   if (trimmedLine.startsWith("<!--")) {
-    return { closingPattern: /-->/, terminatesOnBlank: false };
+    return { closingPattern: /-->/, terminatesOnBlank: false, countsNestedHeadings: false };
   }
   if (trimmedLine.startsWith("<?")) {
-    return { closingPattern: /\?>/, terminatesOnBlank: false };
+    return { closingPattern: /\?>/, terminatesOnBlank: false, countsNestedHeadings: false };
   }
   if (/^<![A-Z]/.test(trimmedLine)) {
-    return { closingPattern: />/, terminatesOnBlank: false };
+    return { closingPattern: />/, terminatesOnBlank: false, countsNestedHeadings: false };
   }
   if (trimmedLine.startsWith("<![CDATA[")) {
-    return { closingPattern: /\]\]>/, terminatesOnBlank: false };
+    return { closingPattern: /\]\]>/, terminatesOnBlank: false, countsNestedHeadings: false };
   }
 
   if (HTML_BLOCK_TAG_PATTERN.test(trimmedLine)) {
-    return { terminatesOnBlank: true };
+    return { terminatesOnBlank: true, countsNestedHeadings: true };
   }
 
   // CommonMark also treats a complete open/closing HTML tag on its own line as
   // an HTML block. Raw h1-h6 lines are handled above so they still count toward
   // renderIndex.
   if (/^<\/?[A-Za-z][A-Za-z0-9-]*(?:\s+[^<>]*)?>\s*$/.test(trimmedLine)) {
-    return { terminatesOnBlank: true };
+    return { terminatesOnBlank: true, countsNestedHeadings: true };
   }
 
   return null;

From 0c74bcf8536523b7d1056142178a59d6dc4db2f6 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 20:59:09 -0500
Subject: [PATCH 12/32] Count multiline HTML headings in plan TOC

---
 .../Tools/ProposePlan/extractPlanHeadings.test.ts |  5 +++++
 .../Tools/ProposePlan/extractPlanHeadings.ts      | 15 +++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 4d9c5d545e..278cc6432a 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -151,6 +151,11 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("counts multiline raw HTML headings so later renderIndex values stay aligned", () => {
+    const md = `<h2>\nMultiline HTML heading\n</h2>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 1, level: 2, text: "Outside" }]);
+  });
+
   test("counts raw HTML headings so renderIndex stays aligned", () => {
     const md = `# Markdown one\n\n<h2>Inline HTML two</h2>\n\n### Markdown three`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 7f7965763c..200d69174b 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -96,6 +96,21 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       continue;
     }
 
+    const multilineHtmlHeadingMatch = /^<h([1-6])\b[^>]*>(?!.*<\/h\1>)/i.exec(structuralTrimmed);
+    if (multilineHtmlHeadingMatch) {
+      const level = multilineHtmlHeadingMatch[1];
+      // Multiline raw HTML headings render as hN elements, but collecting their
+      // display text would require a full HTML parse. Count the DOM node so
+      // later markdown headings keep correct renderIndex alignment.
+      renderIndex += 1;
+      htmlBlockState ??= {
+        closingPattern: new RegExp(`</h${level}>`, "i"),
+        terminatesOnBlank: false,
+        countsNestedHeadings: false,
+      };
+      continue;
+    }
+
     if (htmlBlockState) {
       if (htmlBlockTerminates(htmlBlockState, structuralTrimmed)) {
         htmlBlockState = null;

From fbaf1fe3c0f3feb73c9d2624c6342fb70b7f1131 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 21:06:59 -0500
Subject: [PATCH 13/32] Count inline raw HTML heading tags

---
 .../Tools/ProposePlan/extractPlanHeadings.test.ts | 10 ++++++++++
 .../Tools/ProposePlan/extractPlanHeadings.ts      | 15 +++++++--------
 2 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 278cc6432a..527ab5287c 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -151,6 +151,16 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("counts raw HTML heading tags with surrounding inline content", () => {
+    const md = `<h2>Intro</h2> trailing text\n<h2>A</h2><h3>B</h3>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Intro" },
+      { renderIndex: 1, level: 2, text: "A" },
+      { renderIndex: 2, level: 3, text: "B" },
+      { renderIndex: 3, level: 2, text: "Outside" },
+    ]);
+  });
+
   test("counts multiline raw HTML headings so later renderIndex values stay aligned", () => {
     const md = `<h2>\nMultiline HTML heading\n</h2>\n\n## Outside`;
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 1, level: 2, text: "Outside" }]);
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 200d69174b..3a4195f6c0 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -79,12 +79,12 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       continue;
     }
 
-    // Raw HTML heading on its own line (`<h2>Hello</h2>`). Streamdown emits these
-    // through rehype-raw, so we count them too to keep `renderIndex` aligned.
-    // Check this even while inside another raw HTML block (`<div>...</div>`),
-    // because nested h1-h6 tags still render into the same heading NodeList.
-    const htmlMatch = /^<h([1-6])\b[^>]*>(.*?)<\/h\1>\s*$/i.exec(structuralTrimmed);
-    if (htmlMatch) {
+    // Raw HTML h1-h6 tags render into the same heading NodeList even when they
+    // are nested in another HTML block or share a line with other HTML/text.
+    const htmlHeadingMatches = Array.from(
+      structuralTrimmed.matchAll(/<h([1-6])\b[^>]*>(.*?)<\/h\1>/gi)
+    );
+    for (const htmlMatch of htmlHeadingMatches) {
       const level = parseInt(htmlMatch[1], 10);
       const text = stripMarkdownFormatting(htmlMatch[2].replace(/<[^>]+>/g, ""));
       if (text) {
@@ -93,10 +93,9 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       // Empty raw HTML headings still render as hN elements, so they consume
       // an index even when they do not produce a useful TOC entry.
       renderIndex += 1;
-      continue;
     }
 
-    const multilineHtmlHeadingMatch = /^<h([1-6])\b[^>]*>(?!.*<\/h\1>)/i.exec(structuralTrimmed);
+    const multilineHtmlHeadingMatch = /<h([1-6])\b[^>]*>(?!.*<\/h\1>)/i.exec(structuralTrimmed);
     if (multilineHtmlHeadingMatch) {
       const level = multilineHtmlHeadingMatch[1];
       // Multiline raw HTML headings render as hN elements, but collecting their

From 3b5a99929f4f3a40da4664247afc5bdaa5fbcd8d Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 21:15:55 -0500
Subject: [PATCH 14/32] Preserve indentation for raw HTML headings

---
 .../ProposePlan/extractPlanHeadings.test.ts   | 13 +++
 .../Tools/ProposePlan/extractPlanHeadings.ts  | 87 +++++++++++++------
 2 files changed, 72 insertions(+), 28 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 527ab5287c..d5750583f4 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -151,6 +151,19 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("does not count four-space-indented raw HTML headings outside HTML blocks", () => {
+    const md = `    <h2>Code sample heading</h2>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
+  });
+
+  test("counts indented raw HTML headings inside raw HTML blocks", () => {
+    const md = `<div>\n    <h2>Inner HTML heading</h2>\n</div>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Inner HTML heading" },
+      { renderIndex: 1, level: 2, text: "Outside" },
+    ]);
+  });
+
   test("counts raw HTML heading tags with surrounding inline content", () => {
     const md = `<h2>Intro</h2> trailing text\n<h2>A</h2><h3>B</h3>\n\n## Outside`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 3a4195f6c0..00eafbb6e8 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -79,35 +79,35 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       continue;
     }
 
-    // Raw HTML h1-h6 tags render into the same heading NodeList even when they
-    // are nested in another HTML block or share a line with other HTML/text.
-    const htmlHeadingMatches = Array.from(
-      structuralTrimmed.matchAll(/<h([1-6])\b[^>]*>(.*?)<\/h\1>/gi)
-    );
-    for (const htmlMatch of htmlHeadingMatches) {
-      const level = parseInt(htmlMatch[1], 10);
-      const text = stripMarkdownFormatting(htmlMatch[2].replace(/<[^>]+>/g, ""));
-      if (text) {
-        headings.push({ renderIndex, level, text });
+    const htmlCandidateLine: string | null = htmlBlockState
+      ? structuralTrimmed
+      : getHtmlCandidateLine(structuralLine);
+
+    if (htmlCandidateLine != null) {
+      // Raw HTML h1-h6 tags render into the same heading NodeList even when they
+      // are nested in another HTML block or share a line with other HTML/text.
+      for (const htmlHeading of extractCompleteHtmlHeadings(htmlCandidateLine)) {
+        if (htmlHeading.text) {
+          headings.push({ renderIndex, level: htmlHeading.level, text: htmlHeading.text });
+        }
+        // Empty raw HTML headings still render as hN elements, so they consume
+        // an index even when they do not produce a useful TOC entry.
+        renderIndex += 1;
       }
-      // Empty raw HTML headings still render as hN elements, so they consume
-      // an index even when they do not produce a useful TOC entry.
-      renderIndex += 1;
-    }
 
-    const multilineHtmlHeadingMatch = /<h([1-6])\b[^>]*>(?!.*<\/h\1>)/i.exec(structuralTrimmed);
-    if (multilineHtmlHeadingMatch) {
-      const level = multilineHtmlHeadingMatch[1];
-      // Multiline raw HTML headings render as hN elements, but collecting their
-      // display text would require a full HTML parse. Count the DOM node so
-      // later markdown headings keep correct renderIndex alignment.
-      renderIndex += 1;
-      htmlBlockState ??= {
-        closingPattern: new RegExp(`</h${level}>`, "i"),
-        terminatesOnBlank: false,
-        countsNestedHeadings: false,
-      };
-      continue;
+      const multilineHtmlHeadingLevel = getMultilineHtmlHeadingLevel(htmlCandidateLine);
+      if (multilineHtmlHeadingLevel != null) {
+        // Multiline raw HTML headings render as hN elements, but collecting their
+        // display text would require a full HTML parse. Count the DOM node so
+        // later markdown headings keep correct renderIndex alignment.
+        renderIndex += 1;
+        htmlBlockState ??= {
+          closingPattern: new RegExp(`</h${multilineHtmlHeadingLevel}>`, "i"),
+          terminatesOnBlank: false,
+          countsNestedHeadings: false,
+        };
+        continue;
+      }
     }
 
     if (htmlBlockState) {
@@ -117,7 +117,9 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       continue;
     }
 
-    const htmlBlockStart = getHtmlBlockStart(structuralTrimmed);
+    const htmlBlockStart: HtmlBlockState | null = htmlCandidateLine
+      ? getHtmlBlockStart(htmlCandidateLine)
+      : null;
     if (htmlBlockStart) {
       if (!htmlBlockTerminates(htmlBlockStart, structuralTrimmed)) {
         htmlBlockState = htmlBlockStart;
@@ -189,6 +191,35 @@ const HTML_BLOCK_TAGS =
   "address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|search|section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul";
 const HTML_BLOCK_TAG_PATTERN = new RegExp(`^</?(?:${HTML_BLOCK_TAGS})(?=[\\s>/])`, "i");
 
+interface CompleteHtmlHeading {
+  level: number;
+  text: string;
+}
+
+function extractCompleteHtmlHeadings(line: string): CompleteHtmlHeading[] {
+  const headings: CompleteHtmlHeading[] = [];
+  const headingPattern = /<h([1-6])\b[^>]*>(.*?)<\/h\1>/gi;
+  let match = headingPattern.exec(line);
+  while (match) {
+    headings.push({
+      level: parseInt(match[1], 10),
+      text: stripMarkdownFormatting(match[2].replace(/<[^>]+>/g, "")),
+    });
+    match = headingPattern.exec(line);
+  }
+  return headings;
+}
+
+function getMultilineHtmlHeadingLevel(line: string): string | null {
+  const match = /<h([1-6])\b[^>]*>(?!.*<\/h\1>)/i.exec(line);
+  return match ? match[1] : null;
+}
+
+function getHtmlCandidateLine(line: string): string | null {
+  const match = /^ {0,3}(?! )(.*)$/.exec(line);
+  return match ? match[1].trim() : null;
+}
+
 function getHtmlBlockStart(trimmedLine: string): HtmlBlockState | null {
   const pairedTagMatch = /^<(script|pre|style)(?=[\s>])/i.exec(trimmedLine);
   if (pairedTagMatch) {

From 794cc557bc6e8c1e84848791c558c697ee7f3509 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 21:22:53 -0500
Subject: [PATCH 15/32] Skip non-rendered raw HTML heading markup

---
 .../Tools/ProposePlan/extractPlanHeadings.test.ts   |  5 +++++
 .../Tools/ProposePlan/extractPlanHeadings.ts        | 13 ++++++++++---
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index d5750583f4..196d5432d7 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -138,6 +138,11 @@ describe("extractPlanHeadings", () => {
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Actual heading" }]);
   });
 
+  test("does not count heading markup inside single-line non-rendered HTML contexts", () => {
+    const md = `<!-- <h2>Comment heading</h2> -->\n<script><h2>Script heading</h2></script>\n<style><h2>Style heading</h2></style>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
+  });
+
   test("does not count HTML-looking headings inside script or style blocks", () => {
     const md = `<script>\n<h2>Hidden script heading</h2>\n</script>\n\n<style>\n<h3>Hidden style heading</h3>\n</style>\n\n## Outside`;
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 00eafbb6e8..ae478c476c 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -83,6 +83,16 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       ? structuralTrimmed
       : getHtmlCandidateLine(structuralLine);
 
+    const htmlBlockStart: HtmlBlockState | null = htmlCandidateLine
+      ? getHtmlBlockStart(htmlCandidateLine)
+      : null;
+    if (htmlBlockStart && !htmlBlockStart.countsNestedHeadings) {
+      if (!htmlBlockTerminates(htmlBlockStart, structuralTrimmed)) {
+        htmlBlockState = htmlBlockStart;
+      }
+      continue;
+    }
+
     if (htmlCandidateLine != null) {
       // Raw HTML h1-h6 tags render into the same heading NodeList even when they
       // are nested in another HTML block or share a line with other HTML/text.
@@ -117,9 +127,6 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       continue;
     }
 
-    const htmlBlockStart: HtmlBlockState | null = htmlCandidateLine
-      ? getHtmlBlockStart(htmlCandidateLine)
-      : null;
     if (htmlBlockStart) {
       if (!htmlBlockTerminates(htmlBlockStart, structuralTrimmed)) {
         htmlBlockState = htmlBlockStart;

From 7c94d9f19a4164499edf9abeccf71dc3464ce463 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 21:28:11 -0500
Subject: [PATCH 16/32] Match CommonMark type1 HTML block endings

---
 .../features/Tools/ProposePlan/extractPlanHeadings.test.ts   | 5 +++++
 .../features/Tools/ProposePlan/extractPlanHeadings.ts        | 5 ++---
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 196d5432d7..89883bb41f 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -143,6 +143,11 @@ describe("extractPlanHeadings", () => {
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
   });
 
+  test("ends script/pre/style HTML blocks on any type-1 closing tag", () => {
+    const md = `<script>\n<h2>Hidden script heading</h2>\n</style>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
+  });
+
   test("does not count HTML-looking headings inside script or style blocks", () => {
     const md = `<script>\n<h2>Hidden script heading</h2>\n</script>\n\n<style>\n<h3>Hidden style heading</h3>\n</style>\n\n## Outside`;
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index ae478c476c..9193e09642 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -228,10 +228,9 @@ function getHtmlCandidateLine(line: string): string | null {
 }
 
 function getHtmlBlockStart(trimmedLine: string): HtmlBlockState | null {
-  const pairedTagMatch = /^<(script|pre|style)(?=[\s>])/i.exec(trimmedLine);
-  if (pairedTagMatch) {
+  if (/^<(?:script|pre|style)(?=[\s>])/i.test(trimmedLine)) {
     return {
-      closingPattern: new RegExp(`</${pairedTagMatch[1]}>`, "i"),
+      closingPattern: /<\/(?:script|pre|style)>/i,
       terminatesOnBlank: false,
       countsNestedHeadings: false,
     };

From a52c7cd5036d1449d75ca5e118fe432766f75cbc Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 21:33:33 -0500
Subject: [PATCH 17/32] Loosen type1 HTML block boundary parsing

---
 .../features/Tools/ProposePlan/extractPlanHeadings.test.ts    | 2 +-
 src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 89883bb41f..03391acb95 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -144,7 +144,7 @@ describe("extractPlanHeadings", () => {
   });
 
   test("ends script/pre/style HTML blocks on any type-1 closing tag", () => {
-    const md = `<script>\n<h2>Hidden script heading</h2>\n</style>\n\n## Outside`;
+    const md = `<script\n<h2>Hidden script heading</h2>\n</style   >\n\n## Outside`;
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
   });
 
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 9193e09642..60c0210156 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -228,9 +228,9 @@ function getHtmlCandidateLine(line: string): string | null {
 }
 
 function getHtmlBlockStart(trimmedLine: string): HtmlBlockState | null {
-  if (/^<(?:script|pre|style)(?=[\s>])/i.test(trimmedLine)) {
+  if (/^<(?:script|pre|style)(?=[\s>]|$)/i.test(trimmedLine)) {
     return {
-      closingPattern: /<\/(?:script|pre|style)>/i,
+      closingPattern: /<\/(?:script|pre|style)\s*>/i,
       terminatesOnBlank: false,
       countsNestedHeadings: false,
     };

From c6b4e3d62256a380e6df8eb952b8124a816ff6da Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 21:40:12 -0500
Subject: [PATCH 18/32] Preserve list code indentation in plan TOC

---
 .../Tools/ProposePlan/extractPlanHeadings.test.ts  |  5 +++++
 .../Tools/ProposePlan/extractPlanHeadings.ts       | 14 ++++++++++++--
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 03391acb95..b2b76396de 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -87,6 +87,11 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("does not count list-contained indented code as headings", () => {
+    const md = `-     # Not a heading\n1.     ## Not a heading either\n\n## Visible`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Visible" }]);
+  });
+
   test("skips headings inside container-prefixed fenced code blocks", () => {
     const md = `> \`\`\`markdown\n> # Hidden quoted heading\n> \`\`\`\n\n- \`\`\`markdown\n  ## Hidden list heading\n  \`\`\`\n\n## Visible`;
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Visible" }]);
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 60c0210156..fbae413982 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -283,15 +283,21 @@ function stripAtxContainerPrefixes(line: string): string {
       continue;
     }
 
-    const unorderedListMatch = /^ {0,3}[-+*][ \t]+/.exec(remaining);
+    const unorderedListMatch = /^( {0,3}[-+*])([ \t]+)/.exec(remaining);
     if (unorderedListMatch) {
+      if (isIndentedListCodePrefix(unorderedListMatch[2])) {
+        return remaining;
+      }
       remaining = remaining.slice(unorderedListMatch[0].length);
       changed = true;
       continue;
     }
 
-    const orderedListMatch = /^ {0,3}\d{1,9}[.)][ \t]+/.exec(remaining);
+    const orderedListMatch = /^( {0,3}\d{1,9}[.)])([ \t]+)/.exec(remaining);
     if (orderedListMatch) {
+      if (isIndentedListCodePrefix(orderedListMatch[2])) {
+        return remaining;
+      }
       remaining = remaining.slice(orderedListMatch[0].length);
       changed = true;
     }
@@ -299,6 +305,10 @@ function stripAtxContainerPrefixes(line: string): string {
   return remaining;
 }
 
+function isIndentedListCodePrefix(spacesAfterMarker: string): boolean {
+  return spacesAfterMarker.includes("\t") || spacesAfterMarker.length > 4;
+}
+
 function stripBlockquotePrefixes(line: string): string {
   let remaining = line;
   while (true) {

From 5dfb6cc1ec65bb9d00ed7f7e6d9392882dcc0a14 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 21:46:33 -0500
Subject: [PATCH 19/32] Reject tab-indented HTML headings in plan TOC

---
 .../features/Tools/ProposePlan/extractPlanHeadings.test.ts   | 5 +++++
 .../features/Tools/ProposePlan/extractPlanHeadings.ts        | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index b2b76396de..d13df510b2 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -166,6 +166,11 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("does not count tab-indented raw HTML headings outside HTML blocks", () => {
+    const md = `\t<h2>Code sample heading</h2>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
+  });
+
   test("does not count four-space-indented raw HTML headings outside HTML blocks", () => {
     const md = `    <h2>Code sample heading</h2>\n\n## Outside`;
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index fbae413982..a288f62fe2 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -223,7 +223,7 @@ function getMultilineHtmlHeadingLevel(line: string): string | null {
 }
 
 function getHtmlCandidateLine(line: string): string | null {
-  const match = /^ {0,3}(?! )(.*)$/.exec(line);
+  const match = /^ {0,3}(?![ \t])(.*)$/.exec(line);
   return match ? match[1].trim() : null;
 }
 

From ea70a278a0747f949def5d74e07e77b93ecb69f5 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 21:53:43 -0500
Subject: [PATCH 20/32] Allow setext punctuation headings in plan TOC

---
 .../Tools/ProposePlan/extractPlanHeadings.test.ts  |  9 +++++++++
 .../Tools/ProposePlan/extractPlanHeadings.ts       | 14 +++++++++++---
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index d13df510b2..3f7feef31b 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -131,6 +131,15 @@ describe("extractPlanHeadings", () => {
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "After" }]);
   });
 
+  test("allows setext text that starts with list punctuation but is not a list", () => {
+    const md = `-foo\n---\n\n+bar\n===\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "-foo" },
+      { renderIndex: 1, level: 1, text: "+bar" },
+      { renderIndex: 2, level: 2, text: "After" },
+    ]);
+  });
+
   test("does not confuse thematic breaks with setext underlines", () => {
     const md = `Some intro paragraph.\n\n---\n\n# Heading`;
     // The `---` here is preceded by a blank line, so it's a thematic break, not
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index a288f62fe2..c43dff7eb3 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -159,9 +159,7 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
     if (
       i + 1 < lines.length &&
       /^ {0,3}\S/.test(blockquoteLine) &&
-      blockquoteTrimmed.length > 0 &&
-      !/^[#>\-*+`~<]/.test(blockquoteTrimmed) &&
-      !/^\d{1,9}[.)][ \t]/.test(blockquoteTrimmed)
+      isSetextTextCandidate(blockquoteTrimmed)
     ) {
       const nextSetextLine = stripBlockquotePrefixes(lines[i + 1]);
       if (/^ {0,3}=+[ \t]*$/.test(nextSetextLine)) {
@@ -198,6 +196,16 @@ const HTML_BLOCK_TAGS =
   "address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|search|section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul";
 const HTML_BLOCK_TAG_PATTERN = new RegExp(`^</?(?:${HTML_BLOCK_TAGS})(?=[\\s>/])`, "i");
 
+function isSetextTextCandidate(text: string): boolean {
+  return (
+    text.length > 0 &&
+    !/^[-+*][ \t]/.test(text) &&
+    !/^\d{1,9}[.)][ \t]/.test(text) &&
+    !/^(`{3,}|~{3,})/.test(text) &&
+    !/^<[^>]+>/.test(text)
+  );
+}
+
 interface CompleteHtmlHeading {
   level: number;
   text: string;

From 1685df83a1a701c9c3109b969acabfa85de0abf3 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 22:02:19 -0500
Subject: [PATCH 21/32] Parse multiline setext plan headings

---
 .../ProposePlan/extractPlanHeadings.test.ts   | 16 ++++
 .../Tools/ProposePlan/extractPlanHeadings.ts  | 84 ++++++++++---------
 2 files changed, 61 insertions(+), 39 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 3f7feef31b..2b4c2e3cce 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -105,6 +105,22 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("combines multi-line setext heading text", () => {
+    const md = `Foo\nBar\n---\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Foo Bar" },
+      { renderIndex: 1, level: 2, text: "After" },
+    ]);
+  });
+
+  test("allows inline HTML paragraph text as a setext heading", () => {
+    const md = `<em>Roadmap</em>\n---\n\n## After`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Roadmap" },
+      { renderIndex: 1, level: 2, text: "After" },
+    ]);
+  });
+
   test("recognizes setext headings inside blockquotes", () => {
     const md = `> Quoted title\n> ===\n\n## After`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index c43dff7eb3..9f50df48f0 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -44,9 +44,6 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
     const line = lines[i];
     const structuralLine = stripAtxContainerPrefixes(line);
     const structuralTrimmed = structuralLine.trim();
-    const blockquoteLine = stripBlockquotePrefixes(line);
-    const blockquoteTrimmed = blockquoteLine.trim();
-
     // Track fenced code blocks. CommonMark allows up to three leading spaces
     // before a fence; four spaces are indented code, not a fence. We also strip
     // container markers so quoted/list-contained fences suppress headings inside
@@ -151,34 +148,17 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       continue;
     }
 
-    // Setext heading: text line followed by === (h1) or --- (h2). Skip blank
-    // text lines and list/fence/thematic-break starters so we don't invent a
-    // heading where markdown renders a list item or horizontal rule instead.
-    // Preserve underline indentation: a 4-space-indented underline is code, not
-    // a heading marker, so trimming it would create phantom headings.
-    if (
-      i + 1 < lines.length &&
-      /^ {0,3}\S/.test(blockquoteLine) &&
-      isSetextTextCandidate(blockquoteTrimmed)
-    ) {
-      const nextSetextLine = stripBlockquotePrefixes(lines[i + 1]);
-      if (/^ {0,3}=+[ \t]*$/.test(nextSetextLine)) {
-        const text = stripMarkdownFormatting(blockquoteTrimmed);
-        if (text) {
-          headings.push({ renderIndex, level: 1, text });
-          renderIndex += 1;
-          i += 1; // consume the underline
-          continue;
-        }
-      }
-      if (/^ {0,3}-{2,}[ \t]*$/.test(nextSetextLine)) {
-        const text = stripMarkdownFormatting(blockquoteTrimmed);
-        if (text) {
-          headings.push({ renderIndex, level: 2, text });
-          renderIndex += 1;
-          i += 1; // consume the underline
-          continue;
-        }
+    // Setext heading: one or more paragraph lines followed by === (h1) or ---
+    // (h2). Preserve underline indentation: a 4-space-indented underline is
+    // code, not a heading marker, so trimming it would create phantom headings.
+    const setextHeading = getSetextHeadingAt(lines, i);
+    if (setextHeading) {
+      const text = stripMarkdownFormatting(setextHeading.text);
+      if (text) {
+        headings.push({ renderIndex, level: setextHeading.level, text });
+        renderIndex += 1;
+        i = setextHeading.underlineIndex;
+        continue;
       }
     }
   }
@@ -202,10 +182,43 @@ function isSetextTextCandidate(text: string): boolean {
     !/^[-+*][ \t]/.test(text) &&
     !/^\d{1,9}[.)][ \t]/.test(text) &&
     !/^(`{3,}|~{3,})/.test(text) &&
-    !/^<[^>]+>/.test(text)
+    !isSetextHtmlBlockLine(text)
   );
 }
 
+interface SetextHeadingMatch {
+  level: 1 | 2;
+  text: string;
+  underlineIndex: number;
+}
+
+function getSetextHeadingAt(lines: string[], startIndex: number): SetextHeadingMatch | null {
+  const textParts: string[] = [];
+  for (let i = startIndex; i < lines.length; i++) {
+    const line = stripBlockquotePrefixes(lines[i]);
+    const trimmed = line.trim();
+
+    if (textParts.length > 0) {
+      if (/^ {0,3}=+[ \t]*$/.test(line)) {
+        return { level: 1, text: textParts.join(" "), underlineIndex: i };
+      }
+      if (/^ {0,3}-{2,}[ \t]*$/.test(line)) {
+        return { level: 2, text: textParts.join(" "), underlineIndex: i };
+      }
+    }
+
+    if (!/^ {0,3}\S/.test(line) || !isSetextTextCandidate(trimmed)) {
+      return null;
+    }
+    textParts.push(trimmed);
+  }
+  return null;
+}
+
+function isSetextHtmlBlockLine(text: string): boolean {
+  return getHtmlBlockStart(text) != null;
+}
+
 interface CompleteHtmlHeading {
   level: number;
   text: string;
@@ -261,13 +274,6 @@ function getHtmlBlockStart(trimmedLine: string): HtmlBlockState | null {
     return { terminatesOnBlank: true, countsNestedHeadings: true };
   }
 
-  // CommonMark also treats a complete open/closing HTML tag on its own line as
-  // an HTML block. Raw h1-h6 lines are handled above so they still count toward
-  // renderIndex.
-  if (/^<\/?[A-Za-z][A-Za-z0-9-]*(?:\s+[^<>]*)?>\s*$/.test(trimmedLine)) {
-    return { terminatesOnBlank: true, countsNestedHeadings: true };
-  }
-
   return null;
 }
 

From 0f7664e68e0f2fee4bdea4a9a794376166c833a8 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 22:11:23 -0500
Subject: [PATCH 22/32] Use markdown parser for plan TOC extraction

---
 .../ProposePlan/extractPlanHeadings.test.ts   |  10 +-
 .../Tools/ProposePlan/extractPlanHeadings.ts  | 327 +++---------------
 2 files changed, 49 insertions(+), 288 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 2b4c2e3cce..354ca7ec2f 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -173,11 +173,6 @@ describe("extractPlanHeadings", () => {
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
   });
 
-  test("ends script/pre/style HTML blocks on any type-1 closing tag", () => {
-    const md = `<script\n<h2>Hidden script heading</h2>\n</style   >\n\n## Outside`;
-    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
-  });
-
   test("does not count HTML-looking headings inside script or style blocks", () => {
     const md = `<script>\n<h2>Hidden script heading</h2>\n</script>\n\n<style>\n<h3>Hidden style heading</h3>\n</style>\n\n## Outside`;
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
@@ -221,7 +216,10 @@ describe("extractPlanHeadings", () => {
 
   test("counts multiline raw HTML headings so later renderIndex values stay aligned", () => {
     const md = `<h2>\nMultiline HTML heading\n</h2>\n\n## Outside`;
-    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 1, level: 2, text: "Outside" }]);
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Multiline HTML heading" },
+      { renderIndex: 1, level: 2, text: "Outside" },
+    ]);
   });
 
   test("counts raw HTML headings so renderIndex stays aligned", () => {
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 9f50df48f0..5cd99845ca 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -1,3 +1,5 @@
+import MarkdownIt from "markdown-it";
+
 /**
  * A heading entry extracted from a plan's markdown source.
  *
@@ -15,150 +17,57 @@ export interface PlanHeading {
   text: string;
 }
 
+interface HtmlHeading {
+  level: number;
+  text: string;
+}
+
+const markdownParser = new MarkdownIt({ html: true, linkify: false, typographer: false });
+const HTML_HEADING_PATTERN = /<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1\s*>/gi;
+const NON_RENDERED_HTML_BLOCK_PATTERN =
+  /<!--([\s\S]*?)(?:-->|$)|<\?(?:[\s\S]*?)(?:\?>|$)|<!\[CDATA\[(?:[\s\S]*?)(?:\]\]>|$)|<![A-Z][\s\S]*?(?:>|$)|<(?:script|pre|style)(?=[\s>]|$)[\s\S]*?(?:<\/(?:script|pre|style)\s*>|$)/gi;
+
 /**
  * Extract heading entries from a plan's markdown source.
  *
- * Supports ATX headings (`# Heading`, with optional trailing `#` markers), setext
- * headings (a text line followed by `===` or `---`), and raw HTML headings on
- * their own line (`<h2>...</h2>`). Skips lines inside fenced code blocks
- * (``` or ~~~) so example markdown inside code samples never shows up in the TOC.
- *
- * The output indices line up with what Streamdown / remark-gfm will render so
- * `renderIndex` can be used to locate the matching DOM element by order.
+ * Markdown block structure is delegated to markdown-it so ATX, setext,
+ * blockquote/list containers, indented code, and fenced code stay aligned with
+ * the rendered markdown. Raw HTML h1-h6 tags are counted separately because the
+ * renderer allows raw HTML and those tags also appear in the heading NodeList.
  */
 export function extractPlanHeadings(markdown: string): PlanHeading[] {
   if (!markdown) {
     return [];
   }
 
-  const lines = markdown.split("\n");
+  const tokens = markdownParser.parse(markdown, {});
   const headings: PlanHeading[] = [];
-
-  let inFence = false;
-  let fenceChar: "`" | "~" | null = null;
-  let fenceLength = 0;
-  let htmlBlockState: HtmlBlockState | null = null;
   let renderIndex = 0;
 
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const structuralLine = stripAtxContainerPrefixes(line);
-    const structuralTrimmed = structuralLine.trim();
-    // Track fenced code blocks. CommonMark allows up to three leading spaces
-    // before a fence; four spaces are indented code, not a fence. We also strip
-    // container markers so quoted/list-contained fences suppress headings inside
-    // them the same way the markdown renderer does.
-    const fenceMatch = /^ {0,3}(`{3,}|~{3,})/.exec(structuralLine);
-    if (fenceMatch) {
-      const marker = fenceMatch[1];
-      const ch = marker[0] as "`" | "~";
-      const len = marker.length;
-      if (!inFence) {
-        inFence = true;
-        fenceChar = ch;
-        fenceLength = len;
-      } else if (ch === fenceChar && len >= fenceLength && /^[`~]+\s*$/.test(structuralTrimmed)) {
-        inFence = false;
-        fenceChar = null;
-        fenceLength = 0;
-      }
-      continue;
-    }
-
-    if (inFence) {
-      continue;
-    }
-
-    if (htmlBlockState && !htmlBlockState.countsNestedHeadings) {
-      if (htmlBlockTerminates(htmlBlockState, structuralTrimmed)) {
-        htmlBlockState = null;
-      }
-      continue;
-    }
-
-    const htmlCandidateLine: string | null = htmlBlockState
-      ? structuralTrimmed
-      : getHtmlCandidateLine(structuralLine);
-
-    const htmlBlockStart: HtmlBlockState | null = htmlCandidateLine
-      ? getHtmlBlockStart(htmlCandidateLine)
-      : null;
-    if (htmlBlockStart && !htmlBlockStart.countsNestedHeadings) {
-      if (!htmlBlockTerminates(htmlBlockStart, structuralTrimmed)) {
-        htmlBlockState = htmlBlockStart;
-      }
-      continue;
-    }
-
-    if (htmlCandidateLine != null) {
-      // Raw HTML h1-h6 tags render into the same heading NodeList even when they
-      // are nested in another HTML block or share a line with other HTML/text.
-      for (const htmlHeading of extractCompleteHtmlHeadings(htmlCandidateLine)) {
-        if (htmlHeading.text) {
-          headings.push({ renderIndex, level: htmlHeading.level, text: htmlHeading.text });
-        }
-        // Empty raw HTML headings still render as hN elements, so they consume
-        // an index even when they do not produce a useful TOC entry.
-        renderIndex += 1;
-      }
-
-      const multilineHtmlHeadingLevel = getMultilineHtmlHeadingLevel(htmlCandidateLine);
-      if (multilineHtmlHeadingLevel != null) {
-        // Multiline raw HTML headings render as hN elements, but collecting their
-        // display text would require a full HTML parse. Count the DOM node so
-        // later markdown headings keep correct renderIndex alignment.
-        renderIndex += 1;
-        htmlBlockState ??= {
-          closingPattern: new RegExp(`</h${multilineHtmlHeadingLevel}>`, "i"),
-          terminatesOnBlank: false,
-          countsNestedHeadings: false,
-        };
-        continue;
-      }
-    }
-
-    if (htmlBlockState) {
-      if (htmlBlockTerminates(htmlBlockState, structuralTrimmed)) {
-        htmlBlockState = null;
-      }
-      continue;
-    }
-
-    if (htmlBlockStart) {
-      if (!htmlBlockTerminates(htmlBlockStart, structuralTrimmed)) {
-        htmlBlockState = htmlBlockStart;
-      }
-      continue;
-    }
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
 
-    // ATX heading: up to three leading spaces, then 1-6 `#`s. Four leading
-    // spaces are indented code, so matching them would drift from markdown's
-    // rendered h1..h6 order.
-    const atxMatch = /^ {0,3}(#{1,6})(?:[ \t]+(.*)|[ \t]*)$/.exec(structuralLine);
-    if (atxMatch) {
-      const level = atxMatch[1].length;
-      const rawText = (atxMatch[2] ?? "").replace(/[ \t]+#+[ \t]*$/, "");
-      const text = stripMarkdownFormatting(rawText);
+    if (token.type === "heading_open") {
+      const level = parseHeadingLevel(token.tag);
+      const inline = tokens[i + 1];
+      const text = stripMarkdownFormatting(inline?.type === "inline" ? inline.content : "");
       if (text) {
         headings.push({ renderIndex, level, text });
       }
-      // Empty headings still render as hN elements, so they must consume a
-      // renderIndex even though they are not useful TOC entries.
+      // Empty markdown headings still render hN elements, so they consume an
+      // index even when they do not produce a useful TOC entry.
       renderIndex += 1;
       continue;
     }
 
-    // Setext heading: one or more paragraph lines followed by === (h1) or ---
-    // (h2). Preserve underline indentation: a 4-space-indented underline is
-    // code, not a heading marker, so trimming it would create phantom headings.
-    const setextHeading = getSetextHeadingAt(lines, i);
-    if (setextHeading) {
-      const text = stripMarkdownFormatting(setextHeading.text);
-      if (text) {
-        headings.push({ renderIndex, level: setextHeading.level, text });
+    if (token.type === "html_block" || token.type === "html_inline") {
+      for (const htmlHeading of extractHtmlHeadings(token.content)) {
+        if (htmlHeading.text) {
+          headings.push({ renderIndex, level: htmlHeading.level, text: htmlHeading.text });
+        }
+        // Empty raw HTML headings still render hN elements, so they consume an
+        // index even when they do not produce a useful TOC entry.
         renderIndex += 1;
-        i = setextHeading.underlineIndex;
-        continue;
       }
     }
   }
@@ -166,182 +75,36 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
   return headings;
 }
 
-interface HtmlBlockState {
-  closingPattern?: RegExp;
-  terminatesOnBlank: boolean;
-  countsNestedHeadings: boolean;
+function parseHeadingLevel(tag: string): number {
+  const level = Number(tag.replace(/^h/i, ""));
+  return level >= 1 && level <= 6 ? level : 1;
 }
 
-const HTML_BLOCK_TAGS =
-  "address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|nav|noframes|ol|optgroup|option|p|param|search|section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul";
-const HTML_BLOCK_TAG_PATTERN = new RegExp(`^</?(?:${HTML_BLOCK_TAGS})(?=[\\s>/])`, "i");
+function extractHtmlHeadings(html: string): HtmlHeading[] {
+  const renderedHtml = html.replace(NON_RENDERED_HTML_BLOCK_PATTERN, "");
+  const headings: HtmlHeading[] = [];
+  HTML_HEADING_PATTERN.lastIndex = 0;
 
-function isSetextTextCandidate(text: string): boolean {
-  return (
-    text.length > 0 &&
-    !/^[-+*][ \t]/.test(text) &&
-    !/^\d{1,9}[.)][ \t]/.test(text) &&
-    !/^(`{3,}|~{3,})/.test(text) &&
-    !isSetextHtmlBlockLine(text)
-  );
-}
-
-interface SetextHeadingMatch {
-  level: 1 | 2;
-  text: string;
-  underlineIndex: number;
-}
-
-function getSetextHeadingAt(lines: string[], startIndex: number): SetextHeadingMatch | null {
-  const textParts: string[] = [];
-  for (let i = startIndex; i < lines.length; i++) {
-    const line = stripBlockquotePrefixes(lines[i]);
-    const trimmed = line.trim();
-
-    if (textParts.length > 0) {
-      if (/^ {0,3}=+[ \t]*$/.test(line)) {
-        return { level: 1, text: textParts.join(" "), underlineIndex: i };
-      }
-      if (/^ {0,3}-{2,}[ \t]*$/.test(line)) {
-        return { level: 2, text: textParts.join(" "), underlineIndex: i };
-      }
-    }
-
-    if (!/^ {0,3}\S/.test(line) || !isSetextTextCandidate(trimmed)) {
-      return null;
-    }
-    textParts.push(trimmed);
-  }
-  return null;
-}
-
-function isSetextHtmlBlockLine(text: string): boolean {
-  return getHtmlBlockStart(text) != null;
-}
-
-interface CompleteHtmlHeading {
-  level: number;
-  text: string;
-}
-
-function extractCompleteHtmlHeadings(line: string): CompleteHtmlHeading[] {
-  const headings: CompleteHtmlHeading[] = [];
-  const headingPattern = /<h([1-6])\b[^>]*>(.*?)<\/h\1>/gi;
-  let match = headingPattern.exec(line);
+  let match = HTML_HEADING_PATTERN.exec(renderedHtml);
   while (match) {
     headings.push({
       level: parseInt(match[1], 10),
       text: stripMarkdownFormatting(match[2].replace(/<[^>]+>/g, "")),
     });
-    match = headingPattern.exec(line);
-  }
-  return headings;
-}
-
-function getMultilineHtmlHeadingLevel(line: string): string | null {
-  const match = /<h([1-6])\b[^>]*>(?!.*<\/h\1>)/i.exec(line);
-  return match ? match[1] : null;
-}
-
-function getHtmlCandidateLine(line: string): string | null {
-  const match = /^ {0,3}(?![ \t])(.*)$/.exec(line);
-  return match ? match[1].trim() : null;
-}
-
-function getHtmlBlockStart(trimmedLine: string): HtmlBlockState | null {
-  if (/^<(?:script|pre|style)(?=[\s>]|$)/i.test(trimmedLine)) {
-    return {
-      closingPattern: /<\/(?:script|pre|style)\s*>/i,
-      terminatesOnBlank: false,
-      countsNestedHeadings: false,
-    };
-  }
-
-  if (trimmedLine.startsWith("<!--")) {
-    return { closingPattern: /-->/, terminatesOnBlank: false, countsNestedHeadings: false };
-  }
-  if (trimmedLine.startsWith("<?")) {
-    return { closingPattern: /\?>/, terminatesOnBlank: false, countsNestedHeadings: false };
-  }
-  if (/^<![A-Z]/.test(trimmedLine)) {
-    return { closingPattern: />/, terminatesOnBlank: false, countsNestedHeadings: false };
-  }
-  if (trimmedLine.startsWith("<![CDATA[")) {
-    return { closingPattern: /\]\]>/, terminatesOnBlank: false, countsNestedHeadings: false };
+    match = HTML_HEADING_PATTERN.exec(renderedHtml);
   }
 
-  if (HTML_BLOCK_TAG_PATTERN.test(trimmedLine)) {
-    return { terminatesOnBlank: true, countsNestedHeadings: true };
-  }
-
-  return null;
-}
-
-function htmlBlockTerminates(state: HtmlBlockState, trimmedLine: string): boolean {
-  if (state.closingPattern) {
-    return state.closingPattern.test(trimmedLine);
-  }
-  return state.terminatesOnBlank && trimmedLine.length === 0;
-}
-
-function stripAtxContainerPrefixes(line: string): string {
-  let remaining = line;
-  let changed = true;
-  while (changed) {
-    changed = false;
-
-    const blockquoteMatch = /^ {0,3}>[ \t]?/.exec(remaining);
-    if (blockquoteMatch) {
-      remaining = remaining.slice(blockquoteMatch[0].length);
-      changed = true;
-      continue;
-    }
-
-    const unorderedListMatch = /^( {0,3}[-+*])([ \t]+)/.exec(remaining);
-    if (unorderedListMatch) {
-      if (isIndentedListCodePrefix(unorderedListMatch[2])) {
-        return remaining;
-      }
-      remaining = remaining.slice(unorderedListMatch[0].length);
-      changed = true;
-      continue;
-    }
-
-    const orderedListMatch = /^( {0,3}\d{1,9}[.)])([ \t]+)/.exec(remaining);
-    if (orderedListMatch) {
-      if (isIndentedListCodePrefix(orderedListMatch[2])) {
-        return remaining;
-      }
-      remaining = remaining.slice(orderedListMatch[0].length);
-      changed = true;
-    }
-  }
-  return remaining;
-}
-
-function isIndentedListCodePrefix(spacesAfterMarker: string): boolean {
-  return spacesAfterMarker.includes("\t") || spacesAfterMarker.length > 4;
-}
-
-function stripBlockquotePrefixes(line: string): string {
-  let remaining = line;
-  while (true) {
-    const blockquoteMatch = /^ {0,3}>[ \t]?/.exec(remaining);
-    if (!blockquoteMatch) {
-      return remaining;
-    }
-    remaining = remaining.slice(blockquoteMatch[0].length);
-  }
+  return headings;
 }
 
 /**
  * Lightweight inline-formatting stripper used only for TOC display text. Not a
- * full markdown parser — we trade exhaustive correctness for predictable output
- * on the small subset of inline syntax that shows up in heading lines.
+ * full markdown parser — markdown-it has already handled block structure; this
+ * only normalizes raw HTML heading text and a few markdown-ish inline remnants.
  */
 function stripMarkdownFormatting(text: string): string {
   return text
-    .replace(/\\([\\`*_{}[\]()#+\-.!|~])/g, "$1") // unescape \*  \[ etc.
+    .replace(/\\([\\`*_{}\x5B\]()#+\-.!|~])/g, "$1") // unescape \*  \[ etc.
     .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1") // ![alt](src)
     .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") // [label](href)
     .replace(/`([^`]+)`/g, "$1") // `code`

From 0d97834972a4882b7150c0c16dc884d95deb1241 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 22:13:04 -0500
Subject: [PATCH 23/32] Rerun PR checks after resolving review


From d803b2ef9409a82fd590376a099afba0cff3c977 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 22:20:03 -0500
Subject: [PATCH 24/32] Respect raw HTML allowlist in plan TOC

---
 .../features/Tools/ProposePlan/extractPlanHeadings.test.ts   | 5 +++++
 .../features/Tools/ProposePlan/extractPlanHeadings.ts        | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 354ca7ec2f..4786eea9e9 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -178,6 +178,11 @@ describe("extractPlanHeadings", () => {
     expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
   });
 
+  test("ignores headings inside unsupported raw HTML blocks", () => {
+    const md = `<custom><h2>Unsupported</h2></custom>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([{ renderIndex: 0, level: 2, text: "Outside" }]);
+  });
+
   test("counts raw HTML headings nested inside raw HTML blocks", () => {
     const md = `<div>\n<h2>Inner HTML heading</h2>\n</div>\n\n## Outside`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 5cd99845ca..e5b52ac623 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -1,3 +1,4 @@
+import { rawHtmlUsesOnlyAllowedTags } from "@/browser/features/Messages/MarkdownCore";
 import MarkdownIt from "markdown-it";
 
 /**
@@ -81,6 +82,10 @@ function parseHeadingLevel(tag: string): number {
 }
 
 function extractHtmlHeadings(html: string): HtmlHeading[] {
+  if (!rawHtmlUsesOnlyAllowedTags(html)) {
+    return [];
+  }
+
   const renderedHtml = html.replace(NON_RENDERED_HTML_BLOCK_PATTERN, "");
   const headings: HtmlHeading[] = [];
   HTML_HEADING_PATTERN.lastIndex = 0;

From 1ab11202cc1fc6a6d489969eb666106a54c8a13b Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 22:27:56 -0500
Subject: [PATCH 25/32] Scan inline raw HTML headings in plan TOC

---
 .../Tools/ProposePlan/extractPlanHeadings.test.ts  |  8 ++++++++
 .../Tools/ProposePlan/extractPlanHeadings.ts       | 14 ++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 4786eea9e9..9d1e43869a 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -227,6 +227,14 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("counts raw HTML headings inside inline paragraph tokens", () => {
+    const md = `Intro <h2>Inline Section</h2>\n\n## Next`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Inline Section" },
+      { renderIndex: 1, level: 2, text: "Next" },
+    ]);
+  });
+
   test("counts raw HTML headings so renderIndex stays aligned", () => {
     const md = `# Markdown one\n\n<h2>Inline HTML two</h2>\n\n### Markdown three`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index e5b52ac623..256cb117ee 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -61,6 +61,20 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
       continue;
     }
 
+    if (token.type === "inline" && tokens[i - 1]?.type !== "heading_open") {
+      const children = token.children ?? [];
+      if (children.some((child) => child.type === "html_inline")) {
+        const inlineHtml = children.map((child) => child.content).join("");
+        for (const htmlHeading of extractHtmlHeadings(inlineHtml)) {
+          if (htmlHeading.text) {
+            headings.push({ renderIndex, level: htmlHeading.level, text: htmlHeading.text });
+          }
+          renderIndex += 1;
+        }
+      }
+      continue;
+    }
+
     if (token.type === "html_block" || token.type === "html_inline") {
       for (const htmlHeading of extractHtmlHeadings(token.content)) {
         if (htmlHeading.text) {

From a04e419d36516086680251d7e4b0bb950e2fb6be Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 22:37:10 -0500
Subject: [PATCH 26/32] Tighten inline TOC heading extraction

---
 .../ProposePlan/extractPlanHeadings.test.ts   |  8 +++++
 .../Tools/ProposePlan/extractPlanHeadings.ts  | 29 ++++++++++++++++++-
 src/browser/styles/globals.css                |  8 ++---
 3 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 9d1e43869a..a55fec1687 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -227,6 +227,14 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("does not count escaped raw HTML headings inside inline code", () => {
+    const md = `Intro \`<h2>Code</h2>\` <h2>Real</h2>\n\n## Next`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Real" },
+      { renderIndex: 1, level: 2, text: "Next" },
+    ]);
+  });
+
   test("counts raw HTML headings inside inline paragraph tokens", () => {
     const md = `Intro <h2>Inline Section</h2>\n\n## Next`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 256cb117ee..ed2e08dacd 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -64,7 +64,7 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
     if (token.type === "inline" && tokens[i - 1]?.type !== "heading_open") {
       const children = token.children ?? [];
       if (children.some((child) => child.type === "html_inline")) {
-        const inlineHtml = children.map((child) => child.content).join("");
+        const inlineHtml = reconstructInlineHtml(children);
         for (const htmlHeading of extractHtmlHeadings(inlineHtml)) {
           if (htmlHeading.text) {
             headings.push({ renderIndex, level: htmlHeading.level, text: htmlHeading.text });
@@ -90,6 +90,33 @@ export function extractPlanHeadings(markdown: string): PlanHeading[] {
   return headings;
 }
 
+interface InlineTokenChild {
+  type: string;
+  content: string;
+}
+
+function reconstructInlineHtml(children: InlineTokenChild[]): string {
+  let html = "";
+  let insideHtml = false;
+
+  for (const child of children) {
+    if (child.type === "html_inline") {
+      html += child.content;
+      const isClosingTag = child.content.startsWith("</");
+      const isCompleteTag =
+        /<\/[A-Za-z][^>]*>/.test(child.content) || /\/>\s*$/.test(child.content);
+      insideHtml = !isClosingTag && !isCompleteTag;
+      continue;
+    }
+
+    if (child.type === "text" && insideHtml) {
+      html += child.content;
+    }
+  }
+
+  return html;
+}
+
 function parseHeadingLevel(tag: string): number {
   const level = Number(tag.replace(/^h/i, ""));
   return level >= 1 && level <= 6 ? level : 1;
diff --git a/src/browser/styles/globals.css b/src/browser/styles/globals.css
index 250101bf18..d6c1e76bec 100644
--- a/src/browser/styles/globals.css
+++ b/src/browser/styles/globals.css
@@ -1743,11 +1743,11 @@ code {
 
 /*
  * Full TOC visibility. The plan stays centered in the transcript; the TOC uses
- * the left gutter beside that centered column. The gutter width is fixed at the
- * reveal breakpoint so the nav can be centered in the available lane without
- * relying on container-relative units that resolve inconsistently here.
+ * the left gutter beside that centered column. The 80rem reveal point leaves at
+ * least 12rem of mirrored gutter for the centered rail before overflow clipping
+ * can occur.
  */
-@container transcript (min-width: 78.5rem) {
+@container transcript (min-width: 80rem) {
   .plan-toc-aware .plan-toc-aside {
     width: var(--plan-toc-wide-gutter);
     padding-inline: 0;

From d94a28f5d19d4e59744d745b904215bbcaabc647 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Sun, 24 May 2026 22:43:23 -0500
Subject: [PATCH 27/32] Preserve nested inline TOC heading text

---
 .../ProposePlan/extractPlanHeadings.test.ts   |  8 +++++
 .../Tools/ProposePlan/extractPlanHeadings.ts  | 30 +++++++++++++++----
 src/browser/styles/globals.css                |  6 ++--
 3 files changed, 35 insertions(+), 9 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index a55fec1687..eeb4f7295c 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -227,6 +227,14 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("preserves text after nested inline tags inside raw HTML headings", () => {
+    const md = `<h2><em>Auth</em> rollout</h2>\n\n## Next`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Auth rollout" },
+      { renderIndex: 1, level: 2, text: "Next" },
+    ]);
+  });
+
   test("does not count escaped raw HTML headings inside inline code", () => {
     const md = `Intro \`<h2>Code</h2>\` <h2>Real</h2>\n\n## Next`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index ed2e08dacd..52e959f683 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -96,20 +96,17 @@ interface InlineTokenChild {
 }
 
 function reconstructInlineHtml(children: InlineTokenChild[]): string {
+  const openTags: string[] = [];
   let html = "";
-  let insideHtml = false;
 
   for (const child of children) {
     if (child.type === "html_inline") {
       html += child.content;
-      const isClosingTag = child.content.startsWith("</");
-      const isCompleteTag =
-        /<\/[A-Za-z][^>]*>/.test(child.content) || /\/>\s*$/.test(child.content);
-      insideHtml = !isClosingTag && !isCompleteTag;
+      updateInlineHtmlStack(openTags, child.content);
       continue;
     }
 
-    if (child.type === "text" && insideHtml) {
+    if (child.type === "text" && openTags.length > 0) {
       html += child.content;
     }
   }
@@ -117,6 +114,27 @@ function reconstructInlineHtml(children: InlineTokenChild[]): string {
   return html;
 }
 
+function updateInlineHtmlStack(openTags: string[], rawHtml: string): void {
+  const tagPattern = /<\s*(\/)?\s*([A-Za-z][A-Za-z0-9:-]*)\b[^>]*(\/)?\s*>/g;
+  let match = tagPattern.exec(rawHtml);
+  while (match) {
+    const tagName = match[2].toLowerCase();
+    const isClosingTag = match[1] != null;
+    const isSelfClosing = match[3] != null || /<[^>]*\/\s*>$/.test(match[0]);
+
+    if (isClosingTag) {
+      const openIndex = openTags.lastIndexOf(tagName);
+      if (openIndex >= 0) {
+        openTags.splice(openIndex, 1);
+      }
+    } else if (!isSelfClosing && !/<\/\s*[A-Za-z][A-Za-z0-9:-]*\s*>/.test(match[0])) {
+      openTags.push(tagName);
+    }
+
+    match = tagPattern.exec(rawHtml);
+  }
+}
+
 function parseHeadingLevel(tag: string): number {
   const level = Number(tag.replace(/^h/i, ""));
   return level >= 1 && level <= 6 ? level : 1;
diff --git a/src/browser/styles/globals.css b/src/browser/styles/globals.css
index d6c1e76bec..2237685e08 100644
--- a/src/browser/styles/globals.css
+++ b/src/browser/styles/globals.css
@@ -1743,11 +1743,11 @@ code {
 
 /*
  * Full TOC visibility. The plan stays centered in the transcript; the TOC uses
- * the left gutter beside that centered column. The 80rem reveal point leaves at
- * least 12rem of mirrored gutter for the centered rail before overflow clipping
+ * the left gutter beside that centered column. The 82rem reveal point leaves at
+ * least 13rem of mirrored gutter for the centered rail before overflow clipping
  * can occur.
  */
-@container transcript (min-width: 80rem) {
+@container transcript (min-width: 82rem) {
   .plan-toc-aware .plan-toc-aside {
     width: var(--plan-toc-wide-gutter);
     padding-inline: 0;

From 475299d84228d06944e6ca49dbd43b5367bf01b6 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 25 May 2026 10:10:14 -0500
Subject: [PATCH 28/32] Polish plan TOC reveal styling

---
 src/browser/styles/globals.css | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/src/browser/styles/globals.css b/src/browser/styles/globals.css
index 2237685e08..60470e2bf0 100644
--- a/src/browser/styles/globals.css
+++ b/src/browser/styles/globals.css
@@ -1541,8 +1541,9 @@ code {
 .plan-toc-layout {
   position: relative;
   --plan-toc-compact-column: 2.5rem;
+  --plan-toc-compact-right-gap: 0.5rem;
   --plan-toc-wide-column: 11rem;
-  --plan-toc-wide-gutter: 13rem;
+  --plan-toc-wide-gutter: 12rem;
 }
 
 .plan-toc-aside {
@@ -1573,7 +1574,7 @@ code {
   justify-content: center;
   min-height: 7.25rem;
   width: 0.75rem;
-  margin-left: calc((var(--plan-toc-compact-column) - 0.75rem) / 2);
+  margin-left: calc(var(--plan-toc-compact-column) - 0.75rem - var(--plan-toc-compact-right-gap));
   padding: 0;
   border: 0;
   background: transparent;
@@ -1610,11 +1611,11 @@ code {
 
 .plan-toc-heading {
   /* The plan title sits at the top of the TOC, in place of a separate
-     "CONTENTS" label. Keep it neutral (not plan-blue) so the side nav reads as
-     quiet structure instead of competing with the plan card itself. */
+     "CONTENTS" label. A light plan tint ties the side nav back to the plan
+     card without competing with the main content. */
   font-size: 12px;
   font-weight: 600;
-  color: var(--color-foreground);
+  color: color-mix(in srgb, var(--color-plan-mode) 58%, var(--color-foreground) 42%);
   margin: 0 0 6px 0;
   padding: 2px 0;
   /* Let long plan titles wrap inside the gutter instead of wasting available
@@ -1630,7 +1631,7 @@ code {
   background: transparent;
   border: 0;
   font: inherit;
-  color: var(--color-foreground);
+  color: inherit;
   cursor: pointer;
   display: block;
   width: 100%;
@@ -1641,7 +1642,7 @@ code {
 }
 
 .plan-toc-heading-link:hover {
-  color: var(--color-foreground);
+  color: color-mix(in srgb, var(--color-plan-mode) 70%, var(--color-foreground) 30%);
   background: var(--color-hover);
 }
 
@@ -1743,11 +1744,11 @@ code {
 
 /*
  * Full TOC visibility. The plan stays centered in the transcript; the TOC uses
- * the left gutter beside that centered column. The 82rem reveal point leaves at
- * least 13rem of mirrored gutter for the centered rail before overflow clipping
+ * the left gutter beside that centered column. The 80rem reveal point leaves at
+ * least 12rem of mirrored gutter for the centered rail before overflow clipping
  * can occur.
  */
-@container transcript (min-width: 82rem) {
+@container transcript (min-width: 80rem) {
   .plan-toc-aware .plan-toc-aside {
     width: var(--plan-toc-wide-gutter);
     padding-inline: 0;

From f8a2accceabc666884d907814717870310a9d53f Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 25 May 2026 10:38:06 -0500
Subject: [PATCH 29/32] Show plan TOC in wide story

---
 .../Tools/ProposePlan/ProposePlanToolCall.stories.tsx |  2 +-
 src/browser/styles/globals.css                        | 11 +++++------
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx b/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx
index ad3c604389..a199d7254e 100644
--- a/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx
+++ b/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx
@@ -269,7 +269,7 @@ Blue/green cutover with automatic rollback on auth-error spikes.
       description: {
         story:
           "Wide-viewport rendering of a multi-section plan. The sticky " +
-          '"Contents" navigation appears in the right gutter beside the plan ' +
+          '"Contents" navigation appears in the left gutter beside the plan ' +
           "card, anchored to the plan's vertical bounds via `position: sticky` " +
           "inside an absolutely-positioned `<aside>`. " +
           "Visibility is purely CSS-driven (container query + visibility class) " +
diff --git a/src/browser/styles/globals.css b/src/browser/styles/globals.css
index 60470e2bf0..261fd35425 100644
--- a/src/browser/styles/globals.css
+++ b/src/browser/styles/globals.css
@@ -1543,7 +1543,7 @@ code {
   --plan-toc-compact-column: 2.5rem;
   --plan-toc-compact-right-gap: 0.5rem;
   --plan-toc-wide-column: 11rem;
-  --plan-toc-wide-gutter: 12rem;
+  --plan-toc-wide-gutter: 11.25rem;
 }
 
 .plan-toc-aside {
@@ -1631,7 +1631,6 @@ code {
   background: transparent;
   border: 0;
   font: inherit;
-  color: inherit;
   cursor: pointer;
   display: block;
   width: 100%;
@@ -1744,11 +1743,11 @@ code {
 
 /*
  * Full TOC visibility. The plan stays centered in the transcript; the TOC uses
- * the left gutter beside that centered column. The 80rem reveal point leaves at
- * least 12rem of mirrored gutter for the centered rail before overflow clipping
- * can occur.
+ * the left gutter beside that centered column. The 78.5rem reveal point leaves
+ * enough mirrored gutter for the centered rail before overflow clipping can occur,
+ * including the 1600px wide Storybook viewport.
  */
-@container transcript (min-width: 80rem) {
+@container transcript (min-width: 78.5rem) {
   .plan-toc-aware .plan-toc-aside {
     width: var(--plan-toc-wide-gutter);
     padding-inline: 0;

From 0e4f7c0383eea043452880689626858fa37005ce Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 25 May 2026 10:54:23 -0500
Subject: [PATCH 30/32] Pin plan TOC story to wide Chromatic mode

---
 docs/AGENTS.md                                |  1 +
 .../Tools/ProposePlan/PlanTableOfContents.tsx |  2 +-
 .../ProposePlanToolCall.stories.tsx           | 40 +++++++++++++++++++
 .../builtInSkillContent.generated.ts          |  1 +
 tests/ui/storybook/budget.test.ts             |  3 +-
 tests/ui/storybook/coverage.test.ts           | 35 ++++++++++++++++
 6 files changed, 80 insertions(+), 2 deletions(-)

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 670ee8bbde..62b7ed1aab 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -228,6 +228,7 @@ Freely make breaking changes, and reorganize / cleanup IPC as needed.
 - **Use conditional rendering for testability:** Components like `AgentModePicker` use `{isOpen && <div>...}` instead of Radix Portal. This renders inline and works in happy-dom.
 - When adding new dropdown/popover components that need tests/ui coverage, prefer the conditional rendering pattern over Radix Portal.
 - E2E tests (tests/e2e) work with Radix but are slow (~2min startup); reserve for scenarios that truly need real Electron.
+- **Storybook responsive/Chromatic validation:** Do not prove responsive snapshots by only resizing `iframe.html`; that bypasses Storybook/Chromatic viewport mode configuration. If a story depends on a breakpoint (wide gutters, mobile, touch), pin an explicit `parameters.chromatic.modes[*].viewport`, mirror it with story `globals.viewport` for local viewing, and validate through the Storybook manager or an equivalent Chromatic-mode check. Add a play/static contract when a missing mode would silently snapshot the wrong UI.
 - Only use `validateApiKeys()` in tests that actually make AI API calls.
 
 ## Tool: todo_write
diff --git a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
index 41e8c9ad34..79e8c9f703 100644
--- a/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
+++ b/src/browser/features/Tools/ProposePlan/PlanTableOfContents.tsx
@@ -95,7 +95,7 @@ export const PlanTableOfContents: React.FC<PlanTableOfContentsProps> = (props) =
       <div className="plan-toc-compact-hint" aria-hidden="true">
         Expand to see ToC
       </div>
-      <nav className="plan-toc">
+      <nav className="plan-toc" data-testid="plan-toc-nav">
         {titleHeadingEntry ? (
           <TooltipIfPresent tooltip={headingText} side="right" align="start">
             <button
diff --git a/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx b/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx
index a199d7254e..2c4143b57f 100644
--- a/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx
+++ b/src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx
@@ -1,3 +1,5 @@
+import { waitFor, within } from "@storybook/test";
+
 import type { AppStory } from "@/browser/stories/meta.js";
 import { appMeta, AppWithMocks } from "@/browser/stories/meta.js";
 import { setupSimpleChatStory } from "@/browser/stories/helpers/chatSetup";
@@ -8,6 +10,20 @@ import { STABLE_TIMESTAMP } from "@/browser/stories/mocks/workspaces";
 const meta = { ...appMeta, title: "App/Chat/Tools/ProposePlan" };
 export default meta;
 
+const PLAN_TOC_CHROMATIC_VIEWPORT = { width: 1600, height: 900 } as const;
+const PLAN_TOC_CHROMATIC_MODES = {
+  "dark-wide": { theme: "dark", viewport: PLAN_TOC_CHROMATIC_VIEWPORT },
+} as const;
+
+function isChromaticRuntime(): boolean {
+  if (typeof window === "undefined") {
+    return false;
+  }
+
+  const chromaticRuntimeFlag = (window as Window & { chromatic?: boolean }).chromatic;
+  return /Chromatic/i.test(window.navigator.userAgent) || chromaticRuntimeFlag === true;
+}
+
 /**
  * Story showing a propose_plan tool call with Plan UI.
  * Tests the plan card rendering with icon action buttons at the bottom.
@@ -263,8 +279,32 @@ Blue/green cutover with automatic rollback on auth-error spikes.
       }
     />
   ),
+  globals: {
+    viewport: { value: "wide", isRotated: false },
+  },
+  play: async ({ canvasElement }) => {
+    const shouldAssertFullToc =
+      isChromaticRuntime() || window.innerWidth >= PLAN_TOC_CHROMATIC_VIEWPORT.width;
+    if (!shouldAssertFullToc) {
+      return;
+    }
+
+    const canvas = within(canvasElement);
+    const toc = await canvas.findByTestId("plan-toc-nav");
+    await waitFor(() => {
+      // User rationale: this story exists to snapshot the full sticky TOC. Make
+      // Chromatic fail loudly if a viewport/mode regression captures only the compact hint.
+      if (window.getComputedStyle(toc).display === "none" || toc.getClientRects().length === 0) {
+        throw new Error("Expected the full plan TOC to be visible in the wide Storybook story");
+      }
+    });
+  },
   parameters: {
     viewport: { defaultViewport: "wide" },
+    chromatic: {
+      ...(appMeta.parameters?.chromatic ?? {}),
+      modes: PLAN_TOC_CHROMATIC_MODES,
+    },
     docs: {
       description: {
         story:
diff --git a/src/node/services/agentSkills/builtInSkillContent.generated.ts b/src/node/services/agentSkills/builtInSkillContent.generated.ts
index 3f39493bf4..4e216c0f21 100644
--- a/src/node/services/agentSkills/builtInSkillContent.generated.ts
+++ b/src/node/services/agentSkills/builtInSkillContent.generated.ts
@@ -668,6 +668,7 @@ export const BUILTIN_SKILL_FILES: Record<string, Record<string, string>> = {
       "- **Use conditional rendering for testability:** Components like `AgentModePicker` use `{isOpen && <div>...}` instead of Radix Portal. This renders inline and works in happy-dom.",
       "- When adding new dropdown/popover components that need tests/ui coverage, prefer the conditional rendering pattern over Radix Portal.",
       "- E2E tests (tests/e2e) work with Radix but are slow (~2min startup); reserve for scenarios that truly need real Electron.",
+      "- **Storybook responsive/Chromatic validation:** Do not prove responsive snapshots by only resizing `iframe.html`; that bypasses Storybook/Chromatic viewport mode configuration. If a story depends on a breakpoint (wide gutters, mobile, touch), pin an explicit `parameters.chromatic.modes[*].viewport`, mirror it with story `globals.viewport` for local viewing, and validate through the Storybook manager or an equivalent Chromatic-mode check. Add a play/static contract when a missing mode would silently snapshot the wrong UI.",
       "- Only use `validateApiKeys()` in tests that actually make AI API calls.",
       "",
       "## Tool: todo_write",
diff --git a/tests/ui/storybook/budget.test.ts b/tests/ui/storybook/budget.test.ts
index 9d877c51e1..6ac9fdcfa2 100644
--- a/tests/ui/storybook/budget.test.ts
+++ b/tests/ui/storybook/budget.test.ts
@@ -5,7 +5,8 @@ import { join } from "node:path";
 const STORY_DIR = "src/browser/stories";
 const COLOCATED_STORY_DIRS = ["src/browser/components", "src/browser/features"];
 const MAX_SNAPSHOT_ENABLED_FILES = 70;
-const MAX_ESTIMATED_SNAPSHOTS = 300;
+// Includes the plan ToC wide-viewport story, which intentionally protects gutter-only UI.
+const MAX_ESTIMATED_SNAPSHOTS = 303;
 const STORY_EXPORT_PATTERN = /^export const \w+/gm;
 const SMOKE_MODE_PATTERN = /modes:\s*CHROMATIC_SMOKE_MODES/g;
 const INLINE_MODE_OBJECT_PATTERN = /modes:\s*{/g;
diff --git a/tests/ui/storybook/coverage.test.ts b/tests/ui/storybook/coverage.test.ts
index e2f7028def..f142d7b575 100644
--- a/tests/ui/storybook/coverage.test.ts
+++ b/tests/ui/storybook/coverage.test.ts
@@ -2,6 +2,9 @@ import { describe, expect, test } from "bun:test";
 import { existsSync, readFileSync } from "node:fs";
 
 const STORY_DIR = "src/browser/stories";
+const PLAN_TOC_STORY_PATH =
+  "src/browser/features/Tools/ProposePlan/ProposePlanToolCall.stories.tsx";
+const PLAN_TOC_MIN_CHROMATIC_WIDTH = 1600;
 
 /** App-level integration allowlist — files that must exist with smoke coverage. */
 const REQUIRED_APP_STORIES = [
@@ -46,6 +49,25 @@ const hasSmokeStoryWithDualThemeCoverage = (content: string): boolean => {
   );
 };
 
+function getPlanTocChromaticWidth(content: string): number | null {
+  const viewportMatch = content.match(
+    /PLAN_TOC_CHROMATIC_VIEWPORT\s*=\s*\{\s*width:\s*(\d+),\s*height:\s*\d+\s*\}/
+  );
+  if (!viewportMatch?.[1]) {
+    return null;
+  }
+
+  return Number(viewportMatch[1]);
+}
+
+function hasPlanTocWideChromaticMode(content: string): boolean {
+  return (
+    /PLAN_TOC_CHROMATIC_MODES\s*=\s*\{[\s\S]*viewport:\s*PLAN_TOC_CHROMATIC_VIEWPORT/.test(
+      content
+    ) && /modes:\s*PLAN_TOC_CHROMATIC_MODES/.test(content)
+  );
+}
+
 describe("Storybook coverage contract", () => {
   describe("App stories", () => {
     for (const filename of REQUIRED_APP_STORIES) {
@@ -85,6 +107,19 @@ describe("Storybook coverage contract", () => {
     }
   });
 
+  describe("Story-specific visual contracts", () => {
+    test("plan ToC story pins a wide Chromatic viewport", () => {
+      const content = readFileSync(PLAN_TOC_STORY_PATH, "utf-8");
+
+      // This story validates gutter-only UI: the full ToC is hidden at Chromatic's
+      // default 1200px width, so it must carry an explicit wide mode.
+      expect(hasPlanTocWideChromaticMode(content)).toBe(true);
+      expect(getPlanTocChromaticWidth(content)).toBeGreaterThanOrEqual(
+        PLAN_TOC_MIN_CHROMATIC_WIDTH
+      );
+    });
+  });
+
   describe("Migrated files removed", () => {
     for (const filename of MIGRATED_APP_STORIES) {
       test(`${filename} does not exist in src/browser/stories`, () => {

From ae88d5e31e2bdbc09500e2c38d42868a3b9177c6 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 25 May 2026 10:57:23 -0500
Subject: [PATCH 31/32] Count pre raw HTML headings in plan TOC

---
 .../Tools/ProposePlan/extractPlanHeadings.test.ts         | 8 ++++++++
 .../features/Tools/ProposePlan/extractPlanHeadings.ts     | 2 +-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index eeb4f7295c..5814113091 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -235,6 +235,14 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("counts raw HTML headings inside pre blocks to preserve DOM index alignment", () => {
+    const md = `<pre><h2>Rendered from raw HTML</h2></pre>\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Rendered from raw HTML" },
+      { renderIndex: 1, level: 2, text: "Outside" },
+    ]);
+  });
+
   test("does not count escaped raw HTML headings inside inline code", () => {
     const md = `Intro \`<h2>Code</h2>\` <h2>Real</h2>\n\n## Next`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 52e959f683..5e1312a153 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -26,7 +26,7 @@ interface HtmlHeading {
 const markdownParser = new MarkdownIt({ html: true, linkify: false, typographer: false });
 const HTML_HEADING_PATTERN = /<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1\s*>/gi;
 const NON_RENDERED_HTML_BLOCK_PATTERN =
-  /<!--([\s\S]*?)(?:-->|$)|<\?(?:[\s\S]*?)(?:\?>|$)|<!\[CDATA\[(?:[\s\S]*?)(?:\]\]>|$)|<![A-Z][\s\S]*?(?:>|$)|<(?:script|pre|style)(?=[\s>]|$)[\s\S]*?(?:<\/(?:script|pre|style)\s*>|$)/gi;
+  /<!--([\s\S]*?)(?:-->|$)|<\?(?:[\s\S]*?)(?:\?>|$)|<!\[CDATA\[(?:[\s\S]*?)(?:\]\]>|$)|<![A-Z][\s\S]*?(?:>|$)|<(?:script|style)(?=[\s>]|$)[\s\S]*?(?:<\/(?:script|style)\s*>|$)/gi;
 
 /**
  * Extract heading entries from a plan's markdown source.

From c5b4e9eda93b606ea25b853397236a7db5878839 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 25 May 2026 11:07:43 -0500
Subject: [PATCH 32/32] Handle implicit raw HTML plan headings

---
 .../ProposePlan/extractPlanHeadings.test.ts   | 17 +++++++
 .../Tools/ProposePlan/extractPlanHeadings.ts  | 44 ++++++++++++++++---
 2 files changed, 55 insertions(+), 6 deletions(-)

diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
index 5814113091..0219217f8a 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.test.ts
@@ -235,6 +235,23 @@ describe("extractPlanHeadings", () => {
     ]);
   });
 
+  test("counts implicitly closed raw HTML headings to preserve DOM index alignment", () => {
+    const md = `<h2>Implicit close\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Implicit close" },
+      { renderIndex: 1, level: 2, text: "Outside" },
+    ]);
+  });
+
+  test("stops implicitly closed raw HTML headings before the next heading tag", () => {
+    const md = `<h2>Intro<h3>Nested close\n\n## Outside`;
+    expect(extractPlanHeadings(md)).toEqual([
+      { renderIndex: 0, level: 2, text: "Intro" },
+      { renderIndex: 1, level: 3, text: "Nested close" },
+      { renderIndex: 2, level: 2, text: "Outside" },
+    ]);
+  });
+
   test("counts raw HTML headings inside pre blocks to preserve DOM index alignment", () => {
     const md = `<pre><h2>Rendered from raw HTML</h2></pre>\n\n## Outside`;
     expect(extractPlanHeadings(md)).toEqual([
diff --git a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
index 5e1312a153..f1319c868b 100644
--- a/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
+++ b/src/browser/features/Tools/ProposePlan/extractPlanHeadings.ts
@@ -24,10 +24,13 @@ interface HtmlHeading {
 }
 
 const markdownParser = new MarkdownIt({ html: true, linkify: false, typographer: false });
-const HTML_HEADING_PATTERN = /<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1\s*>/gi;
+const HTML_HEADING_OPEN_PATTERN = /<h([1-6])\b[^>]*>/gi;
 const NON_RENDERED_HTML_BLOCK_PATTERN =
   /<!--([\s\S]*?)(?:-->|$)|<\?(?:[\s\S]*?)(?:\?>|$)|<!\[CDATA\[(?:[\s\S]*?)(?:\]\]>|$)|<![A-Z][\s\S]*?(?:>|$)|<(?:script|style)(?=[\s>]|$)[\s\S]*?(?:<\/(?:script|style)\s*>|$)/gi;
 
+const IMPLICIT_HEADING_BOUNDARY_PATTERN =
+  /<h[1-6]\b[^>]*>|<\/?(?:address|article|aside|blockquote|details|dialog|div|dl|dt|dd|fieldset|figcaption|figure|footer|form|header|hr|li|main|nav|ol|p|pre|section|summary|table|tbody|td|tfoot|th|thead|tr|ul)\b[^>]*>/i;
+
 /**
  * Extract heading entries from a plan's markdown source.
  *
@@ -147,20 +150,49 @@ function extractHtmlHeadings(html: string): HtmlHeading[] {
 
   const renderedHtml = html.replace(NON_RENDERED_HTML_BLOCK_PATTERN, "");
   const headings: HtmlHeading[] = [];
-  HTML_HEADING_PATTERN.lastIndex = 0;
+  HTML_HEADING_OPEN_PATTERN.lastIndex = 0;
 
-  let match = HTML_HEADING_PATTERN.exec(renderedHtml);
+  let match = HTML_HEADING_OPEN_PATTERN.exec(renderedHtml);
   while (match) {
+    const level = parseInt(match[1], 10);
+    const contentStart = match.index + match[0].length;
+    const contentEnd = findHtmlHeadingContentEnd(renderedHtml, contentStart, level);
+
     headings.push({
-      level: parseInt(match[1], 10),
-      text: stripMarkdownFormatting(match[2].replace(/<[^>]+>/g, "")),
+      level,
+      text: stripMarkdownFormatting(
+        renderedHtml.slice(contentStart, contentEnd).replace(/<[^>]+>/g, "")
+      ),
     });
-    match = HTML_HEADING_PATTERN.exec(renderedHtml);
+
+    HTML_HEADING_OPEN_PATTERN.lastIndex = Math.max(contentEnd, contentStart);
+    match = HTML_HEADING_OPEN_PATTERN.exec(renderedHtml);
   }
 
   return headings;
 }
 
+function findHtmlHeadingContentEnd(html: string, contentStart: number, level: number): number {
+  const remaining = html.slice(contentStart);
+  const explicitClose = new RegExp(`</h${level}\\s*>`, "i").exec(remaining);
+  const implicitBoundary = IMPLICIT_HEADING_BOUNDARY_PATTERN.exec(remaining);
+  const explicitCloseIndex = explicitClose?.index;
+  const implicitBoundaryIndex = implicitBoundary?.index;
+
+  if (
+    implicitBoundaryIndex != null &&
+    (explicitCloseIndex == null || implicitBoundaryIndex < explicitCloseIndex)
+  ) {
+    return contentStart + implicitBoundaryIndex;
+  }
+
+  if (explicitCloseIndex != null) {
+    return contentStart + explicitCloseIndex;
+  }
+
+  return html.length;
+}
+
 /**
  * Lightweight inline-formatting stripper used only for TOC display text. Not a
  * full markdown parser — markdown-it has already handled block structure; this