jamdesk 1.1.75 → 1.1.76

package/vendored/lib/prefetch-rsc.ts

@@ -0,0 +1,19 @@
+// Issues an RSC GET (without `Next-Router-Prefetch`) so the route's full
+// server render runs and the regional Vercel Data Cache is populated.
+
+export function prefetchRsc(href: string): void {
+  if (typeof window === 'undefined') return;
+  const sep = href.includes('?') ? '&' : '?';
+  const url = `${href}${sep}_rsc=${Date.now().toString(36)}`;
+  fetch(url, {
+    method: 'GET',
+    headers: { RSC: '1', Accept: 'text/x-component' },
+    cache: 'no-store',
+    credentials: 'same-origin',
+    priority: 'low',
+  })
+    // Consume the body so the response buffer is released. Letting it
+    // sit unread holds ~100KB per paced fetch in memory until GC.
+    .then((r) => r.arrayBuffer())
+    .catch(() => {});
+}

package/vendored/lib/r2-content.ts

@@ -61,3 +61,19 @@ export async function fetchStaticFile(_projectSlug: string, _filename: string):
 export async function fetchCustomCss(_projectSlug: string): Promise<string | null> { return null; }
 export async function fetchCustomJs(_projectSlug: string): Promise<string | null> { return null; }
 export function setR2Client(_client: unknown): void {}
+
+// Stubs for the perf observability + race-fetch additions. CLI dev mode
+// reads from the filesystem so these all no-op.
+export const R2_CLIENT_CONFIG = {} as Record<string, unknown>;
+export const R2_OPENAPI_CLIENT_CONFIG = {} as Record<string, unknown>;
+export type R2TimingPhase =
+  | 'layout-metadata'
+  | 'layout-render'
+  | 'page-metadata'
+  | 'page-render';
+export function incrementR2Op(_ms: number): void {}
+export function getR2OpsSnapshot(): { ops: number; ms: number } { return { ops: 0, ms: 0 }; }
+export function withR2OpsContext<T>(fn: () => T): T { return fn(); }
+export function enterR2OpsContextForTest<T>(fn: () => T): T { return fn(); }
+export function emitR2OpsSummary(_phase: R2TimingPhase, _projectSlug?: string | null): void {}
+export async function withTimeout<T>(promise: Promise<T>, _operation: string): Promise<T> { return promise; }

package/vendored/lib/r2-feature-flags.ts

@@ -0,0 +1,7 @@
+// `?.trim()` is defensive against trailing whitespace in Vercel UI / CLI
+// stdin — see ISR_MODE incident in builder/CLAUDE.md. Function (not const)
+// so tests can flip the env var via `vi.stubEnv` without a module reset,
+// matching the existing `isIsrMode()` pattern in page-isr-helpers.ts.
+export function isR2ParallelCounterEnabled(): boolean {
+  return process.env.R2_PARALLEL_COUNTER?.trim() === 'true';
+}

package/vendored/lib/render-doc-page-openapi-helpers.ts

@@ -0,0 +1,110 @@
+// Try OpenAPI spec candidates concurrently and return the first by INDEX
+// (not by resolution order) whose parse succeeds. Multilingual docs sites
+// (e.g. 10 languages × 3 spec extensions = 30 candidates) previously paid
+// up to 30 sequential R2 RTTs on a cache miss. We fire all candidate
+// fetches at once but await them in index order, so latency on the common
+// case (primary succeeds) is bounded by the primary fetch — not by the
+// slowest of all candidates as it would be with Promise.allSettled.
+import type { OpenApiEndpointData, parseEndpoint } from '@/lib/openapi';
+
+type TryCandidate<T> = (specPath: string) => Promise<{ endpoint: T; specPath: string }>;
+
+export type CandidateResult<T> =
+  | { kind: 'success'; endpoint: T; specPath: string }
+  | { kind: 'failure'; lastError: unknown; specPath: string };
+
+type Settled<T> =
+  | { ok: true; endpoint: T; specPath: string }
+  | { ok: false; error: unknown };
+
+export async function tryOpenApiCandidatesInParallel<T = OpenApiEndpointData>(
+  candidates: string[],
+  tryCandidate: TryCandidate<T>,
+): Promise<CandidateResult<T>> {
+  if (candidates.length === 0) {
+    return { kind: 'failure', lastError: new Error('no candidates'), specPath: '' };
+  }
+
+  // Eager catch handlers prevent unhandled-rejection logs when a slow loser
+  // rejects after the primary has already won. Loser GETs continue running
+  // in the background until R2 responds; `maxAttempts: 1` on the OpenAPI
+  // client bounds them to one round-trip each.
+  const inflight: Promise<Settled<T>>[] = candidates.map((c) =>
+    tryCandidate(c).then(
+      ({ endpoint, specPath }) => ({ ok: true as const, endpoint, specPath }),
+      (error: unknown) => ({ ok: false as const, error }),
+    ),
+  );
+
+  // On all-reject, surface the primary candidate's error so logs are
+  // attributed to the intended spec — fallback errors are typically "404".
+  let primaryError: unknown | undefined;
+  for (let i = 0; i < inflight.length; i++) {
+    const r = await inflight[i];
+    if (r.ok) {
+      return { kind: 'success', endpoint: r.endpoint, specPath: r.specPath };
+    }
+    if (primaryError === undefined) primaryError = r.error;
+  }
+
+  return {
+    kind: 'failure',
+    lastError: primaryError ?? new Error('unknown'),
+    specPath: candidates[0],
+  };
+}
+
+interface TryOpenApiSpecOpts {
+  projectSlug: string | null;
+  isIsr: boolean;
+  parsedMethod: string;
+  parsedPath: string;
+  resolveIsrSpec: ((slug: string, specPath: string) => Promise<unknown>) | null;
+  getStaticSpec: ((specPath: string, contentDir: string) => Promise<{ api: unknown }>) | null;
+  contentDir: string | null;
+  parseEndpointFn: typeof parseEndpoint;
+}
+
+export function makeTryOpenApiSpec(opts: TryOpenApiSpecOpts) {
+  return async (specPath: string): Promise<{ endpoint: OpenApiEndpointData; specPath: string }> => {
+    const useIsr = opts.isIsr && !!opts.projectSlug && !!opts.resolveIsrSpec;
+    if (useIsr && opts.resolveIsrSpec && opts.projectSlug) {
+      const spec = await opts.resolveIsrSpec(opts.projectSlug, specPath);
+      const endpoint = opts.parseEndpointFn(
+        spec as Parameters<typeof parseEndpoint>[0],
+        opts.parsedMethod as never,
+        opts.parsedPath,
+        specPath,
+      );
+      return { endpoint, specPath };
+    }
+    if (!opts.getStaticSpec || !opts.contentDir) {
+      throw new Error('static spec branch requires getStaticSpec + contentDir');
+    }
+    const { api } = await opts.getStaticSpec(specPath, opts.contentDir);
+    const endpoint = opts.parseEndpointFn(
+      api as Parameters<typeof parseEndpoint>[0],
+      opts.parsedMethod as never,
+      opts.parsedPath,
+      specPath,
+    );
+    return { endpoint, specPath };
+  };
+}
+
+// Aggregated on-call signal for misconfigured projects: replaces the
+// per-failure spam log from the old sequential for-loop. Returns null
+// when there's no fallback (single candidate, or primary won). Format
+// is grep-stable — on-call dashboards key off the "[openapi] primary spec"
+// prefix and the "resolved via fallback" delimiter.
+export function formatFallbackWarning(
+  candidates: string[],
+  winnerSpecPath: string,
+  method: string,
+  path: string,
+): string | null {
+  if (candidates.length <= 1) return null;
+  const primary = candidates[0];
+  if (winnerSpecPath === primary) return null;
+  return `[openapi] primary spec "${primary}" did not contain ${method} ${path}; resolved via fallback "${winnerSpecPath}"`;
+}

package/vendored/lib/render-doc-page-parallel-helpers.ts

@@ -0,0 +1,60 @@
+// Snippets (R2 I/O) and inline-component extraction (Babel/remark CPU)
+// have no data dependency once raw + preprocessed MDX are available, so
+// they run as Promise.all. The JS event loop interleaves Babel work with
+// R2 await microtasks, giving wall-clock = max(R2, CPU) instead of sum.
+import type React from 'react';
+import type { ExtractedParam } from './remark-extract-param-fields';
+
+// AnyComponent matches the project-wide convention used in
+// process-mdx-with-exports.ts and snippet-loader-isr.ts. ComponentType<unknown>
+// is too strict — MDXComponents includes typed React components like
+// MemoExoticComponent<({ title }: CardProps) => JSX.Element>, which are NOT
+// assignable to ComponentType<unknown> (props variance).
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyComponent = React.ComponentType<any>;
+
+interface ParallelInput {
+  isIsr: boolean;
+  projectSlug: string | null;
+  rawContent: string;
+  preprocessedContent: string;
+  mdxComponents: Record<string, AnyComponent>;
+  snippetComponents: Record<string, AnyComponent>;
+  loadSnippets: (
+    projectSlug: string,
+    rawContent: string,
+    builtIns: Record<string, AnyComponent>,
+  ) => Promise<Record<string, AnyComponent>>;
+  buildAlias: (
+    rawContent: string,
+    snippetComponents: Record<string, AnyComponent>,
+  ) => Record<string, AnyComponent>;
+  extractInline: (
+    content: string,
+    components: Record<string, AnyComponent>,
+  ) => Promise<{ inlineComponents: Record<string, AnyComponent>; paramFields: ExtractedParam[] }>;
+}
+
+interface ParallelOutput {
+  snippetAliases: Record<string, AnyComponent>;
+  inlineComponents: Record<string, AnyComponent>;
+  paramFields: ExtractedParam[];
+}
+
+export async function loadSnippetsAndInlineComponents(
+  input: ParallelInput,
+): Promise<ParallelOutput> {
+  const snippetsP = input.isIsr && input.projectSlug
+    ? input.loadSnippets(input.projectSlug, input.rawContent, input.mdxComponents)
+    : Promise.resolve(input.buildAlias(input.rawContent, input.snippetComponents));
+
+  const inlineP = input.extractInline(input.preprocessedContent, input.mdxComponents);
+
+  const [snippetAliases, inline] = await Promise.all([snippetsP, inlineP]);
+
+  return {
+    snippetAliases,
+    inlineComponents: inline.inlineComponents,
+    paramFields: inline.paramFields,
+  };
+}

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

@@ -34,6 +34,9 @@ import { rehypeClassToClassName } from '@/lib/rehype-class-to-classname';
 import { remarkSvgNamespaceAttrs } from '@/lib/remark-svg-namespace-attrs';
 import { rehypeNoZoomToData } from '@/lib/rehype-nozoom-to-data';
 import { rehypeUnwrapNestedAnchors } from './rehype-unwrap-nested-anchors';
+import { loadSnippetsAndInlineComponents } from './render-doc-page-parallel-helpers';
+import { tryOpenApiCandidatesInParallel, makeTryOpenApiSpec, formatFallbackWarning } from './render-doc-page-openapi-helpers';
+import { logger } from '../shared/logger';
 import { preprocessMdx, containsPanel, containsView, buildSnippetAliasMap } from '@/lib/preprocess-mdx';
 import { loadSnippetsForIsr } from '@/lib/snippet-loader-isr';
 import { PanelWrapper } from '@/components/mdx/PanelWrapper';
@@ -229,26 +232,30 @@ export async function buildDocMetadata(input: RenderInput): Promise<Metadata> {
     ? (data.title === config.name ? { absolute: data.title } : data.title)
     : { absolute: buildSiteTitle(config.name) };
 
+  const markdownHref = `${hostAtDocs ? '/docs/' : '/'}${pagePath}.md`;
+
   return {
     title: titleValue,
     description: data.description || '',
     ...seoMetadata,
     ...(isRoot && { robots: { index: false, follow: true } }),
-    ...(data.rss ? {
-      alternates: {
-        ...seoMetadata.alternates,
-        types: {
+    alternates: {
+      ...seoMetadata.alternates,
+      types: {
+        'text/markdown': markdownHref,
+        ...(data.rss && {
           'application/rss+xml': hostAtDocs ? '/docs/feed.xml' : '/feed.xml',
-        },
+        }),
       },
-    } : {}),
+    },
   };
 }
 
 export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
   const { slug: slugInput, projectSlug, hostAtDocs, requestHeaders } = input;
+  const isIsr = isIsrMode();
 
-  if (isIsrMode()) {
+  if (isIsr) {
     if (!projectSlug) notFound();
     const exists = await projectExists(projectSlug);
     if (!exists) notFound();
@@ -256,6 +263,10 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
 
   const loader = getContentLoader(projectSlug ?? undefined);
   const configP = loader.getConfig();
+  // Shiki init takes 200-500ms on cold function instances. Kick it off
+  // before the content fetch so the two run concurrently. Warm instances
+  // resolve from the globalThis singleton instantly.
+  const highlighterP = getHighlighter();
 
   const normalizedSlug = normalizeSlugForContent(slugInput || [], hostAtDocs);
   const slug = needsSlugRewrite(normalizedSlug)
@@ -263,9 +274,10 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
     : normalizedSlug;
   const pagePath = slug.join('/');
   const currentLang = extractLanguageFromPath(`/${pagePath}`);
-  const [fileContents, config] = await Promise.all([
+  const [fileContents, config, highlighter] = await Promise.all([
     loader.getContent(pagePath).catch(() => null),
     configP,
+    highlighterP,
   ]);
 
   if (!fileContents) {
@@ -285,14 +297,14 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
   });
   const jsonLdScript = renderJsonLdScript(jsonLd);
 
-  const highlighter = await getHighlighter();
+  const openApiSpecField = typeof data.openapi === 'string' && data.openapi ? data.openapi : null;
 
-  let snippetAliases: Record<string, React.ComponentType<unknown>> = {};
-  if (isIsrMode() && projectSlug) {
-    snippetAliases = await loadSnippetsForIsr(projectSlug, rawContent, MDXComponents);
-  } else {
-    snippetAliases = buildSnippetAliasMap(rawContent, SnippetComponents);
-  }
+  // Resolve openapi-isr dynamic import concurrently with the snippet/inline
+  // parallel block. Win is small — one module-resolve, ~5–30ms on a true cold
+  // start, <1ms on warm V8. Kept because the syntactic cost is one ternary.
+  const openApiIsrP = openApiSpecField && isIsr && projectSlug
+    ? import('@/lib/openapi-isr')
+    : null;
 
   const content = preprocessMdx(rawContent, { assetVersion: config.assetVersion });
 
@@ -300,13 +312,29 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
     .filter(h => typeof h.stepNumber === 'number')
     .map(h => ({ title: h.text, slug: h.id }));
 
-  const { inlineComponents, paramFields } = await extractInlineComponents(content, MDXComponents);
+  // [render-timing] proves the snippet/inline parallel win. With Promise.all,
+  // wall-clock should be ~max(R2_snippets, CPU_inline). Compare against the
+  // per-op `[r2-timing]` for snippet R2: if snippetInlineMs ≈ snippet R2 ms,
+  // inline ran "for free" inside the R2 wait. Sum-of-both = parallelism failed.
+  const snippetInlineStart = performance.now();
+  const { snippetAliases, inlineComponents, paramFields } = await loadSnippetsAndInlineComponents({
+    isIsr,
+    projectSlug: projectSlug ?? null,
+    rawContent,
+    preprocessedContent: content,
+    mdxComponents: MDXComponents,
+    snippetComponents: SnippetComponents,
+    loadSnippets: loadSnippetsForIsr,
+    buildAlias: buildSnippetAliasMap,
+    extractInline: extractInlineComponents,
+  });
+  const snippetInlineMs = Math.round(performance.now() - snippetInlineStart);
 
   const overriddenComponents = Object.keys(inlineComponents).filter(
     (name) => name in MDXComponents,
   );
   if (overriddenComponents.length > 0) {
-    console.warn(
+    logger.warn(
       `[MDX] Inline component(s) override built-in: ${overriddenComponents.join(', ')} in ${slug.join('/')}`,
     );
   }
@@ -339,9 +367,11 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
   let openApiEndpointData: OpenApiEndpointData | null = null;
   let openApiCodeExamples: CodeExample[] | null = null;
   let openApiError: string | null = null;
+  let openApiMs: number | null = null;
+  let openApiCandidates = 0;
 
   let lastFailure: { err: unknown; specPath: string } | null = null;
-  if (data.openapi && typeof data.openapi === 'string') {
+  if (openApiSpecField) {
     try {
       const openApiConfig = config.api?.openapi;
       const allSpecPaths: string[] = typeof openApiConfig === 'string'
@@ -351,7 +381,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
           : [];
 
       const parsed = parseOpenApiFrontmatter(
-        data.openapi,
+        openApiSpecField,
         allSpecPaths.length > 0 ? allSpecPaths : undefined,
       );
 
@@ -359,43 +389,40 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
         ? allSpecPaths
         : [parsed.specPath];
       const specsToTry = baseSpecs.flatMap(p => candidateSpecPaths(p, currentLang));
+      openApiCandidates = specsToTry.length;
 
-      const useIsr = isIsrMode() && !!projectSlug;
-      const resolveSpec = useIsr
-        ? (await import('@/lib/openapi-isr')).resolveOpenApiSpec
+      const useIsr = isIsr && !!projectSlug;
+      const resolveSpec = useIsr && openApiIsrP
+        ? (await openApiIsrP).resolveOpenApiSpec
         : null;
       const contentDir = useIsr ? null : getContentDir();
 
-      for (let i = 0; i < specsToTry.length; i++) {
-        const specPath = specsToTry[i];
-        try {
-          if (resolveSpec && projectSlug) {
-            const spec = await resolveSpec(projectSlug, specPath);
-            openApiEndpointData = parseEndpoint(
-              spec as Parameters<typeof parseEndpoint>[0],
-              parsed.method,
-              parsed.path,
-              specPath,
-            );
-          } else {
-            const { api } = await getCachedSpec(specPath, contentDir!);
-            openApiEndpointData = parseEndpoint(api, parsed.method, parsed.path, specPath);
-          }
-          lastFailure = null;
-          break;
-        } catch (err) {
-          lastFailure = { err, specPath };
-          const isLast = i === specsToTry.length - 1;
-          if (!isLast) {
-            console.warn(
-              `[openapi] spec candidate "${specPath}" failed; trying next: ${(err as Error).message}`,
-            );
-          }
-        }
+      const tryOne = makeTryOpenApiSpec({
+        projectSlug: projectSlug ?? null,
+        isIsr: useIsr,
+        parsedMethod: parsed.method,
+        parsedPath: parsed.path,
+        resolveIsrSpec: resolveSpec,
+        getStaticSpec: useIsr ? null : getCachedSpec,
+        contentDir,
+        parseEndpointFn: parseEndpoint,
+      });
+
+      // See `[render-timing]` block above snippetInlineMs for the verification
+      // protocol. Same idea here: openApiMs ≈ max(per-spec R2) = parallel.
+      const openApiStart = performance.now();
+      const result = await tryOpenApiCandidatesInParallel(specsToTry, tryOne);
+      openApiMs = Math.round(performance.now() - openApiStart);
+      if (result.kind === 'success') {
+        openApiEndpointData = result.endpoint;
+        lastFailure = null;
+        const warning = formatFallbackWarning(specsToTry, result.specPath, parsed.method, parsed.path);
+        if (warning) logger.warn(warning);
+      } else {
+        lastFailure = { err: result.lastError, specPath: result.specPath };
+        throw result.lastError;
       }
 
-      if (lastFailure) throw lastFailure.err;
-
       if (openApiEndpointData) {
         const { method: authMethod, headerName: authHeaderName } = resolveAuth(openApiEndpointData, config);
         const languages = config.api?.examples?.languages;
@@ -403,13 +430,21 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
       }
     } catch (err) {
       const typed = classifyOpenApiLoadError(err, lastFailure?.specPath ?? null);
-      console.warn(formatOpenApiWarning(typed));
+      logger.warn(formatOpenApiWarning(typed));
       openApiError = typed.suggestion
         ? `${typed.message} — ${typed.suggestion}`
         : typed.message;
     }
   }
 
+  logger.info('[render-timing]', {
+    region: process.env.VERCEL_REGION || 'unknown',
+    pagePath,
+    snippetInlineMs,
+    openApiMs,
+    openApiCandidates,
+  });
+
   let mdxApiMethod: HttpMethod | null = null;
   let mdxApiPath: string | null = null;
   if (data.api && typeof data.api === 'string' && !data.openapi) {

package/vendored/lib/sidebar-prefetch-walker.ts

@@ -0,0 +1,50 @@
+import type { ResolvedGroup } from '@/lib/navigation-resolver';
+
+/**
+ * Flatten a resolved navigation tree to the list of hrefs that should be
+ * prefetched under the existing group-engagement rule from Sidebar.tsx:
+ *
+ *   shouldPrefetch = level !== 0 || isExpanded || !group.name
+ *
+ * Children of a level-0 group emit only when that group is expanded.
+ * Children of nameless or deeper-level groups always emit. Order matches
+ * the rendered sidebar so paced prefetches mirror what a user is most
+ * likely to click next.
+ */
+export function getPrefetchableHrefs(
+  groups: ResolvedGroup[],
+  expandedGroups: Set<string>,
+  linkPrefix: string,
+  level: number = 0,
+): string[] {
+  const out: string[] = [];
+  const walk = (groups: ResolvedGroup[], level: number) => {
+    for (const group of groups) {
+      const isExpanded = expandedGroups.has(group.name);
+      const groupOpen = level !== 0 || isExpanded || !group.name;
+      if (!groupOpen) continue;
+
+      if (group.items) {
+        for (const item of group.items) {
+          if (item.type === 'page') {
+            out.push(`${linkPrefix}/${item.page.path}`);
+          } else if (item.type === 'group') {
+            walk([item.group], level + 1);
+          }
+        }
+      } else {
+        for (const page of group.pages) {
+          out.push(`${linkPrefix}/${page.path}`);
+        }
+        if (group.nested) walk(group.nested, level + 1);
+      }
+    }
+  };
+  walk(groups, level);
+
+  // Dedup: a docs.json config can reference the same page from two groups
+  // (uncommon but legal). Without this, the pacer fires router.prefetch()
+  // twice for the same href since scheduleNext walks the items array
+  // literally and `seen` is populated up-front, not within the chain.
+  return Array.from(new Set(out));
+}

package/vendored/lib/static-artifacts.ts

@@ -170,7 +170,8 @@ Disallow: /
   return `User-agent: *
 Allow: /
 
-Disallow: /_next/
+Allow: /_next/static/
+Allow: /_next/image
 
 Sitemap: ${sitemapUrl || defaultSitemapUrl}
 `;