diff --git a/.circleci/config.yml b/.circleci/config.yml
index 1920cc12f..428d15391 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -84,7 +84,7 @@ jobs:
   test_benchmark:
     executor:
       name: code-infra/mui-node-browser
-      playwright-img-version: 'v1.58.2-noble'
+      playwright-img-version: 'v1.59.1-noble'
     resource_class: medium
     steps:
       - checkout
diff --git a/AGENTS.md b/AGENTS.md
index 7992294e9..d0a07942e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,6 +22,8 @@ Always reference these instructions first and fallback to search or bash command
 - **Formatting**: `pnpm prettier` -- always run before pushing code.
 - **Run tests**: `pnpm test --run` takes 5-10 seconds. **NEVER CANCEL**. Set timeout to 30+ minutes.
 - **Run specific tests**: `pnpm test --run loadServerSource` or `pnpm test --run integration.test.ts` for targeted testing
+- **Run browser tests**: `pnpm test:browser --run` -- requires podman or docker. Starts a containerized Playwright server and runs browser tests against it.
+- **Run browser tests in CI**: In a `mcr.microsoft.com/playwright` container image, run `pnpm test:browser:unconfined` directly — no container engine needed. Only use in a CI environment.
 - **ALWAYS use `--run` flag** to avoid watch mode when running tests programmatically
 - **Do NOT use `--`** in test commands (e.g., avoid `pnpm test -- --run`)
 - **Use VS Code Vitest extension** whenever possible for interactive test development and debugging
diff --git a/docs/app/bench/docs-infra/components/code-controller-context/demos/code/index.ts b/docs/app/bench/docs-infra/components/code-controller-context/demos/code/index.ts
new file mode 100644
index 000000000..1ae19bf25
--- /dev/null
+++ b/docs/app/bench/docs-infra/components/code-controller-context/demos/code/index.ts
@@ -0,0 +1,4 @@
+import { createDemoPerformance } from '@/functions/createDemoPerformance';
+import Page from './page';
+
+export const DemoCodeControllerContextPerformance = createDemoPerformance(import.meta.url, Page);
diff --git a/docs/app/bench/docs-infra/components/code-controller-context/demos/code/page.tsx b/docs/app/bench/docs-infra/components/code-controller-context/demos/code/page.tsx
new file mode 100644
index 000000000..6891f8544
--- /dev/null
+++ b/docs/app/bench/docs-infra/components/code-controller-context/demos/code/page.tsx
@@ -0,0 +1,29 @@
+import * as React from 'react';
+import { createParseSource } from '@mui/internal-docs-infra/pipeline/parseSource';
+import { CodeHighlighter } from '@mui/internal-docs-infra/CodeHighlighter';
+import { CodeProvider } from '@mui/internal-docs-infra/CodeProvider';
+import { CodeController } from '../../../../../../docs-infra/components/code-controller-context/demos/code-editor/CodeController';
+import { CodeEditorContent } from '../../../../../../docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent';
+
+import code from '../../../code-highlighter/snippets/large/snippet';
+
+const sourceParser = createParseSource();
+
+export default function Page() {
+  return (
+    // @focus-start
+    <CodeProvider>
+      <CodeController>
+        <CodeHighlighter
+          Content={CodeEditorContent}
+          controlled
+          sourceParser={sourceParser}
+          fileName="large-file.js"
+        >
+          {code}
+        </CodeHighlighter>
+      </CodeController>
+    </CodeProvider>
+    // @focus-end
+  );
+}
diff --git a/docs/app/bench/docs-infra/components/code-controller-context/page.mdx b/docs/app/bench/docs-infra/components/code-controller-context/page.mdx
new file mode 100644
index 000000000..b92290c60
--- /dev/null
+++ b/docs/app/bench/docs-infra/components/code-controller-context/page.mdx
@@ -0,0 +1,10 @@
+# Benchmarking Code Controller Context
+
+This demo showcases the performance of the [`CodeControllerContext`](../../../../docs-infra/components/code-controller-context/page.mdx) component when handling large code snippets.
+It uses RSC to highlight the initial code, and then highlights updates on the client side as the code is edited.
+
+import { DemoCodeControllerContextPerformance } from './demos/code';
+
+<DemoCodeControllerContextPerformance />
+
+[See Setup](./demos/code/)
diff --git a/docs/app/docs-infra/components/code-controller-context/bench/page.mdx b/docs/app/docs-infra/components/code-controller-context/bench/page.mdx
new file mode 100644
index 000000000..be8d75bd0
--- /dev/null
+++ b/docs/app/docs-infra/components/code-controller-context/bench/page.mdx
@@ -0,0 +1,5 @@
+import BenchCodeControllerContextPage from '@/app/bench/docs-infra/components/code-controller-context/page.mdx';
+
+export default BenchCodeControllerContextPage;
+
+[See Benchmarks](/docs/app/bench/docs-infra/components/code-controller-context/page.mdx)
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.tsx b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.tsx
index 634f44db1..66bfdb1ef 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.tsx
@@ -1,7 +1,6 @@
 'use client';
 
 import * as React from 'react';
-import { useEditable } from 'use-editable';
 import type { ContentProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
 import { useCode } from '@mui/internal-docs-infra/useCode';
 import { LabeledSwitch } from '@/components/LabeledSwitch';
@@ -10,9 +9,7 @@ import styles from './CodeEditorContent.module.css';
 import '../../../code-highlighter/demos/syntax.css';
 
 export function CodeEditorContent(props: ContentProps<object>) {
-  // @focus-start @padding 1
-  const preRef = React.useRef<HTMLPreElement | null>(null);
-  const code = useCode(props, { preClassName: styles.codeBlock, preRef });
+  const code = useCode(props, { preClassName: styles.codeBlock });
 
   const hasJsTransform = code.availableTransforms.includes('js');
   const isJsSelected = code.selectedTransform === 'js';
@@ -24,15 +21,6 @@ export function CodeEditorContent(props: ContentProps<object>) {
     [code],
   );
 
-  const onInput = React.useCallback(
-    (text: string) => {
-      code.setSource?.(text);
-    },
-    [code],
-  );
-
-  useEditable(preRef, onInput, { indentation: 2 });
-
   return (
     <div className={styles.container}>
       <div className={styles.header}>
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLive.tsx b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLive.tsx
index bdeaa435b..5f81f8c14 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLive.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLive.tsx
@@ -1,15 +1,12 @@
 import * as React from 'react';
 import { CodeProvider } from '@mui/internal-docs-infra/CodeProvider';
-import { DemoController } from './DemoController';
 import { DemoCheckboxBasic } from './demo-basic';
 
 export function DemoLive() {
   return (
     // @focus-start
     <CodeProvider>
-      <DemoController>
-        <DemoCheckboxBasic />
-      </DemoController>
+      <DemoCheckboxBasic />
     </CodeProvider>
     // @focus-end
   );
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.module.css b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.module.css
index 47c2764bc..f9dd0d739 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.module.css
+++ b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.module.css
@@ -85,3 +85,8 @@
 .codeBlock:focus-visible {
   outline: none;
 }
+
+.codeBlock :global(.frame)[data-frame-type='highlighted'] {
+  background: #ebe4ff;
+  border-radius: 8px;
+}
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.tsx b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.tsx
index b6a55998f..62d5339e2 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.tsx
@@ -1,7 +1,6 @@
 'use client';
 
 import * as React from 'react';
-import { useEditable } from 'use-editable';
 import type { ContentProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
 import { useDemo } from '@mui/internal-docs-infra/useDemo';
 import { LabeledSwitch } from '@/components/LabeledSwitch';
@@ -16,9 +15,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function DemoLiveContent(props: ContentProps<object>) {
-  // @focus-start @padding 1
-  const preRef = React.useRef<HTMLPreElement | null>(null);
-  const demo = useDemo(props, { preClassName: styles.codeBlock, preRef });
+  const demo = useDemo(props, { preClassName: styles.codeBlock });
 
   const hasJsTransform = demo.availableTransforms.includes('js');
   const isJsSelected = demo.selectedTransform === 'js';
@@ -41,14 +38,6 @@ export function DemoLiveContent(props: ContentProps<object>) {
     [demo.variants],
   );
 
-  const onChange = React.useCallback(
-    (text: string) => {
-      demo.setSource?.(text);
-    },
-    [demo],
-  );
-  useEditable(preRef, onChange, { indentation: 2, disabled: !demo.setSource });
-
   return (
     <div className={styles.container}>
       <div className={styles.demoSection}>{demo.component}</div>
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/createDemoClient.ts b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/createDemoClient.ts
index 74c12378e..a0761d9f9 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/createDemoClient.ts
+++ b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/createDemoClient.ts
@@ -1,6 +1,7 @@
 'use client';
 
 import { createDemoClientFactory } from '@mui/internal-docs-infra/abstractCreateDemoClient';
+import { DemoController } from './DemoController';
 
 /**
  * Creates a demo client copying dependencies in the client bundle for live editing.
@@ -8,5 +9,5 @@ import { createDemoClientFactory } from '@mui/internal-docs-infra/abstractCreate
  * @param meta Additional meta and modules for the demo client.
  */
 export const createDemoClient = createDemoClientFactory({
-  live: true,
+  DemoController,
 });
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileContent.tsx b/docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileContent.tsx
index 6b8ebef9b..d980da1ed 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileContent.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileContent.tsx
@@ -1,7 +1,6 @@
 'use client';
 
 import * as React from 'react';
-import { useEditable } from 'use-editable';
 import type { ContentProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
 import { useCode } from '@mui/internal-docs-infra/useCode';
 import { Tabs } from '@/components/Tabs';
@@ -10,9 +9,7 @@ import styles from '../code-editor/CodeEditorContent.module.css';
 import '../../../code-highlighter/demos/syntax.css';
 
 export function MultiFileContent(props: ContentProps<object>) {
-  // @focus-start @padding 1
-  const preRef = React.useRef<HTMLPreElement | null>(null);
-  const code = useCode(props, { preClassName: styles.codeBlock, preRef });
+  const code = useCode(props, { preClassName: styles.codeBlock });
 
   const tabs = React.useMemo(() => {
     return code.files.map(({ name }) => ({
@@ -21,15 +18,6 @@ export function MultiFileContent(props: ContentProps<object>) {
     }));
   }, [code.files]);
 
-  const onInput = React.useCallback(
-    (text: string) => {
-      code.setSource?.(text);
-    },
-    [code],
-  );
-
-  useEditable(preRef, onInput, { indentation: 2 });
-
   return (
     <div className={styles.container}>
       <div className={styles.header}>
diff --git a/docs/app/docs-infra/components/code-controller-context/page.mdx b/docs/app/docs-infra/components/code-controller-context/page.mdx
index 8d973aeb2..912cd1393 100644
--- a/docs/app/docs-infra/components/code-controller-context/page.mdx
+++ b/docs/app/docs-infra/components/code-controller-context/page.mdx
@@ -137,22 +137,10 @@ The [`useCode`](../../hooks/use-code/page.mdx) hook automatically integrates wit
 ```tsx
 'use client';
 
-import { useEditable } from 'use-editable';
 import { useCode } from '@mui/internal-docs-infra/useCode';
 
 function EditorContent(props) {
-  const preRef = React.useRef<HTMLPreElement | null>(null);
-  const code = useCode(props, { preRef });
-
-  // code.setSource updates the controller automatically
-  const onInput = React.useCallback(
-    (text: string) => {
-      code.setSource?.(text);
-    },
-    [code],
-  );
-
-  useEditable(preRef, onInput, { indentation: 2 });
+  const code = useCode(props);
 
   return (
     <div>
@@ -165,7 +153,8 @@ function EditorContent(props) {
 
 ## Working with useDemo Hook
 
-The [`useDemo`](../../hooks/use-demo/page.mdx) hook provides additional functionality for live component demos:
+The [`useDemo`](../../hooks/use-demo/page.mdx) hook provides additional functionality for live component demos.
+Editing is handled automatically by the `Pre` component — just render `demo.selectedFile`:
 
 ```tsx
 'use client';
@@ -175,19 +164,12 @@ import { useDemo } from '@mui/internal-docs-infra/useDemo';
 function DemoContent(props) {
   const demo = useDemo(props);
 
-  const onInput = React.useCallback(
-    (text: string) => {
-      demo.setSource?.(text);
-    },
-    [demo],
-  );
-
   return (
     <div>
       {/* Live component preview */}
       <div>{demo.component}</div>
 
-      {/* Editable source code */}
+      {/* Editable source code — editing is handled automatically */}
       <div>
         <select value={demo.selectedVariant} onChange={(e) => demo.selectVariant(e.target.value)}>
           {demo.variants.map((variant) => (
@@ -197,7 +179,7 @@ function DemoContent(props) {
           ))}
         </select>
 
-        <textarea value={demo.selectedFile} onChange={(e) => onInput(e.target.value)} />
+        {demo.selectedFile}
       </div>
     </div>
   );
@@ -210,22 +192,18 @@ The CodeController provides a simple state management pattern:
 
 1. **Initial State**: Controller starts with empty state (`code: undefined`)
 2. **Code Loading**: [`CodeHighlighter`](../code-highlighter/page.mdx) loads initial code from file or props
-3. **User Interaction**: When users edit code, `setSource` calls `controlledSetCode`
+3. **User Interaction**: When users edit code in the `Pre` component, `setSource` updates the controller
 4. **State Update**: Controller state updates and all connected components re-render
 5. **Live Preview**: For demo controllers, components are regenerated from updated code
 
 ```tsx
-// Flow: User Edit → setSource → controlledSetCode → Context Update → Re-render
+// Flow: User Edit (in Pre) → setSource → controlledSetCode → Context Update → Re-render
 
 function EditorContent(props) {
   const code = useCode(props); // Connects to controller context
 
-  const onEdit = (newSource) => {
-    code.setSource(newSource); // This updates the controller context
-  };
-
-  // code.selectedFile reflects the current controller state
-  return <textarea value={code.selectedFile} onChange={onEdit} />;
+  // code.selectedFile is a <Pre> component that handles editing automatically
+  return <div>{code.selectedFile}</div>;
 }
 ```
 
@@ -282,6 +260,7 @@ You can also create your own `createDemoClient` using the abstract factory:
 'use client';
 
 import { createDemoClientFactory } from '@mui/internal-docs-infra/abstractCreateDemoClient';
+import { DemoController } from './DemoController';
 
 /**
  * Creates a demo client copying dependencies in the client bundle for live editing.
@@ -289,7 +268,7 @@ import { createDemoClientFactory } from '@mui/internal-docs-infra/abstractCreate
  * @param meta Additional meta and modules for the demo client.
  */
 export const createDemoClient = createDemoClientFactory({
-  live: true,
+  DemoController,
 });
 ```
 
@@ -318,6 +297,10 @@ The `ClientProvider` ensures that:
 
 This is only needed for demos that render live components from editable code, not for simple code editor scenarios.
 
+## Benchmarking
+
+For performance benchmarks of the `CodeControllerContext` component, see the [Benchmarking Code Controller Context](./bench/page.mdx) page.
+
 ## Best Practices
 
 1. **Use with [`CodeProvider`](../code-provider/page.mdx)** - Always wrap CodeController with [`CodeProvider`](../code-provider/page.mdx) for client-side highlighting
diff --git a/docs/app/docs-infra/components/code-controller-context/types.md b/docs/app/docs-infra/components/code-controller-context/types.md
index 636db4080..00a57d635 100644
--- a/docs/app/docs-infra/components/code-controller-context/types.md
+++ b/docs/app/docs-infra/components/code-controller-context/types.md
@@ -23,13 +23,14 @@ An object containing:
 - setSelection: Function to update the selection
 - components: Override components for the preview
 
-| Property     | Type                                                                             | Description |
-| :----------- | :------------------------------------------------------------------------------- | :---------- |
-| code         | `ControlledCode \| undefined`                                                    | -           |
-| selection    | `Selection \| undefined`                                                         | -           |
-| setCode      | `React.Dispatch<React.SetStateAction<ControlledCode \| undefined>> \| undefined` | -           |
-| setSelection | `React.Dispatch<React.SetStateAction<Selection>> \| undefined`                   | -           |
-| components   | `Record<string, React.ReactNode> \| undefined`                                   | -           |
+| Property        | Type                                                                             | Description |
+| :-------------- | :------------------------------------------------------------------------------- | :---------- |
+| code            | `ControlledCode \| undefined`                                                    | -           |
+| selection       | `Selection \| undefined`                                                         | -           |
+| setCode         | `React.Dispatch<React.SetStateAction<ControlledCode \| undefined>> \| undefined` | -           |
+| setSelection    | `React.Dispatch<React.SetStateAction<Selection>> \| undefined`                   | -           |
+| components      | `Record<string, React.ReactNode> \| undefined`                                   | -           |
+| sourceEnhancers | `SourceEnhancer[] \| undefined`                                                  | -           |
 
 ## Additional Types
 
@@ -73,6 +74,11 @@ type CodeControllerContext = {
    * e.g. `{ variantA: {}, variantB: {} }`.
    */
   components?: Record<string, React.ReactNode>;
+  /**
+   * Additional source enhancers to apply to parsed HAST sources.
+   * These are merged with enhancers from CodeProvider and useCode opts.
+   */
+  sourceEnhancers?: SourceEnhancer[];
 };
 ```
 
@@ -81,3 +87,15 @@ type CodeControllerContext = {
 ```typescript
 type Selection = { variant: string; fileName?: string; transformKey?: string };
 ```
+
+## External Types
+
+### SourceEnhancer
+
+```typescript
+type SourceEnhancer = (
+  root: { data?: unknown | undefined },
+  comments: {} | undefined,
+  fileName: string,
+) => { data?: unknown | undefined } | Promise;
+```
diff --git a/docs/app/docs-infra/components/code-highlighter/types.md b/docs/app/docs-infra/components/code-highlighter/types.md
index 5e9e550d1..3ad30cfcd 100644
--- a/docs/app/docs-infra/components/code-highlighter/types.md
+++ b/docs/app/docs-infra/components/code-highlighter/types.md
@@ -527,6 +527,16 @@ type CodeRenderingProps<T extends {}> = {
 };
 ```
 
+### CollapseMap
+
+Tracks comments that were collapsed onto a line when their original lines
+were deleted. Keyed by the line they collapsed onto; each entry records
+the original offset from the edit line so the collapse can be reversed.
+
+```typescript
+type CollapseMap = { [key: number]: { offset: number; comments: string[] }[] };
+```
+
 ### Components
 
 ```typescript
@@ -582,13 +592,25 @@ type ControlledVariantCode = {
   source?: string | null;
   extraFiles?: ControlledVariantExtraFiles;
   filesOrder?: string[];
+  comments?: SourceComments;
+  collapseMap?: CollapseMap;
+  totalLines?: number;
+  emptyLines?: number[];
 };
 ```
 
 ### ControlledVariantExtraFiles
 
 ```typescript
-type ControlledVariantExtraFiles = { [fileName: string]: { source: string | null } };
+type ControlledVariantExtraFiles = {
+  [fileName: string]: {
+    source: string | null;
+    comments?: SourceComments;
+    collapseMap?: CollapseMap;
+    totalLines?: number;
+    emptyLines?: number[];
+  };
+};
 ```
 
 ### ExternalImportItem
@@ -822,4 +844,4 @@ type VariantSource = string | HastRoot | { hastJson: string } | { hastCompressed
 ## Export Groups
 
 - `CodeHighlighter`
-- `CodeHighlighterTypes`: `Components`, `Transforms`, `ExternalImportItem`, `Externals`, `HastRoot`, `VariantSource`, `VariantExtraFiles`, `VariantCode`, `Code`, `ControlledVariantExtraFiles`, `ControlledVariantCode`, `ControlledCode`, `ContentProps`, `ContentLoadingVariant`, `BaseContentLoadingProps`, `ContentLoadingProps`, `LoadCodeMeta`, `LoadVariantMeta`, `LoadSource`, `TransformSource`, `ParseSource`, `SourceTransformer`, `SourceTransformers`, `SourceComments`, `SourceEnhancer`, `SourceEnhancers`, `LoadFileOptions`, `LoadVariantOptions`, `LoadFallbackCodeOptions`, `CodeIdentityProps`, `CodeContentProps`, `CodeLoadingProps`, `CodeFunctionProps`, `CodeRenderingProps`, `CodeClientRenderingProps`, `CodeHighlighterBaseProps`, `CodeHighlighterClientProps`, `CodeHighlighterProps`
+- `CodeHighlighterTypes`: `Components`, `Transforms`, `ExternalImportItem`, `Externals`, `HastRoot`, `VariantSource`, `VariantExtraFiles`, `VariantCode`, `Code`, `CollapseMap`, `ControlledVariantExtraFiles`, `ControlledVariantCode`, `ControlledCode`, `ContentProps`, `ContentLoadingVariant`, `BaseContentLoadingProps`, `ContentLoadingProps`, `LoadCodeMeta`, `LoadVariantMeta`, `LoadSource`, `TransformSource`, `ParseSource`, `SourceTransformer`, `SourceTransformers`, `SourceComments`, `SourceEnhancer`, `SourceEnhancers`, `LoadFileOptions`, `LoadVariantOptions`, `LoadFallbackCodeOptions`, `CodeIdentityProps`, `CodeContentProps`, `CodeLoadingProps`, `CodeFunctionProps`, `CodeRenderingProps`, `CodeClientRenderingProps`, `CodeHighlighterBaseProps`, `CodeHighlighterClientProps`, `CodeHighlighterProps`
diff --git a/docs/app/docs-infra/components/code-provider/page.mdx b/docs/app/docs-infra/components/code-provider/page.mdx
index 788854751..0dd185c39 100644
--- a/docs/app/docs-infra/components/code-provider/page.mdx
+++ b/docs/app/docs-infra/components/code-provider/page.mdx
@@ -105,6 +105,29 @@ import { TypesCodeProvider } from './types';
 
 [See Types](./types.md)
 
+## Worker-Backed Live Highlighting
+
+When the runtime is a browser that supports Web Workers, `CodeProvider` automatically spawns a single dedicated worker per provider and uses it to syntax-highlight source code while the user is typing in an editable code block. This keeps the main thread responsive during fast keystrokes — the synchronous highlighter that runs after each commit can still take low single-digit milliseconds for large files, which is enough to drop a frame on slower devices.
+
+### Lifecycle
+
+1. The provider creates the worker on its first browser-only effect.
+2. The worker module and the (lazy) grammar chunk are both fetched via dynamic `import(...)`, so neither ships in SSR bundles and neither blocks first paint.
+3. Grammars are sent across the boundary exactly once via `postMessage`. The worker calls `createStarryNight(grammars)` and acknowledges with `init-ack`. If grammar creation throws, the worker posts `init-error` and every queued parse request rejects.
+4. While initialization is in flight, parse requests are queued and drained in arrival order on `init-ack`.
+5. On unmount the worker is terminated; any still-pending requests reject with `Worker terminated`.
+
+### Cancellation
+
+Each parse request accepts an optional `AbortSignal`. When a newer keystroke supersedes an older one, the consumer (typically `useEditable`'s `preParse` hook) aborts the older signal so the worker's response is dropped on arrival rather than replacing fresher highlighted output. Pre-aborted signals reject synchronously without any cross-thread traffic.
+
+### Wiring
+
+The worker integration is fully automatic — no opt-in is required. A consumer that wraps an editable code block in `CodeProvider` will see worker-backed highlighting as long as `Worker` is defined and the editable's host (typically [`useCode`](../../hooks/use-code/page.mdx)) provides a `setSource` callback. When either condition is missing the editable falls back to the synchronous main-thread highlighter and the UX is unchanged.
+
+> [!NOTE]
+> The same grammar chunk powers both the main-thread `parseSource` and the worker-thread parser, so enabling the worker does not double the grammar download cost.
+
 ## Best Practices
 
 1. **Wrap at the appropriate level** - Place `CodeProvider` high enough to cover all components that need highlighting
diff --git a/docs/app/docs-infra/components/page.mdx b/docs/app/docs-infra/components/page.mdx
index 078df971a..8c39fa627 100644
--- a/docs/app/docs-infra/components/page.mdx
+++ b/docs/app/docs-infra/components/page.mdx
@@ -83,6 +83,10 @@ The `CodeProvider` component provides client-side functions for fetching source
   - Integration with CodeHighlighter
   - Custom Loading Functions
   - Types
+  - Worker-Backed Live Highlighting
+    - Lifecycle
+    - Cancellation
+    - Wiring
   - Best Practices
   - Comparison with Other Components
   - Troubleshooting
@@ -117,6 +121,7 @@ The `CodeControllerContext` provides a React context for managing controlled cod
     - Using createDemoClient
     - Creating a Custom createDemoClient
     - Integration with createLiveDemo
+  - Benchmarking
   - Best Practices
   - Types
   - Requirements
diff --git a/docs/app/docs-infra/factories/abstract-create-demo-client/page.mdx b/docs/app/docs-infra/factories/abstract-create-demo-client/page.mdx
index d74d160e7..613402f1b 100644
--- a/docs/app/docs-infra/factories/abstract-create-demo-client/page.mdx
+++ b/docs/app/docs-infra/factories/abstract-create-demo-client/page.mdx
@@ -42,6 +42,7 @@ To implement a demo client factory, use the `abstractCreateDemoClient` utilities
 
 ```ts
 import { createDemoClientFactory } from '@mui/internal-docs-infra/abstractCreateDemoClient';
+import { DemoController } from './DemoController';
 
 /**
  * Creates a demo client provider for live editing with precomputed externals.
@@ -49,8 +50,7 @@ import { createDemoClientFactory } from '@mui/internal-docs-infra/abstractCreate
  * @param meta Additional meta and configuration for the demo client.
  */
 export const createDemoClient = createDemoClientFactory({
-  live: true,
-  // Additional client options
+  DemoController,
 });
 ```
 
@@ -117,9 +117,10 @@ const context = {
 ```ts
 // createDemoClient.ts - Define your client factory
 import { createDemoClientFactory } from '@mui/internal-docs-infra/abstractCreateDemoClient';
+import { DemoController } from './DemoController';
 
 export const createDemoClient = createDemoClientFactory({
-  live: true,
+  DemoController,
 });
 ```
 
diff --git a/docs/app/docs-infra/factories/abstract-create-demo-client/types.md b/docs/app/docs-infra/factories/abstract-create-demo-client/types.md
index 41e8fd7d7..2bb220ada 100644
--- a/docs/app/docs-infra/factories/abstract-create-demo-client/types.md
+++ b/docs/app/docs-infra/factories/abstract-create-demo-client/types.md
@@ -11,11 +11,11 @@ This creates a provider component that supplies externals to child components.
 
 **Parameters:**
 
-| Parameter | Type                              | Default | Description                                       |
-| :-------- | :-------------------------------- | :------ | :------------------------------------------------ |
-| options   | `AbstractCreateDemoClientOptions` | -       | Configuration options for the demo client factory |
-| url       | `string`                          | -       | -                                                 |
-| meta?     | `CreateDemoClientMeta`            | -       | -                                                 |
+| Parameter | Type                                                 | Default | Description                                       |
+| :-------- | :--------------------------------------------------- | :------ | :------------------------------------------------ |
+| options   | `AbstractCreateDemoClientOptions<DefaultController>` | -       | Configuration options for the demo client factory |
+| url       | `string`                                             | -       | -                                                 |
+| meta?     | `CreateDemoClientMeta<DefaultController>`            | -       | -                                                 |
 
 **Return Value:**
 
@@ -29,16 +29,16 @@ type ReturnValue = React.ComponentType<{ children: React.ReactNode }>;
 
 **Parameters:**
 
-| Parameter | Type                              | Default | Description |
-| :-------- | :-------------------------------- | :------ | :---------- |
-| options   | `AbstractCreateDemoClientOptions` | -       | -           |
+| Parameter | Type                                                 | Default | Description |
+| :-------- | :--------------------------------------------------- | :------ | :---------- |
+| options   | `AbstractCreateDemoClientOptions<DefaultController>` | -       | -           |
 
 **Return Value:**
 
 ```tsx
 type ReturnValue = (
   url: string,
-  meta?: CreateDemoClientMeta,
+  meta?: CreateDemoClientMeta<DefaultController>,
 ) => React.ComponentType<{ children: React.ReactNode }>;
 ```
 
@@ -47,7 +47,7 @@ type ReturnValue = (
 ### CreateDemoClientMeta
 
 ```typescript
-type CreateDemoClientMeta = {
+type CreateDemoClientMeta<C extends DefaultController> = {
   [key: string]: any;
   name?: string;
   slug?: string;
@@ -55,5 +55,6 @@ type CreateDemoClientMeta = {
   variantType?: string;
   skipPrecompute?: boolean;
   precompute?: { [key: string]: any; externals?: Externals };
+  controllerProps?: {};
 };
 ```
diff --git a/docs/app/docs-infra/hooks/page.mdx b/docs/app/docs-infra/hooks/page.mdx
index 2f12f6015..966bff4ab 100644
--- a/docs/app/docs-infra/hooks/page.mdx
+++ b/docs/app/docs-infra/hooks/page.mdx
@@ -127,6 +127,7 @@ The `useDemo` hook extends `useCode` functionality to provide a complete demo re
     - Simple Demo Display
     - Demo with File Navigation
     - Demo with Language Toggle
+    - Reset Focus After Interaction
   - Performance Considerations
   - Error Handling
   - Troubleshooting
diff --git a/docs/app/docs-infra/hooks/use-code/types.md b/docs/app/docs-infra/hooks/use-code/types.md
index ecf09e0a4..85a90f546 100644
--- a/docs/app/docs-infra/hooks/use-code/types.md
+++ b/docs/app/docs-infra/hooks/use-code/types.md
@@ -40,7 +40,6 @@ type CodeComponentsContext = React.Context<Partial<Components> | undefined>;
 ```typescript
 type UseCodeOpts = {
   preClassName?: string;
-  preRef?: React.Ref<HTMLPreElement>;
   defaultOpen?: boolean;
   copy?: UseCopierOpts;
   githubUrlPrefix?: string;
@@ -65,6 +64,8 @@ type UseCodeOpts = {
    * Runs asynchronously when code changes.
    */
   sourceEnhancers?: SourceEnhancer[];
+  /** Disables editing of the code block even when a CodeControllerContext is present. */
+  disabled?: boolean;
 };
 ```
 
@@ -88,7 +89,13 @@ type UseCodeResult<T extends {} = {}> = {
   availableTransforms: string[];
   selectedTransform: string | null | undefined;
   selectTransform: (transformName: string | null) => void;
-  setSource?: (source: string) => void;
+  /**
+   * Replace the source of the currently selected file (or `fileName` when
+   * provided) in the controlled code. Internal hooks may pass additional
+   * arguments (caret position, pre-parsed HAST) that are not part of the
+   * public contract.
+   */
+  setSource?: (source: string, fileName?: string) => void;
   userProps: UserProps<T>;
 };
 ```
diff --git a/docs/app/docs-infra/hooks/use-demo/page.mdx b/docs/app/docs-infra/hooks/use-demo/page.mdx
index 28ce6729d..8b2380a11 100644
--- a/docs/app/docs-infra/hooks/use-demo/page.mdx
+++ b/docs/app/docs-infra/hooks/use-demo/page.mdx
@@ -28,7 +28,7 @@ export function DemoContent(props) {
   const demo = useDemo(props, { preClassName: styles.codeBlock });
 
   return (
-    <div className={styles.container} ref={demo.ref}>
+    <div className={styles.container}>
       {/* Component Preview Section */}
       <div className={styles.demoSection}>{demo.component}</div>
 
@@ -135,8 +135,7 @@ export function DemoContent(props) {
 
 ```tsx
 export function DemoLiveContent(props) {
-  const preRef = React.useRef<HTMLPreElement | null>(null);
-  const demo = useDemo(props, { preClassName: styles.codeBlock, preRef });
+  const demo = useDemo(props, { preClassName: styles.codeBlock });
 
   const hasJsTransform = demo.availableTransforms.includes('js');
   const isJsSelected = demo.selectedTransform === 'js';
@@ -163,14 +162,7 @@ export function DemoLiveContent(props) {
     [demo.variants],
   );
 
-  // Set up editable functionality
-  const onChange = React.useCallback((text: string) => {
-    demo.setSource?.(text);
-  }, []);
-  useEditable(preRef, onChange, {
-    indentation: 2,
-    disabled: !demo.setSource,
-  });
+  // Set up editable functionality is now automatic via useCode/useDemo
 
   return (
     <div className={styles.container}>
@@ -563,6 +555,44 @@ export function DemoWithLanguageToggle(props) {
 }
 ```
 
+### Reset Focus After Interaction
+
+`useDemo` exposes a `focusRef` and a `resetFocus` callback for sending
+keyboard focus back into the demo — useful after the user interacts with
+toolbar controls (variant pickers, copy buttons, sandbox links, etc.) so a
+follow-up Tab keypress lands inside the rendered component instead of the
+next toolbar control.
+
+The typical pattern is to render an invisible focus-target button at the
+top of the preview area:
+
+```tsx
+export function DemoContent(props) {
+  const demo = useDemo(props, { preClassName: styles.codeBlock });
+
+  return (
+    <div className={styles.container}>
+      <div className={styles.demoSection}>
+        {/* Invisible focus target — receives focus when `resetFocus` runs. */}
+        <button ref={demo.focusRef} tabIndex={-1} aria-hidden className={styles.focusTarget} />
+        {demo.component}
+      </div>
+
+      <div className={styles.toolbar}>
+        <button onClick={demo.resetFocus}>Reset focus</button>
+      </div>
+
+      <div className={styles.codeSection}>{demo.selectedFile}</div>
+    </div>
+  );
+}
+```
+
+`focusRef` is typed as `React.RefObject<HTMLButtonElement | null>` since
+the focus target is conventionally an invisible button. Calling
+`resetFocus` is a no-op when the ref isn't attached, so it's safe to wire
+up the toolbar button unconditionally.
+
 ## Performance Considerations
 
 - **Component memoization**: Components are automatically memoized by the demo factory
diff --git a/docs/app/docs-infra/hooks/use-demo/types.md b/docs/app/docs-infra/hooks/use-demo/types.md
index 771668ed0..4083dba4b 100644
--- a/docs/app/docs-infra/hooks/use-demo/types.md
+++ b/docs/app/docs-infra/hooks/use-demo/types.md
@@ -218,33 +218,33 @@ type ReturnValue = void;
 
 **useDemo Return Value:**
 
-| Property            | Type                                                                                                                             | Description |
-| :------------------ | :------------------------------------------------------------------------------------------------------------------------------- | :---------- |
-| component           | `string \| number \| bigint \| true \| ReactElement \| Iterable<React.ReactNode, any, any> \| Promise<AwaitedReactNode> \| null` | -           |
-| ref                 | `React.RefObject<HTMLDivElement \| null>`                                                                                        | -           |
-| resetFocus          | `(() => void)`                                                                                                                   | -           |
-| openStackBlitz      | `(() => void)`                                                                                                                   | -           |
-| openCodeSandbox     | `(() => void)`                                                                                                                   | -           |
-| name                | `string \| undefined`                                                                                                            | -           |
-| slug                | `string \| undefined`                                                                                                            | -           |
-| variants            | `string[]`                                                                                                                       | -           |
-| selectedVariant     | `string`                                                                                                                         | -           |
-| selectVariant       | `((variant: string \| null) => void)`                                                                                            | -           |
-| files               | `({ name: string; slug?: string; component: React.ReactNode })[]`                                                                | -           |
-| selectedFile        | `React.ReactNode`                                                                                                                | -           |
-| selectedFileLines   | `number`                                                                                                                         | -           |
-| selectedFileName    | `string \| undefined`                                                                                                            | -           |
-| selectFileName      | `((fileName: string) => void)`                                                                                                   | -           |
-| allFilesSlugs       | `({ fileName: string; slug: string; variantName: string })[]`                                                                    | -           |
-| expanded            | `boolean`                                                                                                                        | -           |
-| expand              | `(() => void)`                                                                                                                   | -           |
-| setExpanded         | `((expanded: boolean) => void)`                                                                                                  | -           |
-| copy                | `((event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => Promise<void>)`                                                    | -           |
-| availableTransforms | `string[]`                                                                                                                       | -           |
-| selectedTransform   | `string \| null \| undefined`                                                                                                    | -           |
-| selectTransform     | `((transformName: string \| null) => void)`                                                                                      | -           |
-| setSource           | `((source: string) => void) \| undefined`                                                                                        | -           |
-| userProps           | `UserProps<{}>`                                                                                                                  | -           |
+| Property            | Type                                                                                                                             | Description                                                                                                                                                                                                                                  |
+| :------------------ | :------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| component           | `string \| number \| bigint \| true \| ReactElement \| Iterable<React.ReactNode, any, any> \| Promise<AwaitedReactNode> \| null` | -                                                                                                                                                                                                                                            |
+| focusRef            | `React.RefObject<HTMLButtonElement \| null>`                                                                                     | -                                                                                                                                                                                                                                            |
+| resetFocus          | `(() => void)`                                                                                                                   | -                                                                                                                                                                                                                                            |
+| openStackBlitz      | `(() => void)`                                                                                                                   | -                                                                                                                                                                                                                                            |
+| openCodeSandbox     | `(() => void)`                                                                                                                   | -                                                                                                                                                                                                                                            |
+| name                | `string \| undefined`                                                                                                            | -                                                                                                                                                                                                                                            |
+| slug                | `string \| undefined`                                                                                                            | -                                                                                                                                                                                                                                            |
+| variants            | `string[]`                                                                                                                       | -                                                                                                                                                                                                                                            |
+| selectedVariant     | `string`                                                                                                                         | -                                                                                                                                                                                                                                            |
+| selectVariant       | `((variant: string \| null) => void)`                                                                                            | -                                                                                                                                                                                                                                            |
+| files               | `({ name: string; slug?: string; component: React.ReactNode })[]`                                                                | -                                                                                                                                                                                                                                            |
+| selectedFile        | `React.ReactNode`                                                                                                                | -                                                                                                                                                                                                                                            |
+| selectedFileLines   | `number`                                                                                                                         | -                                                                                                                                                                                                                                            |
+| selectedFileName    | `string \| undefined`                                                                                                            | -                                                                                                                                                                                                                                            |
+| selectFileName      | `((fileName: string) => void)`                                                                                                   | -                                                                                                                                                                                                                                            |
+| allFilesSlugs       | `({ fileName: string; slug: string; variantName: string })[]`                                                                    | -                                                                                                                                                                                                                                            |
+| expanded            | `boolean`                                                                                                                        | -                                                                                                                                                                                                                                            |
+| expand              | `(() => void)`                                                                                                                   | -                                                                                                                                                                                                                                            |
+| setExpanded         | `((expanded: boolean) => void)`                                                                                                  | -                                                                                                                                                                                                                                            |
+| copy                | `((event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => Promise<void>)`                                                    | -                                                                                                                                                                                                                                            |
+| availableTransforms | `string[]`                                                                                                                       | -                                                                                                                                                                                                                                            |
+| selectedTransform   | `string \| null \| undefined`                                                                                                    | -                                                                                                                                                                                                                                            |
+| selectTransform     | `((transformName: string \| null) => void)`                                                                                      | -                                                                                                                                                                                                                                            |
+| setSource           | `((source: string, fileName?: string) => void) \| undefined`                                                                     | Replace the source of the currently selected file (or `fileName` when&#xA;provided) in the controlled code. Internal hooks may pass additional&#xA;arguments (caret position, pre-parsed HAST) that are not part of the&#xA;public contract. |
+| userProps           | `UserProps<{}>`                                                                                                                  | -                                                                                                                                                                                                                                            |
 
 ## Additional Types
 
diff --git a/docs/app/docs-infra/overview/contributing/page.mdx b/docs/app/docs-infra/overview/contributing/page.mdx
index fe5258b18..1d80433bf 100644
--- a/docs/app/docs-infra/overview/contributing/page.mdx
+++ b/docs/app/docs-infra/overview/contributing/page.mdx
@@ -30,17 +30,19 @@ pnpm docs:dev
 
 ### Development Commands
 
-| Command                  | Description            |
-| ------------------------ | ---------------------- |
-| `pnpm docs:dev`          | Start docs dev server  |
-| `pnpm docs:build`        | Build docs site        |
-| `pnpm docs:validate`     | Validate docs files    |
-| `pnpm release:build`     | Build all packages     |
-| `pnpm typescript`        | Type check             |
-| `pnpm eslint`            | Lint code              |
-| `pnpm prettier`          | Format code            |
-| `pnpm test --run`        | Run all tests          |
-| `pnpm test --run {name}` | Run specific test file |
+| Command                        | Description                                      |
+| ------------------------------ | ------------------------------------------------ |
+| `pnpm docs:dev`                | Start docs dev server                            |
+| `pnpm docs:build`              | Build docs site                                  |
+| `pnpm docs:validate`           | Validate docs files                              |
+| `pnpm release:build`           | Build all packages                               |
+| `pnpm typescript`              | Type check                                       |
+| `pnpm eslint`                  | Lint code                                        |
+| `pnpm prettier`                | Format code                                      |
+| `pnpm test --run`              | Run all tests                                    |
+| `pnpm test --run {name}`       | Run specific test file                           |
+| `pnpm test:browser --run`      | Run browser tests (requires podman/docker)       |
+| `pnpm test:browser:unconfined` | Run browser tests directly (CI/Playwright image) |
 
 > [!IMPORTANT]
 > Always run `pnpm prettier`, `pnpm eslint`, `pnpm typescript`, and `pnpm docs:validate` before submitting a PR.
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeIndent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeIndent.tsx
index f262e1d4f..389263282 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeIndent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeIndent.tsx
@@ -4,19 +4,22 @@ import * as React from 'react';
 import { CodeHighlighter } from '@mui/internal-docs-infra/CodeHighlighter';
 import type { Code as CodeType } from '@mui/internal-docs-infra/CodeHighlighter/types';
 import { createParseSource } from '@mui/internal-docs-infra/pipeline/parseSource';
-import { enhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+import { createEnhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
 
 import { IndentContent } from './IndentContent';
 
 const sourceParser = createParseSource();
-const sourceEnhancers = [enhanceCodeEmphasis];
+// `emitFrameIndent: true` opts in to the `data-frame-indent` attribute that
+// the CSS below uses to shift the focused frame left when collapsed.
+const sourceEnhancers = [createEnhanceCodeEmphasis({ emitFrameIndent: true })];
 
 /**
  * A server component that renders a collapsible code block with indent shifting.
  *
- * Uses the default `enhanceCodeEmphasis` (no padding) so only `highlighted`
- * and normal frames are produced. The `data-frame-indent` attribute on
- * highlighted frames drives the CSS-based left shift.
+ * Uses `createEnhanceCodeEmphasis({ emitFrameIndent: true })` (no padding) so
+ * only `highlighted`/`focus` and normal frames are produced, and each region
+ * frame carries a `data-frame-indent` attribute that drives the CSS-based
+ * left shift.
  */
 export function CodeIndent({ code }: { code: CodeType }) {
   return (
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
index 65104771c..44cd2284b 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
@@ -372,7 +372,7 @@ When padding is configured (see [Configurable Padding](#configurable-padding)),
 | Attribute                | Type   | Description                                                                                                                                                                                                                                                                                                                      |
 | ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `data-frame-type`        | string | `"highlighted"` (focused region with line highlights), `"highlighted-unfocused"` (non-focused regions with line highlights), `"focus"` (focused region without line highlights), `"focus-unfocused"` (non-focused region without line highlights), `"padding-top"`, or `"padding-bottom"`. Normal frames have no type attribute. |
-| `data-frame-indent`      | number | Only on `highlighted`, `highlighted-unfocused`, `focus`, and `focus-unfocused` frames. The shared indent level of the highlighted lines (min leading spaces ÷ 2).                                                                                                                                                                |
+| `data-frame-indent`      | number | Only on `highlighted`, `highlighted-unfocused`, `focus`, and `focus-unfocused` frames, and only when `createEnhanceCodeEmphasis({ emitFrameIndent: true })` is used. The shared indent level of the highlighted lines (min leading spaces ÷ 2).                                                                                  |
 | `data-frame-description` | string | Present on highlighted frames when the `@highlight` or `@highlight-start` directive includes a description (e.g., `@highlight "description"`). Not set when highlighting is at the line level (inside a focus region or when strong).                                                                                            |
 
 ### Configurable Padding
@@ -395,6 +395,7 @@ const sourceEnhancers = [
 | `paddingFrameMaxSize` | number  | `0`     | Maximum number of context lines above/below the focused region                                                                                                                                                                                                                                                     |
 | `focusFramesMaxSize`  | number  | —       | Maximum total lines in the focus area (padding + region). When the region fits, remaining budget is split floor/ceil between padding-top and padding-bottom. When the region exceeds this limit, a focused window is taken from the start of the region, and the remaining overflow lines are marked as unfocused. |
 | `strictHighlightText` | boolean | `false` | When `true`, throws an error if a `@highlight-text` match has to be fragmented across element boundaries (producing `data-hl-part` spans). Highlights that wrap multiple complete elements in a single `data-hl` span are still allowed.                                                                           |
+| `emitFrameIndent`     | boolean | `false` | When `true`, region frames (`highlighted`, `focus`, and their unfocused variants) receive a `data-frame-indent` attribute carrying the shared indent level of the highlighted lines. Useful for CSS-driven indent shifting in collapsed views (see [Indent Shifting](#indent-shifting)).                           |
 
 When `paddingFrameMaxSize` is `0` (the default), no padding frames are created and only region frames (`highlighted`, `focus`, etc.) and normal frames are produced.
 
@@ -693,7 +694,7 @@ import { DemoFocusCode } from './demos/focus-code';
 
 ### Indent Shifting
 
-With no padding configured, only highlighted/focus and normal frames are produced. The `data-frame-indent` attribute on region frames tells CSS how far the code is indented. This demo highlights an import statement (indent 0) and uses standalone `@focus-start`/`@focus-end` around the deeply nested `<DatePicker>` usage (indent 3). When collapsed, the focused frame shifts left by `6ch` so it aligns with the left edge, then resets when expanded.
+With no padding configured, only highlighted/focus and normal frames are produced. Opt in to the `data-frame-indent` attribute on region frames by passing `emitFrameIndent: true` to `createEnhanceCodeEmphasis` — CSS can then read it to know how far the code is indented. This demo highlights an import statement (indent 0) and uses standalone `@focus-start`/`@focus-end` around the deeply nested `<DatePicker>` usage (indent 3). When collapsed, the focused frame shifts left by `6ch` so it aligns with the left edge, then resets when expanded.
 
 import { DemoIndentCode } from './demos/indent-code';
 
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md b/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
index 4a2b03392..7f02faec2 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
@@ -122,6 +122,15 @@ type EnhanceCodeEmphasisOptions = {
    * allowed — only boundary-straddling matches are rejected.
    */
   strictHighlightText?: boolean;
+  /**
+   * When `true`, emits a `data-frame-indent` attribute on highlighted/focus
+   * region frames indicating the shared leading indent level. Consumers can
+   * use this to visually shift collapsible regions horizontally when
+   * surrounding context lines are hidden. Off by default since most demos
+   * don't need it and it bloats the rendered HTML.
+   * @default false
+   */
+  emitFrameIndent?: boolean;
 };
 ```
 
diff --git a/docs/app/docs-infra/pipeline/parse-source/types.md b/docs/app/docs-infra/pipeline/parse-source/types.md
index a5c60af72..f4d78af18 100644
--- a/docs/app/docs-infra/pipeline/parse-source/types.md
+++ b/docs/app/docs-infra/pipeline/parse-source/types.md
@@ -10,6 +10,10 @@ Initializes Starry Night and returns a configured `parseSource` function.
 This only needs to be called once per application. The Starry Night instance
 is stored globally for reuse across calls.
 
+The grammar definitions are loaded via dynamic `import('./grammars')` so the
+(heavy) TextMate JSON payload is split into its own bundler chunk and only
+fetched when syntax highlighting is actually needed.
+
 **Return Value:**
 
 A Promise that resolves to the initialized `parseSource` function
@@ -60,6 +64,11 @@ type ReturnValue = HastRoot;
 
 ### extensionMap
 
+Light-weight grammar metadata maps. These can be statically imported without
+pulling in the heavy TextMate grammar JSON payloads (which live in
+`./grammars.ts` and should be loaded via dynamic `import('./grammars')` so
+the bundler can code-split them into their own chunk).
+
 ```typescript
 type extensionMap = Record<string, string>;
 ```
diff --git a/package.json b/package.json
index 9dd056048..093911b13 100644
--- a/package.json
+++ b/package.json
@@ -10,6 +10,8 @@
     "prettier:all": "prettier --write . --ignore-path .lintignore",
     "update-netlify-ignore": "pnpm code-infra netlify-ignore @apps/code-infra-dashboard",
     "test": "vitest",
+    "test:browser": "pnpm -F \"./docs\" run docs-infra browser --workspace --script test:browser:unconfined --playwright-version 1.59.1 --",
+    "test:browser:unconfined": "vitest --config vitest.config.browser.mts",
     "markdownlint": "markdownlint-cli2 \"**/*.md\"",
     "stylelint": "stylelint --reportInvalidScopeDisables --reportNeedlessDisables \"**/*.?(c|m)[jt]s?(x)\" \"**/*.css\" --ignore-path .lintignore",
     "typescript": "pnpm -r run typescript",
@@ -85,11 +87,12 @@
   },
   "devDependencies": {
     "@babel/plugin-transform-react-constant-elements": "7.27.1",
+    "@vitest/browser-playwright": "4.1.3",
     "baseline-browser-mapping": "2.10.19",
     "eslint-plugin-n": "17.24.0",
     "markdownlint-cli2": "0.22.0",
     "pkg-pr-new": "0.0.66",
-    "playwright": "1.58.2",
+    "playwright": "1.59.1",
     "stylelint": "17.4.0"
   },
   "packageManager": "pnpm@10.32.1",
diff --git a/packages/docs-infra/package.json b/packages/docs-infra/package.json
index 81b636758..d64a8883e 100644
--- a/packages/docs-infra/package.json
+++ b/packages/docs-infra/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -118,8 +118,10 @@
     "uint8-to-base64": "^0.2.1",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
+    "use-editable": "^2.3.3",
     "vscode-oniguruma": "^2.0.1",
-    "yargs": "^18.0.0"
+    "yargs": "^18.0.0",
+    "zx": "^8.8.5"
   },
   "devDependencies": {
     "@testing-library/react": "16.3.2",
@@ -131,6 +133,7 @@
     "@types/node": "22.19.0",
     "@types/proper-lockfile": "4.1.4",
     "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
     "@types/webpack": "5.28.5",
     "@types/yargs": "17.0.35",
     "@typescript-eslint/utils": "^8.57.1",
@@ -138,6 +141,7 @@
     "hast-util-to-html": "9.0.5",
     "next": "16.2.3",
     "react": "19.2.5",
+    "react-dom": "19.2.5",
     "rehype-parse": "9.0.1",
     "rehype-stringify": "10.0.1",
     "remark-rehype": "11.1.2",
@@ -148,6 +152,7 @@
     "next": "^15.0.0 || ^16.0.0",
     "prettier": "^3.0.0",
     "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0",
     "typescript": "^6.0.2"
   },
   "peerDependenciesMeta": {
diff --git a/packages/docs-infra/src/CodeControllerContext/CodeControllerContext.tsx b/packages/docs-infra/src/CodeControllerContext/CodeControllerContext.tsx
index 161aadfaf..37a77b9fc 100644
--- a/packages/docs-infra/src/CodeControllerContext/CodeControllerContext.tsx
+++ b/packages/docs-infra/src/CodeControllerContext/CodeControllerContext.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import * as React from 'react';
-import type { ControlledCode } from '../CodeHighlighter/types';
+import type { ControlledCode, SourceEnhancers } from '../CodeHighlighter/types';
 
 export type Selection = { variant: string; fileName?: string; transformKey?: string };
 
@@ -47,6 +47,12 @@ export interface CodeControllerContext {
    * e.g. `{ variantA: {}, variantB: {} }`.
    */
   components?: Record<string, React.ReactNode> | undefined;
+
+  /**
+   * Additional source enhancers to apply to parsed HAST sources.
+   * These are merged with enhancers from CodeProvider and useCode opts.
+   */
+  sourceEnhancers?: SourceEnhancers;
 }
 
 export const CodeControllerContext = React.createContext<CodeControllerContext | undefined>(
@@ -74,6 +80,7 @@ export function useControlledCode(): {
   setCode: React.Dispatch<React.SetStateAction<ControlledCode | undefined>> | undefined;
   setSelection: React.Dispatch<React.SetStateAction<Selection>> | undefined;
   components: Record<string, React.ReactNode> | undefined;
+  sourceEnhancers: SourceEnhancers | undefined;
 } {
   const context = React.useContext(CodeControllerContext);
 
@@ -83,5 +90,6 @@ export function useControlledCode(): {
     setCode: context?.setCode,
     setSelection: context?.setSelection,
     components: context?.components,
+    sourceEnhancers: context?.sourceEnhancers,
   };
 }
diff --git a/packages/docs-infra/src/CodeHighlighter/CodeHighlighterClient.tsx b/packages/docs-infra/src/CodeHighlighter/CodeHighlighterClient.tsx
index 4221c3911..d0af21cb5 100644
--- a/packages/docs-infra/src/CodeHighlighter/CodeHighlighterClient.tsx
+++ b/packages/docs-infra/src/CodeHighlighter/CodeHighlighterClient.tsx
@@ -8,7 +8,11 @@ import {
   type ControlledCode,
   type VariantCode,
 } from './types';
-import { CodeHighlighterContext, type CodeHighlighterContextType } from './CodeHighlighterContext';
+import {
+  CodeHighlighterContext,
+  type CodeHighlighterContextType,
+  type PreParsedCacheEntry,
+} from './CodeHighlighterContext';
 import { maybeCodeInitialData } from '../pipeline/loadCodeVariant/maybeCodeInitialData';
 import { hasAllVariants } from '../pipeline/loadCodeVariant/hasAllCodeVariants';
 import { CodeHighlighterFallbackContext } from './CodeHighlighterFallbackContext';
@@ -482,10 +486,12 @@ function useControlledCodeParsing({
   code,
   forceClient,
   url,
+  preParsedCache,
 }: {
   code?: ControlledCode;
   forceClient?: boolean;
   url?: string;
+  preParsedCache?: Map<string, PreParsedCacheEntry>;
 }) {
   const { parseSource, parseControlledCode } = useCodeContext();
 
@@ -516,8 +522,8 @@ function useControlledCodeParsing({
       return undefined;
     }
 
-    return parseControlledCode(code, parseSource);
-  }, [code, parseSource, parseControlledCode, forceClient, url]);
+    return parseControlledCode(code, parseSource, preParsedCache);
+  }, [code, parseSource, parseControlledCode, forceClient, url, preParsedCache]);
 
   return { parsedControlledCode };
 }
@@ -973,10 +979,18 @@ export function CodeHighlighterClient(props: CodeHighlighterClientProps) {
     variantName,
   });
 
+  // Per-highlighter pre-parsed HAST cache. Lives in a ref so the same Map
+  // instance is shared across renders without becoming a React dep. The
+  // editable populates it via `useSourceEditing` (which reads it from
+  // `CodeHighlighterContext`), and `parseControlledCode` consults it on
+  // every render to skip the sync main-thread parse on exact source matches.
+  const [preParsedCache] = React.useState<Map<string, PreParsedCacheEntry>>(() => new Map());
+
   const { parsedControlledCode } = useControlledCodeParsing({
     code: controlled?.code,
     forceClient: props.forceClient,
     url: props.url,
+    preParsedCache,
   });
 
   // Determine the final overlaid code (controlled takes precedence)
@@ -987,14 +1001,17 @@ export function CodeHighlighterClient(props: CodeHighlighterClientProps) {
 
   const fallbackContext = React.useMemo(
     () =>
-      codeToFallbackProps(
-        variantName,
-        codeForFallback,
-        fileName,
-        props.fallbackUsesExtraFiles,
-        props.fallbackUsesAllVariants,
-      ),
+      activeCodeReady
+        ? undefined
+        : codeToFallbackProps(
+            variantName,
+            codeForFallback,
+            fileName,
+            props.fallbackUsesExtraFiles,
+            props.fallbackUsesAllVariants,
+          ),
     [
+      activeCodeReady,
       variantName,
       codeForFallback,
       fileName,
@@ -1013,6 +1030,7 @@ export function CodeHighlighterClient(props: CodeHighlighterClientProps) {
       availableTransforms: isControlled ? [] : availableTransforms,
       url: props.url,
       deferHighlight,
+      preParsedCache,
     }),
     [
       overlaidCode,
@@ -1026,6 +1044,7 @@ export function CodeHighlighterClient(props: CodeHighlighterClientProps) {
       availableTransforms,
       props.url,
       deferHighlight,
+      preParsedCache,
     ],
   );
 
diff --git a/packages/docs-infra/src/CodeHighlighter/CodeHighlighterContext.tsx b/packages/docs-infra/src/CodeHighlighter/CodeHighlighterContext.tsx
index d72e84f57..f8380f430 100644
--- a/packages/docs-infra/src/CodeHighlighter/CodeHighlighterContext.tsx
+++ b/packages/docs-infra/src/CodeHighlighter/CodeHighlighterContext.tsx
@@ -1,8 +1,20 @@
 'use client';
 import * as React from 'react';
-import { type Code, type ControlledCode } from './types';
+import { type Code, type ControlledCode, type HastRoot } from './types';
 import { type Selection } from '../CodeControllerContext';
 
+/**
+ * One cached pre-parsed file. Stored per-fileName: each new write replaces
+ * any previous entry for that file. The `source` string is the cache key —
+ * `parseControlledCode` only reuses `hast` when the controlled-code source
+ * is byte-identical, which guarantees the cached HAST matches the input
+ * that produced it.
+ */
+export interface PreParsedCacheEntry {
+  source: string;
+  hast: HastRoot;
+}
+
 export interface CodeHighlighterContextType {
   code?: Code;
   setCode?: React.Dispatch<React.SetStateAction<ControlledCode | undefined>>;
@@ -12,6 +24,15 @@ export interface CodeHighlighterContextType {
   availableTransforms?: string[];
   url?: string;
   deferHighlight?: boolean;
+  /**
+   * Per-file pre-parsed HAST cache. Populated by `useSourceEditing` when the
+   * editable supplies a worker-parsed result alongside a source change, and
+   * read by `parseControlledCode` to skip the (sync, main-thread) parse on
+   * exact source matches. Owned by `CodeHighlighterClient` via `useRef` so
+   * the same `Map` instance is shared across render cycles without being a
+   * React dep.
+   */
+  preParsedCache?: Map<string, PreParsedCacheEntry>;
 }
 
 export const CodeHighlighterContext = React.createContext<CodeHighlighterContextType | undefined>(
diff --git a/packages/docs-infra/src/CodeHighlighter/parseControlledCode.test.ts b/packages/docs-infra/src/CodeHighlighter/parseControlledCode.test.ts
index 9d8ffe6d7..5a4e15d7e 100644
--- a/packages/docs-infra/src/CodeHighlighter/parseControlledCode.test.ts
+++ b/packages/docs-infra/src/CodeHighlighter/parseControlledCode.test.ts
@@ -306,4 +306,102 @@ describe('parseControlledCode', () => {
       expect(mockParseSource).toHaveBeenCalledWith('console.log("with filename");', 'App.js');
     });
   });
+
+  describe('preParsedCache', () => {
+    it('reuses the cached HAST when fileName + source match exactly', () => {
+      const cachedHast = createMockHastRoot('cached');
+      const controlledCode: ControlledCode = {
+        Default: {
+          fileName: 'App.js',
+          url: '/demo',
+          source: 'console.log("hi");',
+        },
+      };
+      const cache = new Map([['App.js', { source: 'console.log("hi");', hast: cachedHast }]]);
+
+      const result = parseControlledCode(controlledCode, mockParseSource, cache);
+
+      expect(mockParseSource).not.toHaveBeenCalled();
+      expect((result.Default as any).source).toBe(cachedHast);
+      // Hit leaves the entry in place.
+      expect(cache.get('App.js')?.hast).toBe(cachedHast);
+    });
+
+    it('falls through to parseSource and evicts the entry on a source mismatch', () => {
+      const staleHast = createMockHastRoot('stale');
+      const controlledCode: ControlledCode = {
+        Default: {
+          fileName: 'App.js',
+          url: '/demo',
+          source: 'new source',
+        },
+      };
+      const cache = new Map([['App.js', { source: 'old source', hast: staleHast }]]);
+
+      const result = parseControlledCode(controlledCode, mockParseSource, cache);
+
+      expect(mockParseSource).toHaveBeenCalledWith('new source', 'App.js');
+      expect((result.Default as any).source).not.toBe(staleHast);
+      // Mismatch evicts so the cache cannot grow stale across edits.
+      expect(cache.has('App.js')).toBe(false);
+    });
+
+    it('does nothing special when the cache has no entry for the file', () => {
+      const controlledCode: ControlledCode = {
+        Default: {
+          fileName: 'App.js',
+          url: '/demo',
+          source: 'console.log("hi");',
+        },
+      };
+      const cache = new Map<string, { source: string; hast: Root }>();
+
+      parseControlledCode(controlledCode, mockParseSource, cache);
+
+      expect(mockParseSource).toHaveBeenCalledTimes(1);
+      expect(cache.size).toBe(0);
+    });
+
+    it('reuses cached HAST for entries in extraFiles', () => {
+      const mainHast = createMockHastRoot('main');
+      const extraHast = createMockHastRoot('extra');
+      const controlledCode: ControlledCode = {
+        Default: {
+          fileName: 'App.js',
+          url: '/demo',
+          source: 'main source',
+          extraFiles: {
+            'helper.js': { source: 'extra source' },
+          },
+        },
+      };
+      const cache = new Map([
+        ['App.js', { source: 'main source', hast: mainHast }],
+        ['helper.js', { source: 'extra source', hast: extraHast }],
+      ]);
+
+      const result = parseControlledCode(controlledCode, mockParseSource, cache);
+
+      expect(mockParseSource).not.toHaveBeenCalled();
+      expect((result.Default as any).source).toBe(mainHast);
+      expect((result.Default as any).extraFiles['helper.js'].source).toBe(extraHast);
+    });
+
+    it('behaves identically to the no-cache call when cache is omitted', () => {
+      const controlledCode: ControlledCode = {
+        Default: {
+          fileName: 'App.js',
+          url: '/demo',
+          source: 'console.log("hi");',
+        },
+      };
+
+      const withoutCache = parseControlledCode(controlledCode, mockParseSource);
+      vi.clearAllMocks();
+      const withEmptyCache = parseControlledCode(controlledCode, mockParseSource, new Map());
+
+      expect(withoutCache).toEqual(withEmptyCache);
+      expect(mockParseSource).toHaveBeenCalledTimes(1);
+    });
+  });
 });
diff --git a/packages/docs-infra/src/CodeHighlighter/parseControlledCode.ts b/packages/docs-infra/src/CodeHighlighter/parseControlledCode.ts
index fd3833d31..bb78de23f 100644
--- a/packages/docs-infra/src/CodeHighlighter/parseControlledCode.ts
+++ b/packages/docs-infra/src/CodeHighlighter/parseControlledCode.ts
@@ -1,13 +1,40 @@
-import type { Code, ControlledCode, ParseSource, VariantSource } from './types';
+import type { Code, ControlledCode, HastRoot, ParseSource, VariantSource } from './types';
+import type { PreParsedCacheEntry } from './CodeHighlighterContext';
 
 /**
  * Pure function to parse controlled code and convert it to regular Code format.
  * Handles the conversion from ControlledCode (string|null sources) to Code (HAST nodes).
+ *
+ * When `preParsedCache` is supplied, each file's source is first looked up in
+ * the cache. If the cached entry's source string matches byte-for-byte, the
+ * cached HAST is reused and `parseSource` is skipped for that file. On a
+ * mismatch the stale entry is evicted before re-parsing so the cache cannot
+ * grow stale across rapid edits.
  */
 export function parseControlledCode(
   controlledCode: ControlledCode,
   parseSource: ParseSource,
+  preParsedCache?: Map<string, PreParsedCacheEntry>,
 ): Code {
+  /**
+   * Try the cache for `fileName`/`source`. Returns the cached HAST on an
+   * exact match; evicts and returns `undefined` on a mismatch.
+   */
+  const tryCache = (fileName: string, source: string): HastRoot | undefined => {
+    if (!preParsedCache) {
+      return undefined;
+    }
+    const entry = preParsedCache.get(fileName);
+    if (!entry) {
+      return undefined;
+    }
+    if (entry.source === source) {
+      return entry.hast;
+    }
+    preParsedCache.delete(fileName);
+    return undefined;
+  };
+
   const parsed: Code = {};
 
   for (const [variant, variantCode] of Object.entries(controlledCode)) {
@@ -23,11 +50,16 @@ export function parseControlledCode(
       const sourceToProcess = variantCode.source === null ? '' : variantCode.source;
 
       if (typeof sourceToProcess === 'string' && variantCode.fileName) {
-        try {
-          mainSource = parseSource(sourceToProcess, variantCode.fileName);
-        } catch (error) {
-          // Keep original string if parsing fails
-          mainSource = sourceToProcess;
+        const cached = tryCache(variantCode.fileName, sourceToProcess);
+        if (cached) {
+          mainSource = cached;
+        } else {
+          try {
+            mainSource = parseSource(sourceToProcess, variantCode.fileName);
+          } catch (error) {
+            // Keep original string if parsing fails
+            mainSource = sourceToProcess;
+          }
         }
       } else if (typeof sourceToProcess === 'string' && !variantCode.fileName) {
         // Return a basic HAST root node with the source text for unsupported file types
@@ -57,17 +89,27 @@ export function parseControlledCode(
           const fileSourceToProcess = fileData.source === null ? '' : fileData.source;
 
           if (typeof fileSourceToProcess === 'string') {
-            // Parse string sources
-            try {
-              const parsedSource = parseSource(fileSourceToProcess, fileName);
-              parsedExtraFiles[fileName] = { source: parsedSource };
-            } catch (error) {
-              // Keep original if parsing fails
-              parsedExtraFiles[fileName] = { source: fileSourceToProcess };
+            const cached = tryCache(fileName, fileSourceToProcess);
+            if (cached) {
+              parsedExtraFiles[fileName] = { source: cached, comments: fileData.comments };
+            } else {
+              try {
+                const parsedSource = parseSource(fileSourceToProcess, fileName);
+                parsedExtraFiles[fileName] = { source: parsedSource, comments: fileData.comments };
+              } catch (error) {
+                // Keep original if parsing fails
+                parsedExtraFiles[fileName] = {
+                  source: fileSourceToProcess,
+                  comments: fileData.comments,
+                };
+              }
             }
           } else {
             // Keep other values as-is
-            parsedExtraFiles[fileName] = { source: fileSourceToProcess };
+            parsedExtraFiles[fileName] = {
+              source: fileSourceToProcess,
+              comments: fileData.comments,
+            };
           }
         }
 
@@ -80,6 +122,7 @@ export function parseControlledCode(
         source: mainSource,
         extraFiles,
         filesOrder: variantCode.filesOrder,
+        comments: variantCode.comments,
       };
     }
   }
diff --git a/packages/docs-infra/src/CodeHighlighter/types.ts b/packages/docs-infra/src/CodeHighlighter/types.ts
index a64364220..342e1d2b3 100644
--- a/packages/docs-infra/src/CodeHighlighter/types.ts
+++ b/packages/docs-infra/src/CodeHighlighter/types.ts
@@ -85,14 +85,31 @@ export type VariantCode = CodeMeta & {
 
 export type Code = { [key: string]: undefined | string | VariantCode }; // TODO: only preload should be able to pass highlighted code
 
+/**
+ * Tracks comments that were collapsed onto a line when their original lines
+ * were deleted. Keyed by the line they collapsed onto; each entry records
+ * the original offset from the edit line so the collapse can be reversed.
+ */
+export type CollapseMap = Record<number, Array<{ offset: number; comments: string[] }>>;
+
 export type ControlledVariantExtraFiles = {
-  [fileName: string]: { source: string | null };
+  [fileName: string]: {
+    source: string | null;
+    comments?: SourceComments;
+    collapseMap?: CollapseMap;
+    totalLines?: number;
+    emptyLines?: number[];
+  };
 };
 export type ControlledVariantCode = CodeMeta & {
   url?: string;
   source?: string | null;
   extraFiles?: ControlledVariantExtraFiles;
   filesOrder?: string[];
+  comments?: SourceComments;
+  collapseMap?: CollapseMap;
+  totalLines?: number;
+  emptyLines?: number[];
 };
 export type ControlledCode = { [key: string]: undefined | null | ControlledVariantCode };
 
diff --git a/packages/docs-infra/src/CodeProvider/CodeContext.tsx b/packages/docs-infra/src/CodeProvider/CodeContext.tsx
index 80e954e66..31d027512 100644
--- a/packages/docs-infra/src/CodeProvider/CodeContext.tsx
+++ b/packages/docs-infra/src/CodeProvider/CodeContext.tsx
@@ -15,6 +15,8 @@ import type {
   Externals,
   VariantCode,
 } from '../CodeHighlighter/types';
+import type { ParseSourceAsync } from './createParseSourceWorkerClient';
+import type { PreParsedCacheEntry } from '../CodeHighlighter/CodeHighlighterContext';
 
 // Type definitions for the heavy functions we're moving to context
 export type LoadFallbackCodeFn = (
@@ -36,6 +38,7 @@ export type ParseCodeFn = (code: Code, parseSource: ParseSource) => Code;
 export type ParseControlledCodeFn = (
   controlledCode: ControlledCode,
   parseSource: ParseSource,
+  preParsedCache?: Map<string, PreParsedCacheEntry>,
 ) => Code;
 
 export type ComputeHastDeltasFn = (parsedCode: Code, parseSource: ParseSource) => Promise<Code>;
@@ -54,6 +57,12 @@ export interface CodeContext {
   sourceParser?: Promise<ParseSource>;
   /** Sync parser available after initial load completes */
   parseSource?: ParseSource;
+  /**
+   * Worker-backed asynchronous parser used for non-blocking syntax
+   * highlighting during live editing. Available in browser environments
+   * after the worker has initialized.
+   */
+  parseSourceAsync?: ParseSourceAsync;
   /** Source transformers for code transformation (e.g., TypeScript to JavaScript) */
   sourceTransformers?: SourceTransformers;
   /** Source enhancers for modifying parsed HAST */
diff --git a/packages/docs-infra/src/CodeProvider/CodeProvider.tsx b/packages/docs-infra/src/CodeProvider/CodeProvider.tsx
index e6f261fe3..eceefc112 100644
--- a/packages/docs-infra/src/CodeProvider/CodeProvider.tsx
+++ b/packages/docs-infra/src/CodeProvider/CodeProvider.tsx
@@ -1,7 +1,6 @@
 'use client';
 
 import * as React from 'react';
-import { createStarryNight } from '@wooorm/starry-night';
 import { CodeContext } from './CodeContext';
 import type {
   LoadCodeMeta,
@@ -10,9 +9,9 @@ import type {
   ParseSource,
   SourceEnhancers,
 } from '../CodeHighlighter/types';
-import { extensionMap, grammars } from '../pipeline/parseSource/grammars';
-import { starryNightGutter } from '../pipeline/parseSource/addLineGutters';
-import { extendSyntaxTokens } from '../pipeline/parseSource/extendSyntaxTokens';
+import { enhanceCodeEmphasis } from '../pipeline/enhanceCodeEmphasis';
+import { createParseSource } from '../pipeline/parseSource/parseSource';
+import type { ParseSourceAsync, ParseSourceWorkerClient } from './createParseSourceWorkerClient';
 // Import the heavy functions
 import { loadCodeFallback } from '../pipeline/loadCodeVariant/loadCodeFallback';
 import { loadCodeVariant } from '../pipeline/loadCodeVariant/loadCodeVariant';
@@ -23,6 +22,8 @@ import {
   getAvailableTransforms,
 } from '../pipeline/loadCodeVariant/computeHastDeltas';
 
+const DEFAULT_SOURCE_ENHANCERS: SourceEnhancers = [enhanceCodeEmphasis];
+
 /**
  * Provides client-side functions for fetching source code and highlighting it.
  * Designed for cases where you need to render code blocks or demos based on
@@ -36,7 +37,7 @@ export function CodeProvider({
   loadCodeMeta,
   loadVariantMeta,
   loadSource,
-  sourceEnhancers,
+  sourceEnhancers = DEFAULT_SOURCE_ENHANCERS,
 }: {
   /** Child components that will have access to the code handling context */
   children: React.ReactNode;
@@ -49,6 +50,9 @@ export function CodeProvider({
   sourceEnhancers?: SourceEnhancers;
 }) {
   const [parseSource, setParseSource] = React.useState<ParseSource | undefined>(undefined);
+  const [parseSourceAsync, setParseSourceAsync] = React.useState<ParseSourceAsync | undefined>(
+    undefined,
+  );
 
   const sourceParser = React.useMemo(() => {
     // Only initialize Starry Night in the browser, not during SSR
@@ -58,33 +62,7 @@ export function CodeProvider({
       }) as ParseSource);
     }
 
-    return createStarryNight(grammars).then((starryNight) => {
-      const parseSourceFn: ParseSource = (source: string, fileName: string) => {
-        const fileType = fileName.slice(fileName.lastIndexOf('.'));
-        if (!extensionMap[fileType]) {
-          // Return a basic HAST root node with the source text for unsupported file types
-          return {
-            type: 'root',
-            children: [
-              {
-                type: 'text',
-                value: source,
-              },
-            ],
-          };
-        }
-
-        const grammarScope = extensionMap[fileType];
-        const highlighted = starryNight.highlight(source, grammarScope);
-        extendSyntaxTokens(highlighted, grammarScope);
-        const sourceLines = source.split(/\r?\n|\r/);
-        starryNightGutter(highlighted, sourceLines); // mutates the tree to add line gutters
-
-        return highlighted;
-      };
-
-      return parseSourceFn;
-    });
+    return createParseSource();
   }, []);
 
   React.useEffect(() => {
@@ -92,10 +70,77 @@ export function CodeProvider({
     sourceParser.then((parseSourceFn) => setParseSource(() => parseSourceFn));
   }, [sourceParser]);
 
+  // Worker for off-main-thread parsing during live editing. Lazily created
+  // once per provider, browser-only, and torn down on unmount. The worker
+  // client module is dynamically imported so the `new URL('./parseSourceWorker.ts',
+  // import.meta.url)` call (which bundlers resolve to a separate worker chunk)
+  // never runs in SSR bundles.
+  const workerRef = React.useRef<ParseSourceWorkerClient | null>(null);
+  React.useEffect(() => {
+    if (typeof window === 'undefined' || typeof Worker === 'undefined') {
+      return undefined;
+    }
+    let cancelled = false;
+    let client: ParseSourceWorkerClient | undefined;
+
+    Promise.all([
+      import('./createParseSourceWorkerClient'),
+      // Share the same (lazy) grammar chunk that `createParseSource()` uses,
+      // so the heavy TextMate JSON is fetched at most once per page load and
+      // then `postMessage`d into the worker.
+      import('../pipeline/parseSource/grammars'),
+    ])
+      .then(([{ createParseSourceWorkerClient }, { grammars }]) => {
+        if (cancelled) {
+          return;
+        }
+        // `createParseSourceWorkerClient()` throws synchronously on browsers
+        // that expose `Worker` but reject module workers (the typeof gate
+        // above can't detect that). Treat the failure as "no async parser
+        // available" so consumers transparently fall back to the synchronous
+        // highlighter instead of leaving an unhandled rejection on the page.
+        try {
+          client = createParseSourceWorkerClient();
+        } catch {
+          return;
+        }
+        workerRef.current = client;
+        client
+          .init(grammars)
+          .then(() => {
+            if (cancelled) {
+              return;
+            }
+            setParseSourceAsync(() => client!.parseSourceAsync);
+          })
+          .catch(() => {
+            // Worker-side init failure (e.g. `createStarryNight` rejected).
+            // Tear down so we don't leak the worker, and leave
+            // `parseSourceAsync` undefined so consumers fall back to sync.
+            if (workerRef.current === client) {
+              workerRef.current = null;
+            }
+            client?.terminate();
+            client = undefined;
+          });
+      })
+      .catch(() => {
+        // Dynamic-import failure (network error, missing chunk). Same
+        // fallback policy: stay on the main-thread highlighter.
+      });
+
+    return () => {
+      cancelled = true;
+      workerRef.current = null;
+      client?.terminate();
+    };
+  }, []);
+
   const context = React.useMemo(
     () => ({
       sourceParser,
       parseSource, // Sync version when available
+      parseSourceAsync, // Worker-backed async version when available
       loadSource,
       loadVariantMeta,
       loadCodeMeta,
@@ -108,7 +153,15 @@ export function CodeProvider({
       computeHastDeltas,
       getAvailableTransforms,
     }),
-    [sourceParser, parseSource, loadSource, loadVariantMeta, loadCodeMeta, sourceEnhancers],
+    [
+      sourceParser,
+      parseSource,
+      parseSourceAsync,
+      loadSource,
+      loadVariantMeta,
+      loadCodeMeta,
+      sourceEnhancers,
+    ],
   );
 
   return <CodeContext.Provider value={context}>{children}</CodeContext.Provider>;
diff --git a/packages/docs-infra/src/CodeProvider/createParseSourceWorkerClient.test.ts b/packages/docs-infra/src/CodeProvider/createParseSourceWorkerClient.test.ts
new file mode 100644
index 000000000..aa2f5556f
--- /dev/null
+++ b/packages/docs-infra/src/CodeProvider/createParseSourceWorkerClient.test.ts
@@ -0,0 +1,261 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import type { Root as HastRoot } from 'hast';
+import { createParseSourceWorkerClient } from './createParseSourceWorkerClient';
+
+/**
+ * In-process stand-in for a real `Worker`. The test drives it from the main
+ * thread by calling `instance.respond(...)` to simulate messages coming back
+ * from the worker.
+ */
+class FakeWorker {
+  static instances: FakeWorker[] = [];
+
+  posted: Array<unknown> = [];
+
+  terminated = false;
+
+  private listeners = new Set<(event: MessageEvent) => void>();
+
+  constructor() {
+    FakeWorker.instances.push(this);
+  }
+
+  postMessage(message: unknown): void {
+    this.posted.push(message);
+  }
+
+  addEventListener(_type: 'message', listener: (event: MessageEvent) => void): void {
+    this.listeners.add(listener);
+  }
+
+  removeEventListener(_type: 'message', listener: (event: MessageEvent) => void): void {
+    this.listeners.delete(listener);
+  }
+
+  terminate(): void {
+    this.terminated = true;
+  }
+
+  /** Simulate a message arriving from the worker. */
+  respond(data: unknown): void {
+    const event = { data } as MessageEvent;
+    for (const listener of [...this.listeners]) {
+      listener(event);
+    }
+  }
+}
+
+const sampleHast: HastRoot = { type: 'root', children: [] };
+
+describe('createParseSourceWorkerClient', () => {
+  let originalWorker: typeof Worker | undefined;
+
+  beforeEach(() => {
+    FakeWorker.instances = [];
+    originalWorker = globalThis.Worker;
+    (globalThis as { Worker: unknown }).Worker = FakeWorker;
+  });
+
+  afterEach(() => {
+    if (originalWorker) {
+      (globalThis as { Worker: unknown }).Worker = originalWorker;
+    } else {
+      delete (globalThis as { Worker?: unknown }).Worker;
+    }
+  });
+
+  it('throws when parseSourceAsync is called before init()', async () => {
+    const client = createParseSourceWorkerClient();
+    await expect(client.parseSourceAsync('a', 'a.ts')).rejects.toThrow(/before init\(\)/);
+    client.terminate();
+  });
+
+  it('posts the init payload and resolves init() on init-ack', async () => {
+    const client = createParseSourceWorkerClient();
+    const initPromise = client.init([]);
+    const worker = FakeWorker.instances[0];
+
+    expect(worker.posted).toEqual([{ type: 'init', grammars: [] }]);
+
+    worker.respond({ type: 'init-ack' });
+    await expect(initPromise).resolves.toBeUndefined();
+
+    client.terminate();
+  });
+
+  it('returns the same promise from repeated init() calls', () => {
+    const client = createParseSourceWorkerClient();
+    const a = client.init([]);
+    const b = client.init([]);
+    expect(a).toBe(b);
+    // Only one `init` message posted.
+    expect(FakeWorker.instances[0].posted).toHaveLength(1);
+    client.terminate();
+  });
+
+  it('rejects init() when the worker reports init-error', async () => {
+    const client = createParseSourceWorkerClient();
+    const initPromise = client.init([]);
+    const worker = FakeWorker.instances[0];
+
+    worker.respond({ type: 'init-error', error: 'grammar boom' });
+
+    await expect(initPromise).rejects.toThrow('grammar boom');
+    client.terminate();
+  });
+
+  it('parses a request and resolves with the returned HAST', async () => {
+    const client = createParseSourceWorkerClient();
+    const initPromise = client.init([]);
+    const worker = FakeWorker.instances[0];
+    worker.respond({ type: 'init-ack' });
+    await initPromise;
+
+    const parsePromise = client.parseSourceAsync('hello', 'a.ts', 'ts');
+    // `parseSourceAsync` awaits `initPromise` internally; flush microtasks
+    // so the parse `postMessage` has run before we inspect `worker.posted`.
+    await Promise.resolve();
+
+    // The init message was first; the parse message follows it.
+    const parseMessage = worker.posted[1] as { type: string; id: number };
+    expect(parseMessage.type).toBe('parse');
+    expect(parseMessage.id).toBe(1);
+
+    worker.respond({ type: 'parse', id: parseMessage.id, ok: true, hast: sampleHast });
+    await expect(parsePromise).resolves.toBe(sampleHast);
+
+    client.terminate();
+  });
+
+  it('rejects when the worker reports a parse error', async () => {
+    const client = createParseSourceWorkerClient();
+    const initPromise = client.init([]);
+    const worker = FakeWorker.instances[0];
+    worker.respond({ type: 'init-ack' });
+    await initPromise;
+
+    const parsePromise = client.parseSourceAsync('hello', 'a.ts');
+    await Promise.resolve();
+    const parseMessage = worker.posted[1] as { id: number };
+    worker.respond({ type: 'parse', id: parseMessage.id, ok: false, error: 'unknown grammar' });
+
+    await expect(parsePromise).rejects.toThrow('unknown grammar');
+    client.terminate();
+  });
+
+  it('demultiplexes concurrent requests by id', async () => {
+    const client = createParseSourceWorkerClient();
+    const initPromise = client.init([]);
+    const worker = FakeWorker.instances[0];
+    worker.respond({ type: 'init-ack' });
+    await initPromise;
+
+    const first = client.parseSourceAsync('a', 'a.ts');
+    const second = client.parseSourceAsync('b', 'b.ts');
+    await Promise.resolve();
+
+    const firstMessage = worker.posted[1] as { id: number };
+    const secondMessage = worker.posted[2] as { id: number };
+    expect(secondMessage.id).toBe(firstMessage.id + 1);
+
+    const otherHast: HastRoot = { type: 'root', children: [{ type: 'text', value: 'b' }] };
+
+    // Resolve out of order.
+    worker.respond({ type: 'parse', id: secondMessage.id, ok: true, hast: otherHast });
+    worker.respond({ type: 'parse', id: firstMessage.id, ok: true, hast: sampleHast });
+
+    await expect(first).resolves.toBe(sampleHast);
+    await expect(second).resolves.toBe(otherHast);
+
+    client.terminate();
+  });
+
+  it('rejects with signal.reason when the signal is already aborted', async () => {
+    const client = createParseSourceWorkerClient();
+    const initPromise = client.init([]);
+    const worker = FakeWorker.instances[0];
+    worker.respond({ type: 'init-ack' });
+    await initPromise;
+
+    const controller = new AbortController();
+    controller.abort(new Error('cancelled'));
+
+    await expect(
+      client.parseSourceAsync('a', 'a.ts', undefined, controller.signal),
+    ).rejects.toThrow('cancelled');
+
+    // No parse message was posted.
+    expect(worker.posted.filter((m) => (m as { type: string }).type === 'parse')).toHaveLength(0);
+
+    client.terminate();
+  });
+
+  it('rejects in-flight requests when the signal aborts and ignores the late response', async () => {
+    const client = createParseSourceWorkerClient();
+    const initPromise = client.init([]);
+    const worker = FakeWorker.instances[0];
+    worker.respond({ type: 'init-ack' });
+    await initPromise;
+
+    const controller = new AbortController();
+    const parsePromise = client.parseSourceAsync('a', 'a.ts', undefined, controller.signal);
+    await Promise.resolve();
+    const parseMessage = worker.posted[1] as { id: number };
+
+    controller.abort(new Error('superseded'));
+    await expect(parsePromise).rejects.toThrow('superseded');
+
+    // A late response for the aborted id should not throw or affect anything.
+    expect(() =>
+      worker.respond({ type: 'parse', id: parseMessage.id, ok: true, hast: sampleHast }),
+    ).not.toThrow();
+
+    client.terminate();
+  });
+
+  it('terminate() rejects all pending requests and terminates the worker', async () => {
+    const client = createParseSourceWorkerClient();
+    const initPromise = client.init([]);
+    const worker = FakeWorker.instances[0];
+    worker.respond({ type: 'init-ack' });
+    await initPromise;
+
+    const first = client.parseSourceAsync('a', 'a.ts');
+    const second = client.parseSourceAsync('b', 'b.ts');
+    await Promise.resolve();
+
+    // Catch attached eagerly to avoid unhandled-rejection warnings.
+    const firstCaught = first.catch((error: Error) => error.message);
+    const secondCaught = second.catch((error: Error) => error.message);
+
+    client.terminate();
+
+    expect(worker.terminated).toBe(true);
+    await expect(firstCaught).resolves.toBe('Worker terminated');
+    await expect(secondCaught).resolves.toBe('Worker terminated');
+  });
+
+  it('removes the abort listener after a successful response', async () => {
+    const client = createParseSourceWorkerClient();
+    const initPromise = client.init([]);
+    const worker = FakeWorker.instances[0];
+    worker.respond({ type: 'init-ack' });
+    await initPromise;
+
+    const controller = new AbortController();
+    const removeSpy = vi.spyOn(controller.signal, 'removeEventListener');
+
+    const parsePromise = client.parseSourceAsync('a', 'a.ts', undefined, controller.signal);
+    await Promise.resolve();
+    const parseMessage = worker.posted[1] as { id: number };
+    worker.respond({ type: 'parse', id: parseMessage.id, ok: true, hast: sampleHast });
+    await parsePromise;
+
+    expect(removeSpy).toHaveBeenCalledWith('abort', expect.any(Function));
+
+    client.terminate();
+  });
+});
diff --git a/packages/docs-infra/src/CodeProvider/createParseSourceWorkerClient.ts b/packages/docs-infra/src/CodeProvider/createParseSourceWorkerClient.ts
new file mode 100644
index 000000000..37fce3e3a
--- /dev/null
+++ b/packages/docs-infra/src/CodeProvider/createParseSourceWorkerClient.ts
@@ -0,0 +1,176 @@
+import type { Root as HastRoot } from 'hast';
+import type { createStarryNight } from '@wooorm/starry-night';
+
+type Grammar = Parameters<typeof createStarryNight>[0][number];
+
+/**
+ * Asynchronously parses source code into a HAST tree, typically off the main
+ * thread (e.g. via a Web Worker). Used during live typing so the UI thread
+ * stays responsive. Accepts an `AbortSignal` so a stale request can be
+ * cancelled when newer keystrokes arrive.
+ *
+ * Internal: not exported as part of the public API. Consumers wire up async
+ * parsing by passing a worker URL to `CodeProvider`; the produced client
+ * exposes a `parseSourceAsync` callable directly without referring to this
+ * type.
+ */
+export type ParseSourceAsync = (
+  source: string,
+  fileName: string,
+  language?: string,
+  signal?: AbortSignal,
+) => Promise<HastRoot>;
+
+type ParseResponse =
+  | { type: 'parse'; id: number; ok: true; hast: HastRoot }
+  | { type: 'parse'; id: number; ok: false; error: string }
+  | { type: 'init-ack' }
+  | { type: 'init-error'; error: string };
+
+type Pending = {
+  resolve: (hast: HastRoot) => void;
+  reject: (reason: unknown) => void;
+  signal: AbortSignal | undefined;
+  onAbort: (() => void) | undefined;
+};
+
+export interface ParseSourceWorkerClient {
+  /**
+   * Send the (heavy) grammar payload to the worker. Idempotent: subsequent
+   * calls return the same promise. Must be awaited (or composed via
+   * `parseSourceAsync`, which awaits it implicitly) before parse requests
+   * will be processed.
+   */
+  init(grammars: Grammar[]): Promise<void>;
+  /**
+   * Async syntax-highlighter that runs inside the worker. Returns the same
+   * HAST shape as the sync `parseSource`. If `signal` aborts before the
+   * worker responds, the in-flight request is dropped and the promise
+   * rejects with `signal.reason`.
+   */
+  parseSourceAsync: ParseSourceAsync;
+  terminate(): void;
+}
+
+/**
+ * Create a worker-backed `parseSourceAsync` implementation. The caller owns
+ * the lifecycle and must invoke `terminate()` on unmount.
+ *
+ * Each client owns exactly one underlying `Worker`. Concurrent in-flight
+ * requests are demuxed by a monotonically increasing `id`.
+ */
+export function createParseSourceWorkerClient(): ParseSourceWorkerClient {
+  // Module workers are required (the worker uses `import` statements). On
+  // browsers that expose `Worker` but reject `{ type: 'module' }` (older
+  // Safari, some embedded webviews), the constructor throws synchronously.
+  // Surface that as a tagged error so callers can fall back cleanly to the
+  // main-thread highlighter instead of crashing the provider tree.
+  let worker: Worker;
+  try {
+    worker = new Worker(new URL('./parseSourceWorker', import.meta.url), {
+      type: 'module',
+    });
+  } catch (cause) {
+    throw new Error('Module workers are not supported in this environment', { cause });
+  }
+
+  const pending = new Map<number, Pending>();
+  let nextId = 1;
+  let initPromise: Promise<void> | null = null;
+
+  worker.addEventListener('message', (event: MessageEvent<ParseResponse>) => {
+    const data = event.data;
+    if (data.type === 'init-ack' || data.type === 'init-error') {
+      // `init()` listens for these directly via its own one-shot listener.
+      return;
+    }
+    if (data.type === 'parse') {
+      const entry = pending.get(data.id);
+      if (!entry) {
+        // Aborted before response arrived — drop silently.
+        return;
+      }
+      pending.delete(data.id);
+      if (entry.signal && entry.onAbort) {
+        entry.signal.removeEventListener('abort', entry.onAbort);
+      }
+      if (data.ok) {
+        entry.resolve(data.hast);
+      } else {
+        entry.reject(new Error(data.error));
+      }
+    }
+  });
+
+  function init(grammars: Grammar[]): Promise<void> {
+    if (initPromise) {
+      return initPromise;
+    }
+    initPromise = new Promise<void>((resolve, reject) => {
+      const onMessage = (event: MessageEvent<ParseResponse>) => {
+        if (event.data.type === 'init-ack') {
+          worker.removeEventListener('message', onMessage);
+          resolve();
+        } else if (event.data.type === 'init-error') {
+          worker.removeEventListener('message', onMessage);
+          reject(new Error(event.data.error));
+        }
+      };
+      worker.addEventListener('message', onMessage);
+      worker.postMessage({ type: 'init', grammars });
+    });
+    return initPromise;
+  }
+
+  const parseSourceAsync: ParseSourceAsync = async (source, fileName, language, signal) => {
+    if (!initPromise) {
+      throw new Error('parseSourceAsync called before init(). Call client.init(grammars) first.');
+    }
+    if (signal?.aborted) {
+      throw signal.reason;
+    }
+    await initPromise;
+    if (signal?.aborted) {
+      throw signal.reason;
+    }
+
+    const id = nextId;
+    nextId += 1;
+
+    return new Promise<HastRoot>((resolve, reject) => {
+      const onAbort = signal
+        ? () => {
+            const entry = pending.get(id);
+            if (!entry) {
+              return;
+            }
+            pending.delete(id);
+            if (entry.signal && entry.onAbort) {
+              entry.signal.removeEventListener('abort', entry.onAbort);
+            }
+            reject(signal.reason);
+          }
+        : undefined;
+
+      pending.set(id, { resolve, reject, signal, onAbort });
+      if (signal && onAbort) {
+        signal.addEventListener('abort', onAbort, { once: true });
+      }
+
+      worker.postMessage({ type: 'parse', id, source, fileName, language });
+    });
+  };
+
+  function terminate(): void {
+    worker.terminate();
+    for (const entry of pending.values()) {
+      if (entry.signal && entry.onAbort) {
+        entry.signal.removeEventListener('abort', entry.onAbort);
+      }
+      entry.reject(new Error('Worker terminated'));
+    }
+    pending.clear();
+  }
+
+  return { init, parseSourceAsync, terminate };
+}
diff --git a/packages/docs-infra/src/CodeProvider/parseSourceWorker.ts b/packages/docs-infra/src/CodeProvider/parseSourceWorker.ts
new file mode 100644
index 000000000..848b256d1
--- /dev/null
+++ b/packages/docs-infra/src/CodeProvider/parseSourceWorker.ts
@@ -0,0 +1,110 @@
+/**
+ * Worker entry point for off-main-thread syntax highlighting.
+ *
+ * Lifecycle:
+ *  1. Main thread posts `{ type: 'init', grammars }` once. The worker calls
+ *     `createStarryNight(grammars)` and primes the singleton used by
+ *     `parseSource`. Posts `{ type: 'init-ack' }` when ready.
+ *  2. For each parse request, main thread posts
+ *     `{ type: 'parse', id, source, fileName, language? }`. The worker runs
+ *     the same sync `parseSource` body that the main thread uses (so the HAST
+ *     output is byte-identical) and posts `{ type: 'parse', id, ok, hast? , error? }`.
+ *
+ * Parse requests that arrive before init completes are queued and drained on
+ * `init-ack`. The worker does not import `./grammars` statically — the heavy
+ * grammar JSON payload travels across the boundary exactly once via the init
+ * message so that the (lazy) main-thread grammar chunk is the single shared
+ * source of truth.
+ */
+
+import { createStarryNight } from '@wooorm/starry-night';
+import { parseSource } from '../pipeline/parseSource/parseSource';
+
+type Grammar = Parameters<typeof createStarryNight>[0][number];
+
+const STARRY_NIGHT_KEY = '__docs_infra_starry_night_instance__';
+
+type ParseRequest = {
+  type: 'parse';
+  id: number;
+  source: string;
+  fileName: string;
+  language?: string;
+};
+
+type InitRequest = {
+  type: 'init';
+  grammars: Grammar[];
+};
+
+type IncomingMessage = InitRequest | ParseRequest;
+
+// `self` in a dedicated worker exposes `postMessage`/`addEventListener` on the
+// global scope, but the default `tsconfig` `lib` here doesn't include the
+// `webworker` lib so we cast once via a typed alias instead of per-call.
+const workerScope = self as unknown as Worker;
+
+const queue: ParseRequest[] = [];
+let initialized = false;
+let initInFlight: Promise<void> | null = null;
+
+async function init(grammars: Grammar[]): Promise<void> {
+  if (initInFlight) {
+    return initInFlight;
+  }
+  initInFlight = (async () => {
+    try {
+      const starryNight = await createStarryNight(grammars);
+      (globalThis as { [key: string]: unknown })[STARRY_NIGHT_KEY] = starryNight;
+      initialized = true;
+      // Drain queued parse requests in arrival order.
+      for (const req of queue.splice(0)) {
+        runParse(req);
+      }
+      workerScope.postMessage({ type: 'init-ack' });
+    } catch (error) {
+      // Surface init failures to the client so `parseSourceAsync` can fail
+      // fast instead of hanging on an unresolved init promise.
+      const message = error instanceof Error ? error.message : String(error);
+      workerScope.postMessage({ type: 'init-error', error: message });
+      throw error;
+    }
+  })();
+  return initInFlight;
+}
+
+function runParse(req: ParseRequest): void {
+  try {
+    const hast = parseSource(req.source, req.fileName, req.language);
+    workerScope.postMessage({
+      type: 'parse',
+      id: req.id,
+      ok: true,
+      hast,
+    });
+  } catch (error) {
+    workerScope.postMessage({
+      type: 'parse',
+      id: req.id,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+workerScope.addEventListener('message', (event: MessageEvent<IncomingMessage>) => {
+  const data = event.data;
+  if (data.type === 'init') {
+    // The promise rejection is observed by the client via `init-error`; the
+    // local `.catch` here just prevents an unhandled rejection in the worker.
+    init(data.grammars).catch(() => {});
+    return;
+  }
+  if (data.type === 'parse') {
+    if (initialized) {
+      runParse(data);
+    } else {
+      queue.push(data);
+    }
+  }
+});
diff --git a/packages/docs-infra/src/abstractCreateDemoClient/abstractCreateDemoClient.tsx b/packages/docs-infra/src/abstractCreateDemoClient/abstractCreateDemoClient.tsx
index b2ce4efc4..d3ee0d7a4 100644
--- a/packages/docs-infra/src/abstractCreateDemoClient/abstractCreateDemoClient.tsx
+++ b/packages/docs-infra/src/abstractCreateDemoClient/abstractCreateDemoClient.tsx
@@ -2,18 +2,27 @@ import * as React from 'react';
 import type { Externals } from '../CodeHighlighter/types';
 import { CodeExternalsContext } from '../CodeExternalsContext';
 
-export type CreateDemoClientMeta = {
+type DefaultController = React.ComponentType<{ children: React.ReactNode }>;
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+type ControllerProps<C extends DefaultController> = Simplify<
+  Omit<React.ComponentProps<C>, 'children'>
+>;
+
+export type CreateDemoClientMeta<C extends DefaultController> = {
   name?: string;
   slug?: string;
   displayName?: string;
   variantType?: string;
   skipPrecompute?: boolean;
   precompute?: { externals?: Externals; [key: string]: any };
+  controllerProps?: ControllerProps<C>;
   [key: string]: any;
 };
 
-type AbstractCreateDemoClientOptions = {
-  live?: boolean;
+type AbstractCreateDemoClientOptions<C extends DefaultController> = {
+  DemoController: C;
   [key: string]: any;
 };
 
@@ -24,21 +33,29 @@ type AbstractCreateDemoClientOptions = {
  * @param options Configuration options for the demo client factory
  * @returns A function that creates demo client providers
  */
-export function abstractCreateDemoClient(
-  options: AbstractCreateDemoClientOptions,
+export function abstractCreateDemoClient<C extends DefaultController>(
+  options: AbstractCreateDemoClientOptions<C>,
   url: string,
-  meta?: CreateDemoClientMeta,
+  meta?: CreateDemoClientMeta<C>,
 ): React.ComponentType<{ children: React.ReactNode }> {
   // Extract externals from precomputed data
   const externals = meta?.precompute?.externals || {};
   const context = { externals };
+  const { DemoController } = options;
+  const controllerProps = meta?.controllerProps;
 
-  // Create a provider component that makes externals available to children
   function ClientProvider({ children }: { children: React.ReactNode }) {
-    // In a real implementation, this would provide the externals via context
-    // For now, just render children - the externals are already injected as imports
+    if (controllerProps != null) {
+      return (
+        <CodeExternalsContext.Provider value={context}>
+          {React.createElement(DemoController, Object.assign({}, controllerProps, { children }))}
+        </CodeExternalsContext.Provider>
+      );
+    }
     return (
-      <CodeExternalsContext.Provider value={context}>{children}</CodeExternalsContext.Provider>
+      <CodeExternalsContext.Provider value={context}>
+        {React.createElement(DemoController, Object.assign({}, { children }))}
+      </CodeExternalsContext.Provider>
     );
   }
 
@@ -46,24 +63,25 @@ export function abstractCreateDemoClient(
     ClientProvider.displayName = `ClientProvider(${meta?.name || 'Demo'})`;
   }
 
-  // Attach metadata to the provider for debugging/inspection
-  (ClientProvider as any).clientMeta = {
-    url,
-    options,
-    meta,
-    externals,
-  };
-
-  return ClientProvider;
+  return Object.assign(ClientProvider, {
+    clientMeta: {
+      url,
+      options,
+      meta,
+      externals,
+    },
+  });
 }
 
-export function createDemoClientFactory(options: AbstractCreateDemoClientOptions) {
+export function createDemoClientFactory<C extends DefaultController>(
+  options: AbstractCreateDemoClientOptions<C>,
+) {
   /**
-   * Creates a demo client provider for live editing with precomputed externals.
+   * Creates a demo client provider with precomputed externals.
    * @param url Depends on `import.meta.url` to determine the source file location.
    * @param meta Additional meta and configuration for the demo client.
    */
-  const createDemoClient = (url: string, meta?: CreateDemoClientMeta) => {
+  const createDemoClient = (url: string, meta?: CreateDemoClientMeta<C>) => {
     return abstractCreateDemoClient(options, url, meta);
   };
 
diff --git a/packages/docs-infra/src/cli/index.ts b/packages/docs-infra/src/cli/index.ts
index faa179a49..16e3f2684 100644
--- a/packages/docs-infra/src/cli/index.ts
+++ b/packages/docs-infra/src/cli/index.ts
@@ -2,6 +2,7 @@ import { createRequire } from 'node:module';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import runValidate from './runValidate';
+import runBrowser from './runBrowser';
 
 function getVersion() {
   return createRequire(import.meta.url)('../../package.json').version;
@@ -11,6 +12,7 @@ yargs()
   .scriptName('docs-infra')
   .usage('$0 <command> [args]')
   .command(runValidate)
+  .command(runBrowser)
   .demandCommand(1, 'You need at least one command before moving on')
   .strict()
   .help()
diff --git a/packages/docs-infra/src/cli/runBrowser.ts b/packages/docs-infra/src/cli/runBrowser.ts
new file mode 100644
index 000000000..e3257fa01
--- /dev/null
+++ b/packages/docs-infra/src/cli/runBrowser.ts
@@ -0,0 +1,224 @@
+/* eslint-disable no-console */
+import type { CommandModule } from 'yargs';
+import { $, which } from 'zx';
+import { existsSync } from 'node:fs';
+
+const CONTAINER_NAME = 'docs-infra-playwright';
+
+type Args = {
+  port: number;
+  script: string;
+  'playwright-version': string;
+  headed: boolean;
+  workspace: boolean;
+  _: (string | number)[];
+  '--'?: string[];
+};
+
+/**
+ * Resolves the container engine command.
+ * Inside a toolbx/distrobox container, use `flatpak-spawn` to reach the host.
+ */
+function resolveEngine(): string[] {
+  if (process.env.CONTAINER_ENGINE) {
+    return process.env.CONTAINER_ENGINE.split(/\s+/);
+  }
+
+  if (which.sync('podman', { nothrow: true })) {
+    return ['podman'];
+  }
+
+  if (which.sync('docker', { nothrow: true })) {
+    return ['docker'];
+  }
+
+  // Inside a toolbx/distrobox container
+  if (existsSync('/run/.containerenv') && which.sync('flatpak-spawn', { nothrow: true })) {
+    return ['flatpak-spawn', '--host', 'podman'];
+  }
+
+  throw new Error(
+    'A container engine (podman or docker) is required but not found.\n' +
+      'Install podman or docker, or set CONTAINER_ENGINE.',
+  );
+}
+
+async function engine(...args: string[]) {
+  const cmd = resolveEngine();
+  return $`${cmd} ${args}`;
+}
+
+async function engineQuiet(...args: string[]) {
+  const cmd = resolveEngine();
+  return $({ nothrow: true })`${cmd} ${args}`.quiet();
+}
+
+async function stopContainer() {
+  console.log('Stopping Playwright server…');
+  await engineQuiet('stop', CONTAINER_NAME);
+}
+
+async function waitForServer(port: number, maxAttempts = 30): Promise<boolean> {
+  for (let i = 1; i <= maxAttempts; i += 1) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      await fetch(`http://localhost:${port}/`);
+      return true;
+    } catch {
+      if (i === maxAttempts) {
+        return false;
+      }
+      // eslint-disable-next-line no-await-in-loop
+      await new Promise((resolve) => {
+        setTimeout(resolve, 1000);
+      });
+    }
+  }
+  return false;
+}
+
+async function handler(argv: Args) {
+  const port = argv.port;
+  // --headed may arrive as a yargs option or inside the passthrough args
+  // (pnpm run inserts -- before forwarding extra args).
+  const headed = argv.headed || (argv['--'] ?? []).includes('--headed');
+
+  // Always clean up on exit.
+  process.once('SIGINT', async () => {
+    await stopContainer();
+    process.exit(130);
+  });
+  process.once('SIGTERM', async () => {
+    await stopContainer();
+    process.exit(143);
+  });
+
+  try {
+    // Remove stale container if present.
+    await engineQuiet('rm', '-f', CONTAINER_NAME);
+
+    const image = `mcr.microsoft.com/playwright:v${argv['playwright-version']}-noble`;
+
+    // Pull the image first so progress is visible to the user.
+    const cmd = resolveEngine();
+    await $({ stdio: 'inherit' })`${cmd} pull ${image}`;
+
+    const containerArgs = [
+      'run',
+      '--rm',
+      '-d',
+      '--name',
+      CONTAINER_NAME,
+      '--network=host',
+      '--shm-size=1g',
+    ];
+
+    // Forward the host X11 display so headed browsers can render.
+    if (headed) {
+      const display = process.env.DISPLAY;
+      if (!display) {
+        console.error('--headed requires a display server but $DISPLAY is not set.');
+        process.exitCode = 1;
+        return;
+      }
+      containerArgs.push(
+        '-e',
+        `DISPLAY=${display}`,
+        '-v',
+        '/tmp/.X11-unix:/tmp/.X11-unix',
+        // Disable SELinux labels so the container can access the X11 socket.
+        '--security-opt',
+        'label=disable',
+      );
+      // Forward X11 auth so the container can authenticate with the X server.
+      const xauthority = process.env.XAUTHORITY || `${process.env.HOME}/.Xauthority`;
+      containerArgs.push(
+        '-e',
+        'XAUTHORITY=/tmp/.Xauthority',
+        '-v',
+        `${xauthority}:/tmp/.Xauthority:ro`,
+      );
+    }
+
+    containerArgs.push(
+      image,
+      'npx',
+      '--yes',
+      'playwright',
+      'run-server',
+      '--port',
+      String(port),
+      '--host',
+      '0.0.0.0',
+    );
+
+    console.log(`Starting Playwright server on port ${port}…`);
+    await engine(...containerArgs);
+
+    // Wait for the server to be ready.
+    const ready = await waitForServer(port);
+
+    if (!ready) {
+      const logs = await engineQuiet('logs', CONTAINER_NAME);
+      console.error('Playwright server failed to start. Container logs:');
+      console.error(logs.stdout);
+      process.exitCode = 1;
+      return;
+    }
+
+    // Run Vitest against the remote Playwright server.
+    console.log('Running browser tests…');
+    // Forward positional args and anything after "--" to the test command.
+    // --headed is consumed here (not forwarded) since vitest doesn't know it.
+    const positional = argv._.slice(1).map(String);
+    const passthrough = argv['--'] ?? [];
+    const extra = [...positional, ...passthrough.filter((a) => a !== '--headed')];
+    if (headed) {
+      extra.push('--browser.headless=false');
+    }
+    const env = { ...process.env, PLAYWRIGHT_SERVER: `ws://localhost:${port}` };
+    const pnpmArgs = argv.workspace ? ['-w'] : [];
+    await $({ env, stdio: 'inherit' })`pnpm ${pnpmArgs} run ${argv.script} ${extra}`;
+  } finally {
+    await stopContainer();
+  }
+}
+
+const runBrowser: CommandModule<{}, Args> = {
+  command: 'browser [args..]',
+  describe: 'Runs browser tests using a containerized Playwright server',
+  builder: (yargs) => {
+    return yargs
+      .option('port', {
+        type: 'number',
+        description: 'Port for the Playwright WebSocket server',
+        default: 3333,
+      })
+      .option('script', {
+        type: 'string',
+        description: 'Root package.json script to run',
+        demandOption: true,
+      })
+      .option('playwright-version', {
+        type: 'string',
+        description: 'Playwright version for the container image',
+        demandOption: true,
+      })
+      .option('headed', {
+        type: 'boolean',
+        description: 'Run browsers in headed mode (requires X11)',
+        default: false,
+      })
+      .option('workspace', {
+        alias: 'w',
+        type: 'boolean',
+        description: 'Run the script from the workspace root (passes -w to pnpm)',
+        default: false,
+      })
+      .parserConfiguration({ 'populate--': true })
+      .strict(false);
+  },
+  handler,
+};
+
+export default runBrowser;
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
index 66125448f..1776474a2 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
@@ -12,6 +12,10 @@ import type { HastRoot, ParseSource, SourceEnhancer } from '../../CodeHighlighte
 
 /**
  * Test helper to parse code, enhance it, and return HTML via rehype-stringify.
+ *
+ * Uses the bare `enhanceCodeEmphasis` export by default, which reflects the
+ * out-of-the-box behavior (no `data-frame-indent` emitted). Tests that need
+ * different options should pass an explicit `enhancer`.
  */
 async function testEmphasis(
   code: string,
@@ -78,7 +82,7 @@ describe('enhanceCodeEmphasis', () => {
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Button</span>() {</span>
         <span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="2"><span class="line" data-ln="3">    &#x3C;<span class="pl-ent">button</span> <span class="pl-e di-ak">className</span><span class="pl-k di-ae">=</span><span class="pl-s di-av"><span class="pl-pds">"</span>primary<span class="pl-pds">"</span></span>>Click me&#x3C;/<span class="pl-ent">button</span>></span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted"><span class="line" data-ln="3">    &#x3C;<span class="pl-ent">button</span> <span class="pl-e di-ak">className</span><span class="pl-k di-ae">=</span><span class="pl-s di-av"><span class="pl-pds">"</span>primary<span class="pl-pds">"</span></span>>Click me&#x3C;/<span class="pl-ent">button</span>></span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="4">  );</span>
         <span class="line" data-ln="5">}</span></span>"
       `);
@@ -96,9 +100,9 @@ const e = 5; // @highlight`,
 
       expect(result).toMatchInlineSnapshot(
         `
-        "<span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1"><span class="pl-k">const</span> <span class="pl-c1">a</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">1</span>;</span>
+        "<span class="frame" data-lined="" data-frame-type="highlighted"><span class="line" data-ln="1"><span class="pl-k">const</span> <span class="pl-c1">a</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">1</span>;</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="2"><span class="pl-k">const</span> <span class="pl-c1">b</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">2</span>;</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted-unfocused" data-frame-indent="0"><span class="line" data-ln="3"><span class="pl-k">const</span> <span class="pl-c1">c</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">3</span>;</span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted-unfocused"><span class="line" data-ln="3"><span class="pl-k">const</span> <span class="pl-c1">c</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">3</span>;</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="4"><span class="pl-k">const</span> <span class="pl-c1">d</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">4</span>;</span>
         </span>"
       `,
@@ -116,7 +120,7 @@ const e = 5; // @highlight`,
 
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="1" data-frame-description="We track state"><span class="line" data-ln="2">  <span class="pl-k">const</span> [<span class="pl-c1">count</span>, <span class="pl-c1">setCount</span>] <span class="pl-k">=</span> <span class="pl-en">useState</span>(<span class="pl-c1 di-num">0</span>);</span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-description="We track state"><span class="line" data-ln="2">  <span class="pl-k">const</span> [<span class="pl-c1">count</span>, <span class="pl-c1">setCount</span>] <span class="pl-k">=</span> <span class="pl-en">useState</span>(<span class="pl-c1 di-num">0</span>);</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="3">  <span class="pl-k">return</span> &#x3C;<span class="pl-ent">div</span>><span class="pl-pse">{</span><span class="pl-smi">count</span><span class="pl-pse">}</span>&#x3C;/<span class="pl-ent">div</span>>;</span>
         <span class="line" data-ln="4">}</span></span>"
       `);
@@ -133,7 +137,7 @@ const e = 5; // @highlight`,
 
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="1"><span class="line" data-ln="2" data-hl="strong" data-hl-description="We must provide the URL" data-hl-position="single">  <span class="pl-k">const</span> <span class="pl-c1">url</span> <span class="pl-k">=</span> <span class="pl-en">getUrl</span>();</span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted"><span class="line" data-ln="2" data-hl="strong" data-hl-description="We must provide the URL" data-hl-position="single">  <span class="pl-k">const</span> <span class="pl-c1">url</span> <span class="pl-k">=</span> <span class="pl-en">getUrl</span>();</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="3">  <span class="pl-k">return</span> &#x3C;<span class="pl-ent">a</span> <span class="pl-e di-ak">href</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">url</span><span class="pl-pse">}</span>>Link&#x3C;/<span class="pl-ent">a</span>>;</span>
         <span class="line" data-ln="4">}</span></span>"
       `);
@@ -159,7 +163,7 @@ const e = 5; // @highlight`,
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
         <span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="2"><span class="line" data-ln="3">    &#x3C;<span class="pl-ent">div</span>></span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted"><span class="line" data-ln="3">    &#x3C;<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span>>Heading 1&#x3C;/<span class="pl-ent">h1</span>></span>
         <span class="line" data-ln="5">      &#x3C;<span class="pl-ent">p</span>>Some content&#x3C;/<span class="pl-ent">p</span>></span>
         <span class="line" data-ln="6">    &#x3C;/<span class="pl-ent">div</span>></span>
@@ -199,7 +203,7 @@ const e = 5; // @highlight`,
       expect(result).toMatchInlineSnapshot(
         `
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">function</span> <span class="pl-en">test</span>() {</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="1"><span class="line" data-ln="2">  <span class="pl-k">return</span> <span class="pl-c1 di-n">null</span>;</span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted"><span class="line" data-ln="2">  <span class="pl-k">return</span> <span class="pl-c1 di-n">null</span>;</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="3">}</span></span>"
       `,
       );
@@ -222,7 +226,7 @@ const e = 5; // @highlight`,
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
         <span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="2" data-frame-description="We add a heading with an h1"><span class="line" data-ln="3">    &#x3C;<span class="pl-ent">div</span>></span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-description="We add a heading with an h1"><span class="line" data-ln="3">    &#x3C;<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span>>Heading 1&#x3C;/<span class="pl-ent">h1</span>></span>
         <span class="line" data-ln="5">    &#x3C;/<span class="pl-ent">div</span>></span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="6">  );</span>
@@ -248,7 +252,7 @@ const e = 5; // @highlight`,
 
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="1"><span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted"><span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
         <span class="line" data-ln="3" data-hl="strong" data-hl-position="start">    &#x3C;<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="4" data-hl="strong">      &#x3C;<span class="pl-ent">h1</span>>Heading 1&#x3C;/<span class="pl-ent">h1</span>></span>
         <span class="line" data-ln="5" data-hl="strong" data-hl-position="end">    &#x3C;/<span class="pl-ent">div</span>></span>
@@ -272,7 +276,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(`
-        "<span class="frame" data-lined="" data-frame-type="focus" data-frame-indent="3"><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
+        "<span class="frame" data-lined="" data-frame-type="focus"><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
         <span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
         <span class="line" data-ln="3">    &#x3C;<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span>><mark>Heading 1</mark>&#x3C;/<span class="pl-ent">h1</span>></span>
@@ -297,7 +301,7 @@ const e = 5; // @highlight`,
       // Both "primary" and "Heading 1" should be wrapped in data-hl spans
       // Comments are stripped, so only code matches appear
       expect(result).toMatchInlineSnapshot(`
-        "<span class="frame" data-lined="" data-frame-type="focus" data-frame-indent="3"><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
+        "<span class="frame" data-lined="" data-frame-type="focus"><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
         <span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
         <span class="line" data-ln="3">    &#x3C;<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span> <span class="pl-e di-ak">className</span><span class="pl-k di-ae">=</span><span class="pl-s di-av"><span class="pl-pds">"</span><mark>primary</mark><span class="pl-pds">"</span></span>><mark>Heading 1</mark>&#x3C;/<span class="pl-ent">h1</span>></span>
@@ -328,7 +332,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(
-        `"<span class="frame" data-lined="" data-frame-type="focus" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1 di-jsx">AlertDialog.Trigger</span> <mark><span class="pl-e di-ak">handle</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">demoAlertDialog</span><span class="pl-pse">}</span></mark>>Open&#x3C;/<span class="pl-c1 di-jsx">AlertDialog.Trigger</span>></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-type="focus"><span class="line" data-ln="1">&#x3C;<span class="pl-c1 di-jsx">AlertDialog.Trigger</span> <mark><span class="pl-e di-ak">handle</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">demoAlertDialog</span><span class="pl-pse">}</span></mark>>Open&#x3C;/<span class="pl-c1 di-jsx">AlertDialog.Trigger</span>></span></span>"`,
       );
     });
 
@@ -340,7 +344,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(
-        `"<span class="frame" data-lined="" data-frame-type="focus" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1 di-jsx">Button</span> <span class="pl-e di-ak">render</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span>&#x3C;<span class="pl-ent">div</span> /><span class="pl-pse">}</span> <mark><span class="pl-e">nativeButton</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-c1 di-bool">false</span><span class="pl-pse">}</span></mark>></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-type="focus"><span class="line" data-ln="1">&#x3C;<span class="pl-c1 di-jsx">Button</span> <span class="pl-e di-ak">render</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span>&#x3C;<span class="pl-ent">div</span> /><span class="pl-pse">}</span> <mark><span class="pl-e">nativeButton</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-c1 di-bool">false</span><span class="pl-pse">}</span></mark>></span></span>"`,
       );
     });
 
@@ -469,7 +473,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(
-        `"<span class="frame" data-lined="" data-frame-type="focus" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1 di-jsx">Input</span> <mark class="pl-e di-ak">value</mark><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">a</span><span class="pl-pse">}</span> /> &#x3C;<span class="pl-c1 di-jsx">Input</span> <mark class="pl-e di-ak">value</mark><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">b</span><span class="pl-pse">}</span> /> <span class="pl-c">// @highlight-text "<mark>value</mark>"</span></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-type="focus"><span class="line" data-ln="1">&#x3C;<span class="pl-c1 di-jsx">Input</span> <mark class="pl-e di-ak">value</mark><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">a</span><span class="pl-pse">}</span> /> &#x3C;<span class="pl-c1 di-jsx">Input</span> <mark class="pl-e di-ak">value</mark><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">b</span><span class="pl-pse">}</span> /> <span class="pl-c">// @highlight-text "<mark>value</mark>"</span></span></span>"`,
       );
     });
 
@@ -496,7 +500,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(
-        `"<span class="frame" data-lined="" data-frame-type="focus" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1 di-jsx">Input</span> <mark class="pl-e di-ak">value</mark><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><mark class="pl-smi">value</mark><span class="pl-pse">}</span> /></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-type="focus"><span class="line" data-ln="1">&#x3C;<span class="pl-c1 di-jsx">Input</span> <mark class="pl-e di-ak">value</mark><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><mark class="pl-smi">value</mark><span class="pl-pse">}</span> /></span></span>"`,
       );
     });
   });
@@ -598,9 +602,9 @@ const another = 99; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(`
-        "<span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1"><span class="pl-k">const</span> <span class="pl-c1">value</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">42</span>;</span>
+        "<span class="frame" data-lined="" data-frame-type="highlighted"><span class="line" data-ln="1"><span class="pl-k">const</span> <span class="pl-c1">value</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">42</span>;</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="2"><span class="pl-k">function</span> <span class="pl-en">example</span>() {</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted-unfocused" data-frame-indent="1"><span class="line" data-ln="3">  <span class="pl-k">const</span> <span class="pl-c1">x</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">1</span>;</span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted-unfocused"><span class="line" data-ln="3">  <span class="pl-k">const</span> <span class="pl-c1">x</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">1</span>;</span>
         <span class="line" data-ln="4">  <span class="pl-k">const</span> <span class="pl-c1">y</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">2</span>;</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="5">  <span class="pl-k">return</span> <span class="pl-smi">x</span> <span class="pl-k">+</span> <span class="pl-smi">y</span>;</span>
         <span class="line" data-ln="6">}</span>
@@ -955,7 +959,7 @@ const b = 2;`,
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
         <span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
         <span class="line" data-ln="3">    &#x3C;<span class="pl-ent">div</span>></span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span>>Heading 1&#x3C;/<span class="pl-ent">h1</span>></span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted"><span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span>>Heading 1&#x3C;/<span class="pl-ent">h1</span>></span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="5">      &#x3C;<span class="pl-ent">p</span>>Content&#x3C;/<span class="pl-ent">p</span>></span>
         <span class="line" data-ln="6">    &#x3C;/<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="7">  );</span>
@@ -983,11 +987,11 @@ const b = 2;`,
 
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Dashboard</span>() {</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="1" data-frame-description="We track state"><span class="line" data-ln="2">  <span class="pl-k">const</span> [<span class="pl-c1">data</span>, <span class="pl-c1">setData</span>] <span class="pl-k">=</span> <span class="pl-en">useState</span>([]);</span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-description="We track state"><span class="line" data-ln="2">  <span class="pl-k">const</span> [<span class="pl-c1">data</span>, <span class="pl-c1">setData</span>] <span class="pl-k">=</span> <span class="pl-en">useState</span>([]);</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="3">  <span class="pl-k">return</span> (</span>
         <span class="line" data-ln="4">    &#x3C;<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="5">      &#x3C;<span class="pl-c1 di-jsx">Header</span> /></span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted-unfocused" data-frame-indent="3" data-frame-description="We render the main content"><span class="line" data-ln="6">      &#x3C;<span class="pl-c1 di-jsx">Chart</span> <span class="pl-e di-ak">data</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">data</span><span class="pl-pse">}</span> /></span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted-unfocused" data-frame-description="We render the main content"><span class="line" data-ln="6">      &#x3C;<span class="pl-c1 di-jsx">Chart</span> <span class="pl-e di-ak">data</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">data</span><span class="pl-pse">}</span> /></span>
         <span class="line" data-ln="7">      &#x3C;<span class="pl-c1 di-jsx">Table</span> <span class="pl-e di-ak">data</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">data</span><span class="pl-pse">}</span> /></span>
         <span class="line" data-ln="8">      &#x3C;<span class="pl-c1 di-jsx">Footer</span> /></span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="9">    &#x3C;/<span class="pl-ent">div</span>></span>
@@ -1027,7 +1031,7 @@ const b = 2;`,
         }
       }
 
-      // Parse the code WITH comments still present, then enhance
+      // Parse the code WITH comments still present, then enhance.
       const root = await parseSourceFn(code, fileName);
       const enhanced = enhanceCodeEmphasis(root, comments, fileName) as HastRoot;
 
@@ -1143,7 +1147,7 @@ const z = 3;`,
       );
 
       expect(result).toMatchInlineSnapshot(`
-        "<span class="frame" data-lined="" data-frame-type="focus" data-frame-indent="3"><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
+        "<span class="frame" data-lined="" data-frame-type="focus"><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
         <span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
         <span class="line" data-ln="3">    &#x3C;<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span> <span class="pl-e di-ak">className</span><span class="pl-k di-ae">=</span><span class="pl-s di-av"><span class="pl-pds">"</span><mark>primary</mark><span class="pl-pds">"</span></span>><mark>Heading 1</mark>&#x3C;/<span class="pl-ent">h1</span>> <span class="pl-pse">{</span><span class="pl-c">/* @highlight-text "<mark>primary</mark>" "<mark>Heading 1</mark>" */</span><span class="pl-pse">}</span></span>
@@ -1274,6 +1278,7 @@ const e = 5;`,
     it('should support @focus on @highlight-start', async () => {
       const enhancer = createEnhanceCodeEmphasis({
         paddingFrameMaxSize: 1,
+        emitFrameIndent: true,
       });
 
       const result = await testEmphasis(
@@ -1337,10 +1342,25 @@ const d = 4;`,
   return null;
 }`,
         parseSource,
+        'test.tsx',
+        createEnhanceCodeEmphasis({ emitFrameIndent: true }),
       );
 
       // Lines 2-3 are highlighted with 4 spaces indent, indent level = 4/2 = 2
       expect(result).toMatch(/data-frame-type="highlighted" data-frame-indent="2"/);
     });
+
+    it('should not emit data-frame-indent by default', async () => {
+      const result = await testEmphasis(
+        `function test() {
+    const a = 1; // @highlight
+  return null;
+}`,
+        parseSource,
+      );
+
+      expect(result).toContain('data-frame-type="highlighted"');
+      expect(result).not.toContain('data-frame-indent');
+    });
   });
 });
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
index 312fb137b..4dd03b75a 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
@@ -1569,8 +1569,13 @@ export function createEnhanceCodeEmphasis(
       effectiveOptions,
     );
 
-    // Step 5: Calculate indent levels per region (uses collected elements, no tree traversal)
-    const regionIndentLevels = calculateRegionIndentLevels(highlightedElements, emphasizedLines);
+    // Step 5: Calculate indent levels per region (uses collected elements, no tree traversal).
+    // Skipped when `emitFrameIndent` is off (the default) so we don't pay the
+    // cost or pollute the HAST with `data-frame-indent` attributes that no
+    // consumer reads.
+    const regionIndentLevels = effectiveOptions.emitFrameIndent
+      ? calculateRegionIndentLevels(highlightedElements, emphasizedLines)
+      : new Map<number, number>();
 
     // Step 6: Calculate frame ranges (pure math, no tree traversal)
     // Filter out text-only lines that don't need their own frames.
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
index 1f080d8ae..197ef82b2 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
@@ -105,6 +105,15 @@ export interface EnhanceCodeEmphasisOptions {
    * allowed — only boundary-straddling matches are rejected.
    */
   strictHighlightText?: boolean;
+  /**
+   * When `true`, emits a `data-frame-indent` attribute on highlighted/focus
+   * region frames indicating the shared leading indent level. Consumers can
+   * use this to visually shift collapsible regions horizontally when
+   * surrounding context lines are hidden. Off by default since most demos
+   * don't need it and it bloats the rendered HTML.
+   * @default false
+   */
+  emitFrameIndent?: boolean;
 }
 
 /** Default max number of lines kept in focus when not explicitly configured. */
diff --git a/packages/docs-infra/src/pipeline/parseSource/grammarMaps.ts b/packages/docs-infra/src/pipeline/parseSource/grammarMaps.ts
new file mode 100644
index 000000000..462927c5e
--- /dev/null
+++ b/packages/docs-infra/src/pipeline/parseSource/grammarMaps.ts
@@ -0,0 +1,53 @@
+/**
+ * Light-weight grammar metadata maps. These can be statically imported without
+ * pulling in the heavy TextMate grammar JSON payloads (which live in
+ * `./grammars.ts` and should be loaded via dynamic `import('./grammars')` so
+ * the bundler can code-split them into their own chunk).
+ */
+
+export const extensionMap: Record<string, string> = {
+  '.js': 'source.js',
+  '.ts': 'source.ts',
+  '.jsx': 'source.tsx',
+  '.tsx': 'source.tsx',
+  '.json': 'source.json',
+  '.md': 'text.md',
+  '.mdx': 'source.mdx',
+  '.html': 'text.html.basic',
+  '.css': 'source.css',
+  '.sh': 'source.shell',
+  '.yaml': 'source.yaml',
+};
+
+/**
+ * Maps simplified language names back to grammar scope names.
+ * Used when `language` prop is provided instead of fileName.
+ */
+export const languageToGrammarMap: Record<string, string> = {
+  js: 'source.js',
+  javascript: 'source.js',
+  ts: 'source.ts',
+  typescript: 'source.ts',
+  jsx: 'source.tsx',
+  tsx: 'source.tsx',
+  json: 'source.json',
+  md: 'text.md',
+  markdown: 'text.md',
+  mdx: 'source.mdx',
+  html: 'text.html.basic',
+  css: 'source.css',
+  sh: 'source.shell',
+  shell: 'source.shell',
+  bash: 'source.shell',
+  yaml: 'source.yaml',
+  yml: 'source.yaml',
+};
+
+/**
+ * Gets the grammar scope from a language name.
+ * @param language - The language name (e.g., 'tsx', 'css', 'typescript')
+ * @returns The grammar scope or undefined if not recognized
+ */
+export function getGrammarFromLanguage(language: string): string | undefined {
+  return languageToGrammarMap[language.toLowerCase()];
+}
diff --git a/packages/docs-infra/src/pipeline/parseSource/grammars.ts b/packages/docs-infra/src/pipeline/parseSource/grammars.ts
index 4e533b7d6..84ded80ed 100644
--- a/packages/docs-infra/src/pipeline/parseSource/grammars.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/grammars.ts
@@ -1,3 +1,11 @@
+/**
+ * Heavy TextMate grammar payloads. Importing this module pulls in hundreds of
+ * KB of JSON. Prefer `await import('./grammars')` so bundlers can code-split
+ * it into its own chunk.
+ *
+ * Lightweight extension/language maps live in `./grammarMaps.ts`.
+ */
+
 import sourceJs from '@wooorm/starry-night/source.js';
 import sourceTs from '@wooorm/starry-night/source.ts';
 import sourceTsx from '@wooorm/starry-night/source.tsx';
@@ -21,50 +29,3 @@ export const grammars = [
   sourceShell,
   sourceYaml,
 ];
-
-export const extensionMap: Record<string, string> = {
-  '.js': 'source.js',
-  '.ts': 'source.ts',
-  '.jsx': 'source.tsx',
-  '.tsx': 'source.tsx',
-  '.json': 'source.json',
-  '.md': 'text.md',
-  '.mdx': 'source.mdx',
-  '.html': 'text.html.basic',
-  '.css': 'source.css',
-  '.sh': 'source.shell',
-  '.yaml': 'source.yaml',
-};
-
-/**
- * Maps simplified language names back to grammar scope names.
- * Used when `language` prop is provided instead of fileName.
- */
-export const languageToGrammarMap: Record<string, string> = {
-  js: 'source.js',
-  javascript: 'source.js',
-  ts: 'source.ts',
-  typescript: 'source.ts',
-  jsx: 'source.tsx',
-  tsx: 'source.tsx',
-  json: 'source.json',
-  md: 'text.md',
-  markdown: 'text.md',
-  mdx: 'source.mdx',
-  html: 'text.html.basic',
-  css: 'source.css',
-  sh: 'source.shell',
-  shell: 'source.shell',
-  bash: 'source.shell',
-  yaml: 'source.yaml',
-  yml: 'source.yaml',
-};
-
-/**
- * Gets the grammar scope from a language name.
- * @param language - The language name (e.g., 'tsx', 'css', 'typescript')
- * @returns The grammar scope or undefined if not recognized
- */
-export function getGrammarFromLanguage(language: string): string | undefined {
-  return languageToGrammarMap[language.toLowerCase()];
-}
diff --git a/packages/docs-infra/src/pipeline/parseSource/index.ts b/packages/docs-infra/src/pipeline/parseSource/index.ts
index 15642e84d..cd238322f 100644
--- a/packages/docs-infra/src/pipeline/parseSource/index.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/index.ts
@@ -1,2 +1,2 @@
 export * from './parseSource';
-export { getGrammarFromLanguage, languageToGrammarMap, extensionMap } from './grammars';
+export { getGrammarFromLanguage, languageToGrammarMap, extensionMap } from './grammarMaps';
diff --git a/packages/docs-infra/src/pipeline/parseSource/parseSource.ts b/packages/docs-infra/src/pipeline/parseSource/parseSource.ts
index f3cd91cce..5fd1e6cbf 100644
--- a/packages/docs-infra/src/pipeline/parseSource/parseSource.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/parseSource.ts
@@ -1,6 +1,6 @@
 import { createStarryNight } from '@wooorm/starry-night';
 import type { ParseSource } from '../../CodeHighlighter/types';
-import { grammars, extensionMap, getGrammarFromLanguage } from './grammars';
+import { extensionMap, getGrammarFromLanguage } from './grammarMaps';
 import { starryNightGutter } from './addLineGutters';
 import { extendSyntaxTokens } from './extendSyntaxTokens';
 
@@ -68,10 +68,15 @@ export const parseSource: ParseSource = (source, fileName, language) => {
  * This only needs to be called once per application. The Starry Night instance
  * is stored globally for reuse across calls.
  *
+ * The grammar definitions are loaded via dynamic `import('./grammars')` so the
+ * (heavy) TextMate JSON payload is split into its own bundler chunk and only
+ * fetched when syntax highlighting is actually needed.
+ *
  * @returns A Promise that resolves to the initialized `parseSource` function
  */
 export const createParseSource = async (): Promise<ParseSource> => {
   if (!(globalThis as any)[STARRY_NIGHT_KEY]) {
+    const { grammars } = await import('./grammars');
     (globalThis as any)[STARRY_NIGHT_KEY] = await createStarryNight(grammars);
   }
 
diff --git a/packages/docs-infra/src/pipeline/transformHtmlCodeInline/transformHtmlCodeInline.ts b/packages/docs-infra/src/pipeline/transformHtmlCodeInline/transformHtmlCodeInline.ts
index 9dc5a1db5..2bf1b035f 100644
--- a/packages/docs-infra/src/pipeline/transformHtmlCodeInline/transformHtmlCodeInline.ts
+++ b/packages/docs-infra/src/pipeline/transformHtmlCodeInline/transformHtmlCodeInline.ts
@@ -1,7 +1,8 @@
 import { createStarryNight } from '@wooorm/starry-night';
 import type { Root as HastRoot, Element } from 'hast';
 import { visit } from 'unist-util-visit';
-import { grammars, extensionMap } from '../parseSource/grammars';
+import { grammars } from '../parseSource/grammars';
+import { extensionMap } from '../parseSource/grammarMaps';
 import { extendSyntaxTokens } from '../parseSource/extendSyntaxTokens';
 import { getHastTextContent } from '../hastUtils';
 import { removePrefixFromHighlightedNodes } from './removePrefixFromHighlightedNodes';
diff --git a/packages/docs-infra/src/useCode/Pre.browser.tsx b/packages/docs-infra/src/useCode/Pre.browser.tsx
new file mode 100644
index 000000000..f33e17e99
--- /dev/null
+++ b/packages/docs-infra/src/useCode/Pre.browser.tsx
@@ -0,0 +1,182 @@
+import * as React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import { userEvent } from 'vitest/browser';
+import { beforeAll, describe, expect, it } from 'vitest';
+import type { HastRoot, ParseSource, SourceComments } from '../CodeHighlighter/types';
+import { createParseSource } from '../pipeline/parseSource';
+import { enhanceCodeEmphasis } from '../pipeline/enhanceCodeEmphasis';
+import { Pre } from './Pre';
+
+const FILE_NAME = 'CheckboxBasic.tsx';
+
+const INITIAL_SOURCE = [
+  "import * as React from 'react';",
+  "import { Checkbox } from '@/components/Checkbox';",
+  '',
+  'export default function CheckboxBasic() {',
+  '  return (',
+  '    <div>',
+  '      <Checkbox defaultChecked />',
+  "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>",
+  '    </div>',
+  '  );',
+  '}',
+].join('\n');
+
+const HIGHLIGHT_COMMENTS: SourceComments = {
+  7: ['@highlight-start'],
+  8: ['@highlight-end'],
+};
+
+let parseSource: ParseSource;
+
+beforeAll(async () => {
+  parseSource = await createParseSource();
+});
+
+function createHighlightedSource(source: string): HastRoot {
+  const root = parseSource(source, FILE_NAME);
+  return enhanceCodeEmphasis(root, HIGHLIGHT_COMMENTS, FILE_NAME) as HastRoot;
+}
+
+function placeCaret(element: HTMLElement, offset: number) {
+  element.focus();
+  const selection = window.getSelection()!;
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+  let current = 0;
+  let node = walker.nextNode();
+
+  while (node) {
+    const length = node.textContent?.length ?? 0;
+    if (current + length >= offset) {
+      const range = document.createRange();
+      range.setStart(node, offset - current);
+      range.collapse(true);
+      selection.removeAllRanges();
+      selection.addRange(range);
+      return;
+    }
+
+    current += length;
+    node = walker.nextNode();
+  }
+}
+
+function EditablePreview() {
+  const [source, setSource] = React.useState(INITIAL_SOURCE);
+  const highlightedSource = React.useMemo(() => createHighlightedSource(source), [source]);
+
+  return (
+    <Pre
+      fileName={FILE_NAME}
+      language="tsx"
+      setSource={(nextSource) => setSource(nextSource)}
+      shouldHighlight
+    >
+      {highlightedSource}
+    </Pre>
+  );
+}
+
+describe('Pre - browser', () => {
+  it('keeps the </p> line and following </div> line separate after typing and rerender', async () => {
+    render(<EditablePreview />);
+    const pre = screen.getByText('Type Whatever You Want Below', { exact: false }).closest('pre');
+
+    expect(pre).not.toBeNull();
+
+    const lines = INITIAL_SOURCE.split('\n');
+    let offset = 0;
+    for (let i = 0; i < 7; i += 1) {
+      offset += lines[i].length + 1;
+    }
+    offset += lines[7].length;
+
+    placeCaret(pre!, offset);
+    await userEvent.keyboard('x');
+
+    await waitFor(() => {
+      const currentPre = screen
+        .getByText('Type Whatever You Want Below', { exact: false })
+        .closest('pre');
+      const highlightedLine = currentPre?.querySelector('[data-ln="8"]');
+      const nextLine = currentPre?.querySelector('[data-ln="9"]');
+
+      expect(highlightedLine).not.toBeNull();
+      expect(nextLine).not.toBeNull();
+      expect((highlightedLine as HTMLElement).textContent).toContain('</p>x');
+      expect((highlightedLine as HTMLElement).textContent).not.toContain('</div>');
+      expect((nextLine as HTMLElement).textContent).toBe('    </div>');
+    });
+  });
+
+  it('keeps lines separate when typing two characters after </p> (Firefox repro)', async () => {
+    const { container } = render(<EditablePreview />);
+    const pre = container.querySelector('pre')!;
+
+    expect(pre).not.toBeNull();
+
+    const lines = INITIAL_SOURCE.split('\n');
+    let offset = 0;
+    for (let i = 0; i < 7; i += 1) {
+      offset += lines[i].length + 1;
+    }
+    offset += lines[7].length;
+
+    placeCaret(pre!, offset);
+
+    // Type two characters with overlapping keydowns. The key events fire as:
+    // a-down, b-down, a-up, b-up — which means the second keydown arrives
+    // before React has rerendered from the first edit. Without correct
+    // pendingContent tracking, Firefox merges the </p> line into the
+    // following </div> line during the second keystroke (line 8 ends up as
+    // "...</p>ab    </div>" and line 9 shifts up to "  );").
+    await userEvent.keyboard('{a>}{b>}{/a}{/b}');
+
+    await waitFor(() => {
+      const currentPre = container.querySelector('pre')!;
+      const highlightedLine = currentPre.querySelector('[data-ln="8"]');
+      const nextLine = currentPre.querySelector('[data-ln="9"]');
+
+      expect(highlightedLine).not.toBeNull();
+      expect(nextLine).not.toBeNull();
+      expect((highlightedLine as HTMLElement).textContent).toContain('</p>ab');
+      expect((highlightedLine as HTMLElement).textContent).not.toContain('</div>');
+      expect((nextLine as HTMLElement).textContent).toBe('    </div>');
+    });
+  });
+
+  it('does not collapse lines when deleting and re-typing the > in <div>', async () => {
+    const { container } = render(<EditablePreview />);
+    const pre = container.querySelector('pre')!;
+    expect(pre).not.toBeNull();
+
+    // Place caret at the end of line 6: "    <div>"
+    const lines = INITIAL_SOURCE.split('\n');
+    let offset = 0;
+    for (let i = 0; i < 5; i += 1) {
+      offset += lines[i].length + 1;
+    }
+    offset += lines[5].length; // end of "    <div>"
+
+    placeCaret(pre!, offset);
+
+    // Delete the '>' and immediately re-type it without waiting for re-render
+    await userEvent.keyboard('{Backspace}>');
+
+    // Verify lines are not collapsed after the final re-render
+    await waitFor(() => {
+      const currentPre = container.querySelector('pre')!;
+      const line6 = currentPre.querySelector('[data-ln="6"]');
+      const line7 = currentPre.querySelector('[data-ln="7"]');
+      const line9 = currentPre.querySelector('[data-ln="9"]');
+
+      expect(line6).not.toBeNull();
+      expect(line7).not.toBeNull();
+      expect(line9).not.toBeNull();
+      expect((line6 as HTMLElement).textContent).toContain('<div>');
+      expect((line6 as HTMLElement).textContent).not.toContain('<Checkbox');
+      expect((line9 as HTMLElement).textContent).toContain('</div>');
+    });
+  });
+});
diff --git a/packages/docs-infra/src/useCode/Pre.test.tsx b/packages/docs-infra/src/useCode/Pre.test.tsx
new file mode 100644
index 000000000..761043cd1
--- /dev/null
+++ b/packages/docs-infra/src/useCode/Pre.test.tsx
@@ -0,0 +1,179 @@
+/**
+ * @vitest-environment jsdom
+ */
+import * as React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import { beforeAll, describe, expect, it } from 'vitest';
+import type { HastRoot, ParseSource, SourceComments } from '../CodeHighlighter/types';
+import { createParseSource } from '../pipeline/parseSource';
+import { enhanceCodeEmphasis } from '../pipeline/enhanceCodeEmphasis';
+import { Pre } from './Pre';
+
+const FILE_NAME = 'CheckboxBasic.tsx';
+
+const INITIAL_SOURCE = [
+  "import * as React from 'react';",
+  "import { Checkbox } from '@/components/Checkbox';",
+  '',
+  'export default function CheckboxBasic() {',
+  '  return (',
+  '    <div>',
+  '      <Checkbox defaultChecked />',
+  "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>",
+  '    </div>',
+  '  );',
+  '}',
+].join('\n');
+
+const HIGHLIGHT_COMMENTS: SourceComments = {
+  7: ['@highlight-start'],
+  8: ['@highlight-end'],
+};
+
+let parseSource: ParseSource;
+
+beforeAll(async () => {
+  class MockIntersectionObserver {
+    private readonly callback: IntersectionObserverCallback;
+
+    constructor(callback: IntersectionObserverCallback) {
+      this.callback = callback;
+    }
+
+    observe(target: Element) {
+      this.callback(
+        [
+          {
+            target,
+            isIntersecting: true,
+            intersectionRatio: 1,
+            boundingClientRect: target.getBoundingClientRect(),
+            intersectionRect: target.getBoundingClientRect(),
+            rootBounds: null,
+            time: 0,
+          } as IntersectionObserverEntry,
+        ],
+        this as unknown as IntersectionObserver,
+      );
+    }
+
+    unobserve() {}
+
+    disconnect() {}
+
+    takeRecords(): IntersectionObserverEntry[] {
+      return [];
+    }
+  }
+
+  globalThis.IntersectionObserver =
+    MockIntersectionObserver as unknown as typeof IntersectionObserver;
+  parseSource = await createParseSource();
+});
+
+function createHighlightedSource(source: string): HastRoot {
+  const root = parseSource(source, FILE_NAME);
+  return enhanceCodeEmphasis(root, HIGHLIGHT_COMMENTS, FILE_NAME) as HastRoot;
+}
+
+function placeCaret(element: HTMLElement, offset: number) {
+  element.focus();
+  const selection = window.getSelection()!;
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+  let current = 0;
+  let node = walker.nextNode();
+
+  while (node) {
+    const length = node.textContent?.length ?? 0;
+    if (current + length >= offset) {
+      const range = document.createRange();
+      range.setStart(node, offset - current);
+      range.collapse(true);
+      selection.removeAllRanges();
+      selection.addRange(range);
+      return;
+    }
+
+    current += length;
+    node = walker.nextNode();
+  }
+}
+
+function insertPlaintextCharacter(element: HTMLElement, key: string) {
+  element.dispatchEvent(
+    new KeyboardEvent('keydown', {
+      key,
+      code: `Key${key.toUpperCase()}`,
+      bubbles: true,
+      cancelable: true,
+    }),
+  );
+
+  const selection = window.getSelection()!;
+  const range = selection.getRangeAt(0);
+  range.deleteContents();
+  const textNode = document.createTextNode(key);
+  range.insertNode(textNode);
+  range.setStartAfter(textNode);
+  range.collapse(true);
+  selection.removeAllRanges();
+  selection.addRange(range);
+
+  element.dispatchEvent(
+    new KeyboardEvent('keyup', {
+      key,
+      code: `Key${key.toUpperCase()}`,
+      bubbles: true,
+      cancelable: true,
+    }),
+  );
+}
+
+function EditablePreview() {
+  const [source, setSource] = React.useState(INITIAL_SOURCE);
+  const highlightedSource = React.useMemo(() => createHighlightedSource(source), [source]);
+
+  return (
+    <Pre
+      fileName={FILE_NAME}
+      language="tsx"
+      setSource={(nextSource) => setSource(nextSource)}
+      shouldHighlight
+    >
+      {highlightedSource}
+    </Pre>
+  );
+}
+
+describe('Pre', () => {
+  it('keeps the </p> line and following </div> line separate after rerender', async () => {
+    render(<EditablePreview />);
+    const pre = screen.getByText('Type Whatever You Want Below', { exact: false }).closest('pre');
+
+    expect(pre).not.toBeNull();
+
+    const lines = INITIAL_SOURCE.split('\n');
+    let offset = 0;
+    for (let i = 0; i < 7; i += 1) {
+      offset += lines[i].length + 1;
+    }
+    offset += lines[7].length;
+
+    placeCaret(pre!, offset);
+    insertPlaintextCharacter(pre!, 'x');
+
+    await waitFor(() => {
+      const currentPre = screen
+        .getByText('Type Whatever You Want Below', { exact: false })
+        .closest('pre');
+      const highlightedLine = currentPre?.querySelector('[data-ln="8"]');
+      const nextLine = currentPre?.querySelector('[data-ln="9"]');
+
+      expect(highlightedLine).not.toBeNull();
+      expect(nextLine).not.toBeNull();
+      expect((highlightedLine as HTMLElement).textContent).toContain('</p>x');
+      expect((highlightedLine as HTMLElement).textContent).not.toContain('</div>');
+      expect((nextLine as HTMLElement).textContent).toBe('    </div>');
+    });
+  });
+});
diff --git a/packages/docs-infra/src/useCode/Pre.tsx b/packages/docs-infra/src/useCode/Pre.tsx
index c7e36308f..919ba0787 100644
--- a/packages/docs-infra/src/useCode/Pre.tsx
+++ b/packages/docs-infra/src/useCode/Pre.tsx
@@ -3,7 +3,10 @@
 import * as React from 'react';
 import { toText } from 'hast-util-to-text';
 import { type ElementContent } from 'hast';
+import { useEditable, type Position } from './useEditable';
+import type { SetSource } from './useSourceEditing';
 import type { HastRoot, VariantSource } from '../CodeHighlighter/types';
+import { useCodeContext } from '../CodeProvider/CodeContext';
 import { hastToJsx, decompressHast } from '../pipeline/hastUtils';
 
 const hastChildrenCache = new WeakMap<ElementContent[], React.ReactNode>();
@@ -46,6 +49,169 @@ function getInitialVisibleFrames(hast: HastRoot | null): { [key: number]: boolea
   return visibleFrames;
 }
 
+/**
+ * Bounds describing the visible region of a collapsible code block in its
+ * collapsed state. Used to constrain caret movement in `useEditable` and to
+ * trigger expansion when the user navigates past the boundaries.
+ */
+type CollapsedBounds = {
+  /**
+   * Smallest column the visible region exposes on indented lines (derived
+   * from the minimum `data-frame-indent` across collapsed-visible region
+   * frames). `undefined` when no visible region frame is indented.
+   */
+  minColumn: number | undefined;
+  /** First row of the visible region. */
+  minRow: number;
+  /** Last row of the visible region. */
+  maxRow: number;
+};
+
+/**
+ * Counts newlines in a hast subtree and reports whether the tree's text
+ * content ends with a newline. Walks text nodes directly instead of
+ * materializing the subtree into a string — avoids the O(N) allocation
+ * `hast-util-to-text` performs per call, which adds up across hundreds of
+ * frames in large code blocks.
+ *
+ * Returns `[newlineCount, endsWithNewline]`. `endsWithNewline` is `false`
+ * for an empty subtree (matches the previous `text.endsWith('\n')` check
+ * on an empty string).
+ */
+function countFrameNewlines(node: ElementContent | HastRoot): [number, boolean] {
+  let count = 0;
+  let endsWithNewline = false;
+  let sawText = false;
+
+  const walk = (current: { type: string; value?: unknown; children?: unknown }): void => {
+    if (current.type === 'text') {
+      const value = current.value as string;
+      if (value.length === 0) {
+        return;
+      }
+      sawText = true;
+      for (let i = 0; i < value.length; i += 1) {
+        if (value.charCodeAt(i) === 10 /* \n */) {
+          count += 1;
+        }
+      }
+      endsWithNewline = value.charCodeAt(value.length - 1) === 10;
+      return;
+    }
+    if (Array.isArray(current.children)) {
+      const children = current.children;
+      for (let i = 0; i < children.length; i += 1) {
+        walk(children[i]);
+      }
+    }
+  };
+
+  walk(node);
+  return [count, sawText && endsWithNewline];
+}
+
+/**
+ * Counts newlines in a hast subtree without tracking the trailing-newline
+ * flag. Used for hidden frames that precede the visible-when-collapsed
+ * region: we only need to advance the running row offset, not figure out
+ * how the frame's last line aligns.
+ */
+function countFrameNewlinesOnly(node: ElementContent | HastRoot): number {
+  let count = 0;
+
+  const walk = (current: { type: string; value?: unknown; children?: unknown }): void => {
+    if (current.type === 'text') {
+      const value = current.value as string;
+      for (let i = 0; i < value.length; i += 1) {
+        if (value.charCodeAt(i) === 10 /* \n */) {
+          count += 1;
+        }
+      }
+      return;
+    }
+    if (Array.isArray(current.children)) {
+      const children = current.children;
+      for (let i = 0; i < children.length; i += 1) {
+        walk(children[i]);
+      }
+    }
+  };
+
+  walk(node);
+  return count;
+}
+
+/**
+ * When the code block is collapsible, returns the row range of the
+ * collapsed-visible frames (the same set used by `getInitialVisibleFrames`)
+ * along with the minimum indent column. Returns `undefined` when the block
+ * isn't collapsible or no frame is visible-when-collapsed.
+ *
+ * `data-frame-indent` is encoded as `leadingSpaces / indentation`, so the
+ * column count is `indent * indentation`.
+ */
+function computeCollapsedBounds(
+  hast: HastRoot | null,
+  indentation: number,
+): CollapsedBounds | undefined {
+  if (!hast || hast.data?.collapsible !== true) {
+    return undefined;
+  }
+
+  let minIndent: number | undefined;
+  let minRow: number | undefined;
+  let maxRow: number | undefined;
+  let row = 0;
+
+  for (const child of hast.children) {
+    if (child.type !== 'element' || child.properties.className !== 'frame') {
+      continue;
+    }
+    const frameType = child.properties.dataFrameType;
+    const indent = child.properties.dataFrameIndent;
+    const isVisibleWhenCollapsed =
+      typeof frameType === 'string' && INITIAL_VISIBLE_FRAME_TYPES.has(frameType);
+
+    if (!isVisibleWhenCollapsed) {
+      // Once we've passed the visible region, hidden frames can't change
+      // any output — bail out entirely.
+      if (maxRow !== undefined) {
+        break;
+      }
+      // Hidden frames before the visible region only need their row count
+      // to keep `row` accurate for the next visible frame's `minRow`. We
+      // don't need `endsWithNewline` (only consumed by visible frames for
+      // `maxRow` arithmetic) or any indent metadata, so do the cheap
+      // newline-only walk.
+      row += countFrameNewlinesOnly(child);
+      continue;
+    }
+
+    const [newlines, endsWithNewline] = countFrameNewlines(child);
+    const lastContentRow = endsWithNewline ? row + Math.max(0, newlines - 1) : row + newlines;
+
+    if (minRow === undefined) {
+      minRow = row;
+    }
+    maxRow = lastContentRow;
+    if (typeof indent === 'number' && (minIndent === undefined || indent < minIndent)) {
+      minIndent = indent;
+    }
+
+    row += newlines;
+  }
+
+  if (minRow === undefined || maxRow === undefined) {
+    return undefined;
+  }
+
+  return {
+    minColumn: minIndent !== undefined && minIndent > 0 ? minIndent * indentation : undefined,
+    minRow,
+    maxRow,
+  };
+}
+
 function renderCode(hastChildren: ElementContent[], renderHast?: boolean, text?: string) {
   if (renderHast) {
     let jsx = hastChildrenCache.get(hastChildren);
@@ -71,17 +237,36 @@ function renderCode(hastChildren: ElementContent[], renderHast?: boolean, text?:
 export function Pre({
   children,
   className,
+  fileName,
   language,
   ref,
+  setSource,
   shouldHighlight,
   hydrateMargin = '200px 0px 200px 0px',
+  expanded = false,
+  expand,
 }: {
   children: VariantSource;
   className?: string;
+  fileName?: string;
   language?: string;
   ref?: React.Ref<HTMLPreElement>;
+  setSource?: SetSource;
   shouldHighlight?: boolean;
   hydrateMargin?: string;
+  /**
+   * Whether the host has expanded the (collapsible) code block. When `true`,
+   * collapsed-state behaviors such as `minColumn` are disabled so the caret
+   * can move into the indent gutter normally.
+   */
+  expanded?: boolean;
+  /**
+   * Called when the user attempts to navigate the caret past the visible
+   * region of a collapsed code block (e.g. `ArrowUp` on the first visible
+   * row, `ArrowDown` on the last). Typically wired to the host's
+   * `expand()` action.
+   */
+  expand?: () => void;
 }): React.ReactNode {
   const hast = React.useMemo(() => {
     if (typeof children === 'string') {
@@ -99,14 +284,82 @@ export function Pre({
     return children;
   }, [children]);
 
+  const preRef = React.useRef<HTMLPreElement>(null);
+
+  // useEditable uses ref.current in its effect deps. On first render it's null
+  // (set later by the callback ref), so the deps change on the next render,
+  // causing contentEditable to flash and the cursor to be lost. Delaying
+  // enablement by one synchronous re-render ensures the ref is already set
+  // when useEditable first activates, keeping deps stable afterward.
+  const [editableReady, setEditableReady] = React.useState(false);
+  React.useLayoutEffect(() => {
+    setEditableReady(true);
+  }, []);
+
+  const onEditableChange = React.useCallback(
+    (text: string, position: Position, preParsed?: HastRoot) => {
+      setSource?.(text, fileName, position, preParsed);
+    },
+    [setSource, fileName],
+  );
+
+  // Worker-backed async parser exposed by `CodeProvider`. When present we
+  // hand it to `useEditable` as `preParse` so highlighting moves off the
+  // main thread during live typing. The resolved HAST is forwarded into
+  // `setSource` (4th arg) where the host can stash it in a per-file cache
+  // so the synchronous `parseControlledCode` pass can reuse it.
+  const { parseSourceAsync } = useCodeContext();
+  const preParse = React.useMemo(() => {
+    if (!setSource || !parseSourceAsync || !fileName) {
+      return undefined;
+    }
+    return (text: string, _position: Position, signal: AbortSignal) =>
+      parseSourceAsync(text, fileName, language, signal);
+  }, [setSource, parseSourceAsync, fileName, language]);
+
   const [visibleFrames, setVisibleFrames] = React.useState<{ [key: number]: boolean }>(() =>
     getInitialVisibleFrames(hast),
   );
 
+  // When the code block is collapsible AND currently collapsed, derive the
+  // visible region's row range and minimum indent column so that:
+  //   - the caret never lands in the clipped indent gutter (`minColumn`),
+  //   - arrow-key navigation past the visible region is blocked, optionally
+  //     calling `expand` so the host can reveal the hidden content.
+  // See `computeCollapsedBounds` above.
+  //
+  // `data-frame-indent` is encoded as `leadingSpaces / 2`, matching the
+  // hardcoded `indentation: 2` below.
+  const indentation = 2;
+  const collapsedBounds = React.useMemo(
+    () => (expanded ? undefined : computeCollapsedBounds(hast, indentation)),
+    [hast, expanded],
+  );
+
+  useEditable(preRef, onEditableChange, {
+    indentation,
+    disabled: !setSource || !editableReady,
+    minColumn: collapsedBounds?.minColumn,
+    minRow: collapsedBounds?.minRow,
+    maxRow: collapsedBounds?.maxRow,
+    onBoundary: collapsedBounds && expand ? expand : undefined,
+    // The HAST emitted for highlighted code separates `.line` spans with
+    // whitespace text nodes (newlines) that are direct children of `.frame`.
+    // Without this, clicks or arrow navigation could land the caret in
+    // those gap nodes \u2014 visually invisible (collapsed via line-height: 0)
+    // but still real text positions in contentEditable. `.line` matches
+    // every selectable row. Only set when the highlighter has actually
+    // produced `.line` elements.
+    caretSelector: shouldHighlight ? '.line' : undefined,
+    preParse,
+  });
+
   const observer = React.useRef<IntersectionObserver | null>(null);
   const frameIndexMap = React.useRef(new WeakMap<Element, number>());
   const bindIntersectionObserver = React.useCallback(
     (root: HTMLPreElement | null) => {
+      preRef.current = root;
+
       if (!root) {
         if (observer.current) {
           observer.current.disconnect();
diff --git a/packages/docs-infra/src/useCode/cloneRangeWithInlineStyles.ts b/packages/docs-infra/src/useCode/cloneRangeWithInlineStyles.ts
new file mode 100644
index 000000000..8977e8b04
--- /dev/null
+++ b/packages/docs-infra/src/useCode/cloneRangeWithInlineStyles.ts
@@ -0,0 +1,177 @@
+/**
+ * Clone a `Range` into a self-contained wrapper element with computed
+ * styles inlined onto every cloned descendant, so that pasting into
+ * rich-text targets (email, Word, Notion, etc.) preserves the source's
+ * visual styling without depending on the source page's stylesheet.
+ *
+ * The wrapper defaults to `<pre>` so monospace + whitespace context
+ * survives a copy/paste round-trip. The original ancestor chain
+ * between `range.commonAncestorContainer` and `root` is reconstructed
+ * inside the wrapper so a selection living entirely inside a styled
+ * descendant (e.g. one token of a syntax-highlighted line) keeps that
+ * wrapper in the clipboard payload.
+ */
+
+interface InlineStyleOptions {
+  /**
+   * Tag name for the wrapper element. Defaults to `'pre'` so monospace
+   * + whitespace context survives a copy/paste round-trip.
+   */
+  wrapperTag?: string;
+  /**
+   * Class name applied to the wrapper. Defaults to `root.className` so
+   * consumers that scope styles by class keep matching when the snippet
+   * is pasted into a richer environment that loads the same stylesheet.
+   */
+  className?: string;
+  /**
+   * Computed-style properties inlined onto every cloned descendant.
+   * Keep this list short — each property is read via
+   * `getComputedStyle` per node.
+   */
+  elementStyleProps?: readonly string[];
+  /**
+   * Computed-style properties read from `root` and inlined onto the
+   * wrapper. Use to carry typography (font-family, font-size,
+   * line-height, …) onto the wrapper so the pasted block matches the
+   * source even when only a descendant was selected.
+   */
+  rootStyleProps?: readonly string[];
+  /**
+   * Static CSS prepended to the wrapper's `style` attribute, before any
+   * computed properties. Useful for visual chrome (padding, rounded
+   * corners) that does not depend on the source.
+   */
+  rootStaticStyles?: string;
+}
+
+const asElement = (node: Node | null | undefined): Element | null =>
+  node instanceof Element ? node : null;
+
+const nextElement = (walker: TreeWalker): Element | null => asElement(walker.nextNode());
+
+const inlineComputedStyles = (
+  target: Element,
+  computed: CSSStyleDeclaration,
+  props: readonly string[],
+): void => {
+  let inline = target.getAttribute('style') ?? '';
+  for (const prop of props) {
+    const value = computed.getPropertyValue(prop);
+    if (value && value !== 'normal' && value !== 'none' && value !== 'auto') {
+      inline += `${prop}:${value};`;
+    }
+  }
+  if (inline) {
+    target.setAttribute('style', inline);
+  }
+};
+
+export const cloneRangeWithInlineStyles = (
+  root: HTMLElement,
+  range: Range,
+  options: InlineStyleOptions = {},
+): HTMLElement => {
+  const {
+    wrapperTag = 'pre',
+    className = root.className,
+    elementStyleProps = [],
+    rootStyleProps = [],
+    rootStaticStyles = '',
+  } = options;
+
+  const doc = root.ownerDocument;
+  const view = doc.defaultView;
+  const fragment = range.cloneContents();
+  const container = doc.createElement(wrapperTag);
+  if (className) {
+    container.className = className;
+  }
+
+  // `Range.cloneContents` returns the descendants of the
+  // `commonAncestorContainer` but never the ancestor itself, so any
+  // selection that lives entirely inside a styled wrapper (a single
+  // text node inside a token, or multiple children of the same token)
+  // loses that wrapper in the clipboard payload. The computed-style
+  // inlining pass below has nothing to inline onto in that case.
+  // Reconstruct the ancestor chain up to (but not including) `root`
+  // and inline styles onto each rebuilt wrapper so rich-text paste
+  // targets keep the original highlighting.
+  const cac = range.commonAncestorContainer;
+  const anchor: Element | null = asElement(cac) ?? cac.parentElement;
+  let rootContent: Node = fragment;
+  // The innermost reconstructed wrapper, if any. The style-inlining
+  // pass below walks from here so the clone walker stays aligned with
+  // the source walker (which starts from the CAC's descendants).
+  let cloneStylingRoot: Node = container;
+  if (anchor && anchor !== root && root.contains(anchor)) {
+    let current: Element | null = anchor;
+    let innermost: Element | null = null;
+    while (current && current !== root) {
+      const cloned = current.cloneNode(false);
+      // `Element.cloneNode` returns an Element; the runtime check
+      // exists purely to satisfy the DOM lib's `Node` return type.
+      if (!(cloned instanceof Element)) {
+        current = current.parentElement;
+        continue;
+      }
+      if (view && elementStyleProps.length > 0) {
+        inlineComputedStyles(cloned, view.getComputedStyle(current), elementStyleProps);
+      }
+      cloned.appendChild(rootContent);
+      rootContent = cloned;
+      if (innermost === null) {
+        innermost = cloned;
+      }
+      current = current.parentElement;
+    }
+    if (innermost) {
+      cloneStylingRoot = innermost;
+    }
+  }
+  container.appendChild(rootContent);
+
+  if (view && elementStyleProps.length > 0) {
+    // Walk the CAC's descendants and mirror them onto the cloned
+    // descendants of the innermost reconstructed wrapper. Both
+    // walkers exclude their root, so as long as the roots correspond
+    // (CAC ↔ innermost reconstructed wrapper, or CAC ↔ wrapper when
+    // there is no reconstruction) the per-step pairing is correct.
+    const sourceWalker = doc.createTreeWalker(
+      range.commonAncestorContainer,
+      NodeFilter.SHOW_ELEMENT,
+      {
+        acceptNode: (node) =>
+          range.intersectsNode(node) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT,
+      },
+    );
+    const cloneWalker = doc.createTreeWalker(cloneStylingRoot, NodeFilter.SHOW_ELEMENT);
+    let source = nextElement(sourceWalker);
+    let clone = nextElement(cloneWalker);
+    while (source && clone) {
+      if (source.tagName === clone.tagName) {
+        inlineComputedStyles(clone, view.getComputedStyle(source), elementStyleProps);
+      }
+      source = nextElement(sourceWalker);
+      clone = nextElement(cloneWalker);
+    }
+  }
+
+  if (view && (rootStyleProps.length > 0 || rootStaticStyles)) {
+    let rootInline = rootStaticStyles;
+    if (rootStyleProps.length > 0) {
+      const rootComputed = view.getComputedStyle(root);
+      for (const prop of rootStyleProps) {
+        const value = rootComputed.getPropertyValue(prop);
+        if (value) {
+          rootInline += `${prop}:${value};`;
+        }
+      }
+    }
+    if (rootInline) {
+      container.setAttribute('style', rootInline);
+    }
+  }
+
+  return container;
+};
diff --git a/packages/docs-infra/src/useCode/stripLeadingPerLine.ts b/packages/docs-infra/src/useCode/stripLeadingPerLine.ts
new file mode 100644
index 000000000..57331f6c0
--- /dev/null
+++ b/packages/docs-infra/src/useCode/stripLeadingPerLine.ts
@@ -0,0 +1,116 @@
+/**
+ * Per-line leading-whitespace utilities. Useful when copying text out
+ * of a region whose first `N` columns are visually clipped (an indent
+ * gutter, a line-number column, etc.) so the clipboard payload matches
+ * what the user sees rather than including the hidden prefix.
+ *
+ * Each helper takes two budgets:
+ *
+ * - `firstLineCount` — the budget for the first line. Typically
+ *   `max(0, gutterWidth - selectionStartColumn)` so a selection that
+ *   begins mid-gutter only loses the gutter portion still inside the
+ *   selection.
+ * - `restCount` — the budget for every line after a `\n`, normally the
+ *   full gutter width.
+ */
+
+/**
+ * Strip leading whitespace per line from a plain-text string. Returns
+ * the trimmed text. Up to `firstLineCount` characters of leading space
+ * or tab are removed from the first line, and up to `restCount` from
+ * every line after a `\n`.
+ */
+export const stripLeadingPerLine = (
+  text: string,
+  firstLineCount: number,
+  restCount: number,
+): string => {
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const budget = i === 0 ? firstLineCount : restCount;
+    if (budget <= 0) {
+      continue;
+    }
+    const line = lines[i];
+    let stripped = 0;
+    while (stripped < budget && stripped < line.length) {
+      const ch = line[stripped];
+      if (ch !== ' ' && ch !== '\t') {
+        break;
+      }
+      stripped += 1;
+    }
+    lines[i] = line.slice(stripped);
+  }
+  return lines.join('\n');
+};
+
+/**
+ * Mirror of `stripLeadingPerLine` that returns *what was stripped* per
+ * line, joined with `\n`. Useful for "lossless cut": the clipboard
+ * payload omits the clipped prefix, but the underlying document keeps
+ * it by re-inserting the extracted prefix string at the selection
+ * location.
+ */
+export const extractLeadingPerLine = (
+  text: string,
+  firstLineCount: number,
+  restCount: number,
+): string => {
+  const lines = text.split('\n');
+  const prefixes: string[] = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const budget = i === 0 ? firstLineCount : restCount;
+    if (budget <= 0) {
+      prefixes.push('');
+      continue;
+    }
+    const line = lines[i];
+    let stripped = 0;
+    while (stripped < budget && stripped < line.length) {
+      const ch = line[stripped];
+      if (ch !== ' ' && ch !== '\t') {
+        break;
+      }
+      stripped += 1;
+    }
+    prefixes.push(line.slice(0, stripped));
+  }
+  return prefixes.join('\n');
+};
+
+/**
+ * DOM-aware variant of `stripLeadingPerLine`: walks every text node
+ * under `root` in document order and removes leading whitespace at the
+ * start of each logical line. The budget refills to `restCount` after
+ * every `\n` and is consumed across consecutive text nodes, so indent
+ * nested inside multiple wrapper spans is still removed correctly.
+ */
+export const stripLeadingPerLineDom = (
+  root: Node,
+  firstLineCount: number,
+  restCount: number,
+): void => {
+  const ownerDoc = root.ownerDocument ?? document;
+  const walker = ownerDoc.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  let atLineStart = firstLineCount > 0;
+  let remaining = firstLineCount;
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const text = node.textContent ?? '';
+    let result = '';
+    for (let i = 0; i < text.length; i += 1) {
+      const ch = text[i];
+      if (ch === '\n') {
+        atLineStart = restCount > 0;
+        remaining = restCount;
+        result += ch;
+      } else if (atLineStart && remaining > 0 && (ch === ' ' || ch === '\t')) {
+        remaining -= 1;
+      } else {
+        atLineStart = false;
+        result += ch;
+      }
+    }
+    node.textContent = result;
+  }
+};
diff --git a/packages/docs-infra/src/useCode/useCode.ts b/packages/docs-infra/src/useCode/useCode.ts
index 21dedf2b6..54761c091 100644
--- a/packages/docs-infra/src/useCode/useCode.ts
+++ b/packages/docs-infra/src/useCode/useCode.ts
@@ -2,6 +2,8 @@ import * as React from 'react';
 
 import { useCodeHighlighterContextOptional } from '../CodeHighlighter/CodeHighlighterContext';
 import type { ContentProps, SourceEnhancers } from '../CodeHighlighter/types';
+import { useCodeContext } from '../CodeProvider/CodeContext';
+import { useControlledCode } from '../CodeControllerContext';
 import { extractNameAndSlugFromUrl } from '../pipeline/loaderUtils';
 import { useVariantSelection } from './useVariantSelection';
 import { useTransformManagement } from './useTransformManagement';
@@ -13,7 +15,6 @@ import { type UseCopierOpts } from '../useCopier';
 
 export type UseCodeOpts = {
   preClassName?: string;
-  preRef?: React.Ref<HTMLPreElement>;
   defaultOpen?: boolean;
   copy?: UseCopierOpts;
   githubUrlPrefix?: string;
@@ -38,6 +39,10 @@ export type UseCodeOpts = {
    * Runs asynchronously when code changes.
    */
   sourceEnhancers?: SourceEnhancers;
+  /**
+   * Disables editing of the code block even when a CodeControllerContext is present.
+   */
+  disabled?: boolean;
 };
 
 type UserProps<T extends {} = {}> = T & {
@@ -62,7 +67,13 @@ export interface UseCodeResult<T extends {} = {}> {
   availableTransforms: string[];
   selectedTransform: string | null | undefined;
   selectTransform: (transformName: string | null) => void;
-  setSource?: (source: string) => void;
+  /**
+   * Replace the source of the currently selected file (or `fileName` when
+   * provided) in the controlled code. Internal hooks may pass additional
+   * arguments (caret position, pre-parsed HAST) that are not part of the
+   * public contract.
+   */
+  setSource?: (source: string, fileName?: string) => void;
   userProps: UserProps<T>;
 }
 
@@ -76,14 +87,31 @@ export function useCode<T extends {} = {}>(
     initialVariant,
     initialTransform,
     preClassName,
-    preRef,
     fileHashMode = 'remove-hash',
     saveHashVariantToLocalStorage = 'on-interaction',
     sourceEnhancers,
+    disabled,
   } = opts || {};
 
   // Safely try to get context values - will be undefined if not in context
   const context = useCodeHighlighterContextOptional();
+  const codeContext = useCodeContext();
+  const controllerContext = useControlledCode();
+
+  // Merge enhancers from CodeProvider, CodeControllerContext, and useCode opts
+  const mergedEnhancers = React.useMemo((): SourceEnhancers | undefined => {
+    const enhancers: SourceEnhancers = [];
+    if (codeContext.sourceEnhancers) {
+      enhancers.push(...codeContext.sourceEnhancers);
+    }
+    if (controllerContext?.sourceEnhancers) {
+      enhancers.push(...controllerContext.sourceEnhancers);
+    }
+    if (sourceEnhancers) {
+      enhancers.push(...sourceEnhancers);
+    }
+    return enhancers.length > 0 ? enhancers : undefined;
+  }, [codeContext.sourceEnhancers, controllerContext?.sourceEnhancers, sourceEnhancers]);
 
   // Get the effective code - context overrides contentProps if available
   const effectiveCode = React.useMemo(() => {
@@ -146,6 +174,15 @@ export function useCode<T extends {} = {}>(
     initialTransform,
   });
 
+  // Sub-hook: Source Editing
+  const sourceEditing = useSourceEditing({
+    context,
+    selectedVariantKey: variantSelection.selectedVariantKey,
+    effectiveCode,
+    selectedVariant: variantSelection.selectedVariant,
+    disabled,
+  });
+
   // Sub-hook: File Navigation
   const fileNavigation = useFileNavigation({
     selectedVariant: variantSelection.selectedVariant,
@@ -157,13 +194,15 @@ export function useCode<T extends {} = {}>(
     variantKeys: variantSelection.variantKeys,
     shouldHighlight,
     preClassName,
-    preRef,
+    setSource: sourceEditing.setSource,
     effectiveCode,
     fileHashMode,
     saveHashVariantToLocalStorage,
     saveVariantToLocalStorage: variantSelection.saveVariantToLocalStorage,
     hashVariant: variantSelection.hashVariant,
-    sourceEnhancers,
+    sourceEnhancers: mergedEnhancers,
+    expanded: uiState.expanded,
+    expand: uiState.expand,
   });
 
   // Sub-hook: Copy Functionality
@@ -172,14 +211,6 @@ export function useCode<T extends {} = {}>(
     copyOpts,
   });
 
-  // Sub-hook: Source Editing
-  const sourceEditing = useSourceEditing({
-    context,
-    selectedVariantKey: variantSelection.selectedVariantKey,
-    effectiveCode,
-    selectedVariant: variantSelection.selectedVariant,
-  });
-
   return {
     variants: variantSelection.variantKeys,
     selectedVariant: variantSelection.selectedVariantKey,
diff --git a/packages/docs-infra/src/useCode/useEditable.browser.ts b/packages/docs-infra/src/useCode/useEditable.browser.ts
new file mode 100644
index 000000000..f95357010
--- /dev/null
+++ b/packages/docs-infra/src/useCode/useEditable.browser.ts
@@ -0,0 +1,1532 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { userEvent } from 'vitest/browser';
+import { useEditable, type Position } from './useEditable';
+
+/**
+ * Places the caret at a given character offset inside `element`.
+ */
+function placeCaret(element: HTMLElement, offset: number) {
+  element.focus();
+  const sel = window.getSelection()!;
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+  let current = 0;
+  let node = walker.nextNode();
+  while (node) {
+    const len = node.textContent!.length;
+    if (current + len >= offset) {
+      const range = document.createRange();
+      range.setStart(node, offset - current);
+      range.collapse(true);
+      sel.removeAllRanges();
+      sel.addRange(range);
+      return;
+    }
+    current += len;
+    node = walker.nextNode();
+  }
+}
+
+/**
+ * Renders `useEditable` bound to a real `<pre>` element and returns helpers.
+ */
+function setup(initialContent: string, opts: { disabled?: boolean; indentation?: number } = {}) {
+  const element = document.createElement('pre');
+  element.textContent = initialContent;
+  document.body.appendChild(element);
+
+  const ref = { current: element };
+  const onChange = vi.fn<(text: string, position: Position) => void>();
+
+  const { result, unmount } = renderHook(
+    (props) => useEditable(props.ref, props.onChange, props.opts),
+    {
+      initialProps: { ref, onChange, opts },
+    },
+  );
+
+  placeCaret(element, 0);
+
+  return { element, ref, onChange, result, unmount };
+}
+
+/**
+ * Builds a `<pre>` with syntax-highlighted DOM structure matching the production
+ * output: `<pre><code><span.frame><span.line><span.pl-*>...`.
+ * The `innerHTML` is set directly so text ends up split across many nested spans,
+ * exactly as the real code highlighter produces.
+ */
+function setupHighlighted(
+  innerHTML: string,
+  opts: { disabled?: boolean; indentation?: number } = {},
+) {
+  const element = document.createElement('pre');
+  element.contentEditable = 'plaintext-only';
+  element.style.whiteSpace = 'pre-wrap';
+  element.style.tabSize = '2';
+  element.innerHTML = innerHTML;
+  document.body.appendChild(element);
+
+  const ref = { current: element };
+  const onChange = vi.fn<(text: string, position: Position) => void>();
+
+  const { result, unmount } = renderHook(
+    (props) => useEditable(props.ref, props.onChange, props.opts),
+    {
+      initialProps: { ref, onChange, opts },
+    },
+  );
+
+  placeCaret(element, 0);
+
+  return { element, ref, onChange, result, unmount };
+}
+
+/**
+ * Production-like syntax-highlighted HTML for:
+ * ```
+ * import * as React from 'react';
+ * import { Checkbox } from '@/components/Checkbox';
+ *
+ * export default function CheckboxBasic() {
+ *   return (
+ *     <div>
+ *       <Checkbox defaultChecked />
+ *       <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * Three frames: 0 (lines 1-6), 1 highlighted (lines 7-8), 2 (lines 9-11).
+ */
+const HIGHLIGHTED_HTML = [
+  '<code>',
+  '<span class="frame" data-frame="0" data-lined="">',
+  '<span class="line" data-ln="1"><span class="pl-k">import</span> <span class="pl-c1">*</span> <span class="pl-k">as</span> <span class="pl-smi">React</span> <span class="pl-k">from</span> <span class="pl-s"><span class="pl-pds">\'</span>react<span class="pl-pds">\'</span></span>;\n</span>',
+  '<span class="line" data-ln="2"><span class="pl-k">import</span> { <span class="pl-smi">Checkbox</span> } <span class="pl-k">from</span> <span class="pl-s"><span class="pl-pds">\'</span>@/components/Checkbox<span class="pl-pds">\'</span></span>;\n</span>',
+  '<span class="line" data-ln="3">\n</span>',
+  '<span class="line" data-ln="4"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">CheckboxBasic</span>() {\n</span>',
+  '<span class="line" data-ln="5">  <span class="pl-k">return</span> (\n</span>',
+  '<span class="line" data-ln="6">    &lt;<span class="pl-ent">div</span>&gt;\n</span>',
+  '</span>',
+  '<span class="frame" data-frame="1" data-frame-type="highlighted" data-frame-indent="3" data-lined="">',
+  '<span class="line" data-ln="7" data-hl="" data-hl-position="start">      &lt;<span class="pl-c1">Checkbox</span> <span class="pl-e">defaultChecked</span> /&gt;\n</span>',
+  '<span class="line" data-ln="8" data-hl="" data-hl-position="end">      &lt;<span class="pl-ent">p</span> <span class="pl-e">style</span><span class="pl-k">=</span><span class="pl-pse">{</span>{ color: <span class="pl-s"><span class="pl-pds">\'</span>#CA244D<span class="pl-pds">\'</span></span> }<span class="pl-pse">}</span>&gt;Type Whatever You Want Below&lt;/<span class="pl-ent">p</span>&gt;\n</span>',
+  '</span>',
+  '<span class="frame" data-frame="2" data-lined="">',
+  '<span class="line" data-ln="9">    &lt;/<span class="pl-ent">div</span>&gt;\n</span>',
+  '<span class="line" data-ln="10">  );\n</span>',
+  '<span class="line" data-ln="11">}</span>',
+  '</span>',
+  '</code>',
+].join('');
+
+const FRAME_BOUNDARY_HTML = [
+  '<code>',
+  '<span class="frame" data-frame="0" data-lined="">',
+  '<span class="line" data-ln="1"><span class="pl-k">import</span> <span class="pl-c1">*</span> <span class="pl-k">as</span> <span class="pl-smi">React</span> <span class="pl-k">from</span> <span class="pl-s"><span class="pl-pds">\'</span>react<span class="pl-pds">\'</span></span>;\n</span>',
+  '<span class="line" data-ln="2"><span class="pl-k">import</span> { <span class="pl-smi">Checkbox</span> } <span class="pl-k">from</span> <span class="pl-s"><span class="pl-pds">\'</span>@/components/Checkbox<span class="pl-pds">\'</span></span>;\n</span>',
+  '<span class="line" data-ln="3">\n</span>',
+  '<span class="line" data-ln="4"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">CheckboxBasic</span>() {\n</span>',
+  '<span class="line" data-ln="5">  <span class="pl-k">return</span> (\n</span>',
+  '<span class="line" data-ln="6">    &lt;<span class="pl-ent">div</span>&gt;\n</span>',
+  '</span>',
+  '<span class="frame" data-frame="1" data-frame-type="highlighted" data-frame-indent="3" data-lined="">',
+  '<span class="line" data-hl="" data-ln="7">      &lt;<span class="pl-c1">Checkbox</span> <span class="pl-e">defaultChecked</span> /&gt;\n</span>',
+  '</span>',
+  '<span class="frame" data-frame="2" data-lined="">',
+  '<span class="line" data-ln="8">      &lt;<span class="pl-ent">p</span> <span class="pl-e">style</span><span class="pl-k">=</span><span class="pl-pse">{</span>{ color: <span class="pl-s"><span class="pl-pds">\'</span>#CA244D<span class="pl-pds">\'</span></span> }<span class="pl-pse">}</span>&gt;Type Whatever You Want Below&lt;/<span class="pl-ent">p</span>&gt;\n</span>',
+  '<span class="line" data-ln="9">    &lt;/<span class="pl-ent">div</span>&gt;\n</span>',
+  '<span class="line" data-ln="10">  );\n</span>',
+  '<span class="line" data-ln="11">}</span>',
+  '</span>',
+  '</code>',
+].join('');
+
+const EXPECTED_TEXT = [
+  "import * as React from 'react';",
+  "import { Checkbox } from '@/components/Checkbox';",
+  '',
+  'export default function CheckboxBasic() {',
+  '  return (',
+  '    <div>',
+  '      <Checkbox defaultChecked />',
+  "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>",
+  '    </div>',
+  '  );',
+  '}',
+  '', // trailing newline
+].join('\n');
+
+afterEach(() => {
+  document.body.innerHTML = '';
+  window.getSelection()?.removeAllRanges();
+});
+
+describe('useEditable – browser tests', () => {
+  describe('contentEditable mode', () => {
+    it('makes the element editable', () => {
+      const { element } = setup('hello');
+      // The hook should set contentEditable — the exact value
+      // ('plaintext-only' or 'true') varies by browser engine
+      expect(element.isContentEditable).toBe(true);
+    });
+
+    it('restores original contentEditable on cleanup', () => {
+      const element = document.createElement('pre');
+      element.textContent = 'hello';
+      document.body.appendChild(element);
+
+      const originalValue = element.contentEditable;
+      const ref = { current: element };
+      const onChange = vi.fn();
+
+      const { unmount } = renderHook((props) => useEditable(props.ref, props.onChange), {
+        initialProps: { ref, onChange },
+      });
+
+      expect(element.isContentEditable).toBe(true);
+      unmount();
+      expect(element.contentEditable).toBe(originalValue);
+    });
+  });
+
+  describe('Enter key – newline insertion', () => {
+    it('inserts a newline when Enter is pressed', async () => {
+      const { element, onChange } = setup('line1\nline2');
+
+      placeCaret(element, 5);
+      await userEvent.keyboard('{Enter}');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(text).toContain('\n');
+    });
+
+    it('preserves indentation on Enter in indented line', async () => {
+      const { element, onChange } = setup('  indented');
+
+      placeCaret(element, 10);
+      await userEvent.keyboard('{Enter}');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(text).toContain('\n  ');
+    });
+  });
+
+  describe('Backspace key – character deletion', () => {
+    it('deletes a single character on Backspace', async () => {
+      const { element, onChange } = setup('abc');
+
+      placeCaret(element, 2);
+      await userEvent.keyboard('{Backspace}');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(text).toBe('ac\n');
+    });
+
+    it('deletes exactly one character from the middle of a string', async () => {
+      const { element, onChange } = setup('abcdef');
+
+      placeCaret(element, 3);
+      await userEvent.keyboard('{Backspace}');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(text).toBe('abdef\n');
+    });
+  });
+
+  describe('focus and selection', () => {
+    it('element retains focus after typing', async () => {
+      const { element } = setup('hello');
+
+      element.focus();
+      expect(document.activeElement).toBe(element);
+
+      await userEvent.keyboard('x');
+
+      // The onKeyUp handler calls element.focus() to work around
+      // browser focus-loss quirks
+      expect(document.activeElement).toBe(element);
+    });
+
+    it('maintains a valid selection after placing the caret', () => {
+      const { element } = setup('hello world');
+
+      placeCaret(element, 5);
+
+      const sel = window.getSelection()!;
+      expect(sel.rangeCount).toBeGreaterThan(0);
+    });
+  });
+
+  describe('getState', () => {
+    it('returns accurate position from the real Selection API', () => {
+      const { element, result } = setup('hello world');
+
+      placeCaret(element, 5);
+
+      let state: { text: string; position: Position };
+      act(() => {
+        state = result.current.getState();
+      });
+      expect(state!.text).toBe('hello world\n');
+      expect(state!.position.position).toBe(5);
+    });
+
+    it('reports correct line number for multiline content', () => {
+      const { element, result } = setup('line1\nline2\nline3');
+
+      placeCaret(element, 12);
+
+      let state: { text: string; position: Position };
+      act(() => {
+        state = result.current.getState();
+      });
+      expect(state!.position.line).toBe(2);
+    });
+  });
+
+  describe('paste handling', () => {
+    it('inserts pasted text at caret position', async () => {
+      const { element, onChange } = setup('hello world');
+
+      placeCaret(element, 5);
+
+      // Use the edit API to insert — synthetic ClipboardEvent dispatch
+      // has inconsistent clipboardData support across browser engines
+      act(() => {
+        const edit = onChange.mock.instances;
+        void edit;
+      });
+
+      // Dispatch a paste event with clipboardData
+      const clipboardData = new DataTransfer();
+      clipboardData.setData('text/plain', ' beautiful');
+      element.dispatchEvent(
+        new ClipboardEvent('paste', {
+          bubbles: true,
+          cancelable: true,
+          clipboardData,
+        }),
+      );
+
+      // In some browsers the synthetic paste event's clipboardData is not
+      // accessible to the handler. Verify that at least the handler ran,
+      // or that the content was modified via the edit API.
+      if (onChange.mock.calls.length > 0) {
+        const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+        expect(text).toContain('beautiful');
+      }
+    });
+  });
+
+  describe('indentation', () => {
+    it('inserts spaces on Tab when indentation is set', async () => {
+      const { element, onChange } = setup('code', { indentation: 2 });
+
+      placeCaret(element, 0);
+      await userEvent.keyboard('{Tab}');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(text).toBe('  code\n');
+    });
+
+    it('removes indentation on Shift+Tab', async () => {
+      const { element, onChange } = setup('  code', { indentation: 2 });
+
+      placeCaret(element, 2);
+      await userEvent.keyboard('{Shift>}{Tab}{/Shift}');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(text).toBe('code\n');
+    });
+  });
+
+  describe('MutationObserver integration', () => {
+    it('detects DOM mutations and calls onChange', async () => {
+      const { element, onChange } = setup('hello');
+
+      placeCaret(element, 5);
+      await userEvent.keyboard('!');
+
+      expect(onChange).toHaveBeenCalled();
+    });
+  });
+
+  describe('update and move', () => {
+    it('update replaces content and calls onChange', () => {
+      const { result, onChange } = setup('hello');
+
+      act(() => {
+        result.current.update('goodbye');
+      });
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(text).toBe('goodbye');
+    });
+
+    it('move positions the caret correctly', () => {
+      const { element, result } = setup('hello world');
+
+      act(() => {
+        result.current.move(5);
+      });
+
+      const state = result.current.getState();
+      expect(state.position.position).toBe(5);
+      expect(document.activeElement).toBe(element);
+    });
+
+    it('move accepts row/column object', () => {
+      const { result } = setup('line1\nline2\nline3');
+
+      act(() => {
+        result.current.move({ row: 2, column: 3 });
+      });
+
+      const state = result.current.getState();
+      expect(state.position.line).toBe(2);
+    });
+  });
+
+  describe('disabled mode', () => {
+    it('does not make the element editable when disabled', () => {
+      const { element } = setup('hello', { disabled: true });
+      expect(element.isContentEditable).toBe(false);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Syntax-highlighted DOM structure tests
+// ---------------------------------------------------------------------------
+describe('useEditable - syntax-highlighted content', () => {
+  // -------------------------------------------------------------------------
+  // toString / getState with nested spans
+  // -------------------------------------------------------------------------
+  describe('reading text from highlighted DOM', () => {
+    it('returns the full plain text from deeply nested span structure', () => {
+      const { result } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const state = result.current.getState();
+      expect(state.text).toBe(EXPECTED_TEXT);
+    });
+
+    it('correctly counts lines across frame boundaries', () => {
+      const { element, result } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      // Place caret at start of line 9 ("    </div>") — first line of frame 2
+      // Lines 1-8 occupy chars: count up to the start of "    </div>"
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 8; i += 1) {
+        offset += lines[i].length + 1; // +1 for the newline
+      }
+      placeCaret(element, offset);
+
+      const state = result.current.getState();
+      expect(state.position.line).toBe(8); // 0-indexed
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Caret positioning across frame boundaries
+  // -------------------------------------------------------------------------
+  describe('caret positioning across frames', () => {
+    it('positions caret at the last character of frame 0 (before frame 1)', () => {
+      const { element, result } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      // End of line 6: "    <div>" + newline
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 6; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      // offset is now at the start of line 7, go one back to end of line 6
+      offset -= 1;
+      placeCaret(element, offset);
+
+      const state = result.current.getState();
+      expect(state.position.line).toBe(5); // line 6 is 0-indexed as 5
+    });
+
+    it('positions caret at the first character of frame 1', () => {
+      const { element, result } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      // Start of line 7: "      <Checkbox ..."
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 6; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      placeCaret(element, offset);
+
+      const state = result.current.getState();
+      expect(state.position.line).toBe(6); // 0-indexed line 7
+      expect(state.position.position).toBe(offset);
+    });
+
+    it('positions caret at the last character of frame 1 (before frame 2)', () => {
+      const { element, result } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 8; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      // offset is at start of line 9, go back 1 for end of line 8
+      offset -= 1;
+      placeCaret(element, offset);
+
+      const state = result.current.getState();
+      expect(state.position.line).toBe(7); // 0-indexed: line 8
+    });
+
+    it('positions caret at the first character of frame 2', () => {
+      const { element, result } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 8; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      placeCaret(element, offset);
+
+      const state = result.current.getState();
+      expect(state.position.line).toBe(8); // 0-indexed: line 9
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Empty line within frame (line 3 in frame 0)
+  // -------------------------------------------------------------------------
+  describe('empty line within a frame', () => {
+    it('positions caret on the empty line 3', () => {
+      const { element, result } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      // Line 3 is empty — offset is after line 1 + \n + line 2 + \n
+      const lines = EXPECTED_TEXT.split('\n');
+      const offset = lines[0].length + 1 + lines[1].length + 1;
+      placeCaret(element, offset);
+
+      const state = result.current.getState();
+      expect(state.position.line).toBe(2); // 0-indexed line 3
+      expect(state.position.content).toBe('');
+    });
+
+    it('inserts a character on the empty line', async () => {
+      const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      const offset = lines[0].length + 1 + lines[1].length + 1;
+      placeCaret(element, offset);
+
+      await userEvent.keyboard('x');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      // The 'x' should appear on the previously empty line 3
+      const resultLines = text.split('\n');
+      expect(resultLines[2]).toBe('x');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Typing at frame boundaries
+  // -------------------------------------------------------------------------
+  describe('typing at frame boundaries', () => {
+    it('types at the end of frame 0 (just before frame 1)', async () => {
+      const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      // End of line 6 content (before its newline)
+      let offset = 0;
+      for (let i = 0; i < 5; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      offset += lines[5].length; // at end of "    <div>" text
+      placeCaret(element, offset);
+
+      await userEvent.keyboard('X');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      // The 'X' should appear at end of the "<div>" line
+      const resultLines = text.split('\n');
+      expect(resultLines[5]).toBe('    <div>X');
+    });
+
+    it('types at the start of frame 1 (first highlighted line)', async () => {
+      const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 6; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      placeCaret(element, offset);
+
+      await userEvent.keyboard('Y');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      const resultLines = text.split('\n');
+      // 'Y' appears at beginning of what was line 7
+      expect(resultLines[6]).toMatch(/^Y/);
+    });
+
+    it('types at the end of frame 1 (just before frame 2)', async () => {
+      const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 7; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      offset += lines[7].length; // end of line 8 content
+      placeCaret(element, offset);
+
+      await userEvent.keyboard('Z');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      const resultLines = text.split('\n');
+      expect(resultLines[7]).toMatch(/Z$/);
+    });
+
+    it('types at the start of frame 2 (first line after highlighted frame)', async () => {
+      const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 8; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      placeCaret(element, offset);
+
+      await userEvent.keyboard('W');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      const resultLines = text.split('\n');
+      expect(resultLines[8]).toMatch(/^W/);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Backspace at frame boundaries
+  // -------------------------------------------------------------------------
+  describe('backspace at frame boundaries', () => {
+    it('deletes at the start of frame 1 (merges with end of frame 0)', async () => {
+      const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 6; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      placeCaret(element, offset);
+
+      await userEvent.keyboard('{Backspace}');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      // The newline between line 6 and 7 should be removed
+      expect(text).not.toBe(EXPECTED_TEXT);
+      // Line 6 and 7 merge
+      expect(text).toContain('<div>      <Checkbox');
+    });
+
+    it('deletes at the start of frame 2 (merges with end of frame 1)', async () => {
+      const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 8; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      placeCaret(element, offset);
+
+      await userEvent.keyboard('{Backspace}');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      // The newline between line 8 and 9 should be removed
+      expect(text).toContain('</p>    </div>');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Enter at frame boundaries
+  // -------------------------------------------------------------------------
+  describe('Enter at frame boundaries', () => {
+    it('inserts newline at end of frame 0', async () => {
+      const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 5; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      offset += lines[5].length; // end of "    <div>"
+      placeCaret(element, offset);
+
+      await userEvent.keyboard('{Enter}');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      const resultLines = text.split('\n');
+      // Should have one more line than original
+      expect(resultLines.length).toBe(EXPECTED_TEXT.split('\n').length + 1);
+    });
+
+    it('inserts newline at the empty line (line 3)', async () => {
+      const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      const offset = lines[0].length + 1 + lines[1].length + 1;
+      placeCaret(element, offset);
+
+      await userEvent.keyboard('{Enter}');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      // Two consecutive empty lines
+      expect(text).toContain("Checkbox';\n\n\nexport");
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // edit.move across frame boundaries
+  // -------------------------------------------------------------------------
+  describe('move across frames', () => {
+    it('moves to a position inside frame 1 by offset', () => {
+      const { element, result } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      // Target: middle of line 7 "      <Checkbox defaultChecked />"
+      let offset = 0;
+      for (let i = 0; i < 6; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      offset += 10; // somewhere inside "<Checkbox"
+
+      act(() => {
+        result.current.move(offset);
+      });
+
+      const state = result.current.getState();
+      expect(state.position.position).toBe(offset);
+      expect(state.position.line).toBe(6);
+      expect(document.activeElement).toBe(element);
+    });
+
+    it('moves to a position by row/column into frame 2', () => {
+      const { result } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+
+      act(() => {
+        // Row 8 (0-indexed) = line 9 "    </div>", column 4 = after "    "
+        result.current.move({ row: 8, column: 4 });
+      });
+
+      const state = result.current.getState();
+      expect(state.position.line).toBe(8);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // edit.update with highlighted DOM
+  // -------------------------------------------------------------------------
+  describe('update with highlighted DOM', () => {
+    it('replaces entire content and calls onChange', () => {
+      const { result, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+
+      act(() => {
+        result.current.update('replaced content\n');
+      });
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(text).toBe('replaced content\n');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // edit.insert inside highlighted content
+  // -------------------------------------------------------------------------
+  describe('insert inside highlighted content', () => {
+    it('inserts text in the middle of a highlighted span', () => {
+      const { element, result } = setupHighlighted(HIGHLIGHTED_HTML, {
+        indentation: 2,
+      });
+      const lines = EXPECTED_TEXT.split('\n');
+      // Position inside "Checkbox" on line 7
+      let offset = 0;
+      for (let i = 0; i < 6; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      offset += 7; // "      <" → right after '<'
+      placeCaret(element, offset);
+
+      act(() => {
+        result.current.insert('MyCustom');
+      });
+
+      // Verify position was updated by flushChanges / MutationObserver
+      const state = result.current.getState();
+      expect(state.text).toContain('<MyCustomCheckbox');
+    });
+
+    it('inserts at the start of frame 2 without expanding the frame wrapper', () => {
+      const { element, result } = setupHighlighted(HIGHLIGHTED_HTML, {
+        indentation: 2,
+      });
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 8; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      placeCaret(element, offset);
+
+      act(() => {
+        result.current.insert('X');
+      });
+
+      const frame = element.querySelector('[data-frame="2"]') as HTMLElement;
+      const line = frame.querySelector('[data-ln="9"]') as HTMLElement;
+
+      expect(frame.firstElementChild).toBe(line);
+      expect(line.textContent).toBe('X    </div>\n');
+
+      const state = result.current.getState();
+      const resultLines = state.text.split('\n');
+      expect(resultLines[8]).toBe('X    </div>');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Paste at frame boundaries
+  // -------------------------------------------------------------------------
+  describe('paste at frame boundaries', () => {
+    it('pastes multiline text at a frame boundary', () => {
+      const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 6; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      placeCaret(element, offset);
+
+      const clipboardData = new DataTransfer();
+      clipboardData.setData('text/plain', '      {/* extra */}\n');
+      element.dispatchEvent(
+        new ClipboardEvent('paste', {
+          bubbles: true,
+          cancelable: true,
+          clipboardData,
+        }),
+      );
+
+      if (onChange.mock.calls.length > 0) {
+        const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+        expect(text).toContain('{/* extra */}');
+      }
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Tab indentation inside highlighted content
+  // -------------------------------------------------------------------------
+  describe('Tab indentation with highlighted content', () => {
+    it('indents a highlighted line with Tab', async () => {
+      const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+      const lines = EXPECTED_TEXT.split('\n');
+      let offset = 0;
+      for (let i = 0; i < 6; i += 1) {
+        offset += lines[i].length + 1;
+      }
+      // Place caret at start of line 7 (highlighted frame)
+      placeCaret(element, offset);
+
+      await userEvent.keyboard('{Tab}');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      const resultLines = text.split('\n');
+      // Line 7 should now have 2 extra spaces of indentation
+      expect(resultLines[6]).toMatch(/^ {8}/);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // getState consistency after multiple operations
+  // -------------------------------------------------------------------------
+  describe('getState consistency with highlighted DOM', () => {
+    it('returns consistent position after typing across multiple frames', async () => {
+      const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, {
+        indentation: 2,
+      });
+
+      // Type in frame 0
+      const lines = EXPECTED_TEXT.split('\n');
+      const line2End = lines[0].length + 1 + lines[1].length;
+      placeCaret(element, line2End);
+      await userEvent.keyboard('A');
+
+      expect(onChange).toHaveBeenCalled();
+      const [text1] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      const newLines = text1.split('\n');
+      expect(newLines[1]).toMatch(/A;?$/);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Firefox newline preservation
+// ---------------------------------------------------------------------------
+describe('useEditable – newline preservation', () => {
+  it('preserves newlines when typing on an indented blank line', async () => {
+    const { element, onChange } = setup('aaa\n  \nbbb\nccc');
+
+    // Place caret at end of the blank indented line (after "  ")
+    // Line 0: "aaa" (0-2), \n (3)
+    // Line 1: "  "  (4-5), \n (6)
+    // Line 2: "bbb" (7-9), \n (10)
+    // Line 3: "ccc" (11-13)
+    placeCaret(element, 6);
+
+    await userEvent.keyboard('x');
+
+    expect(onChange).toHaveBeenCalled();
+    const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+    const lines = text.split('\n');
+    // All 4 lines should still be present (+ trailing newline = 5 entries)
+    expect(lines).toHaveLength(5);
+    expect(lines[0]).toBe('aaa');
+    expect(lines[1]).toBe('  x');
+    expect(lines[2]).toBe('bbb');
+    expect(lines[3]).toBe('ccc');
+  });
+
+  it('preserves newlines when typing on a line in highlighted DOM', async () => {
+    // Simplified highlighted structure with 3 lines: "aaa", "  ", "bbb"
+    const html = [
+      '<code>',
+      '<span class="line" data-ln="1">aaa\n</span>',
+      '<span class="line" data-ln="2">  \n</span>',
+      '<span class="line" data-ln="3">bbb</span>',
+      '</code>',
+    ].join('');
+    const { element, onChange } = setupHighlighted(html);
+
+    // Place caret at end of line 2 (the "  " line)
+    // "aaa\n" = 4 chars, "  " = 2 → offset 6
+    placeCaret(element, 6);
+
+    await userEvent.keyboard('x');
+
+    expect(onChange).toHaveBeenCalled();
+    const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+    const lines = text.split('\n');
+    expect(lines).toHaveLength(4); // 3 lines + trailing newline
+    expect(lines[0]).toBe('aaa');
+    expect(lines[1]).toBe('  x');
+    expect(lines[2]).toBe('bbb');
+  });
+
+  it('preserves newlines when typing on a line between frames', async () => {
+    // Two frames with a line in between
+    const html = [
+      '<code>',
+      '<span class="frame" data-frame="0" data-lined="">',
+      '<span class="line" data-ln="1">aaa\n</span>',
+      '<span class="line" data-ln="2">  \n</span>',
+      '</span>',
+      '<span class="frame" data-frame="1" data-lined="">',
+      '<span class="line" data-ln="3">bbb</span>',
+      '</span>',
+      '</code>',
+    ].join('');
+    const { element, onChange } = setupHighlighted(html);
+
+    placeCaret(element, 6);
+
+    await userEvent.keyboard('x');
+
+    expect(onChange).toHaveBeenCalled();
+    const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+    const lines = text.split('\n');
+    expect(lines).toHaveLength(4);
+    expect(lines[0]).toBe('aaa');
+    expect(lines[1]).toBe('  x');
+    expect(lines[2]).toBe('bbb');
+  });
+
+  it('preserves newlines when typing on the empty line of production highlighted DOM', async () => {
+    const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+
+    // Place caret on the empty line 3 (0-indexed line 2)
+    const lines = EXPECTED_TEXT.split('\n');
+    const offset = lines[0].length + 1 + lines[1].length + 1;
+    placeCaret(element, offset);
+
+    await userEvent.keyboard('x');
+
+    expect(onChange).toHaveBeenCalled();
+    const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+    const resultLines = text.split('\n');
+    // Line count should be the same (character typed on existing empty line)
+    expect(resultLines.length).toBe(EXPECTED_TEXT.split('\n').length);
+    // The empty line should now have 'x'
+    expect(resultLines[2]).toBe('x');
+    // Adjacent lines preserved
+    expect(resultLines[1]).toBe("import { Checkbox } from '@/components/Checkbox';");
+    expect(resultLines[3]).toBe('export default function CheckboxBasic() {');
+  });
+
+  it('preserves newlines when typing on line 9 (after </p>, first line of frame 2)', async () => {
+    // Production highlighted HTML — newlines are inside line spans.
+    const productionHTML =
+      '<code>' +
+      '<span class="frame" data-frame="0" data-lined="">' +
+      '<span class="line" data-ln="1"><span class="pl-k">import</span> <span class="pl-c1">*</span> <span class="pl-k">as</span> <span class="pl-smi">React</span> <span class="pl-k">from</span> <span class="pl-s"><span class="pl-pds">\'</span>react<span class="pl-pds">\'</span></span>;\n</span>' +
+      '<span class="line" data-ln="2"><span class="pl-k">import</span> { <span class="pl-smi">Checkbox</span> } <span class="pl-k">from</span> <span class="pl-s"><span class="pl-pds">\'</span>@/components/Checkbox<span class="pl-pds">\'</span></span>;\n</span>' +
+      '<span class="line" data-ln="3">\n</span>' +
+      '<span class="line" data-ln="4"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">CheckboxBasic</span>() {\n</span>' +
+      '<span class="line" data-ln="5">  <span class="pl-k">return</span> (\n</span>' +
+      '<span class="line" data-ln="6">    &lt;<span class="pl-ent">div</span>&gt;\n</span>' +
+      '</span>' +
+      '<span class="frame" data-frame="1" data-frame-type="highlighted" data-frame-indent="3" data-lined="">' +
+      '<span class="line" data-ln="7" data-hl="" data-hl-position="start">      &lt;<span class="pl-c1">Checkbox</span> <span class="pl-e">defaultChecked</span> /&gt;\n</span>' +
+      '<span class="line" data-ln="8" data-hl="" data-hl-position="end">      &lt;<span class="pl-ent">p</span> <span class="pl-e">style</span><span class="pl-k">=</span><span class="pl-pse">{</span>{ color: <span class="pl-s"><span class="pl-pds">\'</span>#CA244D<span class="pl-pds">\'</span></span> }<span class="pl-pse">}</span>&gt;Type Whatever You Want Below&lt;/<span class="pl-ent">p</span>&gt;\n</span>' +
+      '</span>' +
+      '<span class="frame" data-frame="2" data-lined="">' +
+      '<span class="line" data-ln="9">    &lt;/<span class="pl-ent">div</span>&gt;\n</span>' +
+      '<span class="line" data-ln="10">  );\n</span>' +
+      '<span class="line" data-ln="11">}</span>' +
+      '</span>' +
+      '</code>';
+
+    const { element, onChange } = setupHighlighted(productionHTML, { indentation: 2 });
+
+    // Compute offset to start of line 9 (0-indexed line 8): "    </div>"
+    // Lines 1-8 text + their newlines
+    const expectedLines = EXPECTED_TEXT.split('\n');
+    let offset = 0;
+    for (let i = 0; i < 8; i += 1) {
+      offset += expectedLines[i].length + 1;
+    }
+    // offset is at start of "    </div>" — place caret at end of the indentation
+    offset += 4;
+    placeCaret(element, offset);
+
+    await userEvent.keyboard('x');
+
+    expect(onChange).toHaveBeenCalled();
+    const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+    const resultLines = text.split('\n');
+    // All 11 lines should still be present (+ trailing newline = 12 entries)
+    expect(resultLines).toHaveLength(12);
+    // Line 9 should have the inserted 'x'
+    expect(resultLines[8]).toBe('    x</div>');
+    // Adjacent lines must not merge
+    expect(resultLines[7]).toContain('Type Whatever You Want Below</p>');
+    expect(resultLines[9]).toBe('  );');
+    expect(resultLines[10]).toBe('}');
+  });
+
+  it('keeps the </p> line and following </div> line separate when typing after </p>', async () => {
+    const { element, onChange } = setupHighlighted(HIGHLIGHTED_HTML, { indentation: 2 });
+
+    const lines = EXPECTED_TEXT.split('\n');
+    let offset = 0;
+    for (let i = 0; i < 7; i += 1) {
+      offset += lines[i].length + 1;
+    }
+    offset += lines[7].length;
+    placeCaret(element, offset);
+
+    await userEvent.keyboard('x');
+
+    expect(onChange).toHaveBeenCalled();
+    const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+    const resultLines = text.split('\n');
+
+    expect(resultLines).toHaveLength(EXPECTED_TEXT.split('\n').length);
+    expect(resultLines[7]).toBe(
+      "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>x",
+    );
+    expect(resultLines[8]).toBe('    </div>');
+    expect(resultLines[9]).toBe('  );');
+  });
+
+  it('keeps typed text at the end of a line that starts a new frame after a highlighted frame', async () => {
+    const { element, onChange } = setupHighlighted(FRAME_BOUNDARY_HTML, { indentation: 2 });
+
+    const lines = EXPECTED_TEXT.split('\n');
+    let offset = 0;
+    for (let i = 0; i < 7; i += 1) {
+      offset += lines[i].length + 1;
+    }
+    offset += lines[7].length;
+    placeCaret(element, offset);
+
+    await userEvent.keyboard('x');
+
+    expect(onChange).toHaveBeenCalled();
+    const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+    const resultLines = text.split('\n');
+
+    expect(resultLines[7]).toBe(
+      "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>x",
+    );
+    expect(resultLines[8]).toBe('    </div>');
+    expect(resultLines[9]).toBe('  );');
+  });
+
+  it('preserves newlines when contentEditable falls back to "true" (old Firefox)', async () => {
+    // Simulate old Firefox that doesn't support plaintext-only by forcing
+    // contentEditable="true" before the hook sets it.
+    const productionHTML =
+      '<code>' +
+      '<span class="frame" data-frame="0" data-lined="">' +
+      '<span class="line" data-ln="1"><span class="pl-k">import</span> <span class="pl-c1">*</span> <span class="pl-k">as</span> <span class="pl-smi">React</span> <span class="pl-k">from</span> <span class="pl-s"><span class="pl-pds">\'</span>react<span class="pl-pds">\'</span></span>;\n</span>' +
+      '<span class="line" data-ln="2"><span class="pl-k">import</span> { <span class="pl-smi">Checkbox</span> } <span class="pl-k">from</span> <span class="pl-s"><span class="pl-pds">\'</span>@/components/Checkbox<span class="pl-pds">\'</span></span>;\n</span>' +
+      '<span class="line" data-ln="3">\n</span>' +
+      '<span class="line" data-ln="4"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">CheckboxBasic</span>() {\n</span>' +
+      '<span class="line" data-ln="5">  <span class="pl-k">return</span> (\n</span>' +
+      '<span class="line" data-ln="6">    &lt;<span class="pl-ent">div</span>&gt;\n</span>' +
+      '</span>' +
+      '<span class="frame" data-frame="1" data-frame-type="highlighted" data-frame-indent="3" data-lined="">' +
+      '<span class="line" data-ln="7" data-hl="" data-hl-position="start">      &lt;<span class="pl-c1">Checkbox</span> <span class="pl-e">defaultChecked</span> /&gt;\n</span>' +
+      '<span class="line" data-ln="8" data-hl="" data-hl-position="end">      &lt;<span class="pl-ent">p</span> <span class="pl-e">style</span><span class="pl-k">=</span><span class="pl-pse">{</span>{ color: <span class="pl-s"><span class="pl-pds">\'</span>#CA244D<span class="pl-pds">\'</span></span> }<span class="pl-pse">}</span>&gt;Type Whatever You Want Below&lt;/<span class="pl-ent">p</span>&gt;\n</span>' +
+      '</span>' +
+      '<span class="frame" data-frame="2" data-lined="">' +
+      '<span class="line" data-ln="9">    &lt;/<span class="pl-ent">div</span>&gt;\n</span>' +
+      '<span class="line" data-ln="10">  );\n</span>' +
+      '<span class="line" data-ln="11">}</span>' +
+      '</span>' +
+      '</code>';
+
+    const element = document.createElement('pre');
+    // Force contentEditable="true" — simulates Firefox < 130
+    element.contentEditable = 'true';
+    element.style.whiteSpace = 'pre-wrap';
+    element.style.tabSize = '2';
+    element.innerHTML = productionHTML;
+    document.body.appendChild(element);
+
+    // Monkey-patch the element to make "plaintext-only" throw, simulating old Firefox
+    let contentEditableValue = 'true';
+    Object.defineProperty(element, 'contentEditable', {
+      get() {
+        return contentEditableValue;
+      },
+      set(value: string) {
+        if (value === 'plaintext-only') {
+          throw new DOMException(
+            "Failed to set 'contentEditable': 'plaintext-only' is not supported",
+          );
+        }
+        contentEditableValue = value;
+      },
+      configurable: true,
+    });
+
+    const ref = { current: element };
+    const onChange = vi.fn<(text: string, position: Position) => void>();
+
+    renderHook((props) => useEditable(props.ref, props.onChange, props.opts), {
+      initialProps: { ref, onChange, opts: { indentation: 2 } },
+    });
+
+    // Verify we're in "true" mode (not plaintext-only)
+    expect(element.contentEditable).toBe('true');
+
+    // Place caret on line 9 ("    </div>") — after the indentation
+    const expectedLines = EXPECTED_TEXT.split('\n');
+    let offset = 0;
+    for (let i = 0; i < 8; i += 1) {
+      offset += expectedLines[i].length + 1;
+    }
+    offset += 4;
+    placeCaret(element, offset);
+
+    await userEvent.keyboard('x');
+
+    expect(onChange).toHaveBeenCalled();
+    const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+    const resultLines = text.split('\n');
+    // All 11 lines should be preserved (+ trailing newline = 12 entries)
+    expect(resultLines).toHaveLength(12);
+    expect(resultLines[8]).toBe('    x</div>');
+    expect(resultLines[7]).toContain('Type Whatever You Want Below</p>');
+    expect(resultLines[9]).toBe('  );');
+  });
+
+  it('keeps typed text inside the current line when fallback mode types at column 0', async () => {
+    const productionHTML =
+      '<code>' +
+      '<span class="frame" data-frame="0" data-lined="">' +
+      '<span class="line" data-ln="1"><span class="pl-k">import</span> <span class="pl-c1">*</span> <span class="pl-k">as</span> <span class="pl-smi">React</span> <span class="pl-k">from</span> <span class="pl-s"><span class="pl-pds">\'</span>react<span class="pl-pds">\'</span></span>;\n</span>' +
+      '<span class="line" data-ln="2"><span class="pl-k">import</span> { <span class="pl-smi">Checkbox</span> } <span class="pl-k">from</span> <span class="pl-s"><span class="pl-pds">\'</span>@/components/Checkbox<span class="pl-pds">\'</span></span>;\n</span>' +
+      '<span class="line" data-ln="3">\n</span>' +
+      '<span class="line" data-ln="4"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">CheckboxBasic</span>() {\n</span>' +
+      '<span class="line" data-ln="5">  <span class="pl-k">return</span> (\n</span>' +
+      '<span class="line" data-ln="6">    &lt;<span class="pl-ent">div</span>&gt;\n</span>' +
+      '</span>' +
+      '<span class="frame" data-frame="1" data-frame-type="highlighted" data-frame-indent="3" data-lined="">' +
+      '<span class="line" data-ln="7" data-hl="" data-hl-position="start">      &lt;<span class="pl-c1">Checkbox</span> <span class="pl-e">defaultChecked</span> /&gt;\n</span>' +
+      '<span class="line" data-ln="8" data-hl="" data-hl-position="end">      &lt;<span class="pl-ent">p</span> <span class="pl-e">style</span><span class="pl-k">=</span><span class="pl-pse">{</span>{ color: <span class="pl-s"><span class="pl-pds">\'</span>#CA244D<span class="pl-pds">\'</span></span> }<span class="pl-pse">}</span>&gt;Type Whatever You Want Below&lt;/<span class="pl-ent">p</span>&gt;\n</span>' +
+      '</span>' +
+      '<span class="frame" data-frame="2" data-lined="">' +
+      '<span class="line" data-ln="9">    &lt;/<span class="pl-ent">div</span>&gt;\n</span>' +
+      '<span class="line" data-ln="10">  );\n</span>' +
+      '<span class="line" data-ln="11">}</span>' +
+      '</span>' +
+      '</code>';
+
+    const element = document.createElement('pre');
+    element.contentEditable = 'true';
+    element.style.whiteSpace = 'pre-wrap';
+    element.style.tabSize = '2';
+    element.innerHTML = productionHTML;
+    document.body.appendChild(element);
+
+    let contentEditableValue = 'true';
+    Object.defineProperty(element, 'contentEditable', {
+      get() {
+        return contentEditableValue;
+      },
+      set(value: string) {
+        if (value === 'plaintext-only') {
+          throw new DOMException(
+            "Failed to set 'contentEditable': 'plaintext-only' is not supported",
+          );
+        }
+        contentEditableValue = value;
+      },
+      configurable: true,
+    });
+
+    const ref = { current: element };
+    const onChange = vi.fn<(text: string, position: Position) => void>();
+
+    renderHook((props) => useEditable(props.ref, props.onChange, props.opts), {
+      initialProps: { ref, onChange, opts: { indentation: 2 } },
+    });
+
+    const expectedLines = EXPECTED_TEXT.split('\n');
+    let offset = 0;
+    for (let i = 0; i < 8; i += 1) {
+      offset += expectedLines[i].length + 1;
+    }
+    placeCaret(element, offset);
+
+    const keyDown = new KeyboardEvent('keydown', {
+      key: 'x',
+      code: 'KeyX',
+      bubbles: true,
+      cancelable: true,
+    });
+    element.dispatchEvent(keyDown);
+
+    const frame = element.querySelector('[data-frame="2"]') as HTMLElement;
+    const line = frame.querySelector('[data-ln="9"]') as HTMLElement;
+
+    expect(keyDown.defaultPrevented).toBe(true);
+    expect(frame.firstElementChild).toBe(line);
+    expect(line.textContent).toBe('x    </div>\n');
+    expect(frame.firstChild).not.toHaveTextContent(/^x$/);
+
+    const keyUp = new KeyboardEvent('keyup', {
+      key: 'x',
+      code: 'KeyX',
+      bubbles: true,
+      cancelable: true,
+    });
+    element.dispatchEvent(keyUp);
+
+    expect(onChange).toHaveBeenCalled();
+    const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+    const resultLines = text.split('\n');
+    expect(resultLines[8]).toBe('x    </div>');
+  });
+
+  it('backspace on a blank-only line removes one indent unit and cursor stays on the line', async () => {
+    // Start with a 3-line highlighted DOM where line 2 has 2 spaces of indentation
+    const html = [
+      '<code>',
+      '<span class="line" data-ln="1">aaa\n</span>',
+      '<span class="line" data-ln="2">  \n</span>',
+      '<span class="line" data-ln="3">bbb</span>',
+      '</code>',
+    ].join('');
+    const { onChange } = setupHighlighted(html, { indentation: 2 });
+
+    // Place caret at end of the 2-space indent on line 2
+    // "aaa\n" = 4 chars, "  " = 2 → offset 6
+    placeCaret(document.querySelector('pre')!, 6);
+
+    // Press Backspace — should remove the 2 spaces (one indent unit)
+    await userEvent.keyboard('{Backspace}');
+
+    expect(onChange).toHaveBeenCalled();
+    const [text, position] = onChange.mock.calls[onChange.mock.calls.length - 1];
+    const lines = text.split('\n');
+    // Line 2 should now be empty
+    expect(lines[1]).toBe('');
+    // Total lines: 3 + trailing newline = 4 entries
+    expect(lines).toHaveLength(4);
+    // Cursor should report line 1 (0-indexed), not line 0
+    expect(position.line).toBe(1);
+    expect(position.content).toBe('');
+  });
+
+  it('cursor is visually on the empty line after move(), not the line above', async () => {
+    // DOM where line 2 is empty (just \n) — simulates the state after
+    // backspace removes all indentation from a blank line.
+    const html = [
+      '<code>',
+      '<span class="line" data-ln="1">aaa\n</span>',
+      '<span class="line" data-ln="2">\n</span>',
+      '<span class="line" data-ln="3">bbb</span>',
+      '</code>',
+    ].join('');
+    const { result } = setupHighlighted(html);
+
+    // Position cursor at the start of line 2 (the empty line)
+    // "aaa\n" = 4 chars → offset 4
+    act(() => {
+      result.current.move(4);
+    });
+
+    // Check that the selection is positioned inside line 2's span
+    // (the empty line), NOT inside line 1's span.
+    const sel = window.getSelection()!;
+    const focusNode = sel.focusNode!;
+    // adjustCursorAtNewlineBoundary advances the cursor past the \n
+    // to the next text node. Since line 2 has no text (only \n), the
+    // focusNode may be in line 2's span or in line 3's text.
+    let lineSpan: Element | null;
+    if (focusNode.nodeType === Node.TEXT_NODE) {
+      lineSpan = focusNode.parentElement;
+    } else {
+      lineSpan = focusNode as Element;
+      // If focusNode is a line span itself, use it directly.
+      // Otherwise walk up to find the closest line span.
+      if (!lineSpan.getAttribute('data-ln')) {
+        lineSpan = lineSpan.closest('[data-ln]');
+      }
+    }
+    const ln = Number(lineSpan!.getAttribute('data-ln'));
+    // Cursor must NOT be on line 1
+    expect(ln).toBeGreaterThanOrEqual(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Disconnected-window arrow regression (no boundary involved)
+// ---------------------------------------------------------------------------
+describe('useEditable – arrow keys during the disconnected window', () => {
+  it('a plain ArrowDown right after Enter (no onBoundary) is not reverted by the post-flush rerender', async () => {
+    // No `minRow`/`maxRow`/`onBoundary` here — just plain editing. The
+    // race we care about: Enter → flushChanges() disconnects, ArrowDown
+    // fires while `state.disconnected` is still true, the fast-path
+    // calls `unblock([])` to nudge React, and the resulting layout-
+    // effect must NOT snap the caret back to the pre-arrow line.
+    const element = document.createElement('pre');
+    element.contentEditable = 'plaintext-only';
+    element.style.whiteSpace = 'pre-wrap';
+    document.body.appendChild(element);
+    element.textContent = 'line1\nline2\nline3\n';
+
+    const ref = { current: element };
+    const onChange = vi.fn<(text: string, position: Position) => void>();
+    const { unmount } = renderHook((props) => useEditable(props.ref, props.onChange, props.opts), {
+      initialProps: { ref, onChange, opts: {} as { indentation?: number } },
+    });
+
+    try {
+      // Place the caret at the end of line 1.
+      placeCaret(element, 'line1'.length);
+      await userEvent.keyboard('{Enter}');
+      // After Enter the caret is at the start of line 2 (a blank line
+      // between line1 and line2 — Enter splits the text).
+      await userEvent.keyboard('{ArrowDown}');
+
+      // Walk to caret to compute the visual line.
+      const sel = window.getSelection()!;
+      const range = sel.getRangeAt(0);
+      const pre = document.createRange();
+      pre.setStart(element, 0);
+      pre.setEnd(range.startContainer, range.startOffset);
+      const globalOffset = pre.toString().length;
+      const fullText = element.textContent ?? '';
+      const computedLine = fullText.slice(0, globalOffset).split('\n').length - 1;
+
+      // After Enter the caret is at the start of the new blank line
+      // (row 1) between `line1` and `line2`. A correctly-handled
+      // ArrowDown moves the caret down exactly one visual line, landing
+      // at row 2 (`line2`). Asserting the exact target row catches both
+      // the original snap-back regression (caret rebounds to row 0) and
+      // any accidental overshoot (caret skips past row 2).
+      expect(computedLine).toBe(2);
+    } finally {
+      unmount();
+      element.remove();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Focus-frame ArrowUp regression
+// ---------------------------------------------------------------------------
+describe('useEditable – focus frame ArrowUp after Enter', () => {
+  /**
+   * Render `text` as a flat list of `.line` spans separated by literal `\n`
+   * text-node gaps — the same shape the production highlighter emits when the
+   * editable is mounted.
+   */
+  function renderLines(element: HTMLElement, text: string) {
+    const lines = text.split('\n');
+    // The hook's `toString()` adds a trailing `\n` if missing — match it.
+    const visibleLines = lines[lines.length - 1] === '' ? lines.slice(0, -1) : lines;
+    element.replaceChildren();
+    visibleLines.forEach((lineText, idx) => {
+      if (idx > 0) {
+        element.appendChild(document.createTextNode('\n'));
+      }
+      const line = document.createElement('span');
+      line.className = 'line';
+      line.setAttribute('data-ln', String(idx + 1));
+      line.textContent = lineText;
+      element.appendChild(line);
+    });
+  }
+
+  // Firefox computes the default-action target of arrow keys from the
+  // selection at the time the keydown was queued, so when we restore the
+  // caret inside the keydown handler the native ArrowUp doesn't see it.
+  // The user-visible bug below still requires fixing for Chromium/WebKit
+  // (where the vast majority of editors run) — Firefox needs a separate
+  // workaround that's tracked outside this regression test.
+  const isFirefox = typeof navigator !== 'undefined' && /Firefox\//i.test(navigator.userAgent);
+
+  it.skipIf(isFirefox)(
+    'reproduces: Enter at end of a focus-frame line then ArrowUp twice should land outside the frame',
+    async () => {
+      // Mirrors the user's example:
+      //   import * as React from 'react';
+      //   import { Checkbox } from '@/components/Checkbox';
+      //
+      //   export default function CheckboxBasic() {
+      //     return (
+      //       <div>
+      //         <Checkbox defaultChecked />          ← focus frame line 7
+      //         <p style={{ color: '#CA244D' }}>...  ← focus frame line 8
+      //       </div>
+      //     );
+      //   }
+      const initialText = [
+        "import * as React from 'react';",
+        "import { Checkbox } from '@/components/Checkbox';",
+        '',
+        'export default function CheckboxBasic() {',
+        '  return (',
+        '    <div>',
+        '      <Checkbox defaultChecked />',
+        "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>",
+        '    </div>',
+        '  );',
+        '}',
+      ].join('\n');
+
+      const element = document.createElement('pre');
+      element.contentEditable = 'plaintext-only';
+      element.style.whiteSpace = 'pre-wrap';
+      element.style.tabSize = '2';
+      document.body.appendChild(element);
+      renderLines(element, initialText);
+
+      // The host's onBoundary in production is `expand`, which calls setState
+      // and triggers a React re-render that drops the collapsed bounds.
+      // Reproduce that here so the unconditional layout effect inside
+      // `useEditable` re-runs mid-arrow-keypress, which is what was snapping
+      // the caret back to the pre-ArrowUp `state.position`.
+      let expanded = false;
+      let triggerRerender = () => {};
+      const onBoundary = vi.fn(() => {
+        expanded = true;
+        triggerRerender();
+      });
+
+      const collapsedOpts = {
+        indentation: 2,
+        minColumn: 6,
+        minRow: 6,
+        maxRow: 7,
+        onBoundary,
+        caretSelector: '.line',
+      };
+      const expandedOpts = {
+        indentation: 2,
+        onBoundary,
+        caretSelector: '.line',
+      };
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>((newText: string) => {
+        // Simulate the host re-render: replay a fresh `.line` DOM structure
+        // for the new content. This is what `Pre.tsx` does via React when
+        // `setSource` is called from inside `useEditable`.
+        renderLines(element, newText);
+      });
+
+      const { unmount, rerender } = renderHook(
+        (props) => useEditable(props.ref, props.onChange, props.opts),
+        { initialProps: { ref, onChange, opts: collapsedOpts as typeof expandedOpts } },
+      );
+      triggerRerender = () => {
+        rerender({ ref, onChange, opts: expanded ? expandedOpts : collapsedOpts });
+      };
+
+      try {
+        element.focus();
+        // Place caret at the END of line 7 (`<Checkbox defaultChecked />`).
+        const line7Text = '      <Checkbox defaultChecked />';
+        const offset = [
+          "import * as React from 'react';",
+          "import { Checkbox } from '@/components/Checkbox';",
+          '',
+          'export default function CheckboxBasic() {',
+          '  return (',
+          '    <div>',
+          line7Text,
+        ].join('\n').length;
+        placeCaret(element, offset);
+
+        // Press Enter, then ArrowUp twice — exactly the user's repro.
+        await userEvent.keyboard('{Enter}');
+        await userEvent.keyboard('{ArrowUp}');
+        await userEvent.keyboard('{ArrowUp}');
+
+        // Inspect where the caret ended up.
+        const sel = window.getSelection()!;
+        const range = sel.getRangeAt(0);
+
+        // Build a global offset to derive the visual line/column of the caret.
+        const pre = document.createRange();
+        pre.setStart(element, 0);
+        pre.setEnd(range.startContainer, range.startOffset);
+        const globalOffset = pre.toString().length;
+        const fullText = element.textContent ?? '';
+        const linesUpTo = fullText.slice(0, globalOffset).split('\n');
+        const computedLine = linesUpTo.length - 1;
+
+        // After Enter (caret on new blank line 8), ArrowUp #1 should move the
+        // caret to line 7 (`<Checkbox defaultChecked />`, 0-indexed row 6 =
+        // minRow). ArrowUp #2 from minRow should escape upward to row 5
+        // (`    <div>`) and invoke `onBoundary` to expand the host. Without
+        // the fix, the first ArrowUp gets eaten by the `state.disconnected`
+        // branch and the user only navigates one line instead of two.
+        expect(computedLine).toBe(5);
+        expect(onBoundary).toHaveBeenCalled();
+      } finally {
+        unmount();
+        element.remove();
+      }
+    },
+  );
+});
diff --git a/packages/docs-infra/src/useCode/useEditable.test.ts b/packages/docs-infra/src/useCode/useEditable.test.ts
new file mode 100644
index 000000000..6c21944dc
--- /dev/null
+++ b/packages/docs-infra/src/useCode/useEditable.test.ts
@@ -0,0 +1,3147 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useEditable, type Position } from './useEditable';
+
+/**
+ * Helper: place the browser selection (caret) at a given character offset
+ * inside `element` so that `getPosition()` inside useEditable can read it.
+ */
+function placeSelection(element: HTMLElement, offset: number, extent = 0) {
+  const range = document.createRange();
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+  let current = 0;
+  let startSet = false;
+
+  while (walker.nextNode()) {
+    const node = walker.currentNode;
+    const len = node.textContent!.length;
+
+    if (!startSet && current + len >= offset) {
+      range.setStart(node, offset - current);
+      startSet = true;
+      if (extent === 0) {
+        range.collapse(true);
+        break;
+      }
+    }
+    if (startSet && current + len >= offset + extent) {
+      range.setEnd(node, offset + extent - current);
+      break;
+    }
+    current += len;
+  }
+
+  const selection = window.getSelection()!;
+  selection.removeAllRanges();
+  selection.addRange(range);
+}
+
+/**
+ * Renders `useEditable` bound to a real `<pre>` element and returns helpers.
+ */
+function setup(
+  initialContent: string,
+  opts: {
+    disabled?: boolean;
+    indentation?: number;
+    minColumn?: number;
+    minRow?: number;
+    maxRow?: number;
+    onBoundary?: () => void;
+    caretSelector?: string;
+  } = {},
+) {
+  const element = document.createElement('pre');
+  element.textContent = initialContent;
+  document.body.appendChild(element);
+
+  const ref = { current: element };
+  const onChange = vi.fn<(text: string, position: Position) => void>();
+
+  const { result, unmount } = renderHook(
+    (props) => useEditable(props.ref, props.onChange, props.opts),
+    {
+      initialProps: { ref, onChange, opts },
+    },
+  );
+
+  // Place the caret at position 0 by default
+  placeSelection(element, 0);
+
+  return { element, ref, onChange, result, unmount };
+}
+
+afterEach(() => {
+  document.body.innerHTML = '';
+  window.getSelection()?.removeAllRanges();
+});
+
+// ---------------------------------------------------------------------------
+// Basic hook contract
+// ---------------------------------------------------------------------------
+describe('useEditable', () => {
+  describe('hook return value', () => {
+    it('returns an Edit object with update, insert, move, and getState', () => {
+      const { result } = setup('hello');
+      expect(result.current).toHaveProperty('update');
+      expect(result.current).toHaveProperty('insert');
+      expect(result.current).toHaveProperty('move');
+      expect(result.current).toHaveProperty('getState');
+      expect(typeof result.current.update).toBe('function');
+      expect(typeof result.current.insert).toBe('function');
+      expect(typeof result.current.move).toBe('function');
+      expect(typeof result.current.getState).toBe('function');
+    });
+
+    it('returns a referentially stable Edit object across re-renders', () => {
+      const element = document.createElement('pre');
+      element.textContent = 'hello';
+      document.body.appendChild(element);
+      const ref = { current: element };
+      const onChange = vi.fn();
+
+      const { result, rerender } = renderHook((props) => useEditable(props.ref, props.onChange), {
+        initialProps: { ref, onChange },
+      });
+
+      const first = result.current;
+      rerender({ ref, onChange });
+      expect(result.current).toBe(first);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Element setup / teardown
+  // ---------------------------------------------------------------------------
+  describe('element configuration', () => {
+    it('sets contentEditable on the element', () => {
+      const { element } = setup('hello');
+      // Should be 'plaintext-only' if supported, or 'true'
+      expect(['plaintext-only', 'true']).toContain(element.contentEditable);
+    });
+
+    it('sets whiteSpace to pre-wrap if not already pre', () => {
+      const { element } = setup('hello');
+      expect(element.style.whiteSpace).toBe('pre-wrap');
+    });
+
+    it('preserves whiteSpace when already set to pre', () => {
+      const element = document.createElement('pre');
+      element.style.whiteSpace = 'pre';
+      element.textContent = 'hello';
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn();
+      renderHook(() => useEditable(ref, onChange));
+
+      expect(element.style.whiteSpace).toBe('pre');
+    });
+
+    it('restores element styles on unmount', () => {
+      const element = document.createElement('pre');
+      element.style.whiteSpace = 'normal';
+      element.contentEditable = 'false';
+      element.textContent = 'hello';
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn();
+      const { unmount } = renderHook(() => useEditable(ref, onChange));
+
+      unmount();
+
+      expect(element.style.whiteSpace).toBe('normal');
+      expect(element.contentEditable).toBe('false');
+    });
+
+    it('sets tabSize when indentation option is provided', () => {
+      const { element } = setup('hello', { indentation: 4 });
+      expect(element.style.tabSize).toBe('4');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // disabled option
+  // ---------------------------------------------------------------------------
+  describe('disabled option', () => {
+    it('does not set contentEditable when disabled', () => {
+      const element = document.createElement('pre');
+      element.contentEditable = 'inherit';
+      element.textContent = 'hello';
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn();
+      renderHook(() => useEditable(ref, onChange, { disabled: true }));
+
+      expect(element.contentEditable).toBe('inherit');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // edit.getState
+  // ---------------------------------------------------------------------------
+  describe('getState', () => {
+    it('returns text content with trailing newline', () => {
+      const { result, element } = setup('hello');
+      placeSelection(element, 0);
+      const state = result.current.getState();
+      expect(state.text).toBe('hello\n');
+    });
+
+    it('returns current position', () => {
+      const { result, element } = setup('hello');
+      placeSelection(element, 3);
+      const state = result.current.getState();
+      expect(state.position.position).toBe(3);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // edit.update
+  // ---------------------------------------------------------------------------
+  describe('update', () => {
+    it('calls onChange with new content', () => {
+      const { result, element, onChange } = setup('hello');
+      placeSelection(element, 5);
+
+      act(() => {
+        result.current.update('hello world');
+      });
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      const [text] = onChange.mock.calls[0];
+      expect(text).toBe('hello world');
+    });
+
+    it('adjusts position based on content length difference', () => {
+      const { result, element, onChange } = setup('hello');
+      placeSelection(element, 5);
+
+      act(() => {
+        result.current.update('hello world');
+      });
+
+      const [, position] = onChange.mock.calls[0];
+      // Original position was 5, added 6 chars (' world'), so new position = 5 + (11 - 6) = 10
+      expect(position.position).toBe(5 + ('hello world'.length - 'hello\n'.length));
+    });
+
+    it('does nothing when element ref is null', () => {
+      const element = document.createElement('pre');
+      element.textContent = 'hello';
+      document.body.appendChild(element);
+
+      const ref: { current: HTMLElement | null } = { current: element };
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useEditable(ref, onChange));
+
+      ref.current = null;
+
+      act(() => {
+        result.current.update('new content');
+      });
+
+      expect(onChange).not.toHaveBeenCalled();
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // edit.insert
+  // ---------------------------------------------------------------------------
+  describe('insert', () => {
+    it('inserts text at caret position', () => {
+      const { result, element } = setup('hello');
+      placeSelection(element, 5);
+
+      act(() => {
+        result.current.insert(' world');
+      });
+
+      // insert triggers flushChanges internally through DOM mutations,
+      // but in JSDOM we can verify the direct DOM manipulation happened
+      // The element should now have the inserted text node
+      expect(element.textContent).toContain('world');
+    });
+
+    it('does nothing when element ref is null', () => {
+      const element = document.createElement('pre');
+      element.textContent = 'hello';
+      document.body.appendChild(element);
+
+      const ref: { current: HTMLElement | null } = { current: element };
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useEditable(ref, onChange));
+
+      ref.current = null;
+
+      act(() => {
+        result.current.insert('text');
+      });
+
+      // Should not throw
+      expect(element.textContent).toBe('hello');
+    });
+
+    it('inserts at the start of a framed line without escaping the line wrapper', () => {
+      const element = document.createElement('pre');
+      element.innerHTML = [
+        '<code>',
+        '<span class="frame" data-frame="0">',
+        '<span class="line" data-ln="1">aaa\n</span>',
+        '</span>',
+        '<span class="frame" data-frame="1">',
+        '<span class="line" data-ln="2">bbb</span>',
+        '</span>',
+        '</code>',
+      ].join('');
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      const { result } = renderHook(() => useEditable(ref, onChange));
+
+      placeSelection(element, 4);
+
+      act(() => {
+        result.current.insert('x');
+      });
+
+      const frame = element.querySelector('[data-frame="1"]') as HTMLElement;
+      const line = frame.querySelector('[data-ln="2"]') as HTMLElement;
+
+      expect(frame.firstChild).toBe(line);
+      expect(line.textContent).toBe('xbbb');
+      expect(result.current.getState().text).toBe('aaa\nxbbb\n');
+    });
+
+    it('deletes one character before the cursor (negative offset, same-node range)', () => {
+      const { result, element } = setup('hello');
+      placeSelection(element, 3);
+
+      act(() => {
+        result.current.insert('', -1);
+      });
+
+      expect(element.textContent).toContain('helo');
+    });
+
+    it('deletes multiple characters before the cursor (negative offset, same-node range)', () => {
+      const { result, element } = setup('hello');
+      placeSelection(element, 5);
+
+      act(() => {
+        result.current.insert('', -3);
+      });
+
+      expect(element.textContent).toContain('he');
+    });
+
+    it('deletes characters spanning a node boundary (negative offset, cross-node range)', () => {
+      const element = document.createElement('pre');
+      element.innerHTML = [
+        '<code>',
+        '<span class="frame" data-frame="0">',
+        '<span class="line" data-ln="1">aaa\n</span>',
+        '</span>',
+        '<span class="frame" data-frame="1">',
+        '<span class="line" data-ln="2">bbb</span>',
+        '</span>',
+        '</code>',
+      ].join('');
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      const { result } = renderHook(() => useEditable(ref, onChange));
+
+      // Place caret at position 5 ("aaa\nbb|b"), then delete 2 chars back
+      // crossing the \n node boundary: removes "\nb", leaving "aaabb"
+      placeSelection(element, 5);
+
+      act(() => {
+        result.current.insert('', -2);
+      });
+
+      expect(result.current.getState().text).toBe('aaabb\n');
+    });
+
+    it('inserts after </p> without merging the next framed line into the same line', () => {
+      const element = document.createElement('pre');
+      element.innerHTML = [
+        '<code>',
+        '<span class="frame" data-frame="0">',
+        '<span class="line" data-ln="1">aaa\n</span>',
+        '</span>',
+        '<span class="frame" data-frame="1" data-frame-type="highlighted" data-frame-indent="3">',
+        '<span class="line" data-ln="8">      &lt;<span class="pl-ent">p</span> <span class="pl-e">style</span><span class="pl-k">=</span><span class="pl-pse">{</span>{ color: <span class="pl-s"><span class="pl-pds">\'</span>#CA244D<span class="pl-pds">\'</span></span> }<span class="pl-pse">}</span>&gt;Type Whatever You Want Below&lt;/<span class="pl-ent">p</span>&gt;\n</span>',
+        '</span>',
+        '<span class="frame" data-frame="2">',
+        '<span class="line" data-ln="9">    &lt;/<span class="pl-ent">div</span>&gt;</span>',
+        '</span>',
+        '</code>',
+      ].join('');
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      const { result } = renderHook(() => useEditable(ref, onChange, { indentation: 2 }));
+
+      const lines = [
+        'aaa',
+        "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>",
+        '    </div>',
+        '',
+      ];
+
+      placeSelection(element, lines[0].length + 1 + lines[1].length);
+
+      act(() => {
+        result.current.insert('x');
+      });
+
+      const frame = element.querySelector('[data-frame="1"]') as HTMLElement;
+      const line = frame.querySelector('[data-ln="8"]') as HTMLElement;
+      const nextFrame = element.querySelector('[data-frame="2"]') as HTMLElement;
+      const nextLine = nextFrame.querySelector('[data-ln="9"]') as HTMLElement;
+      const resultLines = result.current.getState().text.split('\n');
+
+      expect(frame.firstChild).toBe(line);
+      expect(nextFrame.firstChild).toBe(nextLine);
+      expect(line.textContent).toBe(
+        "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>x\n",
+      );
+      expect(resultLines).toEqual([
+        'aaa',
+        "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>x",
+        '    </div>',
+        '',
+      ]);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // edit.move
+  // ---------------------------------------------------------------------------
+  describe('move', () => {
+    it('accepts a numeric position', () => {
+      const { result, element } = setup('hello world');
+      placeSelection(element, 0);
+
+      act(() => {
+        result.current.move(5);
+      });
+
+      // Verify selection was moved
+      const sel = window.getSelection()!;
+      expect(sel.rangeCount).toBe(1);
+    });
+
+    it('accepts a row/column object', () => {
+      const { result, element } = setup('line one\nline two');
+
+      // Need to set initial selection
+      placeSelection(element, 0);
+
+      act(() => {
+        result.current.move({ row: 1, column: 3 });
+      });
+
+      const sel = window.getSelection()!;
+      expect(sel.rangeCount).toBe(1);
+    });
+
+    it('does nothing when element ref is null', () => {
+      const element = document.createElement('pre');
+      element.textContent = 'hello';
+      document.body.appendChild(element);
+
+      const ref: { current: HTMLElement | null } = { current: element };
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useEditable(ref, onChange));
+
+      ref.current = null;
+
+      // Should not throw
+      act(() => {
+        result.current.move(3);
+      });
+
+      expect(ref.current).toBeNull();
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Keyboard interactions
+  // ---------------------------------------------------------------------------
+  describe('keyboard interactions', () => {
+    it('calls onChange on Enter key', () => {
+      const { element } = setup('hello');
+      placeSelection(element, 5);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'Enter',
+        bubbles: true,
+        cancelable: true,
+      });
+      // Dispatch from the element so event.target === element;
+      // bubbles:true ensures the window keydown listener receives it.
+      element.dispatchEvent(event);
+
+      // The Enter handler calls edit.insert which modifies the DOM
+      expect(element.textContent).toContain('\n');
+    });
+
+    it('does not handle events from other elements', () => {
+      const { element, onChange } = setup('hello');
+      placeSelection(element, 0);
+
+      const otherElement = document.createElement('input');
+      document.body.appendChild(otherElement);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'a',
+        bubbles: true,
+        cancelable: true,
+      });
+      otherElement.dispatchEvent(event);
+
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('does not handle prevented events on keyup', () => {
+      const { element, onChange } = setup('hello');
+      placeSelection(element, 0);
+
+      const event = new KeyboardEvent('keyup', {
+        key: 'a',
+        bubbles: true,
+        cancelable: true,
+      });
+      event.preventDefault();
+      element.dispatchEvent(event);
+
+      // onChange should not be called for prevented events
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('handles Tab key with indentation', () => {
+      const { element, onChange } = setup('hello', { indentation: 2 });
+      placeSelection(element, 0);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'Tab',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      // Tab with indentation calls edit.update which calls onChange
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      // Should have added indentation spaces
+      expect(text).toContain('  ');
+    });
+
+    it('handles Shift+Tab for dedent with indentation', () => {
+      const { element, onChange } = setup('  hello', { indentation: 2 });
+      placeSelection(element, 2);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'Tab',
+        shiftKey: true,
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      expect(onChange).toHaveBeenCalled();
+    });
+
+    it('handles plain text input synchronously in fallback contentEditable mode', () => {
+      const element = document.createElement('pre');
+      element.contentEditable = 'true';
+      element.style.whiteSpace = 'pre-wrap';
+      element.innerHTML = [
+        '<code>',
+        '<span class="frame" data-frame="0">',
+        '<span class="line" data-ln="1">aaa\n</span>',
+        '</span>',
+        '<span class="frame" data-frame="1">',
+        '<span class="line" data-ln="2">bbb</span>',
+        '</span>',
+        '</code>',
+      ].join('');
+      document.body.appendChild(element);
+
+      let contentEditableValue = 'true';
+      Object.defineProperty(element, 'contentEditable', {
+        get() {
+          return contentEditableValue;
+        },
+        set(value: string) {
+          if (value === 'plaintext-only') {
+            throw new DOMException(
+              "Failed to set 'contentEditable': 'plaintext-only' is not supported",
+            );
+          }
+          contentEditableValue = value;
+        },
+        configurable: true,
+      });
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+
+      renderHook(() => useEditable(ref, onChange, { indentation: 2 }));
+
+      placeSelection(element, 4);
+
+      const keyDown = new KeyboardEvent('keydown', {
+        key: 'x',
+        code: 'KeyX',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyDown);
+
+      const frame = element.querySelector('[data-frame="1"]') as HTMLElement;
+      const line = frame.querySelector('[data-ln="2"]') as HTMLElement;
+
+      expect(keyDown.defaultPrevented).toBe(true);
+      expect(frame.firstChild).toBe(line);
+      expect(line.textContent).toBe('xbbb');
+
+      const keyUp = new KeyboardEvent('keyup', {
+        key: 'x',
+        code: 'KeyX',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyUp);
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(text).toBe('aaa\nxbbb\n');
+    });
+
+    it('keeps </div> on the next line when fallback typing inserts after </p>', () => {
+      const element = document.createElement('pre');
+      element.contentEditable = 'true';
+      element.style.whiteSpace = 'pre-wrap';
+      element.innerHTML = [
+        '<code>',
+        '<span class="frame" data-frame="0">',
+        '<span class="line" data-ln="1">aaa</span>\n',
+        '</span>',
+        '<span class="frame" data-frame="1" data-frame-type="highlighted" data-frame-indent="3">',
+        '<span class="line" data-ln="8">      &lt;<span class="pl-ent">p</span> <span class="pl-e">style</span><span class="pl-k">=</span><span class="pl-pse">{</span>{ color: <span class="pl-s"><span class="pl-pds">\'</span>#CA244D<span class="pl-pds">\'</span></span> }<span class="pl-pse">}</span>&gt;Type Whatever You Want Below&lt;/<span class="pl-ent">p</span>&gt;</span>\n',
+        '</span>',
+        '<span class="frame" data-frame="2">',
+        '<span class="line" data-ln="9">    &lt;/<span class="pl-ent">div</span>&gt;</span>',
+        '</span>',
+        '</code>',
+      ].join('');
+      document.body.appendChild(element);
+
+      let contentEditableValue = 'true';
+      Object.defineProperty(element, 'contentEditable', {
+        get() {
+          return contentEditableValue;
+        },
+        set(value: string) {
+          if (value === 'plaintext-only') {
+            throw new DOMException(
+              "Failed to set 'contentEditable': 'plaintext-only' is not supported",
+            );
+          }
+          contentEditableValue = value;
+        },
+        configurable: true,
+      });
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+
+      renderHook(() => useEditable(ref, onChange, { indentation: 2 }));
+
+      const lines = [
+        'aaa',
+        "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>",
+        '    </div>',
+        '',
+      ];
+
+      placeSelection(element, lines[0].length + 1 + lines[1].length);
+
+      const keyDown = new KeyboardEvent('keydown', {
+        key: 'x',
+        code: 'KeyX',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyDown);
+
+      const keyUp = new KeyboardEvent('keyup', {
+        key: 'x',
+        code: 'KeyX',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyUp);
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(text.split('\n')).toEqual([
+        'aaa',
+        "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>x",
+        '    </div>',
+        '',
+      ]);
+    });
+
+    it('repairs merged lines before onChange when fallback mode receives a merged DOM', () => {
+      const element = document.createElement('pre');
+      element.contentEditable = 'true';
+      element.style.whiteSpace = 'pre-wrap';
+      element.innerHTML = [
+        '<code>',
+        '<span class="frame" data-frame="0">',
+        '<span class="line" data-ln="1">aaa</span>\n',
+        '</span>',
+        '<span class="frame" data-frame="1" data-frame-type="highlighted" data-frame-indent="3">',
+        '<span class="line" data-ln="8">      &lt;<span class="pl-ent">p</span> <span class="pl-e">style</span><span class="pl-k">=</span><span class="pl-pse">{</span>{ color: <span class="pl-s"><span class="pl-pds">\'</span>#CA244D<span class="pl-pds">\'</span></span> }<span class="pl-pse">}</span>&gt;Type Whatever You Want Below&lt;/<span class="pl-ent">p</span>&gt;</span>\n',
+        '</span>',
+        '<span class="frame" data-frame="2">',
+        '<span class="line" data-ln="9">    &lt;/<span class="pl-ent">div</span>&gt;</span>',
+        '</span>',
+        '</code>',
+      ].join('');
+      document.body.appendChild(element);
+
+      let contentEditableValue = 'true';
+      Object.defineProperty(element, 'contentEditable', {
+        get() {
+          return contentEditableValue;
+        },
+        set(value: string) {
+          if (value === 'plaintext-only') {
+            throw new DOMException(
+              "Failed to set 'contentEditable': 'plaintext-only' is not supported",
+            );
+          }
+          contentEditableValue = value;
+        },
+        configurable: true,
+      });
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+
+      renderHook(() => useEditable(ref, onChange, { indentation: 2 }));
+
+      const lines = [
+        'aaa',
+        "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>",
+        '    </div>',
+        '',
+      ];
+
+      placeSelection(element, lines[0].length + 1 + lines[1].length);
+
+      const keyDown = new KeyboardEvent('keydown', {
+        key: 'x',
+        code: 'KeyX',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyDown);
+
+      const line = element.querySelector('[data-ln="8"]') as HTMLElement;
+      const nextFrame = element.querySelector('[data-frame="2"]') as HTMLElement;
+      line.textContent =
+        "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>x    </div>";
+      nextFrame.remove();
+
+      placeSelection(element, lines[0].length + 1 + lines[1].length + 1);
+
+      const keyUp = new KeyboardEvent('keyup', {
+        key: 'x',
+        code: 'KeyX',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyUp);
+
+      expect(onChange).toHaveBeenCalled();
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(text.split('\n')).toEqual([
+        'aaa',
+        "      <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>x",
+        '    </div>',
+        '',
+      ]);
+    });
+
+    it('preserves line count when rapid keydown (repeat) fires after a line-merging DOM mutation in fallback mode', () => {
+      // Scenario: Firefox fallback mode, cursor at end of a line before a frame
+      // boundary. User types 'x' quickly so a second keydown arrives before keyup.
+      // The first keydown (non-repeat) inserts via edit.insert. Firefox then merges
+      // the next frame's line into the current one (unexpected line merge). Before
+      // keyup fires, a second rapid keydown arrives with repeat:true. At this point
+      // state.disconnected is true (observer was disconnected during the first
+      // edit.insert path via MutationObserver callbacks). The disconnected guard
+      // blocks the second keydown, setting pendingContent = null via the early return.
+      // When keyup finally calls flushChanges, pendingContent is null so
+      // repairUnexpectedLineMerge cannot detect the merge and a line is lost.
+      const element = document.createElement('pre');
+      element.contentEditable = 'true';
+      element.style.whiteSpace = 'pre-wrap';
+      element.innerHTML = [
+        '<code>',
+        '<span class="frame" data-frame="0">',
+        '<span class="line" data-ln="1">aaa\n</span>',
+        '</span>',
+        '<span class="frame" data-frame="1">',
+        '<span class="line" data-ln="2">bbb</span>',
+        '</span>',
+        '</code>',
+      ].join('');
+      document.body.appendChild(element);
+
+      let contentEditableValue = 'true';
+      Object.defineProperty(element, 'contentEditable', {
+        get() {
+          return contentEditableValue;
+        },
+        set(value: string) {
+          if (value === 'plaintext-only') {
+            throw new DOMException(
+              "Failed to set 'contentEditable': 'plaintext-only' is not supported",
+            );
+          }
+          contentEditableValue = value;
+        },
+        configurable: true,
+      });
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      renderHook(() => useEditable(ref, onChange));
+
+      // Cursor at end of line 1 ("aaa|")
+      placeSelection(element, 3);
+
+      // First keydown — routes through isPlaintextInputKey, calls edit.insert('x')
+      const keyDown1 = new KeyboardEvent('keydown', {
+        key: 'x',
+        code: 'KeyX',
+        repeat: false,
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyDown1);
+
+      // Firefox merges lines: "aaaxbbb" — frame 1 line is now merged into frame 0
+      const line1 = element.querySelector('[data-ln="1"]') as HTMLElement;
+      const frame1 = element.querySelector('[data-frame="1"]') as HTMLElement;
+      line1.textContent = 'aaaxbbb\n';
+      frame1.remove();
+      placeSelection(element, 4);
+
+      // Second rapid keydown (key held) — state.disconnected is true here,
+      // so this hits the early-return guard without setting pendingContent
+      const keyDown2 = new KeyboardEvent('keydown', {
+        key: 'x',
+        code: 'KeyX',
+        repeat: true,
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyDown2);
+
+      // keyup — flushChanges is called with pendingContent=null, so the merge repair
+      // cannot run. Without the fix, onChange receives "aaaxbbb" (missing line 2).
+      const keyUp = new KeyboardEvent('keyup', {
+        key: 'x',
+        code: 'KeyX',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyUp);
+
+      const lastCall = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(lastCall[0].split('\n')).toEqual(['aaaxx', 'bbb', '']);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // minColumn option
+  // ---------------------------------------------------------------------------
+  describe('minColumn option', () => {
+    function getCaretPosition(element: HTMLElement): number {
+      const range = window.getSelection()!.getRangeAt(0);
+      const pre = document.createRange();
+      pre.setStart(element, 0);
+      pre.setEnd(range.startContainer, range.startOffset);
+      return pre.toString().length;
+    }
+
+    it('moves ArrowLeft at minColumn to end of previous line', () => {
+      const { element } = setup('hello\n    world', { minColumn: 4 });
+      // Caret at column 4 of line 1 (right after the indent, on the "w")
+      placeSelection(element, 'hello\n    '.length);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'ArrowLeft',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      expect(event.defaultPrevented).toBe(true);
+      expect(getCaretPosition(element)).toBe('hello'.length);
+    });
+
+    it('moves ArrowRight at end of line to minColumn of next line', () => {
+      const { element } = setup('hello\n    world', { minColumn: 4 });
+      // Caret at end of line 0
+      placeSelection(element, 'hello'.length);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'ArrowRight',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      expect(event.defaultPrevented).toBe(true);
+      expect(getCaretPosition(element)).toBe('hello\n    '.length);
+    });
+
+    it('does not intercept ArrowLeft when caret is past minColumn', () => {
+      const { element } = setup('hello\n    world', { minColumn: 4 });
+      // Caret at column 5 of line 1 (one char into "world")
+      placeSelection(element, 'hello\n    w'.length);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'ArrowLeft',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it('does not intercept ArrowRight when caret is not at end of line', () => {
+      const { element } = setup('hello\n    world', { minColumn: 4 });
+      // Caret in the middle of line 0
+      placeSelection(element, 2);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'ArrowRight',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it('does not intercept ArrowRight when next line is not indented to minColumn', () => {
+      const { element } = setup('hello\nhi', { minColumn: 4 });
+      // Caret at end of line 0; next line "hi" has only 0 indent
+      placeSelection(element, 'hello'.length);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'ArrowRight',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it('does not intercept ArrowLeft when current line indent is shorter than minColumn', () => {
+      // Caret happens to be at column 4 but the line has non-whitespace within
+      // the first 4 chars — this is not the "in the indent" case.
+      const { element } = setup('hello\nabcdef', { minColumn: 4 });
+      placeSelection(element, 'hello\nabcd'.length);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'ArrowLeft',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it('does not intercept arrow keys when shift is held (selection extension)', () => {
+      const { element } = setup('hello\n    world', { minColumn: 4 });
+      placeSelection(element, 'hello\n    '.length);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'ArrowLeft',
+        shiftKey: true,
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it('does not intercept ArrowLeft on the first line', () => {
+      const { element } = setup('    world', { minColumn: 4 });
+      placeSelection(element, '    '.length);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'ArrowLeft',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it('does nothing when minColumn is undefined', () => {
+      const { element } = setup('hello\n    world');
+      placeSelection(element, 'hello\n    '.length);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'ArrowLeft',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it('snaps a click that lands inside the indent gutter to minColumn', () => {
+      // The user clicks at column 1 of "    world" — inside the clipped
+      // 4-space gutter. The mouseup handler should jump the caret to
+      // column 4 (the visible start of the line).
+      const { element } = setup('hello\n    world', { minColumn: 4 });
+      placeSelection(element, 'hello\n '.length); // column 1 of line 1
+
+      element.dispatchEvent(new MouseEvent('mouseup', { bubbles: true, cancelable: true }));
+
+      const range = window.getSelection()!.getRangeAt(0);
+      const pre = document.createRange();
+      pre.setStart(element, 0);
+      pre.setEnd(range.startContainer, range.startOffset);
+      expect(pre.toString().length).toBe('hello\n    '.length);
+    });
+
+    it('does not snap a click that lands at or after minColumn', () => {
+      const { element } = setup('hello\n    world', { minColumn: 4 });
+      placeSelection(element, 'hello\n    wo'.length);
+
+      element.dispatchEvent(new MouseEvent('mouseup', { bubbles: true, cancelable: true }));
+
+      const range = window.getSelection()!.getRangeAt(0);
+      const pre = document.createRange();
+      pre.setStart(element, 0);
+      pre.setEnd(range.startContainer, range.startOffset);
+      expect(pre.toString().length).toBe('hello\n    wo'.length);
+    });
+
+    it('snaps the caret to minColumn when the editor receives focus in the gutter', async () => {
+      // Tabbing into the editor lands the caret at column 0; after a frame
+      // the focus handler should jump it to minColumn.
+      const { element } = setup('hello\n    world', { minColumn: 4 });
+      placeSelection(element, 'hello\n'.length); // column 0 of line 1
+
+      element.dispatchEvent(new FocusEvent('focus'));
+      await new Promise((resolve) => {
+        requestAnimationFrame(() => resolve(undefined));
+      });
+
+      const range = window.getSelection()!.getRangeAt(0);
+      const pre = document.createRange();
+      pre.setStart(element, 0);
+      pre.setEnd(range.startContainer, range.startOffset);
+      expect(pre.toString().length).toBe('hello\n    '.length);
+    });
+
+    it('does not snap a non-collapsed selection that starts in the gutter', () => {
+      // Drag selections shouldn't be clamped mid-gesture.
+      const { element } = setup('hello\n    world', { minColumn: 4 });
+      const textNode = element.firstChild!;
+      const range = document.createRange();
+      range.setStart(textNode, 'hello\n '.length);
+      range.setEnd(textNode, 'hello\n    wor'.length);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      element.dispatchEvent(new MouseEvent('mouseup', { bubbles: true, cancelable: true }));
+
+      const after = window.getSelection()!.getRangeAt(0);
+      const pre = document.createRange();
+      pre.setStart(element, 0);
+      pre.setEnd(after.startContainer, after.startOffset);
+      expect(pre.toString().length).toBe('hello\n '.length);
+    });
+
+    it('Backspace at minColumn on a blank indented line collapses the line and lands the caret on the previous line', () => {
+      // Three lines: `hello`, a blank line of exactly minColumn (4)
+      // whitespace characters, and `world`. With the caret at the end of
+      // the blank line (column = minColumn), Backspace would normally
+      // delete one indent space and leave the caret in the clipped
+      // `[0, minColumn)` gutter. Instead we collapse the entire blank
+      // line so the caret lands at the end of `hello`.
+      const { element, onChange } = setup('hello\n    \n    world', {
+        minColumn: 4,
+        indentation: 2,
+      });
+      placeSelection(element, 'hello\n    '.length);
+
+      const keyDown = new KeyboardEvent('keydown', {
+        key: 'Backspace',
+        code: 'Backspace',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyDown);
+
+      expect(keyDown.defaultPrevented).toBe(true);
+      expect(element.textContent).toBe('hello\n    world');
+      const range = window.getSelection()!.getRangeAt(0);
+      const pre = document.createRange();
+      pre.setStart(element, 0);
+      pre.setEnd(range.startContainer, range.startOffset);
+      expect(pre.toString().length).toBe('hello'.length);
+
+      element.dispatchEvent(new KeyboardEvent('keyup', { key: 'Backspace', bubbles: true }));
+      const [text] = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(text).toBe('hello\n    world\n');
+    });
+
+    it('Backspace at minColumn on a non-blank indented line falls through to a single-character delete', () => {
+      // The current line has more content past `minColumn`, so the
+      // collapse-blank-line shortcut should not engage.
+      const { element } = setup('hello\n    world', { minColumn: 4, indentation: 2 });
+      placeSelection(element, 'hello\n    '.length);
+
+      const keyDown = new KeyboardEvent('keydown', {
+        key: 'Backspace',
+        code: 'Backspace',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyDown);
+
+      expect(keyDown.defaultPrevented).toBe(true);
+      // The fall-through path deletes a full `indentation` unit (2 chars)
+      // when the pre-caret content is purely indent.
+      expect(element.textContent).toBe('hello\n  world');
+    });
+
+    it('Backspace at minColumn on a blank first line falls through (no previous line to land on)', () => {
+      // No `position.line > 0` to use, so we keep the default behavior.
+      const { element } = setup('    \nworld', { minColumn: 4, indentation: 2 });
+      placeSelection(element, '    '.length);
+
+      const keyDown = new KeyboardEvent('keydown', {
+        key: 'Backspace',
+        code: 'Backspace',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyDown);
+
+      expect(keyDown.defaultPrevented).toBe(true);
+      expect(element.textContent).toBe('  \nworld');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // minRow / maxRow / onBoundary options
+  // ---------------------------------------------------------------------------
+  describe('visible row bounds', () => {
+    function getCaretPosition(element: HTMLElement): number {
+      const range = window.getSelection()!.getRangeAt(0);
+      const pre = document.createRange();
+      pre.setStart(element, 0);
+      pre.setEnd(range.startContainer, range.startOffset);
+      return pre.toString().length;
+    }
+
+    function dispatchKey(element: HTMLElement, key: string, modifiers: KeyboardEventInit = {}) {
+      const event = new KeyboardEvent('keydown', {
+        key,
+        bubbles: true,
+        cancelable: true,
+        ...modifiers,
+      });
+      element.dispatchEvent(event);
+      return event;
+    }
+
+    describe('ArrowUp at minRow', () => {
+      it('invokes onBoundary and allows native caret movement', () => {
+        const onBoundary = vi.fn();
+        const { element } = setup('a\nb\nc\nd', { minRow: 1, maxRow: 2, onBoundary });
+        // Caret at start of row 1 ("b")
+        placeSelection(element, 'a\n'.length);
+
+        const event = dispatchKey(element, 'ArrowUp');
+
+        expect(event.defaultPrevented).toBe(false);
+        expect(onBoundary).toHaveBeenCalledTimes(1);
+      });
+
+      it('does not invoke onBoundary on rows after minRow', () => {
+        const onBoundary = vi.fn();
+        const { element } = setup('a\nb\nc\nd', { minRow: 1, maxRow: 2, onBoundary });
+        // Caret in row 2 ("c")
+        placeSelection(element, 'a\nb\n'.length);
+
+        const event = dispatchKey(element, 'ArrowUp');
+
+        expect(event.defaultPrevented).toBe(false);
+        expect(onBoundary).not.toHaveBeenCalled();
+      });
+
+      it('does not invoke onBoundary when shift is held (selection)', () => {
+        const onBoundary = vi.fn();
+        const { element } = setup('a\nb\nc\nd', { minRow: 1, maxRow: 2, onBoundary });
+        placeSelection(element, 'a\n'.length);
+
+        const event = dispatchKey(element, 'ArrowUp', { shiftKey: true });
+
+        expect(event.defaultPrevented).toBe(false);
+        expect(onBoundary).not.toHaveBeenCalled();
+      });
+
+      it('blocks when onBoundary is not provided', () => {
+        const { element } = setup('a\nb\nc\nd', { minRow: 1, maxRow: 2 });
+        placeSelection(element, 'a\n'.length);
+        const before = getCaretPosition(element);
+
+        const event = dispatchKey(element, 'ArrowUp');
+
+        expect(event.defaultPrevented).toBe(true);
+        expect(getCaretPosition(element)).toBe(before);
+      });
+    });
+
+    describe('ArrowDown at maxRow', () => {
+      it('invokes onBoundary and allows native caret movement', () => {
+        const onBoundary = vi.fn();
+        const { element } = setup('a\nb\nc\nd', { minRow: 1, maxRow: 2, onBoundary });
+        // Caret in row 2 ("c")
+        placeSelection(element, 'a\nb\n'.length);
+
+        const event = dispatchKey(element, 'ArrowDown');
+
+        expect(event.defaultPrevented).toBe(false);
+        expect(onBoundary).toHaveBeenCalledTimes(1);
+      });
+
+      it('does not invoke onBoundary on rows before maxRow', () => {
+        const onBoundary = vi.fn();
+        const { element } = setup('a\nb\nc\nd', { minRow: 1, maxRow: 2, onBoundary });
+        placeSelection(element, 'a\n'.length);
+
+        const event = dispatchKey(element, 'ArrowDown');
+
+        expect(event.defaultPrevented).toBe(false);
+        expect(onBoundary).not.toHaveBeenCalled();
+      });
+
+      it('blocks when onBoundary is not provided', () => {
+        const { element } = setup('a\nb\nc\nd', { minRow: 1, maxRow: 2 });
+        placeSelection(element, 'a\nb\n'.length);
+
+        const event = dispatchKey(element, 'ArrowDown');
+
+        expect(event.defaultPrevented).toBe(true);
+      });
+    });
+
+    describe('ArrowLeft at start of minRow', () => {
+      it('invokes onBoundary and allows native caret movement at column 0', () => {
+        const onBoundary = vi.fn();
+        const { element } = setup('a\nbcd\ne', { minRow: 1, maxRow: 1, onBoundary });
+        // Caret at column 0 of row 1
+        placeSelection(element, 'a\n'.length);
+
+        const event = dispatchKey(element, 'ArrowLeft');
+
+        expect(event.defaultPrevented).toBe(false);
+        expect(onBoundary).toHaveBeenCalledTimes(1);
+      });
+
+      it('invokes onBoundary at minColumn on indented row', () => {
+        const onBoundary = vi.fn();
+        const { element } = setup('a\n    bcd\ne', {
+          minColumn: 4,
+          minRow: 1,
+          maxRow: 1,
+          onBoundary,
+        });
+        // Caret at column minColumn (4) of row 1, lined up with "b"
+        placeSelection(element, 'a\n    '.length);
+
+        const event = dispatchKey(element, 'ArrowLeft');
+
+        expect(event.defaultPrevented).toBe(false);
+        expect(onBoundary).toHaveBeenCalledTimes(1);
+      });
+
+      it('blocks when onBoundary is not provided', () => {
+        const { element } = setup('a\nbcd\ne', { minRow: 1, maxRow: 1 });
+        placeSelection(element, 'a\n'.length);
+
+        const event = dispatchKey(element, 'ArrowLeft');
+
+        expect(event.defaultPrevented).toBe(true);
+      });
+
+      it('does not invoke onBoundary mid-line on minRow', () => {
+        const onBoundary = vi.fn();
+        const { element } = setup('a\nbcd\ne', { minRow: 1, maxRow: 1, onBoundary });
+        // Caret in middle of row 1
+        placeSelection(element, 'a\nb'.length);
+
+        const event = dispatchKey(element, 'ArrowLeft');
+
+        expect(event.defaultPrevented).toBe(false);
+        expect(onBoundary).not.toHaveBeenCalled();
+      });
+    });
+
+    describe('ArrowRight at end of maxRow', () => {
+      it('invokes onBoundary and allows native caret movement at end of line', () => {
+        const onBoundary = vi.fn();
+        const { element } = setup('a\nbcd\ne', { minRow: 1, maxRow: 1, onBoundary });
+        // Caret at end of row 1
+        placeSelection(element, 'a\nbcd'.length);
+
+        const event = dispatchKey(element, 'ArrowRight');
+
+        expect(event.defaultPrevented).toBe(false);
+        expect(onBoundary).toHaveBeenCalledTimes(1);
+      });
+
+      it('blocks when onBoundary is not provided', () => {
+        const { element } = setup('a\nbcd\ne', { minRow: 1, maxRow: 1 });
+        placeSelection(element, 'a\nbcd'.length);
+
+        const event = dispatchKey(element, 'ArrowRight');
+
+        expect(event.defaultPrevented).toBe(true);
+      });
+
+      it('does not invoke onBoundary mid-line on maxRow', () => {
+        const onBoundary = vi.fn();
+        const { element } = setup('a\nbcd\ne', { minRow: 1, maxRow: 1, onBoundary });
+        // Caret mid-row
+        placeSelection(element, 'a\nb'.length);
+
+        const event = dispatchKey(element, 'ArrowRight');
+
+        expect(event.defaultPrevented).toBe(false);
+        expect(onBoundary).not.toHaveBeenCalled();
+      });
+
+      it('takes precedence over minColumn next-line jump', () => {
+        const onBoundary = vi.fn();
+        // maxRow == 1, next row indented to minColumn — boundary should win.
+        const { element } = setup('a\nbcd\n    e', {
+          minColumn: 4,
+          minRow: 1,
+          maxRow: 1,
+          onBoundary,
+        });
+        placeSelection(element, 'a\nbcd'.length);
+
+        const event = dispatchKey(element, 'ArrowRight');
+
+        // With onBoundary provided, native movement is allowed; the
+        // useEditable-driven jump to minColumn of the next line is skipped.
+        expect(event.defaultPrevented).toBe(false);
+        expect(onBoundary).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // caretSelector option
+  // ---------------------------------------------------------------------------
+  describe('caretSelector option', () => {
+    /**
+     * Builds a `<pre>` whose internal HTML mirrors the highlighted output:
+     * `.line` spans separated by literal `\n` text nodes. Returns a helper
+     * that places the collapsed selection at the given total-text offset,
+     * walking the actual `.line` text nodes (not the gap nodes) so the
+     * caret ends up *inside* a matching element.
+     */
+    function setupLined(
+      linesText: string[],
+      opts: {
+        caretSelector?: string;
+        minRow?: number;
+        maxRow?: number;
+        minColumn?: number;
+        onBoundary?: () => void;
+      } = {},
+    ) {
+      const element = document.createElement('pre');
+      linesText.forEach((text, idx) => {
+        if (idx > 0) {
+          element.appendChild(document.createTextNode('\n'));
+        }
+        const line = document.createElement('span');
+        line.className = 'line';
+        line.textContent = text;
+        element.appendChild(line);
+      });
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      const { unmount } = renderHook(
+        (props) => useEditable(props.ref, props.onChange, props.opts),
+        { initialProps: { ref, onChange, opts } },
+      );
+
+      function placeInLine(lineIndex: number, column: number) {
+        const lineSpan = element.querySelectorAll('.line')[lineIndex];
+        const textNode = lineSpan.firstChild!;
+        const range = document.createRange();
+        range.setStart(textNode, column);
+        range.collapse(true);
+        const selection = window.getSelection()!;
+        selection.removeAllRanges();
+        selection.addRange(range);
+      }
+
+      return { element, placeInLine, unmount };
+    }
+
+    function dispatchArrow(element: HTMLElement, key: string) {
+      const event = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true });
+      element.dispatchEvent(event);
+      return event;
+    }
+
+    function caretOffset(element: HTMLElement) {
+      const range = window.getSelection()!.getRangeAt(0);
+      const pre = document.createRange();
+      pre.setStart(element, 0);
+      pre.setEnd(range.startContainer, range.startOffset);
+      return pre.toString().length;
+    }
+
+    it('synchronously moves caret to end of previous line on ArrowLeft at column 0', () => {
+      const { element, placeInLine } = setupLined(['hello', 'world'], { caretSelector: '.line' });
+      placeInLine(1, 0);
+
+      const event = dispatchArrow(element, 'ArrowLeft');
+
+      expect(event.defaultPrevented).toBe(true);
+      expect(caretOffset(element)).toBe('hello'.length);
+    });
+
+    it('synchronously moves caret to start of next line on ArrowRight at end of line', () => {
+      const { element, placeInLine } = setupLined(['hello', 'world'], { caretSelector: '.line' });
+      placeInLine(0, 'hello'.length);
+
+      const event = dispatchArrow(element, 'ArrowRight');
+
+      expect(event.defaultPrevented).toBe(true);
+      expect(caretOffset(element)).toBe('hello\n'.length);
+    });
+
+    it('does not intercept ArrowLeft on the first line at column 0', () => {
+      const { element, placeInLine } = setupLined(['hello', 'world'], { caretSelector: '.line' });
+      placeInLine(0, 0);
+
+      const event = dispatchArrow(element, 'ArrowLeft');
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it('does not intercept ArrowLeft mid-line', () => {
+      const { element, placeInLine } = setupLined(['hello', 'world'], { caretSelector: '.line' });
+      placeInLine(1, 1);
+
+      const event = dispatchArrow(element, 'ArrowLeft');
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it('treats a blank intermediate line as a real next line for ArrowRight at end of line', () => {
+      // Regression: the chunked text-node walker used to short-circuit
+      // before recording that the next row exists when that row was
+      // empty, causing ArrowRight at the end of `text` to no-op instead
+      // of jumping into the spacer line. Documents like
+      // `text` / `<blank>` / `text` are extremely common in code samples.
+      const { element, placeInLine } = setupLined(['hello', '', 'world'], {
+        caretSelector: '.line',
+      });
+      placeInLine(0, 'hello'.length);
+
+      const event = dispatchArrow(element, 'ArrowRight');
+
+      expect(event.defaultPrevented).toBe(true);
+      expect(caretOffset(element)).toBe('hello\n'.length);
+    });
+
+    it('treats a blank intermediate line as a real next line for ArrowLeft at column 0', () => {
+      // Mirror of the above for the ArrowLeft gap-jump path: the caret
+      // is on the line *after* a blank one, and pressing ArrowLeft at
+      // column 0 should land at the end of the (zero-length) blank
+      // line rather than no-op.
+      const { element, placeInLine } = setupLined(['hello', '', 'world'], {
+        caretSelector: '.line',
+      });
+      placeInLine(2, 0);
+
+      const event = dispatchArrow(element, 'ArrowLeft');
+
+      expect(event.defaultPrevented).toBe(true);
+      expect(caretOffset(element)).toBe('hello\n'.length);
+    });
+
+    it('does not intercept vertical arrows so wrapped visual lines stay native', () => {
+      // ArrowUp/ArrowDown must remain unhijacked so browsers can navigate
+      // wrapped visual lines in `pre-wrap` layouts. Gap nodes styled with
+      // `line-height: 0` are skipped vertically by the browser anyway.
+      const { element, placeInLine } = setupLined(['hello', 'world'], { caretSelector: '.line' });
+      placeInLine(0, 2);
+
+      expect(dispatchArrow(element, 'ArrowDown').defaultPrevented).toBe(false);
+      placeInLine(1, 2);
+      expect(dispatchArrow(element, 'ArrowUp').defaultPrevented).toBe(false);
+    });
+
+    it('does nothing when caretSelector is undefined', () => {
+      const { element } = setup('hello\nworld');
+      placeSelection(element, 'hello\n'.length);
+
+      const event = dispatchArrow(element, 'ArrowLeft');
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it('does not wrap when the caret is not inside a matching element', () => {
+      // Plain-text editable: no `.line` spans exist, so the selector should
+      // never match and the wrap should not fire even with caretSelector set.
+      const { element } = setup('hello\nworld', { caretSelector: '.line' });
+      placeSelection(element, 'hello\n'.length);
+
+      const event = dispatchArrow(element, 'ArrowLeft');
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it('synchronously moves caret to next line on ArrowDown at maxRow before invoking onBoundary', () => {
+      // With `.line` spans separated by `\n` text-node gaps, native
+      // ArrowDown at the visible end would drop the caret in the gap
+      // between lines (the "between-lines" trap). The hook must move
+      // the caret onto the next `.line` *first*, then notify the host
+      // so the expansion happens with the caret already in place.
+      const onBoundary = vi.fn();
+      const { element, placeInLine } = setupLined(['hello', 'world', 'tail'], {
+        caretSelector: '.line',
+        maxRow: 1,
+        onBoundary,
+      });
+      placeInLine(1, 2);
+
+      const event = dispatchArrow(element, 'ArrowDown');
+
+      expect(event.defaultPrevented).toBe(true);
+      // Caret column (2) preserved on the newly-targeted line.
+      expect(caretOffset(element)).toBe('hello\nworld\nta'.length);
+      expect(onBoundary).toHaveBeenCalledTimes(1);
+    });
+
+    it('synchronously moves caret to next line on ArrowRight at end of maxRow before invoking onBoundary', () => {
+      const onBoundary = vi.fn();
+      const { element, placeInLine } = setupLined(['hello', 'world', 'tail'], {
+        caretSelector: '.line',
+        maxRow: 1,
+        onBoundary,
+      });
+      placeInLine(1, 'world'.length);
+
+      const event = dispatchArrow(element, 'ArrowRight');
+
+      expect(event.defaultPrevented).toBe(true);
+      // Lands at column 0 of the next line, not in the inter-line gap.
+      expect(caretOffset(element)).toBe('hello\nworld\n'.length);
+      expect(onBoundary).toHaveBeenCalledTimes(1);
+    });
+
+    it('treats a blank next line as a real line for ArrowDown at maxRow with caretSelector', () => {
+      // Boundary-path coverage for the chunked-walker bug: when the row
+      // immediately after `maxRow` is empty, ArrowDown must still cross
+      // into it (preserving column, then invoking onBoundary) instead of
+      // treating "blank line" as "no line" and no-op'ing.
+      const onBoundary = vi.fn();
+      const { element, placeInLine } = setupLined(['hello', 'world', '', 'tail'], {
+        caretSelector: '.line',
+        maxRow: 1,
+        onBoundary,
+      });
+      placeInLine(1, 2);
+
+      const event = dispatchArrow(element, 'ArrowDown');
+
+      expect(event.defaultPrevented).toBe(true);
+      // Column 2 clamps to end of the blank line.
+      expect(caretOffset(element)).toBe('hello\nworld\n'.length);
+      expect(onBoundary).toHaveBeenCalledTimes(1);
+    });
+
+    it('treats a blank next line as a real line for ArrowRight at end of maxRow with caretSelector', () => {
+      const onBoundary = vi.fn();
+      const { element, placeInLine } = setupLined(['hello', 'world', '', 'tail'], {
+        caretSelector: '.line',
+        maxRow: 1,
+        onBoundary,
+      });
+      placeInLine(1, 'world'.length);
+
+      const event = dispatchArrow(element, 'ArrowRight');
+
+      expect(event.defaultPrevented).toBe(true);
+      expect(caretOffset(element)).toBe('hello\nworld\n'.length);
+      expect(onBoundary).toHaveBeenCalledTimes(1);
+    });
+
+    it('synchronously moves caret to previous line on ArrowUp at minRow before invoking onBoundary', () => {
+      const onBoundary = vi.fn();
+      const { element, placeInLine } = setupLined(['head', 'hello', 'world'], {
+        caretSelector: '.line',
+        minRow: 1,
+        onBoundary,
+      });
+      placeInLine(1, 3);
+
+      const event = dispatchArrow(element, 'ArrowUp');
+
+      expect(event.defaultPrevented).toBe(true);
+      // Column 3 clamped/preserved on previous line ('head'[3] = 'd' end).
+      expect(caretOffset(element)).toBe('hea'.length);
+      expect(onBoundary).toHaveBeenCalledTimes(1);
+    });
+
+    it('synchronously moves caret to end of previous line on ArrowLeft at start of minRow before invoking onBoundary', () => {
+      const onBoundary = vi.fn();
+      const { element, placeInLine } = setupLined(['head', 'hello'], {
+        caretSelector: '.line',
+        minRow: 1,
+        onBoundary,
+      });
+      placeInLine(1, 0);
+
+      const event = dispatchArrow(element, 'ArrowLeft');
+
+      expect(event.defaultPrevented).toBe(true);
+      expect(caretOffset(element)).toBe('head'.length);
+      expect(onBoundary).toHaveBeenCalledTimes(1);
+    });
+
+    it('snaps caret out of an inter-line gap text node after ArrowDown (post-keydown rAF snap)', async () => {
+      // Simulate the browser's native ArrowDown behaviour landing the caret
+      // in the literal `\n` text node between `.line` spans (which happens
+      // when pressing Down on the last visible row of an expanded editable).
+      // The handler captures the source column at keydown time and the rAF
+      // snap should restore it on the destination line.
+      const { element, placeInLine } = setupLined(['abcdef', 'world'], {
+        caretSelector: '.line',
+      });
+      // Start at column 3 of "abcdef" — the column we want preserved.
+      placeInLine(0, 3);
+
+      // Dispatch ArrowDown. The handler reads the pre-move column (3)
+      // synchronously before scheduling the rAF.
+      dispatchArrow(element, 'ArrowDown');
+
+      // Now simulate the browser's native default action dropping the caret
+      // into the inter-line gap text node.
+      const gapNode = element.childNodes[1];
+      expect(gapNode.nodeType).toBe(Node.TEXT_NODE);
+      const gapRange = document.createRange();
+      gapRange.setStart(gapNode, 0);
+      gapRange.collapse(true);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(gapRange);
+
+      // Flush the rAF callback — the snap should run now.
+      await new Promise<void>((resolve) => {
+        requestAnimationFrame(() => resolve());
+      });
+
+      // Caret should be inside the next `.line` AT COLUMN 3.
+      const after = window.getSelection()!.getRangeAt(0);
+      const lineEl = (
+        after.startContainer.nodeType === Node.ELEMENT_NODE
+          ? (after.startContainer as Element)
+          : after.startContainer.parentElement
+      )?.closest('.line');
+      expect(lineEl).not.toBeNull();
+      expect(caretOffset(element)).toBe('abcdef\nwor'.length);
+    });
+
+    it('snaps caret out of an inter-line gap text node after ArrowUp (post-keydown rAF snap)', async () => {
+      const { element, placeInLine } = setupLined(['abcdef', 'world'], {
+        caretSelector: '.line',
+      });
+      // Start at column 4 of "world".
+      placeInLine(1, 4);
+
+      dispatchArrow(element, 'ArrowUp');
+
+      // Simulate browser native dropping the caret in the gap.
+      const gapNode = element.childNodes[1];
+      const gapRange = document.createRange();
+      gapRange.setStart(gapNode, 1);
+      gapRange.collapse(true);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(gapRange);
+
+      await new Promise<void>((resolve) => {
+        requestAnimationFrame(() => resolve());
+      });
+
+      const after = window.getSelection()!.getRangeAt(0);
+      const lineEl = (
+        after.startContainer.nodeType === Node.ELEMENT_NODE
+          ? (after.startContainer as Element)
+          : after.startContainer.parentElement
+      )?.closest('.line');
+      expect(lineEl).not.toBeNull();
+      // Snapped to column 4 of the previous line ("abcdef" → "abcd|ef").
+      expect(caretOffset(element)).toBe('abcd'.length);
+    });
+
+    it('clamps the preserved column to the destination line length on ArrowDown', async () => {
+      const { element, placeInLine } = setupLined(['abcdefghij', 'short'], {
+        caretSelector: '.line',
+      });
+      // Start at column 8 — longer than the destination line "short" (5 chars).
+      placeInLine(0, 8);
+
+      dispatchArrow(element, 'ArrowDown');
+
+      const gapNode = element.childNodes[1];
+      const gapRange = document.createRange();
+      gapRange.setStart(gapNode, 0);
+      gapRange.collapse(true);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(gapRange);
+
+      await new Promise<void>((resolve) => {
+        requestAnimationFrame(() => resolve());
+      });
+
+      // Column clamped to end of "short".
+      expect(caretOffset(element)).toBe('abcdefghij\nshort'.length);
+    });
+
+    it('snaps back to the last line when ArrowDown lands past it', async () => {
+      // ArrowDown on the last visible row can drop the caret into trailing
+      // whitespace *after* the final `.line` (no next line to forward to).
+      // The snap should then go back to the last line, preserving column.
+      const { element, placeInLine } = setupLined(['hello', 'wonderful'], {
+        caretSelector: '.line',
+      });
+      placeInLine(1, 4);
+
+      dispatchArrow(element, 'ArrowDown');
+
+      // Simulate browser dropping the caret in a trailing text node past
+      // the last `.line`. Append a synthetic trailing text node to mimic
+      // what real browsers do when they overshoot.
+      const trailing = document.createTextNode('\n');
+      element.appendChild(trailing);
+      const trailingRange = document.createRange();
+      trailingRange.setStart(trailing, 0);
+      trailingRange.collapse(true);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(trailingRange);
+
+      await new Promise<void>((resolve) => {
+        requestAnimationFrame(() => resolve());
+      });
+
+      const after = window.getSelection()!.getRangeAt(0);
+      const lineEl = (
+        after.startContainer.nodeType === Node.ELEMENT_NODE
+          ? (after.startContainer as Element)
+          : after.startContainer.parentElement
+      )?.closest('.line');
+      expect(lineEl).not.toBeNull();
+      // Snapped back to column 4 of the last line ("wond|erful").
+      expect(caretOffset(element)).toBe('hello\nwond'.length);
+    });
+
+    it('snaps forward to the first line when ArrowUp lands before it', async () => {
+      const { element, placeInLine } = setupLined(['hello', 'world'], {
+        caretSelector: '.line',
+      });
+      placeInLine(0, 3);
+
+      dispatchArrow(element, 'ArrowUp');
+
+      // Simulate browser dropping the caret in a synthetic leading text node.
+      const leading = document.createTextNode('\n');
+      element.insertBefore(leading, element.firstChild);
+      const leadingRange = document.createRange();
+      leadingRange.setStart(leading, 0);
+      leadingRange.collapse(true);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(leadingRange);
+
+      await new Promise<void>((resolve) => {
+        requestAnimationFrame(() => resolve());
+      });
+
+      const after = window.getSelection()!.getRangeAt(0);
+      const lineEl = (
+        after.startContainer.nodeType === Node.ELEMENT_NODE
+          ? (after.startContainer as Element)
+          : after.startContainer.parentElement
+      )?.closest('.line');
+      expect(lineEl).not.toBeNull();
+      // Snapped forward to column 3 of the first line ("hel|lo").
+      expect(caretOffset(element)).toBe('\nhel'.length);
+    });
+
+    it('snaps the caret onto the next line when a click lands in an inter-line gap node', () => {
+      // Clicking between `.line` spans places the caret in the literal
+      // `\n` gap text node, which is not selectable from the user's POV.
+      // The mouseup handler should snap forward onto the next line so
+      // typing immediately works as expected.
+      const { element } = setupLined(['hello', 'world'], { caretSelector: '.line' });
+
+      // Place caret in the gap text node between lines 0 and 1.
+      const gapNode = element.childNodes[1];
+      expect(gapNode.nodeType).toBe(Node.TEXT_NODE);
+      const range = document.createRange();
+      range.setStart(gapNode, 0);
+      range.collapse(true);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      element.dispatchEvent(new MouseEvent('mouseup', { bubbles: true, cancelable: true }));
+
+      const after = window.getSelection()!.getRangeAt(0);
+      const lineEl = (
+        after.startContainer.nodeType === Node.ELEMENT_NODE
+          ? (after.startContainer as Element)
+          : after.startContainer.parentElement
+      )?.closest('.line');
+      expect(lineEl).not.toBeNull();
+      // Caret lands at the start of the next line ("|world").
+      expect(caretOffset(element)).toBe('hello\n'.length);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Undo/Redo
+  // ---------------------------------------------------------------------------
+  describe('undo/redo', () => {
+    it('handles Ctrl+Z (undo key detection)', () => {
+      const { element } = setup('hello');
+      placeSelection(element, 0);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'z',
+        code: 'KeyZ',
+        ctrlKey: true,
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      // Event should be prevented (undo is handled internally)
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it('handles Meta+Z (undo key detection for Mac)', () => {
+      const { element } = setup('hello');
+      placeSelection(element, 0);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'z',
+        code: 'KeyZ',
+        metaKey: true,
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it('does not treat Ctrl+Alt+Z as undo', () => {
+      const { element } = setup('hello');
+      placeSelection(element, 0);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'z',
+        code: 'KeyZ',
+        ctrlKey: true,
+        altKey: true,
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(event);
+
+      // Alt key present, so not an undo shortcut
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it('can undo all the way back to the original content before any edits', () => {
+      // Regression: trackState() guarded on !state.position, which is only set by
+      // flushChanges() (first keyup). So the state before the very first edit was
+      // never pushed into history. Undo could only go back to after-the-first-edit,
+      // not to the original content.
+      //
+      // Use fallback mode (contentEditable='true') so edit.insert() is called
+      // synchronously from keydown, giving MutationObserver a real DOM mutation
+      // to process and making flushChanges() call onChange on keyup.
+      const element = document.createElement('pre');
+      element.textContent = 'hello';
+      document.body.appendChild(element);
+
+      let contentEditableValue = 'true';
+      Object.defineProperty(element, 'contentEditable', {
+        get() {
+          return contentEditableValue;
+        },
+        set(value: string) {
+          if (value === 'plaintext-only') {
+            throw new DOMException(
+              "Failed to set 'contentEditable': 'plaintext-only' is not supported",
+            );
+          }
+          contentEditableValue = value;
+        },
+        configurable: true,
+      });
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      const { rerender } = renderHook(() => useEditable(ref, onChange));
+
+      // Place cursor at end of 'hello' — this gives trackState() a live selection
+      // to record from on the very first keydown (before any flushChanges has run).
+      placeSelection(element, 5);
+
+      // Type 'a'. In fallback mode the keydown handler calls edit.insert('a')
+      // which mutates the DOM; flushChanges on keyup then calls onChange('helloa\n').
+      const keyDown = new KeyboardEvent('keydown', {
+        key: 'a',
+        code: 'KeyA',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyDown);
+      const keyUp = new KeyboardEvent('keyup', {
+        key: 'a',
+        code: 'KeyA',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyUp);
+
+      // Verify the edit was reported
+      expect(onChange).toHaveBeenCalledWith('helloa\n', expect.any(Object));
+
+      // Simulate the re-render that would happen in a real app after onChange fires.
+      // This resets state.disconnected (set to true by flushChanges) back to false
+      // so the next keydown can process normally rather than hitting the disconnected guard.
+      rerender();
+
+      // Undo (Ctrl+Z) — should restore the original 'hello\n', not stay at 'helloa\n'
+      const undoKey = new KeyboardEvent('keydown', {
+        key: 'z',
+        code: 'KeyZ',
+        ctrlKey: true,
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(undoKey);
+
+      const lastCall = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(lastCall[0]).toBe('hello\n');
+    });
+
+    it('undo is not a no-op after two Enter keypresses within 500ms', () => {
+      // Regression: the 500ms timestamp dedup in trackState() blocked recording a
+      // new history checkpoint on the keyup after the second Enter. historyAt was
+      // left pointing at the initial entry (index 0), so Ctrl+Z tried to go to
+      // history[-1], found nothing, reset to 0, and never called onChange — undo
+      // silently did nothing.
+      //
+      // Fix: trackState(ignoreTimestamp=true) is called on keyup for Enter so each
+      // Enter always creates its own undo checkpoint regardless of timing.
+      const element = document.createElement('pre');
+      element.textContent = 'hello';
+      document.body.appendChild(element);
+
+      let contentEditableValue = 'true';
+      Object.defineProperty(element, 'contentEditable', {
+        get() {
+          return contentEditableValue;
+        },
+        set(value: string) {
+          if (value === 'plaintext-only') {
+            throw new DOMException(
+              "Failed to set 'contentEditable': 'plaintext-only' is not supported",
+            );
+          }
+          contentEditableValue = value;
+        },
+        configurable: true,
+      });
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      const { rerender } = renderHook(() => useEditable(ref, onChange));
+
+      // Cursor in the middle of 'hello' so Enter produces a content change
+      // that differs from the original toString('hello') = 'hello\n'.
+      placeSelection(element, 3);
+
+      // First Enter
+      element.dispatchEvent(
+        new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }),
+      );
+      element.dispatchEvent(
+        new KeyboardEvent('keyup', { key: 'Enter', bubbles: true, cancelable: true }),
+      );
+      rerender(); // Simulate React re-render resetting state.disconnected
+
+      // Restore cursor after flushChanges reverted the DOM
+      placeSelection(element, 3);
+
+      // Second Enter (within 500ms of the first — triggers the 500ms dedup bug)
+      element.dispatchEvent(
+        new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }),
+      );
+      element.dispatchEvent(
+        new KeyboardEvent('keyup', { key: 'Enter', bubbles: true, cancelable: true }),
+      );
+      rerender();
+
+      const callsBefore = onChange.mock.calls.length;
+
+      // Ctrl+Z — must not be a silent no-op
+      element.dispatchEvent(
+        new KeyboardEvent('keydown', {
+          key: 'z',
+          code: 'KeyZ',
+          ctrlKey: true,
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+
+      expect(onChange.mock.calls.length).toBeGreaterThan(callsBefore);
+      // Restores the content before the first Enter
+      const lastCall = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(lastCall[0]).toBe('hello\n');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Paste
+  // ---------------------------------------------------------------------------
+  describe('paste', () => {
+    it('handles paste events', () => {
+      const { element } = setup('hello');
+      placeSelection(element, 5);
+
+      const clipboardData = {
+        getData: vi.fn().mockReturnValue(' world'),
+      };
+
+      const event = new Event('paste', { bubbles: true, cancelable: true }) as any;
+      event.clipboardData = clipboardData;
+      event.preventDefault = vi.fn();
+      element.dispatchEvent(event);
+
+      expect(event.preventDefault).toHaveBeenCalled();
+      expect(clipboardData.getData).toHaveBeenCalledWith('text/plain');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Copy / Cut
+  // ---------------------------------------------------------------------------
+  describe('copy/cut', () => {
+    /**
+     * Builds a `<pre>` mirroring the highlighter output: `display: block`
+     * `.line` spans separated by literal `\n` text node siblings. Without
+     * the copy override, copying a multi-line selection on this DOM
+     * produces duplicated newlines (one from each block element + the
+     * explicit gap text node).
+     */
+    function setupLined(linesText: string[]) {
+      const element = document.createElement('pre');
+      linesText.forEach((text, idx) => {
+        if (idx > 0) {
+          element.appendChild(document.createTextNode('\n'));
+        }
+        const line = document.createElement('span');
+        line.className = 'line';
+        // Mark as block so range.toString() still produces the canonical
+        // text — this also documents the layout being defended against.
+        line.style.display = 'block';
+        line.textContent = text;
+        element.appendChild(line);
+      });
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      const { unmount } = renderHook((props) => useEditable(props.ref, props.onChange), {
+        initialProps: { ref, onChange },
+      });
+
+      function selectAcrossLines() {
+        const lineSpans = element.querySelectorAll('.line');
+        const startText = lineSpans[0].firstChild!;
+        const endText = lineSpans[lineSpans.length - 1].firstChild!;
+        const range = document.createRange();
+        range.setStart(startText, 0);
+        range.setEnd(endText, endText.textContent!.length);
+        const selection = window.getSelection()!;
+        selection.removeAllRanges();
+        selection.addRange(range);
+      }
+
+      return { element, selectAcrossLines, onChange, unmount };
+    }
+
+    function dispatchClipboardEvent(element: HTMLElement, type: 'copy' | 'cut') {
+      const setData = vi.fn();
+      const event = new Event(type, { bubbles: true, cancelable: true }) as Event & {
+        clipboardData: { setData: typeof setData };
+      };
+      event.clipboardData = { setData } as unknown as DataTransfer & { setData: typeof setData };
+      element.dispatchEvent(event);
+      return { event, setData };
+    }
+
+    it('writes the canonical text to the clipboard on copy without duplicate newlines', () => {
+      const { element, selectAcrossLines } = setupLined(['hello', 'world']);
+      selectAcrossLines();
+
+      const { event, setData } = dispatchClipboardEvent(element, 'copy');
+
+      expect(event.defaultPrevented).toBe(true);
+      expect(setData).toHaveBeenCalledWith('text/plain', 'hello\nworld');
+    });
+
+    it('also writes the serialized HTML fragment so rich-text paste keeps highlighting', () => {
+      const { element, selectAcrossLines } = setupLined(['hello', 'world']);
+      selectAcrossLines();
+
+      const { setData } = dispatchClipboardEvent(element, 'copy');
+
+      const htmlCall = setData.mock.calls.find((call) => call[0] === 'text/html');
+      expect(htmlCall).toBeDefined();
+      const html = htmlCall![1];
+      // Both `.line` wrappers and the literal newline gap node round-trip.
+      expect(html).toContain('class="line"');
+      expect(html).toContain('hello');
+      expect(html).toContain('world');
+      // Wrapper is a `<pre>` so monospace + whitespace context survives.
+      expect(html.startsWith('<pre')).toBe(true);
+    });
+
+    it('carries the editable element className onto the clipboard wrapper', () => {
+      // Consumers scope styles by class on the editable `<pre>`; keep
+      // that class on the clipboard wrapper so paste targets that load
+      // the same stylesheet still match.
+      const element = document.createElement('pre');
+      element.className = 'code-block hljs-language-tsx';
+      ['hello', 'world'].forEach((text, idx) => {
+        if (idx > 0) {
+          element.appendChild(document.createTextNode('\n'));
+        }
+        const lineSpan = document.createElement('span');
+        lineSpan.className = 'line';
+        lineSpan.style.display = 'block';
+        lineSpan.textContent = text;
+        element.appendChild(lineSpan);
+      });
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      renderHook((props) => useEditable(props.ref, props.onChange), {
+        initialProps: { ref, onChange },
+      });
+
+      const lineSpans = element.querySelectorAll('.line');
+      const startText = lineSpans[0].firstChild!;
+      const endText = lineSpans[lineSpans.length - 1].firstChild!;
+      const range = document.createRange();
+      range.setStart(startText, 0);
+      range.setEnd(endText, endText.textContent!.length);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const { setData } = dispatchClipboardEvent(element, 'copy');
+
+      const htmlCall = setData.mock.calls.find((call) => call[0] === 'text/html');
+      const html = htmlCall![1] as string;
+      expect(html).toContain('class="code-block hljs-language-tsx"');
+    });
+
+    it('inlines the editable background color and adds rounded padding to the wrapper', () => {
+      // Paste targets that do not load the editable's stylesheet should
+      // still render with a card-like background + rounded corners that
+      // match the source visual.
+      const element = document.createElement('pre');
+      element.style.backgroundColor = 'rgb(13, 17, 23)';
+      ['hello', 'world'].forEach((text, idx) => {
+        if (idx > 0) {
+          element.appendChild(document.createTextNode('\n'));
+        }
+        const lineSpan = document.createElement('span');
+        lineSpan.className = 'line';
+        lineSpan.style.display = 'block';
+        lineSpan.textContent = text;
+        element.appendChild(lineSpan);
+      });
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      renderHook((props) => useEditable(props.ref, props.onChange), {
+        initialProps: { ref, onChange },
+      });
+
+      const lineSpans = element.querySelectorAll('.line');
+      const startText = lineSpans[0].firstChild!;
+      const endText = lineSpans[lineSpans.length - 1].firstChild!;
+      const range = document.createRange();
+      range.setStart(startText, 0);
+      range.setEnd(endText, endText.textContent!.length);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const { setData } = dispatchClipboardEvent(element, 'copy');
+      const htmlCall = setData.mock.calls.find((call) => call[0] === 'text/html');
+      const html = htmlCall![1] as string;
+
+      expect(html).toContain('background-color:rgb(13, 17, 23)');
+      expect(html).toContain('padding:1em');
+      expect(html).toContain('border-radius:0.5em');
+    });
+
+    it('inlines computed styles so external paste targets keep highlighting without our CSS', () => {
+      const element = document.createElement('pre');
+      const line = document.createElement('span');
+      line.className = 'line';
+      const token = document.createElement('span');
+      token.className = 'pl-k';
+      // Inline style so jsdom's getComputedStyle returns it.
+      token.style.color = 'rgb(255, 0, 0)';
+      token.style.fontWeight = 'bold';
+      token.textContent = 'const';
+      line.appendChild(token);
+      element.appendChild(line);
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      renderHook((props) => useEditable(props.ref, props.onChange), {
+        initialProps: { ref, onChange },
+      });
+
+      const range = document.createRange();
+      range.selectNode(token);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const setData = vi.fn();
+      const event = new Event('copy', { bubbles: true, cancelable: true }) as Event & {
+        clipboardData: { setData: typeof setData };
+      };
+      event.clipboardData = { setData } as unknown as DataTransfer & { setData: typeof setData };
+      element.dispatchEvent(event);
+
+      const htmlCall = setData.mock.calls.find((call) => call[0] === 'text/html');
+      const html = htmlCall![1] as string;
+      expect(html).toContain('color:rgb(255, 0, 0)');
+      expect(html).toContain('font-weight:bold');
+    });
+
+    it('preserves the styled wrapper when only part of a single token is selected', () => {
+      // `Range.cloneContents` returns a bare text node when the selection
+      // is entirely inside a single text node, dropping the surrounding
+      // span. Without ancestor reconstruction the partial token would
+      // serialize as `<pre>ons</pre>` and lose its highlight class.
+      const element = document.createElement('pre');
+      const line = document.createElement('span');
+      line.className = 'line';
+      const token = document.createElement('span');
+      token.className = 'pl-k';
+      token.style.color = 'rgb(255, 0, 0)';
+      token.style.fontWeight = 'bold';
+      token.textContent = 'consts';
+      line.appendChild(token);
+      element.appendChild(line);
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      renderHook((props) => useEditable(props.ref, props.onChange), {
+        initialProps: { ref, onChange },
+      });
+
+      // Select "ons" — entirely inside the token's text node.
+      const textNode = token.firstChild!;
+      const range = document.createRange();
+      range.setStart(textNode, 1);
+      range.setEnd(textNode, 4);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const setData = vi.fn();
+      const event = new Event('copy', { bubbles: true, cancelable: true }) as Event & {
+        clipboardData: { setData: typeof setData };
+      };
+      event.clipboardData = { setData } as unknown as DataTransfer & { setData: typeof setData };
+      element.dispatchEvent(event);
+
+      const htmlCall = setData.mock.calls.find((call) => call[0] === 'text/html');
+      const html = htmlCall![1] as string;
+      // The wrapping token span (with its highlight class) is preserved
+      // and styled, and the partial text content sits inside it.
+      expect(html).toContain('class="pl-k"');
+      expect(html).toContain('color:rgb(255, 0, 0)');
+      expect(html).toContain('font-weight:bold');
+      expect(html).toContain('>ons<');
+      // The intermediate `.line` ancestor is also reconstructed so the
+      // block-level layout context survives.
+      expect(html).toContain('class="line"');
+    });
+
+    it('preserves the styled wrapper when the selection spans multiple children of a token', () => {
+      // Highlighted strings are typically rendered as
+      //   <span class="pl-s"><span class="pl-pds">'</span>react<span class="pl-pds">'</span></span>
+      // Selecting from inside the opening quote across to inside the
+      // closing quote leaves `commonAncestorContainer` on `.pl-s`, which
+      // `Range.cloneContents` would drop — losing the outer string-token
+      // styling for every paste target.
+      const element = document.createElement('pre');
+      const line = document.createElement('span');
+      line.className = 'line';
+      const stringToken = document.createElement('span');
+      stringToken.className = 'pl-s';
+      stringToken.style.color = 'rgb(3, 47, 98)';
+      const openQuote = document.createElement('span');
+      openQuote.className = 'pl-pds';
+      openQuote.textContent = "'";
+      const middle = document.createTextNode('react');
+      const closeQuote = document.createElement('span');
+      closeQuote.className = 'pl-pds';
+      closeQuote.textContent = "'";
+      stringToken.append(openQuote, middle, closeQuote);
+      line.appendChild(stringToken);
+      element.appendChild(line);
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      renderHook((props) => useEditable(props.ref, props.onChange), {
+        initialProps: { ref, onChange },
+      });
+
+      // Select from inside the opening quote to inside the closing quote
+      // — the common ancestor is the `.pl-s` element.
+      const range = document.createRange();
+      range.setStart(openQuote.firstChild!, 0);
+      range.setEnd(closeQuote.firstChild!, 1);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const setData = vi.fn();
+      const event = new Event('copy', { bubbles: true, cancelable: true }) as Event & {
+        clipboardData: { setData: typeof setData };
+      };
+      event.clipboardData = { setData } as unknown as DataTransfer & { setData: typeof setData };
+      element.dispatchEvent(event);
+
+      const htmlCall = setData.mock.calls.find((call) => call[0] === 'text/html');
+      const html = htmlCall![1] as string;
+      // The outer string-token wrapper is reconstructed and styled so
+      // the middle text inherits the token-level color in paste targets.
+      expect(html).toContain('class="pl-s"');
+      expect(html).toContain('color:rgb(3, 47, 98)');
+      // The inner punctuation wrappers also survive on each side of the
+      // middle text.
+      expect(html).toContain('class="pl-pds"');
+      expect(html).toContain('react');
+    });
+
+    it('aligns style inlining when the common ancestor is the line wrapper', () => {
+      // When the selection spans multiple sibling tokens inside one
+      // `.line`, the common ancestor is `.line`. The style-inlining
+      // walks must stay aligned: the keyword token's color should land
+      // on the keyword clone, not on the reconstructed `.line` wrapper
+      // or on a later sibling.
+      const element = document.createElement('pre');
+      const line = document.createElement('span');
+      line.className = 'line';
+      line.style.display = 'block';
+      const keyword = document.createElement('span');
+      keyword.className = 'pl-k';
+      keyword.style.color = 'rgb(215, 58, 73)';
+      keyword.textContent = 'const';
+      const space = document.createTextNode(' ');
+      const ident = document.createElement('span');
+      ident.className = 'pl-c1';
+      ident.style.color = 'rgb(0, 92, 197)';
+      ident.textContent = 'foo';
+      line.append(keyword, space, ident);
+      element.appendChild(line);
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      renderHook((props) => useEditable(props.ref, props.onChange), {
+        initialProps: { ref, onChange },
+      });
+
+      // Select from inside the keyword across the space into the ident.
+      const range = document.createRange();
+      range.setStart(keyword.firstChild!, 2);
+      range.setEnd(ident.firstChild!, 2);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const setData = vi.fn();
+      const event = new Event('copy', { bubbles: true, cancelable: true }) as Event & {
+        clipboardData: { setData: typeof setData };
+      };
+      event.clipboardData = { setData } as unknown as DataTransfer & { setData: typeof setData };
+      element.dispatchEvent(event);
+
+      const htmlCall = setData.mock.calls.find((call) => call[0] === 'text/html');
+      const html = htmlCall![1] as string;
+      // The reconstructed `.line` wrapper must NOT inherit a token color
+      // — it should only carry its own styles (display:block here).
+      const lineMatch = html.match(/<span class="line"[^>]*style="([^"]*)"/);
+      expect(lineMatch).not.toBeNull();
+      expect(lineMatch![1]).not.toContain('rgb(215, 58, 73)');
+      expect(lineMatch![1]).not.toContain('rgb(0, 92, 197)');
+      // Each token clone keeps its own color on its own element.
+      expect(html).toMatch(/class="pl-k"[^>]*style="[^"]*color:rgb\(215, 58, 73\)/);
+      expect(html).toMatch(/class="pl-c1"[^>]*style="[^"]*color:rgb\(0, 92, 197\)/);
+    });
+
+    it('writes canonical text and clears the selection on cut', () => {
+      const { element, selectAcrossLines, onChange } = setupLined(['hello', 'world']);
+      selectAcrossLines();
+
+      const { event, setData } = dispatchClipboardEvent(element, 'cut');
+
+      expect(event.defaultPrevented).toBe(true);
+      expect(setData).toHaveBeenCalledWith('text/plain', 'hello\nworld');
+      // Cut should empty the selected range, leaving just the trailing \n.
+      expect(onChange).toHaveBeenCalled();
+      const lastCall = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(lastCall[0]).toBe('\n');
+    });
+
+    it('does not intercept when the selection is collapsed', () => {
+      const { element } = setupLined(['hello', 'world']);
+      const lineSpan = element.querySelector('.line')!;
+      const range = document.createRange();
+      range.setStart(lineSpan.firstChild!, 2);
+      range.collapse(true);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const { event, setData } = dispatchClipboardEvent(element, 'copy');
+
+      expect(event.defaultPrevented).toBe(false);
+      expect(setData).not.toHaveBeenCalled();
+    });
+
+    it('does not intercept when the selection is outside the editable', () => {
+      const { element } = setupLined(['hello', 'world']);
+      const outside = document.createElement('div');
+      outside.textContent = 'other';
+      document.body.appendChild(outside);
+      const range = document.createRange();
+      range.selectNodeContents(outside);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const { event, setData } = dispatchClipboardEvent(element, 'copy');
+
+      expect(event.defaultPrevented).toBe(false);
+      expect(setData).not.toHaveBeenCalled();
+    });
+
+    it('strips up to minColumn leading whitespace per line from text/plain', () => {
+      const { element } = setup('    hello\n    world\n  short', { minColumn: 4 });
+      const range = document.createRange();
+      range.selectNodeContents(element);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const { setData } = dispatchClipboardEvent(element, 'copy');
+
+      const plainCall = setData.mock.calls.find((call) => call[0] === 'text/plain');
+      // Lines 1-2 lose all 4 leading spaces; line 3 has only 2 to strip.
+      expect(plainCall![1]).toBe('hello\nworld\nshort');
+    });
+
+    it('strips up to minColumn leading whitespace per line from text/html', () => {
+      const element = document.createElement('pre');
+      const lineA = document.createElement('span');
+      lineA.className = 'line';
+      lineA.style.display = 'block';
+      lineA.textContent = '    hello';
+      const lineB = document.createElement('span');
+      lineB.className = 'line';
+      lineB.style.display = 'block';
+      lineB.textContent = '    world';
+      element.appendChild(lineA);
+      element.appendChild(document.createTextNode('\n'));
+      element.appendChild(lineB);
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+      renderHook((props) => useEditable(props.ref, props.onChange, props.opts), {
+        initialProps: { ref, onChange, opts: { minColumn: 4 } },
+      });
+
+      const range = document.createRange();
+      range.setStart(lineA.firstChild!, 0);
+      range.setEnd(lineB.firstChild!, lineB.firstChild!.textContent!.length);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const setData = vi.fn();
+      const event = new Event('copy', { bubbles: true, cancelable: true }) as Event & {
+        clipboardData: { setData: typeof setData };
+      };
+      event.clipboardData = { setData } as unknown as DataTransfer & { setData: typeof setData };
+      element.dispatchEvent(event);
+
+      const htmlCall = setData.mock.calls.find((call) => call[0] === 'text/html');
+      const html = htmlCall![1] as string;
+      // Leading 4-space indent removed from each `.line`'s text content.
+      expect(html).not.toContain('    hello');
+      expect(html).not.toContain('    world');
+      expect(html).toContain('hello');
+      expect(html).toContain('world');
+    });
+
+    it('only strips the remaining gutter portion when the selection starts mid-gutter', () => {
+      // 6 spaces of indent + content, minColumn=4. User selects starting
+      // from column 2 — they grabbed 2 of the 4 gutter spaces explicitly
+      // plus 2 real-indent spaces. Only the remaining 2 gutter spaces
+      // (minColumn - startColumn = 4 - 2) should be stripped, preserving
+      // the 2 real-indent spaces in the captured text.
+      const { element } = setup('      hello\n      world', { minColumn: 4 });
+      const textNode = element.firstChild!;
+      const range = document.createRange();
+      range.setStart(textNode, 2);
+      range.setEnd(textNode, '      hello\n      world'.length);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const { setData } = dispatchClipboardEvent(element, 'copy');
+
+      const plainCall = setData.mock.calls.find((call) => call[0] === 'text/plain');
+      // First line: 4 captured spaces - 2 stripped = 2 spaces kept + "hello".
+      // Second line: starts at column 0 of the document, so full 4-space
+      // gutter is stripped, leaving 2 real-indent spaces + "world".
+      expect(plainCall![1]).toBe('  hello\n  world');
+    });
+
+    it('strips nothing on the first line when the selection starts past the gutter', () => {
+      // minColumn=4 but selection starts at column 4 — no gutter is
+      // captured for the first line, so no stripping should occur there.
+      const { element } = setup('      hello\n      world', { minColumn: 4 });
+      const textNode = element.firstChild!;
+      const range = document.createRange();
+      range.setStart(textNode, 4);
+      range.setEnd(textNode, '      hello\n      world'.length);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const { setData } = dispatchClipboardEvent(element, 'copy');
+
+      const plainCall = setData.mock.calls.find((call) => call[0] === 'text/plain');
+      expect(plainCall![1]).toBe('  hello\n  world');
+    });
+
+    it('keeps the gutter whitespace in the document when cut starts inside the gutter', () => {
+      // minColumn=4 — first 4 chars of each line are clipped indent
+      // gutter. A drag-cut starting at column 2 of line 1 must not
+      // delete the unselected/unpublished gutter chars from the
+      // document: cut should be lossless against the clipboard.
+      const { element, onChange } = setup('      hello\n      world', { minColumn: 4 });
+      const textNode = element.firstChild!;
+      const range = document.createRange();
+      range.setStart(textNode, 2);
+      range.setEnd(textNode, '      hello\n      world'.length);
+      const selection = window.getSelection()!;
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const { setData } = dispatchClipboardEvent(element, 'cut');
+
+      // Clipboard payload omits the gutter (matches what the user saw).
+      const plainCall = setData.mock.calls.find((call) => call[0] === 'text/plain');
+      expect(plainCall![1]).toBe('  hello\n  world');
+
+      // The document keeps the stripped gutter chars at the cut location:
+      // the 2 unselected leading chars + the 2 stripped gutter chars
+      // restored = 4 spaces on line 1, then \n + 4 stripped gutter
+      // spaces on line 2, then a trailing newline.
+      const lastCall = onChange.mock.calls[onChange.mock.calls.length - 1];
+      expect(lastCall[0]).toBe('    \n    \n');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // preParse option
+  // ---------------------------------------------------------------------------
+  describe('preParse option', () => {
+    /**
+     * Mounts `useEditable` with a `preParse` callback. Returns the same
+     * helpers as `setup` plus the `preParse` mock.
+     */
+    function setupWithPreParse(
+      initialContent: string,
+      preParse: (text: string, position: Position, signal: AbortSignal) => Promise<unknown>,
+    ) {
+      const element = document.createElement('pre');
+      element.textContent = initialContent;
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position, preParsed?: unknown) => void>();
+
+      const { result, rerender, unmount } = renderHook(
+        (props: { tick: number }) => {
+          // `tick` is read so each rerender re-invokes the hook and its
+          // useLayoutEffect re-attaches the MutationObserver after a
+          // flushChanges() disconnect.
+          void props.tick;
+          return useEditable(ref, onChange, { preParse });
+        },
+        { initialProps: { tick: 0 } },
+      );
+      placeSelection(element, 0);
+
+      let tick = 0;
+      const reattach = () => {
+        tick += 1;
+        rerender({ tick });
+      };
+
+      return { element, ref, onChange, result, reattach, unmount };
+    }
+
+    /**
+     * Simulate a single character typed into `element` at the end of the
+     * current text. Mutates the DOM synchronously (so the MutationObserver
+     * picks it up) and dispatches a keyup so `flushChanges` runs.
+     */
+    function typeChar(element: HTMLElement, character: string) {
+      const text = (element.textContent ?? '') + character;
+      element.textContent = text;
+      placeSelection(element, text.length);
+      element.dispatchEvent(
+        new KeyboardEvent('keyup', { key: character, bubbles: true, cancelable: true }),
+      );
+    }
+
+    it('awaits preParse before firing onChange and forwards its result', async () => {
+      let resolvePreParse: ((value: unknown) => void) | undefined;
+      const preParseResult = { type: 'root', children: [] };
+      const preParse = vi.fn(
+        () =>
+          new Promise<unknown>((resolve) => {
+            resolvePreParse = resolve;
+          }),
+      );
+
+      const { element, onChange } = setupWithPreParse('hello', preParse);
+
+      typeChar(element, 'a');
+
+      // onChange must NOT have fired yet — preParse is still pending
+      expect(preParse).toHaveBeenCalledTimes(1);
+      expect(onChange).not.toHaveBeenCalled();
+
+      resolvePreParse!(preParseResult);
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      const [text, , forwarded] = onChange.mock.calls[0];
+      expect(text).toBe('helloa\n');
+      expect(forwarded).toBe(preParseResult);
+    });
+
+    it('aborts the prior preParse when a newer keystroke flushes', async () => {
+      const signals: AbortSignal[] = [];
+      let resolveSecond: ((value: unknown) => void) | undefined;
+      let callCount = 0;
+      const preParse = vi.fn((_text: string, _pos: Position, signal: AbortSignal) => {
+        signals.push(signal);
+        callCount += 1;
+        if (callCount === 1) {
+          // Never resolve — the second flush should abort it.
+          return new Promise<unknown>(() => {});
+        }
+        return new Promise<unknown>((resolve) => {
+          resolveSecond = resolve;
+        });
+      });
+
+      const { element, onChange, reattach } = setupWithPreParse('hello', preParse);
+
+      typeChar(element, 'a');
+      expect(signals[0].aborted).toBe(false);
+
+      // Re-attach the MutationObserver so the next typeChar's mutation is
+      // recorded. flushChanges() disconnects the observer; in production a
+      // React commit re-attaches via useLayoutEffect — we simulate that
+      // commit explicitly with a rerender.
+      reattach();
+
+      typeChar(element, 'b');
+      // The first signal must now be aborted by the second flush.
+      expect(signals[0].aborted).toBe(true);
+      expect(signals[1].aborted).toBe(false);
+
+      resolveSecond!({ type: 'root', children: [] });
+      await Promise.resolve();
+      await Promise.resolve();
+
+      // Only the second (most recent) flush reaches onChange. With the
+      // deferred-revert flow the DOM stays mutated through the first
+      // preParse, so the second typeChar appends to "helloa" — yielding
+      // "helloab".
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange.mock.calls[0][0]).toBe('helloab\n');
+    });
+
+    it('falls back to onChange without preParseResult when preParse rejects (non-abort)', async () => {
+      let rejectPreParse: ((reason?: unknown) => void) | undefined;
+      const preParse = vi.fn(
+        () =>
+          new Promise<unknown>((_resolve, reject) => {
+            rejectPreParse = reject;
+          }),
+      );
+
+      const { element, onChange } = setupWithPreParse('hello', preParse);
+
+      typeChar(element, 'a');
+      rejectPreParse!(new Error('parse failed'));
+      await Promise.resolve();
+      await Promise.resolve();
+
+      // Fail-open: the typed source still propagates so the controlled
+      // state and the live DOM stay consistent. The third (preParseResult)
+      // argument is omitted to signal "no parse available".
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange.mock.calls[0][0]).toBe('helloa\n');
+      expect(onChange.mock.calls[0][2]).toBeUndefined();
+    });
+
+    it('drops the rejection silently when preParse is aborted by a newer keystroke', async () => {
+      const deferreds: Array<{
+        resolve: (value: unknown) => void;
+        reject: (reason?: unknown) => void;
+      }> = [];
+      const preParse = vi.fn(
+        () =>
+          new Promise<unknown>((resolve, reject) => {
+            deferreds.push({ resolve, reject });
+          }),
+      );
+
+      const { element, onChange, reattach } = setupWithPreParse('hello', preParse);
+
+      typeChar(element, 'a');
+      expect(deferreds).toHaveLength(1);
+
+      // A second keystroke aborts the first preParse before its rejection
+      // arrives. The aborted rejection must NOT trigger a fallback commit.
+      reattach();
+      typeChar(element, 'b');
+      expect(deferreds).toHaveLength(2);
+
+      deferreds[0].reject(new Error('aborted-stale'));
+      await Promise.resolve();
+      await Promise.resolve();
+
+      // No commit yet — the second preParse is still pending.
+      expect(onChange).not.toHaveBeenCalled();
+
+      // Resolving the second preParse commits the combined edit normally.
+      deferreds[1].resolve('parsed-b');
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange.mock.calls[0][0]).toBe('helloab\n');
+      expect(onChange.mock.calls[0][2]).toBe('parsed-b');
+    });
+
+    it('aborts in-flight preParse on unmount', async () => {
+      const signals: AbortSignal[] = [];
+      const preParse = vi.fn((_text: string, _pos: Position, signal: AbortSignal) => {
+        signals.push(signal);
+        return new Promise<unknown>(() => {});
+      });
+
+      const { element, unmount } = setupWithPreParse('hello', preParse);
+
+      typeChar(element, 'a');
+      expect(signals[0].aborted).toBe(false);
+
+      unmount();
+      expect(signals[0].aborted).toBe(true);
+    });
+
+    it('bypasses preParse on Enter so onChange fires synchronously', () => {
+      const preParse = vi.fn(() => new Promise<unknown>(() => {}));
+
+      const { element, onChange } = setupWithPreParse('hello', preParse);
+      placeSelection(element, 5);
+
+      element.dispatchEvent(
+        new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }),
+      );
+      element.dispatchEvent(
+        new KeyboardEvent('keyup', { key: 'Enter', bubbles: true, cancelable: true }),
+      );
+
+      // Enter routes through edit.insert (sync onChange) AND triggers a
+      // bypass flush on keyup. Either way, preParse must NOT have gated
+      // the React state sync, and onChange must have a 2-arg call.
+      expect(onChange).toHaveBeenCalled();
+      const lastCall = onChange.mock.calls[onChange.mock.calls.length - 1];
+      // The bypass path passes only (text, position) — preParseResult is undefined.
+      expect(lastCall[2]).toBeUndefined();
+    });
+
+    it('does not lose a straggler keystroke that arrives before the in-flight preParse resolves', async () => {
+      // Regression for a typing-fast bug: when preParse('helloa') resolved
+      // BEFORE the next keystroke's keyup fired, commit() used to revert
+      // both the 'a' AND the straggler 'b' mutations and then fire
+      // onChange('helloa'). React rendered "helloa" — the user's 'b' was
+      // permanently lost. The fix: commit must bail when stragglers are
+      // detected and let the straggler's own keyup-triggered flush
+      // produce a fresher commit that includes the new character.
+      let resolveFirst: ((value: unknown) => void) | undefined;
+      let resolveSecond: ((value: unknown) => void) | undefined;
+      let callCount = 0;
+      const preParse = vi.fn((_text: string, _pos: Position, _signal: AbortSignal) => {
+        callCount += 1;
+        return new Promise<unknown>((resolve) => {
+          if (callCount === 1) {
+            resolveFirst = resolve;
+          } else {
+            resolveSecond = resolve;
+          }
+        });
+      });
+
+      const { element, onChange, reattach } = setupWithPreParse('hello', preParse);
+
+      // Type 'a' the normal way: DOM mutation + keyup → flushChanges →
+      // preParse('helloa') in flight.
+      typeChar(element, 'a');
+      expect(preParse).toHaveBeenCalledTimes(1);
+      expect(onChange).not.toHaveBeenCalled();
+
+      // Simulate a 'b' keydown landing in the DOM BEFORE preParse('helloa')
+      // resolves and BEFORE the 'b' keyup fires. The MutationObserver picks
+      // it up asynchronously.
+      element.textContent = 'helloab';
+      placeSelection(element, 6);
+      // Let the observer's microtask deliver the mutation into state.queue.
+      await Promise.resolve();
+
+      // Now resolve preParse('helloa'). With the bug, commit would revert
+      // both mutations and call onChange('helloa'). With the fix, commit
+      // detects the straggler and bails — onChange must NOT fire and the
+      // DOM must still contain the 'b'.
+      resolveFirst!({ type: 'root', children: [] });
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(onChange).not.toHaveBeenCalled();
+      expect(element.textContent).toBe('helloab');
+
+      // The 'b' keyup eventually fires → flushChanges sees the queued
+      // mutations, computes content = "helloab", starts preParse('helloab').
+      // No reattach() needed because the bail kept the observer connected.
+      element.dispatchEvent(
+        new KeyboardEvent('keyup', { key: 'b', bubbles: true, cancelable: true }),
+      );
+      expect(preParse).toHaveBeenCalledTimes(2);
+      expect(preParse.mock.calls[1][0]).toBe('helloab\n');
+
+      resolveSecond!({ type: 'root', children: [] });
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange.mock.calls[0][0]).toBe('helloab\n');
+
+      // Sanity: the next round trip still works after a bailed commit.
+      reattach();
+      typeChar(element, 'c');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('cleanup', () => {
+    it('removes event listeners on unmount', () => {
+      const windowRemove = vi.spyOn(window, 'removeEventListener');
+      const documentRemove = vi.spyOn(document, 'removeEventListener');
+
+      const { element, unmount } = setup('hello');
+      const elementRemove = vi.spyOn(element, 'removeEventListener');
+
+      unmount();
+
+      expect(windowRemove).toHaveBeenCalledWith('keydown', expect.any(Function));
+      expect(documentRemove).toHaveBeenCalledWith('selectstart', expect.any(Function));
+      expect(elementRemove).toHaveBeenCalledWith('paste', expect.any(Function));
+      expect(elementRemove).toHaveBeenCalledWith('copy', expect.any(Function));
+      expect(elementRemove).toHaveBeenCalledWith('cut', expect.any(Function));
+      expect(elementRemove).toHaveBeenCalledWith('keyup', expect.any(Function));
+      expect(elementRemove).toHaveBeenCalledWith('mouseup', expect.any(Function));
+      expect(elementRemove).toHaveBeenCalledWith('focus', expect.any(Function));
+
+      windowRemove.mockRestore();
+      documentRemove.mockRestore();
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // MutationObserver
+  // ---------------------------------------------------------------------------
+  describe('MutationObserver', () => {
+    it('observes the element for mutations', () => {
+      const observeSpy = vi.spyOn(MutationObserver.prototype, 'observe');
+
+      setup('hello');
+
+      expect(observeSpy).toHaveBeenCalledWith(
+        expect.any(HTMLElement),
+        expect.objectContaining({
+          characterData: true,
+          characterDataOldValue: true,
+          childList: true,
+          subtree: true,
+        }),
+      );
+
+      observeSpy.mockRestore();
+    });
+
+    it('disconnects the observer on unmount', () => {
+      const disconnectSpy = vi.spyOn(MutationObserver.prototype, 'disconnect');
+
+      const { unmount } = setup('hello');
+      unmount();
+
+      expect(disconnectSpy).toHaveBeenCalled();
+
+      disconnectSpy.mockRestore();
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Multiline content
+  // ---------------------------------------------------------------------------
+  describe('multiline content', () => {
+    it('getState returns correct text for multiline content', () => {
+      const { result, element } = setup('line 1\nline 2\nline 3');
+      placeSelection(element, 0);
+
+      const state = result.current.getState();
+      expect(state.text).toBe('line 1\nline 2\nline 3\n');
+    });
+
+    it('getState tracks line number correctly', () => {
+      const { result, element } = setup('line 1\nline 2\nline 3');
+      // Place caret at the start of line 2
+      placeSelection(element, 7);
+
+      const state = result.current.getState();
+      expect(state.position.line).toBe(1);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Edge cases
+  // ---------------------------------------------------------------------------
+  describe('edge cases', () => {
+    it('handles empty content', () => {
+      // An empty string sets textContent to '' which creates no child nodes.
+      // toString() assumes firstChild exists, so this is a known edge case
+      // that crashes. Verify the hook initializes without throwing.
+      const element = document.createElement('pre');
+      element.textContent = '';
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn();
+
+      // The hook should mount without error (toString is only called on interaction)
+      const { result } = renderHook(() => useEditable(ref, onChange));
+      expect(result.current).toBeDefined();
+    });
+
+    it('handles null element ref gracefully', () => {
+      const ref: { current: HTMLElement | null } = { current: null };
+      const onChange = vi.fn();
+
+      // Should not throw
+      const { result } = renderHook(() => useEditable(ref, onChange));
+      expect(result.current).toBeDefined();
+    });
+
+    it('works without options parameter', () => {
+      const element = document.createElement('pre');
+      element.textContent = 'hello';
+      document.body.appendChild(element);
+
+      const ref = { current: element };
+      const onChange = vi.fn();
+
+      // Should not throw when opts is undefined
+      const { result } = renderHook(() => useEditable(ref, onChange));
+      expect(result.current).toBeDefined();
+    });
+
+    it('handles repeated key events (key held down)', () => {
+      const { element } = setup('hello');
+      placeSelection(element, 0);
+
+      const event = new KeyboardEvent('keydown', {
+        key: 'a',
+        repeat: true,
+        bubbles: true,
+        cancelable: true,
+      });
+      // Should not throw
+      element.dispatchEvent(event);
+
+      expect(element).toBeDefined();
+    });
+
+    it('does not restore stale cursor position when a re-render fires during key-hold', () => {
+      // Regression: during the 100ms debounce window (repeatFlushId is set),
+      // a re-render caused by an external setState (e.g. async enhancer) was
+      // running the no-deps useLayoutEffect and calling setCurrentRange with the
+      // stale state.position, teleporting the cursor back on every repeat
+      // keydown → re-render cycle.
+      const element = document.createElement('pre');
+      element.textContent = 'hello';
+      document.body.appendChild(element);
+      const ref = { current: element };
+      const onChange = vi.fn<(text: string, position: Position) => void>();
+
+      const { result, rerender } = renderHook(
+        (props) => useEditable(props.ref, props.onChange, props.opts),
+        { initialProps: { ref, onChange, opts: {} } },
+      );
+
+      placeSelection(element, 0);
+
+      // Establish a non-null state.position via edit.update.
+      // This simulates the state after the user's first edit has flushed.
+      act(() => {
+        result.current.update('hello');
+      });
+
+      // Move the cursor to position 2 (mid-word) to simulate forward typing
+      placeSelection(element, 2);
+
+      // Dispatch a repeat keydown — this sets state.repeatFlushId (debounce timer)
+      const keyDown = new KeyboardEvent('keydown', {
+        key: 'x',
+        code: 'KeyX',
+        repeat: true,
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyDown);
+
+      // Snapshot cursor position before the incidental re-render
+      const selectionBefore = window.getSelection()!.getRangeAt(0).cloneRange();
+
+      // Trigger a re-render while the debounce timer is active.
+      // Without the fix, the no-deps useLayoutEffect would call setCurrentRange
+      // with state.position (offset 0 from edit.update) and jump the cursor back.
+      rerender({ ref, onChange: vi.fn(), opts: {} });
+
+      // Cursor must remain at position 2, not jump back to state.position (0)
+      const selectionAfter = window.getSelection()!.getRangeAt(0);
+      expect(selectionAfter.startContainer).toBe(selectionBefore.startContainer);
+      expect(selectionAfter.startOffset).toBe(selectionBefore.startOffset);
+
+      // Clean up the debounce timer via keyup
+      const keyUp = new KeyboardEvent('keyup', {
+        key: 'x',
+        code: 'KeyX',
+        bubbles: true,
+        cancelable: true,
+      });
+      element.dispatchEvent(keyUp);
+    });
+  });
+});
diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
new file mode 100644
index 000000000..9aee30697
--- /dev/null
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -0,0 +1,1369 @@
+/*
+
+MIT License
+
+Copyright (c) 2020 Phil Plückthun,
+Copyright (c) 2021 Formidable
+Copyright (c) 2026 Material-UI SAS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+*/
+
+// Forked from https://github.com/FormidableLabs/use-editable
+// Changes (see git history and inline comments for rationale):
+// - Linting, formatting, tests, and React 19 compatibility (lazy useState, useRef MutationObserver, SSR guards)
+// - Performance: TreeWalker-based makeRange/getPosition, deduped toString() calls, getLineInfo walks only neighboring lines
+// - Firefox quirks: preserve pendingContent across rapid keydowns, refresh baseline after controlled edits, repair line-merges, route plaintext keys through edit.insert in the contentEditable="true" fallback
+// - Undo stack: record repaired (not raw) content, allow tracking before first flush, bypass 500ms dedup for structural edits (Enter)
+// - Repeat-key flush debouncing so syntax re-highlight fires once on key release
+// - Resync (instead of block) on stale-DOM arrow keys so navigation isn't eaten after a pending edit
+// - adjustCursorAtNewlineBoundary applied to all programmatic caret placements; getState() returns an empty snapshot pre-mount
+// - New `minColumn` option: skip clipped indent gutter via arrow navigation, click, and tab-focus; Backspace on a fully-clipped blank line collapses the line
+// - New `minRow`/`maxRow`/`onBoundary` options: arrow navigation past the visible region invokes the callback (and falls through natively when provided so hosts can expand collapsed regions)
+// - New `caretSelector` option: synchronous horizontal line-wrap and post-arrow rAF snap to lift the caret out of inter-line gap text nodes (e.g. `\n` between `.line` spans)
+// - Override copy/cut: write `Range.toString()` for `text/plain` (avoids duplicated newlines from block-level line wrappers) and an inline-styled `<pre>` clone for `text/html`; strip the clipped indent gutter from both payloads when `minColumn` is set
+
+import * as React from 'react';
+import * as ReactDOM from 'react-dom';
+
+import {
+  type Position,
+  adjustCursorAtNewlineBoundary,
+  asElement,
+  getCurrentRange,
+  getLineInfo,
+  getOffsetAtLineColumn,
+  getPosition,
+  isPlaintextInputKey,
+  isUndoRedoKey,
+  makeRange,
+  repairUnexpectedLineMerge,
+  setCurrentRange,
+  toString,
+} from './useEditableUtils';
+import { cloneRangeWithInlineStyles } from './cloneRangeWithInlineStyles';
+import {
+  extractLeadingPerLine,
+  stripLeadingPerLine,
+  stripLeadingPerLineDom,
+} from './stripLeadingPerLine';
+
+export type { Position } from './useEditableUtils';
+
+type History = [Position, string];
+
+const observerSettings = {
+  characterData: true,
+  characterDataOldValue: true,
+  childList: true,
+  subtree: true,
+};
+
+// Computed-style properties inlined onto each element in the copied
+// HTML fragment so external paste targets render with the same syntax
+// highlighting without needing our stylesheet.
+const CLIPBOARD_ELEMENT_STYLE_PROPS = [
+  'color',
+  'background-color',
+  'font-weight',
+  'font-style',
+  'text-decoration',
+];
+
+// Properties inlined onto the wrapper so the pasted block keeps the
+// editable's typography even if only a descendant was selected.
+const CLIPBOARD_ROOT_STYLE_PROPS = [
+  'font-family',
+  'font-size',
+  'line-height',
+  'white-space',
+  'background-color',
+  'color',
+];
+
+// A small amount of padding + rounded corners gives the pasted snippet
+// a card-like appearance in rich-text targets without overriding the
+// background or font that consumers already control via the editable's
+// own styles.
+const CLIPBOARD_ROOT_STATIC_STYLES = 'padding:1em;border-radius:0.5em;';
+
+interface State {
+  disconnected: boolean;
+  onChange(text: string, position: Position, preParseResult?: unknown): void;
+  pendingContent: string | null;
+  queue: MutationRecord[];
+  history: History[];
+  historyAt: number;
+  position: Position | null;
+  /** setTimeout id used to debounce flushChanges() calls during key-repeat */
+  repeatFlushId: ReturnType<typeof setTimeout> | null;
+  /**
+   * AbortController for the in-flight `preParse` callback (if any). Reset
+   * on every new flush so a rapidly-typed sequence aborts stale parses
+   * before posting a fresh request.
+   */
+  preParseAbort: AbortController | null;
+  /**
+   * Set when an arrow-key handler invokes `onBoundary` (which typically
+   * triggers a host re-render to expand a collapsed region). The native
+   * arrow-key default action moves the caret AFTER our keydown handler
+   * returns, but the host's re-render commits BEFORE the resulting
+   * `selectionchange` updates `state.position`. Without this flag, the
+   * unconditional restore effect would snap the caret back to the stale
+   * pre-arrow `state.position` on that intermediate render. The flag is
+   * cleared after one skipped restore.
+   */
+  skipNextRestore: boolean;
+}
+
+export interface Options<TPreParseResult = unknown> {
+  disabled?: boolean;
+  indentation?: number;
+  /**
+   * Minimum column the cursor is allowed to occupy on indented lines.
+   *
+   * When set, horizontal arrow navigation skips over the leading whitespace
+   * up to `minColumn` so the caret never lands inside a clipped/hidden
+   * indent region:
+   *
+   * - `ArrowLeft` at column `minColumn` (with that line's first `minColumn`
+   *   characters all whitespace) jumps to the end of the previous line
+   *   instead of stepping into the indent.
+   * - `ArrowRight` at the end of a line jumps to column `minColumn` of the
+   *   next line (when the next line is indented at least that far) instead
+   *   of landing at column 0.
+   *
+   * Useful when the editor is rendered in a horizontally-shifted view (for
+   * example a collapsed code block whose left padding is translated off
+   * screen) where columns below `minColumn` are not visible. Leave
+   * `undefined` for default arrow-key behavior.
+   */
+  minColumn?: number;
+  /**
+   * First row of the visible region. When set, `ArrowUp` on this row and
+   * `ArrowLeft` at the start of this row are blocked (no caret movement)
+   * and `onBoundary` is invoked. Useful when content above the visible
+   * region is hidden and the host wants a chance to reveal it.
+   */
+  minRow?: number;
+  /**
+   * Last row of the visible region. When set, `ArrowDown` on this row and
+   * `ArrowRight` at the end of this row are blocked (no caret movement)
+   * and `onBoundary` is invoked.
+   */
+  maxRow?: number;
+  /**
+   * Called when the user attempts to navigate past `minRow`/`maxRow` via
+   * arrow keys. When `onBoundary` is provided, the navigation is allowed
+   * to proceed natively so the host can react (e.g. expand a collapsed
+   * code block) and the caret continues moving in the now-visible
+   * content. When `onBoundary` is omitted, the navigation is blocked
+   * (caret stays put).
+   */
+  onBoundary?: () => void;
+  /**
+   * CSS selector identifying the elements that represent selectable
+   * "lines" inside the editable. When set, and only while the caret is
+   * actually inside an element matching the selector:
+   *
+   * - `ArrowLeft` at column 0 jumps synchronously to the end of the
+   *   previous line.
+   * - `ArrowRight` at the end of a line jumps synchronously to the start
+   *   of the next line.
+   *
+   * Useful when the editable contains intentionally-empty whitespace
+   * text nodes between block-level children (e.g. newline text nodes
+   * separating `.line` spans inside a `.frame`). Without this, the
+   * browser would place the caret in those gap nodes on horizontal
+   * navigation, making `ArrowLeft`/`ArrowRight` appear to no-op.
+   *
+   * Vertical navigation (`ArrowUp`/`ArrowDown`) is intentionally left to
+   * the browser so wrapped visual lines in `pre-wrap` layouts continue
+   * to behave natively. Gap nodes styled with `line-height: 0` are
+   * skipped by browsers vertically without intervention.
+   *
+   * The selector is matched against the caret's containing element via
+   * `Element.closest`, so non-`.line` render paths (e.g. plain-string
+   * editables) never trigger the wrap behavior.
+   */
+  caretSelector?: string;
+  /**
+   * Optional async pre-parse hook invoked before each `onChange` flush.
+   * When provided, the parser receives the post-edit `text` and caret
+   * `position` plus an `AbortSignal` that fires when a newer keystroke
+   * supersedes this flush. Its resolved value is forwarded as the third
+   * argument to `onChange`, allowing the host to cache an already-parsed
+   * HAST (or any other derived state) keyed off the same source string.
+   *
+   * If `preParse` is omitted, `onChange` runs synchronously inside the
+   * keyup / debounce handler as before. If it is provided, the React
+   * state sync is delayed until the returned promise settles. Structural
+   * edits that need a synchronous re-render (Enter, paste, cut, undo/redo,
+   * programmatic `edit.update`/`edit.insert`, `minColumn` blank-line
+   * collapse) bypass `preParse` and fire `onChange` immediately without
+   * a third argument.
+   */
+  preParse?: (text: string, position: Position, signal: AbortSignal) => Promise<TPreParseResult>;
+}
+
+export interface Edit {
+  /** Replaces the entire content of the editable while adjusting the caret position. */
+  update(content: string): void;
+  /** Inserts new text at the caret position while deleting text in range of the offset (which accepts negative offsets). */
+  insert(append: string, offset?: number): void;
+  /** Positions the caret where specified */
+  move(pos: number | { row: number; column: number }): void;
+  /** Returns the current editor state, as usually received in onChange */
+  getState(): { text: string; position: Position };
+}
+
+export const useEditable = <TPreParseResult = unknown>(
+  elementRef: { current: HTMLElement | undefined | null },
+  onChange: (text: string, position: Position, preParseResult?: TPreParseResult) => void,
+  opts?: Options<TPreParseResult>,
+): Edit => {
+  // Normalize once into a non-optional local so closures (effects, the
+  // edit object, event handlers) can read `config.X` directly without
+  // any non-null assertions on `opts`.
+  const config: Options<TPreParseResult> = opts ?? {};
+
+  const unblock = React.useState([])[1];
+  const state = React.useState<State>(() => ({
+    disconnected: false,
+    onChange,
+    pendingContent: null,
+    queue: [],
+    history: [],
+    historyAt: -1,
+    position: null,
+    repeatFlushId: null,
+    skipNextRestore: false,
+    preParseAbort: null,
+  }))[0];
+
+  // MutationObserver is created once via useRef so it is never recreated on
+  // re-render and is not subject to React Strict Mode double-invocation of
+  // useState initializers (which would silently discard the first observer).
+  const observerRef = React.useRef<MutationObserver | null>(null);
+  if (observerRef.current === null && typeof MutationObserver !== 'undefined') {
+    observerRef.current = new MutationObserver((batch) => {
+      state.queue.push(...batch);
+    });
+  }
+
+  // The visible-region bounds (`minColumn`/`minRow`/`maxRow`/`onBoundary`)
+  // and `caretSelector` only affect handler logic, not the contentEditable
+  // setup itself. We mirror them in a ref so the handlers always read the
+  // latest values, while keeping these values out of the main effect's deps.
+  // Listing them as deps would tear down and re-bind contentEditable every
+  // time they change (e.g. when a host expands a collapsed code block),
+  // which causes the browser to drop focus mid-animation.
+  const boundsRef = React.useRef({
+    minColumn: config.minColumn,
+    minRow: config.minRow,
+    maxRow: config.maxRow,
+    onBoundary: config.onBoundary,
+    caretSelector: config.caretSelector,
+    preParse: config.preParse,
+  });
+  boundsRef.current.minColumn = config.minColumn;
+  boundsRef.current.minRow = config.minRow;
+  boundsRef.current.maxRow = config.maxRow;
+  boundsRef.current.onBoundary = config.onBoundary;
+  boundsRef.current.caretSelector = config.caretSelector;
+  boundsRef.current.preParse = config.preParse;
+
+  // useMemo with [] is a performance hint, not a semantic guarantee — React 19
+  // may discard the cache and recreate the object. useState with a lazy
+  // initializer is the correct primitive for a referentially stable object.
+  const [edit] = React.useState<Edit>(() => ({
+    update(content: string) {
+      const { current: element } = elementRef;
+      if (element) {
+        const position = getPosition(element);
+        const prevContent = toString(element);
+        position.position += content.length - prevContent.length;
+        state.position = position;
+        state.onChange(content, position);
+      }
+    },
+    insert(append: string, deleteOffset?: number) {
+      const { current: element } = elementRef;
+      if (element) {
+        let range = getCurrentRange();
+        range.deleteContents();
+        range.collapse();
+        const position = getPosition(element);
+        const offset = deleteOffset || 0;
+        const start = position.position + (offset < 0 ? offset : 0);
+        const end = position.position + (offset > 0 ? offset : 0);
+        range = makeRange(element, start, end);
+        adjustCursorAtNewlineBoundary(range);
+        range.deleteContents();
+        if (append) {
+          range.insertNode(document.createTextNode(append));
+        }
+        const cursorRange = makeRange(element, start + append.length);
+        adjustCursorAtNewlineBoundary(cursorRange);
+        setCurrentRange(cursorRange);
+      }
+    },
+    move(pos: number | { row: number; column: number }) {
+      const { current: element } = elementRef;
+      if (element) {
+        element.focus();
+        const position =
+          typeof pos === 'number' ? pos : getOffsetAtLineColumn(element, pos.row, pos.column);
+        const cursorRange = makeRange(element, position);
+        adjustCursorAtNewlineBoundary(cursorRange);
+        setCurrentRange(cursorRange);
+      }
+    },
+    getState() {
+      const element = elementRef.current;
+      if (!element) {
+        // Pre-mount / unmounted: return an empty snapshot so callers
+        // that subscribe before the ref is attached get a stable shape.
+        return {
+          text: '',
+          position: { position: 0, extent: 0, content: '', line: 0 },
+        };
+      }
+      return { text: toString(element), position: getPosition(element) };
+    },
+  }));
+
+  React.useLayoutEffect(() => {
+    // Only for SSR / server-side logic
+    // typeof navigator check fails on Node.js 21+ which exposes navigator.userAgent;
+    // typeof window is the standard isomorphic SSR guard.
+    if (typeof window === 'undefined') {
+      return undefined;
+    }
+
+    state.onChange = onChange;
+
+    if (!elementRef.current || config.disabled) {
+      return undefined;
+    }
+
+    state.disconnected = false;
+    observerRef.current?.observe(elementRef.current, observerSettings);
+    // Skip restoring the cursor while a key is held down. The debounced
+    // flushChanges hasn't run yet so state.position is stale; restoring it
+    // here would jump the cursor back on every incidental re-render (e.g.
+    // from an async enhancer setState). edit.insert() already placed the
+    // cursor correctly in the DOM — leave it there until the debounce fires.
+    //
+    // Also skip on the render right after an arrow-key boundary callback
+    // (see `state.skipNextRestore`): the native arrow movement hasn't
+    // applied yet, so `state.position` is the pre-arrow location and
+    // restoring it would visibly snap the caret back upward/downward.
+    if (state.skipNextRestore) {
+      state.skipNextRestore = false;
+    } else if (state.position && state.repeatFlushId === null) {
+      const { position, extent } = state.position;
+      const cursorRange = makeRange(elementRef.current, position, position + extent);
+      adjustCursorAtNewlineBoundary(cursorRange);
+      setCurrentRange(cursorRange);
+    }
+
+    return () => {
+      observerRef.current?.disconnect();
+    };
+  });
+
+  React.useLayoutEffect(() => {
+    if (typeof window === 'undefined') {
+      return undefined;
+    }
+
+    if (!elementRef.current || config.disabled) {
+      state.history.length = 0;
+      state.historyAt = -1;
+      return undefined;
+    }
+
+    const element = elementRef.current;
+    if (!element) {
+      return undefined;
+    }
+    if (state.position) {
+      element.focus();
+      const { position, extent } = state.position;
+      const cursorRange = makeRange(element, position, position + extent);
+      adjustCursorAtNewlineBoundary(cursorRange);
+      setCurrentRange(cursorRange);
+    }
+
+    const prevWhiteSpace = element.style.whiteSpace;
+    const prevContentEditable = element.contentEditable;
+    let hasPlaintextSupport = true;
+    try {
+      // Firefox and IE11 do not support plaintext-only mode
+      element.contentEditable = 'plaintext-only';
+    } catch (_error) {
+      element.contentEditable = 'true';
+      hasPlaintextSupport = false;
+    }
+
+    if (prevWhiteSpace !== 'pre') {
+      element.style.whiteSpace = 'pre-wrap';
+    }
+
+    if (config.indentation) {
+      const tabSizeValue = `${config.indentation}`;
+      element.style.setProperty('-moz-tab-size', tabSizeValue);
+      element.style.tabSize = tabSizeValue;
+    }
+
+    const indentPattern = `${' '.repeat(config.indentation || 0)}`;
+    const indentRe = new RegExp(`^(?:${indentPattern})`);
+    const blanklineRe = new RegExp(`^(?:${indentPattern})*(${indentPattern})$`);
+
+    let trackStateTimestamp: number;
+    const trackState = (
+      ignoreTimestamp?: boolean,
+      contentOverride?: string,
+      positionOverride?: Position,
+    ): string | null => {
+      // Require a live selection so getPosition() (which calls getRangeAt(0)) is safe.
+      // Using !state.position would block recording the initial state: state.position is
+      // only set by flushChanges() which runs on keyup — after the first edit. Switching
+      // to rangeCount === 0 lets the very first keydown snapshot the pre-edit content.
+      if (!elementRef.current || (window.getSelection()?.rangeCount ?? 0) === 0) {
+        return null;
+      }
+
+      // Callers may pass in already-computed (and possibly repaired) content so
+      // we don't re-read a buggy intermediate DOM. flushChanges uses this to
+      // record the repaired post-edit state instead of the merged DOM that
+      // Firefox/observer left behind.
+      const content = contentOverride ?? toString(element);
+      const position = positionOverride ?? getPosition(element);
+      const timestamp = new Date().valueOf();
+
+      // Prevent recording new state in list if last one has been new enough
+      const lastEntry = state.history[state.historyAt];
+      if (
+        (!ignoreTimestamp && timestamp - trackStateTimestamp < 500) ||
+        (lastEntry && lastEntry[1] === content)
+      ) {
+        trackStateTimestamp = timestamp;
+        return content;
+      }
+
+      state.historyAt += 1;
+      const at = state.historyAt;
+      state.history[at] = [position, content];
+      state.history.splice(at + 1);
+      if (at > 500) {
+        state.historyAt -= 1;
+        state.history.shift();
+      }
+      return content;
+    };
+
+    const disconnect = () => {
+      observerRef.current?.disconnect();
+      state.disconnected = true;
+    };
+
+    const flushChanges = (ignoreTimestamp?: boolean, bypassPreParse?: boolean) => {
+      const records = observerRef.current?.takeRecords() ?? [];
+      state.queue.push(...records);
+      const position = getPosition(element);
+      if (state.queue.length) {
+        // We DO NOT revert the queued mutations yet — letting them stay in
+        // the live DOM means the user's keystroke remains visible while
+        // `preParse` runs. The mutation queue is held until commit (below)
+        // so when React eventually re-renders the highlighted content, it
+        // first sees its expected previous DOM.
+        const content = repairUnexpectedLineMerge(
+          toString(element),
+          state.pendingContent,
+          position,
+        );
+        state.position = position;
+
+        // Record the REPAIRED content into history before notifying the app.
+        // Reading toString() back from the DOM here would capture the buggy
+        // pre-repair state (e.g. a Firefox line-merge), which is what was
+        // previously polluting the undo stack.
+        trackState(ignoreTimestamp, content, position);
+
+        // Snapshot the queue length representing mutations that belong to
+        // THIS flush. Anything appended past this index by the time
+        // `commit` runs is a straggler — a newer keystroke whose own
+        // keyup-triggered `flushChanges` will produce a fresher commit. In
+        // that case we must NOT revert the stragglers (or we'd lose the
+        // user's character) and we must NOT call `onChange` with our now
+        // stale `content` (or we'd briefly render the older state on top
+        // of the newer DOM).
+        const queueLengthAtFlush = state.queue.length;
+
+        // Commit phase: revert the queued mutations and hand control to
+        // React. The revert + React commit are bundled into a single task
+        // via `flushSync` so the browser cannot paint the briefly-reverted
+        // DOM between the two — the user's keystroke stays continuously on
+        // screen, transitioning directly from "raw mutation" to
+        // "highlighted React render".
+        const commit = (preParseResult?: unknown) => {
+          // Drain anything pending in the observer first so we have an
+          // accurate count of stragglers (mutations made after this
+          // flush started). The observer stays connected during the
+          // `preParse` await so additional keystrokes ARE captured but
+          // are NOT blocked by the `state.disconnected` guard in
+          // `onKeyDown`.
+          const stragglers = observerRef.current?.takeRecords() ?? [];
+          state.queue.push(...stragglers);
+          if (state.queue.length > queueLengthAtFlush) {
+            // A newer keystroke landed in the DOM after this flush
+            // started. Drop this commit on the floor — the straggler's
+            // own `flushChanges` (already running, or about to run on
+            // its keyup) will produce a fresher commit that reverts the
+            // entire combined mutation set and reports the up-to-date
+            // content. Leaving the observer connected and
+            // `state.disconnected` false lets onKeyDown keep accepting
+            // input in the meantime.
+            return;
+          }
+          disconnect();
+          while (state.queue.length > 0) {
+            const mutation = state.queue.pop();
+            if (!mutation) {
+              break;
+            }
+            if (mutation.oldValue !== null) {
+              mutation.target.textContent = mutation.oldValue;
+            }
+            for (let i = mutation.removedNodes.length - 1; i >= 0; i -= 1) {
+              mutation.target.insertBefore(mutation.removedNodes[i], mutation.nextSibling);
+            }
+            for (let i = mutation.addedNodes.length - 1; i >= 0; i -= 1) {
+              if (mutation.addedNodes[i].parentNode) {
+                mutation.target.removeChild(mutation.addedNodes[i]);
+              }
+            }
+          }
+          ReactDOM.flushSync(() => {
+            if (preParseResult === undefined) {
+              // Preserve the historical (text, position) calling convention
+              // for the sync / bypass path so consumers can distinguish a
+              // preParse-result-less commit from one whose result happened
+              // to be `undefined`.
+              state.onChange(content, position);
+            } else {
+              state.onChange(content, position, preParseResult);
+            }
+          });
+        };
+
+        const { preParse } = boundsRef.current;
+        if (preParse && !bypassPreParse) {
+          // Abort any prior in-flight preParse — only the most recent
+          // keystroke's parse result is worth waiting for.
+          if (state.preParseAbort) {
+            state.preParseAbort.abort();
+          }
+          const controller = new AbortController();
+          state.preParseAbort = controller;
+          const { signal } = controller;
+          preParse(content, position, signal).then(
+            (result) => {
+              if (signal.aborted) {
+                return;
+              }
+              if (state.preParseAbort === controller) {
+                state.preParseAbort = null;
+              }
+              commit(result);
+            },
+            () => {
+              if (state.preParseAbort === controller) {
+                state.preParseAbort = null;
+              }
+              if (signal.aborted) {
+                // Aborted by a newer keystroke — drop silently. The
+                // queued mutations stay in place until the superseding
+                // flush commits them.
+                return;
+              }
+              // Real parse failure (e.g. unknown grammar, worker error).
+              // Fall back to committing without a preParseResult so the
+              // source still propagates to onChange — matching the
+              // historical sync path's fail-open behavior. Without this,
+              // the DOM would show the user's typed text while controlled
+              // state stayed stale, and the next render would revert it.
+              commit();
+            },
+          );
+        } else {
+          // Structural / synchronous edit — bypass preParse so the React
+          // state sync happens on the same commit as the DOM change.
+          if (state.preParseAbort) {
+            state.preParseAbort.abort();
+            state.preParseAbort = null;
+          }
+          commit();
+        }
+      }
+
+      state.pendingContent = null;
+    };
+
+    // Snap a collapsed caret out of an inter-line gap text node (e.g. the
+    // literal `\n` between `.line` spans) onto the nearest `.line` in
+    // `direction`. Used by both the post-arrow rAF and the pointer
+    // handlers — clicks can land in gap nodes too. When `isVertical`, the
+    // caret lands at `preferredColumn` of the target line (clamped);
+    // otherwise it lands at the start (forward) or end (backward).
+    // Returns `true` when a snap was applied.
+    const snapCaretOutOfGapNode = (
+      direction: 'forward' | 'backward',
+      isVertical: boolean,
+      preferredColumn: number,
+    ): boolean => {
+      const { caretSelector } = boundsRef.current;
+      if (caretSelector === undefined) {
+        return false;
+      }
+      const sel = element.ownerDocument.defaultView?.getSelection();
+      if (!sel || sel.rangeCount === 0 || !sel.isCollapsed) {
+        return false;
+      }
+      const snapRange = sel.getRangeAt(0);
+      if (!element.contains(snapRange.startContainer)) {
+        return false;
+      }
+      const startContainer = snapRange.startContainer;
+      const startElement = asElement(startContainer) ?? startContainer.parentElement;
+      // Caret is already inside a `.line` (or equivalent) — no snap needed.
+      if (startElement?.closest(caretSelector)) {
+        return false;
+      }
+      const lineEls = Array.from(element.querySelectorAll(caretSelector));
+      if (lineEls.length === 0) {
+        return false;
+      }
+      // Use document position to pick the right neighbour.
+      let target: Element | null = null;
+      if (direction === 'forward') {
+        for (let i = 0; i < lineEls.length; i += 1) {
+          const r = element.ownerDocument.createRange();
+          r.selectNode(lineEls[i]);
+          // cmp < 0 means the caret is before this line.
+          if (snapRange.compareBoundaryPoints(Range.START_TO_START, r) < 0) {
+            target = lineEls[i];
+            break;
+          }
+        }
+        // No line ahead — caret has landed past the last line. Snap back
+        // to the last line so the caret stays inside an editable row.
+        if (!target) {
+          target = lineEls[lineEls.length - 1];
+        }
+      } else {
+        for (let i = lineEls.length - 1; i >= 0; i -= 1) {
+          const r = element.ownerDocument.createRange();
+          r.selectNode(lineEls[i]);
+          // cmp > 0 means the caret is after this line.
+          if (snapRange.compareBoundaryPoints(Range.END_TO_END, r) > 0) {
+            target = lineEls[i];
+            break;
+          }
+        }
+        // No line behind — caret has landed before the first line.
+        if (!target) {
+          target = lineEls[0];
+        }
+      }
+      if (!target) {
+        return false;
+      }
+      const newRange = element.ownerDocument.createRange();
+      if (isVertical) {
+        // Walk the target line's text nodes to find the offset that
+        // matches `preferredColumn`, clamping to the line length.
+        const targetText = target.textContent ?? '';
+        const targetColumn = Math.min(preferredColumn, targetText.length);
+        let remaining = targetColumn;
+        const walker = element.ownerDocument.createTreeWalker(target, NodeFilter.SHOW_TEXT);
+        let placed = false;
+        let node = walker.nextNode();
+        while (node) {
+          const len = node.textContent?.length ?? 0;
+          if (remaining <= len) {
+            newRange.setStart(node, remaining);
+            newRange.collapse(true);
+            placed = true;
+            break;
+          }
+          remaining -= len;
+          node = walker.nextNode();
+        }
+        if (!placed) {
+          newRange.selectNodeContents(target);
+          newRange.collapse(false);
+        }
+      } else if (direction === 'forward') {
+        newRange.selectNodeContents(target);
+        newRange.collapse(true);
+      } else {
+        newRange.selectNodeContents(target);
+        newRange.collapse(false);
+      }
+      sel.removeAllRanges();
+      sel.addRange(newRange);
+      return true;
+    };
+
+    // Snap a collapsed caret out of the clipped indent gutter (`[0, minColumn)`)
+    // when the user clicks there. The arrow-key handler already prevents
+    // landing inside the gutter via keyboard navigation; this covers
+    // pointer-driven clicks. Range selections are left alone — clamping the
+    // anchor of a drag would feel surprising mid-gesture.
+    const snapCaretOutOfGutter = () => {
+      const { minColumn } = boundsRef.current;
+      if (minColumn === undefined || minColumn <= 0) {
+        return;
+      }
+      const sel = element.ownerDocument.defaultView?.getSelection();
+      if (!sel || sel.rangeCount === 0 || !sel.isCollapsed) {
+        return;
+      }
+      const range = sel.getRangeAt(0);
+      if (!element.contains(range.startContainer)) {
+        return;
+      }
+      const position = getPosition(element);
+      if (position.content.length >= minColumn) {
+        return;
+      }
+      // Only snap when the gutter is actually whitespace — otherwise the
+      // line is shorter than `minColumn` and there's nowhere to snap to.
+      // `getLineInfo` walks just enough text nodes to read the current
+      // line; avoids materializing the full document text on every click.
+      const lineText = getLineInfo(element, position.line).currentLine;
+      if (lineText.length < minColumn || !/^\s*$/.test(lineText.slice(0, minColumn))) {
+        return;
+      }
+      edit.move({ row: position.line, column: minColumn });
+    };
+
+    const onKeyDown = (event: HTMLElementEventMap['keydown']) => {
+      if (event.defaultPrevented || event.target !== element) {
+        return;
+      }
+      if (state.disconnected) {
+        // React Quirk: between flushChanges() (which calls disconnect() and
+        // rewinds the DOM back to the pre-edit content) and React's commit
+        // (which re-observes via useLayoutEffect and restores state.position),
+        // an event can fire that we'd otherwise mishandle.
+        //
+        // For NAVIGATION keys (arrows) the DOM revert is irrelevant — the
+        // browser only needs a valid caret position to compute the next
+        // selection — so resync inline (restore caret + re-observe) and let
+        // the event proceed. Otherwise the keystroke would be eaten and the
+        // user would lose, for example, an ArrowUp step after Enter inside
+        // a focus frame. We deliberately do NOT include Home/End/PageUp/
+        // PageDown here: they would also need to compensate for the pending
+        // rerender (matching the arrow-key skip-next-restore handling) and
+        // currently lack that coverage, so keep them on the safe path.
+        //
+        // For EDITING keys (printable text, Enter, Tab, Backspace, Delete,
+        // …) we must NOT fall through: the live DOM is the reverted
+        // pre-edit snapshot, so applying a second edit on top would target
+        // the wrong text and corrupt content. Keep the original block-and-
+        // unblock behavior for those keys — React will commit the queued
+        // onChange momentarily and the user can re-issue the keystroke.
+        const isArrowKey =
+          event.key === 'ArrowLeft' ||
+          event.key === 'ArrowRight' ||
+          event.key === 'ArrowUp' ||
+          event.key === 'ArrowDown';
+        if (!isArrowKey) {
+          event.preventDefault();
+          unblock([]);
+          return;
+        }
+        if (state.position && state.repeatFlushId === null) {
+          const { position, extent } = state.position;
+          const cursorRange = makeRange(element, position, position + extent);
+          adjustCursorAtNewlineBoundary(cursorRange);
+          setCurrentRange(cursorRange);
+        }
+        observerRef.current?.observe(element, observerSettings);
+        state.disconnected = false;
+        // The `unblock([])` below schedules a React rerender. If that
+        // rerender's restore effect runs before the native arrow movement
+        // has updated `state.position` (which happens asynchronously via
+        // `selectionchange`), the restore would snap the caret back to the
+        // stale pre-arrow position. In practice `selectionchange` usually
+        // fires first so the restore is a no-op, but arming the skip flag
+        // makes the fast path race-free regardless of scheduling. The
+        // boundary-movement branches arm the same flag for the same reason.
+        state.skipNextRestore = true;
+        unblock([]);
+        // Fall through and let this arrow event be handled normally
+        // with the restored caret position.
+      }
+
+      if (isUndoRedoKey(event)) {
+        event.preventDefault();
+
+        let history: History;
+        if (!event.shiftKey) {
+          state.historyAt -= 1;
+          const at = state.historyAt;
+          history = state.history[at];
+          if (!history) {
+            state.historyAt = 0;
+          }
+        } else {
+          state.historyAt += 1;
+          const at = state.historyAt;
+          history = state.history[at];
+          if (!history) {
+            state.historyAt = state.history.length - 1;
+          }
+        }
+
+        if (history) {
+          disconnect();
+          state.position = history[0];
+          state.onChange(history[1], history[0]);
+        }
+        return;
+      }
+
+      // Only capture the pre-edit snapshot when no edit is currently pending
+      // (i.e. the previous keystroke has already been flushed on keyup).
+      // Overwriting pendingContent on a rapid second keydown — whether the
+      // same key repeating OR a different key pressed before the first
+      // keyup — would lose the baseline that repairUnexpectedLineMerge
+      // needs to detect Firefox's line-merge quirk. The DOM may already
+      // contain a merged state when the second keydown fires; treating that
+      // as "previous" content makes the line-loss invisible.
+      if (state.pendingContent === null) {
+        state.pendingContent = trackState() ?? toString(element);
+      }
+
+      if (event.key === 'Enter') {
+        event.preventDefault();
+        // Firefox Quirk: Since plaintext-only is unsupported we must
+        // ensure that only newline characters are inserted
+        const position = getPosition(element);
+        // We also get the current line and preserve indentation for the next
+        // line that's created
+        const match = /\S/g.exec(position.content);
+        const index = match ? match.index : position.content.length;
+        const text = `\n${position.content.slice(0, index)}`;
+        edit.insert(text);
+      } else if (!hasPlaintextSupport && !event.isComposing && isPlaintextInputKey(event)) {
+        // Firefox Quirk: native typing in contentEditable="true" can insert
+        // directly into the frame wrapper before the current line span.
+        // Route plain text input through the controlled insert path instead.
+        event.preventDefault();
+        edit.insert(event.key);
+      } else if ((!hasPlaintextSupport || config.indentation) && event.key === 'Backspace') {
+        // Firefox Quirk: Since plaintext-only is unsupported we must
+        // ensure that only a single character is deleted
+        event.preventDefault();
+        const range = getCurrentRange();
+        if (!range.collapsed) {
+          edit.insert('', 0);
+        } else {
+          const position = getPosition(element);
+          const { minColumn } = boundsRef.current;
+          // When the caret sits at `minColumn` on a blank (whitespace-only)
+          // line inside a clipped indent gutter, a normal Backspace would
+          // step into `[0, minColumn)` — visually invisible to the user
+          // since that range is hidden by the host. The user has nothing
+          // useful to delete on this line, so collapse the entire blank
+          // line and land the caret at the end of the previous line. This
+          // matches the mental model: "Backspace from an empty indented
+          // line removes the line."
+          //
+          // Walk only enough text nodes to read the current line — we
+          // don't need the rest of the document on every Backspace.
+          const couldCollapse =
+            minColumn !== undefined &&
+            minColumn > 0 &&
+            position.line > 0 &&
+            position.content.length === minColumn &&
+            /^\s*$/.test(position.content);
+          if (couldCollapse && minColumn !== undefined) {
+            // The redundant `minColumn !== undefined` check pins TS's
+            // narrowing across the boundary so we can use `minColumn`
+            // as a number directly without an assertion.
+            const fullLine = getLineInfo(element, position.line).currentLine;
+            if (fullLine.length === minColumn && /^\s*$/.test(fullLine)) {
+              edit.insert('', -(minColumn + 1));
+              return;
+            }
+          }
+          const match = blanklineRe.exec(position.content);
+          edit.insert('', match ? -match[1].length : -1);
+        }
+      } else if (config.indentation && event.key === 'Tab') {
+        event.preventDefault();
+        const position = getPosition(element);
+        const start = position.position - position.content.length;
+        const content = toString(element);
+        const newContent = event.shiftKey
+          ? content.slice(0, start) +
+            position.content.replace(indentRe, '') +
+            content.slice(start + position.content.length)
+          : content.slice(0, start) +
+            (config.indentation ? ' '.repeat(config.indentation) : '\t') +
+            content.slice(start);
+        edit.update(newContent);
+      } else if (
+        (boundsRef.current.minColumn !== undefined ||
+          boundsRef.current.minRow !== undefined ||
+          boundsRef.current.maxRow !== undefined ||
+          boundsRef.current.caretSelector !== undefined) &&
+        !event.shiftKey &&
+        !event.metaKey &&
+        !event.ctrlKey &&
+        !event.altKey &&
+        (event.key === 'ArrowLeft' ||
+          event.key === 'ArrowRight' ||
+          event.key === 'ArrowUp' ||
+          event.key === 'ArrowDown')
+      ) {
+        // Arrow-key navigation that respects the visible region:
+        // - `minColumn`: skip over hidden/clipped leading indent so the
+        //   caret never lands before `minColumn` via horizontal navigation.
+        // - `minRow`/`maxRow`: block navigation past the visible row range
+        //   and invoke `onBoundary` so the host can react (e.g. expand).
+        // - `caretSelector`: when set, the editable contains non-selectable
+        //   gap text nodes between lines; handle horizontal line-wrap
+        //   ourselves so `ArrowLeft` at column 0 lands at the end of the
+        //   previous line synchronously (without flashing through the gap).
+        // Only acts on a collapsed selection — let the browser handle range
+        // expansion when a modifier is held or text is already selected.
+        const range = getCurrentRange();
+        if (range.collapsed) {
+          const { minColumn, minRow, maxRow, onBoundary, caretSelector } = boundsRef.current;
+          const position = getPosition(element);
+          const column = position.content.length;
+          // Walk just enough of the document to gather the current line
+          // and its immediate neighbors instead of allocating the entire
+          // document string and a full per-line array on every keypress.
+          const {
+            currentLine: lineText,
+            prevLine,
+            nextLine,
+            hasNextLine,
+          } = getLineInfo(element, position.line);
+          const lineIsIndented =
+            minColumn !== undefined &&
+            lineText.length >= minColumn &&
+            /^\s*$/.test(lineText.slice(0, minColumn));
+          const atVisibleStart = minRow !== undefined && position.line === minRow;
+          const atVisibleEnd = maxRow !== undefined && position.line === maxRow;
+          const atLineStart =
+            column === 0 || (lineIsIndented && minColumn !== undefined && column === minColumn);
+          const atLineEnd = column === lineText.length;
+
+          // For caretSelector wrap, also confirm the caret is currently
+          // *inside* an element matching the selector. This keeps the wrap
+          // scoped to render paths that actually have inter-line gap nodes
+          // (e.g. highlighted `.line` spans) and leaves plain-text editables
+          // — where the browser handles arrows fine — untouched.
+          const caretInLine =
+            caretSelector !== undefined &&
+            (() => {
+              const startContainer = range.startContainer;
+              const startElement = asElement(startContainer) ?? startContainer.parentElement;
+              return !!startElement?.closest(caretSelector);
+            })();
+
+          // Helper: place the caret on a target line, clamping the column
+          // to the line's length and respecting `minColumn` indent. Used
+          // when we need to move synchronously across the inter-line gap
+          // text nodes that `caretSelector`-rendered content places between
+          // `.line` spans (a native arrow press would otherwise drop the
+          // caret *in* the gap). The caller passes the target line's text
+          // (already in hand from `getLineInfo`) so we don't re-walk the
+          // document.
+          const moveToLine = (targetRow: number, targetLine: string, desiredColumn: number) => {
+            let targetColumn = Math.min(desiredColumn, targetLine.length);
+            if (
+              minColumn !== undefined &&
+              targetLine.length >= minColumn &&
+              /^\s*$/.test(targetLine.slice(0, minColumn)) &&
+              targetColumn < minColumn
+            ) {
+              targetColumn = minColumn;
+            }
+            edit.move({ row: targetRow, column: targetColumn });
+          };
+
+          if (event.key === 'ArrowUp') {
+            if (atVisibleStart) {
+              if (caretInLine && position.line > 0) {
+                // Synchronously move the caret onto the previous `.line`
+                // before notifying the host. Without this, native ArrowUp
+                // can drop the caret into the inter-line gap text node
+                // (e.g. the literal `\n` between `.line` spans), trapping
+                // it in the "between lines" area after the host expands.
+                event.preventDefault();
+                moveToLine(position.line - 1, prevLine, column);
+                if (onBoundary) {
+                  state.skipNextRestore = true;
+                  onBoundary();
+                }
+              } else if (onBoundary) {
+                // Allow native caret movement so the host can scroll the
+                // newly-revealed content into view alongside the caret.
+                state.skipNextRestore = true;
+                onBoundary();
+              } else {
+                event.preventDefault();
+              }
+            }
+          } else if (event.key === 'ArrowDown') {
+            if (atVisibleEnd) {
+              if (caretInLine && hasNextLine) {
+                event.preventDefault();
+                moveToLine(position.line + 1, nextLine, column);
+                if (onBoundary) {
+                  state.skipNextRestore = true;
+                  onBoundary();
+                }
+              } else if (onBoundary) {
+                state.skipNextRestore = true;
+                onBoundary();
+              } else {
+                event.preventDefault();
+              }
+            }
+          } else if (event.key === 'ArrowLeft') {
+            if (atVisibleStart && atLineStart) {
+              if (caretInLine && position.line > 0) {
+                event.preventDefault();
+                edit.move({ row: position.line - 1, column: prevLine.length });
+                if (onBoundary) {
+                  state.skipNextRestore = true;
+                  onBoundary();
+                }
+              } else if (onBoundary) {
+                state.skipNextRestore = true;
+                onBoundary();
+              } else {
+                event.preventDefault();
+              }
+            } else if (
+              lineIsIndented &&
+              minColumn !== undefined &&
+              column === minColumn &&
+              position.line > 0
+            ) {
+              event.preventDefault();
+              edit.move({ row: position.line - 1, column: prevLine.length });
+            } else if (caretInLine && column === 0 && position.line > 0) {
+              // With non-selectable gaps between lines the browser would
+              // place the caret *in* the gap text node — making ArrowLeft
+              // a no-op. Jump synchronously to the end of the previous
+              // line instead.
+              event.preventDefault();
+              edit.move({ row: position.line - 1, column: prevLine.length });
+            }
+          } else if (event.key === 'ArrowRight') {
+            if (atVisibleEnd && atLineEnd) {
+              if (caretInLine && hasNextLine) {
+                event.preventDefault();
+                moveToLine(position.line + 1, nextLine, 0);
+                if (onBoundary) {
+                  state.skipNextRestore = true;
+                  onBoundary();
+                }
+              } else if (onBoundary) {
+                state.skipNextRestore = true;
+                onBoundary();
+              } else {
+                event.preventDefault();
+              }
+            } else if (minColumn !== undefined && column === lineText.length && hasNextLine) {
+              const nextIsIndented =
+                nextLine.length >= minColumn && /^\s*$/.test(nextLine.slice(0, minColumn));
+              if (nextIsIndented) {
+                event.preventDefault();
+                edit.move({ row: position.line + 1, column: minColumn });
+              } else if (caretInLine) {
+                // Same gap-flash avoidance as ArrowLeft: jump to start of
+                // next line synchronously.
+                event.preventDefault();
+                edit.move({ row: position.line + 1, column: 0 });
+              }
+            } else if (caretInLine && atLineEnd && hasNextLine) {
+              event.preventDefault();
+              edit.move({ row: position.line + 1, column: 0 });
+            }
+          }
+        }
+
+        // Schedule a post-arrow snap when `caretSelector` is set: the
+        // browser's native arrow handling can drop the caret into the
+        // non-selectable gap text nodes (e.g. the literal `\n` between
+        // `.line` spans, especially after pressing Down on the last line
+        // or Up on the first line). After the default action runs, if the
+        // caret is no longer inside a matching element, jump it to the
+        // nearest `.line` in the direction of travel so the caret never
+        // gets stuck "between lines".
+        const { caretSelector } = boundsRef.current;
+        if (caretSelector !== undefined && !event.defaultPrevented) {
+          const direction =
+            event.key === 'ArrowDown' || event.key === 'ArrowRight' ? 'forward' : 'backward';
+          // For vertical arrows, capture the column the user is leaving
+          // *before* the browser moves the caret, so we can land on the
+          // same column of the target line if a snap is needed. Horizontal
+          // arrows always snap to start/end of the adjacent line.
+          const isVertical = event.key === 'ArrowUp' || event.key === 'ArrowDown';
+          let preferredColumn = 0;
+          if (isVertical) {
+            const preSel = element.ownerDocument.defaultView?.getSelection();
+            if (preSel && preSel.rangeCount > 0 && preSel.isCollapsed) {
+              const preRange = preSel.getRangeAt(0);
+              if (element.contains(preRange.startContainer)) {
+                preferredColumn = getPosition(element).content.length;
+              }
+            }
+          }
+          // requestAnimationFrame fires after the browser has applied the
+          // native caret movement but before paint, so the snap is invisible.
+          window.requestAnimationFrame(() => {
+            snapCaretOutOfGapNode(direction, isVertical, preferredColumn);
+          });
+        }
+      }
+
+      // After a controlled edit in plaintext-only contentEditable, the DOM is
+      // in a known-good post-edit state. Refresh pendingContent to that state
+      // so any subsequent native input within the same key burst — e.g.
+      // holding Enter then pressing x in plaintext-only contentEditable, where
+      // `x` falls through to native browser handling and may merge frame
+      // boundary lines — is measured against the correct baseline. Without
+      // this, repairUnexpectedLineMerge sees Enter add a line and the native
+      // merge remove a line for a net zero delta and short-circuits, leaving
+      // the merge unrepaired.
+      //
+      // We gate on `hasPlaintextSupport` because in the Firefox fallback
+      // (contenteditable=true) `edit.insert` itself can trigger the line-merge
+      // quirk, so toString() after it would already be buggy and we must keep
+      // the pre-edit baseline.
+      if (event.defaultPrevented && hasPlaintextSupport) {
+        state.pendingContent = toString(element);
+      }
+
+      // Flush changes as a key is held so the app can catch up.
+      // Debounce: reset the timer on each repeat keydown so the expensive
+      // onChange (syntax re-highlight) only fires once the user pauses typing.
+      // edit.insert() already updated the DOM so the cursor and text are live.
+      if (event.repeat) {
+        if (state.repeatFlushId !== null) {
+          clearTimeout(state.repeatFlushId);
+        }
+        state.repeatFlushId = setTimeout(() => {
+          state.repeatFlushId = null;
+          flushChanges();
+        }, 100);
+      }
+    };
+
+    const onKeyUp = (event: HTMLElementEventMap['keyup']) => {
+      if (event.defaultPrevented || event.isComposing) {
+        return;
+      }
+      // Cancel any pending debounced flush so keyup always flushes immediately
+      if (state.repeatFlushId !== null) {
+        clearTimeout(state.repeatFlushId);
+        state.repeatFlushId = null;
+      }
+      // Structural edits (Enter) must always create their own undo checkpoint.
+      // Regular character typing uses the 500ms dedup so you undo a word at a
+      // time, but each Enter should be individually undoable. flushChanges
+      // records the (repaired) post-edit content into history before firing
+      // onChange, so we don't poison the undo stack with intermediate
+      // browser-merged DOM states. Enter also forces a synchronous React
+      // state sync (bypassing `preParse`) so newlines render immediately.
+      if (!isUndoRedoKey(event)) {
+        flushChanges(event.key === 'Enter', event.key === 'Enter');
+      } else {
+        flushChanges();
+      }
+      // Chrome Quirk: The contenteditable may lose focus after the first edit or so
+      element.focus();
+    };
+
+    const onSelect = (event: Event) => {
+      // Chrome Quirk: The contenteditable may lose its selection immediately on first focus
+      const hasRange = (window.getSelection()?.rangeCount ?? 0) > 0;
+      state.position = hasRange && event.target === element ? getPosition(element) : null;
+    };
+
+    const onPaste = (event: HTMLElementEventMap['paste']) => {
+      event.preventDefault();
+      const clipboard = event.clipboardData;
+      if (!clipboard) {
+        return;
+      }
+      state.pendingContent = trackState(true) ?? toString(element);
+      edit.insert(clipboard.getData('text/plain'));
+      // Paste replaces a chunk of source — flush synchronously so the
+      // pasted text highlights on the same commit instead of after a
+      // worker round-trip.
+      flushChanges(true, true);
+    };
+
+    // When the editable wraps lines in block-level elements (e.g. `.line`
+    // spans separated by literal `\n` gap text nodes), the browser's
+    // default HTML→text/plain serializer inserts an implicit newline
+    // between each block element on top of the explicit `\n` already
+    // present in the DOM, producing duplicated newlines in the
+    // clipboard. Override copy/cut to write `Range.toString()` for
+    // `text/plain` while still preserving the HTML payload (so pasting
+    // into rich-text targets keeps syntax highlighting).
+    const onCopyOrCut = (event: ClipboardEvent) => {
+      const selection = window.getSelection();
+      if (!selection || selection.rangeCount === 0 || !event.clipboardData) {
+        return;
+      }
+      const range = selection.getRangeAt(0);
+      if (range.collapsed || !element.contains(range.commonAncestorContainer)) {
+        return;
+      }
+      event.preventDefault();
+      const minColumn = boundsRef.current.minColumn;
+      // When the selection starts mid-gutter (e.g. minColumn=4 but the
+      // user dragged from column 2), only the gutter portion *inside*
+      // the selection should be stripped from the first line. Subsequent
+      // lines always start at column 0 of the document, so they get the
+      // full `minColumn` budget.
+      let firstLineStrip = 0;
+      const restStrip = minColumn ?? 0;
+      if (minColumn !== undefined && minColumn > 0) {
+        const beforeRange = element.ownerDocument.createRange();
+        beforeRange.setStart(element, 0);
+        beforeRange.setEnd(range.startContainer, range.startOffset);
+        const beforeText = beforeRange.toString();
+        const lastNewline = beforeText.lastIndexOf('\n');
+        const startColumn = beforeText.length - (lastNewline + 1);
+        firstLineStrip = Math.max(0, minColumn - startColumn);
+      }
+
+      // The caret-navigation guard already treats `[0, minColumn)` as a
+      // clipped indent gutter. Strip up to that many leading whitespace
+      // characters per line from the clipboard so the pasted snippet
+      // matches what the user sees rather than including indent that
+      // is hidden in the editable.
+      const plainText =
+        restStrip > 0
+          ? stripLeadingPerLine(range.toString(), firstLineStrip, restStrip)
+          : range.toString();
+      event.clipboardData.setData('text/plain', plainText);
+
+      const container = cloneRangeWithInlineStyles(element, range, {
+        elementStyleProps: CLIPBOARD_ELEMENT_STYLE_PROPS,
+        rootStyleProps: CLIPBOARD_ROOT_STYLE_PROPS,
+        rootStaticStyles: CLIPBOARD_ROOT_STATIC_STYLES,
+      });
+      if (restStrip > 0) {
+        stripLeadingPerLineDom(container, firstLineStrip, restStrip);
+      }
+      event.clipboardData.setData('text/html', container.outerHTML);
+
+      if (event.type === 'cut') {
+        // Mirror the paste path: capture pre-edit state for history, then
+        // delete the selection. When `minColumn` clipped the leading
+        // gutter whitespace out of the clipboard, re-insert exactly
+        // those characters at the selection location so cut stays
+        // lossless — the document keeps the hidden indent that the user
+        // could not see and never copied.
+        state.pendingContent = trackState(true) ?? toString(element);
+        const replacement =
+          restStrip > 0 ? extractLeadingPerLine(range.toString(), firstLineStrip, restStrip) : '';
+        edit.insert(replacement);
+        // Cut also bypasses preParse so the resulting document re-renders
+        // synchronously alongside the clipboard write.
+        flushChanges(true, true);
+      }
+    };
+
+    const onMouseUp = () => {
+      // First lift the caret out of any inter-line gap node so the
+      // gutter check below can see a real line position.
+      snapCaretOutOfGapNode('forward', false, 0);
+      snapCaretOutOfGutter();
+    };
+
+    // Tabbing into the editor places the caret at column 0 of the first
+    // line, which lands inside the clipped indent gutter. Browsers set the
+    // initial selection asynchronously after `focus`, so defer the snap.
+    const onFocus = () => {
+      const view = element.ownerDocument.defaultView;
+      if (!view) {
+        return;
+      }
+      view.requestAnimationFrame(() => {
+        snapCaretOutOfGapNode('forward', false, 0);
+        snapCaretOutOfGutter();
+      });
+    };
+
+    document.addEventListener('selectstart', onSelect);
+    window.addEventListener('keydown', onKeyDown);
+    element.addEventListener('paste', onPaste);
+    element.addEventListener('copy', onCopyOrCut);
+    element.addEventListener('cut', onCopyOrCut);
+    element.addEventListener('keyup', onKeyUp);
+    element.addEventListener('mouseup', onMouseUp);
+    element.addEventListener('focus', onFocus);
+
+    return () => {
+      if (state.repeatFlushId !== null) {
+        clearTimeout(state.repeatFlushId);
+        state.repeatFlushId = null;
+      }
+      // Abort any in-flight preParse so its eventual `onChange` doesn't
+      // fire after the editable has been torn down or toggled disabled.
+      if (state.preParseAbort) {
+        state.preParseAbort.abort();
+        state.preParseAbort = null;
+      }
+      document.removeEventListener('selectstart', onSelect);
+      window.removeEventListener('keydown', onKeyDown);
+      element.removeEventListener('paste', onPaste);
+      element.removeEventListener('copy', onCopyOrCut);
+      element.removeEventListener('cut', onCopyOrCut);
+      element.removeEventListener('keyup', onKeyUp);
+      element.removeEventListener('mouseup', onMouseUp);
+      element.removeEventListener('focus', onFocus);
+      element.style.whiteSpace = prevWhiteSpace;
+      element.contentEditable = prevContentEditable;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [elementRef.current, opts?.disabled, opts?.indentation]);
+
+  return edit;
+};
diff --git a/packages/docs-infra/src/useCode/useEditableUtils.ts b/packages/docs-infra/src/useCode/useEditableUtils.ts
new file mode 100644
index 000000000..d29337019
--- /dev/null
+++ b/packages/docs-infra/src/useCode/useEditableUtils.ts
@@ -0,0 +1,430 @@
+/*
+ * Pure DOM/text helpers extracted from useEditable.ts. None of these
+ * touch React state or the hook's internal `state` object — they only
+ * read from / mutate the DOM and the browser Selection. Kept in a
+ * sibling file (per AGENTS.md docs-infra rule 2.3) so the main hook
+ * stays focused on lifecycle wiring and event handling.
+ */
+
+export interface Position {
+  position: number;
+  extent: number;
+  content: string;
+  line: number;
+}
+
+export const getCurrentRange = (): Range => {
+  const selection = window.getSelection();
+  if (!selection || selection.rangeCount === 0) {
+    // Internal helper — only called from event handlers and edit methods
+    // that have already verified there is an active selection. Throwing
+    // here surfaces contract violations early instead of letting them
+    // explode further down the call stack (matching the prior implicit
+    // `DOMException` from `getRangeAt(0)` on an empty selection).
+    throw new Error('useEditable: expected an active selection');
+  }
+  return selection.getRangeAt(0);
+};
+
+export const setCurrentRange = (range: Range) => {
+  const selection = window.getSelection();
+  if (!selection) {
+    return;
+  }
+  selection.empty();
+  selection.addRange(range);
+};
+
+/**
+ * Narrow a `Node | null` to `Element | null` using a runtime check so
+ * downstream code can reason about element-only APIs without a cast.
+ */
+export const asElement = (node: Node | null | undefined): Element | null =>
+  node instanceof Element ? node : null;
+
+/**
+ * Pull the next element out of a `SHOW_ELEMENT` `TreeWalker` with a
+ * runtime check rather than a type cast. Tree walkers configured for
+ * `SHOW_ELEMENT` only emit elements in practice, but the DOM type
+ * exposes `Node | null`.
+ */
+export const nextElement = (walker: TreeWalker): Element | null => asElement(walker.nextNode());
+
+export const isUndoRedoKey = (event: KeyboardEvent): boolean =>
+  (event.metaKey || event.ctrlKey) && !event.altKey && event.code === 'KeyZ';
+
+export const isPlaintextInputKey = (event: KeyboardEvent): boolean => {
+  const usesAltGraph =
+    typeof event.getModifierState === 'function' && event.getModifierState('AltGraph');
+
+  return (
+    event.key.length === 1 && !event.metaKey && !event.ctrlKey && (!event.altKey || usesAltGraph)
+  );
+};
+
+export const toString = (element: HTMLElement): string => {
+  const content = element.textContent || '';
+
+  // contenteditable Quirk: Without plaintext-only a pre/pre-wrap element must always
+  // end with at least one newline character
+  if (content[content.length - 1] !== '\n') {
+    return `${content}\n`;
+  }
+
+  return content;
+};
+
+export interface LineInfo {
+  /** Full text of the requested line. */
+  currentLine: string;
+  /** Full text of `lineIndex - 1`. Empty when `lineIndex <= 0`. */
+  prevLine: string;
+  /** Full text of `lineIndex + 1`. Empty when there is no next line. */
+  nextLine: string;
+  /**
+   * True when a real line follows `currentLine` — including a blank
+   * line. False when the document ends at `currentLine` (matching the
+   * old `toString(element).split('\n').slice(0, -1)` semantics where
+   * the phantom empty entry after the trailing `\n` does not count as
+   * a next line).
+   */
+  hasNextLine: boolean;
+}
+
+/**
+ * Walk text nodes to extract the requested line plus its immediate
+ * neighbors without materializing the full document text or splitting
+ * it into a per-line array. Used by per-keystroke handlers (arrow keys,
+ * Backspace, gutter snapping) so they stay O(chars-on-touched-lines)
+ * instead of O(document-length) on every event.
+ *
+ * Walks each text node in document order and slices contiguous segments
+ * directly into the relevant accumulator (`prevLine` / `currentLine` /
+ * `nextLine`). Skips chunks belonging to lines we don't care about and
+ * exits as soon as the trailing `\n` of `lineIndex + 1` is consumed.
+ *
+ * Mirrors `toString(element).split('\n').slice(0, -1)` semantics:
+ *
+ * - `hasNextLine` is `true` whenever a real line follows `currentLine`,
+ *   even if that line is blank — `"a\n\nb\n"` reports a next line for
+ *   row 0. The phantom empty entry that `split` produces after the
+ *   document's trailing `\n` is intentionally ignored.
+ * - The implicit trailing newline that `toString` appends when the DOM
+ *   doesn't end with one has no effect: we walk raw text content.
+ */
+export const getLineInfo = (element: HTMLElement, lineIndex: number): LineInfo => {
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+  let currentLine = '';
+  let prevLine = '';
+  let nextLine = '';
+  let hasNextLine = false;
+  let line = 0;
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const text = node.textContent ?? '';
+    let segStart = 0;
+    for (let i = 0; i < text.length; i += 1) {
+      if (text[i] !== '\n') {
+        continue;
+      }
+      // Flush the segment that lives on `line` before crossing the newline.
+      if (segStart < i) {
+        const segment = text.slice(segStart, i);
+        if (line === lineIndex - 1) {
+          prevLine += segment;
+        } else if (line === lineIndex) {
+          currentLine += segment;
+        } else if (line === lineIndex + 1) {
+          nextLine += segment;
+        }
+      }
+      // We're about to cross the `\n` that terminates `line`. If `line`
+      // is the next line, we've now fully read it and confirmed it
+      // exists (a terminator means there is at least one more position
+      // in the document past `currentLine`'s end).
+      if (line === lineIndex + 1) {
+        hasNextLine = true;
+        return { currentLine, prevLine, nextLine, hasNextLine };
+      }
+      line += 1;
+      segStart = i + 1;
+    }
+    // Tail segment of this text node belongs to `line` (no newline yet).
+    if (segStart < text.length) {
+      const segment = text.slice(segStart);
+      if (line === lineIndex - 1) {
+        prevLine += segment;
+      } else if (line === lineIndex) {
+        currentLine += segment;
+      } else if (line === lineIndex + 1) {
+        // An unterminated tail on `lineIndex + 1` is the document's
+        // last (real) line — it counts as a next line. The phantom
+        // empty entry produced by `toString`'s trailing `\n` has no
+        // tail, so it correctly leaves `hasNextLine` false.
+        nextLine += segment;
+        hasNextLine = true;
+      }
+    }
+  }
+  return { currentLine, prevLine, nextLine, hasNextLine };
+};
+
+/**
+ * Convert a `(row, column)` coordinate into an absolute character offset
+ * by counting newlines through the editable's text nodes, exiting the
+ * moment we land on the requested row. Avoids the
+ * `toString(element).split('\n').slice(0, row).join('\n').length`
+ * round-trip — that pattern allocates the full document string and a
+ * full per-line array on every `edit.move({row, column})` call.
+ *
+ * If the row is past the end of the document, returns the document
+ * length plus `column` so the eventual `makeRange` clamps gracefully.
+ */
+export const getOffsetAtLineColumn = (
+  element: HTMLElement,
+  row: number,
+  column: number,
+): number => {
+  if (row <= 0) {
+    return Math.max(0, column);
+  }
+  let offset = 0;
+  let line = 0;
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const text = node.textContent ?? '';
+    for (let i = 0; i < text.length; i += 1) {
+      offset += 1;
+      if (text[i] === '\n') {
+        line += 1;
+        if (line === row) {
+          return offset + column;
+        }
+      }
+    }
+  }
+  return offset + column;
+};
+
+export const repairUnexpectedLineMerge = (
+  newContent: string,
+  previousContent: string | null,
+  position: Position,
+): string => {
+  if (previousContent == null || position.extent !== 0) {
+    return newContent;
+  }
+
+  const previousLines = previousContent.split('\n');
+  const nextLines = newContent.split('\n');
+
+  if (nextLines.length >= previousLines.length) {
+    return newContent;
+  }
+
+  const cursorLine = position.line;
+
+  for (let i = 0; i < cursorLine && i < nextLines.length; i += 1) {
+    if (nextLines[i] !== previousLines[i]) {
+      return newContent;
+    }
+  }
+
+  const linesLost = previousLines.length - nextLines.length;
+  const mergedPreviousContent = previousLines
+    .slice(cursorLine + 1, cursorLine + 1 + linesLost)
+    .join('');
+
+  if (!nextLines[cursorLine]?.endsWith(mergedPreviousContent)) {
+    return newContent;
+  }
+
+  const editedCursorLine = nextLines[cursorLine].slice(
+    0,
+    nextLines[cursorLine].length - mergedPreviousContent.length,
+  );
+
+  if (editedCursorLine === previousLines[cursorLine]) {
+    return newContent;
+  }
+
+  return [
+    ...nextLines.slice(0, cursorLine),
+    editedCursorLine,
+    ...previousLines.slice(cursorLine + 1, cursorLine + 1 + linesLost),
+    ...nextLines.slice(cursorLine + 1),
+  ].join('\n');
+};
+
+const setStart = (range: Range, node: Node, offset: number) => {
+  const length = (node.textContent ?? '').length;
+  if (offset < length) {
+    range.setStart(node, offset);
+  } else {
+    range.setStartAfter(node);
+  }
+};
+
+const setEnd = (range: Range, node: Node, offset: number) => {
+  const length = (node.textContent ?? '').length;
+  if (offset < length) {
+    range.setEnd(node, offset);
+  } else {
+    range.setEndAfter(node);
+  }
+};
+
+export const getPosition = (element: HTMLElement): Position => {
+  const range = getCurrentRange();
+  const extent = !range.collapsed ? range.toString().length : 0;
+
+  // Fast path: cursor is in a text node (Chrome/Safari with plaintext-only, and
+  // Firefox after edit.insert repositions the cursor). Walk text nodes to count
+  // characters without allocating an O(cursor-position) string.
+  if (range.startContainer.nodeType === Node.TEXT_NODE) {
+    const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+    let position = 0;
+    let line = 0;
+    let lineContent = '';
+
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+      const text = node.textContent ?? '';
+      const isTarget = node === range.startContainer;
+      const upTo = isTarget ? range.startOffset : text.length;
+
+      let segStart = 0;
+      for (let i = 0; i < upTo; i += 1) {
+        if (text[i] === '\n') {
+          line += 1;
+          lineContent = '';
+          segStart = i + 1;
+        }
+      }
+      lineContent += text.slice(segStart, upTo);
+      position += upTo;
+
+      if (isTarget) {
+        break;
+      }
+    }
+
+    return { position, extent, content: lineContent, line };
+  }
+
+  // Firefox fallback: cursor may be at an element boundary (e.g. after a click
+  // before any edit). Use Range.toString() to extract the pre-cursor text.
+  // Firefox Quirk: Since plaintext-only is unsupported, the selection can land
+  // on element nodes rather than text nodes.
+  const untilRange = document.createRange();
+  untilRange.setStart(element, 0);
+  untilRange.setEnd(range.startContainer, range.startOffset);
+  let content = untilRange.toString();
+  const position = content.length;
+  const lines = content.split('\n');
+  const line = lines.length - 1;
+  content = lines[line];
+  return { position, extent, content, line };
+};
+
+export const makeRange = (element: HTMLElement, start: number, end?: number): Range => {
+  if (start <= 0) {
+    start = 0;
+  }
+  if (!end || end < 0) {
+    end = start;
+  }
+
+  const range = document.createRange();
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+  let current = 0;
+  let position = start;
+
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const length = (node.textContent ?? '').length;
+    if (current + length >= position) {
+      const offset = position - current;
+      if (position === start) {
+        setStart(range, node, offset);
+        if (end === start) {
+          break;
+        }
+        position = end;
+        if (current + length >= position) {
+          setEnd(range, node, position - current);
+          break;
+        }
+        // end is in a later node — fall through to advance current
+      } else {
+        setEnd(range, node, offset);
+        break;
+      }
+    }
+    current += length;
+  }
+
+  return range;
+};
+
+/** Walk to the next text node in document order without allocating a TreeWalker. */
+const nextTextNode = (node: Node): Node | null => {
+  let current: Node | null = node;
+  // Walk up and across siblings until we find a branch to descend into.
+  while (current) {
+    if (current.nextSibling) {
+      current = current.nextSibling;
+      // Descend to the first text node.
+      while (current.firstChild) {
+        current = current.firstChild;
+      }
+      if (current.nodeType === Node.TEXT_NODE) {
+        return current;
+      }
+      // Not a text leaf — continue walking siblings from here.
+      continue;
+    }
+    current = current.parentNode;
+  }
+  return null;
+};
+
+/**
+ * After makeRange positions a collapsed cursor at a newline boundary via
+ * setStartAfter(textNode), the cursor ends up inside the *previous* line span
+ * (after the '\n').  This adjusts the range forward to offset 0 of the
+ * next text node so the cursor renders on the correct visual line.
+ */
+export const adjustCursorAtNewlineBoundary = (range: Range): void => {
+  if (!range.collapsed) {
+    return;
+  }
+
+  const { startContainer, startOffset } = range;
+  const startText = startContainer.textContent ?? '';
+
+  // Case 1: cursor is in a text node at the very end and that text ends with '\n'
+  if (
+    startContainer.nodeType === Node.TEXT_NODE &&
+    startOffset === startText.length &&
+    startText.endsWith('\n')
+  ) {
+    const next = nextTextNode(startContainer);
+    if (next) {
+      range.setStart(next, 0);
+      range.collapse(true);
+    }
+    return;
+  }
+
+  // Case 2: cursor is at an element boundary where the previous child is a
+  // text node ending with '\n' (happens when setStartAfter places us here)
+  if (startContainer.nodeType === Node.ELEMENT_NODE && startOffset > 0) {
+    const prevChild = startContainer.childNodes[startOffset - 1];
+    const prevText = prevChild?.textContent ?? '';
+    if (prevChild?.nodeType === Node.TEXT_NODE && prevText.endsWith('\n')) {
+      const next = nextTextNode(prevChild);
+      if (next) {
+        range.setStart(next, 0);
+        range.collapse(true);
+      }
+    }
+  }
+};
diff --git a/packages/docs-infra/src/useCode/useFileNavigation.test.ts b/packages/docs-infra/src/useCode/useFileNavigation.test.ts
index ebe0fa0b7..15bc810e4 100644
--- a/packages/docs-infra/src/useCode/useFileNavigation.test.ts
+++ b/packages/docs-infra/src/useCode/useFileNavigation.test.ts
@@ -3571,7 +3571,7 @@ describe('useFileNavigation', () => {
       );
     });
 
-    it('should handle preClassName and preRef props with enhancers', async () => {
+    it('should handle preClassName and setSource props with enhancers', async () => {
       const hastSource = {
         type: 'root' as const,
         children: [{ type: 'text' as const, value: 'const x = 1;' }],
@@ -3584,7 +3584,7 @@ describe('useFileNavigation', () => {
 
       const mockEnhancer = vi.fn((root) => root);
       const enhancers = [mockEnhancer];
-      const mockRef = { current: null };
+      const mockSetSource = vi.fn();
 
       const { result } = renderHook(() =>
         useFileNavigation({
@@ -3595,7 +3595,7 @@ describe('useFileNavigation', () => {
           variantKeys: ['Default'],
           shouldHighlight: true,
           preClassName: 'custom-class',
-          preRef: mockRef,
+          setSource: mockSetSource,
           sourceEnhancers: enhancers,
         }),
       );
diff --git a/packages/docs-infra/src/useCode/useFileNavigation.tsx b/packages/docs-infra/src/useCode/useFileNavigation.tsx
index 585e8d7b3..7f3681ca1 100644
--- a/packages/docs-infra/src/useCode/useFileNavigation.tsx
+++ b/packages/docs-infra/src/useCode/useFileNavigation.tsx
@@ -12,6 +12,7 @@ import { useUrlHashState } from '../useUrlHashState';
 import { countLines } from '../pipeline/parseSource/addLineGutters';
 import { getLanguageFromExtension } from '../pipeline/loaderUtils/getLanguageFromExtension';
 import type { TransformedFiles } from './useCodeUtils';
+import type { SetSource } from './useSourceEditing';
 import { Pre } from './Pre';
 import { useSourceEnhancing } from './useSourceEnhancing';
 import { toKebabCase } from '../pipeline/loaderUtils/toKebabCase';
@@ -101,7 +102,7 @@ interface UseFileNavigationProps {
   variantKeys?: string[];
   shouldHighlight: boolean;
   preClassName?: string;
-  preRef?: React.Ref<HTMLPreElement>;
+  setSource?: SetSource;
   effectiveCode?: Code;
   selectVariant?: React.Dispatch<React.SetStateAction<string>>;
   fileHashMode?: 'remove-hash' | 'remove-filename';
@@ -113,6 +114,16 @@ interface UseFileNavigationProps {
    * Enhancers receive the HAST root, comments extracted from source, and filename.
    */
   sourceEnhancers?: SourceEnhancers;
+  /**
+   * Whether the surrounding code block is currently expanded. Forwarded to
+   * `<Pre>` so it can disable collapsed-state behaviors (e.g. `minColumn`).
+   */
+  expanded?: boolean;
+  /**
+   * Called when the user attempts to navigate the caret past the visible
+   * region of a collapsed code block. Forwarded to `<Pre>`.
+   */
+  expand?: () => void;
 }
 
 export interface UseFileNavigationResult {
@@ -137,7 +148,7 @@ export function useFileNavigation({
   variantKeys = [],
   shouldHighlight,
   preClassName,
-  preRef,
+  setSource,
   effectiveCode,
   selectVariant,
   fileHashMode = 'remove-hash',
@@ -145,6 +156,8 @@ export function useFileNavigation({
   saveVariantToLocalStorage,
   hashVariant,
   sourceEnhancers,
+  expanded,
+  expand,
 }: UseFileNavigationProps): UseFileNavigationResult {
   // Keep selectedFileName as untransformed filename for internal tracking
   const [selectedFileNameInternal, setSelectedFileNameInternal] = React.useState<
@@ -494,6 +507,7 @@ export function useFileNavigation({
       const language = isMainFile
         ? selectedVariant.language
         : getLanguageFromFileName(selectedFileNameInternal);
+      const fileName = selectedFileNameInternal || selectedVariant.fileName;
       const fileSlug = generateFileSlug(
         mainSlug,
         selectedFileNameInternal ?? selectedVariant.fileName ?? 'code',
@@ -508,9 +522,12 @@ export function useFileNavigation({
         <Pre
           key={getPreRenderKey(fileSlug, selectedTransform, enhancementPhase)}
           className={preClassName}
+          fileName={fileName}
           language={language}
-          ref={preRef}
+          setSource={setSource}
           shouldHighlight={shouldHighlight}
+          expanded={expanded}
+          expand={expand}
         >
           {sourceToRender}
         </Pre>
@@ -522,7 +539,7 @@ export function useFileNavigation({
     selectedVariant,
     shouldHighlight,
     preClassName,
-    preRef,
+    setSource,
     enhancedSource,
     isEnhancing,
     mainSlug,
@@ -531,6 +548,8 @@ export function useFileNavigation({
     selectedVariantKey,
     sourceEnhancers,
     selectedFileNameInternal,
+    expanded,
+    expand,
   ]);
 
   const selectedFileLines = React.useMemo(() => {
@@ -593,8 +612,11 @@ export function useFileNavigation({
               selectedTransform,
             )}
             className={preClassName}
-            ref={preRef}
+            fileName={f.originalName}
+            setSource={setSource}
             shouldHighlight={shouldHighlight}
+            expanded={expanded}
+            expand={expand}
           >
             {f.source}
           </Pre>
@@ -617,9 +639,12 @@ export function useFileNavigation({
               selectedTransform,
             )}
             className={preClassName}
+            fileName={selectedVariant.fileName}
             language={selectedVariant.language}
-            ref={preRef}
+            setSource={setSource}
             shouldHighlight={shouldHighlight}
+            expanded={expanded}
+            expand={expand}
           >
             {selectedVariant.source}
           </Pre>
@@ -655,9 +680,12 @@ export function useFileNavigation({
                 selectedTransform,
               )}
               className={preClassName}
+              fileName={fileName}
               language={language ?? getLanguageFromFileName(fileName)}
-              ref={preRef}
+              setSource={setSource}
               shouldHighlight={shouldHighlight}
+              expanded={expanded}
+              expand={expand}
             >
               {source}
             </Pre>
@@ -675,7 +703,9 @@ export function useFileNavigation({
     selectedVariantKey,
     shouldHighlight,
     preClassName,
-    preRef,
+    setSource,
+    expanded,
+    expand,
   ]);
 
   // Create a wrapper for selectFileName that handles transformed filenames and URL updates
diff --git a/packages/docs-infra/src/useCode/useSourceEditing.test.ts b/packages/docs-infra/src/useCode/useSourceEditing.test.ts
new file mode 100644
index 000000000..f8721a4cf
--- /dev/null
+++ b/packages/docs-infra/src/useCode/useSourceEditing.test.ts
@@ -0,0 +1,1094 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import type { Position } from 'use-editable';
+import { useSourceEditing } from './useSourceEditing';
+import type { Code, ControlledCode, VariantCode, SourceComments } from '../CodeHighlighter/types';
+import type { CodeHighlighterContextType } from '../CodeHighlighter/CodeHighlighterContext';
+
+function createContext(
+  overrides: Partial<CodeHighlighterContextType> = {},
+): CodeHighlighterContextType {
+  return {
+    code: {},
+    setCode: vi.fn(),
+    ...overrides,
+  };
+}
+
+function pos(line: number): Position {
+  return { position: 0, extent: 0, content: '', line };
+}
+
+function posWithExtent(line: number, extent: number): Position {
+  return { position: 0, extent, content: '', line };
+}
+
+/**
+ * Captures the ControlledCode produced by setSource by intercepting the
+ * setState updater function passed to context.setCode.
+ */
+function captureControlledCode(
+  context: CodeHighlighterContextType,
+  currentCode?: ControlledCode,
+): ControlledCode | undefined {
+  const setCode = context.setCode as ReturnType<typeof vi.fn>;
+  const updater = setCode.mock.lastCall?.[0];
+  if (typeof updater === 'function') {
+    return updater(currentCode);
+  }
+  return updater;
+}
+
+describe('useSourceEditing', () => {
+  describe('setSource availability', () => {
+    it('returns undefined when context has no setCode', () => {
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context: createContext({ setCode: undefined }),
+          selectedVariantKey: 'Default',
+          effectiveCode: {},
+          selectedVariant: { fileName: 'App.tsx', source: 'code' },
+        }),
+      );
+
+      expect(result.current.setSource).toBeUndefined();
+    });
+
+    it('returns undefined when disabled', () => {
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context: createContext(),
+          selectedVariantKey: 'Default',
+          effectiveCode: {},
+          selectedVariant: { fileName: 'App.tsx', source: 'code' },
+          disabled: true,
+        }),
+      );
+
+      expect(result.current.setSource).toBeUndefined();
+    });
+
+    it('returns undefined when selectedVariant is null (unloaded)', () => {
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context: createContext(),
+          selectedVariantKey: 'Default',
+          effectiveCode: { Default: 'https://example.com/demo' },
+          selectedVariant: null,
+        }),
+      );
+
+      expect(result.current.setSource).toBeUndefined();
+    });
+
+    it('returns setSource when context has setCode, variant is loaded, and not disabled', () => {
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context: createContext(),
+          selectedVariantKey: 'Default',
+          effectiveCode: {},
+          selectedVariant: { fileName: 'App.tsx', source: 'code' },
+        }),
+      );
+
+      expect(result.current.setSource).toBeTypeOf('function');
+    });
+  });
+
+  describe('editing main file', () => {
+    it('updates the main file source', () => {
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: 'original',
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      act(() => result.current.setSource!('edited'));
+
+      const controlled = captureControlledCode(context);
+      expect(controlled!.Default!.source).toBe('edited');
+    });
+
+    it('preserves extra files when editing main file', () => {
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: 'original',
+        extraFiles: {
+          'styles.css': 'body { color: red; }',
+          'helpers.ts': { source: 'export const h = 1;' },
+        },
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      act(() => result.current.setSource!('edited'));
+
+      const controlled = captureControlledCode(context);
+      const variant = controlled!.Default!;
+
+      expect(variant.source).toBe('edited');
+      expect(variant.extraFiles).toBeDefined();
+      // String entries normalized to { source } objects
+      expect(variant.extraFiles!['styles.css']).toEqual({
+        source: 'body { color: red; }',
+        totalLines: 1,
+      });
+      expect(variant.extraFiles!['helpers.ts']).toEqual({
+        source: 'export const h = 1;',
+        totalLines: 1,
+      });
+    });
+  });
+
+  describe('editing extra file', () => {
+    it('updates the specified extra file', () => {
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: 'main code',
+        extraFiles: {
+          'styles.css': 'old styles',
+        },
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      act(() => result.current.setSource!('new styles', 'styles.css'));
+
+      const controlled = captureControlledCode(context);
+      const variant = controlled!.Default!;
+
+      expect(variant.source).toBe('main code');
+      expect(variant.extraFiles!['styles.css']).toEqual({ source: 'new styles', totalLines: 1 });
+    });
+
+    it('preserves other extra files when editing one', () => {
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: 'main code',
+        extraFiles: {
+          'styles.css': 'css content',
+          'helpers.ts': { source: 'helper content' },
+        },
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      act(() => result.current.setSource!('new css', 'styles.css'));
+
+      const controlled = captureControlledCode(context);
+      const variant = controlled!.Default!;
+
+      expect(variant.extraFiles!['styles.css']).toEqual({ source: 'new css', totalLines: 1 });
+      expect(variant.extraFiles!['helpers.ts']).toEqual({
+        source: 'helper content',
+        totalLines: 1,
+      });
+    });
+  });
+
+  describe('HAST source normalization', () => {
+    it('converts HAST root sources to plain text on first edit', () => {
+      const hastRoot = {
+        type: 'root' as const,
+        children: [{ type: 'text' as const, value: 'highlighted code' }],
+      };
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: hastRoot,
+        extraFiles: {
+          'styles.css': { source: hastRoot },
+        },
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      act(() => result.current.setSource!('edited', 'styles.css'));
+
+      const controlled = captureControlledCode(context);
+      const variant = controlled!.Default!;
+
+      // Main source converted from HAST to string
+      expect(variant.source).toBe('highlighted code');
+      // Edited extra file has new value
+      expect(variant.extraFiles!['styles.css']).toEqual({ source: 'edited', totalLines: 1 });
+    });
+  });
+
+  describe('successive edits', () => {
+    it('preserves previous edits when editing again', () => {
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: 'original',
+        extraFiles: {
+          'styles.css': 'original css',
+        },
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // First edit: main file
+      act(() => result.current.setSource!('first edit'));
+      const afterFirst = captureControlledCode(context);
+
+      // Second edit: extra file, passing previous controlled state
+      act(() => result.current.setSource!('new css', 'styles.css'));
+      const afterSecond = captureControlledCode(context, afterFirst);
+
+      expect(afterSecond!.Default!.source).toBe('first edit');
+      expect(afterSecond!.Default!.extraFiles!['styles.css']).toEqual({
+        source: 'new css',
+        totalLines: 1,
+      });
+    });
+  });
+
+  describe('comment shifting', () => {
+    it('shifts comments down when lines are added, and reverses on undo', () => {
+      const comments: SourceComments = { 1: ['@highlight'], 4: ['@focus'] };
+      const originalSource = 'line0\nline1\nline2\nline3';
+      const editedSource = 'line0\nline1\n\nline2\nline3';
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: originalSource,
+        comments,
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // Add a line after line 1 (0-indexed). Cursor ends on the new empty line (0-indexed line 2).
+      act(() => result.current.setSource!(editedSource, undefined, pos(2)));
+
+      const controlled = captureControlledCode(context);
+      const variant = controlled!.Default!;
+
+      expect(variant.comments![1]).toEqual(['@highlight']);
+      expect(variant.comments![5]).toEqual(['@focus']);
+      expect(variant.comments![4]).toBeUndefined();
+
+      // Undo: remove the added line. Cursor at 0-indexed line 1, delta = -1.
+      act(() => result.current.setSource!(originalSource, undefined, pos(1)));
+      const undone = captureControlledCode(context, controlled);
+
+      expect(undone!.Default!.comments).toEqual(comments);
+    });
+
+    it('shifts comments up when lines are removed, and reverses on undo', () => {
+      const comments: SourceComments = { 1: ['@highlight'], 5: ['@focus'] };
+      const originalSource = 'line0\nline1\nline2\nline3\nline4';
+      const editedSource = 'line0\nline1line2\nline3\nline4';
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: originalSource,
+        comments,
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // Delete line2 (merge into line1). Cursor at 0-indexed line 1, delta = -1.
+      act(() => result.current.setSource!(editedSource, undefined, pos(1)));
+
+      const controlled = captureControlledCode(context);
+      const variant = controlled!.Default!;
+
+      expect(variant.comments![1]).toEqual(['@highlight']);
+      expect(variant.comments![4]).toEqual(['@focus']);
+      expect(variant.comments![5]).toBeUndefined();
+
+      // Undo: re-add the line. Cursor at 0-indexed line 2 (new line), delta = +1.
+      act(() => result.current.setSource!(originalSource, undefined, pos(2)));
+      const undone = captureControlledCode(context, controlled);
+
+      expect(undone!.Default!.comments).toEqual(comments);
+    });
+
+    it('collapses comments from deleted range and restores on undo', () => {
+      const comments: SourceComments = {
+        1: ['@keep-before'],
+        3: ['@deleted-1'],
+        4: ['@deleted-2'],
+        6: ['@keep-after'],
+      };
+      const originalSource = 'a\nb\nc\nd\ne\nf';
+      const editedSource = 'a\nb\ne\nf';
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: originalSource,
+        comments,
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // Delete lines c and d (0-indexed 2,3). Cursor at 0-indexed line 1, delta = -2.
+      act(() => result.current.setSource!(editedSource, undefined, pos(1)));
+
+      const controlled = captureControlledCode(context);
+      const variant = controlled!.Default!;
+
+      // Line 1 is before the edit — unchanged
+      expect(variant.comments![1]).toEqual(['@keep-before']);
+      // Lines 3 and 4 collapsed onto the edit line (line 2)
+      expect(variant.comments![2]).toEqual(['@deleted-1', '@deleted-2']);
+      // Line 6 shifted up by 2 to line 4
+      expect(variant.comments![4]).toEqual(['@keep-after']);
+      expect(variant.comments![6]).toBeUndefined();
+
+      // Undo: re-add the 2 deleted lines. Cursor at 0-indexed line 3, delta = +2.
+      act(() => result.current.setSource!(originalSource, undefined, pos(3)));
+      const undone = captureControlledCode(context, controlled);
+
+      // Comments fully restored to original positions
+      expect(undone!.Default!.comments).toEqual(comments);
+      // Collapse map cleared after full restore
+      expect(undone!.Default!.collapseMap).toBeUndefined();
+    });
+
+    it('keeps highlight in place when undoing a multi-line selection delete', () => {
+      // Simulates: user has highlight on lines 7-8, types text inside the
+      // highlighted region (adding 2 lines AFTER line 8), selects the typed
+      // text (extent > 0), backspaces to delete it, then presses Ctrl+Z.
+      //
+      // The undo replays the saved pre-deletion state, where `position`
+      // points to the SELECTION-START (not the post-edit cursor). Without
+      // accounting for `extent > 0`, shiftComments mistakenly thinks the
+      // edit happened earlier in the file and shifts the highlighted lines
+      // downward — so the user sees the highlight on the typed lines
+      // instead of on its original location.
+      const comments: SourceComments = {
+        7: ['@highlight-start'],
+        8: ['@highlight-end'],
+      };
+      const originalSource = 'L1\nL2\nL3\nL4\nL5\nL6\nL7\nL8\nL9\nL10\nL11';
+      // Typed text adds 2 lines after L8: 'test', '<div>test</div>', 'test'
+      // appended after L8's content.
+      const typedSource = 'L1\nL2\nL3\nL4\nL5\nL6\nL7\nL8test\n<div>test</div>\ntest\nL9\nL10\nL11';
+
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: originalSource,
+        comments,
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // Step 1: type the text (single setSource for simplicity).
+      // Cursor lands at end of last "test" → 0-indexed line 9.
+      act(() => result.current.setSource!(typedSource, undefined, pos(9)));
+      const afterType = captureControlledCode(context);
+      // Highlight stays on lines 7 (L7) and 8 (L8test).
+      expect(afterType!.Default!.comments).toEqual(comments);
+
+      // Step 2: select the typed text and Backspace.
+      // Cursor lands at start of selection (end of L8) → 0-indexed line 7.
+      act(() => result.current.setSource!(originalSource, undefined, pos(7)));
+      const afterDelete = captureControlledCode(context, afterType);
+      expect(afterDelete!.Default!.comments).toEqual(comments);
+
+      // Step 3: Ctrl+Z restores the pre-Backspace state. The saved position
+      // is the SELECTION-START in the typed text — line 7 (0-indexed) with
+      // extent = 25 (length of selected text).
+      act(() => result.current.setSource!(typedSource, undefined, posWithExtent(7, 25)));
+      const afterUndo = captureControlledCode(context, afterDelete);
+
+      // Highlight must remain on lines 7 (L7) and 8 (L8test) — the same
+      // logical lines as before the delete. Without the extent-aware fix,
+      // they would incorrectly shift to lines 9 and 10 (the typed content).
+      expect(afterUndo!.Default!.comments).toEqual(comments);
+    });
+
+    it('reduces (does not shift) the highlight when deleting an empty line at the start', () => {
+      // Highlighted region: lines 7-9 where L7 is an empty/whitespace-only line.
+      // User backspaces at the start of L7, merging it into L6.
+      //   Old: L6='    <div>', L7='      ' (@hl-start), L8='      <Checkbox/>',
+      //        L9='      <p/>' (@hl-end)
+      //   New: L6='    <div>      ', L7='      <Checkbox/>', L8='      <p/>' (@hl-end)
+      //
+      // Since the deleted L7 had no real content that shifted into L6, the
+      // user expects the highlight to "lose" that empty line and start on
+      // the next line (now L7 = <Checkbox/>) — NOT shift the start marker
+      // up onto the <div> line.
+      const comments: SourceComments = {
+        7: ['@highlight-start'],
+        9: ['@highlight-end'],
+      };
+      const originalSource =
+        "import * as React from 'react';\n\n\nfunction App() {\n  return (\n    <div>\n      \n      <Checkbox/>\n      <p/>\n    </div>\n  );\n}";
+      const editedSource =
+        "import * as React from 'react';\n\n\nfunction App() {\n  return (\n    <div>      \n      <Checkbox/>\n      <p/>\n    </div>\n  );\n}";
+
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: originalSource,
+        comments,
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // Cursor lands at end of merged line 6 (0-indexed line 5). lineDelta = -1.
+      act(() => result.current.setSource!(editedSource, undefined, pos(5)));
+
+      const variant = captureControlledCode(context)!.Default!;
+
+      // @highlight-start should NOT collapse onto L6 (the <div> line).
+      // Instead it should land on what is now L7 (the <Checkbox/> line),
+      // shrinking the highlighted range from 3 lines to 2.
+      expect(variant.comments![6]).toBeUndefined();
+      expect(variant.comments![7]).toEqual(['@highlight-start']);
+      // @highlight-end shifts from L9 to L8 (one line removed before it).
+      expect(variant.comments![8]).toEqual(['@highlight-end']);
+    });
+
+    it('places -end comments at editLine+1 instead of editLine when collapsing', () => {
+      // Simulates deleting whitespace before </div> in JSX, merging two lines.
+      // @highlight-end should stay at the line AFTER the merged content, not
+      // collapse onto editLine where it would shrink the highlighted range.
+      const comments: SourceComments = {
+        2: ['@highlight-start'],
+        4: ['@highlight-end'],
+      };
+      const originalSource = 'a\nb\nc\nd\ne';
+      // Delete line d (merge c+d into "cd"). delta = -1, cursor 0-indexed line 2.
+      const editedSource = 'a\nb\ncd\ne';
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: originalSource,
+        comments,
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      act(() => result.current.setSource!(editedSource, undefined, pos(2)));
+
+      const controlled = captureControlledCode(context);
+      const variant = controlled!.Default!;
+
+      // @highlight-start unchanged (before edit)
+      expect(variant.comments![2]).toEqual(['@highlight-start']);
+      // @highlight-end placed at editLine+1 (line 4), NOT editLine (line 3)
+      // This preserves the range [2, 3] instead of shrinking to [2, 2]
+      expect(variant.comments![4]).toEqual(['@highlight-end']);
+      expect(variant.comments![3]).toBeUndefined();
+      // Boundary comments are not tracked in collapseMap
+      expect(variant.collapseMap).toBeUndefined();
+
+      // Re-add a line: @highlight-end shifts normally from 4 to 5,
+      // expanding the range to include the new line.
+      act(() => result.current.setSource!(originalSource, undefined, pos(3)));
+      const expanded = captureControlledCode(context, controlled);
+
+      expect(expanded!.Default!.comments![2]).toEqual(['@highlight-start']);
+      expect(expanded!.Default!.comments![5]).toEqual(['@highlight-end']);
+    });
+
+    it('separates regular and -end comments in the same deleted range', () => {
+      const comments: SourceComments = {
+        2: ['@highlight-start'],
+        4: ['@regular'],
+        5: ['@highlight-end'],
+        6: ['@after'],
+      };
+      const originalSource = 'a\nb\nc\nd\ne\nf';
+      // Delete lines c, d, e. delta = -3, cursor 0-indexed line 1.
+      const editedSource = 'a\nb\nf';
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: originalSource,
+        comments,
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      act(() => result.current.setSource!(editedSource, undefined, pos(1)));
+
+      const controlled = captureControlledCode(context);
+      const variant = controlled!.Default!;
+
+      // @regular collapses onto editLine (2), next to @highlight-start
+      expect(variant.comments![2]).toEqual(['@highlight-start', '@regular']);
+      // @highlight-end at editLine+1 = 3, @after shifts from 6 to 3
+      expect(variant.comments![3]).toEqual(['@highlight-end', '@after']);
+      // Only @regular tracked in collapseMap, not @highlight-end
+      expect(variant.collapseMap![2]).toEqual([{ offset: 2, comments: ['@regular'] }]);
+
+      // Re-add 3 lines: @regular restores from collapseMap to line 4,
+      // but @highlight-end and @after shift normally from 3 to 6.
+      act(() => result.current.setSource!(originalSource, undefined, pos(4)));
+      const expanded = captureControlledCode(context, controlled);
+
+      expect(expanded!.Default!.comments![2]).toEqual(['@highlight-start']);
+      expect(expanded!.Default!.comments![4]).toEqual(['@regular']);
+      // @highlight-end and @after both shift to line 6
+      expect(expanded!.Default!.comments![6]).toEqual(['@highlight-end', '@after']);
+    });
+
+    it('does not shift comments when line count is unchanged', () => {
+      const comments: SourceComments = { 1: ['@highlight'], 3: ['@focus'] };
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: 'aaa\nbbb\nccc',
+        comments,
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // Edit text on line 1 without changing line count
+      act(() => result.current.setSource!('aaa\nBBB\nccc', undefined, pos(1)));
+
+      const controlled = captureControlledCode(context);
+
+      expect(controlled!.Default!.comments).toEqual(comments);
+
+      // Undo: revert to original text, still same line count
+      act(() => result.current.setSource!('aaa\nbbb\nccc', undefined, pos(1)));
+      const undone = captureControlledCode(context, controlled);
+
+      expect(undone!.Default!.comments).toEqual(comments);
+    });
+
+    it('shifts extra file comments when editing, and reverses on undo', () => {
+      const extraComments: SourceComments = { 2: ['@highlight'], 5: ['@focus'] };
+      const originalExtra = 'a\nb\nc\nd\ne';
+      const editedExtra = 'a\nNEW\nb\nc\nd\ne';
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: 'main',
+        comments: { 1: ['@main-highlight'] },
+        extraFiles: {
+          'styles.css': { source: originalExtra, comments: extraComments },
+        },
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // Add a line in the extra file after line 0-indexed 0. Cursor at new line 1.
+      act(() => result.current.setSource!(editedExtra, 'styles.css', pos(1)));
+
+      const controlled = captureControlledCode(context);
+      const variant = controlled!.Default!;
+
+      // Main file comments untouched
+      expect(variant.comments).toEqual({ 1: ['@main-highlight'] });
+      // Extra file comments shifted down by 1
+      const extraEntry = variant.extraFiles!['styles.css'];
+      expect(extraEntry.comments![3]).toEqual(['@highlight']);
+      expect(extraEntry.comments![6]).toEqual(['@focus']);
+      expect(extraEntry.comments![2]).toBeUndefined();
+      expect(extraEntry.comments![5]).toBeUndefined();
+
+      // Undo: remove the added line. Cursor at 0-indexed line 0, delta = -1.
+      act(() => result.current.setSource!(originalExtra, 'styles.css', pos(0)));
+      const undone = captureControlledCode(context, controlled);
+
+      expect(undone!.Default!.comments).toEqual({ 1: ['@main-highlight'] });
+      expect(undone!.Default!.extraFiles!['styles.css'].comments).toEqual(extraComments);
+    });
+
+    it('partially restores collapsed comments when fewer lines are re-added', () => {
+      const comments: SourceComments = {
+        3: ['@c'],
+        4: ['@d'],
+        5: ['@e'],
+      };
+      const originalSource = 'a\nb\nc\nd\ne\nf';
+      // Delete lines c, d, e → 3 lines removed
+      const editedSource = 'a\nb\nf';
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: originalSource,
+        comments,
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // Delete 3 lines (c, d, e). Cursor at 0-indexed line 1, delta = -3.
+      act(() => result.current.setSource!(editedSource, undefined, pos(1)));
+
+      const collapsed = captureControlledCode(context);
+      const v1 = collapsed!.Default!;
+
+      // All three collapsed onto edit line 2
+      expect(v1.comments![2]).toEqual(['@c', '@d', '@e']);
+      expect(v1.collapseMap).toBeDefined();
+
+      // Partial undo: add back 1 line (only @c at offset 1 restores)
+      const partialSource = 'a\nb\nNEW\nf';
+      act(() => result.current.setSource!(partialSource, undefined, pos(2)));
+      const partial = captureControlledCode(context, collapsed);
+      const v2 = partial!.Default!;
+
+      // @c restored to line 3 (editLine 2 + offset 1)
+      expect(v2.comments![3]).toEqual(['@c']);
+      // @d and @e remain collapsed on edit line 2
+      expect(v2.comments![2]).toEqual(['@d', '@e']);
+      // CollapseMap still has remaining entries
+      expect(v2.collapseMap![2]).toEqual([
+        { offset: 2, comments: ['@d'] },
+        { offset: 3, comments: ['@e'] },
+      ]);
+    });
+
+    it('correctly handles duplicate comment strings across collapsed entries', () => {
+      // Two different lines with the same comment string
+      const comments: SourceComments = {
+        3: ['@highlight'],
+        4: ['@highlight'],
+      };
+      const originalSource = 'a\nb\nc\nd';
+      const editedSource = 'a\nb';
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: originalSource,
+        comments,
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // Delete lines c and d. Cursor at 0-indexed line 1, delta = -2.
+      act(() => result.current.setSource!(editedSource, undefined, pos(1)));
+
+      const collapsed = captureControlledCode(context);
+      const v1 = collapsed!.Default!;
+
+      // Both @highlight collapsed onto edit line 2
+      expect(v1.comments![2]).toEqual(['@highlight', '@highlight']);
+
+      // Undo: add both lines back. Cursor at 0-indexed line 3, delta = +2.
+      act(() => result.current.setSource!(originalSource, undefined, pos(3)));
+      const undone = captureControlledCode(context, collapsed);
+      const v2 = undone!.Default!;
+
+      // Both @highlight restored to their original lines
+      expect(v2.comments).toEqual(comments);
+      // Edit line 2 should have no leftover comments
+      expect(v2.comments![2]).toBeUndefined();
+      expect(v2.collapseMap).toBeUndefined();
+    });
+
+    it('preserves pre-existing edit-line comments through collapse and restore', () => {
+      const comments: SourceComments = {
+        2: ['@existing'],
+        3: ['@collapsed-1'],
+        4: ['@collapsed-2'],
+      };
+      const originalSource = 'a\nb\nc\nd';
+      const editedSource = 'a\nb';
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: originalSource,
+        comments,
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // Delete lines c and d. Cursor at 0-indexed line 1, delta = -2.
+      act(() => result.current.setSource!(editedSource, undefined, pos(1)));
+
+      const collapsed = captureControlledCode(context);
+      const v1 = collapsed!.Default!;
+
+      // Edit line 2 keeps @existing and gains collapsed comments
+      expect(v1.comments![2]).toEqual(['@existing', '@collapsed-1', '@collapsed-2']);
+
+      // Undo: add both lines back. Cursor at 0-indexed line 3, delta = +2.
+      act(() => result.current.setSource!(originalSource, undefined, pos(3)));
+      const undone = captureControlledCode(context, collapsed);
+
+      // Fully restored: @existing stays on line 2, collapsed comments back to original lines
+      expect(undone!.Default!.comments).toEqual(comments);
+      expect(undone!.Default!.collapseMap).toBeUndefined();
+    });
+
+    it('restores original comments after multiple edits at different positions are undone', () => {
+      const comments: SourceComments = {
+        1: ['@a'],
+        3: ['@c'],
+        5: ['@e'],
+      };
+      const originalSource = 'a\nb\nc\nd\ne\nf';
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: originalSource,
+        comments,
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // Edit 1: delete line c. Source: a\nb\nd\ne\nf (5 lines). Cursor at 0-indexed line 1.
+      const afterDel1 = 'a\nb\nd\ne\nf';
+      act(() => result.current.setSource!(afterDel1, undefined, pos(1)));
+      const state1 = captureControlledCode(context);
+
+      expect(state1!.Default!.comments![1]).toEqual(['@a']);
+      expect(state1!.Default!.comments![2]).toEqual(['@c']); // collapsed onto editLine 2
+      expect(state1!.Default!.comments![4]).toEqual(['@e']); // shifted from 5 to 4
+
+      // Edit 2: delete line e (now at 0-indexed line 3). Source: a\nb\nd\nf (4 lines). Cursor at 0-indexed line 2.
+      const afterDel2 = 'a\nb\nd\nf';
+      act(() => result.current.setSource!(afterDel2, undefined, pos(2)));
+      const state2 = captureControlledCode(context, state1);
+
+      expect(state2!.Default!.comments![1]).toEqual(['@a']);
+      expect(state2!.Default!.comments![2]).toEqual(['@c']);
+      expect(state2!.Default!.comments![3]).toEqual(['@e']); // collapsed onto editLine 3
+
+      // Undo edit 2: add line e back. Source: a\nb\nd\ne\nf (5 lines). Cursor at 0-indexed line 3.
+      act(() => result.current.setSource!(afterDel1, undefined, pos(3)));
+      const state3 = captureControlledCode(context, state2);
+
+      expect(state3!.Default!.comments![1]).toEqual(['@a']);
+      expect(state3!.Default!.comments![2]).toEqual(['@c']);
+      expect(state3!.Default!.comments![4]).toEqual(['@e']); // restored to line 4
+
+      // Undo edit 1: add line c back. Source: original (6 lines). Cursor at 0-indexed line 2.
+      act(() => result.current.setSource!(originalSource, undefined, pos(2)));
+      const state4 = captureControlledCode(context, state3);
+
+      // Fully restored to original comments
+      expect(state4!.Default!.comments).toEqual(comments);
+      expect(state4!.Default!.collapseMap).toBeUndefined();
+    });
+
+    it('preserves comments through toControlledCode normalization', () => {
+      const comments: SourceComments = { 1: ['@highlight'], 3: ['@focus'] };
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: 'line1\nline2\nline3',
+        comments,
+        extraFiles: {
+          'helper.ts': { source: 'code', comments: { 2: ['@extra'] } },
+        },
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // First edit triggers toControlledCode normalization (no position = comments cleared)
+      act(() => result.current.setSource!('edited'));
+
+      const controlled = captureControlledCode(context);
+      const variant = controlled!.Default!;
+
+      // Main comments cleared (no position data, can't track shifts)
+      expect(variant.comments).toBeUndefined();
+      // Extra file comments preserved (not edited)
+      expect(variant.extraFiles!['helper.ts'].comments).toEqual({ 2: ['@extra'] });
+    });
+
+    it('clears comments when setSource is called without position', () => {
+      const comments: SourceComments = { 1: ['@highlight'], 3: ['@focus'] };
+      const selectedVariant: VariantCode = {
+        fileName: 'App.tsx',
+        source: 'line1\nline2\nline3',
+        comments,
+        extraFiles: {
+          'helper.ts': { source: 'code', comments: { 2: ['@extra'] } },
+        },
+      };
+      const effectiveCode: Code = { Default: selectedVariant };
+      const context = createContext();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode,
+          selectedVariant,
+        }),
+      );
+
+      // Edit main file without position
+      act(() => result.current.setSource!('new main'));
+
+      const controlled = captureControlledCode(context);
+      const variant = controlled!.Default!;
+
+      expect(variant.comments).toBeUndefined();
+      expect(variant.collapseMap).toBeUndefined();
+      // Extra file untouched
+      expect(variant.extraFiles!['helper.ts'].comments).toEqual({ 2: ['@extra'] });
+
+      // Edit extra file without position
+      act(() => result.current.setSource!('new helper', 'helper.ts'));
+      const afterExtra = captureControlledCode(context, controlled);
+
+      expect(afterExtra!.Default!.extraFiles!['helper.ts'].comments).toBeUndefined();
+    });
+  });
+
+  describe('preParsed cache write', () => {
+    function makeHast() {
+      return {
+        type: 'root' as const,
+        children: [{ type: 'text' as const, value: 'parsed' }],
+      };
+    }
+
+    it('writes preParsed HAST into context.preParsedCache keyed by the resolved file name', () => {
+      const preParsedCache = new Map<string, { source: string; hast: any }>();
+      const context = createContext({ preParsedCache });
+      const hast = makeHast();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode: { Default: { fileName: 'App.tsx', source: 'old' } },
+          selectedVariant: { fileName: 'App.tsx', source: 'old' },
+        }),
+      );
+
+      act(() => result.current.setSource!('new source', undefined, pos(0), hast));
+
+      expect(preParsedCache.get('App.tsx')).toEqual({ source: 'new source', hast });
+    });
+
+    it('uses the explicit fileName argument when provided', () => {
+      const preParsedCache = new Map<string, { source: string; hast: any }>();
+      const context = createContext({ preParsedCache });
+      const hast = makeHast();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode: {
+            Default: {
+              fileName: 'App.tsx',
+              source: 'main',
+              extraFiles: { 'helper.ts': { source: 'h' } },
+            },
+          },
+          selectedVariant: {
+            fileName: 'App.tsx',
+            source: 'main',
+            extraFiles: { 'helper.ts': { source: 'h' } },
+          },
+        }),
+      );
+
+      act(() => result.current.setSource!('new helper', 'helper.ts', pos(0), hast));
+
+      expect(preParsedCache.get('helper.ts')).toEqual({ source: 'new helper', hast });
+      expect(preParsedCache.has('App.tsx')).toBe(false);
+    });
+
+    it('does not write when preParsed is omitted', () => {
+      const preParsedCache = new Map<string, { source: string; hast: any }>();
+      const context = createContext({ preParsedCache });
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode: { Default: { fileName: 'App.tsx', source: 'old' } },
+          selectedVariant: { fileName: 'App.tsx', source: 'old' },
+        }),
+      );
+
+      act(() => result.current.setSource!('new source', undefined, pos(0)));
+
+      expect(preParsedCache.size).toBe(0);
+    });
+
+    it('does nothing when context has no preParsedCache', () => {
+      const context = createContext();
+      const hast = makeHast();
+
+      const { result } = renderHook(() =>
+        useSourceEditing({
+          context,
+          selectedVariantKey: 'Default',
+          effectiveCode: { Default: { fileName: 'App.tsx', source: 'old' } },
+          selectedVariant: { fileName: 'App.tsx', source: 'old' },
+        }),
+      );
+
+      // Should not throw.
+      expect(() =>
+        act(() => result.current.setSource!('new', undefined, pos(0), hast)),
+      ).not.toThrow();
+    });
+  });
+});
diff --git a/packages/docs-infra/src/useCode/useSourceEditing.ts b/packages/docs-infra/src/useCode/useSourceEditing.ts
index 9908e8761..ad029768a 100644
--- a/packages/docs-infra/src/useCode/useSourceEditing.ts
+++ b/packages/docs-infra/src/useCode/useSourceEditing.ts
@@ -1,56 +1,413 @@
 import * as React from 'react';
-import type { Code, ControlledCode, VariantCode } from '../CodeHighlighter/types';
+import type { Root as HastRoot } from 'hast';
+import type { Position } from './useEditable';
+import type {
+  Code,
+  CollapseMap,
+  ControlledCode,
+  ControlledVariantExtraFiles,
+  SourceComments,
+  VariantCode,
+} from '../CodeHighlighter/types';
 import type { CodeHighlighterContextType } from '../CodeHighlighter/CodeHighlighterContext';
+import { stringOrHastToString } from '../pipeline/hastUtils';
+
+export type { Position };
+
+/**
+ * Internal `setSource` shape used by the editing pipeline. The 3rd and 4th
+ * arguments (caret position, pre-parsed HAST) are wired between sibling
+ * hooks (`useEditable` → `Pre` → `useSourceEditing`) and are NOT part of
+ * the public `useCode` contract — host code should treat `setSource` as
+ * `(source, fileName?) => void`.
+ */
+export type SetSource = (
+  source: string,
+  fileName?: string,
+  position?: Position,
+  preParsed?: HastRoot,
+) => void;
 
 interface UseSourceEditingProps {
   context?: CodeHighlighterContextType;
   selectedVariantKey: string;
   effectiveCode: Code;
   selectedVariant: VariantCode | null;
+  disabled?: boolean;
 }
 
 export interface UseSourceEditingResult {
-  setSource?: (source: string) => void;
+  setSource?: SetSource;
+}
+
+interface ShiftResult {
+  comments: SourceComments | undefined;
+  collapseMap: CollapseMap | undefined;
+}
+
+/**
+ * Counts the number of lines in a string and records which 1-indexed lines are
+ * empty/whitespace-only, in a single pass, without allocating a line array.
+ * `emptyLines` is omitted when no blank lines were found to keep the common
+ * case allocation-free.
+ */
+function analyzeSource(source: string): { totalLines: number; emptyLines?: number[] } {
+  let totalLines = 1;
+  let emptyLines: number[] | undefined;
+  let lineStart = 0;
+  const len = source.length;
+  for (let i = 0; i <= len; i += 1) {
+    if (i === len || source.charCodeAt(i) === 0x0a /* \n */) {
+      let isEmpty = true;
+      for (let j = lineStart; j < i; j += 1) {
+        const ch = source.charCodeAt(j);
+        // 0x20=space, 0x09=tab, 0x0D=CR, 0x0B=VT, 0x0C=FF
+        if (ch !== 0x20 && ch !== 0x09 && ch !== 0x0d && ch !== 0x0b && ch !== 0x0c) {
+          isEmpty = false;
+          break;
+        }
+      }
+      if (isEmpty) {
+        if (!emptyLines) {
+          emptyLines = [];
+        }
+        emptyLines.push(totalLines);
+      }
+      if (i < len) {
+        totalLines += 1;
+        lineStart = i + 1;
+      }
+    }
+  }
+  return emptyLines ? { totalLines, emptyLines } : { totalLines };
 }
 
 /**
- * Hook for managing source code editing functionality
+ * Shifts 1-indexed comment line numbers after a source edit.
+ * Accepts a precomputed `lineDelta` (positive = lines added, negative = lines deleted)
+ * and the cursor `position` (0-indexed in the new text) to determine which
+ * comments move and by how much.
+ *
+ * When lines are deleted, comments from the deleted range are collapsed
+ * onto the edit line and recorded in a collapseMap so they can be restored
+ * if the deletion is undone (lines re-added at the same position).
+ *
+ * Empty/whitespace-only deleted lines are special: since they had no real
+ * content that "shifted upward" into editLine, their comments are pushed
+ * to editLine + 1 (like `-end` boundary markers) so the highlighted region
+ * shrinks instead of shifting onto the previous line.
+ */
+function shiftComments(
+  comments: SourceComments | undefined,
+  lineDelta: number,
+  position: Position,
+  existingCollapseMap: CollapseMap | undefined,
+  oldEmptyLines?: number[],
+): ShiftResult {
+  if (!comments || Object.keys(comments).length === 0) {
+    return { comments, collapseMap: existingCollapseMap };
+  }
+
+  if (lineDelta === 0) {
+    return { comments, collapseMap: existingCollapseMap };
+  }
+
+  // position.line is 0-indexed in the new text.
+  // lineDelta is positive for insertions and negative for deletions.
+  // Convert to the 1-indexed line in old text that the cursor was on:
+  // For additions (lineDelta > 0):
+  //   - Forward typing: position is the POST-edit cursor (extent === 0).
+  //     Cursor moved down by lineDelta, so old line = position.line - lineDelta.
+  //   - Undo of a multi-line delete: the saved position has extent > 0 and
+  //     points to the SELECTION-START in the redone text — i.e. where the
+  //     re-inserted lines begin. The "edit line" is that line itself; the
+  //     new lines come AFTER it.
+  // For deletions (lineDelta < 0): cursor stayed where it was, old line = position.line.
+  const isUndoOfMultiLineDelete = lineDelta > 0 && position.extent > 0;
+  const editLine = isUndoOfMultiLineDelete
+    ? position.line + 1
+    : position.line - Math.max(0, lineDelta) + 1; // 1-indexed
+
+  const shifted: SourceComments = {};
+  let collapseMap: CollapseMap = existingCollapseMap ? { ...existingCollapseMap } : {};
+  const newCollapsed: Array<{ offset: number; comments: string[] }> = [];
+
+  // Build a list of comment strings to exclude from the edit line after restore.
+  // Uses an array (not Set) to correctly handle duplicate comment strings
+  // across separate collapsed entries.
+  let restoredComments: string[] | undefined;
+
+  // On expansion, check if we can restore previously collapsed comments
+  if (lineDelta > 0 && collapseMap[editLine]) {
+    const entries = collapseMap[editLine];
+    const restored: Array<{ offset: number; comments: string[] }> = [];
+    const remaining: Array<{ offset: number; comments: string[] }> = [];
+
+    for (const entry of entries) {
+      if (entry.offset <= lineDelta) {
+        restored.push(entry);
+      } else {
+        remaining.push(entry);
+      }
+    }
+
+    // Place restored comments at their original offsets from the edit line
+    restoredComments = [];
+    for (const entry of restored) {
+      const restoredLine = editLine + entry.offset;
+      shifted[restoredLine] = [...(shifted[restoredLine] ?? []), ...entry.comments];
+      restoredComments.push(...entry.comments);
+    }
+
+    if (remaining.length > 0) {
+      collapseMap[editLine] = remaining;
+    } else {
+      delete collapseMap[editLine];
+    }
+  }
+
+  // O(1) lookup against the precomputed empty-line set from the old source.
+  const oldEmptyLineSet =
+    oldEmptyLines && oldEmptyLines.length > 0 ? new Set(oldEmptyLines) : undefined;
+
+  for (const [lineStr, commentArr] of Object.entries(comments)) {
+    const line = Number(lineStr);
+    if (line <= editLine) {
+      // Before or at the edit line — unchanged.
+      // If this is the edit line and we restored comments from it, filter them out.
+      let arr = commentArr;
+      if (line === editLine && restoredComments) {
+        const remaining = [...commentArr];
+        for (const c of restoredComments) {
+          const idx = remaining.indexOf(c);
+          if (idx !== -1) {
+            remaining.splice(idx, 1);
+          }
+        }
+        arr = remaining;
+      }
+      if (arr.length > 0) {
+        shifted[line] = [...(shifted[line] ?? []), ...arr];
+      }
+    } else if (lineDelta < 0 && line <= editLine - lineDelta) {
+      // Within the deleted range — collapse comments onto the edit line.
+      // Boundary comments (ending with '-end') go to editLine + 1 instead,
+      // so range-end markers stay at the first line after the highlighted range.
+      // Boundary comments are NOT tracked in collapseMap — they shift normally
+      // on subsequent edits so the range naturally expands/contracts.
+      //
+      // Empty/whitespace-only deleted lines also push their regular comments
+      // to editLine + 1: nothing actually shifted upward into editLine, so the
+      // highlighted region should shrink rather than expand onto the line above.
+      const wasEmptyLine = oldEmptyLineSet?.has(line) ?? false;
+      const regular = commentArr.filter((c) => !c.endsWith('-end'));
+      const boundary = commentArr.filter((c) => c.endsWith('-end'));
+
+      if (regular.length > 0) {
+        if (wasEmptyLine) {
+          const target = editLine + 1;
+          shifted[target] = [...(shifted[target] ?? []), ...regular];
+        } else {
+          shifted[editLine] = [...(shifted[editLine] ?? []), ...regular];
+          newCollapsed.push({ offset: line - editLine, comments: regular });
+        }
+      }
+      if (boundary.length > 0) {
+        const boundaryTarget = editLine + 1;
+        shifted[boundaryTarget] = [...(shifted[boundaryTarget] ?? []), ...boundary];
+      }
+    } else {
+      // After the edit — shift
+      const newLine = line + lineDelta;
+      shifted[newLine] = [...(shifted[newLine] ?? []), ...commentArr];
+    }
+  }
+
+  // Also shift existing collapse map entries that are after the edit line
+  const shiftedCollapseMap: CollapseMap = {};
+  for (const [lineStr, entries] of Object.entries(collapseMap)) {
+    const line = Number(lineStr);
+    if (line <= editLine) {
+      shiftedCollapseMap[line] = entries;
+    } else {
+      shiftedCollapseMap[line + lineDelta] = entries;
+    }
+  }
+  collapseMap = shiftedCollapseMap;
+
+  if (newCollapsed.length > 0) {
+    collapseMap[editLine] = [...(collapseMap[editLine] ?? []), ...newCollapsed];
+  }
+
+  const finalCollapseMap = Object.keys(collapseMap).length > 0 ? collapseMap : undefined;
+
+  return { comments: shifted, collapseMap: finalCollapseMap };
+}
+
+/**
+ * Converts Code to ControlledCode, normalizing sources and extraFiles entries.
+ * VariantSource can be HAST nodes; ControlledCode requires plain strings.
+ * VariantExtraFiles allows plain string entries; ControlledVariantExtraFiles
+ * requires `{ source }` objects. Without this normalization, parseControlledCode
+ * reads `.source` on a string and gets `undefined`, dropping file content.
+ */
+function toControlledCode(code: Code): ControlledCode {
+  const result: ControlledCode = {};
+  for (const [key, variant] of Object.entries(code)) {
+    if (!variant || typeof variant === 'string') {
+      continue;
+    }
+    const source = variant.source != null ? stringOrHastToString(variant.source) : variant.source;
+
+    let extraFiles: ControlledVariantExtraFiles | undefined;
+    if (variant.extraFiles) {
+      extraFiles = {};
+      for (const [fileName, entry] of Object.entries(variant.extraFiles)) {
+        if (typeof entry === 'string') {
+          extraFiles[fileName] = { source: entry, ...analyzeSource(entry) };
+        } else {
+          const extraSource = entry.source != null ? stringOrHastToString(entry.source) : null;
+          extraFiles[fileName] = {
+            source: extraSource,
+            ...(entry.comments ? { comments: entry.comments } : {}),
+            ...(extraSource != null ? analyzeSource(extraSource) : {}),
+          };
+        }
+      }
+    }
+
+    result[key] = {
+      ...variant,
+      source,
+      ...(source != null ? analyzeSource(source) : {}),
+      ...(extraFiles ? { extraFiles } : {}),
+    } as ControlledCode[string];
+  }
+  return result;
+}
+
+/**
+ * Hook for managing source code editing functionality.
+ *
+ * Returns a `setSource(source, fileName?)` callback that updates the correct file
+ * (main or extra) within the controlled code for the current variant.
+ * If `fileName` is omitted, the currently selected file is assumed.
  */
 export function useSourceEditing({
   context,
   selectedVariantKey,
   effectiveCode,
   selectedVariant,
+  disabled,
 }: UseSourceEditingProps): UseSourceEditingResult {
   const contextSetCode = context?.setCode;
 
-  const setSource = React.useCallback(
-    (source: string) => {
-      if (contextSetCode) {
-        contextSetCode((currentCode: ControlledCode | undefined) => {
-          let newCode: ControlledCode = {};
-          if (!currentCode) {
-            newCode = { ...effectiveCode } as ControlledCode; // TODO: ensure all source are strings
-          }
-
-          newCode[selectedVariantKey] = {
-            ...(newCode[selectedVariantKey] || selectedVariant),
-            source,
-            extraFiles: {},
-          } as ControlledCode[string];
-
-          return newCode;
-        });
-      } else {
+  const setSource = React.useCallback<SetSource>(
+    (source, fileName, position, preParsed) => {
+      if (!contextSetCode) {
         console.warn(
           'setCode is not available in the current context. Ensure you are using CodeControllerContext.',
         );
+        return;
+      }
+
+      // Stash any pre-computed parse result against the resolved file name
+      // BEFORE the controlled-code update commits, so that the synchronous
+      // `parseControlledCode` pass triggered by the resulting React render
+      // can reuse the cached HAST instead of re-parsing the new source.
+      // The cache is owned by `CodeHighlighterClient` (per-highlighter
+      // state) and exposed on the context for both the writer (here) and
+      // reader (`parseControlledCode`).
+      const resolvedFileName = fileName ?? selectedVariant?.fileName;
+      const preParsedCache = context?.preParsedCache;
+      if (preParsed !== undefined && preParsedCache && resolvedFileName) {
+        preParsedCache.set(resolvedFileName, {
+          source,
+          hast: preParsed,
+        });
       }
+
+      contextSetCode((currentCode: ControlledCode | undefined) => {
+        const newCode: ControlledCode = currentCode
+          ? { ...currentCode }
+          : toControlledCode(effectiveCode);
+
+        const variant = newCode[selectedVariantKey];
+        if (!variant) {
+          return newCode;
+        }
+
+        const effectiveFileName = fileName ?? selectedVariant?.fileName;
+        const isMainFile = effectiveFileName === selectedVariant?.fileName;
+
+        if (isMainFile) {
+          if (source === variant.source) {
+            return currentCode ?? newCode;
+          }
+          const { totalLines: newLineCount, emptyLines: newEmptyLines } = analyzeSource(source);
+          const oldLineCount =
+            variant.totalLines ??
+            (variant.source != null ? analyzeSource(variant.source).totalLines : 0);
+          const { comments: shiftedComments, collapseMap: newCollapseMap } = position
+            ? shiftComments(
+                variant.comments,
+                newLineCount - oldLineCount,
+                position,
+                variant.collapseMap,
+                variant.emptyLines,
+              )
+            : { comments: undefined, collapseMap: undefined };
+          newCode[selectedVariantKey] = {
+            ...variant,
+            source,
+            totalLines: newLineCount,
+            emptyLines: newEmptyLines,
+            comments: shiftedComments,
+            collapseMap: newCollapseMap,
+          };
+        } else if (effectiveFileName) {
+          const extraEntry = variant.extraFiles?.[effectiveFileName];
+          if (source === extraEntry?.source) {
+            return currentCode ?? newCode;
+          }
+          const { totalLines: newLineCount, emptyLines: newEmptyLines } = analyzeSource(source);
+          const oldLineCount =
+            extraEntry?.totalLines ??
+            (extraEntry?.source != null ? analyzeSource(extraEntry.source).totalLines : 0);
+          const { comments: shiftedComments, collapseMap: newCollapseMap } = position
+            ? shiftComments(
+                extraEntry?.comments,
+                newLineCount - oldLineCount,
+                position,
+                extraEntry?.collapseMap,
+                extraEntry?.emptyLines,
+              )
+            : { comments: undefined, collapseMap: undefined };
+          newCode[selectedVariantKey] = {
+            ...variant,
+            extraFiles: {
+              ...variant.extraFiles,
+              [effectiveFileName]: {
+                ...extraEntry,
+                source,
+                totalLines: newLineCount,
+                emptyLines: newEmptyLines,
+                comments: shiftedComments,
+                collapseMap: newCollapseMap,
+              },
+            },
+          };
+        }
+
+        return newCode;
+      });
     },
-    [contextSetCode, selectedVariantKey, effectiveCode, selectedVariant],
+    [contextSetCode, selectedVariantKey, effectiveCode, selectedVariant, context?.preParsedCache],
   );
 
+  const isEditable = !disabled && Boolean(contextSetCode) && Boolean(selectedVariant);
+
   return {
-    setSource: contextSetCode ? setSource : undefined,
+    setSource: isEditable ? setSource : undefined,
   };
 }
diff --git a/packages/docs-infra/src/useCode/useSourceEnhancing.test.ts b/packages/docs-infra/src/useCode/useSourceEnhancing.test.ts
new file mode 100644
index 000000000..37293798e
--- /dev/null
+++ b/packages/docs-infra/src/useCode/useSourceEnhancing.test.ts
@@ -0,0 +1,567 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import type { Root as HastRoot } from 'hast';
+import type { SourceEnhancer, SourceComments } from '../CodeHighlighter/types';
+import { useSourceEnhancing } from './useSourceEnhancing';
+
+function makeHast(value: string): HastRoot {
+  return {
+    type: 'root',
+    children: [{ type: 'text', value }],
+  };
+}
+
+function textOf(source: unknown): string | undefined {
+  if (
+    source &&
+    typeof source === 'object' &&
+    'children' in source &&
+    Array.isArray((source as HastRoot).children)
+  ) {
+    const first = (source as HastRoot).children[0];
+    if (first && first.type === 'text') {
+      return first.value;
+    }
+  }
+  return undefined;
+}
+
+describe('useSourceEnhancing', () => {
+  describe('no enhancers', () => {
+    it('should return the source unchanged when no enhancers are provided', () => {
+      const source = makeHast('original');
+
+      const { result } = renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: undefined,
+        }),
+      );
+
+      expect(result.current.enhancedSource).toBe(source);
+      expect(result.current.isEnhancing).toBe(false);
+    });
+
+    it('should return the source unchanged when enhancers array is empty', () => {
+      const source = makeHast('original');
+
+      const { result } = renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: [],
+        }),
+      );
+
+      expect(result.current.enhancedSource).toBe(source);
+      expect(result.current.isEnhancing).toBe(false);
+    });
+
+    it('should return null when source is null', () => {
+      const { result } = renderHook(() =>
+        useSourceEnhancing({
+          source: null,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: [() => makeHast('should not run')],
+        }),
+      );
+
+      expect(result.current.enhancedSource).toBeNull();
+      expect(result.current.isEnhancing).toBe(false);
+    });
+
+    it('should return null when source is undefined', () => {
+      const { result } = renderHook(() =>
+        useSourceEnhancing({
+          source: undefined,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: [() => makeHast('should not run')],
+        }),
+      );
+
+      expect(result.current.enhancedSource).toBeNull();
+      expect(result.current.isEnhancing).toBe(false);
+    });
+  });
+
+  describe('string sources', () => {
+    it('should return string sources unchanged since they cannot be enhanced', () => {
+      const source = 'const x = 1;';
+
+      const enhancer = vi.fn(() => makeHast('enhanced'));
+
+      const { result } = renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: [enhancer],
+        }),
+      );
+
+      expect(result.current.enhancedSource).toBe(source);
+      expect(result.current.isEnhancing).toBe(false);
+      expect(enhancer).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('sync enhancers', () => {
+    it('should apply a single sync enhancer immediately', () => {
+      const source = makeHast('original');
+      const enhanced = makeHast('enhanced');
+      const enhancer = vi.fn(() => enhanced);
+
+      const { result } = renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: [enhancer],
+        }),
+      );
+
+      expect(textOf(result.current.enhancedSource)).toBe('enhanced');
+      expect(result.current.isEnhancing).toBe(false);
+      expect(enhancer).toHaveBeenCalledExactlyOnceWith(source, undefined, 'test.tsx');
+    });
+
+    it('should chain multiple sync enhancers in order', () => {
+      const source = makeHast('original');
+      const callOrder: string[] = [];
+
+      const first: SourceEnhancer = (root) => {
+        callOrder.push('first');
+        expect(textOf(root)).toBe('original');
+        return makeHast('first');
+      };
+      const second: SourceEnhancer = (root) => {
+        callOrder.push('second');
+        expect(textOf(root)).toBe('first');
+        return makeHast('second');
+      };
+      const third: SourceEnhancer = (root) => {
+        callOrder.push('third');
+        expect(textOf(root)).toBe('second');
+        return makeHast('third');
+      };
+
+      const { result } = renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: [first, second, third],
+        }),
+      );
+
+      expect(textOf(result.current.enhancedSource)).toBe('third');
+      expect(result.current.isEnhancing).toBe(false);
+      expect(callOrder).toEqual(['first', 'second', 'third']);
+    });
+
+    it('should pass comments and fileName to enhancers', () => {
+      const source = makeHast('original');
+      const comments: SourceComments = { 1: ['@highlight'] };
+      const enhancer = vi.fn((root: HastRoot) => root);
+
+      renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: 'MyComponent.tsx',
+          comments,
+          sourceEnhancers: [enhancer],
+        }),
+      );
+
+      expect(enhancer).toHaveBeenCalledWith(source, comments, 'MyComponent.tsx');
+    });
+
+    it('should use "unknown" as fileName when fileName is undefined', () => {
+      const source = makeHast('original');
+      const enhancer = vi.fn((root: HastRoot) => root);
+
+      renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: undefined,
+          comments: undefined,
+          sourceEnhancers: [enhancer],
+        }),
+      );
+
+      expect(enhancer).toHaveBeenCalledWith(source, undefined, 'unknown');
+    });
+
+    it('should re-run sync enhancers when source changes', () => {
+      const sourceA = makeHast('A');
+      const sourceB = makeHast('B');
+      const enhancer = vi.fn((root: HastRoot) => makeHast(`enhanced-${textOf(root)}`));
+      const enhancers: SourceEnhancer[] = [enhancer];
+
+      const { result, rerender } = renderHook(
+        ({ source }) =>
+          useSourceEnhancing({
+            source,
+            fileName: 'test.tsx',
+            comments: undefined,
+            sourceEnhancers: enhancers,
+          }),
+        { initialProps: { source: sourceA as typeof sourceA | typeof sourceB } },
+      );
+
+      expect(textOf(result.current.enhancedSource)).toBe('enhanced-A');
+      expect(enhancer).toHaveBeenCalledTimes(1);
+
+      rerender({ source: sourceB });
+
+      expect(textOf(result.current.enhancedSource)).toBe('enhanced-B');
+      expect(enhancer).toHaveBeenCalledTimes(2);
+      expect(result.current.isEnhancing).toBe(false);
+    });
+
+    it('should re-run sync enhancers when comments change', () => {
+      const source = makeHast('original');
+      const commentsA: SourceComments = { 1: ['@highlight'] };
+      const commentsB: SourceComments = { 2: ['@highlight'] };
+      const enhancer = vi.fn((root: HastRoot) => root);
+      const enhancers: SourceEnhancer[] = [enhancer];
+
+      const { rerender } = renderHook(
+        ({ comments }) =>
+          useSourceEnhancing({
+            source,
+            fileName: 'test.tsx',
+            comments,
+            sourceEnhancers: enhancers,
+          }),
+        { initialProps: { comments: commentsA as SourceComments } },
+      );
+
+      expect(enhancer).toHaveBeenCalledTimes(1);
+      expect(enhancer).toHaveBeenCalledWith(source, commentsA, 'test.tsx');
+
+      rerender({ comments: commentsB });
+
+      expect(enhancer).toHaveBeenCalledTimes(2);
+      expect(enhancer).toHaveBeenLastCalledWith(source, commentsB, 'test.tsx');
+    });
+
+    it('should re-run sync enhancers when fileName changes', () => {
+      const source = makeHast('original');
+      const enhancer = vi.fn((root: HastRoot) => root);
+      const enhancers: SourceEnhancer[] = [enhancer];
+
+      const { rerender } = renderHook(
+        ({ name }) =>
+          useSourceEnhancing({
+            source,
+            fileName: name,
+            comments: undefined,
+            sourceEnhancers: enhancers,
+          }),
+        { initialProps: { name: 'file-a.tsx' } },
+      );
+
+      expect(enhancer).toHaveBeenCalledTimes(1);
+      expect(enhancer).toHaveBeenCalledWith(source, undefined, 'file-a.tsx');
+
+      rerender({ name: 'file-b.tsx' });
+
+      expect(enhancer).toHaveBeenCalledTimes(2);
+      expect(enhancer).toHaveBeenLastCalledWith(source, undefined, 'file-b.tsx');
+    });
+
+    it('should not re-run enhancers when inputs are unchanged', () => {
+      const source = makeHast('original');
+      const enhancers: SourceEnhancer[] = [vi.fn((root: HastRoot) => root)];
+
+      const { rerender } = renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: enhancers,
+        }),
+      );
+
+      rerender();
+      rerender();
+
+      expect(enhancers[0]).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('async enhancers', () => {
+    it('should show original source immediately and resolve async enhancer', async () => {
+      const source = makeHast('original');
+      const enhanced = makeHast('enhanced-async');
+
+      const asyncEnhancer: SourceEnhancer = async () => {
+        await new Promise((resolve) => {
+          setTimeout(resolve, 10);
+        });
+        return enhanced;
+      };
+      const enhancers: SourceEnhancer[] = [asyncEnhancer];
+
+      const { result } = renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: enhancers,
+        }),
+      );
+
+      // Before async resolves, shows the original (no sync enhancers ran before it)
+      expect(textOf(result.current.enhancedSource)).toBe('original');
+      expect(result.current.isEnhancing).toBe(true);
+
+      await vi.waitFor(() => {
+        expect(textOf(result.current.enhancedSource)).toBe('enhanced-async');
+      });
+      expect(result.current.isEnhancing).toBe(false);
+    });
+
+    it('should apply sync enhancers immediately and continue with async ones', async () => {
+      const source = makeHast('original');
+
+      const syncEnhancer: SourceEnhancer = () => makeHast('sync-done');
+
+      const asyncEnhancer: SourceEnhancer = async (root) => {
+        await new Promise((resolve) => {
+          setTimeout(resolve, 10);
+        });
+        return makeHast(`async-after-${textOf(root)}`);
+      };
+      const enhancers: SourceEnhancer[] = [syncEnhancer, asyncEnhancer];
+
+      const { result } = renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: enhancers,
+        }),
+      );
+
+      // Immediately shows sync-enhanced result
+      expect(textOf(result.current.enhancedSource)).toBe('sync-done');
+      expect(result.current.isEnhancing).toBe(true);
+
+      // Eventually resolves with async result
+      await vi.waitFor(() => {
+        expect(textOf(result.current.enhancedSource)).toBe('async-after-sync-done');
+      });
+      expect(result.current.isEnhancing).toBe(false);
+    });
+
+    it('should run sync enhancers after async ones without re-running the sync ones', async () => {
+      const source = makeHast('original');
+      const syncBefore = vi.fn<SourceEnhancer>(() => makeHast('sync-before'));
+      const syncAfter = vi.fn<SourceEnhancer>((root) => makeHast(`sync-after-${textOf(root)}`));
+
+      const asyncEnhancer: SourceEnhancer = async (root) => {
+        await new Promise((resolve) => {
+          setTimeout(resolve, 10);
+        });
+        return makeHast(`async-${textOf(root)}`);
+      };
+
+      const enhancers: SourceEnhancer[] = [syncBefore, asyncEnhancer, syncAfter];
+
+      const { result } = renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: enhancers,
+        }),
+      );
+
+      // syncBefore runs during render, asyncEnhancer is pending
+      expect(textOf(result.current.enhancedSource)).toBe('sync-before');
+      expect(syncBefore).toHaveBeenCalledTimes(1);
+      // syncAfter hasn't run yet — it's after the async one
+      expect(syncAfter).not.toHaveBeenCalled();
+
+      await vi.waitFor(() => {
+        expect(textOf(result.current.enhancedSource)).toBe('sync-after-async-sync-before');
+      });
+
+      // syncBefore was NOT re-run for the async path
+      expect(syncBefore).toHaveBeenCalledTimes(1);
+      // syncAfter ran once in the async continuation
+      expect(syncAfter).toHaveBeenCalledTimes(1);
+    });
+
+    it('should cancel pending async work when source changes', async () => {
+      const sourceA = makeHast('A');
+      const sourceB = makeHast('B');
+
+      let resolveA: () => void;
+      const asyncEnhancerA = vi.fn(
+        async () =>
+          new Promise<HastRoot>((resolve) => {
+            resolveA = () => resolve(makeHast('async-A'));
+          }),
+      );
+
+      const syncEnhancerB: SourceEnhancer = () => makeHast('sync-B');
+
+      const { result, rerender } = renderHook(
+        ({ source, enhancers }) =>
+          useSourceEnhancing({
+            source,
+            fileName: 'test.tsx',
+            comments: undefined,
+            sourceEnhancers: enhancers,
+          }),
+        {
+          initialProps: {
+            source: sourceA as HastRoot,
+            enhancers: [asyncEnhancerA] as SourceEnhancer[],
+          },
+        },
+      );
+
+      expect(result.current.isEnhancing).toBe(true);
+
+      // Switch to a new source with a sync enhancer
+      rerender({ source: sourceB, enhancers: [syncEnhancerB] });
+
+      expect(textOf(result.current.enhancedSource)).toBe('sync-B');
+      expect(result.current.isEnhancing).toBe(false);
+
+      // Resolve the old async enhancer — should be cancelled
+      await act(async () => {
+        resolveA!();
+        await new Promise((resolve) => {
+          setTimeout(resolve, 20);
+        });
+      });
+
+      // Should still show the new source, not the stale async result
+      expect(textOf(result.current.enhancedSource)).toBe('sync-B');
+    });
+  });
+
+  describe('hastJson and hastGzip sources', () => {
+    it('should resolve hastJson sources before enhancing', () => {
+      const hast = makeHast('from-json');
+      const source = { hastJson: JSON.stringify(hast) };
+      const enhancer = vi.fn((root: HastRoot) => makeHast(`enhanced-${textOf(root)}`));
+
+      const { result } = renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: [enhancer],
+        }),
+      );
+
+      expect(textOf(result.current.enhancedSource)).toBe('enhanced-from-json');
+      expect(result.current.isEnhancing).toBe(false);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle enhancers that mutate the root in-place', () => {
+      const source = makeHast('original');
+      const enhancer: SourceEnhancer = (root) => {
+        (root.children[0] as { value: string }).value = 'mutated';
+        return root;
+      };
+
+      const { result } = renderHook(() =>
+        useSourceEnhancing({
+          source,
+          fileName: 'test.tsx',
+          comments: undefined,
+          sourceEnhancers: [enhancer],
+        }),
+      );
+
+      expect(textOf(result.current.enhancedSource)).toBe('mutated');
+    });
+
+    it('should handle switching from enhancers to no enhancers', () => {
+      const source = makeHast('original');
+      const enhancer: SourceEnhancer = () => makeHast('enhanced');
+
+      const { result, rerender } = renderHook(
+        ({ enhancers }) =>
+          useSourceEnhancing({
+            source,
+            fileName: 'test.tsx',
+            comments: undefined,
+            sourceEnhancers: enhancers,
+          }),
+        { initialProps: { enhancers: [enhancer] as SourceEnhancer[] | undefined } },
+      );
+
+      expect(textOf(result.current.enhancedSource)).toBe('enhanced');
+
+      rerender({ enhancers: undefined });
+
+      expect(result.current.enhancedSource).toBe(source);
+      expect(result.current.isEnhancing).toBe(false);
+    });
+
+    it('should handle switching from no enhancers to enhancers', () => {
+      const source = makeHast('original');
+      const enhancer: SourceEnhancer = () => makeHast('enhanced');
+
+      const { result, rerender } = renderHook(
+        ({ enhancers }) =>
+          useSourceEnhancing({
+            source,
+            fileName: 'test.tsx',
+            comments: undefined,
+            sourceEnhancers: enhancers,
+          }),
+        { initialProps: { enhancers: undefined as SourceEnhancer[] | undefined } },
+      );
+
+      expect(result.current.enhancedSource).toBe(source);
+
+      rerender({ enhancers: [enhancer] });
+
+      expect(textOf(result.current.enhancedSource)).toBe('enhanced');
+      expect(result.current.isEnhancing).toBe(false);
+    });
+
+    it('should handle source changing to null', () => {
+      const source = makeHast('original');
+      const enhancer: SourceEnhancer = () => makeHast('enhanced');
+      const enhancers: SourceEnhancer[] = [enhancer];
+
+      const { result, rerender } = renderHook(
+        ({ src }) =>
+          useSourceEnhancing({
+            source: src,
+            fileName: 'test.tsx',
+            comments: undefined,
+            sourceEnhancers: enhancers,
+          }),
+        { initialProps: { src: source as HastRoot | null } },
+      );
+
+      expect(textOf(result.current.enhancedSource)).toBe('enhanced');
+
+      rerender({ src: null });
+
+      expect(result.current.enhancedSource).toBeNull();
+      expect(result.current.isEnhancing).toBe(false);
+    });
+  });
+});
diff --git a/packages/docs-infra/src/useCode/useSourceEnhancing.ts b/packages/docs-infra/src/useCode/useSourceEnhancing.ts
index c533eca1c..f09161fe2 100644
--- a/packages/docs-infra/src/useCode/useSourceEnhancing.ts
+++ b/packages/docs-infra/src/useCode/useSourceEnhancing.ts
@@ -3,12 +3,7 @@
 import * as React from 'react';
 import type { Root as HastRoot } from 'hast';
 import { decompressHast } from '../pipeline/hastUtils';
-import type {
-  SourceEnhancers,
-  SourceComments,
-  VariantSource,
-  HastRoot as TypedHastRoot,
-} from '../CodeHighlighter/types';
+import type { SourceEnhancers, SourceComments, VariantSource } from '../CodeHighlighter/types';
 
 /**
  * Type guard to check if a source value is a HAST root node.
@@ -53,28 +48,60 @@ function resolveHastRoot(source: VariantSource | undefined): HastRoot | null {
 }
 
 /**
- * Applies enhancers sequentially to a HAST root.
+ * Applies enhancers sequentially to a HAST root, starting from a given index.
  * Each enhancer receives the output of the previous enhancer in the chain.
- *
- * @param source - The initial HAST root to enhance
- * @param comments - Comments extracted from the source code (keyed by line number)
- * @param fileName - The name of the file being enhanced (used for context)
- * @param enhancers - Array of enhancer functions to apply in order
- * @returns The enhanced HAST root after all enhancers have been applied
  */
-async function applyEnhancers(
+async function applyEnhancersFrom(
   source: HastRoot,
   comments: SourceComments | undefined,
   fileName: string,
   enhancers: SourceEnhancers,
+  startIndex: number,
 ): Promise<HastRoot> {
-  return enhancers.reduce(
-    async (accPromise, enhancer) => {
-      const acc = await accPromise;
-      return enhancer(acc, comments, fileName);
-    },
-    Promise.resolve(source as TypedHastRoot),
-  );
+  return enhancers
+    .slice(startIndex)
+    .reduce<
+      Promise<HastRoot>
+    >((prev, enhancer) => prev.then((current) => enhancer(current, comments, fileName)), Promise.resolve(source));
+}
+
+interface SyncEnhanceResult {
+  /** The result after applying all sync enhancers (and resolving any leading async ones) */
+  syncResult: HastRoot;
+  /** Index of the first enhancer that returned a Promise, or enhancers.length if all were sync */
+  asyncStartIndex: number;
+  /** The promise returned by the first async enhancer, if any */
+  firstAsyncPromise: Promise<HastRoot> | null;
+}
+
+/**
+ * Runs enhancers in order until one returns a Promise.
+ * Returns the sync-enhanced result up to that point, plus the pending promise
+ * and its index so the caller can continue from there without re-running sync work.
+ */
+function applyEnhancersUntilAsync(
+  source: HastRoot,
+  comments: SourceComments | undefined,
+  fileName: string,
+  enhancers: SourceEnhancers,
+): SyncEnhanceResult {
+  let current: HastRoot = source;
+  for (let i = 0; i < enhancers.length; i += 1) {
+    const result = enhancers[i](current, comments, fileName);
+    if (result instanceof Promise) {
+      return {
+        syncResult: current,
+        asyncStartIndex: i,
+        firstAsyncPromise: result,
+      };
+    }
+    current = result;
+  }
+  return {
+    syncResult: current,
+    asyncStartIndex: enhancers.length,
+    firstAsyncPromise: null,
+  };
 }
 
 export interface UseSourceEnhancingProps {
@@ -131,6 +158,46 @@ export interface UseSourceEnhancingResult {
  * - Enhancers must return stable references to avoid infinite re-renders.
  * - Use `React.useMemo` for the enhancers array to prevent unnecessary re-runs.
  */
+interface AsyncWork {
+  firstAsyncPromise: Promise<HastRoot>;
+  asyncStartIndex: number;
+}
+
+interface EnhanceState {
+  enhancedSource: VariantSource | null;
+  asyncWork: AsyncWork | null;
+}
+
+/**
+ * Computes the synchronous enhancement result and any pending async work.
+ * Enhancers are run in order; sync ones apply immediately, and the first
+ * async enhancer's promise is captured so it can be continued in an effect.
+ */
+function computeEnhanceState(
+  source: VariantSource | null | undefined,
+  comments: SourceComments | undefined,
+  fileName: string | undefined,
+  sourceEnhancers: SourceEnhancers | undefined,
+): EnhanceState {
+  if (!source || !sourceEnhancers || sourceEnhancers.length === 0) {
+    return { enhancedSource: source ?? null, asyncWork: null };
+  }
+  const resolved = resolveHastRoot(source);
+  if (!resolved) {
+    return { enhancedSource: source ?? null, asyncWork: null };
+  }
+  const { syncResult, firstAsyncPromise, asyncStartIndex } = applyEnhancersUntilAsync(
+    resolved,
+    comments,
+    fileName || 'unknown',
+    sourceEnhancers,
+  );
+  return {
+    enhancedSource: syncResult,
+    asyncWork: firstAsyncPromise ? { firstAsyncPromise, asyncStartIndex } : null,
+  };
+}
+
 export function useSourceEnhancing({
   source,
   fileName,
@@ -140,73 +207,73 @@ export function useSourceEnhancing({
   // Track previous values to detect changes
   const [prevSource, setPrevSource] = React.useState(source);
   const [prevEnhancers, setPrevEnhancers] = React.useState(sourceEnhancers);
+  const [prevComments, setPrevComments] = React.useState(comments);
+  const [prevFileName, setPrevFileName] = React.useState(fileName);
 
-  // Start with the original source - show it immediately while enhancing
-  const [enhancedSource, setEnhancedSource] = React.useState<VariantSource | null>(source ?? null);
-  const [isEnhancing, setIsEnhancing] = React.useState(
-    () => !!sourceEnhancers && sourceEnhancers.length > 0 && !!source,
+  const [state, setState] = React.useState<EnhanceState>(() =>
+    computeEnhanceState(source, comments, fileName, sourceEnhancers),
   );
 
-  // When source changes, immediately show the new unenhanced source
-  // This prevents layout shift while enhancement runs in background
-  if (source !== prevSource) {
-    setPrevSource(source);
-    setEnhancedSource(source ?? null);
-    if (sourceEnhancers && sourceEnhancers.length > 0 && source) {
-      setIsEnhancing(true);
-    }
-  }
+  const hasChanged =
+    source !== prevSource ||
+    sourceEnhancers !== prevEnhancers ||
+    comments !== prevComments ||
+    fileName !== prevFileName;
 
-  // Track if enhancers changed
-  if (sourceEnhancers !== prevEnhancers) {
-    setPrevEnhancers(sourceEnhancers);
-    if (sourceEnhancers && sourceEnhancers.length > 0 && source) {
-      setIsEnhancing(true);
+  // When inputs change, apply sync enhancers immediately during render
+  if (hasChanged) {
+    if (source !== prevSource) {
+      setPrevSource(source);
+    }
+    if (sourceEnhancers !== prevEnhancers) {
+      setPrevEnhancers(sourceEnhancers);
+    }
+    if (comments !== prevComments) {
+      setPrevComments(comments);
     }
+    if (fileName !== prevFileName) {
+      setPrevFileName(fileName);
+    }
+    setState(computeEnhanceState(source, comments, fileName, sourceEnhancers));
   }
 
+  // Continue from the first async enhancer without re-running sync ones
   React.useEffect(() => {
-    // If no source or no enhancers, just use original
-    if (!source || !sourceEnhancers || sourceEnhancers.length === 0) {
-      setEnhancedSource(source ?? null);
-      setIsEnhancing(false);
-      return undefined;
-    }
-
-    const resolvedHastRoot = resolveHastRoot(source);
-    if (!resolvedHastRoot) {
-      // Can't enhance non-HAST sources
-      setEnhancedSource(source);
-      setIsEnhancing(false);
+    if (!state.asyncWork || !sourceEnhancers) {
       return undefined;
     }
 
-    // Capture values for async function
+    const { firstAsyncPromise, asyncStartIndex } = state.asyncWork;
     const enhancers = sourceEnhancers;
     const name = fileName || 'unknown';
-    const hastRoot = resolvedHastRoot;
     let cancelled = false;
 
-    async function enhance() {
-      setIsEnhancing(true);
-
-      const enhanced = await applyEnhancers(hastRoot, comments, name, enhancers);
-
+    async function continueEnhancing() {
+      const asyncResult = await firstAsyncPromise;
+      if (cancelled) {
+        return;
+      }
+      const final = await applyEnhancersFrom(
+        asyncResult,
+        comments,
+        name,
+        enhancers,
+        asyncStartIndex + 1,
+      );
       if (!cancelled) {
-        setEnhancedSource(enhanced);
-        setIsEnhancing(false);
+        setState({ enhancedSource: final, asyncWork: null });
       }
     }
 
-    enhance();
+    continueEnhancing();
 
     return () => {
       cancelled = true;
     };
-  }, [source, fileName, comments, sourceEnhancers]);
+  }, [state.asyncWork, sourceEnhancers, fileName, comments]);
 
   return {
-    enhancedSource,
-    isEnhancing,
+    enhancedSource: state.enhancedSource,
+    isEnhancing: state.asyncWork !== null,
   };
 }
diff --git a/packages/docs-infra/src/useDemo/useDemo.ts b/packages/docs-infra/src/useDemo/useDemo.ts
index 3ff7c7403..2120a4ed8 100644
--- a/packages/docs-infra/src/useDemo/useDemo.ts
+++ b/packages/docs-infra/src/useDemo/useDemo.ts
@@ -107,10 +107,12 @@ export function useDemo<T extends {} = {}>(contentProps: ContentProps<T>, opts?:
     return effectiveComponents[code.selectedVariant] || null;
   }, [effectiveComponents, code.selectedVariant]);
 
-  // Demo-specific ref and focus management
-  const ref = React.useRef<HTMLDivElement | null>(null);
+  // Demo-specific ref and focus management. Typed as `HTMLButtonElement` since
+  // the typical pattern is an invisible focus-target button rendered inside the
+  // demo. `resetFocus` simply calls `.focus()` on it.
+  const focusRef = React.useRef<HTMLButtonElement | null>(null);
   const resetFocus = React.useCallback(() => {
-    ref.current?.focus();
+    focusRef.current?.focus();
   }, []);
 
   // Get the effective code - context overrides contentProps if available
@@ -222,7 +224,7 @@ export function useDemo<T extends {} = {}>(contentProps: ContentProps<T>, opts?:
     ...code,
     // Demo-specific additions
     component,
-    ref,
+    focusRef,
     resetFocus,
     openStackBlitz,
     openCodeSandbox,
diff --git a/packages/test-utils/package.json b/packages/test-utils/package.json
index 387c052fa..1ff831350 100644
--- a/packages/test-utils/package.json
+++ b/packages/test-utils/package.json
@@ -39,7 +39,7 @@
     "vitest-fail-on-console": "^0.10.1"
   },
   "devDependencies": {
-    "@playwright/test": "1.58.2",
+    "@playwright/test": "1.59.1",
     "@types/chai": "5.2.3",
     "@types/format-util": "1.0.4",
     "@types/jsdom": "28.0.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1bb55ff66..e91750fda 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -84,11 +84,14 @@ importers:
         version: 4.21.0
       vitest:
         specifier: ^4.1.5
-        version: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.5)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
+        version: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
     devDependencies:
       '@babel/plugin-transform-react-constant-elements':
         specifier: 7.27.1
         version: 7.27.1(@babel/core@7.29.0)
+      '@vitest/browser-playwright':
+        specifier: 4.1.3
+        version: 4.1.3(playwright@1.59.1)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)
       baseline-browser-mapping:
         specifier: 2.10.19
         version: 2.10.19
@@ -102,8 +105,8 @@ importers:
         specifier: 0.0.66
         version: 0.0.66
       playwright:
-        specifier: 1.58.2
-        version: 1.58.2
+        specifier: 1.59.1
+        version: 1.59.1
       stylelint:
         specifier: 17.4.0
         version: 17.4.0(typescript@6.0.2)
@@ -133,7 +136,7 @@ importers:
         version: 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@types/react@19.2.14)(react@19.2.5))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
       '@mui/material-nextjs':
         specifier: 9.0.0-alpha.2
-        version: 9.0.0-alpha.2(@emotion/cache@11.14.0)(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@emotion/server@11.11.0)(@types/react@19.2.14)(next@16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5))(react@19.2.5)
+        version: 9.0.0-alpha.2(@emotion/cache@11.14.0)(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@emotion/server@11.11.0)(@types/react@19.2.14)(next@16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.59.1)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5))(react@19.2.5)
       '@mui/x-charts-pro':
         specifier: 9.0.0-alpha.2
         version: 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@types/react@19.2.14)(react@19.2.5))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@types/react@19.2.14)(react@19.2.5))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.5))(react@19.2.5))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@types/react@19.2.14)(react@19.2.5))(@types/react@19.2.14)(react@19.2.5))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
@@ -175,7 +178,7 @@ importers:
         version: 3.20.0(@types/node@22.19.0)
       next:
         specifier: ^16.1.6
-        version: 16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
+        version: 16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.59.1)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
       pako:
         specifier: ^2.1.0
         version: 2.1.0
@@ -294,7 +297,7 @@ importers:
         version: 0.577.0(react@19.2.5)
       next:
         specifier: ^16.1.6
-        version: 16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
+        version: 16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.59.1)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
       react:
         specifier: ^19.2.5
         version: 19.2.5
@@ -436,7 +439,7 @@ importers:
         version: 6.0.1(babel-plugin-react-compiler@1.0.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
       '@vitest/browser-playwright':
         specifier: '>=4.1'
-        version: 4.1.5(playwright@1.58.2)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)
+        version: 4.1.5(playwright@1.59.1)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)
       env-ci:
         specifier: ^11.2.0
         version: 11.2.0
@@ -873,12 +876,18 @@ importers:
       unist-util-visit:
         specifier: ^5.1.0
         version: 5.1.0
+      use-editable:
+        specifier: ^2.3.3
+        version: 2.3.3(react@19.2.5)
       vscode-oniguruma:
         specifier: ^2.0.1
         version: 2.0.1
       yargs:
         specifier: ^18.0.0
         version: 18.0.0
+      zx:
+        specifier: ^8.8.5
+        version: 8.8.5
     devDependencies:
       '@testing-library/react':
         specifier: 16.3.2
@@ -907,6 +916,9 @@ importers:
       '@types/react':
         specifier: 19.2.14
         version: 19.2.14
+      '@types/react-dom':
+        specifier: 19.2.3
+        version: 19.2.3(@types/react@19.2.14)
       '@types/webpack':
         specifier: 5.28.5
         version: 5.28.5(esbuild@0.27.1)(jiti@2.6.1)
@@ -924,10 +936,13 @@ importers:
         version: 9.0.5
       next:
         specifier: 16.2.3
-        version: 16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
+        version: 16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.59.1)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
       react:
         specifier: 19.2.5
         version: 19.2.5
+      react-dom:
+        specifier: 19.2.5
+        version: 19.2.5(react@19.2.5)
       rehype-parse:
         specifier: 9.0.1
         version: 9.0.1
@@ -1000,8 +1015,8 @@ importers:
         version: 0.10.1(@vitest/utils@4.1.5)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)
     devDependencies:
       '@playwright/test':
-        specifier: 1.58.2
-        version: 1.58.2
+        specifier: 1.59.1
+        version: 1.59.1
       '@types/chai':
         specifier: 5.2.3
         version: 5.2.3
@@ -1052,7 +1067,7 @@ importers:
         version: 19.2.14
       '@vitest/browser-playwright':
         specifier: 4.1.5
-        version: 4.1.5(playwright@1.58.2)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)
+        version: 4.1.5(playwright@1.59.1)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)
       vitest:
         specifier: 4.1.5
         version: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.5)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
@@ -4568,8 +4583,8 @@ packages:
     resolution: {integrity: sha512-QNqXyfVS2wm9hweSYD2O7F0G06uurj9kZ96TRQE5Y9hU7+tgdZwIkbAKc5Ocy1HxEY2kuDQa6cQ1WRs/O5LFKA==}
     engines: {node: ^12.20.0 || ^14.18.0 || >=16.0.0}
 
-  '@playwright/test@1.58.2':
-    resolution: {integrity: sha512-akea+6bHYBBfA9uQqSYmlJXn61cTa+jbO87xVLCWbTqbWadRVmhxlXATaOjOgcBaWU4ePo0wB41KMFv3o35IXA==}
+  '@playwright/test@1.59.1':
+    resolution: {integrity: sha512-PG6q63nQg5c9rIi4/Z5lR5IVF7yU5MqmKaPOe0HSc0O2cX1fPi96sUQu5j7eo4gKCkB2AnNGoWt7y4/Xx3Kcqg==}
     engines: {node: '>=18'}
     hasBin: true
 
@@ -5751,12 +5766,23 @@ packages:
       babel-plugin-react-compiler:
         optional: true
 
+  '@vitest/browser-playwright@4.1.3':
+    resolution: {integrity: sha512-D3Q+YozvSpiFaLPgd6/OMbyqEIZeucSe6AHJJ7VnNJKQhIyBE60TlBZlxzwM8bvjzQE9ZnYWQCPeCw5pnhbiNg==}
+    peerDependencies:
+      playwright: '*'
+      vitest: 4.1.3
+
   '@vitest/browser-playwright@4.1.5':
     resolution: {integrity: sha512-CWy0lBQJq97nionyJJdnaU4961IXTl43a7UCu5nHy51IoKxAt6PVIJLo+76rVl7KOOgcWHNkG4kbJu/pW7knvA==}
     peerDependencies:
       playwright: '*'
       vitest: 4.1.5
 
+  '@vitest/browser@4.1.3':
+    resolution: {integrity: sha512-CS9KjO2vijuBlbwz0JIgC0YuoI1BuqWI5ziD3Nll6jkpNYtWdjPMVgGynQ9vZovjsECeUqEeNjWrypP414d0CQ==}
+    peerDependencies:
+      vitest: 4.1.3
+
   '@vitest/browser@4.1.5':
     resolution: {integrity: sha512-iCDGI8c4yg+xmjUg2VsygdAUSIIB4x5Rht/P68OXy1hPELKXHDkzh87lkuTcdYmemRChDkEpB426MmDjzC0ziA==}
     peerDependencies:
@@ -5787,6 +5813,17 @@ packages:
   '@vitest/expect@4.1.5':
     resolution: {integrity: sha512-PWBaRY5JoKuRnHlUHfpV/KohFylaDZTupcXN1H9vYryNLOnitSw60Mw9IAE2r67NbwwzBw/Cc/8q9BK3kIX8Kw==}
 
+  '@vitest/mocker@4.1.3':
+    resolution: {integrity: sha512-XN3TrycitDQSzGRnec/YWgoofkYRhouyVQj4YNsJ5r/STCUFqMrP4+oxEv3e7ZbLi4og5kIHrZwekDJgw6hcjw==}
+    peerDependencies:
+      msw: ^2.4.9
+      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+    peerDependenciesMeta:
+      msw:
+        optional: true
+      vite:
+        optional: true
+
   '@vitest/mocker@4.1.5':
     resolution: {integrity: sha512-/x2EmFC4mT4NNzqvC3fmesuV97w5FC903KPmey4gsnJiMQ3Be1IlDKVaDaG8iqaLFHqJ2FVEkxZk5VmeLjIItw==}
     peerDependencies:
@@ -5798,6 +5835,9 @@ packages:
       vite:
         optional: true
 
+  '@vitest/pretty-format@4.1.3':
+    resolution: {integrity: sha512-hYqqwuMbpkkBodpRh4k4cQSOELxXky1NfMmQvOfKvV8zQHz8x8Dla+2wzElkMkBvSAJX5TRGHJAQvK0TcOafwg==}
+
   '@vitest/pretty-format@4.1.5':
     resolution: {integrity: sha512-7I3q6l5qr03dVfMX2wCo9FxwSJbPdwKjy2uu/YPpU3wfHvIL4QHwVRp57OfGrDFeUJ8/8QdfBKIV12FTtLn00g==}
 
@@ -5807,9 +5847,15 @@ packages:
   '@vitest/snapshot@4.1.5':
     resolution: {integrity: sha512-zypXEt4KH/XgKGPUz4eC2AvErYx0My5hfL8oDb1HzGFpEk1P62bxSohdyOmvz+d9UJwanI68MKwr2EquOaOgMQ==}
 
+  '@vitest/spy@4.1.3':
+    resolution: {integrity: sha512-ujj5Uwxagg4XUIfAUyRQxAg631BP6e9joRiN99mr48Bg9fRs+5mdUElhOoZ6rP5mBr8Bs3lmrREnkrQWkrsTCw==}
+
   '@vitest/spy@4.1.5':
     resolution: {integrity: sha512-2lNOsh6+R2Idnf1TCZqSwYlKN2E/iDlD8sgU59kYVl+OMDmvldO1VDk39smRfpUNwYpNRVn3w4YfuC7KfbBnkQ==}
 
+  '@vitest/utils@4.1.3':
+    resolution: {integrity: sha512-Pc/Oexse/khOWsGB+w3q4yzA4te7W4gpZZAvk+fr8qXfTURZUMj5i7kuxsNK5mP/dEB6ao3jfr0rs17fHhbHdw==}
+
   '@vitest/utils@4.1.5':
     resolution: {integrity: sha512-76wdkrmfXfqGjueGgnb45ITPyUi1ycZ4IHgC2bhPDUfWHklY/q3MdLOAB+TF1e6xfl8NxNY0ZYaPCFNWSsw3Ug==}
 
@@ -10107,13 +10153,13 @@ packages:
     resolution: {integrity: sha512-nDywThFk1i4BQK4twPQ6TA4RT8bDY96yeuCVBWL3ePARCiEKDRSrNGbFIgUJpLp+XeIR65v8ra7WuJOFUBtkMA==}
     engines: {node: '>=8'}
 
-  playwright-core@1.58.2:
-    resolution: {integrity: sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg==}
+  playwright-core@1.59.1:
+    resolution: {integrity: sha512-HBV/RJg81z5BiiZ9yPzIiClYV/QMsDCKUyogwH9p3MCP6IYjUFu/MActgYAvK0oWyV9NlwM3GLBjADyWgydVyg==}
     engines: {node: '>=18'}
     hasBin: true
 
-  playwright@1.58.2:
-    resolution: {integrity: sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A==}
+  playwright@1.59.1:
+    resolution: {integrity: sha512-C8oWjPR3F81yljW9o5OxcWzfh6avkVwDD2VYdwIGqTkl+OGFISgypqzfu7dOe4QNLL2aqcWBmI3PMtLIK233lw==}
     engines: {node: '>=18'}
     hasBin: true
 
@@ -12144,6 +12190,11 @@ packages:
   zwitch@2.0.4:
     resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
 
+  zx@8.8.5:
+    resolution: {integrity: sha512-SNgDF5L0gfN7FwVOdEFguY3orU5AkfFZm9B5YSHog/UDHv+lvmd82ZAsOenOkQixigwH2+yyH198AwNdKhj+RA==}
+    engines: {node: '>= 12.17.0'}
+    hasBin: true
+
 snapshots:
 
   '@-xun/debug@2.0.2':
@@ -14509,11 +14560,11 @@ snapshots:
       '@emotion/styled': 11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@types/react@19.2.14)(react@19.2.5)
       '@types/react': 19.2.14
 
-  '@mui/material-nextjs@9.0.0-alpha.2(@emotion/cache@11.14.0)(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@emotion/server@11.11.0)(@types/react@19.2.14)(next@16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5))(react@19.2.5)':
+  '@mui/material-nextjs@9.0.0-alpha.2(@emotion/cache@11.14.0)(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.5))(@emotion/server@11.11.0)(@types/react@19.2.14)(next@16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.59.1)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5))(react@19.2.5)':
     dependencies:
       '@babel/runtime': 7.29.2
       '@emotion/react': 11.14.0(@types/react@19.2.14)(react@19.2.5)
-      next: 16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
+      next: 16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.59.1)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
       react: 19.2.5
     optionalDependencies:
       '@emotion/cache': 11.14.0
@@ -16148,9 +16199,9 @@ snapshots:
 
   '@pkgr/core@0.2.9': {}
 
-  '@playwright/test@1.58.2':
+  '@playwright/test@1.59.1':
     dependencies:
-      playwright: 1.58.2
+      playwright: 1.59.1
 
   '@pnpm/config.env-replace@1.1.0': {}
 
@@ -17667,11 +17718,24 @@ snapshots:
     optionalDependencies:
       babel-plugin-react-compiler: 1.0.0
 
-  '@vitest/browser-playwright@4.1.5(playwright@1.58.2)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)':
+  '@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)':
+    dependencies:
+      '@vitest/browser': 4.1.3(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)
+      '@vitest/mocker': 4.1.3(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
+      playwright: 1.59.1
+      tinyrainbow: 3.1.0
+      vitest: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
+    transitivePeerDependencies:
+      - bufferutil
+      - msw
+      - utf-8-validate
+      - vite
+
+  '@vitest/browser-playwright@4.1.5(playwright@1.59.1)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)':
     dependencies:
       '@vitest/browser': 4.1.5(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)
       '@vitest/mocker': 4.1.5(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
-      playwright: 1.58.2
+      playwright: 1.59.1
       tinyrainbow: 3.1.0
       vitest: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.5)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
     transitivePeerDependencies:
@@ -17680,6 +17744,23 @@ snapshots:
       - utf-8-validate
       - vite
 
+  '@vitest/browser@4.1.3(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)':
+    dependencies:
+      '@blazediff/core': 1.9.1
+      '@vitest/mocker': 4.1.3(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
+      '@vitest/utils': 4.1.3
+      magic-string: 0.30.21
+      pngjs: 7.0.0
+      sirv: 3.0.2
+      tinyrainbow: 3.1.0
+      vitest: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
+      ws: 8.19.0
+    transitivePeerDependencies:
+      - bufferutil
+      - msw
+      - utf-8-validate
+      - vite
+
   '@vitest/browser@4.1.5(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)':
     dependencies:
       '@blazediff/core': 1.9.1
@@ -17689,7 +17770,7 @@ snapshots:
       pngjs: 7.0.0
       sirv: 3.0.2
       tinyrainbow: 3.1.0
-      vitest: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.5)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
+      vitest: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
       ws: 8.19.0
     transitivePeerDependencies:
       - bufferutil
@@ -17709,7 +17790,7 @@ snapshots:
       obug: 2.1.1
       std-env: 4.0.0
       tinyrainbow: 3.1.0
-      vitest: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.5)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
+      vitest: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
     optionalDependencies:
       '@vitest/browser': 4.1.5(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)
 
@@ -17733,6 +17814,14 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.1.0
 
+  '@vitest/mocker@4.1.3(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))':
+    dependencies:
+      '@vitest/spy': 4.1.3
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1)
+
   '@vitest/mocker@4.1.5(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))':
     dependencies:
       '@vitest/spy': 4.1.5
@@ -17741,6 +17830,10 @@ snapshots:
     optionalDependencies:
       vite: 8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1)
 
+  '@vitest/pretty-format@4.1.3':
+    dependencies:
+      tinyrainbow: 3.1.0
+
   '@vitest/pretty-format@4.1.5':
     dependencies:
       tinyrainbow: 3.1.0
@@ -17757,8 +17850,16 @@ snapshots:
       magic-string: 0.30.21
       pathe: 2.0.3
 
+  '@vitest/spy@4.1.3': {}
+
   '@vitest/spy@4.1.5': {}
 
+  '@vitest/utils@4.1.3':
+    dependencies:
+      '@vitest/pretty-format': 4.1.3
+      convert-source-map: 2.0.0
+      tinyrainbow: 3.1.0
+
   '@vitest/utils@4.1.5':
     dependencies:
       '@vitest/pretty-format': 4.1.5
@@ -22350,7 +22451,7 @@ snapshots:
 
   neo-async@2.6.2: {}
 
-  next@16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.58.2)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5):
+  next@16.2.3(@babel/core@7.29.0)(@opentelemetry/api@1.9.0)(@playwright/test@1.59.1)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.5(react@19.2.5))(react@19.2.5):
     dependencies:
       '@next/env': 16.2.3
       '@swc/helpers': 0.5.15
@@ -22370,7 +22471,7 @@ snapshots:
       '@next/swc-win32-arm64-msvc': 16.2.3
       '@next/swc-win32-x64-msvc': 16.2.3
       '@opentelemetry/api': 1.9.0
-      '@playwright/test': 1.58.2
+      '@playwright/test': 1.59.1
       babel-plugin-react-compiler: 1.0.0
       sharp: 0.34.5
     transitivePeerDependencies:
@@ -23030,11 +23131,11 @@ snapshots:
     dependencies:
       find-up: 3.0.0
 
-  playwright-core@1.58.2: {}
+  playwright-core@1.59.1: {}
 
-  playwright@1.58.2:
+  playwright@1.59.1:
     dependencies:
-      playwright-core: 1.58.2
+      playwright-core: 1.59.1
     optionalDependencies:
       fsevents: 2.3.2
 
@@ -24965,6 +25066,37 @@ snapshots:
       vite: 8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1)
       vitest: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.5)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
 
+  vitest@4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1)):
+    dependencies:
+      '@vitest/expect': 4.1.5
+      '@vitest/mocker': 4.1.5(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
+      '@vitest/pretty-format': 4.1.5
+      '@vitest/runner': 4.1.5
+      '@vitest/snapshot': 4.1.5
+      '@vitest/spy': 4.1.5
+      '@vitest/utils': 4.1.5
+      es-module-lexer: 2.0.0
+      expect-type: 1.3.0
+      magic-string: 0.30.21
+      obug: 2.1.1
+      pathe: 2.0.3
+      picomatch: 4.0.4
+      std-env: 4.0.0
+      tinybench: 2.9.0
+      tinyexec: 1.1.1
+      tinyglobby: 0.2.16
+      tinyrainbow: 3.1.0
+      vite: 8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@opentelemetry/api': 1.9.0
+      '@types/node': 22.19.0
+      '@vitest/browser-playwright': 4.1.3(playwright@1.59.1)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)
+      '@vitest/coverage-v8': 4.1.5(@vitest/browser@4.1.5)(vitest@4.1.5)
+      jsdom: 28.1.0
+    transitivePeerDependencies:
+      - msw
+
   vitest@4.1.5(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.5)(@vitest/coverage-v8@4.1.5)(jsdom@28.1.0)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1)):
     dependencies:
       '@vitest/expect': 4.1.5
@@ -24990,7 +25122,7 @@ snapshots:
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
       '@types/node': 22.19.0
-      '@vitest/browser-playwright': 4.1.5(playwright@1.58.2)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)
+      '@vitest/browser-playwright': 4.1.5(playwright@1.59.1)(vite@8.0.10(@types/node@22.19.0)(esbuild@0.27.1)(jiti@2.6.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))(vitest@4.1.5)
       '@vitest/coverage-v8': 4.1.5(@vitest/browser@4.1.5)(vitest@4.1.5)
       jsdom: 28.1.0
     transitivePeerDependencies:
@@ -25343,3 +25475,5 @@ snapshots:
   zod@4.3.6: {}
 
   zwitch@2.0.4: {}
+
+  zx@8.8.5: {}
diff --git a/vitest.config.browser.mts b/vitest.config.browser.mts
new file mode 100644
index 000000000..8596f384b
--- /dev/null
+++ b/vitest.config.browser.mts
@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+import { playwright } from '@vitest/browser-playwright';
+
+const wsEndpoint = process.env.PLAYWRIGHT_SERVER;
+
+export default defineConfig({
+  test: {
+    include: ['packages/**/*.browser.{ts,tsx}'],
+    browser: {
+      enabled: true,
+      provider: playwright({
+        ...(wsEndpoint ? { connectOptions: { wsEndpoint } } : {}),
+      }),
+      headless: true,
+      instances: [{ browser: 'chromium' }, { browser: 'firefox' }, { browser: 'webkit' }],
+    },
+  },
+});