jamdesk 1.1.129 → 1.1.130

package/dist/lib/validate-snippets.js

@@ -0,0 +1,71 @@
+/**
+ * Snippet Validation (CLI)
+ *
+ * Scans MDX pages for snippet-related author issues that would surface as
+ * build warnings on the cloud: (1) `<Snippet>` tag usage, which Jamdesk does
+ * not support; (2) `import … from '/snippets/…'` that references a file that
+ * doesn't exist in the project's snippets/ directory.
+ *
+ * Reuses the pure scanner from snippet-scanner.ts (synced from build-service)
+ * so the matching logic is byte-identical to the cloud build — no drift.
+ *
+ * Scans EVERY project MDX file (not just navigation pages), mirroring the
+ * cloud build's per-file scan in build.ts — an orphan page with a `<Snippet>`
+ * tag warns at build time, so the CLI must surface it too.
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { findSnippetIssues, normalizeSnippetRef } from './snippet-scanner.js';
+/**
+ * Walk the project's snippet files and return the extensionless key set used
+ * by `findSnippetIssues` for membership lookups.
+ */
+async function collectSnippetKeys(projectDir) {
+    const snippetsDir = path.join(projectDir, 'snippets');
+    if (!(await fs.pathExists(snippetsDir))) {
+        return new Set();
+    }
+    const { glob } = await import('glob');
+    const files = await glob('**/*.{mdx,tsx,jsx}', {
+        cwd: snippetsDir,
+        ignore: ['node_modules/**'],
+    });
+    return new Set(files.map(normalizeSnippetRef));
+}
+const SNIPPET_WARNING_CAP = 50;
+/**
+ * Validate snippet usage across the project's MDX files.
+ *
+ * @param projectDir - Absolute path to the docs project root.
+ * @param mdxFiles   - MDX/MD file paths to scan. Each may be absolute or
+ *                     relative to projectDir. Callers should pass the SAME
+ *                     full project walk used for image-ref validation so the
+ *                     CLI surfaces the same issues as the cloud build
+ *                     (orphan pages included, not just navigation pages).
+ * @returns Array of SnippetWarning (empty when clean). Never throws.
+ */
+export async function validateSnippets(projectDir, mdxFiles) {
+    const snippetKeys = await collectSnippetKeys(projectDir);
+    const warnings = [];
+    for (const file of mdxFiles) {
+        if (warnings.length >= SNIPPET_WARNING_CAP)
+            break;
+        const abs = path.isAbsolute(file) ? file : path.join(projectDir, file);
+        let content;
+        try {
+            content = await fs.readFile(abs, 'utf-8');
+        }
+        catch {
+            continue; // missing file is its own check elsewhere
+        }
+        const relFile = path.relative(projectDir, abs);
+        const issues = findSnippetIssues(content, relFile, snippetKeys);
+        for (const issue of issues) {
+            if (warnings.length >= SNIPPET_WARNING_CAP)
+                break;
+            warnings.push({ file: relFile, variant: issue.variant, message: issue.message });
+        }
+    }
+    return warnings;
+}
+//# sourceMappingURL=validate-snippets.js.map

package/dist/lib/validate-snippets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-snippets.js","sourceRoot":"","sources":["../../src/lib/validate-snippets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAqB,MAAM,sBAAsB,CAAC;AAWjG;;;GAGG;AACH,KAAK,UAAU,kBAAkB,CAAC,UAAkB;IAClD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IACtD,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;QACxC,OAAO,IAAI,GAAG,EAAE,CAAC;IACnB,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,oBAAoB,EAAE;QAC7C,GAAG,EAAE,WAAW;QAChB,MAAM,EAAE,CAAC,iBAAiB,CAAC;KAC5B,CAAC,CAAC;IACH,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,UAAkB,EAClB,QAAkB;IAElB,MAAM,WAAW,GAAG,MAAM,kBAAkB,CAAC,UAAU,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAqB,EAAE,CAAC;IAEtC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,QAAQ,CAAC,MAAM,IAAI,mBAAmB;YAAE,MAAM;QAElD,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACvE,IAAI,OAAe,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,0CAA0C;QACtD,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;QAChE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,QAAQ,CAAC,MAAM,IAAI,mBAAmB;gBAAE,MAAM;YAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.129",
+  "version": "1.1.130",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",
@@ -108,6 +108,7 @@
     "chalk": "^5.3.0",
     "commander": "^14.0.3",
     "dictionary-en": "^4.0.0",
+    "estree-util-visit": "^2.0.0",
     "fastest-levenshtein": "^1.0.16",
     "fs-extra": "^11.2.0",
     "github-slugger": "^2.0.0",
@@ -118,7 +119,11 @@
     "nspell": "^2.1.5",
     "open": "^11.0.0",
     "ora": "^9.4.0",
-    "tar": "^7.5.15"
+    "remark-mdx": "^3.1.1",
+    "remark-parse": "^11.0.0",
+    "tar": "^7.5.15",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
     "@mdx-js/mdx": "^3.1.1",

package/vendored/components/errors/MdxRenderBoundary.tsx

@@ -0,0 +1,52 @@
+'use client';
+
+/**
+ * MdxRenderBoundary — request-time error boundary around `<MDXRemote>`.
+ *
+ * User MDX is compiled and rendered at request time. A render-time throw —
+ * an undefined component ("Expected component `Snippet` to be defined") or a
+ * bare `{x, y}` expression (ReferenceError) — currently returns HTTP 500 with
+ * no boundary. These errors throw at RENDER (not compile), so only a render
+ * boundary can catch them. The compiled fallback is therefore the last line of
+ * defense for "docs never 500".
+ *
+ * Hand-rolled class component (React error boundaries require a class; there is
+ * no Hooks equivalent). NO new dependency — `react-error-boundary` is
+ * deliberately not used.
+ *
+ * `fallback` is a server-rendered element constructed by the server parent
+ * (e.g. `<MdxErrorBlock/>`, a server component) and passed in as a prop, so the
+ * client boundary never needs to import a server component.
+ */
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+
+interface MdxRenderBoundaryProps {
+  children: ReactNode;
+  fallback: ReactNode;
+}
+
+interface MdxRenderBoundaryState {
+  hasError: boolean;
+}
+
+export class MdxRenderBoundary extends Component<
+  MdxRenderBoundaryProps,
+  MdxRenderBoundaryState
+> {
+  state: MdxRenderBoundaryState = { hasError: false };
+
+  static getDerivedStateFromError(): MdxRenderBoundaryState {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error('[mdx-render-boundary] caught render error', error);
+    // componentStack names the compiled MDX node that threw — the most useful
+    // triage signal when user MDX 500s in production.
+    console.error('[mdx-render-boundary] component stack', errorInfo.componentStack);
+  }
+
+  render() {
+    return this.state.hasError ? this.props.fallback : this.props.children;
+  }
+}

package/vendored/components/mdx/MDXComponents.tsx

@@ -43,6 +43,7 @@ import { View, ViewProvider, ViewSelector, ViewWrapper } from './View';
 import { YouTube } from './YouTube';
 import { Video } from './Video';
 import { Visibility } from './Visibility';
+import { MdxErrorBlock } from './MdxErrorBlock';
 
 /**
  * Extract language from a pre element for tab label
@@ -253,6 +254,8 @@ export const MDXComponents = {
   // search index). This React component is a fail-closed fallback for
   // any <Visibility> that slips past both filters.
   Visibility,
+  // Mintlify-style <Snippet file=…/> is unsupported (snippets are import-based) — placeholder, never throw.
+  Snippet: ({ file }: { file?: string }) => <MdxErrorBlock label={file ? `snippet ${file}` : 'snippet'} />,
   // Sized images from preprocess-mdx (![alt](url =WIDTHx) syntax).
   // These are output as <SizedImage> JSX so they go through component mapping
   // (raw <img> JSX in MDX bypasses the components provider).

package/vendored/components/mdx/MdxErrorBlock.tsx

@@ -0,0 +1,42 @@
+/**
+ * MdxErrorBlock — inline placeholder shown in place of MDX content that failed
+ * to render at request time (an undefined component, a bare `{x, y}` expression
+ * that throws a ReferenceError, etc.). Rendered as the fallback of
+ * `MdxRenderBoundary` so a single broken page degrades to a visible note
+ * instead of an HTTP 500.
+ *
+ * Server component, no client JS. Uses inline `style` with CSS-var fallbacks
+ * (mirrors OpenApiError) — docs themes don't guarantee Tailwind utilities are
+ * compiled, so Tailwind classes can't be relied on here. `role="note"` (a
+ * softer signal than OpenApiError's `role="alert"`) because a per-block render
+ * failure is informational, not a hard page-level error.
+ */
+
+interface MdxErrorBlockProps {
+  label?: string;
+}
+
+export function MdxErrorBlock({ label }: MdxErrorBlockProps) {
+  return (
+    <div
+      role="note"
+      style={{
+        margin: '1rem 0',
+        padding: '0.75rem 1rem',
+        borderRadius: '8px',
+        border: '1px solid #f59e0b',
+        backgroundColor: 'rgba(245, 158, 11, 0.08)',
+        fontSize: '0.875rem',
+        lineHeight: 1.5,
+        color: 'var(--color-text-primary, #1e293b)',
+      }}
+    >
+      <span style={{ fontWeight: 600 }}>⚠ This content couldn’t be displayed</span>
+      {label ? (
+        <span style={{ marginLeft: '0.375rem', color: 'var(--color-text-muted, #64748b)' }}>
+          ({label})
+        </span>
+      ) : null}
+    </div>
+  );
+}

package/vendored/lib/isr-build-executor.ts

@@ -134,6 +134,19 @@ export function normalizeOpenApiRefKey(ref: unknown): string | null {
   return normalized || null;
 }
 
+// Re-export the pure snippet scanner so build.ts and the Task 3.2 test can
+// continue importing from isr-build-executor without any changes, while the
+// CLI (Task 3.4) imports from snippet-scanner.ts directly (no heavy deps).
+export { normalizeSnippetRef, findSnippetIssues } from './snippet-scanner.js';
+export type { SnippetIssue } from './snippet-scanner.js';
+
+// Re-export the pure risky-expression scanner on the same channel. The build
+// surfaces `risky_expression` warnings to tell authors which `{x, y}`-style
+// expressions the recma render guard silently dropped (see
+// lib/recma-guard-expressions.ts).
+export { findRiskyExpressions } from './risky-expression-scanner.js';
+export type { RiskyExpressionIssue } from './risky-expression-scanner.js';
+
 /**
  * Resolve a docs.json `api.openapi` value into the list of string refs the build
  * collects/validates, plus any non-blocking warnings for forms the build can't

package/vendored/lib/recma-collect-missing-refs.ts

@@ -0,0 +1,51 @@
+import { visit } from 'estree-util-visit';
+import type { Program } from 'estree-jsx';
+
+/**
+ * recmaCollectMissingRefs — names the components that user MDX references but
+ * the provider doesn't supply, so the caller can inject per-name placeholder
+ * fallbacks instead of letting `<Foo/>` throw `_missingMdxReference` at render
+ * (an HTTP 500). Part of the "docs never 500" wiring.
+ *
+ * MDX's compiled output emits, for every provider-expected component, a guard:
+ *
+ *     if (!Foo) _missingMdxReference("Foo", true);
+ *
+ * The string-literal first argument is the referenced component name. Inline
+ * `export const X = …` components and imported components are LOCAL bindings,
+ * not provider lookups, so MDX never emits a `_missingMdxReference` for them —
+ * they don't appear here. (Verified against `@mdx-js/mdx` compiled output.)
+ *
+ * The plugin records the raw collected names on `collector.names`; the caller
+ * subtracts the provided component keys to get the genuinely-unknown set. We do
+ * NOT filter dotted names (e.g. `"Tree.Folder"`, emitted for `<Tree.Folder>`
+ * member access) here — the caller drops them, because a fallback keyed on a
+ * dotted string can't be looked up as a provider own-key anyway, and compound
+ * components are already redirected to their flat name by
+ * `recmaCompoundComponents` (which must run BEFORE this plugin in the
+ * `recmaPlugins` array so the flat-name rewrite is in place first).
+ *
+ * Factory-with-collector shape (not a bare plugin) because recma plugins can't
+ * return data — the caller reads `collector.names` after `compileMDX` resolves.
+ */
+export interface MissingRefCollector {
+  names: string[];
+}
+
+export function recmaCollectMissingRefs(collector: MissingRefCollector) {
+  return () => (tree: Program) => {
+    visit(tree, (node) => {
+      if (
+        node.type !== 'CallExpression' ||
+        node.callee.type !== 'Identifier' ||
+        node.callee.name !== '_missingMdxReference'
+      ) {
+        return;
+      }
+      const arg0 = node.arguments[0];
+      if (arg0 && arg0.type === 'Literal' && typeof arg0.value === 'string') {
+        collector.names.push(arg0.value);
+      }
+    });
+  };
+}

package/vendored/lib/recma-guard-expressions.ts

@@ -0,0 +1,151 @@
+import { visit } from 'estree-util-visit';
+import type {
+  Program,
+  Node,
+  CallExpression,
+  Expression,
+  Property,
+} from 'estree-jsx';
+
+/**
+ * recmaGuardExpressions — wraps every AUTHOR-WRITTEN MDX expression in a
+ * `try/catch` so a render-time throw degrades to a silent drop instead of an
+ * HTTP 500. The final, RSC-correct layer of "docs never 500".
+ *
+ * WHY a recma plugin and not an error boundary: user MDX is rendered at request
+ * time by `<MDXRemote>` (an async Server Component). A bare expression like
+ * `{x, y}` in prose compiles to a free `(x, y)` reference that throws
+ * `ReferenceError: x is not defined` at RENDER. A `'use client'` class error
+ * boundary CANNOT catch a throw from an async Server Component during the App
+ * Router server render — the throw bypasses it to the route `error.tsx` and
+ * returns 500 (verified at runtime: the boundary's `componentDidCatch` never
+ * fired). `renderToStaticMarkup` as a server-side trial render is also out — it
+ * false-positives on every async component ("a component suspended while
+ * responding to synchronous input"). The only RSC-safe place to neutralize the
+ * throw is the compiled output itself, here.
+ *
+ * WHAT it transforms: MDX compiles every author expression `{EXPR}` into a child
+ * (or attribute) value inside a `_jsx(...)` / `_jsxs(...)` call. This plugin
+ * finds those values and rewrites
+ *
+ *     EXPR   →   (() => { try { return (EXPR); } catch { return undefined; } })()
+ *
+ * On throw the expression yields `undefined`, which React renders as nothing —
+ * the one broken node vanishes and the rest of the page renders normally. A
+ * valid expression returns exactly what it did before (the IIFE only adds a
+ * catch), so there is no behavioral change for working content and no
+ * double-render or async false-positive.
+ *
+ * Author signal lives elsewhere: dropped expressions are surfaced to the author
+ * via the build-time `risky_expression` warning, NOT a per-render `console.*`
+ * here — a per-render log would flood SSR logs on every hit of a popular page
+ * (see builder/CLAUDE.md "No per-render console.warn in MDX components").
+ *
+ * SCOPE: covers expression throws (undefined identifiers, bad member access).
+ * It does NOT catch a *defined* component that throws inside its own render —
+ * `_jsx(Foo, props)` only constructs the element; `Foo`'s render throw is
+ * deferred past this layer. That residual class has no clean RSC-safe inline
+ * catch and was never observed in the wild.
+ */
+
+const JSX_CALLEES = new Set(['_jsx', '_jsxs', '_jsxDEV']);
+
+/**
+ * A prop value is an "author expression" worth guarding when it is neither
+ * static text nor a compiler-emitted element/spread:
+ *   - `Literal`        → static text/number/string child; cannot throw.
+ *   - `SpreadElement`  → `{...props}`; structural, never an author expression.
+ *   - a `_jsx*(…)` call → a nested element the compiler emitted; its own
+ *                         children get visited and guarded independently.
+ * Everything else in a `children`/attribute position came from author `{EXPR}`
+ * (identifiers, member access, calls, conditionals, sequences, objects) and is
+ * exactly what can throw at render — so it gets wrapped.
+ */
+function isAuthorExpr(node: Node | null | undefined): node is Expression {
+  if (!node || typeof (node as Node).type !== 'string') return false;
+  const type = (node as Node).type;
+  if (type === 'Literal') return false;
+  if (type === 'SpreadElement') return false;
+  if (type === 'JSXElement' || type === 'JSXFragment') return false;
+  if (
+    type === 'CallExpression' &&
+    (node as CallExpression).callee.type === 'Identifier' &&
+    JSX_CALLEES.has(((node as CallExpression).callee as { name: string }).name)
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/** Build `(() => { try { return (expr); } catch { return undefined; } })()`. */
+function guard(expr: Expression): CallExpression {
+  return {
+    type: 'CallExpression',
+    optional: false,
+    arguments: [],
+    callee: {
+      type: 'ArrowFunctionExpression',
+      id: null,
+      expression: false,
+      generator: false,
+      async: false,
+      params: [],
+      body: {
+        type: 'BlockStatement',
+        body: [
+          {
+            type: 'TryStatement',
+            block: {
+              type: 'BlockStatement',
+              body: [{ type: 'ReturnStatement', argument: expr }],
+            },
+            handler: {
+              type: 'CatchClause',
+              param: null,
+              body: {
+                type: 'BlockStatement',
+                body: [
+                  {
+                    type: 'ReturnStatement',
+                    argument: { type: 'Identifier', name: 'undefined' },
+                  },
+                ],
+              },
+            },
+            finalizer: null,
+          },
+        ],
+      },
+    },
+  } as CallExpression;
+}
+
+export function recmaGuardExpressions() {
+  return (tree: Program) => {
+    visit(tree, (node) => {
+      if (
+        node.type !== 'CallExpression' ||
+        node.callee.type !== 'Identifier' ||
+        !JSX_CALLEES.has(node.callee.name)
+      ) {
+        return;
+      }
+      const props = node.arguments[1];
+      if (!props || props.type !== 'ObjectExpression') return;
+
+      for (const prop of props.properties) {
+        if (prop.type !== 'Property') continue;
+        const value = (prop as Property).value;
+        if (value.type === 'ArrayExpression') {
+          // `children: [ "text", _jsx(...), (x, y), ... ]`
+          value.elements = value.elements.map((el) =>
+            isAuthorExpr(el) ? guard(el) : el,
+          );
+        } else if (isAuthorExpr(value)) {
+          // `children: x` (single child) or `someAttr: undefinedRef`
+          (prop as Property).value = guard(value);
+        }
+      }
+    });
+  };
+}

package/vendored/lib/render-doc-page.tsx

@@ -11,7 +11,7 @@
 //     non-ISR local dev): passes `requestHeaders=null` and gets a
 //     subdomain-canonical via `getBaseUrlFromConfig`.
 import { notFound } from 'next/navigation';
-import { MDXRemote } from 'next-mdx-remote/rsc';
+import { MDXRemote, compileMDX } from 'next-mdx-remote/rsc';
 import type { Metadata } from 'next';
 import type { AnchorHTMLAttributes, ReactElement, ReactNode } from 'react';
 import { MDXComponents } from '@/components/mdx/MDXComponents';
@@ -24,6 +24,8 @@ import { SocialFooter } from '@/components/navigation/SocialFooter';
 import { ApiPageWrapper } from '@/components/mdx/ApiPage';
 import { OpenApiEndpoint } from '@/components/mdx/OpenApiEndpoint';
 import { OpenApiError } from '@/components/openapi/OpenApiError';
+import { MdxRenderBoundary } from '@/components/errors/MdxRenderBoundary';
+import { MdxErrorBlock } from '@/components/mdx/MdxErrorBlock';
 import { getHighlighter } from '@/lib/shiki-highlighter';
 import type { Highlighter } from 'shiki';
 import type { Pluggable } from 'unified';
@@ -48,6 +50,8 @@ import { getLatexRemarkPlugins, getLatexRehypePlugins } from '@/lib/latex-config
 import { getTypographyRemarkPlugins } from '@/lib/typography-config';
 import { remarkVisibility } from '@/lib/remark-visibility';
 import { recmaCompoundComponents } from '@/lib/recma-compound-components';
+import { recmaCollectMissingRefs, type MissingRefCollector } from '@/lib/recma-collect-missing-refs';
+import { recmaGuardExpressions } from '@/lib/recma-guard-expressions';
 import { extractInlineComponents } from '@/lib/process-mdx-with-exports';
 import { extractHeadings } from '@/lib/heading-extractor';
 import { StepSlugProvider, type StepSlugEntry } from '@/components/mdx/StepSlugContext';
@@ -465,6 +469,80 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
     }
   }
 
+  // ── Single pre-render compile pass ("docs never 500") ──────────────────────
+  // A compile/syntax throw (e.g. an unclosed `<Tabs>`) happens inside
+  // `MDXRemote`'s own `await compileMDX`, OUTSIDE the client render boundary's
+  // subtree — so the boundary CANNOT catch it; it would 500 via `error.tsx`.
+  // Compile ONCE here, in try/catch, against the EXACT source the chosen branch
+  // will render (the API branch strips `<ResponseExample>` when an OpenAPI
+  // endpoint resolved; otherwise plain `content`), with the SAME security +
+  // mdxOptions the call sites use. On failure we substitute an inline
+  // `<MdxErrorBlock>` instead of ever handing known-bad source to MDXRemote.
+  //
+  // The same compile doubles as unknown-component collection: a recma plugin
+  // records every `_missingMdxReference("X", …)` name; subtracting the provided
+  // keys yields the referenced-but-unprovided capitalized components, for which
+  // we inject per-name placeholder fallbacks (own-key injection) below.
+  const effectiveSource = openApiEndpointData
+    ? content.replace(/<ResponseExample>[\s\S]*?<\/ResponseExample>/g, '')
+    : content;
+  const missingRefCollector: MissingRefCollector = { names: [] };
+  let mdxError: string | null = null;
+  let mdxCompileMs: number | null = null;
+  const mdxCompileStart = performance.now();
+  try {
+    await compileMDX({
+      source: effectiveSource,
+      components: AllComponentsWithInline,
+      options: {
+        ...mdxSecurityOptions,
+        mdxOptions: {
+          ...getCommonMdxOptions(config, highlighter),
+          recmaPlugins: [
+            recmaCompoundComponents,
+            recmaCollectMissingRefs(missingRefCollector),
+            recmaGuardExpressions,
+          ],
+        },
+      },
+    });
+  } catch (err) {
+    // Syntax/compile failure — the only path that can 500 around MDXRemote.
+    // Degrade to an inline placeholder; the chosen branch renders it instead
+    // of calling MDXRemote with source known to throw at compile.
+    mdxError = err instanceof Error ? err.message : String(err);
+    logger.warn(`[MDX] compile failed for ${pagePath}: ${mdxError}`);
+  }
+  mdxCompileMs = Math.round(performance.now() - mdxCompileStart);
+
+  // Unknown components = referenced-but-unprovided, capitalized, non-dotted.
+  // Dotted names (e.g. "Tree.Folder") are dropped: compound components are
+  // already redirected to their flat name by recmaCompoundComponents, and a
+  // dotted string can't be a provider own-key. Subtract the provided keys.
+  const providedKeys = new Set(Object.keys(AllComponentsWithInline));
+  const unknownComponentNames = Array.from(new Set(missingRefCollector.names)).filter(
+    (name) =>
+      !name.includes('.') &&
+      /^[A-Z]/.test(name) &&
+      !providedKeys.has(name),
+  );
+
+  // Own-key injection: a real placeholder entry per unknown name. The compiled
+  // MDX does `{ ...props.components }` (own-enumerable copy only — a Proxy trap
+  // would never fire), so each unknown component needs a literal own-key to
+  // resolve to the placeholder instead of throwing `_missingMdxReference`.
+  const ComponentsWithUnknownFallback = {
+    ...AllComponentsWithInline,
+    ...Object.fromEntries(
+      unknownComponentNames.map((name) => [
+        name,
+        function UnknownComponent() {
+          return <MdxErrorBlock label={`unknown component <${name}>`} />;
+        },
+      ]),
+    ),
+  };
+
   // Gate on VERCEL_REGION so the telemetry only fires in Vercel runtime
   // (production + preview). In `jamdesk dev` the structured JSON would
   // pollute the user's terminal on every page render. `[r2-timing]` logs
@@ -477,6 +555,11 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
       snippetInlineMs,
       openApiMs,
       openApiCandidates,
+      // Cost of the mandatory never-500 syntax-guard compile pass (unknown-name
+      // collection piggybacks for free). Watch this in prod for a regression.
+      mdxCompileMs,
+      unknownComponentCount: unknownComponentNames.length,
+      mdxCompileFailed: mdxError !== null,
     });
   }
 
@@ -607,21 +690,25 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
                 <OpenApiError message={openApiError} slug={slug.join('/')} />
               )}
 
-              <StepSlugProvider entries={stepEntries}>
-                <MDXRemote
-                  source={openApiEndpointData
-                    ? content.replace(/<ResponseExample>[\s\S]*?<\/ResponseExample>/g, '')
-                    : content}
-                  components={AllComponentsWithInline}
-                  options={{
-                    ...mdxSecurityOptions,
-                    mdxOptions: {
-                      ...getCommonMdxOptions(config, highlighter),
-                      recmaPlugins: [recmaCompoundComponents],
-                    },
-                  }}
-                />
-              </StepSlugProvider>
+              {mdxError ? (
+                <MdxErrorBlock label="page content" />
+              ) : (
+                <MdxRenderBoundary fallback={<MdxErrorBlock label="page content" />}>
+                  <StepSlugProvider entries={stepEntries}>
+                    <MDXRemote
+                      source={effectiveSource}
+                      components={ComponentsWithUnknownFallback}
+                      options={{
+                        ...mdxSecurityOptions,
+                        mdxOptions: {
+                          ...getCommonMdxOptions(config, highlighter),
+                          recmaPlugins: [recmaCompoundComponents, recmaGuardExpressions],
+                        },
+                      }}
+                    />
+                  </StepSlugProvider>
+                </MdxRenderBoundary>
+              )}
             </div>
 
             {!embed && <PageNavigation currentSlug={slug.join('/')} config={config} />}
@@ -632,20 +719,24 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
     );
   }
 
-  const mdxContent = (
-    <StepSlugProvider entries={stepEntries}>
-      <MDXRemote
-        source={content}
-        components={AllComponentsWithInline}
-        options={{
-          ...mdxSecurityOptions,
-          mdxOptions: {
-            ...getCommonMdxOptions(config, highlighter),
-            recmaPlugins: [recmaCompoundComponents],
-          },
-        }}
-      />
-    </StepSlugProvider>
+  const mdxContent = mdxError ? (
+    <MdxErrorBlock label="page content" />
+  ) : (
+    <MdxRenderBoundary fallback={<MdxErrorBlock label="page content" />}>
+      <StepSlugProvider entries={stepEntries}>
+        <MDXRemote
+          source={content}
+          components={ComponentsWithUnknownFallback}
+          options={{
+            ...mdxSecurityOptions,
+            mdxOptions: {
+              ...getCommonMdxOptions(config, highlighter),
+              recmaPlugins: [recmaCompoundComponents, recmaGuardExpressions],
+            },
+          }}
+        />
+      </StepSlugProvider>
+    </MdxRenderBoundary>
   );
 
   const articleContent = wrap(