jamdesk 1.1.185 → 1.1.187

package/vendored/components/theme/ThemeToggle.tsx

@@ -25,7 +25,9 @@ export function ThemeToggle() {
   const iconClass = 'text-[12px]';
   // Fixed-size icon slot shared by the pre-mount placeholder and the mounted
   // buttons. Without it the control changes width when the FontAwesome icon font
-  // swaps in (font-display: swap), reflowing the header nav horizontally (CLS).
+  // loads in, reflowing the header nav horizontally (CLS). The bundle now uses
+  // font-display: block, so the pre-load glyph is invisible rather than tofu —
+  // but the slot is still what pins the width, so it stays load-bearing.
   // overflow-hidden caps a wide fallback glyph.
   const iconSlot = 'inline-flex items-center justify-center w-4 h-4 overflow-hidden';
 

package/vendored/lib/email-templates/build-failure.tsx

@@ -104,6 +104,7 @@ function formatPhase(phase?: string): string {
     r2_upload: 'CDN Upload',
     embeddings: 'AI Search Indexing',
     vercel_purge: 'Cache Refresh',
+    translate: 'Queueing Translations',
     cleanup: 'Cleanup',
   };
   return phaseLabels[phase] || phase;

package/vendored/lib/isr-build-executor.ts

@@ -571,6 +571,10 @@ export const ISR_PHASES = {
   embeddings: { label: 'Indexing AI search + chat...', weight: 5 },
   vercel_purge: { label: 'Refreshing cache...', weight: 10 },
   cleanup: { label: 'Cleaning up...', weight: 5 },
+  // Terminal and non-fatal: enqueues background translation work. Weight 0 —
+  // it does no user-visible work, and the dashboard's progress bar must not
+  // stall on it.
+  translate: { label: 'Queueing translations...', weight: 0 },
 } as const;
 
 export type IsrPhase = keyof typeof ISR_PHASES;

package/vendored/lib/locale-fallback.ts

@@ -0,0 +1,98 @@
+/**
+ * English fallback for untranslated locale pages.
+ *
+ * The AI translation pipeline writes locale MDX (`es/quickstart.mdx`,
+ * `fr/guides/deploy.mdx`, …) into the customer's repo asynchronously, AFTER
+ * their English push has already built and published. Between those two
+ * moments — minutes normally, much longer on a first backfill — a locale URL
+ * already has a navigation entry (nav is emitted for every configured
+ * language, not just the finished pages) but no file behind it. Without this
+ * module every such URL 404s.
+ *
+ * Both Next entry points over a docs URL consume these helpers:
+ *   - `renderDocPage`   → serves the English body plus an inline notice
+ *   - `buildDocMetadata` → canonicalizes to the English page, `noindex, follow`
+ * They must agree; see the wiring in `lib/render-doc-page.tsx`.
+ */
+import { resolveLocaleFromPath } from './language-utils';
+
+export interface LocaleFallback {
+  /** The locale prefix, in the casing the project declared in docs.json. */
+  locale: string;
+  /** The same page without the locale prefix, e.g. `guides/deploy`. */
+  englishPath: string;
+}
+
+/**
+ * Split a declared locale prefix off a page path.
+ *
+ * `declaredLocales` is the project's **non-default** locales — the default
+ * language's pages live at the root, so its prefix is never a content path (see
+ * `fallbackLocales` in `render-doc-page.tsx`).
+ *
+ * Returns null — meaning "not a locale-prefixed page, leave the 404 alone" —
+ * for a bare page, a locale root with no page, a directory that merely looks
+ * like a language code (`ai/`, `id/`), and any locale not in that list.
+ *
+ * The canonical-code test is delegated to `resolveLocaleFromPath` (itself gated
+ * on the canonical `LANGUAGE_CODES` list) rather than reimplemented here,
+ * because `renderDocPage` calls that same helper to pick localized component
+ * chrome. Two independent notions of "declared locale prefix" would drift into
+ * chrome localizing on a page this fallback does not fire for, or the reverse —
+ * a bug class nobody would trace back to here.
+ *
+ * The locale is matched case-insensitively (`pt-br/a` resolves against a
+ * configured `pt-BR`) but returned in the DECLARED casing, so callers can key
+ * straight back into `navigation.languages`.
+ */
+export function parseLocalePath(
+  path: string,
+  declaredLocales: string[],
+): LocaleFallback | null {
+  const trimmed = String(path ?? '').replace(/^\/+/, '');
+
+  // Gate 1 (unchanged, delegated): is this a canonical language code the
+  // project declared? Keeps the yes/no answer aligned with the chrome resolver.
+  if (!resolveLocaleFromPath(`/${trimmed}`, declaredLocales)) return null;
+
+  // Gate 2 (authoritative): the segment we DROP must be the segment that
+  // MATCHED. `resolveLocaleFromPath` reaches `extractLanguageFromPath`, which
+  // strips a leading `/docs/` because it is written for URL pathnames — but
+  // this function is given a CONTENT path (a hostAtDocs tenant's `/docs` prefix
+  // is already gone, removed upstream by `normalizeSlugForContent`). Mirroring
+  // that strip would drop a real path component and serve `/quickstart`'s body
+  // at `/docs/es/quickstart`. So re-match the first segment here: that makes
+  // this function strictly narrower than the chrome resolver, never wider.
+  const segments = trimmed.split('/').filter(Boolean);
+  const first = segments[0]?.toLowerCase();
+  const declared = declaredLocales.find((l) => l.toLowerCase() === first);
+  if (!declared) return null;
+
+  const englishPath = segments.slice(1).join('/');
+  if (!englishPath) return null;
+
+  return { locale: declared, englishPath };
+}
+
+/**
+ * SEO for a locale URL that is currently serving the English body.
+ *
+ * `noindex` keeps the untranslated duplicate out of the index (it is the same
+ * text as the English page, under a second URL), while the canonical points at
+ * the English original. `follow`, not `nofollow`: the page's links are real, so
+ * link equity should still flow through it.
+ *
+ * @param englishPath - Page path without the locale prefix (`guides/deploy`).
+ * @param siteUrl - Base URL for the site, with or without a trailing slash.
+ */
+export function fallbackSeo(
+  englishPath: string,
+  siteUrl: string,
+): { canonical: string; robots: 'noindex, follow' } {
+  const base = siteUrl.replace(/\/+$/, '');
+  const clean = englishPath.replace(/^\/+|\/+$/g, '');
+  return {
+    canonical: clean ? `${base}/${clean}` : base,
+    robots: 'noindex, follow',
+  };
+}

package/vendored/lib/regenerate-screenshot-handler.ts

@@ -25,7 +25,9 @@ const SLUG_RE = /^[A-Za-z0-9_-]{1,128}$/;
  */
 export async function handleRegenerateScreenshot(req: Request, res: Response): Promise<void> {
   const buildSecret = req.headers['x-build-service-secret'] as string | undefined;
-  const expectedSecret = process.env.BUILD_SERVICE_SECRET;
+  // Trimmed: an untrimmed compare can only reject the legitimate caller, since
+  // header values carry no surrounding whitespace on the wire. See server.ts.
+  const expectedSecret = process.env.BUILD_SERVICE_SECRET?.trim();
   if (!expectedSecret) {
     console.log(JSON.stringify({severity: 'ERROR', message: 'BUILD_SERVICE_SECRET not configured - rejecting /regenerate-screenshot'}));
     res.status(500).json({error: 'Server misconfiguration'});

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

@@ -88,6 +88,7 @@ import {
 import { classifyOpenApiLoadError } from '@/lib/openapi/classify-load-error';
 import { findOperation, deriveOperationDescription, collectLocalSpecPaths } from '@/lib/openapi/operation-description';
 import { extractLanguageFromPath, isValidLanguageCode, resolveLocaleFromPath } from '@/lib/language-utils';
+import { parseLocalePath } from '@/lib/locale-fallback';
 import { DocsLocaleProvider } from '@/components/mdx/docs-locale-context';
 import { findFirstNavPage } from '@/lib/find-first-nav-page';
 import { candidateSpecPaths } from '@/lib/openapi/lang-spec-path';
@@ -212,6 +213,64 @@ function findFirstPage(config: DocsConfig, lang?: string): string {
   return result ? result.replace(/^\//, '') : 'introduction';
 }
 
+/**
+ * Every locale this project declared in docs.json — the whitelist the localized
+ * component chrome (`resolveLocaleFromPath`) gates on. Empty for a project with
+ * translations off.
+ */
+function declaredLocales(config: DocsConfig): string[] {
+  return config.navigation?.languages?.map((l) => l.language) ?? [];
+}
+
+/**
+ * The subset of those that actually live under a URL prefix — the whitelist the
+ * untranslated-page fallback gates on.
+ *
+ * The default language's pages are at the ROOT (`transformLanguagePath` drops
+ * the prefix when `toLang === defaultLang`), so `<default>/…` is never a real
+ * content path. Letting the fallback claim it would put "this page hasn't been
+ * translated yet" on the page that IS the default-language page — and on a
+ * project whose default is not English, serve that language's body under a
+ * "showing the English version" notice.
+ *
+ * The default is resolved the way the rest of the codebase does it
+ * (`buildHreflangAlternates`, `resolveLanguageWithFallback`): explicit
+ * `default: true`, else the first entry. Excluding a locale here can only ever
+ * mean "404 instead of English fallback" — the fallback is consulted solely
+ * when the requested file is already missing — so erring narrow is safe.
+ *
+ * Excluding the default's prefix closes only HALF the hazard the paragraph
+ * above names, because the fallback's DESTINATION is "strip the prefix and
+ * serve the root page" — and the root page is the DEFAULT language's page, not
+ * English. Those coincide on an English-default project and diverge on every
+ * other one, where `/en/quickstart` would 200 with the Spanish body under the
+ * hardcoded "Showing the English version" notice, canonical → the Spanish root.
+ * So the whole fallback is inert unless the default language IS English.
+ *
+ * Inert rather than reworded, for three reasons:
+ *  - This module is English-by-contract end to end (`LocaleFallback.englishPath`,
+ *    `fallbackSeo`'s doc, the notice copy, the `[translation-fallback] serving
+ *    English body` log line). Naming the actual language served means
+ *    generalising all of it — for a population the feature never reaches.
+ *  - `lib/translation/nav.ts` (`unwrapLanguagesNav`) THROWS on a non-English
+ *    default, so the AI pipeline that creates the untranslated window can never
+ *    produce this state. Same exact `!== 'en'` test, deliberately: the set where
+ *    the fallback is inert is exactly the set the pipeline refuses.
+ *  - It restores the pre-feature 404 on precisely the configurations where no
+ *    correct answer exists, and changes nothing for English-default projects.
+ *
+ * The `'en'` is a literal, not `SOURCE_LANGUAGE`: that constant lives under
+ * `lib/translation/`, which is server-only and excluded from CLI vendoring
+ * (`vendor.js` EXCLUDED_SUBTREES), and this file IS vendored.
+ */
+function fallbackLocales(config: DocsConfig): string[] {
+  const languages = config.navigation?.languages;
+  if (!languages || languages.length === 0) return [];
+  const defaultLang = languages.find((l) => l.default)?.language ?? languages[0].language;
+  if (defaultLang !== 'en') return [];
+  return languages.filter((l) => l.language !== defaultLang).map((l) => l.language);
+}
+
 function needsSlugRewrite(slug: string[]): boolean {
   return slug.length === 0 || (slug.length === 1 && isValidLanguageCode(slug[0]));
 }
@@ -296,12 +355,34 @@ export async function buildDocMetadata(input: RenderInput): Promise<Metadata> {
     : normalizedSlug;
   const pagePath = slug.join('/');
 
-  const [fileContents, config] = await Promise.all([
+  const [pageContents, config] = await Promise.all([
     loader.getContent(pagePath).catch(() => null),
     configP,
   ]);
 
+  // Untranslated locale page → serve the English page's metadata for it (see
+  // lib/locale-fallback). This block MUST stay in lockstep with the identical
+  // one in renderDocPage: they are two Next entry points over ONE URL, and a
+  // fallback known to only one of them either serves the English body under an
+  // indexable locale canonical (the duplicate-content problem the noindex
+  // exists to prevent, on every untranslated page) or claims `noindex, follow`
+  // on a page that 404s.
+  //
+  // The two halves read R2 independently, so a translation landing between them
+  // is served with the metadata of the state its own read saw — self-healing on
+  // the next request, and inherent to two reads. Note this changed the severity
+  // of a transient R2 miss on a translated page: it used to cost a `<title>`,
+  // it now costs a `noindex` for one request.
+  const localeFallback = pageContents
+    ? null
+    : parseLocalePath(pagePath, fallbackLocales(config));
+  const fileContents = pageContents ?? (localeFallback
+    ? await loader.getContent(localeFallback.englishPath).catch(() => null)
+    : null);
+
   if (!fileContents) {
+    // Includes the case where the locale prefix matched but the English page
+    // is missing too — nothing to fall back to.
     return { title: 'Not Found' };
   }
 
@@ -352,7 +433,10 @@ export async function buildDocMetadata(input: RenderInput): Promise<Metadata> {
   const baseUrl = resolveBaseUrl(requestHeaders, projectSlug, hostAtDocs);
   const languages = config.navigation?.languages;
 
-  const seoMetadata = buildSeoMetadata(config, data, pagePath, baseUrl, languages, isRootAlias, linkPrefix);
+  const seoMetadata = buildSeoMetadata(
+    config, data, pagePath, baseUrl, languages, isRootAlias, linkPrefix,
+    localeFallback?.englishPath,
+  );
 
   const titleValue = data.title
     ? (data.title === config.name ? { absolute: data.title } : data.title)
@@ -419,15 +503,33 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
     : normalizedSlug;
   const pagePath = slug.join('/');
   const currentLang = extractLanguageFromPath(`/${pagePath}`);
-  const [fileContents, config, highlighter] = await Promise.all([
+  const [pageContents, config, highlighter] = await Promise.all([
     loader.getContent(pagePath).catch(() => null),
     configP,
     highlighterP,
   ]);
 
+  // Untranslated locale page → serve the English body with a notice instead of
+  // 404ing. Mirror of the block in buildDocMetadata — see the comment there for
+  // why both entry points must reach the same verdict on the same URL.
+  const localeFallback = pageContents
+    ? null
+    : parseLocalePath(pagePath, fallbackLocales(config));
+  const fileContents = pageContents ?? (localeFallback
+    ? await loader.getContent(localeFallback.englishPath).catch(() => null)
+    : null);
+
   if (!fileContents) {
+    // Includes the case where the locale prefix matched but the English page
+    // is missing too — nothing to fall back to.
     notFound();
   }
+  if (localeFallback) {
+    logger.info('[translation-fallback] serving English body for untranslated locale page', {
+      locale: localeFallback.locale,
+      pagePath,
+    });
+  }
 
   const parsed = parseFrontmatter(fileContents);
   const data = parsed.data as FrontmatterData;
@@ -436,10 +538,16 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
   // Whitelisted page locale for localized component chrome (Prompt action
   // labels). Unlike `currentLang` above, this only counts a path prefix that
   // is actually declared in navigation.languages — '' otherwise.
-  const docsLocale = resolveLocaleFromPath(
-    `/${pagePath}`,
-    config.navigation?.languages?.map((l) => l.language) ?? [],
-  );
+  const docsLocale = resolveLocaleFromPath(`/${pagePath}`, declaredLocales(config));
+
+  // Plain server-rendered element — no client component, no dependency. On the
+  // fallback the chrome above stays localized (docsLocale is the same declared
+  // prefix parseLocalePath matched); only the body is English.
+  const translationNotice = localeFallback ? (
+    <div role="status" className="jd-translation-pending">
+      This page hasn’t been translated yet. Showing the English version.
+    </div>
+  ) : null;
 
   const baseUrl = resolveBaseUrl(requestHeaders, projectSlug, hostAtDocs);
   const faqPairs = extractFaqPairs(rawContent);
@@ -810,6 +918,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
         {wrap(
           <article className="px-4 sm:px-6 lg:px-8 py-6 sm:py-10 flex-1 min-w-0">
             <Breadcrumb slug={slug} config={config} hidden={embed} />
+            {translationNotice}
 
             {data.title && (
               <header className="mb-4 sm:mb-6">
@@ -929,6 +1038,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
   const articleContent = wrap(
     <article className="px-4 sm:px-6 lg:px-8 py-6 sm:py-10">
       <Breadcrumb slug={slug} config={config} hidden={embed} />
+      {translationNotice}
 
       {data.title && (
         <header className="mb-6 sm:mb-10">

package/vendored/lib/seo.ts

@@ -12,6 +12,7 @@ import type { Metadata } from 'next';
 import type { DocsConfig, Logo, LogoConfig, Favicon, LanguageConfig, LanguageCode } from './docs-types';
 import { normalizeLogo } from './docs-types';
 import { findHreflangAliasCollisions, transformLanguagePath, toHreflang, resolveLocaleFromPath } from './language-utils';
+import { fallbackSeo } from './locale-fallback';
 import { logger } from '../shared/logger';
 
 // Dedupe per-process: same docs.json shape produces the same collision
@@ -674,6 +675,16 @@ function derivePageLocale(pagePath: string, languages?: LanguageConfig[]): strin
  *   `/_jd/og` vs direct `/api/og`) and to strip the prefix off baseUrl for
  *   metadataBase/rootUrl. Falls back to the legacy `baseUrl.endsWith('/docs')`
  *   sniff when omitted, so callers that predate this param are unaffected.
+ * @param englishFallbackPath - Set ONLY when this URL is an untranslated locale
+ *   variant serving the English page's body (`parseLocalePath` matched and the
+ *   locale MDX is not in R2 yet — see lib/locale-fallback). Its value is the
+ *   English page path. The variant then canonicalizes to the English page,
+ *   emits `noindex, follow`, and drops hreflang: advertising an alternate for a
+ *   URL that is serving English is the same "translation that isn't there"
+ *   defect buildHreflangAlternates exists to prevent, and pairing hreflang with
+ *   a cross-URL canonical is the Semrush "Conflicting hreflang and
+ *   rel=canonical" finding. The canonical target emits the full cluster, so
+ *   language discovery is preserved — same reasoning as isRootAlias.
  * @returns Partial<Metadata> to spread into generateMetadata return
  */
 
@@ -696,12 +707,19 @@ export function buildSeoMetadata(
   languages?: LanguageConfig[],
   isRootAlias = false,
   docsPrefix?: string,
+  englishFallbackPath?: string,
 ): Partial<Metadata> {
   const globalMeta = config.seo?.metatags || {};
   const pageMeta = normalizePageMetatags(frontmatter as Record<string, unknown>);
   // Merge: page (flat-wins, already resolved inside normalizePageMetatags) over global
   const metatags: Record<string, string> = { ...globalMeta, ...pageMeta };
   const metadata: Partial<Metadata> = {};
+  // Non-null only for the untranslated-locale variant — see englishFallbackPath.
+  // An empty string is treated as "no fallback": it is unreachable today
+  // (parseLocalePath returns null on an empty englishPath) but would otherwise
+  // canonicalize the page to the bare site root and noindex it.
+  const fallbackPath = englishFallbackPath || null;
+  const fallback = fallbackPath ? fallbackSeo(fallbackPath, baseUrl) : null;
 
   // 1. Generator - always add
   metadata.generator = 'Jamdesk';
@@ -716,7 +734,11 @@ export function buildSeoMetadata(
   const hiddenImpliesNoindex = frontmatter.hidden === true && !projectIndexesHidden;
   const effectiveNoindex = explicitPageNoindex ?? (hiddenImpliesNoindex ? true : undefined);
 
-  if (effectiveNoindex === true) {
+  if (fallback) {
+    // The untranslated variant duplicates the English body under a second URL,
+    // so it stays out of the index no matter what the page or project declares.
+    metadata.robots = fallback.robots;
+  } else if (effectiveNoindex === true) {
     // noindex does NOT imply nofollow - use follow: true
     metadata.robots = { index: false, follow: true };
   } else if (effectiveNoindex !== false && metatags.robots) {
@@ -755,6 +777,12 @@ export function buildSeoMetadata(
   // 7. Canonical
   const cleanPath = pagePath.replace(/^\/+|\/+$/g, '');
   const pageUrl = cleanPath ? `${baseUrl}/${cleanPath}` : baseUrl;
+  // Every canonical form below is computed from the ENGLISH path on the
+  // fallback variant — the served body is the English page's, so claiming the
+  // locale URL as canonical is exactly the duplicate-content problem to avoid.
+  const canonicalPath = fallbackPath
+    ? fallbackPath.replace(/^\/+|\/+$/g, '')
+    : cleanPath;
   let canonical: string;
   if (pageMeta.canonical) {
     // Per-page canonical: use exactly as authored.
@@ -763,14 +791,17 @@ export function buildSeoMetadata(
     // Global canonical is a BASE — append the page path so every page does not
     // report the same URL (which would de-index the whole site). Matches Mintlify.
     const base = globalMeta.canonical.replace(/\/+$/, '');
-    canonical = cleanPath ? `${base}/${cleanPath}` : base;
+    canonical = canonicalPath ? `${base}/${canonicalPath}` : base;
+  } else if (fallback) {
+    canonical = fallback.canonical;
   } else {
     canonical = pageUrl;
   }
 
   // 7b. Hreflang alternates for multi-language support. Suppressed on root-alias
-  // pages — see the isRootAlias param doc above for why.
-  const hreflangLanguages = isRootAlias
+  // pages and on the untranslated-locale fallback — see the isRootAlias and
+  // englishFallbackPath param docs above for why.
+  const hreflangLanguages = isRootAlias || fallback
     ? undefined
     : buildHreflangAlternates(baseUrl, pagePath, languages || []);
 
@@ -806,7 +837,11 @@ export function buildSeoMetadata(
       url: pageUrl,
       siteName: config.name,
       ogImageUrl,
-      locale: derivePageLocale(pagePath, languages),
+      // og:locale describes the language of the CONTENT, so on the fallback it
+      // must follow the English body, not the locale URL. (og:url deliberately
+      // still points at the locale URL — that is the page's real address, and
+      // it is not an indexing directive.)
+      locale: derivePageLocale(fallbackPath ?? pagePath, languages),
     });
   }