jamdesk 1.1.127 → 1.1.128

package/vendored/lib/api-spec-menu-gate.ts

@@ -0,0 +1,36 @@
+import type { ContextualOption, DocsConfig } from './docs-types';
+import { siteHasOpenApiSpecs } from './api-specs-bundle';
+
+export interface ApiSpecGateInput {
+  isIsr: boolean;
+  isApiPage: boolean;
+  /** This page's frontmatter declares an `openapi:` spec. */
+  pageHasOpenApi: boolean;
+  config: DocsConfig;
+}
+
+/**
+ * Insert `download-api-spec` iff: ISR mode (route + R2 only exist in prod) AND
+ * an API page AND the menu is non-empty (respect a disabled menu) AND the site
+ * has ≥1 spec (page-level OR anywhere in docs.json). Never mutates input or dups.
+ * The route is the source of truth (404 if assembly is empty); this is a hint.
+ *
+ * Placement: directly below "View as Markdown", so the download sits with the
+ * page-level actions near the top rather than trailing the MCP/editor
+ * integrations. Falls back to just after "Copy page", then the front, when
+ * "view" is absent (a customized `contextual.options` list).
+ */
+export function withApiSpecDownload(
+  options: ContextualOption[],
+  { isIsr, isApiPage, pageHasOpenApi, config }: ApiSpecGateInput,
+): ContextualOption[] {
+  if (!isIsr || !isApiPage || options.length === 0) return options;
+  if (options.includes('download-api-spec')) return options;
+  if (!(pageHasOpenApi || siteHasOpenApiSpecs(config))) return options;
+  const result = [...options];
+  const viewIdx = result.indexOf('view');
+  const copyIdx = result.indexOf('copy');
+  const insertAt = viewIdx !== -1 ? viewIdx + 1 : copyIdx !== -1 ? copyIdx + 1 : 0;
+  result.splice(insertAt, 0, 'download-api-spec');
+  return result;
+}

package/vendored/lib/api-specs-bundle.ts

@@ -0,0 +1,255 @@
+/**
+ * api-specs.zip assembly — REQUEST-TIME.
+ *
+ * Assembles the downloadable bundle on demand from specs already in R2 plus
+ * remote-URL specs fetched (SSRF-guarded) at request time. Verbatim bundling:
+ * local specs keep their R2 key path so co-located `$ref`s resolve.
+ *
+ * All I/O is injected so this is unit-testable without R2 or network.
+ */
+import path from 'path';
+
+import { zipSync } from 'fflate';
+
+import type { DocsConfig } from './docs-types';
+import { isUrlSafe } from './url-safety';
+import type { BuildWarning } from '../shared/status-reporter';
+
+/** 8 MiB per remote spec; 10s per fetch — bounds a single short-lived request. */
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * Overall wall-clock budget (ms) for ALL remote fetches in one request, measured
+ * from assembler entry. Each fetch is individually bounded, but a docs.json with
+ * several slow remotes could sum past Vercel's 30s function cap and hard-kill the
+ * request — discarding the local specs already assembled. 25s leaves ~5s headroom
+ * under the cap for zipping + streaming the response.
+ */
+const DEFAULT_REMOTE_BUDGET_MS = 25_000;
+
+export function isHttpUrl(ref: string): boolean {
+  return /^https?:\/\//i.test(ref);
+}
+
+function pushRefs(out: string[], seen: Set<string>, val: unknown): void {
+  const add = (r: unknown) => {
+    if (typeof r === 'string' && r && !seen.has(r)) { seen.add(r); out.push(r); }
+  };
+  if (typeof val === 'string') add(val);
+  else if (Array.isArray(val)) val.forEach(add);
+}
+
+function walk(out: string[], seen: Set<string>, node: unknown): void {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) { for (const n of node) walk(out, seen, n); return; }
+  for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+    if (key === 'openapi') pushRefs(out, seen, value);
+    else if (value && typeof value === 'object') walk(out, seen, value);
+  }
+}
+
+/** Every `openapi` ref declared anywhere in docs.json (top-level + nested nav),
+ *  de-duplicated, order-preserving. Locals AND http(s) URLs. */
+export function collectConfigOpenApiRefs(config: DocsConfig): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  pushRefs(out, seen, config.api?.openapi);
+  walk(out, seen, config.navigation);
+  return out;
+}
+
+export function siteHasOpenApiSpecs(config: DocsConfig): boolean {
+  return collectConfigOpenApiRefs(config).length > 0;
+}
+
+export interface ZipEntry { name: string; content: Uint8Array; }
+
+function uniqueName(name: string, used: Set<string>): string {
+  if (!used.has(name)) { used.add(name); return name; }
+  const ext = path.extname(name);
+  const base = name.slice(0, name.length - ext.length);
+  let n = 2;
+  let candidate = `${base}-${n}${ext}`;
+  while (used.has(candidate)) { n += 1; candidate = `${base}-${n}${ext}`; }
+  used.add(candidate);
+  return candidate;
+}
+
+/**
+ * Build a zip from named entries. Entry names are used AS GIVEN (path preserved),
+ * so a local spec passed as `openapi/api.yaml` keeps its directory and its
+ * relative `$ref`s resolve. Colliding names get a `-2`/`-3` suffix. Null if empty.
+ * No `mtime` option: fflate's DOS date floor is 1980, so `mtime: 0` THROWS.
+ */
+export function buildSpecZip(entries: ZipEntry[]): Uint8Array | null {
+  if (entries.length === 0) return null;
+  const used = new Set<string>();
+  const map: Record<string, Uint8Array> = {};
+  for (const e of entries) {
+    const name = e.name.includes('/') ? e.name : (path.basename(e.name) || 'spec');
+    map[uniqueName(name, used)] = e.content;
+  }
+  return zipSync(map);
+}
+
+function remoteWarning(url: string, reason: string): BuildWarning {
+  return {
+    type: 'invalid_openapi_spec',
+    file: 'docs.json',
+    link: url,
+    message: `Remote OpenAPI spec "${url}" excluded from api-specs.zip (${reason}).`,
+  };
+}
+
+function remoteSpecFilename(url: string): string {
+  try {
+    const base = path.basename(new URL(url).pathname);
+    if (base && base !== '/') return base;
+  } catch { /* fall through */ }
+  return 'remote-spec.json';
+}
+
+export type RemoteOutcome = { entry: ZipEntry } | { warning: BuildWarning };
+
+/** Max redirect hops to follow before giving up — bounds redirect chains. */
+const MAX_REDIRECTS = 5;
+
+/**
+ * Fetch one remote spec, SSRF-guarded + bounded. Never throws.
+ *
+ * Follows redirects MANUALLY (`redirect: 'manual'`) and re-validates `isUrlSafe`
+ * on EVERY hop. The default `fetchImpl` in prod is global `fetch` (undici), which
+ * would otherwise follow redirects transparently — letting a safe initial URL
+ * 302 to a private/metadata host and bypass the guard. Re-checking each target
+ * before fetching it closes that SSRF redirect bypass.
+ */
+export async function fetchRemoteSpec(
+  url: string,
+  fetchImpl: typeof fetch,
+  timeoutMs: number,
+  maxBytes: number,
+): Promise<RemoteOutcome> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    let current = url;
+    for (let hop = 0; hop < MAX_REDIRECTS; hop += 1) {
+      // Re-validate before EVERY fetch — covers the initial URL and each
+      // redirect target, so a 302 to a private/metadata host is blocked.
+      if (!isUrlSafe(current)) return { warning: remoteWarning(url, 'blocked by SSRF guard') };
+      const res = await fetchImpl(current, { signal: controller.signal, redirect: 'manual' });
+      if (res.status >= 300 && res.status < 400) {
+        const loc = res.headers.get('location');
+        if (!loc) return { warning: remoteWarning(url, 'redirect without location') };
+        current = new URL(loc, current).toString();
+        continue;
+      }
+      // Terminal response.
+      if (!res.ok) return { warning: remoteWarning(url, `HTTP ${res.status}`) };
+      const declared = res.headers.get('content-length');
+      if (declared && Number(declared) > maxBytes) {
+        return { warning: remoteWarning(url, `exceeds ${maxBytes} bytes`) };
+      }
+      const buf = new Uint8Array(await res.arrayBuffer());
+      if (buf.byteLength > maxBytes) return { warning: remoteWarning(url, `exceeds ${maxBytes} bytes`) };
+      return { entry: { name: remoteSpecFilename(url), content: buf } };
+    }
+    return { warning: remoteWarning(url, 'too many redirects') };
+  } catch (err) {
+    return { warning: remoteWarning(url, err instanceof Error ? err.message : String(err)) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export interface AssembleResult {
+  zip: Uint8Array | null;
+  warnings: BuildWarning[];
+  localCount: number;
+  remoteCount: number;
+}
+
+export interface AssembleDeps {
+  projectSlug: string;
+  /** Raw text of `{slug}/{key}` from R2, or null. (lib/r2-content.ts fetchStaticFile) */
+  fetchStaticFile: (slug: string, key: string) => Promise<string | null>;
+  /** Parsed docs.json from R2, or null. (lib/r2-content.ts fetchDocsConfig) */
+  fetchDocsConfig: (slug: string) => Promise<DocsConfig | null>;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+  maxBytes?: number;
+  /** Clock for the overall remote-fetch budget. Injectable for tests; defaults to Date.now. */
+  now?: () => number;
+  /** Overall wall-clock budget (ms) across all remote fetches. Default 25s, under Vercel's 30s cap. */
+  overallBudgetMs?: number;
+}
+
+/**
+ * Assemble api-specs.zip for one project from R2 + remote URLs. Never throws on
+ * a single spec — failures become non-blocking warnings. Returns `zip: null`
+ * when the project has zero specs (caller 404s).
+ */
+export async function assembleApiSpecsFromR2(deps: AssembleDeps): Promise<AssembleResult> {
+  const {
+    projectSlug, fetchStaticFile, fetchDocsConfig,
+    fetchImpl = fetch, timeoutMs = DEFAULT_TIMEOUT_MS, maxBytes = DEFAULT_MAX_BYTES,
+    now = Date.now, overallBudgetMs = DEFAULT_REMOTE_BUDGET_MS,
+  } = deps;
+  const remoteDeadline = now() + overallBudgetMs;
+
+  const warnings: BuildWarning[] = [];
+  const entries: ZipEntry[] = [];
+  const enc = new TextEncoder();
+
+  // Local specs: the build wrote them to R2 and recorded the keys in
+  // manifest.openapi. Read each verbatim and keep its KEY path in the zip.
+  const manifestRaw = await fetchStaticFile(projectSlug, 'manifest.json');
+  if (manifestRaw) {
+    let openapiKeys: string[] = [];
+    try {
+      const manifest = JSON.parse(manifestRaw) as { openapi?: Record<string, unknown> };
+      openapiKeys = Object.keys(manifest.openapi ?? {});
+    } catch { /* malformed manifest → treat as no locals */ }
+    for (const key of openapiKeys) {
+      const text = await fetchStaticFile(projectSlug, key);
+      if (text == null) {
+        warnings.push(remoteWarning(key, 'not found in R2 at request time'));
+        continue;
+      }
+      entries.push({ name: key, content: enc.encode(text) });
+    }
+  }
+  const localCount = entries.length;
+
+  // Remote specs: declared in docs.json, never uploaded. Fetch (guarded) now.
+  // fetchDocsConfig RE-THROWS on a non-NotFound R2 error (unlike fetchStaticFile,
+  // which returns null) — catch it so a transient config-read failure degrades to
+  // a warning and we still return the locals we already assembled, rather than
+  // discarding a complete local bundle as a 500.
+  let config: DocsConfig | null = null;
+  try {
+    config = await fetchDocsConfig(projectSlug);
+  } catch (err) {
+    warnings.push(remoteWarning('docs.json', `config read failed: ${err instanceof Error ? err.message : String(err)}`));
+  }
+  let remoteCount = 0;
+  if (config) {
+    const remoteUrls = collectConfigOpenApiRefs(config).filter(isHttpUrl);
+    for (const url of remoteUrls) {
+      // Bound total remote time to the overall budget: once spent, skip remaining
+      // remotes (warn) instead of risking a function timeout that would discard the
+      // locals we already have. Clamp each fetch's timeout to the time left so a
+      // single slow remote can't overrun the budget either.
+      const remaining = remoteDeadline - now();
+      if (remaining <= 0) {
+        warnings.push(remoteWarning(url, 'skipped — overall remote-fetch time budget exceeded'));
+        continue;
+      }
+      const outcome = await fetchRemoteSpec(url, fetchImpl, Math.min(timeoutMs, remaining), maxBytes);
+      if ('entry' in outcome) { entries.push(outcome.entry); remoteCount += 1; }
+      else warnings.push(outcome.warning);
+    }
+  }
+
+  return { zip: buildSpecZip(entries), warnings, localCount, remoteCount };
+}

package/vendored/lib/api-specs-markdown-hint.ts

@@ -0,0 +1,40 @@
+/**
+ * Agent-facing footer telling AI tools the site's OpenAPI specs are downloadable
+ * as a single api-specs.zip. Pure + server-safe: no I/O, no request access. The
+ * route resolves the gate inputs (frontmatter, config) and the absolute URL (via
+ * getBaseUrlFromConfig), then calls this.
+ */
+
+export interface ApiSpecsHintInput {
+  /** ISR mode only — the route + the R2 bundle only exist in prod. */
+  isIsr: boolean;
+  /** The contextual (AI-actions) menu is non-empty. Mirrors the menu gate's
+   *  `options.length === 0` guard: a site with contextual.enabled:false (or
+   *  options:[]) suppresses the menu item, so it must suppress the footer too. */
+  menuEnabled: boolean;
+  /** frontmatter `openapi:` present (a page-level spec ref). */
+  pageHasOpenApi: boolean;
+  /** frontmatter `api:` present (config-driven API page). */
+  pageHasApi: boolean;
+  /** siteHasOpenApiSpecs(config) — the site references ≥1 spec anywhere. */
+  siteHasSpecs: boolean;
+  /** Absolute api-specs.zip URL (getBaseUrlFromConfig is total → normally non-empty). */
+  zipUrl: string;
+}
+
+/**
+ * The footer Markdown to append, or null when it must not appear. The gate
+ * mirrors withApiSpecDownload (lib/api-spec-menu-gate.ts): ISR + the menu is
+ * enabled + the page is an API page + the site actually has ≥1 spec (a page-level
+ * `openapi:` short-circuits the site-wide check, exactly as the menu does). The
+ * zip route is the source of truth (it 404s if assembly is empty); this is a hint.
+ */
+export function apiSpecsMarkdownFooter(input: ApiSpecsHintInput): string | null {
+  const { isIsr, menuEnabled, pageHasOpenApi, pageHasApi, siteHasSpecs, zipUrl } = input;
+  if (!isIsr) return null;
+  if (!menuEnabled) return null;                       // contextual.enabled:false / options:[]
+  if (!(pageHasOpenApi || pageHasApi)) return null;    // not an API page
+  if (!(pageHasOpenApi || siteHasSpecs)) return null;  // no spec to bundle
+  if (!zipUrl) return null;                            // defensive
+  return `\n\n---\n\n📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — ${zipUrl}`;
+}

package/vendored/lib/api-specs-route.ts

@@ -0,0 +1,45 @@
+/**
+ * Request-time handler for /api-specs.zip (+ /docs variant). Assembles the
+ * bundle on demand from R2 + remote specs and streams it as a download.
+ */
+import { NextRequest, NextResponse } from 'next/server';
+
+import { log } from '@/lib/logger';
+import { isIsrMode } from '@/lib/page-isr-helpers';
+import { fetchStaticFile, fetchDocsConfig } from '@/lib/r2-content';
+import { assembleApiSpecsFromR2 } from '@/lib/api-specs-bundle';
+
+export async function apiSpecsRouteHandler(request: NextRequest): Promise<NextResponse> {
+  // ISR-only: assembly needs R2. Local dev has neither R2 nor the menu item.
+  if (!isIsrMode()) return new NextResponse('Not found', { status: 404 });
+
+  const projectSlug = request.headers.get('x-project-slug');
+  if (!projectSlug) {
+    log('warn', 'api-specs.zip request missing project slug');
+    return new NextResponse('Project not found', { status: 404 });
+  }
+
+  try {
+    const result = await assembleApiSpecsFromR2({ projectSlug, fetchStaticFile, fetchDocsConfig });
+    if (result.warnings.length) {
+      log('warn', 'api-specs.zip assembled with warnings', {
+        projectSlug, warnings: result.warnings.map((w) => w.message),
+      });
+    }
+    if (!result.zip) return new NextResponse('No API specs found', { status: 404 });
+
+    return new NextResponse(Buffer.from(result.zip), {
+      headers: {
+        'Content-Type': 'application/zip',
+        'Content-Disposition': 'attachment; filename="api-specs.zip"',
+        // Always fresh: assembly is cheap, downloads are rare. Avoids any
+        // post-rebuild staleness / R2-overwrite-consistency window.
+        'Cache-Control': 'no-store',
+        'X-Robots-Tag': 'noindex',
+      },
+    });
+  } catch (error) {
+    log('error', 'Error assembling api-specs.zip', { projectSlug, error: String(error) });
+    return new NextResponse('Error assembling API specs', { status: 500 });
+  }
+}

package/vendored/lib/docs-types.ts

@@ -712,7 +712,7 @@ export interface ErrorsConfig {
  */
 export type ContextualOption =
   | 'copy' | 'view' | 'chatgpt' | 'claude' | 'gemini' | 'perplexity'
-  | 'mcp' | 'cursor' | 'vscode'
+  | 'mcp' | 'cursor' | 'vscode' | 'download-api-spec'
   | {
       title: string;
       description: string;

package/vendored/lib/heading-extractor.ts

@@ -6,6 +6,8 @@
  * and Steps.tsx.
  */
 
+import GithubSlugger, { slug as githubSlug } from 'github-slugger';
+
 export interface HeadingInfo {
   id: string;
   text: string;
@@ -17,26 +19,27 @@ export interface HeadingInfo {
 
 /**
  * Generate a URL-friendly slug from heading text.
- * Canonical implementation — also duplicated in validate-links.cjs (CJS, can't import).
- */
-export function generateSlug(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-}
-
-/**
- * Suffix `base` with -2, -3, ... if it has been seen before. First occurrence
- * keeps the bare slug for backwards compatibility with existing inbound links.
- * Mutates `seen` in place — caller owns the lifetime (one Map per page).
  *
- * Mirrored in scripts/validate-links.cjs — keep both in sync.
+ * Delegates to github-slugger — the SAME library `rehype-slug` uses to assign the
+ * real heading `id` attributes during MDX compile (wired in render-doc-page.tsx).
+ * Using it here keeps the "On this page" TOC, <Update>/<Step> anchors, and the
+ * link validator byte-for-byte aligned with the actual DOM ids — including for
+ * non-ASCII headings, where the previous `[^a-z0-9]+ -> '-'` implementation
+ * diverged (accents/apostrophes/underscores became dashes) and produced dead
+ * anchors (e.g. heading "Abrir cualquier página" → real id `abrir-cualquier-página`,
+ * but the old slug was `abrir-cualquier-p-gina`).
+ *
+ * Stateless: repeated calls with the same text return the same slug. For
+ * per-document uniqueness across duplicate headings, use a `GithubSlugger`
+ * instance (as extractHeadings does) — it mirrors rehype-slug's `-1`/`-2`
+ * suffixing exactly.
+ *
+ * Mirrored in scripts/validate-links.cjs (CJS — can't import the ESM-only
+ * github-slugger), where the algorithm + regex are replicated and guarded by a
+ * drift test (`validate-links-slug.test.ts`). Keep both in sync.
  */
-export function uniquifySlug(seen: Map<string, number>, base: string): string {
-  const count = seen.get(base) ?? 0;
-  seen.set(base, count + 1);
-  return count === 0 ? base : `${base}-${count + 1}`;
+export function generateSlug(text: string): string {
+  return githubSlug(text);
 }
 
 const HEADING_REGEX = /^(#{1,6})\s+(.+)$/;
@@ -57,6 +60,10 @@ const STEP_TITLE_REGEX = /<Step\s+[^>]*title=(?:"([^"]+)"|'([^']+)')/g;
  * Includes markdown headings, <Update label="..."> component anchors,
  * and <Step title="..."> entries inside <Steps> blocks (with per-block numbering).
  * Skips content inside fenced code blocks.
+ *
+ * A single page-scoped `GithubSlugger` assigns ids so duplicate titles (across
+ * H2s, Update labels, and Steps) get `-1`, `-2`, ... suffixes in source order —
+ * the same algorithm rehype-slug applies to the real markdown-heading DOM ids.
  */
 export function extractHeadings(content: string): HeadingInfo[] {
   const headings: HeadingInfo[] = [];
@@ -67,9 +74,9 @@ export function extractHeadings(content: string): HeadingInfo[] {
   // block can't stick the counter across subsequent blocks.
   let inStepsBlock = false;
   let stepCounter = 0;
-  // Page-scoped slug counter so duplicate titles (across H2s, Update labels,
-  // and Steps) get -2, -3, ... suffixes in source order.
-  const seenSlugs = new Map<string, number>();
+  // Page-scoped slugger so duplicate titles get -1, -2, ... suffixes in source
+  // order, matching rehype-slug's per-document GithubSlugger.
+  const slugger = new GithubSlugger();
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -101,9 +108,8 @@ export function extractHeadings(content: string): HeadingInfo[] {
     if (headingMatch) {
       const level = headingMatch[1].length;
       const text = headingMatch[2].trim();
-      const base = generateSlug(text);
-      if (base) {
-        const id = uniquifySlug(seenSlugs, base);
+      if (generateSlug(text)) {
+        const id = slugger.slug(text);
         headings.push({ id, text, level, line: i + 1 });
       }
     }
@@ -111,9 +117,8 @@ export function extractHeadings(content: string): HeadingInfo[] {
     const updateMatch = line.match(UPDATE_LABEL_REGEX);
     if (updateMatch) {
       const text = updateMatch[1];
-      const base = generateSlug(text);
-      if (base) {
-        const id = uniquifySlug(seenSlugs, base);
+      if (generateSlug(text)) {
+        const id = slugger.slug(text);
         headings.push({ id, text, level: 2, line: i + 1 });
       }
     }
@@ -121,10 +126,9 @@ export function extractHeadings(content: string): HeadingInfo[] {
     if (inStepsBlock) {
       for (const match of line.matchAll(STEP_TITLE_REGEX)) {
         const text = match[1] ?? match[2];
-        const base = generateSlug(text);
-        if (!base) continue;
+        if (!generateSlug(text)) continue;
         stepCounter += 1;
-        const id = uniquifySlug(seenSlugs, base);
+        const id = slugger.slug(text);
         headings.push({
           id,
           text,

package/vendored/lib/layout-helpers.tsx

@@ -365,6 +365,8 @@ interface DocsChromeProps {
   customCss: string | null;
   customJs: string | null;
   children: React.ReactNode;
+  embed?: boolean;
+  embedTheme?: 'light' | 'dark' | 'auto';
 }
 
 /**
@@ -383,6 +385,8 @@ export async function DocsChrome({
   customCss,
   customJs,
   children,
+  embed,
+  embedTheme,
 }: DocsChromeProps): Promise<React.ReactElement> {
   // Lowercase to match docs-config canonical case — `data-theme="nebula"` CSS
   // selectors are case-sensitive, so `theme: "NEBULA"` from disk would silently
@@ -410,6 +414,11 @@ export async function DocsChrome({
   const appearanceDefault = config.appearance?.default || 'system';
   const appearanceStrict = config.appearance?.strict || false;
 
+  // In embed mode, an explicit ?theme=dark|light forces that theme so the
+  // panel can match the host app; theme=auto (or omitted) keeps system.
+  const embedForcedTheme =
+    embed && (embedTheme === 'light' || embedTheme === 'dark') ? embedTheme : undefined;
+
   const linkPrefix = config.hostAtDocs ? '/docs' : '';
 
   // Skip building the IIFE string in dev — both the script render below and
@@ -464,6 +473,11 @@ export async function DocsChrome({
           }}
         />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
+        {/* Embed render (widget modal): default every in-frame link to a new tab.
+            Clicking a doc link should open the full docs site in a new tab, not
+            navigate the modal iframe into a chrome'd (non-embed) page. Scoped to
+            embed — this <head> only renders when x-jd-layout=embed. */}
+        {embed && <base target="_blank" />}
         {config.fonts && (
           <>
             <link rel="preconnect" href="https://fonts.googleapis.com" />
@@ -646,11 +660,14 @@ export async function DocsChrome({
         )}
         <ThemeProvider
           defaultTheme={appearanceDefault}
-          forcedTheme={appearanceStrict ? (appearanceDefault === 'system' ? undefined : appearanceDefault as 'light' | 'dark') : undefined}
+          forcedTheme={
+            embedForcedTheme ??
+            (appearanceStrict ? (appearanceDefault === 'system' ? undefined : appearanceDefault as 'light' | 'dark') : undefined)
+          }
         >
           <LinkPrefixProvider prefix={linkPrefix}>
             <ProjectSlugProvider slug={resolvedProjectSlug || ''}>
-              <LayoutWrapper config={config}>
+              <LayoutWrapper config={config} embed={embed}>
                 {children}
               </LayoutWrapper>
             </ProjectSlugProvider>

package/vendored/lib/middleware-helpers.ts

@@ -504,6 +504,31 @@ export function getMcpApiPath(projectSlug: string): string {
   return `/api/mcp/${projectSlug}`;
 }
 
+export type EmbedTheme = 'light' | 'dark' | 'auto';
+
+/**
+ * True when the request opts into the chrome-less embed render.
+ *
+ * Supports `?embed=1` (canonical) and `?layout=embed` (convenience alias).
+ *
+ * @param searchParams - URL search params from the incoming request
+ * @returns true if this request should render without site chrome
+ */
+export function isEmbedRequest(searchParams: URLSearchParams): boolean {
+  return searchParams.get('embed') === '1' || searchParams.get('layout') === 'embed';
+}
+
+/**
+ * Forced theme for an embed render; defaults to 'auto' (prefers-color-scheme).
+ *
+ * @param searchParams - URL search params from the incoming request
+ * @returns 'dark' | 'light' when explicitly set, otherwise 'auto'
+ */
+export function getEmbedTheme(searchParams: URLSearchParams): EmbedTheme {
+  const t = searchParams.get('theme');
+  return t === 'dark' || t === 'light' ? t : 'auto';
+}
+
 /**
  * Check if this is a chat request that needs routing.
  *
@@ -629,6 +654,7 @@ const TRUSTED_PROXY_HEADERS = [
   // attacker on a subdomain ALSO toggle the "owner can sign in"
   // copy. Strip them all from the inbound request.
   'x-jd-layout',
+  'x-jd-embed-theme', // forced-theme for embed render — never client-supplied
   'x-jd-custom-domain',
   'x-jd-project-name',
   'x-jd-project-logo',
@@ -678,6 +704,9 @@ export interface BuildProjectHeadersOptions {
  * Strips any client-supplied copies of those headers from the inbound
  * request to prevent header smuggling.
  *
+ * Strips (but does NOT set) x-jd-layout and x-jd-embed-theme — callers own
+ * those after this call; see TRUSTED_PROXY_HEADERS for the full strip list.
+ *
  * @param projectSlug - Resolved project slug
  * @param existingHeaders - Existing request headers to clone
  * @param hostAtDocs - Whether docs are hosted at /docs