PR review: #253 — Fix T-1237: TOC sidebar can get stuck open in raw source mode

diff --git a/prism/Views/RegularDocumentLayout.swift b/prism/Views/RegularDocumentLayout.swift
index bb7e07f1..3a989397 100644
--- a/prism/Views/RegularDocumentLayout.swift
+++ b/prism/Views/RegularDocumentLayout.swift
@@ -425,7 +425,7 @@ struct RegularDocumentLayout: View {
 }

 /// Toolbar for the regular document layout.
-private struct RegularLayoutToolbar: ViewModifier {
+struct RegularLayoutToolbar: ViewModifier {
     let session: DocumentSession
     let notesManager: NotesManager
     let settings: AppSettings
@@ -435,6 +435,14 @@ private struct RegularLayoutToolbar: ViewModifier {
     @Binding var showRawSource: Bool
     let onSave: () -> Void

+    /// Returns `true` only when raw source is active and the sidebar is
+    /// already closed. An open sidebar must always be closable from the
+    /// toolbar — blanket-disabling on `showRawSource` alone traps users
+    /// with no toolbar control to dismiss the sidebar.
+    static func isTOCToggleDisabled(showRawSource: Bool, showLeftSidebar: Bool) -> Bool {
+        showRawSource && !showLeftSidebar
+    }
+
     func body(content: Content) -> some View {
         content.toolbar {
             ToolbarItemGroup(placement: .navigation) {
@@ -452,7 +460,10 @@ private struct RegularLayoutToolbar: ViewModifier {
                         : LocalizedStringKey("Show table of contents")
                 )
                 .help(showLeftSidebar ? "Hide table of contents" : "Show table of contents")
-                .inactive(showRawSource)
+                .inactive(Self.isTOCToggleDisabled(
+                    showRawSource: showRawSource,
+                    showLeftSidebar: showLeftSidebar
+                ))
             }

             ToolbarItemGroup(placement: .primaryAction) {

diff --git a/prismTests/RegularLayoutToolbarTests.swift b/prismTests/RegularLayoutToolbarTests.swift
new file mode 100644
index 00000000..c8b8d6b8
--- /dev/null
+++ b/prismTests/RegularLayoutToolbarTests.swift
@@ -0,0 +1,60 @@
+//
+//  RegularLayoutToolbarTests.swift
+//  prismTests
+//
+//  Regression tests for T-1237: TOC sidebar can get stuck open in raw source
+//  mode. Before the fix, the toolbar's TOC toggle button was unconditionally
+//  disabled while raw source was active, so an already-open sidebar could
+//  not be closed from the toolbar.
+//
+
+import Foundation
+import Testing
+@testable import prism
+
+@Suite("RegularLayoutToolbar TOC button enablement")
+struct RegularLayoutToolbarTests {
+
+    // MARK: - T-1237 regression
+
+    @Test("TOC toggle is enabled when sidebar is open, even in raw source mode")
+    func tocToggleEnabledWhenSidebarOpenInRawSource() {
+        // Before T-1237 fix this returned `true` (disabled), leaving an
+        // open sidebar stuck visible.
+        #expect(
+            RegularLayoutToolbar.isTOCToggleDisabled(
+                showRawSource: true,
+                showLeftSidebar: true
+            ) == false
+        )
+    }
+
+    @Test("TOC toggle is disabled when sidebar is closed and raw source is on")
+    func tocToggleDisabledWhenSidebarClosedInRawSource() {
+        // Prevents opening the sidebar from a closed state while raw
+        // source is active — TOC navigation targets only exist in the
+        // rendered view.
+        #expect(
+            RegularLayoutToolbar.isTOCToggleDisabled(
+                showRawSource: true,
+                showLeftSidebar: false
+            ) == true
+        )
+    }
+
+    @Test("TOC toggle is enabled in rendered mode regardless of sidebar state")
+    func tocToggleEnabledInRenderedMode() {
+        #expect(
+            RegularLayoutToolbar.isTOCToggleDisabled(
+                showRawSource: false,
+                showLeftSidebar: true
+            ) == false
+        )
+        #expect(
+            RegularLayoutToolbar.isTOCToggleDisabled(
+                showRawSource: false,
+                showLeftSidebar: false
+            ) == false
+        )
+    }
+}

diff --git a/docs/agent-notes/toc-left-sidebar.md b/docs/agent-notes/toc-left-sidebar.md
index 7e84674a..3b87a916 100644
--- a/docs/agent-notes/toc-left-sidebar.md
+++ b/docs/agent-notes/toc-left-sidebar.md
@@ -45,3 +45,5 @@ Only visible sidebars contribute to the threshold calculation.
 - AppSettings sidebar properties use `-1` as sentinel for "use platform default"
 - `SidebarContentsView` toggle binding intentionally checks current value before firing callback to avoid duplicate toggles during `DisclosureGroup` reconciliation.
 - **Sidebar List background**: Any sidebar view using `List` must apply `.scrollContentBackground(.hidden)` on the List and `.listRowBackground(Color.clear)` on rows. Without these, the system List background (white/black) covers the theme background set by the caller. `.scrollContentBackground(.hidden)` does NOT propagate through wrapper views — it must be applied directly to the `List`. See `SidebarNotesView` as the reference pattern. (T-77 regression fix)
+- **TOC toolbar button disable rule (T-1237)**: The regular-layout TOC toolbar button must use `RegularLayoutToolbar.isTOCToggleDisabled(showRawSource:showLeftSidebar:)`, not a bare `.inactive(showRawSource)`. The button toggles between "open" and "close" actions; both are blanket-disabled only when raw source is active AND the sidebar is closed. An already-open sidebar must always be closable, otherwise it stays visible with no toolbar control to dismiss it. Compact mode is unaffected because the TOC there is a sheet, not persistent state.
+- **Toolbar vs. menu command asymmetry (T-1237)**: The `isTOCToggleDisabled` rule applies only to the toolbar button. The menu command (`Cmd+Option+T`, routed through `DocumentActions.toggleTableOfContents`) is not gated on raw source mode and can both open and close the sidebar while raw source is active. This divergence was an intentional scope decision when fixing T-1237 — the menu shortcut was the user's workaround for the toolbar trap. If the two are ever aligned, remove this note.

diff --git a/specs/bugfixes/toc-sidebar-stuck-in-raw-source/report.md b/specs/bugfixes/toc-sidebar-stuck-in-raw-source/report.md
new file mode 100644
index 00000000..5cbf8a8c
--- /dev/null
+++ b/specs/bugfixes/toc-sidebar-stuck-in-raw-source/report.md
@@ -0,0 +1,91 @@
+# Bugfix Report: TOC Sidebar Stuck Open In Raw Source Mode
+
+**Date:** 2026-05-17
+**Status:** Fixed
+**Transit ticket:** T-1237
+
+## Description of the Issue
+
+On iPad/macOS, the TOC left sidebar in `RegularDocumentLayout` could become stuck in the open state when the user switched into raw source view. The toolbar button that toggles the sidebar was unconditionally disabled while raw source was active, so an already-open sidebar could not be closed from the toolbar — the user had to leave raw source mode first.
+
+**Reproduction steps:**
+1. On iPad or macOS, open any markdown document with the TOC sidebar visible.
+2. Toggle raw source mode on.
+3. Try to hide the TOC sidebar via the toolbar `sidebar.left` button.
+4. Observe the button is dimmed/disabled — the sidebar remains visible.
+
+**Impact:** UX trap on iPad/macOS users who use both raw source and the TOC sidebar. Workaround was to exit raw source first, then close the sidebar. Discovered by automated code issue check after commit f8ed94b (PR #245).
+
+## Investigation Summary
+
+Used systematic Fagan inspection.
+
+- **Symptoms examined:** Disabled `sidebar.left` toolbar button while in raw source mode with sidebar open.
+- **Code inspected:** `RegularDocumentLayout.swift` (toolbar + main HStack), `CompactBottomToolbar.swift`, `DocumentReaderView.swift` (action dispatch), `prismApp.swift` (`ToggleTOCButton`), commit f8ed94b.
+- **Hypotheses tested:** Considered auto-hiding the sidebar on entering raw source vs. keeping the toggle live when the sidebar is open. Option B was selected as the least surprising fix that preserves user intent across mode switches.
+
+## Discovered Root Cause
+
+The `.inactive(showRawSource)` modifier on the TOC toolbar button in `RegularLayoutToolbar` conflates two distinct user intents (open vs. close) into one disabled state. Because the sidebar's visibility is orthogonal to raw source and persists across mode switches, disabling the toggle without first ensuring the sidebar is closed creates an unreachable state where the sidebar is visible but its only toolbar control is dimmed.
+
+**Defect type:** Logic error — state coupling.
+
+**Why it occurred:** The intent of the original change (f8ed94b) was correct — TOC navigation targets are not meaningful in raw source view, so the user should not be able to *open* the sidebar from a closed state. The author modelled this as a single "TOC interaction" being inactive, rather than separately considering the "close an already-open sidebar" path.
+
+**Contributing factors:** Compact mode uses a transient sheet, which has no persistent state that can be stuck open, so the same `.inactive(isRawSourceActive)` pattern works fine there. The asymmetric behaviour between compact and regular layouts is what made the regular-layout case a trap.
+
+## Resolution for the Issue
+
+**Changes made:**
+- `prism/Views/RegularDocumentLayout.swift` — replaced `.inactive(showRawSource)` on the TOC toolbar button with `.inactive(RegularLayoutToolbar.isTOCToggleDisabled(showRawSource:showLeftSidebar:))`. The helper returns `true` (disabled) only when raw source is active AND the sidebar is currently closed, allowing the user to close an already-open sidebar.
+- `prism/Views/RegularDocumentLayout.swift` — extracted the disable predicate as a small `static` helper on `RegularLayoutToolbar` so the rule is testable without instantiating SwiftUI views. Changed `RegularLayoutToolbar` from `private` to `internal` so the test target can reference it.
+
+**Approach rationale:** Preserves user intent — if the user explicitly opened the sidebar, that state survives toggling raw source. The button's accessibility label and help text already derive from `showLeftSidebar`, so they continue to read correctly ("Hide table of contents" while the sidebar is open in raw source). Minimal change, no auto-state machinery, no surprise.
+
+**Alternatives considered:**
+- **Auto-hide sidebar on entering raw source (with optional restore):** Simpler state model but surprises users who explicitly chose to open the sidebar. Adding "remember and restore" adds state that's only needed because of this fix.
+- **Apply the same logic to the menu command (`Cmd+Option+T`):** Out of scope — the bug report specifically calls out the toolbar behaviour. The menu command path currently works in raw source (it was the user's workaround for the bug). Changing it here would expand surface area beyond the reported defect.
+
+## Regression Test
+
+**Test file:** `prismTests/RegularLayoutToolbarTests.swift`
+
+**Test names:**
+- `tocToggleEnabledWhenSidebarOpenInRawSource` — the primary T-1237 regression.
+- `tocToggleDisabledWhenSidebarClosedInRawSource` — verifies opening is still blocked.
+- `tocToggleEnabledInRenderedMode` — verifies normal rendered-mode behaviour is unaffected.
+
+**What it verifies:** The 2×2 matrix of (`showRawSource` × `showLeftSidebar`) for the TOC button disable predicate. Only the closed-and-raw-source case is disabled.
+
+**Run command:**
+```
+xcodebuild test -project prism.xcodeproj -scheme prism \
+  -destination 'platform=macOS' \
+  -only-testing:prismTests/RegularLayoutToolbarTests
+```
+
+## Affected Files
+
+| File | Change |
+|------|--------|
+| `prism/Views/RegularDocumentLayout.swift` | Replaced `.inactive(showRawSource)` on TOC toolbar button with a state-aware helper; extracted the helper for testability; changed toolbar struct from `private` to `internal`. |
+| `prismTests/RegularLayoutToolbarTests.swift` | New regression tests for the TOC button disable predicate. |
+
+## Verification
+
+**Automated:**
+- [x] Regression tests pass
+- [x] Full unit test suite passes (`make test-quick`)
+- [x] Linter passes (`make lint`)
+
+**Manual verification (matrix):**
+- Sidebar open + rendered: button enabled (close action)
+- Sidebar closed + rendered: button enabled (open action)
+- Sidebar open + raw source: button enabled (close action) — **previously stuck**
+- Sidebar closed + raw source: button disabled (cannot open)
+
+## Prevention
+
+**Recommendations to avoid similar bugs:**
+- When applying `.inactive(...)`/`.disabled(...)` to a toggle control that switches between two semantic actions, consider whether each action remains valid independently. A blanket disable assumes both actions are equally invalid in the disabled state, which is often false for persistent-state toggles.
+- Compact (sheet-based) and regular (sidebar-based) layouts diverge on state persistence. A pattern that works in compact may trap users in regular — review both layouts when adding cross-mode interaction rules.