jamdesk 1.1.206 → 1.1.207

package/vendored/lib/languages-artifact.ts

@@ -0,0 +1,160 @@
+/**
+ * The `_languages.json` descriptor shape, plus the pure builder for it — kept
+ * free of `./redis` and `./r2`.
+ *
+ * Two very different callers need it. `lib/language-matcher.ts` reads the file
+ * at the edge and therefore imports `./redis` (Upstash) and `./r2`. `build.ts`
+ * runs on Cloud Run and only ever *builds* the descriptor — a pure transform
+ * that must not pull an edge Redis client into the build image. Keeping the
+ * type and the builder here is what keeps those two apart: this module imports
+ * the `DocsConfig` type (erased at compile time) plus two import-light pure
+ * helpers — `./locale-helpers` and `./root-page-slug`, whose own chain
+ * (find-first-nav-page, language-utils, page-isr-helpers, shared/docs-subpath)
+ * is plain data and string work with no React, Next or network in it. The edge
+ * side imports THIS module `import type`-only, so none of that reaches the
+ * middleware bundle.
+ *
+ * `languages` and `defaultLanguage` are lowercased at build time by
+ * normalizeLanguageList(), so comparisons at the edge need no normalization.
+ */
+import { normalizeLanguageList } from './locale-helpers';
+import { findFirstPage } from './root-page-slug';
+import type { DocsConfig } from './docs-types';
+
+export interface LanguagesFile {
+  version: number;
+  generatedAt?: string;
+  /** Mirrors docs.json `localization.autoRedirect`. */
+  autoRedirect: boolean;
+  defaultLanguage: string;
+  languages: string[];
+}
+
+/**
+ * The descriptor that means "this project does not language-route", written
+ * whenever fewer than two languages are routable.
+ *
+ * Byte-identical in shape to language-matcher's EMPTY sentinel, deliberately:
+ * both `getLanguageRouting` return sites gate on `languages.length > 0` and
+ * hand the caller `null`, so this file reads at the edge exactly like no file
+ * at all.
+ *
+ * `autoRedirect` is hardcoded false rather than mirrored from docs.json. It is
+ * not a report of the tenant's setting here — it is this descriptor's own
+ * meaning, and `{autoRedirect: true, languages: []}` would be a file that
+ * contradicts itself for anyone reading it out of R2 during an incident.
+ */
+function noRoutingDescriptor(): LanguagesFile {
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    autoRedirect: false,
+    defaultLanguage: '',
+    languages: [],
+  };
+}
+
+/** docs.json nav paths and on-disk page paths, reduced to one comparable form. */
+function normalizePagePath(value: string): string {
+  return value
+    .replace(/\\/g, '/')
+    .replace(/^\/+/, '')
+    .replace(/\.mdx?$/i, '')
+    .toLowerCase();
+}
+
+/**
+ * Build the `_languages.json` descriptor for a project. ALWAYS returns one.
+ *
+ * Never null, and that is the whole contract. R2ContentUploader exposes no
+ * delete (lib/r2.ts:279-294), so "the file is absent" is not a state a build
+ * can reach for a project that has ever written one — every state has to be
+ * expressed by WRITING the truth over the top. An earlier version returned
+ * null both for the opted-out switch (correctly reasoned about in a comment)
+ * and for "fewer than two languages" (not), which meant a tenant who pulled a
+ * bad translation the documented way — `hidden: true` on the second language —
+ * skipped the write entirely and left `{autoRedirect: true, languages:
+ * ['en','fr']}` in R2 forever, 307-ing French visitors into the language just
+ * hidden, or into an `/fr` the build no longer produces. Silently: the success
+ * log sat inside the same `if`, so a skipped write looked exactly like a
+ * project that never had the feature. Single-language projects now write a
+ * no-routing descriptor too — ~93 small objects, one per build, which is the
+ * price of the absent state not existing.
+ *
+ * Two filters decide what may be a redirect DESTINATION:
+ *
+ * 1. Eligibility, from docs.json. `hidden: true` is the documented way to
+ *    stage a translation that is not ready, and auto-redirecting a first-time
+ *    visitor into it is the maximum possible surfacing of a language its
+ *    author deliberately hid. `href` points at an external site with no local
+ *    `/<code>` tree here, so redirecting there is a 307 into a 404.
+ *
+ * 2. Routability, from what this build actually PRODUCED. Config alone never
+ *    proves a destination exists: `{"language": "de"}` added before anything
+ *    is translated used to cost a broken entry in the language switcher — one
+ *    click — and would now 307 every German-preferring visitor off the
+ *    homepage into a 404. A non-default language is routable only when the
+ *    page `/<code>` really renders is (a) inside that language's own tree and
+ *    (b) among this build's pages.
+ *
+ *    Both clauses are load-bearing. `findFirstPage` falls through to the WHOLE
+ *    nav for a language block with no pages of its own, so (b) alone would
+ *    happily route `/de` at an English page — English served under a German
+ *    URL with `jd-lang=de` pinned, which is worse than not redirecting. And
+ *    (a) alone would route a language whose tree exists but whose front door
+ *    was never translated. The boundary this draws is deliberate: the test is
+ *    the visitor's ENTRY POINT, not page count. One translated page is enough
+ *    if it is the one `/<code>` lands on; two hundred are not enough if it is
+ *    missing. Resolution goes through findFirstPage — the same module the HTML
+ *    renderer and the markdown export both use — so this check cannot drift
+ *    from what the URL actually serves; it is called with the lowercased code
+ *    because that is the segment decideLanguageRedirect emits.
+ *
+ * The default language is exempt from (2). It is never a redirect destination
+ * — decideLanguageRedirect returns null as soon as the negotiated language is
+ * the default — but it has to stay in `languages` for negotiation to see it
+ * and for `defaultLanguage` to remain a member of its own list.
+ *
+ * @param builtPagePaths page paths this build produced, e.g. pageInfos[].path.
+ *   Required, not defaulted: an empty list disables routing for every
+ *   non-default language, and that must be a caller's decision rather than
+ *   something a forgotten argument does quietly.
+ */
+export function buildLanguagesArtifact(
+  docsConfig: DocsConfig,
+  builtPagePaths: readonly string[],
+): LanguagesFile {
+  const nav = docsConfig.navigation as
+    | { languages?: Array<{ language: string; default?: boolean; hidden?: boolean; href?: string }> }
+    | undefined;
+
+  // Applied HERE and not inside normalizeLanguageList(). That helper has
+  // another caller — deriveChunkLocale, via embedding-chunker.ts and
+  // json-ld.ts — which answers "what locale does this file belong to" for
+  // translation chunking and localized JSON-LD. A hidden or href-only entry is
+  // still a real locale for that question; it is only ineligible as an
+  // autoRedirect destination. Filtering inside normalizeLanguageList would
+  // have silently changed which pages get translated or how chunks are
+  // locale-tagged — a much bigger blast radius than this feature.
+  const eligible = (nav?.languages ?? []).filter((l) => l.hidden !== true && !l.href);
+  const entries = normalizeLanguageList(eligible);
+
+  const built = new Set(builtPagePaths.map(normalizePagePath));
+  const routable = entries.filter((entry) => {
+    if (entry.isDefault) return true;
+    const landing = normalizePagePath(findFirstPage(docsConfig, entry.code));
+    return landing.startsWith(`${entry.code}/`) && built.has(landing);
+  });
+
+  if (routable.length < 2) return noRoutingDescriptor();
+
+  const defaultEntry = routable.find((e) => e.isDefault) ?? routable[0];
+
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    autoRedirect: docsConfig.localization?.autoRedirect === true,
+    defaultLanguage: defaultEntry.code,
+    languages: routable.map((e) => e.code),
+  };
+}

package/vendored/lib/layout-helpers.tsx

@@ -24,6 +24,7 @@ import {
 import type { BackgroundConfig, DocsConfig, FontConfig, LanguageCode } from '@/lib/docs-types';
 import { LinkPrefixProvider } from '@/lib/link-prefix-context';
 import { ProjectSlugProvider } from '@/lib/project-slug-context';
+import { ThemePreviewProvider, type ThemePreviewValue } from '@/lib/theme-preview-context';
 import { getAnalyticsScript } from '@/lib/analytics-script';
 import { isConsentGatingEnabled, buildGatedScripts, getCmpScriptSrcs } from '@/lib/consent-gating';
 import { ConsentGate } from '@/components/ConsentGate';
@@ -410,6 +411,7 @@ interface DocsChromeProps {
   children: React.ReactNode;
   embed?: boolean;
   embedTheme?: 'light' | 'dark' | 'auto';
+  themePreview?: ThemePreviewValue;
 }
 
 /**
@@ -430,6 +432,7 @@ export async function DocsChrome({
   children,
   embed,
   embedTheme,
+  themePreview,
 }: DocsChromeProps): Promise<React.ReactElement> {
   // Lowercase to match docs-config canonical case — `data-theme="nebula"` CSS
   // selectors are case-sensitive, so `theme: "NEBULA"` from disk would silently
@@ -781,9 +784,19 @@ export async function DocsChrome({
         >
           <LinkPrefixProvider prefix={linkPrefix}>
             <ProjectSlugProvider slug={resolvedProjectSlug || ''}>
-              <LayoutWrapper config={config} embed={embed}>
-                {children}
-              </LayoutWrapper>
+              <ThemePreviewProvider
+                value={
+                  themePreview ?? {
+                    enabled: false,
+                    activeTheme: themeName ?? 'jam',
+                    defaultTheme: themeName ?? 'jam',
+                  }
+                }
+              >
+                <LayoutWrapper config={config} embed={embed}>
+                  {children}
+                </LayoutWrapper>
+              </ThemePreviewProvider>
             </ProjectSlugProvider>
           </LinkPrefixProvider>
           <CodeBlockCopyButton />

package/vendored/lib/middleware-helpers.ts

@@ -19,7 +19,7 @@ import { getDomainConfig, getDomainMapping, getDomainStatus, getProjectInactive
 import { getForwardedHosts, isJamdeskDomain, normalizeForwardedHost, parseRedisConfig } from './domain-helpers';
 import { getRedirects, matchRedirect, mergeQueryStrings, isInvalidDestination } from './redirect-matcher';
 import { ASSET_PREFIX } from './docs-types';
-import { extractLanguageFromPath } from './language-utils';
+import { extractLanguageFromPath, negotiateLanguage } from './language-utils';
 import { DEFAULT_DOCS_SUBPATH } from '../shared/docs-subpath';
 import { NextResponse } from 'next/server';
 import type { NextRequest } from 'next/server';
@@ -1315,3 +1315,230 @@ export async function customDomainOnlyBlock(args: {
     },
   });
 }
+
+/**
+ * Is this the bare documentation root — the one path where auto-routing to the
+ * visitor's language is safe?
+ *
+ * Exactly two shapes qualify: the site root `/`, and the hostAtDocs `/docs`
+ * root (with or without a trailing slash). Nothing else. In particular an
+ * explicit `/<lang>` root does **not** qualify, and that is the whole point:
+ *
+ *   - `/fr` is a URL a human chose, pasted into a ticket, or reached from a
+ *     search result. Redirecting away from it means a shared French link opens
+ *     in English for any colleague whose browser does not ask for French —
+ *     including a French speaker running an English OS. The URL is a stronger
+ *     statement of intent than Accept-Language, so the URL wins.
+ *   - Bots are exempt from redirects, so a crawler indexes `/fr` happily while
+ *     every human who clicks the result gets bounced. That asymmetry is
+ *     invisible in testing and shows up as a ranking problem months later.
+ *   - It keeps this a pure string test with no language list, so proxy.ts can
+ *     reject every content path before paying for the Redis/R2 read. An earlier
+ *     draft admitted any bare `/<segment>`, which made `/quickstart` — an
+ *     ordinary page — pay that read on every request.
+ *
+ * At the call site `pathname` is INTERNAL (reassigned to `routing.rewrite` in
+ * proxy.ts's getDocsPrefixRouting block), so a subpath-hosted tenant's root
+ * arrives as `/docs`, not `/`.
+ * Both shapes are handled here; dropping the `/docs` case silently disables the
+ * feature for every subpath-mounted site.
+ */
+export function isLocaleRootPath(pathname: string): boolean {
+  // The type says string, and the only call site (proxy.ts's `if (routing?.rewrite)`
+  // guard, plus the always-string `request.nextUrl.pathname` fallback) guarantees
+  // one — so this branch is unreachable today. It stays because edge middleware has
+  // no error boundary: a throw here 500s every docs page, while returning false just
+  // declines to redirect, the same fail-safe direction as every other path in this
+  // feature. One line of insurance against a future caller that isn't as careful.
+  if (typeof pathname !== 'string') return false;
+  const trimmed = pathname.endsWith('/') && pathname.length > 1
+    ? pathname.slice(0, -1)
+    : pathname;
+  return trimmed === '' || trimmed === '/' || trimmed === '/docs';
+}
+
+/**
+ * Case-insensitive substring match list for `isBotUserAgent`.
+ *
+ * NOT in the brief's own snippet — Step 3 there calls `BOT_UA_PATTERNS` without
+ * ever defining it, and no such constant exists anywhere else in this repo
+ * (verified by grep across build-service, cli, and dashboard/hosting). That
+ * omission would not typecheck, so this list was authored here to make the
+ * brief's own required test cases pass: the named crawlers/bots plus `curl`
+ * from the test table, and `spider`/`crawler`/generic `bot` so a UA this list
+ * doesn't yet name by product still fails safe (see the doc comment on
+ * `isBotUserAgent` for why "fails safe" here means "gets flagged as a bot").
+ * `facebookexternalhit` and `curl` are listed explicitly because neither
+ * contains the substring "bot".
+ *
+ * Three more explicit entries beyond the brief's test table, none of them a
+ * crash or a security issue — a missed bot just gets the same 307 a human
+ * would. These are crawl-hygiene and measurement-accuracy fixes, cheap enough
+ * to add on sight:
+ *   - `google-inspectiontool`: Search Console's URL inspection tool. Missed,
+ *     it sees a 307 to a translated locale instead of the canonical page —
+ *     actively misleading to someone debugging indexing on a docs product.
+ *   - `google-extended`: Google's AI-training crawler. Missed, it ingests a
+ *     translated variant instead of canonical.
+ *   - `chrome-lighthouse`: this repo's own CLAUDE.md requires a Lighthouse
+ *     mobile audit before builder-ISR and marketing deploys. Missed, an
+ *     audit measures a redirect hop instead of the target page and quietly
+ *     distorts our own pre-deploy gate. (Modern headless Chrome often drops
+ *     this token, which is exactly why it's low-risk to list: harmless when
+ *     absent, useful when present.)
+ */
+const BOT_UA_PATTERNS = [
+  'bot',
+  'spider',
+  'crawler',
+  'facebookexternalhit',
+  'curl',
+  'wget',
+  'google-inspectiontool',
+  'google-extended',
+  'chrome-lighthouse',
+];
+
+/**
+ * Total predicate: every input, including `null`/`''`/garbage, returns a
+ * boolean. This runs in edge middleware, which has no error boundary — a
+ * throw here 500s the page (see constraints.md).
+ *
+ * A missing or empty User-Agent is treated as a bot. No real browser omits
+ * the header, so the only visitors this can misclassify are non-browser
+ * clients — and for R1.4 the safe failure mode is "do not auto-redirect",
+ * not "guess a language for an unidentified client."
+ */
+export function isBotUserAgent(ua: string | null): boolean {
+  if (!ua) return true;
+  const lowered = ua.toLowerCase();
+  return BOT_UA_PATTERNS.some((pattern) => lowered.includes(pattern));
+}
+
+export interface LanguageRedirectInput {
+  /** Request pathname, already normalized past any hostAtDocs 308. */
+  pathname: string;
+  /** Descriptor from getLanguageRouting(), or null when absent. */
+  routing: { autoRedirect: boolean; defaultLanguage: string; languages: string[] } | null;
+  acceptLanguage: string | null;
+  userAgent: string | null;
+  cookieLanguage: string | null;
+}
+
+/**
+ * Spellings of `JD_LANG_ROUTING_DISABLED` that mean "every tenant". `*` is the
+ * documented one; the rest are here because an operator reaching for this at
+ * 2am should not have to remember a magic string, and no project slug can
+ * collide with any of them.
+ */
+const LANGUAGE_ROUTING_KILL_ALL = new Set(['*', 'all', 'true', '1', 'yes', 'on']);
+
+/** Spellings that mean "nothing disabled", so `...=false` is not a slug. */
+const LANGUAGE_ROUTING_KILL_NONE = new Set(['0', 'false', 'no', 'off']);
+
+/**
+ * The language-routing kill switch: is auto-redirect turned off for this
+ * project by platform configuration?
+ *
+ * Why this exists. `autoRedirect` is baked into `_languages.json` at BUILD
+ * time, so flipping docs.json does nothing until that tenant rebuilds — and
+ * the root CLAUDE.md forbids us triggering a customer rebuild without that
+ * customer's explicit permission for that exact rebuild. Poisoning the Redis
+ * key is not a rollback either: CACHE_TTL is 300s and R2 re-wins in five
+ * minutes. Without this, the only lever for one misbehaving tenant was
+ * rolling back the whole build-service deployment for all ~93.
+ *
+ * Format of the env var, read by proxy.ts:
+ *   unset / empty / `false`  -> nothing disabled (the default; an unset var
+ *                               must change nothing)
+ *   `*`                      -> disabled for every tenant
+ *   `acme,beta-docs`         -> disabled for those project slugs only
+ *
+ * TOTAL and non-throwing by construction — String.split and Set.has cannot
+ * raise, and a non-string argument returns false. That is not a style
+ * preference: proxy.ts has no error boundary, so a throw on this line 500s
+ * every docs page on every tenant. A value nobody can parse disables NOTHING
+ * rather than everything, so a typo cannot take the feature out platform-wide.
+ *
+ * Trimmed and lowercased per entry — Vercel env values pick up trailing
+ * newlines (see the ISR_MODE incident in CLAUDE.md) and slugs are lowercase.
+ */
+export function isLanguageRoutingDisabled(
+  projectSlug: string | null | undefined,
+  rawDenylist: string | null | undefined,
+): boolean {
+  if (typeof rawDenylist !== 'string') return false;
+  const entries = rawDenylist
+    .split(',')
+    .map((entry) => entry.trim().toLowerCase())
+    .filter((entry) => entry.length > 0 && !LANGUAGE_ROUTING_KILL_NONE.has(entry));
+  if (entries.length === 0) return false;
+  if (entries.some((entry) => LANGUAGE_ROUTING_KILL_ALL.has(entry))) return true;
+  const slug = typeof projectSlug === 'string' ? projectSlug.trim().toLowerCase() : '';
+  return slug.length > 0 && entries.includes(slug);
+}
+
+/**
+ * Decide where a language redirect should go, or null for "serve the page
+ * as-is".
+ *
+ * Returns the **internal** (`/docs`-shaped) pathname plus the language that
+ * was chosen. The caller needs both: the pathname must be mapped back to the
+ * tenant's external prefix with toExternalPath(), and the language is the
+ * cookie value — deriving it from the last path segment would write an empty
+ * cookie whenever the destination is the default-language root `/`.
+ *
+ * `viaCookie` tells the caller WHY: true only when an existing cookie named
+ * an offered language, false when the decision came from Accept-Language (or
+ * a cookie was present but named a language the tenant no longer offers — a
+ * stale cookie falls through to negotiation and must not be reported as the
+ * reason). A caller logging "via" from `Boolean(cookieLanguage)` instead
+ * would misattribute every stale-cookie redirect to the cookie.
+ *
+ * Pure and total: every bail-out returns null, so the caller can wire this in
+ * without an error path. Precedence is cookie, then Accept-Language — an
+ * explicit choice always beats a browser default (R1.3).
+ */
+export function decideLanguageRedirect(
+  input: LanguageRedirectInput,
+): { pathname: string; language: string; viaCookie: boolean } | null {
+  const { pathname, routing, acceptLanguage, userAgent, cookieLanguage } = input;
+
+  if (!routing?.autoRedirect) return null;
+  if (isBotUserAgent(userAgent)) return null;
+  // Bare docs root only. An explicit /<lang> root is the visitor's own stated
+  // language and is never redirected away from — see isLocaleRootPath.
+  if (!isLocaleRootPath(pathname)) return null;
+  if (routing.languages.length < 2) return null;
+
+  const available = routing.languages;
+  const defaultLang = routing.defaultLanguage.toLowerCase();
+
+  // A cookie naming a language the tenant has since dropped is stale, not a
+  // preference — fall through to negotiation rather than 404 the visitor.
+  const cookieMatch = cookieLanguage
+    ? available.find((code) => code.toLowerCase() === cookieLanguage.toLowerCase())
+    : undefined;
+
+  // "No cookie match" and "nothing configured matched" are DIFFERENT answers
+  // and must not collapse. negotiateLanguage returning null means R1.6's "do
+  // nothing" — not "fall back to the default". An earlier draft wrote
+  // `?? defaultLang` here, which turned every unmatched visitor into a
+  // redirect to the default root.
+  // negotiateLanguage already returns `string | null` (never undefined), so
+  // wrapping it in another `?? null` added nothing — the single trailing one
+  // normalizes the `undefined` that `?.toLowerCase()` produces when it's null.
+  const negotiated = cookieMatch
+    ? cookieMatch.toLowerCase()
+    : negotiateLanguage(acceptLanguage, available, defaultLang)?.toLowerCase() ?? null;
+  if (!negotiated) return null;
+
+  // Already where they belong: the bare root IS the default-language root.
+  if (negotiated === defaultLang) return null;
+
+  const trimmed = pathname.endsWith('/') && pathname.length > 1
+    ? pathname.slice(0, -1)
+    : pathname;
+  const base = trimmed === '/docs' ? '/docs' : '';
+  return { pathname: `${base}/${negotiated}`, language: negotiated, viaCookie: !!cookieMatch };
+}

package/vendored/lib/page-timestamps.ts

@@ -142,3 +142,39 @@ export function injectLastUpdated(content: string, date: string): string {
 
   return `---\n${newInner}\n---\n${content.slice(match[0].length)}`;
 }
+
+/**
+ * Normalize a frontmatter date value to `YYYY-MM-DD`, or undefined.
+ *
+ * YAML hands back three shapes for what an author typed as a date:
+ * an unquoted `2026-09-01` becomes a **Date**, a quoted one stays a string,
+ * and a bare `2026` becomes a number. Only the first two can mean a date, and
+ * a Date must be formatted in UTC — rendering it raw produces a
+ * timezone-shifted `Date.toString()` inside `<time dateTime>`, the same bug
+ * injectLastUpdated() quotes its own output to avoid.
+ */
+function normalizeDateValue(value: unknown): string | undefined {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? undefined : value.toISOString().slice(0, 10);
+  }
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  const parsed = new Date(trimmed);
+  if (Number.isNaN(parsed.getTime())) return undefined;
+  return parsed.toISOString().slice(0, 10);
+}
+
+/**
+ * Resolve the date shown as "Last updated on …".
+ *
+ * `lastUpdatedDate` is author-owned and wins; `lastUpdated` is build-owned (the
+ * git commit date injected by injectLastUpdated) and is the fallback. An
+ * unusable author value falls through to the git date rather than blanking the
+ * line — a typo should not silently remove a freshness signal.
+ */
+export function resolveLastUpdated(
+  data: { lastUpdated?: unknown; lastUpdatedDate?: unknown },
+): string | undefined {
+  return normalizeDateValue(data.lastUpdatedDate) ?? normalizeDateValue(data.lastUpdated);
+}

package/vendored/lib/rehype-code-meta.ts

@@ -16,6 +16,8 @@ export interface CodeMeta {
   showLineNumbers?: boolean;
   /** Starting line number (default: 1) */
   startLine?: number;
+  /** Suppress the copy button on this block */
+  nocopy?: boolean;
   /** Remaining meta string (status codes, etc.) */
   meta?: string;
 }
@@ -79,6 +81,25 @@ function parseShowLineNumbers(meta: string): boolean {
   return /\bshowLineNumbers\b/.test(meta);
 }
 
+/**
+ * Parse the nocopy flag from a meta string.
+ * Word-bounded so `title="nocopyright.txt"` does not trigger it, and scanned
+ * with any quoted title stripped first so `title="My nocopy guide"` (the word
+ * appearing inside free-text title, not as the flag) does not trigger it either.
+ */
+function parseNocopy(meta: string): boolean {
+  return /\bnocopy\b/.test(meta.replace(/title=(["'])(?:(?!\1).)*\1/g, ''));
+}
+
+/**
+ * The `nocopy` flag token with its surrounding whitespace. Shared by cleanMeta
+ * (pre-Shiki) and rehypeRestoreDataTitle (post-Shiki) because they strip the
+ * same fence at two pipeline stages and the caption is only right if both
+ * agree. Safe to share as a /g literal: String#replace resets lastIndex before
+ * and after; only .test/.exec carry state between calls.
+ */
+const NOCOPY_TOKEN = /\s*\bnocopy\b\s*/g;
+
 /**
  * Parse startLine attribute from meta string
  * Supports: startLine=10 or startLine="10"
@@ -94,6 +115,12 @@ function parseStartLine(meta: string): number | undefined {
 
 /**
  * Remove parsed attributes from meta string
+ *
+ * Accepted tradeoff: an UNQUOTED fallback title that happens to contain the
+ * word "nocopy" (e.g. ```txt My nocopy guide```) has it stripped here same
+ * as the real flag, so the caption renders "My guide" and the block also
+ * loses its copy button. Only a quoted `title="..."` is exempted (see
+ * parseNocopy above). The escape hatch is quoting the title.
  */
 function cleanMeta(meta: string): string {
   return meta
@@ -101,6 +128,7 @@ function cleanMeta(meta: string): string {
     .replace(/\s*title=["'][^"']+["']\s*/g, ' ')
     .replace(/\s*\{[^}]+\}\s*/g, ' ')
     .replace(/\s*showLineNumbers\s*/g, ' ')
+    .replace(NOCOPY_TOKEN, ' ')
     .replace(/\s*startLine=["']?\d+["']?\s*/g, ' ')
     .trim();
 }
@@ -122,6 +150,7 @@ export function parseCodeMeta(meta: string): CodeMeta {
     highlightLines: parseHighlightLines(meta),
     showLineNumbers: parseShowLineNumbers(meta),
     startLine: parseStartLine(meta),
+    nocopy: parseNocopy(meta),
     // Only include meta if we didn't use it as the title
     meta: explicitTitle ? cleanedMeta || undefined : undefined,
   };
@@ -248,8 +277,9 @@ function isCodeFenceFeature(meta: string): boolean {
   if (/^showLineNumbers(\s|$)/.test(trimmed)) return true;
   // startLine=N
   if (/^startLine=/.test(trimmed)) return true;
-  // Multiple features combined (no actual title)
-  if (/^(showLineNumbers|\{[\d,\-\s]+\}|startLine=\d+)(\s+(showLineNumbers|\{[\d,\-\s]+\}|startLine=\d+))*$/.test(trimmed)) return true;
+  // Multiple features combined (no actual title) — also covers a lone
+  // `nocopy`, so a standalone `^nocopy(\s|$)` check above would be redundant.
+  if (/^(showLineNumbers|nocopy|\{[\d,\-\s]+\}|startLine=\d+)(\s+(showLineNumbers|nocopy|\{[\d,\-\s]+\}|startLine=\d+))*$/.test(trimmed)) return true;
   return false;
 }
 
@@ -260,13 +290,48 @@ export const rehypeRestoreDataTitle: Plugin<[], Root> = () => {
         const dataMeta = node.properties['data-meta'] as string | undefined;
         const dataLanguage = node.properties['data-language'] as string | undefined;
 
-        // Only convert data-meta to data-title if:
-        // 1. data-meta exists
-        // 2. It doesn't look like a status code (no colon)
-        // 3. It's not a language/tool label (which CodeGroup uses for tabs)
-        // 4. It's not just code fence features (showLineNumbers, {1,3-5}, startLine=N)
-        if (dataMeta && !dataMeta.includes(':') && !isLanguageLabel(dataMeta, dataLanguage) && !isCodeFenceFeature(dataMeta)) {
-          node.properties['data-title'] = dataMeta;
+        if (!dataMeta || dataMeta.includes(':')) return;
+
+        // An explicit `title="..."` always wins. Promote the PARSED value,
+        // never the raw `data-meta` string — using raw meta here shipped
+        // `title="/snippets/counter.tsx"` as the literal on-page caption
+        // instead of `/snippets/counter.tsx` (pre-existing since 7ed2dfe26).
+        const explicitTitle = parseTitle(dataMeta);
+        if (explicitTitle) {
+          node.properties['data-title'] = explicitTitle;
+          return;
+        }
+
+        // Strip nocopy BEFORE classifying, not after: `JavaScript nocopy`
+        // must still read as the "javascript" language label. Classifying
+        // the raw meta first would test "JavaScript nocopy" against
+        // isLanguageLabel/isCodeFenceFeature (neither matches the combined
+        // string), wrongly promoting it to a standalone title "JavaScript".
+        const cleaned = dataMeta.replace(NOCOPY_TOKEN, ' ').trim();
+        if (!cleaned) return;
+
+        if (isLanguageLabel(cleaned, dataLanguage)) {
+          // The author wrote a language/tool token as the fence meta
+          // (```bash npm). Deliberately NOT promoted to data-title — a
+          // standalone block must not caption itself "npm" — but inside a
+          // <CodeGroup> that token IS the tab label Mintlify documents, and
+          // it is the only thing distinguishing an npm tab from a yarn one.
+          // Dropping it made `npm`/`yarn` both fall through to the language,
+          // and lib/code-utils.ts maps bash -> "cURL": 75 groups in
+          // projects/ rendered two or three IDENTICAL tabs. Re-emitted here
+          // under its own name, so the only reader is CodeGroup's
+          // getTabLabel and no caption changes outside a group.
+          //
+          // Emitted post-Shiki on purpose: this plugin runs after
+          // rehypeShikiFromHighlighter, which replaces the <pre> wholesale,
+          // so a pre-Shiki attribute would be discarded (same reason
+          // data-nocopy is stamped from transformerLineFeatures().pre()).
+          node.properties['data-language-label'] = cleaned;
+          return;
+        }
+
+        if (!isCodeFenceFeature(cleaned)) {
+          node.properties['data-title'] = cleaned;
         }
       }
     });

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

@@ -22,6 +22,7 @@ import { PageColumns } from '@/components/layout/PageColumns';
 import { EmbedLinkInterceptor } from '@/components/layout/EmbedLinkInterceptor';
 import { PageNavigation } from '@/components/navigation/PageNavigation';
 import { LastUpdated } from '@/components/navigation/LastUpdated';
+import { resolveLastUpdated } from './page-timestamps';
 import { SocialFooter } from '@/components/navigation/SocialFooter';
 import { ApiPageWrapper } from '@/components/mdx/ApiPage';
 import { OpenApiEndpoint } from '@/components/mdx/OpenApiEndpoint';
@@ -191,6 +192,16 @@ interface FrontmatterData {
   // Injected at build time (YYYY-MM-DD) when metadata.timestamp is enabled —
   // the date of the last git commit that touched this page. See LastUpdated.
   lastUpdated?: string;
+  /**
+   * Author override; wins over the build-injected `lastUpdated`.
+   *
+   * Typed `string | Date` because that is what YAML actually yields: an
+   * unquoted `2026-09-01` parses to a Date, a quoted one stays a string.
+   * Declaring it `string` would compile but describe a shape the runtime
+   * never guarantees. `resolveLastUpdated` takes `unknown` and handles both,
+   * plus the number YAML produces for a bare `2026`.
+   */
+  lastUpdatedDate?: string | Date;
   [key: string]: unknown;
 }
 
@@ -695,7 +706,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
     faqPairs,
     isRootAlias,
     ogImageUrl,
-    dateModified: typeof data.lastUpdated === 'string' ? data.lastUpdated : undefined,
+    dateModified: resolveLastUpdated(data),
     author: typeof data.author === 'string' ? data.author : undefined,
   });
   const jsonLdScript = renderJsonLdScript(jsonLd);
@@ -1241,7 +1252,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
             </div>
 
             {!embed && <PageNavigation currentSlug={slug.join('/')} config={config} />}
-            {!embed && config.metadata?.timestamp && <LastUpdated date={data.lastUpdated} />}
+            {!embed && config.metadata?.timestamp && <LastUpdated date={resolveLastUpdated(data)} />}
             <SocialFooter config={config} hidden={data.hideFooter} embed={embed} projectSlug={projectSlug ?? undefined} />
           </article>,
         )}
@@ -1303,7 +1314,7 @@ export async function renderDocPage(input: RenderInput): Promise<ReactElement> {
 
         {!embed && <PageNavigation currentSlug={slug.join('/')} config={config} isWideMode={isWideMode || hasPanel} />}
       </div>
-      {!embed && config.metadata?.timestamp && <LastUpdated date={data.lastUpdated} />}
+      {!embed && config.metadata?.timestamp && <LastUpdated date={resolveLastUpdated(data)} />}
       <SocialFooter config={config} hidden={data.hideFooter} embed={embed} projectSlug={projectSlug ?? undefined} />
     </article>,
   );