jamdesk 1.1.41 → 1.1.43

package/vendored/app/[[...slug]]/page.tsx

@@ -44,6 +44,8 @@ import { getTypographyRemarkPlugins } from '@/lib/typography-config';
 import { remarkVisibility } from '@/lib/remark-visibility';
 import { recmaCompoundComponents } from '@/lib/recma-compound-components';
 import { extractInlineComponents } from '@/lib/process-mdx-with-exports';
+import { extractHeadings } from '@/lib/heading-extractor';
+import { StepSlugProvider, type StepSlugEntry } from '@/components/mdx/StepSlugContext';
 import { buildEndpointFromMdx } from '@/lib/build-endpoint-from-mdx';
 import { mdxSecurityOptions } from '@/lib/mdx-security-options';
 import fs from 'fs';
@@ -435,6 +437,13 @@ export default async function DocPage({ params }: PageProps) {
   // (snippets are injected globally via AllComponents)
   const content = preprocessMdx(rawContent, { assetVersion: config.assetVersion });
 
+  // Pre-resolve unique slugs for every <Step> on the page so duplicate titles
+  // across separate <Steps> blocks get -2, -3, ... suffixes that match the
+  // build-time TOC. Provider supplies the list to <Step> via context.
+  const stepEntries: StepSlugEntry[] = extractHeadings(content)
+    .filter(h => typeof h.stepNumber === 'number')
+    .map(h => ({ title: h.text, slug: h.id }));
+
   // Extract and compile inline component exports from MDX
   // Only pass MDXComponents (server-compatible) to inline extraction
   const { inlineComponents, paramFields } = await extractInlineComponents(content, MDXComponents);
@@ -708,21 +717,23 @@ export default async function DocPage({ params }: PageProps) {
             {/* Additional MDX content — strip <ResponseExample> on OpenAPI pages
                 (auto-generated ResponseExamplePanel already handles responses) */}
             <ImagePriorityProvider>
-              <MDXRemote
-                source={openApiEndpointData
-                  ? content.replace(/<ResponseExample>[\s\S]*?<\/ResponseExample>/g, '')
-                  : content}
-                components={AllComponentsWithInline}
-                options={{
-                  // Keep expression props (e.g. cols={2}) compatible under next-mdx-remote v6.
-                  ...mdxSecurityOptions,
-                  mdxOptions: {
-                    remarkPlugins: [remarkGfm, [remarkVisibility, { audience: 'humans' }], ...getTypographyRemarkPlugins(config), ...getLatexRemarkPlugins(config)],
-                    rehypePlugins: [rehypeNoZoomToData, rehypeClassToClassName, rehypeCodeMeta, createShikiRehypePlugin(highlighter, config), rehypeRestoreDataTitle, ...getLatexRehypePlugins(config), rehypeSlug],
-                    recmaPlugins: [recmaCompoundComponents],
-                  },
-                }}
-              />
+              <StepSlugProvider entries={stepEntries}>
+                <MDXRemote
+                  source={openApiEndpointData
+                    ? content.replace(/<ResponseExample>[\s\S]*?<\/ResponseExample>/g, '')
+                    : content}
+                  components={AllComponentsWithInline}
+                  options={{
+                    // Keep expression props (e.g. cols={2}) compatible under next-mdx-remote v6.
+                    ...mdxSecurityOptions,
+                    mdxOptions: {
+                      remarkPlugins: [remarkGfm, [remarkVisibility, { audience: 'humans' }], ...getTypographyRemarkPlugins(config), ...getLatexRemarkPlugins(config)],
+                      rehypePlugins: [rehypeNoZoomToData, rehypeClassToClassName, rehypeCodeMeta, createShikiRehypePlugin(highlighter, config), rehypeRestoreDataTitle, ...getLatexRehypePlugins(config), rehypeSlug],
+                      recmaPlugins: [recmaCompoundComponents],
+                    },
+                  }}
+                />
+              </StepSlugProvider>
             </ImagePriorityProvider>
           </div>
 
@@ -736,19 +747,21 @@ export default async function DocPage({ params }: PageProps) {
 
   // MDX content for non-API pages (extracted for conditional ViewWrapper wrapping)
   const mdxContent = (
-    <MDXRemote
-      source={content}
-      components={AllComponentsWithInline}
-      options={{
-        // Keep expression props (e.g. cols={2}) compatible under next-mdx-remote v6.
-        ...mdxSecurityOptions,
-        mdxOptions: {
-          remarkPlugins: [remarkGfm, [remarkVisibility, { audience: 'humans' }], ...getTypographyRemarkPlugins(config), ...getLatexRemarkPlugins(config)],
-          rehypePlugins: [rehypeNoZoomToData, rehypeClassToClassName, rehypeCodeMeta, createShikiRehypePlugin(highlighter, config), rehypeRestoreDataTitle, ...getLatexRehypePlugins(config), rehypeSlug],
-          recmaPlugins: [recmaCompoundComponents],
-        },
-      }}
-    />
+    <StepSlugProvider entries={stepEntries}>
+      <MDXRemote
+        source={content}
+        components={AllComponentsWithInline}
+        options={{
+          // Keep expression props (e.g. cols={2}) compatible under next-mdx-remote v6.
+          ...mdxSecurityOptions,
+          mdxOptions: {
+            remarkPlugins: [remarkGfm, [remarkVisibility, { audience: 'humans' }], ...getTypographyRemarkPlugins(config), ...getLatexRemarkPlugins(config)],
+            rehypePlugins: [rehypeNoZoomToData, rehypeClassToClassName, rehypeCodeMeta, createShikiRehypePlugin(highlighter, config), rehypeRestoreDataTitle, ...getLatexRehypePlugins(config), rehypeSlug],
+            recmaPlugins: [recmaCompoundComponents],
+          },
+        }}
+      />
+    </StepSlugProvider>
   );
 
   // Shared article content for non-API pages

package/vendored/app/api/isr-health/route.ts

@@ -6,7 +6,6 @@
  */
 
 import { NextResponse } from 'next/server';
-import { getConfigCacheSize } from '@/lib/r2-content';
 import { getSnippetCacheSize } from '@/lib/snippet-compiler-isr';
 import { getOpenApiCacheSize } from '@/lib/openapi-isr';
 import { isIsrMode } from '@/lib/page-isr-helpers';
@@ -14,7 +13,9 @@ import { isIsrMode } from '@/lib/page-isr-helpers';
 interface HealthCheck {
   status: 'ok' | 'degraded' | 'unhealthy';
   cache: {
-    configEntries: number;
+    // configEntries removed — config is now in Next.js Data Cache (unstable_cache),
+    // which is opaque from inside the lambda. Use cacheLayer field instead.
+    cacheLayer: string;
     snippetEntries: number;
     openApiEntries: number;
   };
@@ -40,9 +41,10 @@ export async function GET() {
     heapTotalMB: Math.round(memUsage.heapTotal / 1024 / 1024),
   };
 
-  // Cache stats from actual cache modules
+  // Cache stats — config/mdx/snippet/openapi raw content now in unstable_cache (opaque).
+  // snippetEntries and openApiEntries reflect the in-memory parsed-object layers only.
   const cache = {
-    configEntries: getConfigCacheSize(),
+    cacheLayer: 'unstable_cache',
     snippetEntries: getSnippetCacheSize(),
     openApiEntries: getOpenApiCacheSize(),
   };

package/vendored/components/mdx/StepSlugContext.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import { createContext, useContext, useRef, ReactNode } from 'react';
+import { generateSlug } from '@/lib/heading-extractor';
+
+export interface StepSlugEntry {
+  title: string;
+  slug: string;
+}
+
+interface StepSlugContextValue {
+  // Per-title counter — advances each time useStepSlug is called for that title.
+  counts: Map<string, number>;
+  entries: StepSlugEntry[];
+}
+
+const StepSlugCtx = createContext<StepSlugContextValue | null>(null);
+
+export function StepSlugProvider({
+  entries,
+  children,
+}: {
+  entries: StepSlugEntry[];
+  children: ReactNode;
+}) {
+  // useRef so the same Map persists across renders. We rely on the same
+  // contract React's own useId rests on: source-order rendering during SSR
+  // and during client hydration produces matching ids.
+  const ref = useRef<StepSlugContextValue | null>(null);
+  if (ref.current === null || ref.current.entries !== entries) {
+    ref.current = { counts: new Map(), entries };
+  }
+  return <StepSlugCtx.Provider value={ref.current}>{children}</StepSlugCtx.Provider>;
+}
+
+/**
+ * Resolve the unique slug for a Step with this title. Each call advances the
+ * per-title counter, so two Steps with the same title get sequential slugs
+ * from the provider's `entries` list. Falls back to `generateSlug(title)` if
+ * no provider is mounted (preview/storybook/etc).
+ */
+export function useStepSlug(title: string | undefined): string | undefined {
+  const ctx = useContext(StepSlugCtx);
+  if (!title) return undefined;
+  if (!ctx) return generateSlug(title) || undefined;
+
+  const idx = ctx.counts.get(title) ?? 0;
+  ctx.counts.set(title, idx + 1);
+
+  let seen = 0;
+  for (const entry of ctx.entries) {
+    if (entry.title !== title) continue;
+    if (seen === idx) return entry.slug;
+    seen += 1;
+  }
+  return generateSlug(title) || undefined;
+}

package/vendored/components/mdx/Steps.tsx

@@ -2,7 +2,7 @@
 
 import { ReactNode, Children, cloneElement, isValidElement, memo } from 'react';
 import { getIconClass } from '@/lib/icon-utils';
-import { generateSlug } from '@/lib/heading-extractor';
+import { useStepSlug } from './StepSlugContext';
 
 type TitleSize = 'p' | 'h2' | 'h3';
 type IconType = 'regular' | 'solid' | 'light' | 'thin' | 'sharp-solid' | 'duotone' | 'brands';
@@ -130,7 +130,7 @@ function StepTitle({ title, titleSize }: { title: string; titleSize: TitleSize }
 
 export const Step = memo(function Step({ title, children, stepNumber, isLast, icon, iconType, titleSize = 'p' }: StepProps) {
   const containerClassName = isLast ? 'relative pb-0' : 'relative pb-8';
-  const slug = title ? generateSlug(title) || undefined : undefined;
+  const slug = useStepSlug(title);
 
   // Emit both attrs together or neither — the DOM scanner keys off
   // `data-step-number`, so a label without a number would be a dangling

package/vendored/components/navigation/TableOfContents.tsx

@@ -53,6 +53,31 @@ function getOffsetRelativeTo(element: HTMLElement, container: HTMLElement): numb
   return offset;
 }
 
+// Breathing-room buffer at top/bottom edges of the TOC scroll container so
+// the active item doesn't sit flush against the edge after auto-scrolling.
+// 80px lines up with the TOC's `py-6 sm:py-10` outer padding (PageColumns.tsx
+// wrapper); update both together if that padding changes.
+const TOC_SCROLL_PAD = 80;
+
+/**
+ * Walk up from `start` looking for the nearest ancestor whose computed
+ * overflow-y is `auto` or `scroll`. Returns null if none is found before
+ * reaching <body>. The TOC lives inside `<aside class="toc-scroll">` which
+ * has `xl:overflow-y-auto`; this helper finds it without hard-coding a
+ * selector so the component remains reusable in other layouts.
+ */
+function findScrollableAncestor(start: HTMLElement): HTMLElement | null {
+  let el: HTMLElement | null = start.parentElement;
+  while (el && el !== document.body) {
+    const cs = getComputedStyle(el);
+    if (cs.overflowY === 'auto' || cs.overflowY === 'scroll') {
+      return el;
+    }
+    el = el.parentElement;
+  }
+  return null;
+}
+
 /**
  * Calculate the thumb position (top + height) spanning all active anchors.
  */
@@ -105,6 +130,53 @@ export function TableOfContents({ content, className = '' }: TableOfContentsProp
     updateThumb();
   }, [updateThumb]);
 
+  // Keep the active TOC item visible inside the TOC's own scroll container
+  // (the right-side `<aside class="toc-scroll">` is independent of the center
+  // content scroll, so it doesn't follow the user's reading position on its
+  // own). When `activeAnchors` changes, find the first active link, locate
+  // the nearest scrollable ancestor, and nudge ONLY that ancestor's scrollTop
+  // — never `scrollIntoView`, which would also scroll <main>/window and yank
+  // the user's reading position in the center column.
+  useEffect(() => {
+    if (activeAnchors.length === 0) return;
+    const container = containerRef.current;
+    if (!container) return;
+
+    const firstActiveId = activeAnchors[0];
+    const link = container.querySelector<HTMLElement>(
+      `a[href="#${firstActiveId}"]`,
+    );
+    if (!link) return;
+
+    const scroller = findScrollableAncestor(container);
+    if (!scroller) return;
+
+    const linkRect = link.getBoundingClientRect();
+    // Bail out if the link hasn't laid out yet. Two real cases this catches:
+    //   1. First commit before the browser has measured boxes (or jsdom's
+    //      default 0×0 rect in unit tests).
+    //   2. Sub-xl breakpoints where the TOC's parent <aside class="hidden
+    //      xl:block"> is `display: none` — TableOfContents is still mounted
+    //      but every descendant returns 0×0 rects. Without this guard, the
+    //      ancestor walker below would pick `<main>` (which has
+    //      overflow-y:auto in our layout) and scroll the page itself.
+    if (linkRect.width === 0 && linkRect.height === 0) return;
+
+    const scrollerRect = scroller.getBoundingClientRect();
+    // If the scroller is shorter than 2× the padding, the "already visible"
+    // window `[top + pad, bottom - pad]` collapses to nothing and both branches
+    // below would fire on alternating ticks, oscillating scrollTop. Bail out
+    // — the scroller is too short to position usefully anyway. Reachable on
+    // 200%-zoomed iframe-embedded docs viewers (~220px aside).
+    if (scrollerRect.height < TOC_SCROLL_PAD * 2) return;
+
+    if (linkRect.top < scrollerRect.top + TOC_SCROLL_PAD) {
+      scroller.scrollTop += linkRect.top - scrollerRect.top - TOC_SCROLL_PAD;
+    } else if (linkRect.bottom > scrollerRect.bottom - TOC_SCROLL_PAD) {
+      scroller.scrollTop += linkRect.bottom - scrollerRect.bottom + TOC_SCROLL_PAD;
+    }
+  }, [activeAnchors]);
+
   // Regenerate SVG path on headings change + resize
   useEffect(() => {
     const container = containerRef.current;
@@ -495,7 +567,7 @@ export function TableOfContents({ content, className = '' }: TableOfContentsProp
               }
             };
 
-            // 30px leaves room for the absolute-positioned 18px step circle
+            // 30px leaves room for the absolute-positioned 14px step circle
             // (insetInlineStart: 1) + a gap. Non-step H3s use the same value
             // so mixed step/non-step groups align visually.
             const startOffset = heading.level === 3
@@ -518,13 +590,13 @@ export function TableOfContents({ content, className = '' }: TableOfContentsProp
                 {hasStepNumber && (
                   <span
                     aria-hidden="true"
-                    className="absolute flex items-center justify-center rounded-full text-[11px] font-medium"
+                    className="absolute flex items-center justify-center rounded-full text-[9px] font-medium"
                     style={{
-                      insetInlineStart: 1,
+                      insetInlineStart: 3,
                       top: '50%',
                       transform: 'translateY(-50%)',
-                      width: 18,
-                      height: 18,
+                      width: 14,
+                      height: 14,
                       backgroundColor: isActive
                         ? 'var(--color-primary)'
                         : 'var(--color-bg-primary)',

package/vendored/lib/cache-tags.ts

@@ -0,0 +1,25 @@
+/**
+ * Cache tag helpers for unstable_cache + revalidateTag (Next.js Data Cache).
+ *
+ * Tag shape (keep stable — referenced by /api/revalidate callers in
+ * build-service Cloud Run and by revalidation-helpers.ts invalidators):
+ *
+ *   project:<slug>             invalidates ALL data for a project
+ *   config:<slug>              invalidates only the docs.json config
+ *   mdx:<slug>:<path>          invalidates one page
+ *   snippet:<slug>:<path>      invalidates one snippet
+ *   openapi:<slug>:<path>      invalidates one OpenAPI spec
+ *   manifest:<slug>            invalidates the project path manifest
+ *   static:<slug>:<filename>   invalidates one static file (custom.css, custom.js)
+ *
+ * Not related to the `project-<slug>` hyphen-tagged CDN header set by
+ * app/api/r2/[project]/[...path]/route.ts — that's a separate edge-cache
+ * namespace on the R2 binary route and does not intersect with these.
+ */
+export const projectCacheTag = (slug: string): string => `project:${slug}`;
+export const configCacheTag = (slug: string): string => `config:${slug}`;
+export const mdxCacheTag = (slug: string, path: string): string => `mdx:${slug}:${path}`;
+export const snippetCacheTag = (slug: string, path: string): string => `snippet:${slug}:${path}`;
+export const openapiCacheTag = (slug: string, path: string): string => `openapi:${slug}:${path}`;
+export const manifestCacheTag = (slug: string): string => `manifest:${slug}`;
+export const staticCacheTag = (slug: string, filename: string): string => `static:${slug}:${filename}`;

package/vendored/lib/cache-utils.ts

@@ -0,0 +1,19 @@
+/**
+ * Pure in-memory cache helpers. Kept in a standalone module so client
+ * bundles can import it without pulling in server-only `next/cache` APIs
+ * via r2-content.ts (Turbopack rejects transitive imports of
+ * `revalidateTag` into client components).
+ */
+
+export function evictOldest<K, V extends { timestamp: number }>(
+  cache: Map<K, V>,
+  maxSize: number
+): void {
+  if (cache.size <= maxSize) return;
+
+  const entries = [...cache.entries()].sort((a, b) => a[1].timestamp - b[1].timestamp);
+  const toDelete = entries.slice(0, cache.size - maxSize);
+  for (const [key] of toDelete) {
+    cache.delete(key);
+  }
+}

package/vendored/lib/heading-extractor.ts

@@ -26,6 +26,19 @@ export function generateSlug(text: string): string {
     .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.
+ */
+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}`;
+}
+
 const HEADING_REGEX = /^(#{1,6})\s+(.+)$/;
 const FENCE_REGEX = /^(`{3,}|~{3,})/;
 const UPDATE_LABEL_REGEX = /<Update\s+label=["']([^"']+)["']/;
@@ -54,6 +67,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>();
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -85,8 +101,9 @@ export function extractHeadings(content: string): HeadingInfo[] {
     if (headingMatch) {
       const level = headingMatch[1].length;
       const text = headingMatch[2].trim();
-      const id = generateSlug(text);
-      if (id) {
+      const base = generateSlug(text);
+      if (base) {
+        const id = uniquifySlug(seenSlugs, base);
         headings.push({ id, text, level, line: i + 1 });
       }
     }
@@ -94,8 +111,9 @@ export function extractHeadings(content: string): HeadingInfo[] {
     const updateMatch = line.match(UPDATE_LABEL_REGEX);
     if (updateMatch) {
       const text = updateMatch[1];
-      const id = generateSlug(text);
-      if (id) {
+      const base = generateSlug(text);
+      if (base) {
+        const id = uniquifySlug(seenSlugs, base);
         headings.push({ id, text, level: 2, line: i + 1 });
       }
     }
@@ -103,9 +121,10 @@ export function extractHeadings(content: string): HeadingInfo[] {
     if (inStepsBlock) {
       for (const match of line.matchAll(STEP_TITLE_REGEX)) {
         const text = match[1] ?? match[2];
-        const id = generateSlug(text);
-        if (!id) continue;
+        const base = generateSlug(text);
+        if (!base) continue;
         stepCounter += 1;
+        const id = uniquifySlug(seenSlugs, base);
         headings.push({
           id,
           text,

package/vendored/lib/indexnow.ts

@@ -35,7 +35,7 @@ export function buildChangedUrls(
   if (changedPaths.length === 0) return [];
   const prefix = hostAtDocs ? '/docs' : '';
   return changedPaths.map((p) => {
-    // Defensive: getChangedPaths() already strips extensions, but guard against raw file paths
+    // Defensive: callers strip the .mdx extension, but guard against raw file paths
     const clean = p.replace(/\.mdx?$/, '');
     return `${baseUrl}${prefix}/${clean}`;
   });

package/vendored/lib/middleware-helpers.ts

@@ -27,6 +27,89 @@ import type { NextRequest } from 'next/server';
  */
 export const VALID_SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
 
+/**
+ * Mangle a request pathname so it routes into the (docs)/[project] sub-tree.
+ * The proxy applies this rewrite internally; user-visible URLs are unchanged.
+ *
+ * Slug must be URL-safe — VALID_SLUG_RE catches that upstream, so we
+ * fail loud here if something slipped through.
+ */
+export function injectProjectSlugIntoPath(
+  pathname: string,
+  projectSlug: string,
+  _hostAtDocs: boolean,
+): string {
+  if (!pathname || !pathname.startsWith('/')) {
+    throw new Error(`injectProjectSlugIntoPath: invalid pathname '${pathname}'`);
+  }
+  if (!VALID_SLUG_RE.test(projectSlug)) {
+    throw new Error(`injectProjectSlugIntoPath: invalid slug '${projectSlug}'`);
+  }
+  // hostAtDocs note: the user URL has /docs prefix; we still inject [project]
+  // BEFORE everything else so the route is /[project]/docs/<rest>. The
+  // existing (docs)/[project]/[[...slug]] catch-all handles either shape.
+  if (pathname === '/') return `/${projectSlug}/`;
+  return `/${projectSlug}${pathname}`;
+}
+
+/**
+ * Names of static endpoint route handlers that live at the bare app/<name>/route.ts
+ * (and their app/docs/<name>/route.ts twins for hostAtDocs sites). They render
+ * project-aware output, but do so by reading x-project-slug headers — they are
+ * NOT inside the (docs)/[project] sub-tree, so rewriting their URL to inject a
+ * /[project]/ prefix would route to a path that doesn't exist and 404.
+ *
+ * KEEP IN SYNC with the actual files on disk: every app/<name>/route.ts must
+ * appear here. The Step 5 verification grep guards against drift.
+ */
+export const STATIC_ENDPOINT_NAMES = [
+  'sitemap.xml',
+  'llms.txt',
+  'llms-full.txt',
+  'robots.txt',
+  'feed.xml',
+  'docs.json',
+  'search-data.json',
+] as const;
+
+/** Precomputed path set so the hot-path check avoids per-call template allocs. */
+const STATIC_ENDPOINT_PATHS = new Set<string>(
+  STATIC_ENDPOINT_NAMES.flatMap((n) => [`/${n}`, `/docs/${n}`]),
+);
+
+/** Roots that bypass the (docs) rewrite — both `/X` exact and `/X/...` prefix. */
+const SYSTEM_PATH_ROOTS = [
+  '/_next',      // Next.js asset traffic — most-common bypass for docs sites
+  '/api',
+  '/_jd',
+  '/.well-known',
+  '/jd/unlock',
+] as const;
+
+/** True if pathname is exactly `root` or lives under `root/`. */
+export function isPathOrUnder(pathname: string, root: string): boolean {
+  return pathname === root || pathname.startsWith(root + '/');
+}
+
+/**
+ * Return true when a pathname should be internally rewritten into the
+ * (docs)/[project] route group. Stays outside the group for:
+ *   - SYSTEM_PATH_ROOTS            (api routes, Next assets, _jd, .well-known, unlock)
+ *   - STATIC_ENDPOINT_NAMES files  (sitemap.xml, llms.txt, robots.txt, feed.xml,
+ *                                    docs.json, search-data.json — and their
+ *                                    /docs/<name> twins for hostAtDocs sites)
+ *
+ * MDX pages under /docs/<slug> (hostAtDocs MDX content) ARE rewritten — only
+ * the named static endpoints above are excluded.
+ */
+export function shouldRewriteIntoDocsGroup(pathname: string): boolean {
+  if (STATIC_ENDPOINT_PATHS.has(pathname)) return false;
+  for (const root of SYSTEM_PATH_ROOTS) {
+    if (isPathOrUnder(pathname, root)) return false;
+  }
+  return true;
+}
+
 /**
  * Result of project resolution.
  */
@@ -311,19 +394,26 @@ export async function checkRedirects(
  * - /api/ogimage → NOT skipped (could be a doc page)
  */
 export const INTERNAL_API_ROUTES = [
-  '/api/assets',     // Asset serving from R2 (app/api/assets/[...path])
-  '/api/ev',         // Analytics events (app/api/ev)
-  '/api/indexnow',   // IndexNow key verification (app/api/indexnow/[key])
-  '/api/isr-health', // Health check endpoint (app/api/isr-health)
-  '/api/chat',       // Chat endpoint (app/api/chat/[project])
+  '/api/assets',      // Asset serving from R2 (app/api/assets/[...path])
+  '/api/chat',        // Chat endpoint (app/api/chat/[project]) — gated explicitly in proxy.ts
   '/api/docs-search', // Docs Search API (app/api/docs-search/[project]/search)
-  '/api/mcp',        // MCP endpoint (app/api/mcp/[project])
-  '/api/og',         // OG image generation (app/api/og)
-  '/api/playground', // API playground (token, proxy, demo) — must skip hostAtDocs redirect
-  '/api/r2',         // R2 content serving (app/api/r2/[project]/[...path])
-  '/api/revalidate', // Cache revalidation (app/api/revalidate)
-  '/api/search-ev',  // Search analytics proxy (app/api/search-ev)
-];
+  '/api/ev',          // Analytics events (app/api/ev)
+  '/api/indexnow',    // IndexNow key verification (app/api/indexnow/[key])
+  '/api/isr-health',  // Health check endpoint (app/api/isr-health)
+  '/api/mcp',         // MCP endpoint (app/api/mcp/[project]) — gated explicitly in proxy.ts
+  '/api/og',          // OG image generation (app/api/og)
+  '/api/playground',  // API playground (token, proxy, demo) — must skip hostAtDocs redirect
+  '/api/r2',          // R2 content serving (app/api/r2/[project]/[...path]) — gated explicitly in proxy.ts
+  '/api/revalidate',  // Cache revalidation (app/api/revalidate)
+  '/api/search-ev',   // Search analytics proxy (app/api/search-ev)
+  // NOTE: /api/jd is intentionally NOT here — /api/jd/unlock reads
+  // x-project-slug + x-host-at-docs headers that middleware sets.
+  // NOTE: /api/markdown-export is intentionally NOT here either — it serves
+  // project MDX, which on password-protected sites must hit the implicit
+  // auth gate at proxy.ts:362. Bypassing middleware would leak content.
+  // /api/raw-content is also kept off the list (dev-only; throws in ISR
+  // mode anyway, so adding it would be a no-op with worse documentation).
+] as const;
 
 /**
  * Check if path is an internal API route.
@@ -338,9 +428,7 @@ export const INTERNAL_API_ROUTES = [
  * isInternalApiRoute('/api/users/list')   // false (doc page)
  */
 export function isInternalApiRoute(pathname: string): boolean {
-  return INTERNAL_API_ROUTES.some(route =>
-    pathname === route || pathname.startsWith(route + '/')
-  );
+  return INTERNAL_API_ROUTES.some((route) => isPathOrUnder(pathname, route));
 }
 
 /**

package/vendored/lib/navigation-resolver.ts

@@ -22,7 +22,7 @@ import type {
 
 import { normalizeNavPage, getIconName } from './docs-types';
 import { getLanguageDisplayInfo, extractLanguageFromPath } from './language-utils';
-import { evictOldest } from './r2-content';
+import { evictOldest } from './cache-utils';
 
 // =============================================================================
 // TYPE GUARDS

package/vendored/lib/openapi-isr.ts

@@ -94,16 +94,21 @@ export async function resolveOpenApiSpec(
   return fetchOpenApiSpecFromR2(projectSlug, specRef);
 }
 
-/** Clear OpenAPI cache. If projectSlug is provided, clears only that project. */
+/**
+ * Clear the in-memory parsed-spec Map (covers external-URL specs not wrapped
+ * in unstable_cache). Does NOT emit a project: revalidateTag — that would
+ * discard config/mdx/snippet/static entries unrelated to OpenAPI; the caller
+ * (executeRevalidation) dispatches the project tag explicitly when needed.
+ */
 export function clearOpenApiCache(projectSlug?: string): void {
-  if (projectSlug) {
-    for (const key of specCache.keys()) {
-      if (key.startsWith(`r2:${projectSlug}:`)) {
-        specCache.delete(key);
-      }
-    }
-  } else {
+  if (!projectSlug) {
     specCache.clear();
+    return;
+  }
+  for (const key of specCache.keys()) {
+    if (key.startsWith(`r2:${projectSlug}:`)) {
+      specCache.delete(key);
+    }
   }
 }