jamdesk 1.1.205 → 1.1.207

package/vendored/components/mdx/CodeGroup.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { ReactNode, Children, isValidElement, memo } from 'react';
+import { ReactNode, ReactElement, Children, Fragment, cloneElement, isValidElement, memo } from 'react';
 import { CodePanel, CodePanelTab } from '../ui/CodePanel';
 import { formatLanguage } from '@/lib/code-utils';
 
@@ -11,6 +11,13 @@ interface CodeGroupProps {
 // Loose shape of `pre`/`code` props from MDX/Shiki — only the fields we read.
 type PreProps = {
   'data-language'?: string;
+  'data-nocopy'?: string;
+  // The author's own fence meta, when rehypeRestoreDataTitle classified it as
+  // a language/tool token and so declined to promote it to data-title.
+  'data-language-label'?: string;
+  // rehypeCodeMeta/rehypeRestoreDataTitle mirror the parsed fence title onto
+  // the pre as well as the nested code element.
+  'data-title'?: string;
   children?: ReactNode;
 };
 type CodeProps = {
@@ -47,13 +54,25 @@ function getRawLanguage(child: ReactNode): string | undefined {
 }
 
 /**
- * Extract title from a pre element's code child
- * Returns data-title attribute if present (e.g., title="utils.js")
+ * Extract the title of a code block (e.g., title="utils.js").
+ *
+ * The pre's own data-title is checked FIRST because it is the only one that
+ * survives a real render: rehypeCodeMeta stamps data-title on both the pre
+ * and its nested code element, but Shiki then rebuilds the pre/code subtree
+ * from scratch and only rehypeRestoreDataTitle's pre-level attribute comes
+ * out the other side. Reading solely off the code element (as this did
+ * before) returned undefined for every compiled-MDX block — invisible while
+ * the enclosing filter matched nothing, and a dropped caption the moment it
+ * did. The code-element lookup stays as the fallback for hand-built
+ * children, which carry the title there.
  */
 function getTitle(child: ReactNode): string | undefined {
   if (!isValidElement(child)) return undefined;
 
   const childProps = child.props as PreProps;
+  const preTitle = childProps['data-title'];
+  if (preTitle) return preTitle;
+
   const codeElement = childProps?.children;
 
   if (!isValidElement(codeElement)) return undefined;
@@ -62,15 +81,40 @@ function getTitle(child: ReactNode): string | undefined {
   return codeProps['data-title'];
 }
 
+/**
+ * Whether a pre element carries the nocopy flag. Read directly off the pre's
+ * own props — data-nocopy is set on the PRE element itself by the Shiki
+ * transformer (shiki-transformers.ts, transformerLineFeatures().pre()), the
+ * same place getRawLanguage reads data-language from, not getTitle's
+ * off-the-nested-code-element lookup.
+ */
+function getNocopy(child: ReactNode): boolean {
+  if (!isValidElement(child)) return false;
+
+  const childProps = child.props as PreProps;
+  return childProps['data-nocopy'] !== undefined;
+}
+
 /**
  * Extract tab label from a pre element
- * Priority: data-language > data-meta > className language-*
+ * Priority: data-language-label > data-language > data-meta > className language-*
+ *
+ * data-language-label comes first because it is what the AUTHOR typed after
+ * the language (```bash npm), and in a CodeGroup the fence meta is the tab
+ * label — Mintlify's semantics. Falling straight through to data-language
+ * instead rendered `npm`, `yarn` and `bun` all as "cURL" (lib/code-utils.ts
+ * maps bash -> cURL for RequestExample, where it is correct), so 75 groups in
+ * projects/ showed two or three indistinguishable tabs and a reader could not
+ * pick npm over yarn.
  */
 function getTabLabel(child: ReactNode): string {
   if (!isValidElement(child)) return 'Code';
 
   const childProps = child.props as PreProps;
 
+  const authoredLabel = childProps['data-language-label'];
+  if (authoredLabel) return authoredLabel;
+
   // Check for data-language on the pre element (added by Shiki transformer)
   const preLanguage = childProps['data-language'];
   if (preLanguage) {
@@ -82,7 +126,11 @@ function getTabLabel(child: ReactNode): string {
 
   const codeProps = codeElement.props as CodeProps;
 
-  // Check for title in data-meta or meta props (e.g., "Success Response")
+  // Check for title in data-meta or meta props (e.g., "Success Response").
+  // Reachable only for hand-built children: compiled MDX never gets here,
+  // because Shiki rebuilds the code subtree and drops rehypeCodeMeta's
+  // code-level data-meta, exactly as it drops code-level data-title (see
+  // getTitle above). Kept so JSX callers behave as they always have.
   const metaString = codeProps['data-meta'] || codeProps.meta || '';
   if (metaString) {
     return metaString;
@@ -99,33 +147,133 @@ function getTabLabel(child: ReactNode): string {
   return 'Code';
 }
 
+/**
+ * Property name stamped on MDXComponents' code-fence renderer (MdxPreBlock).
+ * Keep this string literal identical to the marker assignment just below
+ * MdxPreBlock in MDXComponents.tsx — the long doc comment above that
+ * function explains why the two files agree on a marker property instead of
+ * this file importing MdxPreBlock for a `===` identity check.
+ */
+const CODE_FENCE_MARKER = 'jdCodeFenceMarker';
+
+/**
+ * Unwrap one <CodeGroup> child down to its code-fence element, or null when
+ * the child is not a fence at all.
+ *
+ * Two layers have to be peeled, and the pre-fix filter (`child.type ===
+ * 'pre'`) saw through neither, which is why no <CodeGroup> in production
+ * ever rendered a tab strip:
+ *
+ *  1. Compiled MDX hands each fence over wrapped in a single-child
+ *     Fragment, not as the fence element directly.
+ *  2. Inside that Fragment the element's `type` is `_components.pre` — in
+ *     this app the MdxPreBlock *function* — never the string 'pre'.
+ *
+ * The literal-'pre' case is kept because it costs nothing and leaves
+ * callers that hand-build host elements behaving exactly as before.
+ */
+function unwrapCodeFence(child: ReactNode): ReactElement | null {
+  if (!isValidElement(child)) return null;
+
+  const { type } = child;
+  if (type === 'pre') return child;
+  if (
+    typeof type === 'function' &&
+    (type as unknown as Record<string, unknown>)[CODE_FENCE_MARKER] === true
+  ) {
+    return child;
+  }
+
+  // Only a *single-child* Fragment is transparent here. A multi-child one
+  // carries content besides the fence, which must not be silently dropped.
+  if (type === Fragment) {
+    const inner = Children.toArray((child.props as { children?: ReactNode }).children);
+    return inner.length === 1 ? unwrapCodeFence(inner[0]) : null;
+  }
+
+  return null;
+}
+
+/**
+ * Children that are neither code fences nor the blank text nodes MDX emits
+ * between block children. These are rendered after the panel so a
+ * <CodeGroup> cannot silently eat authored prose: before this fix such
+ * content was visible (the whole group fell back to a plain <div>), so
+ * dropping it now would be a content regression rather than a no-op.
+ */
+function isRenderableExtra(child: ReactNode): boolean {
+  if (unwrapCodeFence(child) !== null) return false;
+  if (typeof child === 'string') return child.trim().length > 0;
+  return child !== null && child !== undefined && typeof child !== 'boolean';
+}
+
+/**
+ * Tab content for one fence.
+ *
+ * A fence carrying data-title makes MdxPreBlock take its titled branch and
+ * render a whole CodePanel of its own. Dropped straight into a tab that
+ * would be a panel nested inside a panel — two borders, two headers, two
+ * copy buttons. Strip the attribute so MdxPreBlock yields the bare <pre>
+ * the panel body expects; the title is not lost, it moves to the tab label
+ * (see getTabLabel's caller below).
+ */
+function toTabContent(block: ReactElement): ReactNode {
+  if ((block.props as PreProps)['data-title'] === undefined) return block;
+  return cloneElement(block as ReactElement<Record<string, unknown>>, { 'data-title': undefined });
+}
+
 /**
  * CodeGroup wraps multiple code blocks in a tabbed interface.
  * Uses the shared CodePanel component for consistent styling.
  */
 export const CodeGroup = memo(function CodeGroup({ children }: CodeGroupProps) {
   // Extract code blocks from children
-  const codeBlocks = Children.toArray(children).filter(
-    (child) => isValidElement(child) && child.type === 'pre'
-  );
+  const allChildren = Children.toArray(children);
+  const codeBlocks = allChildren
+    .map(unwrapCodeFence)
+    .filter((block): block is ReactElement => block !== null);
 
   if (codeBlocks.length === 0) {
     return <div>{children}</div>;
   }
 
+  const extras = allChildren.filter(isRenderableExtra);
+
+  // Extract title from first code block (only shown for single blocks)
+  const title = codeBlocks.length === 1 ? getTitle(codeBlocks[0]) : undefined;
+
   // Convert code blocks to CodePanel tabs
   // Note: Icons disabled by default - can be enabled via docs.json in future
   const tabs: CodePanelTab[] = codeBlocks.map((block) => {
     const language = getRawLanguage(block);
+    // A single block already shows its title as the panel caption above the
+    // strip, so labelling its one tab with the same string would just print
+    // the filename twice. Multi-block groups have no caption, so the title
+    // is the tab label — which is also the label Mintlify documents
+    // (`\`\`\`javascript helloWorld.js` → a "helloWorld.js" tab) and the only
+    // place the filename still appears once toTabContent strips it.
+    const fenceTitle = codeBlocks.length === 1 ? undefined : getTitle(block);
     return {
-      label: getTabLabel(block),
-      content: block as ReactNode,
+      label: fenceTitle ?? getTabLabel(block),
+      content: toTabContent(block),
       language,
+      // Per tab, not per panel. The earlier panel-wide flag had to be gated
+      // on `codeBlocks.length === 1` so a nocopy fence could not hide copy
+      // for its unflagged siblings — which meant nocopy did nothing at all
+      // inside a multi-fence group, where the pre-tab-strip <div> path used
+      // to suppress it (CodeBlockCopyButton skips pre.shiki[data-nocopy]).
+      hideCopy: getNocopy(block),
     };
   });
 
-  // Extract title from first code block (only shown for single blocks)
-  const title = codeBlocks.length === 1 ? getTitle(codeBlocks[0]) : undefined;
+  const panel = <CodePanel tabs={tabs} title={title} className="my-6" enableFullscreen />;
 
-  return <CodePanel tabs={tabs} title={title} className="my-6" enableFullscreen />;
+  if (extras.length === 0) return panel;
+
+  return (
+    <>
+      {panel}
+      {extras}
+    </>
+  );
 });

package/vendored/components/mdx/MDXComponents.tsx

@@ -179,6 +179,98 @@ function isVideoUrl(src: string | undefined): boolean {
   return VIDEO_EXTENSIONS_IMG.some(ext => pathOnly.toLowerCase().endsWith(ext));
 }
 
+/**
+ * Renders a fenced code block. Marked with CODE_FENCE_MARKER (a static
+ * property, not identity) so CodeGroup.tsx can recognize its own children —
+ * compiled MDX always passes the *component function* as `_components.pre`
+ * (never the string 'pre'), so CodeGroup's `Children.toArray(children)`
+ * sees unresolved elements whose `.type` is this function reference, not
+ * its rendered output. Verified against a real compile(): each fence also
+ * arrives wrapped in a single-child Fragment, so CodeGroup unwraps one
+ * layer before testing the marker.
+ *
+ * A marker property, not a direct import of this function for `===`
+ * comparison, on purpose: MDXComponents already imports CodeGroup (to
+ * register it as the <CodeGroup> tag below), so CodeGroup importing
+ * MDXComponents back would be circular; and reference equality would be
+ * fragile across the dashboard's and CLI's separately vendored copies of
+ * this file if either ever mounted more than one instance. Keep this
+ * function's marker assignment (just below its definition) and
+ * CodeGroup.tsx's CODE_FENCE_MARKER string literal identical — both files
+ * are always vendored together as one unit (vendor-builder.js and
+ * cli/scripts/vendor.js both copy the whole components/ directory), so they
+ * can't drift apart from a partial vendor, only from an un-mirrored edit.
+ */
+function MdxPreBlock({
+  children,
+  'data-title': dataTitle,
+  'data-nocopy': dataNocopy,
+  ...props
+}: HTMLAttributes<HTMLPreElement> & { 'data-title'?: string; 'data-nocopy'?: string }) {
+  const language = getCodeLanguage(props, children);
+
+  // Check for mermaid diagrams - render with Mermaid component
+  if (language === 'mermaid') {
+    const diagramCode = extractTextFromChildren(children);
+    return (
+      <>
+        <Mermaid>{diagramCode}</Mermaid>
+        {/* Crawler / AI fallback: the client-only SVG leaves the server HTML empty.
+            Use <noscript>, NOT sr-only: a JS-disabled crawler reads it, while users
+            with JS (and screen readers) get the real rendered diagram and never see
+            duplicate text. */}
+        {diagramCode.trim() && (
+          <noscript>
+            <pre>{diagramCode}</pre>
+          </noscript>
+        )}
+      </>
+    );
+  }
+
+  // Check for HTTP code blocks - render with special styling
+  if (language === 'http') {
+    const codeText = extractTextFromChildren(children);
+    const parsed = parseHttpRequest(codeText);
+    if (parsed) {
+      return <HttpCodeBlock method={parsed.method} url={parsed.url} />;
+    }
+  }
+
+  // If no title, render the pre element directly
+  // Copy button is added by CodeBlockCopyButton client component, which
+  // reads data-nocopy straight off this DOM node — keep it in place here
+  // (unlike the CodePanel path below, where CodePanel's own hideCopy prop
+  // does the suppressing instead).
+  if (!dataTitle) {
+    return (
+      <pre {...props} data-nocopy={dataNocopy}>
+        {children}
+      </pre>
+    );
+  }
+
+  // Wrap in CodePanel to show the title. `data-nocopy` is deliberately left
+  // off this inner <pre> — CodeBlockCopyButton skips anything inside
+  // [data-code-panel] regardless, and CodePanel's own copy button(s) are
+  // suppressed via `hideCopy` instead.
+  const preElement = <pre {...props}>{children}</pre>;
+
+  return (
+    <CodePanel
+      tabs={[{ label: language, content: preElement, language }]}
+      title={dataTitle}
+      hideTabs={true}
+      className="my-6"
+      enableFullscreen
+      hideCopy={dataNocopy !== undefined}
+    />
+  );
+}
+// See the doc comment above MdxPreBlock — must match CodeGroup.tsx's
+// CODE_FENCE_MARKER string literal exactly.
+(MdxPreBlock as unknown as { jdCodeFenceMarker?: true }).jdCodeFenceMarker = true;
+
 export const MDXComponents = {
   Card,
   // Callout components
@@ -411,56 +503,7 @@ export const MDXComponents = {
     />
   ),
   // Custom pre component to wrap code blocks with titles in CodePanel
-  pre: ({ children, 'data-title': dataTitle, ...props }: HTMLAttributes<HTMLPreElement> & { 'data-title'?: string }) => {
-    const language = getCodeLanguage(props, children);
-
-    // Check for mermaid diagrams - render with Mermaid component
-    if (language === 'mermaid') {
-      const diagramCode = extractTextFromChildren(children);
-      return (
-        <>
-          <Mermaid>{diagramCode}</Mermaid>
-          {/* Crawler / AI fallback: the client-only SVG leaves the server HTML empty.
-              Use <noscript>, NOT sr-only: a JS-disabled crawler reads it, while users
-              with JS (and screen readers) get the real rendered diagram and never see
-              duplicate text. */}
-          {diagramCode.trim() && (
-            <noscript>
-              <pre>{diagramCode}</pre>
-            </noscript>
-          )}
-        </>
-      );
-    }
-
-    // Check for HTTP code blocks - render with special styling
-    if (language === 'http') {
-      const codeText = extractTextFromChildren(children);
-      const parsed = parseHttpRequest(codeText);
-      if (parsed) {
-        return <HttpCodeBlock method={parsed.method} url={parsed.url} />;
-      }
-    }
-
-    // If no title, render the pre element directly
-    // Copy button is added by CodeBlockCopyButton client component
-    if (!dataTitle) {
-      return <pre {...props}>{children}</pre>;
-    }
-
-    // Wrap in CodePanel to show the title
-    const preElement = <pre {...props}>{children}</pre>;
-
-    return (
-      <CodePanel
-        tabs={[{ label: language, content: preElement, language }]}
-        title={dataTitle}
-        hideTabs={true}
-        className="my-6"
-        enableFullscreen
-      />
-    );
-  },
+  pre: MdxPreBlock,
   // Inline code styling is done via CSS in base.css (.prose :not(pre) > code)
   table: (props: TableHTMLAttributes<HTMLTableElement>) => (
     <div className="overflow-x-auto my-6">

package/vendored/components/navigation/Header.tsx

@@ -13,6 +13,7 @@ import { ThemeToggle } from '@/components/theme/ThemeToggle';
 import { LazySearchModal as SearchModal } from '@/components/search/LazySearchModal';
 import { DefaultLogo } from './DefaultLogo';
 import { LanguageSelector } from './LanguageSelector';
+import { ThemePreviewPicker } from './ThemePreviewPicker';
 import LogoutButton from './LogoutButton';
 import { resolveNavigation } from '@/lib/navigation-resolver';
 import { getIconClass } from '@/lib/icon-utils';
@@ -555,6 +556,12 @@ export function Header({ config, layout = 'header-logo', tabsPosition: tabsPosit
                 renders nothing until the client confirms an active session. */}
             {config.auth?.jwt?.enabled === true && <LogoutButton />}
 
+            {/* Theme preview picker — jamdesk-docs only. The component returns
+                null unless the ThemePreviewProvider enables it, and carries its
+                own `hidden lg:block`, so there is no stray wrapper on customer
+                sites. */}
+            <ThemePreviewPicker />
+
             {/* Theme toggle - hidden on mobile since it's in the sidebar menu.
                 Also hidden when appearance.strict pins users to the configured mode. */}
             {!config.appearance?.strict && (

package/vendored/components/navigation/LanguageSelector.tsx

@@ -13,6 +13,7 @@ import {
   extractLanguageFromPath,
   toHreflang,
 } from '@/lib/language-utils';
+import { LANGUAGE_COOKIE } from '@/lib/language-cookie';
 import { useLinkPrefix } from '@/lib/link-prefix-context';
 import { useProjectSlug } from '@/lib/project-slug-context';
 import { getUiStrings } from '@/lib/ui-strings';
@@ -80,6 +81,40 @@ export function LanguageSelector({
   // Find actual default language from config
   const actualDefault = displayedLanguages.find((l) => l.isDefault)?.code || defaultLanguage;
 
+  // One-time migration: a preference saved before server-side routing existed
+  // lives only in localStorage, so the edge cannot see it and would negotiate
+  // over the top of it. Seed the cookie from it once. saveLanguagePreference
+  // writes both stores, so this converges after a single page view and is a
+  // no-op on every visit after that.
+  //
+  // Ordering, stated plainly: this effect runs AFTER the page has already
+  // loaded, which is AFTER any server-side 307 has already picked a language
+  // and pinned its own cookie — no client code can run before a redirect it
+  // hasn't been GET to yet. So a visitor with a stale localStorage
+  // preference and no cookie can land on one wrong-language page (server
+  // negotiated from Accept-Language, disagreeing with their saved choice);
+  // this effect then corrects the cookie on that same page. The wrong
+  // language is shown exactly once — their NEXT visit to the root reads the
+  // corrected cookie (decideLanguageRedirect prioritizes cookie over
+  // Accept-Language) and self-heals. See
+  // __tests__/lib/language-cookie-self-heal.test.ts. Inherent, not a bug —
+  // do not try to make this effect win a race it structurally cannot enter.
+  useEffect(() => {
+    const saved = getLanguagePreference(projectSlug);
+    if (!saved) return;
+    let current: string | undefined;
+    try {
+      current = document.cookie
+        .split('; ')
+        .find((c) => c.startsWith(`${LANGUAGE_COOKIE}=`))
+        ?.split('=')[1];
+    } catch {
+      return; // cookies unavailable — nothing to migrate into
+    }
+    if (current !== saved) saveLanguagePreference(saved, projectSlug);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- mount-only by design; see comment above
+  }, []);
+
   // Check localStorage preference on mount and redirect if needed.
   // Intentionally mount-only: re-running on pathname/language changes would
   // fight the user's in-session navigation choices (they may have explicitly

package/vendored/components/navigation/ThemePreviewPicker.tsx

@@ -0,0 +1,197 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { useOnClickOutside } from '@/hooks/useOnClickOutside';
+import { useLinkPrefix } from '@/lib/link-prefix-context';
+import { useThemePreview } from '@/lib/theme-preview-context';
+import { THEME_PREVIEW_COOKIE } from '@/lib/theme-preview';
+import { getAllThemes, type ThemeName } from '@/themes';
+
+/**
+ * Jamdesk-only affordance: re-skins jamdesk.com/docs with any built-in theme so
+ * prospects can see all four on a real docs site.
+ *
+ * The gate is server-side (lib/theme-preview.ts decides whether the provider is
+ * enabled); this component ALSO self-guards on `enabled` so a mistake in
+ * Header's conditional can never leak it onto a customer site.
+ *
+ * Strings are English-only by design. jamdesk-docs has fr/es locales, but the
+ * only prose here is "Reset to default" and "Default" — everything else is a
+ * proper noun — and adding entries to lib/ui-strings.ts for a sales affordance
+ * isn't worth the churn across every locale.
+ */
+export function ThemePreviewPicker() {
+  const { enabled, activeTheme, defaultTheme } = useThemePreview();
+  const linkPrefix = useLinkPrefix();
+  const [isOpen, setIsOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const listRef = useRef<HTMLUListElement>(null);
+
+  // Every close path but a theme selection runs through here. A click-outside
+  // would otherwise unmount the focused option and drop focus to <body>, so
+  // the visitor's next Tab restarts at the top of the document. Synchronous on
+  // purpose: this runs during the mousedown dispatch, so a click that lands on
+  // something focusable still ends up there — the browser's own focus default
+  // wins afterwards, which is what it should do.
+  function closeAndRestoreFocus() {
+    const hadFocus = !!containerRef.current?.contains(document.activeElement);
+    setIsOpen(false);
+    if (hadFocus) buttonRef.current?.focus();
+  }
+
+  useOnClickOutside(containerRef, closeAndRestoreFocus, isOpen);
+
+  // Move focus onto the active option when the menu opens. Without this the
+  // trigger keeps focus and Tab is the only way forward — and an earlier cut of
+  // this component closed the menu on Tab (copied from LanguageSelector, where
+  // that is safe only because ArrowUp/Down have already moved focus into the
+  // list), which left the widget keyboard-inoperable: WCAG 2.1.1.
+  useEffect(() => {
+    if (!isOpen) return;
+    const options = listRef.current?.querySelectorAll<HTMLElement>('[role="option"]');
+    if (!options?.length) return;
+    const active = Array.from(options).find((o) => o.getAttribute('aria-selected') === 'true');
+    (active ?? options[0]).focus();
+  }, [isOpen]);
+
+  if (!enabled) return null;
+
+  // Escape only. Arrow-key roving focus is deliberately NOT copied from
+  // LanguageSelector: its options are a customer-configurable list, whereas
+  // this is a fixed four-row Jamdesk-only affordance whose rows are ordinary
+  // buttons that Tab already walks. Escape must stay — it is the way back out
+  // of a menu focus has just been moved into.
+  function handleKeyDown(e: React.KeyboardEvent) {
+    if (e.key === 'Escape') closeAndRestoreFocus();
+  }
+
+  // Tabbing past the last row leaves the widget; close behind it. This is what
+  // LanguageSelector's Tab branch achieved, without eating the Tab that is this
+  // component's only way INTO the option list.
+  function handleFocusOut(e: React.FocusEvent) {
+    // A null relatedTarget means focus landed on <body>, NOT that focus left
+    // the widget — and since the menu always opens with focus inside itself,
+    // that blur comes from inside. Safari and Firefox-on-macOS produce it on
+    // every mousedown over a <button>; Chrome produces it for a mousedown on
+    // this panel's own padding or its divider band. Closing there unmounts the
+    // row before its click can land, so no theme is ever applied. Do not
+    // "simplify" this branch away: genuine outside-pointer closes are
+    // useOnClickOutside's job, and Escape and Tab both supply a real
+    // relatedTarget. The only thing given up is close-on-window-blur.
+    if (!(e.relatedTarget instanceof Element)) return;
+    if (!e.currentTarget.contains(e.relatedTarget)) setIsOpen(false);
+  }
+
+  // `null` clears the cookie. Path mirrors the docs prefix so the cookie is
+  // scoped to /docs on jamdesk.com and to / on jamdesk-docs.jamdesk.app.
+  function applyTheme(name: ThemeName | null) {
+    const path = linkPrefix || '/';
+    // SESSION cookie on the set path — no Max-Age, so the preview dies with the
+    // browser. The picker is desktop-only (`hidden lg:block`), so a persisted
+    // preview would follow a visitor to mobile with no affordance to reset it.
+    // The CLEAR path is the opposite and must stay explicit: `Max-Age=0` is
+    // what expires an existing cookie, and omitting it there would leave the
+    // preview in place.
+    const expiry = name === null ? '; Max-Age=0' : '';
+    // `Secure` means the browser silently DROPS this cookie over plain http, so
+    // the picker looks inert when QA'd on http://localhost — use https or a
+    // deployed host.
+    document.cookie =
+      `${THEME_PREVIEW_COOKIE}=${name ?? ''}; Path=${path}${expiry}; SameSite=Lax; Secure`;
+    // Close first: the reload is not instant, and an open menu left showing the
+    // previous selection reads as a dead click.
+    setIsOpen(false);
+    // Full reload — the theme is applied by the server render (CSS variables,
+    // font class and layout variant all key off config.theme), so there is no
+    // client-side state to update.
+    window.location.reload();
+  }
+
+  const allThemes = getAllThemes();
+  const activeDisplayName = allThemes.find((t) => t.name === activeTheme)?.displayName ?? '';
+
+  return (
+    <div
+      ref={containerRef}
+      className="relative hidden lg:block"
+      onKeyDown={handleKeyDown}
+      onBlur={handleFocusOut}
+    >
+      <button
+        ref={buttonRef}
+        onClick={() => {
+          setIsOpen(!isOpen);
+          // Closing unmounts the focused option. Safari does not focus a
+          // button on mousedown, so without this focus would land on <body>.
+          // Mirrors Prompt.tsx's trigger.
+          if (isOpen) buttonRef.current?.focus();
+        }}
+        aria-expanded={isOpen}
+        aria-haspopup="listbox"
+        aria-label={`Preview a theme: ${activeDisplayName}`}
+        className="flex items-center gap-2 rounded-lg px-2 py-1.5 cursor-pointer transition-colors text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-bg-tertiary)]"
+      >
+        <i
+          className="fa-solid fa-palette text-[12px] text-[var(--color-text-tertiary)]"
+          aria-hidden="true"
+        />
+        <i
+          className={`fa-solid fa-chevron-down text-[10px] text-[var(--color-text-tertiary)] transition-transform ${isOpen ? 'rotate-180' : ''}`}
+          aria-hidden="true"
+        />
+      </button>
+
+      {isOpen && (
+        <div
+          className="absolute right-0 top-full mt-1 z-50 min-w-[190px] py-1 bg-[var(--color-bg-primary)] border border-[var(--color-border)] rounded-lg"
+          style={{ boxShadow: 'var(--shadow-lg)' }}
+        >
+          <ul ref={listRef} role="listbox" aria-label="Preview a theme">
+            {allThemes.map((theme) => {
+              const isActive = theme.name === activeTheme;
+              return (
+                <li key={theme.name}>
+                  <button
+                    role="option"
+                    aria-selected={isActive}
+                    onClick={() => applyTheme(theme.name as ThemeName)}
+                    className="w-full flex items-center justify-between gap-3 px-3 py-2 text-left text-sm cursor-pointer text-[var(--color-text-primary)] hover:bg-[var(--color-bg-tertiary)]"
+                  >
+                    <span>{theme.displayName}</span>
+                    <span className="flex items-center gap-2">
+                      {theme.name === defaultTheme && (
+                        <span className="text-xs text-[var(--color-text-tertiary)]">Default</span>
+                      )}
+                      {isActive && (
+                        <i
+                          className="fa-solid fa-check text-[11px] text-[var(--color-accent)]"
+                          aria-hidden="true"
+                        />
+                      )}
+                    </span>
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+
+          {/* Outside the <ul>: a `role="listbox"` may only own `option` and
+              `group` children, and a reset action is neither. Nesting it as a
+              bare <li><button> would put a `listitem` inside a listbox, which
+              screen readers drop or mis-announce. LanguageSelector — the
+              pattern this component mirrors — has no extra row, so there is no
+              existing precedent to copy here. */}
+          <div className="mt-1 pt-1 border-t border-[var(--color-border)]">
+            <button
+              onClick={() => applyTheme(null)}
+              className="w-full px-3 py-2 text-left text-sm cursor-pointer text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-bg-tertiary)]"
+            >
+              Reset to default
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}