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 b6af1cfe3..b22272da9 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 '../../../../../docs-infra/components/code-highlighter/demos/syntax.css';
 
 export function CodeContent(props: ContentProps<{}>) {
+  // @focus-start @padding 1
   const code = useCode(props, { preClassName: styles.codeBlock });
 
   return <div className={styles.code}>{code.selectedFile}</div>;
+  // @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 1008f6ad1..3c62f1d2a 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 '../../../../../docs-infra/components/code-highlighter/demos/syntax.css';
 export function CodeContentLoading(props: ContentLoadingProps<{}>) {
   return (
     <div>
+      {/* @focus-start */}
       <div className={styles.code}>
         <pre className={styles.codeBlock}>{props.source}</pre>
       </div>
+      {/* @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 f61f0f8fc..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,6 +11,7 @@ const sourceParser = createParseSource();
 
 export default function Page() {
   return (
+    // @focus-start
     <CodeHighlighter
       Content={CodeContent}
       ContentLoading={CodeContentLoading}
@@ -19,5 +20,6 @@ export default function Page() {
     >
       {code}
     </CodeHighlighter>
+    // @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 bb2436740..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,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 }) {
+  // @focus-start @padding 1
   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>
   );
+  // @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 d3dbee261..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,6 +20,7 @@ function greet(name) {
 
 export function CodeEditor() {
   return (
+    // @focus-start
     <CodeProvider>
       <CodeController>
         <CodeHighlighter
@@ -31,5 +32,6 @@ export function CodeEditor() {
         />
       </CodeController>
     </CodeProvider>
+    // @focus-end
   );
 }
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/code-editor/CodeEditorContent.tsx b/docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.tsx
index d2a6fbf48..634f44db1 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 '../../../code-highlighter/demos/syntax.css';
 
 export function CodeEditorContent(props: ContentProps<object>) {
+  // @focus-start @padding 1
   const preRef = React.useRef<HTMLPreElement | null>(null);
   const code = useCode(props, { preClassName: styles.codeBlock, preRef });
 
@@ -47,4 +48,5 @@ export function CodeEditorContent(props: ContentProps<object>) {
       <div className={styles.code}>{code.selectedFile}</div>
     </div>
   );
+  // @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 b42c1ca94..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,6 +27,7 @@ function Runner({ code }: { code: string }) {
 }
 
 export function DemoController({ children }: { children: React.ReactNode }) {
+  // @focus-start @padding 1
   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>
   );
+  // @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 e634b8568..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,10 +5,12 @@ import { DemoCheckboxBasic } from './demo-basic';
 
 export function DemoLive() {
   return (
+    // @focus-start
     <CodeProvider>
       <DemoController>
         <DemoCheckboxBasic />
       </DemoController>
     </CodeProvider>
+    // @focus-end
   );
 }
diff --git a/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.module.css b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.module.css
index 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-controller-context/demos/demo-live/DemoLiveContent.tsx b/docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.tsx
index 100cbd866..b6a55998f 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>) {
+  // @focus-start @padding 1
   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>
   );
+  // @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 5f008e747..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,8 +4,10 @@ import { Checkbox } from '@/components/Checkbox';
 export default function CheckboxBasic() {
   return (
     <div>
+      {/* @focus-start */}
       <Checkbox defaultChecked />
       <p style={{ color: '#CA244D' }}>Type Whatever You Want Below</p>
+      {/* @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 c0cf80e6a..6b8ebef9b 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 '../../../code-highlighter/demos/syntax.css';
 
 export function MultiFileContent(props: ContentProps<object>) {
+  // @focus-start @padding 1
   const preRef = React.useRef<HTMLPreElement | null>(null);
   const code = useCode(props, { preClassName: styles.codeBlock, preRef });
 
@@ -43,4 +44,5 @@ export function MultiFileContent(props: ContentProps<object>) {
       <div className={styles.code}>{code.selectedFile}</div>
     </div>
   );
+  // @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 8f5affceb..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,6 +43,7 @@ p {
 
 export function MultiFileEditor() {
   return (
+    // @focus-start
     <CodeProvider>
       <CodeController>
         <CodeHighlighter
@@ -54,5 +55,6 @@ export function MultiFileEditor() {
         />
       </CodeController>
     </CodeProvider>
+    // @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 29e0e1a90..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,6 +19,7 @@ export function Code({
   fileName?: string;
 }) {
   return (
+    // @focus-start
     <CodeHighlighter
       language={language}
       fileName={fileName}
@@ -27,5 +28,6 @@ export function Code({
     >
       {children}
     </CodeHighlighter>
+    // @focus-end
   );
 }
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..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
@@ -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,27 +86,55 @@
   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;
+.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(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;
   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 +149,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 +158,21 @@
   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;
+}
+
+/* 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;
+}
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 f15c7008c..559edf1a8 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>) {
+  // @focus-start
   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>
   );
+  // @focus-end
 }
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..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
@@ -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,27 +93,41 @@
   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;
+.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;
   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 +142,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 +151,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.tsx b/docs/app/docs-infra/components/code-highlighter/demos/DemoContent.tsx
index 08d6f08ed..bb74f4cc3 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>) {
+  // @focus-start
   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>
   );
+  // @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 093206112..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
@@ -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 (
+    // @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..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
@@ -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 (
+    // @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..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,6 +10,7 @@ const sourceParser = createParseSource();
 
 export function Code({ children, fileName }: { children: string; fileName?: string }) {
   return (
+    // @focus-start
     <CodeHighlighter
       fileName={fileName}
       Content={CodeContent}
@@ -18,5 +19,6 @@ export function Code({ children, fileName }: { children: string; fileName?: stri
     >
       {children}
     </CodeHighlighter>
+    // @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 a75d04ead..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
@@ -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 (
+    // @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..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,6 +10,7 @@ const sourceParser = createParseSource();
 
 export function Code({ children, fileName }: { children: string; fileName?: string }) {
   return (
+    // @focus-start
     <CodeHighlighter
       fileName={fileName}
       Content={CodeContent}
@@ -18,5 +19,6 @@ export function Code({ children, fileName }: { children: string; fileName?: stri
     >
       {children}
     </CodeHighlighter>
+    // @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 5fc1eefda..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,6 +3,7 @@ import { Code } from './Code';
 
 export function BasicCode() {
   return (
+    // @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..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,6 +10,7 @@ const sourceTransformers = [TypescriptToJavascriptTransformer];
 
 export function Code({ children, fileName }: { children: string; fileName?: string }) {
   return (
+    // @focus-start
     <CodeHighlighter
       fileName={fileName}
       Content={CodeContent}
@@ -18,5 +19,6 @@ export function Code({ children, fileName }: { children: string; fileName?: stri
     >
       {children}
     </CodeHighlighter>
+    // @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 34f410482..e6e9f12a0 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 '../syntax.css';
 
 export function DemoContentLoading(props: ContentLoadingProps<object>) {
+  // @focus-start
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -57,4 +58,5 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
       </div>
     </div>
   );
+  // @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 adc5f88e6..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
@@ -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 (
+    // @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 b01246aa3..42212fdf2 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>) {
+  // @focus-start
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -89,4 +90,5 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
       </div>
     </div>
   );
+  // @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 1df8d8c02..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
@@ -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 (
+    // @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..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
@@ -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 (
+    // @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 301bb14fb..8babec8af 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 '../syntax.css';
 
 export function DemoContentLoading(props: ContentLoadingProps<object>) {
+  // @focus-start
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -51,4 +52,5 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
       </div>
     </div>
   );
+  // @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 adc5f88e6..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
@@ -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 (
+    // @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..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
@@ -2,5 +2,8 @@ import * as React from 'react';
 import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxBasic() {
-  return <Checkbox defaultChecked />;
+  return (
+    // @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..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
@@ -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 (
+    // @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..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
@@ -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 (
+    // @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..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
@@ -2,5 +2,8 @@ import * as React from 'react';
 import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxBasic() {
-  return <Checkbox defaultChecked />;
+  return (
+    // @focus
+    <Checkbox defaultChecked />
+  );
 }
diff --git a/docs/app/docs-infra/components/code-highlighter/types.md b/docs/app/docs-infra/components/code-highlighter/types.md
index 05c3cc2bf..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 } };
+type HastRoot = {
+  data?: RootData & { totalLines?: number; collapsible?: boolean; frameSize?: number };
+};
 ```
 
 ### LoadFallbackCodeOptions
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..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,8 +5,10 @@ import { CodeContent } from '../../code-highlighter/demos/CodeContent';
 
 export function Code({ children, fileName }: { children: string; fileName?: string }) {
   return (
+    // @focus-start
     <CodeHighlighter fileName={fileName} Content={CodeContent}>
       {children}
     </CodeHighlighter>
+    // @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 9f15cdb0e..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,8 +4,10 @@ import { Code } from '../../../code-highlighter/demos/CodeBlock';
 
 export function BasicCode() {
   return (
+    // @focus-start
     <CodeProvider>
       <Code fileName="example.js">{`console.log('Hello, world!');`}</Code>
     </CodeProvider>
+    // @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 456030894..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,6 +90,7 @@ const loadSource: LoadSource = async (url: string) => {
 
 export function CodeProviderGitHub({ children }: { children: React.ReactNode }) {
   return (
+    // @focus-start
     <CodeProvider
       loadCodeMeta={loadCodeMeta}
       loadVariantMeta={loadVariantMeta}
@@ -97,5 +98,6 @@ export function CodeProviderGitHub({ children }: { children: React.ReactNode })
     >
       {children}
     </CodeProvider>
+    // @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 813c0aa53..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,8 +4,10 @@ import { DemoCheckboxBasic } from './demo-basic';
 
 export function Docs() {
   return (
+    // @focus-start
     <CodeProviderGitHub>
       <DemoCheckboxBasic />
     </CodeProviderGitHub>
+    // @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 adcf3533a..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
@@ -2,5 +2,8 @@ import * as React from 'react';
 import { Checkbox } from '@/components/Checkbox';
 
 export function CheckboxBasic() {
-  return <Checkbox defaultChecked />;
+  return (
+    // @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..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,6 +4,7 @@ import { useCopier } from '@mui/internal-docs-infra/useCopier';
 import styles from './TextInputCopy.module.css';
 
 export function TextInputCopy() {
+  // @focus-start @padding 1
   const [text, setText] = React.useState('Hello, copy me!');
   const { copy, recentlySuccessful } = useCopier(() => text);
 
@@ -21,4 +22,5 @@ export function TextInputCopy() {
       </button>
     </div>
   );
+  // @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 448c6e43c..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,6 +4,7 @@ import { usePreference } from '@mui/internal-docs-infra/usePreference';
 import styles from './VariantSelector.module.css';
 
 export function VariantSelector() {
+  // @focus-start @padding 1
   const variants = ['contained', 'outlined', 'text'];
   const [variant, setVariant] = usePreference('variant', variants, () => 'contained');
 
@@ -30,4 +31,5 @@ export function VariantSelector() {
       </div>
     </div>
   );
+  // @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 3768c8299..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,6 +19,7 @@ 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
   const { type, additionalTypes } = useTypes(props);
 
@@ -37,6 +38,7 @@ export function TypesTable(props: TypesTableProps) {
       ))}
     </div>
   );
+  // @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 5fba658f6..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,6 +13,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function Component(props: Props) {
+  // @focus-start @padding 1
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
@@ -23,4 +24,5 @@ export function Component(props: Props) {
       {!props.disabled ? props.children : null}
     </button>
   );
+  // @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 4c9842d22..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,6 +22,7 @@ export interface ComponentPartProps {
  * A simple component that displays a title and optional children.
  */
 export function ComponentPart(props: ComponentPartProps) {
+  // @focus-start @padding 1
   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>
   );
+  // @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 6b62cb924..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,6 +38,7 @@ export interface ComponentRootProps {
  * A simple component that displays a title and optional children.
  */
 export function ComponentRoot(props: ComponentRootProps) {
+  // @focus-start @padding 1
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
 
@@ -59,6 +60,7 @@ export function ComponentRoot(props: ComponentRootProps) {
       {!props.disabled ? props.children : null}
     </button>
   );
+  // @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 3aa3e79b9..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,6 +4,7 @@ import { TypesComponent as ComponentTypes, TypesComponentAdditional } from './ty
 export function TypesComponent() {
   return (
     <div>
+      {/* @focus-start */}
       <h3>Component API</h3>
       <h3>Root</h3>
       <ComponentTypes.Root />
@@ -11,6 +12,7 @@ export function TypesComponent() {
       <ComponentTypes.Part />
       <h3>Additional Types</h3>
       <TypesComponentAdditional />
+      {/* @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 049f9c178..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
@@ -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 (
+    // @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..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,6 +22,7 @@ export const DialogClose = React.forwardRef(function DialogClose(
   props: DialogCloseProps,
   ref: React.ForwardedRef<HTMLButtonElement>,
 ) {
+  // @focus-start @padding 1
   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>
   );
+  // @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 a52b109af..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,6 +36,7 @@ export const DialogTrigger = React.forwardRef(function DialogTrigger(
   props: DialogTriggerProps,
   ref: React.ForwardedRef<HTMLButtonElement>,
 ) {
+  // @focus-start @padding 1
   const { className, disabled, children, ...other } = props;
 
   const state: DialogTriggerState = React.useMemo(
@@ -53,6 +54,7 @@ export const DialogTrigger = React.forwardRef(function DialogTrigger(
       {children}
     </button>
   );
+  // @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 fa7299d73..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,11 +4,13 @@ import { TypesAlertDialog as AlertDialogTypes } from './types';
 export function TypesAlertDialog() {
   return (
     <div>
+      {/* @focus-start */}
       <h3>Alert Dialog API</h3>
       <h3>Trigger</h3>
       <AlertDialogTypes.Trigger />
       <h3>Close</h3>
       <AlertDialogTypes.Close />
+      {/* @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 64e9069b6..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,6 +13,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function ComponentPart(props: Props) {
+  // @focus-start @padding 1
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
@@ -23,4 +24,5 @@ export function ComponentPart(props: Props) {
       {!props.disabled ? props.children : null}
     </button>
   );
+  // @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 2c6d2cc0d..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,6 +13,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function ComponentRoot(props: Props) {
+  // @focus-start @padding 1
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
@@ -23,4 +24,5 @@ export function ComponentRoot(props: Props) {
       {!props.disabled ? props.children : null}
     </button>
   );
+  // @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 6793b2638..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,10 +4,12 @@ import { TypesComponent as ComponentTypes } from './types';
 export function TypesComponent() {
   return (
     <div>
+      {/* @focus-start */}
       <h3>ComponentRoot</h3>
       <ComponentTypes.Root />
       <h3>ComponentPart</h3>
       <ComponentTypes.Part />
+      {/* @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 43daa6cbd..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,6 +14,7 @@ interface Props {
  * A simple component that displays a title and optional children.
  */
 export function Component(props: Props) {
+  // @focus-start @padding 1
   const handleClick = (event: React.MouseEvent) => {
     console.warn('Clicked', event);
   };
@@ -24,4 +25,5 @@ export function Component(props: Props) {
       {!props.disabled ? props.children : null}
     </button>
   );
+  // @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 e3e6ef39b..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,6 +14,7 @@ const tabs = [
 ];
 
 export function TabNavigation() {
+  // @focus-start @padding 1
   const [hash, setHash] = useUrlHashState();
   const activeTab = hash || 'overview';
 
@@ -39,4 +40,5 @@ export function TabNavigation() {
       </div>
     </div>
   );
+  // @focus-end
 }
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/CodeIndent.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeIndent.tsx
index 6eed34a39..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,11 +20,13 @@ const sourceEnhancers = [enhanceCodeEmphasis];
  */
 export function CodeIndent({ code }: { code: CodeType }) {
   return (
+    // @focus-start
     <CodeHighlighter
       code={code}
       Content={IndentContent}
       sourceParser={sourceParser}
       sourceEnhancers={sourceEnhancers}
     />
+    // @focus-end
   );
 }
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..c6a1cfa53
--- /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 focused window from the start with unfocused overflow below.
+ */
+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 eec6babd9..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
@@ -5,7 +5,7 @@
 }
 
 .code {
-  padding: 10px 6px;
+  padding: 10px 0 0;
 }
 
 /* Visually hidden but accessible checkbox — provides toggle state without JS */
@@ -22,11 +22,12 @@
 }
 
 .toggle {
-  display: block;
+  display: none;
   width: 100%;
   padding: 6px;
   border: none;
   border-top: 1px solid #d0cdd7;
+  border-radius: 0 0 7px 7px;
   background: #f5f3f8;
   color: #65636d;
   cursor: pointer;
@@ -35,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;
 }
@@ -58,16 +64,105 @@
   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;
+  --code-padding-bottom: 6px;
+  --scrollbar-gutter-size: 15px;
+  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;
+}
+
+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;
+}
+
+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;
+}
+
+pre.codeBlock[data-scrollbar-gutter='expand-from'] :global(code) {
+  margin-bottom: 0;
+  transition: none;
+}
+
+pre.codeBlock[data-scrollbar-gutter='expand-to'] {
+  overflow-x: hidden;
+}
+
+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'],
+.container:has(.checkbox:checked) .code pre.codeBlock[data-scrollbar-gutter='expand-to'] {
+  overflow-x: hidden;
+}
+
+.container:has(.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 +175,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,17 +216,74 @@
   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 */
+.codeBlock :global(.frame[data-frame-truncated='visible']) {
+  border-radius: 8px 8px 0 0;
+}
+
+/* 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 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='highlighted-unfocused']),
+.codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 0;
   overflow: hidden;
+  overflow-anchor: none;
   opacity: 0;
+  visibility: hidden;
   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,
+    visibility 0.3s;
+}
+
+@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,
+      visibility 0.3s;
+  }
+}
+
+/* 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 */
@@ -122,14 +294,48 @@
 }
 
 /* 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']) {
-  max-height: 500px;
-  overflow: visible;
+.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;
+  visibility: visible;
+  transition:
+    max-height 1.5s cubic-bezier(0.25, 0.46, 0.45, 0.94),
+    opacity 0.15s ease,
+    visibility 0s;
+}
+
+@supports (interpolate-size: allow-keywords) {
+  .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;
+    transition:
+      height 0.3s ease,
+      opacity 0.3s ease,
+      visibility 0s;
+  }
 }
 
-.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;
 }
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 675eb68d7..463bbbcca 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,23 +4,40 @@ 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 '../../../components/code-highlighter/demos/syntax.css';
 
 export function CollapsibleContent(props: ContentProps<object>) {
+  // @focus-start @padding 1
   const code = useCode(props, { preClassName: styles.codeBlock });
   const id = React.useId();
   const checkboxId = `${id}-expand`;
+  const { containerRef, toggleRef, 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>
-      <label htmlFor={checkboxId} className={styles.toggle}>
+      {/* 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 ref={toggleRef} htmlFor={checkboxId} className={styles.toggle}>
         <span className={styles.expandLabel}>Expand</span>
         <span className={styles.collapseLabel}>Collapse</span>
       </label>
     </div>
   );
+  // @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
new file mode 100644
index 000000000..b80cac07d
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css
@@ -0,0 +1,410 @@
+.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;
+  overflow-anchor: none;
+}
+
+/* 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: none;
+  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;
+}
+
+/* Only show the toggle when the code block has collapsible frames */
+.code:has([data-collapsible]) ~ .toggle {
+  display: block;
+}
+
+.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;
+  --code-padding-bottom: 6px;
+  --scrollbar-gutter-size: 15px;
+  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;
+}
+
+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;
+}
+
+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;
+}
+
+pre.codeBlock[data-scrollbar-gutter='expand-from'] :global(code) {
+  margin-bottom: 0;
+  transition: none;
+}
+
+pre.codeBlock[data-scrollbar-gutter='expand-to'] {
+  overflow-x: hidden;
+}
+
+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'],
+.codeSection:has(.checkbox:checked) .code pre.codeBlock[data-scrollbar-gutter='expand-to'] {
+  overflow-x: hidden;
+}
+
+.codeSection:has(.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(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;
+  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 */
+.codeBlock :global(.frame[data-frame-truncated='visible']) {
+  border-radius: 8px 8px 0 0;
+}
+
+/* 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).
+   `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']) {
+  max-height: 0;
+  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,
+    visibility 0.3s;
+}
+
+@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,
+      visibility 0.3s;
+  }
+}
+
+/* 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']) {
+  opacity: 0.5;
+  transition: opacity 0.3s ease;
+}
+
+/* When checkbox is checked (expanded), show all frames */
+.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;
+  visibility: visible;
+  transition:
+    max-height 1.5s cubic-bezier(0.25, 0.46, 0.45, 0.94),
+    opacity 0.15s ease,
+    visibility 0s;
+}
+
+@supports (interpolate-size: allow-keywords) {
+  .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;
+    transition:
+      height 0.3s ease,
+      opacity 0.3s ease,
+      visibility 0s;
+  }
+}
+
+.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;
+}
+
+.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..f01399117
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx
@@ -0,0 +1,111 @@
+'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 { useScrollAnchor } from './useScrollAnchor';
+
+import '@wooorm/starry-night/style/light';
+
+const variantNames: Record<string, string | undefined> = {
+  CssModules: 'CSS Modules',
+};
+
+export function CollapsibleDemoContent(props: ContentProps<object>) {
+  // @focus-start @padding 1
+  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`;
+  const { containerRef, toggleRef, anchorScroll } = useScrollAnchor();
+  const blurPointerFocus = React.useCallback((event: React.FocusEvent<HTMLInputElement>) => {
+    if (!event.currentTarget.matches(':focus-visible')) {
+      event.currentTarget.blur();
+    }
+  }, []);
+
+  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 ref={containerRef} 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>
+          <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 ref={toggleRef} 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 7d9b0efde..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
@@ -5,15 +5,16 @@
 }
 
 .code {
-  padding: 10px 6px;
+  padding: 10px 0 0;
 }
 
 .toggle {
-  display: block;
+  display: none;
   width: 100%;
   padding: 6px;
   border: none;
   border-top: 1px solid #d0cdd7;
+  border-radius: 0 0 7px 7px;
   background: #f5f3f8;
   color: #65636d;
   cursor: pointer;
@@ -21,20 +22,65 @@
   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;
 }
 
-/* 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;
+}
+
+/* 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;
 }
 
+/* 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 +93,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,66 +134,154 @@
   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 */
+/* When truncated visible (collapsed): only round top */
+.codeBlock :global(.frame[data-frame-truncated='visible']) {
+  border-radius: 8px 8px 0 0;
+}
+
+/* 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 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='highlighted-unfocused']),
+.codeBlock :global(.frame[data-frame-type='focus-unfocused']) {
   max-height: 0;
   overflow: hidden;
+  overflow-anchor: none;
   opacity: 0;
+  visibility: hidden;
   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,
+    visibility 0.3s;
+}
+
+@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,
+      visibility 0.3s;
+  }
+}
+
+/* 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']) {
-  max-height: 500px;
-  overflow: visible;
+.expanded .codeBlock :global(.frame[data-frame-type='highlighted-unfocused']),
+.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,
+    visibility 0s;
+}
+
+@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,
+      visibility 0s;
+  }
 }
 
-/* ---- Indent shifting: move highlighted frame left by its indent level ---- */
+/* ---- 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']) {
-  transition: margin-left 0.3s ease;
+.codeBlock :global(.frame[data-frame-type='highlighted']),
+.codeBlock :global(.frame[data-frame-type='focus']) {
+  transition: transform 0.3s ease;
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='1']) {
-  margin-left: -2ch;
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='1']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='1']) {
+  transform: translateX(-2ch);
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='2']) {
-  margin-left: -4ch;
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='2']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='2']) {
+  transform: translateX(-4ch);
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='3']) {
-  margin-left: -6ch;
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='3']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='3']) {
+  transform: translateX(-6ch);
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='4']) {
-  margin-left: -8ch;
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='4']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='4']) {
+  transform: translateX(-8ch);
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='5']) {
-  margin-left: -10ch;
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='5']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='5']) {
+  transform: translateX(-10ch);
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='6']) {
-  margin-left: -12ch;
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='6']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='6']) {
+  transform: translateX(-12ch);
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='7']) {
-  margin-left: -14ch;
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='7']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='7']) {
+  transform: translateX(-14ch);
 }
 
-.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='8']) {
-  margin-left: -16ch;
+.codeBlock :global(.frame[data-frame-type='highlighted'][data-frame-indent='8']),
+.codeBlock :global(.frame[data-frame-type='focus'][data-frame-indent='8']) {
+  transform: translateX(-16ch);
 }
 
 /* Reset indent shift when expanded */
-.expanded .codeBlock :global(.frame[data-frame-type='highlighted']) {
-  margin-left: 0;
+.expanded .codeBlock :global(.frame[data-frame-type='highlighted']),
+.expanded .codeBlock :global(.frame[data-frame-type='focus']) {
+  transform: translateX(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 c352f96e8..dad52af7a 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,19 +4,30 @@ 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 '../../../components/code-highlighter/demos/syntax.css';
 
 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>
   );
+  // @focus-end
 }
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..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,6 +42,7 @@ export function UserProfile({ id }: { id: string }) {
 }`;
 
 export async function CollapsibleCode() {
+  // @focus-start @padding 1
   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/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..fe24f520b
--- /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 @padding 1
+  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..14772c480
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/createDemo.ts
@@ -0,0 +1,19 @@
+import 'server-only';
+
+import {
+  createDemoFactory,
+  createDemoWithVariantsFactory,
+} from '@mui/internal-docs-infra/abstractCreateDemo';
+
+import { CollapsibleDemoContent as DemoContent } from '../CollapsibleDemoContent';
+import { DemoTitle } from '../../../../components/code-highlighter/demos/DemoTitle';
+
+export const createDemo = createDemoFactory({
+  DemoContent,
+  DemoTitle,
+});
+
+export const createDemoWithVariants = createDemoWithVariantsFactory({
+  DemoContent,
+  DemoTitle,
+});
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/focus-code/FocusCode.tsx b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/focus-code/FocusCode.tsx
index 0852a0eef..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
@@ -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 @padding 1
   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..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
@@ -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 @padding 1
   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/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..3ec63609c
--- /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 @padding 1
+  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/demos/useScrollAnchor.ts b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
new file mode 100644
index 000000000..2fd7aa9db
--- /dev/null
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts
@@ -0,0 +1,222 @@
+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;
+}
+
+const GUTTER_STATE_ATTRIBUTE = 'data-scrollbar-gutter';
+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
+ * 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;
+}
+
+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
+ * 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;
+  }
+
+  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);
+}
+
+/**
+ * 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.
+ */
+function animateScrollbarGutterExpand(pre: HTMLElement) {
+  const scrollbarHeight = measureScrollbarHeight(pre);
+  if (scrollbarHeight === 0) {
+    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');
+
+  // 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() {
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const toggleRef = React.useRef<HTMLLabelElement>(null);
+
+  // 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;
+    if (!container) {
+      return;
+    }
+
+    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;
+    }
+
+    // On collapse, animate the scrollbar gutter (padding swap) to avoid
+    // 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;
+    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.
+    function cleanup() {
+      if (!active) {
+        return;
+      }
+      active = false;
+      clearTimeout(cleanupTimer);
+      observer.disconnect();
+      window.removeEventListener('wheel', stopOnUserInteraction);
+      window.removeEventListener('touchmove', stopOnUserInteraction);
+      window.removeEventListener('pointerdown', stopOnUserInteraction);
+      window.removeEventListener('keydown', stopOnUserInteraction);
+    }
+
+    function stopOnUserInteraction() {
+      cleanup();
+    }
+    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 });
+
+    observer.observe(container);
+
+    // Safety cleanup after the CSS transition completes.
+    const timeout = getTransitionTimeout(direction);
+    cleanupTimer = setTimeout(cleanup, timeout + 500);
+  }, []);
+
+  return { containerRef, toggleRef, anchorScroll };
+}
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..aed60e8d4 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,78 @@ 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.
+
+---
+
+## 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'
+```
 
 ---
 
@@ -147,15 +218,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 |
+| 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
 
@@ -287,10 +369,11 @@ 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).                                                                                                                                                                |
+| `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
 
@@ -307,13 +390,59 @@ 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.
+
+### 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`
 
-When `paddingFrameMaxSize` is `0` (the default), no padding frames are created and only `highlighted` and normal frames are produced.
+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
 
@@ -330,13 +459,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:
@@ -345,20 +467,64 @@ 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:
+Target frame types with CSS to style highlighted frames and create collapsible code blocks:
 
 ```css
-/* Normal frames and unfocused highlighted frames are hidden by default (collapsed) */
-.codeBlock .frame:not([data-frame-type]),
+/* 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'],
+.codeBlock .frame[data-frame-type='focus-unfocused'] {
   max-height: 0;
   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 */
+@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: clip;
+    transition:
+      height 0.3s ease,
+      opacity 0.3s ease;
+  }
 }
 
 /* Padding frames appear dimmed when collapsed */
@@ -369,11 +535,28 @@ Target frame types with CSS to create collapsible code blocks:
 }
 
 /* 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'] {
-  max-height: 500px;
-  overflow: visible;
+.expanded .codeBlock .frame[data-frame-type='highlighted-unfocused'],
+.expanded .codeBlock .frame[data-frame-type='focus-unfocused'] {
+  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 .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: clip;
+    transition:
+      height 0.3s ease,
+      opacity 0.3s ease;
+  }
 }
 
 .expanded .codeBlock .frame[data-frame-type='padding-top'],
@@ -381,203 +564,107 @@ 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'] {
-  transition: margin-left 0.3s ease;
+/* Use indent level to shift highlighted/focus frames left when collapsed */
+.codeBlock .frame[data-frame-type='highlighted'],
+.codeBlock .frame[data-frame-type='focus'] {
+  transition: transform 0.3s ease;
 }
 
-.codeBlock .frame[data-frame-type='highlighted'][data-frame-indent='1'] {
-  margin-left: -2ch;
+.codeBlock .frame[data-frame-type='highlighted'][data-frame-indent='1'],
+.codeBlock .frame[data-frame-type='focus'][data-frame-indent='1'] {
+  transform: translateX(-2ch);
 }
 
-.codeBlock .frame[data-frame-type='highlighted'][data-frame-indent='2'] {
-  margin-left: -4ch;
+.codeBlock .frame[data-frame-type='highlighted'][data-frame-indent='2'],
+.codeBlock .frame[data-frame-type='focus'][data-frame-indent='2'] {
+  transform: translateX(-4ch);
 }
 
 /* Reset indent shift when expanded */
-.expanded .codeBlock .frame[data-frame-type='highlighted'] {
-  margin-left: 0;
+.expanded .codeBlock .frame[data-frame-type='highlighted'],
+.expanded .codeBlock .frame[data-frame-type='focus'] {
+  transform: translateX(0);
 }
 ```
 
-### Demo: 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.
-
-import { DemoCollapsibleCode } from './demos/collapsible-code';
-
-<DemoCollapsibleCode />
-
-### 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.
-
-import { DemoFocusCode } from './demos/focus-code';
-
-<DemoFocusCode />
-
-### 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.
-
-import { DemoIndentCode } from './demos/indent-code';
-
-<DemoIndentCode />
-
----
-
-## Implementation Details
-
-### How It Works
+### Collapsible Code Block
 
-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
-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
+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:
 
-### 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 */]
+```css
+/* Hide toggle by default */
+.toggle {
+  display: none;
 }
-```
-
-For text highlighting with `@highlight-text "text"`, the specified text within the line is wrapped in a span:
 
-```ts
-{
-  type: 'element',
-  tagName: 'span',
-  properties: { dataHl: '' },
-  children: [{ type: 'text', value: 'text' }]
+/* Show only when the code block has collapsible frames */
+.pre code:has([data-collapsible]) ~ .toggle {
+  display: block;
 }
 ```
 
-### Data Attributes
-
-The enhancer adds these attributes to line elements:
-
-| 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 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)
+The following demo shows a code block that starts collapsed, revealing only the highlighted and padding frames. Click **Expand** to show the full source.
 
-For text highlighting with `@highlight-text "text"`:
+import { DemoCollapsibleCode } from './demos/collapsible-code';
 
-- The specified text within the line is wrapped in a `<span data-hl="">` element
-- The line element itself does not receive any additional attributes
+<DemoCollapsibleCode />
 
-### Stack-Based Pairing
+### Collapsible Demo
 
-Multi-line directives are paired using a stack:
+A full demo component with a live preview, file tabs, and collapsible code. The code section starts collapsed, showing only the focused region.
 
-- `@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
+import { DemoCollapsibleDemo } from './demos/collapsible-demo';
 
----
+<DemoCollapsibleDemo />
 
-## Configuration
+### @focus with Multiple Regions
 
-### Adding to Source Enhancers
+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.
 
-Configure in your webpack loader or server-side loading:
+import { DemoFocusCode } from './demos/focus-code';
 
-```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';
+<DemoFocusCode />
 
-const sourceEnhancers = [enhanceCodeEmphasis];
-```
+### Indent Shifting
 
-For configurable padding, use the factory:
+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.
 
-```ts
-import { createEnhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+import { DemoIndentCode } from './demos/indent-code';
 
-const sourceEnhancers = [
-  createEnhanceCodeEmphasis({
-    paddingFrameMaxSize: 3,
-    focusFramesMaxSize: 10,
-  }),
-];
-```
+<DemoIndentCode />
 
-Then pass to your loading pipeline:
+### Focus Max Size
 
-```ts
-// Create a loadSource that extracts emphasis comments
-const loadSource = createLoadServerSource({
-  notableCommentsPrefix: ['@highlight'],
-  removeCommentsWithPrefix: ['@highlight'],
-});
+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.
 
-// Use with loadCodeVariant
-const { code } = await loadCodeVariant(url, variantName, variant, {
-  loadSource,
-  sourceEnhancers,
-  sourceParser,
-});
+import { DemoMaxSizeCode } from './demos/max-size-code';
 
-// Or with CodeHighlighter
-<CodeHighlighter
-  sourceEnhancers={sourceEnhancers}
-  // ... other props
-/>
+<DemoMaxSizeCode />
 
-// Or with useCode
-const { selectedFile } = useCode(props, {
-  sourceEnhancers,
-});
-```
+---
 
-### Comment Prefix
+## Styling Emphasized Lines
 
-The default comment prefix is `@highlight`, exported as `EMPHASIS_COMMENT_PREFIX`:
+### Frame-Level Highlighting
 
-```ts
-import { EMPHASIS_COMMENT_PREFIX } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+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:
 
-console.log(EMPHASIS_COMMENT_PREFIX); // '@highlight'
+```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;
+}
 ```
 
-To use a different prefix, you would need to create a custom enhancer based on this implementation.
+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.
 
----
-
-## Styling Emphasized Lines
+### Line-Level Highlighting
 
-The `data-hl` attribute can be targeted with CSS. First, ensure lines are displayed as blocks for proper 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 */
@@ -591,60 +678,82 @@ 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) */
+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-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;
 }
 ```
 
@@ -745,6 +854,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/enhance-code-emphasis/types.md b/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
index 6ff352ea5..4a2b03392 100644
--- a/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
+++ b/docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md
@@ -76,11 +76,20 @@ 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 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 */
+  focusFramesMaxSize?: number;
   /**
-   * Whether the line itself should receive data-hl (from
-   * @highlight or multiline region)
+   * 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.
    */
-  lineHighlight?: boolean;
+  propagatedOverride?: boolean;
 };
 ```
 
@@ -97,10 +106,13 @@ 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.
+   * @default 12
    */
   focusFramesMaxSize?: number;
   /**
@@ -113,6 +125,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,11 +150,41 @@ type FrameRange = {
     | 'padding-top'
     | 'highlighted'
     | 'highlighted-unfocused'
+    | 'focus'
+    | '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';
 };
 ```
 
+### 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/lint-javascript-demo-focus/page.mdx b/docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
new file mode 100644
index 000000000..62497153b
--- /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 `@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 `@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 `@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 `@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
+
+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>
+      {/* @focus-start */}
+      <Button>Click me</Button>
+      <TextField label="Name" />
+      {/* @focus-end */}
+    </div>
+  );
+}
+```
+
+For a single child inside a wrapper:
+
+```tsx
+// After fix
+export default function Demo() {
+  return (
+    <div>
+      {/* @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() {
+  // @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 (
+    // @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 (
+    // @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() {
+  // @focus-start @padding 1
+  const code = useCode();
+  return <CodeEditor code={code} />;
+  // @focus-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..6a88a206f
--- /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 focus comments around the preview section.
+
+```typescript
+type lintJavascriptDemoFocus = {
+  meta: {
+    type: 'suggestion';
+    docs: {
+      description: 'Require demo files to have @focus-start / @focus-end comments around the preview section.';
+    };
+    fixable: 'code';
+    messages: {
+      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 @padding 1 and // @focus-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/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-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/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/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 51d893376..51e3967cd 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))
@@ -55,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
@@ -67,20 +71,19 @@ 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
-    - Demo: Collapsible Code Block
-    - Demo: @focus with Multiple Regions
-    - Demo: Indent Shifting
-  - 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
     - Showing Descriptions
   - Best Practices
     - Be Specific
@@ -91,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:
@@ -98,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, FrameRange
+- Types: EMPHASIS_COMMENT_PREFIX, EmphasisMeta, EnhanceCodeEmphasisOptions, FOCUS_COMMENT_PREFIX, FrameRange, MIN_COMMENT_PREFIX, PADDING_COMMENT_PREFIX
 
 </details>
 
@@ -322,6 +330,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 `@focus` comments around the preview section of demo files. These comments control which parts of the code are 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.
@@ -1076,6 +1109,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
@@ -1417,6 +1451,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 4cae70559..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;
 };
 ```
 
@@ -165,6 +170,16 @@ type WithDocsInfraOptions = {
    * @example ['@highlight', '@focus']
    */
   notableCommentsPrefix?: string[];
+  /**
+   * Options for the code emphasis enhancer used by demo loaders.
+   * Passed to `createEnhanceCodeEmphasis` in the precomputed code highlighter loader.
+   */
+  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/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/docs/next.config.mjs b/docs/next.config.mjs
index b2b9af7d4..ac9e9e0f8 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'],
       },
+      demoEmphasisOptions: { paddingFrameMaxSize: 2, focusFramesMaxSize: 18 },
     })(withMDX(nextConfig)),
   ),
 );
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 db6cbedfc..75ac395ae 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 459068c4d..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",
@@ -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.2.3",
diff --git a/packages/docs-infra/src/CodeHighlighter/types.ts b/packages/docs-infra/src/CodeHighlighter/types.ts
index af15c23fa..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 };
+  data?: RootData & { totalLines?: number; collapsible?: boolean; frameSize?: number };
 }
 
 export type VariantSource = string | HastRoot | { hastJson: string } | { hastCompressed: string };
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 7eb89faff..bc8433d9d 100644
--- a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
+++ b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.test.ts
@@ -78,7 +78,7 @@ describe('enhanceCodeEmphasis', () => {
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Button</span>() {</span>
         <span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="2"><span class="line" data-ln="3" data-hl="" data-hl-position="single">    &#x3C;<span class="pl-ent">button</span> <span class="pl-e di-ak">className</span><span class="pl-k di-ae">=</span><span class="pl-s di-av"><span class="pl-pds">"</span>primary<span class="pl-pds">"</span></span>>Click me&#x3C;/<span class="pl-ent">button</span>></span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="2"><span class="line" data-ln="3">    &#x3C;<span class="pl-ent">button</span> <span class="pl-e di-ak">className</span><span class="pl-k di-ae">=</span><span class="pl-s di-av"><span class="pl-pds">"</span>primary<span class="pl-pds">"</span></span>>Click me&#x3C;/<span class="pl-ent">button</span>></span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="4">  );</span>
         <span class="line" data-ln="5">}</span></span>"
       `);
@@ -96,9 +96,9 @@ const e = 5; // @highlight`,
 
       expect(result).toMatchInlineSnapshot(
         `
-        "<span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1" 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 di-num">1</span>;</span>
+        "<span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1"><span class="pl-k">const</span> <span class="pl-c1">a</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">1</span>;</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="2"><span class="pl-k">const</span> <span class="pl-c1">b</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">2</span>;</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted-unfocused" data-frame-indent="0"><span class="line" data-ln="3" 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 di-num">3</span>;</span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted-unfocused" data-frame-indent="0"><span class="line" data-ln="3"><span class="pl-k">const</span> <span class="pl-c1">c</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">3</span>;</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="4"><span class="pl-k">const</span> <span class="pl-c1">d</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">4</span>;</span>
         </span>"
       `,
@@ -116,7 +116,7 @@ const e = 5; // @highlight`,
 
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="1"><span class="line" data-ln="2" data-hl="" 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 di-num">0</span>);</span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="1" data-frame-description="We track state"><span class="line" data-ln="2">  <span class="pl-k">const</span> [<span class="pl-c1">count</span>, <span class="pl-c1">setCount</span>] <span class="pl-k">=</span> <span class="pl-en">useState</span>(<span class="pl-c1 di-num">0</span>);</span>
         </span><span class="frame" data-lined=""><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>"
       `);
@@ -159,10 +159,10 @@ const e = 5; // @highlight`,
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
         <span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="2"><span class="line" data-ln="3" 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-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=""><span class="line" data-ln="7">  );</span>
         <span class="line" data-ln="8">}</span></span>"
       `);
@@ -199,7 +199,7 @@ const e = 5; // @highlight`,
       expect(result).toMatchInlineSnapshot(
         `
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">function</span> <span class="pl-en">test</span>() {</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="1"><span class="line" data-ln="2" data-hl="">  <span class="pl-k">return</span> <span class="pl-c1 di-n">null</span>;</span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="1"><span class="line" data-ln="2">  <span class="pl-k">return</span> <span class="pl-c1 di-n">null</span>;</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="3">}</span></span>"
       `,
       );
@@ -222,9 +222,9 @@ const e = 5; // @highlight`,
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
         <span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="2"><span class="line" data-ln="3" 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-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=""><span class="line" data-ln="6">  );</span>
         <span class="line" data-ln="7">}</span></span>"
       `);
@@ -248,11 +248,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><span class="frame" data-lined="" 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-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=""><span class="line" data-ln="7">}</span></span>"
       `);
     });
@@ -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 di-ak">className</span><span class="pl-k di-ae">=</span><span class="pl-s di-av"><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 di-ak">className</span><span class="pl-k di-ae">=</span><span class="pl-s di-av"><span class="pl-pds">"</span><mark>primary</mark><span class="pl-pds">"</span></span>><mark>Heading 1</mark>&#x3C;/<span class="pl-ent">h1</span>></span>
+        <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 di-jsx">AlertDialog.Trigger</span> <span data-hl=""><span class="pl-e di-ak">handle</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">demoAlertDialog</span><span class="pl-pse">}</span></span>>Open&#x3C;/<span class="pl-c1 di-jsx">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 di-jsx">AlertDialog.Trigger</span> <mark><span class="pl-e di-ak">handle</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">demoAlertDialog</span><span class="pl-pse">}</span></mark>>Open&#x3C;/<span class="pl-c1 di-jsx">AlertDialog.Trigger</span>></span></span>"`,
       );
     });
 
@@ -340,7 +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 di-jsx">Button</span> <span class="pl-e di-ak">render</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span>&#x3C;<span class="pl-ent">div</span> /><span class="pl-pse">}</span> <span data-hl=""><span class="pl-e">nativeButton</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-c1 di-bool">false</span><span class="pl-pse">}</span></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 di-jsx">Button</span> <span class="pl-e di-ak">render</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span>&#x3C;<span class="pl-ent">div</span> /><span class="pl-pse">}</span> <mark><span class="pl-e">nativeButton</span><span class="pl-k">=</span><span class="pl-pse">{</span><span class="pl-c1 di-bool">false</span><span class="pl-pse">}</span></mark>></span></span>"`,
       );
     });
 
@@ -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 () => {
@@ -365,11 +365,11 @@ 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 frame should have data-frame-type="highlighted" from @highlight AND wrap ", 40px" from @highlight-text.
+      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 di-num di-cv">40</span><span class="pl-k">px</span></span>',
+        '<mark>, <span class="pl-c1 di-num di-cv">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 di-jsx">Input</span> <span data-hl=""><span class="pl-e di-ak">value</span></span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">a</span><span class="pl-pse">}</span> /> &#x3C;<span class="pl-c1 di-jsx">Input</span> <span data-hl=""><span class="pl-e di-ak">value</span></span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">b</span><span class="pl-pse">}</span> /> <span class="pl-c">// @highlight-text "<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 di-jsx">Input</span> <mark class="pl-e di-ak">value</mark><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">a</span><span class="pl-pse">}</span> /> &#x3C;<span class="pl-c1 di-jsx">Input</span> <mark class="pl-e di-ak">value</mark><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">b</span><span class="pl-pse">}</span> /> <span class="pl-c">// @highlight-text "<mark>value</mark>"</span></span></span>"`,
       );
     });
 
@@ -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 di-jsx">Input</span> <span data-hl=""><span class="pl-e di-ak">value</span></span><span class="pl-k di-ae">=</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 di-jsx">Input</span> <mark class="pl-e di-ak">value</mark><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><mark class="pl-smi">value</mark><span class="pl-pse">}</span> /></span></span>"`,
       );
     });
   });
@@ -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');
     });
 
@@ -597,10 +597,10 @@ const another = 99; // @highlight`,
       );
 
       expect(result).toMatchInlineSnapshot(`
-        "<span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1" 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 di-num">42</span>;</span>
+        "<span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="0"><span class="line" data-ln="1"><span class="pl-k">const</span> <span class="pl-c1">value</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">42</span>;</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="2"><span class="pl-k">function</span> <span class="pl-en">example</span>() {</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted-unfocused" data-frame-indent="1"><span class="line" data-ln="3" 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 di-num">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 di-num">2</span>;</span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted-unfocused" data-frame-indent="1"><span class="line" data-ln="3">  <span class="pl-k">const</span> <span class="pl-c1">x</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">1</span>;</span>
+        <span class="line" data-ln="4">  <span class="pl-k">const</span> <span class="pl-c1">y</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">2</span>;</span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="5">  <span class="pl-k">return</span> <span class="pl-smi">x</span> <span class="pl-k">+</span> <span class="pl-smi">y</span>;</span>
         <span class="line" data-ln="6">}</span>
         </span>"
@@ -623,19 +623,73 @@ 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=""/);
+      // 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=""/);
+      // 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"');
     });
+
+    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', () => {
@@ -680,7 +734,7 @@ const c = 3;`,
       );
 
       expect(result).toMatchInlineSnapshot(`
-        "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">const</span> <span class="pl-c1">a</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">1</span>;</span>
+        "<span class="frame" data-lined="" data-frame-type="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 di-num">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 di-num">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 di-num">3</span>;</span></span>"
       `);
@@ -695,7 +749,7 @@ const b = 2;`,
 
       // Should not add any emphasis since there's no quoted text
       expect(result).toMatchInlineSnapshot(`
-        "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">const</span> <span class="pl-c1">a</span> <span class="pl-k">=</span> <span class="pl-c1 di-num">1</span>;</span>
+        "<span class="frame" data-lined="" data-frame-type="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 di-num">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 di-num">2</span>;</span></span>"
       `);
     });
@@ -719,7 +773,7 @@ const b = 2;`,
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Component</span>() {</span>
         <span class="line" data-ln="2">  <span class="pl-k">return</span> (</span>
         <span class="line" data-ln="3">    &#x3C;<span class="pl-ent">div</span>></span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="3"><span class="line" data-ln="4" 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-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=""><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>
@@ -747,13 +801,13 @@ const b = 2;`,
 
       expect(result).toMatchInlineSnapshot(`
         "<span class="frame" data-lined=""><span class="line" data-ln="1"><span class="pl-k">export</span> <span class="pl-k">default</span> <span class="pl-k">function</span> <span class="pl-en">Dashboard</span>() {</span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted" data-frame-indent="1"><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-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=""><span class="line" data-ln="3">  <span class="pl-k">return</span> (</span>
         <span class="line" data-ln="4">    &#x3C;<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="5">      &#x3C;<span class="pl-c1 di-jsx">Header</span> /></span>
-        </span><span class="frame" data-lined="" data-frame-type="highlighted-unfocused" data-frame-indent="3"><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 di-jsx">Chart</span> <span class="pl-e di-ak">data</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">data</span><span class="pl-pse">}</span> /></span>
-        <span class="line" data-ln="7" data-hl="" data-hl-position="end">      &#x3C;<span class="pl-c1 di-jsx">Table</span> <span class="pl-e di-ak">data</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">data</span><span class="pl-pse">}</span> /></span>
-        <span class="line" data-ln="8" data-hl="" data-hl-position="single">      &#x3C;<span class="pl-c1 di-jsx">Footer</span> /></span>
+        </span><span class="frame" data-lined="" data-frame-type="highlighted-unfocused" data-frame-indent="3" data-frame-description="We render the main content"><span class="line" data-ln="6">      &#x3C;<span class="pl-c1 di-jsx">Chart</span> <span class="pl-e di-ak">data</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">data</span><span class="pl-pse">}</span> /></span>
+        <span class="line" data-ln="7">      &#x3C;<span class="pl-c1 di-jsx">Table</span> <span class="pl-e di-ak">data</span><span class="pl-k di-ae">=</span><span class="pl-pse">{</span><span class="pl-smi">data</span><span class="pl-pse">}</span> /></span>
+        <span class="line" data-ln="8">      &#x3C;<span class="pl-c1 di-jsx">Footer</span> /></span>
         </span><span class="frame" data-lined=""><span class="line" data-ln="9">    &#x3C;/<span class="pl-ent">div</span>></span>
         <span class="line" data-ln="10">  );</span>
         <span class="line" data-ln="11">}</span></span>"
@@ -825,8 +879,8 @@ const b = 2;`,
       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/);
+      // Check that the content lines are in a highlighted frame
+      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"');
@@ -841,8 +895,8 @@ const z = 3;`,
         parseSource,
       );
 
-      // Line 2 has the @highlight comment and should be highlighted
-      expect(result).toMatch(/data-ln="2"[^>]*data-hl/);
+      // Line 2 has the @highlight comment and should be in a highlighted frame
+      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/);
@@ -867,14 +921,33 @@ 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 (<h1>) should be in a highlighted frame
+      expect(result).toContain('data-frame-type="highlighted"');
 
       // Line 6 has {/* @highlight-end */} - should NOT have data-hl
       expect(result).toContain('data-ln="6"');
       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() {
@@ -888,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 di-ak">className</span><span class="pl-k di-ae">=</span><span class="pl-s di-av"><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 di-ak">className</span><span class="pl-k di-ae">=</span><span class="pl-s di-av"><span class="pl-pds">"</span><mark>primary</mark><span class="pl-pds">"</span></span>><mark>Heading 1</mark>&#x3C;/<span class="pl-ent">h1</span>> <span class="pl-pse">{</span><span class="pl-c">/* @highlight-text "<mark>primary</mark>" "<mark>Heading 1</mark>" */</span><span class="pl-pse">}</span></span>
+        <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>"
       `);
@@ -928,14 +1001,10 @@ const g = 7;`,
       expect(result).toContain('data-frame-type="highlighted"');
       expect(result).toContain('data-frame-type="padding-bottom"');
 
-      // Verify frame boundaries: which lines belong to which frame
-      expect(result).toMatch(/data-frame-type="padding-top"><span class="line" data-ln="2"/);
-      expect(result).toMatch(/data-frame-type="highlighted"[^>]*><span class="line" data-ln="4"/);
-      expect(result).toMatch(/data-frame-type="padding-bottom"><span class="line" data-ln="5"/);
-      // Padding top should include lines 2-3
-      expect(result).toMatch(/data-frame-type="padding-top">.*data-ln="3"/s);
-      // Padding bottom should include lines 5-6
-      expect(result).toMatch(/data-frame-type="padding-bottom">.*data-ln="6"/s);
+      // Verify frame boundaries
+      expect(result).toMatch(/data-frame-type="padding-top"/);
+      expect(result).toMatch(/data-frame-type="highlighted"/);
+      expect(result).toMatch(/data-frame-type="padding-bottom"/);
     });
 
     it('should limit total focus area with focusFramesMaxSize', async () => {
@@ -966,13 +1035,9 @@ const l = 12;`,
       // focusFramesMaxSize = 5, so remaining for padding = 5 - 3 = 2
       // floor(2/2)=1 top, ceil(2/2)=1 bottom
       // Even though paddingFrameMaxSize is 5, focusFramesMaxSize caps it
-      // Padding top: only line 5 (capped to 1)
-      expect(result).toMatch(/data-frame-type="padding-top"><span class="line" data-ln="5"/);
-      // Highlighted: lines 6-8
-      expect(result).toMatch(/data-frame-type="highlighted"[^>]*><span class="line" data-ln="6"/);
-      expect(result).toMatch(/data-frame-type="highlighted"[^>]*>.*data-ln="8"/s);
-      // Padding bottom: only line 9 (capped to 1)
-      expect(result).toMatch(/data-frame-type="padding-bottom"><span class="line" data-ln="9"/);
+      expect(result).toMatch(/data-frame-type="padding-top"/);
+      expect(result).toMatch(/data-frame-type="highlighted"/);
+      expect(result).toMatch(/data-frame-type="padding-bottom"/);
     });
 
     it('should not add padding when paddingFrameMaxSize is 0', async () => {
@@ -1015,17 +1080,13 @@ const e = 5;`,
 
       // Two highlight regions: line 1 and line 4
       // @focus is on line 4, so padding goes around line 4
-      // Padding top: line 3
-      expect(result).toMatch(/data-frame-type="padding-top"><span class="line" data-ln="3"/);
-      // Highlighted (focused): line 4
-      expect(result).toMatch(/data-frame-type="highlighted"[^>]*><span class="line" data-ln="4"/);
-      // Padding bottom: line 5
-      expect(result).toMatch(/data-frame-type="padding-bottom"><span class="line" data-ln="5"/);
+      // Padding top: line 3, padding bottom: line 5
+      expect(result).toMatch(/data-frame-type="padding-top"/);
+      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)
-      expect(result).toMatch(
-        /data-frame-type="highlighted-unfocused"[^>]*><span class="line" data-ln="1"/,
-      );
+      expect(result).toMatch(/data-frame-type="highlighted-unfocused"/);
     });
 
     it('should support @focus on @highlight-start', async () => {
@@ -1050,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 () => {
@@ -1068,18 +1136,13 @@ const d = 4;`,
       );
 
       // @focus on line 3 with description "important line"
-      // Highlighted (focused): line 3
-      expect(result).toMatch(/data-frame-type="highlighted"[^>]*><span class="line" data-ln="3"/);
-      expect(result).toContain('data-hl-description="Important line"');
-      // Padding top: line 2
-      expect(result).toMatch(/data-frame-type="padding-top"><span class="line" data-ln="2"/);
-      // Padding bottom: line 4
-      expect(result).toMatch(/data-frame-type="padding-bottom"><span class="line" data-ln="4"/);
+      expect(result).toMatch(/data-frame-type="highlighted"/);
+      expect(result).toContain('data-frame-description="Important line"');
+      expect(result).toContain('data-frame-type="padding-top"');
+      expect(result).toContain('data-frame-type="padding-bottom"');
 
       // Line 1 is highlighted-unfocused
-      expect(result).toMatch(
-        /data-frame-type="highlighted-unfocused"[^>]*><span class="line" data-ln="1"/,
-      );
+      expect(result).toMatch(/data-frame-type="highlighted-unfocused"/);
     });
   });
 
diff --git a/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts b/packages/docs-infra/src/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.ts
index b33d07ae6..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 } 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';
@@ -18,6 +22,26 @@ 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';
+
+/**
+ * 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.
  */
@@ -32,57 +56,284 @@ 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;
+  /** 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 char = content[i];
+    if (quoteChar) {
+      result += '_';
+      if (char === quoteChar) {
+        quoteChar = undefined;
+      }
+    } else if (char === '"' || char === "'") {
+      quoteChar = char;
+      result += '_';
+    } else {
+      result += char;
+    }
+  }
+  return result;
+}
+
+/**
+ * Returns `true` when `ch` is an ASCII whitespace character.
+ */
+function isWhitespace(char: string | undefined): boolean {
+  return char === ' ' || char === '\t' || char === '\n' || char === '\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 pos = idx + '@padding'.length;
+  while (pos < masked.length && isWhitespace(masked[pos])) {
+    pos += 1;
+  }
+  const digits = readDigits(masked, pos);
+  if (digits.length === 0) {
+    return undefined;
+  }
+  // Must be followed by whitespace or end-of-string
+  const afterDigits = pos + 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 pos = idx + '@min'.length;
+  while (pos < masked.length && isWhitespace(masked[pos])) {
+    pos += 1;
+  }
+  const digits = readDigits(masked, pos);
+  if (digits.length === 0) {
+    return undefined;
+  }
+  // Must be followed by whitespace or end-of-string
+  const afterDigits = pos + 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);
+    }
+  }
+  // Find first quoted substring anywhere
+  for (let i = 0; i < content.length; 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);
+      }
+    }
   }
-  // Also try to find quoted string anywhere in the content
-  const anyMatch = content.match(/(["'])([^"']+)\1/);
-  return anyMatch?.[2];
+  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 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;
+        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 };
 }
 
@@ -97,6 +348,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 +361,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 +379,120 @@ 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 {
+  // 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,
+      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) {
+      // 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: false,
+        paddingFrameMaxSize: undefined,
+        focusFramesMaxSize: undefined,
+      });
+    }
+  } else {
+    const afterHighlight = contentWithoutModifiers.trim();
+    const { focus, remaining: remainingSingle } = extractFocus(afterHighlight);
+    const description = extractQuotedString(remainingSingle) || undefined;
+    directives.push({
+      line,
+      type: 'single',
+      description,
+      focus,
+      lineHighlight: true,
+      paddingFrameMaxSize,
+      focusFramesMaxSize,
+    });
+  }
+}
+
+/**
+ * Parses a `@focus` comment into a focus-only directive (no line highlight).
+ */
+function parseFocusDirective(directives: EmphasisDirective[], line: number, content: string): void {
+  // 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,
+      paddingFrameMaxSize,
+      focusFramesMaxSize,
+    });
+  } else {
+    // Single line: @focus or @focus "description"
+    const afterFocus = contentWithoutModifiers.trim();
+    const description = extractQuotedString(afterFocus) || undefined;
+    directives.push({
+      line,
+      type: 'single',
+      description,
+      focus: true,
+      lineHighlight: false,
+      paddingFrameMaxSize,
+      focusFramesMaxSize,
+    });
+  }
+}
+
 /**
  * Capitalizes the first letter of a string.
  *
@@ -298,8 +630,10 @@ function calculateEmphasizedLines(
         description,
         strong,
         position: 'single',
-        lineHighlight: true,
+        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.
@@ -313,8 +647,11 @@ function calculateEmphasizedLines(
       emphasizedLines.set(directive.line, {
         ...existing,
         position: existing?.position ?? 'single',
+        lineHighlight: existing?.lineHighlight ?? directive.lineHighlight,
         highlightTexts: mergedTexts,
         focus: directive.focus || existing?.focus,
+        paddingFrameMaxSize: directive.paddingFrameMaxSize ?? existing?.paddingFrameMaxSize,
+        focusFramesMaxSize: directive.focusFramesMaxSize ?? existing?.focusFramesMaxSize,
       });
     }
   }
@@ -333,7 +670,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;
@@ -363,26 +702,63 @@ 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: true, // Inside a multiline region = always line highlight
+              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,
+              // 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,
               description: line === startLine ? description : undefined,
               position,
-              lineHighlight: true,
+              lineHighlight: startDirective.lineHighlight,
               focus: startDirective.focus,
+              paddingFrameMaxSize: startDirective.paddingFrameMaxSize,
+              focusFramesMaxSize: startDirective.focusFramesMaxSize,
+              propagatedOverride: true,
             };
 
         emphasizedLines.set(line, meta);
@@ -393,9 +769,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.
  */
@@ -404,7 +806,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) {
@@ -414,6 +816,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.
@@ -555,16 +975,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,
@@ -585,19 +1000,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(
@@ -738,16 +1153,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,
@@ -812,8 +1222,16 @@ 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
+            // For text highlight, wrap the specific text(s) in a <mark> element
             let children = child.children;
             for (const text of meta.highlightTexts) {
               children = wrapTextInHighlightSpan(
@@ -824,11 +1242,22 @@ 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).
-            // Standalone @highlight-text lines should not get line-level highlights.
-            if (meta.lineHighlight) {
-              child.properties.dataHl = meta.strong ? 'strong' : '';
+            // 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 marks
+            // because the frame itself handles the visual emphasis.
+            if (shouldApplyLineHl) {
+              const hlValue = meta.strong ? 'strong' : '';
+              child.properties.dataHl = hlValue;
 
               if (meta.description) {
                 child.properties.dataHlDescription = meta.description;
@@ -838,7 +1267,7 @@ function applyEmphasisAndCollectHighlightedElements(
                 child.properties.dataHlPosition = meta.position;
               }
             }
-          } else {
+          } else if (shouldApplyLineHl) {
             // Use data-hl with optional "strong" value on the line
             child.properties.dataHl = meta.strong ? 'strong' : '';
 
@@ -920,6 +1349,78 @@ function calculateRegionIndentLevels(
   return regionIndentLevels;
 }
 
+/**
+ * Post-restructure pass that reconciles line-level `data-hl` attributes with
+ * frame-level types.
+ *
+ * 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 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' ||
+        child.tagName !== 'span' ||
+        child.properties?.className !== 'line' ||
+        typeof child.properties.dataLn !== 'number'
+      ) {
+        continue;
+      }
+
+      const meta = emphasizedLines.get(child.properties.dataLn);
+      if (!meta) {
+        continue;
+      }
+
+      // 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;
+      }
+
+      // 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;
+      }
+    }
+  }
+}
+
 /**
  * Creates a source enhancer that adds emphasis to code lines based on `@highlight` comments
  * and restructures frames around highlighted regions.
@@ -978,19 +1479,59 @@ export function createEnhanceCodeEmphasis(
   options: EnhanceCodeEmphasisOptions = {},
 ): SourceEnhancer {
   return (root: HastRoot, comments: SourceComments | undefined): HastRoot => {
-    if (!comments || Object.keys(comments).length === 0) {
-      return root;
+    // 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 = parseEmphasisDirectives(comments);
+    const directives =
+      comments && Object.keys(comments).length > 0 ? parseEmphasisDirectives(comments) : [];
 
-    if (directives.length === 0) {
-      return root;
-    }
+    const effectiveOptions = options;
+    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;
+
+    // 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,
+        normalFrameMaxSize,
+      );
+      restructureFrames(root, frameRanges, new Map());
+      markCollapsible(frameRanges);
+      return root;
+    }
 
     // Step 3: Calculate which lines are emphasized (no tree traversal)
     const emphasizedLines = calculateEmphasizedLines(directives, lineElements);
@@ -1003,18 +1544,34 @@ export function createEnhanceCodeEmphasis(
     const highlightedElements = applyEmphasisAndCollectHighlightedElements(
       root,
       emphasizedLines,
-      options,
+      effectiveOptions,
     );
 
     // Step 5: Calculate indent levels per region (uses collected elements, no tree traversal)
     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, options);
+    // 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,
+      normalFrameMaxSize,
+    );
 
     // 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);
 
     return root;
   };
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..654a91c3b
--- /dev/null
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts
@@ -0,0 +1,597 @@
+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-start with @focus — skip
+        {
+          code: `
+{/* @highlight-start @focus */}
+export default function Demo() {
+  return <div>Hello</div>;
+}
+{/* @highlight-end */}
+          `,
+        },
+        // File already has @focus — skip
+        {
+          code: `
+// @focus-start
+export default function Demo() {
+  return <div>Hello</div>;
+}
+// @focus-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' } });
+          `,
+        },
+        // File already has standalone @focus in a comment — skip
+        {
+          code: `
+// @focus
+export default function Demo() {
+  return <div>Hello</div>;
+}
+          `,
+        },
+        // 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)
+        {
+          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() {
+  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-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-text "Click"
+export default function Demo() {
+  return <Button>Click</Button>;
+}`,
+          output: `// @highlight-text "Click"
+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() {
+  // @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>
+      {/* @focus-start */}
+      <Button>Click me</Button>
+      <Button>Click me too</Button>
+      {/* @focus-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>
+      {/* @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>
+      {/* @focus-start */}
+      <Input />
+      <Button />
+      {/* @focus-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 (
+    <>
+      {/* @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 () => {
+  // @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: `// @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 (
+    // @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>
+      {/* @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>
+      {/* @focus-start */}
+      <Input />
+      <Button />
+      {/* @focus-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 = () => {
+  // @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() {
+  // @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>
+      {/* @focus-start */}
+      <Input />
+      <Button />
+      {/* @focus-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() {
+  // @focus-start @padding 1
+  const code = useCode();
+  return (
+    <div>
+      {code.file}
+    </div>
+  );
+  // @focus-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) {
+  // @focus-start @padding 1
+  const code = useCode(props);
+  return (
+    <div>{code.file}</div>
+  );
+  // @focus-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) {
+  // @focus-start @padding 1
+  const { disabled, children, ...other } = props;
+  return (
+    <button type="button" ref={ref} disabled={disabled} {...other}>
+      {children}
+    </button>
+  );
+  // @focus-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(() => {
+  // @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) {
+  // @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 (
+    // @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 (
+    // @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 (
+    // @focus-start
+    <Card>
+    <Button>Click</Button>
+  </Card>
+    // @focus-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>
+      {/* @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 (
+    // @focus
+    <Checkbox defaultChecked />
+  );
+}`,
+          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
new file mode 100644
index 000000000..3b4392521
--- /dev/null
+++ b/packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts
@@ -0,0 +1,527 @@
+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 focus comments around the preview section.
+ */
+export const lintJavascriptDemoFocus = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Require demo files to have @focus-start / @focus-end comments around the preview section.',
+    },
+    fixable: 'code',
+    messages: {
+      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 @padding 1 and // @focus-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 options = (context.options[0] ?? {}) as { wrapReturn?: boolean };
+
+    // 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, @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);
+    });
+
+    if (hasFocusComment) {
+      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 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);
+        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, `{/* @focus */}\n${indentation}`);
+      }
+      if (insideWrapper) {
+        return [
+          fixer.insertTextBeforeRange(firstNode.range, `{/* @focus-start */}\n${indentation}`),
+          fixer.insertTextAfterRange(lastNode.range, `\n${indentation}{/* @focus-end */}`),
+        ];
+      }
+
+      // 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);
+
+        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}// @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}// @focus-start\n`,
+            ),
+            fixer.insertTextAfterRange(
+              [lastLineStartOffset, lastLineStartOffset + lastLine.length],
+              `\n${lastIndentation}// @focus-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}// @focus\n${innerIndentation}`,
+            ),
+            fixer.insertTextAfterRange(lastNode.range, `\n${returnIndentation})`),
+          ];
+        }
+        return [
+          fixer.replaceTextRange(
+            [returnKeywordEnd, firstNode.range[0]],
+            ` (\n${innerIndentation}// @focus-start\n${innerIndentation}`,
+          ),
+          fixer.insertTextAfterRange(
+            lastNode.range,
+            `\n${innerIndentation}// @focus-end\n${returnIndentation})`,
+          ),
+        ];
+      }
+
+      // 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,
+        column: 0,
+      });
+      if (isSingleLine) {
+        return fixer.insertTextBeforeRange(
+          [lineStartOffset, lineStartOffset],
+          `${indentation}// @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}// @focus-start\n`,
+        ),
+        fixer.insertTextAfterRange(
+          [lastLineStartOffset, lastLineStartOffset + lastLine.length],
+          `\n${lastIndentation}// @focus-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}// @focus-start @padding 1\n`,
+        ),
+        fixer.insertTextAfterRange(
+          [lastLineStartOffset, lastLineStartOffset + lastLine.length],
+          `\n${lastIndentation}// @focus-end`,
+        ),
+      ];
+    },
+  });
+}
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/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts b/packages/docs-infra/src/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts
index 0c1e4f6fd..df4de46a5 100644
--- a/packages/docs-infra/src/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts
+++ b/packages/docs-infra/src/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts
@@ -10,9 +10,11 @@ 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';
 import { parseCreateFactoryCall } from './parseCreateFactoryCall';
 import { resolveVariantPathsWithFs } from '../loadServerCodeMeta/resolveModulePathWithFs';
@@ -65,6 +67,11 @@ export type LoaderOptions = {
     showWrapperMeasures?: boolean;
   };
   output?: 'hast' | 'hastJson' | 'hastCompressed';
+  /**
+   * 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.
@@ -171,10 +178,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 ?? []),
     ];
@@ -192,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/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/__snapshots__/highlightTypes.test.ts.snap b/packages/docs-infra/src/pipeline/loadServerTypes/__snapshots__/highlightTypes.test.ts.snap
index 6c0152287..5dd72f534 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
@@ -95,6 +95,7 @@ exports[`highlightTypes > snapshot tests - precomputed output verification > sho
         ],
         "properties": {
           "className": "frame",
+          "dataFrameType": "focus",
           "dataLined": "",
         },
         "tagName": "span",
@@ -253,6 +254,7 @@ exports[`highlightTypes > snapshot tests - precomputed output verification > sho
         ],
         "properties": {
           "className": "frame",
+          "dataFrameType": "focus",
           "dataLined": "",
         },
         "tagName": "span",
@@ -713,6 +715,7 @@ exports[`highlightTypes > snapshot tests - precomputed output verification > sho
       ],
       "properties": {
         "className": "frame",
+        "dataFrameType": "focus",
         "dataLined": "",
       },
       "tagName": "span",
@@ -860,6 +863,7 @@ exports[`highlightTypes > snapshot tests - precomputed output verification > sho
       ],
       "properties": {
         "className": "frame",
+        "dataFrameType": "focus",
         "dataLined": "",
       },
       "tagName": "span",
@@ -1013,6 +1017,7 @@ exports[`highlightTypes > snapshot tests - precomputed output verification > sho
       ],
       "properties": {
         "className": "frame",
+        "dataFrameType": "focus",
         "dataLined": "",
       },
       "tagName": "span",
@@ -1218,6 +1223,7 @@ exports[`highlightTypes > snapshot tests - precomputed output verification > sho
       ],
       "properties": {
         "className": "frame",
+        "dataFrameType": "focus",
         "dataLined": "",
       },
       "tagName": "span",
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/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/loaderUtils/parseImportsAndComments.test.ts b/packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.test.ts
index 26d0ec665..6d7c18025 100644
--- a/packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.test.ts
+++ b/packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.test.ts
@@ -3017,6 +3017,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 976f1d1ae..110ee5727 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/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 cd4717c49..c06bd052d 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.test.ts
@@ -1,93 +1,101 @@
 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', () => {
     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);
 
       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' },
       ]);
     });
 
     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);
 
       expect(result).toEqual<FrameRange[]>([
-        { startLine: 1, endLine: 1, type: 'highlighted' },
+        { startLine: 1, endLine: 1, type: 'highlighted', regionIndex: 0 },
         { startLine: 2, endLine: 5, type: 'normal' },
       ]);
     });
 
     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);
 
       expect(result).toEqual<FrameRange[]>([
         { startLine: 1, endLine: 4, type: 'normal' },
-        { startLine: 5, endLine: 5, type: 'highlighted' },
+        { startLine: 5, endLine: 5, type: 'highlighted', regionIndex: 0 },
       ]);
     });
 
     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);
 
-      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', () => {
       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);
 
       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' },
       ]);
     });
 
     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);
 
       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' },
       ]);
     });
 
     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
@@ -95,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' },
       ]);
     });
@@ -103,7 +111,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,
@@ -112,14 +122,16 @@ 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' },
       ]);
     });
 
     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,
@@ -128,14 +140,16 @@ 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' },
       ]);
     });
 
     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,
@@ -145,15 +159,15 @@ 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' },
       ]);
     });
 
     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, {
@@ -163,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' },
       ]);
     });
@@ -177,7 +191,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,
@@ -187,21 +203,22 @@ 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' }],
-        [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, {
@@ -211,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' },
       ]);
     });
@@ -219,7 +243,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,
@@ -229,17 +255,95 @@ 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
       // 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,
@@ -249,31 +353,313 @@ 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' },
       ]);
     });
+
+    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: 'highlighted', regionIndex: 0, truncated: 'visible' },
+        {
+          startLine: 7,
+          endLine: 8,
+          type: 'highlighted-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: 'highlighted', 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: 'highlighted', regionIndex: 0, truncated: 'visible' },
+        {
+          startLine: 7,
+          endLine: 9,
+          type: 'highlighted-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: 'highlighted', regionIndex: 0, truncated: 'visible' },
+        {
+          startLine: 8,
+          endLine: 9,
+          type: 'highlighted-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('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 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[]>([
+        {
+          startLine: 1,
+          endLine: DEFAULT_FOCUS_FRAMES_MAX_SIZE,
+          type: 'focus',
+          regionIndex: 0,
+          truncated: 'visible',
+        },
+        {
+          startLine: DEFAULT_FOCUS_FRAMES_MAX_SIZE + 1,
+          endLine: totalLines,
+          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>([
-        [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, {
         paddingFrameMaxSize: 3,
       });
 
-      // Second region is focused, so it gets padding
+      // Second region is focused, so it gets padding.
+      // 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' },
+        { 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: 'highlighted', regionIndex: 1 },
         { startLine: 16, endLine: 18, type: 'padding-bottom' },
         { startLine: 19, endLine: 20, type: 'normal' },
       ]);
@@ -281,8 +667,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, {
@@ -293,13 +679,62 @@ 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 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 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 }],
+        [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' },
+      ]);
+    });
+
+    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', () => {
@@ -312,11 +747,15 @@ 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);
 
-      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', () => {
@@ -324,26 +763,30 @@ 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', () => {
       const emphasizedLines = new Map<number, EmphasisMeta>([
-        [5, { position: 'single', highlightTexts: ['Button'] }],
+        [5, { position: 'single', lineHighlight: true, highlightTexts: ['Button'] }],
       ]);
 
       const result = calculateFrameRanges(emphasizedLines, 10);
 
       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' },
       ]);
     });
 
     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,
@@ -351,7 +794,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' },
       ]);
     });
@@ -362,8 +805,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, {
@@ -372,10 +815,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' },
       ]);
     });
@@ -384,8 +827,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, {
@@ -394,11 +837,119 @@ 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' },
       ]);
     });
   });
+
+  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 3de56e90c..1f080d8ae 100644
--- a/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts
@@ -12,8 +12,20 @@ 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 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 */
+  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;
 }
 
 /**
@@ -30,8 +42,18 @@ export interface FrameRange {
     | 'padding-top'
     | 'highlighted'
     | 'highlighted-unfocused'
+    | 'focus'
+    | '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';
 }
 
 /**
@@ -46,6 +68,14 @@ 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;
+  /** 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 */
+  focusFramesMaxSize?: number;
 }
 
 /**
@@ -59,10 +89,13 @@ 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.
+   * @default 12
    */
   focusFramesMaxSize?: number;
   /**
@@ -74,6 +107,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.
  *
@@ -88,18 +124,92 @@ 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(channels: OverrideChannels, meta: EmphasisMeta | undefined): void {
+    if (meta?.paddingFrameMaxSize !== undefined) {
+      if (meta.focus) {
+        if (meta.propagatedOverride) {
+          channels.propagatedFocusPadding ??= meta.paddingFrameMaxSize;
+        } else {
+          channels.explicitFocusPadding ??= meta.paddingFrameMaxSize;
+        }
+      } else {
+        channels.nonFocusPadding ??= meta.paddingFrameMaxSize;
+      }
+    }
+    if (meta?.focusFramesMaxSize !== undefined) {
+      if (meta.focus) {
+        if (meta.propagatedOverride) {
+          channels.propagatedFocusMaxSize ??= meta.focusFramesMaxSize;
+        } else {
+          channels.explicitFocusMaxSize ??= meta.focusFramesMaxSize;
+        }
+      } else {
+        channels.nonFocusMaxSize ??= meta.focusFramesMaxSize;
+      }
+    }
+  }
+
+  function resolvePadding(channels: OverrideChannels): number | undefined {
+    return (
+      channels.explicitFocusPadding ?? channels.propagatedFocusPadding ?? channels.nonFocusPadding
+    );
+  }
+
+  function resolveMaxSize(channels: OverrideChannels): number | undefined {
+    return (
+      channels.explicitFocusMaxSize ?? channels.propagatedFocusMaxSize ?? channels.nonFocusMaxSize
+    );
+  }
+
   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;
+  let allLinesHighlighted = firstMeta?.lineHighlight ?? false;
+  let channels = emptyChannels();
+  accumulateOverrides(channels, firstMeta);
 
   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 {
+        allLinesHighlighted = false;
+      }
+      accumulateOverrides(channels, meta);
     } else {
       // Gap found, close current region and start a new one
       regions.push({
@@ -107,19 +217,32 @@ function groupHighlightRegions(emphasizedLines: Map<number, EmphasisMeta>): High
         endLine: regionEnd,
         index: regions.length,
         focused: hasFocus,
+        hasLineHighlight,
+        allLinesHighlighted,
+        paddingFrameMaxSize: resolvePadding(channels),
+        focusFramesMaxSize: resolveMaxSize(channels),
       });
       regionStart = line;
       regionEnd = line;
-      hasFocus = emphasizedLines.get(line)?.focus ?? false;
+      const meta = emphasizedLines.get(line);
+      hasFocus = meta?.focus ?? false;
+      hasLineHighlight = meta?.lineHighlight ?? false;
+      allLinesHighlighted = meta?.lineHighlight ?? false;
+      channels = emptyChannels();
+      accumulateOverrides(channels, meta);
     }
   }
 
   // Close the last region
   regions.push({
+    paddingFrameMaxSize: resolvePadding(channels),
     startLine: regionStart,
     endLine: regionEnd,
     index: regions.length,
     focused: hasFocus,
+    hasLineHighlight,
+    allLinesHighlighted,
+    focusFramesMaxSize: resolveMaxSize(channels),
   });
 
   return regions;
@@ -143,26 +266,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;
@@ -184,6 +310,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.
  *
@@ -196,13 +347,42 @@ function calculatePadding(
  * @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;
+
+  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 (
+    normalFrameMaxSize !== undefined &&
+    (!Number.isFinite(normalFrameMaxSize) || normalFrameMaxSize < 1)
+  ) {
+    throw new Error(`normalFrameMaxSize must be a finite number >= 1, got ${normalFrameMaxSize}`);
+  }
+
   if (totalLines <= 0) {
     return [];
   }
@@ -210,23 +390,56 @@ 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) {
+      const autoFrames: FrameRange[] = [
+        {
+          startLine: 1,
+          endLine: autoFocusMax,
+          type: 'focus',
+          regionIndex: 0,
+          truncated: 'visible',
+        },
+      ];
+      // 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 }];
   }
 
   const focusedIndex = determineFocusedRegionIndex(regions);
 
-  // Calculate padding for the focused region
+  // Calculate focus window split (for oversized regions)
   const focusedRegion = regions[focusedIndex];
+  const focusFramesMaxSize = focusedRegion.focusFramesMaxSize ?? effectiveFocusFramesMaxSize;
+  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;
@@ -252,12 +465,58 @@ export function calculateFrameRanges(
       frames.push({ startLine: currentLine, endLine: region.startLine - 1, type: 'normal' });
     }
 
-    // Highlighted frame (focused gets 'highlighted', others get 'highlighted-unfocused')
-    frames.push({
-      startLine: region.startLine,
-      endLine: region.endLine,
-      type: isFocused ? 'highlighted' : 'highlighted-unfocused',
-    });
+    if (isFocused && focusWindow) {
+      // Split oversized focused region into unfocused-top + focused-center + unfocused-bottom
+      const [focusStart, focusEnd] = focusWindow;
+      const isHighlightFrame =
+        region.hasLineHighlight && (!region.focused || region.allLinesHighlighted);
+      const unfocusedType: FrameRange['type'] = isHighlightFrame
+        ? 'highlighted-unfocused'
+        : 'focus-unfocused';
+      const focusedType: FrameRange['type'] = isHighlightFrame ? '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 {
+      // 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 || region.allLinesHighlighted)) {
+        frameType = isFocused ? 'highlighted' : 'highlighted-unfocused';
+      } else {
+        frameType = isFocused ? 'focus' : 'focus-unfocused';
+      }
+      frames.push({
+        startLine: region.startLine,
+        endLine: region.endLine,
+        type: frameType,
+        regionIndex: i,
+      });
+    }
 
     currentLine = region.endLine + 1;
 
@@ -277,5 +536,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;
 }
diff --git a/packages/docs-infra/src/pipeline/parseSource/createFrame.ts b/packages/docs-infra/src/pipeline/parseSource/createFrame.ts
index 15d6a4fa7..f17249f87 100644
--- a/packages/docs-infra/src/pipeline/parseSource/createFrame.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/createFrame.ts
@@ -11,6 +11,7 @@ export function createFrame(
   children: Array<ElementContent>,
   frameType?: FrameRange['type'],
   indentLevel?: number,
+  truncated?: FrameRange['truncated'],
 ): Element {
   const properties: Properties = {
     className: 'frame',
@@ -21,14 +22,21 @@ 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;
   }
 
+  if (truncated) {
+    properties.dataFrameTruncated = truncated;
+  }
+
   return {
     type: 'element',
     tagName: 'span',
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 37b4d135a..f3cd91cce 100644
--- a/packages/docs-infra/src/pipeline/parseSource/parseSource.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/parseSource.ts
@@ -38,9 +38,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: [
         {
@@ -49,6 +50,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);
diff --git a/packages/docs-infra/src/pipeline/parseSource/restructureFrames.test.ts b/packages/docs-infra/src/pipeline/parseSource/restructureFrames.test.ts
index cc5ecda90..c226aa593 100644
--- a/packages/docs-infra/src/pipeline/parseSource/restructureFrames.test.ts
+++ b/packages/docs-infra/src/pipeline/parseSource/restructureFrames.test.ts
@@ -144,7 +144,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' },
       ];
 
@@ -173,7 +173,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 65f4c5699..5f21ee1e9 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,20 +108,13 @@ 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;
-
-      newFrames.push(createFrame(children, range.type, indentLevel));
-    }
+      const indentLevel =
+        range.regionIndex !== undefined ? regionIndentLevels.get(range.regionIndex) : undefined;
 
-    // Increment region index after each highlighted frame (focused or unfocused)
-    if (range.type === 'highlighted' || range.type === 'highlighted-unfocused') {
-      highlightedRegionIndex += 1;
+      newFrames.push(createFrame(children, range.type, indentLevel, range.truncated));
     }
   }
 
-  // Step 4: Replace root children
+  // Step 3: Replace root children
   root.children = newFrames;
 }
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 23135f852..de5394e6a 100644
--- a/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts
+++ b/packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts
@@ -7,11 +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 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.
+   * 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.
@@ -243,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<{
@@ -331,8 +357,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],
                 },
               );
 
diff --git a/packages/docs-infra/src/useCode/Pre.tsx b/packages/docs-infra/src/useCode/Pre.tsx
index 0c59ebcf6..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}
@@ -201,6 +242,16 @@ export function Pre({
                 ? String(child.properties.dataFrameIndent)
                 : undefined
             }
+            data-frame-truncated={
+              child.properties.dataFrameTruncated
+                ? String(child.properties.dataFrameTruncated)
+                : undefined
+            }
+            data-frame-description={
+              child.properties.dataFrameDescription
+                ? String(child.properties.dataFrameDescription)
+                : undefined
+            }
             ref={observeFrame}
           >
             {renderCode(
@@ -220,9 +271,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>
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 05a5db43e..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,9 +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={getPreRenderKey(fileSlug, selectedTransform, enhancementPhase)}
           className={preClassName}
           language={language}
           ref={preRef}
@@ -504,7 +524,11 @@ export function useFileNavigation({
     preClassName,
     preRef,
     enhancedSource,
+    isEnhancing,
+    mainSlug,
     selectedFile,
+    selectedTransform,
+    selectedVariantKey,
     sourceEnhancers,
     selectedFileNameInternal,
   ]);
@@ -563,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>
         ),
@@ -580,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}
@@ -614,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}
@@ -631,6 +671,7 @@ export function useFileNavigation({
     selectedVariant,
     transformedFiles,
     mainSlug,
+    selectedTransform,
     selectedVariantKey,
     shouldHighlight,
     preClassName,
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 846a42c15..56d854e26 100644
--- a/packages/docs-infra/src/withDocsInfra/withDocsInfra.ts
+++ b/packages/docs-infra/src/withDocsInfra/withDocsInfra.ts
@@ -2,6 +2,8 @@ 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';
+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
@@ -84,6 +86,16 @@ export interface WithDocsInfraOptions {
    * @example ['@highlight', '@focus']
    */
   notableCommentsPrefix?: string[];
+  /**
+   * Options for the code emphasis enhancer used by demo loaders.
+   * Passed to `createEnhanceCodeEmphasis` in the precomputed code highlighter loader.
+   */
+  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
@@ -171,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;
 }
 
 /**
@@ -184,6 +201,7 @@ export function getDocsInfraMdxOptions(
     baseDir,
     errorIfIndexOutOfDate = Boolean(process.env.CI),
     defaultInlineCodeLanguage,
+    codeBlockEmphasisOptions,
   } = customOptions;
 
   // Normalize extractToIndex to options object
@@ -230,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'],
@@ -277,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 = {
@@ -305,6 +327,9 @@ export function withDocsInfra(options: WithDocsInfraOptions = {}) {
       output,
       ...(removeCommentsWithPrefix && { removeCommentsWithPrefix }),
       ...(notableCommentsPrefix && { notableCommentsPrefix }),
+      ...(demoEmphasisOptions && {
+        emphasisOptions: demoEmphasisOptions as unknown as JSONValue,
+      }),
     };
 
     const turbopackRules: Exclude<NextConfig['turbopack'], undefined>['rules'] = {
@@ -332,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 }
@@ -454,6 +482,7 @@ export function withDocsInfra(options: WithDocsInfraOptions = {}) {
                 performance,
                 socketDir: '.next/docs-infra',
                 updateParentIndex,
+                ...(codeBlockEmphasisOptions ? { codeBlockEmphasisOptions } : {}),
                 ...(ordering ? { ordering } : {}),
                 ...(descriptionReplacements ? { descriptionReplacements } : {}),
               },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8ba9c0a2c..07006cf15 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
@@ -910,6 +913,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@6.0.2)
       estree-util-to-js:
         specifier: 2.0.0
         version: 2.0.0