jamdesk 1.1.140 → 1.1.142

package/vendored/components/mdx/MermaidInner.tsx

@@ -47,8 +47,29 @@ interface ColorPalette {
   ganttSections: string[];
   ganttGridLine: string;
   gitBranchColors: string[];
+  pieSliceStroke: string;
 }
 
+// Mermaid's built-in palettes (including 'neutral') color pie slices with
+// washed-out, near-white grays: low-contrast on a light background and wiped to
+// transparent by the dark-mode path-fill inversion below — so slices render with
+// no visible color in either mode. We override slice + legend fills with a
+// distinct, mid-tone palette that reads on both backgrounds, mirroring the
+// curated colors already used for gantt bars and git branches. Every entry has at
+// least one channel < 200, so isLightColor() never flags them.
+const PIE_SLICE_COLORS = [
+  '#3b82f6', // blue
+  '#ef4444', // red
+  '#22c55e', // green
+  '#f59e0b', // amber
+  '#a855f7', // purple
+  '#14b8a6', // teal
+  '#ec4899', // pink
+  '#f97316', // orange
+  '#64748b', // slate
+  '#84cc16', // lime
+];
+
 const darkPalette: ColorPalette = {
   text: '#e5e7eb',
   line: '#9ca3af',
@@ -59,6 +80,7 @@ const darkPalette: ColorPalette = {
   ganttSections: ['#1e1e3f', '#2d2d1e', '#1e2d1e'],
   ganttGridLine: '#374151',
   gitBranchColors: ['#3b82f6', '#eab308', '#22c55e', '#f97316', '#ec4899', '#a78bfa'],
+  pieSliceStroke: '#1f2937', // dark slate — crisp separation between slices on a dark bg
 };
 
 const lightPalette: ColorPalette = {
@@ -71,6 +93,7 @@ const lightPalette: ColorPalette = {
   ganttSections: ['#f0f0ff', '#fff8e6', '#f0fff0'],
   ganttGridLine: '#e5e7eb',
   gitBranchColors: ['#3b82f6', '#eab308', '#22c55e', '#f97316', '#ec4899', '#8b5cf6'],
+  pieSliceStroke: '#ffffff', // white — crisp separation between slices on a light bg
 };
 
 // Styling helper utilities
@@ -129,7 +152,46 @@ function applyClassDiagramStyles(svgEl: SVGElement, palette: ColorPalette): void
 }
 
 function applyPieChartStyles(svgEl: SVGElement, palette: ColorPalette): void {
+  // Title and legend text follow the theme text color.
   styleElements(svgEl, '.pieLabel, .legend text, .pieTitleText', { fill: palette.text });
+
+  const slices = svgEl.querySelectorAll<SVGPathElement>('path.pieCircle');
+  if (slices.length === 0) return; // not a pie chart
+
+  // Re-color slices and legend swatches from PIE_SLICE_COLORS. Each distinct
+  // original (washed-out) color maps to one vivid color, recorded as the slices
+  // are walked, then reused for the legend so a slice and its legend entry —
+  // which share mermaid's original ordinal color — get the same override.
+  const colorMap = new Map<string, string>();
+  let nextColor = 0;
+  const overrideFor = (rawFill: string | null | undefined): string => {
+    const key = normalizeColor(rawFill) ?? `pos-${nextColor}`;
+    let vivid = colorMap.get(key);
+    if (!vivid) {
+      vivid = PIE_SLICE_COLORS[nextColor % PIE_SLICE_COLORS.length];
+      nextColor += 1;
+      colorMap.set(key, vivid);
+    }
+    return vivid;
+  };
+
+  slices.forEach((slice) => {
+    const vivid = overrideFor(slice.style.fill || slice.getAttribute('fill'));
+    slice.style.fill = vivid;
+    slice.style.stroke = palette.pieSliceStroke;
+    slice.style.strokeWidth = '2';
+  });
+
+  // Legend swatches: <g class="legend"> > rect, fill set via inline style.
+  svgEl.querySelectorAll<SVGRectElement>('.legend rect').forEach((swatch) => {
+    const vivid = overrideFor(swatch.style.fill || swatch.getAttribute('fill'));
+    swatch.style.fill = vivid;
+    swatch.style.stroke = vivid;
+  });
+
+  // Percentage labels sit on top of the slices — white reads on every palette
+  // tone. The dark-mode text inversion spares text.slice so this survives there.
+  styleElements(svgEl, 'text.slice', { fill: '#ffffff' });
 }
 
 // Check if an RGB color is light (r,g,b > threshold)
@@ -147,6 +209,26 @@ function isDarkColor(rgbString: string, threshold = 150): boolean {
   return r < threshold && g < threshold && b < threshold;
 }
 
+// Normalize a CSS color (hex or rgb()) to a canonical "r,g,b" string. A pie
+// slice's fill arrives as a hex attribute (e.g. "#ECECFF") while its matching
+// legend swatch's fill is an inline style the browser reports as "rgb(...)" —
+// normalizing lets the same underlying color compare equal across both formats,
+// so a slice and its legend entry get the same override color. Returns null when
+// the value can't be parsed (caller falls back to a positional key).
+function normalizeColor(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const v = value.trim();
+  const rgb = v.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i);
+  if (rgb) return `${+rgb[1]},${+rgb[2]},${+rgb[3]}`;
+  let hex = v.replace(/^#/, '');
+  if (hex.length === 3) hex = hex.split('').map((c) => c + c).join('');
+  if (hex.length === 6 && /^[0-9a-f]{6}$/i.test(hex)) {
+    const n = parseInt(hex, 16);
+    return `${(n >> 16) & 255},${(n >> 8) & 255},${n & 255}`;
+  }
+  return null;
+}
+
 // Shared styles applied to both light and dark modes
 function applyCommonStyles(svgEl: SVGElement, palette: ColorPalette): void {
   // Cluster/subgraph backgrounds
@@ -174,15 +256,22 @@ function applyCommonStyles(svgEl: SVGElement, palette: ColorPalette): void {
 
 // Dark mode requires additional color inversions
 function applyDarkModeInversions(svgEl: SVGElement, palette: ColorPalette): void {
-  // Make background rects transparent
+  // Make background rects transparent. Pie legend swatches (.legend rect) are
+  // re-colored in applyPieChartStyles — leave their fills alone.
   svgEl.querySelectorAll('rect').forEach((rect) => {
-    if (!rect.closest('.cluster') && !rect.closest('.node') && !rect.classList.contains('actor')) {
+    if (
+      !rect.closest('.cluster') &&
+      !rect.closest('.node') &&
+      !rect.classList.contains('actor') &&
+      !rect.closest('.legend')
+    ) {
       (rect as SVGElement).style.fill = 'transparent';
     }
   });
 
-  // Invert text colors
-  styleElements(svgEl, 'text, .nodeLabel, .edgeLabel, .label, tspan', { fill: palette.text });
+  // Invert text colors. text.slice (pie percentage labels) is excluded so the
+  // white set in applyPieChartStyles stays legible on the colored slices.
+  styleElements(svgEl, 'text:not(.slice), .nodeLabel, .edgeLabel, .label, tspan', { fill: palette.text });
   styleElements(svgEl, 'text.actor, .messageText, .labelText, .loopText, .noteText', { fill: palette.text });
 
   // Invert foreignObject text and clear light backgrounds
@@ -198,8 +287,10 @@ function applyDarkModeInversions(svgEl: SVGElement, palette: ColorPalette): void
     }
   });
 
-  // Invert lines and paths
+  // Invert lines and paths. Pie slices (path.pieCircle) carry their own colors
+  // from applyPieChartStyles — skip them so the fill isn't wiped to transparent.
   svgEl.querySelectorAll('path, line').forEach((el) => {
+    if ((el as Element).classList.contains('pieCircle')) return;
     const computed = window.getComputedStyle(el);
     if (computed.stroke && computed.stroke !== 'none') {
       (el as SVGElement).style.stroke = palette.line;

package/vendored/components/search/SearchModal.tsx

@@ -157,6 +157,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
   const router = useRouter();
   const resultsContainerRef = useRef<HTMLDivElement>(null);
   const modalRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
   // Track if user clicked a result (to avoid double-tracking on modal close)
   const hasTrackedRef = useRef(false);
   // Store last search state for tracking on modal close
@@ -519,17 +520,34 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
           <div className="flex items-center gap-3 px-4 py-3 border-b border-[var(--color-border)]">
             <i className="fa-solid fa-magnifying-glass h-4 w-4 text-[var(--color-text-muted)] flex-shrink-0" aria-hidden="true" />
             <input
+              ref={inputRef}
               type="search"
               placeholder="Search documentation…"
               value={query}
               onChange={(e) => setQuery(e.target.value)}
-              className="flex-1 bg-transparent text-[var(--color-text-primary)] placeholder-[var(--color-text-muted)] outline-none text-base"
+              className="flex-1 bg-transparent text-[var(--color-text-primary)] placeholder-[var(--color-text-muted)] outline-none text-base [&::-webkit-search-cancel-button]:appearance-none [&::-webkit-search-decoration]:appearance-none"
               autoComplete="off"
               autoFocus
               aria-label="Search documentation"
               aria-controls="search-results"
               aria-activedescendant={rows[selectedIndex] ? `search-result-${selectedIndex}` : undefined}
             />
+            {query && (
+              <button
+                type="button"
+                onClick={() => {
+                  setQuery('');
+                  inputRef.current?.focus();
+                }}
+                className="flex items-center justify-center w-4 h-4 cursor-pointer rounded-full bg-[var(--color-text-muted)] hover:bg-[var(--color-text-secondary)] transition-colors flex-shrink-0 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-accent)]"
+                aria-label="Clear search"
+              >
+                <i
+                  className="fa-solid fa-xmark text-[9px] leading-none text-[var(--color-bg-primary)]"
+                  aria-hidden="true"
+                />
+              </button>
+            )}
             <button
               onClick={onClose}
               className="p-1.5 cursor-pointer hover:bg-[var(--color-bg-tertiary)] rounded-lg transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-accent)]"

package/vendored/lib/deprecated-components.ts

@@ -24,6 +24,7 @@ export interface DeprecatedComponentInfo {
 /**
  * Map of deprecated components to their replacements.
  * Add new deprecated components here as they are removed.
+ * NEVER remove entries: render-time auto-migrate (preprocess-mdx.ts) rewrites stale R2 content with them forever.
  */
 export const DEPRECATED_COMPONENTS: Record<string, DeprecatedComponentInfo> = {
   CardGroup: {

package/vendored/lib/firestore-helpers.ts

@@ -0,0 +1,20 @@
+import admin from 'firebase-admin';
+
+/**
+ * True when a Firestore project claims this slug (the canonical slug lives at
+ * projects/{id}/github/config.slug — collection-group query avoids enumerating
+ * every project). Used as the server-side guard for expectOrphan deletes:
+ * orphan-purge tooling must never be able to wipe a live tenant, regardless of
+ * what a client-side script computed. The collection-group single-field index
+ * exemption for `github.slug` (COLLECTION_GROUP ASCENDING) already exists in
+ * dashboard/firestore.indexes.json, so this query needs no new index.
+ */
+export async function isSlugActive(slug: string): Promise<boolean> {
+  const snap = await admin
+    .firestore()
+    .collectionGroup('github')
+    .where('slug', '==', slug)
+    .limit(1)
+    .get();
+  return !snap.empty;
+}

package/vendored/lib/is-modified-click.ts

@@ -0,0 +1,11 @@
+import type { MouseEvent } from 'react';
+
+/**
+ * True when the user has asked the browser for special handling — new tab
+ * (cmd/ctrl), new window (shift), background tab (middle/non-primary button) —
+ * or another handler already claimed the event. Click interceptors must defer
+ * to native behavior in these cases instead of hijacking the click.
+ */
+export function isModifiedClick(e: MouseEvent): boolean {
+  return e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey;
+}

package/vendored/lib/middleware-helpers.ts

@@ -431,6 +431,10 @@ const SKIP_EXTENSIONS = [
   '.ttf',
   '.eot',
   '.map',
+  // sitemap.xsl is constant content (no project context needed); skipping
+  // avoids the resolution round-trip AND the password gate, which special-
+  // cases sitemap.xml but would otherwise intercept the stylesheet fetch.
+  '.xsl',
 ];
 
 /**

package/vendored/lib/preprocess-mdx.ts

@@ -7,8 +7,9 @@
  */
 
 import { ASSET_PREFIX, appendAssetVersion } from './docs-types';
-import { checkForDeprecatedComponents } from './deprecated-components';
+import { convertDeprecatedComponents } from './deprecated-components';
 import { filterVisibility } from './visibility-filter';
+import { logger } from '../shared/logger';
 
 /**
  * JSX components that contain markdown content requiring special preprocessing.
@@ -1083,6 +1084,24 @@ export function preprocessMdx(content: string, options?: { assetVersion?: string
   // that flow through preprocessMdx independently.
   processed = filterVisibility(processed, 'humans');
 
+  // Auto-migrate deprecated components instead of failing. Builds hard-fail
+  // on these separately (build.ts — now the SOLE author-facing gate) so
+  // authors are still told — but content uploaded to R2 BEFORE a component
+  // was deprecated never rebuilds, and throwing here turned every render of
+  // such a page into a 500 (2026-06-12 mintlfiy incident). Render what the
+  // author meant. Runs EARLY so converted tags (e.g. <Columns>) get the same
+  // JSX_CONTENT_COMPONENTS indentation/blank-line treatment as authored ones.
+  // Called unconditionally so self-closing forms (e.g. <CardGroup/>) are not
+  // silently skipped — conversion gates on changes.length > 0, not on a
+  // separate pre-check whose pattern was narrower than convertDeprecatedComponents.
+  const { content: converted, changes } = convertDeprecatedComponents(processed);
+  if (changes.length > 0) {
+    processed = converted;
+    logger.warn(
+      `[MDX] auto-migrated deprecated component(s) at render time: ${changes.join('; ')} — run \`jamdesk migrate\` to update the source`,
+    );
+  }
+
   // Strip snippet imports
   processed = stripSnippetImports(processed);
 
@@ -1136,17 +1155,6 @@ export function preprocessMdx(content: string, options?: { assetVersion?: string
   // it and bleed an :HL hint into prefetched RSC payloads.
   processed = addLazyLoadingToRawImg(processed);
 
-  // Check for deprecated components (defense-in-depth - builds also check earlier)
-  const deprecatedErrors = checkForDeprecatedComponents(processed, 'content');
-  if (deprecatedErrors.length > 0) {
-    const err = deprecatedErrors[0];
-    throw new Error(
-      `<${err.component}> has been removed. Use <${err.replacement}> instead.\n\n` +
-      `${err.migrationHint}\n\n` +
-      `Run \`jamdesk migrate\` to convert automatically.`
-    );
-  }
-
   // Clean up any resulting empty lines at the start
   processed = processed.replace(/^\n+/, '');
 

package/vendored/lib/redis.ts

@@ -116,6 +116,38 @@ export async function deleteDomainAuthSecret(
   await upstashCommand(kvUrl, kvToken, 'DEL', `domainAuthSecret:${hostname}`);
 }
 
+/**
+ * Purge ALL slug-scoped Redis keys for a deleted project.
+ *
+ * Project deletion historically removed only the domain-scoped keys
+ * (domain:/domainCfg:/domainVerify:/domainStatus:, via removeDomain) and left
+ * these six behind — which kept deleted tenants resolvable on *.jamdesk.app
+ * and serving stale R2 content (2026-06-12 mintlfiy incident). Called from
+ * the build-service /delete-project-assets handler during the delete cascade.
+ *
+ * Returns the number of keys that actually existed and were deleted.
+ */
+export async function purgeProjectRedisKeys(
+  slug: string,
+  kvUrl?: string,
+  kvToken?: string
+): Promise<number> {
+  if (!kvUrl || !kvToken) return 0;
+  const keys = [
+    `projectCfg:${slug}`,
+    `projectInactive:${slug}`,
+    `projectMeta:${slug}`,
+    `projectAuthSecret:${slug}`,
+    `projectAuthPublic:${slug}`,
+    `domainAuthSecret:${slug}.jamdesk.app`,
+  ];
+  // Single variadic DEL: one round trip, and atomic on the Redis side — a
+  // transient failure can't purge some keys and orphan the rest (the exact
+  // partial-purge incident class this function exists to close).
+  const result = await upstashCommand(kvUrl, kvToken, 'DEL', ...keys);
+  return typeof result === 'number' ? result : 0;
+}
+
 // ---------------------------------------------------------------------------
 // Project inactive flag — write side only.
 // Set when the project owner's subscription is canceled, past_due, or

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

@@ -338,7 +338,17 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
     ? import('@/lib/openapi-isr')
     : null;
 
-  const content = preprocessMdx(rawContent, { assetVersion: config.assetVersion });
+  // Preprocess can throw on malformed stale R2 content. A throw here escapes
+  // every guard below and 500s via error.tsx — catch it and route to the same
+  // inline-placeholder path as a compile failure (never-500 invariant).
+  let content = '';
+  let preprocessError: string | null = null;
+  try {
+    content = preprocessMdx(rawContent, { assetVersion: config.assetVersion });
+  } catch (err) {
+    preprocessError = err instanceof Error ? err.message : String(err);
+    logger.warn(`[MDX] preprocess failed for ${pagePath}: ${preprocessError}`);
+  }
 
   const stepEntries: StepSlugEntry[] = extractHeadings(content)
     .filter(h => typeof h.stepNumber === 'number')
@@ -487,31 +497,33 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
     ? content.replace(/<ResponseExample>[\s\S]*?<\/ResponseExample>/g, '')
     : content;
   const missingRefCollector: MissingRefCollector = { names: [] };
-  let mdxError: string | null = null;
+  let mdxError: string | null = preprocessError;
   let mdxCompileMs: number | null = null;
   const mdxCompileStart = performance.now();
-  try {
-    await compileMDX({
-      source: effectiveSource,
-      components: AllComponentsWithInline,
-      options: {
-        ...mdxSecurityOptions,
-        mdxOptions: {
-          ...getCommonMdxOptions(config, highlighter),
-          recmaPlugins: [
-            recmaCompoundComponents,
-            recmaCollectMissingRefs(missingRefCollector),
-            recmaGuardExpressions,
-          ],
+  if (!mdxError) {
+    try {
+      await compileMDX({
+        source: effectiveSource,
+        components: AllComponentsWithInline,
+        options: {
+          ...mdxSecurityOptions,
+          mdxOptions: {
+            ...getCommonMdxOptions(config, highlighter),
+            recmaPlugins: [
+              recmaCompoundComponents,
+              recmaCollectMissingRefs(missingRefCollector),
+              recmaGuardExpressions,
+            ],
+          },
         },
-      },
-    });
-  } catch (err) {
-    // Syntax/compile failure — the only path that can 500 around MDXRemote.
-    // Degrade to an inline placeholder; the chosen branch renders it instead
-    // of calling MDXRemote with source known to throw at compile.
-    mdxError = err instanceof Error ? err.message : String(err);
-    logger.warn(`[MDX] compile failed for ${pagePath}: ${mdxError}`);
+      });
+    } catch (err) {
+      // Syntax/compile failure — the only path that can 500 around MDXRemote.
+      // Degrade to an inline placeholder; the chosen branch renders it instead
+      // of calling MDXRemote with source known to throw at compile.
+      mdxError = err instanceof Error ? err.message : String(err);
+      logger.warn(`[MDX] compile failed for ${pagePath}: ${mdxError}`);
+    }
   }
   mdxCompileMs = Math.round(performance.now() - mdxCompileStart);
 

package/vendored/lib/scanner-blocklist.ts

@@ -55,7 +55,8 @@ export type ScannerCategory =
   | 'secrets-config' // /secrets.yml, /application.yml, /vault.env, /elasticsearch.yml, etc.
   | 'cms-exploit'    // Atlassian .action/.jspa + Confluence /exportword + /rest/tinymce/*
   | 'backup-archive' // /backup.sql, /*.zip, /*.tar.gz, /*.bak, /*.swp, /*.orig, etc.
-  | 'framework-config'; // Django settings.py, webpack-stats.json, Laravel/Rails logs, Spring Boot /actuator|/management
+  | 'framework-config' // Django settings.py, webpack-stats.json, Laravel/Rails logs, Spring Boot /actuator|/management
+  | 'legacy-content';  // Confluence-legacy /download/(attachments|thumbnails|export) — stale-index re-crawls of dead migrated URLs, NOT exploit probes
 
 // Exact-match → category (lowercase keys).
 const SCANNER_EXACT: ReadonlyMap<string, ScannerCategory> = new Map([
@@ -63,6 +64,10 @@ const SCANNER_EXACT: ReadonlyMap<string, ScannerCategory> = new Map([
   ['/wp-config.php', 'wordpress' as const],
   ['/wp-config.php.bak', 'wordpress' as const],
   ['/xmlrpc.php', 'wordpress' as const],
+  // Bare WP install-dir probe (40 hits / 72h, 2026-06-12). Exact match
+  // ONLY — a customer docs site about WordPress may legitimately own
+  // /wordpress/<page>; only the bare root probe is scanner-distinctive.
+  ['/wordpress', 'wordpress' as const],
   ['/adminer.php', 'php-config' as const],
   ['/config.php', 'php-config' as const],
   ['/configuration.php', 'php-config' as const],
@@ -141,6 +146,24 @@ const CMS_EXPLOIT_EXTENSION_REGEX = /\.(action|jspa)$/;
 const CMS_EXPLOIT_TINYMCE_PREFIX = '/rest/tinymce/';
 const CMS_EXPLOIT_EXPORTWORD = '/exportword';
 
+// Confluence-legacy download URL space: /download/attachments/<id>/…,
+// /download/thumbnails/<id>/…, /download/export/pdfexport-<jobid>/….
+// Stale crawlers replay these from pre-migration indexes (photofinale's
+// old Confluence site); each otherwise costs an assets-route pass +
+// ~300ms R2 GET before 404ing. The numeric content-ID segment /
+// pdfexport- job prefix are the Confluence fingerprints —
+// precision-over-recall: bare /download, non-numeric IDs, and other
+// /download/export/* names intentionally do NOT match.
+//
+// NOTE: this check runs BEFORE tenant docs.json redirect resolution
+// (proxy.ts step order), so matching paths can never be tenant redirect
+// SOURCES. If a future Confluence-migration customer needs 301s over
+// this URL space to preserve backlinks, this pattern must be revisited.
+// Own category (not cms-exploit): these are benign stale re-crawls,
+// and cms-exploit volume feeds the digest's WAF-promotion ranking.
+const LEGACY_CONTENT_CONFLUENCE_DOWNLOAD_REGEX =
+  /^\/download\/(?:(?:attachments|thumbnails)\/\d+(?:\/|$)|export\/pdfexport-)/;
+
 // Prefix-match → category (lowercase). Matches the exact prefix OR `${prefix}/...`.
 // /actuator and /management cover Spring Boot management endpoints —
 // /management is the default-overridable base path (management.endpoints.web.base-path).
@@ -232,6 +255,8 @@ export function classifyScannerProbe(pathname: string): ScannerCategory | null {
   if (lower === CMS_EXPLOIT_EXPORTWORD) return 'cms-exploit';
   if (lower.startsWith(CMS_EXPLOIT_TINYMCE_PREFIX)) return 'cms-exploit';
 
+  if (LEGACY_CONTENT_CONFLUENCE_DOWNLOAD_REGEX.test(lower)) return 'legacy-content';
+
   if (BACKUP_ARCHIVE_EXTENSION_REGEX.test(lower)) return 'backup-archive';
 
   if (FRAMEWORK_BASENAMES.has(basename)) return 'framework-config';

package/vendored/lib/sitemap-xsl.ts

@@ -0,0 +1,121 @@
+/**
+ * Sitemap XSL stylesheet — purely cosmetic, for humans who open sitemap.xml
+ * in a browser. Crawlers ignore the xml-stylesheet processing instruction.
+ *
+ * Served at /sitemap.xsl and /docs/sitemap.xsl by constant-content routes
+ * (no R2, identical for every project). The PI injected into sitemap.xml
+ * uses a RELATIVE href ("sitemap.xsl") so the same XML body resolves the
+ * stylesheet correctly from both /sitemap.xml and /docs/sitemap.xml —
+ * browsers require the XSL to be same-origin anyway.
+ *
+ * XSLT 1.0 only: that's all browser XSLT processors implement.
+ */
+
+import { NextResponse } from 'next/server';
+
+/** Processing instruction injected into served sitemap.xml bodies. */
+export const SITEMAP_STYLESHEET_PI = '<?xml-stylesheet type="text/xsl" href="sitemap.xsl"?>';
+
+/**
+ * Inject the stylesheet PI immediately after the XML declaration (the PI is
+ * only valid in the prolog, before the root element). Sitemaps without a
+ * declaration get it prepended. Idempotent: if a build-time generator ever
+ * starts baking a stylesheet PI into the R2 artifact, serve-time injection
+ * must not double it.
+ */
+export function injectSitemapStylesheet(xml: string): string {
+  if (xml.includes('<?xml-stylesheet')) return xml;
+  const declMatch = xml.match(/^\uFEFF?<\?xml[^?]*\?>\r?\n?/);
+  if (declMatch) {
+    return declMatch[0] + SITEMAP_STYLESHEET_PI + '\n' + xml.slice(declMatch[0].length);
+  }
+  return SITEMAP_STYLESHEET_PI + '\n' + xml;
+}
+
+/**
+ * Shared GET handler for /sitemap.xsl and /docs/sitemap.xsl (same pattern as
+ * lib/api-specs-route.ts) - one place for the headers, two thin route files.
+ */
+export function sitemapXslRouteHandler(): NextResponse {
+  return new NextResponse(SITEMAP_XSL, {
+    headers: {
+      'Content-Type': 'text/xsl; charset=utf-8',
+      'Cache-Control': 'public, max-age=86400, s-maxage=86400',
+    },
+  });
+}
+
+export const SITEMAP_XSL = `<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet version="1.0"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:sm="http://www.sitemaps.org/schemas/sitemap/0.9"
+  xmlns:xhtml="http://www.w3.org/1999/xhtml">
+  <xsl:output method="html" encoding="UTF-8" indent="yes"/>
+  <xsl:template match="/">
+    <html>
+      <head>
+        <title>XML Sitemap</title>
+        <meta name="viewport" content="width=device-width, initial-scale=1"/>
+        <style>
+          body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+                 margin: 0; padding: 2rem; color: #1a1a2e; background: #fafafa; }
+          h1 { font-size: 1.4rem; margin: 0 0 0.25rem; }
+          p.meta { color: #6b7280; margin: 0 0 1.5rem; font-size: 0.875rem; }
+          table { border-collapse: collapse; width: 100%; background: #fff;
+                  border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden;
+                  font-size: 0.875rem; }
+          th { text-align: left; padding: 0.6rem 0.9rem; background: #f3f4f6;
+               font-weight: 600; border-bottom: 1px solid #e5e7eb; white-space: nowrap; }
+          td { padding: 0.5rem 0.9rem; border-bottom: 1px solid #f3f4f6;
+               vertical-align: top; }
+          tr:last-child td { border-bottom: none; }
+          a { color: #4f46e5; text-decoration: none; word-break: break-all; }
+          a:hover { text-decoration: underline; }
+          .num { color: #9ca3af; text-align: right; }
+          .alt { color: #6b7280; white-space: nowrap; }
+          .alt a { color: #6b7280; }
+          .nowrap { white-space: nowrap; }
+        </style>
+      </head>
+      <body>
+        <h1>XML Sitemap</h1>
+        <p class="meta">
+          <xsl:value-of select="count(sm:urlset/sm:url)"/> URLs.
+          This is how the sitemap looks to humans; search engines read the raw XML.
+        </p>
+        <table>
+          <tr>
+            <th class="num">#</th>
+            <th>URL</th>
+            <xsl:if test="sm:urlset/sm:url/xhtml:link">
+              <th>Languages</th>
+            </xsl:if>
+            <th>Last modified</th>
+            <th>Change freq.</th>
+            <th>Priority</th>
+          </tr>
+          <xsl:for-each select="sm:urlset/sm:url">
+            <tr>
+              <td class="num"><xsl:value-of select="position()"/></td>
+              <td>
+                <a href="{sm:loc}"><xsl:value-of select="sm:loc"/></a>
+              </td>
+              <xsl:if test="/sm:urlset/sm:url/xhtml:link">
+                <td class="alt">
+                  <xsl:for-each select="xhtml:link[@hreflang != 'x-default']">
+                    <a href="{@href}"><xsl:value-of select="@hreflang"/></a>
+                    <xsl:if test="position() != last()"><xsl:text> </xsl:text></xsl:if>
+                  </xsl:for-each>
+                </td>
+              </xsl:if>
+              <td class="nowrap"><xsl:value-of select="sm:lastmod"/></td>
+              <td><xsl:value-of select="sm:changefreq"/></td>
+              <td><xsl:value-of select="sm:priority"/></td>
+            </tr>
+          </xsl:for-each>
+        </table>
+      </body>
+    </html>
+  </xsl:template>
+</xsl:stylesheet>
+`;

package/vendored/lib/static-file-route.ts

@@ -15,6 +15,7 @@ import { isKnownLanguageCode } from '@/lib/language-utils';
 import { log } from '@/lib/logger';
 import { isIsrMode } from '@/lib/page-isr-helpers';
 import { fetchStaticFile } from '@/lib/r2-content';
+import { injectSitemapStylesheet } from '@/lib/sitemap-xsl';
 
 /** Filenames served via createStaticFileHandler (7 at root + 7 at /docs). */
 export const STATIC_FILE_NAMES = [
@@ -207,6 +208,10 @@ export function createStaticFileHandler(
   const contentType = contentTypeOverride || getContentType(filename);
   const cacheControl = cacheControlOverride || 'public, max-age=3600, s-maxage=3600';
   const synthesizeNoindexResponse = buildNoindexResponse(filename);
+  // Cosmetic browser rendering only — crawlers ignore the PI. Injected at
+  // serve time (not into the R2 artifact) so it ships with an ISR deploy
+  // alone: no Cloud Run change, no per-project rebuilds.
+  const postProcess = filename === 'sitemap.xml' ? injectSitemapStylesheet : (s: string) => s;
 
   return async function GET(request: NextRequest): Promise<NextResponse> {
     if (!isIsrMode()) {
@@ -216,7 +221,7 @@ export function createStaticFileHandler(
       // 404s on these paths and breaks the SearchModal init.
       const localPath = path.join(process.cwd(), 'public', filename);
       if (fs.existsSync(localPath)) {
-        return new NextResponse(fs.readFileSync(localPath), {
+        return new NextResponse(postProcess(fs.readFileSync(localPath, 'utf-8')), {
           headers: { 'Content-Type': contentType, 'Cache-Control': 'no-cache' },
         });
       }
@@ -245,7 +250,7 @@ export function createStaticFileHandler(
         return new NextResponse(`${label} not found`, { status: 404 });
       }
 
-      return new NextResponse(content, {
+      return new NextResponse(postProcess(content), {
         headers: {
           'Content-Type': contentType,
           'Cache-Control': cacheControl,