From 9d2ca03c4c67fddd768d4acfc687c373e6dba7b4 Mon Sep 17 00:00:00 2001
From: Frederic Barthelemy <git@fbartho.com>
Date: Wed, 9 Sep 2026 15:53:56 -0700
Subject: [PATCH] docs(editor): state the fault-tracking constraints in present
 tense

---
 .../components/editor/editor-panel-render-model.ts    |  5 ++---
 .../editor/useMarkdownRichModeFaultTracking.ts        | 11 +++++------
 .../store/slices/editor/actions/editor-draft-state.ts |  6 +++---
 3 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/src/renderer/src/components/editor/editor-panel-render-model.ts b/src/renderer/src/components/editor/editor-panel-render-model.ts
index c0d957eb702..e45cb9731bf 100644
--- a/src/renderer/src/components/editor/editor-panel-render-model.ts
+++ b/src/renderer/src/components/editor/editor-panel-render-model.ts
@@ -127,9 +127,8 @@ export function getEditorPanelRenderModel({
     !inlineFileContent.loadError &&
     activeFile.conflict?.kind !== 'conflict-placeholder' &&
     activeFile.conflict?.conflictStatus !== 'unresolved'
-  // Why: classifying scans the whole document, so it only runs while the user
-  // is looking at Rich mode. Source-view tabs read the stored fault instead
-  // (see useMarkdownRichModeFaultTracking) rather than re-scanning.
+  // Why: classification scans the whole document, so it runs only in Rich
+  // mode; Source-view tabs read the stored fault (useMarkdownRichModeFaultTracking).
   const richModeEligibility =
     canRenderInlineMarkdown && mdViewMode === 'rich'
       ? getCachedMarkdownRichModeEligibility({
diff --git a/src/renderer/src/components/editor/useMarkdownRichModeFaultTracking.ts b/src/renderer/src/components/editor/useMarkdownRichModeFaultTracking.ts
index 435d0140451..39495d1a475 100644
--- a/src/renderer/src/components/editor/useMarkdownRichModeFaultTracking.ts
+++ b/src/renderer/src/components/editor/useMarkdownRichModeFaultTracking.ts
@@ -10,10 +10,9 @@ type UseMarkdownRichModeFaultTrackingParams = {
   setMarkdownRichModeFaultedContent: (fileId: string, content: string | null) => void
 }
 
-// Why: getMarkdownRenderMode only decides source-vs-rich-vs-preview for the
-// content it's given; recording that a Rich attempt fell back (or recovered)
-// as durable per-tab state is a side effect, so it belongs in an effect keyed
-// off the render model's output rather than during render itself.
+// Why: recording that a Rich attempt fell back or recovered is durable per-tab
+// state, a side effect, so it lives in an effect keyed off the render model's
+// output, never inside render.
 export function useMarkdownRichModeFaultTracking({
   fileId,
   mdViewMode,
@@ -29,8 +28,8 @@ export function useMarkdownRichModeFaultTracking({
       setMarkdownRichModeFaultedContent(fileId, inlineMarkdownContent)
       return
     }
-    // Why: a successful Rich attempt for this content means it's no longer a
-    // fault, whatever content is currently stored for this tab.
+    // Why: a successful Rich attempt for this content clears the fault,
+    // whatever content is currently stored for this tab.
     setMarkdownRichModeFaultedContent(fileId, null)
   }, [
     fileId,
diff --git a/src/renderer/src/store/slices/editor/actions/editor-draft-state.ts b/src/renderer/src/store/slices/editor/actions/editor-draft-state.ts
index 8d94cc55d1b..4d77084aa88 100644
--- a/src/renderer/src/store/slices/editor/actions/editor-draft-state.ts
+++ b/src/renderer/src/store/slices/editor/actions/editor-draft-state.ts
@@ -17,9 +17,9 @@ export type EditorDraftState = {
   // Why: per-file opt-in to open an oversized markdown file in the rich editor despite the size limit.
   markdownRichModeSizeOverride: Record<string, boolean>
   setMarkdownRichModeSizeOverride: (fileId: string, enabled: boolean) => void
-  // Why: the content string that made rich mode fall back to Source for this
-  // tab, so the toggle can offer Preview without re-scanning. A stale entry
-  // (content no longer matches) reads as "not faulted for this content".
+  // Why: the content that made rich mode fall back to Source for this tab, so
+  // the toggle can offer Preview without re-scanning; a stale entry (content
+  // differs) reads as not faulted.
   markdownRichModeFaultedContent: Record<string, string>
   setMarkdownRichModeFaultedContent: (fileId: string, content: string | null) => void
   editorViewMode: Record<string, EditorViewMode>