diff --git a/apps/docs/app/(diffs)/_docs/DocsPage.tsx b/apps/docs/app/(diffs)/_docs/DocsPage.tsx
index d2a722628..2f4be5c3a 100644
--- a/apps/docs/app/(diffs)/_docs/DocsPage.tsx
+++ b/apps/docs/app/(diffs)/_docs/DocsPage.tsx
@@ -31,15 +31,21 @@ import {
   CUSTOM_HUNK_SEPARATORS_SWITCHER,
 } from '../docs/CustomHunkSeparators/constants';
 import {
-  EDIT_DEMO_FILE_EXAMPLE,
+  EDIT_FOCUS_POSITION_EXAMPLE,
   EDIT_LAZY_FILE_EXAMPLE,
   EDIT_MARKER_EXAMPLE,
   EDIT_MARKER_TYPE,
+  EDIT_ON_ATTACH_REACT_EXAMPLE,
+  EDIT_ON_ATTACH_VANILLA_EXAMPLE,
   EDIT_ON_CHANGE_EXAMPLE,
+  EDIT_PERSIST_STATE_EXAMPLE,
+  EDIT_PERSIST_STATE_REACT_EXAMPLE,
   EDIT_REACT_CODE_VIEW_EXAMPLE,
+  EDIT_REACT_CREATE_EDITOR_EXAMPLE,
   EDIT_REACT_EXAMPLE,
   EDIT_REACT_FILE_DIFF_EXAMPLE,
   EDIT_REACT_MULTI_FILE_DIFF_EXAMPLE,
+  EDIT_REACT_SHARED_EDITOR_EXAMPLE,
   EDIT_SELECTION_ACTION_CONTEXT_TYPE,
   EDIT_SELECTION_ACTION_EXAMPLE,
   EDIT_UNDO_REDO_EXAMPLE,
@@ -424,7 +430,6 @@ async function CodeViewSection() {
 
 async function EditSection() {
   const [
-    editDemoFile,
     keymapFile,
     editVanillaFileExample,
     editVanillaFileDiffExample,
@@ -432,11 +437,18 @@ async function EditSection() {
     editLazyFileExample,
     editorOptionsType,
     editOnChangeExample,
+    editOnAttachReactExample,
+    editOnAttachVanillaExample,
+    editFocusPositionExample,
     editorPublicApi,
     editSelectionActionContextType,
     editSelectionActionExample,
+    editPersistStateExample,
+    editPersistStateReactExample,
     editMarkerType,
     editMarkerExample,
+    editReactCreateEditorExample,
+    editReactSharedEditorExample,
     editReactCodeViewExample,
     editReactExample,
     editReactFileDiffExample,
@@ -445,7 +457,6 @@ async function EditSection() {
     editWorkerPoolReactExample,
     editWorkerPoolVanillaExample,
   ] = await Promise.all([
-    preloadFile(EDIT_DEMO_FILE_EXAMPLE),
     preloadFile(DEFAULT_KEYMAP_FILE_EXAMPLE),
     preloadFile(EDIT_VANILLA_FILE_EXAMPLE),
     preloadFile(EDIT_VANILLA_FILE_DIFF_EXAMPLE),
@@ -453,11 +464,18 @@ async function EditSection() {
     preloadFile(EDIT_LAZY_FILE_EXAMPLE),
     preloadFile(EDITOR_OPTIONS_TYPE),
     preloadFile(EDIT_ON_CHANGE_EXAMPLE),
+    preloadFile(EDIT_ON_ATTACH_REACT_EXAMPLE),
+    preloadFile(EDIT_ON_ATTACH_VANILLA_EXAMPLE),
+    preloadFile(EDIT_FOCUS_POSITION_EXAMPLE),
     preloadFile(EDITOR_PUBLIC_API),
     preloadFile(EDIT_SELECTION_ACTION_CONTEXT_TYPE),
     preloadFile(EDIT_SELECTION_ACTION_EXAMPLE),
+    preloadFile(EDIT_PERSIST_STATE_EXAMPLE),
+    preloadFile(EDIT_PERSIST_STATE_REACT_EXAMPLE),
     preloadFile(EDIT_MARKER_TYPE),
     preloadFile(EDIT_MARKER_EXAMPLE),
+    preloadFile(EDIT_REACT_CREATE_EDITOR_EXAMPLE),
+    preloadFile(EDIT_REACT_SHARED_EDITOR_EXAMPLE),
     preloadFile(EDIT_REACT_CODE_VIEW_EXAMPLE),
     preloadFile(EDIT_REACT_EXAMPLE),
     preloadFile(EDIT_REACT_FILE_DIFF_EXAMPLE),
@@ -469,7 +487,6 @@ async function EditSection() {
   const content = await renderMDX({
     filePath: '(diffs)/docs/Edit/content.mdx',
     scope: {
-      editDemoFile,
       keymapFile,
       editVanillaFileExample,
       editVanillaFileDiffExample,
@@ -477,11 +494,18 @@ async function EditSection() {
       editLazyFileExample,
       editorOptionsType,
       editOnChangeExample,
+      editOnAttachReactExample,
+      editOnAttachVanillaExample,
+      editFocusPositionExample,
       editorPublicApi,
       editSelectionActionContextType,
       editSelectionActionExample,
+      editPersistStateExample,
+      editPersistStateReactExample,
       editMarkerType,
       editMarkerExample,
+      editReactCreateEditorExample,
+      editReactSharedEditorExample,
       editReactCodeViewExample,
       editReactExample,
       editReactFileDiffExample,
diff --git a/apps/docs/app/(diffs)/_home/AgentUi.tsx b/apps/docs/app/(diffs)/_home/AgentUi.tsx
index a0e2c0d59..757ca1581 100644
--- a/apps/docs/app/(diffs)/_home/AgentUi.tsx
+++ b/apps/docs/app/(diffs)/_home/AgentUi.tsx
@@ -2,7 +2,7 @@
 
 import { DEFAULT_THEMES, type FileDiffMetadata } from '@pierre/diffs';
 import type { EditorOptions } from '@pierre/diffs/edit';
-import { File, FileDiff } from '@pierre/diffs/react';
+import { File, FileDiff, Virtualizer } from '@pierre/diffs/react';
 import {
   IconArrow,
   IconChevronSm,
@@ -21,7 +21,6 @@ import {
   type CSSProperties,
   useCallback,
   useEffect,
-  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -41,12 +40,6 @@ import {
   getSessionGitStatus,
   getSessionPaths,
 } from './mockData';
-// Runs as a layout effect in the browser (so DOM reads/writes land before the
-// next paint) but falls back to useEffect during SSR, where useLayoutEffect
-// would warn. The demo is server-rendered, so the fallback matters.
-const useIsomorphicLayoutEffect =
-  typeof window === 'undefined' ? useEffect : useLayoutEffect;
-
 // Added/removed line totals for a single file's diff.
 interface DiffStats {
   additions: number;
@@ -66,33 +59,6 @@ function countDiffStats(diff: FileDiffMetadata): DiffStats {
   return { additions, deletions };
 }
 
-// The editor's stylesheet flattens every line number to one neutral colour
-// (`--diffs-editor-line-number-fg`) and is injected as an unlayered <style>,
-// so it overrides the library's per-line colouring (which lives in @layer
-// base). We adopt this extra, higher-specificity unlayered sheet into the
-// editor's shadow root to restore jade/red numbers for added and deleted
-// lines, while leaving the active/selected line to the editor's own styling.
-const LINE_NUMBER_COLOR_CSS = `
-[data-column-number][data-line-type='change-addition']:not([data-selected-line]):not([data-editor-active-line]) {
-  color: var(--diffs-addition-base);
-}
-[data-column-number][data-line-type='change-deletion']:not([data-selected-line]):not([data-editor-active-line]) {
-  color: var(--diffs-deletion-base);
-}
-`;
-
-let lineNumberColorSheet: CSSStyleSheet | null = null;
-function getLineNumberColorSheet(): CSSStyleSheet | null {
-  if (typeof CSSStyleSheet === 'undefined') {
-    return null;
-  }
-  if (lineNumberColorSheet == null) {
-    lineNumberColorSheet = new CSSStyleSheet();
-    lineNumberColorSheet.replaceSync(LINE_NUMBER_COLOR_CSS);
-  }
-  return lineNumberColorSheet;
-}
-
 // `renderSelectionAction` returns a plain DOM node, not React, and renders into
 // the editor's shadow DOM where the page's CSS (including agent-ui.css) doesn't
 // reach, so the comment icon is inlined as markup painted with `currentColor`
@@ -452,28 +418,6 @@ function makeAddedFile(path: string): AuiChangedFile {
   };
 }
 
-// A placeholder file (one outside the agent's change set) that the user edited,
-// modeled as a "modified" change diffing the original placeholder contents
-// against the live edits. This surfaces it in the Changes panel with tracked
-// +/- counts even though it was never part of the original session.
-function makeEditedPlaceholder(path: string, after: string): AuiChangedFile {
-  const before = getPlaceholderContents(path);
-  const stats = countDiffStats(
-    getFileDiff(
-      {
-        path,
-        status: 'modified',
-        before,
-        after: before,
-        additions: 0,
-        deletions: 0,
-      },
-      after
-    )
-  );
-  return { path, status: 'modified', before, after, ...stats };
-}
-
 // Toolbar above the file explorer: New file, New folder, and the search toggle.
 // Lives in its own component (rendered only once we have a model) so
 // useFileTreeSearch — which subscribes to the model — is never called against a
@@ -1026,27 +970,48 @@ export function AgentUi({
   const recordEditedStatsRef = useRef(recordEditedStats);
   recordEditedStatsRef.current = recordEditedStats;
 
-  // Persisted in-editor edits keyed by path, so switching files keeps the
-  // agent's tweaked output.
-  const editsRef = useRef<Map<string, string>>(new Map());
+  // One FileDiffMetadata per changed file, parsed on first visit and reused
+  // on every revisit. Edit sessions write edits back into the metadata (the
+  // library treats the host's metadata as the diff's content owner and
+  // self-heals session-shaped metadata on re-render), so reusing the object
+  // is what keeps a diff's edited content across file switches — the editor's
+  // persist-state API covers only selections and scroll for diffs.
+  // Placeholder File surfaces need no equivalent: with `persistState` on the
+  // shared editor, the per-cacheKey document cache restores their edited
+  // contents (and undo history) on re-attach.
+  const diffsRef = useRef<Map<string, FileDiffMetadata>>(new Map());
+  // Paths the user has edited. Only consulted to stop an edited file from
+  // hydrating out of its prerendered (pristine) server HTML on revisit.
+  const editedPathsRef = useRef<Set<string>>(new Set());
   // The stable onChange callback has no path argument, so track its live target
   // here.
   const activeTargetRef = useRef<string | null>(null);
   useEffect(() => {
     activeTargetRef.current = activePath;
   }, [activePath]);
-
-  // Edited placeholder files modeled as "modified" changes from their live
-  // edits. Recomputed when the tracked set changes (each edit also refreshes the
-  // displayed counts via `liveStats`, so the row decoration stays current).
+  // The path the editor was last attached to, so onAttach can tell a file
+  // switch (refocus the editor) from the initial mount (leave page focus
+  // alone).
+  const lastAttachedPathRef = useRef<string | null>(null);
+
+  // Edited placeholder files listed in the Changes panel as "modified". The
+  // entries carry zero snapshot counts because the tree's row decoration
+  // always finds live counts in `liveStats` for tracked placeholders; the
+  // edited contents themselves live in the shared editor's persist-state
+  // document cache, not here.
   const editedPlaceholderFiles = useMemo<AuiChangedFile[]>(
     () =>
-      editedPlaceholders.map((path) =>
-        makeEditedPlaceholder(
+      editedPlaceholders.map((path) => {
+        const before = getPlaceholderContents(path);
+        return {
           path,
-          editsRef.current.get(path) ?? getPlaceholderContents(path)
-        )
-      ),
+          status: 'modified' as const,
+          before,
+          after: before,
+          additions: 0,
+          deletions: 0,
+        };
+      }),
     [editedPlaceholders]
   );
 
@@ -1064,6 +1029,7 @@ export function AgentUi({
 
   const editorOptions = useMemo<EditorOptions<undefined>>(
     () => ({
+      persistState: true,
       enabledSelectionAction: true,
       renderSelectionAction(selectionAction) {
         const container = document.createElement('div');
@@ -1104,12 +1070,28 @@ export function AgentUi({
         container.append(addToChat, copy);
         return container;
       },
+      onAttach(editor) {
+        // Selecting a file leaves keyboard focus in the tree, so undo/redo
+        // shortcuts would silently go nowhere until the user clicks back into
+        // the code — reading as a lost edit history even though the
+        // persist-state document cache restored it. When a file switch lands,
+        // hand focus to the editor; preventScroll keeps the restored viewport
+        // position. The initial auto-opened file must not steal page focus.
+        const target = activeTargetRef.current;
+        if (
+          lastAttachedPathRef.current !== null &&
+          lastAttachedPathRef.current !== target
+        ) {
+          editor.focus({ preventScroll: true });
+        }
+        lastAttachedPathRef.current = target;
+      },
       onChange(file) {
         const target = activeTargetRef.current;
         if (target == null) {
           return;
         }
-        editsRef.current.set(target, file.contents);
+        editedPathsRef.current.add(target);
         // Recompute the edited file's diff against its original snapshot so the
         // Changes tree's +/- totals reflect the live edits.
         recordEditedStatsRef.current(target, file.contents);
@@ -1143,57 +1125,30 @@ export function AgentUi({
     [activePath, activeFile]
   );
 
-  const editKey = activeFile?.path ?? '';
-
-  // Rebuild the diff surface whenever the active file changes, substituting any
-  // persisted edits for the snapshot's `after`.
-  const fileDiff = useMemo(
-    () =>
-      activeFile != null
-        ? getFileDiff(activeFile, editsRef.current.get(editKey))
-        : null,
-    [activeFile, editKey]
-  );
+  // The active file's diff metadata: parsed once on first visit, then reused
+  // from the cache so revisits render the content the last edit session wrote
+  // back into it.
+  const fileDiff = useMemo(() => {
+    if (activeFile == null) {
+      return null;
+    }
+    let diff = diffsRef.current.get(activeFile.path);
+    if (diff == null) {
+      diff = getFileDiff(activeFile);
+      diffsRef.current.set(activeFile.path, diff);
+    }
+    return diff;
+  }, [activeFile]);
 
   // Server-rendered, already-highlighted HTML for the active diff. Only safe
   // when the file is unedited so the markup matches `fileDiff`.
   const activePrerenderedHTML =
-    activePath != null && editsRef.current.get(editKey) == null
+    activePath != null && !editedPathsRef.current.has(activePath)
       ? prerenderedDiffs?.[activePath]
       : undefined;
 
   const breadcrumbSegments = activePath != null ? activePath.split('/') : [];
 
-  // Re-adopt the jade/red line-number override whenever the diff surface is
-  // rebuilt (each file switch remounts the diffs-container with a fresh shadow
-  // root).
-  const surfaceWrapRef = useRef<HTMLDivElement | null>(null);
-  useEffect(() => {
-    const sheet = getLineNumberColorSheet();
-    if (sheet == null) {
-      return;
-    }
-    const container = surfaceWrapRef.current?.querySelector('.aui-surface');
-    const shadowRoot = container?.shadowRoot;
-    if (shadowRoot == null) {
-      return;
-    }
-    if (!shadowRoot.adoptedStyleSheets.includes(sheet)) {
-      shadowRoot.adoptedStyleSheets = [...shadowRoot.adoptedStyleSheets, sheet];
-    }
-  }, [activePath]);
-
-  // `key={activePath}` remounts the FileDiff or File surface for each file while
-  // `.aui-surface-wrap` remains mounted and retains its scroll offset. Reset the
-  // outer host after the new surface is laid out but before paint. Editing a
-  // file does not change `activePath`, so this never disturbs a session.
-  useIsomorphicLayoutEffect(() => {
-    const wrap = surfaceWrapRef.current;
-    if (wrap != null) {
-      wrap.scrollTop = 0;
-    }
-  }, [activePath]);
-
   const changedCount = changesSession.changedFiles.length;
 
   return (
@@ -1268,7 +1223,14 @@ export function AgentUi({
             </nav>
           </header>
 
-          <div className="aui-surface-wrap" ref={surfaceWrapRef}>
+          <Virtualizer
+            className="aui-surface-wrap"
+            contentStyle={{
+              display: 'flex',
+              minHeight: '100%',
+              width: '100%',
+            }}
+          >
             {activeFile != null && fileDiff != null ? (
               <FileDiff
                 key={activePath}
@@ -1281,17 +1243,19 @@ export function AgentUi({
               />
             ) : placeholderContents != null && activePath != null ? (
               // Editable view for explorer files that aren't part of the change
-              // set (e.g. the root README or a generated stub). The app-level
-              // provider creates an independent editor for this keyed surface.
-              // Caller-owned `editsRef` seeds its contents when revisited.
+              // set (e.g. the root README or a generated stub). Always mounts
+              // with the pristine placeholder contents: `cacheKey` is required
+              // by the shared editor's `persistState`, whose per-file document
+              // cache substitutes any previously edited contents (and their
+              // undo history) when the surface re-attaches.
               // Highlighted on the main thread since this File is mounted
               // dynamically outside the editable surface's worker pool.
               <File
                 key={activePath}
                 file={{
                   name: activePath,
-                  contents:
-                    editsRef.current.get(activePath) ?? placeholderContents,
+                  cacheKey: activePath,
+                  contents: placeholderContents,
                 }}
                 className="aui-surface"
                 options={{
@@ -1307,7 +1271,7 @@ export function AgentUi({
             ) : (
               <div className="aui-empty">Select a file to review.</div>
             )}
-          </div>
+          </Virtualizer>
 
           <div className="aui-composer">
             {snippets.length > 0 && (
diff --git a/apps/docs/app/(diffs)/_home/agent-ui.css b/apps/docs/app/(diffs)/_home/agent-ui.css
index c425aab0f..24f136619 100644
--- a/apps/docs/app/(diffs)/_home/agent-ui.css
+++ b/apps/docs/app/(diffs)/_home/agent-ui.css
@@ -201,15 +201,22 @@ button.aui-dot.is-zoom:hover {
   overscroll-behavior: contain;
 }
 
+/* The surface and the empty state are now single children of the Virtualizer's
+   row-flex content element (see VIRTUALIZER_CONTENT_STYLE in AgentUi.tsx):
+   flex-grow fills the scroller's width, and the default align-items: stretch
+   fills its height (which is why .aui-empty must not set height: 100% — a
+   definite height would opt it out of stretching). */
 .aui-surface {
   display: block;
+  flex: 1 1 auto;
+  min-width: 100%;
 }
 
 .aui-empty {
   display: flex;
+  flex: 1 1 auto;
   align-items: center;
   justify-content: center;
-  height: 100%;
   color: var(--ide-fg-muted);
 }
 
diff --git a/apps/docs/app/(diffs)/docs/Edit/EditDemo.tsx b/apps/docs/app/(diffs)/docs/Edit/EditDemo.tsx
deleted file mode 100644
index d95b64093..000000000
--- a/apps/docs/app/(diffs)/docs/Edit/EditDemo.tsx
+++ /dev/null
@@ -1,46 +0,0 @@
-'use client';
-
-import { File } from '@pierre/diffs/react';
-import type { PreloadedFileResult } from '@pierre/diffs/ssr';
-import { useMemo, useState } from 'react';
-
-interface EditDemoProps {
-  // Server-preloaded, already-highlighted file. Spreading it into <File> ships
-  // the highlighted surface in the initial SSR HTML and hydrates from it, so
-  // the demo paints instantly instead of flashing in after the client attaches
-  // the editor.
-  prerenderedFile: PreloadedFileResult<undefined>;
-}
-
-export function EditDemo({ prerenderedFile }: EditDemoProps) {
-  const [changeCount, setChangeCount] = useState(0);
-  const editorOptions = useMemo(
-    () => ({
-      onChange() {
-        setChangeCount((count) => count + 1);
-      },
-    }),
-    []
-  );
-  return (
-    <div className="not-prose bg-card overflow-hidden rounded-lg border">
-      <div className="flex flex-wrap items-center justify-between gap-3 border-b px-4 py-3">
-        <div>
-          <h5 className="text-sm font-medium">Edit mode demo</h5>
-          <p className="text-muted-foreground text-xs">
-            Click into the code and type to try edit mode.
-          </p>
-        </div>
-        <div className="text-muted-foreground text-xs">
-          Changes: {changeCount}
-        </div>
-      </div>
-      <File
-        {...prerenderedFile}
-        className="max-h-[480px] overflow-auto rounded-none border-0"
-        edit
-        editorOptions={editorOptions}
-      />
-    </div>
-  );
-}
diff --git a/apps/docs/app/(diffs)/docs/Edit/constants.ts b/apps/docs/app/(diffs)/docs/Edit/constants.ts
index a2f38c549..e71a8fd78 100644
--- a/apps/docs/app/(diffs)/docs/Edit/constants.ts
+++ b/apps/docs/app/(diffs)/docs/Edit/constants.ts
@@ -1,4 +1,3 @@
-import type { FileOptions } from '@pierre/diffs/react';
 import type { PreloadFileOptions } from '@pierre/diffs/ssr';
 
 import { CustomScrollbarCSS } from '@/components/CustomScrollbarCSS';
@@ -9,50 +8,6 @@ const options = {
   unsafeCSS: CustomScrollbarCSS,
 } as const;
 
-// Enabling the token transformer in the server render keeps the markup
-// editor-ready, so hydration does not rerender the surface when the editor
-// attaches. Mirrors `(diffs)/_edit/constants.ts`.
-const editableDemoOptions: FileOptions<undefined> = {
-  theme: { dark: 'pierre-dark', light: 'pierre-light' },
-  disableFileHeader: true,
-  useTokenTransformer: true,
-};
-
-// The file rendered by the interactive `<EditDemo />` on the Edit page.
-// Preloaded server-side so the surface is highlighted in the initial HTML
-// instead of flashing in after the client attaches the editor.
-export const EDIT_DEMO_FILE_EXAMPLE: PreloadFileOptions<undefined> = {
-  file: {
-    name: 'editable-demo.ts',
-    contents: `import { VirtualizedFile } from '@pierre/diffs';
-import { Editor } from '@pierre/diffs/edit';
-
-const fileInstance = new VirtualizedFile({
-  theme: { dark: 'pierre-dark', light: 'pierre-light' },
-});
-
-// render the file into a DOM container
-fileInstance.render({
-  file: { name: 'index.ts', contents: 'export const foo: string = "bar";\\n' },
-  containerWrapper: document.getElementById('file-container')
-});
-
-const editor = new Editor({
-  onChange(file, lineAnnotations) {
-    console.log('change', file.name, lineAnnotations);
-  },
-});
-
-// Attach the editor to the file instance
-const dispose = editor.edit(fileInstance);
-
-// Later, when the editor is no longer needed:
-dispose();
-`,
-  },
-  options: editableDemoOptions,
-};
-
 export const EDIT_VANILLA_FILE_EXAMPLE: PreloadFileOptions<undefined> = {
   file: {
     name: 'editor_vanilla_file.ts',
@@ -393,6 +348,78 @@ export const EDIT_SELECTION_ACTION_CONTEXT_TYPE: PreloadFileOptions<undefined> =
     options,
   };
 
+export const EDIT_PERSIST_STATE_EXAMPLE: PreloadFileOptions<undefined> = {
+  file: {
+    name: 'editor_persist_state.ts',
+    contents: `import type { FileContents } from '@pierre/diffs';
+import { Editor } from '@pierre/diffs/edit';
+
+// Unique, stable cacheKeys identify each file's cached document and its
+// stored editor state.
+const fileA: FileContents = {
+  name: 'a.ts',
+  contents: 'export const a = 1;',
+  cacheKey: 'a.ts',
+};
+const fileB: FileContents = {
+  name: 'b.ts',
+  contents: 'export const b = 2;',
+  cacheKey: 'b.ts',
+};
+
+// \`fileInstance\` is a rendered File — see the Vanilla JS section above.
+const editor = new Editor({ persistState: true });
+editor.edit(fileInstance);
+fileInstance.render({ file: fileA });
+
+// ...the user edits, selects, and scrolls fileA...
+
+// Switching files caches fileA's document (contents + undo history) on the
+// editor and writes its selections and scroll offsets to the state storage.
+// fileB has no record yet, so its surface starts scrolled to the top.
+fileInstance.render({ file: fileB });
+
+// Switching back renders fileA's edited contents — even though the original
+// \`contents\` string is passed again — and restores its selections, scroll
+// position, and undo history.
+fileInstance.render({ file: fileA });`,
+  },
+  options,
+};
+
+export const EDIT_PERSIST_STATE_REACT_EXAMPLE: PreloadFileOptions<undefined> = {
+  file: {
+    name: 'editor_persist_state_react.tsx',
+    contents: `import type { FileContents } from '@pierre/diffs';
+import { Editor, type EditorOptions } from '@pierre/diffs/edit';
+import { type CreateEditor, EditProvider, File } from '@pierre/diffs/react';
+import { useCallback, useMemo } from 'react';
+
+// Editors are cached by \`editorOptions\` object identity, so the stable
+// options object below hands every file rendered here the same editor. Its
+// cached documents and default 'inMemory' state store live on that instance,
+// which is what lets per-file contents, selections, and scroll survive
+// surface remounts.
+export function PersistedEditor({ file }: { file: FileContents }) {
+  const createEditor = useCallback<CreateEditor<undefined>>(
+    (options) => new Editor(options),
+    []
+  );
+  const editorOptions = useMemo<EditorOptions<undefined>>(
+    () => ({ persistState: true }),
+    []
+  );
+
+  return (
+    <EditProvider createEditor={createEditor}>
+      <File file={file} edit editorOptions={editorOptions} />
+    </EditProvider>
+  );
+}`,
+  },
+  options,
+};
+
 export const EDIT_MARKER_TYPE: PreloadFileOptions<undefined> = {
   file: {
     name: 'marker.ts',
@@ -474,6 +501,7 @@ export function EditableFileWithHistoryToolbar() {
   const editorRef = useRef<Editor<undefined> | null>(null);
   const editorOptions = useMemo<EditorOptions<undefined>>(
     () => ({
+      historyMaxEntries: 100,
       onAttach(editor) {
         editorRef.current = editor;
       },
@@ -487,9 +515,6 @@ export function EditableFileWithHistoryToolbar() {
     []
   );
 
-  // This example is self-contained. Apps should usually mount EditProvider near
-  // the root so its factory is available to every editable File, diff, and
-  // CodeView.
   return (
     <EditProvider createEditor={createEditor}>
       <div className="toolbar">
@@ -512,6 +537,56 @@ export function EditableFileWithHistoryToolbar() {
   options,
 };
 
+export const EDIT_REACT_CREATE_EDITOR_EXAMPLE: PreloadFileOptions<undefined> = {
+  file: {
+    name: 'editor_react_create_editor.tsx',
+    contents: `const createEditor = useCallback<CreateEditor<undefined>>(
+  (surfaceOptions) =>
+    new Editor({
+      ...defaultEditorOptions,
+      ...surfaceOptions,
+    }),
+  []
+);
+
+const editorOptions = useMemo<EditorOptions<undefined>>(
+  () => ({
+    onChange: handleChange,
+    onAttach(editor) {
+      editorRef.current = editor;
+    },
+  }),
+  [handleChange]
+);
+
+// Mount EditProvider near the root so its editors are available to every
+// editable File, diff, and CodeView.
+return (
+  <EditProvider createEditor={createEditor}>
+    <File file={file} edit={editing} editorOptions={editorOptions} />
+  </EditProvider>
+);`,
+  },
+  options,
+};
+
+export const EDIT_REACT_SHARED_EDITOR_EXAMPLE: PreloadFileOptions<undefined> = {
+  file: {
+    name: 'editor_react_shared_editor.tsx',
+    contents: `const editorOptions = useMemo<EditorOptions<undefined>>(
+  () => ({ persistState: true, onChange: handleChange }),
+  [handleChange]
+);
+
+return (
+  <EditProvider createEditor={createEditor}>
+    <File file={activeFile} edit editorOptions={editorOptions} />
+  </EditProvider>
+);`,
+  },
+  options,
+};
+
 export const EDIT_REACT_EXAMPLE: PreloadFileOptions<undefined> = {
   file: {
     name: 'editor_react.tsx',
@@ -975,15 +1050,22 @@ interface EditorOptions<LAnnotation> {
   // (default: 'default' — both quotes and brackets)
   autoSurround?: 'default' | 'never' | 'brackets' | 'quotes' | 'languageDefined';
 
+  // Per-language comment tokens for the toggle-comment commands, merged over
+  // the built-in defaults ('//' and '/* */'). A null lineComment disables
+  // line comments for that language.
+  languageCommentConfig?: Record<
+    string,
+    { lineComment?: string | null; blockComment?: readonly [string, string] }
+  >;
+
   // Show the floating Selection Action popover after a user selection.
   // Programmatic setSelections/setState calls do not open it (default: false).
   enabledSelectionAction?: boolean;
 
-  // Custom clipboard provider.
-  // Highly recommended to use native clipboard API if you are building an electron app.
-  // see https://www.electronjs.org/docs/latest/api/clipboard
+  // Custom clipboard provider. Recommended in Electron apps — use the native
+  // clipboard API: https://www.electronjs.org/docs/latest/api/clipboard
   clipboard?: {
-    readText: () => Promise<string> | string;
+    readText: (type?: string) => Promise<string> | string;
   };
 
   // Custom Selection Action UI. See Selection Action docs for context shape.
@@ -1018,6 +1100,48 @@ interface EditorOptions<LAnnotation> {
   options,
 };
 
+export const EDIT_ON_ATTACH_REACT_EXAMPLE: PreloadFileOptions<undefined> = {
+  file: {
+    name: 'editor_on_attach_react.tsx',
+    contents: `const editorOptions = useMemo<EditorOptions<undefined>>(
+  () => ({
+    onAttach(editor) {
+      editor.focus({ lineNumber: 'first-visible', preventScroll: true });
+    },
+  }),
+  []
+);
+
+return <CodeView items={items} editorOptions={editorOptions} />;`,
+  },
+  options,
+};
+
+export const EDIT_ON_ATTACH_VANILLA_EXAMPLE: PreloadFileOptions<undefined> = {
+  file: {
+    name: 'editor_on_attach_vanilla.ts',
+    contents: `const viewer = new CodeView({
+  createEditor(options) {
+    return new Editor({
+      ...options,
+      onAttach(editor) {
+        editor.focus({ lineNumber: 'first-visible', preventScroll: true });
+      },
+    });
+  },
+});`,
+  },
+  options,
+};
+
+export const EDIT_FOCUS_POSITION_EXAMPLE: PreloadFileOptions<undefined> = {
+  file: {
+    name: 'editor_focus_position.ts',
+    contents: `editor.focus({ lineNumber: 13, character: 4 });`,
+  },
+  options,
+};
+
 export const EDIT_ON_CHANGE_EXAMPLE: PreloadFileOptions<undefined> = {
   file: {
     name: 'editor_on_change.ts',
@@ -1099,14 +1223,14 @@ const file: FileContents | undefined = editor.getFile();
 // Full document text, or '' when nothing is attached.
 const text: string = editor.getText();
 
-// Snapshot selections and horizontal code position for explicit restoration.
+// Snapshot selections and scroll positions for explicit restoration:
 const state: EditorState = editor.getState();
 // EditorState = {
 //   selections?: EditorSelection[];
-//   view?: { scrollLeft: number };
+//   view?: { scrollLeft: number; scrollTop?: number };
 // }
 
-// Restore selections and horizontal code position after re-rendering.
+// Restore selections and scroll positions after re-rendering.
 editor.setState(state);
 
 // Replace all cursors and ranges programmatically. Positions are zero-based;
diff --git a/apps/docs/app/(diffs)/docs/Edit/content.mdx b/apps/docs/app/(diffs)/docs/Edit/content.mdx
index b1f71bcc7..94b9d2f2f 100644
--- a/apps/docs/app/(diffs)/docs/Edit/content.mdx
+++ b/apps/docs/app/(diffs)/docs/Edit/content.mdx
@@ -12,11 +12,13 @@ virtualization.
 Edit mode features include:
 
 - Text editing
-- Selection management, including multiple cursors
+- Multiple cursors
 - Automatic indentation
+- Brace matching
 - History (undo and redo)
 - Find-in-file search and replace
 - [Selection Action](#edit-mode-selection-action) (opt-in, custom UI)
+- Markers (inline diagnostics)
 - SSR support
 - Mobile-friendly
 - Lightweight
@@ -24,32 +26,24 @@ Edit mode features include:
 Use the `Editor` API to add editing to `File`, `FileDiff`, `MultiFileDiff`, and
 `PatchDiff`, or to individual `CodeView` items. In React, wrap editable surfaces
 in `EditProvider`, then set a standalone surface's `edit` prop or a `CodeView`
-item's `edit` flag. In vanilla JS, call `editor.edit(component)` after rendering
-a standalone surface, or give `CodeView` its own `createEditor` option.
+item's `edit` flag. In vanilla JS, call `editor.edit(fileInstance)` after
+rendering a standalone surface, or give `CodeView` its own `createEditor`
+option.
 
-Edit mode is not a full-fledged IDE, though you may certainly use it to create
-your own IDE-like experiences. Edit mode is purpose-built and best suited for
-editing code rendered by our Diffs library. It builds on our already powerful
-file and diff surfaces to preserve diff layout, annotations, syntax
-highlighting, SSR, and virtualization while adding editing, multiple selections,
-history, search and replace, and markers. This makes it most ideal for “review
-and correct” flows with generative code changes.
-
-### Demo
-
-To enable edit mode on a `File` instance, import `Editor` from
-`@pierre/diffs/edit`. It is intentionally separate from the core bundle so you
-can lazy-load it when editing is optional.
-
-<EditDemo prerenderedFile={editDemoFile} />
+Edit mode is not a full-fledged IDE, though you can build IDE-like experiences
+on top of it. It is purpose-built for code rendered by this library: the
+existing file and diff surfaces keep their diff layout, annotations, syntax
+highlighting, SSR, and virtualization, and edit mode adds editing, multiple
+selections, history, search and replace, and markers. That focus makes it a
+natural fit for “review and correct” flows with generative code changes.
 
 ### How It Works
 
 Edit mode does not replace `File`, `FileDiff`, or their virtualized variants.
 You render the surface first, then attach editing:
 
-1. **Attach** — Call `editor.edit(component)` in vanilla JS, or pass `edit` on a
-   React `File`, `FileDiff`, `MultiFileDiff`, or `PatchDiff` wrapped in
+1. **Attach** — Call `editor.edit(fileInstance)` in vanilla JS, or pass `edit`
+   on a React `File`, `FileDiff`, `MultiFileDiff`, or `PatchDiff` wrapped in
    `EditProvider`. For React `CodeView`, use the same provider and set
    `edit: true` on an item. Vanilla `CodeView` instead takes
    `CodeViewOptions.createEditor`. The hookup returns a dispose function for a
@@ -76,14 +70,100 @@ expand buttons keep working. The diff layout is preserved, so a `FileDiff` or
 `MultiFileDiff` stays in whatever view it was rendered in; in unified diffs,
 deleted lines and annotation lines remain read-only.
 
-### Editing with line annotations
+### React
+
+Wrap editable surfaces in a permanently mounted `EditProvider`, then toggle the
+standalone surface's `edit` prop or a `CodeView` item's `edit` flag. Standalone
+surface DOM and imperative file/diff instances stay mounted across the toggle.
+The provider's `createEditor` factory gives each editable surface or `CodeView`
+item its own `Editor`, cached by `editorOptions` object identity: an edit
+session that restarts with the same options object reuses its editor, and
+surfaces editable at the same time need distinct options objects.
+
+Pass creation-time callbacks and behavior through the surface's `editorOptions`;
+the factory can spread shared defaults before the surface options so the surface
+wins. Keep factories and object props stable: define static values at module
+scope, or use `useCallback` and `useMemo` when they depend on component values.
+
+<DocsCodeExample {...editReactCreateEditorExample} />
+
+Because editors are cached by options identity, passing one stable
+`editorOptions` object to every surface shares one `Editor` across them. This is
+the pattern for IDE-like UIs that edit one file at a time across many files,
+normally combined with `persistState` so each file's contents, history,
+selections, and scroll position survive switches — see
+[Persisting Editor State](#edit-mode-persisting-editor-state):
+
+<DocsCodeExample {...editReactSharedEditorExample} />
+
+Changes to `createEditor` or `editorOptions` do not disturb an active edit
+session; their latest values apply the next time `edit` transitions from false
+to true. Use `onAttach` with your own ref when controls need imperative APIs
+such as history, selections, markers, save, or search. Use `Virtualizer` for
+large editable files. The `FileDiff` tab below shows the controlled annotation
+feedback loop.
+
+<EditComponentTabs
+  fileExample={editReactExample}
+  fileDiffExample={editReactFileDiffExample}
+  multiFileDiffExample={editReactMultiFileDiffExample}
+/>
+
+### Vanilla JS
+
+Render with `File` or `FileDiff` first, then attach the editor with
+`editor.edit(component)`. Use `VirtualizedFile` and `VirtualizedFileDiff` for
+large editable files. Keep any emitted annotation collection in your external
+source of truth before a later render. Call `cleanUp()` when the editor is
+removed. The `FileDiff` tab below includes this synchronization.
+
+<EditComponentTabs
+  fileExample={editVanillaFileExample}
+  fileDiffExample={editVanillaFileDiffExample}
+/>
+
+### CodeView
+
+`CodeView` manages one `Editor` per editable item. In React, wrap it in the same
+app-level `EditProvider` used by other editable surfaces, set `edit: true` on an
+item, and pass creation-time item-editor behavior through the `CodeView`
+`editorOptions` prop. In vanilla JS, pass `createEditor` in `CodeViewOptions`
+instead. Increment the item's `version` whenever `edit` changes.
+
+`CodeView` uses item-aware callbacks instead of `editorOptions.onChange`.
+`onItemEditChange` receives the owning item with each live change: replace that
+item's annotations whenever the emitted array changes, and increment its
+`version`. This live update keeps annotation coordinates synchronized throughout
+the edit session. `onItemEditComplete` receives the item and latest contents
+when a changed session ends because editing is disabled or the item is collapsed
+or removed. Sessions with no changes do not emit it. Resetting, cleaning up, or
+unmounting the viewer is silent teardown.
+
+Persist edited contents to the item's `file`, or rebuild its `fileDiff`. Assign
+a fresh `cacheKey` and increment `version`; `CodeView` does not update item data
+for you.
+
+<CodeViewExampleTabs
+  reactExample={editReactCodeViewExample}
+  vanillaExample={editVanillaCodeViewExample}
+/>
+
+Editors retain their document and history while items move in and out of the
+virtualized window.
+
+`editorOptions` and provider-factory changes are creation-time inputs: active
+item sessions keep their current editor, while the latest values apply to the
+next item that enters edit mode. Simultaneously edited items always receive
+independent editor instances.
+
+### Editing with Line Annotations
 
 Applications own the annotation collection passed to a `File`, `FileDiff`, or
 other editable surface. When an edit affects annotation coordinates, the editor
 remaps them and passes the complete current collection as `onChange`'s second
 argument alongside the edited file. This collection is authoritative when
-present; it is not a delta. Replace your application-owned collection with it
-before a later render can reapply stale coordinates.
+present; it is not a delta. Replace your application-owned collection with it;
+otherwise a later render reapplies stale coordinates.
 
 The editor preserves the existing array reference for ordinary same-line edits
 and other edits that do not affect any annotation. When a structural edit
@@ -150,253 +230,74 @@ annotation, enable editing, insert a line above it, remove its logical line,
 then use undo and redo. The playground controls demonstrate the integration;
 they are not additional public editor options.
 
-### React
-
-Give a permanently mounted `EditProvider` a stable `createEditor` factory, then
-toggle only the standalone surface's `edit` prop or a `CodeView` item's `edit`
-flag. The provider does not own an editor instance. Each editable `File`,
-`FileDiff`, `MultiFileDiff`, or `PatchDiff` surface and each editable `CodeView`
-item creates its own editor when an edit session starts. Standalone surface DOM
-and imperative file/diff instances stay mounted across the toggle.
-
-Pass creation-time callbacks and behavior through the surface's `editorOptions`.
-A provider can add shared defaults by spreading them before the surface options,
-so the surface wins. Keep factories and object props stable: define static
-values at module scope, or use `useCallback` for factories and callbacks and
-`useMemo` for `options` and `editorOptions` when they depend on component
-values.
-
-```tsx
-const createEditor = useCallback<CreateEditor<undefined>>(
-  (surfaceOptions) =>
-    new Editor({
-      ...sharedEditorDefaults,
-      ...surfaceOptions,
-    }),
-  []
-);
-
-const editorOptions = useMemo<EditorOptions<undefined>>(
-  () => ({
-    onChange: handleChange,
-    onAttach(editor) {
-      editorRef.current = editor;
-    },
-  }),
-  [handleChange]
-);
-
-// This example is self-contained. Apps should usually mount EditProvider near
-// the root so its factory is available to every editable File, diff, and
-// CodeView.
-return (
-  <EditProvider createEditor={createEditor}>
-    <File file={file} edit={editing} editorOptions={editorOptions} />
-  </EditProvider>
-);
-```
-
-Changes to `createEditor` or `editorOptions` do not disturb an active edit
-session. Their latest values apply the next time `edit` transitions from false
-to true. Re-entering edit mode creates a fresh editor with fresh history and
-state. Sibling editable surfaces receive independent editors and callbacks; use
-`onAttach` with your own ref when controls need imperative APIs such as history,
-selections, markers, save, or search. Use `Virtualizer` for large editable
-files. The `FileDiff` tab below shows the controlled annotation feedback loop.
-
-<EditComponentTabs
-  fileExample={editReactExample}
-  fileDiffExample={editReactFileDiffExample}
-  multiFileDiffExample={editReactMultiFileDiffExample}
-/>
-
-### Vanilla JS
-
-Render with `File` or `FileDiff` first, then attach the editor with
-`editor.edit(component)`. Use `VirtualizedFile` and `VirtualizedFileDiff` for
-large editable files. Keep any emitted annotation collection in your external
-source of truth before a later render. Call `cleanUp()` when the editor is
-removed. The `FileDiff` tab below includes this synchronization.
-
-<EditComponentTabs
-  fileExample={editVanillaFileExample}
-  fileDiffExample={editVanillaFileDiffExample}
-/>
-
-### CodeView
-
-`CodeView` manages one `Editor` per editable item. In React, wrap it in the same
-app-level `EditProvider` used by other editable surfaces, set `edit: true` on an
-item, and pass creation-time item-editor behavior through the `CodeView`
-`editorOptions` prop. In vanilla JS, pass `createEditor` in `CodeViewOptions`
-instead. Increment the item's `version` whenever `edit` changes.
-
-`CodeView` uses item-aware callbacks instead of `editorOptions.onChange`.
-`onItemEditChange` receives the owning item with each live change: replace that
-item's annotations whenever the emitted array changes, and increment its
-`version`. This live update keeps annotation coordinates synchronized throughout
-the edit session. `onItemEditComplete` receives the item and latest contents
-when a changed session ends because editing is disabled or the item is collapsed
-or removed. Sessions with no changes do not emit it. Resetting, cleaning up, or
-unmounting the viewer is silent teardown.
-
-Persist edited contents to the item's `file`, or rebuild its `fileDiff`. Assign
-a fresh `cacheKey` and increment `version`; `CodeView` does not update item data
-for you.
-
-<CodeViewExampleTabs
-  reactExample={editReactCodeViewExample}
-  vanillaExample={editVanillaCodeViewExample}
-/>
-
-Editors retain their document and history while items move in and out of the
-virtualized window.
-
-`editorOptions` and provider-factory changes are creation-time inputs: active
-item sessions keep their current editor, while the latest values apply to the
-next item that enters edit mode. Simultaneously edited items always receive
-independent editor instances.
-
-### Autofocus on Attach
-
-Use `onAttach` to opt into initial caret placement. At this point the text
-document and editable DOM are ready. In React, pass a stable `editorOptions`
-object to any editable surface, including `CodeView`:
-
-```tsx
-const editorOptions = useMemo<EditorOptions<undefined>>(
-  () => ({
-    onAttach(editor) {
-      editor.focus({ lineNumber: 'first-visible', preventScroll: true });
-    },
-  }),
-  []
-);
-
-return <CodeView items={items} editorOptions={editorOptions} />;
-```
-
-Vanilla `CodeView` can add the same behavior in its editor factory:
-
-```ts
-const viewer = new CodeView({
-  createEditor(options) {
-    return new Editor({
-      ...options,
-      onAttach(editor) {
-        editor.focus({ lineNumber: 'first-visible', preventScroll: true });
-      },
-    });
-  },
-});
-```
-
-`'first-visible'` selects the first editable row whose top falls inside the
-usable viewport and places the caret at character zero. If no editable row top
-is visible, the call does nothing. Set `offset` to a non-negative number of CSS
-pixels to move the usable top below the viewport if needed. With
-`preventScroll: true`, the focus request does not change the vertical scroll
-position.
-
-You can also target a specific document position:
-
-```ts
-editor.focus({ lineNumber: 13, character: 4 });
-```
+### Selection Action
 
-Numeric `lineNumber` values are one-based, while `character` values are
-zero-based. Numeric targeting works on every attached editor. Any targeted focus
-replaces the current selection, so use either this initial placement or restored
-selection/view state as the owner of the edit session's starting position, not
-both. `CodeView` retains an editor while its item is recycled, so `onAttach` is
-not repeated for virtualized remounts in the same edit session.
+Selection Action is an opt-in edit mode feature for showing custom UI alongside
+the current selection — useful for quick transforms, refactor prompts, or other
+selection-scoped tools. Set `enabledSelectionAction: true` and return your UI
+from `renderSelectionAction`; a floating popover holding your UI appears after
+the user creates a ranged selection. Programmatic `setSelections` and `setState`
+calls update the selection without opening the popover. The popover can hold any
+number of actions.
 
-### Editor Options
+<DocsCodeExample {...editSelectionActionExample} />
 
-Pass these when constructing `new Editor({ ... })`, or update them later with
-[`setOptions`](#edit-mode-api-reference).
+`renderSelectionAction` runs when the popover opens. Its context includes the
+active `selection`, the editable `textDocument`, helpers to read or modify the
+selection (`getSelectionText`, `replaceSelectionText`, `applyEdits`), and
+`close` to dismiss the popover:
 
-<DocsCodeExample {...editorOptionsType} />
+<DocsCodeExample {...editSelectionActionContextType} />
 
-`EditorKeymap` is an array of `{ platform?, bindings }` groups. `platform` can
-be `mac`, `windows`, or `linux`; omit it to enable the group's bindings
-everywhere. Later groups take precedence when bindings overlap. When set, custom
-bindings take precedence, while unmatched shortcuts fall back to the built-in
-keymap. Keymaps are immutable; pass a new array to `setOptions` to change one.
+### Persisting Editor State
 
-#### `onChange`
+By default, each edit session starts fresh: switching files (or re-entering edit
+mode) discards the previous file's edits, history, and selections. Set
+`persistState: true` to keep per-file state alive across file switches on the
+same `Editor` instance. State is keyed by the file's `cacheKey`, so every
+editable file must provide one — unique and stable (the editor throws
+otherwise). Diffs parsed with `parseDiffFromFile` derive a cache key from the
+file pair automatically.
 
-The third argument is an `EditorChangeEvent`. Its `changes` array contains every
-normalized edit in the change:
+Two layers persist:
 
-<DocsCodeExample {...editOnChangeExample} />
+- **File contents and undo history.** The editor caches each file's text
+  document on the instance. When a file whose `cacheKey` it has already seen
+  attaches again, the editor swaps the cached document back in — the host keeps
+  passing the original `contents`, and the edited text with its full undo
+  timeline returns.
+- **Editor state.** Selections and scroll positions — the code scroller's
+  `scrollLeft` and the surrounding viewport's `scrollTop` — are written to
+  `persistStateStorage` when the editor detaches or switches files, and restored
+  on the next attach with the same `cacheKey`. If the user scrolls before an
+  async restore lands, the restore leaves the viewport alone.
 
-Ranges use zero-based line and character positions.
+A file with no stored record yet — its first open — starts scrolled to the top
+instead of inheriting whatever offset the previous file left behind in a shared
+scroll container.
 
-#### Persisting file state
-
-State persistence is disabled by default. Set `persistState: true` to preserve
-an editable `File`'s text document, undo history, selections, and horizontal
-code scroll position when the attached file renders a different file and later
-returns. This currently applies to `File` and `VirtualizedFile` surfaces; diff
-surfaces do not use the persistence cache.
-
-Every editable file must provide an explicit, non-empty `file.cacheKey` while
-`persistState` is enabled. The editor throws if it encounters an unkeyed file;
-it does not fall back to `file.name`. Cache keys must be unique and stable
-within the persistence storage namespace. Reuse the same key when a rename or
-move should resume the same editing session; change it when new incoming
-contents should start a fresh document.
-
-```ts
-import type { EditorState, FileContents } from '@pierre/diffs';
-import { Editor, type IStateStorage } from '@pierre/diffs/edit';
-
-const editor = new Editor({
-  persistState: true,
-  persistStateStorage: 'inMemory',
-});
-
-const file: FileContents = {
-  name: 'src/example.ts',
-  contents: 'export const value = 1;',
-  cacheKey: 'workspace-file-1',
-};
-
-// Custom storage may be synchronous or asynchronous.
-const states = new Map<string, EditorState>();
-const customStorage: IStateStorage = {
-  get(cacheKey) {
-    return states.get(cacheKey);
-  },
-  set(cacheKey, state) {
-    states.set(cacheKey, state);
-  },
-};
-
-const editorWithCustomStorage = new Editor({
-  persistState: true,
-  persistStateStorage: customStorage,
-});
-```
-
-`persistStateStorage` accepts `'inMemory'`, `'indexedDB'`, or an `IStateStorage`
-implementation. It defaults to `'inMemory'`. Text documents and undo history
-remain scoped to the `Editor` instance; IndexedDB and custom storage persist
-only serializable item-local editor state.
+<DocsCodeExample {...editPersistStateExample} />
 
-### API Reference
+`persistStateStorage` selects where the serializable state lives: `'inMemory'`
+(the default) lasts as long as the `Editor` instance, `'indexedDB'` survives
+page reloads, and a custom `IStateStorage` — an object with `get(cacheKey)` and
+`set(cacheKey, state)`, synchronous or async — bridges to your own store. Cached
+text documents always stay on the editor instance regardless of the storage
+choice, so persisting content across file switches means reusing one editor
+rather than creating one per file.
 
-These methods are available on an `Editor` instance. Attach it to a rendered
-`File` or `FileDiff` with `edit()` first.
+In React, reuse one editor by passing the same `editorOptions` object to every
+surface — `EditProvider` caches editors by options identity, so a stable object
+yields one instance across file switches:
 
-<DocsCodeExample {...editorPublicApi} />
+<DocsCodeExample {...editPersistStateReactExample} />
 
-#### Markers
+### Markers
 
-Markers add inline diagnostics—errors, warnings, and other annotations—to the
-editable surface, with a hover popover that shows each marker's message. They
-are useful for surfacing linter or language-server output alongside live edits.
+Markers add inline diagnostics — errors, warnings, and other annotations — to
+the editable surface, with a hover popover that shows each marker's message.
+They are useful for surfacing linter or language-server output alongside live
+edits.
 
 Each marker is positioned with zero-based `start` and `end` positions and a
 `severity` that drives its color and popover styling:
@@ -412,25 +313,18 @@ the `severity` literals against the `Marker` type without importing it.
 Markers re-anchor as the document changes, so they stay attached to their text
 while you edit. Pass an empty array to clear them.
 
-#### History
-
-The editor keeps a single undo stack covering user edits and programmatic edits
-alike — `applyEdits` joins the same timeline as typed input, so a mixed sequence
-undoes exactly like an all-local one. Its optional `updateHistory` argument
-defaults to `true`; passing `false` remaps live selections instead of restoring
-snapshots but keeps the text edit undoable. Use `editor.canUndo` and
-`editor.canRedo` to enable or disable toolbar buttons, and call `editor.undo()`
-or `editor.redo()` to step through history from code. These methods share the
-same stack as the keyboard shortcuts (<kbd>Cmd/Ctrl-Z</kbd> and
+### History
 
-<kbd>Cmd/Ctrl-Shift-Z</kbd>).
+Each editor keeps a single undo stack per file. Typed input and programmatic
+`applyEdits` calls join the same timeline, so a mixed sequence undoes exactly
+like a hand-typed one, and each undo or redo restores the selections that went
+with the edit. Drive it with `undo()` and `redo()` — the same commands behind
+`Cmd/Ctrl+Z` — and read `canUndo` and `canRedo` for toolbar state. History lives
+in the file's text document, so with
+[`persistState`](#edit-mode-persisting-editor-state) it survives file switches.
 
-`undo()` and `redo()` are no-ops when there is nothing to undo or redo. Both run
-through the same change path as a normal edit, so your `onChange` handler fires
-and you can re-read `canUndo` / `canRedo` to keep UI state in sync.
-
-Limit the stack size with `historyMaxEntries` in
-[Editor Options](#edit-mode-editor-options) (default: 100).
+You can limit the stack size with `historyMaxEntries` in
+[Editor Options](#edit-mode-editor-options) (default is `100`).
 
 <DocsCodeExample {...editUndoRedoExample} />
 
@@ -457,7 +351,7 @@ usual.
   reactExample={editWorkerPoolReactExample}
 />
 
-### Lazy Loading
+### Lazy Importing
 
 Because `@pierre/diffs/edit` is a standalone entry point, you can dynamic-import
 it only when the user enters edit mode. That keeps the initial page bundle
@@ -466,24 +360,64 @@ rare.
 
 <DocsCodeExample {...editLazyFileExample} />
 
-### Selection Action
+### API Reference
 
-Selection Action is an opt-in edit mode feature for showing custom UI alongside
-the current selection—useful for quick transforms, refactor prompts, or other
-selection-scoped tools. Set `enabledSelectionAction: true` and return your UI
-from `renderSelectionAction`; a floating popover holding your UI appears after
-the user creates a ranged selection. Programmatic `setSelections` and `setState`
-calls update the selection without opening the popover. The popover can hold any
-number of actions.
+These methods are available on an `Editor` instance. Attach it to a rendered
+`File` or `FileDiff` with `edit()` first.
 
-<DocsCodeExample {...editSelectionActionExample} />
+<DocsCodeExample {...editorPublicApi} />
 
-`renderSelectionAction` runs when the popover opens. Its context includes the
-active `selection`, the editable `textDocument`, helpers to read or modify the
-selection (`getSelectionText`, `replaceSelectionText`, `applyEdits`), and
-`close` to dismiss the popover:
+#### Editor Options
 
-<DocsCodeExample {...editSelectionActionContextType} />
+Pass these when constructing `new Editor({ ... })`, or update them later with
+[`setOptions`](#edit-mode-api-reference).
+
+<DocsCodeExample {...editorOptionsType} />
+
+`EditorKeymap` is an array of `{ platform?, bindings }` groups. `platform` can
+be `mac`, `windows`, or `linux`; omit it to enable the group's bindings
+everywhere. Later groups take precedence when bindings overlap. When set, custom
+bindings take precedence, while unmatched shortcuts fall back to the built-in
+keymap. Keymaps are immutable; pass a new array to `setOptions` to change one.
+
+#### `onChange`
+
+The third argument is an `EditorChangeEvent`. Its `changes` array contains every
+normalized edit in the change:
+
+<DocsCodeExample {...editOnChangeExample} />
+
+Ranges use zero-based line and character positions.
+
+#### `onAttach`
+
+Use `onAttach` to opt into initial caret placement. At this point the text
+document and editable DOM are ready. In React, pass a stable `editorOptions`
+object to any editable surface, including `CodeView`:
+
+<DocsCodeExample {...editOnAttachReactExample} />
+
+Vanilla `CodeView` can add the same behavior in its editor factory:
+
+<DocsCodeExample {...editOnAttachVanillaExample} />
+
+`'first-visible'` selects the first editable row whose top falls inside the
+usable viewport and places the caret at character zero. If no editable row top
+is visible, the call does nothing. Set `offset` to a non-negative number of CSS
+pixels to move the usable top below the viewport if needed. With
+`preventScroll: true`, the focus request does not change the vertical scroll
+position.
+
+You can also target a specific document position:
+
+<DocsCodeExample {...editFocusPositionExample} />
+
+Numeric `lineNumber` values are one-based, while `character` values are
+zero-based. Numeric targeting works on every attached editor. Any targeted focus
+replaces the current selection, so use either this initial placement or restored
+selection/view state as the owner of the edit session's starting position, not
+both. `CodeView` retains an editor while its item is recycled, so `onAttach` is
+not repeated for virtualized remounts in the same edit session.
 
 ### Keyboard Shortcuts
 
diff --git a/apps/docs/lib/mdx.tsx b/apps/docs/lib/mdx.tsx
index 7e4dad7ac..52d6ef2a4 100644
--- a/apps/docs/lib/mdx.tsx
+++ b/apps/docs/lib/mdx.tsx
@@ -18,7 +18,6 @@ import { KeyboardShortcuts } from '../app/(diffs)/_edit/KeyboardShortcuts';
 import { CustomHunkSeparators } from '../app/(diffs)/_examples/CustomHunkSeparators/CustomHunkSeparators';
 import { CodeViewExampleTabs } from '../app/(diffs)/docs/CodeView/ExampleTabs';
 import { EditComponentTabs } from '../app/(diffs)/docs/Edit/ComponentTabs';
-import { EditDemo } from '../app/(diffs)/docs/Edit/EditDemo';
 import { EditWorkerPoolTabs } from '../app/(diffs)/docs/Edit/WorkerPoolTabs';
 import { PackageManagerTabs } from '../app/(diffs)/docs/Installation/PackageManagerTabs';
 import { CodeToggle } from '../app/(diffs)/docs/Overview/CodeToggle';
@@ -90,7 +89,6 @@ const defaultComponents = {
   DocsCodeExample,
   CodeViewExampleTabs,
   EditComponentTabs,
-  EditDemo,
   EditWorkerPoolTabs,
   KeyboardShortcuts,
   CustomHunkSeparators,
diff --git a/packages/diffs/src/editor/editor.ts b/packages/diffs/src/editor/editor.ts
index c703dd2e5..b8af7cd87 100644
--- a/packages/diffs/src/editor/editor.ts
+++ b/packages/diffs/src/editor/editor.ts
@@ -127,6 +127,7 @@ import {
   extend,
   getLineNumberAttr,
   h,
+  lookupScrollContainer,
   round,
 } from './utils';
 
@@ -182,6 +183,11 @@ interface EditorAttachState {
   delivered: boolean;
 }
 
+interface ViewportInputWatch {
+  userScrolled(): boolean;
+  dispose(): void;
+}
+
 export interface EditorOptions<LAnnotation> {
   /** The maximum number of entries to keep in the undo stack. */
   historyMaxEntries?: number;
@@ -595,6 +601,7 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
         fileInstance != null
           ? {
               scrollLeft: fileInstance.getCodeScrollLeft(),
+              scrollTop: this.#getViewportScrollTop(),
             }
           : undefined,
     };
@@ -611,6 +618,11 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
     // sits outside that viewport (e.g. TreeApp remount restore).
     if (view != null) {
       this.#fileInstance.setCodeScrollLeft(view.scrollLeft);
+      // Records persisted before scrollTop existed lack it: leave the
+      // viewport where it is rather than guessing.
+      if (view.scrollTop !== undefined) {
+        this.#setViewportScrollTop(view.scrollTop);
+      }
       return;
     }
     this.#scrollToPrimaryCaret();
@@ -730,7 +742,7 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
       this.#attachState.delivered = false;
     }
     const hadFileInstance = this.#fileInstance != null;
-    const shouldRestoreState = this.#isStatePersistenceEnabled;
+    const shouldRestoreState = this.#options.persistState === true;
     this.#stateRestoreGeneration++;
     this.#persistCurrentState();
     if (hadFileInstance) {
@@ -933,9 +945,10 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
       this.#fileInfo.name !== fileOrDiff.name ||
       this.#fileInfo.lang !== fileOrDiff.lang ||
       this.#fileInfo.cacheKey !== fileOrDiff.cacheKey;
-    const persistedCacheKey = this.#isStatePersistenceEnabled
-      ? requirePersistedCacheKey(fileOrDiff)
-      : undefined;
+    const persistedCacheKey =
+      this.#options.persistState === true
+        ? requirePersistedCacheKey(fileOrDiff)
+        : undefined;
 
     let persistedStateTarget:
       | { cacheKey: string; textDocument: TextDocument<LAnnotation> }
@@ -958,8 +971,15 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
         persistedCacheKey !== undefined
           ? this.#getCachedTextDocument(fileOrDiff, persistedCacheKey)
           : undefined;
+      // A File render substitutes cached text before painting (see
+      // __prepareFile), so its DOM always matches a reused document.
+      const reusableTextDocument =
+        fileInstance.type === 'file' ||
+        cachedTextDocument?.getText() === contents
+          ? cachedTextDocument
+          : undefined;
       const textDocument =
-        cachedTextDocument ??
+        reusableTextDocument ??
         new TextDocument(fileOrDiff.name, contents, languageId, 0, editStack);
       this.#fileInfo = { name, lang, cacheKey };
       this.#textDocument = textDocument;
@@ -977,9 +997,13 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
       // content element must drop the previous document's measurements here.
       this.#wrapLineOffsetsCache.clear();
       this.#selections = this.#initSelections;
-      if (this.#textDocument !== undefined && this.#options.__debug === true) {
+      if (this.#options.__debug === true) {
+        // A reused document keeps its undo history; only the fallback path
+        // actually rebuilds one from the host's contents.
         console.log(
-          '[diffs/editor] text document rebuilt from',
+          reusableTextDocument !== undefined
+            ? '[diffs/editor] cached text document reused for'
+            : '[diffs/editor] text document rebuilt from',
           fileOrDiff.name
         );
       }
@@ -1157,12 +1181,6 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
     this.#scheduleOnAttach(fileInstance);
   };
 
-  get #isStatePersistenceEnabled(): boolean {
-    return (
-      this.#options.persistState === true && this.#fileInstance?.type === 'file'
-    );
-  }
-
   #getCachedTextDocument(
     file: FileContents | FileDiffMetadata,
     cacheKey: string
@@ -1188,7 +1206,11 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
     const fileInfo = this.#fileInfo;
     const textDocument = this.#textDocument;
     if (
-      !this.#isStatePersistenceEnabled ||
+      this.#options.persistState !== true ||
+      // Requires an attached instance: a repeated cleanUp still holds the
+      // retained fileInfo but must not write (empty) state over the record
+      // the first cleanUp persisted.
+      this.#fileInstance === undefined ||
       fileInfo === undefined ||
       textDocument === undefined
     ) {
@@ -1214,7 +1236,8 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
       if (
         textDocument.version === pendingRestore.documentVersion &&
         this.#selections === pendingRestore.selections &&
-        state.view?.scrollLeft === pendingRestore.view?.scrollLeft
+        state.view?.scrollLeft === pendingRestore.view?.scrollLeft &&
+        state.view?.scrollTop === pendingRestore.view?.scrollTop
       ) {
         return;
       }
@@ -1276,10 +1299,14 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
     const documentVersion = textDocument.version;
     const selections = this.#selections;
     const view = this.getState().view;
+    let inputWatch: ViewportInputWatch | undefined;
     const applyState = (state: EditorState | undefined): void => {
       const currentView = this.getState().view;
+      // scrollTop is deliberately not part of this staleness check: the
+      // surface can legitimately adjust vertical scroll while an async read
+      // is in flight (height reconciliation, clamping), and that must not
+      // block the restore. User scrolls are detected by `inputWatch` instead.
       if (
-        state === undefined ||
         generation !== this.#stateRestoreGeneration ||
         this.#textDocument !== textDocument ||
         textDocument.version !== documentVersion ||
@@ -1290,7 +1317,25 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
       ) {
         return;
       }
-      this.setState(cloneEditorState(state));
+      // Once the user engages the viewport, the vertical position is theirs:
+      // neither the first-open reset nor a stored scrollTop may move it.
+      const userScrolled = inputWatch?.userScrolled() === true;
+      if (state === undefined) {
+        // No stored record for this cacheKey — the file is opened for the
+        // first time. Start the code scroller and the viewport at the top
+        // instead of inheriting whatever offset the previous file left in a
+        // viewport that stays mounted across switches.
+        this.#fileInstance?.setCodeScrollLeft(0);
+        if (!userScrolled) {
+          this.#setViewportScrollTop(0);
+        }
+        return;
+      }
+      const restored = cloneEditorState(state);
+      if (userScrolled && restored.view !== undefined) {
+        restored.view = { scrollLeft: restored.view.scrollLeft };
+      }
+      this.setState(restored);
     };
     const readState = (): void | Promise<void> => {
       let result: EditorState | undefined | Promise<EditorState | undefined>;
@@ -1312,6 +1357,7 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
     const result =
       pendingWrite === undefined ? readState() : pendingWrite.then(readState);
     if (isPromise(result)) {
+      inputWatch = this.#watchViewportUserInput();
       const pendingRestore = {
         cacheKey,
         textDocument,
@@ -1322,6 +1368,7 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
       };
       this.#pendingStateRestore = pendingRestore;
       void pendingRestore.completion.finally(() => {
+        inputWatch?.dispose();
         if (this.#pendingStateRestore === pendingRestore) {
           this.#pendingStateRestore = undefined;
         }
@@ -1329,6 +1376,31 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
     }
   }
 
+  #watchViewportUserInput(): ViewportInputWatch | undefined {
+    const viewport = this.#getScrollViewport();
+    if (!(viewport instanceof HTMLElement)) {
+      return undefined;
+    }
+    let scrolled = false;
+    const eventTypes = ['wheel', 'touchstart', 'mousedown'] as const;
+    const dispose = (): void => {
+      for (const type of eventTypes) {
+        viewport.removeEventListener(type, onInput, { capture: true });
+      }
+    };
+    const onInput = (): void => {
+      scrolled = true;
+      dispose();
+    };
+    for (const type of eventTypes) {
+      viewport.addEventListener(type, onInput, {
+        capture: true,
+        passive: true,
+      });
+    }
+    return { userScrolled: () => scrolled, dispose };
+  }
+
   // Whether a zero-based document line has (or will have on scroll) a
   // rendered row. False only for lines hidden inside a collapsed unchanged
   // region of a diff host; hosts without collapsible regions treat every
@@ -1468,6 +1540,37 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
     queueRender(callback);
   }
 
+  // Get the editor's scrolling viewport, return undefined if the Virtualizer
+  // is not present.`
+  #getScrollViewport(): HTMLElement | Document | undefined {
+    const viewport = this.#fileInstance?.getEditorViewport?.();
+    if (viewport !== undefined) {
+      return viewport;
+    }
+    const fileContainer = this.#fileContainer;
+    if (this.#fileInstance == null || fileContainer == null) {
+      return undefined;
+    }
+    return lookupScrollContainer(fileContainer);
+  }
+
+  #getViewportScrollTop(): number {
+    const viewport = this.#getScrollViewport();
+    if (viewport instanceof HTMLElement) {
+      return viewport.scrollTop;
+    }
+    return viewport?.defaultView?.scrollY ?? 0;
+  }
+
+  #setViewportScrollTop(scrollTop: number): void {
+    const viewport = this.#getScrollViewport();
+    if (viewport instanceof HTMLElement) {
+      viewport.scrollTop = scrollTop;
+    } else if (viewport instanceof Document) {
+      viewport.defaultView?.scrollTo({ top: scrollTop });
+    }
+  }
+
   #initialize(): void {
     // Safari doesn't support `::selection` for slot elements in ShadowDOM,
     // Add a global style to disable selection for slot elements
@@ -3468,9 +3571,11 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
     ) {
       return undefined;
     }
-    const viewport =
-      this.#fileInstance?.getEditorViewport?.() ??
-      this.#getDefaultEditorViewport(fileContainer);
+
+    const viewport = this.#getScrollViewport();
+    if (viewport === undefined) {
+      return undefined;
+    }
 
     let viewportTop: number;
     let viewportBottom: number;
@@ -3479,12 +3584,8 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
       viewportTop = viewportRect.top;
       viewportBottom = viewportRect.bottom;
     } else {
-      const viewportWindow = viewport.defaultView;
-      if (viewportWindow == null) {
-        return undefined;
-      }
       viewportTop = 0;
-      viewportBottom = viewportWindow.innerHeight;
+      viewportBottom = viewport.defaultView?.innerHeight ?? 0;
     }
 
     const stickyHeader = fileContainer.shadowRoot?.querySelector<HTMLElement>(
@@ -3521,32 +3622,6 @@ export class Editor<LAnnotation> implements DiffsEditor<LAnnotation> {
     return undefined;
   }
 
-  // Non-virtualized surfaces inherit visibility from their nearest vertical
-  // scrollport; page-scrolling surfaces use the owning document.
-  #getDefaultEditorViewport(
-    fileContainer: HTMLElement
-  ): HTMLElement | Document {
-    const ownerDocument = fileContainer.ownerDocument;
-    let element = fileContainer.parentElement;
-    while (
-      element != null &&
-      element !== ownerDocument.body &&
-      element !== ownerDocument.documentElement
-    ) {
-      const overflowY =
-        element.ownerDocument.defaultView?.getComputedStyle(element).overflowY;
-      if (
-        overflowY === 'auto' ||
-        overflowY === 'scroll' ||
-        overflowY === 'overlay'
-      ) {
-        return element;
-      }
-      element = element.parentElement;
-    }
-    return ownerDocument;
-  }
-
   #focusAtPosition(position: Position, preventScroll: boolean): void {
     const selection: EditorSelection = {
       start: position,
diff --git a/packages/diffs/src/editor/utils.ts b/packages/diffs/src/editor/utils.ts
index 26ca9e920..9c188a446 100644
--- a/packages/diffs/src/editor/utils.ts
+++ b/packages/diffs/src/editor/utils.ts
@@ -144,3 +144,30 @@ export function getGraphemeSegmenter(): Intl.Segmenter | undefined {
   }
   return graphemeSegmenter;
 }
+
+// lookup the scroll container for the given element
+export function lookupScrollContainer(
+  element: HTMLElement
+): HTMLElement | Document {
+  const ownerDocument = element.ownerDocument;
+  let parentElement = element.parentElement;
+  while (
+    parentElement != null &&
+    parentElement !== ownerDocument.body &&
+    parentElement !== ownerDocument.documentElement
+  ) {
+    const overflowY =
+      parentElement.ownerDocument.defaultView?.getComputedStyle(
+        parentElement
+      ).overflowY;
+    if (
+      overflowY === 'auto' ||
+      overflowY === 'scroll' ||
+      overflowY === 'overlay'
+    ) {
+      return parentElement;
+    }
+    parentElement = parentElement.parentElement;
+  }
+  return ownerDocument;
+}
diff --git a/packages/diffs/src/react/EditContext.tsx b/packages/diffs/src/react/EditContext.tsx
index 827c01df2..e915b2762 100644
--- a/packages/diffs/src/react/EditContext.tsx
+++ b/packages/diffs/src/react/EditContext.tsx
@@ -2,7 +2,7 @@
 'use client';
 
 import type { Context, PropsWithChildren } from 'react';
-import { createContext, useContext } from 'react';
+import { createContext, useContext, useRef } from 'react';
 
 import type { EditorOptions } from '../edit';
 import type { DiffsEditor } from '../types';
@@ -25,7 +25,22 @@ export function EditProvider<LAnnotation>({
   children,
   createEditor,
 }: PropsWithChildren<EditProviderProps<LAnnotation>>): React.JSX.Element {
-  const stableCreateEditor = useStableCallback(createEditor);
+  // Editors cached by options-object identity: an edit session that restarts
+  // with the same `editorOptions`
+  const editorCacheRef = useRef(
+    new WeakMap<EditorOptions<LAnnotation>, DiffsEditor<LAnnotation>>()
+  );
+  const stableCreateEditor = useStableCallback(
+    (options: EditorOptions<LAnnotation>): DiffsEditor<LAnnotation> => {
+      const cached = editorCacheRef.current.get(options);
+      if (cached != null) {
+        return cached;
+      }
+      const editor = createEditor(options);
+      editorCacheRef.current.set(options, editor);
+      return editor;
+    }
+  );
   return (
     <EditContext.Provider value={stableCreateEditor}>
       {children}
diff --git a/packages/diffs/src/types.ts b/packages/diffs/src/types.ts
index 96f3a87d6..67c013c7f 100644
--- a/packages/diffs/src/types.ts
+++ b/packages/diffs/src/types.ts
@@ -1256,6 +1256,8 @@ export interface EditorSelection extends Range {
 export interface EditorViewState {
   /** Horizontal position owned by the current editable code scroller. */
   scrollLeft: number;
+  /** Vertical position of the editor viewport. */
+  scrollTop?: number;
 }
 
 export interface EditorState {
diff --git a/packages/diffs/test/editorPersistStateLifecycle.test.ts b/packages/diffs/test/editorPersistStateLifecycle.test.ts
index 13931598c..9b479f52d 100644
--- a/packages/diffs/test/editorPersistStateLifecycle.test.ts
+++ b/packages/diffs/test/editorPersistStateLifecycle.test.ts
@@ -1,6 +1,7 @@
 import { afterAll, describe, expect, test } from 'bun:test';
 
 import { File } from '../src/components/File';
+import { FileDiff } from '../src/components/FileDiff';
 import { DEFAULT_THEMES } from '../src/constants';
 import { Editor, type IStateStorage } from '../src/edit';
 import { disposeHighlighter } from '../src/highlighter/shared_highlighter';
@@ -448,4 +449,402 @@ describe('Editor persisted state lifecycle', () => {
       dom.cleanup();
     }
   });
+
+  // Renders a file inside a scrollable wrapper (the editor's default viewport
+  // is its nearest overflow-y:auto ancestor) so the restore path's scroll
+  // behavior is observable. The wrapper starts scrolled away from 0,0 as if a
+  // previously open file had left an offset behind.
+  function attachFileInScrolledViewport(
+    editor: Editor<undefined>,
+    fileContents: FileContents
+  ): AttachedFile & { viewport: HTMLElement } {
+    const viewport = document.createElement('div');
+    viewport.style.overflowY = 'auto';
+    document.body.appendChild(viewport);
+    const container = document.createElement('div');
+    viewport.appendChild(container);
+    viewport.scrollTop = 40;
+    viewport.scrollLeft = 8;
+
+    const file = new File<undefined>({
+      disableErrorHandling: true,
+      disableFileHeader: true,
+      theme: DEFAULT_THEMES,
+    });
+    file.render({
+      file: fileContents,
+      fileContainer: container,
+      forceRender: true,
+    });
+    editor.edit(file);
+    return { container, file, viewport };
+  }
+
+  test('a missing state record resets the viewport scroll to 0,0', async () => {
+    const dom = installDom();
+    const storage: IStateStorage = {
+      get: () => undefined,
+      set() {},
+    };
+    const editor = new Editor<undefined>({
+      persistState: true,
+      persistStateStorage: storage,
+    });
+    let attached: (AttachedFile & { viewport: HTMLElement }) | undefined;
+
+    try {
+      attached = attachFileInScrolledViewport(editor, {
+        ...ORIGINAL_FILE,
+      });
+      const { viewport } = attached;
+      // The reset targets the viewport's vertical position (and the code
+      // scroller's own horizontal offset); the viewport's scrollLeft is left
+      // to the host.
+      await waitFor(() => viewport.scrollTop === 0);
+    } finally {
+      editor.cleanUp();
+      attached?.file.cleanUp();
+      dom.cleanup();
+    }
+  });
+
+  test('a record with scrollTop restores the viewport position', async () => {
+    const dom = installDom();
+    const storage: IStateStorage = {
+      get: () => ({ ...savedCaret(3), view: { scrollLeft: 0, scrollTop: 25 } }),
+      set() {},
+    };
+    const editor = new Editor<undefined>({
+      persistState: true,
+      persistStateStorage: storage,
+    });
+    let attached: (AttachedFile & { viewport: HTMLElement }) | undefined;
+
+    try {
+      attached = attachFileInScrolledViewport(editor, {
+        ...ORIGINAL_FILE,
+      });
+      const { viewport } = attached;
+      await waitFor(() => viewport.scrollTop === 25);
+    } finally {
+      editor.cleanUp();
+      attached?.file.cleanUp();
+      dom.cleanup();
+    }
+  });
+
+  // The shared-editor pattern (e.g. an EditProvider handing every keyed
+  // surface the same Editor): the outgoing surface's cleanUp persists its
+  // record into the editor's per-instance storage, and re-attaching a new
+  // surface for the same cacheKey restores it — including the viewport's
+  // vertical position.
+  test('a reused editor restores viewport scrollTop across surface remounts', async () => {
+    const dom = installDom();
+    const editor = new Editor<undefined>({ persistState: true });
+    let attached: (AttachedFile & { viewport: HTMLElement }) | undefined;
+    let reattached: (AttachedFile & { viewport: HTMLElement }) | undefined;
+
+    try {
+      attached = attachFileInScrolledViewport(editor, {
+        ...ORIGINAL_FILE,
+      });
+      // First visit has no record: the viewport resets to 0. Then the user
+      // scrolls, and leaving the file persists that position.
+      await waitFor(() => attached!.viewport.scrollTop === 0);
+      attached.viewport.scrollTop = 33;
+      editor.cleanUp();
+      attached.file.cleanUp();
+
+      reattached = attachFileInScrolledViewport(editor, {
+        ...ORIGINAL_FILE,
+      });
+      await waitFor(() => reattached!.viewport.scrollTop === 33);
+    } finally {
+      editor.cleanUp();
+      attached?.file.cleanUp();
+      reattached?.file.cleanUp();
+      dom.cleanup();
+    }
+  });
+
+  // A user scroll while an async read is in flight is signalled by its input
+  // event (wheel/touch/pointer press); the late restore must leave the
+  // user's vertical position alone while still applying selections.
+  test('a user scroll during an async read wins over the restored scrollTop', async () => {
+    const dom = installDom();
+    const pendingState = createDeferred<EditorState | undefined>();
+    const gets: string[] = [];
+    const storage: IStateStorage = {
+      get(cacheKey) {
+        gets.push(cacheKey);
+        return pendingState.promise;
+      },
+      set() {},
+    };
+    const editor = new Editor<undefined>({
+      persistState: true,
+      persistStateStorage: storage,
+    });
+    let attached: (AttachedFile & { viewport: HTMLElement }) | undefined;
+
+    try {
+      attached = attachFileInScrolledViewport(editor, { ...ORIGINAL_FILE });
+      const { viewport } = attached;
+      await waitFor(() => gets.length === 1);
+
+      viewport.dispatchEvent(new Event('wheel'));
+      viewport.scrollTop = 77;
+      pendingState.resolve({
+        ...savedCaret(3),
+        view: { scrollLeft: 0, scrollTop: 25 },
+      });
+      await waitFor(
+        () => editor.getState().selections?.[0]?.start.character === 3
+      );
+      expect(editor.getState().selections).toEqual(savedCaret(3).selections);
+      expect(viewport.scrollTop).toBe(77);
+    } finally {
+      editor.cleanUp();
+      attached?.file.cleanUp();
+      dom.cleanup();
+    }
+  });
+
+  // The counterpart: scrollTop moved by layout work alone (no input event —
+  // height reconciliation, clamping) must not block the async restore.
+  test('a layout-driven scroll change does not block the async scrollTop restore', async () => {
+    const dom = installDom();
+    const pendingState = createDeferred<EditorState | undefined>();
+    const gets: string[] = [];
+    const storage: IStateStorage = {
+      get(cacheKey) {
+        gets.push(cacheKey);
+        return pendingState.promise;
+      },
+      set() {},
+    };
+    const editor = new Editor<undefined>({
+      persistState: true,
+      persistStateStorage: storage,
+    });
+    let attached: (AttachedFile & { viewport: HTMLElement }) | undefined;
+
+    try {
+      attached = attachFileInScrolledViewport(editor, { ...ORIGINAL_FILE });
+      const { viewport } = attached;
+      await waitFor(() => gets.length === 1);
+
+      viewport.scrollTop = 5;
+      pendingState.resolve({
+        ...savedCaret(3),
+        view: { scrollLeft: 0, scrollTop: 25 },
+      });
+      await waitFor(() => viewport.scrollTop === 25);
+      expect(viewport.scrollTop).toBe(25);
+      expect(editor.getState().selections).toEqual(savedCaret(3).selections);
+    } finally {
+      editor.cleanUp();
+      attached?.file.cleanUp();
+      dom.cleanup();
+    }
+  });
+
+  // Diffs persist only their serializable state, keyed by the cacheKey
+  // parseDiffFromFile derives from the file pair. A first attach has no
+  // record (reset to 0,0); a later fresh editor + fresh FileDiff for the same
+  // pair restores the persisted viewport position.
+  test('with persistState, a diff resets on first attach and restores on revisit', async () => {
+    const dom = installDom();
+    const editor = new Editor<undefined>({ persistState: true });
+    const viewport = document.createElement('div');
+    viewport.style.overflowY = 'auto';
+    document.body.appendChild(viewport);
+    const container = document.createElement('div');
+    viewport.appendChild(container);
+    viewport.scrollTop = 40;
+    viewport.scrollLeft = 8;
+
+    const oldFile: FileContents = { name: 'diffed.ts', contents: 'alpha\n' };
+    const newFile: FileContents = {
+      name: 'diffed.ts',
+      contents: 'alpha\nbravo\n',
+    };
+    const fileDiff = new FileDiff<undefined>({
+      disableErrorHandling: true,
+      disableFileHeader: true,
+      theme: DEFAULT_THEMES,
+    });
+    const revisitDiff = new FileDiff<undefined>({
+      disableErrorHandling: true,
+      disableFileHeader: true,
+      theme: DEFAULT_THEMES,
+    });
+    try {
+      fileDiff.render({
+        oldFile,
+        newFile,
+        fileContainer: container,
+        forceRender: true,
+      });
+      editor.edit(fileDiff);
+      await waitFor(() => viewport.scrollTop === 0);
+
+      // Scroll the diff, tear the surface down, and revisit the same pair on
+      // a fresh component with the same editor — its record must restore the
+      // position.
+      viewport.scrollTop = 27;
+      editor.cleanUp();
+      fileDiff.cleanUp();
+      container.innerHTML = '';
+      viewport.scrollTop = 5;
+
+      revisitDiff.render({
+        oldFile,
+        newFile,
+        fileContainer: container,
+        forceRender: true,
+      });
+      editor.edit(revisitDiff);
+      await waitFor(() => viewport.scrollTop === 27);
+    } finally {
+      editor.cleanUp();
+      fileDiff.cleanUp();
+      revisitDiff.cleanUp();
+      dom.cleanup();
+    }
+  });
+
+  // A FileDiff renders straight from the host's metadata (no __prepareFile
+  // substitution like File), so a host that re-parses pristine metadata after
+  // edits — same derived cacheKey, original content — must get a document
+  // built from that metadata, not the edited cached one, or the rendered rows
+  // and the editing document would diverge.
+  test('a re-parsed pristine diff does not adopt the edited cached document', async () => {
+    const dom = installDom();
+    const editor = new Editor<undefined>({ persistState: true });
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const oldFile: FileContents = {
+      name: 'diffed-reparse.ts',
+      contents: 'alpha\n',
+    };
+    const newFile: FileContents = {
+      name: 'diffed-reparse.ts',
+      contents: 'alpha\nbravo\n',
+    };
+    const first = new FileDiff<undefined>({
+      disableErrorHandling: true,
+      disableFileHeader: true,
+      theme: DEFAULT_THEMES,
+    });
+    const second = new FileDiff<undefined>({
+      disableErrorHandling: true,
+      disableFileHeader: true,
+      theme: DEFAULT_THEMES,
+    });
+    try {
+      first.render({
+        oldFile,
+        newFile,
+        fileContainer: container,
+        forceRender: true,
+      });
+      editor.edit(first);
+      await waitFor(() => editor.getText() === 'alpha\nbravo\n');
+      editor.applyEdits([
+        {
+          range: {
+            start: { line: 0, character: 0 },
+            end: { line: 0, character: 0 },
+          },
+          newText: 'edited ',
+        },
+      ]);
+      expect(editor.getText()).toBe('edited alpha\nbravo\n');
+      editor.cleanUp();
+      first.cleanUp();
+      container.innerHTML = '';
+
+      second.render({
+        oldFile,
+        newFile,
+        fileContainer: container,
+        forceRender: true,
+      });
+      editor.edit(second);
+      // waitFor times out silently; the expect below is the real assertion.
+      await waitFor(() => editor.getText() === 'alpha\nbravo\n');
+      expect(editor.getText()).toBe('alpha\nbravo\n');
+    } finally {
+      editor.cleanUp();
+      first.cleanUp();
+      second.cleanUp();
+      dom.cleanup();
+    }
+  });
+
+  test('without persistState, attaching a diff leaves the viewport alone', async () => {
+    const dom = installDom();
+    const editor = new Editor<undefined>();
+    const viewport = document.createElement('div');
+    viewport.style.overflowY = 'auto';
+    document.body.appendChild(viewport);
+    const container = document.createElement('div');
+    viewport.appendChild(container);
+    viewport.scrollTop = 40;
+
+    const fileDiff = new FileDiff<undefined>({
+      disableErrorHandling: true,
+      disableFileHeader: true,
+      theme: DEFAULT_THEMES,
+    });
+    try {
+      fileDiff.render({
+        oldFile: { name: 'diffed.ts', contents: 'alpha\n' },
+        newFile: { name: 'diffed.ts', contents: 'alpha\nbravo\n' },
+        fileContainer: container,
+        forceRender: true,
+      });
+      editor.edit(fileDiff);
+      // Attach work settles asynchronously; give it time to (incorrectly)
+      // move the viewport before asserting it stayed put.
+      await wait(50);
+      expect(viewport.scrollTop).toBe(40);
+    } finally {
+      editor.cleanUp();
+      fileDiff.cleanUp();
+      dom.cleanup();
+    }
+  });
+
+  test('a record without scrollTop leaves the viewport scroll alone', async () => {
+    const dom = installDom();
+    const storage: IStateStorage = {
+      // A record persisted before scrollTop existed: setState still honors
+      // scrollLeft exactly but must not move the viewport vertically.
+      get: () => ({ ...savedCaret(3), view: { scrollLeft: 0 } }),
+      set() {},
+    };
+    const editor = new Editor<undefined>({
+      persistState: true,
+      persistStateStorage: storage,
+    });
+    let attached: (AttachedFile & { viewport: HTMLElement }) | undefined;
+
+    try {
+      attached = attachFileInScrolledViewport(editor, {
+        ...ORIGINAL_FILE,
+      });
+      const { viewport } = attached;
+      await waitFor(
+        () => editor.getState().selections?.[0]?.start.character === 3
+      );
+      expect(viewport.scrollTop).toBe(40);
+      expect(viewport.scrollLeft).toBe(8);
+    } finally {
+      editor.cleanUp();
+      attached?.file.cleanUp();
+      dom.cleanup();
+    }
+  });
 });
diff --git a/packages/diffs/test/editorRecycle.test.ts b/packages/diffs/test/editorRecycle.test.ts
index e9fa13ff0..371bc40ad 100644
--- a/packages/diffs/test/editorRecycle.test.ts
+++ b/packages/diffs/test/editorRecycle.test.ts
@@ -12,7 +12,7 @@ import type {
   HighlightedToken,
   RenderRange,
 } from '../src/types';
-import { installDom, wait } from './domHarness';
+import { installDom, wait, waitFor } from './domHarness';
 
 function createTestHighlighter(): DiffsHighlighter {
   return {
@@ -238,7 +238,7 @@ describe('Editor onAttach lifecycle', () => {
       // onAttach must wait for the replacement to synchronize.
       component.rerender();
       editor.edit(component);
-      await wait(20);
+      await waitFor(() => onAttach.mock.calls.length === 1);
 
       expect(onAttach).toHaveBeenCalledTimes(1);
       expect(focusTargets).toHaveLength(1);
diff --git a/packages/diffs/test/editorState.test.ts b/packages/diffs/test/editorState.test.ts
index 208d73215..fdb1a3977 100644
--- a/packages/diffs/test/editorState.test.ts
+++ b/packages/diffs/test/editorState.test.ts
@@ -159,7 +159,7 @@ describe('Editor state', () => {
       editor.edit(component);
       component.codeScrollLeft = 24;
 
-      expect(editor.getState().view).toEqual({ scrollLeft: 24 });
+      expect(editor.getState().view).toEqual({ scrollLeft: 24, scrollTop: 0 });
     } finally {
       editor.cleanUp();
       component.cleanUp();
@@ -213,7 +213,7 @@ describe('Editor state', () => {
       component.codeScrollLeft = 24;
       editor.cleanUp();
 
-      expect(storedState?.view).toEqual({ scrollLeft: 24 });
+      expect(storedState?.view).toEqual({ scrollLeft: 24, scrollTop: 0 });
     } finally {
       editor.cleanUp();
       component.cleanUp();
diff --git a/packages/diffs/test/reactEditorOptions.test.ts b/packages/diffs/test/reactEditorOptions.test.ts
index e9c5e6774..eb3edb65a 100644
--- a/packages/diffs/test/reactEditorOptions.test.ts
+++ b/packages/diffs/test/reactEditorOptions.test.ts
@@ -907,17 +907,14 @@ describe('React editor factory lifecycle', () => {
 
       await waitFor(() => onAttach.mock.calls.length >= 2);
       await wait(0);
-      const activeEditors = editors.filter(
-        (editor) => editor.cleanUpCount === 0
-      );
-      expect(editors.length).toBeGreaterThanOrEqual(4);
-      expect(editors.filter((editor) => editor.cleanUpCount > 0)).toHaveLength(
-        editors.length - 2
-      );
-      expect(activeEditors).toHaveLength(2);
+      // The provider caches editors by options-object identity, so
+      // StrictMode's simulated destroy/re-create pass reuses each surface's
+      // editor instead of leaking a second one: exactly one editor per
+      // surface, cleaned up by the destroy pass and re-attached after it.
+      expect(editors).toHaveLength(2);
       expect(onAttach).toHaveBeenCalledTimes(2);
       expect(new Set(onAttach.mock.calls.map(([editor]) => editor))).toEqual(
-        new Set(activeEditors)
+        new Set(editors)
       );
 
       await unmountRoot(root);
@@ -931,4 +928,48 @@ describe('React editor factory lifecycle', () => {
       cleanup();
     }
   });
+
+  test('a factory returning an owner-constructed editor shares it as configured, ignoring surface editorOptions', async () => {
+    const { cleanup } = installDom();
+    const cleanupActEnvironment = installReactActEnvironment();
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    // The owner-constructed editor is used exactly as constructed: its own
+    // onAttach must fire, while the surface's editorOptions (including its
+    // onAttach) only reach the factory, which discards them.
+    let attachedEditor: Editor<undefined> | undefined;
+    const sharedEditor = new Editor<undefined>({
+      onAttach(editor) {
+        attachedEditor = editor;
+      },
+    });
+    const factory = mock((_options: EditorOptions<undefined>) => sharedEditor);
+    const surfaceOnAttach = mock((_editor: Editor<undefined>) => {});
+    let root: Root | undefined;
+
+    try {
+      root = createReactRoot(container);
+      await act(async () => {
+        root!.render(
+          createElement(
+            EditProviderComponent,
+            { createEditor: factory },
+            createEditableSurfaceElement('File', true, {
+              onAttach: surfaceOnAttach,
+            })
+          )
+        );
+        await wait(10);
+      });
+      await waitFor(() => attachedEditor !== undefined);
+
+      expect(attachedEditor).toBe(sharedEditor);
+      expect(factory).toHaveBeenCalled();
+      expect(surfaceOnAttach).not.toHaveBeenCalled();
+    } finally {
+      await unmountRoot(root);
+      cleanupActEnvironment();
+      cleanup();
+    }
+  });
 });
diff --git a/skills/diffs/references/api-react.md b/skills/diffs/references/api-react.md
index ba70538ac..96e6bf76e 100644
--- a/skills/diffs/references/api-react.md
+++ b/skills/diffs/references/api-react.md
@@ -15,7 +15,7 @@ entry also re-exports every type in [Shared types](api-types.md).
 | `CodeView`                  | Component | Renders a virtualized list of files and diffs.            |
 | `Virtualizer`               | Component | Provides simple viewport virtualization.                  |
 | `useVirtualizer`            | Hook      | Gets the nearest simple `Virtualizer` instance.           |
-| `EditProvider`              | Component | Supplies an editor factory to editable surfaces.          |
+| `EditProvider`              | Component | Supplies an editor factory.                               |
 | `useCreateEditor`           | Hook      | Gets the nearest editor factory.                          |
 | `WorkerPoolContextProvider` | Component | Creates and supplies a worker pool.                       |
 | `useWorkerPool`             | Hook      | Gets the nearest worker pool.                             |
@@ -41,7 +41,7 @@ entry also re-exports every type in [Shared types](api-types.md).
 | `CodeViewReactOptions`              | Defines the React-safe `CodeView` option set.                     |
 | `CodeViewHandle`                    | Defines imperative list, selection, scroll, and editor controls.  |
 | `CreateEditor`                      | Defines the editor factory.                                       |
-| `EditProviderProps`                 | Defines `EditProvider` props.                                     |
+| `EditProviderProps`                 | Defines the `EditProvider` factory prop.                          |
 | `MergeConflictActionsTypeOption`    | Selects no actions, default actions, or a custom action renderer. |
 | `RenderMergeConflictActionContext`  | Supplies conflict resolution to a custom action renderer.         |
 | `RenderMergeConflictActions`        | Defines a custom conflict action renderer.                        |
diff --git a/skills/diffs/references/recipe-edit-react.md b/skills/diffs/references/recipe-edit-react.md
index ba91d708b..c51e57dab 100644
--- a/skills/diffs/references/recipe-edit-react.md
+++ b/skills/diffs/references/recipe-edit-react.md
@@ -2,7 +2,16 @@
 
 Mount one stable `EditProvider` above the editable surfaces. The provider
 supplies an editor factory. Each active surface or `CodeView` item owns a
-separate editor instance.
+separate editor instance, cached by `editorOptions` object identity — an edit
+session restarting with the same options object reuses its editor, and
+simultaneously editable surfaces need distinct options objects.
+
+To share one editor across surfaces, pass the same `editorOptions` object to
+each of them: the cache then hands every surface the same instance. Instance
+state — such as `persistState` records and their default `inMemory` storage —
+survives surface remounts, so per-file selections and scroll positions restore
+across file switches. Share an options object only where one surface is editable
+at a time; simultaneously editable surfaces need distinct options objects.
 
 ## Contents