jamdesk 1.1.35 → 1.1.38

package/templates/docs.json

@@ -1,10 +1,37 @@
 {
   "name": "{{PROJECT_NAME}}",
+  "theme": "jam",
+  "api": {
+    "openapi": [
+      "/openapi/example-api.yaml"
+    ],
+    "examples": {
+      "languages": [
+        "curl",
+        "python",
+        "javascript",
+        "go",
+        "ruby",
+        "csharp",
+        "java",
+        "rust",
+        "php"
+      ]
+    }
+  },
   "navigation": {
     "groups": [
       {
         "group": "Getting Started",
         "pages": ["introduction", "quickstart"]
+      },
+      {
+        "group": "API Pages",
+        "icon": "plug",
+        "pages": [
+          { "page": "api-reference/openapi-example", "title": "OpenAPI Example" },
+          "api-reference/request-response-examples"
+        ]
       }
     ]
   }

package/templates/openapi/example-api.yaml

@@ -0,0 +1,185 @@
+openapi: 3.0.3
+info:
+  title: Acme Support API
+  version: "1.0.0"
+  description: |
+    The Acme Support API lets you create and track customer support tickets.
+    Use it to post new issues from your product and keep users updated on status.
+servers:
+  - url: https://jamdesk-docs.jamdesk.app/api/playground/demo
+security: []
+paths:
+  /tickets:
+    get:
+      summary: List support tickets
+      description: Retrieve all open support tickets.
+      operationId: listTickets
+      responses:
+        "200":
+          description: Ticket list
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tickets:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/TicketSummary"
+                  total:
+                    type: integer
+              example:
+                tickets:
+                  - id: "tkt_9S8L2"
+                    customer_id: "cus_2X9W8"
+                    subject: "Export stuck on step 3"
+                    priority: "high"
+                    status: "open"
+                    created_at: "2026-02-04T16:12:00Z"
+                total: 1
+    post:
+      summary: Create a support ticket
+      description: Create a new ticket for a customer issue or request.
+      operationId: createTicket
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateTicketRequest"
+            example:
+              customer_id: "cus_2X9W8"
+              subject: "Export stuck on step 3"
+              priority: "high"
+              tags: ["export", "bug"]
+              message: "The export job fails with error 504 after 2 minutes."
+      responses:
+        "201":
+          description: Ticket created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Ticket"
+              example:
+                id: "tkt_9S8L2"
+                customer_id: "cus_2X9W8"
+                subject: "Export stuck on step 3"
+                priority: "high"
+                status: "open"
+                created_at: "2026-02-04T16:12:00Z"
+        "400":
+          description: Invalid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              example:
+                code: "invalid_request"
+                message: "subject is required"
+  /tickets/{ticket_id}:
+    get:
+      summary: Get a support ticket
+      description: Retrieve a specific support ticket by its ID.
+      operationId: getTicket
+      parameters:
+        - name: ticket_id
+          in: path
+          required: true
+          description: Unique ticket identifier
+          schema:
+            type: string
+          example: "tkt_9S8L2"
+      responses:
+        "200":
+          description: Ticket details
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Ticket"
+              example:
+                id: "tkt_9S8L2"
+                customer_id: "cus_2X9W8"
+                subject: "Export stuck on step 3"
+                priority: "high"
+                status: "open"
+                tags: ["export", "bug"]
+                message: "The export job fails with error 504 after 2 minutes."
+                created_at: "2026-02-04T16:12:00Z"
+                updated_at: "2026-02-04T16:12:00Z"
+components:
+  schemas:
+    CreateTicketRequest:
+      type: object
+      required:
+        - customer_id
+        - subject
+        - message
+      properties:
+        customer_id:
+          type: string
+          description: Customer identifier in Acme.
+        subject:
+          type: string
+          description: Short summary of the issue.
+        priority:
+          type: string
+          enum: [low, normal, high, urgent]
+        tags:
+          type: array
+          items:
+            type: string
+        message:
+          type: string
+          description: Detailed problem description.
+    TicketSummary:
+      type: object
+      description: Abbreviated ticket for list responses (excludes message and tags).
+      properties:
+        id:
+          type: string
+        customer_id:
+          type: string
+        subject:
+          type: string
+        priority:
+          type: string
+        status:
+          type: string
+          enum: [open, pending, resolved]
+        created_at:
+          type: string
+          format: date-time
+    Ticket:
+      type: object
+      description: Full ticket detail including message and tags.
+      properties:
+        id:
+          type: string
+        customer_id:
+          type: string
+        subject:
+          type: string
+        priority:
+          type: string
+        status:
+          type: string
+          enum: [open, pending, resolved]
+        tags:
+          type: array
+          items:
+            type: string
+        message:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    Error:
+      type: object
+      properties:
+        code:
+          type: string
+        message:
+          type: string

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

@@ -48,7 +48,6 @@ import { buildEndpointFromMdx } from '@/lib/build-endpoint-from-mdx';
 import { mdxSecurityOptions } from '@/lib/mdx-security-options';
 import fs from 'fs';
 import path from 'path';
-import matter from 'gray-matter';
 import { getContentDir } from '@/lib/docs';
 import type { DocsConfig } from '@/lib/docs-types';
 import { buildSeoMetadata, generateAutoDescription, buildSiteTitle } from '@/lib/seo';
@@ -61,7 +60,6 @@ import {
   normalizeSlugForContent,
   parseFrontmatter,
   projectExists,
-  type ContentLoader,
 } from '@/lib/content-loader';
 import { getBaseUrl, pathToSlug } from '@/lib/page-isr-helpers';
 import {
@@ -70,6 +68,7 @@ import {
   parseEndpoint,
   generateCodeExamples,
   formatOpenApiWarning,
+  deriveAuthFromSecurity,
   type OpenApiEndpointData,
   type CodeExample,
   type AuthMethod,
@@ -134,6 +133,22 @@ function resolveBaseUrl(
   return process.env.SITE_URL || DEFAULT_SITE_URL;
 }
 
+/**
+ * docs.json override is treated as a UNIT — if method is set, both method and name
+ * come from docs.json, avoiding a stale customer-set `name` pairing with a
+ * spec-derived `method`. Falls back to deriving auth from the OpenAPI security schemes.
+ */
+function resolveAuth(
+  endpoint: OpenApiEndpointData | null | undefined,
+  config: DocsConfig,
+): { method?: AuthMethod; headerName?: string } {
+  const override = config.api?.mdx?.auth;
+  if (override?.method) {
+    return { method: override.method, headerName: override.name };
+  }
+  return endpoint ? deriveAuthFromSecurity(endpoint.security) : {};
+}
+
 /**
  * Frontmatter data from MDX files.
  */
@@ -548,9 +563,9 @@ export default async function DocPage({ params }: PageProps) {
 
       // Generate code examples
       if (openApiEndpointData) {
-        const authMethod = config.api?.mdx?.auth?.method as AuthMethod | undefined;
+        const { method: authMethod, headerName: authHeaderName } = resolveAuth(openApiEndpointData, config);
         const languages = config.api?.examples?.languages;
-        openApiCodeExamples = generateCodeExamples(openApiEndpointData, { authMethod, languages });
+        openApiCodeExamples = generateCodeExamples(openApiEndpointData, { authMethod, authHeaderName, languages });
       }
     } catch (err) {
       const typed = classifyOpenApiLoadError(err, lastFailure?.specPath ?? null);
@@ -616,6 +631,9 @@ export default async function DocPage({ params }: PageProps) {
     mdxEndpointData = buildEndpointFromMdx(mdxApiMethod, mdxApiPath, paramFields, fallbackServerUrl);
   }
 
+  const resolvedMdxAuth = resolveAuth(mdxEndpointData, config);
+  const resolvedOpenApiAuth = resolveAuth(openApiEndpointData, config);
+
   // For API pages, wrap the entire content area with ApiPageWrapper
   // so code panels can be positioned as siblings at the page level
   if (isApiPage) {
@@ -653,8 +671,8 @@ export default async function DocPage({ params }: PageProps) {
                   endpoint={mdxEndpointData}
                   playgroundOnly
                   playgroundDisplay={playgroundDisplay}
-                  authMethod={config.api?.mdx?.auth?.method as AuthMethod | undefined}
-                  authHeaderName={config.api?.mdx?.auth?.name}
+                  authMethod={resolvedMdxAuth.method}
+                  authHeaderName={resolvedMdxAuth.headerName}
                   serverUrl={fallbackServerUrl}
                   proxyEnabled={proxyEnabled}
                   languages={config.api?.examples?.languages}
@@ -674,8 +692,8 @@ export default async function DocPage({ params }: PageProps) {
                 endpoint={openApiEndpointData}
                 codeExamples={openApiCodeExamples || undefined}
                 playgroundDisplay={playgroundDisplay}
-                authMethod={config.api?.mdx?.auth?.method as AuthMethod | undefined}
-                authHeaderName={config.api?.mdx?.auth?.name}
+                authMethod={resolvedOpenApiAuth.method}
+                authHeaderName={resolvedOpenApiAuth.headerName}
                 serverUrl={fallbackServerUrl}
                 proxyEnabled={proxyEnabled}
                 languages={config.api?.examples?.languages}

package/vendored/app/api/chat/[project]/route.ts

@@ -30,6 +30,7 @@ import { rewriteQueryForSearch } from '@/lib/query-rewriter';
 import { fetchDocsConfig } from '@/lib/r2-content';
 import { redis } from '@/lib/redis';
 import { CHAT_TOOLS } from '@/lib/chat-tools';
+import { rewriteSlugLinks } from '@/lib/link-rewriter';
 import { log } from '@/lib/logger';
 
 export const runtime = 'nodejs';
@@ -43,6 +44,7 @@ const MAX_HISTORY = 10;
  *  Used both for searchQuery enrichment and to skip the rewriter. */
 const SHORT_FOLLOWUP_LEN = 60;
 const VALID_ROLES = new Set<string>(['user', 'assistant']);
+const VALID_LOCALE_RE = /^[a-zA-Z]{2,3}(?:[-_][a-zA-Z]{2,4})?$/;
 
 export async function POST(
   request: NextRequest,
@@ -75,7 +77,7 @@ export async function POST(
     }
   }
 
-  let body: { message: unknown; history?: unknown[] };
+  let body: { message: unknown; history?: unknown[]; locale?: unknown };
   try {
     body = await request.json();
   } catch {
@@ -88,6 +90,14 @@ export async function POST(
     return Response.json({ error: 'Invalid message' }, { status: 400 });
   }
 
+  let clientLocale: string | undefined;
+  if (body.locale !== undefined) {
+    if (typeof body.locale !== 'string' || !VALID_LOCALE_RE.test(body.locale)) {
+      return Response.json({ error: 'Invalid locale' }, { status: 400 });
+    }
+    clientLocale = body.locale;
+  }
+
   // Sanitize history: only allow valid roles, string content, capped length
   const history = (Array.isArray(rawHistory) ? rawHistory : [])
     .filter((h): h is { role: 'user' | 'assistant'; content: string } => {
@@ -122,6 +132,29 @@ export async function POST(
     fetchDocsConfig(project).catch(() => null),
   ]);
 
+  // Per-project rollout gate. Filter applies ONLY when the client sent a
+  // locale AND the project is opted in. Both default to off so this is a
+  // safe deploy. Set the flag with: redis-cli SET chatLocaleFilter:<slug> true
+  //
+  // Skip the Redis read entirely when no client locale was sent — the filter
+  // can never apply, so the round-trip would just block vector queries for
+  // nothing. This matters because the vector query path below depends on
+  // `effectiveLocale` and would otherwise wait on this read serially.
+  const localeFilterEnabled = clientLocale && redis
+    ? await redis.get(`chatLocaleFilter:${project}`)
+        .then((v) => v === 'true')
+        .catch((err) => {
+          // Fail-open is intentional (don't 500 chat on a Redis blip), but
+          // SREs need a signal — without this log, intermittent Redis
+          // outages silently regress the locale-pollution fix.
+          log('warn', 'chat: locale flag read failed, defaulting filter off', {
+            project, error: String(err),
+          });
+          return false;
+        })
+    : false;
+  const effectiveLocale = (localeFilterEnabled && clientLocale) ? clientLocale : undefined;
+
   // Fully parallel retrieval:
   //   - Original vector query runs immediately.
   //   - Rewriter + rewritten-query vector search are chained into ONE promise,
@@ -130,7 +163,8 @@ export async function POST(
   //     max(original, rewriter) + rewritten_query_time.
   // Any failure in the rewrite path resolves to an empty chunk list — the
   // original query still returns results so chat doesn't fail.
-  const originalQueryPromise = querySimilarChunks(project, searchQuery, 15);
+
+  const originalQueryPromise = querySimilarChunks(project, searchQuery, 15, { locale: effectiveLocale });
 
   // Skipping the rewriter on short follow-ups avoids 500-2000ms of serial
   // Anthropic latency — `searchQuery` above is already enriched with prior-turn
@@ -145,7 +179,7 @@ export async function POST(
             // (which is enriched with prior-turn context for short follow-ups).
             // The rewriter only sees `message`, so a no-op rewrite equals `message`.
             if (!rewritten || rewritten === message) return [];
-            return querySimilarChunks(project, rewritten, 15).catch(() => []);
+            return querySimilarChunks(project, rewritten, 15, { locale: effectiveLocale }).catch(() => []);
           });
 
   let originalChunks: Awaited<ReturnType<typeof querySimilarChunks>>;
@@ -196,6 +230,12 @@ export async function POST(
   const baseUrl = getBaseUrl(project, originalHost);
   const siteName = resolveSiteName(config);
 
+  // Map of pageSlug → canonical absolute URL, consumed by rewriteSlugLinks
+  // after the stream completes to canonicalize Haiku-generated link targets.
+  const slugToUrl: Record<string, string> = Object.fromEntries(
+    chunks.map((c) => [c.pageSlug, `${baseUrl}${docsPath}/${c.pageSlug}`]),
+  );
+
   const systemPrompt = buildSystemPrompt(siteName, chunks, baseUrl, docsPath);
 
   const stream = anthropic.messages.stream({
@@ -344,6 +384,16 @@ export async function POST(
             : explicitSources.length > 0
               ? explicitSources
               : topChunksAsCitations(2, seen);
+
+          // Two-pass URL rewrite: stream raw markdown live (for typing-effect
+          // UX), then emit a `text_replace` event with canonical absolute URLs
+          // once we have the full final markdown. Brief artifact: between the
+          // last text chunk and this event the user sees rendered slug-form
+          // URLs. Skip the event when nothing changed.
+          const rewrittenMarkdown = rewriteSlugLinks(markdownText, slugToUrl);
+          if (rewrittenMarkdown !== markdownText) {
+            controller.enqueue(sendEvent({ type: 'text_replace', content: rewrittenMarkdown }));
+          }
         } else if (toolUse.name === 'ask_clarification') {
           const input = toolUse.input as ClarificationInput;
           const options = Array.isArray(input.options) ? input.options : [];

package/vendored/app/api/docs-search/[project]/search/route.ts

@@ -20,6 +20,9 @@ import { querySimilarChunks } from '@/lib/vector-store';
 import { verifyApiKey } from '@/lib/docs-search-auth';
 import { getBaseUrl, trackServerAnalytics } from '@/lib/route-helpers';
 import { redis } from '@/lib/redis';
+import { fetchDocsConfig } from '@/lib/r2-content';
+import { isMultiLanguageConfig } from '@/lib/navigation-utils';
+import { log } from '@/lib/logger';
 
 export const runtime = 'nodejs';
 export const maxDuration = 30;
@@ -34,6 +37,11 @@ const MAX_LIMIT = 20;
 const DEFAULT_LIMIT = 5;
 const MAX_QUERY_LENGTH = 500;
 const RATE_LIMIT_PER_MIN = 60;
+/** BCP-47-ish: 2-3 letter primary tag, optional 2-4 letter region/script.
+ *  Matches the chat endpoint's VALID_LOCALE_RE — keep both contracts in sync.
+ *  Limitation: 3-segment tags like `zh-Hant-HK` are rejected. Documented. */
+const VALID_LANGUAGE_RE = /^[a-zA-Z]{2,3}(?:[-_][a-zA-Z]{2,4})?$/;
+const DEFAULT_LANGUAGE = 'en';
 
 export async function OPTIONS(_request: NextRequest) {
   return new NextResponse(null, { status: 204, headers: CORS_HEADERS });
@@ -89,7 +97,7 @@ export async function POST(
   }
 
   // --- Parse & validate request body ---
-  let body: { query?: string; limit?: number };
+  let body: { query?: string; limit?: number; language?: unknown };
   try {
     body = await request.json();
   } catch {
@@ -101,6 +109,23 @@ export async function POST(
 
   const { query, limit: rawLimit } = body;
 
+  // Validate language. `null` and `undefined` both default to 'en'
+  // (real-world clients send `language: null` from `?? null` fallbacks —
+  // rejecting them as 400 would be gratuitous). A non-string value or a
+  // string that doesn't match the BCP-47 pattern is a 400.
+  let language: string = DEFAULT_LANGUAGE;
+  let languageWasExplicit = false;
+  if (body.language != null) {
+    if (typeof body.language !== 'string' || !VALID_LANGUAGE_RE.test(body.language)) {
+      return NextResponse.json(
+        { error: 'Invalid language code' },
+        { status: 400, headers: CORS_HEADERS },
+      );
+    }
+    language = body.language;
+    languageWasExplicit = true;
+  }
+
   if (!query || typeof query !== 'string' || query.trim().length === 0) {
     return NextResponse.json(
       { error: 'Missing or empty "query" field' },
@@ -125,11 +150,66 @@ export async function POST(
     MAX_LIMIT,
   );
 
+  // --- Multi-language gate ---
+  // Apply the locale filter only when the project is configured for
+  // multiple languages AND the per-project kill switch is not set.
+  // Single-language projects' chunks have no locale metadata, so the
+  // strict filter would return zero. Run the config fetch and kill-switch
+  // read in parallel — fetchDocsConfig has a 5-min in-memory cache, and
+  // Redis is the bottleneck only on a cold cache. .catch() on the kill
+  // switch keeps a Redis blip from breaking searches.
+  const killSwitchPromise: Promise<boolean> = redis
+    ? redis.get(`searchLocaleFilter:${project}`)
+        .then((v) => v === 'disabled')
+        .catch(() => false)
+    : Promise.resolve(false);
+
+  let config: Awaited<ReturnType<typeof fetchDocsConfig>>;
+  let killSwitch: boolean;
+  try {
+    [config, killSwitch] = await Promise.all([
+      fetchDocsConfig(project),
+      killSwitchPromise,
+    ]);
+  } catch (err) {
+    // R2 outage — config unavailable. Asymmetric fail-mode:
+    //  - Caller sent an explicit language: 503 (don't silently leak
+    //    cross-language results to a caller who asked for filtering).
+    //  - Caller defaulted to 'en': fall back to today's no-filter behavior
+    //    so docs sites keep working through R2 incidents.
+    log('error', 'docs-search: fetchDocsConfig failed', {
+      project,
+      error: String(err),
+      languageWasExplicit,
+    });
+    if (languageWasExplicit) {
+      return NextResponse.json(
+        { error: 'Search temporarily unavailable' },
+        { status: 503, headers: CORS_HEADERS },
+      );
+    }
+    config = null;
+    killSwitch = await killSwitchPromise.catch(() => false);
+  }
+
+  if (killSwitch) {
+    // Operators have flipped the kill switch for this project — log so we
+    // can spot escapes. Not an error, but worth surfacing.
+    log('warn', 'docs-search: locale filter kill switch is enabled', {
+      project,
+    });
+  }
+
+  const applyLocaleFilter = !killSwitch && !!config && isMultiLanguageConfig(config);
+  const effectiveLocale = applyLocaleFilter ? language : undefined;
+
   // --- Semantic vector search ---
   const startMs = Date.now();
   let chunks;
   try {
-    chunks = await querySimilarChunks(project, query.trim(), limit);
+    chunks = await querySimilarChunks(project, query.trim(), limit, {
+      locale: effectiveLocale,
+    });
   } catch (err) {
     console.error('Vector search failed:', err);
     return NextResponse.json(
@@ -162,7 +242,7 @@ export async function POST(
   });
 
   return NextResponse.json(
-    { results, query: query.trim(), total: results.length, durationMs },
+    { results, query: query.trim(), language, total: results.length, durationMs },
     { status: 200, headers: CORS_HEADERS },
   );
 }

package/vendored/app/layout.tsx

@@ -8,10 +8,17 @@ import { CodeBlockCopyButton } from '@/components/CodeBlockCopyButton';
 import { HeaderLinkCopy } from '@/components/HeaderLinkCopy';
 import { FontAwesomeLoader } from '@/components/FontAwesomeLoader';
 import { JdReadySentinel } from '@/components/JdReadySentinel';
+import { HtmlLangSync } from '@/components/HtmlLangSync';
 import { FA_CSS_HREF } from '@/lib/font-awesome';
 import { getDocsConfig } from '@/lib/docs';
 import { getDocsConfig as getIsrDocsConfig } from '@/lib/docs-isr';
-import { isIsrMode, getProjectFromRequest, getHostAtDocs } from '@/lib/page-isr-helpers';
+import {
+  isIsrMode,
+  getProjectFromRequest,
+  getHostAtDocs,
+  getLanguageFromRequest,
+} from '@/lib/page-isr-helpers';
+import { isRTLLanguage, resolveLanguageWithFallback } from '@/lib/language-utils';
 import { getTheme, type ThemeName } from '@/themes';
 import { generateFontImports, generateFontVariables, isPreloadedFont, getPrimaryFontFamily } from '@/lib/fonts';
 import fs from 'fs';
@@ -269,8 +276,17 @@ export default async function RootLayout({
   // fetch. The unlock page owns its own visuals.
   const headersList = await headers();
   if (headersList.get('x-jd-unlock-mode') === '1') {
+    // Unlock mode short-circuits before we fetch project config, so we
+    // can't consult `config.navigation.languages` here. The middleware
+    // already extracts language from the original `from` path
+    // (proxy.ts), so the header is our only signal — fall back to "en".
+    const unlockLang = resolveLanguageWithFallback(
+      getLanguageFromRequest(headersList),
+      undefined,
+    );
+    const unlockDir = isRTLLanguage(unlockLang) ? 'rtl' : undefined;
     return (
-      <html lang="en">
+      <html lang={unlockLang} dir={unlockDir}>
         <head>
           <meta name="viewport" content="width=device-width, initial-scale=1" />
           <meta name="robots" content="noindex, nofollow" />
@@ -371,8 +387,14 @@ export default async function RootLayout({
     ? getAnalyticsScript(resolvedProjectSlug)
     : null;
 
+  // Project default — what `lang` resolves to when no path locale is present.
+  // HtmlLangSync uses it on soft-nav back to a non-localized path (e.g. `/`).
+  const projectDefaultLang = resolveLanguageWithFallback(null, config.navigation?.languages);
+  const lang = getLanguageFromRequest(headersList) ?? projectDefaultLang;
+  const dir = isRTLLanguage(lang) ? 'rtl' : undefined;
+
   return (
-    <html lang="en" suppressHydrationWarning data-scroll-behavior="smooth">
+    <html lang={lang} dir={dir} suppressHydrationWarning data-scroll-behavior="smooth">
       <head>
         {/* Add viewport meta for mobile */}
         <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -559,6 +581,7 @@ export default async function RootLayout({
           <CodeBlockCopyButton />
           <HeaderLinkCopy />
           <FontAwesomeLoader />
+          <HtmlLangSync defaultLanguage={projectDefaultLang} />
         </ThemeProvider>
         {/* Crisp Chat */}
         {config.integrations?.crisp?.websiteId &&

package/vendored/components/HtmlLangSync.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+import { useEffect } from 'react';
+import { usePathname } from 'next/navigation';
+import { extractLanguageFromPath, isRTLLanguage } from '@/lib/language-utils';
+import type { LanguageCode } from '@/lib/docs-types';
+
+interface HtmlLangSyncProps {
+  /** Project's resolved default language — used when the path has no locale prefix. */
+  defaultLanguage: LanguageCode;
+}
+
+/**
+ * Keeps `<html lang>` and `<html dir>` in sync with the current pathname
+ * across client-side navigations.
+ *
+ * The root layout only renders server-side on the initial request. Soft
+ * navigations (`router.push`, `<Link>`) leave the html attributes stale at
+ * the value the server emitted, so switching locale via the dropdown left
+ * `lang` pointing at the previous language until a hard refresh.
+ */
+export function HtmlLangSync({ defaultLanguage }: HtmlLangSyncProps) {
+  const pathname = usePathname();
+
+  useEffect(() => {
+    const lang = extractLanguageFromPath(pathname || '/') ?? defaultLanguage;
+    const html = document.documentElement;
+    if (html.lang !== lang) html.lang = lang;
+
+    if (isRTLLanguage(lang)) {
+      if (html.dir !== 'rtl') html.dir = 'rtl';
+    } else if (html.dir) {
+      html.removeAttribute('dir');
+    }
+  }, [pathname, defaultLanguage]);
+
+  return null;
+}

package/vendored/components/mdx/OpenApiEndpoint.tsx

@@ -11,6 +11,7 @@ import { CodePanel, CodePanelTab, getStatusColor } from '../ui/CodePanel';
 import { useShikiHighlightMultiple } from '@/hooks/useShikiHighlight';
 import { preloadHighlighter } from '@/lib/shiki-client';
 import ReactMarkdown from 'react-markdown';
+import { resolveServerUrl } from '@/lib/openapi/resolve-server-url';
 // Icons use Font Awesome CSS classes for lightweight rendering
 import type {
   OpenApiEndpointData,
@@ -916,7 +917,7 @@ export function OpenApiEndpoint({
   const headerParams = parameters.filter(p => p.in === 'header');
   const cookieParams = parameters.filter(p => p.in === 'cookie');
 
-  const baseUrl = servers[0]?.url;
+  const baseUrl = resolveServerUrl(servers[0]);
 
   // Playground state
   const showPlayground = playgroundDisplay !== 'none';