jamdesk 1.1.200 → 1.1.202

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

@@ -49,7 +49,8 @@ import { computeHasCodePanels } from './render-doc-page-helpers';
 import { logger } from '../shared/logger';
 import { preprocessMdx, containsPanel, containsView, buildSnippetAliasMap } from '@/lib/preprocess-mdx';
 import { injectPromptSources } from '@/lib/inject-prompt-source';
-import { loadSnippetsForIsr } from '@/lib/snippet-loader-isr';
+import { loadSnippetsForIsr, collectPageUtilityCandidates } from '@/lib/snippet-loader-isr';
+import { buildUserUtilityCss } from '@/lib/user-utility-css';
 import { PanelWrapper } from '@/components/mdx/PanelWrapper';
 import { ViewWrapper } from '@/components/mdx/View';
 import { getLatexRemarkPlugins, getLatexRehypePlugins } from '@/lib/latex-config';
@@ -58,6 +59,7 @@ 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 { recmaStripEventHandlers } from '@/lib/strip-event-handlers';
 import { extractInlineComponents } from '@/lib/process-mdx-with-exports';
 import { extractHeadings } from '@/lib/heading-extractor';
 import { StepSlugProvider, type StepSlugEntry } from '@/components/mdx/StepSlugContext';
@@ -388,9 +390,12 @@ export async function resolveDerivedDescription(
     // The spec loader REUSES the render path's cached loaders — the ISR module
     // cache (`r2:${slug}:${specPath}`, 10-min TTL) that `renderDocPage`
     // populates when it renders the page's <ApiEndpoint>, or the static
-    // `getCachedSpec`. So the spec is the same warm parse the render already
-    // did: the marginal cost of this lookup is a cache hit, never an uncached
-    // fetch+parse. That matters because docs routes are force-dynamic, so this
+    // `getCachedSpec`. That cache stores the in-flight PROMISE, so this lookup
+    // joins the render's load rather than starting a second one — Next.js runs
+    // `generateMetadata` and the page component for the same request, and a
+    // value-cache populated only after the await let BOTH miss and both pay a
+    // full R2 fetch plus a full SwaggerParser.dereference. See openapi-isr.ts
+    // `cachedSpec`. That matters because docs routes are force-dynamic, so this
     // metadata runs on EVERY page view (every human + crawler). Mirrors the
     // `useIsr`/`projectDir` derivation in `renderDocPage`'s OpenAPI branch.
     const specPaths = collectLocalSpecPaths(config.api.openapi);
@@ -711,6 +716,22 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
   });
   const snippetInlineMs = Math.round(performance.now() - snippetInlineStart);
 
+  // Tailwind never saw this project's MDX when the app was built, so an
+  // author's arbitrary-value class (`bg-[#ED8200]`) has no rule behind it and
+  // the element renders unstyled. Generate just those rules now. Runs AFTER the
+  // snippet load above so every snippet is already a cache hit — and it must
+  // include snippets, because that is where authors put the markup that carries
+  // these classes — but only in ISR, where snippet bodies actually live in R2.
+  // See lib/user-utility-css.ts.
+  const userUtilityCss = projectSlug
+    ? await buildUserUtilityCss(
+        await collectPageUtilityCandidates(projectSlug, rawContent, MDXComponents, isIsr),
+      )
+    : '';
+  const userUtilityStyle = userUtilityCss
+    ? <style data-jd-user-utilities="" dangerouslySetInnerHTML={{ __html: userUtilityCss }} />
+    : null;
+
   const overriddenComponents = Object.keys(inlineComponents).filter(
     (name) => name in MDXComponents,
   );
@@ -919,6 +940,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
             recmaPlugins: [
               recmaCompoundComponents,
               recmaCollectMissingRefs(missingRefCollector),
+              recmaStripEventHandlers,
               recmaGuardExpressions,
             ],
           },
@@ -1082,6 +1104,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
       <>{jsonLdScript}<ApiPageWrapper hasCodePanels={hasCodePanels}>
         {wrap(
           <article className="px-4 sm:px-6 lg:px-8 py-6 sm:py-10 flex-1 min-w-0">
+            {userUtilityStyle}
             <Breadcrumb slug={slug} config={config} hidden={embed} />
             {translationNotice}
 
@@ -1164,7 +1187,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
                             ...mdxSecurityOptions,
                             mdxOptions: {
                               ...getCommonMdxOptions(config, highlighter),
-                              recmaPlugins: [recmaCompoundComponents, recmaGuardExpressions],
+                              recmaPlugins: [recmaCompoundComponents, recmaStripEventHandlers, recmaGuardExpressions],
                             },
                           }}
                         />
@@ -1198,7 +1221,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
                 ...mdxSecurityOptions,
                 mdxOptions: {
                   ...getCommonMdxOptions(config, highlighter),
-                  recmaPlugins: [recmaCompoundComponents, recmaGuardExpressions],
+                  recmaPlugins: [recmaCompoundComponents, recmaStripEventHandlers, recmaGuardExpressions],
                 },
               }}
             />
@@ -1210,6 +1233,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
 
   const articleContent = wrap(
     <article className="px-4 sm:px-6 lg:px-8 py-6 sm:py-10">
+      {userUtilityStyle}
       <Breadcrumb slug={slug} config={config} hidden={embed} />
       {translationNotice}
 

package/vendored/lib/risky-expression-scanner.ts

@@ -29,6 +29,22 @@ import { visit as visitMdast } from 'unist-util-visit';
 import { visit as visitEstree } from 'estree-util-visit';
 import type { Node as EsNode } from 'estree-jsx';
 
+/**
+ * Event-handler prop test — a DELIBERATE copy of the canonical one in
+ * `lib/strip-event-handlers.ts`, kept in sync by
+ * `__tests__/lib/event-handler-predicate-parity.test.ts`.
+ *
+ * Not imported, because this file is vendored standalone into `cli/src/lib/`
+ * (see cli/scripts/vendor.js) where no sibling module exists and the CLI's
+ * `node16` resolution would reject the extensionless path. Every other
+ * build-service file synced there is self-contained for the same reason —
+ * adding a second file to that chain would mean touching vendor.js,
+ * verify-shared-sync.sh and the drift test for one regex.
+ */
+function isEventHandlerProp(name: string): boolean {
+  return /^on[A-Z]/.test(name);
+}
+
 /** A single risky MDX expression found on a page. */
 export interface RiskyExpressionIssue {
   /** The expression source between the braces, e.g. `"x, y"`. */
@@ -254,5 +270,49 @@ export function findRiskyExpressions(content: string, pagePath: string): RiskyEx
     });
   });
 
+  // Pass 3: author event handlers (`onClick={…}`, `onSubmit={…}`). These are
+  // removed at compile time by `recmaStripEventHandlers` /
+  // `babelStripEventHandlers` — a Server Component cannot pass a function across
+  // the RSC boundary, and before the strip existed such a prop returned HTTP 500
+  // from the serializer (see lib/strip-event-handlers.ts).
+  //
+  // Unlike pass 2 this needs no scope modelling and has no precision tradeoff:
+  // the name alone decides it, and the prop is ALWAYS dropped, so the warning is
+  // never a false positive.
+  const jsxElementTypes = new Set(['mdxJsxFlowElement', 'mdxJsxTextElement']);
+  visitMdast(
+    tree as never,
+    (node: {
+      type: string;
+      name?: string | null;
+      attributes?: Array<{ type: string; name?: string }>;
+    }) => {
+      if (!jsxElementTypes.has(node.type) || !node.attributes) return;
+      for (const attr of node.attributes) {
+        // `mdxJsxExpressionAttribute` is a spread (`{...props}`) — no static
+        // name, so it is neither strippable nor warnable.
+        if (attr.type !== 'mdxJsxAttribute' || !attr.name) continue;
+        if (!isEventHandlerProp(attr.name)) continue;
+        const el = node.name ? `<${node.name}>` : 'an element';
+        issues.push({
+          expression: attr.name,
+          undefinedRefs: [],
+          // Deliberately does NOT suggest a `'use client'` snippet. Snippets are
+          // compiled by the same server pipeline (and `isClientComponent` is
+          // computed but never read), so the strip applies there too — the
+          // handler would be just as dead, only silently. It DOES still work
+          // under `jamdesk dev`, which makes that the worst possible advice:
+          // works locally, inert in production.
+          message:
+            `\`${attr.name}\` on ${el} in \`${pagePath}\` was removed. ` +
+            `Documentation pages render on the server, where React cannot pass ` +
+            `event handlers, so the handler never ran. Use a link, or one of the ` +
+            `built-in interactive components — a custom handler cannot run on a ` +
+            `hosted documentation page, including inside a snippet.`,
+        });
+      }
+    },
+  );
+
   return issues;
 }

package/vendored/lib/snippet-compiler-isr.ts

@@ -6,6 +6,7 @@
  */
 
 import { transform } from '@babel/standalone';
+import { babelStripEventHandlers } from './strip-event-handlers';
 import { fetchSnippet } from './r2-content';
 
 interface CompiledSnippet {
@@ -52,7 +53,16 @@ export async function compileSnippetIsr(
   // Transpile JSX to JavaScript
   const transpiled = transform(source, {
     presets: ['react', 'typescript'],
-    plugins: [['transform-react-jsx', { runtime: 'automatic' }]],
+    // babelStripEventHandlers even though NOTHING calls compileSnippetIsr today
+    // (only clearSnippetCache/getSnippetCacheSize are imported elsewhere). This
+    // file is named as THE ISR snippet compiler, so it is exactly what someone
+    // reaches for next — and without the strip it silently reintroduces the
+    // HTTP 500 that lib/strip-event-handlers.ts exists to prevent. Two lines of
+    // insurance on a dead path beats rediscovering that incident.
+    plugins: [
+      babelStripEventHandlers,
+      ['transform-react-jsx', { runtime: 'automatic' }],
+    ],
     filename: snippetPath,
   });
 

package/vendored/lib/snippet-loader-isr.ts

@@ -19,12 +19,15 @@ import { injectPromptSources } from './inject-prompt-source';
 import { mdxSecurityOptions } from './mdx-security-options';
 import { remarkSvgNamespaceAttrs } from './remark-svg-namespace-attrs';
 import { remarkStyleStringToObject } from './remark-style-string-to-object';
+import { recmaStripEventHandlers, babelStripEventHandlers } from './strip-event-handlers';
 import {
   mdxEvalGuardPlugin,
   guardPropertyKey,
   KEY_GUARD_NAME,
   STRICT_MODE_PROLOGUE,
 } from './mdx-eval-guard';
+import { extractUtilityCandidates, MAX_UTILITY_CANDIDATES } from './user-utility-css';
+import { logger } from '../shared/logger';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyComponent = React.ComponentType<any>;
@@ -32,6 +35,14 @@ type AnyComponent = React.ComponentType<any>;
 interface CompiledSnippet {
   exports: Record<string, AnyComponent>;
   isClientComponent: boolean;
+  /**
+   * Arbitrary-value Tailwind classes written in this snippet's own source.
+   * Carried on the compiled result so it rides the existing snippet cache —
+   * the classes an author writes live in the SNIPPET, not in the page that
+   * imports it, so a page-source-only scan would miss them entirely.
+   * See lib/user-utility-css.ts.
+   */
+  utilityCandidates: string[];
 }
 
 // In-memory cache for compiled snippet components
@@ -172,6 +183,12 @@ export function transpileJsx(source: string): string {
       // own identifiers, ahead of the JSX transform.
       mdxEvalGuardPlugin,
       onClickToHrefPlugin,
+      // The <span onClick={window.open}> → <a href> rewrite above keeps the
+      // author's navigation intent and always wins — it visits JSXElement,
+      // this visits the child JSXOpeningElement, and Babel reaches the parent
+      // first, so array order is not what decides it. Every handler that plugin
+      // does not claim is dropped here rather than 500-ing the including page.
+      babelStripEventHandlers,
       ['transform-react-jsx', { runtime: 'automatic', importSource: 'react' }],
     ],
     filename: 'snippet.tsx',
@@ -282,7 +299,13 @@ async function compilePlainMdxSnippet(
       // does on a page, and a snippet crash takes down every page that includes
       // it. The REHYPE pipeline is still deliberately omitted — see the note
       // above about D2 fences.
-      mdxOptions: { remarkPlugins: [remarkSvgNamespaceAttrs, remarkStyleStringToObject] },
+      // recmaStripEventHandlers for the same reason the page pipeline runs it:
+      // an author `on*` in a snippet is unserializable in RSC and 500s the
+      // whole page that includes it (see lib/strip-event-handlers.ts).
+      mdxOptions: {
+        remarkPlugins: [remarkSvgNamespaceAttrs, remarkStyleStringToObject],
+        recmaPlugins: [recmaStripEventHandlers],
+      },
     },
   });
   const PlainMdxSnippet: AnyComponent = () => content as React.ReactElement;
@@ -327,6 +350,7 @@ async function compileSnippet(
     const result: CompiledSnippet = {
       exports: { default: component },
       isClientComponent: false,
+      utilityCandidates: extractUtilityCandidates(source),
     };
     snippetComponentCache.set(cacheKey, { result, timestamp: Date.now() });
     return result;
@@ -378,7 +402,11 @@ async function compileSnippet(
     }
   }
 
-  const result: CompiledSnippet = { exports, isClientComponent };
+  const result: CompiledSnippet = {
+    exports,
+    isClientComponent,
+    utilityCandidates: extractUtilityCandidates(source),
+  };
 
   // Cache the result
   snippetComponentCache.set(cacheKey, { result, timestamp: Date.now() });
@@ -454,6 +482,71 @@ export async function loadSnippetsForIsr(
   return components;
 }
 
+/**
+ * Collect the arbitrary-value Tailwind classes used by a page — its own source
+ * plus every snippet it imports.
+ *
+ * Deliberately a separate pass rather than an extra return value from
+ * `loadSnippetsForIsr`: `compileSnippet` is cached per `project:path`, so by the
+ * time this runs during a page render every snippet is a cache hit and this
+ * costs a map lookup. Threading the candidates back through
+ * `loadSnippetsForIsr` would instead have changed a signature that
+ * `render-doc-page-parallel-helpers` and its tests both depend on.
+ *
+ * Never throws: a failure to collect styling candidates must not fail a render.
+ */
+export async function collectPageUtilityCandidates(
+  projectSlug: string,
+  mdxContent: string,
+  builtInComponents: Record<string, AnyComponent> = {},
+  // Snippet bodies live in R2, which only exists in ISR. Outside it every
+  // fetch here would throw from assertR2Configured and be swallowed below —
+  // dead work on the render critical path, and an R2-configured non-ISR
+  // environment would pull PRODUCTION snippet content into a local preview.
+  // The page's own source is still scanned either way, because the CLI dev
+  // workspace keeps project content outside the tree Tailwind scans, so
+  // skipping it would make dev render unstyled where prod renders correctly.
+  includeSnippets = true
+): Promise<string[]> {
+  const candidates = new Set<string>(extractUtilityCandidates(mdxContent));
+
+  if (includeSnippets) {
+    try {
+      const imports = extractSnippetImports(mdxContent);
+      await Promise.all(
+        imports.map(async (imp) => {
+          try {
+            const compiled = await compileSnippet(
+              projectSlug,
+              normalizeSnippetPath(imp.path),
+              builtInComponents
+            );
+            for (const c of compiled.utilityCandidates) candidates.add(c);
+          } catch {
+            // A snippet that fails to compile renders degraded anyway; its
+            // styling is not worth failing the page for.
+          }
+        })
+      );
+    } catch (error) {
+      // Not reachable today: extractSnippetImports and normalizeSnippetPath do
+      // not throw, and the Promise.all cannot reject because every element
+      // catches. Kept as a render-path guard — but logged, so a future change
+      // that does start throwing here is visible rather than silently costing
+      // every page its snippet styling.
+      logger.warn('[user-utility-css] snippet candidate scan failed', {
+        projectSlug,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  // The per-source cap inside extractUtilityCandidates does NOT bound this
+  // union: a page importing 10 snippets could otherwise reach the compiler with
+  // 10x the cap and build a cache key tens of KB long. Re-apply it to the merge.
+  return [...candidates].sort().slice(0, MAX_UTILITY_CANDIDATES);
+}
+
 /**
  * Clear the snippet component cache.
  */

package/vendored/lib/strip-event-handlers.ts

@@ -0,0 +1,159 @@
+import { visit } from 'estree-util-visit';
+import type { Program, Property } from 'estree-jsx';
+
+/**
+ * strip-event-handlers — removes author-written `on*` event-handler props from
+ * user MDX/JSX before it is rendered as a React Server Component.
+ *
+ * WHY this exists, and why it is NOT covered by the existing never-500 layers:
+ * a Server Component cannot pass a function across the RSC boundary. React
+ * throws `Event handlers cannot be passed to Client Component props` while
+ * SERIALIZING the flight payload — after every component has rendered
+ * successfully. That makes it invisible to both existing guards:
+ *
+ *   - `MdxRenderBoundary` (components/errors/MdxRenderBoundary.tsx) is a client
+ *     class boundary. It only catches throws during CLIENT render, so it cannot
+ *     stop a server-side serialization failure. The response is still HTTP 500.
+ *     Its `fallback` prop IS serialized alongside `children`, so the browser
+ *     shows "⚠ This content couldn't be displayed (page content)" while the
+ *     status is 500 — content degrades, the status does not.
+ *   - `recmaGuardExpressions` wraps author expressions in a try/catch IIFE, but
+ *     `onSubmit={() => …}` does not throw when EVALUATED — it returns a function
+ *     perfectly well. The guard hands that function straight to the serializer.
+ *
+ * So, exactly as the bare-`{x, y}` class before it, the only RSC-safe fix is to
+ * neutralize the construct at COMPILE time. Observed in production on
+ * 2026-08-31: one customer page rendering a snippet with `<form onSubmit={…}>`
+ * returned 500 for three weeks.
+ *
+ * WHAT is removed: any prop whose name matches `/^on[A-Z]/` — React's own
+ * event-handler naming convention, and the same test React applies when it
+ * decides a prop is an event handler. The element and all its other props and
+ * children render normally; only the dead handler goes. This loses nothing that
+ * ever worked: an author `on*` in server-rendered MDX has never been functional,
+ * it has only ever been a 500.
+ *
+ * Two plugins because user content reaches React down two different pipelines:
+ *   - `recmaStripEventHandlers` — the MDX compile path (page bodies and
+ *     plain-markdown snippets), operating on compiled `_jsx(tag, props)` calls.
+ *   - `babelStripEventHandlers` — the Babel path (`export`-style JSX snippets
+ *     and inline page components), operating on JSX attributes before the JSX
+ *     transform runs.
+ *
+ * RESIDUAL SCOPE — three shapes still reach the serializer and still 500. All
+ * three were reproduced against the real flight writer
+ * (`react-server-dom-webpack/server.edge` under `--conditions=react-server`):
+ *
+ *   1. A handler spread from an IDENTIFIER: `<form {...handlers} />`. Not
+ *      statically visible, so it survives. Note an object-LITERAL spread
+ *      (`<div {...{onClick: f}} />`) is NOT in this class — the MDX compiler
+ *      flattens it into the props ObjectExpression, where this plugin sees and
+ *      removes it like any other property.
+ *   2. A computed key: `<div {...{['on' + 'Click']: f}} />` — `propKeyName`
+ *      declines to guess at computed keys.
+ *   3. A function-valued prop whose name is NOT `on[A-Z]` — `render={() => …}`
+ *      or `children={() => …}`. These fail with a DIFFERENT React error
+ *      ("Functions cannot be passed directly to Client Components" /
+ *      "Functions are not valid as a child"), so they are a separate class
+ *      rather than a hole in this one. Stripping every function-valued prop
+ *      would close it, but would also strip callbacks that a purely
+ *      server-rendered inline component legitimately consumes without ever
+ *      serializing them — so that is deliberately NOT done here.
+ *
+ * None of the three has been observed in customer content; `on[A-Z]` is the
+ * shape authors actually reach for when they paste React into MDX.
+ */
+
+/**
+ * React's own rule for "this prop is an event handler": `on` followed by an
+ * uppercase letter. Deliberately NOT a fixed list of known DOM events — a
+ * custom `onFoo` on a component prop is just as unserializable as `onClick`,
+ * and a list would silently miss every event React adds later.
+ *
+ * The uppercase requirement is what keeps legitimate props safe: `once`, `only`
+ * and `onboarding` are ordinary words, not handlers.
+ */
+const EVENT_HANDLER_PROP = /^on[A-Z]/;
+
+export function isEventHandlerProp(name: string): boolean {
+  return EVENT_HANDLER_PROP.test(name);
+}
+
+/** JSX factory callees emitted by the MDX/React compilers. */
+const JSX_CALLEES = new Set(['_jsx', '_jsxs', '_jsxDEV']);
+
+/** The identifier/string name of a `_jsx` prop key (`onClick`, `data-v`, …). */
+function propKeyName(prop: Property): string | undefined {
+  const key = prop.key;
+  // A computed key (`{[expr]: fn}`) has no statically-known name, so it cannot
+  // be classified — left in place rather than guessed at.
+  if (prop.computed) return undefined;
+  if (key.type === 'Identifier') return key.name;
+  if (key.type === 'Literal' && typeof key.value === 'string') return key.value;
+  return undefined;
+}
+
+/**
+ * recma plugin — drops `on*` properties from every compiled `_jsx(tag, {…})`
+ * props object.
+ *
+ * Runs AFTER `recmaCompoundComponents` (so elements that plugin synthesizes are
+ * also cleaned) and BEFORE `recmaGuardExpressions` (no point wrapping an
+ * expression that is about to be deleted).
+ */
+export function recmaStripEventHandlers() {
+  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;
+
+      props.properties = props.properties.filter((prop) => {
+        // A SpreadElement here is an identifier spread (`{...handlers}`) — an
+        // object-literal spread was already flattened into this same properties
+        // list by the MDX compiler. Structural, so keep it (RESIDUAL SCOPE 1).
+        if (prop.type !== 'Property') return true;
+        const name = propKeyName(prop);
+        return !name || !isEventHandlerProp(name);
+      });
+    });
+  };
+}
+
+/**
+ * Babel plugin — drops `on*` JSX attributes before the JSX transform.
+ *
+ * Coexists with `onClickToHrefPlugin` in `transpileJsx`, which rewrites
+ * `<span onClick={() => window.open(url, '_self')}>` into `<a href>` to preserve
+ * the author's navigation intent. That rewrite always wins, and NOT because of
+ * plugin array order: it visits `JSXElement` while this visits the child
+ * `JSXOpeningElement`, and Babel reaches a parent before its child. Whatever it
+ * does not claim is stripped here instead of 500-ing. It is still listed after
+ * that plugin, so the guarantee survives if this ever moves to a `JSXElement`
+ * visitor.
+ */
+export function babelStripEventHandlers() {
+  return {
+    name: 'jd-strip-event-handlers',
+    visitor: {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      JSXOpeningElement(path: any) {
+        path.node.attributes = path.node.attributes.filter(
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (attr: any) =>
+            !(
+              attr.type === 'JSXAttribute' &&
+              attr.name?.type === 'JSXIdentifier' &&
+              isEventHandlerProp(attr.name.name)
+            ),
+        );
+      },
+    },
+  };
+}