jamdesk 1.1.28 → 1.1.30

package/vendored/hooks/useDelayedNavigationSpinner.ts

@@ -0,0 +1,94 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+const DEFAULT_DELAY_MS = 500;
+
+export interface UseDelayedNavigationSpinnerResult {
+  /** Path of the link that was just clicked — set immediately, used for optimistic active highlight. */
+  pendingPathname: string | null;
+  /** Path of the link that has been "pending" longer than the delay threshold — drives the spinner UI. */
+  spinnerPathname: string | null;
+  /** Call from the link's onClick handler with the link's href. */
+  onNavigate: (url: string) => void;
+}
+
+/**
+ * Two-stage navigation feedback:
+ *   1. Click → `pendingPathname` set immediately (optimistic active highlight).
+ *   2. After `delayMs` (default 500ms) → `spinnerPathname` set, signaling
+ *      "this navigation is taking a while, show a spinner."
+ *
+ * Both clear when the live `pathname` matches the pending one (navigation
+ * resolved) or when the user clicks a different link (the new click cancels
+ * the old timer and starts fresh).
+ *
+ * Same-page hash clicks (`/current#anchor`) are ignored — they don't cause
+ * a real navigation, so the timer would never get cleared by `pathname` change.
+ *
+ * Double-clicks on the same pending link are no-ops — the in-flight timer keeps
+ * running so the spinner appears 500ms after the FIRST click, not the second.
+ *
+ * `onNavigate` has stable identity across pathname changes (live values are read
+ * from refs, not closure-captured) so it doesn't bust `React.memo` on the
+ * hundreds of `<NavPage>` instances rendered in large docs sites.
+ */
+export function useDelayedNavigationSpinner(
+  pathname: string | null,
+  delayMs: number = DEFAULT_DELAY_MS,
+): UseDelayedNavigationSpinnerResult {
+  const [pendingPathname, setPendingPathname] = useState<string | null>(null);
+  const [spinnerPathname, setSpinnerPathname] = useState<string | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const pathnameRef = useRef(pathname);
+  const pendingRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    pathnameRef.current = pathname;
+  }, [pathname]);
+
+  const clearTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+
+  const onNavigate = useCallback((url: string) => {
+    const path = url.split('#')[0];
+
+    // Same-page hash click — no real navigation, just clear any leftover state.
+    if (path === pathnameRef.current) {
+      clearTimer();
+      setPendingPathname(null);
+      setSpinnerPathname(null);
+      pendingRef.current = null;
+      return;
+    }
+
+    // Double-click on the same pending link — let the existing timer run.
+    if (path === pendingRef.current) {
+      return;
+    }
+
+    clearTimer();
+    setSpinnerPathname(null);
+    setPendingPathname(path);
+    pendingRef.current = path;
+    timerRef.current = setTimeout(() => {
+      setSpinnerPathname(path);
+      timerRef.current = null;
+    }, delayMs);
+  }, [clearTimer, delayMs]);
+
+  useEffect(() => {
+    clearTimer();
+    setPendingPathname(null);
+    setSpinnerPathname(null);
+    pendingRef.current = null;
+  }, [pathname, clearTimer]);
+
+  useEffect(() => () => clearTimer(), [clearTimer]);
+
+  return { pendingPathname, spinnerPathname, onNavigate };
+}

package/vendored/hooks/useTextStreamPacer.ts

@@ -0,0 +1,152 @@
+/**
+ * Rate-limited text reveal pacer for streaming chat responses.
+ *
+ * Backend SSE deltas often arrive clumped (Haiku generates short answers
+ * fast; CDN/middleware sometimes buffers tiny frames together). Without
+ * pacing, the React message state updates in one big jump and the user
+ * perceives "the response just appeared". This pacer holds incoming text
+ * in a buffer and drains it at a bounded rate via requestAnimationFrame.
+ *
+ * The `now` option exists for deterministic tests: vitest fake timers
+ * do NOT fake `performance.now` unless `toFake: ['performance']` is
+ * passed, and we want tests that don't reach into that global.
+ */
+export interface TextStreamPacerOptions {
+  /** Called each frame with newly-revealed text (never the full accumulated string). */
+  onReveal: (chunk: string) => void;
+  /** Called once after `finish()` has emitted the last buffered characters,
+   *  or synchronously after `finish()` under reduced-motion. */
+  onDrain?: () => void;
+  /** Baseline reveal rate. Default 80 chars/sec (~comfortable "writing" speed). */
+  baseCharsPerSecond?: number;
+  /** Max reveal rate while catching up. Default 400 chars/sec (~2x fast-talker read speed). */
+  maxCharsPerSecond?: number;
+  /** Buffer length at which we switch from base to max rate. Default 200. */
+  catchUpThreshold?: number;
+  /** Buffer length at which finish() dumps the whole buffer at once. Default 800.
+   *  Only applies post-finish — ensures long responses don't take >2s of reveal
+   *  time after the stream completes. Arriving bursts mid-stream pace normally. */
+  instantFlushThreshold?: number;
+  /** If true, pacer flushes immediately on every `enqueue` and `finish` fires
+   *  `onDrain` synchronously. Callers own the `prefers-reduced-motion` check —
+   *  typically via `useMediaQuery('(prefers-reduced-motion: reduce)')`. Default false. */
+  reducedMotion?: boolean;
+  /** Clock function. Default `performance.now`. Injectable for tests. */
+  now?: () => number;
+}
+
+export interface TextStreamPacer {
+  /** Add text to the buffer. RAF loop resumes on first enqueue after idle. */
+  enqueue(text: string): void;
+  /** Signal stream complete — drain remaining buffer at max rate, then fire onDrain. */
+  finish(): void;
+  /** Stop pacing immediately. Buffered text is discarded; onDrain does not fire. */
+  abort(): void;
+}
+
+export function createTextStreamPacer(options: TextStreamPacerOptions): TextStreamPacer {
+  const {
+    onReveal,
+    onDrain,
+    baseCharsPerSecond = 80,
+    maxCharsPerSecond = 400,
+    catchUpThreshold = 200,
+    instantFlushThreshold = 800,
+    reducedMotion = false,
+    now = () => performance.now(),
+  } = options;
+
+  let buffer = '';
+  let finished = false;
+  let aborted = false;
+  let rafId: number | null = null;
+  let lastFrameMs: number | null = null;
+  let fractionalChars = 0;
+
+  const flushBuffer = () => {
+    if (buffer.length === 0) return;
+    const chunk = buffer;
+    buffer = '';
+    onReveal(chunk);
+  };
+
+  const tick = () => {
+    rafId = null;
+    if (aborted) return;
+
+    const t = now();
+    const elapsedMs = lastFrameMs === null ? 16 : t - lastFrameMs;
+    lastFrameMs = t;
+
+    // Instant flush only applies post-completion — it bounds drain time after
+    // finish(), but must not short-circuit pacing while the stream is still
+    // arriving (otherwise a fast Haiku burst would appear in one flash).
+    if (finished && buffer.length >= instantFlushThreshold) {
+      flushBuffer();
+      fractionalChars = 0;
+    } else {
+      // Rate is driven purely by buffer length — don't boost on `finished`,
+      // or short responses whose buffer never hits catchUpThreshold would
+      // drain in one frame and defeat the typing-pace effect.
+      const rate = buffer.length > catchUpThreshold
+        ? maxCharsPerSecond
+        : baseCharsPerSecond;
+
+      fractionalChars += (rate * elapsedMs) / 1000;
+      const reveal = Math.min(Math.floor(fractionalChars), buffer.length);
+      if (reveal > 0) {
+        fractionalChars -= reveal;
+        const chunk = buffer.slice(0, reveal);
+        buffer = buffer.slice(reveal);
+        onReveal(chunk);
+      }
+    }
+
+    if (buffer.length > 0) {
+      schedule();
+      return;
+    }
+
+    // Drained.
+    lastFrameMs = null;
+    fractionalChars = 0;
+    if (finished) {
+      finished = false; // one-shot
+      onDrain?.();
+    }
+  };
+
+  const schedule = () => {
+    if (rafId !== null || aborted) return;
+    rafId = requestAnimationFrame(tick);
+  };
+
+  return {
+    enqueue(text) {
+      if (aborted || !text) return;
+      if (reducedMotion) {
+        onReveal(text);
+        return;
+      }
+      buffer += text;
+      schedule();
+    },
+    finish() {
+      if (aborted) return;
+      if (reducedMotion) {
+        onDrain?.();
+        return;
+      }
+      finished = true;
+      schedule();
+    },
+    abort() {
+      aborted = true;
+      buffer = '';
+      if (rafId !== null) {
+        cancelAnimationFrame(rafId);
+        rafId = null;
+      }
+    },
+  };
+}

package/vendored/lib/chat-prompt.ts

@@ -29,6 +29,40 @@ export function buildCannedIdentityReply(projectName: string): string {
   return `I'm the documentation assistant for ${projectName}, here to help with questions about the product.`;
 }
 
+/**
+ * Detects whether Claude's markdown output is the canned identity reply.
+ *
+ * Haiku at temperature 0.3 drifts the exact string in small ways: curly vs
+ * straight apostrophes, trailing period variants, surrounding markdown
+ * emphasis (`*...*`), or extra whitespace. An exact === compare against
+ * buildCannedIdentityReply would miss those and let the "top 2 by score"
+ * citation fallback attach unrelated docs sources under the identity reply.
+ *
+ * We normalize both sides (strip markdown emphasis/quotes, collapse
+ * whitespace, fold apostrophes, drop trailing punctuation, lowercase) and
+ * compare on the stable prefix "I'm the documentation assistant for <name>".
+ * A suffix check keeps the match anchored so arbitrary Haiku output that
+ * happens to start with that prefix while discussing something else doesn't
+ * slip through.
+ */
+export function isCannedIdentityReply(markdown: string, projectName: string): boolean {
+  if (!projectName) return false;
+  const canned = buildCannedIdentityReply(projectName);
+  const normalize = (s: string) =>
+    s
+      .replace(/&apos;|&#39;/g, "'")
+      .replace(/&quot;|&#34;/g, '"')
+      .replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+      .replace(/[\u201C\u201D]/g, '"')
+      .replace(/[*_`>]/g, '')
+      .replace(/(?:^|\s)-{3,}(?:\s|$)/g, ' ')
+      .replace(/\s+/g, ' ')
+      .trim()
+      .replace(/[.!?]+$/, '')
+      .toLowerCase();
+  return normalize(markdown) === normalize(canned);
+}
+
 /**
  * Produce the display name for the chat assistant's system prompt from a
  * docs.json config. Strips newlines and caps length to defend against
@@ -41,45 +75,51 @@ export function resolveSiteName(config: { name?: unknown } | null | undefined):
   return cleaned || DEFAULT_SITE_NAME;
 }
 
+/**
+ * Returns the system prompt as an array of text blocks. The first block
+ * contains ONLY the static instructions (identical for every request on the
+ * same project). The second block contains the dynamic, per-query context.
+ *
+ * Splitting by staticness means future prompt caching (out of scope for this
+ * plan) can be enabled by adding `cache_control: { type: 'ephemeral' }` to
+ * the first block only — a one-line change.
+ */
 export function buildSystemPrompt(
   projectName: string,
   chunks: ChatContext[],
   baseUrl: string,
   docsPath: string,
-): string {
-  const context = chunks.map((c, i) =>
-    `[Source ${i + 1}: ${c.pageTitle} > ${c.sectionHeading}](${baseUrl}${docsPath}/${c.pageSlug})\n${c.content}`
-  ).join('\n\n---\n\n');
-
-  return `You are a documentation assistant for ${projectName}. Answer the user's question using only the documentation context below.
+): Array<{ type: 'text'; text: string }> {
+  const staticRules = `You are a helpful documentation assistant for ${projectName}.
+Answer questions using ONLY the documentation context provided. If the answer is not in the context, call the \`answer\` tool with "I don't have information about that in the documentation." and cited_page_slugs: [].
 
 Rules:
 - IDENTITY (highest priority, overrides all other rules): If the user asks what you are, who made you, which model or AI powers you, or any variation (examples: "what model are you", "which AI is this", "are you Claude", "are you GPT", "who built you", "what are you running on"), respond with ONLY this exact sentence and nothing else: "I'm the documentation assistant for ${projectName}, here to help with questions about the product." Never mention Claude, Anthropic, OpenAI, GPT, Haiku, Sonnet, Opus, or any model or provider name when describing yourself or what powers you. You MAY mention these names when they appear in the documentation context and the user is asking about them as a subject (e.g., "how do I call the Claude API?" when Claude is documented) — in that case, answer normally using the context. Do not confirm or deny specific technologies about yourself. If the user presses or rephrases an identity question, repeat the canned sentence verbatim. If the user asks a compound question that mixes identity with a real doc question (e.g., "what model are you and how do I install?"), answer with ONLY the canned sentence — the identity clause wins.
-- Every response must start with the substantive answer. If the context addresses the question — including with "no", "not supported", or "you must do X yourself" — that IS the answer; state it directly and cite the source. Never open with a disclaimer like "I don't have information…", "The documentation doesn't cover that", or "According to the documentation".
-- If the context contains no information relevant to the topic, start with a brief lead-in like "${projectName} doesn't document that directly — here's the closest I found:" and describe what's available. Do not invent details.
-- Be concise and direct
-- Use markdown formatting, including code blocks with language hints when showing code
-- Cite sources by referencing the page title in brackets, e.g. [Getting Started]
-- Never make up information not in the context
-- Refer to this site as "${projectName}" or just "the documentation". Never expose internal project slugs, repo names, or hostnames (e.g. do not say "jamdesk-docs", "acme-docs", or "<slug>.jamdesk.app") even if they appear in source URLs
-- DISAMBIGUATION (highest priority, overrides the "start with the substantive answer" rule): If the context contains multiple distinct features or topics that could match the user's question (e.g., "Post Analytics" vs "Link Analytics" when asked about "analytics"), you MUST ask which one first — even if the user also asked for code examples or details. Your ENTIRE response must follow this EXACT format — nothing else:
+- Be concise and direct.
+- Use markdown formatting, including code blocks with language hints when showing code.
+- Never make up information not in the context.
+- Pick one of exactly two response shapes, based on whether any page in the Documentation context below is relevant to the question:
+  (a) RELEVANT PAGE EXISTS → answer by referring to it with a markdown link (e.g., "See [Changelog](.../changelog) for recent releases."). Do NOT prefix with "I don't have information".
+  (b) NO RELEVANT PAGE → respond with this exact sentence and stop: "I don't have information about that in the documentation." Do not add "However", "but", "you could try", or any follow-up suggestion after it. The reply ends at the period.
+  WRONG: "I don't have information about that in the documentation. However, if you're asking about X, you could..." ← This is forbidden. If the first sentence is true, stop there.
+- Never name a page ("the Changelog", "the API reference", "the Settings page", etc.) unless that page appears in the Documentation context below.
+- Refer to this site as "${projectName}" or just "the documentation". Never expose internal project slugs, repo names, or hostnames (e.g. do not say "jamdesk-docs", "acme-docs", or "<slug>.jamdesk.app") even if they appear in source URLs.
+- RESOLVE IMPLICIT SUBJECTS: when the user's question has no explicit subject (pronouns like "it", "this", "they", or bare noun phrases like "the product", "pricing", "the API"), assume they are asking about ${projectName} unless the conversation clearly establishes a different subject. For example, "how much does it cost" means "how much does ${projectName} cost"; "is it open source" means "is ${projectName} open source". Resolve the reference and answer from the documentation context — do not hedge just because the pronoun wasn't spelled out.
+- When the context includes API endpoints (e.g. "POST /analytics/post") or technical operations, proactively include a short code example showing the request (HTTP method, endpoint, JSON body) even if the user didn't explicitly ask. If the context has no code-relevant information, skip the example.
+- Use the pageSlug values (shown in the context as [pageSlug: ...]) when populating cited_page_slugs — not the page title.
 
-<question ending with ?>
+Tool choice:
+- Use the \`answer\` tool for most questions.
+- Use the \`ask_clarification\` tool ONLY when the context contains 2-3 distinct, unrelated features that could match the user's question (e.g. "Post Analytics" vs "Link Analytics" when asked about "analytics"). If you are sure which one the user means, answer directly.`;
 
-1. <option>
-2. <option>
-3. <option>
-
-Rules: question mark required, numbered list required (1. 2. 3.), no descriptions after options, no extra text before or after. Example:
-
-Which type of analytics are you interested in?
+  const context = chunks.map((c) =>
+    `[pageSlug: ${c.pageSlug}] ${c.pageTitle} > ${c.sectionHeading}\nURL: ${baseUrl}${docsPath}/${c.pageSlug}\n${c.content}`,
+  ).join('\n\n---\n\n');
 
-1. Post Analytics
-2. Social Analytics
-3. Link Analytics
-- When the context includes API endpoints (e.g. "POST /analytics/post") or technical operations, proactively include a short code example showing the request (HTTP method, endpoint, JSON body) even if the user didn't explicitly ask for one. Technical users expect to see code. If the context has no code-relevant information, skip the example.
-- When constructing code examples from API endpoints in the context, use the endpoint, HTTP method, and any parameters/body fields mentioned. Always note it's a basic example and link to the full API reference page.
+  const dynamicContext = `Documentation context:\n${context}`;
 
-Documentation context:
-${context}`;
+  return [
+    { type: 'text', text: staticRules },
+    { type: 'text', text: dynamicContext },
+  ];
 }

package/vendored/lib/chat-tools.ts

@@ -0,0 +1,111 @@
+/**
+ * Tool schemas for the AI documentation chat.
+ *
+ * Forces Claude into structured output: it must call exactly one of
+ * `answer` (for direct answers) or `ask_clarification` (when the query
+ * matches 2-3 distinct topics in the retrieved context).
+ *
+ * Replaces the regex-based `extractCitations` and `extractClarificationOptions`
+ * parsers. Citations become the `cited_page_slugs[]` field on the answer tool;
+ * clarification options become the `options[]` field on the clarification tool.
+ */
+import type Anthropic from '@anthropic-ai/sdk';
+
+// Stricter local shapes so tests + consumers get typed access to nested
+// schema fields. The SDK types `input_schema.properties` as `unknown | null`,
+// which would force `any` casts at every access site. These local types are
+// structurally assignable to `Anthropic.Tool`, so they remain valid SDK input.
+interface AnswerToolSchema {
+  name: 'answer';
+  description: string;
+  input_schema: {
+    type: 'object';
+    properties: {
+      markdown: { type: 'string'; description: string };
+      cited_page_slugs: {
+        type: 'array';
+        items: { type: 'string' };
+        description: string;
+      };
+    };
+    required: ['markdown', 'cited_page_slugs'];
+  };
+}
+
+interface ClarificationToolSchema {
+  name: 'ask_clarification';
+  description: string;
+  input_schema: {
+    type: 'object';
+    properties: {
+      question: { type: 'string'; description: string };
+      options: {
+        type: 'array';
+        items: { type: 'string' };
+        minItems: 2;
+        maxItems: 3;
+        description: string;
+      };
+    };
+    required: ['question', 'options'];
+  };
+}
+
+export const ANSWER_TOOL: AnswerToolSchema = {
+  name: 'answer',
+  description:
+    'Provide a direct answer to the user\'s question using the documentation context. ' +
+    'Always populate cited_page_slugs with the pageSlug of every source you referenced. ' +
+    'If the context does not contain an answer, still call this tool and say "I don\'t have information about that in the documentation." with cited_page_slugs: [].',
+  input_schema: {
+    type: 'object',
+    properties: {
+      markdown: {
+        type: 'string',
+        description:
+          'The answer in markdown. Use code blocks with language hints when showing code. ' +
+          'Do not embed citation text like "[Page Title]" — citations are listed in cited_page_slugs.',
+      },
+      cited_page_slugs: {
+        type: 'array',
+        items: { type: 'string' },
+        description:
+          'The pageSlug values (e.g. "getting-started", "api/auth") for every documentation source you referenced. ' +
+          'Empty array if the answer is "I don\'t have information about that".',
+      },
+    },
+    required: ['markdown', 'cited_page_slugs'],
+  },
+};
+
+export const CLARIFICATION_TOOL: ClarificationToolSchema = {
+  name: 'ask_clarification',
+  description:
+    'Ask the user to choose between 2-3 distinct topics when their question is ambiguous. ' +
+    'Only use when the documentation context contains multiple unrelated features that could match ' +
+    '(e.g. "Post Analytics" vs "Link Analytics" when asked about "analytics"). ' +
+    'The question must end with a question mark.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      question: {
+        type: 'string',
+        description: 'A short disambiguation question ending with "?". E.g. "Which type of analytics are you asking about?"',
+      },
+      // minItems/maxItems are advisory to the model — Anthropic does NOT
+      // enforce them server-side. The chat route must defensively validate
+      // options.length before rendering a clarification UI.
+      options: {
+        type: 'array',
+        items: { type: 'string' },
+        minItems: 2,
+        maxItems: 3,
+        description: 'The distinct topics the user can choose between. Short labels like "Post Analytics", "Link Analytics".',
+      },
+    },
+    required: ['question', 'options'],
+  },
+};
+
+// Exported as Anthropic.Tool[] so it passes directly to client.messages.stream({ tools: CHAT_TOOLS }).
+export const CHAT_TOOLS: Anthropic.Tool[] = [ANSWER_TOOL, CLARIFICATION_TOOL];

package/vendored/lib/crisp-bridge.ts

@@ -0,0 +1,91 @@
+/**
+ * Bridge to the Crisp chat widget's command queue API.
+ *
+ * Coordinates visibility between our AI chat panel and Crisp's launcher
+ * so they don't visually collide in the bottom-right corner of docs sites.
+ *
+ * Crisp's docs: https://help.crisp.chat/en/article/how-to-use-crisp-from-javascript-api-1xhvaxt/
+ */
+
+type CrispAction = 'chat:close' | 'chat:hide' | 'chat:show' | 'chat:open';
+type CrispCommand = ['do', CrispAction];
+
+interface CrispQueue {
+  push(command: CrispCommand): void;
+}
+
+function getCrisp(): CrispQueue | null {
+  if (typeof window === 'undefined') return null;
+  const q = (window as unknown as { $crisp?: unknown }).$crisp;
+  if (q && typeof (q as { push?: unknown }).push === 'function') {
+    return q as CrispQueue;
+  }
+  return null;
+}
+
+export function crispAvailable(): boolean {
+  return getCrisp() !== null;
+}
+
+const RETRY_INTERVAL_MS = 500;
+const RETRY_MAX_ATTEMPTS = 30;
+
+let pendingHideTimer: ReturnType<typeof setInterval> | null = null;
+
+function clearPendingHideRetry(): void {
+  if (pendingHideTimer !== null) {
+    clearInterval(pendingHideTimer);
+    pendingHideTimer = null;
+  }
+}
+
+function applyHide(crisp: CrispQueue): void {
+  // chat:close must come before chat:hide. Crisp can auto-reshow the
+  // launcher after a session reset, so closing any open session first
+  // reduces the race window.
+  crisp.push(['do', 'chat:close']);
+  crisp.push(['do', 'chat:hide']);
+}
+
+export function hideCrispLauncher(): void {
+  if (typeof window === 'undefined') return;
+  clearPendingHideRetry();
+  const crisp = getCrisp();
+  if (crisp) {
+    applyHide(crisp);
+    return;
+  }
+  let attempts = 0;
+  pendingHideTimer = setInterval(() => {
+    attempts += 1;
+    const q = getCrisp();
+    if (q) {
+      applyHide(q);
+      clearPendingHideRetry();
+      return;
+    }
+    if (attempts >= RETRY_MAX_ATTEMPTS) {
+      clearPendingHideRetry();
+    }
+  }, RETRY_INTERVAL_MS);
+}
+
+export function showCrispLauncher(): void {
+  clearPendingHideRetry();
+  const crisp = getCrisp();
+  if (!crisp) return;
+  crisp.push(['do', 'chat:show']);
+}
+
+export function openCrispChat(): void {
+  clearPendingHideRetry();
+  const crisp = getCrisp();
+  if (!crisp) return;
+  crisp.push(['do', 'chat:show']);
+  crisp.push(['do', 'chat:open']);
+}
+
+// Test-only: clears module-level retry state between cases.
+export function _resetForTests(): void {
+  clearPendingHideRetry();
+}

package/vendored/lib/docs-types.ts

@@ -394,6 +394,8 @@ export interface NavigationConfig {
  */
 export interface NavbarLink {
   label: string;
+  /** Optional per-language overrides (e.g. `{ "fr": "Blog", "es": "Blog" }`). Falls back to `label`. */
+  labels?: Record<string, string>;
   icon?: IconConfig;
   href: string;
 }
@@ -404,6 +406,8 @@ export interface NavbarLink {
 export interface NavbarPrimary {
   type: 'button' | 'github';
   label?: string;
+  /** Optional per-language overrides. Falls back to `label` or the built-in default. */
+  labels?: Record<string, string>;
   href: string;
 }