[docs-infra] Improve Live Editing

.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

AGENTS.md

@@ -22,6 +22,8 @@ Always reference these instructions first and fallback to search or bash command
 - **Formatting**: `pnpm prettier` -- always run before pushing code.
 - **Run tests**: `pnpm test --run` takes 5-10 seconds. **NEVER CANCEL**. Set timeout to 30+ minutes.
 - **Run specific tests**: `pnpm test --run loadServerSource` or `pnpm test --run integration.test.ts` for targeted testing
+- **Run browser tests**: `pnpm test:browser --run` -- requires podman or docker. Starts a containerized Playwright server and runs browser tests against it.
+- **Run browser tests in CI**: In a `mcr.microsoft.com/playwright` container image, run `pnpm test:browser:unconfined` directly — no container engine needed. Only use in a CI environment.
 - **ALWAYS use `--run` flag** to avoid watch mode when running tests programmatically
 - **Do NOT use `--`** in test commands (e.g., avoid `pnpm test -- --run`)
 - **Use VS Code Vitest extension** whenever possible for interactive test development and debugging

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);

docs/app/bench/docs-infra/components/code-controller-context/demos/code/page.tsx

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import { createParseSource } from '@mui/internal-docs-infra/pipeline/parseSource';
+import { CodeHighlighter } from '@mui/internal-docs-infra/CodeHighlighter';
+import { CodeProvider } from '@mui/internal-docs-infra/CodeProvider';
+import { CodeController } from '../../../../../../docs-infra/components/code-controller-context/demos/code-editor/CodeController';
+import { CodeEditorContent } from '../../../../../../docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent';
+
+import code from '../../../code-highlighter/snippets/large/snippet';
+
+const sourceParser = createParseSource();
+
+export default function Page() {
+  return (
+    // @focus-start
+    <CodeProvider>
+      <CodeController>
+        <CodeHighlighter
+          Content={CodeEditorContent}
+          controlled
+          sourceParser={sourceParser}
+          fileName="large-file.js"
+        >
+          {code}
+        </CodeHighlighter>
+      </CodeController>
+    </CodeProvider>
+    // @focus-end
+  );
+}

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/)

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)

docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.tsx

@@ -1,7 +1,6 @@
 'use client';
 
 import * as React from 'react';
-import { useEditable } from 'use-editable';
 import type { ContentProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
 import { useCode } from '@mui/internal-docs-infra/useCode';
 import { LabeledSwitch } from '@/components/LabeledSwitch';
@@ -10,9 +9,7 @@ import styles from './CodeEditorContent.module.css';
 import '../../../code-highlighter/demos/syntax.css';
 
 export function CodeEditorContent(props: ContentProps<object>) {
-  // @focus-start @padding 1
-  const preRef = React.useRef<HTMLPreElement | null>(null);
-  const code = useCode(props, { preClassName: styles.codeBlock, preRef });
+  const code = useCode(props, { preClassName: styles.codeBlock });
 
   const hasJsTransform = code.availableTransforms.includes('js');
   const isJsSelected = code.selectedTransform === 'js';
@@ -24,15 +21,6 @@ export function CodeEditorContent(props: ContentProps<object>) {
     [code],
   );
 
-  const onInput = React.useCallback(
-    (text: string) => {
-      code.setSource?.(text);
-    },
-    [code],
-  );
-
-  useEditable(preRef, onInput, { indentation: 2 });
-
   return (
     <div className={styles.container}>
       <div className={styles.header}>

docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLive.tsx

@@ -1,15 +1,12 @@
 import * as React from 'react';
 import { CodeProvider } from '@mui/internal-docs-infra/CodeProvider';
-import { DemoController } from './DemoController';
 import { DemoCheckboxBasic } from './demo-basic';
 
 export function DemoLive() {
   return (
     // @focus-start
     <CodeProvider>
-      <DemoController>
-        <DemoCheckboxBasic />
-      </DemoController>
+      <DemoCheckboxBasic />
     </CodeProvider>
     // @focus-end
   );

docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.module.css

@@ -85,3 +85,8 @@
 .codeBlock:focus-visible {
   outline: none;
 }
+
+.codeBlock :global(.frame)[data-frame-type='highlighted'] {
+  background: #ebe4ff;
+  border-radius: 8px;
+}

docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.tsx

@@ -1,7 +1,6 @@
 'use client';
 
 import * as React from 'react';
-import { useEditable } from 'use-editable';
 import type { ContentProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
 import { useDemo } from '@mui/internal-docs-infra/useDemo';
 import { LabeledSwitch } from '@/components/LabeledSwitch';
@@ -16,9 +15,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function DemoLiveContent(props: ContentProps<object>) {
-  // @focus-start @padding 1
-  const preRef = React.useRef<HTMLPreElement | null>(null);
-  const demo = useDemo(props, { preClassName: styles.codeBlock, preRef });
+  const demo = useDemo(props, { preClassName: styles.codeBlock });
 
   const hasJsTransform = demo.availableTransforms.includes('js');
   const isJsSelected = demo.selectedTransform === 'js';
@@ -41,14 +38,6 @@ export function DemoLiveContent(props: ContentProps<object>) {
     [demo.variants],
   );
 
-  const onChange = React.useCallback(
-    (text: string) => {
-      demo.setSource?.(text);
-    },
-    [demo],
-  );
-  useEditable(preRef, onChange, { indentation: 2, disabled: !demo.setSource });
-
   return (
     <div className={styles.container}>
       <div className={styles.demoSection}>{demo.component}</div>

docs/app/docs-infra/components/code-controller-context/demos/demo-live/createDemoClient.ts

@@ -1,12 +1,13 @@
 '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.
  * @param url Depends on `import.meta.url` to determine the source file location.
  * @param meta Additional meta and modules for the demo client.
  */
 export const createDemoClient = createDemoClientFactory({
-  live: true,
+  DemoController,
 });

docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileContent.tsx

@@ -1,7 +1,6 @@
 'use client';
 
 import * as React from 'react';
-import { useEditable } from 'use-editable';
 import type { ContentProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
 import { useCode } from '@mui/internal-docs-infra/useCode';
 import { Tabs } from '@/components/Tabs';
@@ -10,9 +9,7 @@ import styles from '../code-editor/CodeEditorContent.module.css';
 import '../../../code-highlighter/demos/syntax.css';
 
 export function MultiFileContent(props: ContentProps<object>) {
-  // @focus-start @padding 1
-  const preRef = React.useRef<HTMLPreElement | null>(null);
-  const code = useCode(props, { preClassName: styles.codeBlock, preRef });
+  const code = useCode(props, { preClassName: styles.codeBlock });
 
   const tabs = React.useMemo(() => {
     return code.files.map(({ name }) => ({
@@ -21,15 +18,6 @@ export function MultiFileContent(props: ContentProps<object>) {
     }));
   }, [code.files]);
 
-  const onInput = React.useCallback(
-    (text: string) => {
-      code.setSource?.(text);
-    },
-    [code],
-  );
-
-  useEditable(preRef, onInput, { indentation: 2 });
-
   return (
     <div className={styles.container}>
       <div className={styles.header}>

docs/app/docs-infra/components/code-controller-context/page.mdx

@@ -137,22 +137,10 @@ The [`useCode`](../../hooks/use-code/page.mdx) hook automatically integrates wit
 ```tsx
 'use client';
 
-import { useEditable } from 'use-editable';
 import { useCode } from '@mui/internal-docs-infra/useCode';
 
 function EditorContent(props) {
-  const preRef = React.useRef<HTMLPreElement | null>(null);
-  const code = useCode(props, { preRef });
-
-  // code.setSource updates the controller automatically
-  const onInput = React.useCallback(
-    (text: string) => {
-      code.setSource?.(text);
-    },
-    [code],
-  );
-
-  useEditable(preRef, onInput, { indentation: 2 });
+  const code = useCode(props);
 
   return (
     <div>
@@ -165,7 +153,8 @@ function EditorContent(props) {
 
 ## Working with useDemo Hook
 
-The [`useDemo`](../../hooks/use-demo/page.mdx) hook provides additional functionality for live component demos:
+The [`useDemo`](../../hooks/use-demo/page.mdx) hook provides additional functionality for live component demos.
+Editing is handled automatically by the `Pre` component — just render `demo.selectedFile`:
 
 ```tsx
 'use client';
@@ -175,19 +164,12 @@ import { useDemo } from '@mui/internal-docs-infra/useDemo';
 function DemoContent(props) {
   const demo = useDemo(props);
 
-  const onInput = React.useCallback(
-    (text: string) => {
-      demo.setSource?.(text);
-    },
-    [demo],
-  );
-
   return (
     <div>
       {/* Live component preview */}
       <div>{demo.component}</div>
 
-      {/* Editable source code */}
+      {/* Editable source code — editing is handled automatically */}
       <div>
         <select value={demo.selectedVariant} onChange={(e) => demo.selectVariant(e.target.value)}>
           {demo.variants.map((variant) => (
@@ -197,7 +179,7 @@ function DemoContent(props) {
           ))}
         </select>
 
-        <textarea value={demo.selectedFile} onChange={(e) => onInput(e.target.value)} />
+        {demo.selectedFile}
       </div>
     </div>
   );
@@ -210,22 +192,18 @@ The CodeController provides a simple state management pattern:
 
 1. **Initial State**: Controller starts with empty state (`code: undefined`)
 2. **Code Loading**: [`CodeHighlighter`](../code-highlighter/page.mdx) loads initial code from file or props
-3. **User Interaction**: When users edit code, `setSource` calls `controlledSetCode`
+3. **User Interaction**: When users edit code in the `Pre` component, `setSource` updates the controller
 4. **State Update**: Controller state updates and all connected components re-render
 5. **Live Preview**: For demo controllers, components are regenerated from updated code
 
 ```tsx
-// Flow: User Edit → setSource → controlledSetCode → Context Update → Re-render
+// Flow: User Edit (in Pre) → setSource → controlledSetCode → Context Update → Re-render
 
 function EditorContent(props) {
   const code = useCode(props); // Connects to controller context
 
-  const onEdit = (newSource) => {
-    code.setSource(newSource); // This updates the controller context
-  };
-
-  // code.selectedFile reflects the current controller state
-  return <textarea value={code.selectedFile} onChange={onEdit} />;
+  // code.selectedFile is a <Pre> component that handles editing automatically
+  return <div>{code.selectedFile}</div>;
 }
 ```
 
@@ -282,14 +260,15 @@ 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.
  * @param url Depends on `import.meta.url` to determine the source file location.
  * @param meta Additional meta and modules for the demo client.
  */
 export const createDemoClient = createDemoClientFactory({
-  live: true,
+  DemoController,
 });
 ```
 
@@ -318,6 +297,10 @@ The `ClientProvider` ensures that:
 
 This is only needed for demos that render live components from editable code, not for simple code editor scenarios.
 
+## Benchmarking
+
+For performance benchmarks of the `CodeControllerContext` component, see the [Benchmarking Code Controller Context](./bench/page.mdx) page.
+
 ## Best Practices
 
 1. **Use with [`CodeProvider`](../code-provider/page.mdx)** - Always wrap CodeController with [`CodeProvider`](../code-provider/page.mdx) for client-side highlighting

docs/app/docs-infra/components/code-controller-context/types.md

@@ -23,13 +23,14 @@ An object containing:
 - setSelection: Function to update the selection
 - components: Override components for the preview
 
-| Property     | Type                                                                             | Description |
-| :----------- | :------------------------------------------------------------------------------- | :---------- |
-| code         | `ControlledCode \| undefined`                                                    | -           |
-| selection    | `Selection \| undefined`                                                         | -           |
-| setCode      | `React.Dispatch<React.SetStateAction<ControlledCode \| undefined>> \| undefined` | -           |
-| setSelection | `React.Dispatch<React.SetStateAction<Selection>> \| undefined`                   | -           |
-| components   | `Record<string, React.ReactNode> \| undefined`                                   | -           |
+| Property        | Type                                                                             | Description |
+| :-------------- | :------------------------------------------------------------------------------- | :---------- |
+| code            | `ControlledCode \| undefined`                                                    | -           |
+| selection       | `Selection \| undefined`                                                         | -           |
+| setCode         | `React.Dispatch<React.SetStateAction<ControlledCode \| undefined>> \| undefined` | -           |
+| setSelection    | `React.Dispatch<React.SetStateAction<Selection>> \| undefined`                   | -           |
+| components      | `Record<string, React.ReactNode> \| undefined`                                   | -           |
+| sourceEnhancers | `SourceEnhancer[] \| undefined`                                                  | -           |
 
 ## Additional Types
 
@@ -73,6 +74,11 @@ type CodeControllerContext = {
    * e.g. `{ variantA: {}, variantB: {} }`.
    */
   components?: Record<string, React.ReactNode>;
+  /**
+   * Additional source enhancers to apply to parsed HAST sources.
+   * These are merged with enhancers from CodeProvider and useCode opts.
+   */
+  sourceEnhancers?: SourceEnhancer[];
 };
 ```
 
@@ -81,3 +87,15 @@ type CodeControllerContext = {
 ```typescript
 type Selection = { variant: string; fileName?: string; transformKey?: string };
 ```
+
+## External Types
+
+### SourceEnhancer
+
+```typescript
+type SourceEnhancer = (
+  root: { data?: unknown | undefined },
+  comments: {} | undefined,
+  fileName: string,
+) => { data?: unknown | undefined } | Promise;
+```