feat(docs): ExampleCode include + guards; retire the walkthrough renderer

CONTRIBUTING.md

@@ -219,6 +219,38 @@ own Protection Bypass for Automation secret:
 flight does not reach that run; re-run after provisioning. Never pass
 `--skip-domain` to a preview deploy; Vercel requires it to accompany `--prod`.
 
+## Docs pages and example code
+
+A docs page whose capability ships a runnable example (the page shows Run and
+Code tabs) teaches through that example. Its code comes from the example
+files, never from a hand-typed copy:
+
+```mdx
+<ExampleCode file="streaming.component.ts" />
+<ExampleCode file="graph.py" region="stream-modes" title="Stream modes" />
+```
+
+- `file` is a basename or a repo-relative path among the capability's
+  `codeAssetPaths` and `backendAssetPaths` in
+  `libs/cockpit-registry/src/lib/content-descriptors.ts`. An unknown or
+  ambiguous name fails the build.
+- `region` names a marker pair in that file. Markers are `// #region name` …
+  `// #endregion` in TypeScript, `# region name` … `# endregion` in Python,
+  and `<!-- #region name -->` … `<!-- #endregion -->` in HTML. Regions may
+  nest. The marker lines are stripped from the slice on the docs page and
+  the slice is de-indented. The Code tab shows the whole file, markers
+  included, and the region name surfaces in the build error when a region is
+  missing or unterminated, so keep the names meaningful.
+- Hand-written fences stay allowed for fragments the example does not cover,
+  such as another runtime's variant.
+
+`apps/website/src/lib/docs-example-code.spec.ts` fails when a mapped page
+includes nothing, when an include does not resolve, or when a docs-only page
+uses the tag. Its scan is textual, so the tag must not appear in prose,
+fenced code, or MDX comments on any docs page. Pages not yet rewritten sit in
+its `PENDING_PAGES` list; a page that gains its first include must leave the
+list in the same change.
+
 ## Code review
 
 Every PR gets a genuine advisory AI code review

apps/website/content/docs/langgraph/guides/streaming.mdx

@@ -98,6 +98,12 @@ export class ChatComponent {
 </Tab>
 </Tabs>
 
+### The running example
+
+The demo in the Run tab is the smallest real integration of this pattern. The snippet above sketches the pieces by hand; the real component uses the prebuilt `<chat>` composition instead. It injects the agent configured in `app.config.ts` and hands it to `<chat>`, which owns message rendering, input, and the typing indicator.
+
+<ExampleCode file="streaming.component.ts" />
+
 ## Stream status
 
 The `status()` signal reports the current lifecycle state of the SSE connection:

apps/website/src/app/blog/[slug]/page.tsx

@@ -110,7 +110,7 @@ export default async function BlogPostPage({ params }: Params) {
             <TagChips tags={post.frontmatter.tags} />
           ) : null}
         </header>
-        <MdxRenderer source={post.content} />
+        <MdxRenderer source={post.content} docsPath={`/blog/${slug}`} />
       </article>
         <DocsTOC headings={headings} />
       </div>

apps/website/src/app/docs/[library]/[section]/[slug]/page.spec.tsx

@@ -13,8 +13,17 @@ interface ElementProps {
   docsSlot?: ReactNode;
   requestedMode?: string | null;
   resolution?: { kind?: string; identity?: { availableModes?: string[] } };
-  contentBundle?: { runtimeUrl?: string | null };
+  contentBundle?: {
+    runtimeUrl?: string | null;
+    codeSources?: Record<string, string>;
+  };
   contextTrail?: readonly { label: string; href?: string; icon?: ReactNode }[];
+  docsContext?: unknown;
+  docsPath?: string;
+  exampleCode?: {
+    assetPaths?: readonly string[];
+    sources?: Record<string, string>;
+  } | null;
 }
 
 function findElement(
@@ -63,6 +72,20 @@ describe('unified docs workspace route', () => {
       activeSection: 'guides',
       activeSlug: 'streaming',
     });
+
+    const mdx = findElement(
+      workspace?.props.docsSlot,
+      MdxRenderer as ComponentType<never>
+    );
+    expect(mdx?.props.exampleCode?.assetPaths).toContain(
+      'cockpit/langgraph/streaming/angular/src/app/streaming.component.ts'
+    );
+    // The server-rendered <ExampleCode> keeps the raw sources; the client
+    // boundary must not carry a second copy of them into the RSC payload.
+    expect(Object.keys(mdx?.props.exampleCode?.sources ?? {})).toContain(
+      'cockpit/langgraph/streaming/angular/src/app/streaming.component.ts'
+    );
+    expect(workspace?.props.contentBundle?.codeSources).toEqual({});
   });
 
   it('keeps an unmapped page as a complete server Docs slot', async () => {
@@ -78,6 +101,12 @@ describe('unified docs workspace route', () => {
       findElement(slot, DocsPageHeader as ComponentType<never>)
     ).toBeTruthy();
     expect(findElement(slot, MdxRenderer as ComponentType<never>)).toBeTruthy();
+    expect(
+      findElement(slot, MdxRenderer as ComponentType<never>)?.props.exampleCode
+    ).toBeNull();
+    expect(
+      findElement(slot, MdxRenderer as ComponentType<never>)?.props.docsPath
+    ).toBe('/docs/langgraph/guides/testing');
     expect(findElement(slot, DocsTOC as ComponentType<never>)).toBeTruthy();
   });
 

apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx

@@ -34,7 +34,10 @@ import {
   type LibraryId,
 } from '../../../../../lib/docs-config';
 import { WebsiteWorkspace } from '../../../../../components/workspace/WebsiteWorkspace';
-import { getWebsiteWorkspacePage } from '../../../../../lib/workspace-page';
+import {
+  getExampleCodeContext,
+  getWebsiteWorkspacePage,
+} from '../../../../../lib/workspace-page';
 import fs from 'fs';
 import path from 'path';
 
@@ -168,7 +171,11 @@ export default async function DocsPage({ params }: DocsRouteProps) {
             />
           </div>
           <article className="flex-1 py-8 px-4 sm:px-6 md:px-12 md:max-w-3xl">
-            <MdxRenderer source={doc.body} />
+            <MdxRenderer
+              source={doc.body}
+              exampleCode={getExampleCodeContext(workspacePage)}
+              docsPath={pathname}
+            />
           </article>
           {section === 'api' &&
             (() => {
@@ -226,7 +233,11 @@ export default async function DocsPage({ params }: DocsRouteProps) {
       <WebsiteWorkspace
         resolution={workspacePage.resolution}
         presentation={workspacePage.presentation}
-        contentBundle={workspacePage.contentBundle}
+        // Raw sources exist only for the server-rendered `<ExampleCode>` above
+        // (docsSlot already captured them); the workspace shell renders the
+        // highlighted `codeFiles`, so shipping them again would only add dead
+        // weight to this client boundary's RSC payload.
+        contentBundle={{ ...workspacePage.contentBundle, codeSources: {} }}
         navigationTree={workspacePage.navigationTree}
         routePath={pathname}
         docsSlot={docsSlot}

apps/website/src/app/docs/choosing-an-adapter/page.tsx

@@ -52,7 +52,7 @@ export default function ChoosingAnAdapterPage() {
             aria-label={PAGE_TITLE}
             className="flex-1 py-8 px-4 sm:px-6 md:px-12 md:max-w-3xl"
           >
-            <MdxRenderer source={source} />
+            <MdxRenderer source={source} docsPath="/docs/choosing-an-adapter" />
           </article>
         </div>
         {/* This page carries as many headings as any library page, so it gets

apps/website/src/components/docs/MdxRenderer.spec.tsx

@@ -0,0 +1,65 @@
+import { isValidElement, type ReactElement, type ReactNode } from 'react';
+import { describe, expect, it } from 'vitest';
+import { MDXRemote } from 'next-mdx-remote/rsc';
+import { MdxRenderer } from './MdxRenderer';
+
+function findMdx(
+  node: ReactNode
+): ReactElement<{ components: Record<string, unknown> }> | null {
+  if (
+    !isValidElement<{
+      components: Record<string, unknown>;
+      children?: ReactNode;
+    }>(node)
+  )
+    return null;
+  if (node.type === MDXRemote) return node;
+  return findMdx(node.props.children);
+}
+
+describe('MdxRenderer', () => {
+  it('always registers ExampleCode, bound to the page context', () => {
+    const withContext = findMdx(
+      MdxRenderer({
+        source: '# x',
+        exampleCode: {
+          docsPath: '/docs/p',
+          assetPaths: ['a/b.ts'],
+          sources: { 'a/b.ts': '' },
+        },
+      })
+    );
+    const without = findMdx(
+      MdxRenderer({ source: '# x', docsPath: '/docs/only' })
+    );
+
+    expect(typeof withContext?.props.components['ExampleCode']).toBe(
+      'function'
+    );
+    // Not just "a function": an unresolvable file must fail against THIS
+    // page's context, which a hard-coded createExampleCode(null) could not do.
+    expect(() =>
+      (
+        withContext?.props.components['ExampleCode'] as (p: {
+          file: string;
+        }) => unknown
+      )({ file: 'nope.ts' })
+    ).toThrow(/\/docs\/p/);
+
+    expect(typeof without?.props.components['ExampleCode']).toBe('function');
+    expect(() =>
+      (
+        without?.props.components['ExampleCode'] as (p: {
+          file: string;
+        }) => unknown
+      )({ file: 'b.ts' })
+    ).toThrow(/mapped example/);
+    expect(() =>
+      (
+        without?.props.components['ExampleCode'] as (p: {
+          file: string;
+        }) => unknown
+      )({ file: 'b.ts' })
+    ).toThrow(/\/docs\/only/);
+  });
+});

apps/website/src/components/docs/MdxRenderer.tsx

@@ -18,9 +18,9 @@ import {
   MiddlewareHowItFits,
   TelemetryHowItFits,
 } from './diagrams';
-import rehypePrettyCode from 'rehype-pretty-code';
-import rehypeSlug from 'rehype-slug';
-import remarkGfm from 'remark-gfm';
+import { mdxCompileOptions } from './mdx-options';
+import { createExampleCode } from './mdx/ExampleCode';
+import type { ExampleCodeContext } from '../../lib/example-code';
 
 /**
  * Intrinsic size of each SVG diagram in `public/blog/diagrams`.
@@ -87,28 +87,28 @@ const mdxComponents = {
   ...mdxHeadingComponents,
 };
 
-const rehypeOptions = {
-  theme: 'tokyo-night',
-  keepBackground: true,
-};
-
 interface MdxRendererProps {
   source: string;
+  /** Present on docs pages that embed a runnable example; null elsewhere. */
+  exampleCode?: ExampleCodeContext | null;
+  /** Route of the page being rendered, so a docs-only failure can name it. */
+  docsPath?: string;
 }
 
-export function MdxRenderer({ source }: MdxRendererProps) {
+export function MdxRenderer({
+  source,
+  exampleCode = null,
+  docsPath,
+}: MdxRendererProps) {
   return (
     <div className="docs-prose">
       <MDXRemote
         source={source}
-        components={mdxComponents}
-        options={{
-          mdxOptions: {
-            remarkPlugins: [remarkGfm],
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        rehypePlugins: [rehypeSlug, [rehypePrettyCode, rehypeOptions] as any],
-          },
+        components={{
+          ...mdxComponents,
+          ExampleCode: createExampleCode(exampleCode, docsPath),
         }}
+        options={mdxCompileOptions}
       />
     </div>
   );

apps/website/src/components/docs/mdx-options.ts

@@ -0,0 +1,21 @@
+import rehypePrettyCode from 'rehype-pretty-code';
+import rehypeSlug from 'rehype-slug';
+import remarkGfm from 'remark-gfm';
+
+const rehypeOptions = {
+  theme: 'tokyo-night',
+  keepBackground: true,
+};
+
+/**
+ * The one MDX compile configuration. `MdxRenderer` uses it for whole pages and
+ * `ExampleCode` for the fence it synthesizes, so included code is highlighted
+ * and styled exactly like a hand-written block.
+ */
+export const mdxCompileOptions = {
+  mdxOptions: {
+    remarkPlugins: [remarkGfm],
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    rehypePlugins: [rehypeSlug, [rehypePrettyCode, rehypeOptions] as any],
+  },
+};