jamdesk 1.1.206 → 1.1.207

package/vendored/components/ui/CodePanelModal.tsx

@@ -11,9 +11,23 @@ interface CodePanelModalProps {
   tabs: CodePanelTab[];
   title?: string;
   initialTabIndex?: number;
+  /**
+   * Suppress the header copy button, Cmd/Ctrl+C shortcut, and its footer hint
+   * for every tab. A tab's own `hideCopy` overrides this while it is active —
+   * the modal tracks its own activeTab, so it resolves this itself rather than
+   * receiving the panel's already-resolved value.
+   */
+  hideCopy?: boolean;
 }
 
-export function CodePanelModal({ isOpen, onClose, tabs, title, initialTabIndex = 0 }: CodePanelModalProps) {
+export function CodePanelModal({
+  isOpen,
+  onClose,
+  tabs,
+  title,
+  initialTabIndex = 0,
+  hideCopy = false,
+}: CodePanelModalProps) {
   const [activeTab, setActiveTab] = useState(initialTabIndex);
   const [copied, setCopied] = useState(false);
   const [isClosing, setIsClosing] = useState(false);
@@ -22,6 +36,9 @@ export function CodePanelModal({ isOpen, onClose, tabs, title, initialTabIndex =
   const contentRef = useRef<HTMLDivElement>(null);
 
   const currentTab = tabs[activeTab];
+  // Must agree with CodePanel's own resolution, or expanding a nocopy tab to
+  // fullscreen would hand back the copy button the panel just suppressed.
+  const copyHidden = currentTab?.hideCopy ?? hideCopy;
 
   // Handle close with animation
   const handleClose = useCallback(() => {
@@ -87,7 +104,7 @@ export function CodePanelModal({ isOpen, onClose, tabs, title, initialTabIndex =
       }
 
       // Cmd/Ctrl+C to copy (when not selecting text)
-      if ((e.metaKey || e.ctrlKey) && e.key === 'c' && !window.getSelection()?.toString()) {
+      if (!copyHidden && (e.metaKey || e.ctrlKey) && e.key === 'c' && !window.getSelection()?.toString()) {
         e.preventDefault();
         handleCopy();
         return;
@@ -113,7 +130,7 @@ export function CodePanelModal({ isOpen, onClose, tabs, title, initialTabIndex =
 
     document.addEventListener('keydown', handleKeyDown);
     return () => document.removeEventListener('keydown', handleKeyDown);
-  }, [isOpen, handleClose, handleCopy]);
+  }, [isOpen, handleClose, handleCopy, copyHidden]);
 
   if (!isOpen) return null;
 
@@ -224,27 +241,29 @@ export function CodePanelModal({ isOpen, onClose, tabs, title, initialTabIndex =
             {/* Right: Actions */}
             <div className="flex items-center gap-2">
               {/* Copy Button */}
-              <button
-                onClick={handleCopy}
-                className="p-2 rounded-md transition-colors cursor-pointer"
-                style={{ color: codePanelColors.textMuted }}
-                onMouseEnter={(e) => {
-                  e.currentTarget.style.backgroundColor = codePanelColors.tabHoverBg;
-                  e.currentTarget.style.color = codePanelColors.text;
-                }}
-                onMouseLeave={(e) => {
-                  e.currentTarget.style.backgroundColor = 'transparent';
-                  e.currentTarget.style.color = codePanelColors.textMuted;
-                }}
-                title="Copy code"
-                aria-label="Copy code to clipboard"
-              >
-                {copied ? (
-                  <i className="fa-solid fa-check text-emerald-500" aria-hidden="true" />
-                ) : (
-                  <i className="fa-regular fa-copy" aria-hidden="true" />
-                )}
-              </button>
+              {!copyHidden && (
+                <button
+                  onClick={handleCopy}
+                  className="p-2 rounded-md transition-colors cursor-pointer"
+                  style={{ color: codePanelColors.textMuted }}
+                  onMouseEnter={(e) => {
+                    e.currentTarget.style.backgroundColor = codePanelColors.tabHoverBg;
+                    e.currentTarget.style.color = codePanelColors.text;
+                  }}
+                  onMouseLeave={(e) => {
+                    e.currentTarget.style.backgroundColor = 'transparent';
+                    e.currentTarget.style.color = codePanelColors.textMuted;
+                  }}
+                  title="Copy code"
+                  aria-label="Copy code to clipboard"
+                >
+                  {copied ? (
+                    <i className="fa-solid fa-check text-emerald-500" aria-hidden="true" />
+                  ) : (
+                    <i className="fa-regular fa-copy" aria-hidden="true" />
+                  )}
+                </button>
+              )}
 
               {/* Close Button */}
               <button
@@ -304,18 +323,20 @@ export function CodePanelModal({ isOpen, onClose, tabs, title, initialTabIndex =
                 </kbd>
                 <span>Close</span>
               </span>
-              <span className="flex items-center gap-1.5">
-                <kbd
-                  className="px-1.5 py-0.5 rounded text-[10px] font-mono"
-                  style={{
-                    backgroundColor: codePanelColors.tabHoverBg,
-                    border: `0.5px solid ${codePanelColors.border}`,
-                  }}
-                >
-                  {typeof navigator !== 'undefined' && navigator.platform?.includes('Mac') ? '\u2318' : 'Ctrl'}+C
-                </kbd>
-                <span>Copy</span>
-              </span>
+              {!copyHidden && (
+                <span className="flex items-center gap-1.5">
+                  <kbd
+                    className="px-1.5 py-0.5 rounded text-[10px] font-mono"
+                    style={{
+                      backgroundColor: codePanelColors.tabHoverBg,
+                      border: `0.5px solid ${codePanelColors.border}`,
+                    }}
+                  >
+                    {typeof navigator !== 'undefined' && navigator.platform?.includes('Mac') ? '\u2318' : 'Ctrl'}+C
+                  </kbd>
+                  <span>Copy</span>
+                </span>
+              )}
             </div>
             {currentTab?.language && (
               <span className="uppercase tracking-wide">{currentTab.language}</span>

package/vendored/hooks/useWheelScrollChaining.ts

@@ -0,0 +1,181 @@
+'use client';
+
+import { useEffect } from 'react';
+
+/**
+ * Restores native scroll chaining for the desktop three-column layout.
+ *
+ * At >=1024px the layout shell is `lg:h-screen lg:overflow-hidden`
+ * (LayoutWrapper), so the document never scrolls — `#content-scroll-container`
+ * does. That makes every sibling column a scroll dead end: the browser looks
+ * for an ancestor to chain the wheel to, finds only `overflow: hidden`, and
+ * drops the event.
+ *
+ * The worst case is the TOC <aside>, which PageColumns renders unconditionally
+ * at xl+ while TableOfContents returns null when the page has no h2/h3. On a
+ * heading-less page that leaves ~288px (a quarter of a 1280px viewport) where
+ * the wheel does nothing at all. A TOC too short to overflow, a short sidebar
+ * nav, and the shell's own horizontal padding fail the same way.
+ *
+ * This walks up from the event target looking for any scroll container. If
+ * there is none, the delta is handed to the content column — which is what the
+ * browser would have done had the ancestors not been `overflow: hidden`.
+ *
+ * Scope is deliberately narrower than true scroll chaining: a column that CAN
+ * scroll but has hit its end keeps the wheel and stops, exactly as it does
+ * today. Widening that is a separate, visible behaviour change.
+ *
+ * Listener is passive: nothing else was going to scroll, so there is no
+ * default to prevent and no scroll-blocking cost.
+ *
+ * Verifying this with Playwright: its synthetic wheel reports a deltaY twice
+ * what Chrome actually applies (confirmed on a bare overflow-y:auto box —
+ * event 200 -> 100px scrolled). The harness can show WHETHER a region scrolls,
+ * never HOW FAR. Real wheel events are 1:1 in DOM_DELTA_PIXEL.
+ */
+
+/** Fallback px-per-line for wheels reporting DOM_DELTA_LINE (Firefox). */
+const LINE_HEIGHT_PX = 16;
+
+/**
+ * Does `el` own this wheel event — either by declaring it, or by being a
+ * scroll container with somewhere left to go in either direction?
+ *
+ * Deliberately direction-agnostic. A sidebar already scrolled to its bottom
+ * still counts as "owns the wheel", so this hook does not take the wheel away
+ * from a column that merely ran out of room — that would be full scroll
+ * chaining, a behaviour change well beyond restoring the dead zones. Only a
+ * region that can never scroll at all hands its wheel to the content column.
+ *
+ * Only overflowY auto/scroll qualifies: a code block with `overflow-x: auto`
+ * and `overflow-y: hidden` must stay transparent to a vertical wheel, or every
+ * wide snippet becomes its own dead zone.
+ *
+ * The ORDER of the reads below is load-bearing, not incidental. overflowY and
+ * overscrollBehaviorY are style-only resolved values — reading them can cost a
+ * style recalc, never a layout. scrollHeight/clientHeight ARE layout-dependent
+ * and flush layout if it is dirty. Because the overflow test gates them, an
+ * ancestor that is not a scroll container costs one cheap read, and a typical
+ * 6-10 node walk forces zero layouts. Hoisting the scroll-range check above the
+ * overflow check would make every wheel event force layout on every ancestor.
+ */
+function ownsTheWheel(el: Element): boolean {
+  const style = getComputedStyle(el);
+
+  // `overscroll-behavior-y: contain | none` is an author saying explicitly
+  // "scrolling must not chain out of me". Honour it whether or not the element
+  // currently has room — an empty chat transcript or a short playground pane
+  // still means it, and forwarding past it would scroll the docs underneath.
+  // Used by ChatPanel, PlaygroundModal and Prompt.
+  const overscrollY = style.overscrollBehaviorY;
+  if (overscrollY === 'contain' || overscrollY === 'none') return true;
+
+  const overflowY = style.overflowY;
+  if (overflowY !== 'auto' && overflowY !== 'scroll') return false;
+  // Sub-pixel heights (zoom, fractional DPR) can leave a hairline of fake
+  // scroll range, so require more than a pixel before calling it scrollable.
+  return el.scrollHeight - el.clientHeight > 1;
+}
+
+/** Can the content column still move in the direction of `deltaY`? */
+function canConsume(el: Element, deltaY: number): boolean {
+  const overflowY = getComputedStyle(el).overflowY;
+  if (overflowY !== 'auto' && overflowY !== 'scroll') return false;
+  if (el.scrollHeight - el.clientHeight <= 1) return false;
+  return deltaY > 0
+    ? el.scrollTop + el.clientHeight < el.scrollHeight - 1
+    : el.scrollTop > 1;
+}
+
+/** Normalise wheel delta to pixels — deltaY is lines in mode 1, pages in mode 2. */
+function deltaToPixels(event: WheelEvent, viewportHeight: number): number {
+  if (event.deltaMode === 1) return event.deltaY * LINE_HEIGHT_PX;
+  if (event.deltaMode === 2) return event.deltaY * viewportHeight;
+  return event.deltaY;
+}
+
+/**
+ * Is a modal holding a body scroll lock right now?
+ *
+ * `useBodyScrollLock` sets `document.body.style.overflow = 'hidden'` and
+ * nothing else. The `html[data-scroll-locked]` CSS rule in globals.css that
+ * DOES neutralise the content column is first-paint only — `scrollLockBootstrap`
+ * removes the attribute within ~100ms of DOMContentLoaded, long before any
+ * modal opens. So with Cmd+K open the content column is still `overflow-y:
+ * auto` and still scrollable, and without this check the wheel over a modal's
+ * dimmed backdrop scrolled the docs behind it (verified live).
+ */
+function isScrollLocked(): boolean {
+  // Inline first: that is literally what useBodyScrollLock writes, and it is
+  // the one form jsdom reports faithfully (it does not expand the `overflow`
+  // shorthand into computed `overflowY`). The computed check stays as the
+  // catch-all for a lock applied via a stylesheet instead. Both were confirmed
+  // to read 'hidden' in Chrome with the search modal open.
+  if (document.body.style.overflow === 'hidden') return true;
+  return getComputedStyle(document.body).overflowY === 'hidden';
+}
+
+/**
+ * @param enabled - pass false in embed mode. PageColumns emits
+ *   `#content-scroll-container` unconditionally (only the TOC aside is
+ *   embed-gated), so the hook is NOT inert there by construction — it only
+ *   happens to no-op because the embed shell is `min-h-screen`, leaving the
+ *   column unbounded. Any future bounded height would switch it on inside a
+ *   customer's embedded widget.
+ */
+export function useWheelScrollChaining(enabled = true): void {
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleWheel = (event: WheelEvent) => {
+      // ctrl+wheel is pinch-zoom, not a scroll. shift+wheel is the browser's
+      // horizontal-scroll modifier — it still arrives as deltaY, and native
+      // chaining would look for somewhere HORIZONTAL to go, find nothing in a
+      // dead zone, and do nothing. Scrolling vertically instead would invent
+      // behaviour the browser never had.
+      if (event.ctrlKey || event.shiftKey || event.deltaY === 0) return;
+      // A snippet can register its own non-passive wheel handler (a pan/zoom
+      // canvas, a custom carousel) and call preventDefault. Nothing in
+      // build-service does today, but customer `/snippets` 'use client' files
+      // can, and overriding them would scroll the docs out from under the
+      // widget. React's onWheel is passive at the root, so this only catches
+      // native listeners — which are exactly the ones that can mean it.
+      if (event.defaultPrevented) return;
+      if (isScrollLocked()) return;
+
+      const content = document.querySelector<HTMLElement>('#content-scroll-container');
+      if (!content) return;
+
+      // Below lg this is `overflow-y: visible`, so the document scrolls
+      // normally and native chaining already works — bail out there.
+      if (!canConsume(content, event.deltaY)) return;
+
+      // Element, not HTMLElement: an SVG target (D2/Mermaid diagrams, inline
+      // icons) is an SVGElement, and narrowing to HTMLElement skipped the walk
+      // entirely — the delta was then forwarded on top of the browser's own
+      // scroll, doubling scroll speed over every diagram.
+      const target: Element | null =
+        event.target instanceof Element ? event.target : null;
+
+      // The chat panel is its own surface, not page chrome. Before any message
+      // arrives it has nothing to scroll, and forwarding there would scroll the
+      // docs behind an open panel — surprising, and not the dead zone we set
+      // out to fix. Leave it inert, exactly as it is today.
+      if (target?.closest('[data-chat-panel]')) return;
+
+      let node: Element | null = target;
+
+      while (node) {
+        // Something under the cursor owns the wheel — let the browser do it.
+        if (ownsTheWheel(node)) return;
+        if (node === document.documentElement) break;
+        node = node.parentElement;
+      }
+
+      content.scrollTop += deltaToPixels(event, content.clientHeight);
+    };
+
+    window.addEventListener('wheel', handleWheel, { passive: true });
+    return () => window.removeEventListener('wheel', handleWheel);
+  }, [enabled]);
+}

package/vendored/lib/docs-types.ts

@@ -806,6 +806,17 @@ export interface MetadataConfig {
   timestamp?: boolean;
 }
 
+/**
+ * Localization behaviour.
+ *
+ * `autoRedirect` opts a project into server-side Accept-Language routing at
+ * locale roots. Default OFF: turning it on changes what a first-time visitor
+ * sees, so it is never inferred from the presence of `navigation.languages`.
+ */
+export interface LocalizationConfig {
+  autoRedirect?: boolean;
+}
+
 /**
  * Icons library configuration
  */
@@ -947,6 +958,7 @@ export interface DocsConfig {
   thumbnails?: ThumbnailsConfig;
   interaction?: InteractionConfig;
   metadata?: MetadataConfig;
+  localization?: LocalizationConfig;
   analytics?: AnalyticsConfig;
   chat?: ChatConfig;
   spellcheck?: SpellcheckConfig;

package/vendored/lib/language-cookie.ts

@@ -0,0 +1,20 @@
+/**
+ * The language-preference cookie, in a module with NO imports.
+ *
+ * It lives alone because both sides need it and neither may reach the other:
+ * `middleware-helpers.ts` pulls in `next/server`, `@upstash/redis` (via
+ * ./redis and ./cached-redis) and the project resolver, while
+ * `language-utils.ts` is client code — the `'use client'` LanguageSelector
+ * imports it. Having language-utils import the constant from
+ * middleware-helpers would both close an import cycle (middleware-helpers
+ * already imports extractLanguageFromPath from language-utils, line 22) and
+ * drag the edge/Redis modules into the browser bundle. Neither `tsc --noEmit`
+ * nor vitest would catch that — only `next build` would, and this repo has
+ * already taken a production outage from exactly that class of bug.
+ */
+
+/** Cookie carrying the visitor's chosen documentation language. */
+export const LANGUAGE_COOKIE = 'jd-lang';
+
+/** One year — this is a stated preference, not a session detail. */
+export const LANGUAGE_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;

package/vendored/lib/language-matcher.ts

@@ -0,0 +1,124 @@
+/**
+ * Language routing module.
+ *
+ * Fetches a project's language-routing descriptor from `_languages.json` in R2,
+ * cached in Upstash Redis with a 5-minute TTL. Mirrors redirect-matcher.ts —
+ * same cache shape, same negative caching, same fail-open contract.
+ *
+ * Fail-open is not optional here: this runs inside proxy.ts, which has no error
+ * boundary. Any throw becomes a 500 on a page that would otherwise have served
+ * fine, so every path in this file returns null instead of raising.
+ */
+
+import { redis } from './redis';
+import type { LanguagesFile } from './languages-artifact';
+import { getFileBufferFromR2 } from './r2';
+
+// Cache TTL in seconds (5 minutes) — same as redirects.
+const CACHE_TTL = 300;
+
+// Redis cache key prefix.
+const CACHE_PREFIX = 'languages:';
+
+/** Sentinel written on a miss so a project without the file stops hitting R2. */
+const EMPTY: LanguagesFile = {
+  version: 1,
+  autoRedirect: false,
+  defaultLanguage: '',
+  languages: [],
+};
+
+/** Structural gate — a half-written or hand-edited file must not reach callers. */
+function isValid(value: unknown): value is LanguagesFile {
+  if (!value || typeof value !== 'object') return false;
+  const file = value as Partial<LanguagesFile>;
+  return (
+    typeof file.autoRedirect === 'boolean' &&
+    typeof file.defaultLanguage === 'string' &&
+    Array.isArray(file.languages) &&
+    file.languages.every((code) => typeof code === 'string')
+  );
+}
+
+/**
+ * Clear cached language routing for a project (or all projects).
+ * Called during revalidation to pick up an updated `_languages.json` from R2.
+ */
+export async function clearLanguageCache(projectName?: string): Promise<void> {
+  if (!redis) return;
+  try {
+    if (projectName) {
+      await redis.del(`${CACHE_PREFIX}${projectName}`);
+      return;
+    }
+    const keys: string[] = [];
+    let cursor = '0';
+    do {
+      const result: [string, string[]] = await redis.scan(cursor, {
+        match: `${CACHE_PREFIX}*`,
+        count: 100,
+      });
+      cursor = result[0];
+      keys.push(...result[1]);
+    } while (cursor !== '0');
+    if (keys.length > 0) {
+      const pipeline = redis.pipeline();
+      for (const key of keys) pipeline.del(key);
+      await pipeline.exec();
+    }
+  } catch {
+    // Ignore cache clear errors — a stale entry expires in CACHE_TTL anyway.
+  }
+}
+
+/**
+ * Fetch language routing for a project from R2 with Redis caching.
+ * Returns null when the project has no descriptor, or on any failure.
+ */
+export async function getLanguageRouting(projectName: string): Promise<LanguagesFile | null> {
+  const cacheKey = `${CACHE_PREFIX}${projectName}`;
+
+  if (redis) {
+    try {
+      const cached = await redis.get<LanguagesFile>(cacheKey);
+      if (isValid(cached)) {
+        return cached.languages.length > 0 ? cached : null;
+      }
+    } catch (error) {
+      console.error('[Languages] Redis cache read failed:', error);
+      // Continue to R2.
+    }
+  }
+
+  try {
+    const buffer = await getFileBufferFromR2(projectName, '_languages.json');
+    if (!buffer) {
+      // Negative-cache the miss so a single-language project does not pay an R2
+      // round trip on every request for the next five minutes.
+      if (redis) {
+        try {
+          await redis.set(cacheKey, EMPTY, { ex: CACHE_TTL });
+        } catch {
+          // Ignore cache write errors.
+        }
+      }
+      return null;
+    }
+
+    const parsed: unknown = JSON.parse(buffer.toString('utf-8'));
+    if (!isValid(parsed)) return null;
+
+    if (redis) {
+      try {
+        await redis.set(cacheKey, parsed, { ex: CACHE_TTL });
+      } catch {
+        // Ignore cache write errors.
+      }
+    }
+
+    return parsed.languages.length > 0 ? parsed : null;
+  } catch (error) {
+    console.error('[Languages] Failed to load _languages.json:', error);
+    return null;
+  }
+}

package/vendored/lib/language-utils.ts

@@ -6,6 +6,7 @@
 
 import type { LanguageCode, LanguageConfig } from './docs-types';
 import LANGUAGE_CODES_JSON from './language-codes.json';
+import { LANGUAGE_COOKIE, LANGUAGE_COOKIE_MAX_AGE } from './language-cookie';
 
 /**
  * Canonical language code list, shared with the CJS build script via
@@ -472,6 +473,13 @@ function storageKey(projectSlug: string): string {
   return `${LANGUAGE_STORAGE_KEY_PREFIX}${projectSlug}`;
 }
 
+// Mirrors proxy.ts's `secure: process.env.NODE_ENV === 'production'` exactly
+// — gated rather than hardcoded so a write from this client code doesn't
+// silently downgrade the attribute the server's redirect already set.
+// `NODE_ENV` is inlined at build time by Next.js, so this is a build-time
+// constant even though it reads like a runtime check.
+const COOKIE_SECURE_ATTR = process.env.NODE_ENV === 'production' ? '; secure' : '';
+
 /**
  * Save language preference to localStorage, scoped to project slug.
  * Handles private browsing mode gracefully.
@@ -484,6 +492,16 @@ export function saveLanguagePreference(code: LanguageCode, projectSlug: string):
     // localStorage not available (private browsing, etc.)
     // Fail silently
   }
+  // Mirror the choice into the cookie the edge reads. Without this, a visitor
+  // who overrides the server's Accept-Language guess is redirected back to the
+  // language they just rejected on their next visit to a locale root.
+  try {
+    document.cookie =
+      `${LANGUAGE_COOKIE}=${encodeURIComponent(code)}; path=/; max-age=${LANGUAGE_COOKIE_MAX_AGE}; samesite=lax${COOKIE_SECURE_ATTR}`;
+  } catch {
+    // Cookies blocked (private mode, strict settings) — localStorage still
+    // carries the preference for this browser, so degrade quietly.
+  }
 }
 
 /**
@@ -521,6 +539,11 @@ export function clearLanguagePreference(projectSlug: string): void {
   } catch {
     // localStorage not available
   }
+  try {
+    document.cookie = `${LANGUAGE_COOKIE}=; path=/; max-age=0; samesite=lax${COOKIE_SECURE_ATTR}`;
+  } catch {
+    // Ignore — see saveLanguagePreference.
+  }
 }
 
 /**
@@ -545,3 +568,83 @@ export function resolveLanguageWithFallback(
   }
   return 'en';
 }
+
+/**
+ * Cap on Accept-Language segments we will parse. A header is attacker-
+ * controlled; parsing is O(segments x available) and middleware runs on every
+ * request, so we stop reading after a sane number of entries rather than let a
+ * crafted header burn edge CPU. Real browsers send fewer than 10.
+ */
+const MAX_ACCEPT_LANGUAGE_SEGMENTS = 20;
+
+/**
+ * Pick the best available language for an Accept-Language header.
+ *
+ * Returns `null` — meaning "do nothing" — when the header is absent, unusable,
+ * matches nothing available, or resolves to the site's default language. A null
+ * return is always safe: the caller simply serves the page it was going to
+ * serve. This function never throws; middleware has no error boundary, so a
+ * throw here would 500 the page.
+ *
+ * Matching is case-insensitive and two-pass: an exact tag match (`zh-Hans`)
+ * beats a base-language match (`zh`), so a site offering both gets the precise
+ * one.
+ */
+export function negotiateLanguage(
+  header: string | null,
+  available: string[],
+  defaultLang: string,
+): string | null {
+  if (!header || available.length === 0) return null;
+
+  // Map lowercased code -> original casing, so we return the code exactly as
+  // the tenant configured it (callers build URLs from this).
+  const availableByLower = new Map<string, string>();
+  for (const code of available) {
+    availableByLower.set(code.toLowerCase(), code);
+  }
+
+  const parsed: Array<{ tag: string; q: number }> = [];
+  const segments = header.split(',', MAX_ACCEPT_LANGUAGE_SEGMENTS);
+
+  for (const segment of segments) {
+    const [rawTag, ...params] = segment.trim().split(';');
+    const tag = rawTag.trim().toLowerCase();
+    // '*' means "anything" — it expresses no preference, so we decline to guess.
+    if (!tag || tag === '*') continue;
+    if (!BCP47_LANGUAGE_RE.test(tag)) continue;
+
+    let q = 1;
+    for (const param of params) {
+      const match = /^\s*q\s*=\s*([0-9.]+)\s*$/i.exec(param);
+      if (!match) continue;
+      const value = Number.parseFloat(match[1]);
+      // A malformed q (NaN) is ignored, leaving the default q=1 — RFC 9110
+      // treats an unparseable parameter as absent rather than fatal.
+      if (Number.isFinite(value)) q = value;
+    }
+    if (q <= 0) continue;
+    parsed.push({ tag, q });
+  }
+
+  if (parsed.length === 0) return null;
+
+  // Stable sort by descending q: equal-q tags keep header order, which is the
+  // client's own stated preference order.
+  parsed.sort((a, b) => b.q - a.q);
+
+  const defaultLower = defaultLang.toLowerCase();
+
+  for (const { tag } of parsed) {
+    // Pass 1: exact tag ('zh-hans' -> 'zh-Hans').
+    const exact = availableByLower.get(tag);
+    if (exact) return exact.toLowerCase() === defaultLower ? null : exact;
+
+    // Pass 2: base language ('fr-ca' -> 'fr').
+    const base = tag.split('-')[0];
+    const baseMatch = availableByLower.get(base);
+    if (baseMatch) return baseMatch.toLowerCase() === defaultLower ? null : baseMatch;
+  }
+
+  return null;
+}