From 9fbbf841bcda38fef961213dd506771e2584276a Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 19 Mar 2026 22:56:52 -0400
Subject: [PATCH 01/45] Integrate useEditable() and pass controller to
 abstractCreateDemoClient()

---
 .../demos/code-editor/CodeEditorContent.tsx   |  13 +-
 .../demos/demo-live/DemoLive.tsx              |   5 +-
 .../demos/demo-live/DemoLiveContent.tsx       |  12 +-
 .../demos/demo-live/createDemoClient.ts       |   3 +-
 .../demos/multi-file/MultiFileContent.tsx     |  13 +-
 .../code-controller-context/page.mdx          |  43 +--
 .../abstract-create-demo-client/page.mdx      |  18 +-
 docs/app/docs-infra/hooks/use-demo/page.mdx   |  12 +-
 packages/docs-infra/package.json              |   3 +-
 .../abstractCreateDemoClient.tsx              |  62 ++--
 packages/docs-infra/src/useCode/Pre.tsx       |  32 ++
 packages/docs-infra/src/useCode/useCode.ts    |  29 +-
 .../src/useCode/useFileNavigation.test.ts     |   6 +-
 .../src/useCode/useFileNavigation.tsx         |  27 +-
 .../src/useCode/useSourceEditing.test.ts      | 281 ++++++++++++++++++
 .../src/useCode/useSourceEditing.ts           | 114 +++++--
 pnpm-lock.yaml                                |   3 +
 17 files changed, 520 insertions(+), 156 deletions(-)
 create mode 100644 packages/docs-infra/src/useCode/useSourceEditing.test.ts

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 2f9972650..3711b5f15 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,8 +9,7 @@ import styles from './CodeEditorContent.module.css';
 import '@wooorm/starry-night/style/light'; // load the light theme for syntax highlighting
 
 export function CodeEditorContent(props: ContentProps<object>) {
-  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';
@@ -23,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 e634b8568..8352553a9 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,14 +1,11 @@
 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 (
     <CodeProvider>
-      <DemoController>
-        <DemoCheckboxBasic />
-      </DemoController>
+      <DemoCheckboxBasic />
     </CodeProvider>
   );
 }
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 167c91925..f62adebd1 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,8 +15,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function DemoLiveContent(props: ContentProps<object>) {
-  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';
@@ -40,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 a447eebe9..f650db127 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,8 +9,7 @@ import styles from '../code-editor/CodeEditorContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function MultiFileContent(props: ContentProps<object>) {
-  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 }) => ({
@@ -20,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 317172eef..a5920b4cb 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`](../use-code/page.mdx) hook automatically integrates with the Cod
 ```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`](../use-demo/page.mdx) hook provides additional functionality for live component demos:
+The [`useDemo`](../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,
 });
 ```
 
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 c72d1c7c7..c15be26a6 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,
 });
 ```
 
@@ -96,21 +96,24 @@ The generated client provider component:
 ### AbstractCreateDemoClientOptions
 
 ```ts
-type AbstractCreateDemoClientOptions = {
-  live?: boolean; // Enable live demo functionality
-  [key: string]: any; // Additional client configuration
+type DefaultController = React.ComponentType<{ children: React.ReactNode }>;
+
+type AbstractCreateDemoClientOptions<C extends DefaultController> = {
+  DemoController: C; // Required — wraps each demo in this controller component
+  [key: string]: any;
 };
 ```
 
 ### CreateDemoClientMeta
 
 ```ts
-type CreateDemoClientMeta = {
+type CreateDemoClientMeta<C extends DefaultController> = {
   name?: string; // Display name for the demo
   slug?: string; // URL-friendly identifier
   displayName?: string; // Component display name
   variantType?: string; // Type of variant implementation
   skipPrecompute?: boolean; // Skip build-time precomputation
+  controllerProps?: Omit<React.ComponentProps<C>, 'children'>; // Props forwarded to DemoController
   precompute?: {
     // Precomputed data
     externals?: Externals; // External dependencies
@@ -146,9 +149,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/hooks/use-demo/page.mdx b/docs/app/docs-infra/hooks/use-demo/page.mdx
index 7c5e40bdd..dab05bae7 100644
--- a/docs/app/docs-infra/hooks/use-demo/page.mdx
+++ b/docs/app/docs-infra/hooks/use-demo/page.mdx
@@ -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}>
diff --git a/packages/docs-infra/package.json b/packages/docs-infra/package.json
index 1982b445d..ac2df4eeb 100644
--- a/packages/docs-infra/package.json
+++ b/packages/docs-infra/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "bin": {
@@ -100,6 +100,7 @@
     "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"
   },
diff --git a/packages/docs-infra/src/abstractCreateDemoClient/abstractCreateDemoClient.tsx b/packages/docs-infra/src/abstractCreateDemoClient/abstractCreateDemoClient.tsx
index 2a66fa918..db7185bcc 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';
 
-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'>
+>;
+
+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/useCode/Pre.tsx b/packages/docs-infra/src/useCode/Pre.tsx
index a79050a18..43522f720 100644
--- a/packages/docs-infra/src/useCode/Pre.tsx
+++ b/packages/docs-infra/src/useCode/Pre.tsx
@@ -5,6 +5,8 @@ import { toText } from 'hast-util-to-text';
 import { ElementContent } from 'hast';
 import { decompressSync, strFromU8 } from 'fflate';
 import { decode } from 'uint8-to-base64';
+import { useEditable } from 'use-editable';
+import type { Position } from 'use-editable';
 import type { HastRoot, VariantSource } from '../CodeHighlighter/types';
 import { hastToJsx } from '../pipeline/hastUtils';
 
@@ -36,15 +38,19 @@ function renderCode(hastChildren: ElementContent[], renderHast?: boolean, text?:
 export function Pre({
   children,
   className,
+  fileName,
   language,
   ref,
+  setSource,
   shouldHighlight,
   hydrateMargin = '200px 0px 200px 0px',
 }: {
   children: VariantSource;
   className?: string;
+  fileName?: string;
   language?: string;
   ref?: React.Ref<HTMLPreElement>;
+  setSource?: (source: string, fileName?: string, position?: Position) => void;
   shouldHighlight?: boolean;
   hydrateMargin?: string;
 }): React.ReactNode {
@@ -64,6 +70,30 @@ 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) => {
+      setSource?.(text, fileName, position);
+    },
+    [setSource, fileName],
+  );
+
+  useEditable(preRef, onEditableChange, {
+    indentation: 2,
+    disabled: !setSource || !editableReady,
+  });
+
   const [visibleFrames, setVisibleFrames] = React.useState<{ [key: number]: boolean }>({
     [0]: true,
   });
@@ -71,6 +101,8 @@ export function Pre({
   const observer = React.useRef<IntersectionObserver | null>(null);
   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/useCode.ts b/packages/docs-infra/src/useCode/useCode.ts
index 1728571d3..99aa4df3a 100644
--- a/packages/docs-infra/src/useCode/useCode.ts
+++ b/packages/docs-infra/src/useCode/useCode.ts
@@ -9,11 +9,11 @@ import { useFileNavigation } from './useFileNavigation';
 import { useUIState } from './useUIState';
 import { useCopyFunctionality } from './useCopyFunctionality';
 import { useSourceEditing } from './useSourceEditing';
+import type { Position } from './useSourceEditing';
 import { UseCopierOpts } from '../useCopier';
 
 export type UseCodeOpts = {
   preClassName?: string;
-  preRef?: React.Ref<HTMLPreElement>;
   defaultOpen?: boolean;
   copy?: UseCopierOpts;
   githubUrlPrefix?: string;
@@ -38,6 +38,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 +66,7 @@ export interface UseCodeResult<T extends {} = {}> {
   availableTransforms: string[];
   selectedTransform: string | null | undefined;
   selectTransform: (transformName: string | null) => void;
-  setSource?: (source: string) => void;
+  setSource?: (source: string, fileName?: string, position?: Position) => void;
   userProps: UserProps<T>;
 }
 
@@ -76,10 +80,10 @@ 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
@@ -146,6 +150,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,
@@ -156,7 +169,7 @@ export function useCode<T extends {} = {}>(
     variantKeys: variantSelection.variantKeys,
     shouldHighlight,
     preClassName,
-    preRef,
+    setSource: sourceEditing.setSource,
     effectiveCode,
     fileHashMode,
     saveHashVariantToLocalStorage,
@@ -171,14 +184,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/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 a13a69365..d46599a82 100644
--- a/packages/docs-infra/src/useCode/useFileNavigation.tsx
+++ b/packages/docs-infra/src/useCode/useFileNavigation.tsx
@@ -13,6 +13,7 @@ import { useUrlHashState } from '../useUrlHashState';
 import { countLines } from '../pipeline/parseSource/addLineGutters';
 import { getLanguageFromExtension } from '../pipeline/loaderUtils/getLanguageFromExtension';
 import type { TransformedFiles } from './useCodeUtils';
+import type { Position } from './useSourceEditing';
 import { Pre } from './Pre';
 import { useSourceEnhancing } from './useSourceEnhancing';
 
@@ -108,7 +109,7 @@ interface UseFileNavigationProps {
   variantKeys?: string[];
   shouldHighlight: boolean;
   preClassName?: string;
-  preRef?: React.Ref<HTMLPreElement>;
+  setSource?: (source: string, fileName?: string, position?: Position) => void;
   effectiveCode?: Code;
   selectVariant?: React.Dispatch<React.SetStateAction<string>>;
   fileHashMode?: 'remove-hash' | 'remove-filename';
@@ -143,7 +144,7 @@ export function useFileNavigation({
   variantKeys = [],
   shouldHighlight,
   preClassName,
-  preRef,
+  setSource,
   effectiveCode,
   selectVariant,
   fileHashMode = 'remove-hash',
@@ -500,12 +501,15 @@ export function useFileNavigation({
       const language = isMainFile
         ? selectedVariant.language
         : getLanguageFromFileName(selectedFileNameInternal);
+      const fileName = selectedFileNameInternal || selectedVariant.fileName;
 
       return (
         <Pre
+          key={fileName}
           className={preClassName}
+          fileName={fileName}
           language={language}
-          ref={preRef}
+          setSource={setSource}
           shouldHighlight={shouldHighlight}
         >
           {sourceToRender}
@@ -518,7 +522,7 @@ export function useFileNavigation({
     selectedVariant,
     shouldHighlight,
     preClassName,
-    preRef,
+    setSource,
     enhancedSource,
     selectedFile,
     sourceEnhancers,
@@ -579,7 +583,12 @@ export function useFileNavigation({
         name: f.name,
         slug: generateFileSlug(mainSlug, f.originalName, selectedVariantKey),
         component: (
-          <Pre className={preClassName} ref={preRef} shouldHighlight={shouldHighlight}>
+          <Pre
+            className={preClassName}
+            fileName={f.originalName}
+            setSource={setSource}
+            shouldHighlight={shouldHighlight}
+          >
             {f.source}
           </Pre>
         ),
@@ -597,8 +606,9 @@ export function useFileNavigation({
         component: (
           <Pre
             className={preClassName}
+            fileName={selectedVariant.fileName}
             language={selectedVariant.language}
-            ref={preRef}
+            setSource={setSource}
             shouldHighlight={shouldHighlight}
           >
             {selectedVariant.source}
@@ -631,8 +641,9 @@ export function useFileNavigation({
           component: (
             <Pre
               className={preClassName}
+              fileName={fileName}
               language={language ?? getLanguageFromFileName(fileName)}
-              ref={preRef}
+              setSource={setSource}
               shouldHighlight={shouldHighlight}
             >
               {source}
@@ -650,7 +661,7 @@ export function useFileNavigation({
     selectedVariantKey,
     shouldHighlight,
     preClassName,
-    preRef,
+    setSource,
   ]);
 
   // 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..9b523f9ca
--- /dev/null
+++ b/packages/docs-infra/src/useCode/useSourceEditing.test.ts
@@ -0,0 +1,281 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useSourceEditing } from './useSourceEditing';
+import type { Code, ControlledCode, VariantCode } from '../CodeHighlighter/types';
+import type { CodeHighlighterContextType } from '../CodeHighlighter/CodeHighlighterContext';
+
+function createContext(
+  overrides: Partial<CodeHighlighterContextType> = {},
+): CodeHighlighterContextType {
+  return {
+    code: {},
+    setCode: vi.fn(),
+    ...overrides,
+  };
+}
+
+/**
+ * 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; }' });
+      expect(variant.extraFiles!['helpers.ts']).toEqual({ source: 'export const h = 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' });
+    });
+
+    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' });
+      expect(variant.extraFiles!['helpers.ts']).toEqual({ source: 'helper content' });
+    });
+  });
+
+  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' });
+    });
+  });
+
+  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' });
+    });
+  });
+});
diff --git a/packages/docs-infra/src/useCode/useSourceEditing.ts b/packages/docs-infra/src/useCode/useSourceEditing.ts
index 9908e8761..4787c325a 100644
--- a/packages/docs-infra/src/useCode/useSourceEditing.ts
+++ b/packages/docs-infra/src/useCode/useSourceEditing.ts
@@ -1,56 +1,128 @@
 import * as React from 'react';
-import type { Code, ControlledCode, VariantCode } from '../CodeHighlighter/types';
+import type { Position } from 'use-editable';
+import type {
+  Code,
+  ControlledCode,
+  ControlledVariantExtraFiles,
+  VariantCode,
+} from '../CodeHighlighter/types';
 import type { CodeHighlighterContextType } from '../CodeHighlighter/CodeHighlighterContext';
+import { stringOrHastToString } from '../pipeline/hastUtils';
+
+export type { Position };
 
 interface UseSourceEditingProps {
   context?: CodeHighlighterContextType;
   selectedVariantKey: string;
   effectiveCode: Code;
   selectedVariant: VariantCode | null;
+  disabled?: boolean;
 }
 
 export interface UseSourceEditingResult {
-  setSource?: (source: string) => void;
+  setSource?: (source: string, fileName?: string, position?: Position) => void;
+}
+
+/**
+ * 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 };
+        } else {
+          extraFiles[fileName] = {
+            source: entry.source != null ? stringOrHastToString(entry.source) : null,
+          };
+        }
+      }
+    }
+
+    result[key] = {
+      ...variant,
+      source,
+      ...(extraFiles ? { extraFiles } : {}),
+    } as ControlledCode[string];
+  }
+  return result;
 }
 
 /**
- * Hook for managing source code editing functionality
+ * 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 {
+    (source: string, fileName?: string) => {
+      if (!contextSetCode) {
         console.warn(
           'setCode is not available in the current context. Ensure you are using CodeControllerContext.',
         );
+        return;
       }
+
+      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) {
+          newCode[selectedVariantKey] = {
+            ...variant,
+            source,
+          };
+        } else if (effectiveFileName) {
+          newCode[selectedVariantKey] = {
+            ...variant,
+            extraFiles: {
+              ...variant.extraFiles,
+              [effectiveFileName]: { source },
+            },
+          };
+        }
+
+        return newCode;
+      });
     },
     [contextSetCode, selectedVariantKey, effectiveCode, selectedVariant],
   );
 
+  const isEditable = !disabled && Boolean(contextSetCode) && Boolean(selectedVariant);
+
   return {
-    setSource: contextSetCode ? setSource : undefined,
+    setSource: isEditable ? setSource : undefined,
   };
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 850a51fda..69a208fe4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -784,6 +784,9 @@ 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.4)
       vscode-oniguruma:
         specifier: ^2.0.1
         version: 2.0.1

From 2ba514b62703b440003aad6230dcef738b22e187 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 20 Mar 2026 00:05:50 -0400
Subject: [PATCH 02/45] Integrate enhancers in CodeProvider and
 CodeControllerContext

---
 .../CodeControllerContext.tsx                 |   8 +-
 .../src/CodeProvider/CodeProvider.tsx         |   5 +-
 packages/docs-infra/src/useCode/useCode.ts    |  21 +-
 .../src/useCode/useSourceEnhancing.test.ts    | 575 ++++++++++++++++++
 .../src/useCode/useSourceEnhancing.ts         | 192 ++++--
 5 files changed, 735 insertions(+), 66 deletions(-)
 create mode 100644 packages/docs-infra/src/useCode/useSourceEnhancing.test.ts

diff --git a/packages/docs-infra/src/CodeControllerContext/CodeControllerContext.tsx b/packages/docs-infra/src/CodeControllerContext/CodeControllerContext.tsx
index 2cd826644..021dc757d 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>(
diff --git a/packages/docs-infra/src/CodeProvider/CodeProvider.tsx b/packages/docs-infra/src/CodeProvider/CodeProvider.tsx
index 9ad2c0f41..c87675d05 100644
--- a/packages/docs-infra/src/CodeProvider/CodeProvider.tsx
+++ b/packages/docs-infra/src/CodeProvider/CodeProvider.tsx
@@ -10,6 +10,7 @@ import type {
   ParseSource,
   SourceEnhancers,
 } from '../CodeHighlighter/types';
+import { enhanceCodeEmphasis } from '../pipeline/enhanceCodeEmphasis';
 import { extensionMap, grammars } from '../pipeline/parseSource/grammars';
 import { starryNightGutter } from '../pipeline/parseSource/addLineGutters';
 // Import the heavy functions
@@ -22,12 +23,14 @@ import {
   getAvailableTransforms,
 } from '../pipeline/loadCodeVariant/computeHastDeltas';
 
+const DEFAULT_SOURCE_ENHANCERS: SourceEnhancers = [enhanceCodeEmphasis];
+
 export function CodeProvider({
   children,
   loadCodeMeta,
   loadVariantMeta,
   loadSource,
-  sourceEnhancers,
+  sourceEnhancers = DEFAULT_SOURCE_ENHANCERS,
 }: {
   children: React.ReactNode;
   loadCodeMeta?: LoadCodeMeta;
diff --git a/packages/docs-infra/src/useCode/useCode.ts b/packages/docs-infra/src/useCode/useCode.ts
index 99aa4df3a..bb8f9783e 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';
@@ -88,6 +90,23 @@ export function useCode<T extends {} = {}>(
 
   // 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(() => {
@@ -175,7 +194,7 @@ export function useCode<T extends {} = {}>(
     saveHashVariantToLocalStorage,
     saveVariantToLocalStorage: variantSelection.saveVariantToLocalStorage,
     hashVariant: variantSelection.hashVariant,
-    sourceEnhancers,
+    sourceEnhancers: mergedEnhancers,
   });
 
   // Sub-hook: Copy Functionality
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..51f9f16d9
--- /dev/null
+++ b/packages/docs-infra/src/useCode/useSourceEnhancing.test.ts
@@ -0,0 +1,575 @@
+/**
+ * @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 768d5b61c..e5e1267b6 100644
--- a/packages/docs-infra/src/useCode/useSourceEnhancing.ts
+++ b/packages/docs-infra/src/useCode/useSourceEnhancing.ts
@@ -4,12 +4,7 @@ import * as React from 'react';
 import type { Root as HastRoot } from 'hast';
 import { decompressSync, strFromU8 } from 'fflate';
 import { decode } from 'uint8-to-base64';
-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.
@@ -54,30 +49,61 @@ 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 {
   /** The source to enhance (from transformed files or variant) */
   source: VariantSource | null | undefined;
@@ -132,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,
@@ -141,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,
   };
 }

From 7c87a7b246431a9ceab2851ac36c3237e27c53aa Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 20 Mar 2026 01:15:25 -0400
Subject: [PATCH 03/45] Improve comment handling when editing source

---
 .../CodeHighlighter/parseControlledCode.ts    |  13 +-
 .../docs-infra/src/CodeHighlighter/types.ts   |  15 +-
 .../src/useCode/useSourceEditing.test.ts      | 591 +++++++++++++++++-
 .../src/useCode/useSourceEditing.ts           | 168 ++++-
 4 files changed, 780 insertions(+), 7 deletions(-)

diff --git a/packages/docs-infra/src/CodeHighlighter/parseControlledCode.ts b/packages/docs-infra/src/CodeHighlighter/parseControlledCode.ts
index fd3833d31..72180a5d5 100644
--- a/packages/docs-infra/src/CodeHighlighter/parseControlledCode.ts
+++ b/packages/docs-infra/src/CodeHighlighter/parseControlledCode.ts
@@ -60,14 +60,20 @@ export function parseControlledCode(
             // Parse string sources
             try {
               const parsedSource = parseSource(fileSourceToProcess, fileName);
-              parsedExtraFiles[fileName] = { source: parsedSource };
+              parsedExtraFiles[fileName] = { source: parsedSource, comments: fileData.comments };
             } catch (error) {
               // Keep original if parsing fails
-              parsedExtraFiles[fileName] = { source: fileSourceToProcess };
+              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 +86,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 5114b9355..be50ff317 100644
--- a/packages/docs-infra/src/CodeHighlighter/types.ts
+++ b/packages/docs-infra/src/CodeHighlighter/types.ts
@@ -85,14 +85,27 @@ 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;
+  };
 };
 export type ControlledVariantCode = CodeMeta & {
   url?: string;
   source?: string | null;
   extraFiles?: ControlledVariantExtraFiles;
   filesOrder?: string[];
+  comments?: SourceComments;
+  collapseMap?: CollapseMap;
 };
 export type ControlledCode = { [key: string]: undefined | null | ControlledVariantCode };
 
diff --git a/packages/docs-infra/src/useCode/useSourceEditing.test.ts b/packages/docs-infra/src/useCode/useSourceEditing.test.ts
index 9b523f9ca..cbd92d412 100644
--- a/packages/docs-infra/src/useCode/useSourceEditing.test.ts
+++ b/packages/docs-infra/src/useCode/useSourceEditing.test.ts
@@ -3,8 +3,9 @@
  */
 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 } from '../CodeHighlighter/types';
+import type { Code, ControlledCode, VariantCode, SourceComments } from '../CodeHighlighter/types';
 import type { CodeHighlighterContextType } from '../CodeHighlighter/CodeHighlighterContext';
 
 function createContext(
@@ -17,6 +18,10 @@ function createContext(
   };
 }
 
+function pos(line: number): Position {
+  return { position: 0, extent: 0, content: '', line };
+}
+
 /**
  * Captures the ControlledCode produced by setSource by intercepting the
  * setState updater function passed to context.setCode.
@@ -278,4 +283,588 @@ describe('useSourceEditing', () => {
       expect(afterSecond!.Default!.extraFiles!['styles.css']).toEqual({ source: 'new css' });
     });
   });
+
+  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('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();
+    });
+  });
 });
diff --git a/packages/docs-infra/src/useCode/useSourceEditing.ts b/packages/docs-infra/src/useCode/useSourceEditing.ts
index 4787c325a..1cd36b7e7 100644
--- a/packages/docs-infra/src/useCode/useSourceEditing.ts
+++ b/packages/docs-infra/src/useCode/useSourceEditing.ts
@@ -2,8 +2,10 @@ import * as React from 'react';
 import type { Position } from 'use-editable';
 import type {
   Code,
+  CollapseMap,
   ControlledCode,
   ControlledVariantExtraFiles,
+  SourceComments,
   VariantCode,
 } from '../CodeHighlighter/types';
 import type { CodeHighlighterContextType } from '../CodeHighlighter/CodeHighlighterContext';
@@ -23,6 +25,147 @@ export interface UseSourceEditingResult {
   setSource?: (source: string, fileName?: string, position?: Position) => void;
 }
 
+interface ShiftResult {
+  comments: SourceComments | undefined;
+  collapseMap: CollapseMap | undefined;
+}
+
+/**
+ * Shifts 1-indexed comment line numbers after a source edit.
+ * Uses the cursor position (0-indexed in new text) and line count delta
+ * 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).
+ */
+function shiftComments(
+  comments: SourceComments | undefined,
+  oldSource: string | null | undefined,
+  newSource: string,
+  position: Position,
+  existingCollapseMap: CollapseMap | undefined,
+): ShiftResult {
+  if (!comments || Object.keys(comments).length === 0) {
+    return { comments, collapseMap: existingCollapseMap };
+  }
+
+  const oldLineCount = oldSource != null ? oldSource.split('\n').length : 0;
+  const newLineCount = newSource.split('\n').length;
+  const lineDelta = newLineCount - oldLineCount;
+
+  if (lineDelta === 0) {
+    return { comments, collapseMap: existingCollapseMap };
+  }
+
+  // position.line is 0-indexed in the new text.
+  // Convert to the 1-indexed line in old text that the cursor was on:
+  // For additions (lineDelta > 0): cursor moved down, old line = position.line - lineDelta
+  // For deletions (lineDelta < 0): cursor stayed, old line = position.line
+  const editLine = 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];
+    }
+  }
+
+  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.
+      const regular = commentArr.filter((c) => !c.endsWith('-end'));
+      const boundary = commentArr.filter((c) => c.endsWith('-end'));
+
+      if (regular.length > 0) {
+        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.
@@ -47,6 +190,7 @@ function toControlledCode(code: Code): ControlledCode {
         } else {
           extraFiles[fileName] = {
             source: entry.source != null ? stringOrHastToString(entry.source) : null,
+            ...(entry.comments ? { comments: entry.comments } : {}),
           };
         }
       }
@@ -78,7 +222,7 @@ export function useSourceEditing({
   const contextSetCode = context?.setCode;
 
   const setSource = React.useCallback(
-    (source: string, fileName?: string) => {
+    (source: string, fileName?: string, position?: Position) => {
       if (!contextSetCode) {
         console.warn(
           'setCode is not available in the current context. Ensure you are using CodeControllerContext.',
@@ -100,16 +244,36 @@ export function useSourceEditing({
         const isMainFile = effectiveFileName === selectedVariant?.fileName;
 
         if (isMainFile) {
+          const { comments: shiftedComments, collapseMap: newCollapseMap } = position
+            ? shiftComments(variant.comments, variant.source, source, position, variant.collapseMap)
+            : { comments: undefined, collapseMap: undefined };
           newCode[selectedVariantKey] = {
             ...variant,
             source,
+            comments: shiftedComments,
+            collapseMap: newCollapseMap,
           };
         } else if (effectiveFileName) {
+          const extraEntry = variant.extraFiles?.[effectiveFileName];
+          const { comments: shiftedComments, collapseMap: newCollapseMap } = position
+            ? shiftComments(
+                extraEntry?.comments,
+                extraEntry?.source,
+                source,
+                position,
+                extraEntry?.collapseMap,
+              )
+            : { comments: undefined, collapseMap: undefined };
           newCode[selectedVariantKey] = {
             ...variant,
             extraFiles: {
               ...variant.extraFiles,
-              [effectiveFileName]: { source },
+              [effectiveFileName]: {
+                ...extraEntry,
+                source,
+                comments: shiftedComments,
+                collapseMap: newCollapseMap,
+              },
             },
           };
         }

From f1841bc1f1e7573292a642b2d9e3e10a02d072b8 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 20 Mar 2026 01:15:46 -0400
Subject: [PATCH 04/45] Add highlighted section to editing demo

---
 .../demos/demo-live/DemoLiveContent.module.css           | 9 +++++++++
 .../demos/demo-live/demo-basic/CheckboxBasic.tsx         | 2 ++
 2 files changed, 11 insertions(+)

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 6507f1bed..2cb08accd 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
@@ -74,3 +74,12 @@
 .codeBlock:focus-visible {
   outline: none;
 }
+
+.codeBlock :global(.frame) {
+  display: block;
+}
+
+.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/demo-basic/CheckboxBasic.tsx b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/demo-basic/CheckboxBasic.tsx
index 5f008e747..1c24bde32 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/demo-basic/CheckboxBasic.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/demo-basic/CheckboxBasic.tsx
@@ -4,8 +4,10 @@ import { Checkbox } from '@/components/Checkbox';
 export default function CheckboxBasic() {
   return (
     <div>
+      {/* @highlight-start */}
       <Checkbox defaultChecked />
       <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>
+      {/* @highlight-end */}
     </div>
   );
 }

From 7b7ebb14e637b8da24dabd8bb8aa321c6ca6b6eb Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 20 Mar 2026 01:16:46 -0400
Subject: [PATCH 05/45] Prettier

---
 .../src/useCode/useSourceEnhancing.test.ts       | 16 ++++------------
 .../docs-infra/src/useCode/useSourceEnhancing.ts |  9 +++++----
 2 files changed, 9 insertions(+), 16 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useSourceEnhancing.test.ts b/packages/docs-infra/src/useCode/useSourceEnhancing.test.ts
index 51f9f16d9..37293798e 100644
--- a/packages/docs-infra/src/useCode/useSourceEnhancing.test.ts
+++ b/packages/docs-infra/src/useCode/useSourceEnhancing.test.ts
@@ -203,9 +203,7 @@ describe('useSourceEnhancing', () => {
     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 enhancer = vi.fn((root: HastRoot) => makeHast(`enhanced-${textOf(root)}`));
       const enhancers: SourceEnhancer[] = [enhancer];
 
       const { result, rerender } = renderHook(
@@ -369,9 +367,7 @@ describe('useSourceEnhancing', () => {
     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 syncAfter = vi.fn<SourceEnhancer>((root) => makeHast(`sync-after-${textOf(root)}`));
 
       const asyncEnhancer: SourceEnhancer = async (root) => {
         await new Promise((resolve) => {
@@ -398,9 +394,7 @@ describe('useSourceEnhancing', () => {
       expect(syncAfter).not.toHaveBeenCalled();
 
       await vi.waitFor(() => {
-        expect(textOf(result.current.enhancedSource)).toBe(
-          'sync-after-async-sync-before',
-        );
+        expect(textOf(result.current.enhancedSource)).toBe('sync-after-async-sync-before');
       });
 
       // syncBefore was NOT re-run for the async path
@@ -464,9 +458,7 @@ describe('useSourceEnhancing', () => {
     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 enhancer = vi.fn((root: HastRoot) => makeHast(`enhanced-${textOf(root)}`));
 
       const { result } = renderHook(() =>
         useSourceEnhancing({
diff --git a/packages/docs-infra/src/useCode/useSourceEnhancing.ts b/packages/docs-infra/src/useCode/useSourceEnhancing.ts
index e5e1267b6..37cf167dd 100644
--- a/packages/docs-infra/src/useCode/useSourceEnhancing.ts
+++ b/packages/docs-infra/src/useCode/useSourceEnhancing.ts
@@ -59,10 +59,11 @@ async function applyEnhancersFrom(
   enhancers: SourceEnhancers,
   startIndex: number,
 ): Promise<HastRoot> {
-  return enhancers.slice(startIndex).reduce<Promise<HastRoot>>(
-    (prev, enhancer) => prev.then((current) => enhancer(current, comments, fileName)),
-    Promise.resolve(source),
-  );
+  return enhancers
+    .slice(startIndex)
+    .reduce<
+      Promise<HastRoot>
+    >((prev, enhancer) => prev.then((current) => enhancer(current, comments, fileName)), Promise.resolve(source));
 }
 
 interface SyncEnhanceResult {

From 8998ead9a020cf868e095f468966558526619496 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 20 Mar 2026 01:46:09 -0400
Subject: [PATCH 06/45] Update docs

---
 .../components/code-controller-context/page.mdx     | 13 ++++++++++++-
 .../docs-infra/components/code-provider/page.mdx    |  4 ++++
 docs/app/docs-infra/hooks/use-code/page.mdx         |  3 ++-
 docs/app/docs-infra/hooks/use-demo/page.mdx         |  2 +-
 4 files changed, 19 insertions(+), 3 deletions(-)

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 a5920b4cb..de114c757 100644
--- a/docs/app/docs-infra/components/code-controller-context/page.mdx
+++ b/docs/app/docs-infra/components/code-controller-context/page.mdx
@@ -327,6 +327,9 @@ interface CodeControllerContext {
 
   // Override components for live previews
   components?: Record<string, React.ReactNode>;
+
+  // Additional source enhancers merged with enhancers from CodeProvider and useCode opts
+  sourceEnhancers?: SourceEnhancers;
 }
 ```
 
@@ -367,9 +370,17 @@ type ControlledVariantCode = {
   url: string;
   fileName: string;
   source?: string | null;
-  extraFiles?: Record<string, { source: string | null }>;
+  extraFiles?: Record<string, { source: string | null; comments?: SourceComments; collapseMap?: CollapseMap }>;
   filesOrder?: string[];
+  comments?: SourceComments;
+  collapseMap?: CollapseMap;
 };
+
+// Comments extracted from source code, keyed by 1-indexed line number
+type SourceComments = Record<number, string[]>;
+
+// Tracks comments collapsed onto a line when their original lines were deleted
+type CollapseMap = Record<number, Array<{ offset: number; comments: string[] }>>;
 ```
 
 ## Requirements
diff --git a/docs/app/docs-infra/components/code-provider/page.mdx b/docs/app/docs-infra/components/code-provider/page.mdx
index 8edbedf52..878390b04 100644
--- a/docs/app/docs-infra/components/code-provider/page.mdx
+++ b/docs/app/docs-infra/components/code-provider/page.mdx
@@ -112,6 +112,7 @@ The `CodeProvider` component accepts the following props:
 - `loadCodeMeta` (LoadCodeMeta): Function to load code metadata from a URL
 - `loadVariantMeta` (LoadVariantMeta): Function to load variant-specific metadata
 - `loadSource` (LoadSource): Function to load source code and extra files
+- `sourceEnhancers` (SourceEnhancers): Array of enhancer functions applied to parsed HAST sources. Defaults to `[enhanceCodeEmphasis]`. These are merged with any enhancers from `CodeControllerContext` and `useCode` opts.
 
 ### Context Functions
 
@@ -128,6 +129,9 @@ interface CodeContext {
   // Source transformers for code transformation
   sourceTransformers?: SourceTransformers;
 
+  // Source enhancers applied to parsed HAST (defaults to [enhanceCodeEmphasis])
+  sourceEnhancers?: SourceEnhancers;
+
   // Custom loading functions
   loadSource?: LoadSource;
   loadVariantMeta?: LoadVariantMeta;
diff --git a/docs/app/docs-infra/hooks/use-code/page.mdx b/docs/app/docs-infra/hooks/use-code/page.mdx
index b3ecbe3d4..43e2b9318 100644
--- a/docs/app/docs-infra/hooks/use-code/page.mdx
+++ b/docs/app/docs-infra/hooks/use-code/page.mdx
@@ -98,6 +98,7 @@ interface UseCodeOpts {
   fileHashMode?: 'remove-hash' | 'remove-filename'; // Controls hash removal on user interaction
   saveHashVariantToLocalStorage?: 'on-load' | 'on-interaction' | 'never'; // When to persist hash variant
   sourceEnhancers?: SourceEnhancers; // Functions to enhance parsed HAST sources
+  disabled?: boolean; // Disables editing even when a CodeControllerContext is present
 }
 ```
 
@@ -139,7 +140,7 @@ The hook returns a `code` object with the following properties:
 
 #### Source Editing
 
-- **`setSource?: (source: string) => void`** - Function to update source code (when available)
+- **`setSource?: (source: string, fileName?: string, position?: Position) => void`** - Function to update source code (when available). The `position` parameter tracks the cursor position for comment shifting during live edits.
 
 #### User Properties
 
diff --git a/docs/app/docs-infra/hooks/use-demo/page.mdx b/docs/app/docs-infra/hooks/use-demo/page.mdx
index dab05bae7..d5327f914 100644
--- a/docs/app/docs-infra/hooks/use-demo/page.mdx
+++ b/docs/app/docs-infra/hooks/use-demo/page.mdx
@@ -270,7 +270,7 @@ All properties from `useCode` are available with exact types:
 - **`expanded: boolean`**, **`expand: () => void`**, **`setExpanded: React.Dispatch<React.SetStateAction<boolean>>`**
 - **`copy: (event: React.MouseEvent<HTMLButtonElement>) => Promise<void>`**
 - **`availableTransforms: string[]`**, **`selectedTransform: string | null | undefined`**, **`selectTransform: (transformName: string | null) => void`**
-- **`setSource?: (source: string) => void`** (when editing is available)
+- **`setSource?: (source: string, fileName?: string, position?: Position) => void`** (when editing is available)
 - **`userProps: UserProps<T>`** - Generated user properties including name, slug, and custom props
 
 See [useCode documentation](../use-code/page.mdx) for detailed information about inherited functionality.

From ae72b05ba070b7a24e2055bed8a9fdd88d19dfa5 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 20 Mar 2026 08:59:38 -0400
Subject: [PATCH 07/45] prettier

---
 .../docs-infra/components/code-controller-context/page.mdx   | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

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 de114c757..e4c3efd30 100644
--- a/docs/app/docs-infra/components/code-controller-context/page.mdx
+++ b/docs/app/docs-infra/components/code-controller-context/page.mdx
@@ -370,7 +370,10 @@ type ControlledVariantCode = {
   url: string;
   fileName: string;
   source?: string | null;
-  extraFiles?: Record<string, { source: string | null; comments?: SourceComments; collapseMap?: CollapseMap }>;
+  extraFiles?: Record<
+    string,
+    { source: string | null; comments?: SourceComments; collapseMap?: CollapseMap }
+  >;
   filesOrder?: string[];
   comments?: SourceComments;
   collapseMap?: CollapseMap;

From 70b2a3e12060ed38f862e27e7cbe38c6e5d1b763 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 24 Mar 2026 16:03:52 -0400
Subject: [PATCH 08/45] Fork useEditable()

---
 .../docs-infra/src/useCode/useEditable.ts     | 507 ++++++++++++++++++
 1 file changed, 507 insertions(+)
 create mode 100644 packages/docs-infra/src/useCode/useEditable.ts

diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
new file mode 100644
index 000000000..71bae84b0
--- /dev/null
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -0,0 +1,507 @@
+/*
+
+MIT License
+
+Copyright (c) 2020 Phil Plückthun,
+Copyright (c) 2021 Formidable
+
+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:
+// - Fix linting and formatting
+
+import { useState, useLayoutEffect, useMemo } from 'react';
+
+export interface Position {
+  position: number;
+  extent: number;
+  content: string;
+  line: number;
+}
+
+type History = [Position, string];
+
+const observerSettings = {
+  characterData: true,
+  characterDataOldValue: true,
+  childList: true,
+  subtree: true,
+};
+
+const getCurrentRange = () => window.getSelection()!.getRangeAt(0)!;
+
+const setCurrentRange = (range: Range) => {
+  const selection = window.getSelection()!;
+  selection.empty();
+  selection.addRange(range);
+};
+
+const isUndoRedoKey = (event: KeyboardEvent): boolean =>
+  (event.metaKey || event.ctrlKey) && !event.altKey && event.code === 'KeyZ';
+
+const toString = (element: HTMLElement): string => {
+  const queue: Node[] = [element.firstChild!];
+
+  let content = '';
+  let node: Node;
+  while ((node = queue.pop()!)) {
+    if (node.nodeType === Node.TEXT_NODE) {
+      content += node.textContent;
+    } else if (node.nodeType === Node.ELEMENT_NODE && node.nodeName === 'BR') {
+      content += '\n';
+    }
+
+    if (node.nextSibling) queue.push(node.nextSibling);
+    if (node.firstChild) queue.push(node.firstChild);
+  }
+
+  // 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') content += '\n';
+
+  return content;
+};
+
+const setStart = (range: Range, node: Node, offset: number) => {
+  if (offset < node.textContent!.length) {
+    range.setStart(node, offset);
+  } else {
+    range.setStartAfter(node);
+  }
+};
+
+const setEnd = (range: Range, node: Node, offset: number) => {
+  if (offset < node.textContent!.length) {
+    range.setEnd(node, offset);
+  } else {
+    range.setEndAfter(node);
+  }
+};
+
+const getPosition = (element: HTMLElement): Position => {
+  // Firefox Quirk: Since plaintext-only is unsupported the position
+  // of the text here is retrieved via a range, rather than traversal
+  // as seen in makeRange()
+  const range = getCurrentRange();
+  const extent = !range.collapsed ? range.toString().length : 0;
+  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 };
+};
+
+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 queue: Node[] = [element.firstChild!];
+  let current = 0;
+
+  let node: Node;
+  let position = start;
+  while ((node = queue[queue.length - 1])) {
+    if (node.nodeType === Node.TEXT_NODE) {
+      const length = node.textContent!.length;
+      if (current + length >= position) {
+        const offset = position - current;
+        if (position === start) {
+          setStart(range, node, offset);
+          if (end !== start) {
+            position = end;
+            continue;
+          } else {
+            break;
+          }
+        } else {
+          setEnd(range, node, offset);
+          break;
+        }
+      }
+
+      current += node.textContent!.length;
+    } else if (node.nodeType === Node.ELEMENT_NODE && node.nodeName === 'BR') {
+      if (current + 1 >= position) {
+        if (position === start) {
+          setStart(range, node, 0);
+          if (end !== start) {
+            position = end;
+            continue;
+          } else {
+            break;
+          }
+        } else {
+          setEnd(range, node, 0);
+          break;
+        }
+      }
+
+      current++;
+    }
+
+    queue.pop();
+    if (node.nextSibling) queue.push(node.nextSibling);
+    if (node.firstChild) queue.push(node.firstChild);
+  }
+
+  return range;
+};
+
+interface State {
+  observer: MutationObserver;
+  disconnected: boolean;
+  onChange(text: string, position: Position): void;
+  queue: MutationRecord[];
+  history: History[];
+  historyAt: number;
+  position: Position | null;
+}
+
+export interface Options {
+  disabled?: boolean;
+  indentation?: number;
+}
+
+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 = (
+  elementRef: { current: HTMLElement | undefined | null },
+  onChange: (text: string, position: Position) => void,
+  opts?: Options,
+): Edit => {
+  if (!opts) opts = {};
+
+  const unblock = useState([])[1];
+  const state: State = useState(() => {
+    const state: State = {
+      observer: null as any,
+      disconnected: false,
+      onChange,
+      queue: [],
+      history: [],
+      historyAt: -1,
+      position: null,
+    };
+
+    if (typeof MutationObserver !== 'undefined') {
+      state.observer = new MutationObserver((batch) => {
+        state.queue.push(...batch);
+      });
+    }
+
+    return state;
+  })[0];
+
+  const edit = useMemo<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);
+          range.deleteContents();
+          if (append) range.insertNode(document.createTextNode(append));
+          setCurrentRange(makeRange(element, start + append.length));
+        }
+      },
+      move(pos: number | { row: number; column: number }) {
+        const { current: element } = elementRef;
+        if (element) {
+          element.focus();
+          let position = 0;
+          if (typeof pos === 'number') {
+            position = pos;
+          } else {
+            const lines = toString(element).split('\n').slice(0, pos.row);
+            if (pos.row) position += lines.join('\n').length + 1;
+            position += pos.column;
+          }
+
+          setCurrentRange(makeRange(element, position));
+        }
+      },
+      getState() {
+        const { current: element } = elementRef;
+        const text = toString(element!);
+        const position = getPosition(element!);
+        return { text, position };
+      },
+    }),
+    [],
+  );
+
+  // Only for SSR / server-side logic
+  if (typeof navigator !== 'object') return edit;
+
+  useLayoutEffect(() => {
+    state.onChange = onChange;
+
+    if (!elementRef.current || opts!.disabled) return;
+
+    state.disconnected = false;
+    state.observer.observe(elementRef.current, observerSettings);
+    if (state.position) {
+      const { position, extent } = state.position;
+      setCurrentRange(makeRange(elementRef.current, position, position + extent));
+    }
+
+    return () => {
+      state.observer.disconnect();
+    };
+  });
+
+  useLayoutEffect(() => {
+    if (!elementRef.current || opts!.disabled) {
+      state.history.length = 0;
+      state.historyAt = -1;
+      return;
+    }
+
+    const element = elementRef.current!;
+    if (state.position) {
+      element.focus();
+      const { position, extent } = state.position;
+      setCurrentRange(makeRange(element, position, position + extent));
+    }
+
+    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 (opts!.indentation) {
+      element.style.tabSize = (element.style as any).MozTabSize = '' + opts!.indentation;
+    }
+
+    const indentPattern = `${' '.repeat(opts!.indentation || 0)}`;
+    const indentRe = new RegExp(`^(?:${indentPattern})`);
+    const blanklineRe = new RegExp(`^(?:${indentPattern})*(${indentPattern})$`);
+
+    let _trackStateTimestamp: number;
+    const trackState = (ignoreTimestamp?: boolean) => {
+      if (!elementRef.current || !state.position) return;
+
+      const content = toString(element);
+      const position = 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;
+      }
+
+      const at = ++state.historyAt;
+      state.history[at] = [position, content];
+      state.history.splice(at + 1);
+      if (at > 500) {
+        state.historyAt--;
+        state.history.shift();
+      }
+    };
+
+    const disconnect = () => {
+      state.observer.disconnect();
+      state.disconnected = true;
+    };
+
+    const flushChanges = () => {
+      state.queue.push(...state.observer.takeRecords());
+      const position = getPosition(element);
+      if (state.queue.length) {
+        disconnect();
+        const content = toString(element);
+        state.position = position;
+        let mutation: MutationRecord | void;
+        let i = 0;
+        while ((mutation = state.queue.pop())) {
+          if (mutation.oldValue !== null) mutation.target.textContent = mutation.oldValue;
+          for (i = mutation.removedNodes.length - 1; i >= 0; i--)
+            mutation.target.insertBefore(mutation.removedNodes[i], mutation.nextSibling);
+          for (i = mutation.addedNodes.length - 1; i >= 0; i--)
+            if (mutation.addedNodes[i].parentNode)
+              mutation.target.removeChild(mutation.addedNodes[i]);
+        }
+
+        state.onChange(content, position);
+      }
+    };
+
+    const onKeyDown = (event: HTMLElementEventMap['keydown']) => {
+      if (event.defaultPrevented || event.target !== element) {
+        return;
+      } else if (state.disconnected) {
+        // React Quirk: It's expected that we may lose events while disconnected, which is why
+        // we'd like to block some inputs if they're unusually fast. However, this always
+        // coincides with React not executing the update immediately and then getting stuck,
+        // which can be prevented by issuing a dummy state change.
+        event.preventDefault();
+        return unblock([]);
+      }
+
+      if (isUndoRedoKey(event)) {
+        event.preventDefault();
+
+        let history: History;
+        if (!event.shiftKey) {
+          const at = --state.historyAt;
+          history = state.history[at];
+          if (!history) state.historyAt = 0;
+        } else {
+          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;
+      } else {
+        trackState();
+      }
+
+      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 || opts!.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 match = blanklineRe.exec(position.content);
+          edit.insert('', match ? -match[1].length : -1);
+        }
+      } else if (opts!.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) +
+            (opts!.indentation ? ' '.repeat(opts!.indentation) : '\t') +
+            content.slice(start);
+        edit.update(newContent);
+      }
+
+      // Flush changes as a key is held so the app can catch up
+      if (event.repeat) flushChanges();
+    };
+
+    const onKeyUp = (event: HTMLElementEventMap['keyup']) => {
+      if (event.defaultPrevented || event.isComposing) return;
+      if (!isUndoRedoKey(event)) trackState();
+      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
+      state.position =
+        window.getSelection()!.rangeCount && event.target === element ? getPosition(element) : null;
+    };
+
+    const onPaste = (event: HTMLElementEventMap['paste']) => {
+      event.preventDefault();
+      trackState(true);
+      edit.insert(event.clipboardData!.getData('text/plain'));
+      trackState(true);
+      flushChanges();
+    };
+
+    document.addEventListener('selectstart', onSelect);
+    window.addEventListener('keydown', onKeyDown);
+    element.addEventListener('paste', onPaste);
+    element.addEventListener('keyup', onKeyUp);
+
+    return () => {
+      document.removeEventListener('selectstart', onSelect);
+      window.removeEventListener('keydown', onKeyDown);
+      element.removeEventListener('paste', onPaste);
+      element.removeEventListener('keyup', onKeyUp);
+      element.style.whiteSpace = prevWhiteSpace;
+      element.contentEditable = prevContentEditable;
+    };
+  }, [elementRef.current!, opts!.disabled, opts!.indentation]);
+
+  return edit;
+};

From 29a1267f585b0896b10ce6dd549848798fe78c0d Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 24 Mar 2026 16:04:23 -0400
Subject: [PATCH 09/45] Fix lint

---
 .../docs-infra/src/useCode/useEditable.ts     | 173 ++++++++++++------
 1 file changed, 116 insertions(+), 57 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 71bae84b0..5b4297c74 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -4,6 +4,7 @@ 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
@@ -29,7 +30,7 @@ SOFTWARE.
 // Changes:
 // - Fix linting and formatting
 
-import { useState, useLayoutEffect, useMemo } from 'react';
+import * as React from 'react';
 
 export interface Position {
   position: number;
@@ -62,21 +63,27 @@ const toString = (element: HTMLElement): string => {
   const queue: Node[] = [element.firstChild!];
 
   let content = '';
-  let node: Node;
-  while ((node = queue.pop()!)) {
+  while (queue.length > 0) {
+    const node = queue.pop()!;
     if (node.nodeType === Node.TEXT_NODE) {
       content += node.textContent;
     } else if (node.nodeType === Node.ELEMENT_NODE && node.nodeName === 'BR') {
       content += '\n';
     }
 
-    if (node.nextSibling) queue.push(node.nextSibling);
-    if (node.firstChild) queue.push(node.firstChild);
+    if (node.nextSibling) {
+      queue.push(node.nextSibling);
+    }
+    if (node.firstChild) {
+      queue.push(node.firstChild);
+    }
   }
 
   // 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') content += '\n';
+  if (content[content.length - 1] !== '\n') {
+    content += '\n';
+  }
 
   return content;
 };
@@ -115,16 +122,23 @@ const getPosition = (element: HTMLElement): Position => {
 };
 
 const makeRange = (element: HTMLElement, start: number, end?: number): Range => {
-  if (start <= 0) start = 0;
-  if (!end || end < 0) end = start;
+  if (start <= 0) {
+    start = 0;
+  }
+  if (!end || end < 0) {
+    end = start;
+  }
 
   const range = document.createRange();
   const queue: Node[] = [element.firstChild!];
   let current = 0;
 
-  let node: Node;
   let position = start;
-  while ((node = queue[queue.length - 1])) {
+  while (queue.length > 0) {
+    const node = queue[queue.length - 1];
+    if (!node) {
+      break;
+    }
     if (node.nodeType === Node.TEXT_NODE) {
       const length = node.textContent!.length;
       if (current + length >= position) {
@@ -160,12 +174,16 @@ const makeRange = (element: HTMLElement, start: number, end?: number): Range =>
         }
       }
 
-      current++;
+      current += 1;
     }
 
     queue.pop();
-    if (node.nextSibling) queue.push(node.nextSibling);
-    if (node.firstChild) queue.push(node.firstChild);
+    if (node.nextSibling) {
+      queue.push(node.nextSibling);
+    }
+    if (node.firstChild) {
+      queue.push(node.firstChild);
+    }
   }
 
   return range;
@@ -202,11 +220,13 @@ export const useEditable = (
   onChange: (text: string, position: Position) => void,
   opts?: Options,
 ): Edit => {
-  if (!opts) opts = {};
+  if (!opts) {
+    opts = {};
+  }
 
-  const unblock = useState([])[1];
-  const state: State = useState(() => {
-    const state: State = {
+  const unblock = React.useState([])[1];
+  const state: State = React.useState(() => {
+    const initialState: State = {
       observer: null as any,
       disconnected: false,
       onChange,
@@ -217,15 +237,15 @@ export const useEditable = (
     };
 
     if (typeof MutationObserver !== 'undefined') {
-      state.observer = new MutationObserver((batch) => {
-        state.queue.push(...batch);
+      initialState.observer = new MutationObserver((batch) => {
+        initialState.queue.push(...batch);
       });
     }
 
-    return state;
+    return initialState;
   })[0];
 
-  const edit = useMemo<Edit>(
+  const edit = React.useMemo<Edit>(
     () => ({
       update(content: string) {
         const { current: element } = elementRef;
@@ -249,7 +269,9 @@ export const useEditable = (
           const end = position.position + (offset > 0 ? offset : 0);
           range = makeRange(element, start, end);
           range.deleteContents();
-          if (append) range.insertNode(document.createTextNode(append));
+          if (append) {
+            range.insertNode(document.createTextNode(append));
+          }
           setCurrentRange(makeRange(element, start + append.length));
         }
       },
@@ -262,7 +284,9 @@ export const useEditable = (
             position = pos;
           } else {
             const lines = toString(element).split('\n').slice(0, pos.row);
-            if (pos.row) position += lines.join('\n').length + 1;
+            if (pos.row) {
+              position += lines.join('\n').length + 1;
+            }
             position += pos.column;
           }
 
@@ -276,16 +300,21 @@ export const useEditable = (
         return { text, position };
       },
     }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
     [],
   );
 
-  // Only for SSR / server-side logic
-  if (typeof navigator !== 'object') return edit;
+  React.useLayoutEffect(() => {
+    // Only for SSR / server-side logic
+    if (typeof navigator !== 'object') {
+      return undefined;
+    }
 
-  useLayoutEffect(() => {
     state.onChange = onChange;
 
-    if (!elementRef.current || opts!.disabled) return;
+    if (!elementRef.current || opts!.disabled) {
+      return undefined;
+    }
 
     state.disconnected = false;
     state.observer.observe(elementRef.current, observerSettings);
@@ -299,11 +328,15 @@ export const useEditable = (
     };
   });
 
-  useLayoutEffect(() => {
+  React.useLayoutEffect(() => {
+    if (typeof navigator !== 'object') {
+      return undefined;
+    }
+
     if (!elementRef.current || opts!.disabled) {
       state.history.length = 0;
       state.historyAt = -1;
-      return;
+      return undefined;
     }
 
     const element = elementRef.current!;
@@ -324,19 +357,25 @@ export const useEditable = (
       hasPlaintextSupport = false;
     }
 
-    if (prevWhiteSpace !== 'pre') element.style.whiteSpace = 'pre-wrap';
+    if (prevWhiteSpace !== 'pre') {
+      element.style.whiteSpace = 'pre-wrap';
+    }
 
     if (opts!.indentation) {
-      element.style.tabSize = (element.style as any).MozTabSize = '' + opts!.indentation;
+      const tabSizeValue = `${opts!.indentation}`;
+      (element.style as any).MozTabSize = tabSizeValue;
+      element.style.tabSize = tabSizeValue;
     }
 
     const indentPattern = `${' '.repeat(opts!.indentation || 0)}`;
     const indentRe = new RegExp(`^(?:${indentPattern})`);
     const blanklineRe = new RegExp(`^(?:${indentPattern})*(${indentPattern})$`);
 
-    let _trackStateTimestamp: number;
+    let trackStateTimestamp: number;
     const trackState = (ignoreTimestamp?: boolean) => {
-      if (!elementRef.current || !state.position) return;
+      if (!elementRef.current || !state.position) {
+        return;
+      }
 
       const content = toString(element);
       const position = getPosition(element);
@@ -345,18 +384,19 @@ export const useEditable = (
       // Prevent recording new state in list if last one has been new enough
       const lastEntry = state.history[state.historyAt];
       if (
-        (!ignoreTimestamp && timestamp - _trackStateTimestamp < 500) ||
+        (!ignoreTimestamp && timestamp - trackStateTimestamp < 500) ||
         (lastEntry && lastEntry[1] === content)
       ) {
-        _trackStateTimestamp = timestamp;
+        trackStateTimestamp = timestamp;
         return;
       }
 
-      const at = ++state.historyAt;
+      state.historyAt += 1;
+      const at = state.historyAt;
       state.history[at] = [position, content];
       state.history.splice(at + 1);
       if (at > 500) {
-        state.historyAt--;
+        state.historyAt -= 1;
         state.history.shift();
       }
     };
@@ -373,15 +413,19 @@ export const useEditable = (
         disconnect();
         const content = toString(element);
         state.position = position;
-        let mutation: MutationRecord | void;
-        let i = 0;
-        while ((mutation = state.queue.pop())) {
-          if (mutation.oldValue !== null) mutation.target.textContent = mutation.oldValue;
-          for (i = mutation.removedNodes.length - 1; i >= 0; i--)
+        while (state.queue.length > 0) {
+          const mutation = state.queue.pop()!;
+          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 (i = mutation.addedNodes.length - 1; i >= 0; i--)
-            if (mutation.addedNodes[i].parentNode)
+          }
+          for (let i = mutation.addedNodes.length - 1; i >= 0; i -= 1) {
+            if (mutation.addedNodes[i].parentNode) {
               mutation.target.removeChild(mutation.addedNodes[i]);
+            }
+          }
         }
 
         state.onChange(content, position);
@@ -391,13 +435,15 @@ export const useEditable = (
     const onKeyDown = (event: HTMLElementEventMap['keydown']) => {
       if (event.defaultPrevented || event.target !== element) {
         return;
-      } else if (state.disconnected) {
+      }
+      if (state.disconnected) {
         // React Quirk: It's expected that we may lose events while disconnected, which is why
         // we'd like to block some inputs if they're unusually fast. However, this always
         // coincides with React not executing the update immediately and then getting stuck,
         // which can be prevented by issuing a dummy state change.
         event.preventDefault();
-        return unblock([]);
+        unblock([]);
+        return;
       }
 
       if (isUndoRedoKey(event)) {
@@ -405,13 +451,19 @@ export const useEditable = (
 
         let history: History;
         if (!event.shiftKey) {
-          const at = --state.historyAt;
+          state.historyAt -= 1;
+          const at = state.historyAt;
           history = state.history[at];
-          if (!history) state.historyAt = 0;
+          if (!history) {
+            state.historyAt = 0;
+          }
         } else {
-          const at = ++state.historyAt;
+          state.historyAt += 1;
+          const at = state.historyAt;
           history = state.history[at];
-          if (!history) state.historyAt = state.history.length - 1;
+          if (!history) {
+            state.historyAt = state.history.length - 1;
+          }
         }
 
         if (history) {
@@ -420,10 +472,10 @@ export const useEditable = (
           state.onChange(history[1], history[0]);
         }
         return;
-      } else {
-        trackState();
       }
 
+      trackState();
+
       if (event.key === 'Enter') {
         event.preventDefault();
         // Firefox Quirk: Since plaintext-only is unsupported we must
@@ -433,7 +485,7 @@ export const useEditable = (
         // 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);
+        const text = `\n${position.content.slice(0, index)}`;
         edit.insert(text);
       } else if ((!hasPlaintextSupport || opts!.indentation) && event.key === 'Backspace') {
         // Firefox Quirk: Since plaintext-only is unsupported we must
@@ -463,12 +515,18 @@ export const useEditable = (
       }
 
       // Flush changes as a key is held so the app can catch up
-      if (event.repeat) flushChanges();
+      if (event.repeat) {
+        flushChanges();
+      }
     };
 
     const onKeyUp = (event: HTMLElementEventMap['keyup']) => {
-      if (event.defaultPrevented || event.isComposing) return;
-      if (!isUndoRedoKey(event)) trackState();
+      if (event.defaultPrevented || event.isComposing) {
+        return;
+      }
+      if (!isUndoRedoKey(event)) {
+        trackState();
+      }
       flushChanges();
       // Chrome Quirk: The contenteditable may lose focus after the first edit or so
       element.focus();
@@ -501,7 +559,8 @@ export const useEditable = (
       element.style.whiteSpace = prevWhiteSpace;
       element.contentEditable = prevContentEditable;
     };
-  }, [elementRef.current!, opts!.disabled, opts!.indentation]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [elementRef.current, opts?.disabled, opts?.indentation]);
 
   return edit;
 };

From 0b71a73757597cbe76339eb2d16522072603f3d6 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 24 Mar 2026 18:45:35 -0400
Subject: [PATCH 10/45] Add useEditable tests

---
 AGENTS.md                                     |   2 +
 .../docs-infra/overview/contributing/page.mdx |  24 +-
 package.json                                  |   3 +
 packages/docs-infra/package.json              |   3 +-
 packages/docs-infra/src/cli/index.ts          |   2 +
 packages/docs-infra/src/cli/runBrowser.ts     | 167 ++++
 .../src/useCode/useEditable.browser.ts        | 823 ++++++++++++++++++
 .../src/useCode/useEditable.test.ts           | 634 ++++++++++++++
 .../docs-infra/src/useCode/useEditable.ts     |   1 +
 pnpm-lock.yaml                                | 132 ++-
 vitest.config.browser.mts                     |  18 +
 11 files changed, 1785 insertions(+), 24 deletions(-)
 create mode 100644 packages/docs-infra/src/cli/runBrowser.ts
 create mode 100644 packages/docs-infra/src/useCode/useEditable.browser.ts
 create mode 100644 packages/docs-infra/src/useCode/useEditable.test.ts
 create mode 100644 vitest.config.browser.mts

diff --git a/AGENTS.md b/AGENTS.md
index cce4aa2d2..ffb529e68 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 (e.g. CI), run `pnpm test:browser:unconfined` directly — no container engine needed.
 - **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/docs-infra/overview/contributing/page.mdx b/docs/app/docs-infra/overview/contributing/page.mdx
index fe5258b18..7985cd568 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/package.json b/package.json
index b8aa63140..5c1458314 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 --script test:browser:unconfined --playwright-version 1.58.2 --",
+    "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",
@@ -82,6 +84,7 @@
   },
   "devDependencies": {
     "@babel/plugin-transform-react-constant-elements": "7.27.1",
+    "@vitest/browser-playwright": "4.1.0",
     "baseline-browser-mapping": "2.10.7",
     "eslint-plugin-n": "17.24.0",
     "markdownlint-cli2": "0.21.0",
diff --git a/packages/docs-infra/package.json b/packages/docs-infra/package.json
index 6181e1d10..7cfe97b1e 100644
--- a/packages/docs-infra/package.json
+++ b/packages/docs-infra/package.json
@@ -119,7 +119,8 @@
     "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",
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..22bef8743
--- /dev/null
+++ b/packages/docs-infra/src/cli/runBrowser.ts
@@ -0,0 +1,167 @@
+/* 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;
+  _: (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;
+
+  // 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`;
+
+    console.log(`Starting Playwright server on port ${port}…`);
+    await engine(
+      'run',
+      '--rm',
+      '-d',
+      '--name',
+      CONTAINER_NAME,
+      '--network=host',
+      '--shm-size=1g',
+      image,
+      'npx',
+      '--yes',
+      'playwright',
+      'run-server',
+      '--port',
+      String(port),
+      '--host',
+      '0.0.0.0',
+    );
+
+    // 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.
+    const positional = argv._.slice(1).map(String);
+    const passthrough = argv['--'] ?? [];
+    const extra = [...positional, ...passthrough];
+    const env = { ...process.env, PLAYWRIGHT_SERVER: `ws://localhost:${port}` };
+    await $({ env, stdio: 'inherit' })`pnpm -w 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,
+      })
+      .parserConfiguration({ 'populate--': true })
+      .strict(false);
+  },
+  handler,
+};
+
+export default runBrowser;
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..74e37fd02
--- /dev/null
+++ b/packages/docs-infra/src/useCode/useEditable.browser.ts
@@ -0,0 +1,823 @@
+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 walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
+  let current = 0;
+  while (walker.nextNode()) {
+    const node = walker.currentNode;
+    const len = node.textContent!.length;
+    if (current + len >= offset) {
+      const range = document.createRange();
+      range.setStart(node, offset - current);
+      range.collapse(true);
+      window.getSelection()!.removeAllRanges();
+      window.getSelection()!.addRange(range);
+      return;
+    }
+    current += len;
+  }
+}
+
+/**
+ * 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>;</span>\n',
+  '<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>;</span>\n',
+  '<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>() {</span>\n',
+  '<span class="line" data-ln="5">  <span class="pl-k">return</span> (</span>\n',
+  '<span class="line" data-ln="6">    &lt;<span class="pl-ent">div</span>&gt;</span>\n',
+  '</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;</span>\n',
+  '<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;</span>\n',
+  '</span>',
+  '<span class="frame" data-frame="2" data-lined="">',
+  '<span class="line" data-ln="9">    &lt;/<span class="pl-ent">div</span>&gt;</span>\n',
+  '<span class="line" data-ln="10">  );</span>\n',
+  '<span class="line" data-ln="11">}</span>\n',
+  '</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');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // 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;?$/);
+    });
+  });
+});
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..4ffa1dd3f
--- /dev/null
+++ b/packages/docs-infra/src/useCode/useEditable.test.ts
@@ -0,0 +1,634 @@
+/**
+ * @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 } = {}) {
+  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');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // 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();
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // 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);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // 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');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Event listener cleanup
+  // ---------------------------------------------------------------------------
+  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('keyup', 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();
+    });
+  });
+});
diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 5b4297c74..d38af06c4 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -29,6 +29,7 @@ SOFTWARE.
 // Forked from https://github.com/FormidableLabs/use-editable
 // Changes:
 // - Fix linting and formatting
+// - Add Tests
 
 import * as React from 'react';
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d1ba78f85..654b27465 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -57,7 +57,7 @@ importers:
         version: 7.0.0-dev.20260317.1
       '@vitest/coverage-v8':
         specifier: ^4.1.0
-        version: 4.1.0(vitest@4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@vitest/browser@4.1.0(vite@8.0.0(@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.0))(vitest@4.1.0)
       eslint:
         specifier: ^10.0.3
         version: 10.0.3(jiti@2.6.1)
@@ -81,11 +81,14 @@ importers:
         version: 4.21.0
       vitest:
         specifier: ^4.1.0
-        version: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0
+        version: 4.1.0(playwright@1.58.2)(vite@8.0.0(@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.0)
       baseline-browser-mapping:
         specifier: 2.10.7
         version: 2.10.7
@@ -545,7 +548,7 @@ importers:
         version: 7.0.0-dev.20260317.1
       '@vitest/eslint-plugin':
         specifier: ^1.6.11
-        version: 1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(jsdom@28.1.0)(vite@8.0.0(@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: 1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.0)
       babel-plugin-optimize-clsx:
         specifier: ^2.6.2
         version: 2.6.2
@@ -826,6 +829,9 @@ importers:
       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
@@ -941,7 +947,7 @@ importers:
         version: 19.2.4(react@19.2.4)
       vitest-fail-on-console:
         specifier: ^0.10.1
-        version: 0.10.1(@vitest/utils@4.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(jsdom@28.1.0)(vite@8.0.0(@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: 0.10.1(@vitest/utils@4.1.1)(vite@8.0.0(@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.0)
     devDependencies:
       '@playwright/test':
         specifier: 1.58.2
@@ -1842,6 +1848,9 @@ packages:
     resolution: {integrity: sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==}
     engines: {node: '>=18'}
 
+  '@blazediff/core@1.9.1':
+    resolution: {integrity: sha512-ehg3jIkYKulZh+8om/O25vkvSsXXwC+skXmyA87FFx6A/45eqOkZsBltMw/TVteb0mloiGT8oGRTcjRAz66zaA==}
+
   '@bramus/specificity@2.4.2':
     resolution: {integrity: sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==}
     hasBin: true
@@ -6265,6 +6274,17 @@ packages:
     peerDependencies:
       vite: ^4.2.0 || ^5.0.0 || ^6.0.0
 
+  '@vitest/browser-playwright@4.1.0':
+    resolution: {integrity: sha512-2RU7pZELY9/aVMLmABNy1HeZ4FX23FXGY1jRuHLHgWa2zaAE49aNW2GLzebW+BmbTZIKKyFF1QXvk7DEWViUCQ==}
+    peerDependencies:
+      playwright: '*'
+      vitest: 4.1.0
+
+  '@vitest/browser@4.1.0':
+    resolution: {integrity: sha512-tG/iOrgbiHQks0ew7CdelUyNEHkv8NLrt+CqdTivIuoSnXvO7scWMn4Kqo78/UGY1NJ6Hv+vp8BvRnED/bjFdQ==}
+    peerDependencies:
+      vitest: 4.1.0
+
   '@vitest/coverage-v8@4.1.0':
     resolution: {integrity: sha512-nDWulKeik2bL2Va/Wl4x7DLuTKAXa906iRFooIRPR+huHkcvp9QDkPQ2RJdmjOFrqOqvNfoSQLF68deE3xC3CQ==}
     peerDependencies:
@@ -6304,6 +6324,9 @@ packages:
   '@vitest/pretty-format@4.1.0':
     resolution: {integrity: sha512-3RZLZlh88Ib0J7NQTRATfc/3ZPOnSUn2uDBUoGNn5T36+bALixmzphN26OUD3LRXWkJu4H0s5vvUeqBiw+kS0A==}
 
+  '@vitest/pretty-format@4.1.1':
+    resolution: {integrity: sha512-GM+TEQN5WhOygr1lp7skeVjdLPqqWMHsfzXrcHAqZJi/lIVh63H0kaRCY8MDhNWikx19zBUK8ceaLB7X5AH9NQ==}
+
   '@vitest/runner@4.1.0':
     resolution: {integrity: sha512-Duvx2OzQ7d6OjchL+trw+aSrb9idh7pnNfxrklo14p3zmNL4qPCDeIJAK+eBKYjkIwG96Bc6vYuxhqDXQOWpoQ==}
 
@@ -6316,6 +6339,9 @@ packages:
   '@vitest/utils@4.1.0':
     resolution: {integrity: sha512-XfPXT6a8TZY3dcGY8EdwsBulFCIw+BeeX0RZn2x/BtiY/75YGh8FeWGG8QISN/WhaqSrE2OrlDgtF8q5uhOTmw==}
 
+  '@vitest/utils@4.1.1':
+    resolution: {integrity: sha512-cNxAlaB3sHoCdL6pj6yyUXv9Gry1NHNg0kFTXdvSIZXLHsqKH7chiWOkwJ5s5+d/oMwcoG9T0bKU38JZWKusrQ==}
+
   '@webassemblyjs/ast@1.14.1':
     resolution: {integrity: sha512-nuBEDgQfm1ccRp/8bCQrx1frohyufl4JlbMMZ4P1wpeOfDhF6FQkxZJ1b/e+PLwr6X1Nhw6OLme5usuBWYBvuQ==}
 
@@ -10530,6 +10556,10 @@ packages:
   pluralize@3.1.0:
     resolution: {integrity: sha512-2wcybwjwXOzGI1rlxWtlcs0/nSYK0OzNPqsg35TKxJFQlGhFu3cZ1x7EHS4r4bubQlhzyF4YxxlJqQnIhkUQCw==}
 
+  pngjs@7.0.0:
+    resolution: {integrity: sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==}
+    engines: {node: '>=14.19.0'}
+
   possible-typed-array-names@1.1.0:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
     engines: {node: '>= 0.4'}
@@ -11289,6 +11319,10 @@ packages:
     resolution: {integrity: sha512-94Bdh3cC2PKrbgSOUqTiGPWVZeSiXfKOVZNJniWoqrWrRkB1CJzBU3NEbiTsPcYy1lDsANA/THzS+9WBiy5nfQ==}
     engines: {node: '>= 10'}
 
+  sirv@3.0.2:
+    resolution: {integrity: sha512-2wcC/oGxHis/BoHkkPwldgiPSYcpZK3JU28WoMVv55yHJgcZ8rlXvuG9iZggz+sU1d4bRgIGASwyWqjxu3FM0g==}
+    engines: {node: '>=18'}
+
   sisteransi@1.0.5:
     resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
 
@@ -12421,6 +12455,18 @@ packages:
       utf-8-validate:
         optional: true
 
+  ws@8.20.0:
+    resolution: {integrity: sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==}
+    engines: {node: '>=10.0.0'}
+    peerDependencies:
+      bufferutil: ^4.0.1
+      utf-8-validate: '>=5.0.2'
+    peerDependenciesMeta:
+      bufferutil:
+        optional: true
+      utf-8-validate:
+        optional: true
+
   wsl-utils@0.1.0:
     resolution: {integrity: sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw==}
     engines: {node: '>=18'}
@@ -12558,6 +12604,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':
@@ -13979,6 +14030,8 @@ snapshots:
 
   '@bcoe/v8-coverage@1.0.2': {}
 
+  '@blazediff/core@1.9.1': {}
+
   '@bramus/specificity@2.4.2':
     dependencies:
       css-tree: 3.2.1
@@ -18685,7 +18738,37 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@vitest/coverage-v8@4.1.0(vitest@4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(jsdom@28.1.0)(vite@8.0.0(@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@4.1.0(playwright@1.58.2)(vite@8.0.0(@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.0)':
+    dependencies:
+      '@vitest/browser': 4.1.0(vite@8.0.0(@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.0)
+      '@vitest/mocker': 4.1.0(vite@8.0.0(@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
+      tinyrainbow: 3.0.3
+      vitest: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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@4.1.0(vite@8.0.0(@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.0)':
+    dependencies:
+      '@blazediff/core': 1.9.1
+      '@vitest/mocker': 4.1.0(vite@8.0.0(@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.0
+      magic-string: 0.30.21
+      pngjs: 7.0.0
+      sirv: 3.0.2
+      tinyrainbow: 3.0.3
+      vitest: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.20.0
+    transitivePeerDependencies:
+      - bufferutil
+      - msw
+      - utf-8-validate
+      - vite
+
+  '@vitest/coverage-v8@4.1.0(@vitest/browser@4.1.0(vite@8.0.0(@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.0))(vitest@4.1.0)':
     dependencies:
       '@bcoe/v8-coverage': 1.0.2
       '@vitest/utils': 4.1.0
@@ -18697,16 +18780,18 @@ snapshots:
       obug: 2.1.1
       std-env: 4.0.0
       tinyrainbow: 3.0.3
-      vitest: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(vite@8.0.0(@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.0)
 
-  '@vitest/eslint-plugin@1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(jsdom@28.1.0)(vite@8.0.0(@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/eslint-plugin@1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.0)':
     dependencies:
       '@typescript-eslint/scope-manager': 8.57.1
       '@typescript-eslint/utils': 8.57.1(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)
       eslint: 10.0.3(jiti@2.6.1)
     optionalDependencies:
       typescript: 5.9.3
-      vitest: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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:
       - supports-color
 
@@ -18731,6 +18816,10 @@ snapshots:
     dependencies:
       tinyrainbow: 3.0.3
 
+  '@vitest/pretty-format@4.1.1':
+    dependencies:
+      tinyrainbow: 3.0.3
+
   '@vitest/runner@4.1.0':
     dependencies:
       '@vitest/utils': 4.1.0
@@ -18751,6 +18840,12 @@ snapshots:
       convert-source-map: 2.0.0
       tinyrainbow: 3.0.3
 
+  '@vitest/utils@4.1.1':
+    dependencies:
+      '@vitest/pretty-format': 4.1.1
+      convert-source-map: 2.0.0
+      tinyrainbow: 3.0.3
+
   '@webassemblyjs/ast@1.14.1':
     dependencies:
       '@webassemblyjs/helper-numbers': 1.13.2
@@ -23933,6 +24028,8 @@ snapshots:
 
   pluralize@3.1.0: {}
 
+  pngjs@7.0.0: {}
+
   possible-typed-array-names@1.1.0: {}
 
   postcss-safe-parser@7.0.1(postcss@8.5.8):
@@ -24946,6 +25043,12 @@ snapshots:
       mrmime: 2.0.1
       totalist: 3.0.1
 
+  sirv@3.0.2:
+    dependencies:
+      '@polka/url': 1.0.0-next.29
+      mrmime: 2.0.1
+      totalist: 3.0.1
+
   sisteransi@1.0.5: {}
 
   slash@2.0.0: {}
@@ -25850,14 +25953,14 @@ snapshots:
       tsx: 4.21.0
       yaml: 2.8.1
 
-  vitest-fail-on-console@0.10.1(@vitest/utils@4.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(jsdom@28.1.0)(vite@8.0.0(@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-fail-on-console@0.10.1(@vitest/utils@4.1.1)(vite@8.0.0(@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.0):
     dependencies:
-      '@vitest/utils': 4.1.0
+      '@vitest/utils': 4.1.1
       chalk: 5.6.2
       vite: 8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0
       '@vitest/mocker': 4.1.0(vite@8.0.0(@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))
@@ -25882,6 +25985,7 @@ snapshots:
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
       '@types/node': 22.19.0
+      '@vitest/browser-playwright': 4.1.0(playwright@1.58.2)(vite@8.0.0(@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.0)
       jsdom: 28.1.0
     transitivePeerDependencies:
       - msw
@@ -26113,6 +26217,8 @@ snapshots:
 
   ws@8.18.1: {}
 
+  ws@8.20.0: {}
+
   wsl-utils@0.1.0:
     dependencies:
       is-wsl: 3.1.0
@@ -26227,3 +26333,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' }],
+    },
+  },
+});

From 9599f108ed491f6ac3298baf67fbcf2612377072 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 7 Apr 2026 15:44:31 -0400
Subject: [PATCH 11/45] feat: enhance useEditable for better text insertion and
 handling in contentEditable mode

- Added tests for inserting text at the start of a framed line and after </p> without merging lines.
- Improved handling of plain text input in fallback contentEditable mode.
- Implemented logic to keep </div> on the next line when inserting after </p>.
- Added functionality to repair merged lines before onChange when receiving a merged DOM.
- Enhanced toString function to ensure newline character handling.
- Introduced adjustCursorAtNewlineBoundary to correctly position the cursor at newline boundaries.
- Updated useEditable state management to track pending content for better mutation handling.
- Refactored source editing logic to prevent unnecessary updates when source matches.
---
 .../docs-infra/src/useCode/Pre.browser.tsx    | 146 +++++
 packages/docs-infra/src/useCode/Pre.test.tsx  | 179 ++++++
 packages/docs-infra/src/useCode/Pre.tsx       |  10 +-
 .../src/useCode/useEditable.browser.ts        | 522 +++++++++++++++++-
 .../src/useCode/useEditable.test.ts           | 310 +++++++++++
 .../docs-infra/src/useCode/useEditable.ts     | 193 +++++--
 .../src/useCode/useSourceEditing.ts           |   8 +-
 7 files changed, 1309 insertions(+), 59 deletions(-)
 create mode 100644 packages/docs-infra/src/useCode/Pre.browser.tsx
 create mode 100644 packages/docs-infra/src/useCode/Pre.test.tsx

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..57a44fe16
--- /dev/null
+++ b/packages/docs-infra/src/useCode/Pre.browser.tsx
@@ -0,0 +1,146 @@
+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('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 43522f720..541541fae 100644
--- a/packages/docs-infra/src/useCode/Pre.tsx
+++ b/packages/docs-infra/src/useCode/Pre.tsx
@@ -5,8 +5,8 @@ import { toText } from 'hast-util-to-text';
 import { ElementContent } from 'hast';
 import { decompressSync, strFromU8 } from 'fflate';
 import { decode } from 'uint8-to-base64';
-import { useEditable } from 'use-editable';
-import type { Position } from 'use-editable';
+import { useEditable } from './useEditable';
+import type { Position } from './useEditable';
 import type { HastRoot, VariantSource } from '../CodeHighlighter/types';
 import { hastToJsx } from '../pipeline/hastUtils';
 
@@ -54,6 +54,8 @@ export function Pre({
   shouldHighlight?: boolean;
   hydrateMargin?: string;
 }): React.ReactNode {
+  const isEditable = Boolean(setSource);
+
   const hast = React.useMemo(() => {
     if (typeof children === 'string') {
       return null;
@@ -193,7 +195,7 @@ export function Pre({
 
       if (child.properties.className === 'frame') {
         const isVisible = Boolean(visibleFrames[index]);
-        const shouldRenderHast = shouldHighlight && isVisible;
+        const shouldRenderHast = shouldHighlight && (isEditable || isVisible);
 
         return (
           <span
@@ -226,7 +228,7 @@ export function Pre({
         </React.Fragment>
       );
     });
-  }, [hast, observeFrame, shouldHighlight, visibleFrames]);
+  }, [hast, isEditable, observeFrame, shouldHighlight, visibleFrames]);
 
   return (
     <pre ref={bindIntersectionObserver} className={className}>
diff --git a/packages/docs-infra/src/useCode/useEditable.browser.ts b/packages/docs-infra/src/useCode/useEditable.browser.ts
index 74e37fd02..50689ac40 100644
--- a/packages/docs-infra/src/useCode/useEditable.browser.ts
+++ b/packages/docs-infra/src/useCode/useEditable.browser.ts
@@ -8,20 +8,22 @@ import { useEditable, type Position } from './useEditable';
  */
 function placeCaret(element: HTMLElement, offset: number) {
   element.focus();
+  const sel = window.getSelection()!;
   const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
   let current = 0;
-  while (walker.nextNode()) {
-    const node = walker.currentNode;
+  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);
-      window.getSelection()!.removeAllRanges();
-      window.getSelection()!.addRange(range);
+      sel.removeAllRanges();
+      sel.addRange(range);
       return;
     }
     current += len;
+    node = walker.nextNode();
   }
 }
 
@@ -101,21 +103,43 @@ function setupHighlighted(
 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>;</span>\n',
-  '<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>;</span>\n',
+  '<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>() {</span>\n',
-  '<span class="line" data-ln="5">  <span class="pl-k">return</span> (</span>\n',
-  '<span class="line" data-ln="6">    &lt;<span class="pl-ent">div</span>&gt;</span>\n',
+  '<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;</span>\n',
-  '<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;</span>\n',
+  '<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;</span>\n',
-  '<span class="line" data-ln="10">  );</span>\n',
-  '<span class="line" data-ln="11">}</span>\n',
+  '<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('');
@@ -743,6 +767,32 @@ describe('useEditable - syntax-highlighted content', () => {
       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>');
+    });
   });
 
   // -------------------------------------------------------------------------
@@ -821,3 +871,447 @@ describe('useEditable - syntax-highlighted content', () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// 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);
+  });
+});
diff --git a/packages/docs-infra/src/useCode/useEditable.test.ts b/packages/docs-infra/src/useCode/useEditable.test.ts
index 4ffa1dd3f..35a6ca612 100644
--- a/packages/docs-infra/src/useCode/useEditable.test.ts
+++ b/packages/docs-infra/src/useCode/useEditable.test.ts
@@ -275,6 +275,91 @@ describe('useEditable', () => {
       // 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('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>',
+        '',
+      ]);
+    });
   });
 
   // ---------------------------------------------------------------------------
@@ -414,6 +499,231 @@ describe('useEditable', () => {
 
       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>',
+        '',
+      ]);
+    });
   });
 
   // ---------------------------------------------------------------------------
diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index d38af06c4..7fc6e728d 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -60,35 +60,77 @@ const setCurrentRange = (range: Range) => {
 const isUndoRedoKey = (event: KeyboardEvent): boolean =>
   (event.metaKey || event.ctrlKey) && !event.altKey && event.code === 'KeyZ';
 
-const toString = (element: HTMLElement): string => {
-  const queue: Node[] = [element.firstChild!];
+const isPlaintextInputKey = (event: KeyboardEvent): boolean => {
+  const usesAltGraph =
+    typeof event.getModifierState === 'function' && event.getModifierState('AltGraph');
 
-  let content = '';
-  while (queue.length > 0) {
-    const node = queue.pop()!;
-    if (node.nodeType === Node.TEXT_NODE) {
-      content += node.textContent;
-    } else if (node.nodeType === Node.ELEMENT_NODE && node.nodeName === 'BR') {
-      content += '\n';
-    }
+  return (
+    event.key.length === 1 && !event.metaKey && !event.ctrlKey && (!event.altKey || usesAltGraph)
+  );
+};
 
-    if (node.nextSibling) {
-      queue.push(node.nextSibling);
-    }
-    if (node.firstChild) {
-      queue.push(node.firstChild);
-    }
-  }
+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') {
-    content += '\n';
+    return `${content}\n`;
   }
 
   return content;
 };
 
+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) => {
   if (offset < node.textContent!.length) {
     range.setStart(node, offset);
@@ -159,23 +201,6 @@ const makeRange = (element: HTMLElement, start: number, end?: number): Range =>
       }
 
       current += node.textContent!.length;
-    } else if (node.nodeType === Node.ELEMENT_NODE && node.nodeName === 'BR') {
-      if (current + 1 >= position) {
-        if (position === start) {
-          setStart(range, node, 0);
-          if (end !== start) {
-            position = end;
-            continue;
-          } else {
-            break;
-          }
-        } else {
-          setEnd(range, node, 0);
-          break;
-        }
-      }
-
-      current += 1;
     }
 
     queue.pop();
@@ -190,10 +215,74 @@ const makeRange = (element: HTMLElement, start: number, end?: number): Range =>
   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.
+ */
+const adjustCursorAtNewlineBoundary = (range: Range): void => {
+  if (!range.collapsed) {
+    return;
+  }
+
+  const { startContainer, startOffset } = range;
+
+  // 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 === startContainer.textContent!.length &&
+    startContainer.textContent!.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];
+    if (prevChild?.nodeType === Node.TEXT_NODE && prevChild.textContent!.endsWith('\n')) {
+      const next = nextTextNode(prevChild);
+      if (next) {
+        range.setStart(next, 0);
+        range.collapse(true);
+      }
+    }
+  }
+};
+
 interface State {
   observer: MutationObserver;
   disconnected: boolean;
   onChange(text: string, position: Position): void;
+  pendingContent: string | null;
   queue: MutationRecord[];
   history: History[];
   historyAt: number;
@@ -231,6 +320,7 @@ export const useEditable = (
       observer: null as any,
       disconnected: false,
       onChange,
+      pendingContent: null,
       queue: [],
       history: [],
       historyAt: -1,
@@ -269,11 +359,14 @@ export const useEditable = (
           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));
           }
-          setCurrentRange(makeRange(element, start + append.length));
+          const cursorRange = makeRange(element, start + append.length);
+          adjustCursorAtNewlineBoundary(cursorRange);
+          setCurrentRange(cursorRange);
         }
       },
       move(pos: number | { row: number; column: number }) {
@@ -291,7 +384,9 @@ export const useEditable = (
             position += pos.column;
           }
 
-          setCurrentRange(makeRange(element, position));
+          const cursorRange = makeRange(element, position);
+          adjustCursorAtNewlineBoundary(cursorRange);
+          setCurrentRange(cursorRange);
         }
       },
       getState() {
@@ -321,7 +416,9 @@ export const useEditable = (
     state.observer.observe(elementRef.current, observerSettings);
     if (state.position) {
       const { position, extent } = state.position;
-      setCurrentRange(makeRange(elementRef.current, position, position + extent));
+      const cursorRange = makeRange(elementRef.current, position, position + extent);
+      adjustCursorAtNewlineBoundary(cursorRange);
+      setCurrentRange(cursorRange);
     }
 
     return () => {
@@ -344,7 +441,9 @@ export const useEditable = (
     if (state.position) {
       element.focus();
       const { position, extent } = state.position;
-      setCurrentRange(makeRange(element, position, position + extent));
+      const cursorRange = makeRange(element, position, position + extent);
+      adjustCursorAtNewlineBoundary(cursorRange);
+      setCurrentRange(cursorRange);
     }
 
     const prevWhiteSpace = element.style.whiteSpace;
@@ -412,7 +511,11 @@ export const useEditable = (
       const position = getPosition(element);
       if (state.queue.length) {
         disconnect();
-        const content = toString(element);
+        const content = repairUnexpectedLineMerge(
+          toString(element),
+          state.pendingContent,
+          position,
+        );
         state.position = position;
         while (state.queue.length > 0) {
           const mutation = state.queue.pop()!;
@@ -431,6 +534,8 @@ export const useEditable = (
 
         state.onChange(content, position);
       }
+
+      state.pendingContent = null;
     };
 
     const onKeyDown = (event: HTMLElementEventMap['keydown']) => {
@@ -476,6 +581,7 @@ export const useEditable = (
       }
 
       trackState();
+      state.pendingContent = toString(element);
 
       if (event.key === 'Enter') {
         event.preventDefault();
@@ -488,6 +594,12 @@ export const useEditable = (
         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 || opts!.indentation) && event.key === 'Backspace') {
         // Firefox Quirk: Since plaintext-only is unsupported we must
         // ensure that only a single character is deleted
@@ -542,6 +654,7 @@ export const useEditable = (
     const onPaste = (event: HTMLElementEventMap['paste']) => {
       event.preventDefault();
       trackState(true);
+      state.pendingContent = toString(element);
       edit.insert(event.clipboardData!.getData('text/plain'));
       trackState(true);
       flushChanges();
diff --git a/packages/docs-infra/src/useCode/useSourceEditing.ts b/packages/docs-infra/src/useCode/useSourceEditing.ts
index 1cd36b7e7..7a7915876 100644
--- a/packages/docs-infra/src/useCode/useSourceEditing.ts
+++ b/packages/docs-infra/src/useCode/useSourceEditing.ts
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { Position } from 'use-editable';
+import type { Position } from './useEditable';
 import type {
   Code,
   CollapseMap,
@@ -244,6 +244,9 @@ export function useSourceEditing({
         const isMainFile = effectiveFileName === selectedVariant?.fileName;
 
         if (isMainFile) {
+          if (source === variant.source) {
+            return currentCode ?? newCode;
+          }
           const { comments: shiftedComments, collapseMap: newCollapseMap } = position
             ? shiftComments(variant.comments, variant.source, source, position, variant.collapseMap)
             : { comments: undefined, collapseMap: undefined };
@@ -255,6 +258,9 @@ export function useSourceEditing({
           };
         } else if (effectiveFileName) {
           const extraEntry = variant.extraFiles?.[effectiveFileName];
+          if (source === extraEntry?.source) {
+            return currentCode ?? newCode;
+          }
           const { comments: shiftedComments, collapseMap: newCollapseMap } = position
             ? shiftComments(
                 extraEntry?.comments,

From 5d9e6f059c8a93278f825c9253b3df7dca72eea5 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 7 Apr 2026 16:36:50 -0400
Subject: [PATCH 12/45] Fix workspace

---
 package.json                              |   4 +-
 packages/docs-infra/src/cli/runBrowser.ts |  65 +++-
 pnpm-lock.yaml                            | 391 ++++++++++++++++++----
 3 files changed, 396 insertions(+), 64 deletions(-)

diff --git a/package.json b/package.json
index 5c1458314..123270afe 100644
--- a/package.json
+++ b/package.json
@@ -10,7 +10,7 @@
     "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 --script test:browser:unconfined --playwright-version 1.58.2 --",
+    "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",
@@ -84,7 +84,7 @@
   },
   "devDependencies": {
     "@babel/plugin-transform-react-constant-elements": "7.27.1",
-    "@vitest/browser-playwright": "4.1.0",
+    "@vitest/browser-playwright": "4.1.3",
     "baseline-browser-mapping": "2.10.7",
     "eslint-plugin-n": "17.24.0",
     "markdownlint-cli2": "0.21.0",
diff --git a/packages/docs-infra/src/cli/runBrowser.ts b/packages/docs-infra/src/cli/runBrowser.ts
index 22bef8743..e3257fa01 100644
--- a/packages/docs-infra/src/cli/runBrowser.ts
+++ b/packages/docs-infra/src/cli/runBrowser.ts
@@ -9,6 +9,8 @@ type Args = {
   port: number;
   script: string;
   'playwright-version': string;
+  headed: boolean;
+  workspace: boolean;
   _: (string | number)[];
   '--'?: string[];
 };
@@ -77,6 +79,9 @@ async function waitForServer(port: number, maxAttempts = 30): Promise<boolean> {
 
 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 () => {
@@ -94,8 +99,11 @@ async function handler(argv: Args) {
 
     const image = `mcr.microsoft.com/playwright:v${argv['playwright-version']}-noble`;
 
-    console.log(`Starting Playwright server on port ${port}…`);
-    await engine(
+    // 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',
@@ -103,6 +111,36 @@ async function handler(argv: Args) {
       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',
@@ -114,6 +152,9 @@ async function handler(argv: Args) {
       '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);
 
@@ -128,11 +169,16 @@ async function handler(argv: Args) {
     // 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];
+    const extra = [...positional, ...passthrough.filter((a) => a !== '--headed')];
+    if (headed) {
+      extra.push('--browser.headless=false');
+    }
     const env = { ...process.env, PLAYWRIGHT_SERVER: `ws://localhost:${port}` };
-    await $({ env, stdio: 'inherit' })`pnpm -w run ${argv.script} ${extra}`;
+    const pnpmArgs = argv.workspace ? ['-w'] : [];
+    await $({ env, stdio: 'inherit' })`pnpm ${pnpmArgs} run ${argv.script} ${extra}`;
   } finally {
     await stopContainer();
   }
@@ -158,6 +204,17 @@ const runBrowser: CommandModule<{}, Args> = {
         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);
   },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 654b27465..8f1ba5226 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -81,14 +81,14 @@ importers:
         version: 4.21.0
       vitest:
         specifier: ^4.1.0
-        version: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/ui@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0
-        version: 4.1.0(playwright@1.58.2)(vite@8.0.0(@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.0)
+        specifier: 4.1.3
+        version: 4.1.3(playwright@1.59.1)(vite@8.0.0(@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.0)
       baseline-browser-mapping:
         specifier: 2.10.7
         version: 2.10.7
@@ -130,7 +130,7 @@ importers:
         version: 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@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.4))(@emotion/server@11.11.0)(@types/react@19.2.14)(next@16.1.7(@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.4(react@19.2.4))(react@19.2.4))(react@19.2.4)
+        version: 9.0.0-alpha.2(@emotion/cache@11.14.0)(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/server@11.11.0)(@types/react@19.2.14)(next@16.2.1(@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.4(react@19.2.4))(react@19.2.4))(react@19.2.4)
       '@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.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -163,7 +163,7 @@ importers:
         version: 3.20.0(@types/node@22.19.0)
       next:
         specifier: ^16.1.6
-        version: 16.1.7(@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.4(react@19.2.4))(react@19.2.4)
+        version: 16.2.1(@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.4(react@19.2.4))(react@19.2.4)
       pako:
         specifier: ^2.1.0
         version: 2.1.0
@@ -272,8 +272,8 @@ importers:
         specifier: workspace:^
         version: link:../packages/docs-infra/build
       '@next/mdx':
-        specifier: ^16.1.6
-        version: 16.1.6(@mdx-js/loader@3.1.1(webpack@5.102.1(esbuild@0.27.1)(jiti@2.6.1)))(@mdx-js/react@3.1.1(@types/react@19.2.14)(react@19.2.4))
+        specifier: ^16.2.1
+        version: 16.2.1(@mdx-js/loader@3.1.1(webpack@5.102.1(esbuild@0.27.1)(jiti@2.6.1)))(@mdx-js/react@3.1.1(@types/react@19.2.14)(react@19.2.4))
       '@types/mdx':
         specifier: ^2.0.13
         version: 2.0.13
@@ -281,8 +281,8 @@ importers:
         specifier: ^0.577.0
         version: 0.577.0(react@19.2.4)
       next:
-        specifier: ^16.1.6
-        version: 16.1.7(@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.4(react@19.2.4))(react@19.2.4)
+        specifier: ^16.2.1
+        version: 16.2.1(@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.4(react@19.2.4))(react@19.2.4)
       react:
         specifier: ^19.2.4
         version: 19.2.4
@@ -312,8 +312,11 @@ importers:
         version: 5.1.0
     devDependencies:
       '@next/bundle-analyzer':
-        specifier: 16.1.6
-        version: 16.1.6
+        specifier: 16.2.1
+        version: 16.2.1
+      '@playwright/test':
+        specifier: 1.59.1
+        version: 1.59.1
       '@types/node':
         specifier: 22.19.0
         version: 22.19.0
@@ -874,7 +877,7 @@ importers:
         version: 9.0.5
       next:
         specifier: 16.1.7
-        version: 16.1.7(@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.4(react@19.2.4))(react@19.2.4)
+        version: 16.1.7(@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.4(react@19.2.4))(react@19.2.4)
       react:
         specifier: 19.2.4
         version: 19.2.4
@@ -947,7 +950,7 @@ importers:
         version: 19.2.4(react@19.2.4)
       vitest-fail-on-console:
         specifier: ^0.10.1
-        version: 0.10.1(@vitest/utils@4.1.1)(vite@8.0.0(@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.0)
+        version: 0.10.1(@vitest/utils@4.1.3)(vite@8.0.0(@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.0)
     devDependencies:
       '@playwright/test':
         specifier: 1.58.2
@@ -4012,17 +4015,20 @@ packages:
   '@napi-rs/wasm-runtime@1.1.1':
     resolution: {integrity: sha512-p64ah1M1ld8xjWv3qbvFwHiFVWrq1yFvV4f7w+mzaqiR4IlSgkqhcRdHwsGgomwzBH51sRY4NEowLxnaBjcW/A==}
 
-  '@next/bundle-analyzer@16.1.6':
-    resolution: {integrity: sha512-ee2kagdTaeEWPlotgdTOqFHYcD3e2m2bbE3I9Rq2i6ABYi5OgopmtEUe8NM23viaYxLV2tDH/2nd5+qKoEr6cw==}
+  '@next/bundle-analyzer@16.2.1':
+    resolution: {integrity: sha512-fbj2WE6dnCyG8CvQnrBfpHyxdOIyZ4aEHJY0bSqAmamRiIXDqunFQPDvuSOPo24mJE9zQHw7TY6d+sGrXO98TQ==}
 
   '@next/env@16.1.7':
     resolution: {integrity: sha512-rJJbIdJB/RQr2F1nylZr/PJzamvNNhfr3brdKP6s/GW850jbtR70QlSfFselvIBbcPUOlQwBakexjFzqLzF6pg==}
 
+  '@next/env@16.2.1':
+    resolution: {integrity: sha512-n8P/HCkIWW+gVal2Z8XqXJ6aB3J0tuM29OcHpCsobWlChH/SITBs1DFBk/HajgrwDkqqBXPbuUuzgDvUekREPg==}
+
   '@next/eslint-plugin-next@16.1.6':
     resolution: {integrity: sha512-/Qq3PTagA6+nYVfryAtQ7/9FEr/6YVyvOtl6rZnGsbReGLf0jZU6gkpr1FuChAQpvV46a78p4cmHOVP8mbfSMQ==}
 
-  '@next/mdx@16.1.6':
-    resolution: {integrity: sha512-PT5JR4WPPYOls7WD6xEqUVVI9HDY8kY7XLQsNYB2lSZk5eJSXWu3ECtIYmfR0hZpx8Sg7BKZYKi2+u5OTSEx0w==}
+  '@next/mdx@16.2.1':
+    resolution: {integrity: sha512-w0YOkOc+WEnsTJ8uxzBOvpe3R+9BnJOxWCE7qcI/62CzJiUEd8JKtF25e3R8cW5BGsKyRW8p4zE2JLyXKa8xdw==}
     peerDependencies:
       '@mdx-js/loader': '>=0.15.0'
       '@mdx-js/react': '>=0.15.0'
@@ -4038,12 +4044,24 @@ packages:
     cpu: [arm64]
     os: [darwin]
 
+  '@next/swc-darwin-arm64@16.2.1':
+    resolution: {integrity: sha512-BwZ8w8YTaSEr2HIuXLMLxIdElNMPvY9fLqb20LX9A9OMGtJilhHLbCL3ggyd0TwjmMcTxi0XXt+ur1vWUoxj2Q==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
   '@next/swc-darwin-x64@16.1.7':
     resolution: {integrity: sha512-zcnVaaZulS1WL0Ss38R5Q6D2gz7MtBu8GZLPfK+73D/hp4GFMrC2sudLky1QibfV7h6RJBJs/gOFvYP0X7UVlQ==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [darwin]
 
+  '@next/swc-darwin-x64@16.2.1':
+    resolution: {integrity: sha512-/vrcE6iQSJq3uL3VGVHiXeaKbn8Es10DGTGRJnRZlkNQQk3kaNtAJg8Y6xuAlrx/6INKVjkfi5rY0iEXorZ6uA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
   '@next/swc-linux-arm64-gnu@16.1.7':
     resolution: {integrity: sha512-2ant89Lux/Q3VyC8vNVg7uBaFVP9SwoK2jJOOR0L8TQnX8CAYnh4uctAScy2Hwj2dgjVHqHLORQZJ2wH6VxhSQ==}
     engines: {node: '>= 10'}
@@ -4051,6 +4069,13 @@ packages:
     os: [linux]
     libc: [glibc]
 
+  '@next/swc-linux-arm64-gnu@16.2.1':
+    resolution: {integrity: sha512-uLn+0BK+C31LTVbQ/QU+UaVrV0rRSJQ8RfniQAHPghDdgE+SlroYqcmFnO5iNjNfVWCyKZHYrs3Nl0mUzWxbBw==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
   '@next/swc-linux-arm64-musl@16.1.7':
     resolution: {integrity: sha512-uufcze7LYv0FQg9GnNeZ3/whYfo+1Q3HnQpm16o6Uyi0OVzLlk2ZWoY7j07KADZFY8qwDbsmFnMQP3p3+Ftprw==}
     engines: {node: '>= 10'}
@@ -4058,6 +4083,13 @@ packages:
     os: [linux]
     libc: [musl]
 
+  '@next/swc-linux-arm64-musl@16.2.1':
+    resolution: {integrity: sha512-ssKq6iMRnHdnycGp9hCuGnXJZ0YPr4/wNwrfE5DbmvEcgl9+yv97/Kq3TPVDfYome1SW5geciLB9aiEqKXQjlQ==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
   '@next/swc-linux-x64-gnu@16.1.7':
     resolution: {integrity: sha512-KWVf2gxYvHtvuT+c4MBOGxuse5TD7DsMFYSxVxRBnOzok/xryNeQSjXgxSv9QpIVlaGzEn/pIuI6Koosx8CGWA==}
     engines: {node: '>= 10'}
@@ -4065,6 +4097,13 @@ packages:
     os: [linux]
     libc: [glibc]
 
+  '@next/swc-linux-x64-gnu@16.2.1':
+    resolution: {integrity: sha512-HQm7SrHRELJ30T1TSmT706IWovFFSRGxfgUkyWJZF/RKBMdbdRWJuFrcpDdE5vy9UXjFOx6L3mRdqH04Mmx0hg==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
   '@next/swc-linux-x64-musl@16.1.7':
     resolution: {integrity: sha512-HguhaGwsGr1YAGs68uRKc4aGWxLET+NevJskOcCAwXbwj0fYX0RgZW2gsOCzr9S11CSQPIkxmoSbuVaBp4Z3dA==}
     engines: {node: '>= 10'}
@@ -4072,18 +4111,37 @@ packages:
     os: [linux]
     libc: [musl]
 
+  '@next/swc-linux-x64-musl@16.2.1':
+    resolution: {integrity: sha512-aV2iUaC/5HGEpbBkE+4B8aHIudoOy5DYekAKOMSHoIYQ66y/wIVeaRx8MS2ZMdxe/HIXlMho4ubdZs/J8441Tg==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
   '@next/swc-win32-arm64-msvc@16.1.7':
     resolution: {integrity: sha512-S0n3KrDJokKTeFyM/vGGGR8+pCmXYrjNTk2ZozOL1C/JFdfUIL9O1ATaJOl5r2POe56iRChbsszrjMAdWSv7kQ==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [win32]
 
+  '@next/swc-win32-arm64-msvc@16.2.1':
+    resolution: {integrity: sha512-IXdNgiDHaSk0ZUJ+xp0OQTdTgnpx1RCfRTalhn3cjOP+IddTMINwA7DXZrwTmGDO8SUr5q2hdP/du4DcrB1GxA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
   '@next/swc-win32-x64-msvc@16.1.7':
     resolution: {integrity: sha512-mwgtg8CNZGYm06LeEd+bNnOUfwOyNem/rOiP14Lsz+AnUY92Zq/LXwtebtUiaeVkhbroRCQ0c8GlR4UT1U+0yg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [win32]
 
+  '@next/swc-win32-x64-msvc@16.2.1':
+    resolution: {integrity: sha512-qvU+3a39Hay+ieIztkGSbF7+mccbbg1Tk25hc4JDylf8IHjYmY/Zm64Qq1602yPyQqvie+vf5T/uPwNxDNIoeg==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
   '@nicolo-ribaudo/chokidar-2@2.1.8-no-fsevents.3':
     resolution: {integrity: sha512-s88O1aVtXftvp5bCPB7WnmXc5IwOZZ7YPuwNPt+GtOOXpPvad1LfbmjYv+qII7zP6RU2QGnqve27dnLycEnyEQ==}
 
@@ -4424,6 +4482,11 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  '@playwright/test@1.59.1':
+    resolution: {integrity: sha512-PG6q63nQg5c9rIi4/Z5lR5IVF7yU5MqmKaPOe0HSc0O2cX1fPi96sUQu5j7eo4gKCkB2AnNGoWt7y4/Xx3Kcqg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   '@pnpm/config.env-replace@1.1.0':
     resolution: {integrity: sha512-htyl8TWnKL7K/ESFa1oW2UB5lVDxuF5DpM7tBi6Hu2LNL3mWkIzNLG6N4zoCUP1lCKNxWy/3iu8mS8MvToGd6w==}
     engines: {node: '>=12.22.0'}
@@ -6280,11 +6343,22 @@ packages:
       playwright: '*'
       vitest: 4.1.0
 
+  '@vitest/browser-playwright@4.1.3':
+    resolution: {integrity: sha512-D3Q+YozvSpiFaLPgd6/OMbyqEIZeucSe6AHJJ7VnNJKQhIyBE60TlBZlxzwM8bvjzQE9ZnYWQCPeCw5pnhbiNg==}
+    peerDependencies:
+      playwright: '*'
+      vitest: 4.1.3
+
   '@vitest/browser@4.1.0':
     resolution: {integrity: sha512-tG/iOrgbiHQks0ew7CdelUyNEHkv8NLrt+CqdTivIuoSnXvO7scWMn4Kqo78/UGY1NJ6Hv+vp8BvRnED/bjFdQ==}
     peerDependencies:
       vitest: 4.1.0
 
+  '@vitest/browser@4.1.3':
+    resolution: {integrity: sha512-CS9KjO2vijuBlbwz0JIgC0YuoI1BuqWI5ziD3Nll6jkpNYtWdjPMVgGynQ9vZovjsECeUqEeNjWrypP414d0CQ==}
+    peerDependencies:
+      vitest: 4.1.3
+
   '@vitest/coverage-v8@4.1.0':
     resolution: {integrity: sha512-nDWulKeik2bL2Va/Wl4x7DLuTKAXa906iRFooIRPR+huHkcvp9QDkPQ2RJdmjOFrqOqvNfoSQLF68deE3xC3CQ==}
     peerDependencies:
@@ -6321,11 +6395,22 @@ packages:
       vite:
         optional: true
 
+  '@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/pretty-format@4.1.0':
     resolution: {integrity: sha512-3RZLZlh88Ib0J7NQTRATfc/3ZPOnSUn2uDBUoGNn5T36+bALixmzphN26OUD3LRXWkJu4H0s5vvUeqBiw+kS0A==}
 
-  '@vitest/pretty-format@4.1.1':
-    resolution: {integrity: sha512-GM+TEQN5WhOygr1lp7skeVjdLPqqWMHsfzXrcHAqZJi/lIVh63H0kaRCY8MDhNWikx19zBUK8ceaLB7X5AH9NQ==}
+  '@vitest/pretty-format@4.1.3':
+    resolution: {integrity: sha512-hYqqwuMbpkkBodpRh4k4cQSOELxXky1NfMmQvOfKvV8zQHz8x8Dla+2wzElkMkBvSAJX5TRGHJAQvK0TcOafwg==}
 
   '@vitest/runner@4.1.0':
     resolution: {integrity: sha512-Duvx2OzQ7d6OjchL+trw+aSrb9idh7pnNfxrklo14p3zmNL4qPCDeIJAK+eBKYjkIwG96Bc6vYuxhqDXQOWpoQ==}
@@ -6336,11 +6421,19 @@ packages:
   '@vitest/spy@4.1.0':
     resolution: {integrity: sha512-pz77k+PgNpyMDv2FV6qmk5ZVau6c3R8HC8v342T2xlFxQKTrSeYw9waIJG8KgV9fFwAtTu4ceRzMivPTH6wSxw==}
 
+  '@vitest/spy@4.1.3':
+    resolution: {integrity: sha512-ujj5Uwxagg4XUIfAUyRQxAg631BP6e9joRiN99mr48Bg9fRs+5mdUElhOoZ6rP5mBr8Bs3lmrREnkrQWkrsTCw==}
+
+  '@vitest/ui@4.1.0':
+    resolution: {integrity: sha512-sTSDtVM1GOevRGsCNhp1mBUHKo9Qlc55+HCreFT4fe99AHxl1QQNXSL3uj4Pkjh5yEuWZIx8E2tVC94nnBZECQ==}
+    peerDependencies:
+      vitest: 4.1.0
+
   '@vitest/utils@4.1.0':
     resolution: {integrity: sha512-XfPXT6a8TZY3dcGY8EdwsBulFCIw+BeeX0RZn2x/BtiY/75YGh8FeWGG8QISN/WhaqSrE2OrlDgtF8q5uhOTmw==}
 
-  '@vitest/utils@4.1.1':
-    resolution: {integrity: sha512-cNxAlaB3sHoCdL6pj6yyUXv9Gry1NHNg0kFTXdvSIZXLHsqKH7chiWOkwJ5s5+d/oMwcoG9T0bKU38JZWKusrQ==}
+  '@vitest/utils@4.1.3':
+    resolution: {integrity: sha512-Pc/Oexse/khOWsGB+w3q4yzA4te7W4gpZZAvk+fr8qXfTURZUMj5i7kuxsNK5mP/dEB6ao3jfr0rs17fHhbHdw==}
 
   '@webassemblyjs/ast@1.14.1':
     resolution: {integrity: sha512-nuBEDgQfm1ccRp/8bCQrx1frohyufl4JlbMMZ4P1wpeOfDhF6FQkxZJ1b/e+PLwr6X1Nhw6OLme5usuBWYBvuQ==}
@@ -8172,8 +8265,8 @@ packages:
   flatqueue@3.0.0:
     resolution: {integrity: sha512-y1deYaVt+lIc/d2uIcWDNd0CrdQTO5xoCjeFdhX0kSXvm2Acm0o+3bAOiYklTEoRyzwio3sv3/IiBZdusbAe2Q==}
 
-  flatted@3.3.3:
-    resolution: {integrity: sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==}
+  flatted@3.4.0:
+    resolution: {integrity: sha512-kC6Bb+ooptOIvWj5B63EQWkF0FEnNjV2ZNkLMLZRDDduIiWeFF4iKnslwhiWxjAdbg4NzTNo6h0qLuvFrcx+Sw==}
 
   follow-redirects@1.15.11:
     resolution: {integrity: sha512-deG2P0JfjrTxl50XGCDyfI97ZGVCxIpfKYmfyrQ54n5FO/0gfIES8C/Psl6kWVDolizcaaxZJnTS0QSMxvnsBQ==}
@@ -10011,6 +10104,27 @@ packages:
       sass:
         optional: true
 
+  next@16.2.1:
+    resolution: {integrity: sha512-VaChzNL7o9rbfdt60HUj8tev4m6d7iC1igAy157526+cJlXOQu5LzsBXNT+xaJnTP/k+utSX5vMv7m0G+zKH+Q==}
+    engines: {node: '>=20.9.0'}
+    hasBin: true
+    peerDependencies:
+      '@opentelemetry/api': ^1.1.0
+      '@playwright/test': ^1.51.1
+      babel-plugin-react-compiler: '*'
+      react: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+      react-dom: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+      sass: ^1.3.0
+    peerDependenciesMeta:
+      '@opentelemetry/api':
+        optional: true
+      '@playwright/test':
+        optional: true
+      babel-plugin-react-compiler:
+        optional: true
+      sass:
+        optional: true
+
   node-fetch-har@1.0.1:
     resolution: {integrity: sha512-XpTlblmwxdmVHtg6tDB5kXvEziXl8SlNI1Sc9DaKeWJDqreZhHrhijgWdxW84xh2zmYCiiAU9oLriCLu1oyTbg==}
     engines: {node: '>=8.10.0'}
@@ -10548,11 +10662,21 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  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==}
     engines: {node: '>=18'}
     hasBin: true
 
+  playwright@1.59.1:
+    resolution: {integrity: sha512-C8oWjPR3F81yljW9o5OxcWzfh6avkVwDD2VYdwIGqTkl+OGFISgypqzfu7dOe4QNLL2aqcWBmI3PMtLIK233lw==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   pluralize@3.1.0:
     resolution: {integrity: sha512-2wcybwjwXOzGI1rlxWtlcs0/nSYK0OzNPqsg35TKxJFQlGhFu3cZ1x7EHS4r4bubQlhzyF4YxxlJqQnIhkUQCw==}
 
@@ -11749,8 +11873,8 @@ packages:
     resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==}
     engines: {node: '>=12.0.0'}
 
-  tinyrainbow@3.0.3:
-    resolution: {integrity: sha512-PSkbLUoxOFRzJYjjxHJt9xro7D+iilgMX/C9lawzVuYiIdcihh9DXmVibBe8lmcFrRi/VzlPjBxbN7rH24q8/Q==}
+  tinyrainbow@3.1.0:
+    resolution: {integrity: sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==}
     engines: {node: '>=14.0.0'}
 
   title@4.0.1:
@@ -15032,11 +15156,11 @@ snapshots:
       '@emotion/styled': 11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
       '@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.4))(@emotion/server@11.11.0)(@types/react@19.2.14)(next@16.1.7(@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.4(react@19.2.4))(react@19.2.4))(react@19.2.4)':
+  '@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.4))(@emotion/server@11.11.0)(@types/react@19.2.14)(next@16.2.1(@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.4(react@19.2.4))(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@babel/runtime': 7.29.2
       '@emotion/react': 11.14.0(@types/react@19.2.14)(react@19.2.4)
-      next: 16.1.7(@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.4(react@19.2.4))(react@19.2.4)
+      next: 16.2.1(@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.4(react@19.2.4))(react@19.2.4)
       react: 19.2.4
     optionalDependencies:
       '@emotion/cache': 11.14.0
@@ -16121,7 +16245,7 @@ snapshots:
       '@tybys/wasm-util': 0.10.1
     optional: true
 
-  '@next/bundle-analyzer@16.1.6':
+  '@next/bundle-analyzer@16.2.1':
     dependencies:
       webpack-bundle-analyzer: 4.10.1
     transitivePeerDependencies:
@@ -16130,11 +16254,13 @@ snapshots:
 
   '@next/env@16.1.7': {}
 
+  '@next/env@16.2.1': {}
+
   '@next/eslint-plugin-next@16.1.6':
     dependencies:
       fast-glob: 3.3.1
 
-  '@next/mdx@16.1.6(@mdx-js/loader@3.1.1(webpack@5.102.1(esbuild@0.27.1)(jiti@2.6.1)))(@mdx-js/react@3.1.1(@types/react@19.2.14)(react@19.2.4))':
+  '@next/mdx@16.2.1(@mdx-js/loader@3.1.1(webpack@5.102.1(esbuild@0.27.1)(jiti@2.6.1)))(@mdx-js/react@3.1.1(@types/react@19.2.14)(react@19.2.4))':
     dependencies:
       source-map: 0.7.6
     optionalDependencies:
@@ -16144,27 +16270,51 @@ snapshots:
   '@next/swc-darwin-arm64@16.1.7':
     optional: true
 
+  '@next/swc-darwin-arm64@16.2.1':
+    optional: true
+
   '@next/swc-darwin-x64@16.1.7':
     optional: true
 
+  '@next/swc-darwin-x64@16.2.1':
+    optional: true
+
   '@next/swc-linux-arm64-gnu@16.1.7':
     optional: true
 
+  '@next/swc-linux-arm64-gnu@16.2.1':
+    optional: true
+
   '@next/swc-linux-arm64-musl@16.1.7':
     optional: true
 
+  '@next/swc-linux-arm64-musl@16.2.1':
+    optional: true
+
   '@next/swc-linux-x64-gnu@16.1.7':
     optional: true
 
+  '@next/swc-linux-x64-gnu@16.2.1':
+    optional: true
+
   '@next/swc-linux-x64-musl@16.1.7':
     optional: true
 
+  '@next/swc-linux-x64-musl@16.2.1':
+    optional: true
+
   '@next/swc-win32-arm64-msvc@16.1.7':
     optional: true
 
+  '@next/swc-win32-arm64-msvc@16.2.1':
+    optional: true
+
   '@next/swc-win32-x64-msvc@16.1.7':
     optional: true
 
+  '@next/swc-win32-x64-msvc@16.2.1':
+    optional: true
+
   '@nicolo-ribaudo/chokidar-2@2.1.8-no-fsevents.3':
     optional: true
 
@@ -16565,6 +16715,10 @@ snapshots:
     dependencies:
       playwright: 1.58.2
 
+  '@playwright/test@1.59.1':
+    dependencies:
+      playwright: 1.59.1
+
   '@pnpm/config.env-replace@1.1.0': {}
 
   '@pnpm/constants@1001.3.1': {}
@@ -18738,13 +18892,27 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@vitest/browser-playwright@4.1.0(playwright@1.58.2)(vite@8.0.0(@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.0)':
+  '@vitest/browser-playwright@4.1.0(playwright@1.59.1)(vite@8.0.0(@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.0)':
     dependencies:
       '@vitest/browser': 4.1.0(vite@8.0.0(@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.0)
       '@vitest/mocker': 4.1.0(vite@8.0.0(@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
-      tinyrainbow: 3.0.3
-      vitest: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(@vitest/ui@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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
+    optional: true
+
+  '@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.0(@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.0)':
+    dependencies:
+      '@vitest/browser': 4.1.3(vite@8.0.0(@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.0)
+      '@vitest/mocker': 4.1.3(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/ui@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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
@@ -18759,8 +18927,26 @@ snapshots:
       magic-string: 0.30.21
       pngjs: 7.0.0
       sirv: 3.0.2
-      tinyrainbow: 3.0.3
-      vitest: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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))
+      tinyrainbow: 3.1.0
+      vitest: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/ui@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.20.0
+    transitivePeerDependencies:
+      - bufferutil
+      - msw
+      - utf-8-validate
+      - vite
+    optional: true
+
+  '@vitest/browser@4.1.3(vite@8.0.0(@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.0)':
+    dependencies:
+      '@blazediff/core': 1.9.1
+      '@vitest/mocker': 4.1.3(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/ui@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.20.0
     transitivePeerDependencies:
       - bufferutil
@@ -18779,8 +18965,8 @@ snapshots:
       magicast: 0.5.2
       obug: 2.1.1
       std-env: 4.0.0
-      tinyrainbow: 3.0.3
-      vitest: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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))
+      tinyrainbow: 3.1.0
+      vitest: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/ui@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(vite@8.0.0(@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.0)
 
@@ -18791,7 +18977,7 @@ snapshots:
       eslint: 10.0.3(jiti@2.6.1)
     optionalDependencies:
       typescript: 5.9.3
-      vitest: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(@vitest/ui@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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:
       - supports-color
 
@@ -18802,7 +18988,7 @@ snapshots:
       '@vitest/spy': 4.1.0
       '@vitest/utils': 4.1.0
       chai: 6.2.2
-      tinyrainbow: 3.0.3
+      tinyrainbow: 3.1.0
 
   '@vitest/mocker@4.1.0(vite@8.0.0(@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:
@@ -18812,13 +18998,21 @@ snapshots:
     optionalDependencies:
       vite: 8.0.0(@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.3(vite@8.0.0(@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.0(@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.0':
     dependencies:
-      tinyrainbow: 3.0.3
+      tinyrainbow: 3.1.0
 
-  '@vitest/pretty-format@4.1.1':
+  '@vitest/pretty-format@4.1.3':
     dependencies:
-      tinyrainbow: 3.0.3
+      tinyrainbow: 3.1.0
 
   '@vitest/runner@4.1.0':
     dependencies:
@@ -18834,17 +19028,31 @@ snapshots:
 
   '@vitest/spy@4.1.0': {}
 
+  '@vitest/spy@4.1.3': {}
+
+  '@vitest/ui@4.1.0(vitest@4.1.0)':
+    dependencies:
+      '@vitest/utils': 4.1.0
+      fflate: 0.8.2
+      flatted: 3.4.0
+      pathe: 2.0.3
+      sirv: 3.0.2
+      tinyglobby: 0.2.15
+      tinyrainbow: 3.1.0
+      vitest: 4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/ui@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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))
+    optional: true
+
   '@vitest/utils@4.1.0':
     dependencies:
       '@vitest/pretty-format': 4.1.0
       convert-source-map: 2.0.0
-      tinyrainbow: 3.0.3
+      tinyrainbow: 3.1.0
 
-  '@vitest/utils@4.1.1':
+  '@vitest/utils@4.1.3':
     dependencies:
-      '@vitest/pretty-format': 4.1.1
+      '@vitest/pretty-format': 4.1.3
       convert-source-map: 2.0.0
-      tinyrainbow: 3.0.3
+      tinyrainbow: 3.1.0
 
   '@webassemblyjs/ast@1.14.1':
     dependencies:
@@ -21085,20 +21293,20 @@ snapshots:
 
   flat-cache@4.0.1:
     dependencies:
-      flatted: 3.3.3
+      flatted: 3.4.0
       keyv: 4.5.4
 
   flat-cache@6.1.20:
     dependencies:
       cacheable: 2.3.2
-      flatted: 3.3.3
+      flatted: 3.4.0
       hookified: 1.15.1
 
   flat@5.0.2: {}
 
   flatqueue@3.0.0: {}
 
-  flatted@3.3.3: {}
+  flatted@3.4.0: {}
 
   follow-redirects@1.15.11(debug@4.4.3):
     optionalDependencies:
@@ -23340,7 +23548,7 @@ snapshots:
 
   neo-async@2.6.2: {}
 
-  next@16.1.7(@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.4(react@19.2.4))(react@19.2.4):
+  next@16.1.7(@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.4(react@19.2.4))(react@19.2.4):
     dependencies:
       '@next/env': 16.1.7
       '@swc/helpers': 0.5.15
@@ -23360,7 +23568,34 @@ snapshots:
       '@next/swc-win32-arm64-msvc': 16.1.7
       '@next/swc-win32-x64-msvc': 16.1.7
       '@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:
+      - '@babel/core'
+      - babel-plugin-macros
+
+  next@16.2.1(@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.4(react@19.2.4))(react@19.2.4):
+    dependencies:
+      '@next/env': 16.2.1
+      '@swc/helpers': 0.5.15
+      baseline-browser-mapping: 2.10.7
+      caniuse-lite: 1.0.30001780
+      postcss: 8.4.31
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      styled-jsx: 5.1.6(@babel/core@7.29.0)(babel-plugin-macros@3.1.0)(react@19.2.4)
+    optionalDependencies:
+      '@next/swc-darwin-arm64': 16.2.1
+      '@next/swc-darwin-x64': 16.2.1
+      '@next/swc-linux-arm64-gnu': 16.2.1
+      '@next/swc-linux-arm64-musl': 16.2.1
+      '@next/swc-linux-x64-gnu': 16.2.1
+      '@next/swc-linux-x64-musl': 16.2.1
+      '@next/swc-win32-arm64-msvc': 16.2.1
+      '@next/swc-win32-x64-msvc': 16.2.1
+      '@opentelemetry/api': 1.9.0
+      '@playwright/test': 1.59.1
       babel-plugin-react-compiler: 1.0.0
       sharp: 0.34.5
     transitivePeerDependencies:
@@ -24020,12 +24255,20 @@ snapshots:
 
   playwright-core@1.58.2: {}
 
+  playwright-core@1.59.1: {}
+
   playwright@1.58.2:
     dependencies:
       playwright-core: 1.58.2
     optionalDependencies:
       fsevents: 2.3.2
 
+  playwright@1.59.1:
+    dependencies:
+      playwright-core: 1.59.1
+    optionalDependencies:
+      fsevents: 2.3.2
+
   pluralize@3.1.0: {}
 
   pngjs@7.0.0: {}
@@ -25524,7 +25767,7 @@ snapshots:
       fdir: 6.5.0(picomatch@4.0.3)
       picomatch: 4.0.3
 
-  tinyrainbow@3.0.3: {}
+  tinyrainbow@3.1.0: {}
 
   title@4.0.1:
     dependencies:
@@ -25953,14 +26196,45 @@ snapshots:
       tsx: 4.21.0
       yaml: 2.8.1
 
-  vitest-fail-on-console@0.10.1(@vitest/utils@4.1.1)(vite@8.0.0(@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.0):
+  vitest-fail-on-console@0.10.1(@vitest/utils@4.1.3)(vite@8.0.0(@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.0):
     dependencies:
-      '@vitest/utils': 4.1.1
+      '@vitest/utils': 4.1.3
       chalk: 5.6.2
       vite: 8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(@vitest/ui@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(@vitest/ui@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0
+      '@vitest/mocker': 4.1.0(vite@8.0.0(@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.0
+      '@vitest/runner': 4.1.0
+      '@vitest/snapshot': 4.1.0
+      '@vitest/spy': 4.1.0
+      '@vitest/utils': 4.1.0
+      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.3
+      std-env: 4.0.0
+      tinybench: 2.9.0
+      tinyexec: 1.0.2
+      tinyglobby: 0.2.15
+      tinyrainbow: 3.1.0
+      vite: 8.0.0(@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.0(playwright@1.59.1)(vite@8.0.0(@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.0)
+      '@vitest/ui': 4.1.0(vitest@4.1.0)
+      jsdom: 28.1.0
+    transitivePeerDependencies:
+      - msw
 
-  vitest@4.1.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(@vitest/ui@4.1.0)(jsdom@28.1.0)(vite@8.0.0(@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.0
       '@vitest/mocker': 4.1.0(vite@8.0.0(@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))
@@ -25979,13 +26253,14 @@ snapshots:
       tinybench: 2.9.0
       tinyexec: 1.0.2
       tinyglobby: 0.2.15
-      tinyrainbow: 3.0.3
+      tinyrainbow: 3.1.0
       vite: 8.0.0(@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.0(playwright@1.58.2)(vite@8.0.0(@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.0)
+      '@vitest/browser-playwright': 4.1.3(playwright@1.59.1)(vite@8.0.0(@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.0)
+      '@vitest/ui': 4.1.0(vitest@4.1.0)
       jsdom: 28.1.0
     transitivePeerDependencies:
       - msw

From 7a208b4c4145cbc1c03a6bb499c6dd89f28c7f51 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 10 Apr 2026 15:13:18 -0400
Subject: [PATCH 13/45] Prettier

---
 .../docs-infra/overview/contributing/page.mdx | 26 +++++++++----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/app/docs-infra/overview/contributing/page.mdx b/docs/app/docs-infra/overview/contributing/page.mdx
index 7985cd568..1d80433bf 100644
--- a/docs/app/docs-infra/overview/contributing/page.mdx
+++ b/docs/app/docs-infra/overview/contributing/page.mdx
@@ -30,19 +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                           |
-| `pnpm test:browser --run` | Run browser tests (requires podman/docker)       |
-| `pnpm test:browser:unconfined`   | Run browser tests directly (CI/Playwright image) |
+| 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.

From 72ef791dd30321d57968b66f76b46a3db98266d7 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 21 Apr 2026 21:09:29 -0400
Subject: [PATCH 14/45] Optimize useEditable

---
 package.json                                  |  2 +-
 .../src/useCode/useEditable.test.ts           | 51 +++++++++++++++++++
 .../docs-infra/src/useCode/useEditable.ts     | 51 ++++++++-----------
 pnpm-lock.yaml                                | 42 ++++++++-------
 4 files changed, 92 insertions(+), 54 deletions(-)

diff --git a/package.json b/package.json
index e83ff9d99..9bd6d0dc7 100644
--- a/package.json
+++ b/package.json
@@ -90,7 +90,7 @@
     "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/src/useCode/useEditable.test.ts b/packages/docs-infra/src/useCode/useEditable.test.ts
index 35a6ca612..8e73d8289 100644
--- a/packages/docs-infra/src/useCode/useEditable.test.ts
+++ b/packages/docs-infra/src/useCode/useEditable.test.ts
@@ -308,6 +308,57 @@ describe('useEditable', () => {
       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 = [
diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 7fc6e728d..51864e5fb 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -30,6 +30,7 @@ SOFTWARE.
 // Changes:
 // - Fix linting and formatting
 // - Add Tests
+// - Replace manual queue-based DFS in makeRange with TreeWalker for better performance
 
 import * as React from 'react';
 
@@ -173,43 +174,31 @@ const makeRange = (element: HTMLElement, start: number, end?: number): Range =>
   }
 
   const range = document.createRange();
-  const queue: Node[] = [element.firstChild!];
+  const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
   let current = 0;
-
   let position = start;
-  while (queue.length > 0) {
-    const node = queue[queue.length - 1];
-    if (!node) {
-      break;
-    }
-    if (node.nodeType === Node.TEXT_NODE) {
-      const length = node.textContent!.length;
-      if (current + length >= position) {
-        const offset = position - current;
-        if (position === start) {
-          setStart(range, node, offset);
-          if (end !== start) {
-            position = end;
-            continue;
-          } else {
-            break;
-          }
-        } else {
-          setEnd(range, node, offset);
+
+  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 += node.textContent!.length;
-    }
-
-    queue.pop();
-    if (node.nextSibling) {
-      queue.push(node.nextSibling);
-    }
-    if (node.firstChild) {
-      queue.push(node.firstChild);
     }
+    current += length;
   }
 
   return range;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7f111595f..f446c4cec 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -88,7 +88,7 @@ importers:
         version: 7.27.1(@babel/core@7.29.0)
       '@vitest/browser-playwright':
         specifier: 4.1.3
-        version: 4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+        version: 4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       baseline-browser-mapping:
         specifier: 2.10.10
         version: 2.10.10
@@ -102,8 +102,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)
@@ -436,7 +436,7 @@ importers:
         version: 6.0.1(babel-plugin-react-compiler@1.0.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+        version: 4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       env-ci:
         specifier: ^11.2.0
         version: 11.2.0
@@ -598,7 +598,7 @@ importers:
         version: 7.0.0-dev.20260317.1
       '@vitest/eslint-plugin':
         specifier: ^1.6.11
-        version: 1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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: 1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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)))
       babel-plugin-optimize-clsx:
         specifier: ^2.6.2
         version: 2.6.2
@@ -679,7 +679,7 @@ importers:
         version: 16.1.1
       html-validate:
         specifier: ^10.11.2
-        version: 10.11.2(jest-diff@30.2.0)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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: 10.11.2(jest-diff@30.2.0)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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)))
       minimatch:
         specifier: ^10.2.4
         version: 10.2.5
@@ -1064,7 +1064,7 @@ importers:
         version: 19.2.14
       '@vitest/browser-playwright':
         specifier: 4.1.1
-        version: 4.1.1(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+        version: 4.1.1(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       vitest:
         specifier: 4.1.1
         version: 4.1.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.1)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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))
@@ -19362,11 +19362,11 @@ snapshots:
     optionalDependencies:
       babel-plugin-react-compiler: 1.0.0
 
-  '@vitest/browser-playwright@4.1.1(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)':
+  '@vitest/browser-playwright@4.1.1(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)':
     dependencies:
       '@vitest/browser': 4.1.1(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       '@vitest/mocker': 4.1.1(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.1)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
@@ -19375,11 +19375,11 @@ snapshots:
       - utf-8-validate
       - vite
 
-  '@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)':
+  '@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)':
     dependencies:
       '@vitest/browser': 4.1.3(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       '@vitest/mocker': 4.1.3(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
@@ -19436,14 +19436,14 @@ snapshots:
       tinyrainbow: 3.1.0
       vitest: 4.1.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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/eslint-plugin@1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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/eslint-plugin@1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
       '@typescript-eslint/scope-manager': 8.57.1
       '@typescript-eslint/utils': 8.57.1(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)
       eslint: 10.0.3(jiti@2.6.1)
     optionalDependencies:
       typescript: 5.9.3
-      vitest: 4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
       - supports-color
 
@@ -22485,7 +22485,7 @@ snapshots:
       readable-stream: 1.0.34
       through2: 0.4.2
 
-  html-validate@10.11.2(jest-diff@30.2.0)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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))):
+  html-validate@10.11.2(jest-diff@30.2.0)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
       '@html-validate/stylish': 5.0.0
       '@sidvind/better-ajv-errors': 4.0.1(ajv@8.18.0)
@@ -22497,7 +22497,7 @@ snapshots:
       semver: 7.7.4
     optionalDependencies:
       jest-diff: 30.2.0
-      vitest: 4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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))
 
   html-void-elements@3.0.0: {}
 
@@ -24853,8 +24853,7 @@ snapshots:
 
   playwright-core@1.58.2: {}
 
-  playwright-core@1.59.1:
-    optional: true
+  playwright-core@1.59.1: {}
 
   playwright@1.58.2:
     dependencies:
@@ -24867,7 +24866,6 @@ snapshots:
       playwright-core: 1.59.1
     optionalDependencies:
       fsevents: 2.3.2
-    optional: true
 
   pluralize@3.1.0: {}
 
@@ -26939,7 +26937,7 @@ snapshots:
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
       '@types/node': 22.19.0
-      '@vitest/browser-playwright': 4.1.1(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+      '@vitest/browser-playwright': 4.1.1(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       jsdom: 28.1.0
     transitivePeerDependencies:
       - msw
@@ -26969,12 +26967,12 @@ snapshots:
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
       '@types/node': 22.19.0
-      '@vitest/browser-playwright': 4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+      '@vitest/browser-playwright': 4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       jsdom: 28.1.0
     transitivePeerDependencies:
       - msw
 
-  vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.4
       '@vitest/mocker': 4.1.4(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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))
@@ -26999,7 +26997,7 @@ snapshots:
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
       '@types/node': 22.19.0
-      '@vitest/browser-playwright': 4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+      '@vitest/browser-playwright': 4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       '@vitest/coverage-v8': 4.1.2(vitest@4.1.1)
       jsdom: 28.1.0
     transitivePeerDependencies:

From 8c769cfd8421e1da230e32910eb48af2f2ba2b7a Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 09:46:36 -0400
Subject: [PATCH 15/45] Fix issue when holding down key on Firefox

---
 .../src/useCode/useEditable.test.ts           | 91 +++++++++++++++++++
 .../docs-infra/src/useCode/useEditable.ts     | 90 +++++++++++++++---
 2 files changed, 169 insertions(+), 12 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.test.ts b/packages/docs-infra/src/useCode/useEditable.test.ts
index 8e73d8289..ec9326aca 100644
--- a/packages/docs-infra/src/useCode/useEditable.test.ts
+++ b/packages/docs-infra/src/useCode/useEditable.test.ts
@@ -775,6 +775,97 @@ describe('useEditable', () => {
         '',
       ]);
     });
+
+    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', '']);
+    });
   });
 
   // ---------------------------------------------------------------------------
diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 51864e5fb..2659b91c3 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -31,6 +31,10 @@ SOFTWARE.
 // - Fix linting and formatting
 // - Add Tests
 // - Replace manual queue-based DFS in makeRange with TreeWalker for better performance
+// - Replace Range.toString() in getPosition with a TreeWalker character count to avoid O(N) string allocation
+// - Deduplicate toString() calls via trackState return value
+// - Fix Firefox rapid-typing line-loss bug: preserve pre-edit pendingContent across key-repeat keydowns
+// - Debounce repeat-key flushes so highlights only re-render once the user pauses typing
 
 import * as React from 'react';
 
@@ -149,11 +153,46 @@ const setEnd = (range: Range, node: Node, offset: number) => {
 };
 
 const getPosition = (element: HTMLElement): Position => {
-  // Firefox Quirk: Since plaintext-only is unsupported the position
-  // of the text here is retrieved via a range, rather than traversal
-  // as seen in makeRange()
   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);
@@ -276,6 +315,8 @@ interface State {
   history: History[];
   historyAt: number;
   position: Position | null;
+  /** setTimeout id used to debounce flushChanges() calls during key-repeat */
+  repeatFlushId: ReturnType<typeof setTimeout> | null;
 }
 
 export interface Options {
@@ -314,6 +355,7 @@ export const useEditable = (
       history: [],
       historyAt: -1,
       position: null,
+      repeatFlushId: null,
     };
 
     if (typeof MutationObserver !== 'undefined') {
@@ -461,9 +503,9 @@ export const useEditable = (
     const blanklineRe = new RegExp(`^(?:${indentPattern})*(${indentPattern})$`);
 
     let trackStateTimestamp: number;
-    const trackState = (ignoreTimestamp?: boolean) => {
+    const trackState = (ignoreTimestamp?: boolean): string | null => {
       if (!elementRef.current || !state.position) {
-        return;
+        return null;
       }
 
       const content = toString(element);
@@ -477,7 +519,7 @@ export const useEditable = (
         (lastEntry && lastEntry[1] === content)
       ) {
         trackStateTimestamp = timestamp;
-        return;
+        return content;
       }
 
       state.historyAt += 1;
@@ -488,6 +530,7 @@ export const useEditable = (
         state.historyAt -= 1;
         state.history.shift();
       }
+      return content;
     };
 
     const disconnect = () => {
@@ -569,8 +612,14 @@ export const useEditable = (
         return;
       }
 
-      trackState();
-      state.pendingContent = toString(element);
+      // Only capture the pre-edit snapshot on the first keydown in a key-repeat
+      // sequence. Repeated keydowns must NOT overwrite pendingContent because the DOM
+      // may already contain a Firefox-merged state after the first keystroke. If we
+      // overwrote pendingContent here, repairUnexpectedLineMerge would receive the
+      // merged DOM as the "previous" content and could not detect that a line was lost.
+      if (!event.repeat || state.pendingContent === null) {
+        state.pendingContent = trackState() ?? toString(element);
+      }
 
       if (event.key === 'Enter') {
         event.preventDefault();
@@ -616,9 +665,18 @@ export const useEditable = (
         edit.update(newContent);
       }
 
-      // Flush changes as a key is held so the app can catch up
+      // 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) {
-        flushChanges();
+        if (state.repeatFlushId !== null) {
+          clearTimeout(state.repeatFlushId);
+        }
+        state.repeatFlushId = setTimeout(() => {
+          state.repeatFlushId = null;
+          flushChanges();
+        }, 100);
       }
     };
 
@@ -626,6 +684,11 @@ export const useEditable = (
       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;
+      }
       if (!isUndoRedoKey(event)) {
         trackState();
       }
@@ -642,8 +705,7 @@ export const useEditable = (
 
     const onPaste = (event: HTMLElementEventMap['paste']) => {
       event.preventDefault();
-      trackState(true);
-      state.pendingContent = toString(element);
+      state.pendingContent = trackState(true) ?? toString(element);
       edit.insert(event.clipboardData!.getData('text/plain'));
       trackState(true);
       flushChanges();
@@ -655,6 +717,10 @@ export const useEditable = (
     element.addEventListener('keyup', onKeyUp);
 
     return () => {
+      if (state.repeatFlushId !== null) {
+        clearTimeout(state.repeatFlushId);
+        state.repeatFlushId = null;
+      }
       document.removeEventListener('selectstart', onSelect);
       window.removeEventListener('keydown', onKeyDown);
       element.removeEventListener('paste', onPaste);

From 5ced874908b9c828f3afeb49d34fe36d30e80f8f Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 09:46:47 -0400
Subject: [PATCH 16/45] Add benchmark

---
 .../demos/code/index.ts                       |  4 +++
 .../demos/code/page.tsx                       | 27 +++++++++++++++++++
 .../code-controller-context/page.mdx          | 10 +++++++
 .../code-controller-context/bench/page.mdx    |  5 ++++
 .../code-controller-context/page.mdx          |  4 +++
 docs/app/docs-infra/components/page.mdx       |  1 +
 6 files changed, 51 insertions(+)
 create mode 100644 docs/app/bench/docs-infra/components/code-controller-context/demos/code/index.ts
 create mode 100644 docs/app/bench/docs-infra/components/code-controller-context/demos/code/page.tsx
 create mode 100644 docs/app/bench/docs-infra/components/code-controller-context/page.mdx
 create mode 100644 docs/app/docs-infra/components/code-controller-context/bench/page.mdx

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..11f5bb8cf
--- /dev/null
+++ b/docs/app/bench/docs-infra/components/code-controller-context/demos/code/page.tsx
@@ -0,0 +1,27 @@
+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 (
+    <CodeProvider>
+      <CodeController>
+        <CodeHighlighter
+          Content={CodeEditorContent}
+          controlled
+          sourceParser={sourceParser}
+          fileName="large-file.js"
+        >
+          {code}
+        </CodeHighlighter>
+      </CodeController>
+    </CodeProvider>
+  );
+}
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/page.mdx b/docs/app/docs-infra/components/code-controller-context/page.mdx
index 7d1b2fcae..912cd1393 100644
--- a/docs/app/docs-infra/components/code-controller-context/page.mdx
+++ b/docs/app/docs-infra/components/code-controller-context/page.mdx
@@ -297,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/page.mdx b/docs/app/docs-infra/components/page.mdx
index 078df971a..8ab80887f 100644
--- a/docs/app/docs-infra/components/page.mdx
+++ b/docs/app/docs-infra/components/page.mdx
@@ -117,6 +117,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

From cb69ffe372c0030da5c074a6ec9334c004149be1 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 10:14:02 -0400
Subject: [PATCH 17/45] Fix cursor shifting

---
 package.json                                  |    4 +-
 .../src/useCode/useEditable.test.ts           |   61 +
 .../docs-infra/src/useCode/useEditable.ts     |    7 +-
 pnpm-lock.yaml                                | 1493 ++++++++---------
 4 files changed, 814 insertions(+), 751 deletions(-)

diff --git a/package.json b/package.json
index 9bd6d0dc7..db69dafc9 100644
--- a/package.json
+++ b/package.json
@@ -10,7 +10,7 @@
     "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": "pnpm -F \"./docs\" run docs-infra browser --workspace --script test:browser:unconfined --playwright-version 1.58.2 --",
     "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",
@@ -90,7 +90,7 @@
     "eslint-plugin-n": "17.24.0",
     "markdownlint-cli2": "0.22.0",
     "pkg-pr-new": "0.0.66",
-    "playwright": "1.59.1",
+    "playwright": "1.58.2",
     "stylelint": "17.4.0"
   },
   "packageManager": "pnpm@10.32.1",
diff --git a/packages/docs-infra/src/useCode/useEditable.test.ts b/packages/docs-infra/src/useCode/useEditable.test.ts
index ec9326aca..628fdd626 100644
--- a/packages/docs-infra/src/useCode/useEditable.test.ts
+++ b/packages/docs-infra/src/useCode/useEditable.test.ts
@@ -1082,5 +1082,66 @@ describe('useEditable', () => {
 
       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
index 2659b91c3..8816cffea 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -445,7 +445,12 @@ export const useEditable = (
 
     state.disconnected = false;
     state.observer.observe(elementRef.current, observerSettings);
-    if (state.position) {
+    // 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.
+    if (state.position && state.repeatFlushId === null) {
       const { position, extent } = state.position;
       const cursorRange = makeRange(elementRef.current, position, position + extent);
       adjustCursorAtNewlineBoundary(cursorRange);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f446c4cec..dd214005a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -18,7 +18,7 @@ importers:
         version: 3.0.0
       '@actions/github':
         specifier: ^9.0.0
-        version: 9.0.0
+        version: 9.1.0
       '@eslint/compat':
         specifier: ^2.0.3
         version: 2.0.3(eslint@10.0.3(jiti@2.6.1))
@@ -54,7 +54,7 @@ importers:
         version: 8.57.1(eslint@10.0.3(jiti@2.6.1))(typescript@6.0.2)
       '@typescript/native-preview':
         specifier: ^7.0.0-dev.20260314.1
-        version: 7.0.0-dev.20260317.1
+        version: 7.0.0-dev.20260419.1
       '@vitest/coverage-v8':
         specifier: ^4.1.1
         version: 4.1.2(vitest@4.1.1)
@@ -88,7 +88,7 @@ importers:
         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.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+        version: 4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       baseline-browser-mapping:
         specifier: 2.10.10
         version: 2.10.10
@@ -102,8 +102,8 @@ importers:
         specifier: 0.0.66
         version: 0.0.66
       playwright:
-        specifier: 1.59.1
-        version: 1.59.1
+        specifier: 1.58.2
+        version: 1.58.2
       stylelint:
         specifier: 17.4.0
         version: 17.4.0(typescript@6.0.2)
@@ -112,7 +112,7 @@ importers:
     dependencies:
       '@aws-sdk/client-s3':
         specifier: ^3.1009.0
-        version: 3.1009.0
+        version: 3.1032.0
       '@emotion/cache':
         specifier: ^11.14.0
         version: 11.14.0
@@ -133,7 +133,7 @@ importers:
         version: 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@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.4))(@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.4(react@19.2.4))(react@19.2.4))(react@19.2.4)
+        version: 9.0.0-alpha.2(@emotion/cache@11.14.0)(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@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.4(react@19.2.4))(react@19.2.4))(react@19.2.4)
       '@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.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -142,7 +142,7 @@ importers:
         version: 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/x-date-pickers-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.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+        version: 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/x-license':
         specifier: ^8.26.0
         version: 8.26.0(@types/react@19.2.14)(react@19.2.4)
@@ -157,7 +157,7 @@ importers:
         version: 22.0.1
       '@tanstack/react-query':
         specifier: ^5.95.2
-        version: 5.95.2(react@19.2.4)
+        version: 5.99.1(react@19.2.4)
       dayjs:
         specifier: ^1.11.20
         version: 1.11.20
@@ -175,7 +175,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.59.1)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+        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.4(react@19.2.4))(react@19.2.4)
       pako:
         specifier: ^2.1.0
         version: 2.1.0
@@ -239,7 +239,7 @@ importers:
         version: 7.0.6
       '@toolpad/studio':
         specifier: ^0.13.0
-        version: 0.13.0(@mui/x-data-grid-pro@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@types/react@19.2.14)(encoding@0.1.13)(eslint@10.0.3(jiti@2.6.1))(jiti@2.6.1)(lightningcss@1.32.0)(luxon@3.7.2)(terser@5.44.0)(webpack@5.102.1(esbuild@0.27.1)(jiti@2.6.1))
+        version: 0.13.0(@mui/x-data-grid-pro@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(encoding@0.1.13)(eslint@10.0.3(jiti@2.6.1))(jiti@2.6.1)(lightningcss@1.32.0)(luxon@3.7.2)(terser@5.44.0)(webpack@5.102.1(esbuild@0.27.1)(jiti@2.6.1))
       dayjs:
         specifier: ^1.11.20
         version: 1.11.20
@@ -285,7 +285,7 @@ importers:
         version: link:../packages/docs-infra/build
       '@next/mdx':
         specifier: ^16.1.6
-        version: 16.2.1(@mdx-js/loader@3.1.1(webpack@5.102.1(esbuild@0.27.1)(jiti@2.6.1)))(@mdx-js/react@3.1.1(@types/react@19.2.14)(react@19.2.4))
+        version: 16.1.6(@mdx-js/loader@3.1.1(webpack@5.102.1(esbuild@0.27.1)(jiti@2.6.1)))(@mdx-js/react@3.1.1(@types/react@19.2.14)(react@19.2.4))
       '@types/mdx':
         specifier: ^2.0.13
         version: 2.0.13
@@ -294,7 +294,7 @@ importers:
         version: 0.577.0(react@19.2.4)
       next:
         specifier: ^16.1.6
-        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.4(react@19.2.4))(react@19.2.4)
+        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.4(react@19.2.4))(react@19.2.4)
       react:
         specifier: ^19.2.4
         version: 19.2.4
@@ -399,7 +399,7 @@ importers:
     dependencies:
       resolve:
         specifier: ^1.22.11
-        version: 1.22.11
+        version: 1.22.12
     devDependencies:
       '@babel/core':
         specifier: 7.29.0
@@ -436,7 +436,7 @@ importers:
         version: 6.0.1(babel-plugin-react-compiler@1.0.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+        version: 4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       env-ci:
         specifier: ^11.2.0
         version: 11.2.0
@@ -517,7 +517,7 @@ importers:
     dependencies:
       '@argos-ci/core':
         specifier: ^5.1.2
-        version: 5.1.3
+        version: 5.2.1
       '@babel/cli':
         specifier: ^7.28.6
         version: 7.28.6(@babel/core@7.29.0)
@@ -556,10 +556,10 @@ importers:
         version: 1.1.0
       '@inquirer/confirm':
         specifier: ^6.0.10
-        version: 6.0.10(@types/node@22.19.0)
+        version: 6.0.11(@types/node@22.19.0)
       '@inquirer/select':
         specifier: ^5.1.2
-        version: 5.1.2(@types/node@22.19.0)
+        version: 5.1.3(@types/node@22.19.0)
       '@mui/internal-babel-plugin-display-name':
         specifier: workspace:*
         version: link:../babel-plugin-display-name
@@ -595,10 +595,10 @@ importers:
         version: 8.57.1(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)
       '@typescript/native-preview':
         specifier: '>=7.0.0-dev.0'
-        version: 7.0.0-dev.20260317.1
+        version: 7.0.0-dev.20260419.1
       '@vitest/eslint-plugin':
         specifier: ^1.6.11
-        version: 1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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: 1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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)))
       babel-plugin-optimize-clsx:
         specifier: ^2.6.2
         version: 2.6.2
@@ -673,13 +673,13 @@ importers:
         version: 16.1.0
       globals:
         specifier: ^17.4.0
-        version: 17.4.0
+        version: 17.5.0
       globby:
         specifier: ^16.1.1
         version: 16.1.1
       html-validate:
         specifier: ^10.11.2
-        version: 10.11.2(jest-diff@30.2.0)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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: 10.13.1(jest-diff@30.2.0)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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)))
       minimatch:
         specifier: ^10.2.4
         version: 10.2.5
@@ -927,7 +927,7 @@ 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.59.1)(babel-plugin-macros@3.1.0)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+        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.4(react@19.2.4))(react@19.2.4)
       react:
         specifier: 19.2.4
         version: 19.2.4
@@ -1064,7 +1064,7 @@ importers:
         version: 19.2.14
       '@vitest/browser-playwright':
         specifier: 4.1.1
-        version: 4.1.1(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+        version: 4.1.1(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       vitest:
         specifier: 4.1.1
         version: 4.1.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.1)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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))
@@ -1088,8 +1088,8 @@ packages:
   '@actions/exec@3.0.0':
     resolution: {integrity: sha512-6xH/puSoNBXb72VPlZVm7vQ+svQpFyA96qdDBvhB8eNZOE8LtPf9L4oAsfzK/crCL8YZ+19fKYVnM63Sl+Xzlw==}
 
-  '@actions/github@9.0.0':
-    resolution: {integrity: sha512-yJ0RoswsAaKcvkmpCE4XxBRiy/whH2SdTBHWzs0gi4wkqTDhXMChjSdqBz/F4AeiDlP28rQqL33iHb+kjAMX6w==}
+  '@actions/github@9.1.0':
+    resolution: {integrity: sha512-u0hDGQeCS+7VNoLA8hYG65RLdPLMaPGfka0sZ0up7P0AiShqfX6xcuXNteGkQ7X7Tod7AMNwHd4p7DS63i8zzA==}
 
   '@actions/http-client@3.0.2':
     resolution: {integrity: sha512-JP38FYYpyqvUsz+Igqlc/JG6YO9PaKuvqjM3iGvaLqFnJ7TFmcLyy2IDrY0bI0qCQug8E9K+elv5ZNfw62ZJzA==}
@@ -1100,12 +1100,12 @@ packages:
   '@actions/io@3.0.2':
     resolution: {integrity: sha512-nRBchcMM+QK1pdjO7/idu86rbJI5YHUKCvKs0KxnSYbVe3F51UfGxuZX4Qy/fWlp6l7gWFwIkrOzN+oUK03kfw==}
 
-  '@argos-ci/api-client@0.16.1':
-    resolution: {integrity: sha512-lu8eX3lPMXfAQGFqlhkFM1Av75X/IZz2QzrUvAiWS2ltnMm7ROFTgn6pwaSiXmNj53Dd8hr+FqSMjssbMYk6Ag==}
+  '@argos-ci/api-client@0.18.0':
+    resolution: {integrity: sha512-64vK5Bar20C4CT2MidiFQKc/bfw66VNcGKy7i6+WBSA502yRPLGw0163CWL1/+0Tb0thOxB04KoAxcOEN/CjuA==}
     engines: {node: '>=20.0.0'}
 
-  '@argos-ci/core@5.1.3':
-    resolution: {integrity: sha512-Fx3/Pa6zBvsuF8IxCVh6W36NMzzC8HkZHl7jMibJGj90qVzcc/Q0GeZLFt5jiKZGJe5qcV4wXUgMbbWyCTiA7g==}
+  '@argos-ci/core@5.2.1':
+    resolution: {integrity: sha512-aOPB/dat46Qa6zqRyD7QS/ewxYKNTkqpAyVvA8qnfFGYM8dQ7M+MMmiQELsybMt6hRORZ+1n1r1dzVOMGvAeRQ==}
     engines: {node: '>=20.0.0'}
 
   '@argos-ci/util@3.4.0':
@@ -1159,127 +1159,127 @@ packages:
   '@aws-crypto/util@5.2.0':
     resolution: {integrity: sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ==}
 
-  '@aws-sdk/client-s3@3.1009.0':
-    resolution: {integrity: sha512-luy8CxallkoiGWTqU86ca/BbvkWJjs0oala7uIIRN1JtQxMb5i4Yl/PBZVcQFhbK9kQi0PK0GfD8gIpLkI91fw==}
+  '@aws-sdk/client-s3@3.1032.0':
+    resolution: {integrity: sha512-A1wjVhV3IgsZ5td2l4AWgK03EjZ+ldwbiorxuO1hPf7RHJtSdr6oq/gKzyUwP7Tm7ma/M2xS/tplg5C8XB8RWg==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/core@3.973.20':
-    resolution: {integrity: sha512-i3GuX+lowD892F3IuJf8o6AbyDupMTdyTxQrCJGcn71ni5hTZ82L4nQhcdumxZ7XPJRJJVHS/CR3uYOIIs0PVA==}
+  '@aws-sdk/core@3.974.1':
+    resolution: {integrity: sha512-gy/gffKz0zaHDaqRiLCdIvgHmaAL/HXuAtMcBP7euYSFx4BsbsdlfmUBJag+Gqe62z6/XuloKyQyaiH+kS3Vrg==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/crc64-nvme@3.972.5':
-    resolution: {integrity: sha512-2VbTstbjKdT+yKi8m7b3a9CiVac+pL/IY2PHJwsaGkkHmuuqkJZIErPck1h6P3T9ghQMLSdMPyW6Qp7Di5swFg==}
+  '@aws-sdk/crc64-nvme@3.972.7':
+    resolution: {integrity: sha512-QUagVVBbC8gODCF6e1aV0mE2TXWB9Opz4k8EJFdNrujUVQm5R4AjJa1mpOqzwOuROBzqJU9zawzig7M96L8Ejg==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/credential-provider-env@3.972.18':
-    resolution: {integrity: sha512-X0B8AlQY507i5DwjLByeU2Af4ARsl9Vr84koDcXCbAkplmU+1xBFWxEPrWRAoh56waBne/yJqEloSwvRf4x6XA==}
+  '@aws-sdk/credential-provider-env@3.972.27':
+    resolution: {integrity: sha512-xfUt2CUZDC+Tf16A6roD1b4pk/nrXdkoLY3TEhv198AXDtBo5xUJP1zd0e8SmuKLN4PpIBX96OizZbmMlcI6oQ==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/credential-provider-http@3.972.20':
-    resolution: {integrity: sha512-ey9Lelj001+oOfrbKmS6R2CJAiXX7QKY4Vj9VJv6L2eE6/VjD8DocHIoYqztTm70xDLR4E1jYPTKfIui+eRNDA==}
+  '@aws-sdk/credential-provider-http@3.972.29':
+    resolution: {integrity: sha512-hjNeYb6oLyHgMihra83ie0J/T2y9om3cy1qC90h9DRgvYXEoN4BCFf8bHguZjKhXunnv7YkmZRuYL5Mkk77eCA==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/credential-provider-ini@3.972.20':
-    resolution: {integrity: sha512-5flXSnKHMloObNF+9N0cupKegnH1Z37cdVlpETVgx8/rAhCe+VNlkcZH3HDg2SDn9bI765S+rhNPXGDJJPfbtA==}
+  '@aws-sdk/credential-provider-ini@3.972.31':
+    resolution: {integrity: sha512-PuQ7e8WYzAPpzvFcajxf8c0LqSzakVHVlKw8M0oubk8Kf347YOCCqT1seQrHs5AdZuIh2RD9LX4O+Xa5ImEBfQ==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/credential-provider-login@3.972.20':
-    resolution: {integrity: sha512-gEWo54nfqp2jABMu6HNsjVC4hDLpg9HC8IKSJnp0kqWtxIJYHTmiLSsIfI4ScQjxEwpB+jOOH8dOLax1+hy/Hw==}
+  '@aws-sdk/credential-provider-login@3.972.31':
+    resolution: {integrity: sha512-bBmWDmtSpmLOZR6a0kmowBcVL1hiL8Vlap/RXeMpFd7JbWl87YcwqL6T9LH/0oBVEZXu1dUZAtojgSuZgMO5xw==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/credential-provider-node@3.972.21':
-    resolution: {integrity: sha512-hah8if3/B/Q+LBYN5FukyQ1Mym6PLPDsBOBsIgNEYD6wLyZg0UmUF/OKIVC3nX9XH8TfTPuITK+7N/jenVACWA==}
+  '@aws-sdk/credential-provider-node@3.972.32':
+    resolution: {integrity: sha512-9aj0x9hGYUondBZSD0XkksAdHhOKttFw4BWpLCeggeg40qSJxGrAP++g0GCm0VqWc1WtC/NRFiAVzPCy56vmog==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/credential-provider-process@3.972.18':
-    resolution: {integrity: sha512-Tpl7SRaPoOLT32jbTWchPsn52hYYgJ0kpiFgnwk8pxTANQdUymVSZkzFvv1+oOgZm1CrbQUP9MBeoMZ9IzLZjA==}
+  '@aws-sdk/credential-provider-process@3.972.27':
+    resolution: {integrity: sha512-1CZvfb1WzudWWIFAVQkd1OI/T1RxPcSvNWzNsb2BMBVsBJzBtB8dV5f2nymHVU4UqwxipdVt/DAbgdDRf33JDg==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/credential-provider-sso@3.972.20':
-    resolution: {integrity: sha512-p+R+PYR5Z7Gjqf/6pvbCnzEHcqPCpLzR7Yf127HjJ6EAb4hUcD+qsNRnuww1sB/RmSeCLxyay8FMyqREw4p1RA==}
+  '@aws-sdk/credential-provider-sso@3.972.31':
+    resolution: {integrity: sha512-x8Mx18S48XMl9bEEpYwmXDTvjWGPIfDadReN37Lc099/DUrlL4Zs9T9rwwggo6DkKS1aev6v+MTUx7JTa87TZQ==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/credential-provider-web-identity@3.972.20':
-    resolution: {integrity: sha512-rWCmh8o7QY4CsUj63qopzMzkDq/yPpkrpb+CnjBEFSOg/02T/we7sSTVg4QsDiVS9uwZ8VyONhq98qt+pIh3KA==}
+  '@aws-sdk/credential-provider-web-identity@3.972.31':
+    resolution: {integrity: sha512-zfuNMIkGfjYsHis9qytYf74Bcmq6Ji9Xwf4w53baRCI/b2otTwZv3SW1uRiJ5Di7999QzRGhHZ96+eUeo3gSOA==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/middleware-bucket-endpoint@3.972.8':
-    resolution: {integrity: sha512-WR525Rr2QJSETa9a050isktyWi/4yIGcmY3BQ1kpHqb0LqUglQHCS8R27dTJxxWNZvQ0RVGtEZjTCbZJpyF3Aw==}
+  '@aws-sdk/middleware-bucket-endpoint@3.972.10':
+    resolution: {integrity: sha512-Vbc2frZH7wXlMNd+ZZSXUEs/l1Sv8Jj4zUnIfwrYF5lwaLdXHZ9xx4U3rjUcaye3HRhFVc+E5DbBxpRAbB16BA==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/middleware-expect-continue@3.972.8':
-    resolution: {integrity: sha512-5DTBTiotEES1e2jOHAq//zyzCjeMB78lEHd35u15qnrid4Nxm7diqIf9fQQ3Ov0ChH1V3Vvt13thOnrACmfGVQ==}
+  '@aws-sdk/middleware-expect-continue@3.972.10':
+    resolution: {integrity: sha512-2Yn0f1Qiq/DjxYR3wfI3LokXnjOhFM7Ssn4LTdFDIxRMCE6I32MAsVnhPX1cUZsuVA9tiZtwwhlSLAtFGxAZlQ==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/middleware-flexible-checksums@3.973.6':
-    resolution: {integrity: sha512-0nYEgkJH7Yt9k+nZJyllTghnkKaz17TWFcr5Mi0XMVMzYlF4ytDZADQpF2/iJo36cKL5AYSzRsvlykE4M/ErTA==}
+  '@aws-sdk/middleware-flexible-checksums@3.974.9':
+    resolution: {integrity: sha512-ye6xVuMEQ5NCT+yQOryGYsuCXnOwu7iGFGzV+qpXZOWtqXIAAaFostapxj6RCubw36rekVwmdB2lcspFuyNfYQ==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/middleware-host-header@3.972.8':
-    resolution: {integrity: sha512-wAr2REfKsqoKQ+OkNqvOShnBoh+nkPurDKW7uAeVSu6kUECnWlSJiPvnoqxGlfousEY/v9LfS9sNc46hjSYDIQ==}
+  '@aws-sdk/middleware-host-header@3.972.10':
+    resolution: {integrity: sha512-IJSsIMeVQ8MMCPbuh1AbltkFhLBLXn7aejzfX5YKT/VLDHn++Dcz8886tXckE+wQssyPUhaXrJhdakO2VilRhg==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/middleware-location-constraint@3.972.8':
-    resolution: {integrity: sha512-KaUoFuoFPziIa98DSQsTPeke1gvGXlc5ZGMhy+b+nLxZ4A7jmJgLzjEF95l8aOQN2T/qlPP3MrAyELm8ExXucw==}
+  '@aws-sdk/middleware-location-constraint@3.972.10':
+    resolution: {integrity: sha512-rI3NZvJcEvjoD0+0PI0iUAwlPw2IlSlhyvgBK/3WkKJQE/YiKFedd9dMN2lVacdNxPNhxL/jzQaKQdrGtQagjQ==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/middleware-logger@3.972.8':
-    resolution: {integrity: sha512-CWl5UCM57WUFaFi5kB7IBY1UmOeLvNZAZ2/OZ5l20ldiJ3TiIz1pC65gYj8X0BCPWkeR1E32mpsCk1L1I4n+lA==}
+  '@aws-sdk/middleware-logger@3.972.10':
+    resolution: {integrity: sha512-OOuGvvz1Dm20SjZo5oEBePFqxt5nf8AwkNDSyUHvD9/bfNASmstcYxFAHUowy4n6Io7mWUZ04JURZwSBvyQanQ==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/middleware-recursion-detection@3.972.8':
-    resolution: {integrity: sha512-BnnvYs2ZEpdlmZ2PNlV2ZyQ8j8AEkMTjN79y/YA475ER1ByFYrkVR85qmhni8oeTaJcDqbx364wDpitDAA/wCA==}
+  '@aws-sdk/middleware-recursion-detection@3.972.11':
+    resolution: {integrity: sha512-+zz6f79Kj9V5qFK2P+D8Ehjnw4AhphAlCAsPjUqEcInA9umtSSKMrHbSagEeOIsDNuvVrH98bjRHcyQukTrhaQ==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/middleware-sdk-s3@3.972.20':
-    resolution: {integrity: sha512-yhva/xL5H4tWQgsBjwV+RRD0ByCzg0TcByDCLp3GXdn/wlyRNfy8zsswDtCvr1WSKQkSQYlyEzPuWkJG0f5HvQ==}
+  '@aws-sdk/middleware-sdk-s3@3.972.30':
+    resolution: {integrity: sha512-hoQRxjJu4tt3gEOQin21rJKotClJC+x7AmCh9ylRct1DJeaNI/BRlFxMbuhJe54bG6xANPagSs0my8K30QyV9g==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/middleware-ssec@3.972.8':
-    resolution: {integrity: sha512-wqlK0yO/TxEC2UsY9wIlqeeutF6jjLe0f96Pbm40XscTo57nImUk9lBcw0dPgsm0sppFtAkSlDrfpK+pC30Wqw==}
+  '@aws-sdk/middleware-ssec@3.972.10':
+    resolution: {integrity: sha512-Gli9A0u8EVVb+5bFDGS/QbSVg28w/wpEidg1ggVcSj65BDTdGR6punsOcVjqdiu1i42WHWo51MCvARPIIz9juw==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/middleware-user-agent@3.972.21':
-    resolution: {integrity: sha512-62XRl1GDYPpkt7cx1AX1SPy9wgNE9Iw/NPuurJu4lmhCWS7sGKO+kS53TQ8eRmIxy3skmvNInnk0ZbWrU5Dpyg==}
+  '@aws-sdk/middleware-user-agent@3.972.31':
+    resolution: {integrity: sha512-L+hXN2HDomlIsWSHW5DVD7ppccCeRnlHXZ5uHG34ePTjF5bm0I1fmrJLbUGiW97xRXWryit5cjdP4Sx2FwiGog==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/nested-clients@3.996.10':
-    resolution: {integrity: sha512-SlDol5Z+C7Ivnc2rKGqiqfSUmUZzY1qHfVs9myt/nxVwswgfpjdKahyTzLTx802Zfq0NFRs7AejwKzzzl5Co2w==}
+  '@aws-sdk/nested-clients@3.996.21':
+    resolution: {integrity: sha512-Me3d/ua2lb2G0bQfFmvCeQQp3+nN6GSPqMxDmi/IQlQ8CrlpQ5C0JJHpz2AnOUkEFI0lBNrAL3Vnt29l44ndkA==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/region-config-resolver@3.972.8':
-    resolution: {integrity: sha512-1eD4uhTDeambO/PNIDVG19A6+v4NdD7xzwLHDutHsUqz0B+i661MwQB2eYO4/crcCvCiQG4SRm1k81k54FEIvw==}
+  '@aws-sdk/region-config-resolver@3.972.12':
+    resolution: {integrity: sha512-QQI43Mxd53nBij0pm8HXC+t4IOC6gnhhZfzxE0OATQyO6QfPV4e+aTIRRuAJKA6Nig/cR8eLwPryqYTX9ZrjAQ==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/signature-v4-multi-region@3.996.8':
-    resolution: {integrity: sha512-n1qYFD+tbqZuyskVaxUE+t10AUz9g3qzDw3Tp6QZDKmqsjfDmZBd4GIk2EKJJNtcCBtE5YiUjDYA+3djFAFBBg==}
+  '@aws-sdk/signature-v4-multi-region@3.996.18':
+    resolution: {integrity: sha512-4KT8UXRmvNAP5zKq9UI1MIwbnmSChZncBt89RKu/skMqZSSWGkBZTAJsZ+no+txfmF3kVaUFv31CTBZkQ5BJpQ==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/token-providers@3.1009.0':
-    resolution: {integrity: sha512-KCPLuTqN9u0Rr38Arln78fRG9KXpzsPWmof+PZzfAHMMQq2QED6YjQrkrfiH7PDefLWEposY1o4/eGwrmKA4JA==}
+  '@aws-sdk/token-providers@3.1032.0':
+    resolution: {integrity: sha512-n+PU8Z+gll7p3wDrH+Wo6fkt8sPrVnq30YYM6Ryga95oJlEneNMEbDHj0iqjMX3V7gaGdJo/hJWyPo4lscP+mA==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/types@3.973.6':
-    resolution: {integrity: sha512-Atfcy4E++beKtwJHiDln2Nby8W/mam64opFPTiHEqgsthqeydFS1pY+OUlN1ouNOmf8ArPU/6cDS65anOP3KQw==}
+  '@aws-sdk/types@3.973.8':
+    resolution: {integrity: sha512-gjlAdtHMbtR9X5iIhVUvbVcy55KnznpC6bkDUWW9z915bi0ckdUr5cjf16Kp6xq0bP5HBD2xzgbL9F9Quv5vUw==}
     engines: {node: '>=20.0.0'}
 
   '@aws-sdk/util-arn-parser@3.972.3':
     resolution: {integrity: sha512-HzSD8PMFrvgi2Kserxuff5VitNq2sgf3w9qxmskKDiDTThWfVteJxuCS9JXiPIPtmCrp+7N9asfIaVhBFORllA==}
     engines: {node: '>=20.0.0'}
 
-  '@aws-sdk/util-endpoints@3.996.5':
-    resolution: {integrity: sha512-Uh93L5sXFNbyR5sEPMzUU8tJ++Ku97EY4udmC01nB8Zu+xfBPwpIwJ6F7snqQeq8h2pf+8SGN5/NoytfKgYPIw==}
+  '@aws-sdk/util-endpoints@3.996.7':
+    resolution: {integrity: sha512-ty4LQxN1QC+YhUP28NfEgZDEGXkyqOQy+BDriBozqHsrYO4JMgiPhfizqOGF7P+euBTZ5Ez6SKlLAMCLo8tzmw==}
     engines: {node: '>=20.0.0'}
 
   '@aws-sdk/util-locate-window@3.893.0':
     resolution: {integrity: sha512-T89pFfgat6c8nMmpI8eKjBcDcgJq36+m9oiXbcUzeU55MP9ZuGgBomGjGnHaEyF36jenW9gmg3NfZDm0AO2XPg==}
     engines: {node: '>=18.0.0'}
 
-  '@aws-sdk/util-user-agent-browser@3.972.8':
-    resolution: {integrity: sha512-B3KGXJviV2u6Cdw2SDY2aDhoJkVfY/Q/Trwk2CMSkikE1Oi6gRzxhvhIfiRpHfmIsAhV4EA54TVEX8K6CbHbkA==}
+  '@aws-sdk/util-user-agent-browser@3.972.10':
+    resolution: {integrity: sha512-FAzqXvfEssGdSIz8ejatan0bOdx1qefBWKF/gWmVBXIP1HkS7v/wjjaqrAGGKvyihrXTXW00/2/1nTJtxpXz7g==}
 
-  '@aws-sdk/util-user-agent-node@3.973.7':
-    resolution: {integrity: sha512-Hz6EZMUAEzqUd7e+vZ9LE7mn+5gMbxltXy18v+YSFY+9LBJz15wkNZvw5JqfX3z0FS9n3bgUtz3L5rAsfh4YlA==}
+  '@aws-sdk/util-user-agent-node@3.973.17':
+    resolution: {integrity: sha512-utF5qjjbuJQuU9VdCkWl7L87sr93cApsrD+uxGfUnlafX8iyEzJrb7EZnufjThURZVTOtelRMXrblWxpefElUg==}
     engines: {node: '>=20.0.0'}
     peerDependencies:
       aws-crt: '>=1.0.0'
@@ -1287,8 +1287,8 @@ packages:
       aws-crt:
         optional: true
 
-  '@aws-sdk/xml-builder@3.972.11':
-    resolution: {integrity: sha512-iitV/gZKQMvY9d7ovmyFnFuTHbBAtrmLnvaSb/3X8vOKyevwtpmEtyc8AdhVWZe0pI/1GsHxlEvQeOePFzy7KQ==}
+  '@aws-sdk/xml-builder@3.972.18':
+    resolution: {integrity: sha512-BMDNVG1ETXRhl1tnisQiYBef3RShJ1kfZA7x7afivTFMLirfHNTb6U71K569HNXhSXbQZsweHvSDZ6euBw8hPA==}
     engines: {node: '>=20.0.0'}
 
   '@aws/lambda-invoke-store@0.2.2':
@@ -1907,6 +1907,16 @@ packages:
       '@types/react':
         optional: true
 
+  '@base-ui/utils@0.2.7':
+    resolution: {integrity: sha512-nXYKhiL/0JafyJE8PfcflipGftOftlIwKd72rU15iZ1M5yqgg5J9P8NHU71GReDuXco5MJA/eVQqUT5WRqX9sA==}
+    peerDependencies:
+      '@types/react': ^17 || ^18 || ^19
+      react: ^17 || ^18 || ^19
+      react-dom: ^17 || ^18 || ^19
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
   '@bcoe/v8-coverage@1.0.2':
     resolution: {integrity: sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==}
     engines: {node: '>=18'}
@@ -2661,9 +2671,9 @@ packages:
     resolution: {integrity: sha512-bV8v7R/c0gNve8i7yPmZbcCTJUqRbCnMSvcegcMaz+ly+FoZf9i4+3MTjKsX+OZn9w0w1I6VJYQBcdM+yMWPQQ==}
     engines: {node: '>=0.10.0'}
 
-  '@html-validate/stylish@5.0.0':
-    resolution: {integrity: sha512-xjhRV9k1mWfgsOcpYlwsjUOFy3w3EnCDrqUrEw+DWdvOStMK59ts2H7GLKWZtmLI5m6Npp3qMSNReafQy9K2sA==}
-    engines: {node: ^20.11 || >= 22.16}
+  '@html-validate/stylish@5.2.0':
+    resolution: {integrity: sha512-7lF57/RTs2tZi0FtgY7Y5CP73Y2GEPPMaJ9PeZKRRUOs7Bt7/Qlqt8kdsAbVMO7GrpuWtUfGvR11riSOryioow==}
+    engines: {node: ^20.18 || ^22.16 || >= 24.0}
 
   '@humanfs/core@0.19.1':
     resolution: {integrity: sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA==}
@@ -2846,8 +2856,8 @@ packages:
     resolution: {integrity: sha512-S8qNSZiYzFd0wAcyG5AXCvUHC5Sr7xpZ9wZ2py9XR88jUz8wooStVx5M6dRzczbBWjic9NP7+rY0Xi7qqK/aMQ==}
     engines: {node: '>=18'}
 
-  '@inquirer/ansi@2.0.4':
-    resolution: {integrity: sha512-DpcZrQObd7S0R/U3bFdkcT5ebRwbTTC4D3tCc1vsJizmgPLxNJBo+AAFmrZwe8zk30P2QzgzGWZ3Q9uJwWuhIg==}
+  '@inquirer/ansi@2.0.5':
+    resolution: {integrity: sha512-doc2sWgJpbFQ64UflSVd17ibMGDuxO1yKgOgLMwavzESnXjFWJqUeG8saYosqKpHp4kWiM5x1nXvEjbpx90gzw==}
     engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
 
   '@inquirer/checkbox@4.3.0':
@@ -2868,8 +2878,8 @@ packages:
       '@types/node':
         optional: true
 
-  '@inquirer/confirm@6.0.10':
-    resolution: {integrity: sha512-tiNyA73pgpQ0FQ7axqtoLUe4GDYjNCDcVsbgcA5anvwg2z6i+suEngLKKJrWKJolT//GFPZHwN30binDIHgSgQ==}
+  '@inquirer/confirm@6.0.11':
+    resolution: {integrity: sha512-pTpHjg0iEIRMYV/7oCZUMf27/383E6Wyhfc/MY+AVQGEoUobffIYWOK9YLP2XFRGz/9i6WlTQh1CkFVIo2Y7XA==}
     engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
     peerDependencies:
       '@types/node': '>=18'
@@ -2886,8 +2896,8 @@ packages:
       '@types/node':
         optional: true
 
-  '@inquirer/core@11.1.7':
-    resolution: {integrity: sha512-1BiBNDk9btIwYIzNZpkikIHXWeNzNncJePPqwDyVMhXhD1ebqbpn1mKGctpoqAbzywZfdG0O4tvmsGIcOevAPQ==}
+  '@inquirer/core@11.1.8':
+    resolution: {integrity: sha512-/u+yJk2pOKNDOh1ZgdUH2RQaRx6OOH4I0uwL95qPvTFTIL38YBsuSC4r1yXBB3Q6JvNqFFc202gk0Ew79rrcjA==}
     engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
     peerDependencies:
       '@types/node': '>=18'
@@ -2926,8 +2936,8 @@ packages:
     resolution: {integrity: sha512-t2IEY+unGHOzAaVM5Xx6DEWKeXlDDcNPeDyUpsRc6CUhBfU3VQOEl+Vssh7VNp1dR8MdUJBWhuObjXCsVpjN5g==}
     engines: {node: '>=18'}
 
-  '@inquirer/figures@2.0.4':
-    resolution: {integrity: sha512-eLBsjlS7rPS3WEhmOmh1znQ5IsQrxWzxWDxO51e4urv+iVrSnIHbq4zqJIOiyNdYLa+BVjwOtdetcQx1lWPpiQ==}
+  '@inquirer/figures@2.0.5':
+    resolution: {integrity: sha512-NsSs4kzfm12lNetHwAn3GEuH317IzpwrMCbOuMIVytpjnJ90YYHNwdRgYGuKmVxwuIqSgqk3M5qqQt1cDk0tGQ==}
     engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
 
   '@inquirer/input@4.2.5':
@@ -2993,8 +3003,8 @@ packages:
       '@types/node':
         optional: true
 
-  '@inquirer/select@5.1.2':
-    resolution: {integrity: sha512-kTK8YIkHV+f02y7bWCh7E0u2/11lul5WepVTclr3UMBtBr05PgcZNWfMa7FY57ihpQFQH/spLMHTcr0rXy50tA==}
+  '@inquirer/select@5.1.3':
+    resolution: {integrity: sha512-zYyqWgGQi3NhBcNq4Isc5rB3oEdQEh1Q/EcAnOW0FK4MpnXWkvSBYgA4cYrTM4A9UB573omouZbnL9JJ74Mq3A==}
     engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
     peerDependencies:
       '@types/node': '>=18'
@@ -3011,8 +3021,8 @@ packages:
       '@types/node':
         optional: true
 
-  '@inquirer/type@4.0.4':
-    resolution: {integrity: sha512-PamArxO3cFJZoOzspzo6cxVlLeIftyBsZw/S9bKY5DzxqJVZgjoj1oP8d0rskKtp7sZxBycsoer1g6UeJV1BBA==}
+  '@inquirer/type@4.0.5':
+    resolution: {integrity: sha512-aetVUNeKNc/VriqXlw1NRSW0zhMBB0W4bNbWRJgzRl/3d0QNDQFfk0GO5SDdtjMZVg6o8ZKEiadd7SCCzoOn5Q==}
     engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
     peerDependencies:
       '@types/node': '>=18'
@@ -4149,8 +4159,8 @@ packages:
   '@next/eslint-plugin-next@16.1.6':
     resolution: {integrity: sha512-/Qq3PTagA6+nYVfryAtQ7/9FEr/6YVyvOtl6rZnGsbReGLf0jZU6gkpr1FuChAQpvV46a78p4cmHOVP8mbfSMQ==}
 
-  '@next/mdx@16.2.1':
-    resolution: {integrity: sha512-w0YOkOc+WEnsTJ8uxzBOvpe3R+9BnJOxWCE7qcI/62CzJiUEd8JKtF25e3R8cW5BGsKyRW8p4zE2JLyXKa8xdw==}
+  '@next/mdx@16.1.6':
+    resolution: {integrity: sha512-PT5JR4WPPYOls7WD6xEqUVVI9HDY8kY7XLQsNYB2lSZk5eJSXWu3ECtIYmfR0hZpx8Sg7BKZYKi2+u5OTSEx0w==}
     peerDependencies:
       '@mdx-js/loader': '>=0.15.0'
       '@mdx-js/react': '>=0.15.0'
@@ -4564,11 +4574,6 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
-  '@playwright/test@1.59.1':
-    resolution: {integrity: sha512-PG6q63nQg5c9rIi4/Z5lR5IVF7yU5MqmKaPOe0HSc0O2cX1fPi96sUQu5j7eo4gKCkB2AnNGoWt7y4/Xx3Kcqg==}
-    engines: {node: '>=18'}
-    hasBin: true
-
   '@pnpm/config.env-replace@1.1.0':
     resolution: {integrity: sha512-htyl8TWnKL7K/ESFa1oW2UB5lVDxuF5DpM7tBi6Hu2LNL3mWkIzNLG6N4zoCUP1lCKNxWy/3iu8mS8MvToGd6w==}
     engines: {node: '>=12.22.0'}
@@ -5544,9 +5549,9 @@ packages:
   '@sec-ant/readable-stream@0.4.1':
     resolution: {integrity: sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==}
 
-  '@sidvind/better-ajv-errors@4.0.1':
-    resolution: {integrity: sha512-6arF1ssKxItxgitPYXafUoLmsVBA6K7m9+ZGj6hLDoBl7nWpJ33EInwQUdHTle2METeWGxgQiqSex20KZRykew==}
-    engines: {node: '>= 18'}
+  '@sidvind/better-ajv-errors@5.0.0':
+    resolution: {integrity: sha512-FeI/V2KGtOaDX+r0akidCGYy79lVR4YnAqk1GFgZFuHADErCAEmtZL4+IdCAcDXHqfZsII3fs9DrfC1pIR+19w==}
+    engines: {node: ^20.19 || ^22.12 || >= 24.0}
     peerDependencies:
       ajv: ^7.0.0 || ^8.0.0
 
@@ -5581,10 +5586,6 @@ packages:
     resolution: {integrity: sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==}
     engines: {node: '>=18'}
 
-  '@smithy/abort-controller@4.2.12':
-    resolution: {integrity: sha512-xolrFw6b+2iYGl6EcOL7IJY71vvyZ0DJ3mcKtpykqPe2uscwtzDZJa1uVQXyP7w9Dd+kGwYnPbMsJrGISKiY/Q==}
-    engines: {node: '>=18.0.0'}
-
   '@smithy/chunked-blob-reader-native@4.2.3':
     resolution: {integrity: sha512-jA5k5Udn7Y5717L86h4EIv06wIr3xn8GM1qHRi/Nf31annXcXHJjBKvgztnbn2TxH3xWrPBfgwHsOwZf0UmQWw==}
     engines: {node: '>=18.0.0'}
@@ -5593,56 +5594,56 @@ packages:
     resolution: {integrity: sha512-St+kVicSyayWQca+I1rGitaOEH6uKgE8IUWoYnnEX26SWdWQcL6LvMSD19Lg+vYHKdT9B2Zuu7rd3i6Wnyb/iw==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/config-resolver@4.4.11':
-    resolution: {integrity: sha512-YxFiiG4YDAtX7WMN7RuhHZLeTmRRAOyCbr+zB8e3AQzHPnUhS8zXjB1+cniPVQI3xbWsQPM0X2aaIkO/ME0ymw==}
+  '@smithy/config-resolver@4.4.16':
+    resolution: {integrity: sha512-GFlGPNLZKrGfqWpqVb31z7hvYCA9ZscfX1buYnvvMGcRYsQQnhH+4uN6mWWflcD5jB4OXP/LBrdpukEdjl41tg==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/core@3.23.11':
-    resolution: {integrity: sha512-952rGf7hBRnhUIaeLp6q4MptKW8sPFe5VvkoZ5qIzFAtx6c/QZ/54FS3yootsyUSf9gJX/NBqEBNdNR7jMIlpQ==}
+  '@smithy/core@3.23.15':
+    resolution: {integrity: sha512-E7GVCgsQttzfujEZb6Qep005wWf4xiL4x06apFEtzQMWYBPggZh/0cnOxPficw5cuK/YjjkehKoIN4YUaSh0UQ==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/credential-provider-imds@4.2.12':
-    resolution: {integrity: sha512-cr2lR792vNZcYMriSIj+Um3x9KWrjcu98kn234xA6reOAFMmbRpQMOv8KPgEmLLtx3eldU6c5wALKFqNOhugmg==}
+  '@smithy/credential-provider-imds@4.2.14':
+    resolution: {integrity: sha512-Au28zBN48ZAoXdooGUHemuVBrkE+Ie6RPmGNIAJsFqj33Vhb6xAgRifUydZ2aY+M+KaMAETAlKk5NC5h1G7wpg==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/eventstream-codec@4.2.12':
-    resolution: {integrity: sha512-FE3bZdEl62ojmy8x4FHqxq2+BuOHlcxiH5vaZ6aqHJr3AIZzwF5jfx8dEiU/X0a8RboyNDjmXjlbr8AdEyLgiA==}
+  '@smithy/eventstream-codec@4.2.14':
+    resolution: {integrity: sha512-erZq0nOIpzfeZdCyzZjdJb4nVSKLUmSkaQUVkRGQTXs30gyUGeKnrYEg+Xe1W5gE3aReS7IgsvANwVPxSzY6Pw==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/eventstream-serde-browser@4.2.12':
-    resolution: {integrity: sha512-XUSuMxlTxV5pp4VpqZf6Sa3vT/Q75FVkLSpSSE3KkWBvAQWeuWt1msTv8fJfgA4/jcJhrbrbMzN1AC/hvPmm5A==}
+  '@smithy/eventstream-serde-browser@4.2.14':
+    resolution: {integrity: sha512-8IelTCtTctWRbb+0Dcy+C0aICh1qa0qWXqgjcXDmMuCvPJRnv26hiDZoAau2ILOniki65mCPKqOQs/BaWvO4CQ==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/eventstream-serde-config-resolver@4.3.12':
-    resolution: {integrity: sha512-7epsAZ3QvfHkngz6RXQYseyZYHlmWXSTPOfPmXkiS+zA6TBNo1awUaMFL9vxyXlGdoELmCZyZe1nQE+imbmV+Q==}
+  '@smithy/eventstream-serde-config-resolver@4.3.14':
+    resolution: {integrity: sha512-sqHiHpYRYo3FJlaIxD1J8PhbcmJAm7IuM16mVnwSkCToD7g00IBZzKuiLNMGmftULmEUX6/UAz8/NN5uMP8bVA==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/eventstream-serde-node@4.2.12':
-    resolution: {integrity: sha512-D1pFuExo31854eAvg89KMn9Oab/wEeJR6Buy32B49A9Ogdtx5fwZPqBHUlDzaCDpycTFk2+fSQgX689Qsk7UGA==}
+  '@smithy/eventstream-serde-node@4.2.14':
+    resolution: {integrity: sha512-Ht/8BuGlKfFTy0H3+8eEu0vdpwGztCnaLLXtpXNdQqiR7Hj4vFScU3T436vRAjATglOIPjJXronY+1WxxNLSiw==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/eventstream-serde-universal@4.2.12':
-    resolution: {integrity: sha512-+yNuTiyBACxOJUTvbsNsSOfH9G9oKbaJE1lNL3YHpGcuucl6rPZMi3nrpehpVOVR2E07YqFFmtwpImtpzlouHQ==}
+  '@smithy/eventstream-serde-universal@4.2.14':
+    resolution: {integrity: sha512-lWyt4T2XQZUZgK3tQ3Wn0w3XBvZsK/vjTuJl6bXbnGZBHH0ZUSONTYiK9TgjTTzU54xQr3DRFwpjmhp0oLm3gg==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/fetch-http-handler@5.3.15':
-    resolution: {integrity: sha512-T4jFU5N/yiIfrtrsb9uOQn7RdELdM/7HbyLNr6uO/mpkj1ctiVs7CihVr51w4LyQlXWDpXFn4BElf1WmQvZu/A==}
+  '@smithy/fetch-http-handler@5.3.17':
+    resolution: {integrity: sha512-bXOvQzaSm6MnmLaWA1elgfQcAtN4UP3vXqV97bHuoOrHQOJiLT3ds6o9eo5bqd0TJfRFpzdGnDQdW3FACiAVdw==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/hash-blob-browser@4.2.13':
-    resolution: {integrity: sha512-YrF4zWKh+ghLuquldj6e/RzE3xZYL8wIPfkt0MqCRphVICjyyjH8OwKD7LLlKpVEbk4FLizFfC1+gwK6XQdR3g==}
+  '@smithy/hash-blob-browser@4.2.15':
+    resolution: {integrity: sha512-0PJ4Al3fg2nM4qKrAIxyNcApgqHAXcBkN8FeizOz69z0rb26uZ6lMESYtxegaTlXB5Hj84JfwMPavMrwDMjucA==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/hash-node@4.2.12':
-    resolution: {integrity: sha512-QhBYbGrbxTkZ43QoTPrK72DoYviDeg6YKDrHTMJbbC+A0sml3kSjzFtXP7BtbyJnXojLfTQldGdUR0RGD8dA3w==}
+  '@smithy/hash-node@4.2.14':
+    resolution: {integrity: sha512-8ZBDY2DD4wr+GGjTpPtiglEsqr0lUP+KHqgZcWczFf6qeZ/YRjMIOoQWVQlmwu7EtxKTd8YXD8lblmYcpBIA1g==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/hash-stream-node@4.2.12':
-    resolution: {integrity: sha512-O3YbmGExeafuM/kP7Y8r6+1y0hIh3/zn6GROx0uNlB54K9oihAL75Qtc+jFfLNliTi6pxOAYZrRKD9A7iA6UFw==}
+  '@smithy/hash-stream-node@4.2.14':
+    resolution: {integrity: sha512-tw4GANWkZPb6+BdD4Fgucqzey2+r73Z/GRo9zklsCdwrnxxumUV83ZIaBDdudV4Ylazw3EPTiJZhpX42105ruQ==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/invalid-dependency@4.2.12':
-    resolution: {integrity: sha512-/4F1zb7Z8LOu1PalTdESFHR0RbPwHd3FcaG1sI3UEIriQTWakysgJr65lc1jj6QY5ye7aFsisajotH6UhWfm/g==}
+  '@smithy/invalid-dependency@4.2.14':
+    resolution: {integrity: sha512-c21qJiTSb25xvvOp+H2TNZzPCngrvl5vIPqPB8zQ/DmJF4QWXO19x1dWfMJZ6wZuuWUPPm0gV8C0cU3+ifcWuw==}
     engines: {node: '>=18.0.0'}
 
   '@smithy/is-array-buffer@2.2.0':
@@ -5653,76 +5654,76 @@ packages:
     resolution: {integrity: sha512-n6rQ4N8Jj4YTQO3YFrlgZuwKodf4zUFs7EJIWH86pSCWBaAtAGBFfCM7Wx6D2bBJ2xqFNxGBSrUWswT3M0VJow==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/md5-js@4.2.12':
-    resolution: {integrity: sha512-W/oIpHCpWU2+iAkfZYyGWE+qkpuf3vEXHLxQQDx9FPNZTTdnul0dZ2d/gUFrtQ5je1G2kp4cjG0/24YueG2LbQ==}
+  '@smithy/md5-js@4.2.14':
+    resolution: {integrity: sha512-V2v0vx+h0iUSNG1Alt+GNBMSLGCrl9iVsdd+Ap67HPM9PN479x12V8LkuMoKImNZxn3MXeuyUjls+/7ZACZghA==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/middleware-content-length@4.2.12':
-    resolution: {integrity: sha512-YE58Yz+cvFInWI/wOTrB+DbvUVz/pLn5mC5MvOV4fdRUc6qGwygyngcucRQjAhiCEbmfLOXX0gntSIcgMvAjmA==}
+  '@smithy/middleware-content-length@4.2.14':
+    resolution: {integrity: sha512-xhHq7fX4/3lv5NHxLUk3OeEvl0xZ+Ek3qIbWaCL4f9JwgDZEclPBElljaZCAItdGPQl/kSM4LPMOpy1MYgprpw==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/middleware-endpoint@4.4.25':
-    resolution: {integrity: sha512-dqjLwZs2eBxIUG6Qtw8/YZ4DvzHGIf0DA18wrgtfP6a50UIO7e2nY0FPdcbv5tVJKqWCCU5BmGMOUwT7Puan+A==}
+  '@smithy/middleware-endpoint@4.4.30':
+    resolution: {integrity: sha512-qS2XqhKeXmdZ4nEQ4cOxIczSP/Y91wPAHYuRwmWDCh975B7/57uxsm5d6sisnUThn2u2FwzMdJNM7AbO1YPsPg==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/middleware-retry@4.4.42':
-    resolution: {integrity: sha512-vbwyqHRIpIZutNXZpLAozakzamcINaRCpEy1MYmK6xBeW3xN+TyPRA123GjXnuxZIjc9848MRRCugVMTXxC4Eg==}
+  '@smithy/middleware-retry@4.5.3':
+    resolution: {integrity: sha512-TE8dJNi6JuxzGSxMCVd3i9IEWDndCl3bmluLsBNDWok8olgj65OfkndMhl9SZ7m14c+C5SQn/PcUmrDl57rSFw==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/middleware-serde@4.2.14':
-    resolution: {integrity: sha512-+CcaLoLa5apzSRtloOyG7lQvkUw2ZDml3hRh4QiG9WyEPfW5Ke/3tPOPiPjUneuT59Tpn8+c3RVaUvvkkwqZwg==}
+  '@smithy/middleware-serde@4.2.18':
+    resolution: {integrity: sha512-M6CSgnp3v4tYz9ynj2JHbA60woBZcGqEwNjTKjBsNHPV26R1ZX52+0wW8WsZU18q45jD0tw2wL22S17Ze9LpEw==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/middleware-stack@4.2.12':
-    resolution: {integrity: sha512-kruC5gRHwsCOuyCd4ouQxYjgRAym2uDlCvQ5acuMtRrcdfg7mFBg6blaxcJ09STpt3ziEkis6bhg1uwrWU7txw==}
+  '@smithy/middleware-stack@4.2.14':
+    resolution: {integrity: sha512-2dvkUKLuFdKsCRmOE4Mn63co0Djtsm+JMh0bYZQupN1pJwMeE8FmQmRLLzzEMN0dnNi7CDCYYH8F0EVwWiPBeA==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/node-config-provider@4.3.12':
-    resolution: {integrity: sha512-tr2oKX2xMcO+rBOjobSwVAkV05SIfUKz8iI53rzxEmgW3GOOPOv0UioSDk+J8OpRQnpnhsO3Af6IEBabQBVmiw==}
+  '@smithy/node-config-provider@4.3.14':
+    resolution: {integrity: sha512-S+gFjyo/weSVL0P1b9Ts8C/CwIfNCgUPikk3sl6QVsfE/uUuO+QsF+NsE/JkpvWqqyz1wg7HFdiaZuj5CoBMRg==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/node-http-handler@4.4.16':
-    resolution: {integrity: sha512-ULC8UCS/HivdCB3jhi+kLFYe4B5gxH2gi9vHBfEIiRrT2jfKiZNiETJSlzRtE6B26XbBHjPtc8iZKSNqMol9bw==}
+  '@smithy/node-http-handler@4.5.3':
+    resolution: {integrity: sha512-lc5jFL++x17sPhIwMWJ3YOnqmSjw/2Po6VLDlUIXvxVWRuJwRXnJ4jOBBLB0cfI5BB5ehIl02Fxr1PDvk/kxDw==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/property-provider@4.2.12':
-    resolution: {integrity: sha512-jqve46eYU1v7pZ5BM+fmkbq3DerkSluPr5EhvOcHxygxzD05ByDRppRwRPPpFrsFo5yDtCYLKu+kreHKVrvc7A==}
+  '@smithy/property-provider@4.2.14':
+    resolution: {integrity: sha512-WuM31CgfsnQ/10i7NYr0PyxqknD72Y5uMfUMVSniPjbEPceiTErb4eIqJQ+pdxNEAUEWrewrGjIRjVbVHsxZiQ==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/protocol-http@5.3.12':
-    resolution: {integrity: sha512-fit0GZK9I1xoRlR4jXmbLhoN0OdEpa96ul8M65XdmXnxXkuMxM0Y8HDT0Fh0Xb4I85MBvBClOzgSrV1X2s1Hxw==}
+  '@smithy/protocol-http@5.3.14':
+    resolution: {integrity: sha512-dN5F8kHx8RNU0r+pCwNmFZyz6ChjMkzShy/zup6MtkRmmix4vZzJdW+di7x//b1LiynIev88FM18ie+wwPcQtQ==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/querystring-builder@4.2.12':
-    resolution: {integrity: sha512-6wTZjGABQufekycfDGMEB84BgtdOE/rCVTov+EDXQ8NHKTUNIp/j27IliwP7tjIU9LR+sSzyGBOXjeEtVgzCHg==}
+  '@smithy/querystring-builder@4.2.14':
+    resolution: {integrity: sha512-XYA5Z0IqTeF+5XDdh4BBmSA0HvbgVZIyv4cmOoUheDNR57K1HgBp9ukUMx3Cr3XpDHHpLBnexPE3LAtDsZkj2A==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/querystring-parser@4.2.12':
-    resolution: {integrity: sha512-P2OdvrgiAKpkPNKlKUtWbNZKB1XjPxM086NeVhK+W+wI46pIKdWBe5QyXvhUm3MEcyS/rkLvY8rZzyUdmyDZBw==}
+  '@smithy/querystring-parser@4.2.14':
+    resolution: {integrity: sha512-hr+YyqBD23GVvRxGGrcc/oOeNlK3PzT5Fu4dzrDXxzS1LpFiuL2PQQqKPs87M79aW7ziMs+nvB3qdw77SqE7Lw==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/service-error-classification@4.2.12':
-    resolution: {integrity: sha512-LlP29oSQN0Tw0b6D0Xo6BIikBswuIiGYbRACy5ujw/JgWSzTdYj46U83ssf6Ux0GyNJVivs2uReU8pt7Eu9okQ==}
+  '@smithy/service-error-classification@4.2.14':
+    resolution: {integrity: sha512-vVimoUnGxlx4eLLQbZImdOZFOe+Zh+5ACntv8VxZuGP72LdWu5GV3oEmCahSEReBgRJoWjypFkrehSj7BWx1HQ==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/shared-ini-file-loader@4.4.7':
-    resolution: {integrity: sha512-HrOKWsUb+otTeo1HxVWeEb99t5ER1XrBi/xka2Wv6NVmTbuCUC1dvlrksdvxFtODLBjsC+PHK+fuy2x/7Ynyiw==}
+  '@smithy/shared-ini-file-loader@4.4.9':
+    resolution: {integrity: sha512-495/V2I15SHgedSJoDPD23JuSfKAp726ZI1V0wtjB07Wh7q/0tri/0e0DLefZCHgxZonrGKt/OCTpAtP1wE1kQ==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/signature-v4@5.3.12':
-    resolution: {integrity: sha512-B/FBwO3MVOL00DaRSXfXfa/TRXRheagt/q5A2NM13u7q+sHS59EOVGQNfG7DkmVtdQm5m3vOosoKAXSqn/OEgw==}
+  '@smithy/signature-v4@5.3.14':
+    resolution: {integrity: sha512-1D9Y/nmlVjCeSivCbhZ7hgEpmHyY1h0GvpSZt3l0xcD9JjmjVC1CHOozS6+Gh+/ldMH8JuJ6cujObQqfayAVFA==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/smithy-client@4.12.5':
-    resolution: {integrity: sha512-UqwYawyqSr/aog8mnLnfbPurS0gi4G7IYDcD28cUIBhsvWs1+rQcL2IwkUQ+QZ7dibaoRzhNF99fAQ9AUcO00w==}
+  '@smithy/smithy-client@4.12.11':
+    resolution: {integrity: sha512-wzz/Wa1CH/Tlhxh0s4DQPEcXSxSVfJ59AZcUh9Gu0c6JTlKuwGf4o/3P2TExv0VbtPFt8odIBG+eQGK2+vTECg==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/types@4.13.1':
-    resolution: {integrity: sha512-787F3yzE2UiJIQ+wYW1CVg2odHjmaWLGksnKQHUrK/lYZSEcy1msuLVvxaR/sI2/aDe9U+TBuLsXnr3vod1g0g==}
+  '@smithy/types@4.14.1':
+    resolution: {integrity: sha512-59b5HtSVrVR/eYNei3BUj3DCPKD/G7EtDDe7OEJE7i7FtQFugYo6MxbotS8mVJkLNVf8gYaAlEBwwtJ9HzhWSg==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/url-parser@4.2.12':
-    resolution: {integrity: sha512-wOPKPEpso+doCZGIlr+e1lVI6+9VAKfL4kZWFgzVgGWY2hZxshNKod4l2LXS3PRC9otH/JRSjtEHqQ/7eLciRA==}
+  '@smithy/url-parser@4.2.14':
+    resolution: {integrity: sha512-p06BiBigJ8bTA3MgnOfCtDUWnAMY0YfedO/GRpmc7p+wg3KW8vbXy1xwSu5ASy0wV7rRYtlfZOIKH4XqfhjSQQ==}
     engines: {node: '>=18.0.0'}
 
   '@smithy/util-base64@4.3.2':
@@ -5749,32 +5750,32 @@ packages:
     resolution: {integrity: sha512-dWU03V3XUprJwaUIFVv4iOnS1FC9HnMHDfUrlNDSh4315v0cWyaIErP8KiqGVbf5z+JupoVpNM7ZB3jFiTejvQ==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/util-defaults-mode-browser@4.3.41':
-    resolution: {integrity: sha512-M1w1Ux0rSVvBOxIIiqbxvZvhnjQ+VUjJrugtORE90BbadSTH+jsQL279KRL3Hv0w69rE7EuYkV/4Lepz/NBW9g==}
+  '@smithy/util-defaults-mode-browser@4.3.47':
+    resolution: {integrity: sha512-zlIuXai3/SHjQUQ8y3g/woLvrH573SK2wNjcDaHu5e9VOcC0JwM1MI0Sq0GZJyN3BwSUneIhpjZ18nsiz5AtQw==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/util-defaults-mode-node@4.2.44':
-    resolution: {integrity: sha512-YPze3/lD1KmWuZsl9JlfhcgGLX7AXhSoaCDtiPntUjNW5/YY0lOHjkcgxyE9x/h5vvS1fzDifMGjzqnNlNiqOQ==}
+  '@smithy/util-defaults-mode-node@4.2.52':
+    resolution: {integrity: sha512-cQBz8g68Vnw1W2meXlkb3D/hXJU+Taiyj9P8qLJtjREEV9/Td65xi4A/H1sRQ8EIgX5qbZbvdYPKygKLholZ3w==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/util-endpoints@3.3.3':
-    resolution: {integrity: sha512-VACQVe50j0HZPjpwWcjyT51KUQ4AnsvEaQ2lKHOSL4mNLD0G9BjEniQ+yCt1qqfKfiAHRAts26ud7hBjamrwig==}
+  '@smithy/util-endpoints@3.4.1':
+    resolution: {integrity: sha512-wMxNDZJrgS5mQV9oxCs4TWl5767VMgOfqfZ3JHyCkMtGC2ykW9iPqMvFur695Otcc5yxLG8OKO/80tsQBxrhXg==}
     engines: {node: '>=18.0.0'}
 
   '@smithy/util-hex-encoding@4.2.2':
     resolution: {integrity: sha512-Qcz3W5vuHK4sLQdyT93k/rfrUwdJ8/HZ+nMUOyGdpeGA1Wxt65zYwi3oEl9kOM+RswvYq90fzkNDahPS8K0OIg==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/util-middleware@4.2.12':
-    resolution: {integrity: sha512-Er805uFUOvgc0l8nv0e0su0VFISoxhJ/AwOn3gL2NWNY2LUEldP5WtVcRYSQBcjg0y9NfG8JYrCJaYDpupBHJQ==}
+  '@smithy/util-middleware@4.2.14':
+    resolution: {integrity: sha512-1Su2vj9RYNDEv/V+2E+jXkkwGsgR7dc4sfHn9Z7ruzQHJIEni9zzw5CauvRXlFJfmgcqYP8fWa0dkh2Q2YaQyw==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/util-retry@4.2.12':
-    resolution: {integrity: sha512-1zopLDUEOwumjcHdJ1mwBHddubYF8GMQvstVCLC54Y46rqoHwlIU+8ZzUeaBcD+WCJHyDGSeZ2ml9YSe9aqcoQ==}
+  '@smithy/util-retry@4.3.2':
+    resolution: {integrity: sha512-2+KTsJEwTi63NUv4uR9IQ+IFT1yu6Rf6JuoBK2WKaaJ/TRvOiOVGcXAsEqX/TQN2thR9yII21kPUJq1UV/WI2A==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/util-stream@4.5.19':
-    resolution: {integrity: sha512-v4sa+3xTweL1CLO2UP0p7tvIMH/Rq1X4KKOxd568mpe6LSLMQCnDHs4uv7m3ukpl3HvcN2JH6jiCS0SNRXKP/w==}
+  '@smithy/util-stream@4.5.23':
+    resolution: {integrity: sha512-N6on1+ngJ3RznZOnDWNveIwnTSlqxNnXuNAh7ez889ZZaRdXoNRTXKgmYOLe6dB0gCmAVtuRScE1hymQFl4hpg==}
     engines: {node: '>=18.0.0'}
 
   '@smithy/util-uri-escape@4.2.2':
@@ -5789,8 +5790,8 @@ packages:
     resolution: {integrity: sha512-75MeYpjdWRe8M5E3AW0O4Cx3UadweS+cwdXjwYGBW5h/gxxnbeZ877sLPX/ZJA9GVTlL/qG0dXP29JWFCD1Ayw==}
     engines: {node: '>=18.0.0'}
 
-  '@smithy/util-waiter@4.2.13':
-    resolution: {integrity: sha512-2zdZ9DTHngRtcYxJK1GUDxruNr53kv5W2Lupe0LMU+Imr6ohQg8M2T14MNkj1Y0wS3FFwpgpGQyvuaMF7CiTmQ==}
+  '@smithy/util-waiter@4.2.16':
+    resolution: {integrity: sha512-GtclrKoZ3Lt7jPQ7aTIYKfjY92OgceScftVnkTsG8e1KV8rkvZgN+ny6YSRhd9hxB8rZtwVbmln7NTvE5O3GmQ==}
     engines: {node: '>=18.0.0'}
 
   '@smithy/uuid@1.1.2':
@@ -5806,8 +5807,8 @@ packages:
   '@tanstack/query-core@5.67.2':
     resolution: {integrity: sha512-+iaFJ/pt8TaApCk6LuZ0WHS/ECVfTzrxDOEL9HH9Dayyb5OVuomLzDXeSaI2GlGT/8HN7bDGiRXDts3LV+u6ww==}
 
-  '@tanstack/query-core@5.95.2':
-    resolution: {integrity: sha512-o4T8vZHZET4Bib3jZ/tCW9/7080urD4c+0/AUaYVpIqOsr7y0reBc1oX3ttNaSW5mYyvZHctiQ/UOP2PfdmFEQ==}
+  '@tanstack/query-core@5.99.1':
+    resolution: {integrity: sha512-5E8xwxyWvr22yt7zvzP3KOZ5TUElOdVA45NP3/Ao1m9mvc9i18NLTDe9m3M00BH2DR5J20cv7xckMPlhKNs+vQ==}
 
   '@tanstack/query-devtools@5.67.2':
     resolution: {integrity: sha512-O4QXFFd7xqp6EX7sdvc9tsVO8nm4lpWBqwpgjpVLW5g7IeOY6VnS/xvs/YzbRhBVkKTMaJMOUGU7NhSX+YGoNg==}
@@ -5823,8 +5824,8 @@ packages:
     peerDependencies:
       react: ^18 || ^19
 
-  '@tanstack/react-query@5.95.2':
-    resolution: {integrity: sha512-/wGkvLj/st5Ud1Q76KF1uFxScV7WeqN1slQx5280ycwAyYkIPGaRZAEgHxe3bjirSd5Zpwkj6zNcR4cqYni/ZA==}
+  '@tanstack/react-query@5.99.1':
+    resolution: {integrity: sha512-akg5GdwW70lvJvCqVHZ7tizGyc+TATjUzKX9RuF1xknhEe/1leofXk7YLYbrbRsuhNbHJBAayaQUMvvOFZ5L5g==}
     peerDependencies:
       react: ^18 || ^19
 
@@ -6277,43 +6278,43 @@ packages:
     resolution: {integrity: sha512-YWnmJkXbofiz9KbnbbwuA2rpGkFPLbAIetcCNO6mJ8gdhdZ/v7WDXsoGFAJuM6ikUFKTlSQnjWnVO4ux+UzS6A==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
 
-  '@typescript/native-preview-darwin-arm64@7.0.0-dev.20260317.1':
-    resolution: {integrity: sha512-E63cwlaAKeOXGcSaTcuVKdfGQJoms/vSMZH8lYsvxU6el3X96LdbXVcAIqbqwDfPJt7rQ6gw/OOGO45BlTlxSw==}
+  '@typescript/native-preview-darwin-arm64@7.0.0-dev.20260419.1':
+    resolution: {integrity: sha512-qgoZvmBsEE928tqDg7l27qciCrCWRU5bXdiWUykkt4+er3OaNYKUt+UtJvNiuNxiPaVwnRMEjnVyFiO/KNo3gA==}
     cpu: [arm64]
     os: [darwin]
 
-  '@typescript/native-preview-darwin-x64@7.0.0-dev.20260317.1':
-    resolution: {integrity: sha512-cy9kmUiwJmANoz1tOc22HYXqyz92tvNrI9eP/q8LAa5LGega5OlTqAbuSiEc4C9OUL/4EvCJuIYmOk5PFME0tQ==}
+  '@typescript/native-preview-darwin-x64@7.0.0-dev.20260419.1':
+    resolution: {integrity: sha512-3+bXF/Mi4u3jbtuPp0gO4bjk+uaDhQLWR/h7JRrmL6KgVJQ9uywEOorx+1SgbidH6a1neO/pUPAlCvJ7+9zUQA==}
     cpu: [x64]
     os: [darwin]
 
-  '@typescript/native-preview-linux-arm64@7.0.0-dev.20260317.1':
-    resolution: {integrity: sha512-YeRI5O4z5H7JgBCb2tTaZSEEEpojjBxac5DQ1NEm3wwjSSWhHadCaq/mDLq8yWDQo9JK0Yuj3Vb0NK3/P7F9Sw==}
+  '@typescript/native-preview-linux-arm64@7.0.0-dev.20260419.1':
+    resolution: {integrity: sha512-cxK8SJ0tLeAV67hKfPEkPyv6rDIeL8AyGFHJFMz+gz3mKNy6ZEPK+9B8fl/JFGPylOhspgm6+IqFepRJcw74eg==}
     cpu: [arm64]
     os: [linux]
 
-  '@typescript/native-preview-linux-arm@7.0.0-dev.20260317.1':
-    resolution: {integrity: sha512-Q6vKYOej5FoPfYzvNsUdeE4GWWKxUg9wzo2fJxgV50ZQeITEDvSpG1PxS1019kFbe3KSAoIIzSmhP/4EIie7Kg==}
+  '@typescript/native-preview-linux-arm@7.0.0-dev.20260419.1':
+    resolution: {integrity: sha512-e+BjeErUxpHb8FAYfCCrM9MvAl7yL4eYpYEW3jAaPle/K2+6BJPnUpytgB1fbrMWDmbnTWhC4m9NgTPfNHznxA==}
     cpu: [arm]
     os: [linux]
 
-  '@typescript/native-preview-linux-x64@7.0.0-dev.20260317.1':
-    resolution: {integrity: sha512-PJN4JbWrVeJ8WyWbRWVdyUHUUSL9zKqywwroXdqIDgxUO2B09bSUCCs9DFJNHXQ5NqWND/WeVPgpYfnQ95S21Q==}
+  '@typescript/native-preview-linux-x64@7.0.0-dev.20260419.1':
+    resolution: {integrity: sha512-6cf/o48dN5px6mrW8Hq7duGpimoCFAlpEsgbjYWex8Vjv2EH+S1QcWUbh3L0cAhygnxnb4f2gwovBGJqKgf6jg==}
     cpu: [x64]
     os: [linux]
 
-  '@typescript/native-preview-win32-arm64@7.0.0-dev.20260317.1':
-    resolution: {integrity: sha512-Obv+ZTK0NVfv1E/KlTz7G5EyPbE8zNA1qeT59CyoWHl0Mi2iq3njs5dRIfcRbgGDZkSI8wJ+4C4JGfUyZZGZkA==}
+  '@typescript/native-preview-win32-arm64@7.0.0-dev.20260419.1':
+    resolution: {integrity: sha512-yz7AxGsNf1cueTUv0SF5Q1LvRGVHh+F4cSwmwucGVkHJGKdLCQO7cLs4MTFY0gcqsLNr7qKH7gMh5WCQqsPVXQ==}
     cpu: [arm64]
     os: [win32]
 
-  '@typescript/native-preview-win32-x64@7.0.0-dev.20260317.1':
-    resolution: {integrity: sha512-Trt8E1nphVXaicVcXpsyiVArT6Zf+blhqGP/MPx9YEBlp1nuzxFpu1kj7A75r+6js4vIdoKieK215Q4J358qUw==}
+  '@typescript/native-preview-win32-x64@7.0.0-dev.20260419.1':
+    resolution: {integrity: sha512-3sXtVGB4dt/kNp/bQMj0H1q7WhFzVe//rTin9DWV9CpbPXY+Ue8aUIRNevneHBPp5zSsBkkJlg1BlMH1Z87mGA==}
     cpu: [x64]
     os: [win32]
 
-  '@typescript/native-preview@7.0.0-dev.20260317.1':
-    resolution: {integrity: sha512-HmYNuhDoN9OHfsSHuSRvYJobHAHDVubLvSGSrjfNL6C34fVlPkPDi+iA53LcN1pVX5J30kajcKC7Snm13xmuKA==}
+  '@typescript/native-preview@7.0.0-dev.20260419.1':
+    resolution: {integrity: sha512-PzN1nqNe0B4vqyUzZD0Da9LbbdOYhcjLVS0Rkd/lDZEuLuovZCdIpXg1hz2S7JnD4P5P+Uy1aAdO5ubv8vQVTw==}
     hasBin: true
 
   '@ungap/structured-clone@1.3.0':
@@ -7671,6 +7672,9 @@ packages:
     resolution: {integrity: sha512-BS8PfmtDGnrgYdOonGZQdLZslWIeCGFP9tpan0hi1Co2Zr2NKADsvGYA8XxuG/4UWgJ6Cjtv+YJnB6MM69QGlQ==}
     engines: {node: '>= 0.4'}
 
+  date-fns@4.1.0:
+    resolution: {integrity: sha512-Ukq0owbQXxa/U3EGtsdVBkR1w7KOQ5gIBqdH2hkvknzZPYvBxb/aa6E8L7tmjFtkwZBu3UXBbjIgPo/Ez4xaNg==}
+
   dateformat@3.0.3:
     resolution: {integrity: sha512-jyCETtSl3VMZMWeRo7iY1FL19ges1t55hMo5yaam4Jrsm5EPL89UQkoQRyiI+Yf4k8r2ZpdngkV8hr1lIdjb3Q==}
 
@@ -8380,8 +8384,8 @@ packages:
   fast-xml-builder@1.1.4:
     resolution: {integrity: sha512-f2jhpN4Eccy0/Uz9csxh3Nu6q4ErKxf0XIsasomfOihuSUa3/xw6w8dnOtCDgEItQFJG8KyXPzQXzcODDrrbOg==}
 
-  fast-xml-parser@5.4.1:
-    resolution: {integrity: sha512-BQ30U1mKkvXQXXkAGcuyUA/GA26oEB7NzOtsxCDtyu62sjGw5QraKFhx2Em3WQNjPw9PG6MQ9yuIIgkSDfGu5A==}
+  fast-xml-parser@5.5.8:
+    resolution: {integrity: sha512-Z7Fh2nVQSb2d+poDViM063ix2ZGt9jmY1nWhPfHBOK2Hgnb/OW3P4Et3P/81SEej0J7QbWtJqxO05h8QYfK7LQ==}
     hasBin: true
 
   fastest-levenshtein@1.0.16:
@@ -8481,8 +8485,8 @@ packages:
   flatqueue@3.0.0:
     resolution: {integrity: sha512-y1deYaVt+lIc/d2uIcWDNd0CrdQTO5xoCjeFdhX0kSXvm2Acm0o+3bAOiYklTEoRyzwio3sv3/IiBZdusbAe2Q==}
 
-  flatted@3.4.0:
-    resolution: {integrity: sha512-kC6Bb+ooptOIvWj5B63EQWkF0FEnNjV2ZNkLMLZRDDduIiWeFF4iKnslwhiWxjAdbg4NzTNo6h0qLuvFrcx+Sw==}
+  flatted@3.3.3:
+    resolution: {integrity: sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==}
 
   follow-redirects@1.15.11:
     resolution: {integrity: sha512-deG2P0JfjrTxl50XGCDyfI97ZGVCxIpfKYmfyrQ54n5FO/0gfIES8C/Psl6kWVDolizcaaxZJnTS0QSMxvnsBQ==}
@@ -8741,8 +8745,8 @@ packages:
     resolution: {integrity: sha512-7ACyT3wmyp3I61S4fG682L0VA2RGD9otkqGJIwNUMF1SWUombIIk+af1unuDYgMm082aHYwD+mzJvv9Iu8dsgg==}
     engines: {node: '>=18'}
 
-  globals@17.4.0:
-    resolution: {integrity: sha512-hjrNztw/VajQwOLsMNT1cbJiH2muO3OROCHnbehc8eY5JyD2gqz4AcMHPqgaOR59DjgUjYAYLeH699g/eWi2jw==}
+  globals@17.5.0:
+    resolution: {integrity: sha512-qoV+HK2yFl/366t2/Cb3+xxPUo5BuMynomoDmiaZBIdbs+0pYbjfZU+twLhGKp4uCZ/+NbtpVepH5bGCxRyy2g==}
     engines: {node: '>=18'}
 
   globalthis@1.0.4:
@@ -8934,16 +8938,19 @@ packages:
     resolution: {integrity: sha512-QY6S+hZ0f5m1WT8WffYN+Hg+xm/w5I8XeUcAq/ZYP5wVC8xbKi4Whhru3FtrAebD5EhBW8rmFzkDI6eCAuFe2w==}
     hasBin: true
 
-  html-validate@10.11.2:
-    resolution: {integrity: sha512-ZT4812sBvF77WrfTNWcaaml7xSOMDsGvw3plP4zrgcPw5RWESsRgprsVVYnaQD2lSNfD0WObZ0Ur22+xXj0TXA==}
-    engines: {node: ^20.19.0 || >= 22.16.0}
+  html-validate@10.13.1:
+    resolution: {integrity: sha512-1ox3gMhul5GwXnftNEY5nqnEQJ1B2K1GNu2uSO3nJ6D3gmGh/xsKtcSi3zelHam1nFNXyC14vTay+gpS+tbsdA==}
+    engines: {node: ^20.19.0 || ^22.16.0 || >= 24.0.0}
     hasBin: true
     peerDependencies:
+      '@jest/globals': ^28.1.3 || ^29.0.3 || ^30.0.0
       jest: ^28.1.3 || ^29.0.3 || ^30.0.0
       jest-diff: ^28.1.3 || ^29.0.3 || ^30.0.0
       jest-snapshot: ^28.1.3 || ^29.0.3 || ^30.0.0
       vitest: ^1.0.0 || ^2.0.0 || ^3.0.0 || ^4.0.1
     peerDependenciesMeta:
+      '@jest/globals':
+        optional: true
       jest:
         optional: true
       jest-diff:
@@ -10743,8 +10750,8 @@ packages:
     resolution: {integrity: sha512-RjhtfwJOxzcFmNOi6ltcbcu4Iu+FL3zEj83dk4kAS+fVpTxXLO1b38RvJgT/0QwvV/L3aY9TAnyv0EOqW4GoMQ==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
 
-  path-expression-matcher@1.1.3:
-    resolution: {integrity: sha512-qdVgY8KXmVdJZRSS1JdEPOKPdTiEK/pi0RkcT2sw1RhXxohdujUlJFPuS1TSkevZ9vzd3ZlL7ULl1MHGTApKzQ==}
+  path-expression-matcher@1.5.0:
+    resolution: {integrity: sha512-cbrerZV+6rvdQrrD+iGMcZFEiiSrbv9Tfdkvnusy6y0x0GKBXREFg/Y65GhIfm0tnLntThhzCnfKwp1WRjeCyQ==}
     engines: {node: '>=14.0.0'}
 
   path-is-absolute@1.0.1:
@@ -10887,21 +10894,11 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
-  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==}
     engines: {node: '>=18'}
     hasBin: true
 
-  playwright@1.59.1:
-    resolution: {integrity: sha512-C8oWjPR3F81yljW9o5OxcWzfh6avkVwDD2VYdwIGqTkl+OGFISgypqzfu7dOe4QNLL2aqcWBmI3PMtLIK233lw==}
-    engines: {node: '>=18'}
-    hasBin: true
-
   pluralize@3.1.0:
     resolution: {integrity: sha512-2wcybwjwXOzGI1rlxWtlcs0/nSYK0OzNPqsg35TKxJFQlGhFu3cZ1x7EHS4r4bubQlhzyF4YxxlJqQnIhkUQCw==}
 
@@ -11444,8 +11441,8 @@ packages:
     resolution: {integrity: sha512-OcXjMsGdhL4XnbShKpAcSqPMzQoYkYyhbEaeSko47MjRP9NfEQMhZkXL1DoFlt9LWQn4YttrdnV6X2OiyzBi+A==}
     engines: {node: '>=10'}
 
-  resolve@1.22.11:
-    resolution: {integrity: sha512-RfqAvLnMl313r7c9oclB1HhUEAezcpLjz95wFH4LVuhk9JF/r22qmVP9AMmOU4vMX7Q8pN8jwNg/CSpdFnMjTQ==}
+  resolve@1.22.12:
+    resolution: {integrity: sha512-TyeJ1zif53BPfHootBGwPRYT1RUt6oGWsaQr8UyZW/eAm9bKoijtvruSDEmZHm92CwS9nj7/fWttqPCgzep8CA==}
     engines: {node: '>= 0.4'}
     hasBin: true
 
@@ -11937,8 +11934,8 @@ packages:
     resolution: {integrity: sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==}
     engines: {node: '>=8'}
 
-  strnum@2.1.2:
-    resolution: {integrity: sha512-l63NF9y/cLROq/yqKXSLtcMeeyOfnSQlfMSlzFt/K73oIaD8DGaQWd7Z34X9GPiKqP5rbSh84Hl4bOlLcjiSrQ==}
+  strnum@2.2.3:
+    resolution: {integrity: sha512-oKx6RUCuHfT3oyVjtnrmn19H1SiCqgJSg+54XqURKp5aCMbrXrhLjRN9TjuwMjiYstZ0MzDrHqkGZ5dFTKd+zg==}
 
   stubborn-fs@2.0.0:
     resolution: {integrity: sha512-Y0AvSwDw8y+nlSNFXMm2g6L51rBGdAQT20J3YSOqxC53Lo3bjWRtr2BKcfYoAf352WYpsZSTURrA0tqhfgudPA==}
@@ -12884,8 +12881,8 @@ packages:
       utf-8-validate:
         optional: true
 
-  ws@8.20.0:
-    resolution: {integrity: sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==}
+  ws@8.19.0:
+    resolution: {integrity: sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==}
     engines: {node: '>=10.0.0'}
     peerDependencies:
       bufferutil: ^4.0.1
@@ -13066,7 +13063,7 @@ snapshots:
     dependencies:
       '@actions/io': 3.0.2
 
-  '@actions/github@9.0.0':
+  '@actions/github@9.1.0':
     dependencies:
       '@actions/http-client': 3.0.2
       '@octokit/core': 7.0.6
@@ -13088,16 +13085,16 @@ snapshots:
 
   '@actions/io@3.0.2': {}
 
-  '@argos-ci/api-client@0.16.1':
+  '@argos-ci/api-client@0.18.0':
     dependencies:
       debug: 4.4.3(supports-color@8.1.1)
       openapi-fetch: 0.17.0
     transitivePeerDependencies:
       - supports-color
 
-  '@argos-ci/core@5.1.3':
+  '@argos-ci/core@5.2.1':
     dependencies:
-      '@argos-ci/api-client': 0.16.1
+      '@argos-ci/api-client': 0.18.0
       '@argos-ci/util': 3.4.0
       convict: 6.2.5
       debug: 4.4.3(supports-color@8.1.1)
@@ -13139,20 +13136,20 @@ snapshots:
   '@aws-crypto/crc32@5.2.0':
     dependencies:
       '@aws-crypto/util': 5.2.0
-      '@aws-sdk/types': 3.973.6
+      '@aws-sdk/types': 3.973.8
       tslib: 2.8.1
 
   '@aws-crypto/crc32c@5.2.0':
     dependencies:
       '@aws-crypto/util': 5.2.0
-      '@aws-sdk/types': 3.973.6
+      '@aws-sdk/types': 3.973.8
       tslib: 2.8.1
 
   '@aws-crypto/sha1-browser@5.2.0':
     dependencies:
       '@aws-crypto/supports-web-crypto': 5.2.0
       '@aws-crypto/util': 5.2.0
-      '@aws-sdk/types': 3.973.6
+      '@aws-sdk/types': 3.973.8
       '@aws-sdk/util-locate-window': 3.893.0
       '@smithy/util-utf8': 2.3.0
       tslib: 2.8.1
@@ -13162,7 +13159,7 @@ snapshots:
       '@aws-crypto/sha256-js': 5.2.0
       '@aws-crypto/supports-web-crypto': 5.2.0
       '@aws-crypto/util': 5.2.0
-      '@aws-sdk/types': 3.973.6
+      '@aws-sdk/types': 3.973.8
       '@aws-sdk/util-locate-window': 3.893.0
       '@smithy/util-utf8': 2.3.0
       tslib: 2.8.1
@@ -13170,7 +13167,7 @@ snapshots:
   '@aws-crypto/sha256-js@5.2.0':
     dependencies:
       '@aws-crypto/util': 5.2.0
-      '@aws-sdk/types': 3.973.6
+      '@aws-sdk/types': 3.973.8
       tslib: 2.8.1
 
   '@aws-crypto/supports-web-crypto@5.2.0':
@@ -13179,403 +13176,403 @@ snapshots:
 
   '@aws-crypto/util@5.2.0':
     dependencies:
-      '@aws-sdk/types': 3.973.6
+      '@aws-sdk/types': 3.973.8
       '@smithy/util-utf8': 2.3.0
       tslib: 2.8.1
 
-  '@aws-sdk/client-s3@3.1009.0':
+  '@aws-sdk/client-s3@3.1032.0':
     dependencies:
       '@aws-crypto/sha1-browser': 5.2.0
       '@aws-crypto/sha256-browser': 5.2.0
       '@aws-crypto/sha256-js': 5.2.0
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/credential-provider-node': 3.972.21
-      '@aws-sdk/middleware-bucket-endpoint': 3.972.8
-      '@aws-sdk/middleware-expect-continue': 3.972.8
-      '@aws-sdk/middleware-flexible-checksums': 3.973.6
-      '@aws-sdk/middleware-host-header': 3.972.8
-      '@aws-sdk/middleware-location-constraint': 3.972.8
-      '@aws-sdk/middleware-logger': 3.972.8
-      '@aws-sdk/middleware-recursion-detection': 3.972.8
-      '@aws-sdk/middleware-sdk-s3': 3.972.20
-      '@aws-sdk/middleware-ssec': 3.972.8
-      '@aws-sdk/middleware-user-agent': 3.972.21
-      '@aws-sdk/region-config-resolver': 3.972.8
-      '@aws-sdk/signature-v4-multi-region': 3.996.8
-      '@aws-sdk/types': 3.973.6
-      '@aws-sdk/util-endpoints': 3.996.5
-      '@aws-sdk/util-user-agent-browser': 3.972.8
-      '@aws-sdk/util-user-agent-node': 3.973.7
-      '@smithy/config-resolver': 4.4.11
-      '@smithy/core': 3.23.11
-      '@smithy/eventstream-serde-browser': 4.2.12
-      '@smithy/eventstream-serde-config-resolver': 4.3.12
-      '@smithy/eventstream-serde-node': 4.2.12
-      '@smithy/fetch-http-handler': 5.3.15
-      '@smithy/hash-blob-browser': 4.2.13
-      '@smithy/hash-node': 4.2.12
-      '@smithy/hash-stream-node': 4.2.12
-      '@smithy/invalid-dependency': 4.2.12
-      '@smithy/md5-js': 4.2.12
-      '@smithy/middleware-content-length': 4.2.12
-      '@smithy/middleware-endpoint': 4.4.25
-      '@smithy/middleware-retry': 4.4.42
-      '@smithy/middleware-serde': 4.2.14
-      '@smithy/middleware-stack': 4.2.12
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/node-http-handler': 4.4.16
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/smithy-client': 4.12.5
-      '@smithy/types': 4.13.1
-      '@smithy/url-parser': 4.2.12
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/credential-provider-node': 3.972.32
+      '@aws-sdk/middleware-bucket-endpoint': 3.972.10
+      '@aws-sdk/middleware-expect-continue': 3.972.10
+      '@aws-sdk/middleware-flexible-checksums': 3.974.9
+      '@aws-sdk/middleware-host-header': 3.972.10
+      '@aws-sdk/middleware-location-constraint': 3.972.10
+      '@aws-sdk/middleware-logger': 3.972.10
+      '@aws-sdk/middleware-recursion-detection': 3.972.11
+      '@aws-sdk/middleware-sdk-s3': 3.972.30
+      '@aws-sdk/middleware-ssec': 3.972.10
+      '@aws-sdk/middleware-user-agent': 3.972.31
+      '@aws-sdk/region-config-resolver': 3.972.12
+      '@aws-sdk/signature-v4-multi-region': 3.996.18
+      '@aws-sdk/types': 3.973.8
+      '@aws-sdk/util-endpoints': 3.996.7
+      '@aws-sdk/util-user-agent-browser': 3.972.10
+      '@aws-sdk/util-user-agent-node': 3.973.17
+      '@smithy/config-resolver': 4.4.16
+      '@smithy/core': 3.23.15
+      '@smithy/eventstream-serde-browser': 4.2.14
+      '@smithy/eventstream-serde-config-resolver': 4.3.14
+      '@smithy/eventstream-serde-node': 4.2.14
+      '@smithy/fetch-http-handler': 5.3.17
+      '@smithy/hash-blob-browser': 4.2.15
+      '@smithy/hash-node': 4.2.14
+      '@smithy/hash-stream-node': 4.2.14
+      '@smithy/invalid-dependency': 4.2.14
+      '@smithy/md5-js': 4.2.14
+      '@smithy/middleware-content-length': 4.2.14
+      '@smithy/middleware-endpoint': 4.4.30
+      '@smithy/middleware-retry': 4.5.3
+      '@smithy/middleware-serde': 4.2.18
+      '@smithy/middleware-stack': 4.2.14
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/node-http-handler': 4.5.3
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/smithy-client': 4.12.11
+      '@smithy/types': 4.14.1
+      '@smithy/url-parser': 4.2.14
       '@smithy/util-base64': 4.3.2
       '@smithy/util-body-length-browser': 4.2.2
       '@smithy/util-body-length-node': 4.2.3
-      '@smithy/util-defaults-mode-browser': 4.3.41
-      '@smithy/util-defaults-mode-node': 4.2.44
-      '@smithy/util-endpoints': 3.3.3
-      '@smithy/util-middleware': 4.2.12
-      '@smithy/util-retry': 4.2.12
-      '@smithy/util-stream': 4.5.19
+      '@smithy/util-defaults-mode-browser': 4.3.47
+      '@smithy/util-defaults-mode-node': 4.2.52
+      '@smithy/util-endpoints': 3.4.1
+      '@smithy/util-middleware': 4.2.14
+      '@smithy/util-retry': 4.3.2
+      '@smithy/util-stream': 4.5.23
       '@smithy/util-utf8': 4.2.2
-      '@smithy/util-waiter': 4.2.13
+      '@smithy/util-waiter': 4.2.16
       tslib: 2.8.1
     transitivePeerDependencies:
       - aws-crt
 
-  '@aws-sdk/core@3.973.20':
-    dependencies:
-      '@aws-sdk/types': 3.973.6
-      '@aws-sdk/xml-builder': 3.972.11
-      '@smithy/core': 3.23.11
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/property-provider': 4.2.12
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/signature-v4': 5.3.12
-      '@smithy/smithy-client': 4.12.5
-      '@smithy/types': 4.13.1
+  '@aws-sdk/core@3.974.1':
+    dependencies:
+      '@aws-sdk/types': 3.973.8
+      '@aws-sdk/xml-builder': 3.972.18
+      '@smithy/core': 3.23.15
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/property-provider': 4.2.14
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/signature-v4': 5.3.14
+      '@smithy/smithy-client': 4.12.11
+      '@smithy/types': 4.14.1
       '@smithy/util-base64': 4.3.2
-      '@smithy/util-middleware': 4.2.12
+      '@smithy/util-middleware': 4.2.14
       '@smithy/util-utf8': 4.2.2
       tslib: 2.8.1
 
-  '@aws-sdk/crc64-nvme@3.972.5':
+  '@aws-sdk/crc64-nvme@3.972.7':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@aws-sdk/credential-provider-env@3.972.18':
+  '@aws-sdk/credential-provider-env@3.972.27':
     dependencies:
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/types': 3.973.6
-      '@smithy/property-provider': 4.2.12
-      '@smithy/types': 4.13.1
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/types': 3.973.8
+      '@smithy/property-provider': 4.2.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@aws-sdk/credential-provider-http@3.972.20':
-    dependencies:
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/types': 3.973.6
-      '@smithy/fetch-http-handler': 5.3.15
-      '@smithy/node-http-handler': 4.4.16
-      '@smithy/property-provider': 4.2.12
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/smithy-client': 4.12.5
-      '@smithy/types': 4.13.1
-      '@smithy/util-stream': 4.5.19
+  '@aws-sdk/credential-provider-http@3.972.29':
+    dependencies:
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/types': 3.973.8
+      '@smithy/fetch-http-handler': 5.3.17
+      '@smithy/node-http-handler': 4.5.3
+      '@smithy/property-provider': 4.2.14
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/smithy-client': 4.12.11
+      '@smithy/types': 4.14.1
+      '@smithy/util-stream': 4.5.23
       tslib: 2.8.1
 
-  '@aws-sdk/credential-provider-ini@3.972.20':
-    dependencies:
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/credential-provider-env': 3.972.18
-      '@aws-sdk/credential-provider-http': 3.972.20
-      '@aws-sdk/credential-provider-login': 3.972.20
-      '@aws-sdk/credential-provider-process': 3.972.18
-      '@aws-sdk/credential-provider-sso': 3.972.20
-      '@aws-sdk/credential-provider-web-identity': 3.972.20
-      '@aws-sdk/nested-clients': 3.996.10
-      '@aws-sdk/types': 3.973.6
-      '@smithy/credential-provider-imds': 4.2.12
-      '@smithy/property-provider': 4.2.12
-      '@smithy/shared-ini-file-loader': 4.4.7
-      '@smithy/types': 4.13.1
+  '@aws-sdk/credential-provider-ini@3.972.31':
+    dependencies:
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/credential-provider-env': 3.972.27
+      '@aws-sdk/credential-provider-http': 3.972.29
+      '@aws-sdk/credential-provider-login': 3.972.31
+      '@aws-sdk/credential-provider-process': 3.972.27
+      '@aws-sdk/credential-provider-sso': 3.972.31
+      '@aws-sdk/credential-provider-web-identity': 3.972.31
+      '@aws-sdk/nested-clients': 3.996.21
+      '@aws-sdk/types': 3.973.8
+      '@smithy/credential-provider-imds': 4.2.14
+      '@smithy/property-provider': 4.2.14
+      '@smithy/shared-ini-file-loader': 4.4.9
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
     transitivePeerDependencies:
       - aws-crt
 
-  '@aws-sdk/credential-provider-login@3.972.20':
+  '@aws-sdk/credential-provider-login@3.972.31':
     dependencies:
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/nested-clients': 3.996.10
-      '@aws-sdk/types': 3.973.6
-      '@smithy/property-provider': 4.2.12
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/shared-ini-file-loader': 4.4.7
-      '@smithy/types': 4.13.1
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/nested-clients': 3.996.21
+      '@aws-sdk/types': 3.973.8
+      '@smithy/property-provider': 4.2.14
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/shared-ini-file-loader': 4.4.9
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
     transitivePeerDependencies:
       - aws-crt
 
-  '@aws-sdk/credential-provider-node@3.972.21':
-    dependencies:
-      '@aws-sdk/credential-provider-env': 3.972.18
-      '@aws-sdk/credential-provider-http': 3.972.20
-      '@aws-sdk/credential-provider-ini': 3.972.20
-      '@aws-sdk/credential-provider-process': 3.972.18
-      '@aws-sdk/credential-provider-sso': 3.972.20
-      '@aws-sdk/credential-provider-web-identity': 3.972.20
-      '@aws-sdk/types': 3.973.6
-      '@smithy/credential-provider-imds': 4.2.12
-      '@smithy/property-provider': 4.2.12
-      '@smithy/shared-ini-file-loader': 4.4.7
-      '@smithy/types': 4.13.1
+  '@aws-sdk/credential-provider-node@3.972.32':
+    dependencies:
+      '@aws-sdk/credential-provider-env': 3.972.27
+      '@aws-sdk/credential-provider-http': 3.972.29
+      '@aws-sdk/credential-provider-ini': 3.972.31
+      '@aws-sdk/credential-provider-process': 3.972.27
+      '@aws-sdk/credential-provider-sso': 3.972.31
+      '@aws-sdk/credential-provider-web-identity': 3.972.31
+      '@aws-sdk/types': 3.973.8
+      '@smithy/credential-provider-imds': 4.2.14
+      '@smithy/property-provider': 4.2.14
+      '@smithy/shared-ini-file-loader': 4.4.9
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
     transitivePeerDependencies:
       - aws-crt
 
-  '@aws-sdk/credential-provider-process@3.972.18':
+  '@aws-sdk/credential-provider-process@3.972.27':
     dependencies:
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/types': 3.973.6
-      '@smithy/property-provider': 4.2.12
-      '@smithy/shared-ini-file-loader': 4.4.7
-      '@smithy/types': 4.13.1
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/types': 3.973.8
+      '@smithy/property-provider': 4.2.14
+      '@smithy/shared-ini-file-loader': 4.4.9
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@aws-sdk/credential-provider-sso@3.972.20':
+  '@aws-sdk/credential-provider-sso@3.972.31':
     dependencies:
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/nested-clients': 3.996.10
-      '@aws-sdk/token-providers': 3.1009.0
-      '@aws-sdk/types': 3.973.6
-      '@smithy/property-provider': 4.2.12
-      '@smithy/shared-ini-file-loader': 4.4.7
-      '@smithy/types': 4.13.1
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/nested-clients': 3.996.21
+      '@aws-sdk/token-providers': 3.1032.0
+      '@aws-sdk/types': 3.973.8
+      '@smithy/property-provider': 4.2.14
+      '@smithy/shared-ini-file-loader': 4.4.9
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
     transitivePeerDependencies:
       - aws-crt
 
-  '@aws-sdk/credential-provider-web-identity@3.972.20':
+  '@aws-sdk/credential-provider-web-identity@3.972.31':
     dependencies:
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/nested-clients': 3.996.10
-      '@aws-sdk/types': 3.973.6
-      '@smithy/property-provider': 4.2.12
-      '@smithy/shared-ini-file-loader': 4.4.7
-      '@smithy/types': 4.13.1
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/nested-clients': 3.996.21
+      '@aws-sdk/types': 3.973.8
+      '@smithy/property-provider': 4.2.14
+      '@smithy/shared-ini-file-loader': 4.4.9
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
     transitivePeerDependencies:
       - aws-crt
 
-  '@aws-sdk/middleware-bucket-endpoint@3.972.8':
+  '@aws-sdk/middleware-bucket-endpoint@3.972.10':
     dependencies:
-      '@aws-sdk/types': 3.973.6
+      '@aws-sdk/types': 3.973.8
       '@aws-sdk/util-arn-parser': 3.972.3
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/types': 4.13.1
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/types': 4.14.1
       '@smithy/util-config-provider': 4.2.2
       tslib: 2.8.1
 
-  '@aws-sdk/middleware-expect-continue@3.972.8':
+  '@aws-sdk/middleware-expect-continue@3.972.10':
     dependencies:
-      '@aws-sdk/types': 3.973.6
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/types': 4.13.1
+      '@aws-sdk/types': 3.973.8
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@aws-sdk/middleware-flexible-checksums@3.973.6':
+  '@aws-sdk/middleware-flexible-checksums@3.974.9':
     dependencies:
       '@aws-crypto/crc32': 5.2.0
       '@aws-crypto/crc32c': 5.2.0
       '@aws-crypto/util': 5.2.0
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/crc64-nvme': 3.972.5
-      '@aws-sdk/types': 3.973.6
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/crc64-nvme': 3.972.7
+      '@aws-sdk/types': 3.973.8
       '@smithy/is-array-buffer': 4.2.2
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/types': 4.13.1
-      '@smithy/util-middleware': 4.2.12
-      '@smithy/util-stream': 4.5.19
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/types': 4.14.1
+      '@smithy/util-middleware': 4.2.14
+      '@smithy/util-stream': 4.5.23
       '@smithy/util-utf8': 4.2.2
       tslib: 2.8.1
 
-  '@aws-sdk/middleware-host-header@3.972.8':
+  '@aws-sdk/middleware-host-header@3.972.10':
     dependencies:
-      '@aws-sdk/types': 3.973.6
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/types': 4.13.1
+      '@aws-sdk/types': 3.973.8
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@aws-sdk/middleware-location-constraint@3.972.8':
+  '@aws-sdk/middleware-location-constraint@3.972.10':
     dependencies:
-      '@aws-sdk/types': 3.973.6
-      '@smithy/types': 4.13.1
+      '@aws-sdk/types': 3.973.8
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@aws-sdk/middleware-logger@3.972.8':
+  '@aws-sdk/middleware-logger@3.972.10':
     dependencies:
-      '@aws-sdk/types': 3.973.6
-      '@smithy/types': 4.13.1
+      '@aws-sdk/types': 3.973.8
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@aws-sdk/middleware-recursion-detection@3.972.8':
+  '@aws-sdk/middleware-recursion-detection@3.972.11':
     dependencies:
-      '@aws-sdk/types': 3.973.6
+      '@aws-sdk/types': 3.973.8
       '@aws/lambda-invoke-store': 0.2.2
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/types': 4.13.1
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@aws-sdk/middleware-sdk-s3@3.972.20':
+  '@aws-sdk/middleware-sdk-s3@3.972.30':
     dependencies:
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/types': 3.973.6
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/types': 3.973.8
       '@aws-sdk/util-arn-parser': 3.972.3
-      '@smithy/core': 3.23.11
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/signature-v4': 5.3.12
-      '@smithy/smithy-client': 4.12.5
-      '@smithy/types': 4.13.1
+      '@smithy/core': 3.23.15
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/signature-v4': 5.3.14
+      '@smithy/smithy-client': 4.12.11
+      '@smithy/types': 4.14.1
       '@smithy/util-config-provider': 4.2.2
-      '@smithy/util-middleware': 4.2.12
-      '@smithy/util-stream': 4.5.19
+      '@smithy/util-middleware': 4.2.14
+      '@smithy/util-stream': 4.5.23
       '@smithy/util-utf8': 4.2.2
       tslib: 2.8.1
 
-  '@aws-sdk/middleware-ssec@3.972.8':
+  '@aws-sdk/middleware-ssec@3.972.10':
     dependencies:
-      '@aws-sdk/types': 3.973.6
-      '@smithy/types': 4.13.1
+      '@aws-sdk/types': 3.973.8
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@aws-sdk/middleware-user-agent@3.972.21':
+  '@aws-sdk/middleware-user-agent@3.972.31':
     dependencies:
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/types': 3.973.6
-      '@aws-sdk/util-endpoints': 3.996.5
-      '@smithy/core': 3.23.11
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/types': 4.13.1
-      '@smithy/util-retry': 4.2.12
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/types': 3.973.8
+      '@aws-sdk/util-endpoints': 3.996.7
+      '@smithy/core': 3.23.15
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/types': 4.14.1
+      '@smithy/util-retry': 4.3.2
       tslib: 2.8.1
 
-  '@aws-sdk/nested-clients@3.996.10':
+  '@aws-sdk/nested-clients@3.996.21':
     dependencies:
       '@aws-crypto/sha256-browser': 5.2.0
       '@aws-crypto/sha256-js': 5.2.0
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/middleware-host-header': 3.972.8
-      '@aws-sdk/middleware-logger': 3.972.8
-      '@aws-sdk/middleware-recursion-detection': 3.972.8
-      '@aws-sdk/middleware-user-agent': 3.972.21
-      '@aws-sdk/region-config-resolver': 3.972.8
-      '@aws-sdk/types': 3.973.6
-      '@aws-sdk/util-endpoints': 3.996.5
-      '@aws-sdk/util-user-agent-browser': 3.972.8
-      '@aws-sdk/util-user-agent-node': 3.973.7
-      '@smithy/config-resolver': 4.4.11
-      '@smithy/core': 3.23.11
-      '@smithy/fetch-http-handler': 5.3.15
-      '@smithy/hash-node': 4.2.12
-      '@smithy/invalid-dependency': 4.2.12
-      '@smithy/middleware-content-length': 4.2.12
-      '@smithy/middleware-endpoint': 4.4.25
-      '@smithy/middleware-retry': 4.4.42
-      '@smithy/middleware-serde': 4.2.14
-      '@smithy/middleware-stack': 4.2.12
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/node-http-handler': 4.4.16
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/smithy-client': 4.12.5
-      '@smithy/types': 4.13.1
-      '@smithy/url-parser': 4.2.12
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/middleware-host-header': 3.972.10
+      '@aws-sdk/middleware-logger': 3.972.10
+      '@aws-sdk/middleware-recursion-detection': 3.972.11
+      '@aws-sdk/middleware-user-agent': 3.972.31
+      '@aws-sdk/region-config-resolver': 3.972.12
+      '@aws-sdk/types': 3.973.8
+      '@aws-sdk/util-endpoints': 3.996.7
+      '@aws-sdk/util-user-agent-browser': 3.972.10
+      '@aws-sdk/util-user-agent-node': 3.973.17
+      '@smithy/config-resolver': 4.4.16
+      '@smithy/core': 3.23.15
+      '@smithy/fetch-http-handler': 5.3.17
+      '@smithy/hash-node': 4.2.14
+      '@smithy/invalid-dependency': 4.2.14
+      '@smithy/middleware-content-length': 4.2.14
+      '@smithy/middleware-endpoint': 4.4.30
+      '@smithy/middleware-retry': 4.5.3
+      '@smithy/middleware-serde': 4.2.18
+      '@smithy/middleware-stack': 4.2.14
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/node-http-handler': 4.5.3
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/smithy-client': 4.12.11
+      '@smithy/types': 4.14.1
+      '@smithy/url-parser': 4.2.14
       '@smithy/util-base64': 4.3.2
       '@smithy/util-body-length-browser': 4.2.2
       '@smithy/util-body-length-node': 4.2.3
-      '@smithy/util-defaults-mode-browser': 4.3.41
-      '@smithy/util-defaults-mode-node': 4.2.44
-      '@smithy/util-endpoints': 3.3.3
-      '@smithy/util-middleware': 4.2.12
-      '@smithy/util-retry': 4.2.12
+      '@smithy/util-defaults-mode-browser': 4.3.47
+      '@smithy/util-defaults-mode-node': 4.2.52
+      '@smithy/util-endpoints': 3.4.1
+      '@smithy/util-middleware': 4.2.14
+      '@smithy/util-retry': 4.3.2
       '@smithy/util-utf8': 4.2.2
       tslib: 2.8.1
     transitivePeerDependencies:
       - aws-crt
 
-  '@aws-sdk/region-config-resolver@3.972.8':
+  '@aws-sdk/region-config-resolver@3.972.12':
     dependencies:
-      '@aws-sdk/types': 3.973.6
-      '@smithy/config-resolver': 4.4.11
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/types': 4.13.1
+      '@aws-sdk/types': 3.973.8
+      '@smithy/config-resolver': 4.4.16
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@aws-sdk/signature-v4-multi-region@3.996.8':
+  '@aws-sdk/signature-v4-multi-region@3.996.18':
     dependencies:
-      '@aws-sdk/middleware-sdk-s3': 3.972.20
-      '@aws-sdk/types': 3.973.6
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/signature-v4': 5.3.12
-      '@smithy/types': 4.13.1
+      '@aws-sdk/middleware-sdk-s3': 3.972.30
+      '@aws-sdk/types': 3.973.8
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/signature-v4': 5.3.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@aws-sdk/token-providers@3.1009.0':
+  '@aws-sdk/token-providers@3.1032.0':
     dependencies:
-      '@aws-sdk/core': 3.973.20
-      '@aws-sdk/nested-clients': 3.996.10
-      '@aws-sdk/types': 3.973.6
-      '@smithy/property-provider': 4.2.12
-      '@smithy/shared-ini-file-loader': 4.4.7
-      '@smithy/types': 4.13.1
+      '@aws-sdk/core': 3.974.1
+      '@aws-sdk/nested-clients': 3.996.21
+      '@aws-sdk/types': 3.973.8
+      '@smithy/property-provider': 4.2.14
+      '@smithy/shared-ini-file-loader': 4.4.9
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
     transitivePeerDependencies:
       - aws-crt
 
-  '@aws-sdk/types@3.973.6':
+  '@aws-sdk/types@3.973.8':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
   '@aws-sdk/util-arn-parser@3.972.3':
     dependencies:
       tslib: 2.8.1
 
-  '@aws-sdk/util-endpoints@3.996.5':
+  '@aws-sdk/util-endpoints@3.996.7':
     dependencies:
-      '@aws-sdk/types': 3.973.6
-      '@smithy/types': 4.13.1
-      '@smithy/url-parser': 4.2.12
-      '@smithy/util-endpoints': 3.3.3
+      '@aws-sdk/types': 3.973.8
+      '@smithy/types': 4.14.1
+      '@smithy/url-parser': 4.2.14
+      '@smithy/util-endpoints': 3.4.1
       tslib: 2.8.1
 
   '@aws-sdk/util-locate-window@3.893.0':
     dependencies:
       tslib: 2.8.1
 
-  '@aws-sdk/util-user-agent-browser@3.972.8':
+  '@aws-sdk/util-user-agent-browser@3.972.10':
     dependencies:
-      '@aws-sdk/types': 3.973.6
-      '@smithy/types': 4.13.1
+      '@aws-sdk/types': 3.973.8
+      '@smithy/types': 4.14.1
       bowser: 2.12.1
       tslib: 2.8.1
 
-  '@aws-sdk/util-user-agent-node@3.973.7':
+  '@aws-sdk/util-user-agent-node@3.973.17':
     dependencies:
-      '@aws-sdk/middleware-user-agent': 3.972.21
-      '@aws-sdk/types': 3.973.6
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/types': 4.13.1
+      '@aws-sdk/middleware-user-agent': 3.972.31
+      '@aws-sdk/types': 3.973.8
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/types': 4.14.1
       '@smithy/util-config-provider': 4.2.2
       tslib: 2.8.1
 
-  '@aws-sdk/xml-builder@3.972.11':
+  '@aws-sdk/xml-builder@3.972.18':
     dependencies:
-      '@smithy/types': 4.13.1
-      fast-xml-parser: 5.4.1
+      '@smithy/types': 4.14.1
+      fast-xml-parser: 5.5.8
       tslib: 2.8.1
 
   '@aws/lambda-invoke-store@0.2.2': {}
@@ -13669,7 +13666,7 @@ snapshots:
       '@babel/helper-plugin-utils': 7.28.6
       debug: 4.4.3(supports-color@8.1.1)
       lodash.debounce: 4.0.8
-      resolve: 1.22.11
+      resolve: 1.22.12
     transitivePeerDependencies:
       - supports-color
 
@@ -14382,6 +14379,17 @@ snapshots:
     optionalDependencies:
       '@types/react': 19.2.14
 
+  '@base-ui/utils@0.2.7(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@babel/runtime': 7.29.2
+      '@floating-ui/utils': 0.2.11
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      reselect: 5.1.1
+      use-sync-external-store: 1.6.0(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+
   '@bcoe/v8-coverage@1.0.2': {}
 
   '@blazediff/core@1.9.1': {}
@@ -14960,9 +14968,7 @@ snapshots:
     dependencies:
       ip-address: 5.9.4
 
-  '@html-validate/stylish@5.0.0':
-    dependencies:
-      kleur: 4.1.5
+  '@html-validate/stylish@5.2.0': {}
 
   '@humanfs/core@0.19.1': {}
 
@@ -15077,7 +15083,7 @@ snapshots:
 
   '@inquirer/ansi@1.0.2': {}
 
-  '@inquirer/ansi@2.0.4': {}
+  '@inquirer/ansi@2.0.5': {}
 
   '@inquirer/checkbox@4.3.0(@types/node@22.19.0)':
     dependencies:
@@ -15096,10 +15102,10 @@ snapshots:
     optionalDependencies:
       '@types/node': 22.19.0
 
-  '@inquirer/confirm@6.0.10(@types/node@22.19.0)':
+  '@inquirer/confirm@6.0.11(@types/node@22.19.0)':
     dependencies:
-      '@inquirer/core': 11.1.7(@types/node@22.19.0)
-      '@inquirer/type': 4.0.4(@types/node@22.19.0)
+      '@inquirer/core': 11.1.8(@types/node@22.19.0)
+      '@inquirer/type': 4.0.5(@types/node@22.19.0)
     optionalDependencies:
       '@types/node': 22.19.0
 
@@ -15116,11 +15122,11 @@ snapshots:
     optionalDependencies:
       '@types/node': 22.19.0
 
-  '@inquirer/core@11.1.7(@types/node@22.19.0)':
+  '@inquirer/core@11.1.8(@types/node@22.19.0)':
     dependencies:
-      '@inquirer/ansi': 2.0.4
-      '@inquirer/figures': 2.0.4
-      '@inquirer/type': 4.0.4(@types/node@22.19.0)
+      '@inquirer/ansi': 2.0.5
+      '@inquirer/figures': 2.0.5
+      '@inquirer/type': 4.0.5(@types/node@22.19.0)
       cli-width: 4.1.0
       fast-wrap-ansi: 0.2.0
       mute-stream: 3.0.0
@@ -15153,7 +15159,7 @@ snapshots:
 
   '@inquirer/figures@1.0.15': {}
 
-  '@inquirer/figures@2.0.4': {}
+  '@inquirer/figures@2.0.5': {}
 
   '@inquirer/input@4.2.5(@types/node@22.19.0)':
     dependencies:
@@ -15219,12 +15225,12 @@ snapshots:
     optionalDependencies:
       '@types/node': 22.19.0
 
-  '@inquirer/select@5.1.2(@types/node@22.19.0)':
+  '@inquirer/select@5.1.3(@types/node@22.19.0)':
     dependencies:
-      '@inquirer/ansi': 2.0.4
-      '@inquirer/core': 11.1.7(@types/node@22.19.0)
-      '@inquirer/figures': 2.0.4
-      '@inquirer/type': 4.0.4(@types/node@22.19.0)
+      '@inquirer/ansi': 2.0.5
+      '@inquirer/core': 11.1.8(@types/node@22.19.0)
+      '@inquirer/figures': 2.0.5
+      '@inquirer/type': 4.0.5(@types/node@22.19.0)
     optionalDependencies:
       '@types/node': 22.19.0
 
@@ -15232,7 +15238,7 @@ snapshots:
     optionalDependencies:
       '@types/node': 22.19.0
 
-  '@inquirer/type@4.0.4(@types/node@22.19.0)':
+  '@inquirer/type@4.0.5(@types/node@22.19.0)':
     optionalDependencies:
       '@types/node': 22.19.0
 
@@ -15406,11 +15412,11 @@ snapshots:
       '@emotion/styled': 11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
       '@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.4))(@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.4(react@19.2.4))(react@19.2.4))(react@19.2.4)':
+  '@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.4))(@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.4(react@19.2.4))(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@babel/runtime': 7.29.2
       '@emotion/react': 11.14.0(@types/react@19.2.14)(react@19.2.4)
-      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.4(react@19.2.4))(react@19.2.4)
+      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.4(react@19.2.4))(react@19.2.4)
       react: 19.2.4
     optionalDependencies:
       '@emotion/cache': 11.14.0
@@ -16179,13 +16185,13 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
-  '@mui/x-date-pickers-pro@7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(dayjs@1.11.13)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+  '@mui/x-date-pickers-pro@7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(dayjs@1.11.13)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@babel/runtime': 7.29.2
       '@mui/material': 6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/system': 6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
       '@mui/utils': 6.4.9(@types/react@19.2.14)(react@19.2.4)
-      '@mui/x-date-pickers': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(dayjs@1.11.13)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@mui/x-date-pickers': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(dayjs@1.11.13)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/x-internals': 7.26.0(@types/react@19.2.14)(react@19.2.4)
       '@mui/x-license': 7.26.0(@types/react@19.2.14)(react@19.2.4)
       clsx: 2.1.1
@@ -16196,18 +16202,19 @@ snapshots:
     optionalDependencies:
       '@emotion/react': 11.14.0(@types/react@19.2.14)(react@19.2.4)
       '@emotion/styled': 11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
+      date-fns: 4.1.0
       dayjs: 1.11.13
       luxon: 3.7.2
     transitivePeerDependencies:
       - '@types/react'
 
-  '@mui/x-date-pickers-pro@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+  '@mui/x-date-pickers-pro@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@babel/runtime': 7.29.2
       '@mui/material': 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/system': 9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
       '@mui/utils': 7.3.8(@types/react@19.2.14)(react@19.2.4)
-      '@mui/x-date-pickers': 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@mui/x-date-pickers': 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/x-internals': 9.0.0-alpha.2(@types/react@19.2.14)(react@19.2.4)
       '@mui/x-license': 9.0.0-alpha.2(@types/react@19.2.14)(react@19.2.4)
       clsx: 2.1.1
@@ -16218,12 +16225,13 @@ snapshots:
     optionalDependencies:
       '@emotion/react': 11.14.0(@types/react@19.2.14)(react@19.2.4)
       '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
+      date-fns: 4.1.0
       dayjs: 1.11.20
       luxon: 3.7.2
     transitivePeerDependencies:
       - '@types/react'
 
-  '@mui/x-date-pickers@7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(dayjs@1.11.13)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+  '@mui/x-date-pickers@7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(dayjs@1.11.13)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@babel/runtime': 7.29.2
       '@mui/material': 6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -16239,12 +16247,13 @@ snapshots:
     optionalDependencies:
       '@emotion/react': 11.14.0(@types/react@19.2.14)(react@19.2.4)
       '@emotion/styled': 11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
+      date-fns: 4.1.0
       dayjs: 1.11.13
       luxon: 3.7.2
     transitivePeerDependencies:
       - '@types/react'
 
-  '@mui/x-date-pickers@7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+  '@mui/x-date-pickers@7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@babel/runtime': 7.29.2
       '@mui/material': 9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -16260,12 +16269,13 @@ snapshots:
     optionalDependencies:
       '@emotion/react': 11.14.0(@types/react@19.2.14)(react@19.2.4)
       '@emotion/styled': 11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
+      date-fns: 4.1.0
       dayjs: 1.11.20
       luxon: 3.7.2
     transitivePeerDependencies:
       - '@types/react'
 
-  '@mui/x-date-pickers@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+  '@mui/x-date-pickers@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@babel/runtime': 7.29.2
       '@mui/material': 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -16281,6 +16291,7 @@ snapshots:
     optionalDependencies:
       '@emotion/react': 11.14.0(@types/react@19.2.14)(react@19.2.4)
       '@emotion/styled': 11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
+      date-fns: 4.1.0
       dayjs: 1.11.20
       luxon: 3.7.2
     transitivePeerDependencies:
@@ -16388,7 +16399,7 @@ snapshots:
   '@mui/x-tree-view-pro@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@babel/runtime': 7.29.2
-      '@base-ui/utils': 0.2.6(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@base-ui/utils': 0.2.7(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/material': 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/system': 9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
       '@mui/utils': 7.3.8(@types/react@19.2.14)(react@19.2.4)
@@ -16432,7 +16443,7 @@ snapshots:
   '@mui/x-tree-view@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@babel/runtime': 7.29.2
-      '@base-ui/utils': 0.2.6(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@base-ui/utils': 0.2.7(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/material': 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/system': 9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
       '@mui/utils': 7.3.8(@types/react@19.2.14)(react@19.2.4)
@@ -16625,7 +16636,7 @@ snapshots:
     dependencies:
       fast-glob: 3.3.1
 
-  '@next/mdx@16.2.1(@mdx-js/loader@3.1.1(webpack@5.102.1(esbuild@0.27.1)(jiti@2.6.1)))(@mdx-js/react@3.1.1(@types/react@19.2.14)(react@19.2.4))':
+  '@next/mdx@16.1.6(@mdx-js/loader@3.1.1(webpack@5.102.1(esbuild@0.27.1)(jiti@2.6.1)))(@mdx-js/react@3.1.1(@types/react@19.2.14)(react@19.2.4))':
     dependencies:
       source-map: 0.7.6
     optionalDependencies:
@@ -17088,11 +17099,6 @@ snapshots:
     dependencies:
       playwright: 1.58.2
 
-  '@playwright/test@1.59.1':
-    dependencies:
-      playwright: 1.59.1
-    optional: true
-
   '@pnpm/config.env-replace@1.1.0': {}
 
   '@pnpm/constants@1001.3.1': {}
@@ -18023,7 +18029,7 @@ snapshots:
 
   '@sec-ant/readable-stream@0.4.1': {}
 
-  '@sidvind/better-ajv-errors@4.0.1(ajv@8.18.0)':
+  '@sidvind/better-ajv-errors@5.0.0(ajv@8.18.0)':
     dependencies:
       ajv: 8.18.0
       kleur: 4.1.5
@@ -18064,11 +18070,6 @@ snapshots:
 
   '@sindresorhus/merge-streams@4.0.0': {}
 
-  '@smithy/abort-controller@4.2.12':
-    dependencies:
-      '@smithy/types': 4.13.1
-      tslib: 2.8.1
-
   '@smithy/chunked-blob-reader-native@4.2.3':
     dependencies:
       '@smithy/util-base64': 4.3.2
@@ -18078,97 +18079,97 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
-  '@smithy/config-resolver@4.4.11':
+  '@smithy/config-resolver@4.4.16':
     dependencies:
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/types': 4.13.1
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/types': 4.14.1
       '@smithy/util-config-provider': 4.2.2
-      '@smithy/util-endpoints': 3.3.3
-      '@smithy/util-middleware': 4.2.12
+      '@smithy/util-endpoints': 3.4.1
+      '@smithy/util-middleware': 4.2.14
       tslib: 2.8.1
 
-  '@smithy/core@3.23.11':
+  '@smithy/core@3.23.15':
     dependencies:
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/types': 4.13.1
-      '@smithy/url-parser': 4.2.12
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/types': 4.14.1
+      '@smithy/url-parser': 4.2.14
       '@smithy/util-base64': 4.3.2
       '@smithy/util-body-length-browser': 4.2.2
-      '@smithy/util-middleware': 4.2.12
-      '@smithy/util-stream': 4.5.19
+      '@smithy/util-middleware': 4.2.14
+      '@smithy/util-stream': 4.5.23
       '@smithy/util-utf8': 4.2.2
       '@smithy/uuid': 1.1.2
       tslib: 2.8.1
 
-  '@smithy/credential-provider-imds@4.2.12':
+  '@smithy/credential-provider-imds@4.2.14':
     dependencies:
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/property-provider': 4.2.12
-      '@smithy/types': 4.13.1
-      '@smithy/url-parser': 4.2.12
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/property-provider': 4.2.14
+      '@smithy/types': 4.14.1
+      '@smithy/url-parser': 4.2.14
       tslib: 2.8.1
 
-  '@smithy/eventstream-codec@4.2.12':
+  '@smithy/eventstream-codec@4.2.14':
     dependencies:
       '@aws-crypto/crc32': 5.2.0
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       '@smithy/util-hex-encoding': 4.2.2
       tslib: 2.8.1
 
-  '@smithy/eventstream-serde-browser@4.2.12':
+  '@smithy/eventstream-serde-browser@4.2.14':
     dependencies:
-      '@smithy/eventstream-serde-universal': 4.2.12
-      '@smithy/types': 4.13.1
+      '@smithy/eventstream-serde-universal': 4.2.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/eventstream-serde-config-resolver@4.3.12':
+  '@smithy/eventstream-serde-config-resolver@4.3.14':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/eventstream-serde-node@4.2.12':
+  '@smithy/eventstream-serde-node@4.2.14':
     dependencies:
-      '@smithy/eventstream-serde-universal': 4.2.12
-      '@smithy/types': 4.13.1
+      '@smithy/eventstream-serde-universal': 4.2.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/eventstream-serde-universal@4.2.12':
+  '@smithy/eventstream-serde-universal@4.2.14':
     dependencies:
-      '@smithy/eventstream-codec': 4.2.12
-      '@smithy/types': 4.13.1
+      '@smithy/eventstream-codec': 4.2.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/fetch-http-handler@5.3.15':
+  '@smithy/fetch-http-handler@5.3.17':
     dependencies:
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/querystring-builder': 4.2.12
-      '@smithy/types': 4.13.1
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/querystring-builder': 4.2.14
+      '@smithy/types': 4.14.1
       '@smithy/util-base64': 4.3.2
       tslib: 2.8.1
 
-  '@smithy/hash-blob-browser@4.2.13':
+  '@smithy/hash-blob-browser@4.2.15':
     dependencies:
       '@smithy/chunked-blob-reader': 5.2.2
       '@smithy/chunked-blob-reader-native': 4.2.3
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/hash-node@4.2.12':
+  '@smithy/hash-node@4.2.14':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       '@smithy/util-buffer-from': 4.2.2
       '@smithy/util-utf8': 4.2.2
       tslib: 2.8.1
 
-  '@smithy/hash-stream-node@4.2.12':
+  '@smithy/hash-stream-node@4.2.14':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       '@smithy/util-utf8': 4.2.2
       tslib: 2.8.1
 
-  '@smithy/invalid-dependency@4.2.12':
+  '@smithy/invalid-dependency@4.2.14':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
   '@smithy/is-array-buffer@2.2.0':
@@ -18179,127 +18180,127 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
-  '@smithy/md5-js@4.2.12':
+  '@smithy/md5-js@4.2.14':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       '@smithy/util-utf8': 4.2.2
       tslib: 2.8.1
 
-  '@smithy/middleware-content-length@4.2.12':
+  '@smithy/middleware-content-length@4.2.14':
     dependencies:
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/types': 4.13.1
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/middleware-endpoint@4.4.25':
+  '@smithy/middleware-endpoint@4.4.30':
     dependencies:
-      '@smithy/core': 3.23.11
-      '@smithy/middleware-serde': 4.2.14
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/shared-ini-file-loader': 4.4.7
-      '@smithy/types': 4.13.1
-      '@smithy/url-parser': 4.2.12
-      '@smithy/util-middleware': 4.2.12
+      '@smithy/core': 3.23.15
+      '@smithy/middleware-serde': 4.2.18
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/shared-ini-file-loader': 4.4.9
+      '@smithy/types': 4.14.1
+      '@smithy/url-parser': 4.2.14
+      '@smithy/util-middleware': 4.2.14
       tslib: 2.8.1
 
-  '@smithy/middleware-retry@4.4.42':
+  '@smithy/middleware-retry@4.5.3':
     dependencies:
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/service-error-classification': 4.2.12
-      '@smithy/smithy-client': 4.12.5
-      '@smithy/types': 4.13.1
-      '@smithy/util-middleware': 4.2.12
-      '@smithy/util-retry': 4.2.12
+      '@smithy/core': 3.23.15
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/service-error-classification': 4.2.14
+      '@smithy/smithy-client': 4.12.11
+      '@smithy/types': 4.14.1
+      '@smithy/util-middleware': 4.2.14
+      '@smithy/util-retry': 4.3.2
       '@smithy/uuid': 1.1.2
       tslib: 2.8.1
 
-  '@smithy/middleware-serde@4.2.14':
+  '@smithy/middleware-serde@4.2.18':
     dependencies:
-      '@smithy/core': 3.23.11
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/types': 4.13.1
+      '@smithy/core': 3.23.15
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/middleware-stack@4.2.12':
+  '@smithy/middleware-stack@4.2.14':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/node-config-provider@4.3.12':
+  '@smithy/node-config-provider@4.3.14':
     dependencies:
-      '@smithy/property-provider': 4.2.12
-      '@smithy/shared-ini-file-loader': 4.4.7
-      '@smithy/types': 4.13.1
+      '@smithy/property-provider': 4.2.14
+      '@smithy/shared-ini-file-loader': 4.4.9
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/node-http-handler@4.4.16':
+  '@smithy/node-http-handler@4.5.3':
     dependencies:
-      '@smithy/abort-controller': 4.2.12
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/querystring-builder': 4.2.12
-      '@smithy/types': 4.13.1
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/querystring-builder': 4.2.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/property-provider@4.2.12':
+  '@smithy/property-provider@4.2.14':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/protocol-http@5.3.12':
+  '@smithy/protocol-http@5.3.14':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/querystring-builder@4.2.12':
+  '@smithy/querystring-builder@4.2.14':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       '@smithy/util-uri-escape': 4.2.2
       tslib: 2.8.1
 
-  '@smithy/querystring-parser@4.2.12':
+  '@smithy/querystring-parser@4.2.14':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/service-error-classification@4.2.12':
+  '@smithy/service-error-classification@4.2.14':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
 
-  '@smithy/shared-ini-file-loader@4.4.7':
+  '@smithy/shared-ini-file-loader@4.4.9':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/signature-v4@5.3.12':
+  '@smithy/signature-v4@5.3.14':
     dependencies:
       '@smithy/is-array-buffer': 4.2.2
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/types': 4.13.1
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/types': 4.14.1
       '@smithy/util-hex-encoding': 4.2.2
-      '@smithy/util-middleware': 4.2.12
+      '@smithy/util-middleware': 4.2.14
       '@smithy/util-uri-escape': 4.2.2
       '@smithy/util-utf8': 4.2.2
       tslib: 2.8.1
 
-  '@smithy/smithy-client@4.12.5':
+  '@smithy/smithy-client@4.12.11':
     dependencies:
-      '@smithy/core': 3.23.11
-      '@smithy/middleware-endpoint': 4.4.25
-      '@smithy/middleware-stack': 4.2.12
-      '@smithy/protocol-http': 5.3.12
-      '@smithy/types': 4.13.1
-      '@smithy/util-stream': 4.5.19
+      '@smithy/core': 3.23.15
+      '@smithy/middleware-endpoint': 4.4.30
+      '@smithy/middleware-stack': 4.2.14
+      '@smithy/protocol-http': 5.3.14
+      '@smithy/types': 4.14.1
+      '@smithy/util-stream': 4.5.23
       tslib: 2.8.1
 
-  '@smithy/types@4.13.1':
+  '@smithy/types@4.14.1':
     dependencies:
       tslib: 2.8.1
 
-  '@smithy/url-parser@4.2.12':
+  '@smithy/url-parser@4.2.14':
     dependencies:
-      '@smithy/querystring-parser': 4.2.12
-      '@smithy/types': 4.13.1
+      '@smithy/querystring-parser': 4.2.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
   '@smithy/util-base64@4.3.2':
@@ -18330,49 +18331,49 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
-  '@smithy/util-defaults-mode-browser@4.3.41':
+  '@smithy/util-defaults-mode-browser@4.3.47':
     dependencies:
-      '@smithy/property-provider': 4.2.12
-      '@smithy/smithy-client': 4.12.5
-      '@smithy/types': 4.13.1
+      '@smithy/property-provider': 4.2.14
+      '@smithy/smithy-client': 4.12.11
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/util-defaults-mode-node@4.2.44':
+  '@smithy/util-defaults-mode-node@4.2.52':
     dependencies:
-      '@smithy/config-resolver': 4.4.11
-      '@smithy/credential-provider-imds': 4.2.12
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/property-provider': 4.2.12
-      '@smithy/smithy-client': 4.12.5
-      '@smithy/types': 4.13.1
+      '@smithy/config-resolver': 4.4.16
+      '@smithy/credential-provider-imds': 4.2.14
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/property-provider': 4.2.14
+      '@smithy/smithy-client': 4.12.11
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/util-endpoints@3.3.3':
+  '@smithy/util-endpoints@3.4.1':
     dependencies:
-      '@smithy/node-config-provider': 4.3.12
-      '@smithy/types': 4.13.1
+      '@smithy/node-config-provider': 4.3.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
   '@smithy/util-hex-encoding@4.2.2':
     dependencies:
       tslib: 2.8.1
 
-  '@smithy/util-middleware@4.2.12':
+  '@smithy/util-middleware@4.2.14':
     dependencies:
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/util-retry@4.2.12':
+  '@smithy/util-retry@4.3.2':
     dependencies:
-      '@smithy/service-error-classification': 4.2.12
-      '@smithy/types': 4.13.1
+      '@smithy/service-error-classification': 4.2.14
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
-  '@smithy/util-stream@4.5.19':
+  '@smithy/util-stream@4.5.23':
     dependencies:
-      '@smithy/fetch-http-handler': 5.3.15
-      '@smithy/node-http-handler': 4.4.16
-      '@smithy/types': 4.13.1
+      '@smithy/fetch-http-handler': 5.3.17
+      '@smithy/node-http-handler': 4.5.3
+      '@smithy/types': 4.14.1
       '@smithy/util-base64': 4.3.2
       '@smithy/util-buffer-from': 4.2.2
       '@smithy/util-hex-encoding': 4.2.2
@@ -18393,10 +18394,9 @@ snapshots:
       '@smithy/util-buffer-from': 4.2.2
       tslib: 2.8.1
 
-  '@smithy/util-waiter@4.2.13':
+  '@smithy/util-waiter@4.2.16':
     dependencies:
-      '@smithy/abort-controller': 4.2.12
-      '@smithy/types': 4.13.1
+      '@smithy/types': 4.14.1
       tslib: 2.8.1
 
   '@smithy/uuid@1.1.2':
@@ -18411,7 +18411,7 @@ snapshots:
 
   '@tanstack/query-core@5.67.2': {}
 
-  '@tanstack/query-core@5.95.2': {}
+  '@tanstack/query-core@5.99.1': {}
 
   '@tanstack/query-devtools@5.67.2': {}
 
@@ -18426,9 +18426,9 @@ snapshots:
       '@tanstack/query-core': 5.67.2
       react: 19.2.4
 
-  '@tanstack/react-query@5.95.2(react@19.2.4)':
+  '@tanstack/react-query@5.99.1(react@19.2.4)':
     dependencies:
-      '@tanstack/query-core': 5.95.2
+      '@tanstack/query-core': 5.99.1
       react: 19.2.4
 
   '@testing-library/dom@10.4.1':
@@ -18456,7 +18456,7 @@ snapshots:
     dependencies:
       '@testing-library/dom': 10.4.1
 
-  '@toolpad/core@0.13.0(85298da00eeab655321bb3769f2ca5fa)':
+  '@toolpad/core@0.13.0(cbdda4f95dc3b61135f3b45ad0464d58)':
     dependencies:
       '@babel/runtime': 7.29.2
       '@mui/icons-material': 6.4.7(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
@@ -18465,7 +18465,7 @@ snapshots:
       '@mui/x-data-grid': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/x-data-grid-premium': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/x-data-grid-pro': 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
-      '@mui/x-date-pickers': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@mui/x-date-pickers': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@standard-schema/spec': 1.1.0
       '@toolpad/utils': 0.13.0(react@19.2.4)
       '@vitejs/plugin-react': 4.3.4(vite@5.4.14(@types/node@20.19.25)(lightningcss@1.32.0)(terser@5.44.0))
@@ -18482,14 +18482,14 @@ snapshots:
       - supports-color
       - vite
 
-  '@toolpad/studio-components@0.13.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(vm-browserify@1.1.2)':
+  '@toolpad/studio-components@0.13.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(vm-browserify@1.1.2)':
     dependencies:
       '@mui/icons-material': 6.4.7(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
       '@mui/lab': 6.0.0-beta.30(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/material': 6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/x-charts': 7.27.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/x-data-grid-premium': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
-      '@mui/x-date-pickers': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(dayjs@1.11.13)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@mui/x-date-pickers': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(dayjs@1.11.13)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/x-license': 7.26.0(@types/react@19.2.14)(react@19.2.4)
       '@tanstack/react-query': 5.67.2(react@19.2.4)
       '@toolpad/studio-runtime': 0.13.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(vm-browserify@1.1.2)
@@ -18545,7 +18545,7 @@ snapshots:
       - nodemailer
       - react-dom
 
-  '@toolpad/studio@0.13.0(@mui/x-data-grid-pro@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@types/react@19.2.14)(encoding@0.1.13)(eslint@10.0.3(jiti@2.6.1))(jiti@2.6.1)(lightningcss@1.32.0)(luxon@3.7.2)(terser@5.44.0)(webpack@5.102.1(esbuild@0.27.1)(jiti@2.6.1))':
+  '@toolpad/studio@0.13.0(@mui/x-data-grid-pro@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(encoding@0.1.13)(eslint@10.0.3(jiti@2.6.1))(jiti@2.6.1)(lightningcss@1.32.0)(luxon@3.7.2)(terser@5.44.0)(webpack@5.102.1(esbuild@0.27.1)(jiti@2.6.1))':
     dependencies:
       '@auth/core': 0.38.0
       '@emotion/cache': 11.14.0
@@ -18563,14 +18563,14 @@ snapshots:
       '@mui/x-charts': 7.27.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/x-data-grid': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/x-data-grid-premium': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
-      '@mui/x-date-pickers': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
-      '@mui/x-date-pickers-pro': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(dayjs@1.11.13)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@mui/x-date-pickers': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@7.3.8(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(dayjs@1.11.20)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@mui/x-date-pickers-pro': 7.27.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(dayjs@1.11.13)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@mui/x-license': 7.26.0(@types/react@19.2.14)(react@19.2.4)
       '@mui/x-tree-view': 7.26.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@tanstack/react-query': 5.67.2(react@19.2.4)
       '@tanstack/react-query-devtools': 5.67.2(@tanstack/react-query@5.67.2(react@19.2.4))(react@19.2.4)
-      '@toolpad/core': 0.13.0(85298da00eeab655321bb3769f2ca5fa)
-      '@toolpad/studio-components': 0.13.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(vm-browserify@1.1.2)
+      '@toolpad/core': 0.13.0(cbdda4f95dc3b61135f3b45ad0464d58)
+      '@toolpad/studio-components': 0.13.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/system@6.4.7(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(luxon@3.7.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(vm-browserify@1.1.2)
       '@toolpad/studio-runtime': 0.13.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(vm-browserify@1.1.2)
       '@toolpad/utils': 0.13.0(react@19.2.4)
       '@types/cors': 2.8.17
@@ -19252,36 +19252,36 @@ snapshots:
       '@typescript-eslint/types': 8.57.1
       eslint-visitor-keys: 5.0.1
 
-  '@typescript/native-preview-darwin-arm64@7.0.0-dev.20260317.1':
+  '@typescript/native-preview-darwin-arm64@7.0.0-dev.20260419.1':
     optional: true
 
-  '@typescript/native-preview-darwin-x64@7.0.0-dev.20260317.1':
+  '@typescript/native-preview-darwin-x64@7.0.0-dev.20260419.1':
     optional: true
 
-  '@typescript/native-preview-linux-arm64@7.0.0-dev.20260317.1':
+  '@typescript/native-preview-linux-arm64@7.0.0-dev.20260419.1':
     optional: true
 
-  '@typescript/native-preview-linux-arm@7.0.0-dev.20260317.1':
+  '@typescript/native-preview-linux-arm@7.0.0-dev.20260419.1':
     optional: true
 
-  '@typescript/native-preview-linux-x64@7.0.0-dev.20260317.1':
+  '@typescript/native-preview-linux-x64@7.0.0-dev.20260419.1':
     optional: true
 
-  '@typescript/native-preview-win32-arm64@7.0.0-dev.20260317.1':
+  '@typescript/native-preview-win32-arm64@7.0.0-dev.20260419.1':
     optional: true
 
-  '@typescript/native-preview-win32-x64@7.0.0-dev.20260317.1':
+  '@typescript/native-preview-win32-x64@7.0.0-dev.20260419.1':
     optional: true
 
-  '@typescript/native-preview@7.0.0-dev.20260317.1':
+  '@typescript/native-preview@7.0.0-dev.20260419.1':
     optionalDependencies:
-      '@typescript/native-preview-darwin-arm64': 7.0.0-dev.20260317.1
-      '@typescript/native-preview-darwin-x64': 7.0.0-dev.20260317.1
-      '@typescript/native-preview-linux-arm': 7.0.0-dev.20260317.1
-      '@typescript/native-preview-linux-arm64': 7.0.0-dev.20260317.1
-      '@typescript/native-preview-linux-x64': 7.0.0-dev.20260317.1
-      '@typescript/native-preview-win32-arm64': 7.0.0-dev.20260317.1
-      '@typescript/native-preview-win32-x64': 7.0.0-dev.20260317.1
+      '@typescript/native-preview-darwin-arm64': 7.0.0-dev.20260419.1
+      '@typescript/native-preview-darwin-x64': 7.0.0-dev.20260419.1
+      '@typescript/native-preview-linux-arm': 7.0.0-dev.20260419.1
+      '@typescript/native-preview-linux-arm64': 7.0.0-dev.20260419.1
+      '@typescript/native-preview-linux-x64': 7.0.0-dev.20260419.1
+      '@typescript/native-preview-win32-arm64': 7.0.0-dev.20260419.1
+      '@typescript/native-preview-win32-x64': 7.0.0-dev.20260419.1
 
   '@ungap/structured-clone@1.3.0': {}
 
@@ -19362,11 +19362,11 @@ snapshots:
     optionalDependencies:
       babel-plugin-react-compiler: 1.0.0
 
-  '@vitest/browser-playwright@4.1.1(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)':
+  '@vitest/browser-playwright@4.1.1(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)':
     dependencies:
       '@vitest/browser': 4.1.1(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       '@vitest/mocker': 4.1.1(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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
+      playwright: 1.58.2
       tinyrainbow: 3.1.0
       vitest: 4.1.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.1)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
@@ -19375,11 +19375,11 @@ snapshots:
       - utf-8-validate
       - vite
 
-  '@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)':
+  '@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)':
     dependencies:
       '@vitest/browser': 4.1.3(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       '@vitest/mocker': 4.1.3(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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
+      playwright: 1.58.2
       tinyrainbow: 3.1.0
       vitest: 4.1.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
@@ -19398,7 +19398,7 @@ snapshots:
       sirv: 3.0.2
       tinyrainbow: 3.1.0
       vitest: 4.1.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.1)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.20.0
+      ws: 8.19.0
     transitivePeerDependencies:
       - bufferutil
       - msw
@@ -19415,7 +19415,7 @@ snapshots:
       sirv: 3.0.2
       tinyrainbow: 3.1.0
       vitest: 4.1.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.20.0
+      ws: 8.19.0
     transitivePeerDependencies:
       - bufferutil
       - msw
@@ -19436,14 +19436,14 @@ snapshots:
       tinyrainbow: 3.1.0
       vitest: 4.1.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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/eslint-plugin@1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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/eslint-plugin@1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
       '@typescript-eslint/scope-manager': 8.57.1
       '@typescript-eslint/utils': 8.57.1(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)
       eslint: 10.0.3(jiti@2.6.1)
     optionalDependencies:
       typescript: 5.9.3
-      vitest: 4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
       - supports-color
 
@@ -19988,7 +19988,7 @@ snapshots:
     dependencies:
       '@babel/runtime': 7.29.2
       cosmiconfig: 7.1.0
-      resolve: 1.22.11
+      resolve: 1.22.12
 
   babel-plugin-optimize-clsx@2.6.2:
     dependencies:
@@ -20800,6 +20800,9 @@ snapshots:
       es-errors: 1.3.0
       is-data-view: 1.0.2
 
+  date-fns@4.1.0:
+    optional: true
+
   dateformat@3.0.3: {}
 
   dayjs@1.11.13: {}
@@ -21287,7 +21290,7 @@ snapshots:
     dependencies:
       debug: 3.2.7
       is-core-module: 2.16.1
-      resolve: 1.22.11
+      resolve: 1.22.12
     transitivePeerDependencies:
       - supports-color
 
@@ -21808,12 +21811,13 @@ snapshots:
 
   fast-xml-builder@1.1.4:
     dependencies:
-      path-expression-matcher: 1.1.3
+      path-expression-matcher: 1.5.0
 
-  fast-xml-parser@5.4.1:
+  fast-xml-parser@5.5.8:
     dependencies:
       fast-xml-builder: 1.1.4
-      strnum: 2.1.2
+      path-expression-matcher: 1.5.0
+      strnum: 2.2.3
 
   fastest-levenshtein@1.0.16: {}
 
@@ -21903,20 +21907,20 @@ snapshots:
 
   flat-cache@4.0.1:
     dependencies:
-      flatted: 3.4.0
+      flatted: 3.3.3
       keyv: 4.5.4
 
   flat-cache@6.1.20:
     dependencies:
       cacheable: 2.3.2
-      flatted: 3.4.0
+      flatted: 3.3.3
       hookified: 1.15.1
 
   flat@5.0.2: {}
 
   flatqueue@3.0.0: {}
 
-  flatted@3.4.0: {}
+  flatted@3.3.3: {}
 
   follow-redirects@1.15.11(debug@4.4.3):
     optionalDependencies:
@@ -22203,7 +22207,7 @@ snapshots:
 
   globals@15.15.0: {}
 
-  globals@17.4.0: {}
+  globals@17.5.0: {}
 
   globalthis@1.0.4:
     dependencies:
@@ -22485,10 +22489,10 @@ snapshots:
       readable-stream: 1.0.34
       through2: 0.4.2
 
-  html-validate@10.11.2(jest-diff@30.2.0)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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))):
+  html-validate@10.13.1(jest-diff@30.2.0)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
-      '@html-validate/stylish': 5.0.0
-      '@sidvind/better-ajv-errors': 4.0.1(ajv@8.18.0)
+      '@html-validate/stylish': 5.2.0
+      '@sidvind/better-ajv-errors': 5.0.0(ajv@8.18.0)
       ajv: 8.18.0
       glob: 13.0.6
       kleur: 4.1.5
@@ -22497,7 +22501,7 @@ snapshots:
       semver: 7.7.4
     optionalDependencies:
       jest-diff: 30.2.0
-      vitest: 4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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))
 
   html-void-elements@3.0.0: {}
 
@@ -24171,7 +24175,7 @@ snapshots:
 
   neo-async@2.6.2: {}
 
-  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.4(react@19.2.4))(react@19.2.4):
+  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.4(react@19.2.4))(react@19.2.4):
     dependencies:
       '@next/env': 16.2.3
       '@swc/helpers': 0.5.15
@@ -24191,7 +24195,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.59.1
+      '@playwright/test': 1.58.2
       babel-plugin-react-compiler: 1.0.0
       sharp: 0.34.5
     transitivePeerDependencies:
@@ -24248,7 +24252,7 @@ snapshots:
   normalize-package-data@2.5.0:
     dependencies:
       hosted-git-info: 2.8.9
-      resolve: 1.22.11
+      resolve: 1.22.12
       semver: 5.7.2
       validate-npm-package-license: 3.0.4
 
@@ -24727,7 +24731,7 @@ snapshots:
 
   path-exists@5.0.0: {}
 
-  path-expression-matcher@1.1.3: {}
+  path-expression-matcher@1.5.0: {}
 
   path-is-absolute@1.0.1: {}
 
@@ -24853,20 +24857,12 @@ snapshots:
 
   playwright-core@1.58.2: {}
 
-  playwright-core@1.59.1: {}
-
   playwright@1.58.2:
     dependencies:
       playwright-core: 1.58.2
     optionalDependencies:
       fsevents: 2.3.2
 
-  playwright@1.59.1:
-    dependencies:
-      playwright-core: 1.59.1
-    optionalDependencies:
-      fsevents: 2.3.2
-
   pluralize@3.1.0: {}
 
   pngjs@7.0.0: {}
@@ -25549,8 +25545,9 @@ snapshots:
 
   resolve.exports@2.0.3: {}
 
-  resolve@1.22.11:
+  resolve@1.22.12:
     dependencies:
+      es-errors: 1.3.0
       is-core-module: 2.16.1
       path-parse: 1.0.7
       supports-preserve-symlinks-flag: 1.0.0
@@ -26181,7 +26178,7 @@ snapshots:
 
   strip-json-comments@3.1.1: {}
 
-  strnum@2.1.2: {}
+  strnum@2.2.3: {}
 
   stubborn-fs@2.0.0:
     dependencies:
@@ -26937,7 +26934,7 @@ snapshots:
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
       '@types/node': 22.19.0
-      '@vitest/browser-playwright': 4.1.1(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+      '@vitest/browser-playwright': 4.1.1(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       jsdom: 28.1.0
     transitivePeerDependencies:
       - msw
@@ -26967,12 +26964,12 @@ snapshots:
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
       '@types/node': 22.19.0
-      '@vitest/browser-playwright': 4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+      '@vitest/browser-playwright': 4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       jsdom: 28.1.0
     transitivePeerDependencies:
       - msw
 
-  vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.4
       '@vitest/mocker': 4.1.4(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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))
@@ -26997,7 +26994,7 @@ snapshots:
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
       '@types/node': 22.19.0
-      '@vitest/browser-playwright': 4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+      '@vitest/browser-playwright': 4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       '@vitest/coverage-v8': 4.1.2(vitest@4.1.1)
       jsdom: 28.1.0
     transitivePeerDependencies:
@@ -27231,7 +27228,7 @@ snapshots:
 
   ws@8.18.1: {}
 
-  ws@8.20.0: {}
+  ws@8.19.0: {}
 
   wsl-utils@0.1.0:
     dependencies:

From c7c62dfa9af7254b113d5f2242fb1f17f242d098 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 10:38:40 -0400
Subject: [PATCH 18/45] Fix initial undo stack state

---
 .../src/useCode/useEditable.test.ts           | 76 +++++++++++++++++++
 .../docs-infra/src/useCode/useEditable.ts     |  7 +-
 2 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.test.ts b/packages/docs-infra/src/useCode/useEditable.test.ts
index 628fdd626..b61b25cf7 100644
--- a/packages/docs-infra/src/useCode/useEditable.test.ts
+++ b/packages/docs-infra/src/useCode/useEditable.test.ts
@@ -922,6 +922,82 @@ describe('useEditable', () => {
       // 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');
+    });
   });
 
   // ---------------------------------------------------------------------------
diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 8816cffea..1b5ed5a18 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -35,6 +35,7 @@ SOFTWARE.
 // - Deduplicate toString() calls via trackState return value
 // - Fix Firefox rapid-typing line-loss bug: preserve pre-edit pendingContent across key-repeat keydowns
 // - Debounce repeat-key flushes so highlights only re-render once the user pauses typing
+// - Fix undo-to-initial-state bug: allow trackState to record before the first flushChanges
 
 import * as React from 'react';
 
@@ -509,7 +510,11 @@ export const useEditable = (
 
     let trackStateTimestamp: number;
     const trackState = (ignoreTimestamp?: boolean): string | null => {
-      if (!elementRef.current || !state.position) {
+      // 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) {
         return null;
       }
 

From f5c35ca8cbcc4152636389e6cf0f24c56554c363 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 10:51:22 -0400
Subject: [PATCH 19/45] Fix undo stack when pressing enter

---
 .../src/useCode/useEditable.test.ts           | 77 +++++++++++++++++++
 .../docs-infra/src/useCode/useEditable.ts     |  6 +-
 2 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.test.ts b/packages/docs-infra/src/useCode/useEditable.test.ts
index b61b25cf7..85aa70318 100644
--- a/packages/docs-infra/src/useCode/useEditable.test.ts
+++ b/packages/docs-infra/src/useCode/useEditable.test.ts
@@ -998,6 +998,83 @@ describe('useEditable', () => {
       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');
+    });
   });
 
   // ---------------------------------------------------------------------------
diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 1b5ed5a18..fbedfcb85 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -36,6 +36,7 @@ SOFTWARE.
 // - Fix Firefox rapid-typing line-loss bug: preserve pre-edit pendingContent across key-repeat keydowns
 // - Debounce repeat-key flushes so highlights only re-render once the user pauses typing
 // - Fix undo-to-initial-state bug: allow trackState to record before the first flushChanges
+// - Fix undo-after-rapid-Enter bug: bypass 500ms dedup on keyup for structural edits (Enter)
 
 import * as React from 'react';
 
@@ -700,7 +701,10 @@ export const useEditable = (
         state.repeatFlushId = null;
       }
       if (!isUndoRedoKey(event)) {
-        trackState();
+        // 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.
+        trackState(event.key === 'Enter');
       }
       flushChanges();
       // Chrome Quirk: The contenteditable may lose focus after the first edit or so

From 7ca44b013e42689a617724a04323c5356582d790 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 11:07:02 -0400
Subject: [PATCH 20/45] Improve for React 19

---
 .../docs-infra/src/useCode/useEditable.ts     | 170 +++++++++---------
 1 file changed, 86 insertions(+), 84 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index fbedfcb85..defe592f2 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -37,6 +37,7 @@ SOFTWARE.
 // - Debounce repeat-key flushes so highlights only re-render once the user pauses typing
 // - Fix undo-to-initial-state bug: allow trackState to record before the first flushChanges
 // - Fix undo-after-rapid-Enter bug: bypass 500ms dedup on keyup for structural edits (Enter)
+// - Fix React 19 compatibility: useState lazy init for edit, useRef for MutationObserver, window SSR guard
 
 import * as React from 'react';
 
@@ -347,95 +348,96 @@ export const useEditable = (
   }
 
   const unblock = React.useState([])[1];
-  const state: State = React.useState(() => {
-    const initialState: State = {
-      observer: null as any,
-      disconnected: false,
-      onChange,
-      pendingContent: null,
-      queue: [],
-      history: [],
-      historyAt: -1,
-      position: null,
-      repeatFlushId: null,
-    };
-
-    if (typeof MutationObserver !== 'undefined') {
-      initialState.observer = new MutationObserver((batch) => {
-        initialState.queue.push(...batch);
-      });
-    }
-
-    return initialState;
-  })[0];
-
-  const edit = React.useMemo<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);
+  const state: State = React.useState(() => ({
+    observer: null as any,
+    disconnected: false,
+    onChange,
+    pendingContent: null,
+    queue: [] as MutationRecord[],
+    history: [] as History[],
+    historyAt: -1,
+    position: null,
+    repeatFlushId: 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);
+    });
+  }
+  state.observer = observerRef.current as MutationObserver;
+
+  // 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));
         }
-      },
-      move(pos: number | { row: number; column: number }) {
-        const { current: element } = elementRef;
-        if (element) {
-          element.focus();
-          let position = 0;
-          if (typeof pos === 'number') {
-            position = pos;
-          } else {
-            const lines = toString(element).split('\n').slice(0, pos.row);
-            if (pos.row) {
-              position += lines.join('\n').length + 1;
-            }
-            position += pos.column;
+        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();
+        let position = 0;
+        if (typeof pos === 'number') {
+          position = pos;
+        } else {
+          const lines = toString(element).split('\n').slice(0, pos.row);
+          if (pos.row) {
+            position += lines.join('\n').length + 1;
           }
-
-          const cursorRange = makeRange(element, position);
-          adjustCursorAtNewlineBoundary(cursorRange);
-          setCurrentRange(cursorRange);
+          position += pos.column;
         }
-      },
-      getState() {
-        const { current: element } = elementRef;
-        const text = toString(element!);
-        const position = getPosition(element!);
-        return { text, position };
-      },
-    }),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [],
-  );
+        const cursorRange = makeRange(element, position);
+        adjustCursorAtNewlineBoundary(cursorRange);
+        setCurrentRange(cursorRange);
+      }
+    },
+    getState() {
+      const { current: element } = elementRef;
+      const text = toString(element!);
+      const position = getPosition(element!);
+      return { text, position };
+    },
+  }));
 
   React.useLayoutEffect(() => {
     // Only for SSR / server-side logic
-    if (typeof navigator !== 'object') {
+    // 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;
     }
 
@@ -465,7 +467,7 @@ export const useEditable = (
   });
 
   React.useLayoutEffect(() => {
-    if (typeof navigator !== 'object') {
+    if (typeof window === 'undefined') {
       return undefined;
     }
 

From 703ddd6aeca25a04949185b83d1a396667838739 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 11:12:19 -0400
Subject: [PATCH 21/45] Improve typescript types

---
 .../docs-infra/src/useCode/useEditable.ts     | 20 +++++++++----------
 1 file changed, 9 insertions(+), 11 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index defe592f2..e4290384c 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -310,7 +310,6 @@ const adjustCursorAtNewlineBoundary = (range: Range): void => {
 };
 
 interface State {
-  observer: MutationObserver;
   disconnected: boolean;
   onChange(text: string, position: Position): void;
   pendingContent: string | null;
@@ -348,13 +347,12 @@ export const useEditable = (
   }
 
   const unblock = React.useState([])[1];
-  const state: State = React.useState(() => ({
-    observer: null as any,
+  const state = React.useState<State>(() => ({
     disconnected: false,
     onChange,
     pendingContent: null,
-    queue: [] as MutationRecord[],
-    history: [] as History[],
+    queue: [],
+    history: [],
     historyAt: -1,
     position: null,
     repeatFlushId: null,
@@ -369,7 +367,6 @@ export const useEditable = (
       state.queue.push(...batch);
     });
   }
-  state.observer = observerRef.current as MutationObserver;
 
   // useMemo with [] is a performance hint, not a semantic guarantee — React 19
   // may discard the cache and recreate the object. useState with a lazy
@@ -448,7 +445,7 @@ export const useEditable = (
     }
 
     state.disconnected = false;
-    state.observer.observe(elementRef.current, observerSettings);
+    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.
@@ -462,7 +459,7 @@ export const useEditable = (
     }
 
     return () => {
-      state.observer.disconnect();
+      observerRef.current?.disconnect();
     };
   });
 
@@ -503,7 +500,7 @@ export const useEditable = (
 
     if (opts!.indentation) {
       const tabSizeValue = `${opts!.indentation}`;
-      (element.style as any).MozTabSize = tabSizeValue;
+      element.style.setProperty('-moz-tab-size', tabSizeValue);
       element.style.tabSize = tabSizeValue;
     }
 
@@ -547,12 +544,13 @@ export const useEditable = (
     };
 
     const disconnect = () => {
-      state.observer.disconnect();
+      observerRef.current?.disconnect();
       state.disconnected = true;
     };
 
     const flushChanges = () => {
-      state.queue.push(...state.observer.takeRecords());
+      const records = observerRef.current?.takeRecords() ?? [];
+      state.queue.push(...records);
       const position = getPosition(element);
       if (state.queue.length) {
         disconnect();

From c7363e9f5d3872d9f292c8c2c1827097e9d478e4 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 15:38:27 -0400
Subject: [PATCH 22/45] Upgrade playwright

---
 .circleci/config.yml             |  2 +-
 package.json                     |  4 +-
 packages/test-utils/package.json |  2 +-
 pnpm-lock.yaml                   | 80 ++++++++++++++++----------------
 4 files changed, 44 insertions(+), 44 deletions(-)

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/package.json b/package.json
index db69dafc9..9bd6d0dc7 100644
--- a/package.json
+++ b/package.json
@@ -10,7 +10,7 @@
     "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.58.2 --",
+    "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",
@@ -90,7 +90,7 @@
     "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/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 dd214005a..e81b33013 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -88,7 +88,7 @@ importers:
         version: 7.27.1(@babel/core@7.29.0)
       '@vitest/browser-playwright':
         specifier: 4.1.3
-        version: 4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+        version: 4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       baseline-browser-mapping:
         specifier: 2.10.10
         version: 2.10.10
@@ -102,8 +102,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 +133,7 @@ importers:
         version: 9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@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.4))(@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.4(react@19.2.4))(react@19.2.4))(react@19.2.4)
+        version: 9.0.0-alpha.2(@emotion/cache@11.14.0)(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@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.4(react@19.2.4))(react@19.2.4))(react@19.2.4)
       '@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.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@mui/material@9.0.0-alpha.2(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@mui/system@9.0.0-alpha.3(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@emotion/styled@11.14.1(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -175,7 +175,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.4(react@19.2.4))(react@19.2.4)
+        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.4(react@19.2.4))(react@19.2.4)
       pako:
         specifier: ^2.1.0
         version: 2.1.0
@@ -294,7 +294,7 @@ importers:
         version: 0.577.0(react@19.2.4)
       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.4(react@19.2.4))(react@19.2.4)
+        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.4(react@19.2.4))(react@19.2.4)
       react:
         specifier: ^19.2.4
         version: 19.2.4
@@ -436,7 +436,7 @@ importers:
         version: 6.0.1(babel-plugin-react-compiler@1.0.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+        version: 4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       env-ci:
         specifier: ^11.2.0
         version: 11.2.0
@@ -598,7 +598,7 @@ importers:
         version: 7.0.0-dev.20260419.1
       '@vitest/eslint-plugin':
         specifier: ^1.6.11
-        version: 1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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: 1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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)))
       babel-plugin-optimize-clsx:
         specifier: ^2.6.2
         version: 2.6.2
@@ -679,7 +679,7 @@ importers:
         version: 16.1.1
       html-validate:
         specifier: ^10.11.2
-        version: 10.13.1(jest-diff@30.2.0)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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: 10.13.1(jest-diff@30.2.0)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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)))
       minimatch:
         specifier: ^10.2.4
         version: 10.2.5
@@ -927,7 +927,7 @@ 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.4(react@19.2.4))(react@19.2.4)
+        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.4(react@19.2.4))(react@19.2.4)
       react:
         specifier: 19.2.4
         version: 19.2.4
@@ -1003,8 +1003,8 @@ importers:
         version: 0.10.1(@vitest/utils@4.1.4)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
     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
@@ -1064,7 +1064,7 @@ importers:
         version: 19.2.14
       '@vitest/browser-playwright':
         specifier: 4.1.1
-        version: 4.1.1(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+        version: 4.1.1(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       vitest:
         specifier: 4.1.1
         version: 4.1.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.1)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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))
@@ -4569,8 +4569,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
 
@@ -10889,13 +10889,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
 
@@ -15412,11 +15412,11 @@ snapshots:
       '@emotion/styled': 11.14.0(@emotion/react@11.14.0(@types/react@19.2.14)(react@19.2.4))(@types/react@19.2.14)(react@19.2.4)
       '@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.4))(@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.4(react@19.2.4))(react@19.2.4))(react@19.2.4)':
+  '@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.4))(@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.4(react@19.2.4))(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@babel/runtime': 7.29.2
       '@emotion/react': 11.14.0(@types/react@19.2.14)(react@19.2.4)
-      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.4(react@19.2.4))(react@19.2.4)
+      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.4(react@19.2.4))(react@19.2.4)
       react: 19.2.4
     optionalDependencies:
       '@emotion/cache': 11.14.0
@@ -17095,9 +17095,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': {}
 
@@ -19362,11 +19362,11 @@ snapshots:
     optionalDependencies:
       babel-plugin-react-compiler: 1.0.0
 
-  '@vitest/browser-playwright@4.1.1(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)':
+  '@vitest/browser-playwright@4.1.1(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)':
     dependencies:
       '@vitest/browser': 4.1.1(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       '@vitest/mocker': 4.1.1(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.1)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
@@ -19375,11 +19375,11 @@ snapshots:
       - utf-8-validate
       - vite
 
-  '@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)':
+  '@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)':
     dependencies:
       '@vitest/browser': 4.1.3(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       '@vitest/mocker': 4.1.3(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
@@ -19436,14 +19436,14 @@ snapshots:
       tinyrainbow: 3.1.0
       vitest: 4.1.1(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3)(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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/eslint-plugin@1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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/eslint-plugin@1.6.12(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
       '@typescript-eslint/scope-manager': 8.57.1
       '@typescript-eslint/utils': 8.57.1(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)
       eslint: 10.0.3(jiti@2.6.1)
     optionalDependencies:
       typescript: 5.9.3
-      vitest: 4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
       - supports-color
 
@@ -22489,7 +22489,7 @@ snapshots:
       readable-stream: 1.0.34
       through2: 0.4.2
 
-  html-validate@10.13.1(jest-diff@30.2.0)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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))):
+  html-validate@10.13.1(jest-diff@30.2.0)(vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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:
       '@html-validate/stylish': 5.2.0
       '@sidvind/better-ajv-errors': 5.0.0(ajv@8.18.0)
@@ -22501,7 +22501,7 @@ snapshots:
       semver: 7.7.4
     optionalDependencies:
       jest-diff: 30.2.0
-      vitest: 4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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))
 
   html-void-elements@3.0.0: {}
 
@@ -24175,7 +24175,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.4(react@19.2.4))(react@19.2.4):
+  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.4(react@19.2.4))(react@19.2.4):
     dependencies:
       '@next/env': 16.2.3
       '@swc/helpers': 0.5.15
@@ -24195,7 +24195,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:
@@ -24855,11 +24855,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
 
@@ -26934,7 +26934,7 @@ snapshots:
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
       '@types/node': 22.19.0
-      '@vitest/browser-playwright': 4.1.1(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+      '@vitest/browser-playwright': 4.1.1(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       jsdom: 28.1.0
     transitivePeerDependencies:
       - msw
@@ -26964,12 +26964,12 @@ snapshots:
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
       '@types/node': 22.19.0
-      '@vitest/browser-playwright': 4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+      '@vitest/browser-playwright': 4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       jsdom: 28.1.0
     transitivePeerDependencies:
       - msw
 
-  vitest@4.1.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.4(@opentelemetry/api@1.9.0)(@types/node@22.19.0)(@vitest/browser-playwright@4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1))(@vitest/coverage-v8@4.1.2(vitest@4.1.1))(jsdom@28.1.0)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.4
       '@vitest/mocker': 4.1.4(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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))
@@ -26994,7 +26994,7 @@ snapshots:
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
       '@types/node': 22.19.0
-      '@vitest/browser-playwright': 4.1.3(playwright@1.58.2)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
+      '@vitest/browser-playwright': 4.1.3(playwright@1.59.1)(vite@8.0.5(@emnapi/core@1.9.0)(@emnapi/runtime@1.9.2)(@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.1)
       '@vitest/coverage-v8': 4.1.2(vitest@4.1.1)
       jsdom: 28.1.0
     transitivePeerDependencies:

From 951127717652e4765e99427ff0b13e17a3459000 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 16:07:27 -0400
Subject: [PATCH 23/45] Optimize useSourceEditing

---
 .../docs-infra/src/CodeHighlighter/types.ts   |  2 +
 .../src/useCode/useSourceEditing.test.ts      | 26 ++++++---
 .../src/useCode/useSourceEditing.ts           | 53 ++++++++++++++-----
 3 files changed, 61 insertions(+), 20 deletions(-)

diff --git a/packages/docs-infra/src/CodeHighlighter/types.ts b/packages/docs-infra/src/CodeHighlighter/types.ts
index a7e40e392..1c160c9ed 100644
--- a/packages/docs-infra/src/CodeHighlighter/types.ts
+++ b/packages/docs-infra/src/CodeHighlighter/types.ts
@@ -97,6 +97,7 @@ export type ControlledVariantExtraFiles = {
     source: string | null;
     comments?: SourceComments;
     collapseMap?: CollapseMap;
+    totalLines?: number;
   };
 };
 export type ControlledVariantCode = CodeMeta & {
@@ -106,6 +107,7 @@ export type ControlledVariantCode = CodeMeta & {
   filesOrder?: string[];
   comments?: SourceComments;
   collapseMap?: CollapseMap;
+  totalLines?: number;
 };
 export type ControlledCode = { [key: string]: undefined | null | ControlledVariantCode };
 
diff --git a/packages/docs-infra/src/useCode/useSourceEditing.test.ts b/packages/docs-infra/src/useCode/useSourceEditing.test.ts
index cbd92d412..e1288c6b5 100644
--- a/packages/docs-infra/src/useCode/useSourceEditing.test.ts
+++ b/packages/docs-infra/src/useCode/useSourceEditing.test.ts
@@ -147,8 +147,14 @@ describe('useSourceEditing', () => {
       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; }' });
-      expect(variant.extraFiles!['helpers.ts']).toEqual({ source: 'export const h = 1;' });
+      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,
+      });
     });
   });
 
@@ -179,7 +185,7 @@ describe('useSourceEditing', () => {
       const variant = controlled!.Default!;
 
       expect(variant.source).toBe('main code');
-      expect(variant.extraFiles!['styles.css']).toEqual({ source: 'new styles' });
+      expect(variant.extraFiles!['styles.css']).toEqual({ source: 'new styles', totalLines: 1 });
     });
 
     it('preserves other extra files when editing one', () => {
@@ -208,8 +214,11 @@ describe('useSourceEditing', () => {
       const controlled = captureControlledCode(context);
       const variant = controlled!.Default!;
 
-      expect(variant.extraFiles!['styles.css']).toEqual({ source: 'new css' });
-      expect(variant.extraFiles!['helpers.ts']).toEqual({ source: 'helper content' });
+      expect(variant.extraFiles!['styles.css']).toEqual({ source: 'new css', totalLines: 1 });
+      expect(variant.extraFiles!['helpers.ts']).toEqual({
+        source: 'helper content',
+        totalLines: 1,
+      });
     });
   });
 
@@ -246,7 +255,7 @@ describe('useSourceEditing', () => {
       // 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' });
+      expect(variant.extraFiles!['styles.css']).toEqual({ source: 'edited', totalLines: 1 });
     });
   });
 
@@ -280,7 +289,10 @@ describe('useSourceEditing', () => {
       const afterSecond = captureControlledCode(context, afterFirst);
 
       expect(afterSecond!.Default!.source).toBe('first edit');
-      expect(afterSecond!.Default!.extraFiles!['styles.css']).toEqual({ source: 'new css' });
+      expect(afterSecond!.Default!.extraFiles!['styles.css']).toEqual({
+        source: 'new css',
+        totalLines: 1,
+      });
     });
   });
 
diff --git a/packages/docs-infra/src/useCode/useSourceEditing.ts b/packages/docs-infra/src/useCode/useSourceEditing.ts
index 7a7915876..9b705334c 100644
--- a/packages/docs-infra/src/useCode/useSourceEditing.ts
+++ b/packages/docs-infra/src/useCode/useSourceEditing.ts
@@ -30,10 +30,25 @@ interface ShiftResult {
   collapseMap: CollapseMap | undefined;
 }
 
+/**
+ * Counts the number of lines in a string without allocating an intermediate array.
+ */
+function countSourceLines(source: string): number {
+  let count = 1;
+  let idx = 0;
+  // eslint-disable-next-line no-cond-assign
+  while ((idx = source.indexOf('\n', idx)) !== -1) {
+    count += 1;
+    idx += 1;
+  }
+  return count;
+}
+
 /**
  * Shifts 1-indexed comment line numbers after a source edit.
- * Uses the cursor position (0-indexed in new text) and line count delta
- * to determine which comments move and by how much.
+ * 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
@@ -41,8 +56,7 @@ interface ShiftResult {
  */
 function shiftComments(
   comments: SourceComments | undefined,
-  oldSource: string | null | undefined,
-  newSource: string,
+  lineDelta: number,
   position: Position,
   existingCollapseMap: CollapseMap | undefined,
 ): ShiftResult {
@@ -50,15 +64,12 @@ function shiftComments(
     return { comments, collapseMap: existingCollapseMap };
   }
 
-  const oldLineCount = oldSource != null ? oldSource.split('\n').length : 0;
-  const newLineCount = newSource.split('\n').length;
-  const lineDelta = newLineCount - oldLineCount;
-
   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): cursor moved down, old line = position.line - lineDelta
   // For deletions (lineDelta < 0): cursor stayed, old line = position.line
@@ -186,11 +197,13 @@ function toControlledCode(code: Code): ControlledCode {
       extraFiles = {};
       for (const [fileName, entry] of Object.entries(variant.extraFiles)) {
         if (typeof entry === 'string') {
-          extraFiles[fileName] = { source: entry };
+          extraFiles[fileName] = { source: entry, totalLines: countSourceLines(entry) };
         } else {
+          const extraSource = entry.source != null ? stringOrHastToString(entry.source) : null;
           extraFiles[fileName] = {
-            source: entry.source != null ? stringOrHastToString(entry.source) : null,
+            source: extraSource,
             ...(entry.comments ? { comments: entry.comments } : {}),
+            totalLines: extraSource != null ? countSourceLines(extraSource) : undefined,
           };
         }
       }
@@ -199,6 +212,7 @@ function toControlledCode(code: Code): ControlledCode {
     result[key] = {
       ...variant,
       source,
+      totalLines: source != null ? countSourceLines(source) : undefined,
       ...(extraFiles ? { extraFiles } : {}),
     } as ControlledCode[string];
   }
@@ -247,12 +261,21 @@ export function useSourceEditing({
           if (source === variant.source) {
             return currentCode ?? newCode;
           }
+          const newLineCount = countSourceLines(source);
+          const oldLineCount =
+            variant.totalLines ?? (variant.source != null ? countSourceLines(variant.source) : 0);
           const { comments: shiftedComments, collapseMap: newCollapseMap } = position
-            ? shiftComments(variant.comments, variant.source, source, position, variant.collapseMap)
+            ? shiftComments(
+                variant.comments,
+                newLineCount - oldLineCount,
+                position,
+                variant.collapseMap,
+              )
             : { comments: undefined, collapseMap: undefined };
           newCode[selectedVariantKey] = {
             ...variant,
             source,
+            totalLines: newLineCount,
             comments: shiftedComments,
             collapseMap: newCollapseMap,
           };
@@ -261,11 +284,14 @@ export function useSourceEditing({
           if (source === extraEntry?.source) {
             return currentCode ?? newCode;
           }
+          const newLineCount = countSourceLines(source);
+          const oldLineCount =
+            extraEntry?.totalLines ??
+            (extraEntry?.source != null ? countSourceLines(extraEntry.source) : 0);
           const { comments: shiftedComments, collapseMap: newCollapseMap } = position
             ? shiftComments(
                 extraEntry?.comments,
-                extraEntry?.source,
-                source,
+                newLineCount - oldLineCount,
                 position,
                 extraEntry?.collapseMap,
               )
@@ -277,6 +303,7 @@ export function useSourceEditing({
               [effectiveFileName]: {
                 ...extraEntry,
                 source,
+                totalLines: newLineCount,
                 comments: shiftedComments,
                 collapseMap: newCollapseMap,
               },

From dd08e27294a035c36944a6ef0b982c910473b3f6 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 16:14:59 -0400
Subject: [PATCH 24/45] Update types.md

---
 docs/app/docs-infra/components/code-highlighter/types.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/app/docs-infra/components/code-highlighter/types.md b/docs/app/docs-infra/components/code-highlighter/types.md
index 15e1ab10b..f98608e0e 100644
--- a/docs/app/docs-infra/components/code-highlighter/types.md
+++ b/docs/app/docs-infra/components/code-highlighter/types.md
@@ -594,6 +594,7 @@ type ControlledVariantCode = {
   filesOrder?: string[];
   comments?: SourceComments;
   collapseMap?: CollapseMap;
+  totalLines?: number;
 };
 ```
 
@@ -605,6 +606,7 @@ type ControlledVariantExtraFiles = {
     source: string | null;
     comments?: SourceComments;
     collapseMap?: CollapseMap;
+    totalLines?: number;
   };
 };
 ```

From 31dcfc702f090a405c87ee68fdae127fff46302e Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 16:43:41 -0400
Subject: [PATCH 25/45] Fix firefox bug

---
 AGENTS.md                                     |  2 +-
 .../docs-infra/src/useCode/Pre.browser.tsx    | 36 +++++++++++++++++++
 .../docs-infra/src/useCode/useEditable.ts     | 17 +++++----
 3 files changed, 47 insertions(+), 8 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index c8a641ee8..d0a07942e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,7 +23,7 @@ Always reference these instructions first and fallback to search or bash command
 - **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 (e.g. CI), run `pnpm test:browser:unconfined` directly — no container engine needed.
+- **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/packages/docs-infra/src/useCode/Pre.browser.tsx b/packages/docs-infra/src/useCode/Pre.browser.tsx
index 57a44fe16..f33e17e99 100644
--- a/packages/docs-infra/src/useCode/Pre.browser.tsx
+++ b/packages/docs-infra/src/useCode/Pre.browser.tsx
@@ -110,6 +110,42 @@ describe('Pre - browser', () => {
     });
   });
 
+  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')!;
diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index e4290384c..8140b65aa 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -33,7 +33,7 @@ SOFTWARE.
 // - Replace manual queue-based DFS in makeRange with TreeWalker for better performance
 // - Replace Range.toString() in getPosition with a TreeWalker character count to avoid O(N) string allocation
 // - Deduplicate toString() calls via trackState return value
-// - Fix Firefox rapid-typing line-loss bug: preserve pre-edit pendingContent across key-repeat keydowns
+// - Fix Firefox rapid-typing line-loss bug: preserve pre-edit pendingContent across keydowns until flush
 // - Debounce repeat-key flushes so highlights only re-render once the user pauses typing
 // - Fix undo-to-initial-state bug: allow trackState to record before the first flushChanges
 // - Fix undo-after-rapid-Enter bug: bypass 500ms dedup on keyup for structural edits (Enter)
@@ -623,12 +623,15 @@ export const useEditable = (
         return;
       }
 
-      // Only capture the pre-edit snapshot on the first keydown in a key-repeat
-      // sequence. Repeated keydowns must NOT overwrite pendingContent because the DOM
-      // may already contain a Firefox-merged state after the first keystroke. If we
-      // overwrote pendingContent here, repairUnexpectedLineMerge would receive the
-      // merged DOM as the "previous" content and could not detect that a line was lost.
-      if (!event.repeat || state.pendingContent === null) {
+      // 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);
       }
 

From 917dad853e2ebc8ae9b2ac06620e5751ab61fb94 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 16:57:17 -0400
Subject: [PATCH 26/45] Fix highlight state bug

---
 .../src/useCode/useSourceEditing.test.ts      | 66 +++++++++++++++++++
 .../src/useCode/useSourceEditing.ts           | 15 ++++-
 2 files changed, 78 insertions(+), 3 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useSourceEditing.test.ts b/packages/docs-infra/src/useCode/useSourceEditing.test.ts
index e1288c6b5..8e4f789d4 100644
--- a/packages/docs-infra/src/useCode/useSourceEditing.test.ts
+++ b/packages/docs-infra/src/useCode/useSourceEditing.test.ts
@@ -22,6 +22,10 @@ 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.
@@ -423,6 +427,68 @@ describe('useSourceEditing', () => {
       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('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
diff --git a/packages/docs-infra/src/useCode/useSourceEditing.ts b/packages/docs-infra/src/useCode/useSourceEditing.ts
index 9b705334c..7c77390e8 100644
--- a/packages/docs-infra/src/useCode/useSourceEditing.ts
+++ b/packages/docs-infra/src/useCode/useSourceEditing.ts
@@ -71,9 +71,18 @@ function shiftComments(
   // 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): cursor moved down, old line = position.line - lineDelta
-  // For deletions (lineDelta < 0): cursor stayed, old line = position.line
-  const editLine = position.line - Math.max(0, lineDelta) + 1; // 1-indexed
+  // 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 } : {};

From c3f2f9feabc11d20d674e6e459f944df3edd0aeb Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 17:13:12 -0400
Subject: [PATCH 27/45] Handle removing empty lines at the start of a region

---
 .../components/code-highlighter/types.md      |  2 +
 .../docs-infra/src/CodeHighlighter/types.ts   |  2 +
 .../src/useCode/useSourceEditing.test.ts      | 51 +++++++++++
 .../src/useCode/useSourceEditing.ts           | 84 +++++++++++++++----
 4 files changed, 121 insertions(+), 18 deletions(-)

diff --git a/docs/app/docs-infra/components/code-highlighter/types.md b/docs/app/docs-infra/components/code-highlighter/types.md
index f98608e0e..b686843c5 100644
--- a/docs/app/docs-infra/components/code-highlighter/types.md
+++ b/docs/app/docs-infra/components/code-highlighter/types.md
@@ -595,6 +595,7 @@ type ControlledVariantCode = {
   comments?: SourceComments;
   collapseMap?: CollapseMap;
   totalLines?: number;
+  emptyLines?: number[];
 };
 ```
 
@@ -607,6 +608,7 @@ type ControlledVariantExtraFiles = {
     comments?: SourceComments;
     collapseMap?: CollapseMap;
     totalLines?: number;
+    emptyLines?: number[];
   };
 };
 ```
diff --git a/packages/docs-infra/src/CodeHighlighter/types.ts b/packages/docs-infra/src/CodeHighlighter/types.ts
index 1c160c9ed..f1006b253 100644
--- a/packages/docs-infra/src/CodeHighlighter/types.ts
+++ b/packages/docs-infra/src/CodeHighlighter/types.ts
@@ -98,6 +98,7 @@ export type ControlledVariantExtraFiles = {
     comments?: SourceComments;
     collapseMap?: CollapseMap;
     totalLines?: number;
+    emptyLines?: number[];
   };
 };
 export type ControlledVariantCode = CodeMeta & {
@@ -108,6 +109,7 @@ export type ControlledVariantCode = CodeMeta & {
   comments?: SourceComments;
   collapseMap?: CollapseMap;
   totalLines?: number;
+  emptyLines?: number[];
 };
 export type ControlledCode = { [key: string]: undefined | null | ControlledVariantCode };
 
diff --git a/packages/docs-infra/src/useCode/useSourceEditing.test.ts b/packages/docs-infra/src/useCode/useSourceEditing.test.ts
index 8e4f789d4..888672d91 100644
--- a/packages/docs-infra/src/useCode/useSourceEditing.test.ts
+++ b/packages/docs-infra/src/useCode/useSourceEditing.test.ts
@@ -489,6 +489,57 @@ describe('useSourceEditing', () => {
       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
diff --git a/packages/docs-infra/src/useCode/useSourceEditing.ts b/packages/docs-infra/src/useCode/useSourceEditing.ts
index 7c77390e8..c05a806d1 100644
--- a/packages/docs-infra/src/useCode/useSourceEditing.ts
+++ b/packages/docs-infra/src/useCode/useSourceEditing.ts
@@ -31,17 +31,40 @@ interface ShiftResult {
 }
 
 /**
- * Counts the number of lines in a string without allocating an intermediate array.
+ * 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 countSourceLines(source: string): number {
-  let count = 1;
-  let idx = 0;
-  // eslint-disable-next-line no-cond-assign
-  while ((idx = source.indexOf('\n', idx)) !== -1) {
-    count += 1;
-    idx += 1;
+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 count;
+  return emptyLines ? { totalLines, emptyLines } : { totalLines };
 }
 
 /**
@@ -53,12 +76,18 @@ function countSourceLines(source: string): number {
  * 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 };
@@ -122,6 +151,10 @@ function shiftComments(
     }
   }
 
+  // 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) {
@@ -147,12 +180,22 @@ function shiftComments(
       // 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) {
-        shifted[editLine] = [...(shifted[editLine] ?? []), ...regular];
-        newCollapsed.push({ offset: line - editLine, comments: regular });
+        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;
@@ -206,13 +249,13 @@ function toControlledCode(code: Code): ControlledCode {
       extraFiles = {};
       for (const [fileName, entry] of Object.entries(variant.extraFiles)) {
         if (typeof entry === 'string') {
-          extraFiles[fileName] = { source: entry, totalLines: countSourceLines(entry) };
+          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 } : {}),
-            totalLines: extraSource != null ? countSourceLines(extraSource) : undefined,
+            ...(extraSource != null ? analyzeSource(extraSource) : {}),
           };
         }
       }
@@ -221,7 +264,7 @@ function toControlledCode(code: Code): ControlledCode {
     result[key] = {
       ...variant,
       source,
-      totalLines: source != null ? countSourceLines(source) : undefined,
+      ...(source != null ? analyzeSource(source) : {}),
       ...(extraFiles ? { extraFiles } : {}),
     } as ControlledCode[string];
   }
@@ -270,21 +313,24 @@ export function useSourceEditing({
           if (source === variant.source) {
             return currentCode ?? newCode;
           }
-          const newLineCount = countSourceLines(source);
+          const { totalLines: newLineCount, emptyLines: newEmptyLines } = analyzeSource(source);
           const oldLineCount =
-            variant.totalLines ?? (variant.source != null ? countSourceLines(variant.source) : 0);
+            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,
           };
@@ -293,16 +339,17 @@ export function useSourceEditing({
           if (source === extraEntry?.source) {
             return currentCode ?? newCode;
           }
-          const newLineCount = countSourceLines(source);
+          const { totalLines: newLineCount, emptyLines: newEmptyLines } = analyzeSource(source);
           const oldLineCount =
             extraEntry?.totalLines ??
-            (extraEntry?.source != null ? countSourceLines(extraEntry.source) : 0);
+            (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] = {
@@ -313,6 +360,7 @@ export function useSourceEditing({
                 ...extraEntry,
                 source,
                 totalLines: newLineCount,
+                emptyLines: newEmptyLines,
                 comments: shiftedComments,
                 collapseMap: newCollapseMap,
               },

From 0a6358351cc44bdc71ceda3996eba73677ca9540 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 17:24:59 -0400
Subject: [PATCH 28/45] Prevent firefox enter keydown bug

---
 .../docs-infra/src/useCode/useEditable.ts     | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 8140b65aa..720454505 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -34,6 +34,7 @@ SOFTWARE.
 // - Replace Range.toString() in getPosition with a TreeWalker character count to avoid O(N) string allocation
 // - Deduplicate toString() calls via trackState return value
 // - Fix Firefox rapid-typing line-loss bug: preserve pre-edit pendingContent across keydowns until flush
+// - Refresh pendingContent baseline after controlled edits so native input following Enter/Tab/Backspace can still be repaired
 // - Debounce repeat-key flushes so highlights only re-render once the user pauses typing
 // - Fix undo-to-initial-state bug: allow trackState to record before the first flushChanges
 // - Fix undo-after-rapid-Enter bug: bypass 500ms dedup on keyup for structural edits (Enter)
@@ -679,6 +680,24 @@ export const useEditable = (
         edit.update(newContent);
       }
 
+      // 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.

From 4f0ab0c17885446d4ee9739601e954c64a735cad Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 17:27:16 -0400
Subject: [PATCH 29/45] Improve firefox undo stack

---
 .../docs-infra/src/useCode/useEditable.ts     | 40 ++++++++++++++-----
 1 file changed, 29 insertions(+), 11 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 720454505..a2d4ec002 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -35,6 +35,7 @@ SOFTWARE.
 // - Deduplicate toString() calls via trackState return value
 // - Fix Firefox rapid-typing line-loss bug: preserve pre-edit pendingContent across keydowns until flush
 // - Refresh pendingContent baseline after controlled edits so native input following Enter/Tab/Backspace can still be repaired
+// - Record repaired (not raw) content into the undo stack so Firefox merge intermediates don't pollute history
 // - Debounce repeat-key flushes so highlights only re-render once the user pauses typing
 // - Fix undo-to-initial-state bug: allow trackState to record before the first flushChanges
 // - Fix undo-after-rapid-Enter bug: bypass 500ms dedup on keyup for structural edits (Enter)
@@ -510,7 +511,11 @@ export const useEditable = (
     const blanklineRe = new RegExp(`^(?:${indentPattern})*(${indentPattern})$`);
 
     let trackStateTimestamp: number;
-    const trackState = (ignoreTimestamp?: boolean): string | null => {
+    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
@@ -519,8 +524,12 @@ export const useEditable = (
         return null;
       }
 
-      const content = toString(element);
-      const position = getPosition(element);
+      // 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
@@ -549,7 +558,7 @@ export const useEditable = (
       state.disconnected = true;
     };
 
-    const flushChanges = () => {
+    const flushChanges = (ignoreTimestamp?: boolean) => {
       const records = observerRef.current?.takeRecords() ?? [];
       state.queue.push(...records);
       const position = getPosition(element);
@@ -576,6 +585,12 @@ export const useEditable = (
           }
         }
 
+        // 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);
+
         state.onChange(content, position);
       }
 
@@ -722,13 +737,17 @@ export const useEditable = (
         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.
       if (!isUndoRedoKey(event)) {
-        // 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.
-        trackState(event.key === 'Enter');
+        flushChanges(event.key === 'Enter');
+      } else {
+        flushChanges();
       }
-      flushChanges();
       // Chrome Quirk: The contenteditable may lose focus after the first edit or so
       element.focus();
     };
@@ -743,8 +762,7 @@ export const useEditable = (
       event.preventDefault();
       state.pendingContent = trackState(true) ?? toString(element);
       edit.insert(event.clipboardData!.getData('text/plain'));
-      trackState(true);
-      flushChanges();
+      flushChanges(true);
     };
 
     document.addEventListener('selectstart', onSelect);

From e1aa3c37006a544c5b78f375bf31461afb331ec0 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 18:01:32 -0400
Subject: [PATCH 30/45] bump version

---
 packages/docs-infra/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docs-infra/package.json b/packages/docs-infra/package.json
index e8dc8c1bb..c2b8e3dcb 100644
--- a/packages/docs-infra/package.json
+++ b/packages/docs-infra/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",

From d67f138ccc96d574d8b7847dd5531bbeaa359fc5 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 24 Apr 2026 09:51:47 -0400
Subject: [PATCH 31/45] Add missing `@focus`

---
 .../components/code-controller-context/demos/code/page.tsx      | 2 ++
 1 file changed, 2 insertions(+)

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
index 11f5bb8cf..6891f8544 100644
--- 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
@@ -11,6 +11,7 @@ const sourceParser = createParseSource();
 
 export default function Page() {
   return (
+    // @focus-start
     <CodeProvider>
       <CodeController>
         <CodeHighlighter
@@ -23,5 +24,6 @@ export default function Page() {
         </CodeHighlighter>
       </CodeController>
     </CodeProvider>
+    // @focus-end
   );
 }

From bc9b0b6ba3ca39e0d7fcb766f609c0f0802497de Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Sat, 25 Apr 2026 18:39:37 -0400
Subject: [PATCH 32/45] Fix lint

---
 .../demos/demo-live/DemoLiveContent.module.css                | 4 ----
 1 file changed, 4 deletions(-)

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 8eecf03b2..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
@@ -86,10 +86,6 @@
   outline: none;
 }
 
-.codeBlock :global(.frame) {
-  display: block;
-}
-
 .codeBlock :global(.frame)[data-frame-type='highlighted'] {
   background: #ebe4ff;
   border-radius: 8px;

From 1a6585eba6f591b9df1e342dada33f7455980192 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Mon, 27 Apr 2026 17:27:42 -0400
Subject: [PATCH 33/45] Fix resetFocus()

Co-authored-by: Copilot <copilot@github.com>
---
 docs/app/docs-infra/hooks/use-demo/page.mdx | 45 ++++++++++++++++++++-
 packages/docs-infra/src/useDemo/useDemo.ts  | 10 +++--
 2 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/docs/app/docs-infra/hooks/use-demo/page.mdx b/docs/app/docs-infra/hooks/use-demo/page.mdx
index a1aa5fd99..9be6c7338 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>
 
@@ -555,6 +555,49 @@ 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/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,

From c6a0aa5be127bd838f8099f0740a96ae047ab45c Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Mon, 27 Apr 2026 17:32:09 -0400
Subject: [PATCH 34/45] validate docs

---
 docs/app/docs-infra/hooks/page.mdx          | 1 +
 docs/app/docs-infra/hooks/use-demo/page.mdx | 7 +------
 docs/app/docs-infra/hooks/use-demo/types.md | 2 +-
 3 files changed, 3 insertions(+), 7 deletions(-)

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-demo/page.mdx b/docs/app/docs-infra/hooks/use-demo/page.mdx
index 9be6c7338..8b2380a11 100644
--- a/docs/app/docs-infra/hooks/use-demo/page.mdx
+++ b/docs/app/docs-infra/hooks/use-demo/page.mdx
@@ -574,12 +574,7 @@ export function DemoContent(props) {
     <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}
-        />
+        <button ref={demo.focusRef} tabIndex={-1} aria-hidden className={styles.focusTarget} />
         {demo.component}
       </div>
 
diff --git a/docs/app/docs-infra/hooks/use-demo/types.md b/docs/app/docs-infra/hooks/use-demo/types.md
index 7276777c3..c30fea996 100644
--- a/docs/app/docs-infra/hooks/use-demo/types.md
+++ b/docs/app/docs-infra/hooks/use-demo/types.md
@@ -221,7 +221,7 @@ type ReturnValue = void;
 | Property            | Type                                                                                                                             | Description |
 | :------------------ | :------------------------------------------------------------------------------------------------------------------------------- | :---------- |
 | component           | `string \| number \| bigint \| true \| ReactElement \| Iterable<React.ReactNode, any, any> \| Promise<AwaitedReactNode> \| null` | -           |
-| ref                 | `React.RefObject<HTMLDivElement \| null>`                                                                                        | -           |
+| focusRef            | `React.RefObject<HTMLButtonElement \| null>`                                                                                     | -           |
 | resetFocus          | `(() => void)`                                                                                                                   | -           |
 | openStackBlitz      | `(() => void)`                                                                                                                   | -           |
 | openCodeSandbox     | `(() => void)`                                                                                                                   | -           |

From 449ad9906e289719f6abf68e060060ff32d08edf Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Mon, 27 Apr 2026 18:50:26 -0400
Subject: [PATCH 35/45] Opt into indenting

Co-authored-by: Copilot <copilot@github.com>
---
 .../demos/CodeIndent.tsx                      | 13 ++--
 .../pipeline/enhance-code-emphasis/page.mdx   |  5 +-
 .../pipeline/enhance-code-emphasis/types.md   |  9 +++
 .../enhanceCodeEmphasis.test.ts               | 64 ++++++++++++-------
 .../enhanceCodeEmphasis.ts                    |  9 ++-
 .../parseSource/calculateFrameRanges.ts       |  9 +++
 6 files changed, 78 insertions(+), 31 deletions(-)

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 aed60e8d4..c7947bb83 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.
 
@@ -627,7 +628,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/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
index bc8433d9d..8e6a437f4 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>"`,
       );
     });
 
@@ -468,7 +472,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>"`,
       );
     });
 
@@ -495,7 +499,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>"`,
       );
     });
   });
@@ -597,9 +601,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>
@@ -773,7 +777,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>
@@ -801,11 +805,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>
@@ -845,7 +849,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;
 
@@ -961,7 +965,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>
@@ -1092,6 +1096,7 @@ const e = 5;`,
     it('should support @focus on @highlight-start', async () => {
       const enhancer = createEnhanceCodeEmphasis({
         paddingFrameMaxSize: 1,
+        emitFrameIndent: true,
       });
 
       const result = await testEmphasis(
@@ -1155,10 +1160,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 4e30db91c..6228223ea 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
@@ -1547,8 +1547,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. */

From fd20fc3faa09de86fb6ddf38cddb3f8a8d67c4ba Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Mon, 27 Apr 2026 18:59:59 -0400
Subject: [PATCH 36/45] Improve collapsed editable behavior

Co-authored-by: Copilot <copilot@github.com>
---
 packages/docs-infra/src/useCode/Pre.tsx       | 121 +++++-
 packages/docs-infra/src/useCode/useCode.ts    |   2 +
 .../src/useCode/useEditable.test.ts           | 373 +++++++++++++++++-
 .../docs-infra/src/useCode/useEditable.ts     | 154 ++++++++
 .../src/useCode/useFileNavigation.tsx         |  24 ++
 5 files changed, 668 insertions(+), 6 deletions(-)

diff --git a/packages/docs-infra/src/useCode/Pre.tsx b/packages/docs-infra/src/useCode/Pre.tsx
index 8ce615a83..268ea87f6 100644
--- a/packages/docs-infra/src/useCode/Pre.tsx
+++ b/packages/docs-infra/src/useCode/Pre.tsx
@@ -48,6 +48,83 @@ 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;
+};
+
+/**
+ * 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);
+
+    const text = toText(child, { whitespace: 'pre' });
+    const newlines = text.length > 0 ? text.split('\n').length - 1 : 0;
+    const lastContentRow = text.endsWith('\n') ? row + Math.max(0, newlines - 1) : row + newlines;
+
+    if (isVisibleWhenCollapsed) {
+      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);
@@ -79,6 +156,8 @@ export function Pre({
   setSource,
   shouldHighlight,
   hydrateMargin = '200px 0px 200px 0px',
+  expanded = false,
+  expand,
 }: {
   children: VariantSource;
   className?: string;
@@ -88,6 +167,19 @@ export function Pre({
   setSource?: (source: string, fileName?: string, position?: Position) => void;
   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 isEditable = Boolean(setSource);
 
@@ -126,15 +218,34 @@ export function Pre({
     [setSource, fileName],
   );
 
-  useEditable(preRef, onEditableChange, {
-    indentation: 2,
-    disabled: !setSource || !editableReady,
-  });
-
   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,
+  });
+
   const observer = React.useRef<IntersectionObserver | null>(null);
   const frameIndexMap = React.useRef(new WeakMap<Element, number>());
   const bindIntersectionObserver = React.useCallback(
diff --git a/packages/docs-infra/src/useCode/useCode.ts b/packages/docs-infra/src/useCode/useCode.ts
index 999212396..ed37ef3f3 100644
--- a/packages/docs-infra/src/useCode/useCode.ts
+++ b/packages/docs-infra/src/useCode/useCode.ts
@@ -196,6 +196,8 @@ export function useCode<T extends {} = {}>(
     saveVariantToLocalStorage: variantSelection.saveVariantToLocalStorage,
     hashVariant: variantSelection.hashVariant,
     sourceEnhancers: mergedEnhancers,
+    expanded: uiState.expanded,
+    expand: uiState.expand,
   });
 
   // Sub-hook: Copy Functionality
diff --git a/packages/docs-infra/src/useCode/useEditable.test.ts b/packages/docs-infra/src/useCode/useEditable.test.ts
index 85aa70318..70078a56d 100644
--- a/packages/docs-infra/src/useCode/useEditable.test.ts
+++ b/packages/docs-infra/src/useCode/useEditable.test.ts
@@ -42,7 +42,17 @@ function placeSelection(element: HTMLElement, offset: number, extent = 0) {
 /**
  * Renders `useEditable` bound to a real `<pre>` element and returns helpers.
  */
-function setup(initialContent: string, opts: { disabled?: boolean; indentation?: number } = {}) {
+function setup(
+  initialContent: string,
+  opts: {
+    disabled?: boolean;
+    indentation?: number;
+    minColumn?: number;
+    minRow?: number;
+    maxRow?: number;
+    onBoundary?: () => void;
+  } = {},
+) {
   const element = document.createElement('pre');
   element.textContent = initialContent;
   document.body.appendChild(element);
@@ -868,6 +878,367 @@ describe('useEditable', () => {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // 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);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // 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);
+      });
+    });
+  });
+
   // ---------------------------------------------------------------------------
   // Undo/Redo
   // ---------------------------------------------------------------------------
diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index a2d4ec002..ac73e9e3e 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -40,6 +40,8 @@ SOFTWARE.
 // - Fix undo-to-initial-state bug: allow trackState to record before the first flushChanges
 // - Fix undo-after-rapid-Enter bug: bypass 500ms dedup on keyup for structural edits (Enter)
 // - Fix React 19 compatibility: useState lazy init for edit, useRef for MutationObserver, window SSR guard
+// - Add `minColumn` option: skip clipped indent gutter via horizontal arrow navigation
+// - Add `minRow`/`maxRow`/`onBoundary` options: detect arrow-key navigation past the visible region; allow native movement when `onBoundary` is provided so hosts can expand collapsed regions without losing focus
 
 import * as React from 'react';
 
@@ -326,6 +328,48 @@ interface State {
 export interface Options {
   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;
 }
 
 export interface Edit {
@@ -370,6 +414,24 @@ export const useEditable = (
     });
   }
 
+  // The visible-region bounds (`minColumn`/`minRow`/`maxRow`/`onBoundary`)
+  // only affect the keydown handler's logic, not the contentEditable setup
+  // itself. We mirror them in a ref so the keydown handler always reads 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: opts.minColumn,
+    minRow: opts.minRow,
+    maxRow: opts.maxRow,
+    onBoundary: opts.onBoundary,
+  });
+  boundsRef.current.minColumn = opts.minColumn;
+  boundsRef.current.minRow = opts.minRow;
+  boundsRef.current.maxRow = opts.maxRow;
+  boundsRef.current.onBoundary = opts.onBoundary;
+
   // 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.
@@ -693,6 +755,98 @@ export const useEditable = (
             (opts!.indentation ? ' '.repeat(opts!.indentation) : '\t') +
             content.slice(start);
         edit.update(newContent);
+      } else if (
+        (boundsRef.current.minColumn !== undefined ||
+          boundsRef.current.minRow !== undefined ||
+          boundsRef.current.maxRow !== 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).
+        // 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 } = boundsRef.current;
+          const position = getPosition(element);
+          const column = position.content.length;
+          const lines = toString(element).split('\n');
+          const lineText = lines[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;
+
+          if (event.key === 'ArrowUp') {
+            if (atVisibleStart) {
+              if (onBoundary) {
+                // Allow native caret movement so the host can scroll the
+                // newly-revealed content into view alongside the caret.
+                onBoundary();
+              } else {
+                event.preventDefault();
+              }
+            }
+          } else if (event.key === 'ArrowDown') {
+            if (atVisibleEnd) {
+              if (onBoundary) {
+                onBoundary();
+              } else {
+                event.preventDefault();
+              }
+            }
+          } else if (event.key === 'ArrowLeft') {
+            if (atVisibleStart && atLineStart) {
+              if (onBoundary) {
+                onBoundary();
+              } else {
+                event.preventDefault();
+              }
+            } else if (
+              lineIsIndented &&
+              minColumn !== undefined &&
+              column === minColumn &&
+              position.line > 0
+            ) {
+              event.preventDefault();
+              const prevLine = lines[position.line - 1] ?? '';
+              edit.move({ row: position.line - 1, column: prevLine.length });
+            }
+          } else if (atVisibleEnd && atLineEnd) {
+            if (onBoundary) {
+              onBoundary();
+            } else {
+              event.preventDefault();
+            }
+          } else if (
+            minColumn !== undefined &&
+            column === lineText.length &&
+            position.line < lines.length - 1
+          ) {
+            const nextLine = lines[position.line + 1] ?? '';
+            const nextIsIndented =
+              nextLine.length >= minColumn && /^\s*$/.test(nextLine.slice(0, minColumn));
+            if (nextIsIndented) {
+              event.preventDefault();
+              edit.move({ row: position.line + 1, column: minColumn });
+            }
+          }
+        }
       }
 
       // After a controlled edit in plaintext-only contentEditable, the DOM is
diff --git a/packages/docs-infra/src/useCode/useFileNavigation.tsx b/packages/docs-infra/src/useCode/useFileNavigation.tsx
index 14ef2a230..4786c1a5d 100644
--- a/packages/docs-infra/src/useCode/useFileNavigation.tsx
+++ b/packages/docs-infra/src/useCode/useFileNavigation.tsx
@@ -114,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 {
@@ -146,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<
@@ -514,6 +526,8 @@ export function useFileNavigation({
           language={language}
           setSource={setSource}
           shouldHighlight={shouldHighlight}
+          expanded={expanded}
+          expand={expand}
         >
           {sourceToRender}
         </Pre>
@@ -534,6 +548,8 @@ export function useFileNavigation({
     selectedVariantKey,
     sourceEnhancers,
     selectedFileNameInternal,
+    expanded,
+    expand,
   ]);
 
   const selectedFileLines = React.useMemo(() => {
@@ -599,6 +615,8 @@ export function useFileNavigation({
             fileName={f.originalName}
             setSource={setSource}
             shouldHighlight={shouldHighlight}
+            expanded={expanded}
+            expand={expand}
           >
             {f.source}
           </Pre>
@@ -625,6 +643,8 @@ export function useFileNavigation({
             language={selectedVariant.language}
             setSource={setSource}
             shouldHighlight={shouldHighlight}
+            expanded={expanded}
+            expand={expand}
           >
             {selectedVariant.source}
           </Pre>
@@ -664,6 +684,8 @@ export function useFileNavigation({
               language={language ?? getLanguageFromFileName(fileName)}
               setSource={setSource}
               shouldHighlight={shouldHighlight}
+              expanded={expanded}
+              expand={expand}
             >
               {source}
             </Pre>
@@ -682,6 +704,8 @@ export function useFileNavigation({
     shouldHighlight,
     preClassName,
     setSource,
+    expanded,
+    expand,
   ]);
 
   // Create a wrapper for selectFileName that handles transformed filenames and URL updates

From 8f3570dabe45afc72ad591d9a0e4ade932d7a757 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Mon, 27 Apr 2026 21:48:16 -0400
Subject: [PATCH 37/45] Improve caret behavior

---
 packages/docs-infra/src/useCode/Pre.tsx       |    8 +
 .../src/useCode/useEditable.test.ts           | 1038 +++++++++++++++++
 .../docs-infra/src/useCode/useEditable.ts     |  655 ++++++++++-
 3 files changed, 1678 insertions(+), 23 deletions(-)

diff --git a/packages/docs-infra/src/useCode/Pre.tsx b/packages/docs-infra/src/useCode/Pre.tsx
index 268ea87f6..6ce43ff91 100644
--- a/packages/docs-infra/src/useCode/Pre.tsx
+++ b/packages/docs-infra/src/useCode/Pre.tsx
@@ -244,6 +244,14 @@ export function Pre({
     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,
   });
 
   const observer = React.useRef<IntersectionObserver | null>(null);
diff --git a/packages/docs-infra/src/useCode/useEditable.test.ts b/packages/docs-infra/src/useCode/useEditable.test.ts
index 70078a56d..2baf547ee 100644
--- a/packages/docs-infra/src/useCode/useEditable.test.ts
+++ b/packages/docs-infra/src/useCode/useEditable.test.ts
@@ -51,6 +51,7 @@ function setup(
     minRow?: number;
     maxRow?: number;
     onBoundary?: () => void;
+    caretSelector?: string;
   } = {},
 ) {
   const element = document.createElement('pre');
@@ -1025,6 +1026,73 @@ describe('useEditable', () => {
 
       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);
+    });
   });
 
   // ---------------------------------------------------------------------------
@@ -1239,6 +1307,419 @@ describe('useEditable', () => {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // 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('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('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
   // ---------------------------------------------------------------------------
@@ -1470,6 +1951,559 @@ describe('useEditable', () => {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // 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');
+    });
+  });
+
   // ---------------------------------------------------------------------------
   // Event listener cleanup
   // ---------------------------------------------------------------------------
@@ -1486,7 +2520,11 @@ describe('useEditable', () => {
       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();
diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index ac73e9e3e..f1eeb27d5 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -42,6 +42,8 @@ SOFTWARE.
 // - Fix React 19 compatibility: useState lazy init for edit, useRef for MutationObserver, window SSR guard
 // - Add `minColumn` option: skip clipped indent gutter via horizontal arrow navigation
 // - Add `minRow`/`maxRow`/`onBoundary` options: detect arrow-key navigation past the visible region; allow native movement when `onBoundary` is provided so hosts can expand collapsed regions without losing focus
+// - Add `caretSelector` option: when the caret is inside a matching element, `ArrowLeft` at column 0 and `ArrowRight` at the end of a line jump synchronously to the adjacent line so non-selectable gap text nodes (e.g. newlines between `.line` spans) don't trap the caret. Vertical navigation is left to the browser to preserve wrapped-line behavior in `pre-wrap` layouts
+// - Override `copy`/`cut` to write `Range.toString()` for `text/plain` (avoiding duplicated newlines from block-level line wrappers like `display: block` `.line` spans separated by literal `\n` text nodes) and a `<pre>`-wrapped clone with computed styles inlined for `text/html` so pasting into rich-text targets (email, Word, Notion, etc.) keeps syntax highlighting without depending on the host stylesheet. When `minColumn` is set, also strips up to that many leading whitespace characters per line from both payloads so the clipped indent gutter doesn't leak into the clipboard
 
 import * as React from 'react';
 
@@ -81,6 +83,120 @@ const isPlaintextInputKey = (event: KeyboardEvent): boolean => {
   );
 };
 
+// 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_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;';
+
+// Strip leading whitespace characters per line of a plain-text string,
+// used to drop the clipped indent gutter (`minColumn`) from clipboard
+// payloads so the pasted snippet matches what the user sees.
+//
+// `firstLineCount` is the budget for the first line — typically
+// `max(0, minColumn - startColumn)` so that a selection starting
+// mid-gutter only loses the gutter portion still inside the selection.
+// `restCount` is the budget for every line after a `\n`, normally the
+// full `minColumn`.
+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`. Used by `cut` to re-insert the gutter
+// whitespace at the selection location so cut is lossless: the
+// clipboard payload omits the clipped indent gutter, but the underlying
+// document keeps it.
+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 version 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 that indent nested
+// inside multiple wrapper spans is still removed correctly.
+const stripLeadingPerLineDom = (root: Node, firstLineCount: number, restCount: number): void => {
+  const walker = root.ownerDocument!.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;
+  }
+};
+
 const toString = (element: HTMLElement): string => {
   const content = element.textContent || '';
 
@@ -370,6 +486,32 @@ export interface Options {
    * (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;
 }
 
 export interface Edit {
@@ -415,8 +557,8 @@ export const useEditable = (
   }
 
   // The visible-region bounds (`minColumn`/`minRow`/`maxRow`/`onBoundary`)
-  // only affect the keydown handler's logic, not the contentEditable setup
-  // itself. We mirror them in a ref so the keydown handler always reads the
+  // 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),
@@ -426,11 +568,13 @@ export const useEditable = (
     minRow: opts.minRow,
     maxRow: opts.maxRow,
     onBoundary: opts.onBoundary,
+    caretSelector: opts.caretSelector,
   });
   boundsRef.current.minColumn = opts.minColumn;
   boundsRef.current.minRow = opts.minRow;
   boundsRef.current.maxRow = opts.maxRow;
   boundsRef.current.onBoundary = opts.onBoundary;
+  boundsRef.current.caretSelector = opts.caretSelector;
 
   // useMemo with [] is a performance hint, not a semantic guarantee — React 19
   // may discard the cache and recreate the object. useState with a lazy
@@ -758,7 +902,8 @@ export const useEditable = (
       } else if (
         (boundsRef.current.minColumn !== undefined ||
           boundsRef.current.minRow !== undefined ||
-          boundsRef.current.maxRow !== undefined) &&
+          boundsRef.current.maxRow !== undefined ||
+          boundsRef.current.caretSelector !== undefined) &&
         !event.shiftKey &&
         !event.metaKey &&
         !event.ctrlKey &&
@@ -773,14 +918,22 @@ export const useEditable = (
         //   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 } = boundsRef.current;
+          const { minColumn, minRow, maxRow, onBoundary, caretSelector } = boundsRef.current;
           const position = getPosition(element);
           const column = position.content.length;
-          const lines = toString(element).split('\n');
+          const allLines = toString(element).split('\n');
+          // `toString` guarantees a trailing `\n`, so the split produces a
+          // phantom empty entry at the end. Drop it so `lines.length - 1` is
+          // the index of the real last line.
+          const lines = allLines.length > 1 ? allLines.slice(0, -1) : allLines;
           const lineText = lines[position.line] ?? '';
           const lineIsIndented =
             minColumn !== undefined &&
@@ -792,9 +945,54 @@ export const useEditable = (
             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 =
+                startContainer.nodeType === Node.ELEMENT_NODE
+                  ? (startContainer as Element)
+                  : 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).
+          const moveToLine = (targetRow: number, desiredColumn: number) => {
+            const targetLine = lines[targetRow] ?? '';
+            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 (onBoundary) {
+              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, column);
+                onBoundary?.();
+              } else if (onBoundary) {
                 // Allow native caret movement so the host can scroll the
                 // newly-revealed content into view alongside the caret.
                 onBoundary();
@@ -804,7 +1002,11 @@ export const useEditable = (
             }
           } else if (event.key === 'ArrowDown') {
             if (atVisibleEnd) {
-              if (onBoundary) {
+              if (caretInLine && position.line < lines.length - 1) {
+                event.preventDefault();
+                moveToLine(position.line + 1, column);
+                onBoundary?.();
+              } else if (onBoundary) {
                 onBoundary();
               } else {
                 event.preventDefault();
@@ -812,7 +1014,12 @@ export const useEditable = (
             }
           } else if (event.key === 'ArrowLeft') {
             if (atVisibleStart && atLineStart) {
-              if (onBoundary) {
+              if (caretInLine && position.line > 0) {
+                event.preventDefault();
+                const prevLine = lines[position.line - 1] ?? '';
+                edit.move({ row: position.line - 1, column: prevLine.length });
+                onBoundary?.();
+              } else if (onBoundary) {
                 onBoundary();
               } else {
                 event.preventDefault();
@@ -826,26 +1033,82 @@ export const useEditable = (
               event.preventDefault();
               const prevLine = lines[position.line - 1] ?? '';
               edit.move({ row: position.line - 1, column: prevLine.length });
-            }
-          } else if (atVisibleEnd && atLineEnd) {
-            if (onBoundary) {
-              onBoundary();
-            } else {
+            } 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();
+              const prevLine = lines[position.line - 1] ?? '';
+              edit.move({ row: position.line - 1, column: prevLine.length });
             }
-          } else if (
-            minColumn !== undefined &&
-            column === lineText.length &&
-            position.line < lines.length - 1
-          ) {
-            const nextLine = lines[position.line + 1] ?? '';
-            const nextIsIndented =
-              nextLine.length >= minColumn && /^\s*$/.test(nextLine.slice(0, minColumn));
-            if (nextIsIndented) {
+          } else if (event.key === 'ArrowRight') {
+            if (atVisibleEnd && atLineEnd) {
+              if (caretInLine && position.line < lines.length - 1) {
+                event.preventDefault();
+                moveToLine(position.line + 1, 0);
+                onBoundary?.();
+              } else if (onBoundary) {
+                onBoundary();
+              } else {
+                event.preventDefault();
+              }
+            } else if (
+              minColumn !== undefined &&
+              column === lineText.length &&
+              position.line < lines.length - 1
+            ) {
+              const nextLine = lines[position.line + 1] ?? '';
+              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 && position.line < lines.length - 1) {
               event.preventDefault();
-              edit.move({ row: position.line + 1, column: minColumn });
+              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);
+          });
         }
       }
 
@@ -919,10 +1182,352 @@ export const useEditable = (
       flushChanges(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);
+      }
+      let plainText = range.toString();
+      if (restStrip > 0) {
+        // 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.
+        plainText = stripLeadingPerLine(plainText, firstLineStrip, restStrip);
+      }
+      event.clipboardData.setData('text/plain', plainText);
+      // Re-serialize the HTML ourselves since `preventDefault()` skipped
+      // the browser's default text/html write. Wrap in a `<pre>` so the
+      // monospace + whitespace context survives, then inline the
+      // computed styles from each source element onto its clone so
+      // rich-text paste targets (email, Word, Notion, etc.) render with
+      // the same visual styling without needing our stylesheet.
+      const doc = element.ownerDocument;
+      const view = doc.defaultView;
+      const fragment = range.cloneContents();
+      const container = doc.createElement('pre');
+      // Carry the editable's className onto the wrapper so consumers
+      // that scope styles by class (e.g. `.code-block`) keep matching
+      // when the snippet is pasted into a richer environment that loads
+      // the same stylesheet.
+      if (element.className) {
+        container.className = element.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) the
+      // editable 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 =
+        cac.nodeType === Node.ELEMENT_NODE ? (cac as Element) : 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 !== element && element.contains(anchor)) {
+        let current: Element | null = anchor;
+        let innermost: Element | null = null;
+        while (current && current !== element) {
+          const ancestorClone = current.cloneNode(false) as Element;
+          if (view) {
+            const computed = view.getComputedStyle(current);
+            let inline = ancestorClone.getAttribute('style') ?? '';
+            for (const prop of CLIPBOARD_STYLE_PROPS) {
+              const value = computed.getPropertyValue(prop);
+              if (value && value !== 'normal' && value !== 'none' && value !== 'auto') {
+                inline += `${prop}:${value};`;
+              }
+            }
+            if (inline) {
+              ancestorClone.setAttribute('style', inline);
+            }
+          }
+          ancestorClone.appendChild(rootContent);
+          rootContent = ancestorClone;
+          if (innermost === null) {
+            innermost = ancestorClone;
+          }
+          current = current.parentElement;
+        }
+        if (innermost) {
+          cloneStylingRoot = innermost;
+        }
+      }
+      container.appendChild(rootContent);
+      if (view) {
+        // 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 ↔ <pre> 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 = sourceWalker.nextNode() as Element | null;
+        let clone = cloneWalker.nextNode() as Element | null;
+        while (source && clone) {
+          if (source.tagName === clone.tagName) {
+            const computed = view.getComputedStyle(source);
+            let inline = clone.getAttribute('style') ?? '';
+            for (const prop of CLIPBOARD_STYLE_PROPS) {
+              const value = computed.getPropertyValue(prop);
+              if (value && value !== 'normal' && value !== 'none' && value !== 'auto') {
+                inline += `${prop}:${value};`;
+              }
+            }
+            if (inline) {
+              clone.setAttribute('style', inline);
+            }
+          }
+          source = sourceWalker.nextNode() as Element | null;
+          clone = cloneWalker.nextNode() as Element | null;
+        }
+        // Apply the editable's own typography to the wrapper so the
+        // pasted block matches the source font/size even when only a
+        // descendant span was selected.
+        const rootComputed = view.getComputedStyle(element);
+        let rootInline = CLIPBOARD_ROOT_STATIC_STYLES;
+        for (const prop of CLIPBOARD_ROOT_STYLE_PROPS) {
+          const value = rootComputed.getPropertyValue(prop);
+          if (value) {
+            rootInline += `${prop}:${value};`;
+          }
+        }
+        if (rootInline) {
+          container.setAttribute('style', rootInline);
+        }
+      }
+      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);
+        flushChanges(true);
+      }
+    };
+
+    // 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 =
+        startContainer.nodeType === Node.ELEMENT_NODE
+          ? (startContainer as Element)
+          : 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.
+      const lineText = toString(element).split('\n')[position.line] ?? '';
+      if (lineText.length < minColumn || !/^\s*$/.test(lineText.slice(0, minColumn))) {
+        return;
+      }
+      edit.move({ row: position.line, column: minColumn });
+    };
+
+    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) {
@@ -932,7 +1537,11 @@ export const useEditable = (
       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;
     };

From ff387f9a533256a8713df46f0b7b0cb63c7cf270 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Mon, 27 Apr 2026 21:48:23 -0400
Subject: [PATCH 38/45] Prettier

---
 docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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 c7947bb83..7e6202967 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
@@ -395,7 +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)).                            |
+| `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.
 

From a0f3663ed3dec3d64ab9b2da5dd545a6acbe8789 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Mon, 27 Apr 2026 23:16:59 -0400
Subject: [PATCH 39/45] Fix lint

Co-authored-by: Copilot <copilot@github.com>
---
 .../docs-infra/src/useCode/useEditable.ts     | 280 +++++++++---------
 1 file changed, 140 insertions(+), 140 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index f1eeb27d5..536da17b1 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -803,6 +803,146 @@ export const useEditable = (
       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 =
+        startContainer.nodeType === Node.ELEMENT_NODE
+          ? (startContainer as Element)
+          : 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.
+      const lineText = toString(element).split('\n')[position.line] ?? '';
+      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;
@@ -1359,146 +1499,6 @@ export const useEditable = (
       }
     };
 
-    // 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 =
-        startContainer.nodeType === Node.ELEMENT_NODE
-          ? (startContainer as Element)
-          : 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.
-      const lineText = toString(element).split('\n')[position.line] ?? '';
-      if (lineText.length < minColumn || !/^\s*$/.test(lineText.slice(0, minColumn))) {
-        return;
-      }
-      edit.move({ row: position.line, column: minColumn });
-    };
-
     const onMouseUp = () => {
       // First lift the caret out of any inter-line gap node so the
       // gutter check below can see a real line position.

From d36d97a0bd5f1fe2571c565f126e944841c16577 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 28 Apr 2026 00:30:10 -0400
Subject: [PATCH 40/45] Fix cursor edge case

Co-authored-by: Copilot <copilot@github.com>
---
 .../src/useCode/useEditable.browser.ts        | 215 ++++++++++++++++++
 .../docs-infra/src/useCode/useEditable.ts     | 101 +++++++-
 2 files changed, 305 insertions(+), 11 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.browser.ts b/packages/docs-infra/src/useCode/useEditable.browser.ts
index 50689ac40..f95357010 100644
--- a/packages/docs-infra/src/useCode/useEditable.browser.ts
+++ b/packages/docs-infra/src/useCode/useEditable.browser.ts
@@ -1315,3 +1315,218 @@ describe('useEditable – newline preservation', () => {
     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.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 536da17b1..8bd16275c 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -439,6 +439,17 @@ interface State {
   position: Position | null;
   /** setTimeout id used to debounce flushChanges() calls during key-repeat */
   repeatFlushId: ReturnType<typeof setTimeout> | 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 {
@@ -544,6 +555,7 @@ export const useEditable = (
     historyAt: -1,
     position: null,
     repeatFlushId: null,
+    skipNextRestore: false,
   }))[0];
 
   // MutationObserver is created once via useRef so it is never recreated on
@@ -659,7 +671,14 @@ export const useEditable = (
     // 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.
-    if (state.position && state.repeatFlushId === null) {
+    //
+    // 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);
@@ -948,13 +967,57 @@ export const useEditable = (
         return;
       }
       if (state.disconnected) {
-        // React Quirk: It's expected that we may lose events while disconnected, which is why
-        // we'd like to block some inputs if they're unusually fast. However, this always
-        // coincides with React not executing the update immediately and then getting stuck,
-        // which can be prevented by issuing a dummy state change.
-        event.preventDefault();
+        // 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([]);
-        return;
+        // Fall through and let this arrow event be handled normally
+        // with the restored caret position.
       }
 
       if (isUndoRedoKey(event)) {
@@ -1131,10 +1194,14 @@ export const useEditable = (
                 // it in the "between lines" area after the host expands.
                 event.preventDefault();
                 moveToLine(position.line - 1, column);
-                onBoundary?.();
+                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();
@@ -1145,8 +1212,12 @@ export const useEditable = (
               if (caretInLine && position.line < lines.length - 1) {
                 event.preventDefault();
                 moveToLine(position.line + 1, column);
-                onBoundary?.();
+                if (onBoundary) {
+                  state.skipNextRestore = true;
+                  onBoundary();
+                }
               } else if (onBoundary) {
+                state.skipNextRestore = true;
                 onBoundary();
               } else {
                 event.preventDefault();
@@ -1158,8 +1229,12 @@ export const useEditable = (
                 event.preventDefault();
                 const prevLine = lines[position.line - 1] ?? '';
                 edit.move({ row: position.line - 1, column: prevLine.length });
-                onBoundary?.();
+                if (onBoundary) {
+                  state.skipNextRestore = true;
+                  onBoundary();
+                }
               } else if (onBoundary) {
+                state.skipNextRestore = true;
                 onBoundary();
               } else {
                 event.preventDefault();
@@ -1187,8 +1262,12 @@ export const useEditable = (
               if (caretInLine && position.line < lines.length - 1) {
                 event.preventDefault();
                 moveToLine(position.line + 1, 0);
-                onBoundary?.();
+                if (onBoundary) {
+                  state.skipNextRestore = true;
+                  onBoundary();
+                }
               } else if (onBoundary) {
+                state.skipNextRestore = true;
                 onBoundary();
               } else {
                 event.preventDefault();

From 33be548fd5f4044b65c3863d0e2e3b52c264651a Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 28 Apr 2026 08:54:54 -0400
Subject: [PATCH 41/45] Fix backspace in collapsed

---
 .../src/useCode/useEditable.test.ts           | 71 +++++++++++++++++++
 .../docs-infra/src/useCode/useEditable.ts     | 29 +++++++-
 2 files changed, 98 insertions(+), 2 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.test.ts b/packages/docs-infra/src/useCode/useEditable.test.ts
index 2baf547ee..ebbea985e 100644
--- a/packages/docs-infra/src/useCode/useEditable.test.ts
+++ b/packages/docs-infra/src/useCode/useEditable.test.ts
@@ -1093,6 +1093,77 @@ describe('useEditable', () => {
       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');
+    });
   });
 
   // ---------------------------------------------------------------------------
diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 8bd16275c..f70569f29 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -1086,8 +1086,33 @@ export const useEditable = (
           edit.insert('', 0);
         } else {
           const position = getPosition(element);
-          const match = blanklineRe.exec(position.content);
-          edit.insert('', match ? -match[1].length : -1);
+          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."
+          const fullLine =
+            minColumn !== undefined && minColumn > 0
+              ? (toString(element).split('\n')[position.line] ?? '')
+              : '';
+          const collapseBlankIndent =
+            minColumn !== undefined &&
+            minColumn > 0 &&
+            position.line > 0 &&
+            position.content.length === minColumn &&
+            /^\s*$/.test(position.content) &&
+            fullLine.length === minColumn &&
+            /^\s*$/.test(fullLine);
+          if (collapseBlankIndent) {
+            edit.insert('', -(minColumn! + 1));
+          } else {
+            const match = blanklineRe.exec(position.content);
+            edit.insert('', match ? -match[1].length : -1);
+          }
         }
       } else if (opts!.indentation && event.key === 'Tab') {
         event.preventDefault();

From 9c7289be449ff774fb59f8fc881c489abb410fa5 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 28 Apr 2026 09:39:22 -0400
Subject: [PATCH 42/45] Performance improvements

Co-authored-by: Copilot <copilot@github.com>
---
 .../src/useCode/useEditable.test.ts           |  70 ++++++
 .../docs-infra/src/useCode/useEditable.ts     | 203 ++++++++++++++----
 2 files changed, 230 insertions(+), 43 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.test.ts b/packages/docs-infra/src/useCode/useEditable.test.ts
index ebbea985e..b4c213ad3 100644
--- a/packages/docs-infra/src/useCode/useEditable.test.ts
+++ b/packages/docs-infra/src/useCode/useEditable.test.ts
@@ -1484,6 +1484,39 @@ describe('useEditable', () => {
       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
@@ -1555,6 +1588,43 @@ describe('useEditable', () => {
       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'], {
diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index f70569f29..1f34ed793 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -209,6 +209,133 @@ const toString = (element: HTMLElement): string => {
   return content;
 };
 
+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.
+ */
+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.
+ */
+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;
+};
+
 const repairUnexpectedLineMerge = (
   newContent: string,
   previousContent: string | null,
@@ -627,16 +754,8 @@ export const useEditable = (
       const { current: element } = elementRef;
       if (element) {
         element.focus();
-        let position = 0;
-        if (typeof pos === 'number') {
-          position = pos;
-        } else {
-          const lines = toString(element).split('\n').slice(0, pos.row);
-          if (pos.row) {
-            position += lines.join('\n').length + 1;
-          }
-          position += pos.column;
-        }
+        const position =
+          typeof pos === 'number' ? pos : getOffsetAtLineColumn(element, pos.row, pos.column);
         const cursorRange = makeRange(element, position);
         adjustCursorAtNewlineBoundary(cursorRange);
         setCurrentRange(cursorRange);
@@ -955,7 +1074,9 @@ export const useEditable = (
       }
       // Only snap when the gutter is actually whitespace — otherwise the
       // line is shorter than `minColumn` and there's nowhere to snap to.
-      const lineText = toString(element).split('\n')[position.line] ?? '';
+      // `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;
       }
@@ -1095,18 +1216,18 @@ export const useEditable = (
           // 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."
-          const fullLine =
-            minColumn !== undefined && minColumn > 0
-              ? (toString(element).split('\n')[position.line] ?? '')
-              : '';
-          const collapseBlankIndent =
+          //
+          // 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) &&
-            fullLine.length === minColumn &&
-            /^\s*$/.test(fullLine);
+            /^\s*$/.test(position.content);
+          const fullLine = couldCollapse ? getLineInfo(element, position.line).currentLine : '';
+          const collapseBlankIndent =
+            couldCollapse && fullLine.length === minColumn! && /^\s*$/.test(fullLine);
           if (collapseBlankIndent) {
             edit.insert('', -(minColumn! + 1));
           } else {
@@ -1157,12 +1278,15 @@ export const useEditable = (
           const { minColumn, minRow, maxRow, onBoundary, caretSelector } = boundsRef.current;
           const position = getPosition(element);
           const column = position.content.length;
-          const allLines = toString(element).split('\n');
-          // `toString` guarantees a trailing `\n`, so the split produces a
-          // phantom empty entry at the end. Drop it so `lines.length - 1` is
-          // the index of the real last line.
-          const lines = allLines.length > 1 ? allLines.slice(0, -1) : allLines;
-          const lineText = lines[position.line] ?? '';
+          // 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 &&
@@ -1194,9 +1318,10 @@ export const useEditable = (
           // 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).
-          const moveToLine = (targetRow: number, desiredColumn: number) => {
-            const targetLine = lines[targetRow] ?? '';
+          // 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 &&
@@ -1218,7 +1343,7 @@ export const useEditable = (
                 // (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, column);
+                moveToLine(position.line - 1, prevLine, column);
                 if (onBoundary) {
                   state.skipNextRestore = true;
                   onBoundary();
@@ -1234,9 +1359,9 @@ export const useEditable = (
             }
           } else if (event.key === 'ArrowDown') {
             if (atVisibleEnd) {
-              if (caretInLine && position.line < lines.length - 1) {
+              if (caretInLine && hasNextLine) {
                 event.preventDefault();
-                moveToLine(position.line + 1, column);
+                moveToLine(position.line + 1, nextLine, column);
                 if (onBoundary) {
                   state.skipNextRestore = true;
                   onBoundary();
@@ -1252,7 +1377,6 @@ export const useEditable = (
             if (atVisibleStart && atLineStart) {
               if (caretInLine && position.line > 0) {
                 event.preventDefault();
-                const prevLine = lines[position.line - 1] ?? '';
                 edit.move({ row: position.line - 1, column: prevLine.length });
                 if (onBoundary) {
                   state.skipNextRestore = true;
@@ -1271,7 +1395,6 @@ export const useEditable = (
               position.line > 0
             ) {
               event.preventDefault();
-              const prevLine = lines[position.line - 1] ?? '';
               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
@@ -1279,14 +1402,13 @@ export const useEditable = (
               // a no-op. Jump synchronously to the end of the previous
               // line instead.
               event.preventDefault();
-              const prevLine = lines[position.line - 1] ?? '';
               edit.move({ row: position.line - 1, column: prevLine.length });
             }
           } else if (event.key === 'ArrowRight') {
             if (atVisibleEnd && atLineEnd) {
-              if (caretInLine && position.line < lines.length - 1) {
+              if (caretInLine && hasNextLine) {
                 event.preventDefault();
-                moveToLine(position.line + 1, 0);
+                moveToLine(position.line + 1, nextLine, 0);
                 if (onBoundary) {
                   state.skipNextRestore = true;
                   onBoundary();
@@ -1297,12 +1419,7 @@ export const useEditable = (
               } else {
                 event.preventDefault();
               }
-            } else if (
-              minColumn !== undefined &&
-              column === lineText.length &&
-              position.line < lines.length - 1
-            ) {
-              const nextLine = lines[position.line + 1] ?? '';
+            } else if (minColumn !== undefined && column === lineText.length && hasNextLine) {
               const nextIsIndented =
                 nextLine.length >= minColumn && /^\s*$/.test(nextLine.slice(0, minColumn));
               if (nextIsIndented) {
@@ -1314,7 +1431,7 @@ export const useEditable = (
                 event.preventDefault();
                 edit.move({ row: position.line + 1, column: 0 });
               }
-            } else if (caretInLine && atLineEnd && position.line < lines.length - 1) {
+            } else if (caretInLine && atLineEnd && hasNextLine) {
               event.preventDefault();
               edit.move({ row: position.line + 1, column: 0 });
             }

From 1446d2161e69c2111228232acddda90e224e243f Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 28 Apr 2026 10:52:22 -0400
Subject: [PATCH 43/45] Improve TS support

Co-authored-by: Copilot <copilot@github.com>
---
 .../docs-infra/src/useCode/useEditable.ts     | 185 +++++++++++-------
 1 file changed, 119 insertions(+), 66 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 1f34ed793..5ffc9932e 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -63,14 +63,42 @@ const observerSettings = {
   subtree: true,
 };
 
-const getCurrentRange = () => window.getSelection()!.getRangeAt(0)!;
+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.
+    throw new Error('useEditable: expected an active selection');
+  }
+  return selection.getRangeAt(0);
+};
 
 const setCurrentRange = (range: Range) => {
-  const selection = window.getSelection()!;
+  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.
+ */
+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`.
+ */
+const nextElement = (walker: TreeWalker): Element | null => asElement(walker.nextNode());
+
 const isUndoRedoKey = (event: KeyboardEvent): boolean =>
   (event.metaKey || event.ctrlKey) && !event.altKey && event.code === 'KeyZ';
 
@@ -174,7 +202,8 @@ const extractLeadingPerLine = (text: string, firstLineCount: number, restCount:
 // and is consumed across consecutive text nodes so that indent nested
 // inside multiple wrapper spans is still removed correctly.
 const stripLeadingPerLineDom = (root: Node, firstLineCount: number, restCount: number): void => {
-  const walker = root.ownerDocument!.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  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()) {
@@ -255,7 +284,7 @@ const getLineInfo = (element: HTMLElement, lineIndex: number): LineInfo => {
   let hasNextLine = false;
   let line = 0;
   for (let node = walker.nextNode(); node; node = walker.nextNode()) {
-    const text = node.textContent!;
+    const text = node.textContent ?? '';
     let segStart = 0;
     for (let i = 0; i < text.length; i += 1) {
       if (text[i] !== '\n') {
@@ -322,7 +351,7 @@ const getOffsetAtLineColumn = (element: HTMLElement, row: number, column: number
   let line = 0;
   const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
   for (let node = walker.nextNode(); node; node = walker.nextNode()) {
-    const text = node.textContent!;
+    const text = node.textContent ?? '';
     for (let i = 0; i < text.length; i += 1) {
       offset += 1;
       if (text[i] === '\n') {
@@ -387,7 +416,8 @@ const repairUnexpectedLineMerge = (
 };
 
 const setStart = (range: Range, node: Node, offset: number) => {
-  if (offset < node.textContent!.length) {
+  const length = (node.textContent ?? '').length;
+  if (offset < length) {
     range.setStart(node, offset);
   } else {
     range.setStartAfter(node);
@@ -395,7 +425,8 @@ const setStart = (range: Range, node: Node, offset: number) => {
 };
 
 const setEnd = (range: Range, node: Node, offset: number) => {
-  if (offset < node.textContent!.length) {
+  const length = (node.textContent ?? '').length;
+  if (offset < length) {
     range.setEnd(node, offset);
   } else {
     range.setEndAfter(node);
@@ -416,7 +447,7 @@ const getPosition = (element: HTMLElement): Position => {
     let lineContent = '';
 
     for (let node = walker.nextNode(); node; node = walker.nextNode()) {
-      const text = node.textContent!;
+      const text = node.textContent ?? '';
       const isTarget = node === range.startContainer;
       const upTo = isTarget ? range.startOffset : text.length;
 
@@ -468,7 +499,7 @@ const makeRange = (element: HTMLElement, start: number, end?: number): Range =>
   let position = start;
 
   for (let node = walker.nextNode(); node; node = walker.nextNode()) {
-    const length = node.textContent!.length;
+    const length = (node.textContent ?? '').length;
     if (current + length >= position) {
       const offset = position - current;
       if (position === start) {
@@ -527,12 +558,13 @@ const adjustCursorAtNewlineBoundary = (range: Range): void => {
   }
 
   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 === startContainer.textContent!.length &&
-    startContainer.textContent!.endsWith('\n')
+    startOffset === startText.length &&
+    startText.endsWith('\n')
   ) {
     const next = nextTextNode(startContainer);
     if (next) {
@@ -546,7 +578,8 @@ const adjustCursorAtNewlineBoundary = (range: Range): void => {
   // 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];
-    if (prevChild?.nodeType === Node.TEXT_NODE && prevChild.textContent!.endsWith('\n')) {
+    const prevText = prevChild?.textContent ?? '';
+    if (prevChild?.nodeType === Node.TEXT_NODE && prevText.endsWith('\n')) {
       const next = nextTextNode(prevChild);
       if (next) {
         range.setStart(next, 0);
@@ -668,9 +701,10 @@ export const useEditable = (
   onChange: (text: string, position: Position) => void,
   opts?: Options,
 ): Edit => {
-  if (!opts) {
-    opts = {};
-  }
+  // 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 = opts ?? {};
 
   const unblock = React.useState([])[1];
   const state = React.useState<State>(() => ({
@@ -703,17 +737,17 @@ export const useEditable = (
   // 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: opts.minColumn,
-    minRow: opts.minRow,
-    maxRow: opts.maxRow,
-    onBoundary: opts.onBoundary,
-    caretSelector: opts.caretSelector,
+    minColumn: config.minColumn,
+    minRow: config.minRow,
+    maxRow: config.maxRow,
+    onBoundary: config.onBoundary,
+    caretSelector: config.caretSelector,
   });
-  boundsRef.current.minColumn = opts.minColumn;
-  boundsRef.current.minRow = opts.minRow;
-  boundsRef.current.maxRow = opts.maxRow;
-  boundsRef.current.onBoundary = opts.onBoundary;
-  boundsRef.current.caretSelector = opts.caretSelector;
+  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;
 
   // useMemo with [] is a performance hint, not a semantic guarantee — React 19
   // may discard the cache and recreate the object. useState with a lazy
@@ -762,10 +796,16 @@ export const useEditable = (
       }
     },
     getState() {
-      const { current: element } = elementRef;
-      const text = toString(element!);
-      const position = getPosition(element!);
-      return { text, position };
+      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) };
     },
   }));
 
@@ -779,7 +819,7 @@ export const useEditable = (
 
     state.onChange = onChange;
 
-    if (!elementRef.current || opts!.disabled) {
+    if (!elementRef.current || config.disabled) {
       return undefined;
     }
 
@@ -814,13 +854,16 @@ export const useEditable = (
       return undefined;
     }
 
-    if (!elementRef.current || opts!.disabled) {
+    if (!elementRef.current || config.disabled) {
       state.history.length = 0;
       state.historyAt = -1;
       return undefined;
     }
 
-    const element = elementRef.current!;
+    const element = elementRef.current;
+    if (!element) {
+      return undefined;
+    }
     if (state.position) {
       element.focus();
       const { position, extent } = state.position;
@@ -844,13 +887,13 @@ export const useEditable = (
       element.style.whiteSpace = 'pre-wrap';
     }
 
-    if (opts!.indentation) {
-      const tabSizeValue = `${opts!.indentation}`;
+    if (config.indentation) {
+      const tabSizeValue = `${config.indentation}`;
       element.style.setProperty('-moz-tab-size', tabSizeValue);
       element.style.tabSize = tabSizeValue;
     }
 
-    const indentPattern = `${' '.repeat(opts!.indentation || 0)}`;
+    const indentPattern = `${' '.repeat(config.indentation || 0)}`;
     const indentRe = new RegExp(`^(?:${indentPattern})`);
     const blanklineRe = new RegExp(`^(?:${indentPattern})*(${indentPattern})$`);
 
@@ -864,7 +907,7 @@ export const useEditable = (
       // 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) {
+      if (!elementRef.current || (window.getSelection()?.rangeCount ?? 0) === 0) {
         return null;
       }
 
@@ -915,7 +958,10 @@ export const useEditable = (
         );
         state.position = position;
         while (state.queue.length > 0) {
-          const mutation = state.queue.pop()!;
+          const mutation = state.queue.pop();
+          if (!mutation) {
+            break;
+          }
           if (mutation.oldValue !== null) {
             mutation.target.textContent = mutation.oldValue;
           }
@@ -966,10 +1012,7 @@ export const useEditable = (
         return false;
       }
       const startContainer = snapRange.startContainer;
-      const startElement =
-        startContainer.nodeType === Node.ELEMENT_NODE
-          ? (startContainer as Element)
-          : startContainer.parentElement;
+      const startElement = asElement(startContainer) ?? startContainer.parentElement;
       // Caret is already inside a `.line` (or equivalent) — no snap needed.
       if (startElement?.closest(caretSelector)) {
         return false;
@@ -1198,7 +1241,7 @@ export const useEditable = (
         // Route plain text input through the controlled insert path instead.
         event.preventDefault();
         edit.insert(event.key);
-      } else if ((!hasPlaintextSupport || opts!.indentation) && event.key === 'Backspace') {
+      } 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();
@@ -1225,17 +1268,20 @@ export const useEditable = (
             position.line > 0 &&
             position.content.length === minColumn &&
             /^\s*$/.test(position.content);
-          const fullLine = couldCollapse ? getLineInfo(element, position.line).currentLine : '';
-          const collapseBlankIndent =
-            couldCollapse && fullLine.length === minColumn! && /^\s*$/.test(fullLine);
-          if (collapseBlankIndent) {
-            edit.insert('', -(minColumn! + 1));
-          } else {
-            const match = blanklineRe.exec(position.content);
-            edit.insert('', match ? -match[1].length : -1);
+          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 (opts!.indentation && event.key === 'Tab') {
+      } else if (config.indentation && event.key === 'Tab') {
         event.preventDefault();
         const position = getPosition(element);
         const start = position.position - position.content.length;
@@ -1245,7 +1291,7 @@ export const useEditable = (
             position.content.replace(indentRe, '') +
             content.slice(start + position.content.length)
           : content.slice(0, start) +
-            (opts!.indentation ? ' '.repeat(opts!.indentation) : '\t') +
+            (config.indentation ? ' '.repeat(config.indentation) : '\t') +
             content.slice(start);
         edit.update(newContent);
       } else if (
@@ -1306,10 +1352,7 @@ export const useEditable = (
             caretSelector !== undefined &&
             (() => {
               const startContainer = range.startContainer;
-              const startElement =
-                startContainer.nodeType === Node.ELEMENT_NODE
-                  ? (startContainer as Element)
-                  : startContainer.parentElement;
+              const startElement = asElement(startContainer) ?? startContainer.parentElement;
               return !!startElement?.closest(caretSelector);
             })();
 
@@ -1532,14 +1575,18 @@ export const useEditable = (
 
     const onSelect = (event: Event) => {
       // Chrome Quirk: The contenteditable may lose its selection immediately on first focus
-      state.position =
-        window.getSelection()!.rangeCount && event.target === element ? getPosition(element) : null;
+      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(event.clipboardData!.getData('text/plain'));
+      edit.insert(clipboard.getData('text/plain'));
       flushChanges(true);
     };
 
@@ -1615,8 +1662,7 @@ export const useEditable = (
       // editable 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 =
-        cac.nodeType === Node.ELEMENT_NODE ? (cac as Element) : cac.parentElement;
+      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
@@ -1626,7 +1672,14 @@ export const useEditable = (
         let current: Element | null = anchor;
         let innermost: Element | null = null;
         while (current && current !== element) {
-          const ancestorClone = current.cloneNode(false) as Element;
+          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;
+          }
+          const ancestorClone = cloned;
           if (view) {
             const computed = view.getComputedStyle(current);
             let inline = ancestorClone.getAttribute('style') ?? '';
@@ -1667,8 +1720,8 @@ export const useEditable = (
           },
         );
         const cloneWalker = doc.createTreeWalker(cloneStylingRoot, NodeFilter.SHOW_ELEMENT);
-        let source = sourceWalker.nextNode() as Element | null;
-        let clone = cloneWalker.nextNode() as Element | null;
+        let source = nextElement(sourceWalker);
+        let clone = nextElement(cloneWalker);
         while (source && clone) {
           if (source.tagName === clone.tagName) {
             const computed = view.getComputedStyle(source);
@@ -1683,8 +1736,8 @@ export const useEditable = (
               clone.setAttribute('style', inline);
             }
           }
-          source = sourceWalker.nextNode() as Element | null;
-          clone = cloneWalker.nextNode() as Element | null;
+          source = nextElement(sourceWalker);
+          clone = nextElement(cloneWalker);
         }
         // Apply the editable's own typography to the wrapper so the
         // pasted block matches the source font/size even when only a

From d08a735832b4baf02f131a78a339d09d02539868 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 28 Apr 2026 11:24:15 -0400
Subject: [PATCH 44/45] Refactor

Co-authored-by: Copilot <copilot@github.com>
---
 .../src/useCode/cloneRangeWithInlineStyles.ts | 177 +++++
 .../src/useCode/stripLeadingPerLine.ts        | 116 +++
 .../docs-infra/src/useCode/useEditable.ts     | 684 ++----------------
 .../src/useCode/useEditableUtils.ts           | 430 +++++++++++
 4 files changed, 769 insertions(+), 638 deletions(-)
 create mode 100644 packages/docs-infra/src/useCode/cloneRangeWithInlineStyles.ts
 create mode 100644 packages/docs-infra/src/useCode/stripLeadingPerLine.ts
 create mode 100644 packages/docs-infra/src/useCode/useEditableUtils.ts

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/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 5ffc9932e..3e514b69a 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -47,12 +47,29 @@ SOFTWARE.
 
 import * as React from 'react';
 
-export interface Position {
-  position: number;
-  extent: number;
-  content: string;
-  line: number;
-}
+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];
 
@@ -63,58 +80,10 @@ const observerSettings = {
   subtree: true,
 };
 
-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.
-    throw new Error('useEditable: expected an active selection');
-  }
-  return selection.getRangeAt(0);
-};
-
-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.
- */
-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`.
- */
-const nextElement = (walker: TreeWalker): Element | null => asElement(walker.nextNode());
-
-const isUndoRedoKey = (event: KeyboardEvent): boolean =>
-  (event.metaKey || event.ctrlKey) && !event.altKey && event.code === 'KeyZ';
-
-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)
-  );
-};
-
-// Computed-style properties inlined onto each element in the copied HTML
-// fragment so external paste targets render with the same syntax
+// 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_STYLE_PROPS = [
+const CLIPBOARD_ELEMENT_STYLE_PROPS = [
   'color',
   'background-color',
   'font-weight',
@@ -132,463 +101,13 @@ const CLIPBOARD_ROOT_STYLE_PROPS = [
   '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
+
+// 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;';
 
-// Strip leading whitespace characters per line of a plain-text string,
-// used to drop the clipped indent gutter (`minColumn`) from clipboard
-// payloads so the pasted snippet matches what the user sees.
-//
-// `firstLineCount` is the budget for the first line — typically
-// `max(0, minColumn - startColumn)` so that a selection starting
-// mid-gutter only loses the gutter portion still inside the selection.
-// `restCount` is the budget for every line after a `\n`, normally the
-// full `minColumn`.
-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`. Used by `cut` to re-insert the gutter
-// whitespace at the selection location so cut is lossless: the
-// clipboard payload omits the clipped indent gutter, but the underlying
-// document keeps it.
-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 version 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 that indent nested
-// inside multiple wrapper spans is still removed correctly.
-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;
-  }
-};
-
-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;
-};
-
-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.
- */
-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.
- */
-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;
-};
-
-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);
-  }
-};
-
-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 };
-};
-
-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.
- */
-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);
-      }
-    }
-  }
-};
-
 interface State {
   disconnected: boolean;
   onChange(text: string, position: Position): void;
@@ -1625,139 +1144,28 @@ export const useEditable = (
         const startColumn = beforeText.length - (lastNewline + 1);
         firstLineStrip = Math.max(0, minColumn - startColumn);
       }
-      let plainText = range.toString();
-      if (restStrip > 0) {
-        // 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.
-        plainText = stripLeadingPerLine(plainText, firstLineStrip, restStrip);
-      }
+
+      // 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);
-      // Re-serialize the HTML ourselves since `preventDefault()` skipped
-      // the browser's default text/html write. Wrap in a `<pre>` so the
-      // monospace + whitespace context survives, then inline the
-      // computed styles from each source element onto its clone so
-      // rich-text paste targets (email, Word, Notion, etc.) render with
-      // the same visual styling without needing our stylesheet.
-      const doc = element.ownerDocument;
-      const view = doc.defaultView;
-      const fragment = range.cloneContents();
-      const container = doc.createElement('pre');
-      // Carry the editable's className onto the wrapper so consumers
-      // that scope styles by class (e.g. `.code-block`) keep matching
-      // when the snippet is pasted into a richer environment that loads
-      // the same stylesheet.
-      if (element.className) {
-        container.className = element.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) the
-      // editable 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 !== element && element.contains(anchor)) {
-        let current: Element | null = anchor;
-        let innermost: Element | null = null;
-        while (current && current !== element) {
-          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;
-          }
-          const ancestorClone = cloned;
-          if (view) {
-            const computed = view.getComputedStyle(current);
-            let inline = ancestorClone.getAttribute('style') ?? '';
-            for (const prop of CLIPBOARD_STYLE_PROPS) {
-              const value = computed.getPropertyValue(prop);
-              if (value && value !== 'normal' && value !== 'none' && value !== 'auto') {
-                inline += `${prop}:${value};`;
-              }
-            }
-            if (inline) {
-              ancestorClone.setAttribute('style', inline);
-            }
-          }
-          ancestorClone.appendChild(rootContent);
-          rootContent = ancestorClone;
-          if (innermost === null) {
-            innermost = ancestorClone;
-          }
-          current = current.parentElement;
-        }
-        if (innermost) {
-          cloneStylingRoot = innermost;
-        }
-      }
-      container.appendChild(rootContent);
-      if (view) {
-        // 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 ↔ <pre> 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) {
-            const computed = view.getComputedStyle(source);
-            let inline = clone.getAttribute('style') ?? '';
-            for (const prop of CLIPBOARD_STYLE_PROPS) {
-              const value = computed.getPropertyValue(prop);
-              if (value && value !== 'normal' && value !== 'none' && value !== 'auto') {
-                inline += `${prop}:${value};`;
-              }
-            }
-            if (inline) {
-              clone.setAttribute('style', inline);
-            }
-          }
-          source = nextElement(sourceWalker);
-          clone = nextElement(cloneWalker);
-        }
-        // Apply the editable's own typography to the wrapper so the
-        // pasted block matches the source font/size even when only a
-        // descendant span was selected.
-        const rootComputed = view.getComputedStyle(element);
-        let rootInline = CLIPBOARD_ROOT_STATIC_STYLES;
-        for (const prop of CLIPBOARD_ROOT_STYLE_PROPS) {
-          const value = rootComputed.getPropertyValue(prop);
-          if (value) {
-            rootInline += `${prop}:${value};`;
-          }
-        }
-        if (rootInline) {
-          container.setAttribute('style', rootInline);
-        }
-      }
+
+      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
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);
+      }
+    }
+  }
+};

From 43c0650d56b4c3543a2d4d15784e7d7dc41d677c Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 28 Apr 2026 11:39:55 -0400
Subject: [PATCH 45/45] Update changes list

---
 .../docs-infra/src/useCode/useEditable.ts     | 29 ++++++++-----------
 1 file changed, 12 insertions(+), 17 deletions(-)

diff --git a/packages/docs-infra/src/useCode/useEditable.ts b/packages/docs-infra/src/useCode/useEditable.ts
index 3e514b69a..61f6f669f 100644
--- a/packages/docs-infra/src/useCode/useEditable.ts
+++ b/packages/docs-infra/src/useCode/useEditable.ts
@@ -27,23 +27,18 @@ SOFTWARE.
 */
 
 // Forked from https://github.com/FormidableLabs/use-editable
-// Changes:
-// - Fix linting and formatting
-// - Add Tests
-// - Replace manual queue-based DFS in makeRange with TreeWalker for better performance
-// - Replace Range.toString() in getPosition with a TreeWalker character count to avoid O(N) string allocation
-// - Deduplicate toString() calls via trackState return value
-// - Fix Firefox rapid-typing line-loss bug: preserve pre-edit pendingContent across keydowns until flush
-// - Refresh pendingContent baseline after controlled edits so native input following Enter/Tab/Backspace can still be repaired
-// - Record repaired (not raw) content into the undo stack so Firefox merge intermediates don't pollute history
-// - Debounce repeat-key flushes so highlights only re-render once the user pauses typing
-// - Fix undo-to-initial-state bug: allow trackState to record before the first flushChanges
-// - Fix undo-after-rapid-Enter bug: bypass 500ms dedup on keyup for structural edits (Enter)
-// - Fix React 19 compatibility: useState lazy init for edit, useRef for MutationObserver, window SSR guard
-// - Add `minColumn` option: skip clipped indent gutter via horizontal arrow navigation
-// - Add `minRow`/`maxRow`/`onBoundary` options: detect arrow-key navigation past the visible region; allow native movement when `onBoundary` is provided so hosts can expand collapsed regions without losing focus
-// - Add `caretSelector` option: when the caret is inside a matching element, `ArrowLeft` at column 0 and `ArrowRight` at the end of a line jump synchronously to the adjacent line so non-selectable gap text nodes (e.g. newlines between `.line` spans) don't trap the caret. Vertical navigation is left to the browser to preserve wrapped-line behavior in `pre-wrap` layouts
-// - Override `copy`/`cut` to write `Range.toString()` for `text/plain` (avoiding duplicated newlines from block-level line wrappers like `display: block` `.line` spans separated by literal `\n` text nodes) and a `<pre>`-wrapped clone with computed styles inlined for `text/html` so pasting into rich-text targets (email, Word, Notion, etc.) keeps syntax highlighting without depending on the host stylesheet. When `minColumn` is set, also strips up to that many leading whitespace characters per line from both payloads so the clipped indent gutter doesn't leak into the clipboard
+// 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';