[docs-infra] Demo Screenshots as OpenGraph Images

AGENTS.md

@@ -136,6 +136,14 @@ test/
 
 All commands are fast in this repository, but network issues or system load can cause delays. Always wait for completion.
 
+<!-- BEGIN:nextjs-agent-rules -->
+
+## This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+
+<!-- END:nextjs-agent-rules -->
+
 ## Docs Infra Conventions
 
 Follow additional instructions when working in the `@mui/internal-docs-infra` (`packages/docs-infra`) package or `docs/app/docs-infra` docs:

docs/.gitignore

@@ -39,3 +39,11 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+# Playwright
+node_modules/
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+/playwright/.auth/

docs/app/docs-infra/components/code-highlighter/demos/DemoContent.module.css

@@ -4,10 +4,14 @@
 }
 
 .demoSection {
-  padding: 24px;
+  padding: 4px;
   border-radius: 7px 7px 0 0;
 }
 
+.demoSection :global(.demo) {
+  padding: 20px;
+}
+
 .codeSection {
   border-top: 1px solid #d0cdd7;
 }

docs/app/docs-infra/components/code-highlighter/demos/DemoContent.tsx

@@ -45,7 +45,9 @@ export function DemoContent(props: ContentProps<object>) {
         <span key={slug} id={slug} className={styles.fileRefs} />
       ))}
       <div className={styles.container}>
-        <div className={styles.demoSection}>{demo.component}</div>
+        <div className={styles.demoSection}>
+          <div className="demo">{demo.component}</div>
+        </div>
         <div className={styles.codeSection}>
           <div className={styles.header}>
             <div className={styles.headerContainer}>

docs/app/docs-infra/components/code-highlighter/demos/demo-variants/page.tsx

@@ -0,0 +1,6 @@
+import * as React from 'react';
+import { DemoCodeHighlighterDemoVariants } from '.';
+
+export default function Page() {
+  return <DemoCodeHighlighterDemoVariants />;
+}

docs/app/docs-infra/components/code-highlighter/demos/demo-variants/test.ts

@@ -0,0 +1,20 @@
+import path from 'node:path';
+import { test } from '@playwright/test';
+
+const route = path
+  .dirname(import.meta.filename)
+  .split('/app')
+  .pop()!;
+
+test('code highlighter with multiple variants', async ({ page }) => {
+  await page.goto(route);
+  await page.waitForLoadState('networkidle');
+
+  await page.getByRole('combobox').click();
+
+  await page
+    .locator('.demo')
+    .first()
+    /* file://./../../../../../../public/docs-infra/components/code-highlighter/demos/demo-variants.png */
+    .screenshot({ path: `public/${route}.png` });
+});

docs/app/docs-infra/components/code-highlighter/page.mdx

@@ -469,3 +469,17 @@ These types are available by importing from `@mui/internal-docs-infra/CodeHighli
 [See Types](./types.md#CodeHighlighterTypes)
 
 <TypesCodeHighlighterAdditional />
+
+export const metadata =
+  /** @type {import('@mui/internal-docs-infra/createSitemap/types').NextMetadata} */ ({
+    keywords: [],
+    openGraph: {
+      images: [
+        {
+          /* file://./../../../../public/docs-infra/components/code-highlighter/demos/demo-variants.png */
+          url: '/docs-infra/components/code-highlighter/demos/demo-variants.png',
+          alt: 'Highlighted Code with Variants',
+        },
+      ],
+    },
+  });

docs/app/docs-infra/components/page.mdx

@@ -16,6 +16,8 @@
 The `CodeHighlighter` component provides a powerful and flexible way to display interactive code examples with syntax highlighting, multiple variants, and live previews.
 It supports both static code blocks and interactive demos with component previews.
 
+![Highlighted Code with Variants](../../../public/docs-infra/components/code-highlighter/demos/demo-variants.png)
+
 <details>
 
 <summary>Outline</summary>

docs/components/PagesIndex/PagesIndex.module.css

@@ -1,20 +1,25 @@
 .pages {
-  display: flex;
-  flex-direction: row;
-  flex-wrap: wrap;
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
   gap: 12px;
 }
 
+@media (max-width: 768px) {
+  .pages {
+    grid-template-columns: 1fr;
+  }
+}
+
 .page {
   display: flex;
   flex-direction: column;
   border: 1px solid #d0cdd7;
-  max-width: 222px;
   padding: 16px;
   border-radius: 12px;
   background-color: transparent;
   transition: all 0.2s ease;
   text-decoration: none;
+  overflow: hidden;
 }
 
 .page:hover {
@@ -26,6 +31,14 @@
   background-color: #20003820;
 }
 
+.pageImage {
+  width: 100%;
+  height: auto;
+  border-radius: 6px;
+  margin-bottom: 12px;
+  object-fit: cover;
+}
+
 .pageTitle {
   font-weight: bold;
   display: flex;

docs/components/PagesIndex/PagesIndex.tsx

@@ -1,5 +1,6 @@
 import type { SitemapSectionData } from '@mui/internal-docs-infra/createSitemap/types';
 import * as React from 'react';
+import Image from 'next/image';
 import Link from 'next/link';
 import styles from './PagesIndex.module.css';
 
@@ -13,6 +14,15 @@ export function PagesIndex({ data }: { data?: SitemapSectionData }) {
             href={`${data.prefix}${page.path.replace(/^\.\//, '').replace(/\/page\.mdx$/, '')}`}
             className={styles.page}
           >
+            {page.image && (
+              <Image
+                src={page.image.url}
+                alt={page.image.alt ?? page.title ?? ''}
+                width={190}
+                height={107}
+                className={styles.pageImage}
+              />
+            )}
             <div className={styles.pageTitle}>
               <span>{page.title}</span>
 

docs/next.config.mjs

@@ -41,6 +41,7 @@ const nextConfig = {
   devIndicators: {
     position: 'bottom-right',
   },
+  images: { unoptimized: true },
   experimental: {
     turbopackFileSystemCacheForBuild: true,
   },

docs/package.json

@@ -1,5 +1,6 @@
 {
   "name": "docs",
+  "type": "module",
   "private": true,
   "scripts": {
     "dev": "next dev",
@@ -8,17 +9,20 @@
     "link-check": "tsx ./scripts/reportBrokenLinks.mts",
     "start": "serve ./export",
     "docs-infra": "docs-infra",
-    "validate": "docs-infra validate --command 'pnpm validate'"
+    "validate": "docs-infra validate --command 'pnpm validate'",
+    "screenshot": "docs-infra browser --script screenshot:unconfined --playwright-version 1.59.1 --",
+    "screenshot:unconfined": "playwright test",
+    "screenshot:codegen": "playwright codegen"
   },
   "dependencies": {
     "@base-ui/react": "1.3.0",
     "@mdx-js/loader": "^3.1.1",
     "@mdx-js/react": "^3.1.1",
     "@mui/internal-docs-infra": "workspace:^",
-    "@next/mdx": "^16.1.6",
+    "@next/mdx": "^16.2.1",
     "@types/mdx": "^2.0.13",
     "lucide-react": "^0.577.0",
-    "next": "^16.1.6",
+    "next": "^16.2.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-runner": "^1.0.5",
@@ -30,7 +34,8 @@
     "web-vitals": "^5.1.0"
   },
   "devDependencies": {
-    "@next/bundle-analyzer": "16.1.6",
+    "@next/bundle-analyzer": "16.2.1",
+    "@playwright/test": "1.59.1",
     "@types/node": "22.19.0",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",

docs/playwright.config.ts

@@ -0,0 +1,23 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './app',
+  testMatch: '**/test.ts',
+  forbidOnly: !!process.env.CI,
+  reporter: 'html',
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+    viewport: { width: 2560, height: 1440 },
+    deviceScaleFactor: 3,
+    connectOptions: process.env.PLAYWRIGHT_SERVER
+      ? { wsEndpoint: process.env.PLAYWRIGHT_SERVER }
+      : undefined,
+  },
+  webServer: {
+    command: 'pnpm build && pnpm start',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    stdout: 'pipe',
+  },
+});

package.json

@@ -25,6 +25,7 @@
     "docs:start": "pnpm -F \"./docs\" run start",
     "docs:infra": "pnpm -F \"./docs\" run docs-infra",
     "docs:validate": "pnpm -F \"./docs\" run docs-infra validate --command 'pnpm docs:validate'",
+    "docs:screenshot": "pnpm -F \"./docs\" run screenshot",
     "docs:lint": "pnpm -F \"./docs\" run lint",
     "docs:lib": "pnpm -F \"./packages/docs-infra\" run build",
     "test:benchmark": "pnpm -F ./test/performance benchmark"

packages/docs-infra/src/pipeline/parseSource/addLineGutters.test.ts

@@ -229,6 +229,33 @@ describe('starryNightGutter', () => {
     ]);
   });
 
+  it('preserves frame boundary newlines in dataAsString for non-final frames', () => {
+    const tree: Root = {
+      type: 'root',
+      children: [
+        {
+          type: 'text',
+          value: 'line1\nline2\nline3',
+        },
+      ],
+    };
+
+    starryNightGutter(tree, ['line1', 'line2', 'line3'], 2);
+
+    expect(tree.children).toHaveLength(2);
+
+    const firstFrame = tree.children[0];
+    const secondFrame = tree.children[1];
+
+    expect(firstFrame.type).toBe('element');
+    expect(secondFrame.type).toBe('element');
+
+    if (firstFrame.type === 'element' && secondFrame.type === 'element') {
+      expect(firstFrame.properties?.dataAsString).toBe('line1\nline2\n');
+      expect(secondFrame.properties?.dataAsString).toBe('line3');
+    }
+  });
+
   it('should handle multiple consecutive empty lines', () => {
     const tree: Root = {
       type: 'root',

packages/docs-infra/src/pipeline/parseSource/addLineGutters.ts

@@ -155,7 +155,9 @@ export function starryNightGutter(
         if (lineChildren.length > 0) {
           const startLine = Number(lineChildren[0].properties.dataLn) - 1;
           const endLine = Number(lineChildren[lineChildren.length - 1].properties.dataLn);
-          frame.properties.dataAsString = sourceLines.slice(startLine, endLine).join('\n');
+          const hasFollowingLine = endLine < sourceLines.length;
+          frame.properties.dataAsString =
+            sourceLines.slice(startLine, endLine).join('\n') + (hasFollowingLine ? '\n' : '');
         }
       }
     }