jamdesk 1.1.129 → 1.1.131

package/dist/lib/validate-risky-expressions.js

@@ -0,0 +1,54 @@
+/**
+ * Risky-expression Validation (CLI)
+ *
+ * Scans MDX pages for `{x, y}`-style expressions that reference an undefined
+ * identifier — the literal-looking-braces bug (MDX evaluates `{…}` as
+ * JavaScript). On the cloud these throw at render but are silently dropped by
+ * the recma guard (never a 500) and surfaced as a `risky_expression` build
+ * warning. The CLI runs the SAME scanner locally so authors catch the dropped
+ * expression before pushing.
+ *
+ * Reuses the pure scanner from risky-expression-scanner.ts (synced from
+ * build-service) so the matching logic is byte-identical to the cloud build —
+ * no drift. PRECISION over recall, by design (see the scanner's header).
+ *
+ * Scans EVERY project MDX file (not just navigation pages), mirroring the
+ * cloud build's per-file scan in build.ts.
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { findRiskyExpressions } from './risky-expression-scanner.js';
+const RISKY_EXPRESSION_WARNING_CAP = 50;
+/**
+ * Validate risky `{…}` expressions 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/snippet validation.
+ * @returns Array of RiskyExpressionWarning (empty when clean). Never throws.
+ */
+export async function validateRiskyExpressions(projectDir, mdxFiles) {
+    const warnings = [];
+    for (const file of mdxFiles) {
+        if (warnings.length >= RISKY_EXPRESSION_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 = findRiskyExpressions(content, relFile);
+        for (const issue of issues) {
+            if (warnings.length >= RISKY_EXPRESSION_WARNING_CAP)
+                break;
+            warnings.push({ file: relFile, message: issue.message });
+        }
+    }
+    return warnings;
+}
+//# sourceMappingURL=validate-risky-expressions.js.map

package/dist/lib/validate-risky-expressions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-risky-expressions.js","sourceRoot":"","sources":["../../src/lib/validate-risky-expressions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AASrE,MAAM,4BAA4B,GAAG,EAAE,CAAC;AAExC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,UAAkB,EAClB,QAAkB;IAElB,MAAM,QAAQ,GAA6B,EAAE,CAAC;IAE9C,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,QAAQ,CAAC,MAAM,IAAI,4BAA4B;YAAE,MAAM;QAE3D,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,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACtD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,QAAQ,CAAC,MAAM,IAAI,4BAA4B;gBAAE,MAAM;YAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/lib/validate-snippets.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 { type SnippetIssue } from './snippet-scanner.js';
+export interface SnippetWarning {
+    /** Page path relative to projectDir (e.g. "guide/intro.mdx") */
+    file: string;
+    /** Discriminates the two warning variants (drives the CLI hint copy). */
+    variant: SnippetIssue['variant'];
+    /** Author-facing guidance message */
+    message: string;
+}
+/**
+ * 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 declare function validateSnippets(projectDir: string, mdxFiles: string[]): Promise<SnippetWarning[]>;
+//# sourceMappingURL=validate-snippets.d.ts.map

package/dist/lib/validate-snippets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-snippets.d.ts","sourceRoot":"","sources":["../../src/lib/validate-snippets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAA0C,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEjG,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IACjC,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAqBD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,cAAc,EAAE,CAAC,CAwB3B"}

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.131",
   "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,230 @@
+import { generate } from 'astring';
+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 them. There are two catch behaviors by position:
+ *
+ *   children/text position:
+ *     EXPR → (() => { try { return (EXPR); }
+ *                     catch (e) { return e instanceof ReferenceError
+ *                                          ? "{<literal>}" : undefined; } })()
+ *   attribute position:
+ *     EXPR → (() => { try { return (EXPR); } catch { return undefined; } })()
+ *
+ * On any 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.
+ *
+ * RENDER-LITERAL refinement (children/text only): the most common author mistake
+ * is prose with literal braces or a typo'd variable — `coordinates: {x, y} pixel
+ * positions`. MDX evaluates `{x, y}` as JS and `x` is undefined → `ReferenceError`
+ * → the text used to vanish (`coordinates:  pixel positions`). For text positions
+ * we instead render the literal source the author typed (`{x, y}`), reconstructed
+ * at COMPILE time via `astring` and embedded as a string. This applies ONLY to
+ * `ReferenceError` (undefined identifier — the "author meant literal / typo'd a
+ * ref" class); every other throw (e.g. a `TypeError` from member access on a
+ * defined-but-null value — a genuinely broken template) still returns `undefined`
+ * and drops, exactly as before. Attribute expressions never render a literal — a
+ * literal string in a prop is meaningless — so they keep the plain `undefined`
+ * catch.
+ *
+ * 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;
+}
+
+/**
+ * Reconstruct an author expression's `{…}` source so a ReferenceError in a text
+ * position can render the literal the author typed instead of vanishing.
+ *
+ * astring wraps a top-level `SequenceExpression` in parens (`x, y` → `(x, y)`),
+ * but the author wrote `{x, y}` — so a sequence's parts are serialized
+ * individually and re-joined to avoid the spurious inner parens. Compact options
+ * keep multi-line nodes (objects) on a single line. Returns `null` if the node
+ * can't be serialized (unexpected node type), so the caller falls back to the
+ * plain `undefined`-returning guard rather than emitting broken output.
+ */
+function expressionToLiteral(expr: Expression): string | null {
+  const opts = { indent: '', lineEnd: '' } as const;
+  const ser = (node: Expression): string =>
+    generate(node as unknown as Parameters<typeof generate>[0], opts);
+  try {
+    const inner =
+      expr.type === 'SequenceExpression'
+        ? expr.expressions.map((e) => ser(e as Expression)).join(', ')
+        : ser(expr);
+    return '{' + inner + '}';
+  } catch {
+    return null;
+  }
+}
+
+/** The identifier/string name of a `_jsx` prop key (`children`, `data-v`, …). */
+function propKeyName(prop: Property): string | undefined {
+  const key = prop.key;
+  if (key.type === 'Identifier') return key.name;
+  if (key.type === 'Literal' && typeof key.value === 'string') return key.value;
+  return undefined;
+}
+
+/**
+ * Build the guarding IIFE around `expr`.
+ *
+ * `literal` (children/text positions only) is the `{…}` source to render when the
+ * expression throws a `ReferenceError`; pass `null` (attribute positions, or when
+ * serialization failed) to keep the plain `catch → undefined` behavior.
+ *
+ *   literal:    (() => { try { return (expr); }
+ *                        catch (e) { return e instanceof ReferenceError
+ *                                             ? "{literal}" : undefined; } })()
+ *   no literal: (() => { try { return (expr); } catch { return undefined; } })()
+ */
+function guard(expr: Expression, literal: string | null): CallExpression {
+  const catchReturn: Expression =
+    literal === null
+      ? { type: 'Identifier', name: 'undefined' }
+      : {
+          type: 'ConditionalExpression',
+          test: {
+            type: 'BinaryExpression',
+            operator: 'instanceof',
+            left: { type: 'Identifier', name: 'e' },
+            right: { type: 'Identifier', name: 'ReferenceError' },
+          },
+          consequent: { type: 'Literal', value: literal },
+          alternate: { type: 'Identifier', name: 'undefined' },
+        };
+  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: literal === null ? null : { type: 'Identifier', name: 'e' },
+              body: {
+                type: 'BlockStatement',
+                body: [{ type: 'ReturnStatement', argument: catchReturn }],
+              },
+            },
+            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;
+        // Render-literal fallback applies only to text flow (`children`); an
+        // attribute expression that throws degrades to `undefined` (a literal
+        // string in a prop slot is meaningless).
+        const isText = propKeyName(prop as Property) === 'children';
+        const literalOf = (e: Expression): string | null =>
+          isText ? expressionToLiteral(e) : null;
+        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, literalOf(el)) : el,
+          );
+        } else if (isAuthorExpr(value)) {
+          // `children: x` (single child) or `someAttr: undefinedRef`
+          (prop as Property).value = guard(value, literalOf(value));
+        }
+      }
+    });
+  };
+}