fix(theme/CodeBlockRuntime): Render SSR fallback for CodeBlockRuntime to avoid first-paint empty DOM/CLS

e2e/fixtures/code-block-runtime/index.test.ts

@@ -1,5 +1,11 @@
 import { expect, test } from '@playwright/test';
-import { getPort, killProcess, runDevCommand } from '../../utils/runCommands';
+import {
+  getPort,
+  killProcess,
+  runBuildCommand,
+  runDevCommand,
+  runPreviewCommand,
+} from '../../utils/runCommands';
 
 test.describe('<CodeBlockRuntime />', async () => {
   let appPort: number;
@@ -62,3 +68,41 @@ test.describe('<CodeBlockRuntime />', async () => {
     }
   });
 });
+
+test.describe('<CodeBlockRuntime /> SSG', async () => {
+  let appPort: number;
+  let app: Awaited<ReturnType<typeof runPreviewCommand>>;
+  test.beforeAll(async () => {
+    const appDir = __dirname;
+    appPort = await getPort();
+    await runBuildCommand(appDir);
+    app = await runPreviewCommand(appDir, appPort);
+  });
+
+  test.afterAll(async () => {
+    if (app) {
+      await killProcess(app);
+    }
+  });
+
+  test('should render code from static HTML when JavaScript is disabled', async ({
+    browser,
+  }) => {
+    const context = await browser.newContext({ javaScriptEnabled: false });
+    const page = await context.newPage();
+    try {
+      await page.goto(`http://localhost:${appPort}`, {
+        waitUntil: 'domcontentloaded',
+      });
+
+      const containers = page.locator('div.language-js');
+      await expect(containers).toHaveCount(2);
+      const codeElement = containers
+        .locator('.rp-codeblock__content pre code')
+        .first();
+      await expect(codeElement).toHaveText("console.log('Hello CodeBlock!');");
+    } finally {
+      await context.close();
+    }
+  });
+});

packages/core/src/theme/components/CodeBlock/index.scss

@@ -1,6 +1,6 @@
 .rp-codeblock {
   position: relative;
-  margin: 16px 0;
+  margin: 1rem 0;
   border: var(--rp-code-block-border);
   box-shadow: var(--rp-code-block-shadow);
 
@@ -9,14 +9,14 @@
   border-radius: var(--rp-radius);
 
   @media (max-width: 640px) {
-    margin: 24px 0;
+    margin: 1.5rem 0;
     contain: content;
   }
 }
 
 .rp-codeblock__title {
   font-family: var(--rp-font-family-mono);
-  padding: 12px 16px;
+  padding: 0.75rem 1rem;
   font-size: var(--rp-code-font-size);
   background-color: var(--rp-code-title-bg);
   border-bottom: var(--rp-code-block-border);
@@ -59,7 +59,7 @@
     font-size: var(--rp-code-font-size);
     font-family: var(--rp-font-family-mono);
     display: inline-block;
-    padding: 16px 0;
+    padding: 1rem 0;
     width: fit-content;
     min-width: 100%;
     line-height: 1.7;
@@ -76,8 +76,8 @@
     & .line::before {
       content: counter(step);
       counter-increment: step;
-      width: 15px;
-      margin-right: 15px;
+      width: 1rem;
+      margin-right: 1rem;
       display: inline-block;
       text-align: right;
       color: rgba(115, 138, 148, 0.4);

packages/core/src/theme/components/CodeBlockRuntime/index.tsx

@@ -1,7 +1,14 @@
 import type { CodeBlockProps } from '@theme';
 import { getCustomMDXComponent } from '@theme';
 import { toJsxRuntime } from 'hast-util-to-jsx-runtime';
-import { Fragment, type ReactNode, useEffect, useRef, useState } from 'react';
+import {
+  Fragment,
+  type ReactNode,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import {
   type BundledLanguage,
@@ -47,9 +54,39 @@ export function CodeBlockRuntime({
   children: _,
   containerElementClassName,
   onRendered,
-  ...otherProps
+  wrapCode,
+  lineNumbers,
 }: CodeBlockRuntimeProps) {
-  const [child, setChild] = useState<ReactNode | null>(null);
+  // getCustomMDXComponent is stable for theme rendering
+  const mdxComponents = useMemo(() => getCustomMDXComponent(), []);
+  const { pre: ShikiPre, code: Code, ...otherMdxComponents } = mdxComponents;
+  const fallback = useMemo(
+    () => (
+      <ShikiPre
+        title={title}
+        lang={lang}
+        wrapCode={wrapCode}
+        lineNumbers={lineNumbers}
+        containerElementClassName={containerElementClassName}
+        codeButtonGroupProps={codeButtonGroupProps}
+        className="shiki css-variables"
+      >
+        <Code style={{ padding: '1rem 1.25rem' }}>{code}</Code>
+      </ShikiPre>
+    ),
+    [
+      ShikiPre,
+      Code,
+      title,
+      lang,
+      wrapCode,
+      lineNumbers,
+      containerElementClassName,
+      codeButtonGroupProps,
+      code,
+    ],
+  );
+  const [child, setChild] = useState<ReactNode | null>(fallback);
   const codeRef = useLatest(code);
 
   useEffect(() => {
@@ -66,12 +103,6 @@ export function CodeBlockRuntime({
         return;
       }
 
-      const {
-        pre: ShikiPre,
-        code: Code,
-        ...otherMdxComponents
-      } = getCustomMDXComponent();
-
       const reactNode = toJsxRuntime(hast, {
         jsx,
         jsxs,
@@ -84,8 +115,9 @@ export function CodeBlockRuntime({
               lang={lang}
               containerElementClassName={containerElementClassName}
               codeButtonGroupProps={codeButtonGroupProps}
+              wrapCode={wrapCode}
+              lineNumbers={lineNumbers}
               {...props}
-              {...otherProps}
             />
           ),
           code: props => <Code {...props} />,
@@ -96,7 +128,17 @@ export function CodeBlockRuntime({
       setChild(reactNode);
     };
     void highlightCode();
-  }, [lang, code, shikiOptions]);
+  }, [
+    code,
+    codeButtonGroupProps,
+    containerElementClassName,
+    fallback,
+    lang,
+    lineNumbers,
+    shikiOptions,
+    title,
+    wrapCode,
+  ]);
 
   useEffect(() => {
     if (child) {

scripts/dictionary.txt

@@ -37,6 +37,7 @@ deepmerge
 directorytest
 docgen
 docsite
+domcontentloaded
 envinfo
 estree
 facti