jamdesk 1.1.201 → 1.1.203

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,250 @@
+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);
+}
+
+/**
+ * Attributes that only mean something on a `<form>`. When a form is downgraded
+ * to a `<div>` (see `neutralizeDeadForm`) these would become invalid DOM
+ * attributes and draw React warnings, so they go with it.
+ */
+const FORM_ONLY_PROPS = new Set([
+  'method',
+  'encType',
+  'target',
+  'noValidate',
+  'acceptCharset',
+]);
+
+/**
+ * A `<form>` whose only submit path was an `on*` handler we just stripped, and
+ * which has no `action`, is downgraded to a `<div>`.
+ *
+ * WHY, and why the tag rather than the submit button:
+ * with the handler gone the browser falls back to NATIVE submission, and with
+ * no `action` that targets the current URL — so a reader who fills the form in
+ * is navigated to `?<field>=<whatever they typed>`, the page reloads, their
+ * input goes nowhere, and their free text is left in the URL, in history, and
+ * in CDN logs. That is strictly worse than the form doing nothing.
+ *
+ * Observed in production: a customer's feedback snippet POSTed JSON to their
+ * own Lambda from `onSubmit`, whose FIRST statement was `e.preventDefault()`.
+ * Stripping the handler removed the very thing suppressing the native submit.
+ *
+ * Neutralizing the submit BUTTON would not close it. HTML implicit submission
+ * fires on Enter in a form with a single text field whether or not a submit
+ * button exists, so the form element itself has to go. Children render exactly
+ * as before; only the submission path disappears.
+ *
+ * Deliberately narrow: it fires only when a handler was actually removed AND
+ * there is no `action`. A form with an `action` still works natively and is
+ * left alone, and a form that never had a handler is not this bug.
+ */
+
+/** 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;
+
+      const tag = node.arguments[0];
+      const isForm =
+        tag && tag.type === 'Literal' && tag.value === 'form';
+      let strippedHandler = false;
+      let hasAction = false;
+
+      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);
+        if (!name) return true;
+        if (name === 'action') hasAction = true;
+        if (!isEventHandlerProp(name)) return true;
+        strippedHandler = true;
+        return false;
+      });
+
+      if (isForm && strippedHandler && !hasAction) {
+        (tag as { value: string; raw?: string }).value = 'div';
+        delete (tag as { raw?: string }).raw;
+        props.properties = props.properties.filter((prop) => {
+          if (prop.type !== 'Property') return true;
+          const name = propKeyName(prop);
+          return !name || !FORM_ONLY_PROPS.has(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) {
+        const isForm =
+          path.node.name?.type === 'JSXIdentifier' &&
+          path.node.name.name === 'form';
+        let strippedHandler = false;
+        let hasAction = false;
+
+        path.node.attributes = path.node.attributes.filter(
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (attr: any) => {
+            if (
+              attr.type !== 'JSXAttribute' ||
+              attr.name?.type !== 'JSXIdentifier'
+            ) {
+              return true;
+            }
+            if (attr.name.name === 'action') hasAction = true;
+            if (!isEventHandlerProp(attr.name.name)) return true;
+            strippedHandler = true;
+            return false;
+          },
+        );
+
+        if (!isForm || !strippedHandler || hasAction) return;
+
+        // Downgrade to <div> — see neutralizeDeadForm above. The closing tag
+        // is renamed too. Under the `react` preset that lowers JSX to `_jsx`
+        // calls this is unobservable (the closing element is discarded), so it
+        // reads like dead code — but leaving a mismatched AST would emit
+        // `<div>…</form>` for any consumer that preserves JSX, and a test
+        // transpiles with JSX preserved specifically to pin it.
+        path.node.name.name = 'div';
+        const closing = path.parent?.closingElement;
+        if (closing?.name?.type === 'JSXIdentifier') closing.name.name = 'div';
+        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' &&
+              FORM_ONLY_PROPS.has(attr.name.name)
+            ),
+        );
+      },
+    },
+  };
+}