From 16c9fbf4270785438ad056fe2f6a30caea0bdd58 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 10 Apr 2026 21:53:58 -0400
Subject: [PATCH 01/44] Add `lintJavascriptDemoFocus` eslint plugin

---
 .circleci/orbs/code-infra.yml                 |   3 +
 .../code-highlighter/demos/CodeContent.tsx    |   2 +
 .../demos/CodeContentLoading.tsx              |   2 +
 .../code-highlighter/demos/code/page.tsx      |   2 +
 .../demos/code-editor/CodeController.tsx      |   2 +
 .../demos/code-editor/CodeEditor.tsx          |   2 +
 .../demos/code-editor/CodeEditorContent.tsx   |   2 +
 .../demos/demo-live/DemoController.tsx        |   2 +
 .../demos/demo-live/DemoLive.tsx              |   2 +
 .../demos/demo-live/DemoLiveContent.tsx       |   2 +
 .../demo-live/demo-basic/CheckboxBasic.tsx    |   2 +
 .../demos/multi-file/MultiFileContent.tsx     |   2 +
 .../demos/multi-file/MultiFileEditor.tsx      |   2 +
 .../code-highlighter/demos/CodeBlock.tsx      |   2 +
 .../code-highlighter/demos/CodeContent.tsx    |   2 +
 .../code-highlighter/demos/DemoContent.tsx    |   2 +
 .../demos/code-basic/BasicCode.tsx            |   5 +-
 .../demos/code-highlight-idle/BasicCode.tsx   |   5 +-
 .../demos/code-highlight-idle/Code.tsx        |   2 +
 .../demos/code-highlight-init/BasicCode.tsx   |   5 +-
 .../demos/code-highlight-init/Code.tsx        |   2 +
 .../demos/code-transformed/BasicCode.tsx      |   1 +
 .../demos/code-transformed/Code.tsx           |   2 +
 .../DemoContentLoading.tsx                    |   2 +
 .../demo-red/CheckboxRed.tsx                  |   5 +-
 .../DemoContentLoading.tsx                    |   2 +
 .../demo-red/css-modules/CheckboxRed.tsx      |   5 +-
 .../demo-red/tailwind/CheckboxRed.tsx         |   5 +-
 .../demo-fallback/DemoContentLoading.tsx      |   2 +
 .../demo-fallback/demo-red/CheckboxRed.tsx    |   5 +-
 .../demo-basic/CheckboxBasic.tsx              |   5 +-
 .../demo-default/css-modules/CheckboxRed.tsx  |   5 +-
 .../demo-default/tailwind/CheckboxRed.tsx     |   5 +-
 .../demos/demo/demo-basic/CheckboxBasic.tsx   |   5 +-
 .../components/code-provider/demos/Code.tsx   |   2 +
 .../code-provider/demos/base/BasicCode.tsx    |   2 +
 .../demos/fetch-demo/CodeProviderGitHub.tsx   |   2 +
 .../code-provider/demos/fetch-demo/Docs.tsx   |   2 +
 .../fetch-demo/demo-basic/CheckboxBasic.tsx   |   5 +-
 .../demos/text-input-copy/TextInputCopy.tsx   |   2 +
 .../variant-selector/VariantSelector.tsx      |   2 +
 .../hooks/use-types/demos/TypesTable.tsx      |   2 +
 .../hooks/use-types/demos/basic/Component.tsx |   2 +
 .../Component/Part/ComponentPart.tsx          |   2 +
 .../Component/Root/ComponentRoot.tsx          |   2 +
 .../demos/blocks-data-attr/TypesComponent.tsx |   2 +
 .../AlertDialog/AlertDialogTrigger.tsx        |   5 +-
 .../blocks-inherited/Dialog/DialogClose.tsx   |   2 +
 .../blocks-inherited/Dialog/DialogTrigger.tsx |   2 +
 .../blocks-inherited/TypesAlertDialog.tsx     |   2 +
 .../demos/blocks/Component/ComponentPart.tsx  |   2 +
 .../demos/blocks/Component/ComponentRoot.tsx  |   2 +
 .../use-types/demos/blocks/TypesComponent.tsx |   2 +
 .../use-types/demos/data-attr/Component.tsx   |   2 +
 .../demos/tab-navigation/TabNavigation.tsx    |   2 +
 .../demos/CodeIndent.tsx                      |   2 +
 .../demos/CollapsibleContent.tsx              |   2 +
 .../demos/IndentContent.tsx                   |   2 +
 .../lint-javascript-demo-focus/page.mdx       | 200 +++++++
 .../lint-javascript-demo-focus/types.md       |  51 ++
 .../lint-javascript-demo-focus/types.ts       |   4 +
 docs/app/docs-infra/pipeline/page.mdx         |  26 +
 eslint.config.mjs                             |  10 +
 package.json                                  |   1 +
 packages/docs-infra/package.json              |   2 +
 .../pipeline/lintJavascriptDemoFocus/index.ts |   1 +
 .../lintJavascriptDemoFocus.test.ts           | 485 +++++++++++++++++
 .../lintJavascriptDemoFocus.ts                | 488 ++++++++++++++++++
 pnpm-lock.yaml                                |   6 +
 69 files changed, 1416 insertions(+), 13 deletions(-)
 create mode 100644 docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
 create mode 100644 docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md
 create mode 100644 docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.ts
 create mode 100644 packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/index.ts
 create mode 100644 packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
 create mode 100644 packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts

diff --git a/.circleci/orbs/code-infra.yml b/.circleci/orbs/code-infra.yml
index 7a9972903..b5212fa79 100644
--- a/.circleci/orbs/code-infra.yml
+++ b/.circleci/orbs/code-infra.yml
@@ -82,6 +82,9 @@ commands:
   eslint:
     description: 'Runs ESLint on the codebase'
     steps:
+      - run:
+          name: Build docs-infra for ESLint plugins
+          command: pnpm run docs:lib
       - restore_cache:
           keys:
             - eslint-cache-{{ checksum "pnpm-lock.yaml" }}
diff --git a/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx b/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx
index dd99934a1..fb73829ff 100644
--- a/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx
+++ b/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx
@@ -10,7 +10,9 @@ import styles from './CodeContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function CodeContent(props: ContentProps<{}>) {
+  // @highlight-start @focus
   const code = useCode(props, { preClassName: styles.codeBlock });
 
   return <div className={styles.code}>{code.selectedFile}</div>;
+  // @highlight-end
 }
diff --git a/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx b/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx
index 8d15dfde8..051462704 100644
--- a/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx
+++ b/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx
@@ -9,9 +9,11 @@ import '@wooorm/starry-night/style/light';
 export function CodeContentLoading(props: ContentLoadingProps<{}>) {
   return (
     <div>
+      {/* @highlight-start @focus */}
       <div className={styles.code}>
         <pre className={styles.codeBlock}>{props.source}</pre>
       </div>
+      {/* @highlight-end */}
     </div>
   );
 }
diff --git a/docs/app/bench/docs-infra/components/code-highlighter/demos/code/page.tsx b/docs/app/bench/docs-infra/components/code-highlighter/demos/code/page.tsx
index f61f0f8fc..4f30b08f5 100644
--- a/docs/app/bench/docs-infra/components/code-highlighter/demos/code/page.tsx
+++ b/docs/app/bench/docs-infra/components/code-highlighter/demos/code/page.tsx
@@ -11,6 +11,7 @@ const sourceParser = createParseSource();
 
 export default function Page() {
   return (
+    // @highlight-start @focus
     <CodeHighlighter
       Content={CodeContent}
       ContentLoading={CodeContentLoading}
@@ -19,5 +20,6 @@ export default function Page() {
     >
       {code}
     </CodeHighlighter>
+    // @highlight-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx
index bb2436740..1fa4b43ae 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx
@@ -5,6 +5,7 @@ import { CodeControllerContext } from '@mui/internal-docs-infra/CodeControllerCo
 import type { ControlledCode } from '@mui/internal-docs-infra/CodeHighlighter/types';
 
 export function CodeController({ children }: { children: React.ReactNode }) {
+  // @highlight-start @focus
   const [code, setCode] = React.useState<ControlledCode | undefined>(undefined);
 
   const contextValue = React.useMemo(() => ({ code, setCode }), [code, setCode]);
@@ -12,4 +13,5 @@ export function CodeController({ children }: { children: React.ReactNode }) {
   return (
     <CodeControllerContext.Provider value={contextValue}>{children}</CodeControllerContext.Provider>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditor.tsx b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditor.tsx
index d3dbee261..87790c3d3 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditor.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditor.tsx
@@ -20,6 +20,7 @@ function greet(name) {
 
 export function CodeEditor() {
   return (
+    // @highlight-start @focus
     <CodeProvider>
       <CodeController>
         <CodeHighlighter
@@ -31,5 +32,6 @@ export function CodeEditor() {
         />
       </CodeController>
     </CodeProvider>
+    // @highlight-end
   );
 }
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..2fc5bdeef 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
@@ -10,6 +10,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>) {
+  // @highlight-start @focus
   const preRef = React.useRef<HTMLPreElement | null>(null);
   const code = useCode(props, { preClassName: styles.codeBlock, preRef });
 
@@ -47,4 +48,5 @@ export function CodeEditorContent(props: ContentProps<object>) {
       <div className={styles.code}>{code.selectedFile}</div>
     </div>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx
index b42c1ca94..c3bb22508 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx
@@ -27,6 +27,7 @@ function Runner({ code }: { code: string }) {
 }
 
 export function DemoController({ children }: { children: React.ReactNode }) {
+  // @highlight-start @focus
   const [code, setCode] = React.useState<ControlledCode | undefined>(undefined);
 
   const components = React.useMemo(
@@ -56,4 +57,5 @@ export function DemoController({ children }: { children: React.ReactNode }) {
   return (
     <CodeControllerContext.Provider value={contextValue}>{children}</CodeControllerContext.Provider>
   );
+  // @highlight-end
 }
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..b0b3103ec 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
@@ -5,10 +5,12 @@ import { DemoCheckboxBasic } from './demo-basic';
 
 export function DemoLive() {
   return (
+    // @highlight-start @focus
     <CodeProvider>
       <DemoController>
         <DemoCheckboxBasic />
       </DemoController>
     </CodeProvider>
+    // @highlight-end
   );
 }
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..a72cab791 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
@@ -16,6 +16,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function DemoLiveContent(props: ContentProps<object>) {
+  // @highlight-start @focus
   const preRef = React.useRef<HTMLPreElement | null>(null);
   const demo = useDemo(props, { preClassName: styles.codeBlock, preRef });
 
@@ -85,4 +86,5 @@ export function DemoLiveContent(props: ContentProps<object>) {
       </div>
     </div>
   );
+  // @highlight-end
 }
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..545677549 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 @focus */}
       <Checkbox defaultChecked />
       <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>
+      {/* @highlight-end */}
     </div>
   );
 }
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..561f3fdc6 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
@@ -10,6 +10,7 @@ import styles from '../code-editor/CodeEditorContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function MultiFileContent(props: ContentProps<object>) {
+  // @highlight-start @focus
   const preRef = React.useRef<HTMLPreElement | null>(null);
   const code = useCode(props, { preClassName: styles.codeBlock, preRef });
 
@@ -43,4 +44,5 @@ export function MultiFileContent(props: ContentProps<object>) {
       <div className={styles.code}>{code.selectedFile}</div>
     </div>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileEditor.tsx b/docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileEditor.tsx
index 8f5affceb..ae0a21e80 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileEditor.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileEditor.tsx
@@ -43,6 +43,7 @@ p {
 
 export function MultiFileEditor() {
   return (
+    // @highlight-start @focus
     <CodeProvider>
       <CodeController>
         <CodeHighlighter
@@ -54,5 +55,6 @@ export function MultiFileEditor() {
         />
       </CodeController>
     </CodeProvider>
+    // @highlight-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/CodeBlock.tsx b/docs/app/docs-infra/components/code-highlighter/demos/CodeBlock.tsx
index 29e0e1a90..c48a91b17 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/CodeBlock.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/CodeBlock.tsx
@@ -19,6 +19,7 @@ export function Code({
   fileName?: string;
 }) {
   return (
+    // @highlight-start @focus
     <CodeHighlighter
       language={language}
       fileName={fileName}
@@ -27,5 +28,6 @@ export function Code({
     >
       {children}
     </CodeHighlighter>
+    // @highlight-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.tsx b/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.tsx
index ff6339ce5..b148d9dac 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.tsx
@@ -16,6 +16,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function CodeContent(props: ContentProps<object>) {
+  // @highlight-start @focus
   const code = useCode(props, { preClassName: styles.codeBlock });
 
   const hasJsTransform = code.availableTransforms.includes('js');
@@ -85,4 +86,5 @@ export function CodeContent(props: ContentProps<object>) {
       </div>
     </div>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.tsx b/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.tsx
index 294339889..a6bbc87a4 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.tsx
@@ -16,6 +16,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function DemoContent(props: ContentProps<object>) {
+  // @highlight-start @focus
   const demo = useDemo(props, { preClassName: styles.codeBlock });
 
   const hasJsTransform = demo.availableTransforms.includes('js');
@@ -82,4 +83,5 @@ export function DemoContent(props: ContentProps<object>) {
       </div>
     </div>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-basic/BasicCode.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-basic/BasicCode.tsx
index 093206112..4c2fadb7c 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-basic/BasicCode.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-basic/BasicCode.tsx
@@ -2,5 +2,8 @@ import * as React from 'react';
 import { Code } from '../CodeBlock';
 
 export function BasicCode() {
-  return <Code fileName="hello.js">{`console.log('Hello, world!');`}</Code>;
+  return (
+    // @highlight @focus
+    <Code fileName="hello.js">{`console.log('Hello, world!');`}</Code>
+  );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/BasicCode.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/BasicCode.tsx
index a75d04ead..58ed4229f 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/BasicCode.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/BasicCode.tsx
@@ -2,5 +2,8 @@ import * as React from 'react';
 import { Code } from './Code';
 
 export function BasicCode() {
-  return <Code fileName="hello.js">{`console.log('Hello, world!');`}</Code>;
+  return (
+    // @highlight @focus
+    <Code fileName="hello.js">{`console.log('Hello, world!');`}</Code>
+  );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/Code.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/Code.tsx
index 72b75b3ce..535f2155b 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/Code.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/Code.tsx
@@ -10,6 +10,7 @@ const sourceParser = createParseSource();
 
 export function Code({ children, fileName }: { children: string; fileName?: string }) {
   return (
+    // @highlight-start @focus
     <CodeHighlighter
       fileName={fileName}
       Content={CodeContent}
@@ -18,5 +19,6 @@ export function Code({ children, fileName }: { children: string; fileName?: stri
     >
       {children}
     </CodeHighlighter>
+    // @highlight-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/BasicCode.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/BasicCode.tsx
index a75d04ead..58ed4229f 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/BasicCode.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/BasicCode.tsx
@@ -2,5 +2,8 @@ import * as React from 'react';
 import { Code } from './Code';
 
 export function BasicCode() {
-  return <Code fileName="hello.js">{`console.log('Hello, world!');`}</Code>;
+  return (
+    // @highlight @focus
+    <Code fileName="hello.js">{`console.log('Hello, world!');`}</Code>
+  );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/Code.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/Code.tsx
index 72b75b3ce..535f2155b 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/Code.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/Code.tsx
@@ -10,6 +10,7 @@ const sourceParser = createParseSource();
 
 export function Code({ children, fileName }: { children: string; fileName?: string }) {
   return (
+    // @highlight-start @focus
     <CodeHighlighter
       fileName={fileName}
       Content={CodeContent}
@@ -18,5 +19,6 @@ export function Code({ children, fileName }: { children: string; fileName?: stri
     >
       {children}
     </CodeHighlighter>
+    // @highlight-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/BasicCode.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/BasicCode.tsx
index 5fc1eefda..3e7874e6b 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/BasicCode.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/BasicCode.tsx
@@ -3,6 +3,7 @@ import { Code } from './Code';
 
 export function BasicCode() {
   return (
+    // @highlight @focus
     <Code fileName="example.ts">{`const x: number = 1;\ninterface Props { name: string; }`}</Code>
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/Code.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/Code.tsx
index da1ff3de1..c2993c64e 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/Code.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/Code.tsx
@@ -10,6 +10,7 @@ const sourceTransformers = [TypescriptToJavascriptTransformer];
 
 export function Code({ children, fileName }: { children: string; fileName?: string }) {
   return (
+    // @highlight-start @focus
     <CodeHighlighter
       fileName={fileName}
       Content={CodeContent}
@@ -18,5 +19,6 @@ export function Code({ children, fileName }: { children: string; fileName?: stri
     >
       {children}
     </CodeHighlighter>
+    // @highlight-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx
index 936980ce8..05b382f6d 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx
@@ -9,6 +9,7 @@ import loadingStyles from './DemoContentLoading.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function DemoContentLoading(props: ContentLoadingProps<object>) {
+  // @highlight-start @focus
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -57,4 +58,5 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
       </div>
     </div>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/demo-red/CheckboxRed.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/demo-red/CheckboxRed.tsx
index adc5f88e6..8322e4428 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/demo-red/CheckboxRed.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/demo-red/CheckboxRed.tsx
@@ -3,5 +3,8 @@ import { Checkbox } from '@/components/Checkbox';
 import styles from './CheckboxRed.module.css';
 
 export function CheckboxRed() {
-  return <Checkbox className={styles.root} defaultChecked />;
+  return (
+    // @highlight @focus
+    <Checkbox className={styles.root} defaultChecked />
+  );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx
index 069c8d4aa..78c2658fd 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx
@@ -14,6 +14,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function DemoContentLoading(props: ContentLoadingProps<object>) {
+  // @highlight-start @focus
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -89,4 +90,5 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
       </div>
     </div>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/css-modules/CheckboxRed.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/css-modules/CheckboxRed.tsx
index 1df8d8c02..03a0be5a8 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/css-modules/CheckboxRed.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/css-modules/CheckboxRed.tsx
@@ -4,5 +4,8 @@ import { Checkbox } from '@/components/Checkbox';
 import styles from './CheckboxRed.module.css';
 
 export function CheckboxRed() {
-  return <Checkbox defaultChecked className={styles.root} />;
+  return (
+    // @highlight @focus
+    <Checkbox defaultChecked className={styles.root} />
+  );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/tailwind/CheckboxRed.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/tailwind/CheckboxRed.tsx
index 6ae30479a..7dfbea8d1 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/tailwind/CheckboxRed.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/tailwind/CheckboxRed.tsx
@@ -2,5 +2,8 @@ import * as React from 'react';
 import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxRed() {
-  return <Checkbox defaultChecked className="bg-red-500" />;
+  return (
+    // @highlight @focus
+    <Checkbox defaultChecked className="bg-red-500" />
+  );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx
index c9f806ced..faa341b65 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx
@@ -8,6 +8,7 @@ import styles from '../DemoContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function DemoContentLoading(props: ContentLoadingProps<object>) {
+  // @highlight-start @focus
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -51,4 +52,5 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
       </div>
     </div>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/demo-red/CheckboxRed.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/demo-red/CheckboxRed.tsx
index adc5f88e6..8322e4428 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/demo-red/CheckboxRed.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/demo-red/CheckboxRed.tsx
@@ -3,5 +3,8 @@ import { Checkbox } from '@/components/Checkbox';
 import styles from './CheckboxRed.module.css';
 
 export function CheckboxRed() {
-  return <Checkbox className={styles.root} defaultChecked />;
+  return (
+    // @highlight @focus
+    <Checkbox className={styles.root} defaultChecked />
+  );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-server-loaded/demo-basic/CheckboxBasic.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-server-loaded/demo-basic/CheckboxBasic.tsx
index adcf3533a..74d562e6d 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-server-loaded/demo-basic/CheckboxBasic.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-server-loaded/demo-basic/CheckboxBasic.tsx
@@ -2,5 +2,8 @@ import * as React from 'react';
 import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxBasic() {
-  return <Checkbox defaultChecked />;
+  return (
+    // @highlight @focus
+    <Checkbox defaultChecked />
+  );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/css-modules/CheckboxRed.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/css-modules/CheckboxRed.tsx
index 1df8d8c02..03a0be5a8 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/css-modules/CheckboxRed.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/css-modules/CheckboxRed.tsx
@@ -4,5 +4,8 @@ import { Checkbox } from '@/components/Checkbox';
 import styles from './CheckboxRed.module.css';
 
 export function CheckboxRed() {
-  return <Checkbox defaultChecked className={styles.root} />;
+  return (
+    // @highlight @focus
+    <Checkbox defaultChecked className={styles.root} />
+  );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/tailwind/CheckboxRed.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/tailwind/CheckboxRed.tsx
index f1c788638..de96d696e 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/tailwind/CheckboxRed.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/tailwind/CheckboxRed.tsx
@@ -2,5 +2,8 @@ import * as React from 'react';
 import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxRed() {
-  return <Checkbox defaultChecked className="bg-red-500 border-red-500" />;
+  return (
+    // @highlight @focus
+    <Checkbox defaultChecked className="bg-red-500 border-red-500" />
+  );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo/demo-basic/CheckboxBasic.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo/demo-basic/CheckboxBasic.tsx
index adcf3533a..74d562e6d 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo/demo-basic/CheckboxBasic.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo/demo-basic/CheckboxBasic.tsx
@@ -2,5 +2,8 @@ import * as React from 'react';
 import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxBasic() {
-  return <Checkbox defaultChecked />;
+  return (
+    // @highlight @focus
+    <Checkbox defaultChecked />
+  );
 }
diff --git a/docs/app/docs-infra/components/code-provider/demos/Code.tsx b/docs/app/docs-infra/components/code-provider/demos/Code.tsx
index ed07a0a6c..815b257f3 100644
--- a/docs/app/docs-infra/components/code-provider/demos/Code.tsx
+++ b/docs/app/docs-infra/components/code-provider/demos/Code.tsx
@@ -5,8 +5,10 @@ import { CodeContent } from '../../code-highlighter/demos/CodeContent';
 
 export function Code({ children, fileName }: { children: string; fileName?: string }) {
   return (
+    // @highlight-start @focus
     <CodeHighlighter fileName={fileName} Content={CodeContent}>
       {children}
     </CodeHighlighter>
+    // @highlight-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-provider/demos/base/BasicCode.tsx b/docs/app/docs-infra/components/code-provider/demos/base/BasicCode.tsx
index 9f15cdb0e..a84ee1eea 100644
--- a/docs/app/docs-infra/components/code-provider/demos/base/BasicCode.tsx
+++ b/docs/app/docs-infra/components/code-provider/demos/base/BasicCode.tsx
@@ -4,8 +4,10 @@ import { Code } from '../../../code-highlighter/demos/CodeBlock';
 
 export function BasicCode() {
   return (
+    // @highlight-start @focus
     <CodeProvider>
       <Code fileName="example.js">{`console.log('Hello, world!');`}</Code>
     </CodeProvider>
+    // @highlight-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-provider/demos/fetch-demo/CodeProviderGitHub.tsx b/docs/app/docs-infra/components/code-provider/demos/fetch-demo/CodeProviderGitHub.tsx
index 456030894..27a43d362 100644
--- a/docs/app/docs-infra/components/code-provider/demos/fetch-demo/CodeProviderGitHub.tsx
+++ b/docs/app/docs-infra/components/code-provider/demos/fetch-demo/CodeProviderGitHub.tsx
@@ -90,6 +90,7 @@ const loadSource: LoadSource = async (url: string) => {
 
 export function CodeProviderGitHub({ children }: { children: React.ReactNode }) {
   return (
+    // @highlight-start @focus
     <CodeProvider
       loadCodeMeta={loadCodeMeta}
       loadVariantMeta={loadVariantMeta}
@@ -97,5 +98,6 @@ export function CodeProviderGitHub({ children }: { children: React.ReactNode })
     >
       {children}
     </CodeProvider>
+    // @highlight-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-provider/demos/fetch-demo/Docs.tsx b/docs/app/docs-infra/components/code-provider/demos/fetch-demo/Docs.tsx
index 813c0aa53..5bdcc5b71 100644
--- a/docs/app/docs-infra/components/code-provider/demos/fetch-demo/Docs.tsx
+++ b/docs/app/docs-infra/components/code-provider/demos/fetch-demo/Docs.tsx
@@ -4,8 +4,10 @@ import { DemoCheckboxBasic } from './demo-basic';
 
 export function Docs() {
   return (
+    // @highlight-start @focus
     <CodeProviderGitHub>
       <DemoCheckboxBasic />
     </CodeProviderGitHub>
+    // @highlight-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-provider/demos/fetch-demo/demo-basic/CheckboxBasic.tsx b/docs/app/docs-infra/components/code-provider/demos/fetch-demo/demo-basic/CheckboxBasic.tsx
index adcf3533a..74d562e6d 100644
--- a/docs/app/docs-infra/components/code-provider/demos/fetch-demo/demo-basic/CheckboxBasic.tsx
+++ b/docs/app/docs-infra/components/code-provider/demos/fetch-demo/demo-basic/CheckboxBasic.tsx
@@ -2,5 +2,8 @@ import * as React from 'react';
 import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxBasic() {
-  return <Checkbox defaultChecked />;
+  return (
+    // @highlight @focus
+    <Checkbox defaultChecked />
+  );
 }
diff --git a/docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx b/docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx
index a9e2719bc..e0498b5e3 100644
--- a/docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx
+++ b/docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx
@@ -4,6 +4,7 @@ import { useCopier } from '@mui/internal-docs-infra/useCopier';
 import styles from './TextInputCopy.module.css';
 
 export function TextInputCopy() {
+  // @highlight-start @focus
   const [text, setText] = React.useState('Hello, copy me!');
   const { copy, recentlySuccessful } = useCopier(() => text);
 
@@ -21,4 +22,5 @@ export function TextInputCopy() {
       </button>
     </div>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx b/docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx
index 448c6e43c..cbff74e19 100644
--- a/docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx
+++ b/docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx
@@ -4,6 +4,7 @@ import { usePreference } from '@mui/internal-docs-infra/usePreference';
 import styles from './VariantSelector.module.css';
 
 export function VariantSelector() {
+  // @highlight-start @focus
   const variants = ['contained', 'outlined', 'text'];
   const [variant, setVariant] = usePreference('variant', variants, () => 'contained');
 
@@ -30,4 +31,5 @@ export function VariantSelector() {
       </div>
     </div>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx b/docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx
index 3768c8299..0b57a1b57 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx
@@ -20,6 +20,7 @@ export type TypesTableProps = BaseTypesTableProps<{}>;
 
 export function TypesTable(props: TypesTableProps) {
   // Get the main type and additional types for this export
+  // @highlight-start @focus
   const { type, additionalTypes } = useTypes(props);
 
   return (
@@ -37,6 +38,7 @@ export function TypesTable(props: TypesTableProps) {
       ))}
     </div>
   );
+  // @highlight-end
 }
 
 function TypeMetaDoc(props: { typeMeta: EnhancedTypesMeta }) {
diff --git a/docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx b/docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx
index 5fba658f6..176722c09 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx
@@ -13,6 +13,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function Component(props: Props) {
+  // @highlight-start @focus
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
@@ -23,4 +24,5 @@ export function Component(props: Props) {
       {!props.disabled ? props.children : null}
     </button>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx
index 4c9842d22..9a4981349 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx
@@ -22,6 +22,7 @@ export interface ComponentPartProps {
  * A simple component that displays a title and optional children.
  */
 export function ComponentPart(props: ComponentPartProps) {
+  // @highlight-start @focus
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event, props.input);
   };
@@ -32,6 +33,7 @@ export function ComponentPart(props: ComponentPartProps) {
       {!props.disabled ? props.children : null}
     </button>
   );
+  // @highlight-end
 }
 
 // eslint-disable-next-line @typescript-eslint/no-namespace -- Using namespace for type grouping as per Base UI convention
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx
index 6b62cb924..e41e7dfc1 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx
@@ -38,6 +38,7 @@ export interface ComponentRootProps {
  * A simple component that displays a title and optional children.
  */
 export function ComponentRoot(props: ComponentRootProps) {
+  // @highlight-start @focus
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
 
@@ -59,6 +60,7 @@ export function ComponentRoot(props: ComponentRootProps) {
       {!props.disabled ? props.children : null}
     </button>
   );
+  // @highlight-end
 }
 
 // eslint-disable-next-line @typescript-eslint/no-namespace -- Using namespace for type grouping as per Base UI convention
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/TypesComponent.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/TypesComponent.tsx
index 3aa3e79b9..f4dd9933d 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/TypesComponent.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/TypesComponent.tsx
@@ -4,6 +4,7 @@ import { TypesComponent as ComponentTypes, TypesComponentAdditional } from './ty
 export function TypesComponent() {
   return (
     <div>
+      {/* @highlight-start @focus */}
       <h3>Component API</h3>
       <h3>Root</h3>
       <ComponentTypes.Root />
@@ -11,6 +12,7 @@ export function TypesComponent() {
       <ComponentTypes.Part />
       <h3>Additional Types</h3>
       <TypesComponentAdditional />
+      {/* @highlight-end */}
     </div>
   );
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/AlertDialog/AlertDialogTrigger.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/AlertDialog/AlertDialogTrigger.tsx
index 049f9c178..bc2104450 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/AlertDialog/AlertDialogTrigger.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/AlertDialog/AlertDialogTrigger.tsx
@@ -33,7 +33,10 @@ export const AlertDialogTrigger = React.forwardRef(function AlertDialogTrigger(
   props: AlertDialogTriggerProps,
   ref: React.ForwardedRef<HTMLButtonElement>,
 ) {
-  return <DialogTrigger ref={ref} {...(props as DialogTrigger.Props)} />;
+  return (
+    // @highlight @focus
+    <DialogTrigger ref={ref} {...(props as DialogTrigger.Props)} />
+  );
 });
 
 // eslint-disable-next-line @typescript-eslint/no-namespace, import/export
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx
index 9a2544ad4..5bf0617c1 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx
@@ -22,6 +22,7 @@ export const DialogClose = React.forwardRef(function DialogClose(
   props: DialogCloseProps,
   ref: React.ForwardedRef<HTMLButtonElement>,
 ) {
+  // @highlight-start @focus
   const { render, children, ...other } = props;
 
   // In a real implementation, triggerState would come from context
@@ -32,6 +33,7 @@ export const DialogClose = React.forwardRef(function DialogClose(
       {render ? render(triggerState) : children}
     </button>
   );
+  // @highlight-end
 });
 
 // eslint-disable-next-line @typescript-eslint/no-namespace, import/export
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx
index a52b109af..91d110c30 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx
@@ -36,6 +36,7 @@ export const DialogTrigger = React.forwardRef(function DialogTrigger(
   props: DialogTriggerProps,
   ref: React.ForwardedRef<HTMLButtonElement>,
 ) {
+  // @highlight-start @focus
   const { className, disabled, children, ...other } = props;
 
   const state: DialogTriggerState = React.useMemo(
@@ -53,6 +54,7 @@ export const DialogTrigger = React.forwardRef(function DialogTrigger(
       {children}
     </button>
   );
+  // @highlight-end
 });
 
 // eslint-disable-next-line @typescript-eslint/no-namespace, import/export
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/TypesAlertDialog.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/TypesAlertDialog.tsx
index fa7299d73..54670f3d9 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/TypesAlertDialog.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/TypesAlertDialog.tsx
@@ -4,11 +4,13 @@ import { TypesAlertDialog as AlertDialogTypes } from './types';
 export function TypesAlertDialog() {
   return (
     <div>
+      {/* @highlight-start @focus */}
       <h3>Alert Dialog API</h3>
       <h3>Trigger</h3>
       <AlertDialogTypes.Trigger />
       <h3>Close</h3>
       <AlertDialogTypes.Close />
+      {/* @highlight-end */}
     </div>
   );
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx
index 64e9069b6..202a260ac 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx
@@ -13,6 +13,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function ComponentPart(props: Props) {
+  // @highlight-start @focus
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
@@ -23,4 +24,5 @@ export function ComponentPart(props: Props) {
       {!props.disabled ? props.children : null}
     </button>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx
index 2c6d2cc0d..44f210999 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx
@@ -13,6 +13,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function ComponentRoot(props: Props) {
+  // @highlight-start @focus
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
@@ -23,4 +24,5 @@ export function ComponentRoot(props: Props) {
       {!props.disabled ? props.children : null}
     </button>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks/TypesComponent.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks/TypesComponent.tsx
index 6793b2638..c5d396fdc 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks/TypesComponent.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks/TypesComponent.tsx
@@ -4,10 +4,12 @@ import { TypesComponent as ComponentTypes } from './types';
 export function TypesComponent() {
   return (
     <div>
+      {/* @highlight-start @focus */}
       <h3>ComponentRoot</h3>
       <ComponentTypes.Root />
       <h3>ComponentPart</h3>
       <ComponentTypes.Part />
+      {/* @highlight-end */}
     </div>
   );
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx b/docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx
index 43daa6cbd..ef2f76921 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx
@@ -14,6 +14,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function Component(props: Props) {
+  // @highlight-start @focus
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
@@ -24,4 +25,5 @@ export function Component(props: Props) {
       {!props.disabled ? props.children : null}
     </button>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx b/docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx
index e3e6ef39b..abe05d012 100644
--- a/docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx
+++ b/docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx
@@ -14,6 +14,7 @@ const tabs = [
 ];
 
 export function TabNavigation() {
+  // @highlight-start @focus
   const [hash, setHash] = useUrlHashState();
   const activeTab = hash || 'overview';
 
@@ -39,4 +40,5 @@ export function TabNavigation() {
       </div>
     </div>
   );
+  // @highlight-end
 }
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 6eed34a39..9a0e02ad0 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
@@ -20,11 +20,13 @@ const sourceEnhancers = [enhanceCodeEmphasis];
  */
 export function CodeIndent({ code }: { code: CodeType }) {
   return (
+    // @highlight-start @focus
     <CodeHighlighter
       code={code}
       Content={IndentContent}
       sourceParser={sourceParser}
       sourceEnhancers={sourceEnhancers}
     />
+    // @highlight-end
   );
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
index 79df021aa..4c6c3a19d 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
@@ -8,6 +8,7 @@ import styles from './CollapsibleContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function CollapsibleContent(props: ContentProps<object>) {
+  // @highlight-start @focus
   const code = useCode(props, { preClassName: styles.codeBlock });
   const id = React.useId();
   const checkboxId = `${id}-expand`;
@@ -23,4 +24,5 @@ export function CollapsibleContent(props: ContentProps<object>) {
       </label>
     </div>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx
index d26fa2223..2e51765ca 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx
@@ -8,6 +8,7 @@ import styles from './IndentContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function IndentContent(props: ContentProps<object>) {
+  // @highlight-start @focus
   const code = useCode(props, { preClassName: styles.codeBlock });
   const [expanded, setExpanded] = React.useState(false);
 
@@ -19,4 +20,5 @@ export function IndentContent(props: ContentProps<object>) {
       </button>
     </div>
   );
+  // @highlight-end
 }
diff --git a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
new file mode 100644
index 000000000..c15a840ae
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
@@ -0,0 +1,200 @@
+# Lint JavaScript Demo Focus
+
+An ESLint rule that automatically inserts `@highlight` and `@focus` comments around the preview section of demo files. These comments control which parts of the code are highlighted and focused when rendered in documentation.
+
+## Overview
+
+Demo files in `docs/app/**/demos/**` need `@highlight` / `@focus` comments so the docs infrastructure knows which code to emphasize. Writing these by hand is tedious and error-prone. This ESLint rule detects the preview section of each demo and auto-fixes the comments in.
+
+### Key Features
+
+- **Auto-fixable**: Run `eslint --fix` to insert all comments automatically
+- **Smart comment style**: Uses JSX comments (`{/* */}`) inside wrapper elements and JS comments (`//`) elsewhere
+- **Single vs multi-line**: Uses `@highlight @focus` for single-line previews and `@highlight-start @focus` / `@highlight-end` for multi-line
+- **Named export detection**: Supports both `export default` and named exports (filename match or single-export fallback)
+- **Function body highlighting**: Wraps the entire body when hooks or setup statements are present
+- **Skip when present**: Files that already contain `@highlight` anywhere are left untouched
+
+## Installation & Usage
+
+Import the rule and wire it into your ESLint flat config:
+
+```js
+// eslint.config.mjs
+import { lintJavascriptDemoFocus } from '@mui/internal-docs-infra/pipeline/lintJavascriptDemoFocus';
+
+export default [
+  {
+    files: ['docs/app/**/demos/**/*.tsx', 'docs/app/**/demos/**/*.jsx'],
+    plugins: {
+      'docs-infra': { rules: { 'require-demo-focus': lintJavascriptDemoFocus } },
+    },
+    rules: {
+      'docs-infra/require-demo-focus': 'error',
+    },
+  },
+];
+```
+
+### With `wrapReturn`
+
+Enable the `wrapReturn` option to wrap bare `return <X />` statements in parentheses so the highlight comment can be placed inside:
+
+```js
+rules: {
+  'docs-infra/require-demo-focus': ['error', { wrapReturn: true }],
+},
+```
+
+## How It Works
+
+The rule identifies the main component export of a demo file and inserts comments based on the structure of its return value.
+
+### 1. Wrapper elements
+
+When the return contains a wrapper (`div`, `Box`, `Stack`, or `React.Fragment`), JSX comments are inserted inside the wrapper around its children:
+
+```tsx
+// Before
+export default function Demo() {
+  return (
+    <div>
+      <Button>Click me</Button>
+      <TextField label="Name" />
+    </div>
+  );
+}
+
+// After fix
+export default function Demo() {
+  return (
+    <div>
+      {/* @highlight-start @focus */}
+      <Button>Click me</Button>
+      <TextField label="Name" />
+      {/* @highlight-end */}
+    </div>
+  );
+}
+```
+
+For a single child inside a wrapper:
+
+```tsx
+// After fix
+export default function Demo() {
+  return (
+    <div>
+      {/* @highlight @focus */}
+      <Button>Click me</Button>
+    </div>
+  );
+}
+```
+
+### 2. Non-wrapper returns
+
+When the return is a bare element (not wrapped in `div`, `Box`, `Stack`, or a fragment), JS comments are inserted before the return line:
+
+```tsx
+// Before
+export default function Demo() {
+  return <Button>Click me</Button>;
+}
+
+// After fix
+export default function Demo() {
+  // @highlight @focus
+  return <Button>Click me</Button>;
+}
+```
+
+When the return already has parentheses, the comment is placed inside them:
+
+```tsx
+// Before
+export default function Demo() {
+  return <Button>Click me</Button>;
+}
+
+// After fix
+export default function Demo() {
+  return (
+    // @highlight @focus
+    <Button>Click me</Button>
+  );
+}
+```
+
+With `wrapReturn: true`, bare returns without parentheses are wrapped so the comment appears inside:
+
+```tsx
+// Before
+export default function Demo() {
+  return <Button>Click me</Button>;
+}
+
+// After fix (wrapReturn: true)
+export default function Demo() {
+  return (
+    // @highlight @focus
+    <Button>Click me</Button>
+  );
+}
+```
+
+### 3. Function body highlighting
+
+When the component has setup code (hooks, variables, etc.) before the return, the entire function body is wrapped:
+
+```tsx
+// Before
+export default function Demo() {
+  const code = useCode();
+  return <CodeEditor code={code} />;
+}
+
+// After fix
+export default function Demo() {
+  // @highlight-start @focus
+  const code = useCode();
+  return <CodeEditor code={code} />;
+  // @highlight-end
+}
+```
+
+## Named Export Detection
+
+Not all demos use `export default`. The rule handles named exports with two strategies:
+
+1. **Filename match** (preferred): If a named export matches the filename (e.g., `export function CodeEditor` in `CodeEditor.tsx`), that export is used.
+2. **Single export fallback**: If there is exactly one named component export and no filename match, that export is used.
+
+All common export forms are recognized: `export function`, `export const` with arrow or function expressions, and call-wrapped patterns like `React.forwardRef` or `React.memo`.
+
+```tsx
+// CodeEditor.tsx — filename match
+export function CodeEditor() {
+  return <Editor />;
+}
+
+// Also exports helpers — only CodeEditor is processed
+export function getEditorConfig() {
+  return {};
+}
+```
+
+Call-wrapped components work the same way:
+
+```tsx
+// DialogTrigger.tsx — React.forwardRef with filename match
+export const DialogTrigger = React.forwardRef(function DialogTrigger(props, ref) {
+  return <button ref={ref} {...props} />;
+});
+```
+
+## Types
+
+import { TypesLintJavascriptDemoFocus } from './types';
+
+<TypesLintJavascriptDemoFocus />
diff --git a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md
new file mode 100644
index 000000000..fe25ae84e
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md
@@ -0,0 +1,51 @@
+# Lint Javascript Demo Focus
+
+[//]: types.ts '<-- Autogenerated By (do not edit the following markdown directly), run: pnpm docs:validate docs-infra/pipeline/lint-javascript-demo-focus'
+
+## API Reference
+
+## Additional Types
+
+### lintJavascriptDemoFocus
+
+ESLint rule requiring demo files to have highlight-focus comments around the preview section.
+
+```typescript
+type lintJavascriptDemoFocus = {
+  meta: {
+    type: 'suggestion';
+    docs: {
+      description: 'Require demo files to have @highlight-start @focus / @highlight-end comments around the preview section.';
+    };
+    fixable: 'code';
+    messages: {
+      missingDemoFocusJsx: 'Demo file is missing {/* @highlight-start @focus */} and {/* @highlight-end */} comments around the preview section. Run with --fix to add them automatically.';
+      missingDemoFocusJsxSingle: 'Demo file is missing {/* @highlight @focus */} comment on the preview line. Run with --fix to add it automatically.';
+      missingDemoFocusJs: 'Demo file is missing // @highlight-start @focus and // @highlight-end comments around the preview section. Run with --fix to add them automatically.';
+      missingDemoFocusJsSingle: 'Demo file is missing // @highlight @focus comment on the preview line. Run with --fix to add it automatically.';
+      missingDemoFocusBody: 'Demo file is missing // @highlight-start @focus and // @highlight-end comments around the function body. Run with --fix to add them automatically.';
+    };
+    schema: [
+      {
+        type: 'object';
+        properties: {
+          wrapReturn: {
+            type: 'boolean';
+            description: 'When true, bare return statements without parentheses are wrapped in return (...) and the highlight comment is placed inside the parentheses.';
+          };
+        };
+        additionalProperties: false;
+      },
+    ];
+  };
+  create: create;
+};
+```
+
+## External Types
+
+### create
+
+```typescript
+type create = (context: RuleContext) => { ExportDefaultDeclaration?: undefined; ExportNamedDeclaration?: undefined; Program:exit?: undefined } | { ExportDefaultDeclaration: unknown; ExportNamedDeclaration: unknown; Program:exit: unknown }
+```
diff --git a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.ts b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.ts
new file mode 100644
index 000000000..145f559ec
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.ts
@@ -0,0 +1,4 @@
+import { createTypes } from '@/functions/createTypes';
+import { lintJavascriptDemoFocus } from '@mui/internal-docs-infra/pipeline/lintJavascriptDemoFocus';
+
+export const TypesLintJavascriptDemoFocus = createTypes(import.meta.url, lintJavascriptDemoFocus);
diff --git a/docs/app/docs-infra/pipeline/page.mdx b/docs/app/docs-infra/pipeline/page.mdx
index 1a69595e8..1609e53e4 100644
--- a/docs/app/docs-infra/pipeline/page.mdx
+++ b/docs/app/docs-infra/pipeline/page.mdx
@@ -8,6 +8,7 @@
 - Enhance Code Inline [New] - ([Outline](#enhance-code-inline), [Contents](./enhance-code-inline/page.mdx))
 - Enhance Code Types [New] - ([Outline](#enhance-code-types), [Contents](./enhance-code-types/page.mdx))
 - HAST Utilities - ([Outline](#hast-utilities), [Contents](./hast-utils/page.mdx))
+- Lint JavaScript Demo Focus [New] - ([Outline](#lint-javascript-demo-focus), [Contents](./lint-javascript-demo-focus/page.mdx))
 - Load Code Variant - ([Outline](#load-code-variant), [Contents](./load-code-variant/page.mdx))
 - Load Precomputed Code Highlighter - ([Outline](#load-precomputed-code-highlighter), [Contents](./load-precomputed-code-highlighter/page.mdx))
 - Load Precomputed Code Highlighter Client - ([Outline](#load-precomputed-code-highlighter-client), [Contents](./load-precomputed-code-highlighter-client/page.mdx))
@@ -305,6 +306,31 @@ The `hastUtils` module provides utilities for converting between HAST (Hypertext
 
 [Read more](./hast-utils/page.mdx)
 
+## Lint JavaScript Demo Focus
+
+An ESLint rule that automatically inserts `@highlight` and `@focus` comments around the preview section of demo files. These comments control which parts of the code are highlighted and focused when rendered in documentation.
+
+<details>
+
+<summary>Outline</summary>
+
+- Sections:
+  - Overview
+    - Key Features
+  - Installation & Usage
+    - With `wrapReturn`
+  - How It Works
+    - 1\. Wrapper elements
+    - 2\. Non-wrapper returns
+    - 3\. Function body highlighting
+  - Named Export Detection
+  - Types
+- Types: lintJavascriptDemoFocus
+
+</details>
+
+[Read more](./lint-javascript-demo-focus/page.mdx)
+
 ## Load Code Variant
 
 The `loadCodeVariant` module provides utilities for loading, processing, and transforming code variants with support for syntax highlighting, TypeScript-to-JavaScript transformation, extra files, and metadata management.
diff --git a/eslint.config.mjs b/eslint.config.mjs
index daf471afa..6700c6bea 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -7,6 +7,7 @@ import {
   EXTENSION_TS,
 } from '@mui/internal-code-infra/eslint';
 import nPlugin from 'eslint-plugin-n';
+import { lintJavascriptDemoFocus } from '@mui/internal-docs-infra/pipeline/lintJavascriptDemoFocus';
 
 const config = defineConfig(
   createBaseConfig({ baseDirectory: import.meta.dirname }),
@@ -63,6 +64,15 @@ const config = defineConfig(
       '@next/next/no-img-element': 'off',
     },
   },
+  {
+    files: ['docs/app/**/demos/**/*.tsx', 'docs/app/**/demos/**/*.jsx'],
+    plugins: {
+      'docs-infra': { rules: { 'require-demo-focus': lintJavascriptDemoFocus } },
+    },
+    rules: {
+      'docs-infra/require-demo-focus': ['error', { wrapReturn: true }],
+    },
+  },
   {
     files: [`apps/**/*${EXTENSION_TS}`],
     rules: {
diff --git a/package.json b/package.json
index 039177b36..bbe7e05c2 100644
--- a/package.json
+++ b/package.json
@@ -62,6 +62,7 @@
     "@eslint/compat": "^2.0.3",
     "@mui/internal-bundle-size-checker": "workspace:*",
     "@mui/internal-code-infra": "workspace:*",
+    "@mui/internal-docs-infra": "workspace:*",
     "@mui/internal-netlify-cache": "workspace:*",
     "@next/eslint-plugin-next": "^16.1.6",
     "@octokit/rest": "^22.0.1",
diff --git a/packages/docs-infra/package.json b/packages/docs-infra/package.json
index a74fee71e..945b2264b 100644
--- a/packages/docs-infra/package.json
+++ b/packages/docs-infra/package.json
@@ -43,6 +43,7 @@
     "./pipeline/transformMarkdownMetadata/types": "./src/pipeline/transformMarkdownMetadata/types.ts",
     "./pipeline/transformMarkdownRelativePaths": "./src/pipeline/transformMarkdownRelativePaths/index.ts",
     "./pipeline/hastUtils": "./src/pipeline/hastUtils/index.ts",
+    "./pipeline/lintJavascriptDemoFocus": "./src/pipeline/lintJavascriptDemoFocus/index.ts",
     "./pipeline/loadCodeVariant": "./src/pipeline/loadCodeVariant/index.ts",
     "./pipeline/loaderUtils": "./src/pipeline/loaderUtils/index.ts",
     "./pipeline/loadPrecomputedCodeHighlighter": "./src/pipeline/loadPrecomputedCodeHighlighter/index.ts",
@@ -132,6 +133,7 @@
     "@types/react": "19.2.14",
     "@types/webpack": "5.28.5",
     "@types/yargs": "17.0.35",
+    "@typescript-eslint/utils": "^8.57.1",
     "estree-util-to-js": "2.0.0",
     "hast-util-to-html": "9.0.5",
     "next": "16.1.7",
diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/index.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/index.ts
new file mode 100644
index 000000000..c2d716ccb
--- /dev/null
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/index.ts
@@ -0,0 +1 @@
+export * from './lintJavascriptDemoFocus';
diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
new file mode 100644
index 000000000..285adc114
--- /dev/null
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
@@ -0,0 +1,485 @@
+import { describe, it } from 'vitest';
+import { RuleTester } from 'eslint';
+import parser from '@typescript-eslint/parser';
+import { lintJavascriptDemoFocus } from './lintJavascriptDemoFocus';
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: {
+      ecmaFeatures: { jsx: true },
+    },
+  },
+});
+
+describe('lintJavascriptDemoFocus', () => {
+  // eslint-disable-next-line vitest/expect-expect -- RuleTester uses its own assertion library
+  it('should pass RuleTester', () => {
+    ruleTester.run('require-demo-focus', lintJavascriptDemoFocus, {
+      valid: [
+        // File already has @highlight — skip
+        {
+          code: `
+// @highlight
+export default function Demo() {
+  return <div>Hello</div>;
+}
+          `,
+        },
+        // File already has @highlight-start — skip
+        {
+          code: `
+{/* @highlight-start @focus */}
+export default function Demo() {
+  return <div>Hello</div>;
+}
+{/* @highlight-end */}
+          `,
+        },
+        // No export default, named export doesn't match filename, multiple exports
+        {
+          filename: 'Other.tsx',
+          code: `
+export function Foo() {
+  return <div>Hello</div>;
+}
+export function Bar() {
+  return <span>World</span>;
+}
+          `,
+        },
+        // Export default is not a function
+        {
+          code: `
+const value = 42;
+export default value;
+          `,
+        },
+        // Export default function returns non-JSX
+        {
+          code: `
+export default function Demo() {
+  return null;
+}
+          `,
+        },
+        // Function returns a string
+        {
+          code: `
+export default function Demo() {
+  return 'hello';
+}
+          `,
+        },
+        // Call-wrapped export with no function argument
+        {
+          code: `
+export const theme = createTheme({ palette: { primary: 'red' } });
+          `,
+        },
+      ],
+      invalid: [
+        // Single JSX element (no wrapper), single line: // comment fix
+        {
+          code: `export default function Demo() {
+  return <Button>Click me</Button>;
+}`,
+          output: `export default function Demo() {
+  // @highlight @focus
+  return <Button>Click me</Button>;
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // Wrapper div with multiple children: {/* start/end */} fix
+        {
+          code: `export default function Demo() {
+  return (
+    <div>
+      <Button>Click me</Button>
+      <Button>Click me too</Button>
+    </div>
+  );
+}`,
+          output: `export default function Demo() {
+  return (
+    <div>
+      {/* @highlight-start @focus */}
+      <Button>Click me</Button>
+      <Button>Click me too</Button>
+      {/* @highlight-end */}
+    </div>
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsx' }],
+        },
+        // Wrapper Box with single child: {/* single */} fix
+        {
+          code: `export default function Demo() {
+  return (
+    <Box>
+      <TextField label="Name" />
+    </Box>
+  );
+}`,
+          output: `export default function Demo() {
+  return (
+    <Box>
+      {/* @highlight @focus */}
+      <TextField label="Name" />
+    </Box>
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsxSingle' }],
+        },
+        // Wrapper Stack with multiple children: {/* start/end */} fix
+        {
+          code: `export default function Demo() {
+  return (
+    <Stack>
+      <Input />
+      <Button />
+    </Stack>
+  );
+}`,
+          output: `export default function Demo() {
+  return (
+    <Stack>
+      {/* @highlight-start @focus */}
+      <Input />
+      <Button />
+      {/* @highlight-end */}
+    </Stack>
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsx' }],
+        },
+        // Fragment shorthand with single child: {/* single */} fix
+        {
+          code: `export default function Demo() {
+  return (
+    <>
+      <Button>Click</Button>
+    </>
+  );
+}`,
+          output: `export default function Demo() {
+  return (
+    <>
+      {/* @highlight @focus */}
+      <Button>Click</Button>
+    </>
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsxSingle' }],
+        },
+        // Arrow function with block body returning bare element: // comment fix
+        {
+          code: `export default () => {
+  return <Button>Click</Button>;
+}`,
+          output: `export default () => {
+  // @highlight @focus
+  return <Button>Click</Button>;
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // Arrow function with implicit return of bare element: // comment fix
+        {
+          code: `export default () => <Button>Click</Button>`,
+          output: `// @highlight @focus\nexport default () => <Button>Click</Button>`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // Non-wrapper element inside parentheses: // comment fix
+        {
+          code: `export default function Demo() {
+  return (
+    <Button variant="contained">Submit</Button>
+  );
+}`,
+          output: `export default function Demo() {
+  return (
+    // @highlight @focus
+    <Button variant="contained">Submit</Button>
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // Arrow function with wrapper div single child: {/* single */} fix
+        {
+          code: `export default () => {
+  return (
+    <div>
+      <Button>Click</Button>
+    </div>
+  );
+}`,
+          output: `export default () => {
+  return (
+    <div>
+      {/* @highlight @focus */}
+      <Button>Click</Button>
+    </div>
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsxSingle' }],
+        },
+        // Named export function matching filename
+        {
+          filename: 'CodeEditor.tsx',
+          code: `export function CodeEditor() {
+  return (
+    <div>
+      <Input />
+      <Button />
+    </div>
+  );
+}`,
+          output: `export function CodeEditor() {
+  return (
+    <div>
+      {/* @highlight-start @focus */}
+      <Input />
+      <Button />
+      {/* @highlight-end */}
+    </div>
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsx' }],
+        },
+        // Named export const arrow matching filename
+        {
+          filename: 'MyDemo.tsx',
+          code: `export const MyDemo = () => {
+  return <Button>Click</Button>;
+}`,
+          output: `export const MyDemo = () => {
+  // @highlight @focus
+  return <Button>Click</Button>;
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // Single named export fallback (no filename match)
+        {
+          filename: 'Other.tsx',
+          code: `export function Demo() {
+  return <Button>Click</Button>;
+}`,
+          output: `export function Demo() {
+  // @highlight @focus
+  return <Button>Click</Button>;
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // Named export with filename match preferred over other exports
+        {
+          filename: 'Primary.tsx',
+          code: `export function Helper() {
+  return <span>helper</span>;
+}
+export function Primary() {
+  return (
+    <div>
+      <Input />
+      <Button />
+    </div>
+  );
+}`,
+          output: `export function Helper() {
+  return <span>helper</span>;
+}
+export function Primary() {
+  return (
+    <div>
+      {/* @highlight-start @focus */}
+      <Input />
+      <Button />
+      {/* @highlight-end */}
+    </div>
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsx' }],
+        },
+        // Function with hooks: highlight entire body
+        {
+          code: `export default function Demo() {
+  const code = useCode();
+  return (
+    <div>
+      {code.file}
+    </div>
+  );
+}`,
+          output: `export default function Demo() {
+  // @highlight-start @focus
+  const code = useCode();
+  return (
+    <div>
+      {code.file}
+    </div>
+  );
+  // @highlight-end
+}`,
+          errors: [{ messageId: 'missingDemoFocusBody' }],
+        },
+        // Named export with hooks: highlight entire body
+        {
+          filename: 'CodeContent.tsx',
+          code: `export function CodeContent(props) {
+  const code = useCode(props);
+  return (
+    <div>{code.file}</div>
+  );
+}`,
+          output: `export function CodeContent(props) {
+  // @highlight-start @focus
+  const code = useCode(props);
+  return (
+    <div>{code.file}</div>
+  );
+  // @highlight-end
+}`,
+          errors: [{ messageId: 'missingDemoFocusBody' }],
+        },
+        // Call-wrapped named export: React.forwardRef with filename match
+        {
+          filename: 'DialogTrigger.tsx',
+          code: `export const DialogTrigger = React.forwardRef(function DialogTrigger(props, ref) {
+  const { disabled, children, ...other } = props;
+  return (
+    <button type="button" ref={ref} disabled={disabled} {...other}>
+      {children}
+    </button>
+  );
+});`,
+          output: `export const DialogTrigger = React.forwardRef(function DialogTrigger(props, ref) {
+  // @highlight-start @focus
+  const { disabled, children, ...other } = props;
+  return (
+    <button type="button" ref={ref} disabled={disabled} {...other}>
+      {children}
+    </button>
+  );
+  // @highlight-end
+});`,
+          errors: [{ messageId: 'missingDemoFocusBody' }],
+        },
+        // Call-wrapped named export: React.memo with arrow function
+        {
+          filename: 'MemoDemo.tsx',
+          code: `export const MemoDemo = React.memo(() => {
+  return <Button>Click</Button>;
+});`,
+          output: `export const MemoDemo = React.memo(() => {
+  // @highlight @focus
+  return <Button>Click</Button>;
+});`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // Call-wrapped default export: export default React.forwardRef(...)
+        {
+          code: `export default React.forwardRef(function Demo(props, ref) {
+  return <Button ref={ref}>Click</Button>;
+});`,
+          output: `export default React.forwardRef(function Demo(props, ref) {
+  // @highlight @focus
+  return <Button ref={ref}>Click</Button>;
+});`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+      ],
+    });
+  });
+
+  // eslint-disable-next-line vitest/expect-expect -- RuleTester uses its own assertion library
+  it('should handle wrapReturn option', () => {
+    ruleTester.run('require-demo-focus', lintJavascriptDemoFocus, {
+      valid: [],
+      invalid: [
+        // wrapReturn: bare return single-line -> wrap in parens
+        {
+          options: [{ wrapReturn: true }],
+          code: `export default function Demo() {
+  return <Button>Click me</Button>;
+}`,
+          output: `export default function Demo() {
+  return (
+    // @highlight @focus
+    <Button>Click me</Button>
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // wrapReturn: already has parens, single-line -> just insert comment
+        {
+          options: [{ wrapReturn: true }],
+          code: `export default function Demo() {
+  return (
+    <Checkbox defaultChecked />
+  );
+}`,
+          output: `export default function Demo() {
+  return (
+    // @highlight @focus
+    <Checkbox defaultChecked />
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // wrapReturn: bare return multi-line -> wrap in parens with start/end
+        {
+          options: [{ wrapReturn: true }],
+          code: `export default function Demo() {
+  return <Card>
+    <Button>Click</Button>
+  </Card>;
+}`,
+          output: `export default function Demo() {
+  return (
+    // @highlight-start @focus
+    <Card>
+    <Button>Click</Button>
+  </Card>
+    // @highlight-end
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJs' }],
+        },
+        // wrapReturn: wrapper elements are unaffected (still use JSX comments)
+        {
+          options: [{ wrapReturn: true }],
+          code: `export default function Demo() {
+  return (
+    <div>
+      <Button>Click</Button>
+    </div>
+  );
+}`,
+          output: `export default function Demo() {
+  return (
+    <div>
+      {/* @highlight @focus */}
+      <Button>Click</Button>
+    </div>
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsxSingle' }],
+        },
+        // wrapReturn: named export bare return
+        {
+          options: [{ wrapReturn: true }],
+          filename: 'CheckboxRed.tsx',
+          code: `export function CheckboxRed() {
+  return <Checkbox defaultChecked />;
+}`,
+          output: `export function CheckboxRed() {
+  return (
+    // @highlight @focus
+    <Checkbox defaultChecked />
+  );
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+      ],
+    });
+  });
+});
diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
new file mode 100644
index 000000000..2fcca7928
--- /dev/null
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
@@ -0,0 +1,488 @@
+import * as path from 'node:path';
+import type { Rule } from 'eslint';
+import type { ExportDefaultDeclaration, ExportNamedDeclaration, Node } from 'estree';
+import type { TSESTree } from '@typescript-eslint/utils';
+
+type FunctionLikeNode = ExportDefaultDeclaration['declaration'] | Node;
+
+const WRAPPER_TAGS = ['div', 'Box', 'Stack'];
+
+function getTagName(openingElement: TSESTree.JSXOpeningElement): string | null {
+  if (openingElement.name.type === 'JSXIdentifier') {
+    return openingElement.name.name;
+  }
+  if (
+    openingElement.name.type === 'JSXMemberExpression' &&
+    openingElement.name.object.type === 'JSXIdentifier' &&
+    openingElement.name.object.name === 'React' &&
+    openingElement.name.property.name === 'Fragment'
+  ) {
+    return 'React.Fragment';
+  }
+  return null;
+}
+
+function isBlankJSXText(child: TSESTree.JSXChild): child is TSESTree.JSXText {
+  return child.type === 'JSXText' && !/\S/.test(child.value);
+}
+
+function trimBlankJSXText(children: TSESTree.JSXChild[]): TSESTree.JSXChild[] {
+  return children.filter((child, index, arr) => {
+    const isSurrounding = index === 0 || index === arr.length - 1;
+    return !(isSurrounding && isBlankJSXText(child));
+  });
+}
+
+function isWrapperTag(node: TSESTree.JSXElement): boolean {
+  const tagName = getTagName(node.openingElement);
+  return tagName !== null && WRAPPER_TAGS.includes(tagName);
+}
+
+function isFragmentTag(node: TSESTree.JSXElement): boolean {
+  return getTagName(node.openingElement) === 'React.Fragment';
+}
+
+function isJSXElement(node: unknown): node is TSESTree.JSXElement {
+  return (node as TSESTree.BaseNode).type === 'JSXElement';
+}
+
+function isJSXFragment(node: unknown): node is TSESTree.JSXFragment {
+  return (node as TSESTree.BaseNode).type === 'JSXFragment';
+}
+
+/**
+ * Resolves the function body statements from a function-like declaration.
+ * Handles FunctionDeclaration, ArrowFunctionExpression, and FunctionExpression.
+ */
+function getFunctionBody(declaration: FunctionLikeNode): Node[] | null {
+  if (declaration.type === 'FunctionDeclaration' && declaration.body) {
+    return declaration.body.body;
+  }
+  if (declaration.type === 'ArrowFunctionExpression' || declaration.type === 'FunctionExpression') {
+    if (declaration.body.type === 'BlockStatement') {
+      return declaration.body.body;
+    }
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Gets the implicit return expression from an arrow function with expression body.
+ */
+function getImplicitReturn(declaration: FunctionLikeNode): Node | null {
+  if (
+    declaration.type === 'ArrowFunctionExpression' &&
+    declaration.body.type !== 'BlockStatement'
+  ) {
+    return declaration.body;
+  }
+  return null;
+}
+
+/**
+ * Gets the name of a function-like node.
+ * For FunctionDeclaration, returns the id name.
+ */
+function getFunctionName(node: Node): string | null {
+  if (node.type === 'FunctionDeclaration' && node.id) {
+    return node.id.name;
+  }
+  return null;
+}
+
+/**
+ * Unwraps call expressions (e.g. React.forwardRef, React.memo) to find the
+ * inner function argument. Returns the node itself if it is already a function.
+ */
+function unwrapCallExpression(node: Node): Node | null {
+  if (
+    node.type === 'ArrowFunctionExpression' ||
+    node.type === 'FunctionExpression' ||
+    node.type === 'FunctionDeclaration'
+  ) {
+    return node;
+  }
+  if (node.type === 'CallExpression') {
+    for (const arg of node.arguments) {
+      if (arg.type !== 'SpreadElement') {
+        const inner = unwrapCallExpression(arg);
+        if (inner) {
+          return inner;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+interface NamedExportFunction {
+  name: string | null;
+  node: FunctionLikeNode;
+}
+
+interface PreviewResult {
+  nodes: TSESTree.JSXChild[];
+  /** Whether the preview nodes are inside a wrapper element (fix can insert JSX comments) */
+  insideWrapper: boolean;
+}
+
+/**
+ * Determines the preview nodes from a returned JSX value.
+ * Wrappers (div, Box, Stack, fragments) are unwrapped to their trimmed children.
+ * Non-wrapper elements are returned as-is.
+ */
+function getPreviewNodes(returnedJSX: unknown): PreviewResult | null {
+  if (isJSXElement(returnedJSX)) {
+    if (
+      (isWrapperTag(returnedJSX) || isFragmentTag(returnedJSX)) &&
+      returnedJSX.children.length > 0
+    ) {
+      const trimmed = trimBlankJSXText(returnedJSX.children);
+      if (trimmed.length > 0) {
+        return { nodes: trimmed, insideWrapper: true };
+      }
+    }
+    return { nodes: [returnedJSX], insideWrapper: false };
+  }
+  if (isJSXFragment(returnedJSX) && returnedJSX.children.length > 0) {
+    const trimmed = trimBlankJSXText(returnedJSX.children);
+    if (trimmed.length > 0) {
+      return { nodes: trimmed, insideWrapper: true };
+    }
+  }
+  return null;
+}
+
+/**
+ * ESLint rule requiring demo files to have highlight-focus comments around the preview section.
+ */
+export const lintJavascriptDemoFocus = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Require demo files to have @highlight-start @focus / @highlight-end comments around the preview section.',
+    },
+    fixable: 'code',
+    messages: {
+      missingDemoFocusJsx:
+        'Demo file is missing {/* @highlight-start @focus */} and {/* @highlight-end */} comments around the preview section. Run with --fix to add them automatically.',
+      missingDemoFocusJsxSingle:
+        'Demo file is missing {/* @highlight @focus */} comment on the preview line. Run with --fix to add it automatically.',
+      missingDemoFocusJs:
+        'Demo file is missing // @highlight-start @focus and // @highlight-end comments around the preview section. Run with --fix to add them automatically.',
+      missingDemoFocusJsSingle:
+        'Demo file is missing // @highlight @focus comment on the preview line. Run with --fix to add it automatically.',
+      missingDemoFocusBody:
+        'Demo file is missing // @highlight-start @focus and // @highlight-end comments around the function body. Run with --fix to add them automatically.',
+    } as const,
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          wrapReturn: {
+            type: 'boolean',
+            description:
+              'When true, bare return statements without parentheses are wrapped in return (...) and the highlight comment is placed inside the parentheses.',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  } as const,
+  create(context) {
+    const sourceCode = context.sourceCode;
+    const sourceText = sourceCode.getText();
+
+    const options = (context.options[0] ?? {}) as { wrapReturn?: boolean };
+
+    if (sourceText.includes('@highlight')) {
+      return {};
+    }
+
+    function processFunctionNode(declaration: FunctionLikeNode): void {
+      const implicitReturn = getImplicitReturn(declaration);
+      if (implicitReturn) {
+        const result = getPreviewNodes(implicitReturn);
+        if (result) {
+          reportPreview(context, sourceCode, result, null, options);
+        }
+        return;
+      }
+
+      const body = getFunctionBody(declaration);
+      if (!body || body.length === 0) {
+        return;
+      }
+
+      // If the body has more than just a return (e.g. hooks, variables),
+      // highlight the entire function body
+      const hasSetupStatements = body.length > 1 || body[0].type !== 'ReturnStatement';
+      if (hasSetupStatements) {
+        const firstStatement = body[0];
+        const lastStatement = body[body.length - 1];
+        reportFunctionBody(context, sourceCode, firstStatement, lastStatement);
+        return;
+      }
+
+      const lastReturn = body[0] as Node & { argument: Node | null };
+      if (!lastReturn.argument) {
+        return;
+      }
+
+      const result = getPreviewNodes(lastReturn.argument);
+      if (result) {
+        reportPreview(context, sourceCode, result, lastReturn, options);
+      }
+    }
+
+    let handled = false;
+    const namedExportFunctions: NamedExportFunction[] = [];
+
+    return {
+      ExportDefaultDeclaration(node: ExportDefaultDeclaration & Rule.NodeParentExtension) {
+        handled = true;
+        const inner = unwrapCallExpression(node.declaration as Node);
+        processFunctionNode(inner ?? node.declaration);
+      },
+
+      ExportNamedDeclaration(node: ExportNamedDeclaration & Rule.NodeParentExtension) {
+        const { declaration } = node;
+        if (!declaration) {
+          return;
+        }
+        if (declaration.type === 'FunctionDeclaration') {
+          namedExportFunctions.push({ name: getFunctionName(declaration), node: declaration });
+          return;
+        }
+        // Handle `export const Demo = () => ...`, `export const Demo = function() ...`,
+        // and call-wrapped patterns like `export const Demo = React.forwardRef(function() ...)`
+        if (declaration.type === 'VariableDeclaration') {
+          for (const declarator of declaration.declarations) {
+            if (declarator.init) {
+              const inner = unwrapCallExpression(declarator.init);
+              if (inner) {
+                const name = declarator.id.type === 'Identifier' ? declarator.id.name : null;
+                namedExportFunctions.push({ name, node: inner });
+              }
+            }
+          }
+        }
+      },
+
+      'Program:exit'() {
+        if (handled || namedExportFunctions.length === 0) {
+          return;
+        }
+
+        const filename = path.basename(context.filename, path.extname(context.filename));
+
+        // Strategy 1: find an exported function whose name matches the filename
+        const filenameMatch = namedExportFunctions.find((fn) => fn.name === filename);
+        if (filenameMatch) {
+          processFunctionNode(filenameMatch.node);
+          return;
+        }
+
+        // Strategy 2: if there's exactly one exported function, use it
+        if (namedExportFunctions.length === 1) {
+          processFunctionNode(namedExportFunctions[0].node);
+        }
+      },
+    };
+  },
+} satisfies Rule.RuleModule;
+
+function reportPreview(
+  context: Rule.RuleContext,
+  sourceCode: Rule.RuleContext['sourceCode'],
+  { nodes: previewNodes, insideWrapper }: PreviewResult,
+  returnStatement: Node | null,
+  options: { wrapReturn?: boolean },
+): void {
+  const firstNode = previewNodes[0];
+  const lastNode = previewNodes[previewNodes.length - 1];
+  const isSingleLine = firstNode.loc.start.line === lastNode.loc.end.line;
+
+  const firstLine = sourceCode.lines[firstNode.loc.start.line - 1];
+  const indentation = firstLine.match(/^\s*/)?.[0] ?? '';
+
+  let messageId: string;
+  if (insideWrapper) {
+    messageId = isSingleLine ? 'missingDemoFocusJsxSingle' : 'missingDemoFocusJsx';
+  } else {
+    messageId = isSingleLine ? 'missingDemoFocusJsSingle' : 'missingDemoFocusJs';
+  }
+
+  context.report({
+    loc: {
+      start: firstNode.loc.start,
+      end: lastNode.loc.end,
+    },
+    messageId,
+    fix(fixer) {
+      if (insideWrapper && isSingleLine) {
+        return fixer.insertTextBeforeRange(
+          firstNode.range,
+          `{/* @highlight @focus */}\n${indentation}`,
+        );
+      }
+      if (insideWrapper) {
+        return [
+          fixer.insertTextBeforeRange(
+            firstNode.range,
+            `{/* @highlight-start @focus */}\n${indentation}`,
+          ),
+          fixer.insertTextAfterRange(lastNode.range, `\n${indentation}{/* @highlight-end */}`),
+        ];
+      }
+
+      // Non-wrapper: wrapReturn wraps bare `return <X>` in `return (\n  // comment\n  <X>\n)`
+      if (options.wrapReturn && returnStatement) {
+        const hasParens = hasReturnParens(sourceCode, returnStatement);
+
+        if (hasParens) {
+          // Already `return (...)` — just insert the comment inside
+          const lineStartOffset = sourceCode.getIndexFromLoc({
+            line: firstNode.loc.start.line,
+            column: 0,
+          });
+          if (isSingleLine) {
+            return fixer.insertTextBeforeRange(
+              [lineStartOffset, lineStartOffset],
+              `${indentation}// @highlight @focus\n`,
+            );
+          }
+          const lastLineStartOffset = sourceCode.getIndexFromLoc({
+            line: lastNode.loc.end.line,
+            column: 0,
+          });
+          const lastLine = sourceCode.lines[lastNode.loc.end.line - 1];
+          const lastIndentation = lastLine.match(/^\s*/)?.[0] ?? '';
+          return [
+            fixer.insertTextBeforeRange(
+              [lineStartOffset, lineStartOffset],
+              `${indentation}// @highlight-start @focus\n`,
+            ),
+            fixer.insertTextAfterRange(
+              [lastLineStartOffset, lastLineStartOffset + lastLine.length],
+              `\n${lastIndentation}// @highlight-end`,
+            ),
+          ];
+        }
+
+        // No parens — wrap `return <X>` into `return (\n  // comment\n  <X>\n)`
+        const returnKeywordEnd = returnStatement.range![0] + 'return'.length;
+        const returnIndentation =
+          sourceCode.lines[returnStatement.loc!.start.line - 1].match(/^\s*/)?.[0] ?? '';
+        const innerIndentation = `${returnIndentation}  `;
+
+        if (isSingleLine) {
+          return [
+            fixer.replaceTextRange(
+              [returnKeywordEnd, firstNode.range[0]],
+              ` (\n${innerIndentation}// @highlight @focus\n${innerIndentation}`,
+            ),
+            fixer.insertTextAfterRange(lastNode.range, `\n${returnIndentation})`),
+          ];
+        }
+        return [
+          fixer.replaceTextRange(
+            [returnKeywordEnd, firstNode.range[0]],
+            ` (\n${innerIndentation}// @highlight-start @focus\n${innerIndentation}`,
+          ),
+          fixer.insertTextAfterRange(
+            lastNode.range,
+            `\n${innerIndentation}// @highlight-end\n${returnIndentation})`,
+          ),
+        ];
+      }
+
+      // Default non-wrapper: insert JS comment at the start of the line
+      const lineStartOffset = sourceCode.getIndexFromLoc({
+        line: firstNode.loc.start.line,
+        column: 0,
+      });
+      if (isSingleLine) {
+        return fixer.insertTextBeforeRange(
+          [lineStartOffset, lineStartOffset],
+          `${indentation}// @highlight @focus\n`,
+        );
+      }
+      const lastLineStartOffset = sourceCode.getIndexFromLoc({
+        line: lastNode.loc.end.line,
+        column: 0,
+      });
+      const lastLine = sourceCode.lines[lastNode.loc.end.line - 1];
+      const lastIndentation = lastLine.match(/^\s*/)?.[0] ?? '';
+      return [
+        fixer.insertTextBeforeRange(
+          [lineStartOffset, lineStartOffset],
+          `${indentation}// @highlight-start @focus\n`,
+        ),
+        fixer.insertTextAfterRange(
+          [lastLineStartOffset, lastLineStartOffset + lastLine.length],
+          `\n${lastIndentation}// @highlight-end`,
+        ),
+      ];
+    },
+  });
+}
+
+/**
+ * Checks whether a return statement's argument is wrapped in parentheses.
+ */
+function hasReturnParens(
+  sourceCode: Rule.RuleContext['sourceCode'],
+  returnStatement: Node,
+): boolean {
+  const text = sourceCode.getText(returnStatement as Rule.Node);
+  const afterReturn = text.slice('return'.length).trimStart();
+  return afterReturn.startsWith('(');
+}
+
+/**
+ * Reports when the entire function body should be highlighted (e.g. when there are hooks/setup).
+ */
+function reportFunctionBody(
+  context: Rule.RuleContext,
+  sourceCode: Rule.RuleContext['sourceCode'],
+  firstStatement: Node,
+  lastStatement: Node,
+): void {
+  const firstLine = sourceCode.lines[firstStatement.loc!.start.line - 1];
+  const indentation = firstLine.match(/^\s*/)?.[0] ?? '';
+
+  const lastLine = sourceCode.lines[lastStatement.loc!.end.line - 1];
+  const lastIndentation = lastLine.match(/^\s*/)?.[0] ?? '';
+
+  const lineStartOffset = sourceCode.getIndexFromLoc({
+    line: firstStatement.loc!.start.line,
+    column: 0,
+  });
+  const lastLineStartOffset = sourceCode.getIndexFromLoc({
+    line: lastStatement.loc!.end.line,
+    column: 0,
+  });
+
+  context.report({
+    loc: {
+      start: firstStatement.loc!.start,
+      end: lastStatement.loc!.end,
+    },
+    messageId: 'missingDemoFocusBody',
+    fix(fixer) {
+      return [
+        fixer.insertTextBeforeRange(
+          [lineStartOffset, lineStartOffset],
+          `${indentation}// @highlight-start @focus\n`,
+        ),
+        fixer.insertTextAfterRange(
+          [lastLineStartOffset, lastLineStartOffset + lastLine.length],
+          `\n${lastIndentation}// @highlight-end`,
+        ),
+      ];
+    },
+  });
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4be53bfb1..10c68ea21 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -28,6 +28,9 @@ importers:
       '@mui/internal-code-infra':
         specifier: workspace:*
         version: link:packages/code-infra
+      '@mui/internal-docs-infra':
+        specifier: workspace:*
+        version: link:packages/docs-infra/build
       '@mui/internal-netlify-cache':
         specifier: workspace:*
         version: link:packages/netlify-cache
@@ -907,6 +910,9 @@ importers:
       '@types/yargs':
         specifier: 17.0.35
         version: 17.0.35
+      '@typescript-eslint/utils':
+        specifier: ^8.57.1
+        version: 8.57.1(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)
       estree-util-to-js:
         specifier: 2.0.0
         version: 2.0.0

From e8eff01a117ac4985798524591d721953dca20a9 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 14 Apr 2026 21:42:50 -0400
Subject: [PATCH 02/44] Add `@focus-start`, `@focus-end`

---
 .../code-highlighter/demos/CodeContent.tsx    |   4 +-
 .../demos/CodeContentLoading.tsx              |   4 +-
 .../code-highlighter/demos/code/page.tsx      |   4 +-
 .../demos/code-editor/CodeController.tsx      |   4 +-
 .../demos/code-editor/CodeEditor.tsx          |   4 +-
 .../demos/code-editor/CodeEditorContent.tsx   |   4 +-
 .../demos/demo-live/DemoController.tsx        |   4 +-
 .../demos/demo-live/DemoLive.tsx              |   4 +-
 .../demos/demo-live/DemoLiveContent.tsx       |   4 +-
 .../demo-live/demo-basic/CheckboxBasic.tsx    |   4 +-
 .../demos/multi-file/MultiFileContent.tsx     |   4 +-
 .../demos/multi-file/MultiFileEditor.tsx      |   4 +-
 .../code-highlighter/demos/CodeBlock.tsx      |   4 +-
 .../code-highlighter/demos/CodeContent.tsx    |   4 +-
 .../code-highlighter/demos/DemoContent.tsx    |   4 +-
 .../demos/code-basic/BasicCode.tsx            |   2 +-
 .../demos/code-highlight-idle/BasicCode.tsx   |   2 +-
 .../demos/code-highlight-idle/Code.tsx        |   4 +-
 .../demos/code-highlight-init/BasicCode.tsx   |   2 +-
 .../demos/code-highlight-init/Code.tsx        |   4 +-
 .../demos/code-transformed/BasicCode.tsx      |   2 +-
 .../demos/code-transformed/Code.tsx           |   4 +-
 .../DemoContentLoading.tsx                    |   4 +-
 .../demo-red/CheckboxRed.tsx                  |   2 +-
 .../DemoContentLoading.tsx                    |   4 +-
 .../demo-red/css-modules/CheckboxRed.tsx      |   2 +-
 .../demo-red/tailwind/CheckboxRed.tsx         |   2 +-
 .../demo-fallback/DemoContentLoading.tsx      |   4 +-
 .../demo-fallback/demo-red/CheckboxRed.tsx    |   2 +-
 .../demo-basic/CheckboxBasic.tsx              |   2 +-
 .../demo-default/css-modules/CheckboxRed.tsx  |   2 +-
 .../demo-default/tailwind/CheckboxRed.tsx     |   2 +-
 .../demos/demo/demo-basic/CheckboxBasic.tsx   |   2 +-
 .../components/code-provider/demos/Code.tsx   |   4 +-
 .../code-provider/demos/base/BasicCode.tsx    |   4 +-
 .../demos/fetch-demo/CodeProviderGitHub.tsx   |   4 +-
 .../code-provider/demos/fetch-demo/Docs.tsx   |   4 +-
 .../fetch-demo/demo-basic/CheckboxBasic.tsx   |   2 +-
 .../demos/text-input-copy/TextInputCopy.tsx   |   4 +-
 .../variant-selector/VariantSelector.tsx      |   4 +-
 .../hooks/use-types/demos/TypesTable.tsx      |   4 +-
 .../hooks/use-types/demos/basic/Component.tsx |   4 +-
 .../Component/Part/ComponentPart.tsx          |   4 +-
 .../Component/Root/ComponentRoot.tsx          |   4 +-
 .../demos/blocks-data-attr/TypesComponent.tsx |   4 +-
 .../AlertDialog/AlertDialogTrigger.tsx        |   2 +-
 .../blocks-inherited/Dialog/DialogClose.tsx   |   4 +-
 .../blocks-inherited/Dialog/DialogTrigger.tsx |   4 +-
 .../blocks-inherited/TypesAlertDialog.tsx     |   4 +-
 .../demos/blocks/Component/ComponentPart.tsx  |   4 +-
 .../demos/blocks/Component/ComponentRoot.tsx  |   4 +-
 .../use-types/demos/blocks/TypesComponent.tsx |   4 +-
 .../use-types/demos/data-attr/Component.tsx   |   4 +-
 .../demos/tab-navigation/TabNavigation.tsx    |   4 +-
 .../demos/CodeIndent.tsx                      |   4 +-
 .../demos/CollapsibleContent.module.css       |   8 +-
 .../demos/CollapsibleContent.tsx              |   4 +-
 .../demos/IndentContent.module.css            |  40 ++++--
 .../demos/IndentContent.tsx                   |   4 +-
 .../demos/focus-code/FocusCode.tsx            |  15 ++-
 .../demos/indent-code/IndentCode.tsx          |  15 ++-
 .../pipeline/enhance-code-emphasis/page.mdx   |  78 +++++++----
 .../pipeline/enhance-code-emphasis/types.md   |  18 ++-
 .../lint-javascript-demo-focus/page.mdx       |  24 ++--
 docs/app/docs-infra/pipeline/page.mdx         |   3 +-
 .../enhanceCodeEmphasis.test.ts               | 107 +++++++++++++--
 .../enhanceCodeEmphasis.ts                    | 122 +++++++++++-------
 .../lintJavascriptDemoFocus.test.ts           | 108 ++++++++++------
 .../lintJavascriptDemoFocus.ts                |  63 ++++-----
 .../loadPrecomputedCodeHighlighter.ts         |   3 +
 .../parseSource/calculateFrameRanges.test.ts  |  98 ++++++++------
 .../parseSource/calculateFrameRanges.ts       |  34 ++++-
 .../src/pipeline/parseSource/createFrame.ts   |   7 +-
 .../pipeline/parseSource/restructureFrames.ts |  19 ++-
 .../transformHtmlCodeBlock.ts                 |   5 +-
 75 files changed, 623 insertions(+), 344 deletions(-)

diff --git a/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx b/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx
index fb73829ff..21a4e94e1 100644
--- a/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx
+++ b/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx
@@ -10,9 +10,9 @@ import styles from './CodeContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function CodeContent(props: ContentProps<{}>) {
-  // @highlight-start @focus
+  // @focus-start
   const code = useCode(props, { preClassName: styles.codeBlock });
 
   return <div className={styles.code}>{code.selectedFile}</div>;
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx b/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx
index 051462704..0eb128a2d 100644
--- a/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx
+++ b/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx
@@ -9,11 +9,11 @@ import '@wooorm/starry-night/style/light';
 export function CodeContentLoading(props: ContentLoadingProps<{}>) {
   return (
     <div>
-      {/* @highlight-start @focus */}
+      {/* @focus-start */}
       <div className={styles.code}>
         <pre className={styles.codeBlock}>{props.source}</pre>
       </div>
-      {/* @highlight-end */}
+      {/* @focus-end */}
     </div>
   );
 }
diff --git a/docs/app/bench/docs-infra/components/code-highlighter/demos/code/page.tsx b/docs/app/bench/docs-infra/components/code-highlighter/demos/code/page.tsx
index 4f30b08f5..94910edd0 100644
--- a/docs/app/bench/docs-infra/components/code-highlighter/demos/code/page.tsx
+++ b/docs/app/bench/docs-infra/components/code-highlighter/demos/code/page.tsx
@@ -11,7 +11,7 @@ const sourceParser = createParseSource();
 
 export default function Page() {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeHighlighter
       Content={CodeContent}
       ContentLoading={CodeContentLoading}
@@ -20,6 +20,6 @@ export default function Page() {
     >
       {code}
     </CodeHighlighter>
-    // @highlight-end
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx
index 1fa4b43ae..8af4ab665 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx
@@ -5,7 +5,7 @@ import { CodeControllerContext } from '@mui/internal-docs-infra/CodeControllerCo
 import type { ControlledCode } from '@mui/internal-docs-infra/CodeHighlighter/types';
 
 export function CodeController({ children }: { children: React.ReactNode }) {
-  // @highlight-start @focus
+  // @focus-start
   const [code, setCode] = React.useState<ControlledCode | undefined>(undefined);
 
   const contextValue = React.useMemo(() => ({ code, setCode }), [code, setCode]);
@@ -13,5 +13,5 @@ export function CodeController({ children }: { children: React.ReactNode }) {
   return (
     <CodeControllerContext.Provider value={contextValue}>{children}</CodeControllerContext.Provider>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditor.tsx b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditor.tsx
index 87790c3d3..171e4a180 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditor.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditor.tsx
@@ -20,7 +20,7 @@ function greet(name) {
 
 export function CodeEditor() {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeProvider>
       <CodeController>
         <CodeHighlighter
@@ -32,6 +32,6 @@ export function CodeEditor() {
         />
       </CodeController>
     </CodeProvider>
-    // @highlight-end
+    // @focus-end
   );
 }
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 2fc5bdeef..92e8ec567 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
@@ -10,7 +10,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>) {
-  // @highlight-start @focus
+  // @focus-start
   const preRef = React.useRef<HTMLPreElement | null>(null);
   const code = useCode(props, { preClassName: styles.codeBlock, preRef });
 
@@ -48,5 +48,5 @@ export function CodeEditorContent(props: ContentProps<object>) {
       <div className={styles.code}>{code.selectedFile}</div>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx
index c3bb22508..e737e9f2c 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx
@@ -27,7 +27,7 @@ function Runner({ code }: { code: string }) {
 }
 
 export function DemoController({ children }: { children: React.ReactNode }) {
-  // @highlight-start @focus
+  // @focus-start
   const [code, setCode] = React.useState<ControlledCode | undefined>(undefined);
 
   const components = React.useMemo(
@@ -57,5 +57,5 @@ export function DemoController({ children }: { children: React.ReactNode }) {
   return (
     <CodeControllerContext.Provider value={contextValue}>{children}</CodeControllerContext.Provider>
   );
-  // @highlight-end
+  // @focus-end
 }
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 b0b3103ec..bdeaa435b 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
@@ -5,12 +5,12 @@ import { DemoCheckboxBasic } from './demo-basic';
 
 export function DemoLive() {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeProvider>
       <DemoController>
         <DemoCheckboxBasic />
       </DemoController>
     </CodeProvider>
-    // @highlight-end
+    // @focus-end
   );
 }
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 a72cab791..129dfc5cc 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
@@ -16,7 +16,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function DemoLiveContent(props: ContentProps<object>) {
-  // @highlight-start @focus
+  // @focus-start
   const preRef = React.useRef<HTMLPreElement | null>(null);
   const demo = useDemo(props, { preClassName: styles.codeBlock, preRef });
 
@@ -86,5 +86,5 @@ export function DemoLiveContent(props: ContentProps<object>) {
       </div>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
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 545677549..68a44a51b 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,10 +4,10 @@ import { Checkbox } from '@/components/Checkbox';
 export default function CheckboxBasic() {
   return (
     <div>
-      {/* @highlight-start @focus */}
+      {/* @focus-start */}
       <Checkbox defaultChecked />
       <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>
-      {/* @highlight-end */}
+      {/* @focus-end */}
     </div>
   );
 }
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 561f3fdc6..925b3dcf0 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
@@ -10,7 +10,7 @@ import styles from '../code-editor/CodeEditorContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function MultiFileContent(props: ContentProps<object>) {
-  // @highlight-start @focus
+  // @focus-start
   const preRef = React.useRef<HTMLPreElement | null>(null);
   const code = useCode(props, { preClassName: styles.codeBlock, preRef });
 
@@ -44,5 +44,5 @@ export function MultiFileContent(props: ContentProps<object>) {
       <div className={styles.code}>{code.selectedFile}</div>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileEditor.tsx b/docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileEditor.tsx
index ae0a21e80..9552bc272 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileEditor.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileEditor.tsx
@@ -43,7 +43,7 @@ p {
 
 export function MultiFileEditor() {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeProvider>
       <CodeController>
         <CodeHighlighter
@@ -55,6 +55,6 @@ export function MultiFileEditor() {
         />
       </CodeController>
     </CodeProvider>
-    // @highlight-end
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/CodeBlock.tsx b/docs/app/docs-infra/components/code-highlighter/demos/CodeBlock.tsx
index c48a91b17..051be9fe5 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/CodeBlock.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/CodeBlock.tsx
@@ -19,7 +19,7 @@ export function Code({
   fileName?: string;
 }) {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeHighlighter
       language={language}
       fileName={fileName}
@@ -28,6 +28,6 @@ export function Code({
     >
       {children}
     </CodeHighlighter>
-    // @highlight-end
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.tsx b/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.tsx
index b148d9dac..69019e0e9 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.tsx
@@ -16,7 +16,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function CodeContent(props: ContentProps<object>) {
-  // @highlight-start @focus
+  // @focus-start
   const code = useCode(props, { preClassName: styles.codeBlock });
 
   const hasJsTransform = code.availableTransforms.includes('js');
@@ -86,5 +86,5 @@ export function CodeContent(props: ContentProps<object>) {
       </div>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.tsx b/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.tsx
index a6bbc87a4..28c5ef380 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.tsx
@@ -16,7 +16,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function DemoContent(props: ContentProps<object>) {
-  // @highlight-start @focus
+  // @focus-start
   const demo = useDemo(props, { preClassName: styles.codeBlock });
 
   const hasJsTransform = demo.availableTransforms.includes('js');
@@ -83,5 +83,5 @@ export function DemoContent(props: ContentProps<object>) {
       </div>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-basic/BasicCode.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-basic/BasicCode.tsx
index 4c2fadb7c..bf4d23d95 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-basic/BasicCode.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-basic/BasicCode.tsx
@@ -3,7 +3,7 @@ import { Code } from '../CodeBlock';
 
 export function BasicCode() {
   return (
-    // @highlight @focus
+    // @focus
     <Code fileName="hello.js">{`console.log('Hello, world!');`}</Code>
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/BasicCode.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/BasicCode.tsx
index 58ed4229f..e54933609 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/BasicCode.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/BasicCode.tsx
@@ -3,7 +3,7 @@ import { Code } from './Code';
 
 export function BasicCode() {
   return (
-    // @highlight @focus
+    // @focus
     <Code fileName="hello.js">{`console.log('Hello, world!');`}</Code>
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/Code.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/Code.tsx
index 535f2155b..e3fa7f597 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/Code.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/Code.tsx
@@ -10,7 +10,7 @@ const sourceParser = createParseSource();
 
 export function Code({ children, fileName }: { children: string; fileName?: string }) {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeHighlighter
       fileName={fileName}
       Content={CodeContent}
@@ -19,6 +19,6 @@ export function Code({ children, fileName }: { children: string; fileName?: stri
     >
       {children}
     </CodeHighlighter>
-    // @highlight-end
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/BasicCode.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/BasicCode.tsx
index 58ed4229f..e54933609 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/BasicCode.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/BasicCode.tsx
@@ -3,7 +3,7 @@ import { Code } from './Code';
 
 export function BasicCode() {
   return (
-    // @highlight @focus
+    // @focus
     <Code fileName="hello.js">{`console.log('Hello, world!');`}</Code>
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/Code.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/Code.tsx
index 535f2155b..e3fa7f597 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/Code.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/Code.tsx
@@ -10,7 +10,7 @@ const sourceParser = createParseSource();
 
 export function Code({ children, fileName }: { children: string; fileName?: string }) {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeHighlighter
       fileName={fileName}
       Content={CodeContent}
@@ -19,6 +19,6 @@ export function Code({ children, fileName }: { children: string; fileName?: stri
     >
       {children}
     </CodeHighlighter>
-    // @highlight-end
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/BasicCode.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/BasicCode.tsx
index 3e7874e6b..dc2573e5d 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/BasicCode.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/BasicCode.tsx
@@ -3,7 +3,7 @@ import { Code } from './Code';
 
 export function BasicCode() {
   return (
-    // @highlight @focus
+    // @focus
     <Code fileName="example.ts">{`const x: number = 1;\ninterface Props { name: string; }`}</Code>
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/Code.tsx b/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/Code.tsx
index c2993c64e..3b519dbdd 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/Code.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/code-transformed/Code.tsx
@@ -10,7 +10,7 @@ const sourceTransformers = [TypescriptToJavascriptTransformer];
 
 export function Code({ children, fileName }: { children: string; fileName?: string }) {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeHighlighter
       fileName={fileName}
       Content={CodeContent}
@@ -19,6 +19,6 @@ export function Code({ children, fileName }: { children: string; fileName?: stri
     >
       {children}
     </CodeHighlighter>
-    // @highlight-end
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx
index 05b382f6d..73329fef5 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx
@@ -9,7 +9,7 @@ import loadingStyles from './DemoContentLoading.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function DemoContentLoading(props: ContentLoadingProps<object>) {
-  // @highlight-start @focus
+  // @focus-start
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -58,5 +58,5 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
       </div>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/demo-red/CheckboxRed.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/demo-red/CheckboxRed.tsx
index 8322e4428..86db42ccc 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/demo-red/CheckboxRed.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/demo-red/CheckboxRed.tsx
@@ -4,7 +4,7 @@ import styles from './CheckboxRed.module.css';
 
 export function CheckboxRed() {
   return (
-    // @highlight @focus
+    // @focus
     <Checkbox className={styles.root} defaultChecked />
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx
index 78c2658fd..6482adb9a 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx
@@ -14,7 +14,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function DemoContentLoading(props: ContentLoadingProps<object>) {
-  // @highlight-start @focus
+  // @focus-start
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -90,5 +90,5 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
       </div>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/css-modules/CheckboxRed.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/css-modules/CheckboxRed.tsx
index 03a0be5a8..c38da79d1 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/css-modules/CheckboxRed.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/css-modules/CheckboxRed.tsx
@@ -5,7 +5,7 @@ import styles from './CheckboxRed.module.css';
 
 export function CheckboxRed() {
   return (
-    // @highlight @focus
+    // @focus
     <Checkbox defaultChecked className={styles.root} />
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/tailwind/CheckboxRed.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/tailwind/CheckboxRed.tsx
index 7dfbea8d1..bfe6e82c4 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/tailwind/CheckboxRed.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/tailwind/CheckboxRed.tsx
@@ -3,7 +3,7 @@ import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxRed() {
   return (
-    // @highlight @focus
+    // @focus
     <Checkbox defaultChecked className="bg-red-500" />
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx
index faa341b65..493d2cc3a 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx
@@ -8,7 +8,7 @@ import styles from '../DemoContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function DemoContentLoading(props: ContentLoadingProps<object>) {
-  // @highlight-start @focus
+  // @focus-start
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -52,5 +52,5 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
       </div>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/demo-red/CheckboxRed.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/demo-red/CheckboxRed.tsx
index 8322e4428..86db42ccc 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/demo-red/CheckboxRed.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/demo-red/CheckboxRed.tsx
@@ -4,7 +4,7 @@ import styles from './CheckboxRed.module.css';
 
 export function CheckboxRed() {
   return (
-    // @highlight @focus
+    // @focus
     <Checkbox className={styles.root} defaultChecked />
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-server-loaded/demo-basic/CheckboxBasic.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-server-loaded/demo-basic/CheckboxBasic.tsx
index 74d562e6d..30e1d8fa8 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-server-loaded/demo-basic/CheckboxBasic.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-server-loaded/demo-basic/CheckboxBasic.tsx
@@ -3,7 +3,7 @@ import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxBasic() {
   return (
-    // @highlight @focus
+    // @focus
     <Checkbox defaultChecked />
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/css-modules/CheckboxRed.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/css-modules/CheckboxRed.tsx
index 03a0be5a8..c38da79d1 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/css-modules/CheckboxRed.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/css-modules/CheckboxRed.tsx
@@ -5,7 +5,7 @@ import styles from './CheckboxRed.module.css';
 
 export function CheckboxRed() {
   return (
-    // @highlight @focus
+    // @focus
     <Checkbox defaultChecked className={styles.root} />
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/tailwind/CheckboxRed.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/tailwind/CheckboxRed.tsx
index de96d696e..6804e9994 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/tailwind/CheckboxRed.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/tailwind/CheckboxRed.tsx
@@ -3,7 +3,7 @@ import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxRed() {
   return (
-    // @highlight @focus
+    // @focus
     <Checkbox defaultChecked className="bg-red-500 border-red-500" />
   );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo/demo-basic/CheckboxBasic.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo/demo-basic/CheckboxBasic.tsx
index 74d562e6d..30e1d8fa8 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo/demo-basic/CheckboxBasic.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo/demo-basic/CheckboxBasic.tsx
@@ -3,7 +3,7 @@ import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxBasic() {
   return (
-    // @highlight @focus
+    // @focus
     <Checkbox defaultChecked />
   );
 }
diff --git a/docs/app/docs-infra/components/code-provider/demos/Code.tsx b/docs/app/docs-infra/components/code-provider/demos/Code.tsx
index 815b257f3..61b1b6db3 100644
--- a/docs/app/docs-infra/components/code-provider/demos/Code.tsx
+++ b/docs/app/docs-infra/components/code-provider/demos/Code.tsx
@@ -5,10 +5,10 @@ import { CodeContent } from '../../code-highlighter/demos/CodeContent';
 
 export function Code({ children, fileName }: { children: string; fileName?: string }) {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeHighlighter fileName={fileName} Content={CodeContent}>
       {children}
     </CodeHighlighter>
-    // @highlight-end
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-provider/demos/base/BasicCode.tsx b/docs/app/docs-infra/components/code-provider/demos/base/BasicCode.tsx
index a84ee1eea..6d4e98758 100644
--- a/docs/app/docs-infra/components/code-provider/demos/base/BasicCode.tsx
+++ b/docs/app/docs-infra/components/code-provider/demos/base/BasicCode.tsx
@@ -4,10 +4,10 @@ import { Code } from '../../../code-highlighter/demos/CodeBlock';
 
 export function BasicCode() {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeProvider>
       <Code fileName="example.js">{`console.log('Hello, world!');`}</Code>
     </CodeProvider>
-    // @highlight-end
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-provider/demos/fetch-demo/CodeProviderGitHub.tsx b/docs/app/docs-infra/components/code-provider/demos/fetch-demo/CodeProviderGitHub.tsx
index 27a43d362..401c1fc46 100644
--- a/docs/app/docs-infra/components/code-provider/demos/fetch-demo/CodeProviderGitHub.tsx
+++ b/docs/app/docs-infra/components/code-provider/demos/fetch-demo/CodeProviderGitHub.tsx
@@ -90,7 +90,7 @@ const loadSource: LoadSource = async (url: string) => {
 
 export function CodeProviderGitHub({ children }: { children: React.ReactNode }) {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeProvider
       loadCodeMeta={loadCodeMeta}
       loadVariantMeta={loadVariantMeta}
@@ -98,6 +98,6 @@ export function CodeProviderGitHub({ children }: { children: React.ReactNode })
     >
       {children}
     </CodeProvider>
-    // @highlight-end
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-provider/demos/fetch-demo/Docs.tsx b/docs/app/docs-infra/components/code-provider/demos/fetch-demo/Docs.tsx
index 5bdcc5b71..e22a98b84 100644
--- a/docs/app/docs-infra/components/code-provider/demos/fetch-demo/Docs.tsx
+++ b/docs/app/docs-infra/components/code-provider/demos/fetch-demo/Docs.tsx
@@ -4,10 +4,10 @@ import { DemoCheckboxBasic } from './demo-basic';
 
 export function Docs() {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeProviderGitHub>
       <DemoCheckboxBasic />
     </CodeProviderGitHub>
-    // @highlight-end
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-provider/demos/fetch-demo/demo-basic/CheckboxBasic.tsx b/docs/app/docs-infra/components/code-provider/demos/fetch-demo/demo-basic/CheckboxBasic.tsx
index 74d562e6d..30e1d8fa8 100644
--- a/docs/app/docs-infra/components/code-provider/demos/fetch-demo/demo-basic/CheckboxBasic.tsx
+++ b/docs/app/docs-infra/components/code-provider/demos/fetch-demo/demo-basic/CheckboxBasic.tsx
@@ -3,7 +3,7 @@ import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxBasic() {
   return (
-    // @highlight @focus
+    // @focus
     <Checkbox defaultChecked />
   );
 }
diff --git a/docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx b/docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx
index e0498b5e3..b4c4737bb 100644
--- a/docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx
+++ b/docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx
@@ -4,7 +4,7 @@ import { useCopier } from '@mui/internal-docs-infra/useCopier';
 import styles from './TextInputCopy.module.css';
 
 export function TextInputCopy() {
-  // @highlight-start @focus
+  // @focus-start
   const [text, setText] = React.useState('Hello, copy me!');
   const { copy, recentlySuccessful } = useCopier(() => text);
 
@@ -22,5 +22,5 @@ export function TextInputCopy() {
       </button>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx b/docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx
index cbff74e19..c6ab15c29 100644
--- a/docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx
+++ b/docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx
@@ -4,7 +4,7 @@ import { usePreference } from '@mui/internal-docs-infra/usePreference';
 import styles from './VariantSelector.module.css';
 
 export function VariantSelector() {
-  // @highlight-start @focus
+  // @focus-start
   const variants = ['contained', 'outlined', 'text'];
   const [variant, setVariant] = usePreference('variant', variants, () => 'contained');
 
@@ -31,5 +31,5 @@ export function VariantSelector() {
       </div>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx b/docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx
index 0b57a1b57..2815f853b 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx
@@ -20,7 +20,7 @@ export type TypesTableProps = BaseTypesTableProps<{}>;
 
 export function TypesTable(props: TypesTableProps) {
   // Get the main type and additional types for this export
-  // @highlight-start @focus
+  // @focus-start
   const { type, additionalTypes } = useTypes(props);
 
   return (
@@ -38,7 +38,7 @@ export function TypesTable(props: TypesTableProps) {
       ))}
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
 
 function TypeMetaDoc(props: { typeMeta: EnhancedTypesMeta }) {
diff --git a/docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx b/docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx
index 176722c09..02aee0661 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx
@@ -13,7 +13,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function Component(props: Props) {
-  // @highlight-start @focus
+  // @focus-start
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
@@ -24,5 +24,5 @@ export function Component(props: Props) {
       {!props.disabled ? props.children : null}
     </button>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx
index 9a4981349..f2ffc24e5 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx
@@ -22,7 +22,7 @@ export interface ComponentPartProps {
  * A simple component that displays a title and optional children.
  */
 export function ComponentPart(props: ComponentPartProps) {
-  // @highlight-start @focus
+  // @focus-start
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event, props.input);
   };
@@ -33,7 +33,7 @@ export function ComponentPart(props: ComponentPartProps) {
       {!props.disabled ? props.children : null}
     </button>
   );
-  // @highlight-end
+  // @focus-end
 }
 
 // eslint-disable-next-line @typescript-eslint/no-namespace -- Using namespace for type grouping as per Base UI convention
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx
index e41e7dfc1..d6db3e094 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx
@@ -38,7 +38,7 @@ export interface ComponentRootProps {
  * A simple component that displays a title and optional children.
  */
 export function ComponentRoot(props: ComponentRootProps) {
-  // @highlight-start @focus
+  // @focus-start
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
 
@@ -60,7 +60,7 @@ export function ComponentRoot(props: ComponentRootProps) {
       {!props.disabled ? props.children : null}
     </button>
   );
-  // @highlight-end
+  // @focus-end
 }
 
 // eslint-disable-next-line @typescript-eslint/no-namespace -- Using namespace for type grouping as per Base UI convention
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/TypesComponent.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/TypesComponent.tsx
index f4dd9933d..a174bc693 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/TypesComponent.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/TypesComponent.tsx
@@ -4,7 +4,7 @@ import { TypesComponent as ComponentTypes, TypesComponentAdditional } from './ty
 export function TypesComponent() {
   return (
     <div>
-      {/* @highlight-start @focus */}
+      {/* @focus-start */}
       <h3>Component API</h3>
       <h3>Root</h3>
       <ComponentTypes.Root />
@@ -12,7 +12,7 @@ export function TypesComponent() {
       <ComponentTypes.Part />
       <h3>Additional Types</h3>
       <TypesComponentAdditional />
-      {/* @highlight-end */}
+      {/* @focus-end */}
     </div>
   );
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/AlertDialog/AlertDialogTrigger.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/AlertDialog/AlertDialogTrigger.tsx
index bc2104450..366ead7e3 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/AlertDialog/AlertDialogTrigger.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/AlertDialog/AlertDialogTrigger.tsx
@@ -34,7 +34,7 @@ export const AlertDialogTrigger = React.forwardRef(function AlertDialogTrigger(
   ref: React.ForwardedRef<HTMLButtonElement>,
 ) {
   return (
-    // @highlight @focus
+    // @focus
     <DialogTrigger ref={ref} {...(props as DialogTrigger.Props)} />
   );
 });
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx
index 5bf0617c1..4b531db15 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx
@@ -22,7 +22,7 @@ export const DialogClose = React.forwardRef(function DialogClose(
   props: DialogCloseProps,
   ref: React.ForwardedRef<HTMLButtonElement>,
 ) {
-  // @highlight-start @focus
+  // @focus-start
   const { render, children, ...other } = props;
 
   // In a real implementation, triggerState would come from context
@@ -33,7 +33,7 @@ export const DialogClose = React.forwardRef(function DialogClose(
       {render ? render(triggerState) : children}
     </button>
   );
-  // @highlight-end
+  // @focus-end
 });
 
 // eslint-disable-next-line @typescript-eslint/no-namespace, import/export
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx
index 91d110c30..92db61860 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx
@@ -36,7 +36,7 @@ export const DialogTrigger = React.forwardRef(function DialogTrigger(
   props: DialogTriggerProps,
   ref: React.ForwardedRef<HTMLButtonElement>,
 ) {
-  // @highlight-start @focus
+  // @focus-start
   const { className, disabled, children, ...other } = props;
 
   const state: DialogTriggerState = React.useMemo(
@@ -54,7 +54,7 @@ export const DialogTrigger = React.forwardRef(function DialogTrigger(
       {children}
     </button>
   );
-  // @highlight-end
+  // @focus-end
 });
 
 // eslint-disable-next-line @typescript-eslint/no-namespace, import/export
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/TypesAlertDialog.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/TypesAlertDialog.tsx
index 54670f3d9..8bf4d14e0 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/TypesAlertDialog.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/TypesAlertDialog.tsx
@@ -4,13 +4,13 @@ import { TypesAlertDialog as AlertDialogTypes } from './types';
 export function TypesAlertDialog() {
   return (
     <div>
-      {/* @highlight-start @focus */}
+      {/* @focus-start */}
       <h3>Alert Dialog API</h3>
       <h3>Trigger</h3>
       <AlertDialogTypes.Trigger />
       <h3>Close</h3>
       <AlertDialogTypes.Close />
-      {/* @highlight-end */}
+      {/* @focus-end */}
     </div>
   );
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx
index 202a260ac..d2c081591 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx
@@ -13,7 +13,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function ComponentPart(props: Props) {
-  // @highlight-start @focus
+  // @focus-start
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
@@ -24,5 +24,5 @@ export function ComponentPart(props: Props) {
       {!props.disabled ? props.children : null}
     </button>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx
index 44f210999..520cb3949 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx
@@ -13,7 +13,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function ComponentRoot(props: Props) {
-  // @highlight-start @focus
+  // @focus-start
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
@@ -24,5 +24,5 @@ export function ComponentRoot(props: Props) {
       {!props.disabled ? props.children : null}
     </button>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks/TypesComponent.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks/TypesComponent.tsx
index c5d396fdc..f4e049c8a 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks/TypesComponent.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks/TypesComponent.tsx
@@ -4,12 +4,12 @@ import { TypesComponent as ComponentTypes } from './types';
 export function TypesComponent() {
   return (
     <div>
-      {/* @highlight-start @focus */}
+      {/* @focus-start */}
       <h3>ComponentRoot</h3>
       <ComponentTypes.Root />
       <h3>ComponentPart</h3>
       <ComponentTypes.Part />
-      {/* @highlight-end */}
+      {/* @focus-end */}
     </div>
   );
 }
diff --git a/docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx b/docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx
index ef2f76921..2fc2e774c 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx
@@ -14,7 +14,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function Component(props: Props) {
-  // @highlight-start @focus
+  // @focus-start
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
@@ -25,5 +25,5 @@ export function Component(props: Props) {
       {!props.disabled ? props.children : null}
     </button>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx b/docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx
index abe05d012..cea894043 100644
--- a/docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx
+++ b/docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx
@@ -14,7 +14,7 @@ const tabs = [
 ];
 
 export function TabNavigation() {
-  // @highlight-start @focus
+  // @focus-start
   const [hash, setHash] = useUrlHashState();
   const activeTab = hash || 'overview';
 
@@ -40,5 +40,5 @@ export function TabNavigation() {
       </div>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
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 9a0e02ad0..f262e1d4f 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
@@ -20,13 +20,13 @@ const sourceEnhancers = [enhanceCodeEmphasis];
  */
 export function CodeIndent({ code }: { code: CodeType }) {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <CodeHighlighter
       code={code}
       Content={IndentContent}
       sourceParser={sourceParser}
       sourceEnhancers={sourceEnhancers}
     />
-    // @highlight-end
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
index eec6babd9..f2eb0eadc 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
@@ -103,9 +103,10 @@
 
 /* ---- Collapsible frame behavior ---- */
 
-/* Normal frames and unfocused highlighted frames are hidden by default (collapsed) */
+/* Normal frames and unfocused highlighted/focus frames are hidden by default (collapsed) */
 .codeBlock :global(.frame:not([data-frame-type])),
-.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+.codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 0;
   overflow: hidden;
   opacity: 0;
@@ -123,7 +124,8 @@
 
 /* When checkbox is checked (expanded), show all frames */
 .checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
-.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 500px;
   overflow: visible;
   opacity: 1;
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
index 4c6c3a19d..e48a0e786 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
@@ -8,7 +8,7 @@ import styles from './CollapsibleContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function CollapsibleContent(props: ContentProps<object>) {
-  // @highlight-start @focus
+  // @focus-start
   const code = useCode(props, { preClassName: styles.codeBlock });
   const id = React.useId();
   const checkboxId = `${id}-expand`;
@@ -24,5 +24,5 @@ export function CollapsibleContent(props: ContentProps<object>) {
       </label>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
index 7d9b0efde..031de83b3 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
@@ -70,9 +70,10 @@
 
 /* ---- Collapsible frame behavior (no padding, just highlighted vs normal) ---- */
 
-/* Normal frames and unfocused highlighted frames are hidden by default */
+/* Normal frames and unfocused highlighted/focus frames are hidden by default */
 .codeBlock :global(.frame:not([data-frame-type])),
-.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+.codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 0;
   overflow: hidden;
   opacity: 0;
@@ -83,51 +84,62 @@
 
 /* When expanded, show all frames */
 .expanded .codeBlock :global(.frame:not([data-frame-type])),
-.expanded .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+.expanded .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+.expanded .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 500px;
   overflow: visible;
   opacity: 1;
 }
 
-/* ---- Indent shifting: move highlighted frame left by its indent level ---- */
+/* ---- Indent shifting: move highlighted/focus frame left by its indent level ---- */
 
-.codeBlock :global(.frame[data-frame-type='highlighted']) {
+.codeBlock :global(.frame[data-frame-type='highlighted']),
+.codeBlock :global(.frame[data-frame-type='focus']) {
   transition: margin-left 0.3s ease;
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='1']) {
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='1']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='1']) {
   margin-left: -2ch;
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='2']) {
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='2']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='2']) {
   margin-left: -4ch;
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='3']) {
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='3']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='3']) {
   margin-left: -6ch;
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='4']) {
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='4']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='4']) {
   margin-left: -8ch;
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='5']) {
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='5']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='5']) {
   margin-left: -10ch;
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='6']) {
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='6']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='6']) {
   margin-left: -12ch;
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='7']) {
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='7']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='7']) {
   margin-left: -14ch;
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='8']) {
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='8']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='8']) {
   margin-left: -16ch;
 }
 
 /* Reset indent shift when expanded */
-.expanded .codeBlock :global(.frame[data-frame-type='highlighted']) {
+.expanded .codeBlock :global(.frame[data-frame-type='highlighted']),
+.expanded .codeBlock :global(.frame[data-frame-type='focus']) {
   margin-left: 0;
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx
index 2e51765ca..b9cfb1b36 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx
@@ -8,7 +8,7 @@ import styles from './IndentContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function IndentContent(props: ContentProps<object>) {
-  // @highlight-start @focus
+  // @focus-start
   const code = useCode(props, { preClassName: styles.codeBlock });
   const [expanded, setExpanded] = React.useState(false);
 
@@ -20,5 +20,5 @@ export function IndentContent(props: ContentProps<object>) {
       </button>
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/focus-code/FocusCode.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/focus-code/FocusCode.tsx
index 0852a0eef..1cc9100ca 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/focus-code/FocusCode.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/focus-code/FocusCode.tsx
@@ -1,7 +1,10 @@
 import * as React from 'react';
 import type { Code as CodeType } from '@mui/internal-docs-infra/CodeHighlighter/types';
 import { parseImportsAndComments } from '@mui/internal-docs-infra/pipeline/loaderUtils';
-import { EMPHASIS_COMMENT_PREFIX } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+import {
+  EMPHASIS_COMMENT_PREFIX,
+  FOCUS_COMMENT_PREFIX,
+} from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
 import { Code } from '../Code';
 
 const source = `import * as React from 'react';
@@ -13,11 +16,11 @@ const today = formatDate(new Date()); // @highlight
 export function Calendar() {
   const [events, setEvents] = React.useState([]);
 
-  // @highlight-start @focus
+  // @focus-start
   React.useEffect(() => {
     fetchEvents(today).then(setEvents);
   }, []);
-  // @highlight-end
+  // @focus-end
 
   return (
     <div className="calendar">
@@ -32,9 +35,10 @@ export function Calendar() {
 }`;
 
 export async function FocusCode() {
+  // @focus-start
   const { code: strippedSource, comments } = await parseImportsAndComments(source, '/demo.tsx', {
-    removeCommentsWithPrefix: [EMPHASIS_COMMENT_PREFIX],
-    notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX],
+    removeCommentsWithPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX],
+    notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX],
   });
 
   const code: CodeType = {
@@ -46,4 +50,5 @@ export async function FocusCode() {
   };
 
   return <Code code={code} />;
+  // @focus-end
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/indent-code/IndentCode.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/indent-code/IndentCode.tsx
index e6b27cfed..47169eed8 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/indent-code/IndentCode.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/indent-code/IndentCode.tsx
@@ -1,7 +1,10 @@
 import * as React from 'react';
 import type { Code as CodeType } from '@mui/internal-docs-infra/CodeHighlighter/types';
 import { parseImportsAndComments } from '@mui/internal-docs-infra/pipeline/loaderUtils';
-import { EMPHASIS_COMMENT_PREFIX } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+import {
+  EMPHASIS_COMMENT_PREFIX,
+  FOCUS_COMMENT_PREFIX,
+} from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
 import { CodeIndent } from '../CodeIndent';
 
 const source = `import * as React from 'react';
@@ -18,7 +21,7 @@ export function ScheduleView() {
       <section>
         <form>
           <label htmlFor="date">Pick a date</label>
-          {/* @highlight-start @focus */}
+          {/* @focus-start */}
           <DatePicker
             id="date"
             value={date}
@@ -26,7 +29,7 @@ export function ScheduleView() {
             minDate={new Date()}
             format="MM/dd/yyyy"
           />
-          {/* @highlight-end */}
+          {/* @focus-end */}
         </form>
       </section>
       <footer>
@@ -37,9 +40,10 @@ export function ScheduleView() {
 }`;
 
 export async function IndentCode() {
+  // @focus-start
   const { code: strippedSource, comments } = await parseImportsAndComments(source, '/demo.tsx', {
-    removeCommentsWithPrefix: [EMPHASIS_COMMENT_PREFIX],
-    notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX],
+    removeCommentsWithPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX],
+    notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX],
   });
 
   const code: CodeType = {
@@ -51,4 +55,5 @@ export async function IndentCode() {
   };
 
   return <CodeIndent code={code} />;
+  // @focus-end
 }
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 2ea866ee4..958cb5fd7 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
@@ -156,6 +156,9 @@ The enhancer recognizes these comment patterns:
 | `@highlight-end`              | End multi-line block                     |
 | `@highlight-text "text"`      | Highlight specific text within the line  |
 | `@highlight-text "one" "two"` | Highlight multiple texts within the line |
+| `@focus`                      | Focus current line (no line highlight)   |
+| `@focus-start`                | Start focused block (no line highlight)  |
+| `@focus-end`                  | End focused block                        |
 
 ### Description Format
 
@@ -287,10 +290,10 @@ When padding is configured (see [Configurable Padding](#configurable-padding)),
 
 ### Frame Data Attributes
 
-| Attribute           | Type   | Description                                                                                                                                                      |
-| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `data-frame-type`   | string | `"highlighted"` (focused region), `"highlighted-unfocused"` (non-focused regions), `"padding-top"`, or `"padding-bottom"`. Normal frames have no type attribute. |
-| `data-frame-indent` | number | Only on `highlighted` and `highlighted-unfocused` frames. The shared indent level of the highlighted lines (min leading spaces ÷ 2).                             |
+| 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).                                                                                                                                                                |
 
 ### Configurable Padding
 
@@ -313,7 +316,7 @@ const sourceEnhancers = [
 | `focusFramesMaxSize`  | number  | —       | Maximum total lines in the focus area (padding + highlighted). Remaining budget is split floor/ceil (extra line goes to bottom).                                                                                                         |
 | `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. |
 
-When `paddingFrameMaxSize` is `0` (the default), no padding frames are created and only `highlighted` and normal frames are produced.
+When `paddingFrameMaxSize` is `0` (the default), no padding frames are created and only region frames (`highlighted`, `focus`, etc.) and normal frames are produced.
 
 ### The `@focus` Directive
 
@@ -345,14 +348,34 @@ In this example, `@focus` directs the padding frames to surround the `ThemeProvi
 - `// @highlight-start @focus`
 - `// @highlight-start @focus "We render the provider"`
 
+### Standalone `@focus` (Focus Without Highlight)
+
+Use `@focus`, `@focus-start`, and `@focus-end` to mark a region as focused without adding line-level highlighting (`data-hl`). Lines in a standalone `@focus` region will be part of a focused frame but won't have visual emphasis on individual lines:
+
+```tsx displayComments
+const theme = getTheme(); // @highlight
+const config = getConfig();
+
+// @focus-start
+<ThemeProvider theme={theme}>
+  <App config={config} />
+</ThemeProvider>;
+// @focus-end
+```
+
+In this example, the `ThemeProvider` block is focused (padding frames surround it), but only the `theme` line has line-level highlighting.
+
+This is particularly useful when an ESLint rule like [`lintJavascriptDemoFocus`](/docs-infra/pipeline/lint-javascript-demo-focus) auto-inserts focus markers — the auto-generated `@focus-start`/`@focus-end` marks the preview area without adding highlight styling, leaving `@highlight` for manual use.
+
 ### Styling Frame Types
 
 Target frame types with CSS to create collapsible code blocks:
 
 ```css
-/* Normal frames and unfocused highlighted frames are hidden by default (collapsed) */
+/* Normal frames and unfocused highlighted/focus frames are hidden by default (collapsed) */
 .codeBlock .frame:not([data-frame-type]),
-.codeBlock .frame[data-frame-type='highlighted-unfocused'] {
+.codeBlock .frame[data-frame-type='highlighted-unfocused'],
+.codeBlock .frame[data-frame-type='focus-unfocused'] {
   max-height: 0;
   overflow: hidden;
   opacity: 0;
@@ -370,7 +393,8 @@ Target frame types with CSS to create collapsible code blocks:
 
 /* When expanded, show all frames */
 .expanded .codeBlock .frame:not([data-frame-type]),
-.expanded .codeBlock .frame[data-frame-type='highlighted-unfocused'] {
+.expanded .codeBlock .frame[data-frame-type='highlighted-unfocused'],
+.expanded .codeBlock .frame[data-frame-type='focus-unfocused'] {
   max-height: 500px;
   overflow: visible;
   opacity: 1;
@@ -381,21 +405,25 @@ Target frame types with CSS to create collapsible code blocks:
   opacity: 1;
 }
 
-/* Use indent level to shift highlighted frames left when collapsed */
-.codeBlock .frame[data-frame-type='highlighted'] {
+/* Use indent level to shift highlighted/focus frames left when collapsed */
+.codeBlock .frame[data-frame-type='highlighted'],
+.codeBlock .frame[data-frame-type='focus'] {
   transition: margin-left 0.3s ease;
 }
 
-.codeBlock .frame[data-frame-type='highlighted'][data-frame-indent='1'] {
+.codeBlock .frame[data-frame-type='highlighted'][data-frame-indent='1'],
+.codeBlock .frame[data-frame-type='focus'][data-frame-indent='1'] {
   margin-left: -2ch;
 }
 
-.codeBlock .frame[data-frame-type='highlighted'][data-frame-indent='2'] {
+.codeBlock .frame[data-frame-type='highlighted'][data-frame-indent='2'],
+.codeBlock .frame[data-frame-type='focus'][data-frame-indent='2'] {
   margin-left: -4ch;
 }
 
 /* Reset indent shift when expanded */
-.expanded .codeBlock .frame[data-frame-type='highlighted'] {
+.expanded .codeBlock .frame[data-frame-type='highlighted'],
+.expanded .codeBlock .frame[data-frame-type='focus'] {
   margin-left: 0;
 }
 ```
@@ -410,7 +438,7 @@ import { DemoCollapsibleCode } from './demos/collapsible-code';
 
 ### Demo: @focus with Multiple Regions
 
-When there are multiple highlight regions, `@focus` controls which region receives padding frames. In this demo, the `useEffect` block on the second region is focused — its surrounding lines get padding frames while the first region (`formatDate` call) does not.
+This demo uses `@highlight` on the `formatDate` call and standalone `@focus-start`/`@focus-end` around the `useEffect` block. The `useEffect` region is focused (padding frames surround it) but has no line-level highlighting, while the `formatDate` line has line-level highlighting but is unfocused.
 
 import { DemoFocusCode } from './demos/focus-code';
 
@@ -418,7 +446,7 @@ import { DemoFocusCode } from './demos/focus-code';
 
 ### Demo: Indent Shifting
 
-With no padding configured, only `highlighted` and normal frames are produced. The `data-frame-indent` attribute on highlighted frames tells CSS how far the code is indented. This demo highlights an import statement (indent 0) and the deeply nested `<DatePicker>` usage (indent 3). When collapsed, the JSX 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. 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.
 
 import { DemoIndentCode } from './demos/indent-code';
 
@@ -430,8 +458,8 @@ import { DemoIndentCode } from './demos/indent-code';
 
 ### How It Works
 
-1. **Comment Extraction**: Comments are extracted during parsing with `notableCommentsPrefix: ['@highlight']`
-2. **Directive Parsing**: The enhancer scans comments for `@highlight`, `@highlight-start`, `@highlight-end`, and `@highlight-text` patterns
+1. **Comment Extraction**: Comments are extracted during parsing with `notableCommentsPrefix: ['@highlight', '@focus']`
+2. **Directive Parsing**: The enhancer scans comments for `@highlight`, `@highlight-start`, `@highlight-end`, `@highlight-text`, `@focus`, `@focus-start`, and `@focus-end` patterns
 3. **Line Calculation**: Single-line directives mark their own line; multi-line directives mark all lines from the first line after `@highlight-start` to the last line before `@highlight-end`
 4. **Nested Detection**: Lines inside multiple ranges are automatically marked as strong emphasis
 5. **HAST Modification**: The enhancer traverses the HAST tree and adds `dataHl: ''` (or `dataHl: 'strong'` for nested lines or descriptions ending with `!`) to line elements
@@ -536,10 +564,10 @@ const sourceEnhancers = [
 Then pass to your loading pipeline:
 
 ```ts
-// Create a loadSource that extracts emphasis comments
+// Create a loadSource that extracts emphasis and focus comments
 const loadSource = createLoadServerSource({
-  notableCommentsPrefix: ['@highlight'],
-  removeCommentsWithPrefix: ['@highlight'],
+  notableCommentsPrefix: ['@highlight', '@focus'],
+  removeCommentsWithPrefix: ['@highlight', '@focus'],
 });
 
 // Use with loadCodeVariant
@@ -563,16 +591,18 @@ const { selectedFile } = useCode(props, {
 
 ### Comment Prefix
 
-The default comment prefix is `@highlight`, exported as `EMPHASIS_COMMENT_PREFIX`:
+The default comment prefixes are `@highlight` and `@focus`, exported as `EMPHASIS_COMMENT_PREFIX` and `FOCUS_COMMENT_PREFIX`:
 
 ```ts
-import { EMPHASIS_COMMENT_PREFIX } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+import {
+  EMPHASIS_COMMENT_PREFIX,
+  FOCUS_COMMENT_PREFIX,
+} from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
 
 console.log(EMPHASIS_COMMENT_PREFIX); // '@highlight'
+console.log(FOCUS_COMMENT_PREFIX); // '@focus'
 ```
 
-To use a different prefix, you would need to create a custom enhancer based on this implementation.
-
 ---
 
 ## Styling Emphasized Lines
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 6ff352ea5..c74727465 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
@@ -77,10 +77,11 @@ type EmphasisMeta = {
   /** Whether this line's region is the focused region (for padding) */
   focus?: boolean;
   /**
-   * Whether the line itself should receive data-hl (from
-   * @highlight or multiline region)
+   * Whether the line itself should receive data-hl. True for
+   * @highlight , false for
+   * @focus-only .
    */
-  lineHighlight?: boolean;
+  lineHighlight: boolean;
 };
 ```
 
@@ -113,6 +114,15 @@ type EnhanceCodeEmphasisOptions = {
 };
 ```
 
+### FOCUS_COMMENT_PREFIX
+
+The prefix used to identify focus-only comments in source code.
+Comments starting with this prefix will mark the region as focused without highlighting.
+
+```typescript
+type FOCUS_COMMENT_PREFIX = '@focus';
+```
+
 ### FrameRange
 
 A range of lines that forms a frame in the output.
@@ -129,6 +139,8 @@ type FrameRange = {
     | 'padding-top'
     | 'highlighted'
     | 'highlighted-unfocused'
+    | 'focus'
+    | 'focus-unfocused'
     | 'padding-bottom'
     | 'comment';
 };
diff --git a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
index c15a840ae..eaab005b3 100644
--- a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
+++ b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
@@ -1,19 +1,19 @@
 # Lint JavaScript Demo Focus
 
-An ESLint rule that automatically inserts `@highlight` and `@focus` comments around the preview section of demo files. These comments control which parts of the code are highlighted and focused when rendered in documentation.
+An ESLint rule that automatically inserts `@focus` comments around the preview section of demo files. These comments control which parts of the code are focused when rendered in documentation.
 
 ## Overview
 
-Demo files in `docs/app/**/demos/**` need `@highlight` / `@focus` comments so the docs infrastructure knows which code to emphasize. Writing these by hand is tedious and error-prone. This ESLint rule detects the preview section of each demo and auto-fixes the comments in.
+Demo files in `docs/app/**/demos/**` need `@focus` comments so the docs infrastructure knows which code to emphasize. Writing these by hand is tedious and error-prone. This ESLint rule detects the preview section of each demo and auto-fixes the comments in.
 
 ### Key Features
 
 - **Auto-fixable**: Run `eslint --fix` to insert all comments automatically
 - **Smart comment style**: Uses JSX comments (`{/* */}`) inside wrapper elements and JS comments (`//`) elsewhere
-- **Single vs multi-line**: Uses `@highlight @focus` for single-line previews and `@highlight-start @focus` / `@highlight-end` for multi-line
+- **Single vs multi-line**: Uses `@focus` for single-line previews and `@focus-start` / `@focus-end` for multi-line
 - **Named export detection**: Supports both `export default` and named exports (filename match or single-export fallback)
 - **Function body highlighting**: Wraps the entire body when hooks or setup statements are present
-- **Skip when present**: Files that already contain `@highlight` anywhere are left untouched
+- **Skip when present**: Files that already contain `@highlight` or `@focus` anywhere are left untouched
 
 ## Installation & Usage
 
@@ -69,10 +69,10 @@ export default function Demo() {
 export default function Demo() {
   return (
     <div>
-      {/* @highlight-start @focus */}
+      {/* @focus-start */}
       <Button>Click me</Button>
       <TextField label="Name" />
-      {/* @highlight-end */}
+      {/* @focus-end */}
     </div>
   );
 }
@@ -85,7 +85,7 @@ For a single child inside a wrapper:
 export default function Demo() {
   return (
     <div>
-      {/* @highlight @focus */}
+      {/* @focus */}
       <Button>Click me</Button>
     </div>
   );
@@ -104,7 +104,7 @@ export default function Demo() {
 
 // After fix
 export default function Demo() {
-  // @highlight @focus
+  // @focus
   return <Button>Click me</Button>;
 }
 ```
@@ -120,7 +120,7 @@ export default function Demo() {
 // After fix
 export default function Demo() {
   return (
-    // @highlight @focus
+    // @focus
     <Button>Click me</Button>
   );
 }
@@ -137,7 +137,7 @@ export default function Demo() {
 // After fix (wrapReturn: true)
 export default function Demo() {
   return (
-    // @highlight @focus
+    // @focus
     <Button>Click me</Button>
   );
 }
@@ -156,10 +156,10 @@ export default function Demo() {
 
 // After fix
 export default function Demo() {
-  // @highlight-start @focus
+  // @focus-start
   const code = useCode();
   return <CodeEditor code={code} />;
-  // @highlight-end
+  // @focus-end
 }
 ```
 
diff --git a/docs/app/docs-infra/pipeline/page.mdx b/docs/app/docs-infra/pipeline/page.mdx
index 1609e53e4..1a815aa59 100644
--- a/docs/app/docs-infra/pipeline/page.mdx
+++ b/docs/app/docs-infra/pipeline/page.mdx
@@ -69,6 +69,7 @@ The `enhanceCodeEmphasis` source enhancer adds visual emphasis to specific lines
     - Frame Data Attributes
     - Configurable Padding
     - The `@focus` Directive
+    - Standalone `@focus` (Focus Without Highlight)
     - Styling Frame Types
     - Demo: Collapsible Code Block
     - Demo: @focus with Multiple Regions
@@ -99,7 +100,7 @@ The `enhanceCodeEmphasis` source enhancer adds visual emphasis to specific lines
     - Parameters: options
   - enhanceCodeEmphasis
     - Parameters: root, comments, fileName
-- Types: EMPHASIS_COMMENT_PREFIX, EmphasisMeta, EnhanceCodeEmphasisOptions, FrameRange
+- Types: EMPHASIS_COMMENT_PREFIX, EmphasisMeta, EnhanceCodeEmphasisOptions, FOCUS_COMMENT_PREFIX, FrameRange
 
 </details>
 
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
index 8032ff419..f03943727 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
@@ -6,6 +6,7 @@ import {
   enhanceCodeEmphasis,
   createEnhanceCodeEmphasis,
   EMPHASIS_COMMENT_PREFIX,
+  FOCUS_COMMENT_PREFIX,
 } from './enhanceCodeEmphasis';
 import { parseImportsAndComments } from '../loaderUtils/parseImportsAndComments';
 import type { HastRoot, ParseSource, SourceEnhancer } from '../../CodeHighlighter/types';
@@ -25,8 +26,8 @@ async function testEmphasis(
     code,
     `file:///${fileName}`,
     {
-      notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX],
-      removeCommentsWithPrefix: [EMPHASIS_COMMENT_PREFIX],
+      notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX],
+      removeCommentsWithPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX],
     },
   );
 
@@ -275,7 +276,7 @@ const e = 5; // @highlight`,
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="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="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-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>></span>
+        </span><span class="frame" data-lined="" data-frame-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4" data-hl="" data-hl-position="single">      &#x3C;<span class="pl-ent">h1</span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>></span>
         </span><span class="frame" data-lined="" data-frame-start-line="5" data-frame-end-line="7"><span class="line" data-ln="5">    &#x3C;/<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="6">  );</span>
         <span class="line" data-ln="7">}</span></span>"
@@ -300,7 +301,7 @@ const e = 5; // @highlight`,
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="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="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-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span> <span class="pl-e">className</span><span class="pl-k">=</span><span class="pl-s"><span class="pl-pds">"</span><span data-hl="">primary</span><span class="pl-pds">"</span></span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>></span>
+        </span><span class="frame" data-lined="" data-frame-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4" data-hl="" data-hl-position="single">      &#x3C;<span class="pl-ent">h1</span> <span class="pl-e">className</span><span class="pl-k">=</span><span class="pl-s"><span class="pl-pds">"</span><span data-hl="">primary</span><span class="pl-pds">"</span></span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>></span>
         </span><span class="frame" data-lined="" data-frame-start-line="5" data-frame-end-line="7"><span class="line" data-ln="5">    &#x3C;/<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="6">  );</span>
         <span class="line" data-ln="7">}</span></span>"
@@ -328,7 +329,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(
-        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1">AlertDialog.Trigger</span> <span data-hl=""><span class="pl-e">handle</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">demoAlertDialog</span><span class="pl-pse">}</span></span>>Open&#x3C;/<span class="pl-c1">AlertDialog.Trigger</span>></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1" data-hl="" data-hl-position="single">&#x3C;<span class="pl-c1">AlertDialog.Trigger</span> <span data-hl=""><span class="pl-e">handle</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">demoAlertDialog</span><span class="pl-pse">}</span></span>>Open&#x3C;/<span class="pl-c1">AlertDialog.Trigger</span>></span></span>"`,
       );
     });
 
@@ -340,7 +341,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(
-        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1">Button</span> <span class="pl-e">render</span><span class="pl-k">=</span><span class="pl-pse">{</span>&#x3C;<span class="pl-ent">div</span> /><span class="pl-pse">}</span> <span data-hl=""><span class="pl-e">nativeButton</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-c1">false</span><span class="pl-pse">}</span></span>></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1" data-hl="" data-hl-position="single">&#x3C;<span class="pl-c1">Button</span> <span class="pl-e">render</span><span class="pl-k">=</span><span class="pl-pse">{</span>&#x3C;<span class="pl-ent">div</span> /><span class="pl-pse">}</span> <span data-hl=""><span class="pl-e">nativeButton</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-c1">false</span><span class="pl-pse">}</span></span>></span></span>"`,
       );
     });
 
@@ -468,7 +469,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(
-        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">a</span><span class="pl-pse">}</span> /> &#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">b</span><span class="pl-pse">}</span> /> <span class="pl-c">// @highlight-text "<span data-hl="">value</span>"</span></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1" data-hl="" data-hl-position="single">&#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">a</span><span class="pl-pse">}</span> /> &#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">b</span><span class="pl-pse">}</span> /> <span class="pl-c">// @highlight-text "<span data-hl="">value</span>"</span></span></span>"`,
       );
     });
 
@@ -495,7 +496,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(
-        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span data-hl=""><span class="pl-smi">value</span></span><span class="pl-pse">}</span> /></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1" data-hl="" data-hl-position="single">&#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span data-hl=""><span class="pl-smi">value</span></span><span class="pl-pse">}</span> /></span></span>"`,
       );
     });
   });
@@ -891,7 +892,7 @@ const z = 3;`,
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="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="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-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span> <span class="pl-e">className</span><span class="pl-k">=</span><span class="pl-s"><span class="pl-pds">"</span><span data-hl="">primary</span><span class="pl-pds">"</span></span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>> <span class="pl-pse">{</span><span class="pl-c">/* @highlight-text "<span data-hl="">primary</span>" "<span data-hl="">Heading 1</span>" */</span><span class="pl-pse">}</span></span>
+        </span><span class="frame" data-lined="" data-frame-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4" data-hl="" data-hl-position="single">      &#x3C;<span class="pl-ent">h1</span> <span class="pl-e">className</span><span class="pl-k">=</span><span class="pl-s"><span class="pl-pds">"</span><span data-hl="">primary</span><span class="pl-pds">"</span></span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>> <span class="pl-pse">{</span><span class="pl-c">/* @highlight-text "<span data-hl="">primary</span>" "<span data-hl="">Heading 1</span>" */</span><span class="pl-pse">}</span></span>
         </span><span class="frame" data-lined="" data-frame-start-line="5" data-frame-end-line="7"><span class="line" data-ln="5">    &#x3C;/<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="6">  );</span>
         <span class="line" data-ln="7">}</span></span>"
@@ -1090,6 +1091,94 @@ const d = 4;`,
     });
   });
 
+  describe('standalone @focus directives (focus without highlight)', () => {
+    it('should focus a single line with @focus without highlighting it', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2; // @focus
+const c = 3;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Line 2 is focused but NOT line-highlighted (no data-hl)
+      expect(result).toMatch(
+        /data-frame-start-line="2" data-frame-end-line="2" data-frame-type="focus"/,
+      );
+      expect(result).not.toContain('data-hl=""');
+
+      // Padding frames around the focused region
+      expect(result).toContain('data-frame-type="padding-top"');
+      expect(result).toContain('data-frame-type="padding-bottom"');
+    });
+
+    it('should focus a multiline region with @focus-start/@focus-end without highlighting', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+// @focus-start
+const b = 2;
+const c = 3;
+// @focus-end
+const d = 4;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Lines 2-3 are focused but NOT line-highlighted
+      expect(result).toMatch(/data-frame-type="focus"/);
+      expect(result).not.toContain('data-hl=""');
+
+      // Padding frames around the focused region
+      expect(result).toContain('data-frame-type="padding-top"');
+      expect(result).toContain('data-frame-type="padding-bottom"');
+    });
+
+    it('should focus with @focus while @highlight highlights separately', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1; // @highlight
+const b = 2;
+const c = 3; // @focus
+const d = 4;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Line 1 is highlighted-unfocused (has data-hl but not focused)
+      expect(result).toMatch(
+        /data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted-unfocused"/,
+      );
+      expect(result).toContain('data-hl=""');
+
+      // Line 3 is focused (focus frame type) but no data-hl
+      expect(result).toMatch(
+        /data-frame-start-line="3" data-frame-end-line="3" data-frame-type="focus"/,
+      );
+
+      // Padding frames around @focus region
+      expect(result).toContain('data-frame-type="padding-top"');
+      expect(result).toContain('data-frame-type="padding-bottom"');
+    });
+
+    it('FOCUS_COMMENT_PREFIX should export the correct prefix', () => {
+      expect(FOCUS_COMMENT_PREFIX).toBe('@focus');
+    });
+  });
+
   describe('data-frame-indent', () => {
     it('should set data-frame-indent based on minimum indentation', async () => {
       const result = await testEmphasis(
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
index b33d07ae6..7a67461c0 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
@@ -18,6 +18,12 @@ export type {
  */
 export const EMPHASIS_COMMENT_PREFIX = '@highlight';
 
+/**
+ * The prefix used to identify focus-only comments in source code.
+ * Comments starting with this prefix will mark the region as focused without highlighting.
+ */
+export const FOCUS_COMMENT_PREFIX = '@focus';
+
 /**
  * Parsed emphasis directive from a comment.
  */
@@ -32,6 +38,8 @@ interface EmphasisDirective {
   highlightTexts?: string[];
   /** Whether this directive is marked as the focus target */
   focus?: boolean;
+  /** Whether the line should be visually highlighted (false for focus-only directives) */
+  lineHighlight: boolean;
 }
 
 /**
@@ -97,6 +105,8 @@ function extractFocus(content: string): { focus: boolean; remaining: string } {
  * - Multiline end: `@highlight-end`
  * - Text highlight: `@highlight-text "text to highlight"` or `@highlight-text "one" "two"`
  * - Text highlight focused: `@highlight-text @focus "text to highlight"`
+ * - Focus only (single line): `@focus`
+ * - Focus only (multiline): `@focus-start` / `@focus-end`
  *
  * @param comments - Source comments keyed by line number
  * @returns Array of parsed emphasis directives
@@ -108,52 +118,17 @@ function parseEmphasisDirectives(comments: SourceComments): EmphasisDirective[]
     const line = parseInt(lineStr, 10);
 
     for (const comment of commentArray) {
-      // Check if this is an emphasis comment
-      if (!comment.startsWith(EMPHASIS_COMMENT_PREFIX)) {
+      // Check if this is a @highlight comment
+      if (comment.startsWith(EMPHASIS_COMMENT_PREFIX)) {
+        const content = comment.slice(EMPHASIS_COMMENT_PREFIX.length);
+        parseHighlightDirective(directives, line, content);
         continue;
       }
 
-      // Extract the content after "@highlight"
-      const content = comment.slice(EMPHASIS_COMMENT_PREFIX.length);
-
-      if (content.startsWith('-end')) {
-        // End of multiline emphasis: @highlight-end
-        directives.push({ line, type: 'end' });
-      } else if (content.startsWith('-start')) {
-        // Start of multiline emphasis: @highlight-start or @highlight-start "description"
-        const afterStart = content.slice('-start'.length).trim();
-        const { focus, remaining: remainingStart } = extractFocus(afterStart);
-        const description = extractQuotedString(remainingStart);
-        directives.push({
-          line,
-          type: 'start',
-          description,
-          focus,
-        });
-      } else if (content.startsWith('-text')) {
-        // Text highlight: @highlight-text "text" or @highlight-text "one" "two" "three"
-        const afterText = content.slice('-text'.length).trim();
-        const { focus, remaining: remainingText } = extractFocus(afterText);
-        const highlightTexts = extractAllQuotedStrings(remainingText);
-        if (highlightTexts.length > 0) {
-          directives.push({
-            line,
-            type: 'text',
-            highlightTexts,
-            focus,
-          });
-        }
-      } else {
-        // Single line emphasis: @highlight or @highlight "description"
-        const afterHighlight = content.trim();
-        const { focus, remaining: remainingSingle } = extractFocus(afterHighlight);
-        const description = extractQuotedString(remainingSingle) || undefined;
-        directives.push({
-          line,
-          type: 'single',
-          description,
-          focus,
-        });
+      // Check if this is a @focus comment (focus-only, no highlight)
+      if (comment.startsWith(FOCUS_COMMENT_PREFIX)) {
+        const content = comment.slice(FOCUS_COMMENT_PREFIX.length);
+        parseFocusDirective(directives, line, content);
       }
     }
   }
@@ -161,6 +136,54 @@ function parseEmphasisDirectives(comments: SourceComments): EmphasisDirective[]
   return directives;
 }
 
+/**
+ * Parses a `@highlight` comment into one or more directives.
+ */
+function parseHighlightDirective(
+  directives: EmphasisDirective[],
+  line: number,
+  content: string,
+): void {
+  if (content.startsWith('-end')) {
+    directives.push({ line, type: 'end', lineHighlight: true });
+  } else if (content.startsWith('-start')) {
+    const afterStart = content.slice('-start'.length).trim();
+    const { focus, remaining: remainingStart } = extractFocus(afterStart);
+    const description = extractQuotedString(remainingStart);
+    directives.push({ line, type: 'start', description, focus, lineHighlight: true });
+  } else if (content.startsWith('-text')) {
+    const afterText = content.slice('-text'.length).trim();
+    const { focus, remaining: remainingText } = extractFocus(afterText);
+    const highlightTexts = extractAllQuotedStrings(remainingText);
+    if (highlightTexts.length > 0) {
+      directives.push({ line, type: 'text', highlightTexts, focus, lineHighlight: true });
+    }
+  } else {
+    const afterHighlight = content.trim();
+    const { focus, remaining: remainingSingle } = extractFocus(afterHighlight);
+    const description = extractQuotedString(remainingSingle) || undefined;
+    directives.push({ line, type: 'single', description, focus, lineHighlight: true });
+  }
+}
+
+/**
+ * Parses a `@focus` comment into a focus-only directive (no line highlight).
+ */
+function parseFocusDirective(directives: EmphasisDirective[], line: number, content: string): void {
+  if (content.startsWith('-end')) {
+    directives.push({ line, type: 'end', lineHighlight: false });
+  } else if (content.startsWith('-start')) {
+    const afterStart = content.slice('-start'.length).trim();
+    const description = extractQuotedString(afterStart);
+    directives.push({ line, type: 'start', description, focus: true, lineHighlight: false });
+  } else {
+    // Single line: @focus or @focus "description"
+    const afterFocus = content.trim();
+    const description = extractQuotedString(afterFocus) || undefined;
+    directives.push({ line, type: 'single', description, focus: true, lineHighlight: false });
+  }
+}
+
 /**
  * Capitalizes the first letter of a string.
  *
@@ -298,7 +321,7 @@ function calculateEmphasizedLines(
         description,
         strong,
         position: 'single',
-        lineHighlight: true,
+        lineHighlight: directive.lineHighlight,
         focus: directive.focus,
       });
     } else if (directive.type === 'text') {
@@ -313,6 +336,7 @@ function calculateEmphasizedLines(
       emphasizedLines.set(directive.line, {
         ...existing,
         position: existing?.position ?? 'single',
+        lineHighlight: existing?.lineHighlight ?? directive.lineHighlight,
         highlightTexts: mergedTexts,
         focus: directive.focus || existing?.focus,
       });
@@ -333,7 +357,9 @@ function calculateEmphasizedLines(
       // If the comment was stripped, the line number already points to the first content line.
       const startLineElement = lineElements.get(startDirective.line);
       const isStartCommentOnly =
-        startLineElement && isCommentOnlyLine(startLineElement, '@highlight-start');
+        startLineElement &&
+        (isCommentOnlyLine(startLineElement, '@highlight-start') ||
+          isCommentOnlyLine(startLineElement, '@focus-start'));
 
       const startLine = isStartCommentOnly ? startDirective.line + 1 : startDirective.line;
       const endLine = directive.line - 1;
@@ -374,14 +400,14 @@ function calculateEmphasizedLines(
               position:
                 existing.position && existing.position !== 'single' ? existing.position : position,
               highlightTexts: existing.highlightTexts, // Preserve text highlights from @highlight-text
-              lineHighlight: true, // Inside a multiline region = always line highlight
+              lineHighlight: existing.lineHighlight || startDirective.lineHighlight,
               focus: existing.focus || startDirective.focus,
             }
           : {
               strong,
               description: line === startLine ? description : undefined,
               position,
-              lineHighlight: true,
+              lineHighlight: startDirective.lineHighlight,
               focus: startDirective.focus,
             };
 
@@ -838,7 +864,7 @@ function applyEmphasisAndCollectHighlightedElements(
                 child.properties.dataHlPosition = meta.position;
               }
             }
-          } else {
+          } else if (meta.lineHighlight) {
             // Use data-hl with optional "strong" value on the line
             child.properties.dataHl = meta.strong ? 'strong' : '';
 
diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
index 285adc114..1fd1a1876 100644
--- a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
@@ -17,23 +17,24 @@ describe('lintJavascriptDemoFocus', () => {
   it('should pass RuleTester', () => {
     ruleTester.run('require-demo-focus', lintJavascriptDemoFocus, {
       valid: [
-        // File already has @highlight — skip
+        // File already has @highlight-start with @focus — skip
         {
           code: `
-// @highlight
+{/* @highlight-start @focus */}
 export default function Demo() {
   return <div>Hello</div>;
 }
+{/* @highlight-end */}
           `,
         },
-        // File already has @highlight-start — skip
+        // File already has @focus — skip
         {
           code: `
-{/* @highlight-start @focus */}
+// @focus-start
 export default function Demo() {
   return <div>Hello</div>;
 }
-{/* @highlight-end */}
+// @focus-end
           `,
         },
         // No export default, named export doesn't match filename, multiple exports
@@ -79,13 +80,48 @@ export const theme = createTheme({ palette: { primary: 'red' } });
         },
       ],
       invalid: [
+        // @highlight in a string literal should NOT cause skip
+        {
+          code: `export default function Demo() {
+  return <Button label="@highlight this">Click</Button>;
+}`,
+          output: `export default function Demo() {
+  // @focus
+  return <Button label="@highlight this">Click</Button>;
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // @focus in a string literal should NOT cause skip
+        {
+          code: `export default function Demo() {
+  return <Button label="@focus this">Click</Button>;
+}`,
+          output: `export default function Demo() {
+  // @focus
+  return <Button label="@focus this">Click</Button>;
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // @highlight comment alone should NOT cause skip — @focus is still needed
+        {
+          code: `// @highlight
+export default function Demo() {
+  return <Button>Click</Button>;
+}`,
+          output: `// @highlight
+export default function Demo() {
+  // @focus
+  return <Button>Click</Button>;
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
         // Single JSX element (no wrapper), single line: // comment fix
         {
           code: `export default function Demo() {
   return <Button>Click me</Button>;
 }`,
           output: `export default function Demo() {
-  // @highlight @focus
+  // @focus
   return <Button>Click me</Button>;
 }`,
           errors: [{ messageId: 'missingDemoFocusJsSingle' }],
@@ -103,10 +139,10 @@ export const theme = createTheme({ palette: { primary: 'red' } });
           output: `export default function Demo() {
   return (
     <div>
-      {/* @highlight-start @focus */}
+      {/* @focus-start */}
       <Button>Click me</Button>
       <Button>Click me too</Button>
-      {/* @highlight-end */}
+      {/* @focus-end */}
     </div>
   );
 }`,
@@ -124,7 +160,7 @@ export const theme = createTheme({ palette: { primary: 'red' } });
           output: `export default function Demo() {
   return (
     <Box>
-      {/* @highlight @focus */}
+      {/* @focus */}
       <TextField label="Name" />
     </Box>
   );
@@ -144,10 +180,10 @@ export const theme = createTheme({ palette: { primary: 'red' } });
           output: `export default function Demo() {
   return (
     <Stack>
-      {/* @highlight-start @focus */}
+      {/* @focus-start */}
       <Input />
       <Button />
-      {/* @highlight-end */}
+      {/* @focus-end */}
     </Stack>
   );
 }`,
@@ -165,7 +201,7 @@ export const theme = createTheme({ palette: { primary: 'red' } });
           output: `export default function Demo() {
   return (
     <>
-      {/* @highlight @focus */}
+      {/* @focus */}
       <Button>Click</Button>
     </>
   );
@@ -178,7 +214,7 @@ export const theme = createTheme({ palette: { primary: 'red' } });
   return <Button>Click</Button>;
 }`,
           output: `export default () => {
-  // @highlight @focus
+  // @focus
   return <Button>Click</Button>;
 }`,
           errors: [{ messageId: 'missingDemoFocusJsSingle' }],
@@ -186,7 +222,7 @@ export const theme = createTheme({ palette: { primary: 'red' } });
         // Arrow function with implicit return of bare element: // comment fix
         {
           code: `export default () => <Button>Click</Button>`,
-          output: `// @highlight @focus\nexport default () => <Button>Click</Button>`,
+          output: `// @focus\nexport default () => <Button>Click</Button>`,
           errors: [{ messageId: 'missingDemoFocusJsSingle' }],
         },
         // Non-wrapper element inside parentheses: // comment fix
@@ -198,7 +234,7 @@ export const theme = createTheme({ palette: { primary: 'red' } });
 }`,
           output: `export default function Demo() {
   return (
-    // @highlight @focus
+    // @focus
     <Button variant="contained">Submit</Button>
   );
 }`,
@@ -216,7 +252,7 @@ export const theme = createTheme({ palette: { primary: 'red' } });
           output: `export default () => {
   return (
     <div>
-      {/* @highlight @focus */}
+      {/* @focus */}
       <Button>Click</Button>
     </div>
   );
@@ -237,10 +273,10 @@ export const theme = createTheme({ palette: { primary: 'red' } });
           output: `export function CodeEditor() {
   return (
     <div>
-      {/* @highlight-start @focus */}
+      {/* @focus-start */}
       <Input />
       <Button />
-      {/* @highlight-end */}
+      {/* @focus-end */}
     </div>
   );
 }`,
@@ -253,7 +289,7 @@ export const theme = createTheme({ palette: { primary: 'red' } });
   return <Button>Click</Button>;
 }`,
           output: `export const MyDemo = () => {
-  // @highlight @focus
+  // @focus
   return <Button>Click</Button>;
 }`,
           errors: [{ messageId: 'missingDemoFocusJsSingle' }],
@@ -265,7 +301,7 @@ export const theme = createTheme({ palette: { primary: 'red' } });
   return <Button>Click</Button>;
 }`,
           output: `export function Demo() {
-  // @highlight @focus
+  // @focus
   return <Button>Click</Button>;
 }`,
           errors: [{ messageId: 'missingDemoFocusJsSingle' }],
@@ -290,10 +326,10 @@ export function Primary() {
 export function Primary() {
   return (
     <div>
-      {/* @highlight-start @focus */}
+      {/* @focus-start */}
       <Input />
       <Button />
-      {/* @highlight-end */}
+      {/* @focus-end */}
     </div>
   );
 }`,
@@ -310,14 +346,14 @@ export function Primary() {
   );
 }`,
           output: `export default function Demo() {
-  // @highlight-start @focus
+  // @focus-start
   const code = useCode();
   return (
     <div>
       {code.file}
     </div>
   );
-  // @highlight-end
+  // @focus-end
 }`,
           errors: [{ messageId: 'missingDemoFocusBody' }],
         },
@@ -331,12 +367,12 @@ export function Primary() {
   );
 }`,
           output: `export function CodeContent(props) {
-  // @highlight-start @focus
+  // @focus-start
   const code = useCode(props);
   return (
     <div>{code.file}</div>
   );
-  // @highlight-end
+  // @focus-end
 }`,
           errors: [{ messageId: 'missingDemoFocusBody' }],
         },
@@ -352,14 +388,14 @@ export function Primary() {
   );
 });`,
           output: `export const DialogTrigger = React.forwardRef(function DialogTrigger(props, ref) {
-  // @highlight-start @focus
+  // @focus-start
   const { disabled, children, ...other } = props;
   return (
     <button type="button" ref={ref} disabled={disabled} {...other}>
       {children}
     </button>
   );
-  // @highlight-end
+  // @focus-end
 });`,
           errors: [{ messageId: 'missingDemoFocusBody' }],
         },
@@ -370,7 +406,7 @@ export function Primary() {
   return <Button>Click</Button>;
 });`,
           output: `export const MemoDemo = React.memo(() => {
-  // @highlight @focus
+  // @focus
   return <Button>Click</Button>;
 });`,
           errors: [{ messageId: 'missingDemoFocusJsSingle' }],
@@ -381,7 +417,7 @@ export function Primary() {
   return <Button ref={ref}>Click</Button>;
 });`,
           output: `export default React.forwardRef(function Demo(props, ref) {
-  // @highlight @focus
+  // @focus
   return <Button ref={ref}>Click</Button>;
 });`,
           errors: [{ messageId: 'missingDemoFocusJsSingle' }],
@@ -403,7 +439,7 @@ export function Primary() {
 }`,
           output: `export default function Demo() {
   return (
-    // @highlight @focus
+    // @focus
     <Button>Click me</Button>
   );
 }`,
@@ -419,7 +455,7 @@ export function Primary() {
 }`,
           output: `export default function Demo() {
   return (
-    // @highlight @focus
+    // @focus
     <Checkbox defaultChecked />
   );
 }`,
@@ -435,11 +471,11 @@ export function Primary() {
 }`,
           output: `export default function Demo() {
   return (
-    // @highlight-start @focus
+    // @focus-start
     <Card>
     <Button>Click</Button>
   </Card>
-    // @highlight-end
+    // @focus-end
   );
 }`,
           errors: [{ messageId: 'missingDemoFocusJs' }],
@@ -457,7 +493,7 @@ export function Primary() {
           output: `export default function Demo() {
   return (
     <div>
-      {/* @highlight @focus */}
+      {/* @focus */}
       <Button>Click</Button>
     </div>
   );
@@ -473,7 +509,7 @@ export function Primary() {
 }`,
           output: `export function CheckboxRed() {
   return (
-    // @highlight @focus
+    // @focus
     <Checkbox defaultChecked />
   );
 }`,
diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
index 2fcca7928..61258c372 100644
--- a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
@@ -155,27 +155,27 @@ function getPreviewNodes(returnedJSX: unknown): PreviewResult | null {
 }
 
 /**
- * ESLint rule requiring demo files to have highlight-focus comments around the preview section.
+ * ESLint rule requiring demo files to have focus comments around the preview section.
  */
 export const lintJavascriptDemoFocus = {
   meta: {
     type: 'suggestion',
     docs: {
       description:
-        'Require demo files to have @highlight-start @focus / @highlight-end comments around the preview section.',
+        'Require demo files to have @focus-start / @focus-end comments around the preview section.',
     },
     fixable: 'code',
     messages: {
       missingDemoFocusJsx:
-        'Demo file is missing {/* @highlight-start @focus */} and {/* @highlight-end */} comments around the preview section. Run with --fix to add them automatically.',
+        'Demo file is missing {/* @focus-start */} and {/* @focus-end */} comments around the preview section. Run with --fix to add them automatically.',
       missingDemoFocusJsxSingle:
-        'Demo file is missing {/* @highlight @focus */} comment on the preview line. Run with --fix to add it automatically.',
+        'Demo file is missing {/* @focus */} comment on the preview line. Run with --fix to add it automatically.',
       missingDemoFocusJs:
-        'Demo file is missing // @highlight-start @focus and // @highlight-end comments around the preview section. Run with --fix to add them automatically.',
+        'Demo file is missing // @focus-start and // @focus-end comments around the preview section. Run with --fix to add them automatically.',
       missingDemoFocusJsSingle:
-        'Demo file is missing // @highlight @focus comment on the preview line. Run with --fix to add it automatically.',
+        'Demo file is missing // @focus comment on the preview line. Run with --fix to add it automatically.',
       missingDemoFocusBody:
-        'Demo file is missing // @highlight-start @focus and // @highlight-end comments around the function body. Run with --fix to add them automatically.',
+        'Demo file is missing // @focus-start and // @focus-end comments around the function body. Run with --fix to add them automatically.',
     } as const,
     schema: [
       {
@@ -193,11 +193,22 @@ export const lintJavascriptDemoFocus = {
   } as const,
   create(context) {
     const sourceCode = context.sourceCode;
-    const sourceText = sourceCode.getText();
 
     const options = (context.options[0] ?? {}) as { wrapReturn?: boolean };
 
-    if (sourceText.includes('@highlight')) {
+    // Skip files that already have @focus directives in comments — those files
+    // already control which region the viewer scrolls to.  Files with only
+    // @highlight are *not* skipped so the rule can still add @focus for the
+    // preview area.
+    // We check actual parsed comments (not raw source text) to avoid false
+    // negatives from tokens appearing in string literals or identifiers.
+    // We use includes('@focus') rather than startsWith because @focus can
+    // appear as a modifier on @highlight-start (e.g. "@highlight-start @focus").
+    const hasFocusComment = sourceCode.getAllComments().some((comment) => {
+      return comment.value.includes('@focus');
+    });
+
+    if (hasFocusComment) {
       return {};
     }
 
@@ -323,18 +334,12 @@ function reportPreview(
     messageId,
     fix(fixer) {
       if (insideWrapper && isSingleLine) {
-        return fixer.insertTextBeforeRange(
-          firstNode.range,
-          `{/* @highlight @focus */}\n${indentation}`,
-        );
+        return fixer.insertTextBeforeRange(firstNode.range, `{/* @focus */}\n${indentation}`);
       }
       if (insideWrapper) {
         return [
-          fixer.insertTextBeforeRange(
-            firstNode.range,
-            `{/* @highlight-start @focus */}\n${indentation}`,
-          ),
-          fixer.insertTextAfterRange(lastNode.range, `\n${indentation}{/* @highlight-end */}`),
+          fixer.insertTextBeforeRange(firstNode.range, `{/* @focus-start */}\n${indentation}`),
+          fixer.insertTextAfterRange(lastNode.range, `\n${indentation}{/* @focus-end */}`),
         ];
       }
 
@@ -351,7 +356,7 @@ function reportPreview(
           if (isSingleLine) {
             return fixer.insertTextBeforeRange(
               [lineStartOffset, lineStartOffset],
-              `${indentation}// @highlight @focus\n`,
+              `${indentation}// @focus\n`,
             );
           }
           const lastLineStartOffset = sourceCode.getIndexFromLoc({
@@ -363,11 +368,11 @@ function reportPreview(
           return [
             fixer.insertTextBeforeRange(
               [lineStartOffset, lineStartOffset],
-              `${indentation}// @highlight-start @focus\n`,
+              `${indentation}// @focus-start\n`,
             ),
             fixer.insertTextAfterRange(
               [lastLineStartOffset, lastLineStartOffset + lastLine.length],
-              `\n${lastIndentation}// @highlight-end`,
+              `\n${lastIndentation}// @focus-end`,
             ),
           ];
         }
@@ -382,7 +387,7 @@ function reportPreview(
           return [
             fixer.replaceTextRange(
               [returnKeywordEnd, firstNode.range[0]],
-              ` (\n${innerIndentation}// @highlight @focus\n${innerIndentation}`,
+              ` (\n${innerIndentation}// @focus\n${innerIndentation}`,
             ),
             fixer.insertTextAfterRange(lastNode.range, `\n${returnIndentation})`),
           ];
@@ -390,11 +395,11 @@ function reportPreview(
         return [
           fixer.replaceTextRange(
             [returnKeywordEnd, firstNode.range[0]],
-            ` (\n${innerIndentation}// @highlight-start @focus\n${innerIndentation}`,
+            ` (\n${innerIndentation}// @focus-start\n${innerIndentation}`,
           ),
           fixer.insertTextAfterRange(
             lastNode.range,
-            `\n${innerIndentation}// @highlight-end\n${returnIndentation})`,
+            `\n${innerIndentation}// @focus-end\n${returnIndentation})`,
           ),
         ];
       }
@@ -407,7 +412,7 @@ function reportPreview(
       if (isSingleLine) {
         return fixer.insertTextBeforeRange(
           [lineStartOffset, lineStartOffset],
-          `${indentation}// @highlight @focus\n`,
+          `${indentation}// @focus\n`,
         );
       }
       const lastLineStartOffset = sourceCode.getIndexFromLoc({
@@ -419,11 +424,11 @@ function reportPreview(
       return [
         fixer.insertTextBeforeRange(
           [lineStartOffset, lineStartOffset],
-          `${indentation}// @highlight-start @focus\n`,
+          `${indentation}// @focus-start\n`,
         ),
         fixer.insertTextAfterRange(
           [lastLineStartOffset, lastLineStartOffset + lastLine.length],
-          `\n${lastIndentation}// @highlight-end`,
+          `\n${lastIndentation}// @focus-end`,
         ),
       ];
     },
@@ -476,11 +481,11 @@ function reportFunctionBody(
       return [
         fixer.insertTextBeforeRange(
           [lineStartOffset, lineStartOffset],
-          `${indentation}// @highlight-start @focus\n`,
+          `${indentation}// @focus-start\n`,
         ),
         fixer.insertTextAfterRange(
           [lastLineStartOffset, lastLineStartOffset + lastLine.length],
-          `\n${lastIndentation}// @highlight-end`,
+          `\n${lastIndentation}// @focus-end`,
         ),
       ];
     },
diff --git a/packages/docs-infra/src/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts b/packages/docs-infra/src/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts
index 28fadc439..2a263b26d 100644
--- a/packages/docs-infra/src/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts
+++ b/packages/docs-infra/src/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts
@@ -13,6 +13,7 @@ import type { SourceEnhancers, SourceTransformers, VariantCode } from '../../Cod
 import {
   enhanceCodeEmphasis,
   EMPHASIS_COMMENT_PREFIX,
+  FOCUS_COMMENT_PREFIX,
 } from '../enhanceCodeEmphasis/enhanceCodeEmphasis';
 import { parseCreateFactoryCall } from './parseCreateFactoryCall';
 import { resolveVariantPathsWithFs } from '../loadServerCodeMeta/resolveModulePathWithFs';
@@ -171,10 +172,12 @@ export async function loadPrecomputedCodeHighlighter(
     // Always include @highlight for emphasis comments, plus any additional prefixes from options
     const notableCommentsPrefix = [
       EMPHASIS_COMMENT_PREFIX,
+      FOCUS_COMMENT_PREFIX,
       ...(factoryNotableComments ?? options.notableCommentsPrefix ?? []),
     ];
     const removeCommentsWithPrefix = [
       EMPHASIS_COMMENT_PREFIX,
+      FOCUS_COMMENT_PREFIX,
       ...IGNORE_COMMENT_PREFIXES,
       ...(factoryRemoveComments ?? options.removeCommentsWithPrefix ?? []),
     ];
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
index cd4717c49..1f30e7f21 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
@@ -5,7 +5,9 @@ import { calculateFrameRanges } from './calculateFrameRanges';
 describe('calculateFrameRanges', () => {
   describe('basic reframing', () => {
     it('should split a single highlighted line in the middle', () => {
-      const emphasizedLines = new Map<number, EmphasisMeta>([[10, { position: 'single' }]]);
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [10, { position: 'single', lineHighlight: true }],
+      ]);
 
       const result = calculateFrameRanges(emphasizedLines, 20);
 
@@ -17,7 +19,9 @@ describe('calculateFrameRanges', () => {
     });
 
     it('should handle highlight at line 1', () => {
-      const emphasizedLines = new Map<number, EmphasisMeta>([[1, { position: 'single' }]]);
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [1, { position: 'single', lineHighlight: true }],
+      ]);
 
       const result = calculateFrameRanges(emphasizedLines, 5);
 
@@ -28,7 +32,9 @@ describe('calculateFrameRanges', () => {
     });
 
     it('should handle highlight at last line', () => {
-      const emphasizedLines = new Map<number, EmphasisMeta>([[5, { position: 'single' }]]);
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [5, { position: 'single', lineHighlight: true }],
+      ]);
 
       const result = calculateFrameRanges(emphasizedLines, 5);
 
@@ -40,9 +46,9 @@ describe('calculateFrameRanges', () => {
 
     it('should handle entire code highlighted', () => {
       const emphasizedLines = new Map<number, EmphasisMeta>([
-        [1, { position: 'start' }],
-        [2, {}],
-        [3, { position: 'end' }],
+        [1, { position: 'start', lineHighlight: true }],
+        [2, { lineHighlight: true }],
+        [3, { position: 'end', lineHighlight: true }],
       ]);
 
       const result = calculateFrameRanges(emphasizedLines, 3);
@@ -52,9 +58,9 @@ describe('calculateFrameRanges', () => {
 
     it('should handle a multiline highlight region', () => {
       const emphasizedLines = new Map<number, EmphasisMeta>([
-        [5, { position: 'start' }],
-        [6, {}],
-        [7, { position: 'end' }],
+        [5, { position: 'start', lineHighlight: true }],
+        [6, { lineHighlight: true }],
+        [7, { position: 'end', lineHighlight: true }],
       ]);
 
       const result = calculateFrameRanges(emphasizedLines, 10);
@@ -68,9 +74,9 @@ describe('calculateFrameRanges', () => {
 
     it('should handle multiple disjoint highlight regions', () => {
       const emphasizedLines = new Map<number, EmphasisMeta>([
-        [3, { position: 'single' }],
-        [8, { position: 'start' }],
-        [9, { position: 'end' }],
+        [3, { position: 'single', lineHighlight: true }],
+        [8, { position: 'start', lineHighlight: true }],
+        [9, { position: 'end', lineHighlight: true }],
       ]);
 
       const result = calculateFrameRanges(emphasizedLines, 12);
@@ -86,8 +92,8 @@ describe('calculateFrameRanges', () => {
 
     it('should handle adjacent highlight regions', () => {
       const emphasizedLines = new Map<number, EmphasisMeta>([
-        [3, { position: 'single' }],
-        [4, { position: 'single' }],
+        [3, { position: 'single', lineHighlight: true }],
+        [4, { position: 'single', lineHighlight: true }],
       ]);
 
       // These are consecutive lines, so they form one region
@@ -103,7 +109,9 @@ describe('calculateFrameRanges', () => {
 
   describe('padding frames', () => {
     it('should add padding around the focused region', () => {
-      const emphasizedLines = new Map<number, EmphasisMeta>([[10, { position: 'single' }]]);
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [10, { position: 'single', lineHighlight: true }],
+      ]);
 
       const result = calculateFrameRanges(emphasizedLines, 20, {
         paddingFrameMaxSize: 5,
@@ -119,7 +127,9 @@ describe('calculateFrameRanges', () => {
     });
 
     it('should clamp padding to available lines before the highlight', () => {
-      const emphasizedLines = new Map<number, EmphasisMeta>([[3, { position: 'single' }]]);
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [3, { position: 'single', lineHighlight: true }],
+      ]);
 
       const result = calculateFrameRanges(emphasizedLines, 20, {
         paddingFrameMaxSize: 5,
@@ -135,7 +145,9 @@ describe('calculateFrameRanges', () => {
     });
 
     it('should clamp padding to available lines after the highlight', () => {
-      const emphasizedLines = new Map<number, EmphasisMeta>([[18, { position: 'single' }]]);
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [18, { position: 'single', lineHighlight: true }],
+      ]);
 
       const result = calculateFrameRanges(emphasizedLines, 20, {
         paddingFrameMaxSize: 5,
@@ -152,8 +164,8 @@ describe('calculateFrameRanges', () => {
 
     it('should only add padding to the first (focused) region', () => {
       const emphasizedLines = new Map<number, EmphasisMeta>([
-        [3, { position: 'single' }],
-        [15, { position: 'single' }],
+        [3, { position: 'single', lineHighlight: true }],
+        [15, { position: 'single', lineHighlight: true }],
       ]);
 
       const result = calculateFrameRanges(emphasizedLines, 20, {
@@ -177,7 +189,9 @@ describe('calculateFrameRanges', () => {
       // Line 10 highlighted, paddingFrameMaxSize=5, focusFramesMaxSize=8
       // remaining = 8 - 1 = 7, paddingTop = floor(7/2) = 3, paddingBottom = ceil(7/2) = 4
       // Both capped by paddingFrameMaxSize=5, so: paddingTop=3, paddingBottom=4
-      const emphasizedLines = new Map<number, EmphasisMeta>([[10, { position: 'single' }]]);
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [10, { position: 'single', lineHighlight: true }],
+      ]);
 
       const result = calculateFrameRanges(emphasizedLines, 20, {
         paddingFrameMaxSize: 5,
@@ -197,11 +211,11 @@ describe('calculateFrameRanges', () => {
       // Highlight spans 5 lines but focusFramesMaxSize is 3
       // remaining = 3 - 5 = -2, so no padding
       const emphasizedLines = new Map<number, EmphasisMeta>([
-        [5, { position: 'start' }],
-        [6, {}],
-        [7, {}],
-        [8, {}],
-        [9, { position: 'end' }],
+        [5, { position: 'start', lineHighlight: true }],
+        [6, { lineHighlight: true }],
+        [7, { lineHighlight: true }],
+        [8, { lineHighlight: true }],
+        [9, { position: 'end', lineHighlight: true }],
       ]);
 
       const result = calculateFrameRanges(emphasizedLines, 15, {
@@ -219,7 +233,9 @@ describe('calculateFrameRanges', () => {
     it('should give extra line to padding-bottom when odd remainder', () => {
       // Line 10 highlighted, focusFramesMaxSize=6
       // remaining = 6 - 1 = 5, paddingTop = floor(5/2) = 2, paddingBottom = ceil(5/2) = 3
-      const emphasizedLines = new Map<number, EmphasisMeta>([[10, { position: 'single' }]]);
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [10, { position: 'single', lineHighlight: true }],
+      ]);
 
       const result = calculateFrameRanges(emphasizedLines, 20, {
         paddingFrameMaxSize: 5,
@@ -239,7 +255,9 @@ describe('calculateFrameRanges', () => {
       // Line 10 highlighted, paddingFrameMaxSize=2, focusFramesMaxSize=20
       // remaining = 20 - 1 = 19, paddingTop = floor(19/2) = 9 → capped at 2
       // paddingBottom = ceil(19/2) = 10 → capped at 2
-      const emphasizedLines = new Map<number, EmphasisMeta>([[10, { position: 'single' }]]);
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [10, { position: 'single', lineHighlight: true }],
+      ]);
 
       const result = calculateFrameRanges(emphasizedLines, 20, {
         paddingFrameMaxSize: 2,
@@ -259,8 +277,8 @@ describe('calculateFrameRanges', () => {
   describe('@focus directive', () => {
     it('should add padding around the focused region instead of first', () => {
       const emphasizedLines = new Map<number, EmphasisMeta>([
-        [3, { position: 'single' }],
-        [15, { position: 'single', focus: true }],
+        [3, { position: 'single', lineHighlight: true }],
+        [15, { position: 'single', lineHighlight: true, focus: true }],
       ]);
 
       const result = calculateFrameRanges(emphasizedLines, 20, {
@@ -281,8 +299,8 @@ describe('calculateFrameRanges', () => {
 
     it('should use first region when no @focus specified', () => {
       const emphasizedLines = new Map<number, EmphasisMeta>([
-        [5, { position: 'single' }],
-        [15, { position: 'single' }],
+        [5, { position: 'single', lineHighlight: true }],
+        [15, { position: 'single', lineHighlight: true }],
       ]);
 
       const result = calculateFrameRanges(emphasizedLines, 20, {
@@ -312,7 +330,9 @@ describe('calculateFrameRanges', () => {
     });
 
     it('should handle single line of code that is highlighted', () => {
-      const emphasizedLines = new Map<number, EmphasisMeta>([[1, { position: 'single' }]]);
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [1, { position: 'single', lineHighlight: true }],
+      ]);
 
       const result = calculateFrameRanges(emphasizedLines, 1);
 
@@ -329,7 +349,7 @@ describe('calculateFrameRanges', () => {
 
     it('should handle text-highlighted lines as highlighted regions', () => {
       const emphasizedLines = new Map<number, EmphasisMeta>([
-        [5, { position: 'single', highlightTexts: ['Button'] }],
+        [5, { position: 'single', lineHighlight: true, highlightTexts: ['Button'] }],
       ]);
 
       const result = calculateFrameRanges(emphasizedLines, 10);
@@ -343,7 +363,9 @@ describe('calculateFrameRanges', () => {
 
     it('should not create empty padding frames when padding is 0', () => {
       // paddingFrameMaxSize=0 means no padding
-      const emphasizedLines = new Map<number, EmphasisMeta>([[5, { position: 'single' }]]);
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [5, { position: 'single', lineHighlight: true }],
+      ]);
 
       const result = calculateFrameRanges(emphasizedLines, 10, {
         paddingFrameMaxSize: 0,
@@ -362,8 +384,8 @@ describe('calculateFrameRanges', () => {
       // Second region (8) is normal (no padding for non-focused)
       // But padding-bottom of region 1 (lines 4-6) doesn't overlap with region 2 (line 8)
       const emphasizedLines = new Map<number, EmphasisMeta>([
-        [3, { position: 'single' }],
-        [8, { position: 'single' }],
+        [3, { position: 'single', lineHighlight: true }],
+        [8, { position: 'single', lineHighlight: true }],
       ]);
 
       const result = calculateFrameRanges(emphasizedLines, 12, {
@@ -384,8 +406,8 @@ describe('calculateFrameRanges', () => {
       // Lines 3 and 6 highlighted, paddingFrameMaxSize=5
       // First region (3) gets padding: top=min(2,5)=2, bottom=min(2,5)=2 (only 2 lines between regions)
       const emphasizedLines = new Map<number, EmphasisMeta>([
-        [3, { position: 'single' }],
-        [6, { position: 'single' }],
+        [3, { position: 'single', lineHighlight: true }],
+        [6, { position: 'single', lineHighlight: true }],
       ]);
 
       const result = calculateFrameRanges(emphasizedLines, 10, {
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
index 3de56e90c..564754e0e 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
@@ -12,8 +12,8 @@ export interface EmphasisMeta {
   highlightTexts?: string[];
   /** Whether this line's region is the focused region (for padding) */
   focus?: boolean;
-  /** Whether the line itself should receive data-hl (from @highlight or multiline region) */
-  lineHighlight?: boolean;
+  /** Whether the line itself should receive data-hl. True for @highlight, false for @focus-only. */
+  lineHighlight: boolean;
 }
 
 /**
@@ -30,6 +30,8 @@ export interface FrameRange {
     | 'padding-top'
     | 'highlighted'
     | 'highlighted-unfocused'
+    | 'focus'
+    | 'focus-unfocused'
     | 'padding-bottom'
     | 'comment';
 }
@@ -46,6 +48,8 @@ interface HighlightRegion {
   index: number;
   /** Whether this region is the focused region */
   focused: boolean;
+  /** Whether any line in this region has line-level highlighting (data-hl) */
+  hasLineHighlight: boolean;
 }
 
 /**
@@ -90,16 +94,22 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
 
   let regionStart = sortedLines[0];
   let regionEnd = sortedLines[0];
-  let hasFocus = emphasizedLines.get(sortedLines[0])?.focus ?? false;
+  const firstMeta = emphasizedLines.get(sortedLines[0]);
+  let hasFocus = firstMeta?.focus ?? false;
+  let hasLineHighlight = firstMeta?.lineHighlight ?? false;
 
   for (let i = 1; i < sortedLines.length; i += 1) {
     const line = sortedLines[i];
     if (line === regionEnd + 1) {
       // Consecutive line, extend current region
       regionEnd = line;
-      if (emphasizedLines.get(line)?.focus) {
+      const meta = emphasizedLines.get(line);
+      if (meta?.focus) {
         hasFocus = true;
       }
+      if (meta?.lineHighlight) {
+        hasLineHighlight = true;
+      }
     } else {
       // Gap found, close current region and start a new one
       regions.push({
@@ -107,10 +117,13 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
         endLine: regionEnd,
         index: regions.length,
         focused: hasFocus,
+        hasLineHighlight,
       });
       regionStart = line;
       regionEnd = line;
-      hasFocus = emphasizedLines.get(line)?.focus ?? false;
+      const meta = emphasizedLines.get(line);
+      hasFocus = meta?.focus ?? false;
+      hasLineHighlight = meta?.lineHighlight ?? false;
     }
   }
 
@@ -120,6 +133,7 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
     endLine: regionEnd,
     index: regions.length,
     focused: hasFocus,
+    hasLineHighlight,
   });
 
   return regions;
@@ -252,11 +266,17 @@ export function calculateFrameRanges(
       frames.push({ startLine: currentLine, endLine: region.startLine - 1, type: 'normal' });
     }
 
-    // Highlighted frame (focused gets 'highlighted', others get 'highlighted-unfocused')
+    // Frame type depends on whether the region is focused and has line highlights
+    let frameType: FrameRange['type'];
+    if (region.hasLineHighlight) {
+      frameType = isFocused ? 'highlighted' : 'highlighted-unfocused';
+    } else {
+      frameType = isFocused ? 'focus' : 'focus-unfocused';
+    }
     frames.push({
       startLine: region.startLine,
       endLine: region.endLine,
-      type: isFocused ? 'highlighted' : 'highlighted-unfocused',
+      type: frameType,
     });
 
     currentLine = region.endLine + 1;
diff --git a/packages/docs-infra/src/pipeline/parseSource/createFrame.ts b/packages/docs-infra/src/pipeline/parseSource/createFrame.ts
index 80294ec72..cfb531301 100644
--- a/packages/docs-infra/src/pipeline/parseSource/createFrame.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/createFrame.ts
@@ -28,9 +28,12 @@ export function createFrame(
     properties.dataFrameType = frameType;
   }
 
-  // Set indent level on highlighted frames (focused or unfocused)
+  // Set indent level on region frames (highlighted or focus, focused or unfocused)
   if (
-    (frameType === 'highlighted' || frameType === 'highlighted-unfocused') &&
+    (frameType === 'highlighted' ||
+      frameType === 'highlighted-unfocused' ||
+      frameType === 'focus' ||
+      frameType === 'focus-unfocused') &&
     indentLevel !== undefined
   ) {
     properties.dataFrameIndent = indentLevel;
diff --git a/packages/docs-infra/src/pipeline/parseSource/restructureFrames.ts b/packages/docs-infra/src/pipeline/parseSource/restructureFrames.ts
index e91d95ac0..3ebfb60a9 100644
--- a/packages/docs-infra/src/pipeline/parseSource/restructureFrames.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/restructureFrames.ts
@@ -111,18 +111,25 @@ export function restructureFrames(
 
     // Only create frame if it has children
     if (children.length > 0) {
-      const isHighlighted = range.type === 'highlighted' || range.type === 'highlighted-unfocused';
-      const indentLevel = isHighlighted
-        ? regionIndentLevels.get(highlightedRegionIndex)
-        : undefined;
+      const isRegion =
+        range.type === 'highlighted' ||
+        range.type === 'highlighted-unfocused' ||
+        range.type === 'focus' ||
+        range.type === 'focus-unfocused';
+      const indentLevel = isRegion ? regionIndentLevels.get(highlightedRegionIndex) : undefined;
 
       newFrames.push(
         createFrame(children, range.startLine, range.endLine, range.type, indentLevel),
       );
     }
 
-    // Increment region index after each highlighted frame (focused or unfocused)
-    if (range.type === 'highlighted' || range.type === 'highlighted-unfocused') {
+    // Increment region index after each region frame
+    if (
+      range.type === 'highlighted' ||
+      range.type === 'highlighted-unfocused' ||
+      range.type === 'focus' ||
+      range.type === 'focus-unfocused'
+    ) {
       highlightedRegionIndex += 1;
     }
   }
diff --git a/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts b/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts
index 357b5b097..d92d6b896 100644
--- a/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts
+++ b/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts
@@ -9,6 +9,7 @@ import { IGNORE_COMMENT_PREFIXES, parseImportsAndComments } from '../loaderUtils
 import {
   enhanceCodeEmphasis,
   EMPHASIS_COMMENT_PREFIX,
+  FOCUS_COMMENT_PREFIX,
 } from '../enhanceCodeEmphasis/enhanceCodeEmphasis';
 import type { Code, SourceEnhancers } from '../../CodeHighlighter/types';
 
@@ -331,8 +332,8 @@ export const transformHtmlCodeBlock: Plugin = () => {
                 {
                   removeCommentsWithPrefix: displayComments
                     ? undefined
-                    : [EMPHASIS_COMMENT_PREFIX, ...IGNORE_COMMENT_PREFIXES],
-                  notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX],
+                    : [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX, ...IGNORE_COMMENT_PREFIXES],
+                  notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX],
                 },
               );
 

From da68d0a212f79b236b73e8ae99b8a027b87dc755 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 15 Apr 2026 19:59:33 -0400
Subject: [PATCH 03/44] handle interplay between focus and highlighted portions

---
 .../code-editor/CodeEditorContent.module.css  |  15 +-
 .../demo-live/DemoLiveContent.module.css      |  15 +-
 .../demos/CodeContent.module.css              |  48 ++-
 .../demos/DemoContent.module.css              |  48 ++-
 .../demos/CodeMaxSize.tsx                     |  31 ++
 .../demos/CollapsibleContent.module.css       |  84 ++++-
 .../demos/CollapsibleDemoContent.module.css   | 266 ++++++++++++++++
 .../demos/CollapsibleDemoContent.tsx          |  96 ++++++
 .../demos/IndentContent.module.css            |  86 +++++-
 .../demos/collapsible-demo/Counter.tsx        |  15 +
 .../demos/collapsible-demo/createDemo.ts      |  24 ++
 .../demos/collapsible-demo/index.ts           |   7 +
 .../demos/max-size-code/MaxSizeCode.tsx       |  67 ++++
 .../demos/max-size-code/index.ts              |   7 +
 .../pipeline/enhance-code-emphasis/page.mdx   | 157 +++++++---
 .../pipeline/enhance-code-emphasis/types.md   |  16 +-
 .../lint-javascript-demo-focus/types.md       |  14 +-
 docs/app/docs-infra/pipeline/page.mdx         |   6 +-
 docs/components/Tabs/Tabs.module.css          |   2 +-
 docs/functions/createDemo/index.ts            |   4 +-
 .../abstractCreateDemo/abstractCreateDemo.tsx |   3 +
 .../enhanceCodeEmphasis.test.ts               | 287 ++++++++++++++----
 .../enhanceCodeEmphasis.ts                    |  79 ++++-
 .../parseImportsAndComments.test.ts           |  26 ++
 .../loaderUtils/parseImportsAndComments.ts    |   7 +
 .../parseSource/calculateFrameRanges.test.ts  | 220 ++++++++++++--
 .../parseSource/calculateFrameRanges.ts       | 122 +++++++-
 .../src/pipeline/parseSource/createFrame.ts   |   5 +
 .../parseSource/restructureFrames.test.ts     |   6 +-
 .../pipeline/parseSource/restructureFrames.ts |  34 +--
 packages/docs-infra/src/useCode/Pre.tsx       |   5 +
 31 files changed, 1558 insertions(+), 244 deletions(-)
 create mode 100644 docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeMaxSize.tsx
 create mode 100644 docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
 create mode 100644 docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
 create mode 100644 docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/Counter.tsx
 create mode 100644 docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/createDemo.ts
 create mode 100644 docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/index.ts
 create mode 100644 docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/MaxSizeCode.tsx
 create mode 100644 docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/index.ts

diff --git a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.module.css b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.module.css
index 53de3604c..09e4337c9 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.module.css
+++ b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.module.css
@@ -27,15 +27,26 @@
   display: flex;
 }
 .code {
-  padding: 6px;
+  padding: 6px 0;
 }
 
 .codeBlock {
   margin: 0;
-  padding: 6px;
+  padding: 6px 0;
   overflow-x: auto;
 }
 
+/* Code element inside pre — block so frames stretch to the widest line */
+.codeBlock :global(code) {
+  display: block;
+  min-width: fit-content;
+}
+
+.codeBlock :global(.frame) {
+  display: block;
+  padding: 0 12px;
+}
+
 .codeBlock:focus-visible {
   outline: none;
 }
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..47c2764bc 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
@@ -62,15 +62,26 @@
 }
 
 .code {
-  padding: 10px 6px;
+  padding: 10px 0;
 }
 
 .codeBlock {
   margin: 0;
-  padding: 6px;
+  padding: 6px 0;
   overflow-x: auto;
 }
 
+/* Code element inside pre — block so frames stretch to the widest line */
+.codeBlock :global(code) {
+  display: block;
+  min-width: fit-content;
+}
+
+.codeBlock :global(.frame) {
+  display: block;
+  padding: 0 12px;
+}
+
 .codeBlock:focus-visible {
   outline: none;
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css b/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css
index 5c85bfde9..8cbcc8396 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css
+++ b/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css
@@ -56,15 +56,26 @@
 }
 
 .code {
-  padding: 10px 6px;
+  padding: 10px 0;
 }
 
 .codeBlock {
   margin: 0;
-  padding: 6px;
+  padding: 6px 0;
   overflow-x: auto;
 }
 
+/* Code element inside pre — block so frames stretch to the widest line */
+.codeBlock :global(code) {
+  display: block;
+  min-width: fit-content;
+}
+
+.codeBlock :global(.frame) {
+  display: block;
+  padding: 0 12px;
+}
+
 .codeBlock :global(.frame[data-lined]) {
   display: block;
   white-space: normal;
@@ -75,6 +86,16 @@
   white-space: pre;
 }
 
+/* Highlighted frames get rounded corners and background */
+.codeBlock :global(.frame[data-frame-type='highlighted']),
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+  background: #ebe4ff;
+  border-radius: 8px;
+  margin: 0 6px;
+  padding: 0 6px;
+}
+
+/* Line-level highlight inside a frame (nested emphasis) */
 .codeBlock :global(.line[data-hl]) {
   background: #ebe4ff;
   margin: 0 -6px;
@@ -92,10 +113,6 @@
   padding: 0 6px;
 }
 
-.codeBlock :global(.line[data-hl='strong'][data-hl-position='end']) {
-  position: relative;
-}
-
 .codeBlock :global(.line[data-hl-position='single']) {
   border-radius: 8px;
 }
@@ -110,16 +127,6 @@
   border-bottom-right-radius: 8px;
 }
 
-.codeBlock :global(.line[data-hl]:has(+ .line[data-hl='strong'][data-hl-position='start'])) {
-  margin-bottom: -8px;
-  padding-bottom: 8px;
-}
-
-.codeBlock :global(.line[data-hl='strong'][data-hl-position='end']) + :global(.line[data-hl]) {
-  margin-top: -8px;
-  padding-top: 8px;
-}
-
 .codeBlock :global(.line[data-hl-description])::after {
   content: attr(data-hl-description);
   float: right;
@@ -129,3 +136,12 @@
   padding: 2px 4px;
   margin-right: -6px;
 }
+
+.codeBlock :global(.frame[data-frame-description])::before {
+  content: attr(data-frame-description);
+  float: right;
+  background: #8145b5;
+  border-radius: 8px;
+  color: white;
+  padding: 2px 4px;
+}
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.module.css b/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.module.css
index 189488d57..55c47cdf8 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.module.css
+++ b/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.module.css
@@ -63,15 +63,26 @@
 }
 
 .code {
-  padding: 10px 6px;
+  padding: 10px 0;
 }
 
 .codeBlock {
   margin: 0;
-  padding: 6px;
+  padding: 6px 0;
   overflow-x: auto;
 }
 
+/* Code element inside pre — block so frames stretch to the widest line */
+.codeBlock :global(code) {
+  display: block;
+  min-width: fit-content;
+}
+
+.codeBlock :global(.frame) {
+  display: block;
+  padding: 0 12px;
+}
+
 .codeBlock :global(.frame[data-lined]) {
   display: block;
   white-space: normal;
@@ -82,6 +93,16 @@
   white-space: pre;
 }
 
+/* Highlighted frames get rounded corners and background */
+.codeBlock :global(.frame[data-frame-type='highlighted']),
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+  background: #ebe4ff;
+  border-radius: 8px;
+  margin: 0 6px;
+  padding: 0 6px;
+}
+
+/* Line-level highlight inside a frame (nested emphasis) */
 .codeBlock :global(.line[data-hl]) {
   background: #ebe4ff;
   margin: 0 -6px;
@@ -99,10 +120,6 @@
   padding: 0 6px;
 }
 
-.codeBlock :global(.line[data-hl='strong'][data-hl-position='end']) {
-  position: relative;
-}
-
 .codeBlock :global(.line[data-hl-position='single']) {
   border-radius: 8px;
 }
@@ -117,16 +134,6 @@
   border-bottom-right-radius: 8px;
 }
 
-.codeBlock :global(.line[data-hl]:has(+ .line[data-hl='strong'][data-hl-position='start'])) {
-  margin-bottom: -8px;
-  padding-bottom: 8px;
-}
-
-.codeBlock :global(.line[data-hl='strong'][data-hl-position='end']) + :global(.line[data-hl]) {
-  margin-top: -8px;
-  padding-top: 8px;
-}
-
 .codeBlock :global(.line[data-hl-description])::after {
   content: attr(data-hl-description);
   float: right;
@@ -136,3 +143,12 @@
   padding: 2px 4px;
   margin-right: -6px;
 }
+
+.codeBlock :global(.frame[data-frame-description])::before {
+  content: attr(data-frame-description);
+  float: right;
+  background: #8145b5;
+  border-radius: 8px;
+  color: white;
+  padding: 2px 4px;
+}
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeMaxSize.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeMaxSize.tsx
new file mode 100644
index 000000000..70d430c42
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeMaxSize.tsx
@@ -0,0 +1,31 @@
+import 'server-only';
+
+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 { createEnhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+
+import { CollapsibleContent } from './CollapsibleContent';
+
+const sourceParser = createParseSource();
+const sourceEnhancers = [createEnhanceCodeEmphasis({ focusFramesMaxSize: 6 })];
+
+/**
+ * A server component that renders a collapsible code block with focusFramesMaxSize.
+ *
+ * Uses `focusFramesMaxSize: 6` so highlighted regions longer than 6 lines
+ * are split into a centered focused window with unfocused overflow.
+ */
+export function CodeMaxSize({ code }: { code: CodeType }) {
+  return (
+    // @focus-start
+    <CodeHighlighter
+      code={code}
+      Content={CollapsibleContent}
+      sourceParser={sourceParser}
+      sourceEnhancers={sourceEnhancers}
+    />
+    // @focus-end
+  );
+}
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
index f2eb0eadc..d6ad68f30 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
@@ -5,7 +5,7 @@
 }
 
 .code {
-  padding: 10px 6px;
+  padding: 10px 0 0;
 }
 
 /* Visually hidden but accessible checkbox — provides toggle state without JS */
@@ -27,6 +27,7 @@
   padding: 6px;
   border: none;
   border-top: 1px solid #d0cdd7;
+  border-radius: 0 0 7px 7px;
   background: #f5f3f8;
   color: #65636d;
   cursor: pointer;
@@ -58,16 +59,27 @@
   display: inline;
 }
 
-/* Pre element */
-.codeBlock {
+/* Pre element — `pre` qualifier needed to override layout's `.content pre { overflow-x: auto }` */
+pre.codeBlock {
   margin: 0;
-  padding: 6px;
+  padding: 6px 0;
+  overflow-x: hidden;
+}
+
+.checkbox:checked ~ .code pre.codeBlock {
   overflow-x: auto;
 }
 
+/* Code element inside pre — block so frames stretch to the widest line */
+.codeBlock :global(code) {
+  display: block;
+  min-width: fit-content;
+}
+
 /* Frame can contain multiple lines */
 .codeBlock :global(.frame) {
   display: block;
+  padding: 0 12px;
 }
 
 .codeBlock :global(.frame[data-lined]) {
@@ -80,13 +92,33 @@
   white-space: pre;
 }
 
-/* Highlighted line styling */
+/* Highlighted frames get rounded corners and background */
+.codeBlock :global(.frame[data-frame-type='highlighted']),
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+  background: #ebe4ff;
+  border-radius: 8px;
+  margin: 0 6px;
+  padding: 0 6px;
+}
+
+/* Line-level highlight inside a frame (nested emphasis) */
 .codeBlock :global(.line[data-hl]) {
   background: #ebe4ff;
   margin: 0 -6px;
   padding: 0 6px;
 }
 
+.codeBlock :global(:not(.line)[data-hl]) {
+  background: #e1d9ff;
+  border-radius: 4px;
+}
+
+.codeBlock :global(.line[data-hl='strong']) {
+  background: #e1d9ff;
+  margin: 0 -6px;
+  padding: 0 6px;
+}
+
 .codeBlock :global(.line[data-hl-position='single']) {
   border-radius: 8px;
 }
@@ -101,6 +133,37 @@
   border-bottom-right-radius: 8px;
 }
 
+.codeBlock :global(.line[data-hl-description])::after {
+  content: attr(data-hl-description);
+  float: right;
+  background: #8145b5;
+  border-radius: 8px;
+  color: white;
+  padding: 2px 4px;
+  margin-right: -6px;
+}
+
+.codeBlock :global(.frame[data-frame-description])::before {
+  content: attr(data-frame-description);
+  float: right;
+  background: #8145b5;
+  border-radius: 8px;
+  color: white;
+  padding: 2px 4px;
+}
+
+/* When truncated visible (collapsed): only round top — bottom fades out */
+.codeBlock :global(.frame[data-frame-truncated='visible']) {
+  border-radius: 8px 8px 0 0;
+  -webkit-mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
+  mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
+}
+
+/* Truncated hidden frame is the bottom of the region */
+.codeBlock :global(.frame[data-frame-truncated='hidden']) {
+  border-radius: 0 0 8px 8px;
+}
+
 /* ---- Collapsible frame behavior ---- */
 
 /* Normal frames and unfocused highlighted/focus frames are hidden by default (collapsed) */
@@ -126,7 +189,7 @@
 .checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
-  max-height: 500px;
+  max-height: 2000px;
   overflow: visible;
   opacity: 1;
 }
@@ -135,3 +198,12 @@
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='padding-bottom']) {
   opacity: 1;
 }
+
+/* ---- Truncated frame fade-out (focusFramesMaxSize split) ---- */
+
+/* Reset the mask when expanded */
+.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-truncated='visible']) {
+  -webkit-mask-image: none;
+  mask-image: none;
+  border-radius: 8px 8px 0 0;
+}
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
new file mode 100644
index 000000000..2be02f7d3
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
@@ -0,0 +1,266 @@
+.container {
+  border: 1px solid #d0cdd7;
+  border-radius: 8px;
+}
+
+.demoSection {
+  padding: 24px;
+  border-radius: 7px 7px 0 0;
+}
+
+.codeSection {
+  border-top: 1px solid #d0cdd7;
+  overflow: hidden;
+}
+
+.header {
+  border-bottom: 1px solid #d0cdd7;
+  height: 48px;
+  position: relative;
+}
+
+.headerContainer {
+  position: absolute;
+  width: 100%;
+  display: flex;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.headerContainer::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  bottom: 0;
+  width: 1px;
+  margin: -1px;
+  background-color: #d0cdd7;
+}
+
+.headerActions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding-right: 8px;
+  height: 48px;
+}
+
+.tabContainer {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-left: -1px;
+  padding-bottom: 2px;
+  overflow-x: auto;
+}
+
+.switchContainer {
+  display: flex;
+}
+
+.code {
+  padding: 10px 0 0;
+}
+
+/* Visually hidden but accessible checkbox — provides toggle state without JS */
+.checkbox {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+.toggle {
+  display: block;
+  width: 100%;
+  padding: 6px;
+  border: none;
+  border-top: 1px solid #d0cdd7;
+  border-radius: 0 0 7px 7px;
+  background: #f5f3f8;
+  color: #65636d;
+  cursor: pointer;
+  font-size: 12px;
+  font-family: var(--font-geist-mono);
+  text-align: center;
+}
+
+.toggle:hover {
+  background: #eae7ef;
+}
+
+/* Show focus ring on toggle when checkbox receives keyboard focus */
+.checkbox:focus-visible ~ .toggle {
+  outline: 2px solid #8b5cf6;
+  outline-offset: -2px;
+}
+
+/* Toggle label text based on checkbox state */
+.collapseLabel {
+  display: none;
+}
+
+.checkbox:checked ~ .toggle .expandLabel {
+  display: none;
+}
+
+.checkbox:checked ~ .toggle .collapseLabel {
+  display: inline;
+}
+
+/* Pre element — `pre` qualifier needed to override layout's `.content pre { overflow-x: auto }` */
+pre.codeBlock {
+  margin: 0;
+  padding: 6px 0;
+  overflow-x: hidden;
+}
+
+.checkbox:checked ~ .code pre.codeBlock {
+  overflow-x: auto;
+}
+
+/* Code element inside pre — block so frames stretch to the widest line */
+.codeBlock :global(code) {
+  display: block;
+  min-width: fit-content;
+}
+
+/* Frame can contain multiple lines */
+.codeBlock :global(.frame) {
+  display: block;
+  padding: 0 12px;
+}
+
+.codeBlock :global(.frame[data-lined]) {
+  display: block;
+  white-space: normal;
+}
+
+.codeBlock :global(.frame[data-lined] .line) {
+  display: block;
+  white-space: pre;
+}
+
+/* Highlighted frames get rounded corners and background */
+.codeBlock :global(.frame[data-frame-type='highlighted']),
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+  background: #ebe4ff;
+  border-radius: 8px;
+  margin: 0 6px;
+  padding: 0 6px;
+}
+
+/* Line-level highlight inside a frame (nested emphasis) */
+.codeBlock :global(.line[data-hl]) {
+  background: #ebe4ff;
+  margin: 0 -6px;
+  padding: 0 6px;
+}
+
+.codeBlock :global(:not(.line)[data-hl]) {
+  background: #e1d9ff;
+  border-radius: 4px;
+}
+
+.codeBlock :global(.line[data-hl='strong']) {
+  background: #e1d9ff;
+  margin: 0 -6px;
+  padding: 0 6px;
+}
+
+.codeBlock :global(.line[data-hl-position='single']) {
+  border-radius: 8px;
+}
+
+.codeBlock :global(.line[data-hl-position='start']) {
+  border-top-left-radius: 8px;
+  border-top-right-radius: 8px;
+}
+
+.codeBlock :global(.line[data-hl-position='end']) {
+  border-bottom-left-radius: 8px;
+  border-bottom-right-radius: 8px;
+}
+
+.codeBlock :global(.line[data-hl-description])::after {
+  content: attr(data-hl-description);
+  float: right;
+  background: #8145b5;
+  border-radius: 8px;
+  color: white;
+  padding: 2px 4px;
+  margin-right: -6px;
+}
+
+.codeBlock :global(.frame[data-frame-description])::before {
+  content: attr(data-frame-description);
+  float: right;
+  background: #8145b5;
+  border-radius: 8px;
+  color: white;
+  padding: 2px 4px;
+}
+
+/* When truncated visible (collapsed): only round top — bottom fades out */
+.codeBlock :global(.frame[data-frame-truncated='visible']) {
+  border-radius: 8px 8px 0 0;
+  -webkit-mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
+  mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
+}
+
+/* Truncated hidden frame is the bottom of the region */
+.codeBlock :global(.frame[data-frame-truncated='hidden']) {
+  border-radius: 0 0 8px 8px;
+}
+
+/* ---- Collapsible frame behavior ---- */
+
+/* Normal frames and unfocused highlighted/focus frames are hidden by default (collapsed) */
+.codeBlock :global(.frame:not([data-frame-type])),
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+.codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+  max-height: 0;
+  overflow: hidden;
+  opacity: 0;
+  transition:
+    max-height 0.3s ease,
+    opacity 0.3s ease;
+}
+
+/* Padding frames appear dimmed when collapsed */
+.codeBlock :global(.frame[data-frame-type='padding-top']),
+.codeBlock :global(.frame[data-frame-type='padding-bottom']) {
+  opacity: 0.5;
+  transition: opacity 0.3s ease;
+}
+
+/* When checkbox is checked (expanded), show all frames */
+.checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
+.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+  max-height: 2000px;
+  overflow: visible;
+  opacity: 1;
+}
+
+.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='padding-top']),
+.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='padding-bottom']) {
+  opacity: 1;
+}
+
+/* Reset the mask when expanded */
+.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-truncated='visible']) {
+  -webkit-mask-image: none;
+  mask-image: none;
+  border-radius: 8px 8px 0 0;
+}
+
+.fileRefs {
+  display: none;
+}
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
new file mode 100644
index 000000000..0c5a956d4
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
@@ -0,0 +1,96 @@
+'use client';
+
+import * as React from 'react';
+import type { ContentProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
+import { useDemo } from '@mui/internal-docs-infra/useDemo';
+import { LabeledSwitch } from '@/components/LabeledSwitch';
+import { Tabs } from '@/components/Tabs';
+import { CopyButton } from '@/components/CopyButton';
+import { Select } from '@/components/Select';
+import styles from './CollapsibleDemoContent.module.css';
+
+import '@wooorm/starry-night/style/light';
+
+const variantNames: Record<string, string | undefined> = {
+  CssModules: 'CSS Modules',
+};
+
+export function CollapsibleDemoContent(props: ContentProps<object>) {
+  // @focus-start
+  const demo = useDemo(props, { preClassName: styles.codeBlock });
+
+  const hasJsTransform = demo.availableTransforms.includes('js');
+  const isJsSelected = demo.selectedTransform === 'js';
+
+  const labels = { false: 'TS', true: 'JS' };
+  const toggleJs = React.useCallback(
+    (checked: boolean) => {
+      demo.selectTransform(checked ? 'js' : null);
+    },
+    [demo],
+  );
+
+  const tabs = React.useMemo(
+    () => demo.files.map(({ name, slug }) => ({ id: name, name, slug })),
+    [demo.files],
+  );
+  const variants = React.useMemo(
+    () =>
+      demo.variants.map((variant) => ({ value: variant, label: variantNames[variant] || variant })),
+    [demo.variants],
+  );
+
+  const id = React.useId();
+  const checkboxId = `${id}-expand`;
+
+  return (
+    <div>
+      {demo.allFilesSlugs.map(({ slug }) => (
+        <span key={slug} id={slug} className={styles.fileRefs} />
+      ))}
+      <div className={styles.container}>
+        <div className={styles.demoSection}>{demo.component}</div>
+        <div className={styles.codeSection}>
+          <div className={styles.header}>
+            <div className={styles.headerContainer}>
+              <div className={styles.tabContainer}>
+                <Tabs
+                  tabs={tabs}
+                  selectedTabId={demo.selectedFileName}
+                  onTabSelect={demo.selectFileName}
+                />
+              </div>
+              <div className={styles.headerActions}>
+                <CopyButton copy={demo.copy} />
+                {demo.variants.length > 1 && (
+                  <Select
+                    items={variants}
+                    value={demo.selectedVariant}
+                    onValueChange={demo.selectVariant}
+                  />
+                )}
+                {hasJsTransform && (
+                  <div className={styles.switchContainer}>
+                    <LabeledSwitch
+                      checked={isJsSelected}
+                      onCheckedChange={toggleJs}
+                      labels={labels}
+                    />
+                  </div>
+                )}
+              </div>
+            </div>
+          </div>
+          {/* Visually hidden checkbox provides no-JS toggle state via CSS :checked */}
+          <input type="checkbox" id={checkboxId} className={styles.checkbox} />
+          <div className={styles.code}>{demo.selectedFile}</div>
+          <label htmlFor={checkboxId} className={styles.toggle}>
+            <span className={styles.expandLabel}>Expand</span>
+            <span className={styles.collapseLabel}>Collapse</span>
+          </label>
+        </div>
+      </div>
+    </div>
+  );
+  // @focus-end
+}
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
index 031de83b3..ddef991aa 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
@@ -5,7 +5,7 @@
 }
 
 .code {
-  padding: 10px 6px;
+  padding: 10px 0 0;
 }
 
 .toggle {
@@ -14,6 +14,7 @@
   padding: 6px;
   border: none;
   border-top: 1px solid #d0cdd7;
+  border-radius: 0 0 7px 7px;
   background: #f5f3f8;
   color: #65636d;
   cursor: pointer;
@@ -25,16 +26,27 @@
   background: #eae7ef;
 }
 
-/* Pre element */
-.codeBlock {
+/* Pre element — `pre` qualifier needed to override layout's `.content pre { overflow-x: auto }` */
+pre.codeBlock {
   margin: 0;
-  padding: 6px;
+  padding: 6px 0;
+  overflow-x: hidden;
+}
+
+.expanded pre.codeBlock {
   overflow-x: auto;
 }
 
+/* Code element inside pre — block so frames stretch to the widest line */
+.codeBlock :global(code) {
+  display: block;
+  min-width: fit-content;
+}
+
 /* Frame can contain multiple lines */
 .codeBlock :global(.frame) {
   display: block;
+  padding: 0 12px;
 }
 
 .codeBlock :global(.frame[data-lined]) {
@@ -47,13 +59,33 @@
   white-space: pre;
 }
 
-/* Highlighted line styling */
+/* Highlighted frames get rounded corners and background */
+.codeBlock :global(.frame[data-frame-type='highlighted']),
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+  background: #ebe4ff;
+  border-radius: 8px;
+  margin: 0 6px;
+  padding: 0 6px;
+}
+
+/* Line-level highlight inside a frame (nested emphasis) */
 .codeBlock :global(.line[data-hl]) {
   background: #ebe4ff;
   margin: 0 -6px;
   padding: 0 6px;
 }
 
+.codeBlock :global(:not(.line)[data-hl]) {
+  background: #e1d9ff;
+  border-radius: 4px;
+}
+
+.codeBlock :global(.line[data-hl='strong']) {
+  background: #e1d9ff;
+  margin: 0 -6px;
+  padding: 0 6px;
+}
+
 .codeBlock :global(.line[data-hl-position='single']) {
   border-radius: 8px;
 }
@@ -68,6 +100,37 @@
   border-bottom-right-radius: 8px;
 }
 
+.codeBlock :global(.line[data-hl-description])::after {
+  content: attr(data-hl-description);
+  float: right;
+  background: #8145b5;
+  border-radius: 8px;
+  color: white;
+  padding: 2px 4px;
+  margin-right: -6px;
+}
+
+.codeBlock :global(.frame[data-frame-description])::before {
+  content: attr(data-frame-description);
+  float: right;
+  background: #8145b5;
+  border-radius: 8px;
+  color: white;
+  padding: 2px 4px;
+}
+
+/* When truncated visible (collapsed): only round top — bottom fades out */
+.codeBlock :global(.frame[data-frame-truncated='visible']) {
+  border-radius: 8px 8px 0 0;
+  -webkit-mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
+  mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
+}
+
+/* Truncated hidden frame is the bottom of the region */
+.codeBlock :global(.frame[data-frame-truncated='hidden']) {
+  border-radius: 0 0 8px 8px;
+}
+
 /* ---- Collapsible frame behavior (no padding, just highlighted vs normal) ---- */
 
 /* Normal frames and unfocused highlighted/focus frames are hidden by default */
@@ -86,11 +149,20 @@
 .expanded .codeBlock :global(.frame:not([data-frame-type])),
 .expanded .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
 .expanded .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
-  max-height: 500px;
+  max-height: 2000px;
   overflow: visible;
   opacity: 1;
 }
 
+/* ---- Truncated frame fade-out (focusFramesMaxSize split) ---- */
+
+/* Reset the mask when expanded */
+.expanded .codeBlock :global(.frame[data-frame-truncated='visible']) {
+  -webkit-mask-image: none;
+  mask-image: none;
+  border-radius: 8px 8px 0 0;
+}
+
 /* ---- Indent shifting: move highlighted/focus frame left by its indent level ---- */
 
 .codeBlock :global(.frame[data-frame-type='highlighted']),
@@ -141,5 +213,5 @@
 /* Reset indent shift when expanded */
 .expanded .codeBlock :global(.frame[data-frame-type='highlighted']),
 .expanded .codeBlock :global(.frame[data-frame-type='focus']) {
-  margin-left: 0;
+  margin-left: 6px;
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/Counter.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/Counter.tsx
new file mode 100644
index 000000000..4b2d64690
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/Counter.tsx
@@ -0,0 +1,15 @@
+'use client';
+
+import * as React from 'react';
+
+export function Counter() {
+  // @focus-start
+  const [count, setCount] = React.useState(0);
+
+  return (
+    <button type="button" onClick={() => setCount((c) => c + 1)}>
+      Count: {count} {/* @highlight */}
+    </button>
+  );
+  // @focus-end
+}
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/createDemo.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/createDemo.ts
new file mode 100644
index 000000000..bd37e10f1
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/createDemo.ts
@@ -0,0 +1,24 @@
+import 'server-only';
+
+import {
+  createDemoFactory,
+  createDemoWithVariantsFactory,
+} from '@mui/internal-docs-infra/abstractCreateDemo';
+import { createEnhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+
+import { CollapsibleDemoContent as DemoContent } from '../CollapsibleDemoContent';
+import { DemoTitle } from '../../../../components/code-highlighter/demos/DemoTitle';
+
+const sourceEnhancers = [createEnhanceCodeEmphasis({ paddingFrameMaxSize: 3 })];
+
+export const createDemo = createDemoFactory({
+  DemoContent,
+  DemoTitle,
+  sourceEnhancers,
+});
+
+export const createDemoWithVariants = createDemoWithVariantsFactory({
+  DemoContent,
+  DemoTitle,
+  sourceEnhancers,
+});
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/index.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/index.ts
new file mode 100644
index 000000000..f27ff4182
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/index.ts
@@ -0,0 +1,7 @@
+import { createDemo } from './createDemo';
+import { Counter } from './Counter';
+
+export const DemoCollapsibleDemo = createDemo(import.meta.url, Counter, {
+  name: 'Collapsible Demo',
+  slug: 'collapsible-demo',
+});
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/MaxSizeCode.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/MaxSizeCode.tsx
new file mode 100644
index 000000000..0c141fd24
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/MaxSizeCode.tsx
@@ -0,0 +1,67 @@
+import * as React from 'react';
+import type { Code as CodeType } from '@mui/internal-docs-infra/CodeHighlighter/types';
+import { parseImportsAndComments } from '@mui/internal-docs-infra/pipeline/loaderUtils';
+import { EMPHASIS_COMMENT_PREFIX } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+import { CodeMaxSize } from '../CodeMaxSize';
+
+const source = `import * as React from 'react';
+
+interface FormData {
+  name: string;
+  email: string;
+  message: string;
+}
+
+export function ContactForm() {
+  const [form, setForm] = React.useState<FormData>({
+    name: '',
+    email: '',
+    message: '',
+  });
+
+  const handleSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    const response = await fetch('/api/contact', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(form),
+    });
+    if (!response.ok) {
+      throw new Error('Failed to submit');
+    }
+    setForm({ name: '', email: '', message: '' });
+  };
+
+  return (
+    // @highlight-start
+    <form onSubmit={handleSubmit}>
+      <label htmlFor="name">Name</label>
+      <input id="name" value={form.name} onChange={(e) => setForm({ ...form, name: e.target.value })} />
+      <label htmlFor="email">Email</label>
+      <input id="email" value={form.email} onChange={(e) => setForm({ ...form, email: e.target.value })} />
+      <label htmlFor="message">Message</label>
+      <textarea id="message" value={form.message} onChange={(e) => setForm({ ...form, message: e.target.value })} />
+      <button type="submit">Send</button>
+    </form>
+    // @highlight-end
+  );
+}`;
+
+export async function MaxSizeCode() {
+  // @focus-start
+  const { code: strippedSource, comments } = await parseImportsAndComments(source, '/demo.tsx', {
+    removeCommentsWithPrefix: [EMPHASIS_COMMENT_PREFIX],
+    notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX],
+  });
+
+  const code: CodeType = {
+    Default: {
+      language: 'tsx',
+      source: strippedSource!,
+      comments,
+    },
+  };
+
+  return <CodeMaxSize code={code} />;
+  // @focus-end
+}
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/index.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/index.ts
new file mode 100644
index 000000000..d490c6552
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/index.ts
@@ -0,0 +1,7 @@
+import { createDemo } from '@/functions/createDemo';
+import { MaxSizeCode } from './MaxSizeCode';
+
+export const DemoMaxSizeCode = createDemo(import.meta.url, MaxSizeCode, {
+  name: 'Focus Max Size',
+  slug: 'focus-max-size',
+});
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 958cb5fd7..07632af9e 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
@@ -290,10 +290,11 @@ When padding is configured (see [Configurable Padding](#configurable-padding)),
 
 ### Frame Data Attributes
 
-| 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).                                                                                                                                                                |
+| 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-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
 
@@ -310,11 +311,11 @@ const sourceEnhancers = [
 ];
 ```
 
-| Option                | Type    | Default | Description                                                                                                                                                                                                                              |
-| --------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `paddingFrameMaxSize` | number  | `0`     | Maximum number of context lines above/below the focused region                                                                                                                                                                           |
-| `focusFramesMaxSize`  | number  | —       | Maximum total lines in the focus area (padding + highlighted). Remaining budget is split floor/ceil (extra line goes to bottom).                                                                                                         |
-| `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. |
+| Option                | Type    | Default | Description                                                                                                                                                                                                                                                                                                        |
+| --------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `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.                                                                           |
 
 When `paddingFrameMaxSize` is `0` (the default), no padding frames are created and only region frames (`highlighted`, `focus`, etc.) and normal frames are produced.
 
@@ -333,13 +334,6 @@ const config = getConfig();
 // @highlight-end
 ```
 
-```css
-.Viewport::after {
-  /* @highlight */
-  height: min(40px, var(--scroll-area-overflow-y-end, 40px)); /* @highlight-text ", 40px" */
-}
-```
-
 In this example, `@focus` directs the padding frames to surround the `ThemeProvider` block instead of the `theme` line.
 
 `@focus` can be combined with any highlight directive:
@@ -369,9 +363,18 @@ This is particularly useful when an ESLint rule like [`lintJavascriptDemoFocus`]
 
 ### Styling Frame Types
 
-Target frame types with CSS to create collapsible code blocks:
+Target frame types with CSS to style highlighted frames and create collapsible code blocks:
 
 ```css
+/* Highlighted frames get rounded corners and background */
+.codeBlock .frame[data-frame-type='highlighted'],
+.codeBlock .frame[data-frame-type='highlighted-unfocused'] {
+  background: #ebe4ff;
+  border-radius: 8px;
+  margin: 0 6px;
+  padding: 0 6px;
+}
+
 /* Normal frames and unfocused highlighted/focus frames are hidden by default (collapsed) */
 .codeBlock .frame:not([data-frame-type]),
 .codeBlock .frame[data-frame-type='highlighted-unfocused'],
@@ -436,6 +439,14 @@ import { DemoCollapsibleCode } from './demos/collapsible-code';
 
 <DemoCollapsibleCode />
 
+### Demo: Collapsible Demo
+
+A full demo component with a live preview, file tabs, and collapsible code. The code section starts collapsed, showing only the focused region.
+
+import { DemoCollapsibleDemo } from './demos/collapsible-demo';
+
+<DemoCollapsibleDemo />
+
 ### Demo: @focus with Multiple Regions
 
 This demo uses `@highlight` on the `formatDate` call and standalone `@focus-start`/`@focus-end` around the `useEffect` block. The `useEffect` region is focused (padding frames surround it) but has no line-level highlighting, while the `formatDate` line has line-level highlighting but is unfocused.
@@ -452,6 +463,14 @@ import { DemoIndentCode } from './demos/indent-code';
 
 <DemoIndentCode />
 
+### Demo: Focus Max Size
+
+When `focusFramesMaxSize` is set and a highlighted region exceeds that limit, a focused window is taken from the start of the region, and the remaining overflow lines are marked as unfocused. This demo uses `focusFramesMaxSize: 6` with the `<form>` JSX highlighted (10 lines). When collapsed, only the first 6 lines of the region are visible; expanding reveals the full highlighted region with the overflow lines.
+
+import { DemoMaxSizeCode } from './demos/max-size-code';
+
+<DemoMaxSizeCode />
+
 ---
 
 ## Implementation Details
@@ -496,7 +515,8 @@ For text highlighting with `@highlight-text "text"`, the specified text within t
 
 ### Data Attributes
 
-The enhancer adds these attributes to line elements:
+The enhancer adds these attributes to line elements when the highlight is nested
+(inside a focus frame or strong from nesting):
 
 | Attribute             | Type   | Description                                                                                        |
 | --------------------- | ------ | -------------------------------------------------------------------------------------------------- |
@@ -504,6 +524,10 @@ The enhancer adds these attributes to line elements:
 | `data-hl-description` | string | Description text (if provided in comment)                                                          |
 | `data-hl-position`    | string | `"single"` for single-line, `"start"` or `"end"` for multiline range bounds (from innermost range) |
 
+For standalone highlights (no focus context, not nested), the visual emphasis is
+handled entirely at the frame level. The frame receives `data-frame-description`
+if a description was provided (see [Frame Data Attributes](#frame-data-attributes)).
+
 For single-line emphasis with `@highlight`:
 
 - `data-hl` is set (or `data-hl="strong"` if description ends with `!`)
@@ -517,6 +541,10 @@ For multi-line emphasis with `@highlight-start` / `@highlight-end`:
 - `data-hl-position="start"` is set on the **first** line (only for ranges with more than one line)
 - `data-hl-position="end"` is set on the **last** line (only for ranges with more than one line)
 
+> **Note**: The above line-level attributes are only applied when the highlight is
+> inside a focus region or is nested (strong). For standalone highlights, descriptions
+> are placed on the frame element as `data-frame-description` instead.
+
 For text highlighting with `@highlight-text "text"`:
 
 - The specified text within the line is wrapped in a `<span data-hl="">` element
@@ -607,7 +635,26 @@ console.log(FOCUS_COMMENT_PREFIX); // '@focus'
 
 ## Styling Emphasized Lines
 
-The `data-hl` attribute can be targeted with CSS. First, ensure lines are displayed as blocks for proper highlighting:
+### Frame-Level Highlighting
+
+When `@highlight` is used without `@focus`, the enhancer wraps highlighted lines in a frame with `data-frame-type="highlighted"`. Style these frames with background and rounded corners:
+
+```css
+/* Highlighted frames get rounded corners and background */
+.frame[data-frame-type='highlighted'],
+.frame[data-frame-type='highlighted-unfocused'] {
+  background: #ebe4ff;
+  border-radius: 8px;
+  margin: 0 6px;
+  padding: 0 6px;
+}
+```
+
+The `margin: 0 6px` pulls the frame inward from the `padding: 0 12px` on the parent `.frame`, so highlighted frames appear visually inset. The `padding: 0 6px` ensures child content still has horizontal spacing.
+
+### Line-Level Highlighting
+
+When `@highlight` lines appear inside a `@focus` region, or when highlights are nested, the individual lines receive `data-hl` attributes. Style these with negative margins that expand into the parent frame's padding:
 
 ```css
 /* Required: Display lines as blocks for line-based highlighting */
@@ -621,60 +668,72 @@ The `data-hl` attribute can be targeted with CSS. First, ensure lines are displa
   white-space: pre;
 }
 
-/* Highlight emphasized lines */
+/* Line-level highlight inside a frame (nested emphasis) */
 .line[data-hl] {
-  background-color: rgba(255, 255, 0, 0.1);
-  border-left: 2px solid #ffd700;
-  padding-left: 8px;
+  background: #ebe4ff;
+  margin: 0 -6px;
+  padding: 0 6px;
 }
 
-/* Strong emphasis for critical lines (descriptions ending with !) */
+/* Text-level highlight (from @highlight-text) */
+:not(.line)[data-hl] {
+  background: #e1d9ff;
+  border-radius: 4px;
+}
+
+/* Strong emphasis for nested highlights or descriptions ending with ! */
 .line[data-hl='strong'] {
-  background-color: rgba(255, 100, 100, 0.15);
-  border-left: 3px solid #ff4444;
+  background: #e1d9ff;
+  margin: 0 -6px;
+  padding: 0 6px;
 }
 
 /* Single-line emphasis - rounded on all corners */
 .line[data-hl-position='single'] {
-  border-radius: 4px;
+  border-radius: 8px;
 }
 
 /* Multiline block start - rounded top corners */
 .line[data-hl-position='start'] {
-  border-top-left-radius: 4px;
-  border-top-right-radius: 4px;
+  border-top-left-radius: 8px;
+  border-top-right-radius: 8px;
 }
 
 /* Multiline block end - rounded bottom corners */
 .line[data-hl-position='end'] {
-  border-bottom-left-radius: 4px;
-  border-bottom-right-radius: 4px;
-}
-
-/* Dark mode variant */
-@media (prefers-color-scheme: dark) {
-  .line[data-hl] {
-    background-color: rgba(255, 255, 0, 0.05);
-    border-left-color: #b8860b;
-  }
-
-  .line[data-hl='strong'] {
-    background-color: rgba(255, 100, 100, 0.1);
-    border-left-color: #cc3333;
-  }
+  border-bottom-left-radius: 8px;
+  border-bottom-right-radius: 8px;
 }
 ```
 
 ### Showing Descriptions
 
-You can display the description using CSS `::before`:
+Descriptions can appear on lines (for nested highlights) or frames (for standalone highlights).
+
+**Line-level descriptions** (highlight inside focus, or nested/strong):
 
 ```css
-/* Show description as tooltip */
-.line[data-hl-description]::before {
+.line[data-hl-description]::after {
   content: attr(data-hl-description);
-  position: absolute;
-  /* ... tooltip styles */
+  float: right;
+  background: #8145b5;
+  border-radius: 8px;
+  color: white;
+  padding: 2px 4px;
+  margin-right: -6px;
+}
+```
+
+**Frame-level descriptions** (standalone highlights):
+
+```css
+.frame[data-frame-description]::before {
+  content: attr(data-frame-description);
+  float: right;
+  background: #8145b5;
+  border-radius: 8px;
+  color: white;
+  padding: 2px 4px;
 }
 ```
 
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 c74727465..80b9c50de 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
@@ -98,10 +98,12 @@ type EnhanceCodeEmphasisOptions = {
    */
   paddingFrameMaxSize?: number;
   /**
-   * Maximum total number of lines in the focus area (padding-top + highlighted + padding-bottom).
-   * When set, padding sizes are reduced so the total focus area fits within this limit.
-   * The remainder after subtracting the highlighted size is split: floor(remainder/2) for
+   * Maximum total number of lines in the focus area (padding-top + focused region + padding-bottom).
+   * When the region fits within this limit, padding sizes are reduced so the total focus area
+   * fits. The remainder after subtracting the region size is split: floor(remainder/2) for
    * padding-top and ceil(remainder/2) for 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.
    */
   focusFramesMaxSize?: number;
   /**
@@ -143,6 +145,14 @@ type FrameRange = {
     | 'focus-unfocused'
     | 'padding-bottom'
     | 'comment';
+  /** Index of the highlighted region this frame belongs to. Present on region-type frames. */
+  regionIndex?: number;
+  /**
+   * Present on frames created by splitting an oversized region via `focusFramesMaxSize`.
+   * - `'visible'` — the focused window kept visible when collapsed.
+   * - `'hidden'`  — the overflow portion hidden when collapsed.
+   */
+  truncated?: 'visible' | 'hidden';
 };
 ```
 
diff --git a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md
index fe25ae84e..1458c0dfc 100644
--- a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md
+++ b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md
@@ -8,22 +8,22 @@
 
 ### lintJavascriptDemoFocus
 
-ESLint rule requiring demo files to have highlight-focus comments around the preview section.
+ESLint rule requiring demo files to have focus comments around the preview section.
 
 ```typescript
 type lintJavascriptDemoFocus = {
   meta: {
     type: 'suggestion';
     docs: {
-      description: 'Require demo files to have @highlight-start @focus / @highlight-end comments around the preview section.';
+      description: 'Require demo files to have @focus-start / @focus-end comments around the preview section.';
     };
     fixable: 'code';
     messages: {
-      missingDemoFocusJsx: 'Demo file is missing {/* @highlight-start @focus */} and {/* @highlight-end */} comments around the preview section. Run with --fix to add them automatically.';
-      missingDemoFocusJsxSingle: 'Demo file is missing {/* @highlight @focus */} comment on the preview line. Run with --fix to add it automatically.';
-      missingDemoFocusJs: 'Demo file is missing // @highlight-start @focus and // @highlight-end comments around the preview section. Run with --fix to add them automatically.';
-      missingDemoFocusJsSingle: 'Demo file is missing // @highlight @focus comment on the preview line. Run with --fix to add it automatically.';
-      missingDemoFocusBody: 'Demo file is missing // @highlight-start @focus and // @highlight-end comments around the function body. Run with --fix to add them automatically.';
+      missingDemoFocusJsx: 'Demo file is missing {/* @focus-start */} and {/* @focus-end */} comments around the preview section. Run with --fix to add them automatically.';
+      missingDemoFocusJsxSingle: 'Demo file is missing {/* @focus */} comment on the preview line. Run with --fix to add it automatically.';
+      missingDemoFocusJs: 'Demo file is missing // @focus-start and // @focus-end comments around the preview section. Run with --fix to add them automatically.';
+      missingDemoFocusJsSingle: 'Demo file is missing // @focus comment on the preview line. Run with --fix to add it automatically.';
+      missingDemoFocusBody: 'Demo file is missing // @focus-start and // @focus-end comments around the function body. Run with --fix to add them automatically.';
     };
     schema: [
       {
diff --git a/docs/app/docs-infra/pipeline/page.mdx b/docs/app/docs-infra/pipeline/page.mdx
index 1a815aa59..922065146 100644
--- a/docs/app/docs-infra/pipeline/page.mdx
+++ b/docs/app/docs-infra/pipeline/page.mdx
@@ -72,8 +72,10 @@ The `enhanceCodeEmphasis` source enhancer adds visual emphasis to specific lines
     - Standalone `@focus` (Focus Without Highlight)
     - Styling Frame Types
     - Demo: Collapsible Code Block
+    - Demo: Collapsible Demo
     - Demo: @focus with Multiple Regions
     - Demo: Indent Shifting
+    - Demo: Focus Max Size
   - Implementation Details
     - How It Works
     - HAST Structure
@@ -83,6 +85,8 @@ The `enhanceCodeEmphasis` source enhancer adds visual emphasis to specific lines
     - Adding to Source Enhancers
     - Comment Prefix
   - Styling Emphasized Lines
+    - Frame-Level Highlighting
+    - Line-Level Highlighting
     - Showing Descriptions
   - Best Practices
     - Be Specific
@@ -309,7 +313,7 @@ The `hastUtils` module provides utilities for converting between HAST (Hypertext
 
 ## Lint JavaScript Demo Focus
 
-An ESLint rule that automatically inserts `@highlight` and `@focus` comments around the preview section of demo files. These comments control which parts of the code are highlighted and focused when rendered in documentation.
+An ESLint rule that automatically inserts `@focus` comments around the preview section of demo files. These comments control which parts of the code are focused when rendered in documentation.
 
 <details>
 
diff --git a/docs/components/Tabs/Tabs.module.css b/docs/components/Tabs/Tabs.module.css
index 244f83c0e..d082fc34d 100644
--- a/docs/components/Tabs/Tabs.module.css
+++ b/docs/components/Tabs/Tabs.module.css
@@ -7,7 +7,7 @@
   gap: 0;
   overflow-x: auto;
   max-width: 100%;
-  padding-top: 14px;
+  padding-top: 13px;
 }
 
 .name {
diff --git a/docs/functions/createDemo/index.ts b/docs/functions/createDemo/index.ts
index 988a50dea..db385105a 100644
--- a/docs/functions/createDemo/index.ts
+++ b/docs/functions/createDemo/index.ts
@@ -1,2 +1,2 @@
-// dog-food the demo content
-export * from '../../app/docs-infra/components/code-highlighter/demos/createDemo';
+// dog-food the collapsible demo content
+export * from '../../app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/createDemo';
diff --git a/packages/docs-infra/src/abstractCreateDemo/abstractCreateDemo.tsx b/packages/docs-infra/src/abstractCreateDemo/abstractCreateDemo.tsx
index e1eb1e55a..42a30325a 100644
--- a/packages/docs-infra/src/abstractCreateDemo/abstractCreateDemo.tsx
+++ b/packages/docs-infra/src/abstractCreateDemo/abstractCreateDemo.tsx
@@ -10,6 +10,7 @@ import type {
   LoadSource,
   LoadVariantMeta,
   ParseSource,
+  SourceEnhancers,
 } from '../CodeHighlighter/types';
 import { createDemoDataWithVariants } from '../createDemoData';
 import { DemoGlobalData } from '../createDemoData/types';
@@ -41,6 +42,7 @@ type AbstractCreateDemoOptions<T extends {}> = {
   loadVariantMeta?: LoadVariantMeta;
   loadSource?: LoadSource;
   sourceParser?: Promise<ParseSource>;
+  sourceEnhancers?: SourceEnhancers;
 };
 
 export function abstractCreateDemo<T extends {}>(
@@ -85,6 +87,7 @@ export function abstractCreateDemo<T extends {}>(
         loadVariantMeta={options.loadVariantMeta}
         loadSource={options.loadSource}
         sourceParser={options.sourceParser}
+        sourceEnhancers={options.sourceEnhancers}
         highlightAfter={meta?.highlightAfter || options.highlightAfter}
         enhanceAfter={meta?.enhanceAfter || options.enhanceAfter}
         controlled={options.controlled}
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
index f03943727..e6d408410 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
@@ -79,7 +79,7 @@ describe('enhanceCodeEmphasis', () => {
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="2"><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-start-line="3" data-frame-end-line="3" data-frame-type="highlighted" data-frame-indent="2"><span class="line" data-ln="3" data-hl="" data-hl-position="single">    &#x3C;<span class="pl-ent">button</span> <span class="pl-e">className</span><span class="pl-k">=</span><span class="pl-s"><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-start-line="3" data-frame-end-line="3" 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">className</span><span class="pl-k">=</span><span class="pl-s"><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-start-line="4" data-frame-end-line="5"><span class="line" data-ln="4">  );</span>
         <span class="line" data-ln="5">}</span></span>"
       `);
@@ -97,9 +97,9 @@ const e = 5; // @highlight`,
 
       expect(result).toMatchInlineSnapshot(
         `
-        "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1" data-hl="" data-hl-position="single"><span class="pl-k">const</span> <span class="pl-c1">a</span> <span class="pl-k">=</span> <span class="pl-c1">1</span>;</span>
+        "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" 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">1</span>;</span>
         </span><span class="frame" data-lined="" data-frame-start-line="2" data-frame-end-line="2"><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">2</span>;</span>
-        </span><span class="frame" data-lined="" data-frame-start-line="3" data-frame-end-line="3" data-frame-type="highlighted-unfocused" data-frame-indent="0"><span class="line" data-ln="3" data-hl="" data-hl-position="single"><span class="pl-k">const</span> <span class="pl-c1">c</span> <span class="pl-k">=</span> <span class="pl-c1">3</span>;</span>
+        </span><span class="frame" data-lined="" data-frame-start-line="3" data-frame-end-line="3" 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">3</span>;</span>
         </span><span class="frame" data-lined="" data-frame-start-line="4" data-frame-end-line="4"><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">4</span>;</span>
         </span>"
       `,
@@ -117,7 +117,7 @@ const e = 5; // @highlight`,
 
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1"><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-start-line="2" data-frame-end-line="2" data-frame-type="highlighted" data-frame-indent="1"><span class="line" data-ln="2" data-hl="" data-hl-description="We track state" data-hl-position="single">  <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">0</span>);</span>
+        </span><span class="frame" data-lined="" data-frame-start-line="2" data-frame-end-line="2" 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">0</span>);</span>
         </span><span class="frame" data-lined="" data-frame-start-line="3" data-frame-end-line="4"><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>"
       `);
@@ -160,10 +160,10 @@ const e = 5; // @highlight`,
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="2"><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-start-line="3" data-frame-end-line="6" data-frame-type="highlighted" data-frame-indent="2"><span class="line" data-ln="3" data-hl="" data-hl-position="start">    &#x3C;<span class="pl-ent">div</span>></span>
-        <span class="line" data-ln="4" data-hl="">      &#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="">      &#x3C;<span class="pl-ent">p</span>>Some content&#x3C;/<span class="pl-ent">p</span>></span>
-        <span class="line" data-ln="6" data-hl="" data-hl-position="end">    &#x3C;/<span class="pl-ent">div</span>></span>
+        </span><span class="frame" data-lined="" data-frame-start-line="3" data-frame-end-line="6" data-frame-type="highlighted" data-frame-indent="2"><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>
         </span><span class="frame" data-lined="" data-frame-start-line="7" data-frame-end-line="8"><span class="line" data-ln="7">  );</span>
         <span class="line" data-ln="8">}</span></span>"
       `);
@@ -200,7 +200,7 @@ const e = 5; // @highlight`,
       expect(result).toMatchInlineSnapshot(
         `
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1"><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-start-line="2" data-frame-end-line="2" data-frame-type="highlighted" data-frame-indent="1"><span class="line" data-ln="2" data-hl="">  <span class="pl-k">return</span> <span class="pl-c1">null</span>;</span>
+        </span><span class="frame" data-lined="" data-frame-start-line="2" data-frame-end-line="2" data-frame-type="highlighted" data-frame-indent="1"><span class="line" data-ln="2">  <span class="pl-k">return</span> <span class="pl-c1">null</span>;</span>
         </span><span class="frame" data-lined="" data-frame-start-line="3" data-frame-end-line="3"><span class="line" data-ln="3">}</span></span>"
       `,
       );
@@ -223,9 +223,9 @@ const e = 5; // @highlight`,
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="2"><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-start-line="3" data-frame-end-line="5" data-frame-type="highlighted" data-frame-indent="2"><span class="line" data-ln="3" data-hl="" data-hl-description="We add a heading with an h1" data-hl-position="start">    &#x3C;<span class="pl-ent">div</span>></span>
-        <span class="line" data-ln="4" data-hl="">      &#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="" data-hl-position="end">    &#x3C;/<span class="pl-ent">div</span>></span>
+        </span><span class="frame" data-lined="" data-frame-start-line="3" data-frame-end-line="5" 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 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="" data-frame-start-line="6" data-frame-end-line="7"><span class="line" data-ln="6">  );</span>
         <span class="line" data-ln="7">}</span></span>"
       `);
@@ -249,11 +249,11 @@ const e = 5; // @highlight`,
 
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1"><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-start-line="2" data-frame-end-line="6" data-frame-type="highlighted" data-frame-indent="1"><span class="line" data-ln="2" data-hl="" data-hl-position="start">  <span class="pl-k">return</span> (</span>
+        </span><span class="frame" data-lined="" data-frame-start-line="2" data-frame-end-line="6" data-frame-type="highlighted" data-frame-indent="1"><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>
-        <span class="line" data-ln="6" data-hl="" data-hl-position="end">  );</span>
+        <span class="line" data-ln="6">  );</span>
         </span><span class="frame" data-lined="" data-frame-start-line="7" data-frame-end-line="7"><span class="line" data-ln="7">}</span></span>"
       `);
     });
@@ -276,7 +276,7 @@ const e = 5; // @highlight`,
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="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="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-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4" data-hl="" data-hl-position="single">      &#x3C;<span class="pl-ent">h1</span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>></span>
+        </span><span class="frame" data-lined="" data-frame-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>></span>
         </span><span class="frame" data-lined="" data-frame-start-line="5" data-frame-end-line="7"><span class="line" data-ln="5">    &#x3C;/<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="6">  );</span>
         <span class="line" data-ln="7">}</span></span>"
@@ -301,7 +301,7 @@ const e = 5; // @highlight`,
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="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="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-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4" data-hl="" data-hl-position="single">      &#x3C;<span class="pl-ent">h1</span> <span class="pl-e">className</span><span class="pl-k">=</span><span class="pl-s"><span class="pl-pds">"</span><span data-hl="">primary</span><span class="pl-pds">"</span></span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>></span>
+        </span><span class="frame" data-lined="" data-frame-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span> <span class="pl-e">className</span><span class="pl-k">=</span><span class="pl-s"><span class="pl-pds">"</span><span data-hl="">primary</span><span class="pl-pds">"</span></span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>></span>
         </span><span class="frame" data-lined="" data-frame-start-line="5" data-frame-end-line="7"><span class="line" data-ln="5">    &#x3C;/<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="6">  );</span>
         <span class="line" data-ln="7">}</span></span>"
@@ -329,7 +329,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(
-        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1" data-hl="" data-hl-position="single">&#x3C;<span class="pl-c1">AlertDialog.Trigger</span> <span data-hl=""><span class="pl-e">handle</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">demoAlertDialog</span><span class="pl-pse">}</span></span>>Open&#x3C;/<span class="pl-c1">AlertDialog.Trigger</span>></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1">AlertDialog.Trigger</span> <span data-hl=""><span class="pl-e">handle</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">demoAlertDialog</span><span class="pl-pse">}</span></span>>Open&#x3C;/<span class="pl-c1">AlertDialog.Trigger</span>></span></span>"`,
       );
     });
 
@@ -341,7 +341,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(
-        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1" data-hl="" data-hl-position="single">&#x3C;<span class="pl-c1">Button</span> <span class="pl-e">render</span><span class="pl-k">=</span><span class="pl-pse">{</span>&#x3C;<span class="pl-ent">div</span> /><span class="pl-pse">}</span> <span data-hl=""><span class="pl-e">nativeButton</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-c1">false</span><span class="pl-pse">}</span></span>></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1">Button</span> <span class="pl-e">render</span><span class="pl-k">=</span><span class="pl-pse">{</span>&#x3C;<span class="pl-ent">div</span> /><span class="pl-pse">}</span> <span data-hl=""><span class="pl-e">nativeButton</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-c1">false</span><span class="pl-pse">}</span></span>></span></span>"`,
       );
     });
 
@@ -366,8 +366,10 @@ const e = 5; // @highlight`,
       );
 
       // Both comments map to the same output line after the @highlight comment line is removed.
-      // The line should have data-hl from @highlight AND wrap ", 40px" from @highlight-text.
-      expect(result).toMatch(/data-ln="2"[^>]*data-hl=""/);
+      // The line should NOT have data-hl (simple highlight, frame handles it)
+      // but should still wrap ", 40px" from @highlight-text.
+      expect(result).not.toMatch(/data-ln="2"[^>]*data-hl=""/);
+      expect(result).toMatch(/data-frame-type="highlighted"/);
       // The text highlight wraps ", 40px" which contains syntax-highlighted children
       expect(result).toContain(
         '<span data-hl="">, <span class="pl-c1">40</span><span class="pl-k">px</span></span>',
@@ -469,7 +471,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(
-        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1" data-hl="" data-hl-position="single">&#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">a</span><span class="pl-pse">}</span> /> &#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">b</span><span class="pl-pse">}</span> /> <span class="pl-c">// @highlight-text "<span data-hl="">value</span>"</span></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">a</span><span class="pl-pse">}</span> /> &#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">b</span><span class="pl-pse">}</span> /> <span class="pl-c">// @highlight-text "<span data-hl="">value</span>"</span></span></span>"`,
       );
     });
 
@@ -496,7 +498,7 @@ const e = 5; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(
-        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1" data-hl="" data-hl-position="single">&#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span data-hl=""><span class="pl-smi">value</span></span><span class="pl-pse">}</span> /></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span data-hl=""><span class="pl-smi">value</span></span><span class="pl-pse">}</span> /></span></span>"`,
       );
     });
   });
@@ -598,10 +600,10 @@ const another = 99; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(`
-        "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1" data-hl="" data-hl-position="single"><span class="pl-k">const</span> <span class="pl-c1">value</span> <span class="pl-k">=</span> <span class="pl-c1">42</span>;</span>
+        "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1" 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">42</span>;</span>
         </span><span class="frame" data-lined="" data-frame-start-line="2" data-frame-end-line="2"><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-start-line="3" data-frame-end-line="4" data-frame-type="highlighted-unfocused" data-frame-indent="1"><span class="line" data-ln="3" data-hl="" data-hl-position="start">  <span class="pl-k">const</span> <span class="pl-c1">x</span> <span class="pl-k">=</span> <span class="pl-c1">1</span>;</span>
-        <span class="line" data-ln="4" data-hl="" data-hl-position="end">  <span class="pl-k">const</span> <span class="pl-c1">y</span> <span class="pl-k">=</span> <span class="pl-c1">2</span>;</span>
+        </span><span class="frame" data-lined="" data-frame-start-line="3" data-frame-end-line="4" 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">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">2</span>;</span>
         </span><span class="frame" data-lined="" data-frame-start-line="5" data-frame-end-line="6"><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>
         </span>"
@@ -625,15 +627,13 @@ const another = 99; // @highlight`,
 
       // The @highlight-text line should highlight "Heading 1" text inline
       expect(result).toContain('<span data-hl="">Heading 1</span>');
-      // The line itself should also have data-hl="" (not strong) for line-level styling
-      expect(result).toMatch(/data-ln="4"[^>]*data-hl=""/);
-      expect(result).not.toMatch(/data-ln="4"[^>]*data-hl="strong"/);
-      // The text-highlight line in the middle should NOT have position="single"
-      expect(result).not.toMatch(/data-ln="4"[^>]*data-hl-position="single"/);
-      // Other lines in the multiline region should still have full-line data-hl
-      expect(result).toMatch(/data-ln="3"[^>]*data-hl=""/);
-      expect(result).toMatch(/data-ln="5"[^>]*data-hl=""/);
-      expect(result).toMatch(/data-ln="6"[^>]*data-hl=""/);
+      // The line itself should NOT have line-level data-hl (simple highlight, frame handles it)
+      // but the inline text highlight span is still present
+      expect(result).not.toMatch(/data-ln="4"[^>]*data-hl=""/);
+      // Other lines in the multiline region should also NOT have line-level data-hl
+      expect(result).not.toMatch(/data-ln="3"[^>]*data-hl=""/);
+      expect(result).not.toMatch(/data-ln="5"[^>]*data-hl=""/);
+      expect(result).not.toMatch(/data-ln="6"[^>]*data-hl=""/);
       // The whole region should be in a highlighted frame
       expect(result).toContain('data-frame-type="highlighted"');
     });
@@ -720,7 +720,7 @@ const b = 2;`,
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="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="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-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4" data-hl="" data-hl-position="single">      &#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-start-line="4" data-frame-end-line="4" 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-start-line="5" data-frame-end-line="8"><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>
@@ -748,13 +748,13 @@ const b = 2;`,
 
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="1"><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-start-line="2" data-frame-end-line="2" data-frame-type="highlighted" data-frame-indent="1"><span class="line" data-ln="2" data-hl="" data-hl-description="We track state" data-hl-position="single">  <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-start-line="2" data-frame-end-line="2" 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-start-line="3" data-frame-end-line="5"><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">Header</span> /></span>
-        </span><span class="frame" data-lined="" data-frame-start-line="6" data-frame-end-line="8" data-frame-type="highlighted-unfocused" data-frame-indent="3"><span class="line" data-ln="6" data-hl="" data-hl-description="We render the main content" data-hl-position="start">      &#x3C;<span class="pl-c1">Chart</span> <span class="pl-e">data</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">data</span><span class="pl-pse">}</span> /></span>
-        <span class="line" data-ln="7" data-hl="" data-hl-position="end">      &#x3C;<span class="pl-c1">Table</span> <span class="pl-e">data</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">data</span><span class="pl-pse">}</span> /></span>
-        <span class="line" data-ln="8" data-hl="" data-hl-position="single">      &#x3C;<span class="pl-c1">Footer</span> /></span>
+        </span><span class="frame" data-lined="" data-frame-start-line="6" data-frame-end-line="8" 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">Chart</span> <span class="pl-e">data</span><span class="pl-k">=</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">Table</span> <span class="pl-e">data</span><span class="pl-k">=</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">Footer</span> /></span>
         </span><span class="frame" data-lined="" data-frame-start-line="9" data-frame-end-line="11"><span class="line" data-ln="9">    &#x3C;/<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="10">  );</span>
         <span class="line" data-ln="11">}</span></span>"
@@ -817,17 +817,17 @@ const b = 2;`,
       );
 
       // Line 3 has @highlight-start comment - should NOT have data-hl
-      // Line 4 (<div>) should have data-hl with position="start"
-      // Line 5 (<h1>) should have data-hl
-      // Line 6 (</div>) should have data-hl with position="end"
+      // Lines 4-6 are in a highlighted frame but don't get line-level data-hl
+      // (simple highlight, frame handles the visual emphasis)
       // Line 7 has @highlight-end comment - should NOT have data-hl
 
       // Check that line 3 (the @highlight-start line) does NOT have data-hl
       expect(result).toContain('data-ln="3"');
       expect(result).not.toMatch(/data-ln="3"[^>]*data-hl/);
 
-      // Check that line 4 has data-hl (first content line)
-      expect(result).toMatch(/data-ln="4"[^>]*data-hl/);
+      // Lines 4-6 should NOT have line-level data-hl (simple highlight, frame handles it)
+      expect(result).not.toMatch(/data-ln="4"[^>]*data-hl/);
+      expect(result).toContain('data-frame-type="highlighted"');
 
       // Check that line 7 (the @highlight-end line) does NOT have data-hl
       expect(result).toContain('data-ln="7"');
@@ -842,8 +842,9 @@ const z = 3;`,
         parseSource,
       );
 
-      // Line 2 has the @highlight comment and should be highlighted
-      expect(result).toMatch(/data-ln="2"[^>]*data-hl/);
+      // Line 2 should NOT have line-level data-hl (simple highlight, frame handles it)
+      expect(result).not.toMatch(/data-ln="2"[^>]*data-hl/);
+      expect(result).toContain('data-frame-type="highlighted"');
 
       // Lines 1 and 3 should NOT have data-hl
       expect(result).not.toMatch(/data-ln="1"[^>]*data-hl/);
@@ -868,8 +869,9 @@ const z = 3;`,
       expect(result).toContain('data-ln="4"');
       expect(result).not.toMatch(/data-ln="4"[^>]*data-hl/);
 
-      // Line 5 (<h1>) should have data-hl with position="single" (only line in range)
-      expect(result).toMatch(/data-ln="5"[^>]*data-hl/);
+      // Line 5 should NOT have line-level data-hl (simple highlight, frame handles it)
+      expect(result).not.toMatch(/data-ln="5"[^>]*data-hl/);
+      expect(result).toContain('data-frame-type="highlighted"');
 
       // Line 6 has {/* @highlight-end */} - should NOT have data-hl
       expect(result).toContain('data-ln="6"');
@@ -892,7 +894,7 @@ const z = 3;`,
         "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="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="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-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4" data-hl="" data-hl-position="single">      &#x3C;<span class="pl-ent">h1</span> <span class="pl-e">className</span><span class="pl-k">=</span><span class="pl-s"><span class="pl-pds">"</span><span data-hl="">primary</span><span class="pl-pds">"</span></span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>> <span class="pl-pse">{</span><span class="pl-c">/* @highlight-text "<span data-hl="">primary</span>" "<span data-hl="">Heading 1</span>" */</span><span class="pl-pse">}</span></span>
+        </span><span class="frame" data-lined="" data-frame-start-line="4" data-frame-end-line="4" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span> <span class="pl-e">className</span><span class="pl-k">=</span><span class="pl-s"><span class="pl-pds">"</span><span data-hl="">primary</span><span class="pl-pds">"</span></span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>> <span class="pl-pse">{</span><span class="pl-c">/* @highlight-text "<span data-hl="">primary</span>" "<span data-hl="">Heading 1</span>" */</span><span class="pl-pse">}</span></span>
         </span><span class="frame" data-lined="" data-frame-start-line="5" data-frame-end-line="7"><span class="line" data-ln="5">    &#x3C;/<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="6">  );</span>
         <span class="line" data-ln="7">}</span></span>"
@@ -1025,7 +1027,7 @@ const e = 5;`,
         /data-frame-start-line="3" data-frame-end-line="3" data-frame-type="padding-top"/,
       );
       expect(result).toMatch(
-        /data-frame-start-line="4" data-frame-end-line="4" data-frame-type="highlighted"/,
+        /data-frame-start-line="4" data-frame-end-line="4" data-frame-type="focus"/,
       );
       expect(result).toMatch(
         /data-frame-start-line="5" data-frame-end-line="5" data-frame-type="padding-bottom"/,
@@ -1078,7 +1080,7 @@ const d = 4;`,
 
       // @focus on line 3 with description "important line"
       expect(result).toMatch(
-        /data-frame-start-line="3" data-frame-end-line="3" data-frame-type="highlighted"/,
+        /data-frame-start-line="3" data-frame-end-line="3" data-frame-type="focus"/,
       );
       expect(result).toContain('data-hl-description="Important line"');
       expect(result).toContain('data-frame-type="padding-top"');
@@ -1089,6 +1091,53 @@ const d = 4;`,
         /data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted-unfocused"/,
       );
     });
+
+    it('should preserve data-hl-position="single" for @highlight inside @focus range', async () => {
+      const result = await testEmphasis(
+        `const a = 1;
+// @focus-start
+const b = 2;
+const c = 3; // @highlight
+const d = 4;
+// @focus-end
+const e = 5;`,
+        parseSource,
+      );
+
+      // The single @highlight inside focus should get line-level data-hl with position="single"
+      expect(result).toContain('data-hl="" data-hl-position="single"');
+    });
+
+    it('should put description on frame for standalone @highlight with description', async () => {
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2; // @highlight "tracked variable"
+const c = 3;`,
+        parseSource,
+      );
+
+      // Frame-level description: the highlighted frame gets the description
+      expect(result).toContain('data-frame-description="Tracked variable"');
+      // No line-level description since the frame handles the highlight
+      expect(result).not.toContain('data-hl-description');
+    });
+
+    it('should put description on frame for @highlight-start with description', async () => {
+      const result = await testEmphasis(
+        `const a = 1;
+// @highlight-start "region description"
+const b = 2;
+const c = 3;
+// @highlight-end
+const d = 4;`,
+        parseSource,
+      );
+
+      // Frame-level description: the highlighted frame gets the description
+      expect(result).toContain('data-frame-description="Region description"');
+      // No line-level description since the frame handles the highlight
+      expect(result).not.toContain('data-hl-description');
+    });
   });
 
   describe('standalone @focus directives (focus without highlight)', () => {
@@ -1158,11 +1207,11 @@ const d = 4;`,
         enhancer,
       );
 
-      // Line 1 is highlighted-unfocused (has data-hl but not focused)
+      // Line 1 is highlighted-unfocused (no line-level data-hl, frame handles it)
       expect(result).toMatch(
         /data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted-unfocused"/,
       );
-      expect(result).toContain('data-hl=""');
+      expect(result).not.toContain('data-hl=""');
 
       // Line 3 is focused (focus frame type) but no data-hl
       expect(result).toMatch(
@@ -1179,6 +1228,138 @@ const d = 4;`,
     });
   });
 
+  describe('nested focus and highlight line-level data-hl', () => {
+    it('should apply data-hl on @highlight lines inside a @focus region', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+// @focus-start
+const b = 2;
+const c = 3; // @highlight
+const d = 4;
+// @focus-end
+const e = 5;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // The region has both focus and highlight. Focus takes precedence for the frame
+      // type — highlights within are handled at the line level (data-hl).
+      expect(result).toContain('data-frame-type="focus"');
+
+      // Line c has both focus and highlight → should get data-hl=""
+      expect(result).toMatch(/data-ln="3"[^>]*data-hl=""/);
+
+      // Lines b and d are focus-only (no @highlight) → no data-hl
+      expect(result).not.toMatch(/data-ln="2"[^>]*data-hl/);
+      expect(result).not.toMatch(/data-ln="4"[^>]*data-hl/);
+    });
+
+    it('should apply data-hl on @highlight-start range inside a @focus region', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+// @focus-start
+const b = 2;
+// @highlight-start
+const c = 3;
+const d = 4;
+// @highlight-end
+const e = 5;
+// @focus-end
+const f = 6;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Lines c and d are inside both focus and highlight → data-hl=""
+      expect(result).toMatch(/data-ln="3"[^>]*data-hl=""/);
+      expect(result).toMatch(/data-ln="4"[^>]*data-hl=""/);
+
+      // Lines b and e are focus-only → no data-hl
+      expect(result).not.toMatch(/data-ln="2"[^>]*data-hl/);
+      expect(result).not.toMatch(/data-ln="5"[^>]*data-hl/);
+    });
+
+    it('should apply data-hl="strong" for nested @highlight inside @highlight inside @focus', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+// @focus-start
+// @highlight-start
+const b = 2;
+const c = 3; // @highlight
+const d = 4;
+// @highlight-end
+// @focus-end
+const e = 5;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Lines b and d are highlight+focus → data-hl=""
+      expect(result).toMatch(/data-ln="2"[^>]*data-hl=""/);
+      expect(result).toMatch(/data-ln="4"[^>]*data-hl=""/);
+
+      // Line c is nested highlight (two depths) + focus → data-hl="strong"
+      expect(result).toMatch(/data-ln="3"[^>]*data-hl="strong"/);
+    });
+
+    it('should not apply data-hl on simple highlight lines (frame handles it)', async () => {
+      const result = await testEmphasis(
+        `const a = 1;
+// @highlight-start
+const b = 2;
+const c = 3;
+// @highlight-end
+const d = 4;`,
+        parseSource,
+      );
+
+      // Frame should be highlighted
+      expect(result).toContain('data-frame-type="highlighted"');
+
+      // Lines b and c should NOT have line-level data-hl (simple highlight, frame handles it)
+      expect(result).not.toMatch(/data-ln="2"[^>]*data-hl/);
+      expect(result).not.toMatch(/data-ln="3"[^>]*data-hl/);
+    });
+
+    it('should apply data-hl="strong" for @highlight inside @highlight (highlight inside highlighted frame)', async () => {
+      const result = await testEmphasis(
+        `const a = 1;
+// @highlight-start
+const b = 2;
+const c = 3; // @highlight
+const d = 4;
+// @highlight-end
+const e = 5;`,
+        parseSource,
+      );
+
+      // Frame should be highlighted
+      expect(result).toContain('data-frame-type="highlighted"');
+
+      // Lines b and d are simple highlight → no data-hl (frame handles it)
+      expect(result).not.toMatch(/data-ln="2"[^>]*data-hl=""/);
+      expect(result).not.toMatch(/data-ln="4"[^>]*data-hl=""/);
+
+      // Line c is nested (highlight inside highlight) → data-hl="strong"
+      expect(result).toMatch(/data-ln="3"[^>]*data-hl="strong"/);
+    });
+  });
+
   describe('data-frame-indent', () => {
     it('should set data-frame-indent based on minimum indentation', async () => {
       const result = await testEmphasis(
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
index 7a67461c0..9b518816a 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
@@ -389,16 +389,26 @@ function calculateEmphasizedLines(
         }
 
         // If this line is already emphasized (from an inner range), mark it as strong
-        // since it's now nested inside multiple emphasis ranges, and preserve inner positions
+        // only when both ranges have lineHighlight (true nesting of highlights).
+        // A focus range overlapping with a highlight is not nesting — it just
+        // merges focus into the existing entry.
         const meta: EmphasisMeta = existing
           ? {
-              // Nested ranges are strong unless the inner is a text highlight
-              strong: existing.highlightTexts ? strong : true,
+              // Nested highlight ranges are strong; focus+highlight overlap is not
+              strong:
+                (existing.lineHighlight &&
+                  startDirective.lineHighlight &&
+                  !existing.highlightTexts) ||
+                existing.strong ||
+                strong,
               description: existing.description ?? (line === startLine ? description : undefined),
               // Inner range position takes precedence, but 'single' from a standalone
-              // @highlight-text should be replaced by the multiline range's position
+              // @highlight-text should be replaced by the multiline range's position.
+              // Keep 'single' from regular @highlight (no highlightTexts).
               position:
-                existing.position && existing.position !== 'single' ? existing.position : position,
+                existing.position && !(existing.position === 'single' && existing.highlightTexts)
+                  ? existing.position
+                  : position,
               highlightTexts: existing.highlightTexts, // Preserve text highlights from @highlight-text
               lineHighlight: existing.lineHighlight || startDirective.lineHighlight,
               focus: existing.focus || startDirective.focus,
@@ -838,6 +848,14 @@ function applyEmphasisAndCollectHighlightedElements(
         const meta = emphasizedLines.get(lineNumber);
 
         if (meta !== undefined) {
+          // Determine whether line-level data-hl should be applied.
+          // Line-level highlighting is only needed when highlight lines appear
+          // inside a focus frame (highlight + focus), or when highlights are nested
+          // (strong). Simple standalone highlights don't need line-level marks
+          // because the frame itself handles the visual emphasis.
+          const shouldApplyLineHl =
+            meta.lineHighlight && (meta.focus === true || meta.strong === true);
+
           if (meta.highlightTexts) {
             // For text highlight, wrap the specific text(s) in a span with data-hl
             let children = child.children;
@@ -850,10 +868,10 @@ function applyEmphasisAndCollectHighlightedElements(
             }
             child.children = children;
 
-            // Only mark the line with data-hl when the line also has a line-level
-            // highlight (from @highlight, or from being inside a @highlight-start region).
+            // Only mark the line with data-hl when the highlight is nested
+            // (inside a focus frame or strong from nesting).
             // Standalone @highlight-text lines should not get line-level highlights.
-            if (meta.lineHighlight) {
+            if (shouldApplyLineHl) {
               child.properties.dataHl = meta.strong ? 'strong' : '';
 
               if (meta.description) {
@@ -864,7 +882,7 @@ function applyEmphasisAndCollectHighlightedElements(
                 child.properties.dataHlPosition = meta.position;
               }
             }
-          } else if (meta.lineHighlight) {
+          } else if (shouldApplyLineHl) {
             // Use data-hl with optional "strong" value on the line
             child.properties.dataHl = meta.strong ? 'strong' : '';
 
@@ -946,6 +964,46 @@ function calculateRegionIndentLevels(
   return regionIndentLevels;
 }
 
+/**
+ * Applies frame-level descriptions to highlighted frames after restructuring.
+ *
+ * When a highlighted line has a description but doesn't need line-level `data-hl`
+ * (because the frame handles the visual emphasis), the description is placed on
+ * the frame element as `data-frame-description` instead.
+ */
+function applyFrameDescriptions(root: HastRoot, emphasizedLines: Map<number, EmphasisMeta>): void {
+  for (const frame of root.children) {
+    if (frame.type !== 'element') {
+      continue;
+    }
+
+    for (const child of frame.children) {
+      if (
+        child.type !== 'element' ||
+        child.tagName !== 'span' ||
+        child.properties?.className !== 'line' ||
+        typeof child.properties.dataLn !== 'number'
+      ) {
+        continue;
+      }
+
+      const meta = emphasizedLines.get(child.properties.dataLn);
+      if (!meta?.description) {
+        continue;
+      }
+
+      const shouldApplyLineHl = meta.lineHighlight && (meta.focus === true || meta.strong === true);
+
+      // When the frame handles highlighting (not line-level), put the description
+      // on the frame so it's not lost.
+      if (!shouldApplyLineHl) {
+        frame.properties ??= {};
+        frame.properties.dataFrameDescription = meta.description;
+      }
+    }
+  }
+}
+
 /**
  * Creates a source enhancer that adds emphasis to code lines based on `@highlight` comments
  * and restructures frames around highlighted regions.
@@ -1042,6 +1100,9 @@ export function createEnhanceCodeEmphasis(
     // Step 7: Restructure frames (flat iteration, not deep recursive traversal)
     restructureFrames(root, frameRanges, regionIndentLevels);
 
+    // Step 8: Apply frame-level descriptions to highlighted frames
+    applyFrameDescriptions(root, emphasizedLines);
+
     return root;
   };
 }
diff --git a/packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.test.ts b/packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.test.ts
index b6e31d2f8..1ca4266e7 100644
--- a/packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.test.ts
+++ b/packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.test.ts
@@ -3005,6 +3005,32 @@ import styles from './TextInputCopy.module.css';`;
     const pos = cssImport.positions[0];
     expect(code.slice(pos.start, pos.end)).toBe("'./TextInputCopy.module.css'");
   });
+
+  it('should assign correct line numbers to comments after multi-line imports', async () => {
+    const code = `import {
+  A,
+  B,
+} from './utils';
+
+const x = 1;
+// @focus-start
+const y = 2;
+// @focus-end
+const z = 3;`;
+
+    const result = await parseImportsAndComments(code, '/src/test.tsx', {
+      removeCommentsWithPrefix: ['@focus'],
+      notableCommentsPrefix: ['@focus'],
+    });
+
+    // The multi-line import spans lines 0-3. Without tracking newlines inside
+    // the import detection, outputLine would be stuck at 0, causing these
+    // comment line numbers to be off by 3.
+    expect(result.comments).toEqual({
+      6: ['@focus-start'],
+      7: ['@focus-end'],
+    });
+  });
 });
 
 // Test cases for export-from statements
diff --git a/packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.ts b/packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.ts
index 1abf6d9db..61ef13f97 100644
--- a/packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.ts
+++ b/packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.ts
@@ -332,6 +332,13 @@ function scanForImports(
           const importText = sourceCode.slice(i, detection.nextPos);
           result += importText;
           processedPos += importText.length;
+          // Count newlines in multi-line imports to keep outputLine accurate
+          for (let j = 0; j < importText.length; j += 1) {
+            if (importText[j] === '\n') {
+              outputLine += 1;
+              lineStartPos = i + j + 1;
+            }
+          }
         }
         i = detection.nextPos;
         continue;
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
index 1f30e7f21..575523713 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
@@ -13,7 +13,7 @@ describe('calculateFrameRanges', () => {
 
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 9, type: 'normal' },
-        { startLine: 10, endLine: 10, type: 'highlighted' },
+        { startLine: 10, endLine: 10, type: 'highlighted', regionIndex: 0 },
         { startLine: 11, endLine: 20, type: 'normal' },
       ]);
     });
@@ -26,7 +26,7 @@ describe('calculateFrameRanges', () => {
       const result = calculateFrameRanges(emphasizedLines, 5);
 
       expect(result).toEqual<FrameRange[]>([
-        { startLine: 1, endLine: 1, type: 'highlighted' },
+        { startLine: 1, endLine: 1, type: 'highlighted', regionIndex: 0 },
         { startLine: 2, endLine: 5, type: 'normal' },
       ]);
     });
@@ -40,7 +40,7 @@ describe('calculateFrameRanges', () => {
 
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 4, type: 'normal' },
-        { startLine: 5, endLine: 5, type: 'highlighted' },
+        { startLine: 5, endLine: 5, type: 'highlighted', regionIndex: 0 },
       ]);
     });
 
@@ -53,7 +53,9 @@ describe('calculateFrameRanges', () => {
 
       const result = calculateFrameRanges(emphasizedLines, 3);
 
-      expect(result).toEqual<FrameRange[]>([{ startLine: 1, endLine: 3, type: 'highlighted' }]);
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 3, type: 'highlighted', regionIndex: 0 },
+      ]);
     });
 
     it('should handle a multiline highlight region', () => {
@@ -67,7 +69,7 @@ describe('calculateFrameRanges', () => {
 
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 4, type: 'normal' },
-        { startLine: 5, endLine: 7, type: 'highlighted' },
+        { startLine: 5, endLine: 7, type: 'highlighted', regionIndex: 0 },
         { startLine: 8, endLine: 10, type: 'normal' },
       ]);
     });
@@ -83,9 +85,9 @@ describe('calculateFrameRanges', () => {
 
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 2, type: 'normal' },
-        { startLine: 3, endLine: 3, type: 'highlighted' },
+        { startLine: 3, endLine: 3, type: 'highlighted', regionIndex: 0 },
         { startLine: 4, endLine: 7, type: 'normal' },
-        { startLine: 8, endLine: 9, type: 'highlighted-unfocused' },
+        { startLine: 8, endLine: 9, type: 'highlighted-unfocused', regionIndex: 1 },
         { startLine: 10, endLine: 12, type: 'normal' },
       ]);
     });
@@ -101,7 +103,7 @@ describe('calculateFrameRanges', () => {
 
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 2, type: 'normal' },
-        { startLine: 3, endLine: 4, type: 'highlighted' },
+        { startLine: 3, endLine: 4, type: 'highlighted', regionIndex: 0 },
         { startLine: 5, endLine: 6, type: 'normal' },
       ]);
     });
@@ -120,7 +122,7 @@ describe('calculateFrameRanges', () => {
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 4, type: 'normal' },
         { startLine: 5, endLine: 9, type: 'padding-top' },
-        { startLine: 10, endLine: 10, type: 'highlighted' },
+        { startLine: 10, endLine: 10, type: 'highlighted', regionIndex: 0 },
         { startLine: 11, endLine: 15, type: 'padding-bottom' },
         { startLine: 16, endLine: 20, type: 'normal' },
       ]);
@@ -138,7 +140,7 @@ describe('calculateFrameRanges', () => {
       // Only 2 lines before highlight (1,2), so padding-top is 2 lines, no normal before
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 2, type: 'padding-top' },
-        { startLine: 3, endLine: 3, type: 'highlighted' },
+        { startLine: 3, endLine: 3, type: 'highlighted', regionIndex: 0 },
         { startLine: 4, endLine: 8, type: 'padding-bottom' },
         { startLine: 9, endLine: 20, type: 'normal' },
       ]);
@@ -157,7 +159,7 @@ describe('calculateFrameRanges', () => {
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 12, type: 'normal' },
         { startLine: 13, endLine: 17, type: 'padding-top' },
-        { startLine: 18, endLine: 18, type: 'highlighted' },
+        { startLine: 18, endLine: 18, type: 'highlighted', regionIndex: 0 },
         { startLine: 19, endLine: 20, type: 'padding-bottom' },
       ]);
     });
@@ -175,10 +177,10 @@ describe('calculateFrameRanges', () => {
       // First region gets padding, second does not
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 2, type: 'padding-top' },
-        { startLine: 3, endLine: 3, type: 'highlighted' },
+        { startLine: 3, endLine: 3, type: 'highlighted', regionIndex: 0 },
         { startLine: 4, endLine: 5, type: 'padding-bottom' },
         { startLine: 6, endLine: 14, type: 'normal' },
-        { startLine: 15, endLine: 15, type: 'highlighted-unfocused' },
+        { startLine: 15, endLine: 15, type: 'highlighted-unfocused', regionIndex: 1 },
         { startLine: 16, endLine: 20, type: 'normal' },
       ]);
     });
@@ -201,15 +203,16 @@ describe('calculateFrameRanges', () => {
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 6, type: 'normal' },
         { startLine: 7, endLine: 9, type: 'padding-top' },
-        { startLine: 10, endLine: 10, type: 'highlighted' },
+        { startLine: 10, endLine: 10, type: 'highlighted', regionIndex: 0 },
         { startLine: 11, endLine: 14, type: 'padding-bottom' },
         { startLine: 15, endLine: 20, type: 'normal' },
       ]);
     });
 
-    it('should handle when highlight is larger than focusFramesMaxSize', () => {
-      // Highlight spans 5 lines but focusFramesMaxSize is 3
-      // remaining = 3 - 5 = -2, so no padding
+    it('should split oversized focused region from the start', () => {
+      // Highlight spans 5 lines (5-9) but focusFramesMaxSize is 3
+      // focusStart = 5, focusEnd = 5 + 3 - 1 = 7
+      // unfocused-bottom: 8-9 (2 lines)
       const emphasizedLines = new Map<number, EmphasisMeta>([
         [5, { position: 'start', lineHighlight: true }],
         [6, { lineHighlight: true }],
@@ -225,7 +228,14 @@ describe('calculateFrameRanges', () => {
 
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 4, type: 'normal' },
-        { startLine: 5, endLine: 9, type: 'highlighted' },
+        { startLine: 5, endLine: 7, type: 'highlighted', regionIndex: 0, truncated: 'visible' },
+        {
+          startLine: 8,
+          endLine: 9,
+          type: 'highlighted-unfocused',
+          regionIndex: 0,
+          truncated: 'hidden',
+        },
         { startLine: 10, endLine: 15, type: 'normal' },
       ]);
     });
@@ -245,12 +255,88 @@ describe('calculateFrameRanges', () => {
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 7, type: 'normal' },
         { startLine: 8, endLine: 9, type: 'padding-top' },
-        { startLine: 10, endLine: 10, type: 'highlighted' },
+        { startLine: 10, endLine: 10, type: 'highlighted', regionIndex: 0 },
         { startLine: 11, endLine: 13, type: 'padding-bottom' },
         { startLine: 14, endLine: 20, type: 'normal' },
       ]);
     });
 
+    it('should put all overflow at the bottom', () => {
+      // Highlight spans 6 lines (5-10), focusFramesMaxSize=3
+      // focusStart = 5, focusEnd = 5 + 3 - 1 = 7
+      // unfocused-bottom: 8-10 (3 lines)
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [5, { position: 'start', lineHighlight: true }],
+        [6, { lineHighlight: true }],
+        [7, { lineHighlight: true }],
+        [8, { lineHighlight: true }],
+        [9, { lineHighlight: true }],
+        [10, { position: 'end', lineHighlight: true }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 15, {
+        focusFramesMaxSize: 3,
+      });
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 4, type: 'normal' },
+        { startLine: 5, endLine: 7, type: 'highlighted', regionIndex: 0, truncated: 'visible' },
+        {
+          startLine: 8,
+          endLine: 10,
+          type: 'highlighted-unfocused',
+          regionIndex: 0,
+          truncated: 'hidden',
+        },
+        { startLine: 11, endLine: 15, type: 'normal' },
+      ]);
+    });
+
+    it('should split oversized focus-only region from the start', () => {
+      // Focus-only region (lineHighlight: false) spans 7 lines (3-9), focusFramesMaxSize=3
+      // focusStart = 3, focusEnd = 3 + 3 - 1 = 5
+      // unfocused-bottom: 6-9 (4 lines)
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [3, { lineHighlight: false }],
+        [4, { lineHighlight: false }],
+        [5, { lineHighlight: false }],
+        [6, { lineHighlight: false }],
+        [7, { lineHighlight: false }],
+        [8, { lineHighlight: false }],
+        [9, { lineHighlight: false }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 12, {
+        focusFramesMaxSize: 3,
+      });
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 2, type: 'normal' },
+        { startLine: 3, endLine: 5, type: 'focus', regionIndex: 0, truncated: 'visible' },
+        { startLine: 6, endLine: 9, type: 'focus-unfocused', regionIndex: 0, truncated: 'hidden' },
+        { startLine: 10, endLine: 12, type: 'normal' },
+      ]);
+    });
+
+    it('should not split when region equals focusFramesMaxSize', () => {
+      // Region is exactly 3 lines, focusFramesMaxSize=3 → no split
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [5, { position: 'start', lineHighlight: true }],
+        [6, { lineHighlight: true }],
+        [7, { position: 'end', lineHighlight: true }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 10, {
+        focusFramesMaxSize: 3,
+      });
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 4, type: 'normal' },
+        { startLine: 5, endLine: 7, type: 'highlighted', regionIndex: 0 },
+        { startLine: 8, endLine: 10, type: 'normal' },
+      ]);
+    });
+
     it('should respect paddingFrameMaxSize even within focusFramesMaxSize', () => {
       // Line 10 highlighted, paddingFrameMaxSize=2, focusFramesMaxSize=20
       // remaining = 20 - 1 = 19, paddingTop = floor(19/2) = 9 → capped at 2
@@ -267,13 +353,55 @@ describe('calculateFrameRanges', () => {
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 7, type: 'normal' },
         { startLine: 8, endLine: 9, type: 'padding-top' },
-        { startLine: 10, endLine: 10, type: 'highlighted' },
+        { startLine: 10, endLine: 10, type: 'highlighted', regionIndex: 0 },
         { startLine: 11, endLine: 12, type: 'padding-bottom' },
         { startLine: 13, endLine: 20, type: 'normal' },
       ]);
     });
   });
 
+  describe('input validation', () => {
+    const emphasizedLines = new Map<number, EmphasisMeta>([
+      [3, { position: 'single', lineHighlight: true }],
+    ]);
+
+    it('should throw for focusFramesMaxSize = 0', () => {
+      expect(() => calculateFrameRanges(emphasizedLines, 10, { focusFramesMaxSize: 0 })).toThrow(
+        'focusFramesMaxSize must be a finite number >= 1, got 0',
+      );
+    });
+
+    it('should throw for negative focusFramesMaxSize', () => {
+      expect(() => calculateFrameRanges(emphasizedLines, 10, { focusFramesMaxSize: -5 })).toThrow(
+        'focusFramesMaxSize must be a finite number >= 1, got -5',
+      );
+    });
+
+    it('should throw for NaN focusFramesMaxSize', () => {
+      expect(() => calculateFrameRanges(emphasizedLines, 10, { focusFramesMaxSize: NaN })).toThrow(
+        'focusFramesMaxSize must be a finite number >= 1, got NaN',
+      );
+    });
+
+    it('should throw for Infinity focusFramesMaxSize', () => {
+      expect(() =>
+        calculateFrameRanges(emphasizedLines, 10, { focusFramesMaxSize: Infinity }),
+      ).toThrow('focusFramesMaxSize must be a finite number >= 1, got Infinity');
+    });
+
+    it('should throw for negative paddingFrameMaxSize', () => {
+      expect(() => calculateFrameRanges(emphasizedLines, 10, { paddingFrameMaxSize: -1 })).toThrow(
+        'paddingFrameMaxSize must be a finite number >= 0, got -1',
+      );
+    });
+
+    it('should throw for NaN paddingFrameMaxSize', () => {
+      expect(() => calculateFrameRanges(emphasizedLines, 10, { paddingFrameMaxSize: NaN })).toThrow(
+        'paddingFrameMaxSize must be a finite number >= 0, got NaN',
+      );
+    });
+  });
+
   describe('@focus directive', () => {
     it('should add padding around the focused region instead of first', () => {
       const emphasizedLines = new Map<number, EmphasisMeta>([
@@ -285,13 +413,14 @@ describe('calculateFrameRanges', () => {
         paddingFrameMaxSize: 3,
       });
 
-      // Second region is focused, so it gets padding
+      // Second region is focused, so it gets padding.
+      // It has both focus and lineHighlight, but focus takes precedence for the frame type.
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 2, type: 'normal' },
-        { startLine: 3, endLine: 3, type: 'highlighted-unfocused' },
+        { startLine: 3, endLine: 3, type: 'highlighted-unfocused', regionIndex: 0 },
         { startLine: 4, endLine: 11, type: 'normal' },
         { startLine: 12, endLine: 14, type: 'padding-top' },
-        { startLine: 15, endLine: 15, type: 'highlighted' },
+        { startLine: 15, endLine: 15, type: 'focus', regionIndex: 1 },
         { startLine: 16, endLine: 18, type: 'padding-bottom' },
         { startLine: 19, endLine: 20, type: 'normal' },
       ]);
@@ -311,13 +440,38 @@ describe('calculateFrameRanges', () => {
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 2, type: 'normal' },
         { startLine: 3, endLine: 4, type: 'padding-top' },
-        { startLine: 5, endLine: 5, type: 'highlighted' },
+        { startLine: 5, endLine: 5, type: 'highlighted', regionIndex: 0 },
         { startLine: 6, endLine: 7, type: 'padding-bottom' },
         { startLine: 8, endLine: 14, type: 'normal' },
-        { startLine: 15, endLine: 15, type: 'highlighted-unfocused' },
+        { startLine: 15, endLine: 15, type: 'highlighted-unfocused', regionIndex: 1 },
         { startLine: 16, endLine: 20, type: 'normal' },
       ]);
     });
+
+    it('should use focus frame type when focus region contains highlight lines', () => {
+      // @focus region spanning lines 3-8, with @highlight on line 5
+      // The frame type should be "focus" (not "highlighted") because the region has focus.
+      // The highlight on line 5 is handled at the line level (data-hl).
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [3, { lineHighlight: false, focus: true }],
+        [4, { lineHighlight: false, focus: true }],
+        [5, { lineHighlight: true, focus: true }],
+        [6, { lineHighlight: false, focus: true }],
+        [7, { lineHighlight: false, focus: true }],
+        [8, { lineHighlight: false, focus: true }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 12, {
+        paddingFrameMaxSize: 2,
+      });
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 2, type: 'padding-top' },
+        { startLine: 3, endLine: 8, type: 'focus', regionIndex: 0 },
+        { startLine: 9, endLine: 10, type: 'padding-bottom' },
+        { startLine: 11, endLine: 12, type: 'normal' },
+      ]);
+    });
   });
 
   describe('edge cases', () => {
@@ -336,7 +490,9 @@ describe('calculateFrameRanges', () => {
 
       const result = calculateFrameRanges(emphasizedLines, 1);
 
-      expect(result).toEqual<FrameRange[]>([{ startLine: 1, endLine: 1, type: 'highlighted' }]);
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 1, type: 'highlighted', regionIndex: 0 },
+      ]);
     });
 
     it('should handle empty emphasized lines map', () => {
@@ -356,7 +512,7 @@ describe('calculateFrameRanges', () => {
 
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 4, type: 'normal' },
-        { startLine: 5, endLine: 5, type: 'highlighted' },
+        { startLine: 5, endLine: 5, type: 'highlighted', regionIndex: 0 },
         { startLine: 6, endLine: 10, type: 'normal' },
       ]);
     });
@@ -373,7 +529,7 @@ describe('calculateFrameRanges', () => {
 
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 4, type: 'normal' },
-        { startLine: 5, endLine: 5, type: 'highlighted' },
+        { startLine: 5, endLine: 5, type: 'highlighted', regionIndex: 0 },
         { startLine: 6, endLine: 10, type: 'normal' },
       ]);
     });
@@ -394,10 +550,10 @@ describe('calculateFrameRanges', () => {
 
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 2, type: 'padding-top' },
-        { startLine: 3, endLine: 3, type: 'highlighted' },
+        { startLine: 3, endLine: 3, type: 'highlighted', regionIndex: 0 },
         { startLine: 4, endLine: 6, type: 'padding-bottom' },
         { startLine: 7, endLine: 7, type: 'normal' },
-        { startLine: 8, endLine: 8, type: 'highlighted-unfocused' },
+        { startLine: 8, endLine: 8, type: 'highlighted-unfocused', regionIndex: 1 },
         { startLine: 9, endLine: 12, type: 'normal' },
       ]);
     });
@@ -416,9 +572,9 @@ describe('calculateFrameRanges', () => {
 
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 2, type: 'padding-top' },
-        { startLine: 3, endLine: 3, type: 'highlighted' },
+        { startLine: 3, endLine: 3, type: 'highlighted', regionIndex: 0 },
         { startLine: 4, endLine: 5, type: 'padding-bottom' },
-        { startLine: 6, endLine: 6, type: 'highlighted-unfocused' },
+        { startLine: 6, endLine: 6, type: 'highlighted-unfocused', regionIndex: 1 },
         { startLine: 7, endLine: 10, type: 'normal' },
       ]);
     });
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
index 564754e0e..8e08d91bf 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
@@ -34,6 +34,14 @@ export interface FrameRange {
     | 'focus-unfocused'
     | 'padding-bottom'
     | 'comment';
+  /** Index of the highlighted region this frame belongs to. Present on region-type frames. */
+  regionIndex?: number;
+  /**
+   * Present on frames created by splitting an oversized region via `focusFramesMaxSize`.
+   * - `'visible'` — the focused window kept visible when collapsed.
+   * - `'hidden'`  — the overflow portion hidden when collapsed.
+   */
+  truncated?: 'visible' | 'hidden';
 }
 
 /**
@@ -63,10 +71,12 @@ export interface EnhanceCodeEmphasisOptions {
    */
   paddingFrameMaxSize?: number;
   /**
-   * Maximum total number of lines in the focus area (padding-top + highlighted + padding-bottom).
-   * When set, padding sizes are reduced so the total focus area fits within this limit.
-   * The remainder after subtracting the highlighted size is split: floor(remainder/2) for
+   * Maximum total number of lines in the focus area (padding-top + focused region + padding-bottom).
+   * When the region fits within this limit, padding sizes are reduced so the total focus area
+   * fits. The remainder after subtracting the region size is split: floor(remainder/2) for
    * padding-top and ceil(remainder/2) for 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.
    */
   focusFramesMaxSize?: number;
   /**
@@ -198,6 +208,31 @@ function calculatePadding(
   return [paddingTop, paddingBottom];
 }
 
+/**
+ * When the focused region exceeds focusFramesMaxSize, determines the
+ * sub-window from the start of the region that stays focused.
+ *
+ * @returns [focusStart, focusEnd] (1-based, inclusive) or null if no split needed
+ */
+function calculateFocusWindow(
+  region: HighlightRegion,
+  focusFramesMaxSize: number | undefined,
+): [number, number] | null {
+  if (focusFramesMaxSize === undefined || focusFramesMaxSize < 1) {
+    return null;
+  }
+
+  const regionSize = region.endLine - region.startLine + 1;
+  if (regionSize <= focusFramesMaxSize) {
+    return null;
+  }
+
+  const focusStart = region.startLine;
+  const focusEnd = focusStart + focusFramesMaxSize - 1;
+
+  return [focusStart, focusEnd];
+}
+
 /**
  * Calculates frame ranges for the code block based on emphasized lines.
  *
@@ -217,6 +252,23 @@ export function calculateFrameRanges(
   totalLines: number,
   options: EnhanceCodeEmphasisOptions = {},
 ): FrameRange[] {
+  if (
+    options.focusFramesMaxSize !== undefined &&
+    (!Number.isFinite(options.focusFramesMaxSize) || options.focusFramesMaxSize < 1)
+  ) {
+    throw new Error(
+      `focusFramesMaxSize must be a finite number >= 1, got ${options.focusFramesMaxSize}`,
+    );
+  }
+  if (
+    options.paddingFrameMaxSize !== undefined &&
+    (!Number.isFinite(options.paddingFrameMaxSize) || options.paddingFrameMaxSize < 0)
+  ) {
+    throw new Error(
+      `paddingFrameMaxSize must be a finite number >= 0, got ${options.paddingFrameMaxSize}`,
+    );
+  }
+
   if (totalLines <= 0) {
     return [];
   }
@@ -229,8 +281,11 @@ export function calculateFrameRanges(
 
   const focusedIndex = determineFocusedRegionIndex(regions);
 
-  // Calculate padding for the focused region
+  // Calculate focus window split (for oversized regions)
   const focusedRegion = regions[focusedIndex];
+  const focusWindow = calculateFocusWindow(focusedRegion, options.focusFramesMaxSize);
+
+  // Calculate padding for the focused region (0 when region is split)
   const prevRegionEnd = focusedIndex > 0 ? regions[focusedIndex - 1].endLine : 0;
   const nextRegionStart =
     focusedIndex < regions.length - 1 ? regions[focusedIndex + 1].startLine : totalLines + 1;
@@ -266,18 +321,57 @@ export function calculateFrameRanges(
       frames.push({ startLine: currentLine, endLine: region.startLine - 1, type: 'normal' });
     }
 
-    // Frame type depends on whether the region is focused and has line highlights
-    let frameType: FrameRange['type'];
-    if (region.hasLineHighlight) {
-      frameType = isFocused ? 'highlighted' : 'highlighted-unfocused';
+    if (isFocused && focusWindow) {
+      // Split oversized focused region into unfocused-top + focused-center + unfocused-bottom
+      const [focusStart, focusEnd] = focusWindow;
+      const hasHighlightOnly = region.hasLineHighlight && !region.focused;
+      const unfocusedType: FrameRange['type'] = hasHighlightOnly
+        ? 'highlighted-unfocused'
+        : 'focus-unfocused';
+      const focusedType: FrameRange['type'] = hasHighlightOnly ? 'highlighted' : 'focus';
+
+      if (region.startLine < focusStart) {
+        frames.push({
+          startLine: region.startLine,
+          endLine: focusStart - 1,
+          type: unfocusedType,
+          regionIndex: i,
+          truncated: 'hidden',
+        });
+      }
+      frames.push({
+        startLine: focusStart,
+        endLine: focusEnd,
+        type: focusedType,
+        regionIndex: i,
+        truncated: 'visible',
+      });
+      if (focusEnd < region.endLine) {
+        frames.push({
+          startLine: focusEnd + 1,
+          endLine: region.endLine,
+          type: unfocusedType,
+          regionIndex: i,
+          truncated: 'hidden',
+        });
+      }
     } else {
-      frameType = isFocused ? 'focus' : 'focus-unfocused';
+      // Frame type depends on whether the region has line highlights without focus.
+      // When a region has both focus and highlights, the frame is "focus" and
+      // individual lines receive data-hl for visual highlighting.
+      let frameType: FrameRange['type'];
+      if (region.hasLineHighlight && !region.focused) {
+        frameType = isFocused ? 'highlighted' : 'highlighted-unfocused';
+      } else {
+        frameType = isFocused ? 'focus' : 'focus-unfocused';
+      }
+      frames.push({
+        startLine: region.startLine,
+        endLine: region.endLine,
+        type: frameType,
+        regionIndex: i,
+      });
     }
-    frames.push({
-      startLine: region.startLine,
-      endLine: region.endLine,
-      type: frameType,
-    });
 
     currentLine = region.endLine + 1;
 
diff --git a/packages/docs-infra/src/pipeline/parseSource/createFrame.ts b/packages/docs-infra/src/pipeline/parseSource/createFrame.ts
index cfb531301..a6bb04048 100644
--- a/packages/docs-infra/src/pipeline/parseSource/createFrame.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/createFrame.ts
@@ -13,6 +13,7 @@ export function createFrame(
   endLine?: number,
   frameType?: FrameRange['type'],
   indentLevel?: number,
+  truncated?: FrameRange['truncated'],
 ): Element {
   const properties: Properties = {
     className: 'frame',
@@ -39,6 +40,10 @@ export function createFrame(
     properties.dataFrameIndent = indentLevel;
   }
 
+  if (truncated) {
+    properties.dataFrameTruncated = truncated;
+  }
+
   return {
     type: 'element',
     tagName: 'span',
diff --git a/packages/docs-infra/src/pipeline/parseSource/restructureFrames.test.ts b/packages/docs-infra/src/pipeline/parseSource/restructureFrames.test.ts
index 07842d377..b0c33090b 100644
--- a/packages/docs-infra/src/pipeline/parseSource/restructureFrames.test.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/restructureFrames.test.ts
@@ -154,7 +154,7 @@ describe('restructureFrames', () => {
 
       const frameRanges: FrameRange[] = [
         { startLine: 1, endLine: 2, type: 'normal' },
-        { startLine: 3, endLine: 5, type: 'highlighted' },
+        { startLine: 3, endLine: 5, type: 'highlighted', regionIndex: 0 },
         { startLine: 6, endLine: 7, type: 'normal' },
       ];
 
@@ -183,7 +183,9 @@ describe('restructureFrames', () => {
       const lines = [createLine(1, 'no indent'), createLine(2, '  some indent', '')];
       const root = createRoot(lines);
 
-      const frameRanges: FrameRange[] = [{ startLine: 1, endLine: 2, type: 'highlighted' }];
+      const frameRanges: FrameRange[] = [
+        { startLine: 1, endLine: 2, type: 'highlighted', regionIndex: 0 },
+      ];
 
       const regionIndentLevels = new Map<number, number>([[0, 0]]);
 
diff --git a/packages/docs-infra/src/pipeline/parseSource/restructureFrames.ts b/packages/docs-infra/src/pipeline/parseSource/restructureFrames.ts
index 3ebfb60a9..aa47a218d 100644
--- a/packages/docs-infra/src/pipeline/parseSource/restructureFrames.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/restructureFrames.ts
@@ -86,10 +86,7 @@ export function restructureFrames(
     lineEntryMap.set(entry.lineNumber, entry);
   }
 
-  // Step 2: Track which highlighted region index each frame range belongs to
-  let highlightedRegionIndex = 0;
-
-  // Step 3: Build new frames
+  // Step 2: Build new frames
   const newFrames: RootContent[] = [];
 
   for (const range of frameRanges) {
@@ -111,29 +108,22 @@ export function restructureFrames(
 
     // Only create frame if it has children
     if (children.length > 0) {
-      const isRegion =
-        range.type === 'highlighted' ||
-        range.type === 'highlighted-unfocused' ||
-        range.type === 'focus' ||
-        range.type === 'focus-unfocused';
-      const indentLevel = isRegion ? regionIndentLevels.get(highlightedRegionIndex) : undefined;
+      const indentLevel =
+        range.regionIndex !== undefined ? regionIndentLevels.get(range.regionIndex) : undefined;
 
       newFrames.push(
-        createFrame(children, range.startLine, range.endLine, range.type, indentLevel),
+        createFrame(
+          children,
+          range.startLine,
+          range.endLine,
+          range.type,
+          indentLevel,
+          range.truncated,
+        ),
       );
     }
-
-    // Increment region index after each region frame
-    if (
-      range.type === 'highlighted' ||
-      range.type === 'highlighted-unfocused' ||
-      range.type === 'focus' ||
-      range.type === 'focus-unfocused'
-    ) {
-      highlightedRegionIndex += 1;
-    }
   }
 
-  // Step 4: Replace root children
+  // Step 3: Replace root children
   root.children = newFrames;
 }
diff --git a/packages/docs-infra/src/useCode/Pre.tsx b/packages/docs-infra/src/useCode/Pre.tsx
index a79050a18..e8265d286 100644
--- a/packages/docs-infra/src/useCode/Pre.tsx
+++ b/packages/docs-infra/src/useCode/Pre.tsx
@@ -177,6 +177,11 @@ export function Pre({
                 ? String(child.properties.dataFrameIndent)
                 : undefined
             }
+            data-frame-truncated={
+              child.properties.dataFrameTruncated
+                ? String(child.properties.dataFrameTruncated)
+                : undefined
+            }
             ref={observeFrame}
           >
             {renderCode(

From f3f0047ffcf5de9ec44f94e2067ad1b34c418f0a Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 15 Apr 2026 20:19:53 -0400
Subject: [PATCH 04/44] Add emphasis config

---
 .../demos/collapsible-demo/createDemo.ts               |  5 -----
 docs/next.config.mjs                                   |  1 +
 .../loadPrecomputedCodeHighlighter.ts                  | 10 ++++++++--
 packages/docs-infra/src/withDocsInfra/withDocsInfra.ts |  9 +++++++++
 4 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/createDemo.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/createDemo.ts
index bd37e10f1..14772c480 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/createDemo.ts
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/createDemo.ts
@@ -4,21 +4,16 @@ import {
   createDemoFactory,
   createDemoWithVariantsFactory,
 } from '@mui/internal-docs-infra/abstractCreateDemo';
-import { createEnhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
 
 import { CollapsibleDemoContent as DemoContent } from '../CollapsibleDemoContent';
 import { DemoTitle } from '../../../../components/code-highlighter/demos/DemoTitle';
 
-const sourceEnhancers = [createEnhanceCodeEmphasis({ paddingFrameMaxSize: 3 })];
-
 export const createDemo = createDemoFactory({
   DemoContent,
   DemoTitle,
-  sourceEnhancers,
 });
 
 export const createDemoWithVariants = createDemoWithVariantsFactory({
   DemoContent,
   DemoTitle,
-  sourceEnhancers,
 });
diff --git a/docs/next.config.mjs b/docs/next.config.mjs
index b2b9af7d4..d660c0c37 100644
--- a/docs/next.config.mjs
+++ b/docs/next.config.mjs
@@ -56,6 +56,7 @@ export default withDeploymentConfig(
         index: ['./app/**/demos/*/demo-*/index.ts'],
         client: ['./app/**/demos/*/demo-*/client.ts'],
       },
+      emphasisOptions: { paddingFrameMaxSize: 1 },
     })(withMDX(nextConfig)),
   ),
 );
diff --git a/packages/docs-infra/src/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts b/packages/docs-infra/src/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts
index 2a263b26d..aa47bdae8 100644
--- a/packages/docs-infra/src/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts
+++ b/packages/docs-infra/src/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts
@@ -10,8 +10,9 @@ import { createParseSource } from '../parseSource';
 // TODO: re-enable following benchmarking
 // import { TypescriptToJavascriptTransformer } from '../transformTypescriptToJavascript';
 import type { SourceEnhancers, SourceTransformers, VariantCode } from '../../CodeHighlighter/types';
+import type { EnhanceCodeEmphasisOptions } from '../parseSource/calculateFrameRanges';
 import {
-  enhanceCodeEmphasis,
+  createEnhanceCodeEmphasis,
   EMPHASIS_COMMENT_PREFIX,
   FOCUS_COMMENT_PREFIX,
 } from '../enhanceCodeEmphasis/enhanceCodeEmphasis';
@@ -66,6 +67,11 @@ export type LoaderOptions = {
     showWrapperMeasures?: boolean;
   };
   output?: 'hast' | 'hastJson' | 'hastGzip';
+  /**
+   * Options for the code emphasis enhancer (padding frames, focus frames, etc.).
+   * Passed to `createEnhanceCodeEmphasis`.
+   */
+  emphasisOptions?: EnhanceCodeEmphasisOptions;
   /**
    * Prefixes for comments that should be stripped from the source output.
    * Comments starting with these prefixes will be removed from the returned source.
@@ -195,7 +201,7 @@ export async function loadPrecomputedCodeHighlighter(
     const sourceTransformers: SourceTransformers = [];
 
     // Setup source enhancers for post-parsing modifications
-    const sourceEnhancers: SourceEnhancers = [enhanceCodeEmphasis];
+    const sourceEnhancers: SourceEnhancers = [createEnhanceCodeEmphasis(options.emphasisOptions)];
 
     // Create sourceParser promise for syntax highlighting
     const sourceParser = createParseSource();
diff --git a/packages/docs-infra/src/withDocsInfra/withDocsInfra.ts b/packages/docs-infra/src/withDocsInfra/withDocsInfra.ts
index 16d56da22..19c92ad70 100644
--- a/packages/docs-infra/src/withDocsInfra/withDocsInfra.ts
+++ b/packages/docs-infra/src/withDocsInfra/withDocsInfra.ts
@@ -2,6 +2,7 @@ import type { NextConfig } from 'next';
 import type { Configuration as WebpackConfig, RuleSetRule } from 'webpack';
 import type { OrderingConfig } from '../pipeline/loadServerTypesText/order';
 import type { DescriptionReplacement } from '../pipeline/loadServerTypesMeta/format';
+import type { EnhanceCodeEmphasisOptions } from '../pipeline/parseSource/calculateFrameRanges';
 
 // Local type definition matching Next.js's internal JSONValue
 // Used for Turbopack loader options which require serializable values
@@ -84,6 +85,11 @@ export interface WithDocsInfraOptions {
    * @example ['@highlight', '@focus']
    */
   notableCommentsPrefix?: string[];
+  /**
+   * Options for the code emphasis enhancer (padding frames, focus frames, etc.).
+   * Passed to `createEnhanceCodeEmphasis` in the precomputed code highlighter loader.
+   */
+  emphasisOptions?: EnhanceCodeEmphasisOptions;
   /**
    * Name of the index file to update when syncing types metadata to parent indexes.
    * The types loader will call syncPageIndex to update the parent directory's index
@@ -305,6 +311,9 @@ export function withDocsInfra(options: WithDocsInfraOptions = {}) {
       output,
       ...(removeCommentsWithPrefix && { removeCommentsWithPrefix }),
       ...(notableCommentsPrefix && { notableCommentsPrefix }),
+      ...(options.emphasisOptions && {
+        emphasisOptions: options.emphasisOptions as unknown as JSONValue,
+      }),
     };
 
     const turbopackRules: Exclude<NextConfig['turbopack'], undefined>['rules'] = {

From 807ab405ce8d323695e599779a99ea12281d6026 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 15 Apr 2026 22:19:44 -0400
Subject: [PATCH 05/44] Allow `@padding` and `@min` override

---
 .../pipeline/enhance-code-emphasis/page.mdx   |  80 +++-
 .../pipeline/enhance-code-emphasis/types.md   |  30 +-
 docs/app/docs-infra/pipeline/page.mdx         |   4 +-
 .../pipeline/with-docs-infra/types.md         |   5 +
 .../enhanceCodeEmphasis.test.ts               | 453 ++++++++++++++++++
 .../enhanceCodeEmphasis.ts                    | 421 ++++++++++++++--
 .../parseSource/calculateFrameRanges.test.ts  | 167 +++++++
 .../parseSource/calculateFrameRanges.ts       | 108 ++++-
 8 files changed, 1193 insertions(+), 75 deletions(-)

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 07632af9e..d836b73b1 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
@@ -147,18 +147,26 @@ Each quoted text is independently wrapped in a `<span data-hl="">` element.
 
 The enhancer recognizes these comment patterns:
 
-| Pattern                       | Effect                                   |
-| ----------------------------- | ---------------------------------------- |
-| `@highlight`                  | Emphasize current line                   |
-| `@highlight "description"`    | Emphasize with description               |
-| `@highlight-start`            | Start multi-line block                   |
-| `@highlight-start "desc"`     | Start block with description             |
-| `@highlight-end`              | End multi-line block                     |
-| `@highlight-text "text"`      | Highlight specific text within the line  |
-| `@highlight-text "one" "two"` | Highlight multiple texts within the line |
-| `@focus`                      | Focus current line (no line highlight)   |
-| `@focus-start`                | Start focused block (no line highlight)  |
-| `@focus-end`                  | End focused block                        |
+| Pattern                       | Effect                                                |
+| ----------------------------- | ----------------------------------------------------- |
+| `@highlight`                  | Emphasize current line                                |
+| `@highlight "description"`    | Emphasize with description                            |
+| `@highlight-start`            | Start multi-line block                                |
+| `@highlight-start "desc"`     | Start block with description                          |
+| `@highlight-end`              | End multi-line block                                  |
+| `@highlight-text "text"`      | Highlight specific text within the line               |
+| `@highlight-text "one" "two"` | Highlight multiple texts within the line              |
+| `@focus`                      | Focus current line (no line highlight)                |
+| `@focus-start`                | Start focused block (no line highlight)               |
+| `@focus-end`                  | End focused block                                     |
+| `@highlight @padding 2`       | Highlight line with per-directive padding override    |
+| `@highlight-start @padding 2` | Highlight block with per-directive padding override   |
+| `@focus @padding 2`           | Focus line with per-directive padding override        |
+| `@focus-start @padding 2`     | Focus block with per-directive padding override       |
+| `@highlight @min 6`           | Highlight line with per-directive focus max override  |
+| `@highlight-start @min 6`     | Highlight block with per-directive focus max override |
+| `@focus @min 6`               | Focus line with per-directive focus max override      |
+| `@focus-start @min 6`         | Focus block with per-directive focus max override     |
 
 ### Description Format
 
@@ -319,6 +327,52 @@ const sourceEnhancers = [
 
 When `paddingFrameMaxSize` is `0` (the default), no padding frames are created and only region frames (`highlighted`, `focus`, etc.) and normal frames are produced.
 
+### Per-Directive Padding with `@padding N`
+
+Use `@padding N` directly on emphasis directives to override padding for that region:
+
+```tsx displayComments
+const important = loadData(); // @highlight @padding 1
+
+// @highlight-start @focus @padding 4 "Primary preview area"
+<Panel>
+  <Widget />
+</Panel>;
+// @highlight-end
+```
+
+In this example, the focused block uses padding `4` while the single highlighted line uses padding `1`.
+
+Padding precedence is:
+
+1. Per-directive `@padding N` on the focused region
+2. `createEnhanceCodeEmphasis({ paddingFrameMaxSize })`
+
+### Per-Directive Focus Max with `@min N`
+
+Use `@min N` on emphasis directives to override `focusFramesMaxSize` for the focused region:
+
+```tsx displayComments
+// @highlight-start @focus @min 6
+<form>
+  <Field name="firstName" />
+  <Field name="lastName" />
+  <Field name="email" />
+  <Field name="company" />
+  <Field name="role" />
+  <Field name="location" />
+  <Field name="timezone" />
+</form>
+// @highlight-end
+```
+
+In this example, the focused region is constrained to a visible window of `6` lines when collapsed, regardless of the global `focusFramesMaxSize` option.
+
+Focus max size precedence is:
+
+1. Per-directive `@min N` on the focused region
+2. `createEnhanceCodeEmphasis({ focusFramesMaxSize })`
+
 ### The `@focus` Directive
 
 When multiple highlight regions exist, padding is added around the **first** region by default. Add `@focus` to override which region receives padding:
@@ -478,7 +532,7 @@ import { DemoMaxSizeCode } from './demos/max-size-code';
 ### How It Works
 
 1. **Comment Extraction**: Comments are extracted during parsing with `notableCommentsPrefix: ['@highlight', '@focus']`
-2. **Directive Parsing**: The enhancer scans comments for `@highlight`, `@highlight-start`, `@highlight-end`, `@highlight-text`, `@focus`, `@focus-start`, and `@focus-end` patterns
+2. **Directive Parsing**: The enhancer scans comments for `@highlight`, `@highlight-start`, `@highlight-end`, `@highlight-text`, `@focus`, `@focus-start`, `@focus-end`, and optional `@padding N` / `@min N` modifiers
 3. **Line Calculation**: Single-line directives mark their own line; multi-line directives mark all lines from the first line after `@highlight-start` to the last line before `@highlight-end`
 4. **Nested Detection**: Lines inside multiple ranges are automatically marked as strong emphasis
 5. **HAST Modification**: The enhancer traverses the HAST tree and adds `dataHl: ''` (or `dataHl: 'strong'` for nested lines or descriptions ending with `!`) to line elements
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 80b9c50de..8c568bf18 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
@@ -76,12 +76,12 @@ type EmphasisMeta = {
   highlightTexts?: string[];
   /** Whether this line's region is the focused region (for padding) */
   focus?: boolean;
-  /**
-   * Whether the line itself should receive data-hl. True for
-   * @highlight , false for
-   * @focus-only .
-   */
+  /** Whether the line itself should receive data-hl. True for highlight directives and false for focus-only directives. */
   lineHighlight: boolean;
+  /** Optional per-directive padding override for this region */
+  paddingFrameMaxSize?: number;
+  /** Optional per-directive focus max size override for this region */
+  focusFramesMaxSize?: number;
 };
 ```
 
@@ -156,6 +156,26 @@ type FrameRange = {
 };
 ```
 
+### MIN_COMMENT_PREFIX
+
+Modifier token used inside `@highlight` / `@focus` comments
+to override focus max size for that directive.
+Example:
+
+```typescript
+type MIN_COMMENT_PREFIX = '@min';
+```
+
+### PADDING_COMMENT_PREFIX
+
+Modifier token used inside `@highlight` / `@focus` comments
+to override padding for that directive.
+Example:
+
+```typescript
+type PADDING_COMMENT_PREFIX = '@padding';
+```
+
 ## External Types
 
 ### SourceEnhancer
diff --git a/docs/app/docs-infra/pipeline/page.mdx b/docs/app/docs-infra/pipeline/page.mdx
index 922065146..4179a2b03 100644
--- a/docs/app/docs-infra/pipeline/page.mdx
+++ b/docs/app/docs-infra/pipeline/page.mdx
@@ -68,6 +68,8 @@ The `enhanceCodeEmphasis` source enhancer adds visual emphasis to specific lines
     - How It Works
     - Frame Data Attributes
     - Configurable Padding
+    - Per-Directive Padding with `@padding N`
+    - Per-Directive Focus Max with `@min N`
     - The `@focus` Directive
     - Standalone `@focus` (Focus Without Highlight)
     - Styling Frame Types
@@ -104,7 +106,7 @@ The `enhanceCodeEmphasis` source enhancer adds visual emphasis to specific lines
     - Parameters: options
   - enhanceCodeEmphasis
     - Parameters: root, comments, fileName
-- Types: EMPHASIS_COMMENT_PREFIX, EmphasisMeta, EnhanceCodeEmphasisOptions, FOCUS_COMMENT_PREFIX, FrameRange
+- Types: EMPHASIS_COMMENT_PREFIX, EmphasisMeta, EnhanceCodeEmphasisOptions, FOCUS_COMMENT_PREFIX, FrameRange, MIN_COMMENT_PREFIX, PADDING_COMMENT_PREFIX
 
 </details>
 
diff --git a/docs/app/docs-infra/pipeline/with-docs-infra/types.md b/docs/app/docs-infra/pipeline/with-docs-infra/types.md
index 4cae70559..a6f6d48da 100644
--- a/docs/app/docs-infra/pipeline/with-docs-infra/types.md
+++ b/docs/app/docs-infra/pipeline/with-docs-infra/types.md
@@ -165,6 +165,11 @@ type WithDocsInfraOptions = {
    * @example ['@highlight', '@focus']
    */
   notableCommentsPrefix?: string[];
+  /**
+   * Options for the code emphasis enhancer (padding frames, focus frames, etc.).
+   * Passed to `createEnhanceCodeEmphasis` in the precomputed code highlighter loader.
+   */
+  emphasisOptions?: EnhanceCodeEmphasisOptions;
   /**
    * Name of the index file to update when syncing types metadata to parent indexes.
    * The types loader will call syncPageIndex to update the parent directory's index
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
index e6d408410..444a11e84 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
@@ -1003,6 +1003,459 @@ const c = 3;`,
     });
   });
 
+  describe('@padding directive', () => {
+    it('should override paddingFrameMaxSize with inline @padding N', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1, // default: 1
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;
+const d = 4;
+const e = 5;
+const f = 6; // @highlight @padding 3
+const g = 7;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // The inline @padding 3 should override paddingFrameMaxSize: 1
+      // Line 6 is highlighted; padding of 3 above (lines 3-5) and 3 below (lines 7)
+      expect(result).toContain('data-frame-type="padding-top"');
+      expect(result).toContain('data-frame-type="highlighted"');
+      // Verify padding-top includes lines 3-5
+      expect(result).toMatch(
+        /data-frame-start-line="3" data-frame-end-line="5" data-frame-type="padding-top"/,
+      );
+    });
+
+    it('should parse inline @padding N with just whitespace', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;
+const d = 4; // @highlight @padding 2`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      expect(result).toContain('data-frame-type="padding-top"');
+      // Padding should be 2 (from @padding 2, not 1 from default)
+      expect(result).toMatch(
+        /data-frame-start-line="2" data-frame-end-line="3" data-frame-type="padding-top"/,
+      );
+    });
+
+    it('should use default padding if inline @padding is invalid', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3; // @highlight @padding invalid`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Invalid inline @padding should be ignored, use default paddingFrameMaxSize: 1
+      expect(result).toContain('data-frame-type="padding-top"');
+      expect(result).toMatch(
+        /data-frame-start-line="2" data-frame-end-line="2" data-frame-type="padding-top"/,
+      );
+    });
+  });
+
+  describe('@min directive', () => {
+    it('should override focusFramesMaxSize with inline @min N', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 2,
+        focusFramesMaxSize: 5,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3; // @highlight @min 1
+const d = 4;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Inline @min 1 overrides default focusFramesMaxSize: 5, so no padding remains.
+      expect(result).not.toContain('data-frame-type="padding-top"');
+      expect(result).not.toContain('data-frame-type="padding-bottom"');
+      expect(result).toMatch(
+        /data-frame-start-line="3" data-frame-end-line="3" data-frame-type="highlighted"/,
+      );
+    });
+
+    it('should support per-directive @min on the focused region', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 3,
+        focusFramesMaxSize: 8,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1; // @highlight
+const b = 2;
+const c = 3;
+const d = 4; // @highlight @focus @min 1
+const e = 5;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Focused line uses @min 1, so padding is suppressed around focused region.
+      expect(result).not.toContain('data-frame-type="padding-top"');
+      expect(result).not.toContain('data-frame-type="padding-bottom"');
+      expect(result).toMatch(
+        /data-frame-start-line="4" data-frame-end-line="4" data-frame-type="focus"/,
+      );
+      expect(result).toMatch(
+        /data-frame-start-line="1" data-frame-end-line="1" data-frame-type="highlighted-unfocused"/,
+      );
+    });
+
+    it('should use default focusFramesMaxSize if inline @min is invalid', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+        focusFramesMaxSize: 5,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3; // @highlight @min invalid
+const d = 4;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Invalid inline @min is ignored, so default focusFramesMaxSize applies with padding.
+      expect(result).toContain('data-frame-type="padding-top"');
+      expect(result).toContain('data-frame-type="padding-bottom"');
+      expect(result).toMatch(
+        /data-frame-start-line="2" data-frame-end-line="2" data-frame-type="padding-top"/,
+      );
+    });
+
+    it('should ignore invalid inline @min modifiers without affecting other modifiers', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+        focusFramesMaxSize: 5,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2; // @highlight @focus @min invalid "important"
+const c = 3;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Invalid @min should not break parsing of @focus/description.
+      expect(result).toMatch(
+        /data-frame-start-line="2" data-frame-end-line="2" data-frame-type="focus"/,
+      );
+      expect(result).toContain('data-hl-description="Important"');
+
+      // Falls back to default focusFramesMaxSize + paddingFrameMaxSize.
+      expect(result).toContain('data-frame-type="padding-top"');
+      expect(result).toContain('data-frame-type="padding-bottom"');
+    });
+
+    it('should prefer focus directive @min over earlier highlight @min in same region', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 2,
+        focusFramesMaxSize: 10,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3; // @highlight @min 8
+const d = 4; // @focus @min 1
+const e = 5;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Lines 3-4 form one contiguous region. The focus directive on line 4
+      // carries @min 1, which should override the @min 8 from the highlight
+      // on line 3. With focusFramesMaxSize=1 the 2-line region exceeds the
+      // limit, so it is split into visible + hidden.
+      expect(result).toMatch(
+        /data-frame-start-line="3" data-frame-end-line="3".*truncated="visible"/,
+      );
+      expect(result).toMatch(
+        /data-frame-start-line="4" data-frame-end-line="4".*truncated="hidden"/,
+      );
+    });
+
+    it('should prefer focus directive @padding over earlier highlight @padding in same region', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;
+const d = 4;
+const e = 5; // @highlight @padding 1
+const f = 6; // @focus @padding 4
+const g = 7;
+const h = 8;
+const i = 9;
+const j = 10;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Lines 5-6 form one contiguous region. The focus directive on line 6
+      // carries @padding 4, which should override the @padding 1 from the
+      // highlight on line 5. Padding of 4 above = lines 1-4, below = lines 7-10.
+      expect(result).toMatch(
+        /data-frame-start-line="1" data-frame-end-line="4" data-frame-type="padding-top"/,
+      );
+      expect(result).toMatch(
+        /data-frame-start-line="7" data-frame-end-line="10" data-frame-type="padding-bottom"/,
+      );
+    });
+
+    it('should prefer @focus padding when wrapped by @highlight-start with different padding', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;
+const d = 4;
+// @highlight-start @padding 1
+const e = 5;
+const f = 6; // @focus @padding 4
+const g = 7;
+// @highlight-end
+const h = 8;
+const i = 9;
+const j = 10;
+const k = 11;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // @highlight-start carries @padding 1, but the inner @focus carries
+      // @padding 4. The focus directive's padding should win for the region.
+      // After comment stripping: lines 5-7 form the region, padding 4 above/below.
+      expect(result).toMatch(
+        /data-frame-start-line="1" data-frame-end-line="4" data-frame-type="padding-top"/,
+      );
+      expect(result).toMatch(
+        /data-frame-start-line="8" data-frame-end-line="11" data-frame-type="padding-bottom"/,
+      );
+    });
+
+    it('should keep @focus-start padding when inner @highlight has different padding', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;
+const d = 4;
+// @focus-start @padding 4
+const e = 5;
+const f = 6; // @highlight @padding 1
+const g = 7;
+// @focus-end
+const h = 8;
+const i = 9;
+const j = 10;
+const k = 11;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // @focus-start carries @padding 4. The inner @highlight @padding 1
+      // should not override it. After comment stripping: lines 5-7 form
+      // the focused region, padding 4 above/below.
+      expect(result).toMatch(
+        /data-frame-start-line="1" data-frame-end-line="4" data-frame-type="padding-top"/,
+      );
+      expect(result).toMatch(
+        /data-frame-start-line="8" data-frame-end-line="11" data-frame-type="padding-bottom"/,
+      );
+    });
+
+    it('should use inner @focus padding over outer @focus-start padding', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;
+const d = 4;
+// @focus-start @padding 4
+const e = 5;
+const f = 6; // @focus @padding 2
+const g = 7;
+// @focus-end
+const h = 8;
+const i = 9;
+const j = 10;
+const k = 11;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // @focus-start @padding 4 wraps @focus @padding 2. The explicit inner
+      // @focus @padding 2 is more specific and should override the range's
+      // padding 4. After comment stripping: lines 5-7 form the region,
+      // padding 2 above/below.
+      expect(result).toMatch(
+        /data-frame-start-line="3" data-frame-end-line="4" data-frame-type="padding-top"/,
+      );
+      expect(result).toMatch(
+        /data-frame-start-line="8" data-frame-end-line="9" data-frame-type="padding-bottom"/,
+      );
+    });
+
+    it('should not let @highlight-text modifiers affect region padding', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3; // @highlight-text "c" @padding 5
+const d = 4;
+const e = 5;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // @highlight-text should not carry @padding modifiers.
+      // Default paddingFrameMaxSize=1 should apply.
+      expect(result).toMatch(
+        /data-frame-start-line="2" data-frame-end-line="2" data-frame-type="padding-top"/,
+      );
+      expect(result).toMatch(
+        /data-frame-start-line="4" data-frame-end-line="4" data-frame-type="padding-bottom"/,
+      );
+    });
+
+    it('should not strip @padding from quoted highlight-text', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 2,
+      });
+
+      const result = await testEmphasis(
+        `const a = "@padding 2"; // @highlight-text "@padding 2"
+const b = "other";
+const c = "end";`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // The quoted "@padding 2" should be treated as literal text to highlight,
+      // not stripped as a modifier. The text exists in the string literal on line 1.
+      expect(result).toContain('data-hl=""');
+    });
+
+    it('should not strip @min from quoted highlight-text', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        focusFramesMaxSize: 10,
+      });
+
+      const result = await testEmphasis(
+        `const a = "@min 6"; // @highlight-text "@min 6"
+const b = "other";
+const c = "end";`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // The quoted "@min 6" should be treated as literal text to highlight,
+      // not stripped as a modifier. The text exists in the string literal on line 1.
+      expect(result).toContain('data-hl=""');
+    });
+
+    it('should not strip @padding from description quotes', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2; // @highlight "has @padding 3 text"
+const c = 3;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // The "@padding 3" inside the description quotes should be preserved.
+      expect(result).toContain('data-frame-description="Has @padding 3 text"');
+    });
+
+    it('should extract unquoted @padding while preserving quoted @padding in same comment', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: 1,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;
+const d = 4;
+const e = 5; // @highlight @padding 3 "has @padding text"
+const f = 6;
+const g = 7;
+const h = 8;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Unquoted @padding 3 should be extracted as modifier (padding=3),
+      // while "@padding" inside quotes should remain in the description.
+      expect(result).toContain('data-frame-description="Has @padding text"');
+      expect(result).toMatch(
+        /data-frame-start-line="2" data-frame-end-line="4" data-frame-type="padding-top"/,
+      );
+    });
+  });
+
   describe('@focus directive', () => {
     it('should add padding around the @focus region instead of the first', async () => {
       const enhancer = createEnhanceCodeEmphasis({
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
index 9b518816a..7f4b8b625 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
@@ -24,6 +24,20 @@ export const EMPHASIS_COMMENT_PREFIX = '@highlight';
  */
 export const FOCUS_COMMENT_PREFIX = '@focus';
 
+/**
+ * Modifier token used inside `@highlight` / `@focus` comments
+ * to override padding for that directive.
+ * Example: @highlight @padding 2.
+ */
+export const PADDING_COMMENT_PREFIX = '@padding';
+
+/**
+ * Modifier token used inside `@highlight` / `@focus` comments
+ * to override focus max size for that directive.
+ * Example: @highlight @min 6.
+ */
+export const MIN_COMMENT_PREFIX = '@min';
+
 /**
  * Parsed emphasis directive from a comment.
  */
@@ -40,57 +54,282 @@ interface EmphasisDirective {
   focus?: boolean;
   /** Whether the line should be visually highlighted (false for focus-only directives) */
   lineHighlight: boolean;
+  /** Optional padding override for this region (applies to @highlight, @highlight-start, @focus, @focus-start) */
+  paddingFrameMaxSize?: number;
+  /** Optional focus max size override for this region (applies to @highlight, @highlight-start, @focus, @focus-start) */
+  focusFramesMaxSize?: number;
+}
+
+/**
+ * Replaces quoted content with underscores of the same length so that
+ * regex matching only finds tokens in unquoted territory.
+ * Supports double ("...") and single ('...') quotes.
+ */
+function maskQuotedContent(content: string): string {
+  let result = '';
+  let quoteChar: string | undefined;
+  for (let i = 0; i < content.length; i += 1) {
+    const ch = content[i];
+    if (quoteChar) {
+      result += '_';
+      if (ch === quoteChar) {
+        quoteChar = undefined;
+      }
+    } else if (ch === '"' || ch === "'") {
+      quoteChar = ch;
+      result += '_';
+    } else {
+      result += ch;
+    }
+  }
+  return result;
+}
+
+/**
+ * Returns `true` when `ch` is an ASCII whitespace character.
+ */
+function isWhitespace(ch: string | undefined): boolean {
+  return ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r';
+}
+
+/**
+ * Finds the first occurrence of `token` in `masked` that sits at a word
+ * boundary (preceded by start-of-string or whitespace, followed by
+ * end-of-string or whitespace).  Returns the index or -1.
+ */
+function findToken(masked: string, token: string, startFrom = 0): number {
+  let idx = masked.indexOf(token, startFrom);
+  while (idx !== -1) {
+    const before = idx === 0 || isWhitespace(masked[idx - 1]);
+    const after = idx + token.length >= masked.length || isWhitespace(masked[idx + token.length]);
+    if (before && after) {
+      return idx;
+    }
+    idx = masked.indexOf(token, idx + 1);
+  }
+  return -1;
+}
+
+/**
+ * Reads consecutive ASCII digits starting at `pos`.
+ * Returns the substring of digits (may be empty).
+ */
+function readDigits(str: string, pos: number): string {
+  let end = pos;
+  while (end < str.length && str[end] >= '0' && str[end] <= '9') {
+    end += 1;
+  }
+  return str.slice(pos, end);
+}
+
+/**
+ * Collapses runs of whitespace into a single space and trims.
+ */
+function collapseWhitespace(str: string): string {
+  let result = '';
+  let prevSpace = false;
+  for (let i = 0; i < str.length; i += 1) {
+    if (isWhitespace(str[i])) {
+      prevSpace = true;
+    } else {
+      if (prevSpace && result.length > 0) {
+        result += ' ';
+      }
+      prevSpace = false;
+      result += str[i];
+    }
+  }
+  return result;
+}
+
+/**
+ * Extracts a number from content (e.g., "3" from "@padding 3 @focus").
+ * Returns the parsed number or undefined if not found or invalid.
+ * Only matches unquoted tokens — "@padding 2" inside quotes is ignored.
+ */
+function extractPaddingValue(content: string): number | undefined {
+  const masked = maskQuotedContent(content);
+  const idx = findToken(masked, '@padding');
+  if (idx === -1) {
+    return undefined;
+  }
+  // Skip whitespace after "@padding"
+  let p = idx + '@padding'.length;
+  while (p < masked.length && isWhitespace(masked[p])) {
+    p += 1;
+  }
+  const digits = readDigits(masked, p);
+  if (digits.length === 0) {
+    return undefined;
+  }
+  // Must be followed by whitespace or end-of-string
+  const afterDigits = p + digits.length;
+  if (afterDigits < masked.length && !isWhitespace(masked[afterDigits])) {
+    return undefined;
+  }
+  const value = parseInt(digits, 10);
+  return Number.isNaN(value) ? undefined : value;
+}
+
+/**
+ * Removes the `@padding N` directive from content (if present).
+ * Only removes unquoted tokens — "@padding 2" inside quotes is preserved.
+ */
+function removePaddingDirective(content: string): string {
+  const masked = maskQuotedContent(content);
+  const idx = findToken(masked, '@padding');
+  if (idx === -1) {
+    return content;
+  }
+  // Find the full span: leading whitespace + "@padding" + optional whitespace + digits + trailing whitespace
+  let start = idx;
+  while (start > 0 && isWhitespace(content[start - 1])) {
+    start -= 1;
+  }
+  let end = idx + '@padding'.length;
+  while (end < content.length && isWhitespace(content[end])) {
+    end += 1;
+  }
+  // Skip digits
+  while (end < content.length && content[end] >= '0' && content[end] <= '9') {
+    end += 1;
+  }
+  // Skip trailing whitespace
+  while (end < content.length && isWhitespace(content[end])) {
+    end += 1;
+  }
+  return collapseWhitespace(`${content.slice(0, start)} ${content.slice(end)}`);
+}
+
+/**
+ * Extracts a number from content (e.g., "6" from "@min 6 @focus").
+ * Returns the parsed number or undefined if not found or invalid.
+ * Only matches unquoted tokens — "@min 6" inside quotes is ignored.
+ */
+function extractMinValue(content: string): number | undefined {
+  const masked = maskQuotedContent(content);
+  const idx = findToken(masked, '@min');
+  if (idx === -1) {
+    return undefined;
+  }
+  // Skip whitespace after "@min"
+  let p = idx + '@min'.length;
+  while (p < masked.length && isWhitespace(masked[p])) {
+    p += 1;
+  }
+  const digits = readDigits(masked, p);
+  if (digits.length === 0) {
+    return undefined;
+  }
+  // Must be followed by whitespace or end-of-string
+  const afterDigits = p + digits.length;
+  if (afterDigits < masked.length && !isWhitespace(masked[afterDigits])) {
+    return undefined;
+  }
+  const value = parseInt(digits, 10);
+  return Number.isNaN(value) || value < 1 ? undefined : value;
+}
+
+/**
+ * Removes the `@min` directive (and its optional value) from content.
+ * Only removes unquoted tokens — "@min 6" inside quotes is preserved.
+ */
+function removeMinDirective(content: string): string {
+  const masked = maskQuotedContent(content);
+  const idx = findToken(masked, '@min');
+  if (idx === -1) {
+    return content;
+  }
+  // Find the full span: leading whitespace + "@min" + optional (whitespace + non-whitespace value) + trailing whitespace
+  let start = idx;
+  while (start > 0 && isWhitespace(content[start - 1])) {
+    start -= 1;
+  }
+  let end = idx + '@min'.length;
+  // Skip whitespace after @min
+  let ws = end;
+  while (ws < content.length && isWhitespace(content[ws])) {
+    ws += 1;
+  }
+  // If there's a non-whitespace, non-quote value after @min, skip it
+  if (
+    ws < content.length &&
+    content[ws] !== '"' &&
+    content[ws] !== "'" &&
+    !isWhitespace(content[ws])
+  ) {
+    end = ws;
+    while (end < content.length && !isWhitespace(content[end])) {
+      end += 1;
+    }
+  }
+  // Skip trailing whitespace
+  while (end < content.length && isWhitespace(content[end])) {
+    end += 1;
+  }
+  return collapseWhitespace(`${content.slice(0, start)} ${content.slice(end)}`);
 }
 
 /**
  * Extracts a quoted string from content.
  * Supports both double quotes ("...") and single quotes ('...').
- * Escaped quotes within the string are not supported.
- *
- * @param content - The content to extract the quoted string from
- * @returns The extracted string (without quotes) or undefined if no quoted string found
+ * If the entire content is a single quoted string, returns its inner text.
+ * Otherwise returns the first quoted substring found.
  */
 function extractQuotedString(content: string): string | undefined {
-  const match = content.match(/^(["'])(.*)\1$/);
-  if (match) {
-    return match[2];
+  const trimmed = content.trim();
+  // Check if the entire content is a single quoted string
+  if (trimmed.length >= 2) {
+    const first = trimmed[0];
+    if ((first === '"' || first === "'") && trimmed[trimmed.length - 1] === first) {
+      return trimmed.slice(1, -1);
+    }
   }
-  // Also try to find quoted string anywhere in the content
-  const anyMatch = content.match(/(["'])([^"']+)\1/);
-  return anyMatch?.[2];
+  // Find first quoted substring anywhere
+  for (let i = 0; i < content.length; i += 1) {
+    const ch = content[i];
+    if (ch === '"' || ch === "'") {
+      const close = content.indexOf(ch, i + 1);
+      if (close !== -1 && close > i + 1) {
+        return content.slice(i + 1, close);
+      }
+    }
+  }
+  return undefined;
 }
 
 /**
  * Extracts all quoted strings from content.
  * Supports both double quotes ("...") and single quotes ('...').
- *
- * @param content - The content to extract quoted strings from
- * @returns Array of extracted strings (without quotes), empty if none found
  */
 function extractAllQuotedStrings(content: string): string[] {
   const results: string[] = [];
-  const regex = /(["'])([^"']+)\1/g;
-  let match = regex.exec(content);
-  while (match) {
-    results.push(match[2]);
-    match = regex.exec(content);
+  let i = 0;
+  while (i < content.length) {
+    const ch = content[i];
+    if (ch === '"' || ch === "'") {
+      const close = content.indexOf(ch, i + 1);
+      if (close !== -1 && close > i + 1) {
+        results.push(content.slice(i + 1, close));
+        i = close + 1;
+        continue;
+      }
+    }
+    i += 1;
   }
   return results;
 }
+
 /**
  * Extracts and removes the `@focus` keyword from content.
- *
- * @param content - The content to check for `@focus`
- * @returns An object with `focus` boolean and the `remaining` content with `@focus` removed
  */
 function extractFocus(content: string): { focus: boolean; remaining: string } {
-  // Match @focus only as a standalone token (not inside quotes)
-  const match = content.match(/(^|\s)@focus(\s|$)/);
-  if (!match) {
+  const masked = maskQuotedContent(content);
+  const idx = findToken(masked, '@focus');
+  if (idx === -1) {
     return { focus: false, remaining: content };
   }
-  const start = match.index! + match[1].length;
-  const remaining = (content.slice(0, start) + content.slice(start + '@focus'.length)).trim();
+  const remaining = (content.slice(0, idx) + content.slice(idx + '@focus'.length)).trim();
   return { focus: true, remaining };
 }
 
@@ -144,25 +383,62 @@ function parseHighlightDirective(
   line: number,
   content: string,
 ): void {
-  if (content.startsWith('-end')) {
-    directives.push({ line, type: 'end', lineHighlight: true });
-  } else if (content.startsWith('-start')) {
-    const afterStart = content.slice('-start'.length).trim();
+  // Extract @padding if present
+  const paddingFrameMaxSize = extractPaddingValue(content);
+  const focusFramesMaxSize = extractMinValue(content);
+  const contentWithoutModifiers = removeMinDirective(removePaddingDirective(content));
+
+  if (contentWithoutModifiers.startsWith('-end')) {
+    directives.push({
+      line,
+      type: 'end',
+      lineHighlight: true,
+      paddingFrameMaxSize,
+      focusFramesMaxSize,
+    });
+  } else if (contentWithoutModifiers.startsWith('-start')) {
+    const afterStart = contentWithoutModifiers.slice('-start'.length).trim();
     const { focus, remaining: remainingStart } = extractFocus(afterStart);
     const description = extractQuotedString(remainingStart);
-    directives.push({ line, type: 'start', description, focus, lineHighlight: true });
-  } else if (content.startsWith('-text')) {
-    const afterText = content.slice('-text'.length).trim();
+    directives.push({
+      line,
+      type: 'start',
+      description,
+      focus,
+      lineHighlight: true,
+      paddingFrameMaxSize,
+      focusFramesMaxSize,
+    });
+  } else if (contentWithoutModifiers.startsWith('-text')) {
+    const afterText = contentWithoutModifiers.slice('-text'.length).trim();
     const { focus, remaining: remainingText } = extractFocus(afterText);
     const highlightTexts = extractAllQuotedStrings(remainingText);
     if (highlightTexts.length > 0) {
-      directives.push({ line, type: 'text', highlightTexts, focus, lineHighlight: true });
+      // Text-only markers should not influence region padding, so
+      // @padding/@min modifiers are intentionally omitted here.
+      directives.push({
+        line,
+        type: 'text',
+        highlightTexts,
+        focus,
+        lineHighlight: true,
+        paddingFrameMaxSize: undefined,
+        focusFramesMaxSize: undefined,
+      });
     }
   } else {
-    const afterHighlight = content.trim();
+    const afterHighlight = contentWithoutModifiers.trim();
     const { focus, remaining: remainingSingle } = extractFocus(afterHighlight);
     const description = extractQuotedString(remainingSingle) || undefined;
-    directives.push({ line, type: 'single', description, focus, lineHighlight: true });
+    directives.push({
+      line,
+      type: 'single',
+      description,
+      focus,
+      lineHighlight: true,
+      paddingFrameMaxSize,
+      focusFramesMaxSize,
+    });
   }
 }
 
@@ -170,17 +446,44 @@ function parseHighlightDirective(
  * Parses a `@focus` comment into a focus-only directive (no line highlight).
  */
 function parseFocusDirective(directives: EmphasisDirective[], line: number, content: string): void {
-  if (content.startsWith('-end')) {
-    directives.push({ line, type: 'end', lineHighlight: false });
-  } else if (content.startsWith('-start')) {
-    const afterStart = content.slice('-start'.length).trim();
+  // Extract @padding if present
+  const paddingFrameMaxSize = extractPaddingValue(content);
+  const focusFramesMaxSize = extractMinValue(content);
+  const contentWithoutModifiers = removeMinDirective(removePaddingDirective(content));
+
+  if (contentWithoutModifiers.startsWith('-end')) {
+    directives.push({
+      line,
+      type: 'end',
+      lineHighlight: false,
+      paddingFrameMaxSize,
+      focusFramesMaxSize,
+    });
+  } else if (contentWithoutModifiers.startsWith('-start')) {
+    const afterStart = contentWithoutModifiers.slice('-start'.length).trim();
     const description = extractQuotedString(afterStart);
-    directives.push({ line, type: 'start', description, focus: true, lineHighlight: false });
+    directives.push({
+      line,
+      type: 'start',
+      description,
+      focus: true,
+      lineHighlight: false,
+      paddingFrameMaxSize,
+      focusFramesMaxSize,
+    });
   } else {
     // Single line: @focus or @focus "description"
-    const afterFocus = content.trim();
+    const afterFocus = contentWithoutModifiers.trim();
     const description = extractQuotedString(afterFocus) || undefined;
-    directives.push({ line, type: 'single', description, focus: true, lineHighlight: false });
+    directives.push({
+      line,
+      type: 'single',
+      description,
+      focus: true,
+      lineHighlight: false,
+      paddingFrameMaxSize,
+      focusFramesMaxSize,
+    });
   }
 }
 
@@ -323,6 +626,8 @@ function calculateEmphasizedLines(
         position: 'single',
         lineHighlight: directive.lineHighlight,
         focus: directive.focus,
+        paddingFrameMaxSize: directive.paddingFrameMaxSize,
+        focusFramesMaxSize: directive.focusFramesMaxSize,
       });
     } else if (directive.type === 'text') {
       // Text highlight - emphasize specific text(s) within the line.
@@ -339,6 +644,8 @@ function calculateEmphasizedLines(
         lineHighlight: existing?.lineHighlight ?? directive.lineHighlight,
         highlightTexts: mergedTexts,
         focus: directive.focus || existing?.focus,
+        paddingFrameMaxSize: directive.paddingFrameMaxSize ?? existing?.paddingFrameMaxSize,
+        focusFramesMaxSize: directive.focusFramesMaxSize ?? existing?.focusFramesMaxSize,
       });
     }
   }
@@ -412,6 +719,25 @@ function calculateEmphasizedLines(
               highlightTexts: existing.highlightTexts, // Preserve text highlights from @highlight-text
               lineHighlight: existing.lineHighlight || startDirective.lineHighlight,
               focus: existing.focus || startDirective.focus,
+              // When the outer range is focus and the inner is not, the focus
+              // range's overrides win (focus tier > non-focus).  When both
+              // are the same tier, the inner (existing) wins since it was
+              // placed by a more specific directive.
+              paddingFrameMaxSize:
+                startDirective.focus && !existing.focus
+                  ? (startDirective.paddingFrameMaxSize ?? existing.paddingFrameMaxSize)
+                  : (existing.paddingFrameMaxSize ?? startDirective.paddingFrameMaxSize),
+              focusFramesMaxSize:
+                startDirective.focus && !existing.focus
+                  ? (startDirective.focusFramesMaxSize ?? existing.focusFramesMaxSize)
+                  : (existing.focusFramesMaxSize ?? startDirective.focusFramesMaxSize),
+              // Propagated when existing had no overrides of its own (all come
+              // from the range), or when existing was itself propagated.
+              propagatedOverride:
+                existing.paddingFrameMaxSize !== undefined ||
+                existing.focusFramesMaxSize !== undefined
+                  ? existing.propagatedOverride
+                  : true,
             }
           : {
               strong,
@@ -419,6 +745,9 @@ function calculateEmphasizedLines(
               position,
               lineHighlight: startDirective.lineHighlight,
               focus: startDirective.focus,
+              paddingFrameMaxSize: startDirective.paddingFrameMaxSize,
+              focusFramesMaxSize: startDirective.focusFramesMaxSize,
+              propagatedOverride: true,
             };
 
         emphasizedLines.set(line, meta);
@@ -1069,6 +1398,8 @@ export function createEnhanceCodeEmphasis(
     // Step 1: Parse directives from comments (no tree traversal)
     const directives = parseEmphasisDirectives(comments);
 
+    const effectiveOptions = options;
+
     if (directives.length === 0) {
       return root;
     }
@@ -1087,7 +1418,7 @@ export function createEnhanceCodeEmphasis(
     const highlightedElements = applyEmphasisAndCollectHighlightedElements(
       root,
       emphasizedLines,
-      options,
+      effectiveOptions,
     );
 
     // Step 5: Calculate indent levels per region (uses collected elements, no tree traversal)
@@ -1095,7 +1426,7 @@ export function createEnhanceCodeEmphasis(
 
     // Step 6: Calculate frame ranges (pure math, no tree traversal)
     const totalLines = (root.data as { totalLines?: number })?.totalLines ?? lineElements.size;
-    const frameRanges = calculateFrameRanges(emphasizedLines, totalLines, options);
+    const frameRanges = calculateFrameRanges(emphasizedLines, totalLines, effectiveOptions);
 
     // Step 7: Restructure frames (flat iteration, not deep recursive traversal)
     restructureFrames(root, frameRanges, regionIndentLevels);
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
index 575523713..490581c0d 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
@@ -358,6 +358,173 @@ describe('calculateFrameRanges', () => {
         { startLine: 13, endLine: 20, type: 'normal' },
       ]);
     });
+
+    it('should prefer per-region focusFramesMaxSize over global option', () => {
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [5, { lineHighlight: true, focus: true, focusFramesMaxSize: 2 }],
+        [6, { lineHighlight: true, focus: true, focusFramesMaxSize: 2 }],
+        [7, { lineHighlight: true, focus: true, focusFramesMaxSize: 2 }],
+        [8, { lineHighlight: true, focus: true, focusFramesMaxSize: 2 }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 10, {
+        focusFramesMaxSize: 6,
+      });
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 4, type: 'normal' },
+        { startLine: 5, endLine: 6, type: 'focus', regionIndex: 0, truncated: 'visible' },
+        { startLine: 7, endLine: 8, type: 'focus-unfocused', regionIndex: 0, truncated: 'hidden' },
+        { startLine: 9, endLine: 10, type: 'normal' },
+      ]);
+    });
+
+    it('should use focus directive padding when earlier highlight has conflicting padding', () => {
+      // Line 5: highlight with padding 1, line 6: focus with padding 4
+      // Focus directive's padding should win for the region
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [5, { lineHighlight: true, paddingFrameMaxSize: 1 }],
+        [6, { lineHighlight: true, focus: true, paddingFrameMaxSize: 4 }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 15, {
+        paddingFrameMaxSize: 2,
+      });
+
+      // Region spans lines 5-6, focused. Focus directive says padding 4.
+      // padding-top: lines 1-4 (4 lines), padding-bottom: lines 7-10 (4 lines)
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 4, type: 'padding-top' },
+        { startLine: 5, endLine: 6, type: 'focus', regionIndex: 0 },
+        { startLine: 7, endLine: 10, type: 'padding-bottom' },
+        { startLine: 11, endLine: 15, type: 'normal' },
+      ]);
+    });
+
+    it('should use focus directive focusFramesMaxSize when earlier highlight has conflicting override', () => {
+      // Line 5: highlight with @min 10, line 6: focus with @min 2
+      // Focus directive's @min should win for the region
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [5, { lineHighlight: true, focusFramesMaxSize: 10 }],
+        [6, { lineHighlight: true, focus: true, focusFramesMaxSize: 2 }],
+        [7, { lineHighlight: true, focus: true }],
+        [8, { lineHighlight: true, focus: true }],
+        [9, { lineHighlight: true, focus: true }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 12, {
+        focusFramesMaxSize: 6,
+      });
+
+      // Region spans lines 5-9 (5 lines). Focus @min 2 applies, so
+      // visible window = 2 lines (5-6), hidden overflow = 3 lines (7-9)
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 4, type: 'normal' },
+        { startLine: 5, endLine: 6, type: 'focus', regionIndex: 0, truncated: 'visible' },
+        { startLine: 7, endLine: 9, type: 'focus-unfocused', regionIndex: 0, truncated: 'hidden' },
+        { startLine: 10, endLine: 12, type: 'normal' },
+      ]);
+    });
+
+    it('should keep first focus-line padding when later propagated-focus lines carry different overrides', () => {
+      // All lines have focus=true (propagated from @focus-start) but carry
+      // different paddingFrameMaxSize values (e.g. an inner @highlight).
+      // The first override in the focus channel should be kept.
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [5, { lineHighlight: false, focus: true, paddingFrameMaxSize: 4 }],
+        [6, { lineHighlight: true, focus: true, paddingFrameMaxSize: 1 }],
+        [7, { lineHighlight: false, focus: true }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 15, {
+        paddingFrameMaxSize: 2,
+      });
+
+      // padding 4 from line 5 (first focus override) should win
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 4, type: 'padding-top' },
+        { startLine: 5, endLine: 7, type: 'focus', regionIndex: 0 },
+        { startLine: 8, endLine: 11, type: 'padding-bottom' },
+        { startLine: 12, endLine: 15, type: 'normal' },
+      ]);
+    });
+
+    it('should keep first focus-line focusMaxSize when later propagated-focus lines carry different overrides', () => {
+      // Similar to above but for focusFramesMaxSize
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [5, { lineHighlight: true, focus: true, focusFramesMaxSize: 3 }],
+        [6, { lineHighlight: true, focus: true, focusFramesMaxSize: 10 }],
+        [7, { lineHighlight: true, focus: true }],
+        [8, { lineHighlight: true, focus: true }],
+        [9, { lineHighlight: true, focus: true }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 12, {
+        focusFramesMaxSize: 6,
+      });
+
+      // focusMaxSize 3 from line 5 (first focus override) should win,
+      // splitting the 5-line region into visible 5-7 and hidden 8-9
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 4, type: 'normal' },
+        { startLine: 5, endLine: 7, type: 'focus', regionIndex: 0, truncated: 'visible' },
+        { startLine: 8, endLine: 9, type: 'focus-unfocused', regionIndex: 0, truncated: 'hidden' },
+        { startLine: 10, endLine: 12, type: 'normal' },
+      ]);
+    });
+
+    it('should prefer non-focus override when no focus line carries an override', () => {
+      // Mixed region: highlight lines without focus carry an override,
+      // focus lines have no override. The non-focus override should be used.
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [5, { lineHighlight: true, paddingFrameMaxSize: 3 }],
+        [6, { lineHighlight: false, focus: true }],
+        [7, { lineHighlight: false, focus: true }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 12, {
+        paddingFrameMaxSize: 1,
+      });
+
+      // padding 3 from the non-focus highlight on line 5
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 1, type: 'normal' },
+        { startLine: 2, endLine: 4, type: 'padding-top' },
+        { startLine: 5, endLine: 7, type: 'focus', regionIndex: 0 },
+        { startLine: 8, endLine: 10, type: 'padding-bottom' },
+        { startLine: 11, endLine: 12, type: 'normal' },
+      ]);
+    });
+
+    it('should use inner explicit focus padding over propagated focus-start padding', () => {
+      // Simulates @focus-start @padding 4 wrapping @focus @padding 2.
+      // All lines carry focus=true; lines 5 and 7 are propagated from the
+      // range while line 6 is an explicit per-line directive.
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [
+          5,
+          { lineHighlight: false, focus: true, paddingFrameMaxSize: 4, propagatedOverride: true },
+        ],
+        [6, { lineHighlight: false, focus: true, paddingFrameMaxSize: 2 }],
+        [
+          7,
+          { lineHighlight: false, focus: true, paddingFrameMaxSize: 4, propagatedOverride: true },
+        ],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 15, {
+        paddingFrameMaxSize: 1,
+      });
+
+      // Explicit @focus @padding 2 on line 6 should override propagated padding 4
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 2, type: 'normal' },
+        { startLine: 3, endLine: 4, type: 'padding-top' },
+        { startLine: 5, endLine: 7, type: 'focus', regionIndex: 0 },
+        { startLine: 8, endLine: 9, type: 'padding-bottom' },
+        { startLine: 10, endLine: 15, type: 'normal' },
+      ]);
+    });
   });
 
   describe('input validation', () => {
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
index 8e08d91bf..8e8601e13 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
@@ -12,8 +12,18 @@ export interface EmphasisMeta {
   highlightTexts?: string[];
   /** Whether this line's region is the focused region (for padding) */
   focus?: boolean;
-  /** Whether the line itself should receive data-hl. True for @highlight, false for @focus-only. */
+  /** Whether the line itself should receive data-hl. True for highlight directives and false for focus-only directives. */
   lineHighlight: boolean;
+  /** Optional per-directive padding override for this region */
+  paddingFrameMaxSize?: number;
+  /** Optional per-directive focus max size override for this region */
+  focusFramesMaxSize?: number;
+  /**
+   * True when the overrides were propagated from a multiline range
+   * rather than set by an explicit per-line directive.
+   * Explicit overrides take precedence over propagated ones in regions.
+   */
+  propagatedOverride?: boolean;
 }
 
 /**
@@ -58,6 +68,10 @@ interface HighlightRegion {
   focused: boolean;
   /** Whether any line in this region has line-level highlighting (data-hl) */
   hasLineHighlight: boolean;
+  /** Per-directive padding override for this region, if specified */
+  paddingFrameMaxSize?: number;
+  /** Per-directive focus max size override for this region, if specified */
+  focusFramesMaxSize?: number;
 }
 
 /**
@@ -102,11 +116,71 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
   const sortedLines = Array.from(emphasizedLines.keys()).sort((a, b) => a - b);
   const regions: HighlightRegion[] = [];
 
+  // Track overrides in three tiers (highest to lowest priority):
+  //   1. explicit focus — per-line focus directive (propagatedOverride !== true)
+  //   2. propagated focus — multiline focus range (propagatedOverride === true)
+  //   3. non-focus — highlight directives without focus
+  // Within each tier, first-in-region wins (??=).
+  interface OverrideChannels {
+    explicitFocusPadding: number | undefined;
+    propagatedFocusPadding: number | undefined;
+    nonFocusPadding: number | undefined;
+    explicitFocusMaxSize: number | undefined;
+    propagatedFocusMaxSize: number | undefined;
+    nonFocusMaxSize: number | undefined;
+  }
+
+  function emptyChannels(): OverrideChannels {
+    return {
+      explicitFocusPadding: undefined,
+      propagatedFocusPadding: undefined,
+      nonFocusPadding: undefined,
+      explicitFocusMaxSize: undefined,
+      propagatedFocusMaxSize: undefined,
+      nonFocusMaxSize: undefined,
+    };
+  }
+
+  function accumulateOverrides(ch: OverrideChannels, meta: EmphasisMeta | undefined): void {
+    if (meta?.paddingFrameMaxSize !== undefined) {
+      if (meta.focus) {
+        if (meta.propagatedOverride) {
+          ch.propagatedFocusPadding ??= meta.paddingFrameMaxSize;
+        } else {
+          ch.explicitFocusPadding ??= meta.paddingFrameMaxSize;
+        }
+      } else {
+        ch.nonFocusPadding ??= meta.paddingFrameMaxSize;
+      }
+    }
+    if (meta?.focusFramesMaxSize !== undefined) {
+      if (meta.focus) {
+        if (meta.propagatedOverride) {
+          ch.propagatedFocusMaxSize ??= meta.focusFramesMaxSize;
+        } else {
+          ch.explicitFocusMaxSize ??= meta.focusFramesMaxSize;
+        }
+      } else {
+        ch.nonFocusMaxSize ??= meta.focusFramesMaxSize;
+      }
+    }
+  }
+
+  function resolvePadding(ch: OverrideChannels): number | undefined {
+    return ch.explicitFocusPadding ?? ch.propagatedFocusPadding ?? ch.nonFocusPadding;
+  }
+
+  function resolveMaxSize(ch: OverrideChannels): number | undefined {
+    return ch.explicitFocusMaxSize ?? ch.propagatedFocusMaxSize ?? ch.nonFocusMaxSize;
+  }
+
   let regionStart = sortedLines[0];
   let regionEnd = sortedLines[0];
   const firstMeta = emphasizedLines.get(sortedLines[0]);
   let hasFocus = firstMeta?.focus ?? false;
   let hasLineHighlight = firstMeta?.lineHighlight ?? false;
+  let ch = emptyChannels();
+  accumulateOverrides(ch, firstMeta);
 
   for (let i = 1; i < sortedLines.length; i += 1) {
     const line = sortedLines[i];
@@ -120,6 +194,7 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
       if (meta?.lineHighlight) {
         hasLineHighlight = true;
       }
+      accumulateOverrides(ch, meta);
     } else {
       // Gap found, close current region and start a new one
       regions.push({
@@ -128,22 +203,28 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
         index: regions.length,
         focused: hasFocus,
         hasLineHighlight,
+        paddingFrameMaxSize: resolvePadding(ch),
+        focusFramesMaxSize: resolveMaxSize(ch),
       });
       regionStart = line;
       regionEnd = line;
       const meta = emphasizedLines.get(line);
       hasFocus = meta?.focus ?? false;
       hasLineHighlight = meta?.lineHighlight ?? false;
+      ch = emptyChannels();
+      accumulateOverrides(ch, meta);
     }
   }
 
   // Close the last region
   regions.push({
+    paddingFrameMaxSize: resolvePadding(ch),
     startLine: regionStart,
     endLine: regionEnd,
     index: regions.length,
     focused: hasFocus,
     hasLineHighlight,
+    focusFramesMaxSize: resolveMaxSize(ch),
   });
 
   return regions;
@@ -167,26 +248,29 @@ function determineFocusedRegionIndex(regions: HighlightRegion[]): number {
  * @param region - The focused highlight region
  * @param prevRegionEnd - End line of the previous highlight region (or 0)
  * @param nextRegionStart - Start line of the next highlight region (or totalLines + 1)
- * @param options - Padding configuration options
+ * @param paddingFrameMaxSize - Per-region padding size (or from global options if undefined)
+ * @param focusFramesMaxSize - Global focus frames max size option
  * @returns Padding sizes [paddingTop, paddingBottom]
  */
+
 function calculatePadding(
   region: HighlightRegion,
   prevRegionEnd: number,
   nextRegionStart: number,
-  options: EnhanceCodeEmphasisOptions,
+  paddingFrameMaxSize: number | undefined,
+  focusFramesMaxSize: number | undefined,
 ): [number, number] {
-  const { paddingFrameMaxSize = 0, focusFramesMaxSize } = options;
+  // Use per-region padding, fallback to 0 if not specified
+  const padding = paddingFrameMaxSize ?? 0;
 
-  if (paddingFrameMaxSize <= 0) {
+  if (padding <= 0) {
     return [0, 0];
   }
 
   const highlightSize = region.endLine - region.startLine + 1;
 
-  let paddingTop = paddingFrameMaxSize;
-  let paddingBottom = paddingFrameMaxSize;
-
+  let paddingTop = padding;
+  let paddingBottom = padding;
   // Apply focusFramesMaxSize constraint
   if (focusFramesMaxSize !== undefined) {
     const remaining = focusFramesMaxSize - highlightSize;
@@ -283,19 +367,21 @@ export function calculateFrameRanges(
 
   // Calculate focus window split (for oversized regions)
   const focusedRegion = regions[focusedIndex];
-  const focusWindow = calculateFocusWindow(focusedRegion, options.focusFramesMaxSize);
+  const focusFramesMaxSize = focusedRegion.focusFramesMaxSize ?? options.focusFramesMaxSize;
+  const focusWindow = calculateFocusWindow(focusedRegion, focusFramesMaxSize);
 
   // Calculate padding for the focused region (0 when region is split)
   const prevRegionEnd = focusedIndex > 0 ? regions[focusedIndex - 1].endLine : 0;
   const nextRegionStart =
     focusedIndex < regions.length - 1 ? regions[focusedIndex + 1].startLine : totalLines + 1;
+
   const [paddingTop, paddingBottom] = calculatePadding(
     focusedRegion,
     prevRegionEnd,
     nextRegionStart,
-    options,
+    focusedRegion.paddingFrameMaxSize ?? options.paddingFrameMaxSize,
+    focusFramesMaxSize,
   );
-
   // Build frame ranges by iterating through all regions
   const frames: FrameRange[] = [];
   let currentLine = 1;

From 7ed37da47655cd1ec0405ec4bb21482664ac7029 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 15 Apr 2026 23:16:12 -0400
Subject: [PATCH 06/44] Always return some focus

---
 .../demos/CodeMaxSize.tsx                     |   2 +-
 .../pipeline/enhance-code-emphasis/types.md   |  22 ++-
 .../enhanceCodeEmphasis.test.ts               | 146 +++++++++++++++++-
 .../enhanceCodeEmphasis.ts                    |  21 +--
 .../__snapshots__/highlightTypes.test.ts.snap |   6 +
 .../parseSource/calculateFrameRanges.test.ts  |  58 ++++++-
 .../parseSource/calculateFrameRanges.ts       |  30 +++-
 7 files changed, 261 insertions(+), 24 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeMaxSize.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeMaxSize.tsx
index 70d430c42..c6a1cfa53 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeMaxSize.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeMaxSize.tsx
@@ -15,7 +15,7 @@ const sourceEnhancers = [createEnhanceCodeEmphasis({ focusFramesMaxSize: 6 })];
  * A server component that renders a collapsible code block with focusFramesMaxSize.
  *
  * Uses `focusFramesMaxSize: 6` so highlighted regions longer than 6 lines
- * are split into a centered focused window with unfocused overflow.
+ * are split into a focused window from the start with unfocused overflow below.
  */
 export function CodeMaxSize({ code }: { code: CodeType }) {
   return (
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 8c568bf18..3806d729c 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
@@ -82,6 +82,12 @@ type EmphasisMeta = {
   paddingFrameMaxSize?: number;
   /** Optional per-directive focus max size override for this region */
   focusFramesMaxSize?: number;
+  /**
+   * True when the overrides were propagated from a multiline range
+   * rather than set by an explicit per-line directive.
+   * Explicit overrides take precedence over propagated ones in regions.
+   */
+  propagatedOverride?: boolean;
 };
 ```
 
@@ -98,13 +104,15 @@ type EnhanceCodeEmphasisOptions = {
    */
   paddingFrameMaxSize?: number;
   /**
-   * Maximum total number of lines in the focus area (padding-top + focused region + padding-bottom).
-   * When the region fits within this limit, padding sizes are reduced so the total focus area
-   * fits. The remainder after subtracting the region size is split: floor(remainder/2) for
-   * padding-top and ceil(remainder/2) for 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.
-   */
+ * Maximum total number of lines in the focus area (padding-top + focused region + padding-bottom).
+ * Defaults to `12` when not explicitly configured.
+ * @default 12
+When the region fits within this limit, padding sizes are reduced so the total focus area
+fits. The remainder after subtracting the region size is split: floor(remainder/2) for
+padding-top and ceil(remainder/2) for 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.
+ */
   focusFramesMaxSize?: number;
   /**
    * When `true`, throws an error if a `@highlight-text` match has to be
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
index 444a11e84..d3f4a774a 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
@@ -681,7 +681,7 @@ const c = 3;`,
       );
 
       expect(result).toMatchInlineSnapshot(`
-        "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="3"><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">1</span>;</span>
+        "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="3" data-frame-type="focus"><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">1</span>;</span>
         <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">2</span>;</span>
         <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">3</span>;</span></span>"
       `);
@@ -696,7 +696,7 @@ const b = 2;`,
 
       // Should not add any emphasis since there's no quoted text
       expect(result).toMatchInlineSnapshot(`
-        "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="2"><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">1</span>;</span>
+        "<span class="frame" data-lined="" data-frame-start-line="1" data-frame-end-line="2" data-frame-type="focus"><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">1</span>;</span>
         <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">2</span>;</span></span>"
       `);
     });
@@ -1828,4 +1828,146 @@ const e = 5;`,
       expect(result).toMatch(/data-frame-type="highlighted" data-frame-indent="2"/);
     });
   });
+
+  describe('auto-focus (no directives)', () => {
+    it('should auto-focus from line 1 with truncation when code exceeds focusFramesMaxSize', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        focusFramesMaxSize: 3,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;
+const d = 4;
+const e = 5;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // First 3 lines are auto-focused with truncation, remaining lines are normal
+      expect(result).toMatch(
+        /data-frame-start-line="1" data-frame-end-line="3" data-frame-type="focus"/,
+      );
+      expect(result).toMatch(/data-frame-end-line="3"[^>]*data-frame-truncated="visible"/);
+      expect(result).not.toMatch(/data-frame-type="focus-unfocused"/);
+    });
+
+    it('should auto-focus entire block without truncation when code fits within focusFramesMaxSize', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        focusFramesMaxSize: 10,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // All lines fit → focus frame without truncation
+      expect(result).toMatch(
+        /data-frame-start-line="1" data-frame-end-line="3" data-frame-type="focus"/,
+      );
+      expect(result).not.toContain('data-frame-truncated');
+    });
+
+    it('should auto-focus entire block when focusFramesMaxSize is not set', async () => {
+      const enhancer = createEnhanceCodeEmphasis({});
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // Entire block is auto-focused without truncation
+      expect(result).toMatch(
+        /data-frame-start-line="1" data-frame-end-line="3" data-frame-type="focus"/,
+      );
+      expect(result).not.toContain('data-frame-truncated');
+    });
+
+    it('should truncate auto-focus using the default focusFramesMaxSize when not set', async () => {
+      const enhancer = createEnhanceCodeEmphasis({});
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;
+const d = 4;
+const e = 5;
+const f = 6;
+const g = 7;
+const h = 8;
+const i = 9;
+const j = 10;
+const k = 11;
+const l = 12;
+const m = 13;
+const n = 14;
+const o = 15;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      expect(result).toMatch(
+        /data-frame-start-line="1" data-frame-end-line="12" data-frame-type="focus"/,
+      );
+      expect(result).toMatch(/data-frame-end-line="12"[^>]*data-frame-truncated="visible"/);
+      expect(result).toMatch(/data-frame-start-line="13" data-frame-end-line="15"/);
+    });
+
+    it('should use @highlight for focus instead of auto-focus when directives exist', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        focusFramesMaxSize: 3,
+        paddingFrameMaxSize: 0,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;
+const d = 4; // @highlight
+const e = 5;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // @highlight on line 4 should be the focused region, not auto-focus from line 1
+      expect(result).toMatch(/data-frame-type="highlighted"/);
+      expect(result).not.toMatch(/data-frame-start-line="1"[^>]*data-frame-type="focus"/);
+    });
+
+    it('should auto-focus with no comments at all', async () => {
+      const enhancer = createEnhanceCodeEmphasis({
+        focusFramesMaxSize: 2,
+      });
+
+      const result = await testEmphasis(
+        `const a = 1;
+const b = 2;
+const c = 3;
+const d = 4;`,
+        parseSource,
+        'test.tsx',
+        enhancer,
+      );
+
+      // No comments → auto-focus first 2 lines, rest are normal frames
+      expect(result).toMatch(
+        /data-frame-start-line="1" data-frame-end-line="2" data-frame-type="focus"/,
+      );
+      expect(result).toMatch(/data-frame-end-line="2"[^>]*data-frame-truncated="visible"/);
+      expect(result).not.toMatch(/data-frame-type="focus-unfocused"/);
+    });
+  });
 });
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
index 7f4b8b625..7d0b93d89 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
@@ -1391,21 +1391,23 @@ export function createEnhanceCodeEmphasis(
   options: EnhanceCodeEmphasisOptions = {},
 ): SourceEnhancer {
   return (root: HastRoot, comments: SourceComments | undefined): HastRoot => {
-    if (!comments || Object.keys(comments).length === 0) {
-      return root;
-    }
-
     // Step 1: Parse directives from comments (no tree traversal)
-    const directives = parseEmphasisDirectives(comments);
+    const directives =
+      comments && Object.keys(comments).length > 0 ? parseEmphasisDirectives(comments) : [];
 
     const effectiveOptions = options;
-
-    if (directives.length === 0) {
-      return root;
-    }
+    const hasDirectives = directives.length > 0;
 
     // Step 2 (Traversal 1): Build line element map
     const lineElements = buildLineElementMap(root);
+    const totalLines = (root.data as { totalLines?: number })?.totalLines ?? lineElements.size;
+
+    if (!hasDirectives) {
+      // Auto-focus path: no emphasis, just frame restructuring
+      const frameRanges = calculateFrameRanges(new Map(), totalLines, effectiveOptions);
+      restructureFrames(root, frameRanges, new Map());
+      return root;
+    }
 
     // Step 3: Calculate which lines are emphasized (no tree traversal)
     const emphasizedLines = calculateEmphasizedLines(directives, lineElements);
@@ -1425,7 +1427,6 @@ export function createEnhanceCodeEmphasis(
     const regionIndentLevels = calculateRegionIndentLevels(highlightedElements, emphasizedLines);
 
     // Step 6: Calculate frame ranges (pure math, no tree traversal)
-    const totalLines = (root.data as { totalLines?: number })?.totalLines ?? lineElements.size;
     const frameRanges = calculateFrameRanges(emphasizedLines, totalLines, effectiveOptions);
 
     // Step 7: Restructure frames (flat iteration, not deep recursive traversal)
diff --git a/packages/docs-infra/src/pipeline/loadServerTypes/__snapshots__/highlightTypes.test.ts.snap b/packages/docs-infra/src/pipeline/loadServerTypes/__snapshots__/highlightTypes.test.ts.snap
index d9a477187..4486dbca1 100644
--- a/packages/docs-infra/src/pipeline/loadServerTypes/__snapshots__/highlightTypes.test.ts.snap
+++ b/packages/docs-infra/src/pipeline/loadServerTypes/__snapshots__/highlightTypes.test.ts.snap
@@ -97,6 +97,7 @@ exports[`highlightTypes > snapshot tests - precomputed output verification > sho
           "className": "frame",
           "dataFrameEndLine": 1,
           "dataFrameStartLine": 1,
+          "dataFrameType": "focus",
           "dataLined": "",
         },
         "tagName": "span",
@@ -256,6 +257,7 @@ exports[`highlightTypes > snapshot tests - precomputed output verification > sho
           "className": "frame",
           "dataFrameEndLine": 3,
           "dataFrameStartLine": 1,
+          "dataFrameType": "focus",
           "dataLined": "",
         },
         "tagName": "span",
@@ -718,6 +720,7 @@ exports[`highlightTypes > snapshot tests - precomputed output verification > sho
         "className": "frame",
         "dataFrameEndLine": 4,
         "dataFrameStartLine": 1,
+        "dataFrameType": "focus",
         "dataLined": "",
       },
       "tagName": "span",
@@ -865,6 +868,7 @@ exports[`highlightTypes > snapshot tests - precomputed output verification > sho
         "className": "frame",
         "dataFrameEndLine": 3,
         "dataFrameStartLine": 1,
+        "dataFrameType": "focus",
         "dataLined": "",
       },
       "tagName": "span",
@@ -1016,6 +1020,7 @@ exports[`highlightTypes > snapshot tests - precomputed output verification > sho
         "className": "frame",
         "dataFrameEndLine": 3,
         "dataFrameStartLine": 1,
+        "dataFrameType": "focus",
         "dataLined": "",
       },
       "tagName": "span",
@@ -1223,6 +1228,7 @@ exports[`highlightTypes > snapshot tests - precomputed output verification > sho
         "className": "frame",
         "dataFrameEndLine": 1,
         "dataFrameStartLine": 1,
+        "dataFrameType": "focus",
         "dataLined": "",
       },
       "tagName": "span",
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
index 490581c0d..458925722 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import type { EmphasisMeta, FrameRange } from './calculateFrameRanges';
-import { calculateFrameRanges } from './calculateFrameRanges';
+import { calculateFrameRanges, DEFAULT_FOCUS_FRAMES_MAX_SIZE } from './calculateFrameRanges';
 
 describe('calculateFrameRanges', () => {
   describe('basic reframing', () => {
@@ -527,6 +527,58 @@ describe('calculateFrameRanges', () => {
     });
   });
 
+  describe('auto-focus (no directives)', () => {
+    it('should auto-focus from line 1 when focusFramesMaxSize is set and code exceeds it', () => {
+      const result = calculateFrameRanges(new Map(), 10, {
+        focusFramesMaxSize: 4,
+      });
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 4, type: 'focus', regionIndex: 0, truncated: 'visible' },
+        { startLine: 5, endLine: 10, type: 'normal' },
+      ]);
+    });
+
+    it('should create focus frame without truncation when code fits within focusFramesMaxSize', () => {
+      const result = calculateFrameRanges(new Map(), 5, {
+        focusFramesMaxSize: 8,
+      });
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 5, type: 'focus', regionIndex: 0 },
+      ]);
+    });
+
+    it('should create focus frame without truncation when code equals focusFramesMaxSize', () => {
+      const result = calculateFrameRanges(new Map(), 8, {
+        focusFramesMaxSize: 8,
+      });
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 8, type: 'focus', regionIndex: 0 },
+      ]);
+    });
+
+    it('should use the default focusFramesMaxSize when it is not set', () => {
+      const result = calculateFrameRanges(new Map(), DEFAULT_FOCUS_FRAMES_MAX_SIZE + 3, {});
+
+      expect(result).toEqual<FrameRange[]>([
+        {
+          startLine: 1,
+          endLine: DEFAULT_FOCUS_FRAMES_MAX_SIZE,
+          type: 'focus',
+          regionIndex: 0,
+          truncated: 'visible',
+        },
+        {
+          startLine: DEFAULT_FOCUS_FRAMES_MAX_SIZE + 1,
+          endLine: DEFAULT_FOCUS_FRAMES_MAX_SIZE + 3,
+          type: 'normal',
+        },
+      ]);
+    });
+  });
+
   describe('input validation', () => {
     const emphasizedLines = new Map<number, EmphasisMeta>([
       [3, { position: 'single', lineHighlight: true }],
@@ -667,7 +719,9 @@ describe('calculateFrameRanges', () => {
 
       const result = calculateFrameRanges(emphasizedLines, 10);
 
-      expect(result).toEqual<FrameRange[]>([{ startLine: 1, endLine: 10, type: 'normal' }]);
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 10, type: 'focus', regionIndex: 0 },
+      ]);
     });
 
     it('should handle text-highlighted lines as highlighted regions', () => {
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
index 8e8601e13..2ff4946a8 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
@@ -86,6 +86,8 @@ export interface EnhanceCodeEmphasisOptions {
   paddingFrameMaxSize?: number;
   /**
    * Maximum total number of lines in the focus area (padding-top + focused region + padding-bottom).
+   * Defaults to `12` when not explicitly configured.
+   * @default 12
    * When the region fits within this limit, padding sizes are reduced so the total focus area
    * fits. The remainder after subtracting the region size is split: floor(remainder/2) for
    * padding-top and ceil(remainder/2) for padding-bottom.
@@ -102,6 +104,9 @@ export interface EnhanceCodeEmphasisOptions {
   strictHighlightText?: boolean;
 }
 
+/** Default max number of lines kept in focus when not explicitly configured. */
+export const DEFAULT_FOCUS_FRAMES_MAX_SIZE = 12;
+
 /**
  * Groups consecutive emphasized line numbers into highlight regions.
  *
@@ -336,6 +341,8 @@ export function calculateFrameRanges(
   totalLines: number,
   options: EnhanceCodeEmphasisOptions = {},
 ): FrameRange[] {
+  const effectiveFocusFramesMaxSize = options.focusFramesMaxSize ?? DEFAULT_FOCUS_FRAMES_MAX_SIZE;
+
   if (
     options.focusFramesMaxSize !== undefined &&
     (!Number.isFinite(options.focusFramesMaxSize) || options.focusFramesMaxSize < 1)
@@ -360,14 +367,33 @@ export function calculateFrameRanges(
   const regions = groupHighlightRegions(emphasizedLines);
 
   if (regions.length === 0) {
-    return [{ startLine: 1, endLine: totalLines, type: 'normal' }];
+    // Auto-focus: when no emphasis directives exist, focus from line 1.
+    // If focusFramesMaxSize is set and the code exceeds it, truncate.
+    const autoFocusMax = effectiveFocusFramesMaxSize;
+    if (autoFocusMax !== undefined && totalLines > autoFocusMax) {
+      return [
+        {
+          startLine: 1,
+          endLine: autoFocusMax,
+          type: 'focus',
+          regionIndex: 0,
+          truncated: 'visible',
+        },
+        {
+          startLine: autoFocusMax + 1,
+          endLine: totalLines,
+          type: 'normal',
+        },
+      ];
+    }
+    return [{ startLine: 1, endLine: totalLines, type: 'focus', regionIndex: 0 }];
   }
 
   const focusedIndex = determineFocusedRegionIndex(regions);
 
   // Calculate focus window split (for oversized regions)
   const focusedRegion = regions[focusedIndex];
-  const focusFramesMaxSize = focusedRegion.focusFramesMaxSize ?? options.focusFramesMaxSize;
+  const focusFramesMaxSize = focusedRegion.focusFramesMaxSize ?? effectiveFocusFramesMaxSize;
   const focusWindow = calculateFocusWindow(focusedRegion, focusFramesMaxSize);
 
   // Calculate padding for the focused region (0 when region is split)

From 1e22879b90e7c5f6e1bb889de31bfc1c614cdce0 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 15 Apr 2026 23:22:10 -0400
Subject: [PATCH 07/44] Update focusFramesMaxSize to 18

---
 docs/next.config.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/next.config.mjs b/docs/next.config.mjs
index d660c0c37..26a0318b8 100644
--- a/docs/next.config.mjs
+++ b/docs/next.config.mjs
@@ -56,7 +56,7 @@ export default withDeploymentConfig(
         index: ['./app/**/demos/*/demo-*/index.ts'],
         client: ['./app/**/demos/*/demo-*/client.ts'],
       },
-      emphasisOptions: { paddingFrameMaxSize: 1 },
+      emphasisOptions: { paddingFrameMaxSize: 2, focusFramesMaxSize: 18 },
     })(withMDX(nextConfig)),
   ),
 );

From 4bb784d9bad0e22963364f8cbb846818d4ec0706 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 12:47:10 -0400
Subject: [PATCH 08/44] pnpm dedupe

---
 pnpm-lock.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 701ec6b85..98cd7c38d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -915,7 +915,7 @@ importers:
         version: 17.0.35
       '@typescript-eslint/utils':
         specifier: ^8.57.1
-        version: 8.57.1(eslint@10.0.3(jiti@2.6.1))(typescript@5.9.3)
+        version: 8.57.1(eslint@10.0.3(jiti@2.6.1))(typescript@6.0.2)
       estree-util-to-js:
         specifier: 2.0.0
         version: 2.0.0

From 717d5b8ddae1c0ca3c766d285c421eab6c1619b0 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 13:51:05 -0400
Subject: [PATCH 09/44] Use `<mark>` for `@highlight-text`

---
 .../demos/CodeContent.module.css              |  12 +-
 .../demos/DemoContent.module.css              |  12 +-
 .../enhance-code-emphasis/demos/Code.tsx      |   2 +
 .../demos/CollapsibleDemoContent.module.css   |  12 +-
 .../collapsible-code/CollapsibleCode.tsx      |   2 +
 .../pipeline/enhance-code-emphasis/types.md   |   2 +
 .../enhanceCodeEmphasis.test.ts               | 121 ++++++++++++++----
 .../enhanceCodeEmphasis.ts                    | 116 +++++++++++++----
 .../parseSource/calculateFrameRanges.ts       |   2 +
 packages/docs-infra/src/useCode/Pre.tsx       |   5 +
 10 files changed, 231 insertions(+), 55 deletions(-)

diff --git a/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css b/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css
index 8cbcc8396..3edfe6b9b 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css
+++ b/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css
@@ -102,11 +102,19 @@
   padding: 0 6px;
 }
 
-.codeBlock :global(:not(.line)[data-hl]) {
-  background: #e1d9ff;
+.codeBlock :global(mark) {
+  background: #ebe4ff;
   border-radius: 4px;
 }
 
+.codeBlock :global(mark[data-hl]) {
+  background: #e1d9ff;
+}
+
+.codeBlock :global(mark[data-hl='strong']) {
+  background: #d4c8ff;
+}
+
 .codeBlock :global(.line[data-hl='strong']) {
   background: #e1d9ff;
   margin: 0 -6px;
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.module.css b/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.module.css
index 55c47cdf8..4eea4dc41 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.module.css
+++ b/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.module.css
@@ -109,11 +109,19 @@
   padding: 0 6px;
 }
 
-.codeBlock :global(:not(.line)[data-hl]) {
-  background: #e1d9ff;
+.codeBlock :global(mark) {
+  background: #ebe4ff;
   border-radius: 4px;
 }
 
+.codeBlock :global(mark[data-hl]) {
+  background: #e1d9ff;
+}
+
+.codeBlock :global(mark[data-hl='strong']) {
+  background: #d4c8ff;
+}
+
 .codeBlock :global(.line[data-hl='strong']) {
   background: #e1d9ff;
   margin: 0 -6px;
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/Code.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/Code.tsx
index 1adf091ab..19456e219 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/Code.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/Code.tsx
@@ -20,11 +20,13 @@ const sourceEnhancers = [createEnhanceCodeEmphasis({ paddingFrameMaxSize: 3 })];
  */
 export function Code({ code }: { code: CodeType }) {
   return (
+    // @focus-start
     <CodeHighlighter
       code={code}
       Content={CollapsibleContent}
       sourceParser={sourceParser}
       sourceEnhancers={sourceEnhancers}
     />
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
index 2be02f7d3..69be46d51 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
@@ -163,11 +163,19 @@ pre.codeBlock {
   padding: 0 6px;
 }
 
-.codeBlock :global(:not(.line)[data-hl]) {
-  background: #e1d9ff;
+.codeBlock :global(mark) {
+  background: #ebe4ff;
   border-radius: 4px;
 }
 
+.codeBlock :global(mark[data-hl]) {
+  background: #e1d9ff;
+}
+
+.codeBlock :global(mark[data-hl='strong']) {
+  background: #d4c8ff;
+}
+
 .codeBlock :global(.line[data-hl='strong']) {
   background: #e1d9ff;
   margin: 0 -6px;
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-code/CollapsibleCode.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-code/CollapsibleCode.tsx
index 7d39817e7..bef4902fe 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-code/CollapsibleCode.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-code/CollapsibleCode.tsx
@@ -42,6 +42,7 @@ export function UserProfile({ id }: { id: string }) {
 }`;
 
 export async function CollapsibleCode() {
+  // @focus-start
   const { code: strippedSource, comments } = await parseImportsAndComments(source, '/demo.tsx', {
     removeCommentsWithPrefix: [EMPHASIS_COMMENT_PREFIX],
     notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX],
@@ -56,4 +57,5 @@ export async function CollapsibleCode() {
   };
 
   return <Code code={code} />;
+  // @focus-end
 }
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 3806d729c..03a8c0e27 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
@@ -78,6 +78,8 @@ type EmphasisMeta = {
   focus?: boolean;
   /** Whether the line itself should receive data-hl. True for highlight directives and false for focus-only directives. */
   lineHighlight: boolean;
+  /** How many containing highlight ranges wrap this line (used for mark data-hl propagation) */
+  containingRangeDepth?: number;
   /** Optional per-directive padding override for this region */
   paddingFrameMaxSize?: number;
   /** Optional per-directive focus max size override for this region */
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
index 05e9c65d1..5f5ad5c39 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
@@ -272,11 +272,11 @@ 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="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="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>><span data-hl="">Heading 1</span>&#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">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>
+        <span class="line" data-ln="5">    &#x3C;/<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="6">  );</span>
         <span class="line" data-ln="7">}</span></span>"
       `);
@@ -297,11 +297,11 @@ 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=""><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" 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="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> <span class="pl-e">className</span><span class="pl-k">=</span><span class="pl-s"><span class="pl-pds">"</span><span data-hl="">primary</span><span class="pl-pds">"</span></span>><span data-hl="">Heading 1</span>&#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">div</span>></span>
+        <span class="line" data-ln="4">      &#x3C;<span class="pl-ent">h1</span> <span class="pl-e">className</span><span class="pl-k">=</span><span class="pl-s"><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>
+        <span class="line" data-ln="5">    &#x3C;/<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="6">  );</span>
         <span class="line" data-ln="7">}</span></span>"
       `);
@@ -317,8 +317,8 @@ const e = 5; // @highlight`,
       // "Heading" is a substring of "Heading 1"
       // The first token "Heading" gets wrapped; the second "Heading 1" should not
       // nest inside the already-highlighted span. Only the first match wins.
-      // Verify no nested data-hl spans exist
-      expect(result).not.toContain('data-hl=""><span data-hl="">');
+      // Verify no nested mark elements exist
+      expect(result).not.toContain('<mark><mark>');
     });
 
     it('should highlight JSX prop expressions', async () => {
@@ -328,7 +328,7 @@ 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">&#x3C;<span class="pl-c1">AlertDialog.Trigger</span> <span data-hl=""><span class="pl-e">handle</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">demoAlertDialog</span><span class="pl-pse">}</span></span>>Open&#x3C;/<span class="pl-c1">AlertDialog.Trigger</span>></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-type="focus" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1">AlertDialog.Trigger</span> <mark><span class="pl-e">handle</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">demoAlertDialog</span><span class="pl-pse">}</span></mark>>Open&#x3C;/<span class="pl-c1">AlertDialog.Trigger</span>></span></span>"`,
       );
     });
 
@@ -340,7 +340,7 @@ 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">&#x3C;<span class="pl-c1">Button</span> <span class="pl-e">render</span><span class="pl-k">=</span><span class="pl-pse">{</span>&#x3C;<span class="pl-ent">div</span> /><span class="pl-pse">}</span> <span data-hl=""><span class="pl-e">nativeButton</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-c1">false</span><span class="pl-pse">}</span></span>></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-type="focus" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1">Button</span> <span class="pl-e">render</span><span class="pl-k">=</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">false</span><span class="pl-pse">}</span></mark>></span></span>"`,
       );
     });
 
@@ -351,7 +351,7 @@ const e = 5; // @highlight`,
         'test.css',
       );
 
-      expect(result).toContain('<span data-hl="">, 40px</span>');
+      expect(result).toContain('<mark>, 40px</mark>');
     });
 
     it('should handle @highlight and @highlight-text on adjacent CSS lines', async () => {
@@ -369,7 +369,7 @@ const e = 5; // @highlight`,
       expect(result).toContain('data-frame-type="highlighted"');
       // The text highlight wraps ", 40px" which contains syntax-highlighted children
       expect(result).toContain(
-        '<span data-hl="">, <span class="pl-c1">40</span><span class="pl-k">px</span></span>',
+        '<mark>, <span class="pl-c1">40</span><span class="pl-k">px</span></mark>',
       );
     });
 
@@ -381,8 +381,8 @@ const e = 5; // @highlight`,
 
       // "={false}" spans a pl-k (=), a pl-pse ({), a pl-c1 (false), and a pl-pse (}).
       // The highlight should NOT include the preceding "nativeButton" text from the pl-e element.
-      expect(result).not.toContain('<span data-hl="">nativeButton');
-      expect(result).toContain('data-hl="">');
+      expect(result).not.toContain('<mark>nativeButton');
+      expect(result).toContain('<mark>');
     });
 
     it('should use data-hl-part when match straddles an element boundary', async () => {
@@ -468,7 +468,7 @@ 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">&#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">a</span><span class="pl-pse">}</span> /> &#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">b</span><span class="pl-pse">}</span> /> <span class="pl-c">// @highlight-text "<span data-hl="">value</span>"</span></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-type="focus" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1">Input</span> <mark class="pl-e">value</mark><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-smi">a</span><span class="pl-pse">}</span> /> &#x3C;<span class="pl-c1">Input</span> <mark class="pl-e">value</mark><span class="pl-k">=</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>"`,
       );
     });
 
@@ -480,12 +480,12 @@ const e = 5; // @highlight`,
 
       // Both "value" inside the string literal should be highlighted,
       // plus the one inside the comment text
-      const matches = result.match(/data-hl=""/g);
+      const matches = result.match(/<mark>/g);
       expect(matches?.length).toBeGreaterThanOrEqual(2);
 
       // Verify both occurrences inside the pl-s string element are wrapped
       expect(result).toContain('<span class="pl-s"><span class="pl-pds">"</span>');
-      expect(result).toContain('<span data-hl="">value</span> <span data-hl="">value</span>');
+      expect(result).toContain('<mark>value</mark> <mark>value</mark>');
     });
 
     it('should highlight both leaf and cross-element occurrences of the same text', async () => {
@@ -495,7 +495,7 @@ 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">&#x3C;<span class="pl-c1">Input</span> <span data-hl=""><span class="pl-e">value</span></span><span class="pl-k">=</span><span class="pl-pse">{</span><span data-hl=""><span class="pl-smi">value</span></span><span class="pl-pse">}</span> /></span></span>"`,
+        `"<span class="frame" data-lined="" data-frame-type="focus" data-frame-indent="0"><span class="line" data-ln="1">&#x3C;<span class="pl-c1">Input</span> <mark class="pl-e">value</mark><span class="pl-k">=</span><span class="pl-pse">{</span><mark class="pl-smi">value</mark><span class="pl-pse">}</span> /></span></span>"`,
       );
     });
   });
@@ -510,7 +510,7 @@ const e = 5; // @highlight`,
         createEnhanceCodeEmphasis({ strictHighlightText: true }),
       );
 
-      expect(result).toContain('data-hl=""');
+      expect(result).toContain('<mark>');
       expect(result).not.toContain('data-hl-part');
     });
 
@@ -623,7 +623,8 @@ const another = 99; // @highlight`,
       );
 
       // The @highlight-text line should highlight "Heading 1" text inline
-      expect(result).toContain('<span data-hl="">Heading 1</span>');
+      // with data-hl="" since it's inside 1 containing highlight range
+      expect(result).toContain('<mark data-hl="">Heading 1</mark>');
       // The line itself should NOT have line-level data-hl (simple highlight, frame handles it)
       // but the inline text highlight span is still present
       expect(result).not.toMatch(/data-ln="4"[^>]*data-hl=""/);
@@ -634,6 +635,61 @@ const another = 99; // @highlight`,
       // The whole region should be in a highlighted frame
       expect(result).toContain('data-frame-type="highlighted"');
     });
+
+    it('should produce bare <mark> without data-hl on a non-highlighted line', async () => {
+      const result = await testEmphasis(
+        `export default function Component() {
+  return (
+    <div>
+      <h1>Title</h1> {/* @highlight-text "Title" */}
+    </div>
+  );
+}`,
+        parseSource,
+      );
+
+      // Standalone @highlight-text: mark has no data-hl
+      expect(result).toContain('<mark>Title</mark>');
+      expect(result).not.toContain('<mark data-hl');
+    });
+
+    it('should add data-hl="" to <mark> inside a single highlight range', async () => {
+      const result = await testEmphasis(
+        `export default function Component() {
+  return (
+    // @highlight-start
+    <div>
+      <h1>Title</h1> {/* @highlight-text "Title" */}
+    </div>
+    // @highlight-end
+  );
+}`,
+        parseSource,
+      );
+
+      // @highlight-text inside 1 containing highlight range: mark gets data-hl=""
+      expect(result).toContain('<mark data-hl="">Title</mark>');
+    });
+
+    it('should add data-hl="strong" to <mark> inside nested highlight ranges', async () => {
+      const result = await testEmphasis(
+        `export default function Component() {
+  // @highlight-start
+  return (
+    // @highlight-start
+    <div>
+      <h1>Title</h1> {/* @highlight-text "Title" */}
+    </div>
+    // @highlight-end
+  );
+  // @highlight-end
+}`,
+        parseSource,
+      );
+
+      // @highlight-text inside 2 containing highlight ranges: mark gets data-hl="strong"
+      expect(result).toContain('<mark data-hl="strong">Title</mark>');
+    });
   });
 
   describe('edge cases', () => {
@@ -873,6 +929,25 @@ const z = 3;`,
       expect(result).not.toMatch(/data-ln="6"[^>]*data-hl/);
     });
 
+    it('should preserve frame description when comments are preserved', async () => {
+      const result = await testEmphasisWithPreservedComments(
+        `export default function Component() {
+  return (
+    // @highlight-start "We add a heading with an h1"
+    <div>
+      <h1>Heading 1</h1>
+    </div>
+    // @highlight-end
+  );
+}`,
+        parseSource,
+      );
+
+      // The highlighted frame should have the description
+      expect(result).toContain('data-frame-description="We add a heading with an h1"');
+      expect(result).toContain('data-frame-type="highlighted"');
+    });
+
     it('should highlight text inside the comment and code with @highlight-text', async () => {
       const result = await testEmphasisWithPreservedComments(
         `export default function Component() {
@@ -886,11 +961,11 @@ const z = 3;`,
       );
 
       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="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="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> <span class="pl-e">className</span><span class="pl-k">=</span><span class="pl-s"><span class="pl-pds">"</span><span data-hl="">primary</span><span class="pl-pds">"</span></span>><span data-hl="">Heading 1</span>&#x3C;/<span class="pl-ent">h1</span>> <span class="pl-pse">{</span><span class="pl-c">/* @highlight-text "<span data-hl="">primary</span>" "<span data-hl="">Heading 1</span>" */</span><span class="pl-pse">}</span></span>
-        </span><span class="frame" data-lined=""><span class="line" data-ln="5">    &#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">className</span><span class="pl-k">=</span><span class="pl-s"><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>
+        <span class="line" data-ln="5">    &#x3C;/<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="6">  );</span>
         <span class="line" data-ln="7">}</span></span>"
       `);
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
index 7d0b93d89..d77a7cc46 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
@@ -416,12 +416,14 @@ function parseHighlightDirective(
     if (highlightTexts.length > 0) {
       // Text-only markers should not influence region padding, so
       // @padding/@min modifiers are intentionally omitted here.
+      // lineHighlight is false because @highlight-text only highlights
+      // inline text, it does NOT highlight the line itself.
       directives.push({
         line,
         type: 'text',
         highlightTexts,
         focus,
-        lineHighlight: true,
+        lineHighlight: false,
         paddingFrameMaxSize: undefined,
         focusFramesMaxSize: undefined,
       });
@@ -738,6 +740,11 @@ function calculateEmphasizedLines(
                 existing.focusFramesMaxSize !== undefined
                   ? existing.propagatedOverride
                   : true,
+              // Track how many containing highlight ranges wrap this line
+              // so that inline <mark> elements can receive the right data-hl tier.
+              containingRangeDepth: startDirective.lineHighlight
+                ? (existing.containingRangeDepth ?? 0) + 1
+                : existing.containingRangeDepth,
             }
           : {
               strong,
@@ -758,9 +765,35 @@ function calculateEmphasizedLines(
   return emphasizedLines;
 }
 
+/**
+ * Converts a group of nodes into a `<mark>` element.
+ *
+ * When the group contains exactly one `<span>` child, we replace that
+ * element in-place — changing its `tagName` to `mark` and merging the
+ * highlight properties — instead of wrapping it in an extra `<mark>`.
+ * This keeps the output flat (e.g. `<mark class="pl-e">config</mark>`
+ * instead of `<mark><span class="pl-e">config</span></mark>`).
+ */
+function groupToMark(nodes: ElementContent[], props: Record<string, string>): ElementContent {
+  if (nodes.length === 1 && nodes[0].type === 'element' && nodes[0].tagName === 'span') {
+    const child = nodes[0];
+    return {
+      ...child,
+      tagName: 'mark',
+      properties: { ...child.properties, ...props },
+    };
+  }
+  return {
+    type: 'element',
+    tagName: 'mark',
+    properties: props,
+    children: nodes,
+  };
+}
+
 /**
  * Like {@link getHastTextContent} but replaces any text inside a
- * `data-hl` element with sentinel null characters so that those
+ * `<mark>` element with sentinel null characters so that those
  * regions are invisible to the text search in `wrapTextInHighlightSpan`.
  * This prevents nesting highlights when successive tokens overlap.
  */
@@ -769,7 +802,7 @@ function getSearchableText(node: ElementContent): string {
     return node.value;
   }
   if (node.type === 'element') {
-    if (node.properties?.dataHl !== undefined) {
+    if (node.tagName === 'mark') {
       return '\0'.repeat(getHastTextContent(node).length);
     }
     if (node.children) {
@@ -779,6 +812,24 @@ function getSearchableText(node: ElementContent): string {
   return '';
 }
 
+/**
+ * Recursively walks children and adds `data-hl` to any `<mark>` elements
+ * so they inherit the highlight level of their parent line.
+ */
+function propagateHlToMarks(children: ElementContent[], hlValue: string): void {
+  for (const child of children) {
+    if (child.type === 'element') {
+      if (child.tagName === 'mark') {
+        child.properties = child.properties || {};
+        child.properties.dataHl = hlValue;
+      }
+      if (child.children) {
+        propagateHlToMarks(child.children, hlValue);
+      }
+    }
+  }
+}
+
 /**
  * Injects a `data-hl` highlight span for a character range inside an
  * element's children, without splitting the element itself.
@@ -920,16 +971,11 @@ function injectHighlightInChildren(
     }
 
     if (item.kind === 'group') {
-      const props: Record<string, string> = { dataHl: '' };
+      const props: Record<string, string> = {};
       if (effectivePart !== undefined) {
         props.dataHlPart = effectivePart;
       }
-      highlighted.push({
-        type: 'element',
-        tagName: 'span',
-        properties: props,
-        children: item.nodes,
-      });
+      highlighted.push(groupToMark(item.nodes, props));
     } else {
       highlighted.push({
         ...item.element,
@@ -950,19 +996,19 @@ function injectHighlightInChildren(
 
 /**
  * Wraps all occurrences of a specific text within a line's children in
- * highlight spans with `data-hl`.
+ * `<mark>` elements.
  *
  * Semantic element nodes (syntax-highlighting spans) are never split or
- * cloned. When a match partially overlaps an element, the highlight span
- * is injected *inside* the element via {@link injectHighlightInChildren}.
- * When a match covers entire elements, a single wrapper `data-hl` span
+ * cloned. When a match partially overlaps an element, the highlight is
+ * injected *inside* the element via {@link injectHighlightInChildren}.
+ * When a match covers entire elements, a single wrapper `<mark>`
  * groups them all.
  *
  * If a match is fragmented (spans a partial element boundary), each
  * fragment gets a `data-hl-part` attribute (`"start"`, `"middle"`, or
  * `"end"`) so the segments can be styled together (e.g. border-radius).
  *
- * Already-highlighted nodes (`dataHl`) are excluded from matching so that
+ * Already-highlighted nodes (`<mark>`) are excluded from matching so that
  * successive calls for different tokens don't nest or double-highlight.
  */
 function wrapTextInHighlightSpan(
@@ -1103,16 +1149,11 @@ function wrapTextInHighlightSpan(
     }
 
     if (item.kind === 'group') {
-      const props: Record<string, string> = { dataHl: '' };
+      const props: Record<string, string> = {};
       if (part !== undefined) {
         props.dataHlPart = part;
       }
-      highlighted.push({
-        type: 'element',
-        tagName: 'span',
-        properties: props,
-        children: item.nodes,
-      });
+      highlighted.push(groupToMark(item.nodes, props));
     } else {
       const injectedChildren = injectHighlightInChildren(
         item.element.children,
@@ -1186,7 +1227,7 @@ function applyEmphasisAndCollectHighlightedElements(
             meta.lineHighlight && (meta.focus === true || meta.strong === true);
 
           if (meta.highlightTexts) {
-            // For text highlight, wrap the specific text(s) in a span with data-hl
+            // For text highlight, wrap the specific text(s) in a <mark> element
             let children = child.children;
             for (const text of meta.highlightTexts) {
               children = wrapTextInHighlightSpan(
@@ -1197,11 +1238,22 @@ function applyEmphasisAndCollectHighlightedElements(
             }
             child.children = children;
 
+            // Propagate data-hl to inline <mark> elements based on how many
+            // containing highlight ranges wrap this line. This gives marks
+            // 3 visual tiers: bare (standalone), data-hl="" (inside 1 range),
+            // and data-hl="strong" (inside 2+ nested ranges).
+            if (meta.containingRangeDepth && meta.containingRangeDepth > 0) {
+              const markHlValue = meta.containingRangeDepth >= 2 ? 'strong' : '';
+              propagateHlToMarks(child.children, markHlValue);
+            }
+
             // Only mark the line with data-hl when the highlight is nested
             // (inside a focus frame or strong from nesting).
-            // Standalone @highlight-text lines should not get line-level highlights.
+            // Standalone @highlight-text lines should not get line-level marks
+            // because the frame itself handles the visual emphasis.
             if (shouldApplyLineHl) {
-              child.properties.dataHl = meta.strong ? 'strong' : '';
+              const hlValue = meta.strong ? 'strong' : '';
+              child.properties.dataHl = hlValue;
 
               if (meta.description) {
                 child.properties.dataHlDescription = meta.description;
@@ -1427,7 +1479,19 @@ export function createEnhanceCodeEmphasis(
     const regionIndentLevels = calculateRegionIndentLevels(highlightedElements, emphasizedLines);
 
     // Step 6: Calculate frame ranges (pure math, no tree traversal)
-    const frameRanges = calculateFrameRanges(emphasizedLines, totalLines, effectiveOptions);
+    // Filter out text-only lines that don't need their own frames.
+    // They still receive inline <mark> wrapping from applyEmphasis (step 4).
+    const frameEmphasizedLines = new Map<number, EmphasisMeta>();
+    for (const [line, meta] of emphasizedLines) {
+      if (meta.lineHighlight || meta.focus || !meta.highlightTexts) {
+        frameEmphasizedLines.set(line, meta);
+      }
+    }
+    const frameRanges = calculateFrameRanges(
+      frameEmphasizedLines.size > 0 ? frameEmphasizedLines : new Map(),
+      totalLines,
+      effectiveOptions,
+    );
 
     // Step 7: Restructure frames (flat iteration, not deep recursive traversal)
     restructureFrames(root, frameRanges, regionIndentLevels);
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
index 2ff4946a8..1d6acdf75 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
@@ -14,6 +14,8 @@ export interface EmphasisMeta {
   focus?: boolean;
   /** Whether the line itself should receive data-hl. True for highlight directives and false for focus-only directives. */
   lineHighlight: boolean;
+  /** How many containing highlight ranges wrap this line (used for mark data-hl propagation) */
+  containingRangeDepth?: number;
   /** Optional per-directive padding override for this region */
   paddingFrameMaxSize?: number;
   /** Optional per-directive focus max size override for this region */
diff --git a/packages/docs-infra/src/useCode/Pre.tsx b/packages/docs-infra/src/useCode/Pre.tsx
index 9d2446e23..cd8592547 100644
--- a/packages/docs-infra/src/useCode/Pre.tsx
+++ b/packages/docs-infra/src/useCode/Pre.tsx
@@ -206,6 +206,11 @@ export function Pre({
                 ? String(child.properties.dataFrameTruncated)
                 : undefined
             }
+            data-frame-description={
+              child.properties.dataFrameDescription
+                ? String(child.properties.dataFrameDescription)
+                : undefined
+            }
             ref={observeFrame}
           >
             {renderCode(

From fd28123be4fc085efdf5eab9c964fec2f739c632 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 13:59:16 -0400
Subject: [PATCH 10/44] Update docs

---
 .../pipeline/enhance-code-emphasis/page.mdx   | 33 +++++++++++++------
 1 file changed, 23 insertions(+), 10 deletions(-)

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 d836b73b1..717bfa51f 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
@@ -121,7 +121,7 @@ export default function Component() {
 }
 ```
 
-This wraps the specified text in a `<span data-hl="">` element, allowing you to highlight a specific word or phrase within a line rather than the entire line.
+This wraps the specified text in a `<mark>` element, allowing you to highlight a specific word or phrase within a line rather than the entire line.
 
 ### Multiple Text Highlighting
 
@@ -137,7 +137,7 @@ export default function Component() {
 }
 ```
 
-Each quoted text is independently wrapped in a `<span data-hl="">` element.
+Each quoted text is independently wrapped in a `<mark>` element.
 
 ---
 
@@ -535,7 +535,7 @@ import { DemoMaxSizeCode } from './demos/max-size-code';
 2. **Directive Parsing**: The enhancer scans comments for `@highlight`, `@highlight-start`, `@highlight-end`, `@highlight-text`, `@focus`, `@focus-start`, `@focus-end`, and optional `@padding N` / `@min N` modifiers
 3. **Line Calculation**: Single-line directives mark their own line; multi-line directives mark all lines from the first line after `@highlight-start` to the last line before `@highlight-end`
 4. **Nested Detection**: Lines inside multiple ranges are automatically marked as strong emphasis
-5. **HAST Modification**: The enhancer traverses the HAST tree and adds `dataHl: ''` (or `dataHl: 'strong'` for nested lines or descriptions ending with `!`) to line elements
+5. **HAST Modification**: The enhancer traverses the HAST tree and adds `dataHl: ''` (or `dataHl: 'strong'` for nested lines or descriptions ending with `!`) to line elements. Text highlights (`@highlight-text`) wrap matched text in `<mark>` elements, which inherit `data-hl` from their containing highlight range via `containingRangeDepth`
 
 ### HAST Structure
 
@@ -556,17 +556,19 @@ Lines in the HAST tree have this structure after enhancement:
 }
 ```
 
-For text highlighting with `@highlight-text "text"`, the specified text within the line is wrapped in a span:
+For text highlighting with `@highlight-text "text"`, the specified text within the line is wrapped in a `<mark>` element:
 
 ```ts
 {
   type: 'element',
-  tagName: 'span',
-  properties: { dataHl: '' },
+  tagName: 'mark',
+  properties: {},
   children: [{ type: 'text', value: 'text' }]
 }
 ```
 
+When the `<mark>` is inside a containing highlight range, it inherits `data-hl` based on the nesting depth: `data-hl=""` for one containing range, `data-hl="strong"` for two or more. When the highlighted text matches a single syntax-highlighting `<span>`, the span is replaced in-place (its `tagName` becomes `mark` and highlight properties are merged) to keep the output flat.
+
 ### Data Attributes
 
 The enhancer adds these attributes to line elements when the highlight is nested
@@ -601,8 +603,9 @@ For multi-line emphasis with `@highlight-start` / `@highlight-end`:
 
 For text highlighting with `@highlight-text "text"`:
 
-- The specified text within the line is wrapped in a `<span data-hl="">` element
-- The line element itself does not receive any additional attributes
+- The specified text within the line is wrapped in a `<mark>` element
+- When inside a containing highlight range, marks inherit `data-hl` based on nesting depth (`""` for 1 range, `"strong"` for 2+)
+- The line element itself does not receive any additional attributes unless it is also inside a focus region or nested
 
 ### Stack-Based Pairing
 
@@ -730,11 +733,21 @@ When `@highlight` lines appear inside a `@focus` region, or when highlights are
 }
 
 /* Text-level highlight (from @highlight-text) */
-:not(.line)[data-hl] {
-  background: #e1d9ff;
+mark {
+  background: #ebe4ff;
   border-radius: 4px;
 }
 
+/* Text-level highlight inside a containing highlight range */
+mark[data-hl] {
+  background: #e1d9ff;
+}
+
+/* Text-level highlight inside 2+ nested highlight ranges */
+mark[data-hl='strong'] {
+  background: #d4c8ff;
+}
+
 /* Strong emphasis for nested highlights or descriptions ending with ! */
 .line[data-hl='strong'] {
   background: #e1d9ff;

From 66edfb859313858532266c37223e76b7401e02e6 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 14:25:53 -0400
Subject: [PATCH 11/44] Reorder sections

---
 .../pipeline/enhance-code-emphasis/page.mdx   | 336 +++++++++---------
 docs/app/docs-infra/pipeline/page.mdx         |  26 +-
 2 files changed, 181 insertions(+), 181 deletions(-)

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 717bfa51f..dfbfc4525 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
@@ -141,6 +141,77 @@ Each quoted text is independently wrapped in a `<mark>` element.
 
 ---
 
+## Configuration
+
+### Adding to Source Enhancers
+
+Configure in your webpack loader or server-side loading:
+
+```ts
+import { enhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+import { createLoadServerSource } from '@mui/internal-docs-infra/pipeline/loadServerSource';
+import { loadCodeVariant } from '@mui/internal-docs-infra/pipeline/loadCodeVariant';
+
+const sourceEnhancers = [enhanceCodeEmphasis];
+```
+
+For configurable padding, use the factory:
+
+```ts
+import { createEnhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+
+const sourceEnhancers = [
+  createEnhanceCodeEmphasis({
+    paddingFrameMaxSize: 3,
+    focusFramesMaxSize: 10,
+  }),
+];
+```
+
+Then pass to your loading pipeline:
+
+```ts
+// Create a loadSource that extracts emphasis and focus comments
+const loadSource = createLoadServerSource({
+  notableCommentsPrefix: ['@highlight', '@focus'],
+  removeCommentsWithPrefix: ['@highlight', '@focus'],
+});
+
+// Use with loadCodeVariant
+const { code } = await loadCodeVariant(url, variantName, variant, {
+  loadSource,
+  sourceEnhancers,
+  sourceParser,
+});
+
+// Or with CodeHighlighter
+<CodeHighlighter
+  sourceEnhancers={sourceEnhancers}
+  // ... other props
+/>
+
+// Or with useCode
+const { selectedFile } = useCode(props, {
+  sourceEnhancers,
+});
+```
+
+### Comment Prefix
+
+The default comment prefixes are `@highlight` and `@focus`, exported as `EMPHASIS_COMMENT_PREFIX` and `FOCUS_COMMENT_PREFIX`:
+
+```ts
+import {
+  EMPHASIS_COMMENT_PREFIX,
+  FOCUS_COMMENT_PREFIX,
+} from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+
+console.log(EMPHASIS_COMMENT_PREFIX); // '@highlight'
+console.log(FOCUS_COMMENT_PREFIX); // '@focus'
+```
+
+---
+
 ## Comment Syntax
 
 ### Supported Formats
@@ -485,7 +556,7 @@ Target frame types with CSS to style highlighted frames and create collapsible c
 }
 ```
 
-### Demo: Collapsible Code Block
+### Collapsible Code Block
 
 The following demo shows a code block that starts collapsed, revealing only the highlighted and padding frames. Click **Expand** to show the full source.
 
@@ -493,7 +564,7 @@ import { DemoCollapsibleCode } from './demos/collapsible-code';
 
 <DemoCollapsibleCode />
 
-### Demo: Collapsible Demo
+### Collapsible Demo
 
 A full demo component with a live preview, file tabs, and collapsible code. The code section starts collapsed, showing only the focused region.
 
@@ -501,7 +572,7 @@ import { DemoCollapsibleDemo } from './demos/collapsible-demo';
 
 <DemoCollapsibleDemo />
 
-### Demo: @focus with Multiple Regions
+### @focus with Multiple Regions
 
 This demo uses `@highlight` on the `formatDate` call and standalone `@focus-start`/`@focus-end` around the `useEffect` block. The `useEffect` region is focused (padding frames surround it) but has no line-level highlighting, while the `formatDate` line has line-level highlighting but is unfocused.
 
@@ -509,7 +580,7 @@ import { DemoFocusCode } from './demos/focus-code';
 
 <DemoFocusCode />
 
-### Demo: Indent Shifting
+### 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.
 
@@ -517,7 +588,7 @@ import { DemoIndentCode } from './demos/indent-code';
 
 <DemoIndentCode />
 
-### Demo: Focus Max Size
+### Focus Max Size
 
 When `focusFramesMaxSize` is set and a highlighted region exceeds that limit, a focused window is taken from the start of the region, and the remaining overflow lines are marked as unfocused. This demo uses `focusFramesMaxSize: 6` with the `<form>` JSX highlighted (10 lines). When collapsed, only the first 6 lines of the region are visible; expanding reveals the full highlighted region with the overflow lines.
 
@@ -527,169 +598,6 @@ import { DemoMaxSizeCode } from './demos/max-size-code';
 
 ---
 
-## Implementation Details
-
-### How It Works
-
-1. **Comment Extraction**: Comments are extracted during parsing with `notableCommentsPrefix: ['@highlight', '@focus']`
-2. **Directive Parsing**: The enhancer scans comments for `@highlight`, `@highlight-start`, `@highlight-end`, `@highlight-text`, `@focus`, `@focus-start`, `@focus-end`, and optional `@padding N` / `@min N` modifiers
-3. **Line Calculation**: Single-line directives mark their own line; multi-line directives mark all lines from the first line after `@highlight-start` to the last line before `@highlight-end`
-4. **Nested Detection**: Lines inside multiple ranges are automatically marked as strong emphasis
-5. **HAST Modification**: The enhancer traverses the HAST tree and adds `dataHl: ''` (or `dataHl: 'strong'` for nested lines or descriptions ending with `!`) to line elements. Text highlights (`@highlight-text`) wrap matched text in `<mark>` elements, which inherit `data-hl` from their containing highlight range via `containingRangeDepth`
-
-### HAST Structure
-
-Lines in the HAST tree have this structure after enhancement:
-
-```ts
-{
-  type: 'element',
-  tagName: 'span',
-  properties: {
-    className: 'line',
-    dataLn: 3,                              // Line number
-    dataHl: '',                             // Added by enhancer (or 'strong' for nested/!)
-    dataHlDescription: 'We track state',    // Optional description
-    dataHlPosition: 'single',               // 'single' | 'start' | 'end' for line position
-  },
-  children: [/* code tokens */]
-}
-```
-
-For text highlighting with `@highlight-text "text"`, the specified text within the line is wrapped in a `<mark>` element:
-
-```ts
-{
-  type: 'element',
-  tagName: 'mark',
-  properties: {},
-  children: [{ type: 'text', value: 'text' }]
-}
-```
-
-When the `<mark>` is inside a containing highlight range, it inherits `data-hl` based on the nesting depth: `data-hl=""` for one containing range, `data-hl="strong"` for two or more. When the highlighted text matches a single syntax-highlighting `<span>`, the span is replaced in-place (its `tagName` becomes `mark` and highlight properties are merged) to keep the output flat.
-
-### Data Attributes
-
-The enhancer adds these attributes to line elements when the highlight is nested
-(inside a focus frame or strong from nesting):
-
-| Attribute             | Type   | Description                                                                                        |
-| --------------------- | ------ | -------------------------------------------------------------------------------------------------- |
-| `data-hl`             | string | `""` for normal, `"strong"` if description ends with `!` or line is nested                         |
-| `data-hl-description` | string | Description text (if provided in comment)                                                          |
-| `data-hl-position`    | string | `"single"` for single-line, `"start"` or `"end"` for multiline range bounds (from innermost range) |
-
-For standalone highlights (no focus context, not nested), the visual emphasis is
-handled entirely at the frame level. The frame receives `data-frame-description`
-if a description was provided (see [Frame Data Attributes](#frame-data-attributes)).
-
-For single-line emphasis with `@highlight`:
-
-- `data-hl` is set (or `data-hl="strong"` if description ends with `!`)
-- `data-hl-description` is set if a description was provided
-- `data-hl-position="single"` is set to distinguish from multiline range boundaries
-
-For multi-line emphasis with `@highlight-start` / `@highlight-end`:
-
-- `data-hl` is set on all lines in the range (or `data-hl="strong"` if description ends with `!` or line is nested)
-- `data-hl-description` is set on the **first** line (if provided)
-- `data-hl-position="start"` is set on the **first** line (only for ranges with more than one line)
-- `data-hl-position="end"` is set on the **last** line (only for ranges with more than one line)
-
-> **Note**: The above line-level attributes are only applied when the highlight is
-> inside a focus region or is nested (strong). For standalone highlights, descriptions
-> are placed on the frame element as `data-frame-description` instead.
-
-For text highlighting with `@highlight-text "text"`:
-
-- The specified text within the line is wrapped in a `<mark>` element
-- When inside a containing highlight range, marks inherit `data-hl` based on nesting depth (`""` for 1 range, `"strong"` for 2+)
-- The line element itself does not receive any additional attributes unless it is also inside a focus region or nested
-
-### Stack-Based Pairing
-
-Multi-line directives are paired using a stack:
-
-- `@highlight-start` pushes onto the stack
-- `@highlight-end` pops from the stack and emphasizes the range
-- Inner (nested) ranges are processed before outer ranges
-- Lines that appear in multiple ranges are automatically marked as strong emphasis
-- Position markers from inner ranges are preserved when outer ranges are processed
-
----
-
-## Configuration
-
-### Adding to Source Enhancers
-
-Configure in your webpack loader or server-side loading:
-
-```ts
-import { enhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
-import { createLoadServerSource } from '@mui/internal-docs-infra/pipeline/loadServerSource';
-import { loadCodeVariant } from '@mui/internal-docs-infra/pipeline/loadCodeVariant';
-
-const sourceEnhancers = [enhanceCodeEmphasis];
-```
-
-For configurable padding, use the factory:
-
-```ts
-import { createEnhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
-
-const sourceEnhancers = [
-  createEnhanceCodeEmphasis({
-    paddingFrameMaxSize: 3,
-    focusFramesMaxSize: 10,
-  }),
-];
-```
-
-Then pass to your loading pipeline:
-
-```ts
-// Create a loadSource that extracts emphasis and focus comments
-const loadSource = createLoadServerSource({
-  notableCommentsPrefix: ['@highlight', '@focus'],
-  removeCommentsWithPrefix: ['@highlight', '@focus'],
-});
-
-// Use with loadCodeVariant
-const { code } = await loadCodeVariant(url, variantName, variant, {
-  loadSource,
-  sourceEnhancers,
-  sourceParser,
-});
-
-// Or with CodeHighlighter
-<CodeHighlighter
-  sourceEnhancers={sourceEnhancers}
-  // ... other props
-/>
-
-// Or with useCode
-const { selectedFile } = useCode(props, {
-  sourceEnhancers,
-});
-```
-
-### Comment Prefix
-
-The default comment prefixes are `@highlight` and `@focus`, exported as `EMPHASIS_COMMENT_PREFIX` and `FOCUS_COMMENT_PREFIX`:
-
-```ts
-import {
-  EMPHASIS_COMMENT_PREFIX,
-  FOCUS_COMMENT_PREFIX,
-} from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
-
-console.log(EMPHASIS_COMMENT_PREFIX); // '@highlight'
-console.log(FOCUS_COMMENT_PREFIX); // '@focus'
-```
-
----
-
 ## Styling Emphasized Lines
 
 ### Frame-Level Highlighting
@@ -901,6 +809,98 @@ Verify that:
 
 ---
 
+## Implementation Details
+
+### How It Works
+
+1. **Comment Extraction**: Comments are extracted during parsing with `notableCommentsPrefix: ['@highlight', '@focus']`
+2. **Directive Parsing**: The enhancer scans comments for `@highlight`, `@highlight-start`, `@highlight-end`, `@highlight-text`, `@focus`, `@focus-start`, `@focus-end`, and optional `@padding N` / `@min N` modifiers
+3. **Line Calculation**: Single-line directives mark their own line; multi-line directives mark all lines from the first line after `@highlight-start` to the last line before `@highlight-end`
+4. **Nested Detection**: Lines inside multiple ranges are automatically marked as strong emphasis
+5. **HAST Modification**: The enhancer traverses the HAST tree and adds `dataHl: ''` (or `dataHl: 'strong'` for nested lines or descriptions ending with `!`) to line elements. Text highlights (`@highlight-text`) wrap matched text in `<mark>` elements, which inherit `data-hl` from their containing highlight range via `containingRangeDepth`
+
+### HAST Structure
+
+Lines in the HAST tree have this structure after enhancement:
+
+```ts
+{
+  type: 'element',
+  tagName: 'span',
+  properties: {
+    className: 'line',
+    dataLn: 3,                              // Line number
+    dataHl: '',                             // Added by enhancer (or 'strong' for nested/!)
+    dataHlDescription: 'We track state',    // Optional description
+    dataHlPosition: 'single',               // 'single' | 'start' | 'end' for line position
+  },
+  children: [/* code tokens */]
+}
+```
+
+For text highlighting with `@highlight-text "text"`, the specified text within the line is wrapped in a `<mark>` element:
+
+```ts
+{
+  type: 'element',
+  tagName: 'mark',
+  properties: {},
+  children: [{ type: 'text', value: 'text' }]
+}
+```
+
+When the `<mark>` is inside a containing highlight range, it inherits `data-hl` based on the nesting depth: `data-hl=""` for one containing range, `data-hl="strong"` for two or more. When the highlighted text matches a single syntax-highlighting `<span>`, the span is replaced in-place (its `tagName` becomes `mark` and highlight properties are merged) to keep the output flat.
+
+### Data Attributes
+
+The enhancer adds these attributes to line elements when the highlight is nested
+(inside a focus frame or strong from nesting):
+
+| Attribute             | Type   | Description                                                                                        |
+| --------------------- | ------ | -------------------------------------------------------------------------------------------------- |
+| `data-hl`             | string | `""` for normal, `"strong"` if description ends with `!` or line is nested                         |
+| `data-hl-description` | string | Description text (if provided in comment)                                                          |
+| `data-hl-position`    | string | `"single"` for single-line, `"start"` or `"end"` for multiline range bounds (from innermost range) |
+
+For standalone highlights (no focus context, not nested), the visual emphasis is
+handled entirely at the frame level. The frame receives `data-frame-description`
+if a description was provided (see [Frame Data Attributes](#frame-data-attributes)).
+
+For single-line emphasis with `@highlight`:
+
+- `data-hl` is set (or `data-hl="strong"` if description ends with `!`)
+- `data-hl-description` is set if a description was provided
+- `data-hl-position="single"` is set to distinguish from multiline range boundaries
+
+For multi-line emphasis with `@highlight-start` / `@highlight-end`:
+
+- `data-hl` is set on all lines in the range (or `data-hl="strong"` if description ends with `!` or line is nested)
+- `data-hl-description` is set on the **first** line (if provided)
+- `data-hl-position="start"` is set on the **first** line (only for ranges with more than one line)
+- `data-hl-position="end"` is set on the **last** line (only for ranges with more than one line)
+
+> **Note**: The above line-level attributes are only applied when the highlight is
+> inside a focus region or is nested (strong). For standalone highlights, descriptions
+> are placed on the frame element as `data-frame-description` instead.
+
+For text highlighting with `@highlight-text "text"`:
+
+- The specified text within the line is wrapped in a `<mark>` element
+- When inside a containing highlight range, marks inherit `data-hl` based on nesting depth (`""` for 1 range, `"strong"` for 2+)
+- The line element itself does not receive any additional attributes unless it is also inside a focus region or nested
+
+### Stack-Based Pairing
+
+Multi-line directives are paired using a stack:
+
+- `@highlight-start` pushes onto the stack
+- `@highlight-end` pops from the stack and emphasizes the range
+- Inner (nested) ranges are processed before outer ranges
+- Lines that appear in multiple ranges are automatically marked as strong emphasis
+- Position markers from inner ranges are preserved when outer ranges are processed
+
+---
+
 ## Types
 
 import { TypesEnhanceCodeEmphasis } from './types';
diff --git a/docs/app/docs-infra/pipeline/page.mdx b/docs/app/docs-infra/pipeline/page.mdx
index 988b1c768..8a99f0d28 100644
--- a/docs/app/docs-infra/pipeline/page.mdx
+++ b/docs/app/docs-infra/pipeline/page.mdx
@@ -56,6 +56,9 @@ The `enhanceCodeEmphasis` source enhancer adds visual emphasis to specific lines
     - Multi-line with Description
     - Text Highlighting
     - Multiple Text Highlighting
+  - Configuration
+    - Adding to Source Enhancers
+    - Comment Prefix
   - Comment Syntax
     - Supported Formats
     - Description Format
@@ -73,19 +76,11 @@ The `enhanceCodeEmphasis` source enhancer adds visual emphasis to specific lines
     - The `@focus` Directive
     - Standalone `@focus` (Focus Without Highlight)
     - Styling Frame Types
-    - Demo: Collapsible Code Block
-    - Demo: Collapsible Demo
-    - Demo: @focus with Multiple Regions
-    - Demo: Indent Shifting
-    - Demo: Focus Max Size
-  - Implementation Details
-    - How It Works
-    - HAST Structure
-    - Data Attributes
-    - Stack-Based Pairing
-  - Configuration
-    - Adding to Source Enhancers
-    - Comment Prefix
+    - Collapsible Code Block
+    - Collapsible Demo
+    - @focus with Multiple Regions
+    - Indent Shifting
+    - Focus Max Size
   - Styling Emphasized Lines
     - Frame-Level Highlighting
     - Line-Level Highlighting
@@ -99,6 +94,11 @@ The `enhanceCodeEmphasis` source enhancer adds visual emphasis to specific lines
     - Lines Not Being Emphasized
     - Unmatched Multi-line Pairs
     - Wrong Lines Emphasized
+  - Implementation Details
+    - How It Works
+    - HAST Structure
+    - Data Attributes
+    - Stack-Based Pairing
   - Types
   - Related
 - Exports:

From 908392bc6b8892edaa4d81d84c200b9e25f5b5b8 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 14:42:01 -0400
Subject: [PATCH 12/44] Improve cases where of `@highlight @focus`

---
 .../enhanceCodeEmphasis.test.ts               |  4 +-
 .../parseSource/calculateFrameRanges.test.ts  | 65 +++++++++++++++----
 .../parseSource/calculateFrameRanges.ts       | 23 +++++--
 3 files changed, 72 insertions(+), 20 deletions(-)

diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
index 5f5ad5c39..b2f965505 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
@@ -1082,7 +1082,7 @@ const e = 5;`,
       // @focus is on line 4, so padding goes around line 4
       // Padding top: line 3, padding bottom: line 5
       expect(result).toMatch(/data-frame-type="padding-top"/);
-      expect(result).toMatch(/data-frame-type="focus"/);
+      expect(result).toMatch(/data-frame-type="highlighted"/);
       expect(result).toMatch(/data-frame-type="padding-bottom"/);
 
       // Line 1 still highlighted but no padding around it (unfocused)
@@ -1129,7 +1129,7 @@ const d = 4;`,
       );
 
       // @focus on line 3 with description "important line"
-      expect(result).toMatch(/data-frame-type="focus"/);
+      expect(result).toMatch(/data-frame-type="highlighted"/);
       expect(result).toContain('data-hl-description="Important line"');
       expect(result).toContain('data-frame-type="padding-top"');
       expect(result).toContain('data-frame-type="padding-bottom"');
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
index 458925722..41bd1d4ca 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
@@ -373,8 +373,14 @@ describe('calculateFrameRanges', () => {
 
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 4, type: 'normal' },
-        { startLine: 5, endLine: 6, type: 'focus', regionIndex: 0, truncated: 'visible' },
-        { startLine: 7, endLine: 8, type: 'focus-unfocused', regionIndex: 0, truncated: 'hidden' },
+        { startLine: 5, endLine: 6, type: 'highlighted', regionIndex: 0, truncated: 'visible' },
+        {
+          startLine: 7,
+          endLine: 8,
+          type: 'highlighted-unfocused',
+          regionIndex: 0,
+          truncated: 'hidden',
+        },
         { startLine: 9, endLine: 10, type: 'normal' },
       ]);
     });
@@ -395,7 +401,7 @@ describe('calculateFrameRanges', () => {
       // padding-top: lines 1-4 (4 lines), padding-bottom: lines 7-10 (4 lines)
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 4, type: 'padding-top' },
-        { startLine: 5, endLine: 6, type: 'focus', regionIndex: 0 },
+        { startLine: 5, endLine: 6, type: 'highlighted', regionIndex: 0 },
         { startLine: 7, endLine: 10, type: 'padding-bottom' },
         { startLine: 11, endLine: 15, type: 'normal' },
       ]);
@@ -420,8 +426,14 @@ describe('calculateFrameRanges', () => {
       // visible window = 2 lines (5-6), hidden overflow = 3 lines (7-9)
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 4, type: 'normal' },
-        { startLine: 5, endLine: 6, type: 'focus', regionIndex: 0, truncated: 'visible' },
-        { startLine: 7, endLine: 9, type: 'focus-unfocused', regionIndex: 0, truncated: 'hidden' },
+        { startLine: 5, endLine: 6, type: 'highlighted', regionIndex: 0, truncated: 'visible' },
+        {
+          startLine: 7,
+          endLine: 9,
+          type: 'highlighted-unfocused',
+          regionIndex: 0,
+          truncated: 'hidden',
+        },
         { startLine: 10, endLine: 12, type: 'normal' },
       ]);
     });
@@ -467,8 +479,14 @@ describe('calculateFrameRanges', () => {
       // splitting the 5-line region into visible 5-7 and hidden 8-9
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 4, type: 'normal' },
-        { startLine: 5, endLine: 7, type: 'focus', regionIndex: 0, truncated: 'visible' },
-        { startLine: 8, endLine: 9, type: 'focus-unfocused', regionIndex: 0, truncated: 'hidden' },
+        { startLine: 5, endLine: 7, type: 'highlighted', regionIndex: 0, truncated: 'visible' },
+        {
+          startLine: 8,
+          endLine: 9,
+          type: 'highlighted-unfocused',
+          regionIndex: 0,
+          truncated: 'hidden',
+        },
         { startLine: 10, endLine: 12, type: 'normal' },
       ]);
     });
@@ -633,13 +651,14 @@ describe('calculateFrameRanges', () => {
       });
 
       // Second region is focused, so it gets padding.
-      // It has both focus and lineHighlight, but focus takes precedence for the frame type.
+      // It has both focus and lineHighlight, and since all lines are highlighted,
+      // the frame type is "highlighted" (not "focus").
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 2, type: 'normal' },
         { startLine: 3, endLine: 3, type: 'highlighted-unfocused', regionIndex: 0 },
         { startLine: 4, endLine: 11, type: 'normal' },
         { startLine: 12, endLine: 14, type: 'padding-top' },
-        { startLine: 15, endLine: 15, type: 'focus', regionIndex: 1 },
+        { startLine: 15, endLine: 15, type: 'highlighted', regionIndex: 1 },
         { startLine: 16, endLine: 18, type: 'padding-bottom' },
         { startLine: 19, endLine: 20, type: 'normal' },
       ]);
@@ -667,9 +686,9 @@ describe('calculateFrameRanges', () => {
       ]);
     });
 
-    it('should use focus frame type when focus region contains highlight lines', () => {
+    it('should use focus frame type when focus region has only some lines highlighted', () => {
       // @focus region spanning lines 3-8, with @highlight on line 5
-      // The frame type should be "focus" (not "highlighted") because the region has focus.
+      // The frame type should be "focus" (not "highlighted") because not all lines are highlighted.
       // The highlight on line 5 is handled at the line level (data-hl).
       const emphasizedLines = new Map<number, EmphasisMeta>([
         [3, { lineHighlight: false, focus: true }],
@@ -691,6 +710,30 @@ describe('calculateFrameRanges', () => {
         { startLine: 11, endLine: 12, type: 'normal' },
       ]);
     });
+
+    it('should use highlighted frame type when @highlight-start @focus marks all lines', () => {
+      // @highlight on line 1 (unfocused), @highlight-start @focus on lines 3-5
+      // Since all lines in the focused region have lineHighlight: true,
+      // the frame should be "highlighted" (not "focus").
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [1, { position: 'single', lineHighlight: true }],
+        [3, { lineHighlight: true, focus: true, position: 'start' }],
+        [4, { lineHighlight: true, focus: true }],
+        [5, { lineHighlight: true, focus: true, position: 'end' }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 8, {
+        paddingFrameMaxSize: 1,
+      });
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 1, type: 'highlighted-unfocused', regionIndex: 0 },
+        { startLine: 2, endLine: 2, type: 'padding-top' },
+        { startLine: 3, endLine: 5, type: 'highlighted', regionIndex: 1 },
+        { startLine: 6, endLine: 6, type: 'padding-bottom' },
+        { startLine: 7, endLine: 8, type: 'normal' },
+      ]);
+    });
   });
 
   describe('edge cases', () => {
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
index 1d6acdf75..475858021 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
@@ -70,6 +70,8 @@ interface HighlightRegion {
   focused: boolean;
   /** Whether any line in this region has line-level highlighting (data-hl) */
   hasLineHighlight: boolean;
+  /** Whether every line in this region has line-level highlighting (data-hl) */
+  allLinesHighlighted: boolean;
   /** Per-directive padding override for this region, if specified */
   paddingFrameMaxSize?: number;
   /** Per-directive focus max size override for this region, if specified */
@@ -186,6 +188,7 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
   const firstMeta = emphasizedLines.get(sortedLines[0]);
   let hasFocus = firstMeta?.focus ?? false;
   let hasLineHighlight = firstMeta?.lineHighlight ?? false;
+  let allLinesHighlighted = firstMeta?.lineHighlight ?? false;
   let ch = emptyChannels();
   accumulateOverrides(ch, firstMeta);
 
@@ -200,6 +203,8 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
       }
       if (meta?.lineHighlight) {
         hasLineHighlight = true;
+      } else {
+        allLinesHighlighted = false;
       }
       accumulateOverrides(ch, meta);
     } else {
@@ -210,6 +215,7 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
         index: regions.length,
         focused: hasFocus,
         hasLineHighlight,
+        allLinesHighlighted,
         paddingFrameMaxSize: resolvePadding(ch),
         focusFramesMaxSize: resolveMaxSize(ch),
       });
@@ -218,6 +224,7 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
       const meta = emphasizedLines.get(line);
       hasFocus = meta?.focus ?? false;
       hasLineHighlight = meta?.lineHighlight ?? false;
+      allLinesHighlighted = meta?.lineHighlight ?? false;
       ch = emptyChannels();
       accumulateOverrides(ch, meta);
     }
@@ -231,6 +238,7 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
     index: regions.length,
     focused: hasFocus,
     hasLineHighlight,
+    allLinesHighlighted,
     focusFramesMaxSize: resolveMaxSize(ch),
   });
 
@@ -438,11 +446,12 @@ export function calculateFrameRanges(
     if (isFocused && focusWindow) {
       // Split oversized focused region into unfocused-top + focused-center + unfocused-bottom
       const [focusStart, focusEnd] = focusWindow;
-      const hasHighlightOnly = region.hasLineHighlight && !region.focused;
-      const unfocusedType: FrameRange['type'] = hasHighlightOnly
+      const isHighlightFrame =
+        region.hasLineHighlight && (!region.focused || region.allLinesHighlighted);
+      const unfocusedType: FrameRange['type'] = isHighlightFrame
         ? 'highlighted-unfocused'
         : 'focus-unfocused';
-      const focusedType: FrameRange['type'] = hasHighlightOnly ? 'highlighted' : 'focus';
+      const focusedType: FrameRange['type'] = isHighlightFrame ? 'highlighted' : 'focus';
 
       if (region.startLine < focusStart) {
         frames.push({
@@ -470,11 +479,11 @@ export function calculateFrameRanges(
         });
       }
     } else {
-      // Frame type depends on whether the region has line highlights without focus.
-      // When a region has both focus and highlights, the frame is "focus" and
-      // individual lines receive data-hl for visual highlighting.
+      // Frame type depends on whether the region's lines are highlighted.
+      // When all lines have data-hl (e.g. @highlight-start @focus), use "highlighted".
+      // When only some lines are highlighted (e.g. @focus with inner @highlight), use "focus".
       let frameType: FrameRange['type'];
-      if (region.hasLineHighlight && !region.focused) {
+      if (region.hasLineHighlight && (!region.focused || region.allLinesHighlighted)) {
         frameType = isFocused ? 'highlighted' : 'highlighted-unfocused';
       } else {
         frameType = isFocused ? 'focus' : 'focus-unfocused';

From efcc29867effdda1a63a6d4fa92a1d5ae1890f5a Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 15:11:00 -0400
Subject: [PATCH 13/44] Automatically add appropriate padding

---
 .../components/code-highlighter/demos/CodeContent.tsx       | 2 +-
 .../demos/code-editor/CodeController.tsx                    | 2 +-
 .../demos/code-editor/CodeEditorContent.tsx                 | 2 +-
 .../demos/demo-live/DemoController.tsx                      | 2 +-
 .../demos/demo-live/DemoLiveContent.tsx                     | 2 +-
 .../demos/multi-file/MultiFileContent.tsx                   | 2 +-
 .../use-copier/demos/text-input-copy/TextInputCopy.tsx      | 2 +-
 .../demos/variant-selector/VariantSelector.tsx              | 2 +-
 docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx    | 2 +-
 .../docs-infra/hooks/use-types/demos/basic/Component.tsx    | 2 +-
 .../demos/blocks-data-attr/Component/Part/ComponentPart.tsx | 2 +-
 .../demos/blocks-data-attr/Component/Root/ComponentRoot.tsx | 2 +-
 .../use-types/demos/blocks-inherited/Dialog/DialogClose.tsx | 2 +-
 .../demos/blocks-inherited/Dialog/DialogTrigger.tsx         | 2 +-
 .../use-types/demos/blocks/Component/ComponentPart.tsx      | 2 +-
 .../use-types/demos/blocks/Component/ComponentRoot.tsx      | 2 +-
 .../hooks/use-types/demos/data-attr/Component.tsx           | 2 +-
 .../demos/tab-navigation/TabNavigation.tsx                  | 2 +-
 .../enhance-code-emphasis/demos/CollapsibleContent.tsx      | 2 +-
 .../enhance-code-emphasis/demos/CollapsibleDemoContent.tsx  | 2 +-
 .../pipeline/enhance-code-emphasis/demos/IndentContent.tsx  | 2 +-
 .../demos/collapsible-code/CollapsibleCode.tsx              | 2 +-
 .../demos/collapsible-demo/Counter.tsx                      | 2 +-
 .../enhance-code-emphasis/demos/focus-code/FocusCode.tsx    | 2 +-
 .../enhance-code-emphasis/demos/indent-code/IndentCode.tsx  | 2 +-
 .../demos/max-size-code/MaxSizeCode.tsx                     | 2 +-
 .../docs-infra/pipeline/lint-javascript-demo-focus/page.mdx | 2 +-
 .../docs-infra/pipeline/lint-javascript-demo-focus/types.md | 2 +-
 .../lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts | 6 +++---
 .../lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts      | 4 ++--
 30 files changed, 33 insertions(+), 33 deletions(-)

diff --git a/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx b/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx
index 21a4e94e1..c59558eb2 100644
--- a/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx
+++ b/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx
@@ -10,7 +10,7 @@ import styles from './CodeContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function CodeContent(props: ContentProps<{}>) {
-  // @focus-start
+  // @focus-start @padding 1
   const code = useCode(props, { preClassName: styles.codeBlock });
 
   return <div className={styles.code}>{code.selectedFile}</div>;
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx
index 8af4ab665..515ff7a3e 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx
@@ -5,7 +5,7 @@ import { CodeControllerContext } from '@mui/internal-docs-infra/CodeControllerCo
 import type { ControlledCode } from '@mui/internal-docs-infra/CodeHighlighter/types';
 
 export function CodeController({ children }: { children: React.ReactNode }) {
-  // @focus-start
+  // @focus-start @padding 1
   const [code, setCode] = React.useState<ControlledCode | undefined>(undefined);
 
   const contextValue = React.useMemo(() => ({ code, setCode }), [code, setCode]);
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 92e8ec567..2f7c6923a 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
@@ -10,7 +10,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>) {
-  // @focus-start
+  // @focus-start @padding 1
   const preRef = React.useRef<HTMLPreElement | null>(null);
   const code = useCode(props, { preClassName: styles.codeBlock, preRef });
 
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx
index e737e9f2c..09d2cff26 100644
--- a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx
+++ b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx
@@ -27,7 +27,7 @@ function Runner({ code }: { code: string }) {
 }
 
 export function DemoController({ children }: { children: React.ReactNode }) {
-  // @focus-start
+  // @focus-start @padding 1
   const [code, setCode] = React.useState<ControlledCode | undefined>(undefined);
 
   const components = React.useMemo(
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 129dfc5cc..a4652b9c9 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
@@ -16,7 +16,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function DemoLiveContent(props: ContentProps<object>) {
-  // @focus-start
+  // @focus-start @padding 1
   const preRef = React.useRef<HTMLPreElement | null>(null);
   const demo = useDemo(props, { preClassName: styles.codeBlock, preRef });
 
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 925b3dcf0..ef8c4c00a 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
@@ -10,7 +10,7 @@ import styles from '../code-editor/CodeEditorContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function MultiFileContent(props: ContentProps<object>) {
-  // @focus-start
+  // @focus-start @padding 1
   const preRef = React.useRef<HTMLPreElement | null>(null);
   const code = useCode(props, { preClassName: styles.codeBlock, preRef });
 
diff --git a/docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx b/docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx
index b4c4737bb..909ad1db3 100644
--- a/docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx
+++ b/docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx
@@ -4,7 +4,7 @@ import { useCopier } from '@mui/internal-docs-infra/useCopier';
 import styles from './TextInputCopy.module.css';
 
 export function TextInputCopy() {
-  // @focus-start
+  // @focus-start @padding 1
   const [text, setText] = React.useState('Hello, copy me!');
   const { copy, recentlySuccessful } = useCopier(() => text);
 
diff --git a/docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx b/docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx
index c6ab15c29..3f8721397 100644
--- a/docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx
+++ b/docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx
@@ -4,7 +4,7 @@ import { usePreference } from '@mui/internal-docs-infra/usePreference';
 import styles from './VariantSelector.module.css';
 
 export function VariantSelector() {
-  // @focus-start
+  // @focus-start @padding 1
   const variants = ['contained', 'outlined', 'text'];
   const [variant, setVariant] = usePreference('variant', variants, () => 'contained');
 
diff --git a/docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx b/docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx
index 2815f853b..09014b4e9 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx
@@ -19,8 +19,8 @@ import styles from './TypesTable.module.css';
 export type TypesTableProps = BaseTypesTableProps<{}>;
 
 export function TypesTable(props: TypesTableProps) {
+  // @focus-start @padding 1
   // Get the main type and additional types for this export
-  // @focus-start
   const { type, additionalTypes } = useTypes(props);
 
   return (
diff --git a/docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx b/docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx
index 02aee0661..af6da57d9 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx
@@ -13,7 +13,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function Component(props: Props) {
-  // @focus-start
+  // @focus-start @padding 1
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx
index f2ffc24e5..77031a99d 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx
@@ -22,7 +22,7 @@ export interface ComponentPartProps {
  * A simple component that displays a title and optional children.
  */
 export function ComponentPart(props: ComponentPartProps) {
-  // @focus-start
+  // @focus-start @padding 1
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event, props.input);
   };
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx
index d6db3e094..47974c02c 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx
@@ -38,7 +38,7 @@ export interface ComponentRootProps {
  * A simple component that displays a title and optional children.
  */
 export function ComponentRoot(props: ComponentRootProps) {
-  // @focus-start
+  // @focus-start @padding 1
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
 
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx
index 4b531db15..80eaa7321 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx
@@ -22,7 +22,7 @@ export const DialogClose = React.forwardRef(function DialogClose(
   props: DialogCloseProps,
   ref: React.ForwardedRef<HTMLButtonElement>,
 ) {
-  // @focus-start
+  // @focus-start @padding 1
   const { render, children, ...other } = props;
 
   // In a real implementation, triggerState would come from context
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx
index 92db61860..da5e659c6 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx
@@ -36,7 +36,7 @@ export const DialogTrigger = React.forwardRef(function DialogTrigger(
   props: DialogTriggerProps,
   ref: React.ForwardedRef<HTMLButtonElement>,
 ) {
-  // @focus-start
+  // @focus-start @padding 1
   const { className, disabled, children, ...other } = props;
 
   const state: DialogTriggerState = React.useMemo(
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx
index d2c081591..6c9ed948e 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx
@@ -13,7 +13,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function ComponentPart(props: Props) {
-  // @focus-start
+  // @focus-start @padding 1
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
diff --git a/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx b/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx
index 520cb3949..b4fc98c8d 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx
@@ -13,7 +13,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function ComponentRoot(props: Props) {
-  // @focus-start
+  // @focus-start @padding 1
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
diff --git a/docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx b/docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx
index 2fc2e774c..00e6d3d46 100644
--- a/docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx
+++ b/docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx
@@ -14,7 +14,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function Component(props: Props) {
-  // @focus-start
+  // @focus-start @padding 1
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
diff --git a/docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx b/docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx
index cea894043..995f880c3 100644
--- a/docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx
+++ b/docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx
@@ -14,7 +14,7 @@ const tabs = [
 ];
 
 export function TabNavigation() {
-  // @focus-start
+  // @focus-start @padding 1
   const [hash, setHash] = useUrlHashState();
   const activeTab = hash || 'overview';
 
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
index e48a0e786..8e074fc88 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
@@ -8,7 +8,7 @@ import styles from './CollapsibleContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function CollapsibleContent(props: ContentProps<object>) {
-  // @focus-start
+  // @focus-start @padding 1
   const code = useCode(props, { preClassName: styles.codeBlock });
   const id = React.useId();
   const checkboxId = `${id}-expand`;
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
index 0c5a956d4..046a9fffb 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
@@ -16,7 +16,7 @@ const variantNames: Record<string, string | undefined> = {
 };
 
 export function CollapsibleDemoContent(props: ContentProps<object>) {
-  // @focus-start
+  // @focus-start @padding 1
   const demo = useDemo(props, { preClassName: styles.codeBlock });
 
   const hasJsTransform = demo.availableTransforms.includes('js');
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx
index b9cfb1b36..06074dc96 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx
@@ -8,7 +8,7 @@ import styles from './IndentContent.module.css';
 import '@wooorm/starry-night/style/light';
 
 export function IndentContent(props: ContentProps<object>) {
-  // @focus-start
+  // @focus-start @padding 1
   const code = useCode(props, { preClassName: styles.codeBlock });
   const [expanded, setExpanded] = React.useState(false);
 
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-code/CollapsibleCode.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-code/CollapsibleCode.tsx
index bef4902fe..fa4eea7c6 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-code/CollapsibleCode.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-code/CollapsibleCode.tsx
@@ -42,7 +42,7 @@ export function UserProfile({ id }: { id: string }) {
 }`;
 
 export async function CollapsibleCode() {
-  // @focus-start
+  // @focus-start @padding 1
   const { code: strippedSource, comments } = await parseImportsAndComments(source, '/demo.tsx', {
     removeCommentsWithPrefix: [EMPHASIS_COMMENT_PREFIX],
     notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX],
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/Counter.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/Counter.tsx
index 4b2d64690..fe24f520b 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/Counter.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/Counter.tsx
@@ -3,7 +3,7 @@
 import * as React from 'react';
 
 export function Counter() {
-  // @focus-start
+  // @focus-start @padding 1
   const [count, setCount] = React.useState(0);
 
   return (
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/focus-code/FocusCode.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/focus-code/FocusCode.tsx
index 1cc9100ca..425af2646 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/focus-code/FocusCode.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/focus-code/FocusCode.tsx
@@ -35,7 +35,7 @@ export function Calendar() {
 }`;
 
 export async function FocusCode() {
-  // @focus-start
+  // @focus-start @padding 1
   const { code: strippedSource, comments } = await parseImportsAndComments(source, '/demo.tsx', {
     removeCommentsWithPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX],
     notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX],
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/indent-code/IndentCode.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/indent-code/IndentCode.tsx
index 47169eed8..69a4b40f3 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/indent-code/IndentCode.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/indent-code/IndentCode.tsx
@@ -40,7 +40,7 @@ export function ScheduleView() {
 }`;
 
 export async function IndentCode() {
-  // @focus-start
+  // @focus-start @padding 1
   const { code: strippedSource, comments } = await parseImportsAndComments(source, '/demo.tsx', {
     removeCommentsWithPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX],
     notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX],
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/MaxSizeCode.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/MaxSizeCode.tsx
index 0c141fd24..3ec63609c 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/MaxSizeCode.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/MaxSizeCode.tsx
@@ -48,7 +48,7 @@ export function ContactForm() {
 }`;
 
 export async function MaxSizeCode() {
-  // @focus-start
+  // @focus-start @padding 1
   const { code: strippedSource, comments } = await parseImportsAndComments(source, '/demo.tsx', {
     removeCommentsWithPrefix: [EMPHASIS_COMMENT_PREFIX],
     notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX],
diff --git a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
index eaab005b3..f4258188b 100644
--- a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
+++ b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
@@ -156,7 +156,7 @@ export default function Demo() {
 
 // After fix
 export default function Demo() {
-  // @focus-start
+  // @focus-start @padding 1
   const code = useCode();
   return <CodeEditor code={code} />;
   // @focus-end
diff --git a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md
index 1458c0dfc..c5531f697 100644
--- a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md
+++ b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md
@@ -23,7 +23,7 @@ type lintJavascriptDemoFocus = {
       missingDemoFocusJsxSingle: 'Demo file is missing {/* @focus */} comment on the preview line. Run with --fix to add it automatically.';
       missingDemoFocusJs: 'Demo file is missing // @focus-start and // @focus-end comments around the preview section. Run with --fix to add them automatically.';
       missingDemoFocusJsSingle: 'Demo file is missing // @focus comment on the preview line. Run with --fix to add it automatically.';
-      missingDemoFocusBody: 'Demo file is missing // @focus-start and // @focus-end comments around the function body. Run with --fix to add them automatically.';
+      missingDemoFocusBody: 'Demo file is missing // @focus-start @padding 1 and // @focus-end comments around the function body. Run with --fix to add them automatically.';
     };
     schema: [
       {
diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
index 1fd1a1876..fbb7831fa 100644
--- a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
@@ -346,7 +346,7 @@ export function Primary() {
   );
 }`,
           output: `export default function Demo() {
-  // @focus-start
+  // @focus-start @padding 1
   const code = useCode();
   return (
     <div>
@@ -367,7 +367,7 @@ export function Primary() {
   );
 }`,
           output: `export function CodeContent(props) {
-  // @focus-start
+  // @focus-start @padding 1
   const code = useCode(props);
   return (
     <div>{code.file}</div>
@@ -388,7 +388,7 @@ export function Primary() {
   );
 });`,
           output: `export const DialogTrigger = React.forwardRef(function DialogTrigger(props, ref) {
-  // @focus-start
+  // @focus-start @padding 1
   const { disabled, children, ...other } = props;
   return (
     <button type="button" ref={ref} disabled={disabled} {...other}>
diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
index 61258c372..abc8bced2 100644
--- a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
@@ -175,7 +175,7 @@ export const lintJavascriptDemoFocus = {
       missingDemoFocusJsSingle:
         'Demo file is missing // @focus comment on the preview line. Run with --fix to add it automatically.',
       missingDemoFocusBody:
-        'Demo file is missing // @focus-start and // @focus-end comments around the function body. Run with --fix to add them automatically.',
+        'Demo file is missing // @focus-start @padding 1 and // @focus-end comments around the function body. Run with --fix to add them automatically.',
     } as const,
     schema: [
       {
@@ -481,7 +481,7 @@ function reportFunctionBody(
       return [
         fixer.insertTextBeforeRange(
           [lineStartOffset, lineStartOffset],
-          `${indentation}// @focus-start\n`,
+          `${indentation}// @focus-start @padding 1\n`,
         ),
         fixer.insertTextAfterRange(
           [lastLineStartOffset, lastLineStartOffset + lastLine.length],

From 6645f23105d9f8577096ffd3c995e7fd524e2a68 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 15:23:18 -0400
Subject: [PATCH 14/44] Fix bug where data-hl provided on frame based highlight

---
 .../enhanceCodeEmphasis.test.ts               |  9 ++-
 .../enhanceCodeEmphasis.ts                    | 56 +++++++++++++++----
 2 files changed, 52 insertions(+), 13 deletions(-)

diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
index b2f965505..aac509e52 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
@@ -1111,6 +1111,13 @@ const e = 5;`,
       // Padding goes around that region
       expect(result).toContain('data-frame-type="padding-top"');
       expect(result).toContain('data-frame-type="padding-bottom"');
+
+      // Frame type is "highlighted" (not "focus") because all lines have lineHighlight
+      expect(result).toContain('data-frame-type="highlighted" data-frame-indent=');
+
+      // Lines inside the highlighted frame should NOT have data-hl
+      // (the frame itself communicates the highlight — no double emphasis)
+      expect(result).not.toMatch(/data-frame-type="highlighted"[^>]*>.*?data-hl=""/s);
     });
 
     it('should support @focus combined with a description', async () => {
@@ -1130,7 +1137,7 @@ const d = 4;`,
 
       // @focus on line 3 with description "important line"
       expect(result).toMatch(/data-frame-type="highlighted"/);
-      expect(result).toContain('data-hl-description="Important line"');
+      expect(result).toContain('data-frame-description="Important line"');
       expect(result).toContain('data-frame-type="padding-top"');
       expect(result).toContain('data-frame-type="padding-bottom"');
 
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
index d77a7cc46..f6abc4fdd 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
@@ -1346,18 +1346,30 @@ function calculateRegionIndentLevels(
 }
 
 /**
- * Applies frame-level descriptions to highlighted frames after restructuring.
+ * Post-restructure pass that reconciles line-level `data-hl` attributes with
+ * frame-level types.
  *
- * When a highlighted line has a description but doesn't need line-level `data-hl`
- * (because the frame handles the visual emphasis), the description is placed on
- * the frame element as `data-frame-description` instead.
+ * When a frame's type is `highlighted` or `highlighted-unfocused`, the frame
+ * itself already communicates the highlight — so line-level `data-hl` (empty
+ * value) is redundant and gets stripped. `data-hl="strong"` is preserved
+ * because it communicates deeper nesting that the frame type alone can't convey.
+ *
+ * Descriptions from stripped lines are promoted to the frame element as
+ * `data-frame-description`. For lines that never received `data-hl` in the first
+ * place (standalone highlights without focus), descriptions are also promoted.
  */
-function applyFrameDescriptions(root: HastRoot, emphasizedLines: Map<number, EmphasisMeta>): void {
+function reconcileLineAndFrameEmphasis(
+  root: HastRoot,
+  emphasizedLines: Map<number, EmphasisMeta>,
+): void {
   for (const frame of root.children) {
     if (frame.type !== 'element') {
       continue;
     }
 
+    const frameType = frame.properties?.dataFrameType as string | undefined;
+    const isHighlightedFrame = frameType === 'highlighted' || frameType === 'highlighted-unfocused';
+
     for (const child of frame.children) {
       if (
         child.type !== 'element' ||
@@ -1369,15 +1381,35 @@ function applyFrameDescriptions(root: HastRoot, emphasizedLines: Map<number, Emp
       }
 
       const meta = emphasizedLines.get(child.properties.dataLn);
-      if (!meta?.description) {
+      if (!meta) {
         continue;
       }
 
-      const shouldApplyLineHl = meta.lineHighlight && (meta.focus === true || meta.strong === true);
+      // In highlighted/highlighted-unfocused frames, strip redundant line-level
+      // data-hl (empty value only). The frame already communicates the highlight.
+      // Keep data-hl="strong" — it conveys deeper nesting the frame can't express.
+      if (
+        isHighlightedFrame &&
+        'dataHl' in (child.properties ?? {}) &&
+        child.properties.dataHl !== 'strong'
+      ) {
+        delete child.properties.dataHl;
+
+        // Move description and position to the frame since line-level attrs are gone
+        if (child.properties.dataHlDescription) {
+          frame.properties ??= {};
+          frame.properties.dataFrameDescription = child.properties.dataHlDescription;
+          delete child.properties.dataHlDescription;
+        }
+        if (child.properties.dataHlPosition) {
+          delete child.properties.dataHlPosition;
+        }
+        continue;
+      }
 
-      // When the frame handles highlighting (not line-level), put the description
-      // on the frame so it's not lost.
-      if (!shouldApplyLineHl) {
+      // For non-highlighted frames: promote descriptions to the frame when the
+      // line doesn't have data-hl (standalone highlights without focus).
+      if (meta.description && !('dataHl' in (child.properties ?? {}))) {
         frame.properties ??= {};
         frame.properties.dataFrameDescription = meta.description;
       }
@@ -1496,8 +1528,8 @@ export function createEnhanceCodeEmphasis(
     // Step 7: Restructure frames (flat iteration, not deep recursive traversal)
     restructureFrames(root, frameRanges, regionIndentLevels);
 
-    // Step 8: Apply frame-level descriptions to highlighted frames
-    applyFrameDescriptions(root, emphasizedLines);
+    // Step 8: Reconcile line-level data-hl with frame types and promote descriptions
+    reconcileLineAndFrameEmphasis(root, emphasizedLines);
 
     return root;
   };

From 0b8fdc299239bb9ca77983a6ea8fd278b189bc2a Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 15:33:29 -0400
Subject: [PATCH 15/44] Fix codeblock styles

---
 .../demos/CodeContent.module.css              | 27 ++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css b/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css
index 3edfe6b9b..e9845ecc3 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css
+++ b/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css
@@ -88,7 +88,9 @@
 
 /* Highlighted frames get rounded corners and background */
 .codeBlock :global(.frame[data-frame-type='highlighted']),
-.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+.codeBlock :global(.frame[data-frame-type='focus']),
+.codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
   background: #ebe4ff;
   border-radius: 8px;
   margin: 0 6px;
@@ -115,6 +117,20 @@
   background: #d4c8ff;
 }
 
+.codeBlock :global(mark[data-hl-part='start']) {
+  border-top-right-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+.codeBlock :global(mark[data-hl-part='middle']) {
+  border-radius: 0;
+}
+
+.codeBlock :global(mark[data-hl-part='end']) {
+  border-top-left-radius: 0;
+  border-bottom-left-radius: 0;
+}
+
 .codeBlock :global(.line[data-hl='strong']) {
   background: #e1d9ff;
   margin: 0 -6px;
@@ -153,3 +169,12 @@
   color: white;
   padding: 2px 4px;
 }
+
+/* Truncated frames: adjust rounding so visible/hidden halves connect */
+.codeBlock :global(.frame[data-frame-truncated='visible']) {
+  border-radius: 8px 8px 0 0;
+}
+
+.codeBlock :global(.frame[data-frame-truncated='hidden']) {
+  border-radius: 0 0 8px 8px;
+}

From 772de1bc2ca183d0d7b171a97a8c64bf316df68b Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 15:40:31 -0400
Subject: [PATCH 16/44] Fix background css

---
 .../components/code-highlighter/demos/CodeContent.module.css  | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css b/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css
index e9845ecc3..0023c8da9 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css
+++ b/docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css
@@ -88,9 +88,7 @@
 
 /* Highlighted frames get rounded corners and background */
 .codeBlock :global(.frame[data-frame-type='highlighted']),
-.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
-.codeBlock :global(.frame[data-frame-type='focus']),
-.codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
   background: #ebe4ff;
   border-radius: 8px;
   margin: 0 6px;

From c7d11e8c3317cdc0c8669bf71dcc5aa086d92e68 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 15:48:59 -0400
Subject: [PATCH 17/44] Fix max height

---
 .../enhance-code-emphasis/demos/CollapsibleContent.module.css   | 2 +-
 .../demos/CollapsibleDemoContent.module.css                     | 2 +-
 .../enhance-code-emphasis/demos/IndentContent.module.css        | 2 +-
 docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx     | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
index d6ad68f30..f9250a7e6 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
@@ -189,7 +189,7 @@ pre.codeBlock {
 .checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
-  max-height: 2000px;
+  max-height: 4500px;
   overflow: visible;
   opacity: 1;
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
index 69be46d51..6766c5b50 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
@@ -252,7 +252,7 @@ pre.codeBlock {
 .checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
-  max-height: 2000px;
+  max-height: 4500px;
   overflow: visible;
   opacity: 1;
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
index ddef991aa..9d7f1025d 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
@@ -149,7 +149,7 @@ pre.codeBlock {
 .expanded .codeBlock :global(.frame:not([data-frame-type])),
 .expanded .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
 .expanded .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
-  max-height: 2000px;
+  max-height: 4500px;
   overflow: visible;
   opacity: 1;
 }
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 dfbfc4525..a4c5b0be1 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
@@ -523,7 +523,7 @@ Target frame types with CSS to style highlighted frames and create collapsible c
 .expanded .codeBlock .frame:not([data-frame-type]),
 .expanded .codeBlock .frame[data-frame-type='highlighted-unfocused'],
 .expanded .codeBlock .frame[data-frame-type='focus-unfocused'] {
-  max-height: 500px;
+  max-height: 4500px;
   overflow: visible;
   opacity: 1;
 }

From 88e3f745b26812f51b8d01c921be230277a01253 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 16:10:47 -0400
Subject: [PATCH 18/44] Code review

---
 .../enhanceCodeEmphasis.ts                    | 46 +++++++++----------
 .../lintJavascriptDemoFocus.ts                |  4 +-
 .../parseSource/calculateFrameRanges.ts       | 44 ++++++++++--------
 3 files changed, 49 insertions(+), 45 deletions(-)

diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
index f6abc4fdd..6bdfe75c0 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
@@ -69,17 +69,17 @@ function maskQuotedContent(content: string): string {
   let result = '';
   let quoteChar: string | undefined;
   for (let i = 0; i < content.length; i += 1) {
-    const ch = content[i];
+    const char = content[i];
     if (quoteChar) {
       result += '_';
-      if (ch === quoteChar) {
+      if (char === quoteChar) {
         quoteChar = undefined;
       }
-    } else if (ch === '"' || ch === "'") {
-      quoteChar = ch;
+    } else if (char === '"' || char === "'") {
+      quoteChar = char;
       result += '_';
     } else {
-      result += ch;
+      result += char;
     }
   }
   return result;
@@ -88,8 +88,8 @@ function maskQuotedContent(content: string): string {
 /**
  * Returns `true` when `ch` is an ASCII whitespace character.
  */
-function isWhitespace(ch: string | undefined): boolean {
-  return ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r';
+function isWhitespace(char: string | undefined): boolean {
+  return char === ' ' || char === '\t' || char === '\n' || char === '\r';
 }
 
 /**
@@ -154,16 +154,16 @@ function extractPaddingValue(content: string): number | undefined {
     return undefined;
   }
   // Skip whitespace after "@padding"
-  let p = idx + '@padding'.length;
-  while (p < masked.length && isWhitespace(masked[p])) {
-    p += 1;
+  let pos = idx + '@padding'.length;
+  while (pos < masked.length && isWhitespace(masked[pos])) {
+    pos += 1;
   }
-  const digits = readDigits(masked, p);
+  const digits = readDigits(masked, pos);
   if (digits.length === 0) {
     return undefined;
   }
   // Must be followed by whitespace or end-of-string
-  const afterDigits = p + digits.length;
+  const afterDigits = pos + digits.length;
   if (afterDigits < masked.length && !isWhitespace(masked[afterDigits])) {
     return undefined;
   }
@@ -213,16 +213,16 @@ function extractMinValue(content: string): number | undefined {
     return undefined;
   }
   // Skip whitespace after "@min"
-  let p = idx + '@min'.length;
-  while (p < masked.length && isWhitespace(masked[p])) {
-    p += 1;
+  let pos = idx + '@min'.length;
+  while (pos < masked.length && isWhitespace(masked[pos])) {
+    pos += 1;
   }
-  const digits = readDigits(masked, p);
+  const digits = readDigits(masked, pos);
   if (digits.length === 0) {
     return undefined;
   }
   // Must be followed by whitespace or end-of-string
-  const afterDigits = p + digits.length;
+  const afterDigits = pos + digits.length;
   if (afterDigits < masked.length && !isWhitespace(masked[afterDigits])) {
     return undefined;
   }
@@ -287,9 +287,9 @@ function extractQuotedString(content: string): string | undefined {
   }
   // Find first quoted substring anywhere
   for (let i = 0; i < content.length; i += 1) {
-    const ch = content[i];
-    if (ch === '"' || ch === "'") {
-      const close = content.indexOf(ch, i + 1);
+    const char = content[i];
+    if (char === '"' || char === "'") {
+      const close = content.indexOf(char, i + 1);
       if (close !== -1 && close > i + 1) {
         return content.slice(i + 1, close);
       }
@@ -306,9 +306,9 @@ function extractAllQuotedStrings(content: string): string[] {
   const results: string[] = [];
   let i = 0;
   while (i < content.length) {
-    const ch = content[i];
-    if (ch === '"' || ch === "'") {
-      const close = content.indexOf(ch, i + 1);
+    const char = content[i];
+    if (char === '"' || char === "'") {
+      const close = content.indexOf(char, i + 1);
       if (close !== -1 && close > i + 1) {
         results.push(content.slice(i + 1, close));
         i = close + 1;
diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
index abc8bced2..f3d2c4038 100644
--- a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
@@ -1,4 +1,3 @@
-import * as path from 'node:path';
 import type { Rule } from 'eslint';
 import type { ExportDefaultDeclaration, ExportNamedDeclaration, Node } from 'estree';
 import type { TSESTree } from '@typescript-eslint/utils';
@@ -287,7 +286,8 @@ export const lintJavascriptDemoFocus = {
           return;
         }
 
-        const filename = path.basename(context.filename, path.extname(context.filename));
+        const base = context.filename.split('/').pop() ?? context.filename;
+        const filename = base.includes('.') ? base.slice(0, base.lastIndexOf('.')) : base;
 
         // Strategy 1: find an exported function whose name matches the filename
         const filenameMatch = namedExportFunctions.find((fn) => fn.name === filename);
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
index 475858021..b5ed1c766 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
@@ -150,37 +150,41 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
     };
   }
 
-  function accumulateOverrides(ch: OverrideChannels, meta: EmphasisMeta | undefined): void {
+  function accumulateOverrides(channels: OverrideChannels, meta: EmphasisMeta | undefined): void {
     if (meta?.paddingFrameMaxSize !== undefined) {
       if (meta.focus) {
         if (meta.propagatedOverride) {
-          ch.propagatedFocusPadding ??= meta.paddingFrameMaxSize;
+          channels.propagatedFocusPadding ??= meta.paddingFrameMaxSize;
         } else {
-          ch.explicitFocusPadding ??= meta.paddingFrameMaxSize;
+          channels.explicitFocusPadding ??= meta.paddingFrameMaxSize;
         }
       } else {
-        ch.nonFocusPadding ??= meta.paddingFrameMaxSize;
+        channels.nonFocusPadding ??= meta.paddingFrameMaxSize;
       }
     }
     if (meta?.focusFramesMaxSize !== undefined) {
       if (meta.focus) {
         if (meta.propagatedOverride) {
-          ch.propagatedFocusMaxSize ??= meta.focusFramesMaxSize;
+          channels.propagatedFocusMaxSize ??= meta.focusFramesMaxSize;
         } else {
-          ch.explicitFocusMaxSize ??= meta.focusFramesMaxSize;
+          channels.explicitFocusMaxSize ??= meta.focusFramesMaxSize;
         }
       } else {
-        ch.nonFocusMaxSize ??= meta.focusFramesMaxSize;
+        channels.nonFocusMaxSize ??= meta.focusFramesMaxSize;
       }
     }
   }
 
-  function resolvePadding(ch: OverrideChannels): number | undefined {
-    return ch.explicitFocusPadding ?? ch.propagatedFocusPadding ?? ch.nonFocusPadding;
+  function resolvePadding(channels: OverrideChannels): number | undefined {
+    return (
+      channels.explicitFocusPadding ?? channels.propagatedFocusPadding ?? channels.nonFocusPadding
+    );
   }
 
-  function resolveMaxSize(ch: OverrideChannels): number | undefined {
-    return ch.explicitFocusMaxSize ?? ch.propagatedFocusMaxSize ?? ch.nonFocusMaxSize;
+  function resolveMaxSize(channels: OverrideChannels): number | undefined {
+    return (
+      channels.explicitFocusMaxSize ?? channels.propagatedFocusMaxSize ?? channels.nonFocusMaxSize
+    );
   }
 
   let regionStart = sortedLines[0];
@@ -189,8 +193,8 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
   let hasFocus = firstMeta?.focus ?? false;
   let hasLineHighlight = firstMeta?.lineHighlight ?? false;
   let allLinesHighlighted = firstMeta?.lineHighlight ?? false;
-  let ch = emptyChannels();
-  accumulateOverrides(ch, firstMeta);
+  let channels = emptyChannels();
+  accumulateOverrides(channels, firstMeta);
 
   for (let i = 1; i < sortedLines.length; i += 1) {
     const line = sortedLines[i];
@@ -206,7 +210,7 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
       } else {
         allLinesHighlighted = false;
       }
-      accumulateOverrides(ch, meta);
+      accumulateOverrides(channels, meta);
     } else {
       // Gap found, close current region and start a new one
       regions.push({
@@ -216,8 +220,8 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
         focused: hasFocus,
         hasLineHighlight,
         allLinesHighlighted,
-        paddingFrameMaxSize: resolvePadding(ch),
-        focusFramesMaxSize: resolveMaxSize(ch),
+        paddingFrameMaxSize: resolvePadding(channels),
+        focusFramesMaxSize: resolveMaxSize(channels),
       });
       regionStart = line;
       regionEnd = line;
@@ -225,21 +229,21 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
       hasFocus = meta?.focus ?? false;
       hasLineHighlight = meta?.lineHighlight ?? false;
       allLinesHighlighted = meta?.lineHighlight ?? false;
-      ch = emptyChannels();
-      accumulateOverrides(ch, meta);
+      channels = emptyChannels();
+      accumulateOverrides(channels, meta);
     }
   }
 
   // Close the last region
   regions.push({
-    paddingFrameMaxSize: resolvePadding(ch),
+    paddingFrameMaxSize: resolvePadding(channels),
     startLine: regionStart,
     endLine: regionEnd,
     index: regions.length,
     focused: hasFocus,
     hasLineHighlight,
     allLinesHighlighted,
-    focusFramesMaxSize: resolveMaxSize(ch),
+    focusFramesMaxSize: resolveMaxSize(channels),
   });
 
   return regions;

From 0aa152c64d9fbbe8516b69cb9ad5ee77d52efbba Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 16:34:08 -0400
Subject: [PATCH 19/44] Code review

---
 .../lintJavascriptDemoFocus.test.ts           | 34 +++++++++++++++++++
 .../lintJavascriptDemoFocus.ts                |  9 ++---
 2 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
index fbb7831fa..c2913fd24 100644
--- a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
@@ -78,8 +78,42 @@ export default function Demo() {
 export const theme = createTheme({ palette: { primary: 'red' } });
           `,
         },
+        // File already has standalone @focus in a comment — skip
+        {
+          code: `
+// @focus
+export default function Demo() {
+  return <div>Hello</div>;
+}
+          `,
+        },
       ],
       invalid: [
+        // @focused in a comment should NOT cause skip (not a valid directive)
+        {
+          code: `// @focused
+export default function Demo() {
+  return <Button>Click</Button>;
+}`,
+          output: `// @focused
+export default function Demo() {
+  // @focus
+  return <Button>Click</Button>;
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // Named export with Windows-style backslash path should match filename
+        {
+          filename: 'C:\\Users\\dev\\demos\\CheckboxBasic.tsx',
+          code: `export function CheckboxBasic() {
+  return <Checkbox />;
+}`,
+          output: `export function CheckboxBasic() {
+  // @focus
+  return <Checkbox />;
+}`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
         // @highlight in a string literal should NOT cause skip
         {
           code: `export default function Demo() {
diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
index f3d2c4038..518e72550 100644
--- a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
@@ -201,10 +201,11 @@ export const lintJavascriptDemoFocus = {
     // preview area.
     // We check actual parsed comments (not raw source text) to avoid false
     // negatives from tokens appearing in string literals or identifiers.
-    // We use includes('@focus') rather than startsWith because @focus can
-    // appear as a modifier on @highlight-start (e.g. "@highlight-start @focus").
+    // The regex matches @focus, @focus-start, and @focus-end as standalone
+    // tokens (not as substrings of other words or prose).
+    const focusDirectivePattern = /(?:^|\s)@focus(?:-(?:start|end))?(?:\s|$)/;
     const hasFocusComment = sourceCode.getAllComments().some((comment) => {
-      return comment.value.includes('@focus');
+      return focusDirectivePattern.test(comment.value);
     });
 
     if (hasFocusComment) {
@@ -286,7 +287,7 @@ export const lintJavascriptDemoFocus = {
           return;
         }
 
-        const base = context.filename.split('/').pop() ?? context.filename;
+        const base = context.filename.split(/[/\\]/).pop() ?? context.filename;
         const filename = base.includes('.') ? base.slice(0, base.lastIndexOf('.')) : base;
 
         // Strategy 1: find an exported function whose name matches the filename

From 0a74df37d5ffa550be22ed1b537bdff8fc30cfaa Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 18:14:00 -0400
Subject: [PATCH 20/44] Code review

---
 .../lintJavascriptDemoFocus.test.ts           | 21 ++++++++++++
 .../lintJavascriptDemoFocus.ts                | 32 ++++++++++++++++++-
 .../parseSource/calculateFrameRanges.test.ts  |  7 ++--
 3 files changed, 56 insertions(+), 4 deletions(-)

diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
index c2913fd24..976226156 100644
--- a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
@@ -549,6 +549,27 @@ export function Primary() {
 }`,
           errors: [{ messageId: 'missingDemoFocusJsSingle' }],
         },
+        // wrapReturn: default export implicit-return arrow — wraps in parens
+        {
+          options: [{ wrapReturn: true }],
+          code: `export default () => <Button>Click</Button>`,
+          output: `export default () => (
+  // @focus
+  <Button>Click</Button>
+)`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
+        // wrapReturn: named export implicit-return arrow — wraps in parens
+        {
+          options: [{ wrapReturn: true }],
+          filename: 'CheckboxRed.tsx',
+          code: `export const CheckboxRed = () => <Checkbox defaultChecked />;`,
+          output: `export const CheckboxRed = () => (
+  // @focus
+  <Checkbox defaultChecked />
+);`,
+          errors: [{ messageId: 'missingDemoFocusJsSingle' }],
+        },
       ],
     });
   });
diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
index 518e72550..9741d5529 100644
--- a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
@@ -344,7 +344,7 @@ function reportPreview(
         ];
       }
 
-      // Non-wrapper: wrapReturn wraps bare `return <X>` in `return (\n  // comment\n  <X>\n)`
+      // Non-wrapper: wrapReturn with explicit return wraps `return <X>` into `return (\n  // comment\n  <X>\n)`
       if (options.wrapReturn && returnStatement) {
         const hasParens = hasReturnParens(sourceCode, returnStatement);
 
@@ -405,6 +405,36 @@ function reportPreview(
         ];
       }
 
+      // Non-wrapper: wrapReturn with implicit-return arrow — wrap expression in parens with comment.
+      // `returnStatement` is null for implicit-return arrow functions (`() => <X />`).
+      if (options.wrapReturn && !returnStatement) {
+        const arrowToken = sourceCode.getTokenBefore(firstNode as Rule.Node);
+        if (arrowToken?.value === '=>') {
+          const arrowIndentation =
+            sourceCode.lines[arrowToken.loc.start.line - 1].match(/^\s*/)?.[0] ?? '';
+          const innerIndentation = `${arrowIndentation}  `;
+          if (isSingleLine) {
+            return [
+              fixer.replaceTextRange(
+                [arrowToken.range[1], firstNode.range[0]],
+                ` (\n${innerIndentation}// @focus\n${innerIndentation}`,
+              ),
+              fixer.insertTextAfterRange(lastNode.range, `\n${arrowIndentation})`),
+            ];
+          }
+          return [
+            fixer.replaceTextRange(
+              [arrowToken.range[1], firstNode.range[0]],
+              ` (\n${innerIndentation}// @focus-start\n${innerIndentation}`,
+            ),
+            fixer.insertTextAfterRange(
+              lastNode.range,
+              `\n${innerIndentation}// @focus-end\n${arrowIndentation})`,
+            ),
+          ];
+        }
+      }
+
       // Default non-wrapper: insert JS comment at the start of the line
       const lineStartOffset = sourceCode.getIndexFromLoc({
         line: firstNode.loc.start.line,
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
index 41bd1d4ca..090131476 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
@@ -577,8 +577,9 @@ describe('calculateFrameRanges', () => {
       ]);
     });
 
-    it('should use the default focusFramesMaxSize when it is not set', () => {
-      const result = calculateFrameRanges(new Map(), DEFAULT_FOCUS_FRAMES_MAX_SIZE + 3, {});
+    it('should truncate using the default focusFramesMaxSize when not explicitly set', () => {
+      const totalLines = DEFAULT_FOCUS_FRAMES_MAX_SIZE + 3;
+      const result = calculateFrameRanges(new Map(), totalLines, {});
 
       expect(result).toEqual<FrameRange[]>([
         {
@@ -590,7 +591,7 @@ describe('calculateFrameRanges', () => {
         },
         {
           startLine: DEFAULT_FOCUS_FRAMES_MAX_SIZE + 1,
-          endLine: DEFAULT_FOCUS_FRAMES_MAX_SIZE + 3,
+          endLine: totalLines,
           type: 'normal',
         },
       ]);

From 5cc9c027727b43abaf29c49f7248f2045e62b10d Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 18:40:11 -0400
Subject: [PATCH 21/44] Fix framing on unknown languages

---
 .../loadCodeVariant/loadCodeVariant.test.ts   | 44 +++++++++++----
 .../loadCodeVariant/loadCodeVariant.ts        | 37 ++++++------
 .../pipeline/parseSource/parseSource.test.ts  | 56 +++++++------------
 .../src/pipeline/parseSource/parseSource.ts   | 10 +++-
 4 files changed, 80 insertions(+), 67 deletions(-)

diff --git a/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.test.ts b/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.test.ts
index 2ce06655b..8639adb73 100644
--- a/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.test.ts
+++ b/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.test.ts
@@ -248,7 +248,7 @@ describe('loadCodeVariant', () => {
       consoleWarnSpy.mockRestore();
     });
 
-    it('should return code as-is when no fileName and no URL provided', async () => {
+    it('should return guttered HAST when no fileName, no URL, and no language provided', async () => {
       const variant: VariantCode = {
         source: 'const x = 1;',
         // No fileName provided
@@ -266,19 +266,30 @@ describe('loadCodeVariant', () => {
         },
       );
 
+      // Without language, falls through to plain-text guttered path
       expect(result.code.source).toEqual({
         type: 'root',
+        data: { totalLines: 1 },
         children: [
           {
-            type: 'text',
-            value: 'const x = 1;',
+            type: 'element',
+            tagName: 'span',
+            properties: { className: 'frame', dataLined: '' },
+            children: [
+              {
+                type: 'element',
+                tagName: 'span',
+                properties: { className: 'line', dataLn: 1 },
+                children: [{ type: 'text', value: 'const x = 1;' }],
+              },
+            ],
           },
         ],
-      }); // Should have basic HAST node
-      expect(result.code.fileName).toBeUndefined(); // No fileName available
-      expect(result.dependencies).toEqual([]); // No URL, so no dependencies
-      expect(mockParseSource).not.toHaveBeenCalled(); // No parsing without fileName or language
-      expect(mockLoadSource).not.toHaveBeenCalled(); // No loading needed
+      });
+      expect(result.code.fileName).toBeUndefined();
+      expect(result.dependencies).toEqual([]);
+      expect(mockParseSource).not.toHaveBeenCalled(); // No language, so parseSource not used
+      expect(mockLoadSource).not.toHaveBeenCalled();
     });
 
     it('should parse source when language is provided but no fileName or URL', async () => {
@@ -1857,15 +1868,26 @@ export default function Button(props: ButtonProps) {
         },
       );
 
-      // Should return the code with basic HAST node since no processing can be done
+      // Should return the code with guttered HAST even when parsing is disabled
       expect(result.code).toEqual({
         fileName: undefined,
+        language: undefined,
         source: {
           type: 'root',
+          data: { totalLines: 1 },
           children: [
             {
-              type: 'text',
-              value: 'const x = 1;',
+              type: 'element',
+              tagName: 'span',
+              properties: { className: 'frame', dataLined: '' },
+              children: [
+                {
+                  type: 'element',
+                  tagName: 'span',
+                  properties: { className: 'line', dataLn: 1 },
+                  children: [{ type: 'text', value: 'const x = 1;' }],
+                },
+              ],
             },
           ],
         },
diff --git a/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.ts b/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.ts
index 0d1958e73..b7155ce56 100644
--- a/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.ts
+++ b/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.ts
@@ -20,6 +20,7 @@ import type {
   HastRoot,
 } from '../../CodeHighlighter/types';
 import { performanceMeasure } from '../loadPrecomputedCodeHighlighter/performanceLogger';
+import { starryNightGutter } from '../parseSource/addLineGutters';
 
 /**
  * Converts 0-indexed line numbers to 1-indexed for HAST compatibility.
@@ -760,24 +761,10 @@ export async function loadCodeVariant(
     // Parse the source if we have language and sourceParser
     if (typeof finalSource === 'string' && language && sourceParser && !disableParsing) {
       const parseSource = await sourceParser;
-      let parsedSource: HastRoot = parseSource(finalSource, '', language);
-
-      // Apply source enhancers if provided (run sequentially as a pipeline)
-      if (sourceEnhancers && sourceEnhancers.length > 0) {
-        // Convert comments from 0-indexed to 1-indexed for HAST compatibility
-        const oneIndexedComments = convertCommentsToOneIndexed(variant.comments);
-
-        parsedSource = await sourceEnhancers.reduce(async (accPromise, enhancer) => {
-          const acc = await accPromise;
-          const result = await enhancer(acc, oneIndexedComments, '');
-          return result;
-        }, Promise.resolve(parsedSource));
-      }
-
-      finalSource = parsedSource;
+      finalSource = parseSource(finalSource, '', language);
     } else if (typeof finalSource === 'string') {
-      // No language or parser - return as plain text
-      finalSource = {
+      // No language or parser - build plain-text HAST root with line gutters
+      const root: HastRoot = {
         type: 'root',
         children: [
           {
@@ -786,6 +773,22 @@ export async function loadCodeVariant(
           },
         ],
       };
+      const sourceLines = (finalSource || '').split(/\r?\n|\r/);
+      starryNightGutter(root, sourceLines);
+      finalSource = root;
+    }
+
+    // Apply source enhancers if provided and parsing is not disabled
+    if (!disableParsing && sourceEnhancers && sourceEnhancers.length > 0) {
+      const oneIndexedComments = convertCommentsToOneIndexed(variant.comments);
+
+      finalSource = await sourceEnhancers.reduce(
+        async (accPromise, enhancer) => {
+          const acc = await accPromise;
+          return enhancer(acc, oneIndexedComments, '');
+        },
+        Promise.resolve(finalSource as HastRoot),
+      );
     }
 
     const finalVariant: VariantCode = {
diff --git a/packages/docs-infra/src/pipeline/parseSource/parseSource.test.ts b/packages/docs-infra/src/pipeline/parseSource/parseSource.test.ts
index 019596d09..673600de8 100644
--- a/packages/docs-infra/src/pipeline/parseSource/parseSource.test.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/parseSource.test.ts
@@ -53,60 +53,44 @@ describe('parseSource', () => {
     const source = 'This is some unknown content';
     const result = parseSource(source, 'unknown.xyz') as Root;
 
-    expect(result).toEqual({
-      type: 'root',
-      children: [
-        {
-          type: 'text',
-          value: source,
-        },
-      ],
-    });
+    // Unsupported file types still get line gutters for enhancer compatibility
+    expect(result.type).toBe('root');
+    expect((result.data as { totalLines?: number })?.totalLines).toBe(1);
+    // Should have a frame > line > text structure
+    const frame = result.children[0] as Element;
+    expect(frame.type).toBe('element');
+    expect(frame.properties?.className).toBe('frame');
+    const line = frame.children.find(
+      (child): child is Element =>
+        child.type === 'element' && child.properties?.className === 'line',
+    );
+    expect(line).toBeDefined();
+    expect(line!.children).toEqual([{ type: 'text', value: source }]);
   });
 
   it('should handle file without extension gracefully', async () => {
     const source = 'Content without extension';
     const result = parseSource(source, 'README') as Root;
 
-    expect(result).toEqual({
-      type: 'root',
-      children: [
-        {
-          type: 'text',
-          value: source,
-        },
-      ],
-    });
+    expect(result.type).toBe('root');
+    expect((result.data as { totalLines?: number })?.totalLines).toBe(1);
   });
 
   it('should handle empty content gracefully', async () => {
     const source = '';
     const result = parseSource(source, 'empty.txt') as Root;
 
-    expect(result).toEqual({
-      type: 'root',
-      children: [
-        {
-          type: 'text',
-          value: source,
-        },
-      ],
-    });
+    expect(result.type).toBe('root');
+    // Empty content still gets line gutters (1 empty line)
+    expect((result.data as { totalLines?: number })?.totalLines).toBe(1);
   });
 
   it('should handle content with special characters gracefully', async () => {
     const source = 'Content with symbols: @#$%^&*()';
     const result = parseSource(source, 'special.unknown') as Root;
 
-    expect(result).toEqual({
-      type: 'root',
-      children: [
-        {
-          type: 'text',
-          value: source,
-        },
-      ],
-    });
+    expect(result.type).toBe('root');
+    expect((result.data as { totalLines?: number })?.totalLines).toBe(1);
   });
 
   it('should parse JavaScript content normally', async () => {
diff --git a/packages/docs-infra/src/pipeline/parseSource/parseSource.ts b/packages/docs-infra/src/pipeline/parseSource/parseSource.ts
index b33c3bc00..82d109e1a 100644
--- a/packages/docs-infra/src/pipeline/parseSource/parseSource.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/parseSource.ts
@@ -37,9 +37,10 @@ export const parseSource: ParseSource = (source, fileName, language) => {
   }
 
   if (!grammarScope) {
-    // Return a basic HAST root node with the source text for unsupported file types
-    // TODO: should we split and add line gutters?
-    return {
+    // Return a basic HAST root node with the source text for unsupported file types.
+    // Still add line gutters so that the enhancer pipeline (e.g. auto-focus frames)
+    // can operate on the resulting tree.
+    const root: ReturnType<ParseSource> = {
       type: 'root',
       children: [
         {
@@ -48,6 +49,9 @@ export const parseSource: ParseSource = (source, fileName, language) => {
         },
       ],
     };
+    const sourceLines = source.split(/\r?\n|\r/);
+    starryNightGutter(root, sourceLines);
+    return root;
   }
 
   const highlighted = starryNight.highlight(source, grammarScope);

From b9d537cc53add5c9056b4e3d7a2c39cda41985bc Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 19:07:06 -0400
Subject: [PATCH 22/44] Add collapsible indicator

---
 .../components/code-highlighter/types.md      |  2 +-
 .../docs-infra/src/CodeHighlighter/types.ts   |  2 +-
 .../enhanceCodeEmphasis.ts                    | 30 ++++++++++++++++++-
 packages/docs-infra/src/useCode/Pre.tsx       |  7 ++++-
 4 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/docs/app/docs-infra/components/code-highlighter/types.md b/docs/app/docs-infra/components/code-highlighter/types.md
index 05c3cc2bf..59c046776 100644
--- a/docs/app/docs-infra/components/code-highlighter/types.md
+++ b/docs/app/docs-infra/components/code-highlighter/types.md
@@ -610,7 +610,7 @@ type Externals = { [key: string]: ExternalImportItem[] };
 ### HastRoot
 
 ```typescript
-type HastRoot = { data?: RootData & { totalLines?: number } };
+type HastRoot = { data?: RootData & { totalLines?: number; collapsible?: boolean } };
 ```
 
 ### LoadFallbackCodeOptions
diff --git a/packages/docs-infra/src/CodeHighlighter/types.ts b/packages/docs-infra/src/CodeHighlighter/types.ts
index af15c23fa..bfb312717 100644
--- a/packages/docs-infra/src/CodeHighlighter/types.ts
+++ b/packages/docs-infra/src/CodeHighlighter/types.ts
@@ -24,7 +24,7 @@ export interface ExternalImportItem {
 export type Externals = Record<string, ExternalImportItem[]>;
 
 export interface HastRoot extends Root {
-  data?: RootData & { totalLines?: number };
+  data?: RootData & { totalLines?: number; collapsible?: boolean };
 }
 
 export type VariantSource = string | HastRoot | { hastJson: string } | { hastCompressed: string };
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
index 6bdfe75c0..372d82ff1 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
@@ -1,7 +1,7 @@
 import type { Element, ElementContent } from 'hast';
 import type { HastRoot, SourceComments, SourceEnhancer } from '../../CodeHighlighter/types';
 import { getHastTextContent } from '../loadServerTypes/hastTypeUtils';
-import type { EmphasisMeta, EnhanceCodeEmphasisOptions } from '../parseSource/calculateFrameRanges';
+import type { EmphasisMeta, EnhanceCodeEmphasisOptions, FrameRange } from '../parseSource/calculateFrameRanges';
 import { calculateFrameRanges } from '../parseSource/calculateFrameRanges';
 import { calculateFrameIndent } from './calculateFrameIndent';
 import { restructureFrames } from '../parseSource/restructureFrames';
@@ -1475,6 +1475,32 @@ export function createEnhanceCodeEmphasis(
   options: EnhanceCodeEmphasisOptions = {},
 ): SourceEnhancer {
   return (root: HastRoot, comments: SourceComments | undefined): HastRoot => {
+    // Helper: mark root as collapsible when hidden and visible emphasis frames coexist
+    function markCollapsible(frameRanges: FrameRange[]) {
+      let hasHidden = false;
+      let hasVisible = false;
+      for (const range of frameRanges) {
+        if (
+          range.type === 'normal' ||
+          range.type === 'highlighted-unfocused' ||
+          range.type === 'focus-unfocused'
+        ) {
+          hasHidden = true;
+        } else if (
+          range.type === 'highlighted' ||
+          range.type === 'focus' ||
+          range.type === 'padding-top' ||
+          range.type === 'padding-bottom'
+        ) {
+          hasVisible = true;
+        }
+        if (hasHidden && hasVisible) {
+          root.data = { ...root.data, collapsible: true };
+          return;
+        }
+      }
+    }
+
     // Step 1: Parse directives from comments (no tree traversal)
     const directives =
       comments && Object.keys(comments).length > 0 ? parseEmphasisDirectives(comments) : [];
@@ -1490,6 +1516,7 @@ export function createEnhanceCodeEmphasis(
       // Auto-focus path: no emphasis, just frame restructuring
       const frameRanges = calculateFrameRanges(new Map(), totalLines, effectiveOptions);
       restructureFrames(root, frameRanges, new Map());
+      markCollapsible(frameRanges);
       return root;
     }
 
@@ -1527,6 +1554,7 @@ export function createEnhanceCodeEmphasis(
 
     // Step 7: Restructure frames (flat iteration, not deep recursive traversal)
     restructureFrames(root, frameRanges, regionIndentLevels);
+    markCollapsible(frameRanges);
 
     // Step 8: Reconcile line-level data-hl with frame types and promote descriptions
     reconcileLineAndFrameEmphasis(root, emphasizedLines);
diff --git a/packages/docs-infra/src/useCode/Pre.tsx b/packages/docs-infra/src/useCode/Pre.tsx
index cd8592547..6102cc0ae 100644
--- a/packages/docs-infra/src/useCode/Pre.tsx
+++ b/packages/docs-infra/src/useCode/Pre.tsx
@@ -230,9 +230,14 @@ export function Pre({
     });
   }, [hast, observeFrame, shouldHighlight, visibleFrames]);
 
+  const hasCollapsibleFrames = hast?.data?.collapsible === true;
+
   return (
     <pre ref={bindIntersectionObserver} className={className}>
-      <code className={language ? `language-${language}` : undefined}>
+      <code
+        className={language ? `language-${language}` : undefined}
+        data-collapsible={hasCollapsibleFrames ? '' : undefined}
+      >
         {typeof children === 'string' ? children : frames}
       </code>
     </pre>

From 0fb4832151ff3605a1148a61352ff93079d40de3 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 20:14:24 -0400
Subject: [PATCH 23/44] Maintain max frame size

---
 .../components/code-highlighter/types.md      |   4 +-
 .../docs-infra/src/CodeHighlighter/types.ts   |   2 +-
 .../enhanceCodeEmphasis.ts                    |  18 ++-
 .../parseSource/addLineGutters.test.ts        |   4 +
 .../pipeline/parseSource/addLineGutters.ts    |   4 +
 .../parseSource/calculateFrameRanges.test.ts  | 108 ++++++++++++++++++
 .../parseSource/calculateFrameRanges.ts       |  51 ++++++++-
 7 files changed, 181 insertions(+), 10 deletions(-)

diff --git a/docs/app/docs-infra/components/code-highlighter/types.md b/docs/app/docs-infra/components/code-highlighter/types.md
index 59c046776..5e9e550d1 100644
--- a/docs/app/docs-infra/components/code-highlighter/types.md
+++ b/docs/app/docs-infra/components/code-highlighter/types.md
@@ -610,7 +610,9 @@ type Externals = { [key: string]: ExternalImportItem[] };
 ### HastRoot
 
 ```typescript
-type HastRoot = { data?: RootData & { totalLines?: number; collapsible?: boolean } };
+type HastRoot = {
+  data?: RootData & { totalLines?: number; collapsible?: boolean; frameSize?: number };
+};
 ```
 
 ### LoadFallbackCodeOptions
diff --git a/packages/docs-infra/src/CodeHighlighter/types.ts b/packages/docs-infra/src/CodeHighlighter/types.ts
index bfb312717..a64364220 100644
--- a/packages/docs-infra/src/CodeHighlighter/types.ts
+++ b/packages/docs-infra/src/CodeHighlighter/types.ts
@@ -24,7 +24,7 @@ export interface ExternalImportItem {
 export type Externals = Record<string, ExternalImportItem[]>;
 
 export interface HastRoot extends Root {
-  data?: RootData & { totalLines?: number; collapsible?: boolean };
+  data?: RootData & { totalLines?: number; collapsible?: boolean; frameSize?: number };
 }
 
 export type VariantSource = string | HastRoot | { hastJson: string } | { hastCompressed: string };
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
index 372d82ff1..4e30db91c 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
@@ -1,7 +1,11 @@
 import type { Element, ElementContent } from 'hast';
 import type { HastRoot, SourceComments, SourceEnhancer } from '../../CodeHighlighter/types';
 import { getHastTextContent } from '../loadServerTypes/hastTypeUtils';
-import type { EmphasisMeta, EnhanceCodeEmphasisOptions, FrameRange } from '../parseSource/calculateFrameRanges';
+import type {
+  EmphasisMeta,
+  EnhanceCodeEmphasisOptions,
+  FrameRange,
+} from '../parseSource/calculateFrameRanges';
 import { calculateFrameRanges } from '../parseSource/calculateFrameRanges';
 import { calculateFrameIndent } from './calculateFrameIndent';
 import { restructureFrames } from '../parseSource/restructureFrames';
@@ -1512,9 +1516,18 @@ export function createEnhanceCodeEmphasis(
     const lineElements = buildLineElementMap(root);
     const totalLines = (root.data as { totalLines?: number })?.totalLines ?? lineElements.size;
 
+    // Read frameSize from HAST (set by starryNightGutter when it splits frames)
+    // so emphasis reframing matches the original gutter split size
+    const normalFrameMaxSize = root.data?.frameSize;
+
     if (!hasDirectives) {
       // Auto-focus path: no emphasis, just frame restructuring
-      const frameRanges = calculateFrameRanges(new Map(), totalLines, effectiveOptions);
+      const frameRanges = calculateFrameRanges(
+        new Map(),
+        totalLines,
+        effectiveOptions,
+        normalFrameMaxSize,
+      );
       restructureFrames(root, frameRanges, new Map());
       markCollapsible(frameRanges);
       return root;
@@ -1550,6 +1563,7 @@ export function createEnhanceCodeEmphasis(
       frameEmphasizedLines.size > 0 ? frameEmphasizedLines : new Map(),
       totalLines,
       effectiveOptions,
+      normalFrameMaxSize,
     );
 
     // Step 7: Restructure frames (flat iteration, not deep recursive traversal)
diff --git a/packages/docs-infra/src/pipeline/parseSource/addLineGutters.test.ts b/packages/docs-infra/src/pipeline/parseSource/addLineGutters.test.ts
index f1d8e31fb..e8a1a6f7a 100644
--- a/packages/docs-infra/src/pipeline/parseSource/addLineGutters.test.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/addLineGutters.test.ts
@@ -35,6 +35,8 @@ describe('starryNightGutter', () => {
       },
     ]);
     expect((tree.data as any)?.totalLines).toBe(1);
+    // frameSize should not be set when there is only one frame
+    expect((tree.data as any)?.frameSize).toBeUndefined();
   });
 
   it('should handle text with single line break', () => {
@@ -705,6 +707,8 @@ describe('starryNightGutter', () => {
 
     // Verify total line count
     expect((tree.data as any)?.totalLines).toBe(250);
+    // Verify frameSize is stored when frames are split
+    expect((tree.data as any)?.frameSize).toBe(120);
   });
 });
 
diff --git a/packages/docs-infra/src/pipeline/parseSource/addLineGutters.ts b/packages/docs-infra/src/pipeline/parseSource/addLineGutters.ts
index 8719d2f7f..52fe22df5 100644
--- a/packages/docs-infra/src/pipeline/parseSource/addLineGutters.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/addLineGutters.ts
@@ -169,6 +169,10 @@ export function starryNightGutter(
     tree.data = {};
   }
   (tree.data as any).totalLines = lineNumber;
+  // Store the frame size used for splitting so downstream enhancers can match it
+  if (replacement.length > 1) {
+    (tree.data as any).frameSize = frameSize;
+  }
 }
 
 function createLine(children: Array<ElementContent>, line: number): Element {
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
index 090131476..c06bd052d 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
@@ -844,4 +844,112 @@ describe('calculateFrameRanges', () => {
       ]);
     });
   });
+
+  describe('normalFrameMaxSize', () => {
+    it('should split oversized normal frames in auto-focus path', () => {
+      const result = calculateFrameRanges(
+        new Map(),
+        30,
+        {
+          focusFramesMaxSize: 10,
+        },
+        8,
+      );
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 10, type: 'focus', regionIndex: 0, truncated: 'visible' },
+        { startLine: 11, endLine: 18, type: 'normal' },
+        { startLine: 19, endLine: 26, type: 'normal' },
+        { startLine: 27, endLine: 30, type: 'normal' },
+      ]);
+    });
+
+    it('should split normal frames between regions', () => {
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [3, { lineHighlight: true }],
+        [20, { lineHighlight: true }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 25, {}, 5);
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 2, type: 'normal' },
+        { startLine: 3, endLine: 3, type: 'highlighted', regionIndex: 0 },
+        { startLine: 4, endLine: 8, type: 'normal' },
+        { startLine: 9, endLine: 13, type: 'normal' },
+        { startLine: 14, endLine: 18, type: 'normal' },
+        { startLine: 19, endLine: 19, type: 'normal' },
+        { startLine: 20, endLine: 20, type: 'highlighted-unfocused', regionIndex: 1 },
+        { startLine: 21, endLine: 25, type: 'normal' },
+      ]);
+    });
+
+    it('should not split normal frames when they are within the limit', () => {
+      const result = calculateFrameRanges(
+        new Map(),
+        10,
+        {
+          focusFramesMaxSize: 5,
+        },
+        10,
+      );
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 5, type: 'focus', regionIndex: 0, truncated: 'visible' },
+        { startLine: 6, endLine: 10, type: 'normal' },
+      ]);
+    });
+
+    it('should not affect non-normal frame types', () => {
+      const emphasizedLines = new Map<number, EmphasisMeta>([
+        [1, { lineHighlight: true, focus: true }],
+        [2, { lineHighlight: true, focus: true }],
+        [3, { lineHighlight: true, focus: true }],
+        [4, { lineHighlight: true, focus: true }],
+        [5, { lineHighlight: true, focus: true }],
+        [6, { lineHighlight: true, focus: true }],
+        [7, { lineHighlight: true, focus: true }],
+        [8, { lineHighlight: true, focus: true }],
+        [9, { lineHighlight: true, focus: true }],
+        [10, { lineHighlight: true, focus: true }],
+      ]);
+
+      const result = calculateFrameRanges(emphasizedLines, 10, {}, 3);
+
+      // Single highlighted frame, not split even though > 3 lines
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 10, type: 'highlighted', regionIndex: 0 },
+      ]);
+    });
+
+    it('should handle normalFrameMaxSize of 1', () => {
+      const result = calculateFrameRanges(
+        new Map(),
+        5,
+        {
+          focusFramesMaxSize: 2,
+        },
+        1,
+      );
+
+      expect(result).toEqual<FrameRange[]>([
+        { startLine: 1, endLine: 2, type: 'focus', regionIndex: 0, truncated: 'visible' },
+        { startLine: 3, endLine: 3, type: 'normal' },
+        { startLine: 4, endLine: 4, type: 'normal' },
+        { startLine: 5, endLine: 5, type: 'normal' },
+      ]);
+    });
+
+    it('should throw for invalid normalFrameMaxSize', () => {
+      expect(() => calculateFrameRanges(new Map(), 10, {}, 0)).toThrow(
+        'normalFrameMaxSize must be a finite number >= 1',
+      );
+      expect(() => calculateFrameRanges(new Map(), 10, {}, -1)).toThrow(
+        'normalFrameMaxSize must be a finite number >= 1',
+      );
+      expect(() => calculateFrameRanges(new Map(), 10, {}, Infinity)).toThrow(
+        'normalFrameMaxSize must be a finite number >= 1',
+      );
+    });
+  });
 });
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
index b5ed1c766..bc4979c1b 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
@@ -348,12 +348,16 @@ function calculateFocusWindow(
  * @param emphasizedLines - Map of line numbers to their emphasis metadata
  * @param totalLines - Total number of lines in the code block
  * @param options - Optional padding configuration
+ * @param normalFrameMaxSize - Maximum lines per normal frame. Read from `hast.data.frameSize`
+ *   (set by `starryNightGutter` when it splits a tree into multiple frames) so that emphasis
+ *   reframing matches the original gutter split size.
  * @returns Ordered array of frame ranges covering all lines
  */
 export function calculateFrameRanges(
   emphasizedLines: Map<number, EmphasisMeta>,
   totalLines: number,
   options: EnhanceCodeEmphasisOptions = {},
+  normalFrameMaxSize?: number,
 ): FrameRange[] {
   const effectiveFocusFramesMaxSize = options.focusFramesMaxSize ?? DEFAULT_FOCUS_FRAMES_MAX_SIZE;
 
@@ -373,6 +377,12 @@ export function calculateFrameRanges(
       `paddingFrameMaxSize must be a finite number >= 0, got ${options.paddingFrameMaxSize}`,
     );
   }
+  if (
+    normalFrameMaxSize !== undefined &&
+    (!Number.isFinite(normalFrameMaxSize) || normalFrameMaxSize < 1)
+  ) {
+    throw new Error(`normalFrameMaxSize must be a finite number >= 1, got ${normalFrameMaxSize}`);
+  }
 
   if (totalLines <= 0) {
     return [];
@@ -385,7 +395,7 @@ export function calculateFrameRanges(
     // If focusFramesMaxSize is set and the code exceeds it, truncate.
     const autoFocusMax = effectiveFocusFramesMaxSize;
     if (autoFocusMax !== undefined && totalLines > autoFocusMax) {
-      return [
+      const autoFrames: FrameRange[] = [
         {
           startLine: 1,
           endLine: autoFocusMax,
@@ -393,12 +403,21 @@ export function calculateFrameRanges(
           regionIndex: 0,
           truncated: 'visible',
         },
-        {
-          startLine: autoFocusMax + 1,
-          endLine: totalLines,
-          type: 'normal',
-        },
       ];
+      // Split the trailing normal frame if normalFrameMaxSize is set
+      const normalStart = autoFocusMax + 1;
+      if (normalFrameMaxSize !== undefined && normalFrameMaxSize >= 1) {
+        const maxSize = normalFrameMaxSize;
+        let start = normalStart;
+        while (start <= totalLines) {
+          const end = Math.min(start + maxSize - 1, totalLines);
+          autoFrames.push({ startLine: start, endLine: end, type: 'normal' });
+          start = end + 1;
+        }
+      } else {
+        autoFrames.push({ startLine: normalStart, endLine: totalLines, type: 'normal' });
+      }
+      return autoFrames;
     }
     return [{ startLine: 1, endLine: totalLines, type: 'focus', regionIndex: 0 }];
   }
@@ -518,5 +537,25 @@ export function calculateFrameRanges(
     frames.push({ startLine: currentLine, endLine: totalLines, type: 'normal' });
   }
 
+  // Split oversized normal frames if normalFrameMaxSize is configured
+  if (normalFrameMaxSize !== undefined && normalFrameMaxSize >= 1) {
+    const maxSize = normalFrameMaxSize;
+    const splitFrames: FrameRange[] = [];
+    for (const frame of frames) {
+      const frameSize = frame.endLine - frame.startLine + 1;
+      if (frame.type === 'normal' && frameSize > maxSize) {
+        let start = frame.startLine;
+        while (start <= frame.endLine) {
+          const end = Math.min(start + maxSize - 1, frame.endLine);
+          splitFrames.push({ startLine: start, endLine: end, type: 'normal' });
+          start = end + 1;
+        }
+      } else {
+        splitFrames.push(frame);
+      }
+    }
+    return splitFrames;
+  }
+
   return frames;
 }

From e5a1e009fba9daa550538afd24cbad698f6cedf4 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 20:58:51 -0400
Subject: [PATCH 24/44] Take care of CSS for the example toggle

---
 .../demos/CollapsibleContent.module.css            |  7 ++++++-
 .../demos/CollapsibleDemoContent.module.css        |  7 ++++++-
 .../demos/IndentContent.module.css                 |  7 ++++++-
 .../pipeline/enhance-code-emphasis/page.mdx        | 14 ++++++++++++++
 4 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
index f9250a7e6..3ec5f6642 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
@@ -22,7 +22,7 @@
 }
 
 .toggle {
-  display: block;
+  display: none;
   width: 100%;
   padding: 6px;
   border: none;
@@ -36,6 +36,11 @@
   text-align: center;
 }
 
+/* Only show the toggle when the code block has collapsible frames */
+.code:has([data-collapsible]) ~ .toggle {
+  display: block;
+}
+
 .toggle:hover {
   background: #eae7ef;
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
index 6766c5b50..8fc3735e0 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
@@ -77,7 +77,7 @@
 }
 
 .toggle {
-  display: block;
+  display: none;
   width: 100%;
   padding: 6px;
   border: none;
@@ -91,6 +91,11 @@
   text-align: center;
 }
 
+/* Only show the toggle when the code block has collapsible frames */
+.code:has([data-collapsible]) ~ .toggle {
+  display: block;
+}
+
 .toggle:hover {
   background: #eae7ef;
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
index 9d7f1025d..f5d47935c 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
@@ -9,7 +9,7 @@
 }
 
 .toggle {
-  display: block;
+  display: none;
   width: 100%;
   padding: 6px;
   border: none;
@@ -22,6 +22,11 @@
   font-family: var(--font-geist-mono);
 }
 
+/* Only show the toggle when the code block has collapsible frames */
+.code:has([data-collapsible]) + .toggle {
+  display: block;
+}
+
 .toggle:hover {
   background: #eae7ef;
 }
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 a4c5b0be1..16922bd94 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
@@ -558,6 +558,20 @@ Target frame types with CSS to style highlighted frames and create collapsible c
 
 ### Collapsible Code Block
 
+When a code block has both visible frames (highlighted, focus, padding) and hidden frames (normal, unfocused), the `<code>` element receives a `data-collapsible` attribute. Use this to conditionally show an expand/collapse toggle — code blocks without collapsible frames won't render the button:
+
+```css
+/* Hide toggle by default */
+.toggle {
+  display: none;
+}
+
+/* Show only when the code block has collapsible frames */
+.pre code:has([data-collapsible]) ~ .toggle {
+  display: block;
+}
+```
+
 The following demo shows a code block that starts collapsed, revealing only the highlighted and padding frames. Click **Expand** to show the full source.
 
 import { DemoCollapsibleCode } from './demos/collapsible-code';

From af29f6f213d5af38a8f5643750ccf6b86c3f13f8 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 23:17:23 -0400
Subject: [PATCH 25/44] Improve expand and collapse animation

---
 .../demos/CollapsibleContent.module.css       | 39 ++++++++++--
 .../demos/CollapsibleDemoContent.module.css   | 39 ++++++++++--
 .../demos/IndentContent.module.css            | 60 ++++++++++++++-----
 .../pipeline/enhance-code-emphasis/page.mdx   | 33 ++++++++--
 4 files changed, 145 insertions(+), 26 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
index 3ec5f6642..e03324f8b 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
@@ -73,6 +73,8 @@ pre.codeBlock {
 
 .checkbox:checked ~ .code pre.codeBlock {
   overflow-x: auto;
+  transition: overflow-x 0s 1.5s;
+  transition-behavior: allow-discrete;
 }
 
 /* Code element inside pre — block so frames stretch to the widest line */
@@ -179,8 +181,22 @@ pre.codeBlock {
   overflow: hidden;
   opacity: 0;
   transition:
-    max-height 0.3s ease,
-    opacity 0.3s ease;
+    max-height 0.3s cubic-bezier(0.5, 0, 0, 1),
+    opacity 0.2s ease 0.1s;
+}
+
+@supports (interpolate-size: allow-keywords) {
+  .codeBlock :global(.frame:not([data-frame-type])),
+  .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+  .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+    interpolate-size: allow-keywords;
+    max-height: unset;
+    height: 0;
+    overflow: clip;
+    transition:
+      height 0.3s ease,
+      opacity 0.3s ease;
+  }
 }
 
 /* Padding frames appear dimmed when collapsed */
@@ -194,9 +210,24 @@ pre.codeBlock {
 .checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
-  max-height: 4500px;
-  overflow: visible;
+  max-height: 2220px;
   opacity: 1;
+  transition:
+    max-height 1.5s cubic-bezier(0.25, 0.46, 0.45, 0.94),
+    opacity 0.15s ease;
+}
+
+@supports (interpolate-size: allow-keywords) {
+  .checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
+  .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+  .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+    max-height: unset;
+    height: auto;
+    overflow: clip;
+    transition:
+      height 0.3s ease,
+      opacity 0.3s ease;
+  }
 }
 
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='padding-top']),
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
index 8fc3735e0..fb3fe07e9 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
@@ -128,6 +128,8 @@ pre.codeBlock {
 
 .checkbox:checked ~ .code pre.codeBlock {
   overflow-x: auto;
+  transition: overflow-x 0s 1.5s;
+  transition-behavior: allow-discrete;
 }
 
 /* Code element inside pre — block so frames stretch to the widest line */
@@ -242,8 +244,22 @@ pre.codeBlock {
   overflow: hidden;
   opacity: 0;
   transition:
-    max-height 0.3s ease,
-    opacity 0.3s ease;
+    max-height 0.3s cubic-bezier(0.5, 0, 0, 1),
+    opacity 0.2s ease 0.1s;
+}
+
+@supports (interpolate-size: allow-keywords) {
+  .codeBlock :global(.frame:not([data-frame-type])),
+  .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+  .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+    interpolate-size: allow-keywords;
+    max-height: unset;
+    height: 0;
+    overflow: clip;
+    transition:
+      height 0.3s ease,
+      opacity 0.3s ease;
+  }
 }
 
 /* Padding frames appear dimmed when collapsed */
@@ -257,9 +273,24 @@ pre.codeBlock {
 .checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
-  max-height: 4500px;
-  overflow: visible;
+  max-height: 2220px;
   opacity: 1;
+  transition:
+    max-height 1.5s cubic-bezier(0.25, 0.46, 0.45, 0.94),
+    opacity 0.15s ease;
+}
+
+@supports (interpolate-size: allow-keywords) {
+  .checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
+  .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+  .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+    max-height: unset;
+    height: auto;
+    overflow: clip;
+    transition:
+      height 0.3s ease,
+      opacity 0.3s ease;
+  }
 }
 
 .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='padding-top']),
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
index f5d47935c..50117afab 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
@@ -40,6 +40,8 @@ pre.codeBlock {
 
 .expanded pre.codeBlock {
   overflow-x: auto;
+  transition: overflow-x 0s 1.5s;
+  transition-behavior: allow-discrete;
 }
 
 /* Code element inside pre — block so frames stretch to the widest line */
@@ -146,17 +148,46 @@ pre.codeBlock {
   overflow: hidden;
   opacity: 0;
   transition:
-    max-height 0.3s ease,
-    opacity 0.3s ease;
+    max-height 0.3s cubic-bezier(0.5, 0, 0, 1),
+    opacity 0.2s ease 0.1s;
+}
+
+@supports (interpolate-size: allow-keywords) {
+  .codeBlock :global(.frame:not([data-frame-type])),
+  .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+  .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+    interpolate-size: allow-keywords;
+    max-height: unset;
+    height: 0;
+    overflow: clip;
+    transition:
+      height 0.3s ease,
+      opacity 0.3s ease;
+  }
 }
 
 /* When expanded, show all frames */
 .expanded .codeBlock :global(.frame:not([data-frame-type])),
 .expanded .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
 .expanded .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
-  max-height: 4500px;
-  overflow: visible;
+  max-height: 2220px;
   opacity: 1;
+  transition:
+    max-height 1.5s cubic-bezier(0.25, 0.46, 0.45, 0.94),
+    opacity 0.15s ease;
+}
+
+@supports (interpolate-size: allow-keywords) {
+  .expanded .codeBlock :global(.frame:not([data-frame-type])),
+  .expanded .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+  .expanded .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+    max-height: unset;
+    height: auto;
+    overflow: clip;
+    transition:
+      height 0.3s ease,
+      opacity 0.3s ease;
+  }
 }
 
 /* ---- Truncated frame fade-out (focusFramesMaxSize split) ---- */
@@ -169,54 +200,55 @@ pre.codeBlock {
 }
 
 /* ---- Indent shifting: move highlighted/focus frame left by its indent level ---- */
+/* Uses transform instead of margin-left to avoid layout reflow during height transitions */
 
 .codeBlock :global(.frame[data-frame-type='highlighted']),
 .codeBlock :global(.frame[data-frame-type='focus']) {
-  transition: margin-left 0.3s ease;
+  transition: transform 0.3s ease;
 }
 
 .codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='1']),
 .codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='1']) {
-  margin-left: -2ch;
+  transform: translateX(-2ch);
 }
 
 .codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='2']),
 .codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='2']) {
-  margin-left: -4ch;
+  transform: translateX(-4ch);
 }
 
 .codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='3']),
 .codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='3']) {
-  margin-left: -6ch;
+  transform: translateX(-6ch);
 }
 
 .codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='4']),
 .codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='4']) {
-  margin-left: -8ch;
+  transform: translateX(-8ch);
 }
 
 .codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='5']),
 .codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='5']) {
-  margin-left: -10ch;
+  transform: translateX(-10ch);
 }
 
 .codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='6']),
 .codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='6']) {
-  margin-left: -12ch;
+  transform: translateX(-12ch);
 }
 
 .codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='7']),
 .codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='7']) {
-  margin-left: -14ch;
+  transform: translateX(-14ch);
 }
 
 .codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='8']),
 .codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='8']) {
-  margin-left: -16ch;
+  transform: translateX(-16ch);
 }
 
 /* Reset indent shift when expanded */
 .expanded .codeBlock :global(.frame[data-frame-type='highlighted']),
 .expanded .codeBlock :global(.frame[data-frame-type='focus']) {
-  margin-left: 6px;
+  transform: translateX(0);
 }
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 16922bd94..f6627bde8 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
@@ -512,6 +512,21 @@ Target frame types with CSS to style highlighted frames and create collapsible c
     opacity 0.3s ease;
 }
 
+/* When supported, use interpolate-size for smoother height animation */
+@supports (interpolate-size: allow-keywords) {
+  .codeBlock .frame:not([data-frame-type]),
+  .codeBlock .frame[data-frame-type='highlighted-unfocused'],
+  .codeBlock .frame[data-frame-type='focus-unfocused'] {
+    interpolate-size: allow-keywords;
+    max-height: unset;
+    height: 0;
+    overflow-y: clip;
+    transition:
+      height 0.3s ease,
+      opacity 0.3s ease;
+  }
+}
+
 /* Padding frames appear dimmed when collapsed */
 .codeBlock .frame[data-frame-type='padding-top'],
 .codeBlock .frame[data-frame-type='padding-bottom'] {
@@ -528,6 +543,16 @@ Target frame types with CSS to style highlighted frames and create collapsible c
   opacity: 1;
 }
 
+@supports (interpolate-size: allow-keywords) {
+  .expanded .codeBlock .frame:not([data-frame-type]),
+  .expanded .codeBlock .frame[data-frame-type='highlighted-unfocused'],
+  .expanded .codeBlock .frame[data-frame-type='focus-unfocused'] {
+    max-height: unset;
+    height: auto;
+    overflow: unset;
+  }
+}
+
 .expanded .codeBlock .frame[data-frame-type='padding-top'],
 .expanded .codeBlock .frame[data-frame-type='padding-bottom'] {
   opacity: 1;
@@ -536,23 +561,23 @@ Target frame types with CSS to style highlighted frames and create collapsible c
 /* Use indent level to shift highlighted/focus frames left when collapsed */
 .codeBlock .frame[data-frame-type='highlighted'],
 .codeBlock .frame[data-frame-type='focus'] {
-  transition: margin-left 0.3s ease;
+  transition: transform 0.3s ease;
 }
 
 .codeBlock .frame[data-frame-type='highlighted'][data-frame-indent='1'],
 .codeBlock .frame[data-frame-type='focus'][data-frame-indent='1'] {
-  margin-left: -2ch;
+  transform: translateX(-2ch);
 }
 
 .codeBlock .frame[data-frame-type='highlighted'][data-frame-indent='2'],
 .codeBlock .frame[data-frame-type='focus'][data-frame-indent='2'] {
-  margin-left: -4ch;
+  transform: translateX(-4ch);
 }
 
 /* Reset indent shift when expanded */
 .expanded .codeBlock .frame[data-frame-type='highlighted'],
 .expanded .codeBlock .frame[data-frame-type='focus'] {
-  margin-left: 0;
+  transform: translateX(0);
 }
 ```
 

From f6fc98e2ca20b409084c16e8cc7a547263b6c598 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 23:18:47 -0400
Subject: [PATCH 26/44] Update doc

---
 .../pipeline/enhance-code-emphasis/page.mdx     | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

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 f6627bde8..7dd76a625 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
@@ -508,8 +508,8 @@ Target frame types with CSS to style highlighted frames and create collapsible c
   overflow: hidden;
   opacity: 0;
   transition:
-    max-height 0.3s ease,
-    opacity 0.3s ease;
+    max-height 0.3s cubic-bezier(0.5, 0, 0, 1),
+    opacity 0.2s ease 0.1s;
 }
 
 /* When supported, use interpolate-size for smoother height animation */
@@ -520,7 +520,7 @@ Target frame types with CSS to style highlighted frames and create collapsible c
     interpolate-size: allow-keywords;
     max-height: unset;
     height: 0;
-    overflow-y: clip;
+    overflow: clip;
     transition:
       height 0.3s ease,
       opacity 0.3s ease;
@@ -538,9 +538,11 @@ Target frame types with CSS to style highlighted frames and create collapsible c
 .expanded .codeBlock .frame:not([data-frame-type]),
 .expanded .codeBlock .frame[data-frame-type='highlighted-unfocused'],
 .expanded .codeBlock .frame[data-frame-type='focus-unfocused'] {
-  max-height: 4500px;
-  overflow: visible;
+  max-height: 2220px;
   opacity: 1;
+  transition:
+    max-height 1.5s cubic-bezier(0.25, 0.46, 0.45, 0.94),
+    opacity 0.15s ease;
 }
 
 @supports (interpolate-size: allow-keywords) {
@@ -549,7 +551,10 @@ Target frame types with CSS to style highlighted frames and create collapsible c
   .expanded .codeBlock .frame[data-frame-type='focus-unfocused'] {
     max-height: unset;
     height: auto;
-    overflow: unset;
+    overflow: clip;
+    transition:
+      height 0.3s ease,
+      opacity 0.3s ease;
   }
 }
 

From 33c0cb81d9b9372ace46d7eb3f6879f2a2c26159 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 16 Apr 2026 23:19:34 -0400
Subject: [PATCH 27/44] Add note

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

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 7dd76a625..aed60e8d4 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
@@ -535,6 +535,7 @@ Target frame types with CSS to style highlighted frames and create collapsible c
 }
 
 /* When expanded, show all frames */
+/* max-height = line height (18.5px) × max frame size (120 lines) = 2220px */
 .expanded .codeBlock .frame:not([data-frame-type]),
 .expanded .codeBlock .frame[data-frame-type='highlighted-unfocused'],
 .expanded .codeBlock .frame[data-frame-type='focus-unfocused'] {

From dc4aa5feccc1f97182457f47a3ab6d17dd7f0041 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 17 Apr 2026 19:43:44 -0400
Subject: [PATCH 28/44] Fix tab switch animation

---
 packages/docs-infra/src/useCode/useFileNavigation.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/docs-infra/src/useCode/useFileNavigation.tsx b/packages/docs-infra/src/useCode/useFileNavigation.tsx
index 05a5db43e..ba5810126 100644
--- a/packages/docs-infra/src/useCode/useFileNavigation.tsx
+++ b/packages/docs-infra/src/useCode/useFileNavigation.tsx
@@ -487,6 +487,7 @@ export function useFileNavigation({
 
       return (
         <Pre
+          key={selectedFileNameInternal ?? selectedVariant.fileName}
           className={preClassName}
           language={language}
           ref={preRef}

From fe3d9bd53267e307689019675ea3c5c9c6e2d304 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 17 Apr 2026 23:22:44 -0400
Subject: [PATCH 29/44] Improve scroll experience

---
 .../demos/CollapsibleContent.module.css       |  38 ++--
 .../demos/CollapsibleContent.tsx              |  21 +-
 .../demos/CollapsibleDemoContent.module.css   |  41 ++--
 .../demos/CollapsibleDemoContent.tsx          |  21 +-
 .../demos/IndentContent.module.css            |   3 +-
 .../demos/IndentContent.tsx                   |  13 +-
 .../demos/useScrollAnchor.ts                  | 190 ++++++++++++++++++
 7 files changed, 293 insertions(+), 34 deletions(-)
 create mode 100644 docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
index e03324f8b..55568113f 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
@@ -71,10 +71,8 @@ pre.codeBlock {
   overflow-x: hidden;
 }
 
-.checkbox:checked ~ .code pre.codeBlock {
+.container:has(.checkbox:checked) .code pre.codeBlock {
   overflow-x: auto;
-  transition: overflow-x 0s 1.5s;
-  transition-behavior: allow-discrete;
 }
 
 /* Code element inside pre — block so frames stretch to the widest line */
@@ -179,6 +177,7 @@ pre.codeBlock {
 .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 0;
   overflow: hidden;
+  overflow-anchor: none;
   opacity: 0;
   transition:
     max-height 0.3s cubic-bezier(0.5, 0, 0, 1),
@@ -207,9 +206,15 @@ pre.codeBlock {
 }
 
 /* When checkbox is checked (expanded), show all frames */
-.checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
-.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
-.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+.container:has(.checkbox:checked) .code .codeBlock :global(.frame:not([data-frame-type])),
+.container:has(.checkbox:checked)
+  .code
+  .codeBlock
+  :global(.frame[data-frame-type='highlighted-unfocused']),
+.container:has(.checkbox:checked)
+  .code
+  .codeBlock
+  :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 2220px;
   opacity: 1;
   transition:
@@ -218,9 +223,15 @@ pre.codeBlock {
 }
 
 @supports (interpolate-size: allow-keywords) {
-  .checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
-  .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
-  .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+  .container:has(.checkbox:checked) .code .codeBlock :global(.frame:not([data-frame-type])),
+  .container:has(.checkbox:checked)
+    .code
+    .codeBlock
+    :global(.frame[data-frame-type='highlighted-unfocused']),
+  .container:has(.checkbox:checked)
+    .code
+    .codeBlock
+    :global(.frame[data-frame-type='focus-unfocused']) {
     max-height: unset;
     height: auto;
     overflow: clip;
@@ -230,15 +241,18 @@ pre.codeBlock {
   }
 }
 
-.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='padding-top']),
-.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='padding-bottom']) {
+.container:has(.checkbox:checked) .code .codeBlock :global(.frame[data-frame-type='padding-top']),
+.container:has(.checkbox:checked)
+  .code
+  .codeBlock
+  :global(.frame[data-frame-type='padding-bottom']) {
   opacity: 1;
 }
 
 /* ---- Truncated frame fade-out (focusFramesMaxSize split) ---- */
 
 /* Reset the mask when expanded */
-.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-truncated='visible']) {
+.container:has(.checkbox:checked) .code .codeBlock :global(.frame[data-frame-truncated='visible']) {
   -webkit-mask-image: none;
   mask-image: none;
   border-radius: 8px 8px 0 0;
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
index 8e074fc88..73da35aaa 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
@@ -4,6 +4,7 @@ import * as React from 'react';
 import type { ContentProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
 import { useCode } from '@mui/internal-docs-infra/useCode';
 import styles from './CollapsibleContent.module.css';
+import { useScrollAnchor } from './useScrollAnchor';
 
 import '@wooorm/starry-night/style/light';
 
@@ -12,12 +13,26 @@ export function CollapsibleContent(props: ContentProps<object>) {
   const code = useCode(props, { preClassName: styles.codeBlock });
   const id = React.useId();
   const checkboxId = `${id}-expand`;
+  const { containerRef, anchorScroll } = useScrollAnchor();
+  const blurPointerFocus = React.useCallback((event: React.FocusEvent<HTMLInputElement>) => {
+    if (!event.currentTarget.matches(':focus-visible')) {
+      event.currentTarget.blur();
+    }
+  }, []);
 
   return (
-    <div className={styles.container}>
-      {/* Visually hidden checkbox provides no-JS toggle state via CSS :checked */}
-      <input type="checkbox" id={checkboxId} className={styles.checkbox} />
+    <div ref={containerRef} className={styles.container}>
       <div className={styles.code}>{code.selectedFile}</div>
+      {/* Visually hidden checkbox provides no-JS toggle state via CSS :checked */}
+      <input
+        type="checkbox"
+        id={checkboxId}
+        className={styles.checkbox}
+        onFocus={blurPointerFocus}
+        onChange={(event) => {
+          anchorScroll(event.target.checked ? 'expand' : 'collapse');
+        }}
+      />
       <label htmlFor={checkboxId} className={styles.toggle}>
         <span className={styles.expandLabel}>Expand</span>
         <span className={styles.collapseLabel}>Collapse</span>
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
index fb3fe07e9..8b334a16a 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
@@ -126,10 +126,8 @@ pre.codeBlock {
   overflow-x: hidden;
 }
 
-.checkbox:checked ~ .code pre.codeBlock {
+.codeSection:has(.checkbox:checked) .code pre.codeBlock {
   overflow-x: auto;
-  transition: overflow-x 0s 1.5s;
-  transition-behavior: allow-discrete;
 }
 
 /* Code element inside pre — block so frames stretch to the widest line */
@@ -242,6 +240,7 @@ pre.codeBlock {
 .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 0;
   overflow: hidden;
+  overflow-anchor: none;
   opacity: 0;
   transition:
     max-height 0.3s cubic-bezier(0.5, 0, 0, 1),
@@ -270,9 +269,15 @@ pre.codeBlock {
 }
 
 /* When checkbox is checked (expanded), show all frames */
-.checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
-.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
-.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+.codeSection:has(.checkbox:checked) .code .codeBlock :global(.frame:not([data-frame-type])),
+.codeSection:has(.checkbox:checked)
+  .code
+  .codeBlock
+  :global(.frame[data-frame-type='highlighted-unfocused']),
+.codeSection:has(.checkbox:checked)
+  .code
+  .codeBlock
+  :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 2220px;
   opacity: 1;
   transition:
@@ -281,9 +286,15 @@ pre.codeBlock {
 }
 
 @supports (interpolate-size: allow-keywords) {
-  .checkbox:checked ~ .code .codeBlock :global(.frame:not([data-frame-type])),
-  .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
-  .checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
+  .codeSection:has(.checkbox:checked) .code .codeBlock :global(.frame:not([data-frame-type])),
+  .codeSection:has(.checkbox:checked)
+    .code
+    .codeBlock
+    :global(.frame[data-frame-type='highlighted-unfocused']),
+  .codeSection:has(.checkbox:checked)
+    .code
+    .codeBlock
+    :global(.frame[data-frame-type='focus-unfocused']) {
     max-height: unset;
     height: auto;
     overflow: clip;
@@ -293,13 +304,19 @@ pre.codeBlock {
   }
 }
 
-.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='padding-top']),
-.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-type='padding-bottom']) {
+.codeSection:has(.checkbox:checked) .code .codeBlock :global(.frame[data-frame-type='padding-top']),
+.codeSection:has(.checkbox:checked)
+  .code
+  .codeBlock
+  :global(.frame[data-frame-type='padding-bottom']) {
   opacity: 1;
 }
 
 /* Reset the mask when expanded */
-.checkbox:checked ~ .code .codeBlock :global(.frame[data-frame-truncated='visible']) {
+.codeSection:has(.checkbox:checked)
+  .code
+  .codeBlock
+  :global(.frame[data-frame-truncated='visible']) {
   -webkit-mask-image: none;
   mask-image: none;
   border-radius: 8px 8px 0 0;
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
index 046a9fffb..1f9247e77 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
@@ -8,6 +8,7 @@ import { Tabs } from '@/components/Tabs';
 import { CopyButton } from '@/components/CopyButton';
 import { Select } from '@/components/Select';
 import styles from './CollapsibleDemoContent.module.css';
+import { useScrollAnchor } from './useScrollAnchor';
 
 import '@wooorm/starry-night/style/light';
 
@@ -42,6 +43,12 @@ export function CollapsibleDemoContent(props: ContentProps<object>) {
 
   const id = React.useId();
   const checkboxId = `${id}-expand`;
+  const { containerRef, anchorScroll } = useScrollAnchor();
+  const blurPointerFocus = React.useCallback((event: React.FocusEvent<HTMLInputElement>) => {
+    if (!event.currentTarget.matches(':focus-visible')) {
+      event.currentTarget.blur();
+    }
+  }, []);
 
   return (
     <div>
@@ -50,7 +57,7 @@ export function CollapsibleDemoContent(props: ContentProps<object>) {
       ))}
       <div className={styles.container}>
         <div className={styles.demoSection}>{demo.component}</div>
-        <div className={styles.codeSection}>
+        <div ref={containerRef} className={styles.codeSection}>
           <div className={styles.header}>
             <div className={styles.headerContainer}>
               <div className={styles.tabContainer}>
@@ -81,9 +88,17 @@ export function CollapsibleDemoContent(props: ContentProps<object>) {
               </div>
             </div>
           </div>
-          {/* Visually hidden checkbox provides no-JS toggle state via CSS :checked */}
-          <input type="checkbox" id={checkboxId} className={styles.checkbox} />
           <div className={styles.code}>{demo.selectedFile}</div>
+          {/* Visually hidden checkbox provides no-JS toggle state via CSS :checked */}
+          <input
+            type="checkbox"
+            id={checkboxId}
+            className={styles.checkbox}
+            onFocus={blurPointerFocus}
+            onChange={(event) => {
+              anchorScroll(event.target.checked ? 'expand' : 'collapse');
+            }}
+          />
           <label htmlFor={checkboxId} className={styles.toggle}>
             <span className={styles.expandLabel}>Expand</span>
             <span className={styles.collapseLabel}>Collapse</span>
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
index 50117afab..25a5da9a8 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
@@ -40,8 +40,6 @@ pre.codeBlock {
 
 .expanded pre.codeBlock {
   overflow-x: auto;
-  transition: overflow-x 0s 1.5s;
-  transition-behavior: allow-discrete;
 }
 
 /* Code element inside pre — block so frames stretch to the widest line */
@@ -146,6 +144,7 @@ pre.codeBlock {
 .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 0;
   overflow: hidden;
+  overflow-anchor: none;
   opacity: 0;
   transition:
     max-height 0.3s cubic-bezier(0.5, 0, 0, 1),
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx
index 06074dc96..8654fc6fd 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx
@@ -4,6 +4,7 @@ import * as React from 'react';
 import type { ContentProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
 import { useCode } from '@mui/internal-docs-infra/useCode';
 import styles from './IndentContent.module.css';
+import { useScrollAnchor } from './useScrollAnchor';
 
 import '@wooorm/starry-night/style/light';
 
@@ -11,11 +12,19 @@ export function IndentContent(props: ContentProps<object>) {
   // @focus-start @padding 1
   const code = useCode(props, { preClassName: styles.codeBlock });
   const [expanded, setExpanded] = React.useState(false);
+  const { containerRef, anchorScroll } = useScrollAnchor();
 
   return (
-    <div className={styles.container}>
+    <div ref={containerRef} className={styles.container}>
       <div className={`${styles.code} ${expanded ? styles.expanded : ''}`}>{code.selectedFile}</div>
-      <button type="button" className={styles.toggle} onClick={() => setExpanded((prev) => !prev)}>
+      <button
+        type="button"
+        className={styles.toggle}
+        onClick={() => {
+          anchorScroll(expanded ? 'collapse' : 'expand');
+          setExpanded((prev) => !prev);
+        }}
+      >
         {expanded ? 'Collapse' : 'Expand'}
       </button>
     </div>
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
new file mode 100644
index 000000000..b35244017
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
@@ -0,0 +1,190 @@
+import * as React from 'react';
+
+/**
+ * Selector for the first highlighted or focus frame — the content the user
+ * cares about. Anchoring to this keeps the focused code visually stable
+ * in both expand and collapse directions.
+ */
+const ANCHOR_SELECTOR = ['[data-frame-type="highlighted"]', '[data-frame-type="focus"]'].join(', ');
+
+/**
+ * Whether the browser supports `interpolate-size: allow-keywords` —
+ * determines which CSS transition path is active and thus how long
+ * the rAF loop needs to run.
+ *
+ * - Enhanced: 300ms for both expand and collapse
+ * - Fallback: 300ms collapse, 1500ms expand (max-height)
+ */
+const supportsInterpolateSize =
+  typeof CSS !== 'undefined' && CSS.supports('interpolate-size', 'allow-keywords');
+
+function getTransitionTimeout(direction: 'collapse' | 'expand'): number {
+  if (supportsInterpolateSize) {
+    // @supports path: height 0.3s ease in both directions
+    return 350;
+  }
+  // Fallback path: max-height 0.3s collapse, 1.5s expand
+  return direction === 'collapse' ? 350 : 1550;
+}
+/**
+ * Measures the horizontal scrollbar height of a `<pre>` element by
+ * temporarily forcing `overflow-x: scroll`.
+ */
+function measureScrollbarHeight(pre: HTMLElement): number {
+  const prevOverflow = pre.style.overflowX;
+  pre.style.overflowX = 'scroll';
+  const scrollbarHeight = pre.offsetHeight - pre.clientHeight;
+  pre.style.overflowX = prevOverflow;
+  return scrollbarHeight;
+}
+
+/**
+ * Smoothly transitions the horizontal scrollbar gutter on collapse by
+ * swapping the real scrollbar for equivalent padding-bottom, then
+ * animating that padding down to the CSS base value.
+ *
+ * Skips the animation when content doesn't overflow (no scrollbar exists)
+ * or when the browser uses overlay scrollbars (zero height).
+ */
+function animateScrollbarGutter(pre: HTMLElement) {
+  const scrollbarHeight = measureScrollbarHeight(pre);
+  if (scrollbarHeight === 0) {
+    return; // Overlay scrollbars, nothing to do
+  }
+
+  // Only animate if content actually overflows (scrollbar is visible)
+  if (pre.scrollWidth <= pre.clientWidth) {
+    return;
+  }
+
+  // The CSS sets padding-bottom on the pre (e.g. 6px). The inline padding
+  // must equal scrollbarHeight + cssPadding so total bottom space is constant
+  // when the scrollbar disappears.
+  const cssPaddingBottom = parseFloat(getComputedStyle(pre).paddingBottom) || 0;
+  const totalPadding = scrollbarHeight + cssPaddingBottom;
+
+  // Swap scrollbar for padding in one frame
+  pre.style.overflowX = 'hidden';
+  pre.style.paddingBottom = `${totalPadding}px`;
+
+  // Animate padding down to CSS base value over the collapse duration
+  requestAnimationFrame(() => {
+    pre.style.transition = `padding-bottom 0.3s ease`;
+    pre.style.paddingBottom = `${cssPaddingBottom}px`;
+
+    const timeout = getTransitionTimeout('collapse');
+    setTimeout(() => {
+      pre.style.paddingBottom = '';
+      pre.style.transition = '';
+      pre.style.overflowX = '';
+    }, timeout);
+  });
+}
+
+/**
+ * Whether the browser supports CSS Scroll Anchoring (`overflow-anchor`).
+ * Chrome 56+ and Firefox 66+ support it; Safari does not.
+ * When supported, we must disable it on the scroller before the rendering
+ * step so that only our rAF loop compensates — avoiding double-adjustment.
+ */
+const supportsOverflowAnchor =
+  typeof CSS !== 'undefined' && CSS.supports('overflow-anchor', 'auto');
+
+export function useScrollAnchor() {
+  const containerRef = React.useRef<HTMLDivElement>(null);
+
+  // CSS `overflow-anchor: none` on collapsing frames guides the browser's
+  // native scroll anchoring to use highlighted/focus frames — works pre-hydration.
+  // Post-hydration we disable native anchoring on the scroller permanently
+  // and use the rAF loop as the sole compensation mechanism.
+  // Toggling overflow-anchor per-transition caused scroll jumps because the
+  // browser would re-anchor when the property was restored between cycles.
+  React.useEffect(() => {
+    if (supportsOverflowAnchor) {
+      document.documentElement.style.overflowAnchor = 'none';
+    }
+    return () => {
+      if (supportsOverflowAnchor) {
+        document.documentElement.style.overflowAnchor = '';
+      }
+    };
+  }, []);
+
+  const anchorScroll = React.useCallback((direction: 'collapse' | 'expand') => {
+    const container = containerRef.current;
+    if (!container) {
+      return;
+    }
+
+    const anchor = container.querySelector<HTMLElement>(ANCHOR_SELECTOR);
+    if (!anchor) {
+      return;
+    }
+
+    // On collapse, animate the scrollbar gutter (padding swap) to avoid
+    // an instant 15px height shrink. On expand, the rAF loop naturally
+    // compensates for the scrollbar appearing — no animation needed.
+    if (direction === 'collapse') {
+      const pre = container.querySelector<HTMLElement>('pre');
+      if (pre) {
+        animateScrollbarGutter(pre);
+      }
+    }
+
+    const initialTop = anchor.getBoundingClientRect().top;
+    let active = true;
+
+    // Stop compensating if the user scrolls manually
+    function cleanup() {
+      if (!active) {
+        return;
+      }
+      active = false;
+      window.removeEventListener('wheel', stopOnUserScroll);
+      window.removeEventListener('touchmove', stopOnUserScroll);
+    }
+
+    function stopOnUserScroll() {
+      cleanup();
+    }
+    window.addEventListener('wheel', stopOnUserScroll, { passive: true, once: true });
+    window.addEventListener('touchmove', stopOnUserScroll, { passive: true, once: true });
+
+    const minRunMs = getTransitionTimeout(direction);
+    const maxRunMs = minRunMs + 1200;
+    const settleWindowMs = 120;
+    const startedAt = performance.now();
+    let lastAdjustmentAt = startedAt;
+    let hasAdjusted = false;
+
+    const compensate = (now: number) => {
+      if (!active) {
+        return;
+      }
+      const delta = anchor.getBoundingClientRect().top - initialTop;
+      if (Math.abs(delta) > 0.5) {
+        window.scrollBy(0, delta);
+        lastAdjustmentAt = now;
+        hasAdjusted = true;
+      }
+
+      const elapsed = now - startedAt;
+      const settled =
+        hasAdjusted && elapsed >= minRunMs && now - lastAdjustmentAt >= settleWindowMs;
+      const exceededMax = elapsed >= maxRunMs;
+      if (settled || exceededMax) {
+        cleanup();
+        return;
+      }
+
+      requestAnimationFrame(compensate);
+    };
+
+    requestAnimationFrame(compensate);
+
+    // Failsafe in case rAF is throttled in a background tab.
+    setTimeout(cleanup, maxRunMs + 100);
+  }, []);
+
+  return { containerRef, anchorScroll };
+}

From 6529001b6fb1ce5780bacf41a473a530acc5b1b3 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 17 Apr 2026 23:43:48 -0400
Subject: [PATCH 30/44] Fix scrollbar animation

---
 .../demos/useScrollAnchor.ts                  | 76 ++++++++++++-------
 1 file changed, 49 insertions(+), 27 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
index b35244017..22f5526de 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
@@ -26,6 +26,7 @@ function getTransitionTimeout(direction: 'collapse' | 'expand'): number {
   // Fallback path: max-height 0.3s collapse, 1.5s expand
   return direction === 'collapse' ? 350 : 1550;
 }
+
 /**
  * Measures the horizontal scrollbar height of a `<pre>` element by
  * temporarily forcing `overflow-x: scroll`.
@@ -82,33 +83,50 @@ function animateScrollbarGutter(pre: HTMLElement) {
 }
 
 /**
- * Whether the browser supports CSS Scroll Anchoring (`overflow-anchor`).
- * Chrome 56+ and Firefox 66+ support it; Safari does not.
- * When supported, we must disable it on the scroller before the rendering
- * step so that only our rAF loop compensates — avoiding double-adjustment.
+ * Smoothly transitions the horizontal scrollbar gutter on expand by
+ * reserving the eventual scrollbar space via padding-bottom first,
+ * then letting CSS swap to real overflow-x at the end of the transition.
+ *
+ * This is primarily needed for the max-size split-frame case where hidden
+ * overflow lines can make the scrollbar appear late during expansion.
  */
-const supportsOverflowAnchor =
-  typeof CSS !== 'undefined' && CSS.supports('overflow-anchor', 'auto');
+function animateScrollbarGutterExpand(pre: HTMLElement) {
+  const scrollbarHeight = measureScrollbarHeight(pre);
+  if (scrollbarHeight === 0) {
+    return; // Overlay scrollbars, nothing to do
+  }
+
+  const cssPaddingBottom = parseFloat(getComputedStyle(pre).paddingBottom) || 0;
+  const totalPadding = scrollbarHeight + cssPaddingBottom;
+
+  // Start with the base padding and no horizontal scrollbar.
+  pre.style.overflowX = 'hidden';
+  pre.style.paddingBottom = `${cssPaddingBottom}px`;
+
+  // Animate padding up to reserve future scrollbar space.
+  requestAnimationFrame(() => {
+    pre.style.transition = `padding-bottom 0.3s ease`;
+    pre.style.paddingBottom = `${totalPadding}px`;
+
+    const timeout = getTransitionTimeout('expand');
+    setTimeout(() => {
+      // Hand off from synthetic padding to the real scrollbar.
+      pre.style.paddingBottom = '';
+      pre.style.transition = '';
+      pre.style.overflowX = '';
+    }, timeout);
+  });
+}
 
 export function useScrollAnchor() {
   const containerRef = React.useRef<HTMLDivElement>(null);
 
-  // CSS `overflow-anchor: none` on collapsing frames guides the browser's
-  // native scroll anchoring to use highlighted/focus frames — works pre-hydration.
-  // Post-hydration we disable native anchoring on the scroller permanently
-  // and use the rAF loop as the sole compensation mechanism.
-  // Toggling overflow-anchor per-transition caused scroll jumps because the
-  // browser would re-anchor when the property was restored between cycles.
-  React.useEffect(() => {
-    if (supportsOverflowAnchor) {
-      document.documentElement.style.overflowAnchor = 'none';
-    }
-    return () => {
-      if (supportsOverflowAnchor) {
-        document.documentElement.style.overflowAnchor = '';
-      }
-    };
-  }, []);
+  // CSS `overflow-anchor: none` on hidden frames (set in CSS) guides the browser's
+  // native scroll anchoring to highlighted/focus frames — works both pre- and
+  // post-hydration. In Chrome/Firefox, native anchoring compensates synchronously
+  // per layout step, so the rAF loop below sees delta ≈ 0 and becomes a no-op,
+  // avoiding Electron rAF throttling artifacts. The rAF loop acts as a fallback
+  // for Safari, which has no native overflow-anchor support.
 
   const anchorScroll = React.useCallback((direction: 'collapse' | 'expand') => {
     const container = containerRef.current;
@@ -122,13 +140,17 @@ export function useScrollAnchor() {
     }
 
     // On collapse, animate the scrollbar gutter (padding swap) to avoid
-    // an instant 15px height shrink. On expand, the rAF loop naturally
-    // compensates for the scrollbar appearing — no animation needed.
-    if (direction === 'collapse') {
-      const pre = container.querySelector<HTMLElement>('pre');
-      if (pre) {
+    // an instant height shrink when horizontal scrollbar space disappears.
+    // On expand, do the inverse only for truncated/max-size demos where
+    // scrollbar space can appear late and look like a snap.
+    const pre = container.querySelector<HTMLElement>('pre');
+    if (pre) {
+      if (direction === 'collapse') {
         animateScrollbarGutter(pre);
       }
+      if (direction === 'expand' && pre.querySelector('[data-collapsible]')) {
+        animateScrollbarGutterExpand(pre);
+      }
     }
 
     const initialTop = anchor.getBoundingClientRect().top;

From 60c7011b872d2a43f74223db311807731dddbc57 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 17 Apr 2026 23:48:04 -0400
Subject: [PATCH 31/44] Remove inline styles

---
 .../demos/CollapsibleContent.module.css       | 34 +++++++-
 .../demos/CollapsibleDemoContent.module.css   | 34 +++++++-
 .../demos/useScrollAnchor.ts                  | 80 +++++++++----------
 3 files changed, 104 insertions(+), 44 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
index 55568113f..91d757ffa 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
@@ -67,7 +67,39 @@
 /* Pre element — `pre` qualifier needed to override layout's `.content pre { overflow-x: auto }` */
 pre.codeBlock {
   margin: 0;
-  padding: 6px 0;
+  --code-padding-bottom: 6px;
+  --scrollbar-gutter-size: 15px;
+  --code-padding-with-scrollbar: calc(var(--code-padding-bottom) + var(--scrollbar-gutter-size));
+  padding: var(--code-padding-bottom) 0;
+  overflow-x: hidden;
+}
+
+pre.codeBlock[data-scrollbar-gutter='collapse-from'] {
+  overflow-x: hidden;
+  transition: none;
+  padding-bottom: var(--code-padding-with-scrollbar);
+}
+
+pre.codeBlock[data-scrollbar-gutter='collapse-to'] {
+  overflow-x: hidden;
+  transition: padding-bottom 0.3s ease;
+  padding-bottom: var(--code-padding-bottom);
+}
+
+pre.codeBlock[data-scrollbar-gutter='expand-from'] {
+  overflow-x: hidden;
+  transition: none;
+  padding-bottom: var(--code-padding-bottom);
+}
+
+pre.codeBlock[data-scrollbar-gutter='expand-to'] {
+  overflow-x: hidden;
+  transition: padding-bottom 0.3s ease;
+  padding-bottom: var(--code-padding-with-scrollbar);
+}
+
+.container:has(.checkbox:checked) .code pre.codeBlock[data-scrollbar-gutter='expand-from'],
+.container:has(.checkbox:checked) .code pre.codeBlock[data-scrollbar-gutter='expand-to'] {
   overflow-x: hidden;
 }
 
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
index 8b334a16a..ef7f86429 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
@@ -122,7 +122,39 @@
 /* Pre element — `pre` qualifier needed to override layout's `.content pre { overflow-x: auto }` */
 pre.codeBlock {
   margin: 0;
-  padding: 6px 0;
+  --code-padding-bottom: 6px;
+  --scrollbar-gutter-size: 15px;
+  --code-padding-with-scrollbar: calc(var(--code-padding-bottom) + var(--scrollbar-gutter-size));
+  padding: var(--code-padding-bottom) 0;
+  overflow-x: hidden;
+}
+
+pre.codeBlock[data-scrollbar-gutter='collapse-from'] {
+  overflow-x: hidden;
+  transition: none;
+  padding-bottom: var(--code-padding-with-scrollbar);
+}
+
+pre.codeBlock[data-scrollbar-gutter='collapse-to'] {
+  overflow-x: hidden;
+  transition: padding-bottom 0.3s ease;
+  padding-bottom: var(--code-padding-bottom);
+}
+
+pre.codeBlock[data-scrollbar-gutter='expand-from'] {
+  overflow-x: hidden;
+  transition: none;
+  padding-bottom: var(--code-padding-bottom);
+}
+
+pre.codeBlock[data-scrollbar-gutter='expand-to'] {
+  overflow-x: hidden;
+  transition: padding-bottom 0.3s ease;
+  padding-bottom: var(--code-padding-with-scrollbar);
+}
+
+.codeSection:has(.checkbox:checked) .code pre.codeBlock[data-scrollbar-gutter='expand-from'],
+.codeSection:has(.checkbox:checked) .code pre.codeBlock[data-scrollbar-gutter='expand-to'] {
   overflow-x: hidden;
 }
 
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
index 22f5526de..a6142b984 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
@@ -27,6 +27,9 @@ function getTransitionTimeout(direction: 'collapse' | 'expand'): number {
   return direction === 'collapse' ? 350 : 1550;
 }
 
+const GUTTER_STATE_ATTRIBUTE = 'data-scrollbar-gutter';
+const gutterCleanupTimers = new WeakMap<HTMLElement, number>();
+
 /**
  * Measures the horizontal scrollbar height of a `<pre>` element by
  * temporarily forcing `overflow-x: scroll`.
@@ -39,6 +42,15 @@ function measureScrollbarHeight(pre: HTMLElement): number {
   return scrollbarHeight;
 }
 
+function clearGutterState(pre: HTMLElement) {
+  const existingTimer = gutterCleanupTimers.get(pre);
+  if (existingTimer !== undefined) {
+    clearTimeout(existingTimer);
+    gutterCleanupTimers.delete(pre);
+  }
+  pre.removeAttribute(GUTTER_STATE_ATTRIBUTE);
+}
+
 /**
  * Smoothly transitions the horizontal scrollbar gutter on collapse by
  * swapping the real scrollbar for equivalent padding-bottom, then
@@ -58,28 +70,19 @@ function animateScrollbarGutter(pre: HTMLElement) {
     return;
   }
 
-  // The CSS sets padding-bottom on the pre (e.g. 6px). The inline padding
-  // must equal scrollbarHeight + cssPadding so total bottom space is constant
-  // when the scrollbar disappears.
-  const cssPaddingBottom = parseFloat(getComputedStyle(pre).paddingBottom) || 0;
-  const totalPadding = scrollbarHeight + cssPaddingBottom;
-
-  // Swap scrollbar for padding in one frame
-  pre.style.overflowX = 'hidden';
-  pre.style.paddingBottom = `${totalPadding}px`;
-
-  // Animate padding down to CSS base value over the collapse duration
-  requestAnimationFrame(() => {
-    pre.style.transition = `padding-bottom 0.3s ease`;
-    pre.style.paddingBottom = `${cssPaddingBottom}px`;
-
-    const timeout = getTransitionTimeout('collapse');
-    setTimeout(() => {
-      pre.style.paddingBottom = '';
-      pre.style.transition = '';
-      pre.style.overflowX = '';
-    }, timeout);
-  });
+  clearGutterState(pre);
+  pre.setAttribute(GUTTER_STATE_ATTRIBUTE, 'collapse-from');
+
+  // Move into the transition state on the next macrotask.
+  setTimeout(() => {
+    pre.setAttribute(GUTTER_STATE_ATTRIBUTE, 'collapse-to');
+  }, 0);
+
+  const timeout = getTransitionTimeout('collapse');
+  const cleanupTimer = setTimeout(() => {
+    clearGutterState(pre);
+  }, timeout + 30);
+  gutterCleanupTimers.set(pre, cleanupTimer);
 }
 
 /**
@@ -96,26 +99,19 @@ function animateScrollbarGutterExpand(pre: HTMLElement) {
     return; // Overlay scrollbars, nothing to do
   }
 
-  const cssPaddingBottom = parseFloat(getComputedStyle(pre).paddingBottom) || 0;
-  const totalPadding = scrollbarHeight + cssPaddingBottom;
-
-  // Start with the base padding and no horizontal scrollbar.
-  pre.style.overflowX = 'hidden';
-  pre.style.paddingBottom = `${cssPaddingBottom}px`;
-
-  // Animate padding up to reserve future scrollbar space.
-  requestAnimationFrame(() => {
-    pre.style.transition = `padding-bottom 0.3s ease`;
-    pre.style.paddingBottom = `${totalPadding}px`;
-
-    const timeout = getTransitionTimeout('expand');
-    setTimeout(() => {
-      // Hand off from synthetic padding to the real scrollbar.
-      pre.style.paddingBottom = '';
-      pre.style.transition = '';
-      pre.style.overflowX = '';
-    }, timeout);
-  });
+  clearGutterState(pre);
+  pre.setAttribute(GUTTER_STATE_ATTRIBUTE, 'expand-from');
+
+  // Move into the transition state on the next macrotask.
+  setTimeout(() => {
+    pre.setAttribute(GUTTER_STATE_ATTRIBUTE, 'expand-to');
+  }, 0);
+
+  const timeout = getTransitionTimeout('expand');
+  const cleanupTimer = setTimeout(() => {
+    clearGutterState(pre);
+  }, timeout + 30);
+  gutterCleanupTimers.set(pre, cleanupTimer);
 }
 
 export function useScrollAnchor() {

From dbc50ae8c4647d4c2bb26aa7e138fb9e0088e411 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Fri, 17 Apr 2026 23:58:03 -0400
Subject: [PATCH 32/44] Anchor scroll for large blocks

---
 .../demos/CollapsibleContent.tsx              |  4 ++--
 .../demos/CollapsibleDemoContent.tsx          |  4 ++--
 .../demos/useScrollAnchor.ts                  | 19 ++++++++++++++++---
 3 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
index 73da35aaa..304e5f2e8 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx
@@ -13,7 +13,7 @@ export function CollapsibleContent(props: ContentProps<object>) {
   const code = useCode(props, { preClassName: styles.codeBlock });
   const id = React.useId();
   const checkboxId = `${id}-expand`;
-  const { containerRef, anchorScroll } = useScrollAnchor();
+  const { containerRef, toggleRef, anchorScroll } = useScrollAnchor();
   const blurPointerFocus = React.useCallback((event: React.FocusEvent<HTMLInputElement>) => {
     if (!event.currentTarget.matches(':focus-visible')) {
       event.currentTarget.blur();
@@ -33,7 +33,7 @@ export function CollapsibleContent(props: ContentProps<object>) {
           anchorScroll(event.target.checked ? 'expand' : 'collapse');
         }}
       />
-      <label htmlFor={checkboxId} className={styles.toggle}>
+      <label ref={toggleRef} htmlFor={checkboxId} className={styles.toggle}>
         <span className={styles.expandLabel}>Expand</span>
         <span className={styles.collapseLabel}>Collapse</span>
       </label>
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
index 1f9247e77..f01399117 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
@@ -43,7 +43,7 @@ export function CollapsibleDemoContent(props: ContentProps<object>) {
 
   const id = React.useId();
   const checkboxId = `${id}-expand`;
-  const { containerRef, anchorScroll } = useScrollAnchor();
+  const { containerRef, toggleRef, anchorScroll } = useScrollAnchor();
   const blurPointerFocus = React.useCallback((event: React.FocusEvent<HTMLInputElement>) => {
     if (!event.currentTarget.matches(':focus-visible')) {
       event.currentTarget.blur();
@@ -99,7 +99,7 @@ export function CollapsibleDemoContent(props: ContentProps<object>) {
               anchorScroll(event.target.checked ? 'expand' : 'collapse');
             }}
           />
-          <label htmlFor={checkboxId} className={styles.toggle}>
+          <label ref={toggleRef} htmlFor={checkboxId} className={styles.toggle}>
             <span className={styles.expandLabel}>Expand</span>
             <span className={styles.collapseLabel}>Collapse</span>
           </label>
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
index a6142b984..8d2971416 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
@@ -28,7 +28,12 @@ function getTransitionTimeout(direction: 'collapse' | 'expand'): number {
 }
 
 const GUTTER_STATE_ATTRIBUTE = 'data-scrollbar-gutter';
-const gutterCleanupTimers = new WeakMap<HTMLElement, number>();
+const gutterCleanupTimers = new WeakMap<HTMLElement, ReturnType<typeof setTimeout>>();
+
+function isElementInViewport(element: HTMLElement): boolean {
+  const rect = element.getBoundingClientRect();
+  return rect.bottom > 0 && rect.top < window.innerHeight;
+}
 
 /**
  * Measures the horizontal scrollbar height of a `<pre>` element by
@@ -116,6 +121,7 @@ function animateScrollbarGutterExpand(pre: HTMLElement) {
 
 export function useScrollAnchor() {
   const containerRef = React.useRef<HTMLDivElement>(null);
+  const toggleRef = React.useRef<HTMLLabelElement>(null);
 
   // CSS `overflow-anchor: none` on hidden frames (set in CSS) guides the browser's
   // native scroll anchoring to highlighted/focus frames — works both pre- and
@@ -130,7 +136,14 @@ export function useScrollAnchor() {
       return;
     }
 
-    const anchor = container.querySelector<HTMLElement>(ANCHOR_SELECTOR);
+    const primaryAnchor = container.querySelector<HTMLElement>(ANCHOR_SELECTOR);
+    const toggleAnchor = toggleRef.current;
+
+    let anchor = primaryAnchor ?? toggleAnchor;
+    if (direction === 'collapse' && primaryAnchor && !isElementInViewport(primaryAnchor)) {
+      anchor = toggleAnchor ?? primaryAnchor;
+    }
+
     if (!anchor) {
       return;
     }
@@ -204,5 +217,5 @@ export function useScrollAnchor() {
     setTimeout(cleanup, maxRunMs + 100);
   }, []);
 
-  return { containerRef, anchorScroll };
+  return { containerRef, toggleRef, anchorScroll };
 }

From 428a79554d70eeb5acceb649d055485337f0833b Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Sat, 18 Apr 2026 00:00:22 -0400
Subject: [PATCH 33/44] Update comment

---
 .../enhance-code-emphasis/demos/useScrollAnchor.ts   | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
index 8d2971416..e644d53a1 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
@@ -123,12 +123,12 @@ export function useScrollAnchor() {
   const containerRef = React.useRef<HTMLDivElement>(null);
   const toggleRef = React.useRef<HTMLLabelElement>(null);
 
-  // CSS `overflow-anchor: none` on hidden frames (set in CSS) guides the browser's
-  // native scroll anchoring to highlighted/focus frames — works both pre- and
-  // post-hydration. In Chrome/Firefox, native anchoring compensates synchronously
-  // per layout step, so the rAF loop below sees delta ≈ 0 and becomes a no-op,
-  // avoiding Electron rAF throttling artifacts. The rAF loop acts as a fallback
-  // for Safari, which has no native overflow-anchor support.
+  // CSS `overflow-anchor: none` on hidden frames (set in CSS) nudges native
+  // scroll anchoring toward the visible highlighted/focus content. In Chromium
+  // and Firefox this usually handles most compensation synchronously, while the
+  // rAF loop below smooths any remaining drift so the transition appears stable
+  // and visually "fixed" to the user. In browsers without native overflow-anchor
+  // support (e.g. Safari), the rAF loop is the primary compensation mechanism.
 
   const anchorScroll = React.useCallback((direction: 'collapse' | 'expand') => {
     const container = containerRef.current;

From 92895268c44180e85b5422250437782c68e21ad9 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Mon, 20 Apr 2026 12:34:41 -0400
Subject: [PATCH 34/44] Fix scroll jumping

---
 .../demos/CollapsibleDemoContent.module.css     |  1 +
 .../demos/useScrollAnchor.ts                    | 17 +++++++++++------
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
index ef7f86429..873deba7b 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
@@ -61,6 +61,7 @@
 
 .code {
   padding: 10px 0 0;
+  overflow-anchor: none;
 }
 
 /* Visually hidden but accessible checkbox — provides toggle state without JS */
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
index e644d53a1..d4ddea79a 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
@@ -165,21 +165,26 @@ export function useScrollAnchor() {
     const initialTop = anchor.getBoundingClientRect().top;
     let active = true;
 
-    // Stop compensating if the user scrolls manually
+    // Stop compensating if the user interacts (scroll, click, keyboard),
+    // since UI changes like tab switches can invalidate anchor measurements.
     function cleanup() {
       if (!active) {
         return;
       }
       active = false;
-      window.removeEventListener('wheel', stopOnUserScroll);
-      window.removeEventListener('touchmove', stopOnUserScroll);
+      window.removeEventListener('wheel', stopOnUserInteraction);
+      window.removeEventListener('touchmove', stopOnUserInteraction);
+      window.removeEventListener('pointerdown', stopOnUserInteraction);
+      window.removeEventListener('keydown', stopOnUserInteraction);
     }
 
-    function stopOnUserScroll() {
+    function stopOnUserInteraction() {
       cleanup();
     }
-    window.addEventListener('wheel', stopOnUserScroll, { passive: true, once: true });
-    window.addEventListener('touchmove', stopOnUserScroll, { passive: true, once: true });
+    window.addEventListener('wheel', stopOnUserInteraction, { passive: true, once: true });
+    window.addEventListener('touchmove', stopOnUserInteraction, { passive: true, once: true });
+    window.addEventListener('pointerdown', stopOnUserInteraction, { passive: true, once: true });
+    window.addEventListener('keydown', stopOnUserInteraction, { passive: true, once: true });
 
     const minRunMs = getTransitionTimeout(direction);
     const maxRunMs = minRunMs + 1200;

From fbeacfdd662e95e09fbfee1a4bb9fc280425d90b Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Mon, 20 Apr 2026 12:42:48 -0400
Subject: [PATCH 35/44] Improve scroll anchor performance

---
 .../demos/useScrollAnchor.ts                  | 54 ++++++++-----------
 1 file changed, 21 insertions(+), 33 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
index d4ddea79a..003e0e6ff 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
@@ -164,6 +164,21 @@ export function useScrollAnchor() {
 
     const initialTop = anchor.getBoundingClientRect().top;
     let active = true;
+    let cleanupTimer: ReturnType<typeof setTimeout>;
+
+    // Use ResizeObserver to compensate only when the container layout
+    // actually changes, rather than polling every animation frame.
+    // Callbacks fire after layout, so getBoundingClientRect() reads
+    // already-computed values without forcing an extra reflow.
+    const observer = new ResizeObserver(() => {
+      if (!active) {
+        return;
+      }
+      const delta = anchor.getBoundingClientRect().top - initialTop;
+      if (Math.abs(delta) > 0.5) {
+        window.scrollBy(0, delta);
+      }
+    });
 
     // Stop compensating if the user interacts (scroll, click, keyboard),
     // since UI changes like tab switches can invalidate anchor measurements.
@@ -172,6 +187,8 @@ export function useScrollAnchor() {
         return;
       }
       active = false;
+      clearTimeout(cleanupTimer);
+      observer.disconnect();
       window.removeEventListener('wheel', stopOnUserInteraction);
       window.removeEventListener('touchmove', stopOnUserInteraction);
       window.removeEventListener('pointerdown', stopOnUserInteraction);
@@ -186,40 +203,11 @@ export function useScrollAnchor() {
     window.addEventListener('pointerdown', stopOnUserInteraction, { passive: true, once: true });
     window.addEventListener('keydown', stopOnUserInteraction, { passive: true, once: true });
 
-    const minRunMs = getTransitionTimeout(direction);
-    const maxRunMs = minRunMs + 1200;
-    const settleWindowMs = 120;
-    const startedAt = performance.now();
-    let lastAdjustmentAt = startedAt;
-    let hasAdjusted = false;
-
-    const compensate = (now: number) => {
-      if (!active) {
-        return;
-      }
-      const delta = anchor.getBoundingClientRect().top - initialTop;
-      if (Math.abs(delta) > 0.5) {
-        window.scrollBy(0, delta);
-        lastAdjustmentAt = now;
-        hasAdjusted = true;
-      }
-
-      const elapsed = now - startedAt;
-      const settled =
-        hasAdjusted && elapsed >= minRunMs && now - lastAdjustmentAt >= settleWindowMs;
-      const exceededMax = elapsed >= maxRunMs;
-      if (settled || exceededMax) {
-        cleanup();
-        return;
-      }
-
-      requestAnimationFrame(compensate);
-    };
-
-    requestAnimationFrame(compensate);
+    observer.observe(container);
 
-    // Failsafe in case rAF is throttled in a background tab.
-    setTimeout(cleanup, maxRunMs + 100);
+    // Safety cleanup after the CSS transition completes.
+    const timeout = getTransitionTimeout(direction);
+    cleanupTimer = setTimeout(cleanup, timeout + 500);
   }, []);
 
   return { containerRef, toggleRef, anchorScroll };

From 26f0a0cf5a44c0ca0cc6157d8247548b9e214289 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Mon, 20 Apr 2026 13:26:11 -0400
Subject: [PATCH 36/44] Fix horizontal scroll animation

---
 .../enhance-code-emphasis/demos/useScrollAnchor.ts        | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
index 003e0e6ff..2fd7aa9db 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
@@ -104,6 +104,14 @@ function animateScrollbarGutterExpand(pre: HTMLElement) {
     return; // Overlay scrollbars, nothing to do
   }
 
+  // The <code> element uses `min-width: fit-content`, so its scrollWidth
+  // reflects the widest line including hidden frames. If that doesn't
+  // exceed the container, no scrollbar will appear after expansion.
+  const code = pre.querySelector('code');
+  if (code && code.scrollWidth <= pre.clientWidth) {
+    return;
+  }
+
   clearGutterState(pre);
   pre.setAttribute(GUTTER_STATE_ATTRIBUTE, 'expand-from');
 

From 650727f60e7dbb5677e68144c5772db6b93e01a9 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Mon, 20 Apr 2026 14:28:26 -0400
Subject: [PATCH 37/44] Fix truncated fade css

---
 .../demos/CollapsibleContent.module.css       | 78 +++++++++++++-----
 .../demos/CollapsibleDemoContent.module.css   | 80 ++++++++++++++-----
 .../demos/IndentContent.module.css            | 46 ++++++++---
 3 files changed, 154 insertions(+), 50 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
index 91d757ffa..15035a4f8 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
@@ -69,33 +69,79 @@ pre.codeBlock {
   margin: 0;
   --code-padding-bottom: 6px;
   --scrollbar-gutter-size: 15px;
-  --code-padding-with-scrollbar: calc(var(--code-padding-bottom) + var(--scrollbar-gutter-size));
   padding: var(--code-padding-bottom) 0;
   overflow-x: hidden;
 }
 
+/* Fade overlay at the bottom of truncated code blocks.
+   Uses ::after + transform so the animation is GPU-accelerated.
+   The pre's computed overflow clips the translated pseudo-element. */
+pre.codeBlock:has(:global(.frame[data-frame-truncated='visible'])) {
+  position: relative;
+  padding-bottom: 0;
+  overflow-y: clip;
+}
+
+pre.codeBlock:has(:global(.frame[data-frame-truncated='visible']))::after {
+  content: '';
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  height: 40px;
+  background: linear-gradient(to bottom, transparent, rgb(255 255 255 / 0.8));
+  transition: transform 0.3s ease;
+  pointer-events: none;
+}
+
+.container:has(.checkbox:checked)
+  .code
+  pre.codeBlock:has(:global(.frame[data-frame-truncated='visible'])) {
+  padding-bottom: var(--code-padding-bottom);
+}
+
+.container:has(.checkbox:checked)
+  .code
+  pre.codeBlock:has(:global(.frame[data-frame-truncated='visible']))::after {
+  transform: translateY(100%);
+}
+
 pre.codeBlock[data-scrollbar-gutter='collapse-from'] {
   overflow-x: hidden;
   transition: none;
-  padding-bottom: var(--code-padding-with-scrollbar);
+}
+
+pre.codeBlock[data-scrollbar-gutter='collapse-from'] :global(code) {
+  margin-bottom: var(--scrollbar-gutter-size);
+  transition: none;
 }
 
 pre.codeBlock[data-scrollbar-gutter='collapse-to'] {
   overflow-x: hidden;
-  transition: padding-bottom 0.3s ease;
-  padding-bottom: var(--code-padding-bottom);
+}
+
+pre.codeBlock[data-scrollbar-gutter='collapse-to'] :global(code) {
+  margin-bottom: 0;
+  transition: margin-bottom 0.3s ease;
 }
 
 pre.codeBlock[data-scrollbar-gutter='expand-from'] {
   overflow-x: hidden;
   transition: none;
-  padding-bottom: var(--code-padding-bottom);
+}
+
+pre.codeBlock[data-scrollbar-gutter='expand-from'] :global(code) {
+  margin-bottom: 0;
+  transition: none;
 }
 
 pre.codeBlock[data-scrollbar-gutter='expand-to'] {
   overflow-x: hidden;
-  transition: padding-bottom 0.3s ease;
-  padding-bottom: var(--code-padding-with-scrollbar);
+}
+
+pre.codeBlock[data-scrollbar-gutter='expand-to'] :global(code) {
+  margin-bottom: var(--scrollbar-gutter-size);
+  transition: margin-bottom 0.3s ease;
 }
 
 .container:has(.checkbox:checked) .code pre.codeBlock[data-scrollbar-gutter='expand-from'],
@@ -189,11 +235,9 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] {
   padding: 2px 4px;
 }
 
-/* When truncated visible (collapsed): only round top — bottom fades out */
+/* When truncated visible (collapsed): only round top */
 .codeBlock :global(.frame[data-frame-truncated='visible']) {
   border-radius: 8px 8px 0 0;
-  -webkit-mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
-  mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
 }
 
 /* Truncated hidden frame is the bottom of the region */
@@ -230,6 +274,11 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] {
   }
 }
 
+/* Highlighted-unfocused keeps its background visible — only animate height */
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+  opacity: 1;
+}
+
 /* Padding frames appear dimmed when collapsed */
 .codeBlock :global(.frame[data-frame-type='padding-top']),
 .codeBlock :global(.frame[data-frame-type='padding-bottom']) {
@@ -280,12 +329,3 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] {
   :global(.frame[data-frame-type='padding-bottom']) {
   opacity: 1;
 }
-
-/* ---- Truncated frame fade-out (focusFramesMaxSize split) ---- */
-
-/* Reset the mask when expanded */
-.container:has(.checkbox:checked) .code .codeBlock :global(.frame[data-frame-truncated='visible']) {
-  -webkit-mask-image: none;
-  mask-image: none;
-  border-radius: 8px 8px 0 0;
-}
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
index 873deba7b..ce0b6c2c4 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
@@ -125,33 +125,80 @@ pre.codeBlock {
   margin: 0;
   --code-padding-bottom: 6px;
   --scrollbar-gutter-size: 15px;
-  --code-padding-with-scrollbar: calc(var(--code-padding-bottom) + var(--scrollbar-gutter-size));
   padding: var(--code-padding-bottom) 0;
   overflow-x: hidden;
 }
 
+/* Fade overlay at the bottom of truncated code blocks.
+   Uses ::after + transform so the animation is GPU-accelerated.
+   The pre's computed overflow (hidden/auto) clips the translated
+   pseudo-element without needing an explicit overflow: clip. */
+pre.codeBlock:has(:global(.frame[data-frame-truncated='visible'])) {
+  position: relative;
+  padding-bottom: 0;
+  overflow-y: clip;
+}
+
+pre.codeBlock:has(:global(.frame[data-frame-truncated='visible']))::after {
+  content: '';
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  height: 40px;
+  background: linear-gradient(to bottom, transparent, rgb(255 255 255 / 0.8));
+  transition: transform 0.3s ease;
+  pointer-events: none;
+}
+
+.codeSection:has(.checkbox:checked)
+  .code
+  pre.codeBlock:has(:global(.frame[data-frame-truncated='visible'])) {
+  padding-bottom: var(--code-padding-bottom);
+}
+
+.codeSection:has(.checkbox:checked)
+  .code
+  pre.codeBlock:has(:global(.frame[data-frame-truncated='visible']))::after {
+  transform: translateY(100%);
+}
+
 pre.codeBlock[data-scrollbar-gutter='collapse-from'] {
   overflow-x: hidden;
   transition: none;
-  padding-bottom: var(--code-padding-with-scrollbar);
+}
+
+pre.codeBlock[data-scrollbar-gutter='collapse-from'] :global(code) {
+  margin-bottom: var(--scrollbar-gutter-size);
+  transition: none;
 }
 
 pre.codeBlock[data-scrollbar-gutter='collapse-to'] {
   overflow-x: hidden;
-  transition: padding-bottom 0.3s ease;
-  padding-bottom: var(--code-padding-bottom);
+}
+
+pre.codeBlock[data-scrollbar-gutter='collapse-to'] :global(code) {
+  margin-bottom: 0;
+  transition: margin-bottom 0.3s ease;
 }
 
 pre.codeBlock[data-scrollbar-gutter='expand-from'] {
   overflow-x: hidden;
   transition: none;
-  padding-bottom: var(--code-padding-bottom);
+}
+
+pre.codeBlock[data-scrollbar-gutter='expand-from'] :global(code) {
+  margin-bottom: 0;
+  transition: none;
 }
 
 pre.codeBlock[data-scrollbar-gutter='expand-to'] {
   overflow-x: hidden;
-  transition: padding-bottom 0.3s ease;
-  padding-bottom: var(--code-padding-with-scrollbar);
+}
+
+pre.codeBlock[data-scrollbar-gutter='expand-to'] :global(code) {
+  margin-bottom: var(--scrollbar-gutter-size);
+  transition: margin-bottom 0.3s ease;
 }
 
 .codeSection:has(.checkbox:checked) .code pre.codeBlock[data-scrollbar-gutter='expand-from'],
@@ -253,11 +300,9 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] {
   padding: 2px 4px;
 }
 
-/* When truncated visible (collapsed): only round top — bottom fades out */
+/* When truncated visible (collapsed): only round top */
 .codeBlock :global(.frame[data-frame-truncated='visible']) {
   border-radius: 8px 8px 0 0;
-  -webkit-mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
-  mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
 }
 
 /* Truncated hidden frame is the bottom of the region */
@@ -294,6 +339,11 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] {
   }
 }
 
+/* Highlighted-unfocused keeps its background visible — only animate height */
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+  opacity: 1;
+}
+
 /* Padding frames appear dimmed when collapsed */
 .codeBlock :global(.frame[data-frame-type='padding-top']),
 .codeBlock :global(.frame[data-frame-type='padding-bottom']) {
@@ -345,16 +395,6 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] {
   opacity: 1;
 }
 
-/* Reset the mask when expanded */
-.codeSection:has(.checkbox:checked)
-  .code
-  .codeBlock
-  :global(.frame[data-frame-truncated='visible']) {
-  -webkit-mask-image: none;
-  mask-image: none;
-  border-radius: 8px 8px 0 0;
-}
-
 .fileRefs {
   display: none;
 }
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
index 25a5da9a8..a97d82050 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
@@ -38,6 +38,35 @@ pre.codeBlock {
   overflow-x: hidden;
 }
 
+/* Fade overlay at the bottom of truncated code blocks.
+   Uses ::after + transform so the animation is GPU-accelerated.
+   The pre's computed overflow clips the translated pseudo-element. */
+pre.codeBlock:has(:global(.frame[data-frame-truncated='visible'])) {
+  position: relative;
+  padding-bottom: 0;
+  overflow-y: clip;
+}
+
+pre.codeBlock:has(:global(.frame[data-frame-truncated='visible']))::after {
+  content: '';
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  height: 40px;
+  background: linear-gradient(to bottom, transparent, rgb(255 255 255 / 0.8));
+  transition: transform 0.3s ease;
+  pointer-events: none;
+}
+
+.expanded pre.codeBlock:has(:global(.frame[data-frame-truncated='visible'])) {
+  padding-bottom: 6px;
+}
+
+.expanded pre.codeBlock:has(:global(.frame[data-frame-truncated='visible']))::after {
+  transform: translateY(100%);
+}
+
 .expanded pre.codeBlock {
   overflow-x: auto;
 }
@@ -125,10 +154,9 @@ pre.codeBlock {
 }
 
 /* When truncated visible (collapsed): only round top — bottom fades out */
+/* When truncated visible (collapsed): only round top */
 .codeBlock :global(.frame[data-frame-truncated='visible']) {
   border-radius: 8px 8px 0 0;
-  -webkit-mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
-  mask-image: linear-gradient(to bottom, black 50%, transparent 100%);
 }
 
 /* Truncated hidden frame is the bottom of the region */
@@ -165,6 +193,11 @@ pre.codeBlock {
   }
 }
 
+/* Highlighted-unfocused keeps its background visible — only animate height */
+.codeBlock :global(.frame[data-frame-type='highlighted-unfocused']) {
+  opacity: 1;
+}
+
 /* When expanded, show all frames */
 .expanded .codeBlock :global(.frame:not([data-frame-type])),
 .expanded .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
@@ -189,15 +222,6 @@ pre.codeBlock {
   }
 }
 
-/* ---- Truncated frame fade-out (focusFramesMaxSize split) ---- */
-
-/* Reset the mask when expanded */
-.expanded .codeBlock :global(.frame[data-frame-truncated='visible']) {
-  -webkit-mask-image: none;
-  mask-image: none;
-  border-radius: 8px 8px 0 0;
-}
-
 /* ---- Indent shifting: move highlighted/focus frame left by its indent level ---- */
 /* Uses transform instead of margin-left to avoid layout reflow during height transitions */
 

From cc673ce06525255a5e43a86c9d4703b0675d4ba7 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Mon, 20 Apr 2026 15:26:17 -0400
Subject: [PATCH 38/44] Fix first render

---
 packages/docs-infra/src/useCode/Pre.tsx       | 49 +++++++++++++++++--
 packages/docs-infra/src/useCode/useCode.ts    |  1 +
 .../src/useCode/useFileNavigation.tsx         | 46 +++++++++++++++--
 3 files changed, 89 insertions(+), 7 deletions(-)

diff --git a/packages/docs-infra/src/useCode/Pre.tsx b/packages/docs-infra/src/useCode/Pre.tsx
index 6102cc0ae..446409b41 100644
--- a/packages/docs-infra/src/useCode/Pre.tsx
+++ b/packages/docs-infra/src/useCode/Pre.tsx
@@ -9,6 +9,43 @@ import { hastToJsx, decompressHast } from '../pipeline/hastUtils';
 const hastChildrenCache = new WeakMap<ElementContent[], React.ReactNode>();
 const textChildrenCache = new WeakMap<ElementContent[], string>();
 
+const INITIAL_VISIBLE_FRAME_TYPES = new Set([
+  'highlighted',
+  'focus',
+  'padding-top',
+  'padding-bottom',
+]);
+
+function getInitialVisibleFrames(hast: HastRoot | null): { [key: number]: boolean } {
+  if (!hast) {
+    return { 0: true };
+  }
+
+  const visibleFrames: { [key: number]: boolean } = {};
+  let frameIndex = 0;
+  let hasVisibleEmphasisFrame = false;
+
+  hast.children.forEach((child) => {
+    if (child.type !== 'element' || child.properties.className !== 'frame') {
+      return;
+    }
+
+    const frameType = child.properties.dataFrameType;
+    if (typeof frameType === 'string' && INITIAL_VISIBLE_FRAME_TYPES.has(frameType)) {
+      visibleFrames[frameIndex] = true;
+      hasVisibleEmphasisFrame = true;
+    }
+
+    frameIndex += 1;
+  });
+
+  if (!hasVisibleEmphasisFrame && frameIndex > 0) {
+    visibleFrames[0] = true;
+  }
+
+  return visibleFrames;
+}
+
 function renderCode(hastChildren: ElementContent[], renderHast?: boolean, text?: string) {
   if (renderHast) {
     let jsx = hastChildrenCache.get(hastChildren);
@@ -62,9 +99,9 @@ export function Pre({
     return children;
   }, [children]);
 
-  const [visibleFrames, setVisibleFrames] = React.useState<{ [key: number]: boolean }>({
-    [0]: true,
-  });
+  const [visibleFrames, setVisibleFrames] = React.useState<{ [key: number]: boolean }>(() =>
+    getInitialVisibleFrames(hast),
+  );
 
   const observer = React.useRef<IntersectionObserver | null>(null);
   const frameIndexMap = React.useRef(new WeakMap<Element, number>());
@@ -175,6 +212,8 @@ export function Pre({
   }, []);
 
   const frames = React.useMemo(() => {
+    let frameIndex = 0;
+
     return hast?.children.map((child, index) => {
       if (child.type !== 'element') {
         if (child.type === 'text') {
@@ -185,9 +224,11 @@ export function Pre({
       }
 
       if (child.properties.className === 'frame') {
-        const isVisible = Boolean(visibleFrames[index]);
+        const isVisible = Boolean(visibleFrames[frameIndex]);
         const shouldRenderHast = shouldHighlight && isVisible;
 
+        frameIndex += 1;
+
         return (
           <span
             key={index}
diff --git a/packages/docs-infra/src/useCode/useCode.ts b/packages/docs-infra/src/useCode/useCode.ts
index 1728571d3..cd8252da1 100644
--- a/packages/docs-infra/src/useCode/useCode.ts
+++ b/packages/docs-infra/src/useCode/useCode.ts
@@ -150,6 +150,7 @@ export function useCode<T extends {} = {}>(
   const fileNavigation = useFileNavigation({
     selectedVariant: variantSelection.selectedVariant,
     transformedFiles: transformManagement.transformedFiles,
+    selectedTransform: transformManagement.selectedTransform,
     mainSlug: userProps.slug,
     selectedVariantKey: variantSelection.selectedVariantKey,
     selectVariant: variantSelection.selectVariantProgrammatic,
diff --git a/packages/docs-infra/src/useCode/useFileNavigation.tsx b/packages/docs-infra/src/useCode/useFileNavigation.tsx
index ba5810126..585e8d7b3 100644
--- a/packages/docs-infra/src/useCode/useFileNavigation.tsx
+++ b/packages/docs-infra/src/useCode/useFileNavigation.tsx
@@ -84,9 +84,18 @@ function generateFileSlug(mainSlug: string, fileName: string, variantName: strin
   return `${kebabMainSlug}:${kebabVariantName}:${kebabFileName}`;
 }
 
+function getPreRenderKey(
+  slug: string | undefined,
+  selectedTransform: string | null | undefined,
+  enhancementPhase: 'plain' | 'base' | 'enhanced' = 'plain',
+): string {
+  return `${slug ?? 'code'}:${selectedTransform ?? 'none'}:${enhancementPhase}`;
+}
+
 interface UseFileNavigationProps {
   selectedVariant: VariantCode | null;
   transformedFiles: TransformedFiles | undefined;
+  selectedTransform?: string | null;
   mainSlug?: string;
   selectedVariantKey?: string;
   variantKeys?: string[];
@@ -122,6 +131,7 @@ export interface UseFileNavigationResult {
 export function useFileNavigation({
   selectedVariant,
   transformedFiles,
+  selectedTransform,
   mainSlug = '',
   selectedVariantKey = '',
   variantKeys = [],
@@ -457,7 +467,7 @@ export function useFileNavigation({
   }, [selectedVariant, selectedFileNameInternal]);
 
   // Apply source enhancers to the selected file
-  const { enhancedSource } = useSourceEnhancing({
+  const { enhancedSource, isEnhancing } = useSourceEnhancing({
     source: selectedFile,
     fileName: selectedFileName,
     comments: selectedFileComments,
@@ -484,10 +494,19 @@ export function useFileNavigation({
       const language = isMainFile
         ? selectedVariant.language
         : getLanguageFromFileName(selectedFileNameInternal);
+      const fileSlug = generateFileSlug(
+        mainSlug,
+        selectedFileNameInternal ?? selectedVariant.fileName ?? 'code',
+        selectedVariantKey,
+      );
+      let enhancementPhase: 'plain' | 'base' | 'enhanced' = 'plain';
+      if (sourceEnhancers && sourceEnhancers.length > 0) {
+        enhancementPhase = isEnhancing ? 'base' : 'enhanced';
+      }
 
       return (
         <Pre
-          key={selectedFileNameInternal ?? selectedVariant.fileName}
+          key={getPreRenderKey(fileSlug, selectedTransform, enhancementPhase)}
           className={preClassName}
           language={language}
           ref={preRef}
@@ -505,7 +524,11 @@ export function useFileNavigation({
     preClassName,
     preRef,
     enhancedSource,
+    isEnhancing,
+    mainSlug,
     selectedFile,
+    selectedTransform,
+    selectedVariantKey,
     sourceEnhancers,
     selectedFileNameInternal,
   ]);
@@ -564,7 +587,15 @@ export function useFileNavigation({
         name: f.name,
         slug: generateFileSlug(mainSlug, f.originalName, selectedVariantKey),
         component: (
-          <Pre className={preClassName} ref={preRef} shouldHighlight={shouldHighlight}>
+          <Pre
+            key={getPreRenderKey(
+              generateFileSlug(mainSlug, f.originalName, selectedVariantKey),
+              selectedTransform,
+            )}
+            className={preClassName}
+            ref={preRef}
+            shouldHighlight={shouldHighlight}
+          >
             {f.source}
           </Pre>
         ),
@@ -581,6 +612,10 @@ export function useFileNavigation({
         slug: generateFileSlug(mainSlug, selectedVariant.fileName, selectedVariantKey),
         component: (
           <Pre
+            key={getPreRenderKey(
+              generateFileSlug(mainSlug, selectedVariant.fileName, selectedVariantKey),
+              selectedTransform,
+            )}
             className={preClassName}
             language={selectedVariant.language}
             ref={preRef}
@@ -615,6 +650,10 @@ export function useFileNavigation({
           slug: generateFileSlug(mainSlug, fileName, selectedVariantKey),
           component: (
             <Pre
+              key={getPreRenderKey(
+                generateFileSlug(mainSlug, fileName, selectedVariantKey),
+                selectedTransform,
+              )}
               className={preClassName}
               language={language ?? getLanguageFromFileName(fileName)}
               ref={preRef}
@@ -632,6 +671,7 @@ export function useFileNavigation({
     selectedVariant,
     transformedFiles,
     mainSlug,
+    selectedTransform,
     selectedVariantKey,
     shouldHighlight,
     preClassName,

From c89941d10cb4114bec4af51315a5a6305c0c1600 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 21 Apr 2026 10:14:23 -0400
Subject: [PATCH 39/44] Add emphasis options for code blocks

---
 .../pipeline/load-precomputed-types/page.mdx  |   2 +
 .../pipeline/load-server-types/page.mdx       |   6 +
 docs/app/docs-infra/pipeline/page.mdx         |   1 +
 .../transform-html-code-block/page.mdx        |  36 ++-
 .../pipeline/with-docs-infra/page.mdx         |  46 ++++
 .../pipeline/with-docs-infra/types.md         |  14 +-
 docs/next.config.mjs                          |   2 +-
 .../loadPrecomputedTypes.ts                   |   4 +
 .../loadServerTypes/highlightTypes.test.ts    |  88 +++++++
 .../loadServerTypes/highlightTypes.ts         |  10 +-
 .../highlightTypesMeta.test.ts                | 133 +++++++++++
 .../loadServerTypes/highlightTypesMeta.ts     |  47 +++-
 .../loadServerTypes/loadServerTypes.ts        |  22 +-
 .../transformHtmlCodeBlock.test.ts            | 225 +++++++++++++++++-
 .../transformHtmlCodeBlock.ts                 |  31 ++-
 .../src/withDocsInfra/withDocsInfra.test.ts   | 116 +++++++++
 .../src/withDocsInfra/withDocsInfra.ts        |  30 ++-
 17 files changed, 778 insertions(+), 35 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/load-precomputed-types/page.mdx b/docs/app/docs-infra/pipeline/load-precomputed-types/page.mdx
index 9dd90eedf..c9b7a32a3 100644
--- a/docs/app/docs-infra/pipeline/load-precomputed-types/page.mdx
+++ b/docs/app/docs-infra/pipeline/load-precomputed-types/page.mdx
@@ -19,6 +19,7 @@ The loader processes `types.ts` files that use the `createTypes` factory pattern
 - **Dependency tracking**: Tracks all source files and updates when types change
 - **Performance logging**: Optional detailed timing measurements for debugging
 - **Configurable formatting**: Control how union types and default values are displayed
+- **Configurable code block emphasis**: Tune focus and padding limits for code blocks found in extracted descriptions and examples
 
 ## Usage
 
@@ -160,6 +161,7 @@ config.module.rules.push({
         performance: { logging: true, notableMs: 100 },
         formatting: { shortTypeUnionPrintWidth: 50, defaultValueUnionPrintWidth: 40 },
         socketDir: '.next/docs-infra',
+        codeBlockEmphasisOptions: { paddingFrameMaxSize: 12, focusFramesMaxSize: 40 },
         // Strip "Documentation: <url>" suffixes from descriptions
         descriptionReplacements: [
           { pattern: '\\n\\nDocumentation:.*$', replacement: '', flags: 'm' },
diff --git a/docs/app/docs-infra/pipeline/load-server-types/page.mdx b/docs/app/docs-infra/pipeline/load-server-types/page.mdx
index 82898aadd..3edbfd9a2 100644
--- a/docs/app/docs-infra/pipeline/load-server-types/page.mdx
+++ b/docs/app/docs-infra/pipeline/load-server-types/page.mdx
@@ -33,6 +33,10 @@ const result = await loadServerTypes({
     shortTypeUnionPrintWidth: 40,
     defaultValueUnionPrintWidth: 40,
   },
+  codeBlockEmphasisOptions: {
+    paddingFrameMaxSize: 12,
+    focusFramesMaxSize: 40,
+  },
 });
 
 // result.exports — Record<string, ExportData> with highlighted types
@@ -113,6 +117,8 @@ Transforms markdown content within type descriptions and examples with syntax hi
 - Prop/parameter/property examples and descriptions
 - Data attribute and CSS variable descriptions
 
+Use `codeBlockEmphasisOptions` when these code blocks need different focus or padding limits than the authored MDX defaults.
+
 Also builds a `highlightedExports` map used by the next stage for expanding type references.
 
 > **Note**: Type strings (`typeText`, `defaultText`) remain as plain text at this stage.
diff --git a/docs/app/docs-infra/pipeline/page.mdx b/docs/app/docs-infra/pipeline/page.mdx
index 8a99f0d28..ea5247fa5 100644
--- a/docs/app/docs-infra/pipeline/page.mdx
+++ b/docs/app/docs-infra/pipeline/page.mdx
@@ -1448,6 +1448,7 @@ The `withDocsInfra` function is a Next.js configuration plugin that sets up webp
   - Default MDX Plugins
     - Remark Plugins (Markdown processing)
     - Rehype Plugins (HTML processing)
+    - Code Emphasis Configuration
   - Example: Custom Demo Structure
   - How It Works
   - Integration Example
diff --git a/docs/app/docs-infra/pipeline/transform-html-code-block/page.mdx b/docs/app/docs-infra/pipeline/transform-html-code-block/page.mdx
index 848abc54e..4abc1b9ee 100644
--- a/docs/app/docs-infra/pipeline/transform-html-code-block/page.mdx
+++ b/docs/app/docs-infra/pipeline/transform-html-code-block/page.mdx
@@ -15,6 +15,7 @@ This plugin is typically used in the **second stage** of a markdown-to-HTML proc
 - **Opt-in transformations**: Code blocks are only transformed when marked with `data-transform="true"`
 - **Built-in transformations**: Includes TypeScript-to-JavaScript conversion for marked blocks
 - **Syntax highlighting**: Pre-processes code for faster client rendering
+- **Lenient emphasis defaults**: Inline `@highlight` and `@focus` regions keep up to 25 lines of surrounding context and up to 60 visible focused lines before collapsing
 - **JSX expression cleanup**: Strips trailing semicolons from solo JSX expression lines in `jsx`/`tsx` code blocks
 - **Ignore comment stripping**: Automatically removes tool-specific ignore comments (`prettier-ignore`, `eslint-disable`, `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`) that are noise in documentation
 - **Error handling**: Gracefully handles processing errors
@@ -26,24 +27,43 @@ import { unified } from 'unified';
 import rehypeParse from 'rehype-parse';
 import transformHtmlCodeBlock from '@mui/internal-docs-infra/pipeline/transformHtmlCodeBlock';
 
+const processor = unified().use(rehypeParse).use(transformHtmlCodeBlock).use(rehypeStringify);
+```
+
+## Optional Configuration
+
+You can override the site-wide fallback emphasis window for authored inline code blocks:
+
+```typescript
 const processor = unified()
   .use(rehypeParse)
-  .use(transformHtmlCodeBlock) // No configuration needed
+  .use(transformHtmlCodeBlock, {
+    paddingFrameMaxSize: 12,
+    focusFramesMaxSize: 40,
+  })
   .use(rehypeStringify);
 ```
 
+These values are only the default fallback used by the plugin. Per-block `@padding` and `@min`
+directives still take precedence when they are present in the source.
+
 ### With Next.js and MDX
 
 ```javascript
-// next.config.js
-const withMDX = require('@next/mdx')({
-  options: {
-    remarkPlugins: [transformMarkdownCodeVariants],
-    rehypePlugins: [transformHtmlCodeBlock],
-  },
+// next.config.mjs
+import createMDX from '@next/mdx';
+import { getDocsInfraMdxOptions } from '@mui/internal-docs-infra/withDocsInfra';
+
+const withMDX = createMDX({
+  options: getDocsInfraMdxOptions({
+    codeBlockEmphasisOptions: {
+      paddingFrameMaxSize: 12,
+      focusFramesMaxSize: 40,
+    },
+  }),
 });
 
-module.exports = withMDX({
+export default withMDX({
   // your Next.js config
 });
 ```
diff --git a/docs/app/docs-infra/pipeline/with-docs-infra/page.mdx b/docs/app/docs-infra/pipeline/with-docs-infra/page.mdx
index 89250e25a..e7afd8249 100644
--- a/docs/app/docs-infra/pipeline/with-docs-infra/page.mdx
+++ b/docs/app/docs-infra/pipeline/with-docs-infra/page.mdx
@@ -37,6 +37,12 @@ const withMDX = createMDX({
       include: ['app/docs', 'app/api'],
       exclude: ['app/docs/internal'],
     },
+
+    // Configure authored MDX code blocks processed by transformHtmlCodeBlock
+    codeBlockEmphasisOptions: {
+      paddingFrameMaxSize: 12,
+      focusFramesMaxSize: 40,
+    },
   }),
 });
 
@@ -70,6 +76,18 @@ export default withDocsInfra({
   // Strip @internal comments from displayed source
   removeCommentsWithPrefix: ['@internal'],
 
+  // Configure demo loaders used for /demos/*/index.ts files
+  demoEmphasisOptions: {
+    paddingFrameMaxSize: 2,
+    focusFramesMaxSize: 18,
+  },
+
+  // Configure code blocks rendered from generated type metadata
+  codeBlockEmphasisOptions: {
+    paddingFrameMaxSize: 12,
+    focusFramesMaxSize: 40,
+  },
+
   // Strip "Documentation: <url>" suffixes from extracted JSDoc descriptions
   descriptionReplacements: [{ pattern: '\\n\\nDocumentation:.*$', replacement: '', flags: 'm' }],
 })(withMDX(nextConfig));
@@ -190,6 +208,34 @@ export default withDocsInfra()(withMDX(nextConfig));
 
 - [`transformHtmlCodeBlock`](../transform-html-code-block/page.mdx) - Transform HTML code elements
 
+### Code Emphasis Configuration
+
+Use `demoEmphasisOptions` on `withDocsInfra()` for demo loader output. Use
+`codeBlockEmphasisOptions` on `getDocsInfraMdxOptions()` for authored MDX code blocks,
+and on `withDocsInfra()` for code blocks rendered from generated type metadata.
+
+```js
+const withMDX = createMDX({
+  options: getDocsInfraMdxOptions({
+    codeBlockEmphasisOptions: {
+      paddingFrameMaxSize: 12,
+      focusFramesMaxSize: 40,
+    },
+  }),
+});
+
+export default withDocsInfra({
+  codeBlockEmphasisOptions: {
+    paddingFrameMaxSize: 12,
+    focusFramesMaxSize: 40,
+  },
+  demoEmphasisOptions: {
+    paddingFrameMaxSize: 2,
+    focusFramesMaxSize: 18,
+  },
+})(withMDX(nextConfig));
+```
+
 ## Example: Custom Demo Structure
 
 If your demos follow a different pattern (e.g., `demo-variant/index.ts`):
diff --git a/docs/app/docs-infra/pipeline/with-docs-infra/types.md b/docs/app/docs-infra/pipeline/with-docs-infra/types.md
index a6f6d48da..2a40678fc 100644
--- a/docs/app/docs-infra/pipeline/with-docs-infra/types.md
+++ b/docs/app/docs-infra/pipeline/with-docs-infra/types.md
@@ -94,6 +94,11 @@ type DocsInfraMdxOptions = {
    * @default 'tsx'
    */
   defaultInlineCodeLanguage?: string | false;
+  /**
+   * Options for authored MDX code blocks processed by `transformHtmlCodeBlock`.
+   * Passed to `transformHtmlCodeBlock` in the default rehype plugin list.
+   */
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
 };
 ```
 
@@ -166,10 +171,15 @@ type WithDocsInfraOptions = {
    */
   notableCommentsPrefix?: string[];
   /**
-   * Options for the code emphasis enhancer (padding frames, focus frames, etc.).
+   * Options for the code emphasis enhancer used by demo loaders.
    * Passed to `createEnhanceCodeEmphasis` in the precomputed code highlighter loader.
    */
-  emphasisOptions?: EnhanceCodeEmphasisOptions;
+  demoEmphasisOptions?: EnhanceCodeEmphasisOptions;
+  /**
+   * Options for code blocks rendered inside generated type metadata.
+   * Passed to `transformHtmlCodeBlock` through the types loader pipeline.
+   */
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
   /**
    * Name of the index file to update when syncing types metadata to parent indexes.
    * The types loader will call syncPageIndex to update the parent directory's index
diff --git a/docs/next.config.mjs b/docs/next.config.mjs
index 26a0318b8..ac9e9e0f8 100644
--- a/docs/next.config.mjs
+++ b/docs/next.config.mjs
@@ -56,7 +56,7 @@ export default withDeploymentConfig(
         index: ['./app/**/demos/*/demo-*/index.ts'],
         client: ['./app/**/demos/*/demo-*/client.ts'],
       },
-      emphasisOptions: { paddingFrameMaxSize: 2, focusFramesMaxSize: 18 },
+      demoEmphasisOptions: { paddingFrameMaxSize: 2, focusFramesMaxSize: 18 },
     })(withMDX(nextConfig)),
   ),
 );
diff --git a/packages/docs-infra/src/pipeline/loadPrecomputedTypes/loadPrecomputedTypes.ts b/packages/docs-infra/src/pipeline/loadPrecomputedTypes/loadPrecomputedTypes.ts
index 0f4094116..47699497b 100644
--- a/packages/docs-infra/src/pipeline/loadPrecomputedTypes/loadPrecomputedTypes.ts
+++ b/packages/docs-infra/src/pipeline/loadPrecomputedTypes/loadPrecomputedTypes.ts
@@ -20,6 +20,7 @@ import { loadServerTypes } from '../loadServerTypes';
 import type { SyncPageIndexBaseOptions } from '../transformMarkdownMetadata/types';
 import { rewriteImportsToNull } from '../loaderUtils/rewriteImports';
 import type { OrderingConfig } from '../loadServerTypesText/order';
+import type { TransformHtmlCodeBlockOptions } from '../transformHtmlCodeBlock/transformHtmlCodeBlock';
 
 export type LoaderOptions = {
   /** Performance tracking and logging options */
@@ -72,6 +73,8 @@ export type LoaderOptions = {
    * Each entry has a `pattern` (regex string) and `replacement` string.
    */
   descriptionReplacements?: DescriptionReplacement[];
+  /** Options for code blocks highlighted inside generated type metadata */
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
 };
 
 const functionName = 'Load Precomputed Types';
@@ -172,6 +175,7 @@ export async function loadPrecomputedTypes(
       externalTypesPattern: options.externalTypesPattern,
       ordering: options.ordering,
       descriptionReplacements: options.descriptionReplacements,
+      codeBlockEmphasisOptions: options.codeBlockEmphasisOptions,
       sync: true,
       output: 'hastCompressed',
     });
diff --git a/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypes.test.ts b/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypes.test.ts
index 3556cf789..7cb962753 100644
--- a/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypes.test.ts
+++ b/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypes.test.ts
@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest';
+import type { Element } from 'hast';
 import { decompressHastAsync } from '../hastUtils';
 import { highlightTypes } from './highlightTypes';
 import type { TypesMeta } from '../loadServerTypesMeta';
@@ -40,6 +41,31 @@ function findPreElements(node: any): any[] {
   return [];
 }
 
+function hasClassName(
+  node: { properties?: { className?: string | string[] } },
+  className: string,
+): boolean {
+  const nodeClassName = node.properties?.className;
+
+  if (Array.isArray(nodeClassName)) {
+    return nodeClassName.includes(className);
+  }
+
+  return nodeClassName === className;
+}
+
+function getFrameElements(source: { children?: any[] }): Element[] {
+  return (source.children ?? []).filter(
+    (child): child is Element => child?.type === 'element' && hasClassName(child, 'frame'),
+  );
+}
+
+function countFrameLines(frame: Element): number {
+  return frame.children.filter(
+    (child): child is Element => child.type === 'element' && hasClassName(child, 'line'),
+  ).length;
+}
+
 describe('highlightTypes', () => {
   describe('component type transformation', () => {
     it('should add dataPrecompute to code blocks in component description', async () => {
@@ -296,6 +322,68 @@ describe('highlightTypes', () => {
         expect(hasDataPrecompute(preElements[0])).toBe(true);
       }
     });
+
+    it('should pass codeBlockEmphasisOptions to description code blocks', async () => {
+      const codeLines = Array.from({ length: 90 }, (_, index) => {
+        if (index === 39) {
+          return `const line${index + 1} = ${index + 1}; // @highlight`;
+        }
+
+        return `const line${index + 1} = ${index + 1};`;
+      }).join('\n');
+
+      const types: TypesMeta[] = [
+        {
+          type: 'component' as const,
+          name: 'Button',
+          data: {
+            name: 'Button',
+            description: {
+              type: 'root',
+              children: [
+                {
+                  type: 'element',
+                  tagName: 'pre',
+                  properties: {},
+                  children: [
+                    {
+                      type: 'element',
+                      tagName: 'code',
+                      properties: { className: ['language-ts'] },
+                      children: [{ type: 'text', value: codeLines }],
+                    },
+                  ],
+                },
+              ],
+            },
+            props: {},
+            dataAttributes: {},
+            cssVariables: {},
+          },
+        },
+      ] as any;
+
+      const result = await highlightTypes(types, {}, 'hast', {
+        paddingFrameMaxSize: 5,
+      });
+
+      const componentData = result.types[0];
+      if (componentData.type === 'component') {
+        const preElements = findPreElements(componentData.data.description);
+        expect(preElements).toHaveLength(1);
+
+        const precomputeData = parsePrecomputeData(preElements[0]);
+        const frames = getFrameElements(precomputeData.Default.source);
+
+        expect(frames).toHaveLength(5);
+        expect(frames[1].properties?.dataFrameType).toBe('padding-top');
+        expect(frames[2].properties?.dataFrameType).toBe('highlighted');
+        expect(frames[3].properties?.dataFrameType).toBe('padding-bottom');
+        expect(countFrameLines(frames[1])).toBe(5);
+        expect(countFrameLines(frames[2])).toBe(1);
+        expect(countFrameLines(frames[3])).toBe(5);
+      }
+    });
   });
 
   describe('hook type transformation', () => {
diff --git a/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypes.ts b/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypes.ts
index ca89ed135..7a03a1e48 100644
--- a/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypes.ts
+++ b/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypes.ts
@@ -1,7 +1,10 @@
 import { unified } from 'unified';
 import type { Root as HastRoot } from 'hast';
 import transformHtmlCodeInline from '../transformHtmlCodeInline';
-import { transformHtmlCodeBlock } from '../transformHtmlCodeBlock/transformHtmlCodeBlock';
+import {
+  transformHtmlCodeBlock,
+  type TransformHtmlCodeBlockOptions,
+} from '../transformHtmlCodeBlock/transformHtmlCodeBlock';
 import {
   type ComponentTypeMeta,
   type HookTypeMeta,
@@ -50,8 +53,11 @@ export async function highlightTypes(
   types: TypesMeta[],
   externalTypes: Record<string, string> = {},
   output: TypesOutputFormat = 'hast',
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions,
 ): Promise<HighlightTypesResult> {
-  const processor = unified().use(transformHtmlCodeInline).use(transformHtmlCodeBlock);
+  const processor = unified()
+    .use(transformHtmlCodeInline)
+    .use(transformHtmlCodeBlock, codeBlockEmphasisOptions);
 
   const transformedTypes = await Promise.all(
     types.map(async (typeMeta) => {
diff --git a/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypesMeta.test.ts b/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypesMeta.test.ts
index 90a0a331e..e3cb4d8fa 100644
--- a/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypesMeta.test.ts
+++ b/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypesMeta.test.ts
@@ -12,6 +12,61 @@ import type { SerializedHastRoot, SerializedHastCompressed } from './hastTypeUti
 
 type HastField = HastRoot | SerializedHastRoot | SerializedHastCompressed;
 
+function hasDataPrecompute(node: any): boolean {
+  return (
+    node?.type === 'element' &&
+    node.tagName === 'pre' &&
+    typeof node.properties?.dataPrecompute === 'string'
+  );
+}
+
+function parsePrecomputeData(node: any): any {
+  if (hasDataPrecompute(node)) {
+    return JSON.parse(node.properties.dataPrecompute);
+  }
+
+  return null;
+}
+
+function findPreElements(node: any): any[] {
+  if (!node) {
+    return [];
+  }
+  if (node.type === 'element' && node.tagName === 'pre') {
+    return [node];
+  }
+  if (node.children && Array.isArray(node.children)) {
+    return node.children.flatMap((child: any) => findPreElements(child));
+  }
+
+  return [];
+}
+
+function hasClassName(
+  node: { properties?: { className?: string | string[] } },
+  className: string,
+): boolean {
+  const nodeClassName = node.properties?.className;
+
+  if (Array.isArray(nodeClassName)) {
+    return nodeClassName.includes(className);
+  }
+
+  return nodeClassName === className;
+}
+
+function getFrameElements(source: { children?: any[] }) {
+  return (source.children ?? []).filter(
+    (child: any) => child?.type === 'element' && hasClassName(child, 'frame'),
+  );
+}
+
+function countFrameLines(frame: any): number {
+  return frame.children.filter(
+    (child: any) => child.type === 'element' && hasClassName(child, 'line'),
+  ).length;
+}
+
 /**
  * Helper to check if a highlighted property has the expected fields
  */
@@ -321,6 +376,84 @@ describe('highlightTypesMeta', () => {
       }
     });
 
+    it('should pass codeBlockEmphasisOptions to raw property descriptions', async () => {
+      const codeLines = Array.from({ length: 90 }, (_, index) => {
+        if (index === 39) {
+          return `const line${index + 1} = ${index + 1}; // @highlight`;
+        }
+
+        return `const line${index + 1} = ${index + 1};`;
+      }).join('\n');
+
+      const types: TypesMeta[] = [
+        {
+          type: 'hook',
+          name: 'useFilter',
+          data: {
+            name: 'useFilter',
+            parameters: [
+              {
+                name: 'options',
+                typeText: 'FilterOptions',
+              },
+            ],
+            returnValue: 'Filter',
+          } as HookTypeMeta,
+        },
+      ];
+
+      const rawTypeProperties = {
+        FilterOptions: {
+          locale: {
+            typeText: 'string',
+            description: {
+              type: 'root',
+              children: [
+                {
+                  type: 'element',
+                  tagName: 'pre',
+                  properties: {},
+                  children: [
+                    {
+                      type: 'element',
+                      tagName: 'code',
+                      properties: { className: ['language-ts'] },
+                      children: [{ type: 'text', value: codeLines }],
+                    },
+                  ],
+                },
+              ],
+            } as HastRoot,
+          },
+        },
+      };
+
+      const result = await highlightTypesMeta(types, {
+        rawTypeProperties,
+        codeBlockEmphasisOptions: {
+          paddingFrameMaxSize: 5,
+        },
+      });
+
+      const hook = result[0];
+      expect(hook.type).toBe('hook');
+      if (hook.type === 'hook') {
+        const preElements = findPreElements(hook.data.expandedProperties!.locale.description);
+        expect(preElements).toHaveLength(1);
+
+        const precomputeData = parsePrecomputeData(preElements[0]);
+        const frames = getFrameElements(precomputeData.Default.source);
+
+        expect(frames).toHaveLength(5);
+        expect(frames[1].properties?.dataFrameType).toBe('padding-top');
+        expect(frames[2].properties?.dataFrameType).toBe('highlighted');
+        expect(frames[3].properties?.dataFrameType).toBe('padding-bottom');
+        expect(countFrameLines(frames[1])).toBe(5);
+        expect(countFrameLines(frames[2])).toBe(1);
+        expect(countFrameLines(frames[3])).toBe(5);
+      }
+    });
+
     it('should expand single parameter with generic type args by stripping generics', async () => {
       const types: TypesMeta[] = [
         {
diff --git a/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypesMeta.ts b/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypesMeta.ts
index 3b0ccccb7..bb68845b8 100644
--- a/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypesMeta.ts
+++ b/packages/docs-infra/src/pipeline/loadServerTypes/highlightTypesMeta.ts
@@ -10,7 +10,10 @@
 
 import type { Root as HastRoot } from 'hast';
 import { unified } from 'unified';
-import { transformHtmlCodeBlock } from '../transformHtmlCodeBlock/transformHtmlCodeBlock';
+import {
+  transformHtmlCodeBlock,
+  type TransformHtmlCodeBlockOptions,
+} from '../transformHtmlCodeBlock/transformHtmlCodeBlock';
 import transformHtmlCodeInline from '../transformHtmlCodeInline';
 import {
   type TypesMeta,
@@ -102,9 +105,12 @@ type PreProcessedProperty = Omit<FormattedProperty, 'description' | 'example'> &
 async function highlightRawProperties(
   properties: Record<string, FormattedProperty>,
   output: TypesOutputFormat,
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions,
 ): Promise<Record<string, PreProcessedProperty>> {
   const s = resolveSerializer(output);
-  const processor = unified().use(transformHtmlCodeInline).use(transformHtmlCodeBlock);
+  const processor = unified()
+    .use(transformHtmlCodeInline)
+    .use(transformHtmlCodeBlock, codeBlockEmphasisOptions);
 
   const entries = await Promise.all(
     Object.entries(properties).map(async ([name, prop]) => {
@@ -353,6 +359,8 @@ export interface HighlightTypesMetaOptions {
   rawTypeProperties?: Record<string, Record<string, FormattedProperty>>;
   /** Options for inline type formatting */
   formatting?: FormatInlineTypeOptions;
+  /** Options for code blocks highlighted inside raw type descriptions and examples */
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
   /**
    * When true, replaces every HastRoot field in the output with
    * `{ hastJson: string }` (typed as HastRoot to keep the interface stable).
@@ -379,7 +387,12 @@ export async function highlightTypesMeta(
   types: TypesMeta[],
   options: HighlightTypesMetaOptions = {},
 ): Promise<HighlightedTypesMeta[]> {
-  const { highlightedExports = {}, rawTypeProperties = {}, formatting } = options;
+  const {
+    highlightedExports = {},
+    rawTypeProperties = {},
+    formatting,
+    codeBlockEmphasisOptions,
+  } = options;
 
   const shortTypeUnionPrintWidth =
     formatting?.shortTypeUnionPrintWidth ?? DEFAULT_UNION_PRINT_WIDTH;
@@ -416,6 +429,7 @@ export async function highlightTypesMeta(
             typePrintWidth,
             topLevelTypePrintWidth,
             output,
+            codeBlockEmphasisOptions,
           ),
         };
       }
@@ -431,6 +445,7 @@ export async function highlightTypesMeta(
             typePrintWidth,
             topLevelTypePrintWidth,
             output,
+            codeBlockEmphasisOptions,
           ),
         };
       }
@@ -514,6 +529,7 @@ async function highlightHookTypeMeta(
   typePrintWidth: number,
   topLevelTypePrintWidth: number | undefined,
   output: TypesOutputFormat,
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions,
 ): Promise<HighlightedHookTypeMeta> {
   const s = resolveSerializer(output);
 
@@ -565,7 +581,11 @@ async function highlightHookTypeMeta(
       const paramMatch = lookupRawTypeProperties(paramTypeText, rawTypeProperties);
       if (paramMatch) {
         expandedTypeName = paramMatch.name;
-        const highlightedProps = await highlightRawProperties(paramMatch.properties, output);
+        const highlightedProps = await highlightRawProperties(
+          paramMatch.properties,
+          output,
+          codeBlockEmphasisOptions,
+        );
         const propEntries = await Promise.all(
           Object.entries(highlightedProps).map(async ([propName, prop]) => {
             const highlighted = await highlightPropertyMeta(
@@ -595,7 +615,11 @@ async function highlightHookTypeMeta(
     const returnMatch = lookupRawTypeProperties(data.returnValue, rawTypeProperties);
     if (returnMatch) {
       returnValueTypeName = returnMatch.name;
-      const highlightedProps = await highlightRawProperties(returnMatch.properties, output);
+      const highlightedProps = await highlightRawProperties(
+        returnMatch.properties,
+        output,
+        codeBlockEmphasisOptions,
+      );
       const returnValueEntries = await Promise.all(
         Object.entries(highlightedProps).map(async ([propName, prop]) => {
           const highlighted = await highlightPropertyMeta(
@@ -690,6 +714,7 @@ async function highlightFunctionTypeMeta(
   typePrintWidth: number,
   topLevelTypePrintWidth: number | undefined,
   output: TypesOutputFormat,
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions,
 ): Promise<HighlightedFunctionTypeMeta> {
   const s = resolveSerializer(output);
 
@@ -741,7 +766,11 @@ async function highlightFunctionTypeMeta(
       const funcParamMatch = lookupRawTypeProperties(paramTypeText, rawTypeProperties);
       if (funcParamMatch) {
         expandedTypeName = funcParamMatch.name;
-        const highlightedProps = await highlightRawProperties(funcParamMatch.properties, output);
+        const highlightedProps = await highlightRawProperties(
+          funcParamMatch.properties,
+          output,
+          codeBlockEmphasisOptions,
+        );
         const propEntries = await Promise.all(
           Object.entries(highlightedProps).map(async ([propName, prop]) => {
             const highlighted = await highlightPropertyMeta(
@@ -770,7 +799,11 @@ async function highlightFunctionTypeMeta(
     const funcReturnMatch = lookupRawTypeProperties(data.returnValue, rawTypeProperties);
     if (funcReturnMatch) {
       returnValueTypeName = funcReturnMatch.name;
-      const highlightedProps = await highlightRawProperties(funcReturnMatch.properties, output);
+      const highlightedProps = await highlightRawProperties(
+        funcReturnMatch.properties,
+        output,
+        codeBlockEmphasisOptions,
+      );
       const returnValueEntries = await Promise.all(
         Object.entries(highlightedProps).map(async ([propName, prop]) => {
           const highlighted = await highlightPropertyMeta(
diff --git a/packages/docs-infra/src/pipeline/loadServerTypes/loadServerTypes.ts b/packages/docs-infra/src/pipeline/loadServerTypes/loadServerTypes.ts
index 014b054dc..ec8fefb27 100644
--- a/packages/docs-infra/src/pipeline/loadServerTypes/loadServerTypes.ts
+++ b/packages/docs-infra/src/pipeline/loadServerTypes/loadServerTypes.ts
@@ -22,6 +22,7 @@ import { loadServerTypesText, type TypesSourceData } from '../loadServerTypesTex
 import type { FormattedProperty, TypesMeta } from '../loadServerTypesMeta';
 import type { ExportData } from '../../abstractCreateTypes';
 import type { TypesOutputFormat } from './hastTypeUtils';
+import type { TransformHtmlCodeBlockOptions } from '../transformHtmlCodeBlock/transformHtmlCodeBlock';
 
 export type {
   HighlightedTypesMeta,
@@ -67,6 +68,8 @@ export interface LoadServerTypesOptions extends SyncTypesOptions {
    * @default 'hast'
    */
   output?: TypesOutputFormat;
+  /** Options for code blocks highlighted inside generated type metadata */
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
 }
 
 export interface LoadServerTypesResult {
@@ -122,6 +125,7 @@ export async function loadServerTypes(
     formattingOptions,
     sync = false,
     output = 'hast',
+    codeBlockEmphasisOptions,
   } = options;
 
   // Derive relative path for logging
@@ -210,12 +214,18 @@ export async function loadServerTypes(
   const processedExports = await Promise.all(
     exportEntries.map(async ([exportName, exportData]) => {
       const exportTypes = [exportData.type, ...exportData.additionalTypes];
-      const highlightResult = await highlightTypes(exportTypes, syncResult.externalTypes, output);
+      const highlightResult = await highlightTypes(
+        exportTypes,
+        syncResult.externalTypes,
+        output,
+        codeBlockEmphasisOptions,
+      );
       const highlightedTypes = await highlightTypesMeta(highlightResult.types, {
         highlightedExports: highlightResult.highlightedExports,
         rawTypeProperties: sharedRawTypeProperties,
         formatting: formattingOptions,
         output,
+        codeBlockEmphasisOptions,
       });
 
       // First highlighted type is the main export type, rest are additional
@@ -242,12 +252,14 @@ export async function loadServerTypes(
       syncResult.additionalTypes,
       syncResult.externalTypes,
       output,
+      codeBlockEmphasisOptions,
     );
     additionalTypes = await highlightTypesMeta(highlightResult.types, {
       highlightedExports: highlightResult.highlightedExports,
       rawTypeProperties: sharedRawTypeProperties,
       formatting: formattingOptions,
       output,
+      codeBlockEmphasisOptions,
     });
   }
 
@@ -260,12 +272,18 @@ export async function loadServerTypes(
         if (types.length === 0) {
           return { variantName, enhanced: [] as HighlightedTypesMeta[] };
         }
-        const highlightResult = await highlightTypes(types, syncResult.externalTypes, output);
+        const highlightResult = await highlightTypes(
+          types,
+          syncResult.externalTypes,
+          output,
+          codeBlockEmphasisOptions,
+        );
         const enhanced = await highlightTypesMeta(highlightResult.types, {
           highlightedExports: highlightResult.highlightedExports,
           rawTypeProperties: sharedRawTypeProperties,
           formatting: formattingOptions,
           output,
+          codeBlockEmphasisOptions,
         });
         return { variantName, enhanced };
       }),
diff --git a/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.test.ts b/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.test.ts
index fa1b80b27..98ddf672e 100644
--- a/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.test.ts
+++ b/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.test.ts
@@ -3,9 +3,12 @@ import { unified } from 'unified';
 import rehypeParse from 'rehype-parse';
 import remarkParse from 'remark-parse';
 import remarkRehype from 'remark-rehype';
+import type { Element } from 'hast';
 import { transformHtmlCodeBlock } from './transformHtmlCodeBlock';
+import type { TransformHtmlCodeBlockOptions } from './transformHtmlCodeBlock';
 import { transformMarkdownCode } from '../transformMarkdownCode/transformMarkdownCode';
-import type { VariantCode } from '../../CodeHighlighter/types';
+import { loadCodeVariant } from '../loadCodeVariant/loadCodeVariant';
+import type { SourceComments, SourceEnhancers, VariantCode } from '../../CodeHighlighter/types';
 
 // Mock the loadCodeVariant function
 vi.mock('../loadCodeVariant/loadCodeVariant', () => ({
@@ -30,19 +33,85 @@ vi.mock('../loadCodeVariant/loadCodeVariant', () => ({
 }));
 
 describe('transformHtmlCodeBlock', () => {
-  const getAstFromHtml = async (html: string) => {
-    const processor = unified().use(rehypeParse, { fragment: true }).use(transformHtmlCodeBlock);
+  const hasClassName = (
+    node: { properties?: { className?: string | string[] } },
+    className: string,
+  ) => {
+    const nodeClassName = node.properties?.className;
+
+    if (Array.isArray(nodeClassName)) {
+      return nodeClassName.includes(className);
+    }
+
+    return nodeClassName === className;
+  };
+
+  const convertCommentsToOneIndexed = (comments: SourceComments | undefined) => {
+    if (!comments) {
+      return undefined;
+    }
+
+    const converted: SourceComments = {};
+    Object.entries(comments).forEach(([lineStr, commentArray]) => {
+      converted[Number(lineStr) + 1] = commentArray;
+    });
+
+    return converted;
+  };
+
+  const applySourceEnhancers = async (
+    variant: VariantCode,
+    sourceEnhancers: SourceEnhancers | undefined,
+    fileName: string,
+    parser:
+      | Promise<(source: string, fileName: string, language?: string) => any>
+      | ((source: string, fileName: string, language?: string) => any)
+      | undefined,
+  ) => {
+    if (!parser || !variant.source || typeof variant.source !== 'string') {
+      return variant.source;
+    }
+
+    const parseSource = await parser;
+    let parsedSource = parseSource(variant.source, fileName, variant.language);
+    if (!sourceEnhancers || sourceEnhancers.length === 0) {
+      return parsedSource;
+    }
+
+    const comments = convertCommentsToOneIndexed(variant.comments);
+    parsedSource = await sourceEnhancers.reduce(
+      async (accPromise, enhancer) => enhancer(await accPromise, comments, fileName),
+      Promise.resolve(parsedSource),
+    );
+
+    return parsedSource;
+  };
+
+  const getFrameElements = (source: { children?: any[] }) =>
+    (source.children ?? []).filter(
+      (child): child is Element => child?.type === 'element' && hasClassName(child, 'frame'),
+    );
+
+  const countFrameLines = (frame: Element) =>
+    frame.children.filter(
+      (child): child is Element => child.type === 'element' && hasClassName(child, 'line'),
+    ).length;
+
+  const getAstFromHtml = async (html: string, options?: TransformHtmlCodeBlockOptions) => {
+    const processor = unified()
+      .use(rehypeParse, { fragment: true })
+      .use(transformHtmlCodeBlock, options);
     const tree = await processor.run(processor.parse(html));
     return tree as any;
   };
 
   // More realistic test that mimics Next.js MDX processing pipeline
-  const getAstFromMarkdown = async (markdown: string) => {
+  const getAstFromMarkdown = async (markdown: string, options?: TransformHtmlCodeBlockOptions) => {
     const processor = unified()
       .use(remarkParse) // Parse markdown
       .use(transformMarkdownCode) // Convert markdown code blocks to semantic HTML
       .use(remarkRehype, { allowDangerousHtml: true }) // Convert markdown to HTML AST
-      .use(transformHtmlCodeBlock); // Apply our rehype plugin
+      .use(transformHtmlCodeBlock, options); // Apply our rehype plugin
 
     const tree = await processor.run(processor.parse(markdown));
     return tree as any;
@@ -522,6 +591,152 @@ const x = 1; // @highlight
     expect(precomputeData.Default.comments['0']).toContain('@highlight');
   });
 
+  function mockLoadCodeVariantWithEnhancers() {
+    vi.mocked(loadCodeVariant).mockImplementationOnce(
+      async (
+        _url: string | undefined,
+        _variantName: string,
+        variant: string | VariantCode | undefined,
+        options?: any,
+      ) => {
+        if (!variant || typeof variant === 'string' || !options) {
+          throw new Error('Expected transformHtmlCodeBlock to pass a variant object and options');
+        }
+
+        const fileName = variant.fileName ?? 'code.js';
+        const source = await applySourceEnhancers(
+          variant,
+          options.sourceEnhancers,
+          fileName,
+          options.sourceParser,
+        );
+
+        return {
+          code: {
+            ...variant,
+            source,
+          },
+          dependencies: [],
+          externals: {},
+        };
+      },
+    );
+  }
+
+  it('should use 25 lines of context padding by default for authored page code blocks', async () => {
+    mockLoadCodeVariantWithEnhancers();
+
+    const codeLines = Array.from({ length: 90 }, (_, index) => {
+      if (index === 39) {
+        return `const line${index + 1} = ${index + 1}; // @highlight`;
+      }
+
+      return `const line${index + 1} = ${index + 1};`;
+    }).join('\n');
+
+    const html = `<pre><code class="language-javascript">${codeLines}</code></pre>`;
+
+    const ast = await getAstFromHtml(html);
+    const preElement = findPreElement(ast);
+    expect(preElement).toBeTruthy();
+    const precomputeData = JSON.parse(preElement.properties.dataPrecompute);
+    const frames = getFrameElements(precomputeData.Default.source);
+
+    expect(frames).toHaveLength(5);
+    expect(frames[1].properties?.dataFrameType).toBe('padding-top');
+    expect(frames[2].properties?.dataFrameType).toBe('highlighted');
+    expect(frames[3].properties?.dataFrameType).toBe('padding-bottom');
+    expect(countFrameLines(frames[1])).toBe(25);
+    expect(countFrameLines(frames[2])).toBe(1);
+    expect(countFrameLines(frames[3])).toBe(25);
+  });
+
+  it('should cap focused regions at 60 lines by default for authored page code blocks', async () => {
+    mockLoadCodeVariantWithEnhancers();
+
+    const codeLines = Array.from(
+      { length: 70 },
+      (_, index) => `const line${index + 1} = ${index + 1};`,
+    ).join('\n');
+
+    const html = `<pre><code class="language-javascript">// @highlight-start
+  ${codeLines}
+  // @highlight-end</code></pre>`;
+
+    const ast = await getAstFromHtml(html);
+    const preElement = findPreElement(ast);
+    expect(preElement).toBeTruthy();
+    const precomputeData = JSON.parse(preElement.properties.dataPrecompute);
+    const frames = getFrameElements(precomputeData.Default.source);
+
+    expect(frames).toHaveLength(2);
+    expect(frames[0].properties?.dataFrameType).toBe('highlighted');
+    expect(frames[0].properties?.dataFrameTruncated).toBe('visible');
+    expect(frames[1].properties?.dataFrameType).toBe('highlighted-unfocused');
+    expect(frames[1].properties?.dataFrameTruncated).toBe('hidden');
+    expect(countFrameLines(frames[0])).toBe(60);
+    expect(countFrameLines(frames[1])).toBe(10);
+  });
+
+  it('should allow overriding the default padding context via plugin options', async () => {
+    mockLoadCodeVariantWithEnhancers();
+
+    const codeLines = Array.from({ length: 90 }, (_, index) => {
+      if (index === 39) {
+        return `const line${index + 1} = ${index + 1}; // @highlight`;
+      }
+
+      return `const line${index + 1} = ${index + 1};`;
+    }).join('\n');
+
+    const html = `<pre><code class="language-javascript">${codeLines}</code></pre>`;
+
+    const ast = await getAstFromHtml(html, {
+      paddingFrameMaxSize: 5,
+    });
+    const preElement = findPreElement(ast);
+    expect(preElement).toBeTruthy();
+    const precomputeData = JSON.parse(preElement.properties.dataPrecompute);
+    const frames = getFrameElements(precomputeData.Default.source);
+
+    expect(frames).toHaveLength(5);
+    expect(frames[1].properties?.dataFrameType).toBe('padding-top');
+    expect(frames[2].properties?.dataFrameType).toBe('highlighted');
+    expect(frames[3].properties?.dataFrameType).toBe('padding-bottom');
+    expect(countFrameLines(frames[1])).toBe(5);
+    expect(countFrameLines(frames[2])).toBe(1);
+    expect(countFrameLines(frames[3])).toBe(5);
+  });
+
+  it('should allow overriding the default focus cap via plugin options', async () => {
+    mockLoadCodeVariantWithEnhancers();
+
+    const codeLines = Array.from(
+      { length: 70 },
+      (_, index) => `const line${index + 1} = ${index + 1};`,
+    ).join('\n');
+
+    const html = `<pre><code class="language-javascript">// @highlight-start
+  ${codeLines}
+  // @highlight-end</code></pre>`;
+
+    const ast = await getAstFromHtml(html, {
+      focusFramesMaxSize: 20,
+    });
+    const preElement = findPreElement(ast);
+    expect(preElement).toBeTruthy();
+    const precomputeData = JSON.parse(preElement.properties.dataPrecompute);
+    const frames = getFrameElements(precomputeData.Default.source);
+
+    expect(frames).toHaveLength(2);
+    expect(frames[0].properties?.dataFrameType).toBe('highlighted');
+    expect(frames[0].properties?.dataFrameTruncated).toBe('visible');
+    expect(frames[1].properties?.dataFrameType).toBe('highlighted-unfocused');
+    expect(frames[1].properties?.dataFrameTruncated).toBe('hidden');
+    expect(countFrameLines(frames[0])).toBe(20);
+    expect(countFrameLines(frames[1])).toBe(50);
+  });
+
   it('should strip trailing semicolons from solo JSX expression lines in tsx', async () => {
     const html =
       '<dl><dt><code>index.tsx</code></dt><dd><pre><code class="language-tsx">&lt;Component /&gt;;</code></pre></dd></dl>';
diff --git a/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts b/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts
index cfadfc339..a083d2b40 100644
--- a/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts
+++ b/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts
@@ -7,12 +7,32 @@ import { createParseSource } from '../parseSource';
 import { TypescriptToJavascriptTransformer } from '../transformTypescriptToJavascript';
 import { IGNORE_COMMENT_PREFIXES, parseImportsAndComments } from '../loaderUtils';
 import {
-  enhanceCodeEmphasis,
+  createEnhanceCodeEmphasis,
   EMPHASIS_COMMENT_PREFIX,
   FOCUS_COMMENT_PREFIX,
 } from '../enhanceCodeEmphasis/enhanceCodeEmphasis';
 import type { Code, SourceEnhancers } from '../../CodeHighlighter/types';
 
+const DEFAULT_PADDING_FRAME_MAX_SIZE = 25;
+const DEFAULT_FOCUS_FRAMES_MAX_SIZE = 60;
+
+export interface TransformHtmlCodeBlockOptions {
+  /**
+   * Maximum number of context lines to keep visible above and below focused regions.
+   * These values act as site-wide defaults for authored inline code blocks.
+   * Per-block `@padding` directives still take precedence.
+   * @default 25
+   */
+  paddingFrameMaxSize?: number;
+  /**
+   * Maximum number of visible lines to keep in a focused region before collapsing the rest.
+   * These values act as site-wide defaults for authored inline code blocks.
+   * Per-block `@min` directives still take precedence.
+   * @default 60
+   */
+  focusFramesMaxSize?: number;
+}
+
 /**
  * Reserved data properties that are handled internally and should not be passed to userProps.
  * These are either processed by the transform pipeline or have special meaning.
@@ -244,14 +264,19 @@ function extractFromDl(
  * 5. Stores the combined precompute data on the root element
  * 6. Clears all code element contents and replaces with error message
  */
-export const transformHtmlCodeBlock: Plugin = () => {
+export const transformHtmlCodeBlock: Plugin<[TransformHtmlCodeBlockOptions?]> = (options = {}) => {
   return async (tree) => {
     const transformPromises: Promise<void>[] = [];
 
     // Get the source parser, transformers, and enhancers
     const sourceParser = createParseSource();
     const sourceTransformers = [TypescriptToJavascriptTransformer];
-    const sourceEnhancers: SourceEnhancers = [enhanceCodeEmphasis];
+    const sourceEnhancers: SourceEnhancers = [
+      createEnhanceCodeEmphasis({
+        paddingFrameMaxSize: options.paddingFrameMaxSize ?? DEFAULT_PADDING_FRAME_MAX_SIZE,
+        focusFramesMaxSize: options.focusFramesMaxSize ?? DEFAULT_FOCUS_FRAMES_MAX_SIZE,
+      }),
+    ];
 
     visit(tree, 'element', (node: Element) => {
       let extractedElements: Array<{
diff --git a/packages/docs-infra/src/withDocsInfra/withDocsInfra.test.ts b/packages/docs-infra/src/withDocsInfra/withDocsInfra.test.ts
index 3b4dd60bc..0ecf93d83 100644
--- a/packages/docs-infra/src/withDocsInfra/withDocsInfra.test.ts
+++ b/packages/docs-infra/src/withDocsInfra/withDocsInfra.test.ts
@@ -834,6 +834,104 @@ describe('withDocsInfra', () => {
     });
   });
 
+  describe('emphasis options', () => {
+    it('should pass demoEmphasisOptions to demo code highlighter loaders', () => {
+      const demoEmphasisOptions = {
+        paddingFrameMaxSize: 2,
+        focusFramesMaxSize: 18,
+      };
+
+      const plugin = withDocsInfra({ demoEmphasisOptions });
+      const result = plugin({});
+
+      expect(result.turbopack?.rules?.['./app/**/demos/*/index.ts']).toEqual({
+        loaders: [
+          {
+            loader: '@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter',
+            options: {
+              performance: {},
+              output: 'hastCompressed',
+              emphasisOptions: demoEmphasisOptions,
+            },
+          },
+        ],
+      });
+    });
+
+    it('should pass codeBlockEmphasisOptions to turbopack types loader options', () => {
+      const codeBlockEmphasisOptions = {
+        paddingFrameMaxSize: 8,
+        focusFramesMaxSize: 36,
+      };
+
+      const plugin = withDocsInfra({ codeBlockEmphasisOptions });
+      const result = plugin({});
+
+      expect(result.turbopack?.rules?.['./app/**/types.ts']).toEqual({
+        loaders: [
+          {
+            loader: '@mui/internal-docs-infra/pipeline/loadPrecomputedTypes',
+            options: {
+              performance: {},
+              socketDir: '.next/docs-infra',
+              updateParentIndex: defaultUpdateParentIndex,
+              codeBlockEmphasisOptions,
+            },
+          },
+        ],
+      });
+    });
+
+    it('should pass codeBlockEmphasisOptions to webpack types loader options', () => {
+      const codeBlockEmphasisOptions = {
+        paddingFrameMaxSize: 8,
+        focusFramesMaxSize: 36,
+      };
+
+      const plugin = withDocsInfra({ codeBlockEmphasisOptions });
+      const result = plugin({});
+
+      const mockWebpackConfig: WebpackConfig = {
+        module: {
+          rules: [],
+        },
+      };
+
+      const mockWebpackOptions = {
+        buildId: 'test-build',
+        dev: false,
+        isServer: false,
+        config: {},
+        defaultLoaders: {
+          babel: {
+            test: /\.(js|jsx|ts|tsx)$/,
+            use: 'babel-loader',
+          },
+        },
+        dir: '/tmp',
+        totalPages: 10,
+      } as unknown as WebpackConfigContext;
+
+      const webpackResult = result.webpack!(mockWebpackConfig, mockWebpackOptions);
+
+      expect(webpackResult.module?.rules).toContainEqual({
+        test: new RegExp('[/\\\\]app[/\\\\].*[/\\\\]types\\.ts$'),
+        use: [
+          mockWebpackOptions.defaultLoaders.babel,
+          {
+            loader: '@mui/internal-docs-infra/pipeline/loadPrecomputedTypes',
+            options: {
+              performance: {},
+              socketDir: '.next/docs-infra',
+              updateParentIndex: defaultUpdateParentIndex,
+              codeBlockEmphasisOptions,
+            },
+          },
+        ],
+      });
+    });
+  });
+
   describe('ordering options', () => {
     it('should not include ordering in loader options when not provided', () => {
       const plugin = withDocsInfra();
@@ -990,6 +1088,24 @@ describe('getDocsInfraMdxOptions', () => {
     ]);
   });
 
+  it('should pass codeBlockEmphasisOptions to transformHtmlCodeBlock', () => {
+    const codeBlockEmphasisOptions = {
+      paddingFrameMaxSize: 8,
+      focusFramesMaxSize: 36,
+    };
+
+    const result = getDocsInfraMdxOptions({
+      codeBlockEmphasisOptions,
+      errorIfIndexOutOfDate: false,
+    });
+
+    expect(result.rehypePlugins).toEqual([
+      ['@mui/internal-docs-infra/pipeline/transformHtmlCodeBlock', codeBlockEmphasisOptions],
+      ['@mui/internal-docs-infra/pipeline/transformHtmlCodeInline'],
+      ['@mui/internal-docs-infra/pipeline/enhanceCodeInline'],
+    ]);
+  });
+
   it('should override defaults when explicit plugins provided', () => {
     const customRemarkPlugins: Array<string | [string, ...any[]]> = [
       ['remark-gfm'],
diff --git a/packages/docs-infra/src/withDocsInfra/withDocsInfra.ts b/packages/docs-infra/src/withDocsInfra/withDocsInfra.ts
index abf26008d..56d854e26 100644
--- a/packages/docs-infra/src/withDocsInfra/withDocsInfra.ts
+++ b/packages/docs-infra/src/withDocsInfra/withDocsInfra.ts
@@ -3,6 +3,7 @@ import type { Configuration as WebpackConfig, RuleSetRule } from 'webpack';
 import type { OrderingConfig } from '../pipeline/loadServerTypesText/order';
 import type { DescriptionReplacement } from '../pipeline/loadServerTypesMeta/format';
 import type { EnhanceCodeEmphasisOptions } from '../pipeline/parseSource/calculateFrameRanges';
+import type { TransformHtmlCodeBlockOptions } from '../pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock';
 
 // Local type definition matching Next.js's internal JSONValue
 // Used for Turbopack loader options which require serializable values
@@ -86,10 +87,15 @@ export interface WithDocsInfraOptions {
    */
   notableCommentsPrefix?: string[];
   /**
-   * Options for the code emphasis enhancer (padding frames, focus frames, etc.).
+   * Options for the code emphasis enhancer used by demo loaders.
    * Passed to `createEnhanceCodeEmphasis` in the precomputed code highlighter loader.
    */
-  emphasisOptions?: EnhanceCodeEmphasisOptions;
+  demoEmphasisOptions?: EnhanceCodeEmphasisOptions;
+  /**
+   * Options for code blocks rendered inside generated type metadata.
+   * Passed to `transformHtmlCodeBlock` through the types loader pipeline.
+   */
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
   /**
    * Name of the index file to update when syncing types metadata to parent indexes.
    * The types loader will call syncPageIndex to update the parent directory's index
@@ -177,6 +183,11 @@ export interface DocsInfraMdxOptions {
    * @default 'tsx'
    */
   defaultInlineCodeLanguage?: string | false;
+  /**
+   * Options for authored MDX code blocks processed by `transformHtmlCodeBlock`.
+   * Passed to `transformHtmlCodeBlock` in the default rehype plugin list.
+   */
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
 }
 
 /**
@@ -190,6 +201,7 @@ export function getDocsInfraMdxOptions(
     baseDir,
     errorIfIndexOutOfDate = Boolean(process.env.CI),
     defaultInlineCodeLanguage,
+    codeBlockEmphasisOptions,
   } = customOptions;
 
   // Normalize extractToIndex to options object
@@ -236,7 +248,9 @@ export function getDocsInfraMdxOptions(
   ];
 
   const defaultRehypePlugins: Array<string | [string, ...any[]]> = [
-    ['@mui/internal-docs-infra/pipeline/transformHtmlCodeBlock'],
+    codeBlockEmphasisOptions
+      ? ['@mui/internal-docs-infra/pipeline/transformHtmlCodeBlock', codeBlockEmphasisOptions]
+      : ['@mui/internal-docs-infra/pipeline/transformHtmlCodeBlock'],
     ['@mui/internal-docs-infra/pipeline/transformHtmlCodeInline'],
     // enhancers
     ['@mui/internal-docs-infra/pipeline/enhanceCodeInline'],
@@ -283,6 +297,8 @@ export function withDocsInfra(options: WithDocsInfraOptions = {}) {
   // Only include ordering in loader options if explicitly provided
   const ordering = options.ordering;
   const descriptionReplacements = options.descriptionReplacements;
+  const demoEmphasisOptions = options.demoEmphasisOptions;
+  const codeBlockEmphasisOptions = options.codeBlockEmphasisOptions;
 
   // Compute updateParentIndex options similar to how transformMarkdownMetadata does
   const updateParentIndex = {
@@ -311,8 +327,8 @@ export function withDocsInfra(options: WithDocsInfraOptions = {}) {
       output,
       ...(removeCommentsWithPrefix && { removeCommentsWithPrefix }),
       ...(notableCommentsPrefix && { notableCommentsPrefix }),
-      ...(options.emphasisOptions && {
-        emphasisOptions: options.emphasisOptions as unknown as JSONValue,
+      ...(demoEmphasisOptions && {
+        emphasisOptions: demoEmphasisOptions as unknown as JSONValue,
       }),
     };
 
@@ -341,6 +357,9 @@ export function withDocsInfra(options: WithDocsInfraOptions = {}) {
               performance,
               socketDir: '.next/docs-infra',
               updateParentIndex,
+              ...(codeBlockEmphasisOptions
+                ? { codeBlockEmphasisOptions: codeBlockEmphasisOptions as unknown as JSONValue }
+                : {}),
               ...(ordering ? { ordering: ordering as unknown as JSONValue } : {}),
               ...(descriptionReplacements
                 ? { descriptionReplacements: descriptionReplacements as unknown as JSONValue }
@@ -463,6 +482,7 @@ export function withDocsInfra(options: WithDocsInfraOptions = {}) {
                 performance,
                 socketDir: '.next/docs-infra',
                 updateParentIndex,
+                ...(codeBlockEmphasisOptions ? { codeBlockEmphasisOptions } : {}),
                 ...(ordering ? { ordering } : {}),
                 ...(descriptionReplacements ? { descriptionReplacements } : {}),
               },

From 0b84ea1db82c2e79f7808d85577f9e1422b86941 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 21 Apr 2026 10:17:36 -0400
Subject: [PATCH 40/44] Update page index and types.md

---
 docs/app/docs-infra/pipeline/load-precomputed-types/types.md | 2 ++
 docs/app/docs-infra/pipeline/load-server-types/types.md      | 2 ++
 docs/app/docs-infra/pipeline/page.mdx                        | 1 +
 3 files changed, 5 insertions(+)

diff --git a/docs/app/docs-infra/pipeline/load-precomputed-types/types.md b/docs/app/docs-infra/pipeline/load-precomputed-types/types.md
index 1e68cb885..eb64139da 100644
--- a/docs/app/docs-infra/pipeline/load-precomputed-types/types.md
+++ b/docs/app/docs-infra/pipeline/load-precomputed-types/types.md
@@ -70,5 +70,7 @@ type LoaderOptions = {
    * Each entry has a `pattern` (regex string) and `replacement` string.
    */
   descriptionReplacements?: DescriptionReplacement[];
+  /** Options for code blocks highlighted inside generated type metadata */
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
 };
 ```
diff --git a/docs/app/docs-infra/pipeline/load-server-types/types.md b/docs/app/docs-infra/pipeline/load-server-types/types.md
index 303da45dd..e32b7b830 100644
--- a/docs/app/docs-infra/pipeline/load-server-types/types.md
+++ b/docs/app/docs-infra/pipeline/load-server-types/types.md
@@ -331,6 +331,8 @@ type LoadServerTypesOptions = {
    * @default 'hast'
    */
   output?: TypesOutputFormat;
+  /** Options for code blocks highlighted inside generated type metadata */
+  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
   /** Absolute path to the types.md file to generate */
   typesMarkdownPath: string;
   /** Root context directory (workspace root) */
diff --git a/docs/app/docs-infra/pipeline/page.mdx b/docs/app/docs-infra/pipeline/page.mdx
index ea5247fa5..7abd994b2 100644
--- a/docs/app/docs-infra/pipeline/page.mdx
+++ b/docs/app/docs-infra/pipeline/page.mdx
@@ -1107,6 +1107,7 @@ A rehype plugin that transforms `<pre>` elements containing `<code>` blocks into
   - Overview
   - Key Features
   - Installation & Usage
+  - Optional Configuration
     - With Next.js and MDX
   - Input Examples
     - Single Code Block

From 79f786a1731bc381969c81694cccf3c05ededbd6 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Tue, 21 Apr 2026 19:57:36 -0400
Subject: [PATCH 41/44] Fix type export

---
 .../pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts b/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts
index a083d2b40..de5394e6a 100644
--- a/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts
+++ b/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts
@@ -16,7 +16,7 @@ import type { Code, SourceEnhancers } from '../../CodeHighlighter/types';
 const DEFAULT_PADDING_FRAME_MAX_SIZE = 25;
 const DEFAULT_FOCUS_FRAMES_MAX_SIZE = 60;
 
-export interface TransformHtmlCodeBlockOptions {
+export type TransformHtmlCodeBlockOptions = {
   /**
    * Maximum number of context lines to keep visible above and below focused regions.
    * These values act as site-wide defaults for authored inline code blocks.
@@ -31,7 +31,7 @@ export interface TransformHtmlCodeBlockOptions {
    * @default 60
    */
   focusFramesMaxSize?: number;
-}
+};
 
 /**
  * Reserved data properties that are handled internally and should not be passed to userProps.

From 4e7fd55fa4d9fdc5bf83c058bc1151d28a453817 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 17:59:27 -0400
Subject: [PATCH 42/44] 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 c0f267a26..4399acea1 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.10.0",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",

From 07fc497f0e4fbc9e0d5a5c68911c00b31b7770b3 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Wed, 22 Apr 2026 18:33:16 -0400
Subject: [PATCH 43/44] Code Review

Co-authored-by: Copilot <copilot@github.com>
---
 .../pipeline/enhance-code-emphasis/types.md   | 17 ++++++------
 .../lint-javascript-demo-focus/page.mdx       |  2 +-
 .../lint-javascript-demo-focus/types.md       |  2 +-
 .../lintJavascriptDemoFocus.test.ts           | 27 ++++++++++++++++---
 .../lintJavascriptDemoFocus.ts                | 17 +++++++-----
 .../extractNameAndSlugFromUrl.test.ts         | 14 ++++++++++
 .../loaderUtils/extractNameAndSlugFromUrl.ts  | 23 +++++++++++++++-
 .../parseSource/calculateFrameRanges.ts       |  3 +--
 8 files changed, 81 insertions(+), 24 deletions(-)

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 03a8c0e27..4a2b03392 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
@@ -106,15 +106,14 @@ type EnhanceCodeEmphasisOptions = {
    */
   paddingFrameMaxSize?: number;
   /**
- * Maximum total number of lines in the focus area (padding-top + focused region + padding-bottom).
- * Defaults to `12` when not explicitly configured.
- * @default 12
-When the region fits within this limit, padding sizes are reduced so the total focus area
-fits. The remainder after subtracting the region size is split: floor(remainder/2) for
-padding-top and ceil(remainder/2) for 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.
- */
+   * Maximum total number of lines in the focus area (padding-top + focused region + padding-bottom).
+   * When the region fits within this limit, padding sizes are reduced so the total focus area
+   * fits. The remainder after subtracting the region size is split: floor(remainder/2) for
+   * padding-top and ceil(remainder/2) for 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.
+   * @default 12
+   */
   focusFramesMaxSize?: number;
   /**
    * When `true`, throws an error if a `@highlight-text` match has to be
diff --git a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
index f4258188b..62497153b 100644
--- a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
+++ b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
@@ -13,7 +13,7 @@ Demo files in `docs/app/**/demos/**` need `@focus` comments so the docs infrastr
 - **Single vs multi-line**: Uses `@focus` for single-line previews and `@focus-start` / `@focus-end` for multi-line
 - **Named export detection**: Supports both `export default` and named exports (filename match or single-export fallback)
 - **Function body highlighting**: Wraps the entire body when hooks or setup statements are present
-- **Skip when present**: Files that already contain `@highlight` or `@focus` anywhere are left untouched
+- **Skip when present**: Files that already contain `@focus` or `@highlight` anywhere are left untouched (a `@highlight` implicitly declares a focus region). `@highlight-text` does not count, since it only marks inline text within a line.
 
 ## Installation & Usage
 
diff --git a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md
index c5531f697..6a88a206f 100644
--- a/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md
+++ b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md
@@ -1,4 +1,4 @@
-# Lint Javascript Demo Focus
+# Lint JavaScript Demo Focus
 
 [//]: types.ts '<-- Autogenerated By (do not edit the following markdown directly), run: pnpm docs:validate docs-infra/pipeline/lint-javascript-demo-focus'
 
diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
index 976226156..654a91c3b 100644
--- a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
@@ -87,6 +87,26 @@ export default function Demo() {
 }
           `,
         },
+        // File already has standalone @highlight in a comment — skip
+        // (a @highlight implicitly declares a focus region)
+        {
+          code: `
+// @highlight
+export default function Demo() {
+  return <div>Hello</div>;
+}
+          `,
+        },
+        // File already has @highlight-start/@highlight-end — skip
+        {
+          code: `
+// @highlight-start
+export default function Demo() {
+  return <div>Hello</div>;
+}
+// @highlight-end
+          `,
+        },
       ],
       invalid: [
         // @focused in a comment should NOT cause skip (not a valid directive)
@@ -136,13 +156,14 @@ export default function Demo() {
 }`,
           errors: [{ messageId: 'missingDemoFocusJsSingle' }],
         },
-        // @highlight comment alone should NOT cause skip — @focus is still needed
+        // @highlight-text comment alone should NOT cause skip — it only marks
+        // inline text within a line and does not define a focus region on its own.
         {
-          code: `// @highlight
+          code: `// @highlight-text "Click"
 export default function Demo() {
   return <Button>Click</Button>;
 }`,
-          output: `// @highlight
+          output: `// @highlight-text "Click"
 export default function Demo() {
   // @focus
   return <Button>Click</Button>;
diff --git a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
index 9741d5529..3b4392521 100644
--- a/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
@@ -195,15 +195,18 @@ export const lintJavascriptDemoFocus = {
 
     const options = (context.options[0] ?? {}) as { wrapReturn?: boolean };
 
-    // Skip files that already have @focus directives in comments — those files
-    // already control which region the viewer scrolls to.  Files with only
-    // @highlight are *not* skipped so the rule can still add @focus for the
-    // preview area.
+    // Skip files that already have @focus or @highlight directives in comments —
+    // those files already declare a focus region (a @highlight implicitly defines
+    // one), so the auto-fixer should not add additional markers.
+    // @highlight-text is excluded because it only marks inline text within a line
+    // and does not on its own define a focus region.
     // We check actual parsed comments (not raw source text) to avoid false
     // negatives from tokens appearing in string literals or identifiers.
-    // The regex matches @focus, @focus-start, and @focus-end as standalone
-    // tokens (not as substrings of other words or prose).
-    const focusDirectivePattern = /(?:^|\s)@focus(?:-(?:start|end))?(?:\s|$)/;
+    // The regex matches @focus, @focus-start, @focus-end, @highlight,
+    // @highlight-start, and @highlight-end as standalone tokens (not as
+    // substrings of other words or prose).
+    const focusDirectivePattern =
+      /(?:^|\s)@(?:focus(?:-(?:start|end))?|highlight(?:-(?:start|end))?)(?:\s|$)/;
     const hasFocusComment = sourceCode.getAllComments().some((comment) => {
       return focusDirectivePattern.test(comment.value);
     });
diff --git a/packages/docs-infra/src/pipeline/loaderUtils/extractNameAndSlugFromUrl.test.ts b/packages/docs-infra/src/pipeline/loaderUtils/extractNameAndSlugFromUrl.test.ts
index 177637c72..5254e47bf 100644
--- a/packages/docs-infra/src/pipeline/loaderUtils/extractNameAndSlugFromUrl.test.ts
+++ b/packages/docs-infra/src/pipeline/loaderUtils/extractNameAndSlugFromUrl.test.ts
@@ -144,6 +144,20 @@ describe('extractNameAndSlugFromUrl', () => {
     });
   });
 
+  describe('with brand-name overrides', () => {
+    it('should preserve canonical capitalization for known brand names', () => {
+      expect(extractNameAndSlugFromUrl('/docs/lint-javascript-demo-focus/index.ts')).toEqual({
+        name: 'Lint JavaScript Demo Focus',
+        slug: 'lint-javascript-demo-focus',
+      });
+
+      expect(extractNameAndSlugFromUrl('/docs/typescript-helpers/index.ts')).toEqual({
+        name: 'TypeScript Helpers',
+        slug: 'typescript-helpers',
+      });
+    });
+  });
+
   describe('with different URL formats', () => {
     it('should handle file:// URLs', () => {
       const url = 'file:///C:/Users/dev/project/src/multi-step-form/index.ts';
diff --git a/packages/docs-infra/src/pipeline/loaderUtils/extractNameAndSlugFromUrl.ts b/packages/docs-infra/src/pipeline/loaderUtils/extractNameAndSlugFromUrl.ts
index 58eac8c57..36272867f 100644
--- a/packages/docs-infra/src/pipeline/loaderUtils/extractNameAndSlugFromUrl.ts
+++ b/packages/docs-infra/src/pipeline/loaderUtils/extractNameAndSlugFromUrl.ts
@@ -47,6 +47,27 @@ function camelToTitleCase(camelCase: string): string {
   );
 }
 
+/**
+ * Known brand names and acronyms that have a canonical capitalization.
+ * Keys are lowercase, values are the canonical form to use in titles.
+ */
+const BRAND_NAME_OVERRIDES: Record<string, string> = {
+  javascript: 'JavaScript',
+  typescript: 'TypeScript',
+};
+
+/**
+ * Capitalizes a single word, applying brand-name overrides when applicable.
+ */
+function capitalizeWord(word: string): string {
+  const lower = word.toLowerCase();
+  const override = BRAND_NAME_OVERRIDES[lower];
+  if (override) {
+    return override;
+  }
+  return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+}
+
 /**
  * Converts a kebab-case string to Title Case
  * @param kebabCase - The kebab-case string to convert
@@ -55,7 +76,7 @@ function camelToTitleCase(camelCase: string): string {
 function kebabToTitleCase(kebabCase: string): string {
   return kebabCase
     .split(/[-_]/) // Split on both hyphens and underscores
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .map(capitalizeWord)
     .join(' ');
 }
 
diff --git a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
index bc4979c1b..1f080d8ae 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
@@ -90,13 +90,12 @@ export interface EnhanceCodeEmphasisOptions {
   paddingFrameMaxSize?: number;
   /**
    * Maximum total number of lines in the focus area (padding-top + focused region + padding-bottom).
-   * Defaults to `12` when not explicitly configured.
-   * @default 12
    * When the region fits within this limit, padding sizes are reduced so the total focus area
    * fits. The remainder after subtracting the region size is split: floor(remainder/2) for
    * padding-top and ceil(remainder/2) for 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.
+   * @default 12
    */
   focusFramesMaxSize?: number;
   /**

From 2a0ecc4a508d31a9d1e9bb36f76e79e062b20cb4 Mon Sep 17 00:00:00 2001
From: dav-is <mail@connordav.is>
Date: Thu, 23 Apr 2026 19:38:57 -0400
Subject: [PATCH 44/44] Hide visibility when collapsed

Co-authored-by: Copilot <copilot@github.com>
---
 .../demos/CollapsibleContent.module.css       | 20 ++++++++++++++-----
 .../demos/CollapsibleDemoContent.module.css   | 20 ++++++++++++++-----
 .../demos/IndentContent.module.css            | 20 ++++++++++++++-----
 3 files changed, 45 insertions(+), 15 deletions(-)

diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
index 15035a4f8..dce1cc600 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css
@@ -247,7 +247,11 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] :global(code) {
 
 /* ---- Collapsible frame behavior ---- */
 
-/* Normal frames and unfocused highlighted/focus frames are hidden by default (collapsed) */
+/* Normal frames and unfocused highlighted/focus frames are hidden by default (collapsed).
+   `visibility: hidden` removes the frames from the a11y tree, focus order, and
+   prevents `contenteditable` caret placement while collapsed. `visibility` has
+   built-in transition semantics that keep the element visible during the
+   collapse animation and only flip to hidden at the end. */
 .codeBlock :global(.frame:not([data-frame-type])),
 .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
 .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
@@ -255,9 +259,11 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] :global(code) {
   overflow: hidden;
   overflow-anchor: none;
   opacity: 0;
+  visibility: hidden;
   transition:
     max-height 0.3s cubic-bezier(0.5, 0, 0, 1),
-    opacity 0.2s ease 0.1s;
+    opacity 0.2s ease 0.1s,
+    visibility 0.3s;
 }
 
 @supports (interpolate-size: allow-keywords) {
@@ -270,7 +276,8 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] :global(code) {
     overflow: clip;
     transition:
       height 0.3s ease,
-      opacity 0.3s ease;
+      opacity 0.3s ease,
+      visibility 0.3s;
   }
 }
 
@@ -298,9 +305,11 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] :global(code) {
   :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 2220px;
   opacity: 1;
+  visibility: visible;
   transition:
     max-height 1.5s cubic-bezier(0.25, 0.46, 0.45, 0.94),
-    opacity 0.15s ease;
+    opacity 0.15s ease,
+    visibility 0s;
 }
 
 @supports (interpolate-size: allow-keywords) {
@@ -318,7 +327,8 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] :global(code) {
     overflow: clip;
     transition:
       height 0.3s ease,
-      opacity 0.3s ease;
+      opacity 0.3s ease,
+      visibility 0s;
   }
 }
 
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
index ce0b6c2c4..b80cac07d 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
@@ -312,7 +312,11 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] :global(code) {
 
 /* ---- Collapsible frame behavior ---- */
 
-/* Normal frames and unfocused highlighted/focus frames are hidden by default (collapsed) */
+/* Normal frames and unfocused highlighted/focus frames are hidden by default (collapsed).
+   `visibility: hidden` removes the frames from the a11y tree, focus order, and
+   prevents `contenteditable` caret placement while collapsed. `visibility` has
+   built-in transition semantics that keep the element visible during the
+   collapse animation and only flip to hidden at the end. */
 .codeBlock :global(.frame:not([data-frame-type])),
 .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
 .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
@@ -320,9 +324,11 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] :global(code) {
   overflow: hidden;
   overflow-anchor: none;
   opacity: 0;
+  visibility: hidden;
   transition:
     max-height 0.3s cubic-bezier(0.5, 0, 0, 1),
-    opacity 0.2s ease 0.1s;
+    opacity 0.2s ease 0.1s,
+    visibility 0.3s;
 }
 
 @supports (interpolate-size: allow-keywords) {
@@ -335,7 +341,8 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] :global(code) {
     overflow: clip;
     transition:
       height 0.3s ease,
-      opacity 0.3s ease;
+      opacity 0.3s ease,
+      visibility 0.3s;
   }
 }
 
@@ -363,9 +370,11 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] :global(code) {
   :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 2220px;
   opacity: 1;
+  visibility: visible;
   transition:
     max-height 1.5s cubic-bezier(0.25, 0.46, 0.45, 0.94),
-    opacity 0.15s ease;
+    opacity 0.15s ease,
+    visibility 0s;
 }
 
 @supports (interpolate-size: allow-keywords) {
@@ -383,7 +392,8 @@ pre.codeBlock[data-scrollbar-gutter='expand-to'] :global(code) {
     overflow: clip;
     transition:
       height 0.3s ease,
-      opacity 0.3s ease;
+      opacity 0.3s ease,
+      visibility 0s;
   }
 }
 
diff --git a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
index a97d82050..9995c7e52 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css
@@ -166,7 +166,11 @@ pre.codeBlock:has(:global(.frame[data-frame-truncated='visible']))::after {
 
 /* ---- Collapsible frame behavior (no padding, just highlighted vs normal) ---- */
 
-/* Normal frames and unfocused highlighted/focus frames are hidden by default */
+/* Normal frames and unfocused highlighted/focus frames are hidden by default.
+   `visibility: hidden` removes the frames from the a11y tree, focus order, and
+   prevents `contenteditable` caret placement while collapsed. `visibility` has
+   built-in transition semantics that keep the element visible during the
+   collapse animation and only flip to hidden at the end. */
 .codeBlock :global(.frame:not([data-frame-type])),
 .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
 .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
@@ -174,9 +178,11 @@ pre.codeBlock:has(:global(.frame[data-frame-truncated='visible']))::after {
   overflow: hidden;
   overflow-anchor: none;
   opacity: 0;
+  visibility: hidden;
   transition:
     max-height 0.3s cubic-bezier(0.5, 0, 0, 1),
-    opacity 0.2s ease 0.1s;
+    opacity 0.2s ease 0.1s,
+    visibility 0.3s;
 }
 
 @supports (interpolate-size: allow-keywords) {
@@ -189,7 +195,8 @@ pre.codeBlock:has(:global(.frame[data-frame-truncated='visible']))::after {
     overflow: clip;
     transition:
       height 0.3s ease,
-      opacity 0.3s ease;
+      opacity 0.3s ease,
+      visibility 0.3s;
   }
 }
 
@@ -204,9 +211,11 @@ pre.codeBlock:has(:global(.frame[data-frame-truncated='visible']))::after {
 .expanded .codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 2220px;
   opacity: 1;
+  visibility: visible;
   transition:
     max-height 1.5s cubic-bezier(0.25, 0.46, 0.45, 0.94),
-    opacity 0.15s ease;
+    opacity 0.15s ease,
+    visibility 0s;
 }
 
 @supports (interpolate-size: allow-keywords) {
@@ -218,7 +227,8 @@ pre.codeBlock:has(:global(.frame[data-frame-truncated='visible']))::after {
     overflow: clip;
     transition:
       height 0.3s ease,
-      opacity 0.3s ease;
+      opacity 0.3s ease,
+      visibility 0s;
   }
 }