jamdesk 1.1.29 → 1.1.31

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

@@ -98,11 +98,13 @@ Rules:
 - Be concise and direct.
 - Use markdown formatting, including code blocks with language hints when showing code.
 - Never make up information not in the context.
-- Never combine "I don't have information" with a follow-up suggestion in the same response — that creates a self-contradiction. Pick one of exactly two response shapes:
-  (a) If any page in the Documentation context is relevant to the question, answer by referring to that page with a link (e.g., "See [Changelog](.../changelog) for recent releases."). Do not prefix with "I don't have information".
-  (b) If no relevant page is in context, respond with ONLY "I don't have information about that in the documentation." — no "but check", no "you can find", no alternatives.
+- 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.
 

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;
 }
 

package/vendored/lib/find-first-nav-page.ts

@@ -0,0 +1,40 @@
+/**
+ * Walk the navigation tree and return the slug of the first leaf page.
+ * Used to resolve empty-root and bare-language URLs (`/`, `/fr`, `/es`) to
+ * a concrete page in place, without emitting a redirect. Returns null if no
+ * leaf page is found.
+ */
+export function findFirstNavPage(nav: unknown): string | null {
+  if (!nav || typeof nav !== 'object') return null;
+  const node = nav as Record<string, unknown>;
+  const pages = node.pages;
+
+  if (Array.isArray(pages)) {
+    for (const p of pages) {
+      if (typeof p === 'string' && p.length > 0) return '/' + p;
+      if (p && typeof p === 'object') {
+        const pageVal = (p as Record<string, unknown>).page;
+        if (typeof pageVal === 'string' && pageVal.length > 0) {
+          return '/' + pageVal;
+        }
+        const nested = findFirstNavPage(p);
+        if (nested) return nested;
+      }
+    }
+    // A group is an atomic container — exhaust its pages rather than
+    // falling through to the sibling-key loop below.
+    if ('group' in node) return null;
+  }
+
+  for (const key of ['groups', 'tabs', 'anchors', 'versions', 'languages']) {
+    const arr = node[key];
+    if (Array.isArray(arr)) {
+      for (const item of arr) {
+        const nested = findFirstNavPage(item);
+        if (nested) return nested;
+      }
+    }
+  }
+
+  return null;
+}

package/vendored/lib/hedge-strip.ts

@@ -0,0 +1,29 @@
+/**
+ * Detects and truncates Claude's canned no-answer sentence
+ * ("I don't have information about that in the documentation.") when followed
+ * by a self-contradicting "However..." — a prompt-adherence failure mode of
+ * Haiku 4.5. Tolerates curly-vs-straight apostrophes and surrounding markdown
+ * emphasis.
+ *
+ * ASSUMPTION: the sentence is reserved for the no-answer reply. A docs page
+ * that legitimately contains the phrase would have content silently truncated.
+ */
+export const HEDGE_SENTENCE = "I don't have information about that in the documentation.";
+
+const HEDGE_REGEX = /I\s+don['\u2018\u2019]t\s+have\s+information\s+about\s+that\s+in\s+the\s+documentation\./i;
+
+export function stripHedge(markdown: string): string {
+  if (!markdown) return markdown;
+  const match = HEDGE_REGEX.exec(markdown);
+  if (!match) return markdown;
+  return markdown.slice(0, match.index + match[0].length);
+}
+
+/**
+ * True when the reply is (or contains) the canned no-answer sentence.
+ * Used to suppress misleading citation fallbacks on hedge replies.
+ */
+export function isHedgeReply(markdown: string): boolean {
+  const stripped = stripHedge(markdown);
+  return stripped.length !== markdown.length || stripped.trim() === HEDGE_SENTENCE;
+}

package/vendored/lib/middleware-helpers.ts

@@ -6,6 +6,7 @@
  */
 
 import { log } from './logger';
+import { isIsrMode } from './page-isr-helpers';
 import {
   resolveProjectFromHostname,
   resolveCustomDomain,
@@ -83,7 +84,7 @@ export async function handleProjectResolution(
   const hostname = request.headers.get('host') || '';
 
   // Skip if not in ISR mode
-  if (process.env.ISR_MODE !== 'true') {
+  if (!isIsrMode()) {
     return { projectSlug: null, hostAtDocs: true, skip: true };
   }
 

package/vendored/lib/openapi/lang-spec-path.ts

@@ -0,0 +1,16 @@
+export function langSpecPath(specPath: string, lang: string): string {
+  const lastSlash = specPath.lastIndexOf('/');
+  const fileName = specPath.slice(lastSlash + 1);
+  const dot = fileName.lastIndexOf('.');
+  if (dot === -1) return `${specPath}.${lang}`;
+  const base = fileName.slice(0, dot);
+  const ext = fileName.slice(dot);
+  const dir = specPath.slice(0, lastSlash + 1);
+  return `${dir}${base}.${lang}${ext}`;
+}
+
+export function candidateSpecPaths(specPath: string, lang: string | undefined): string[] {
+  if (!lang || lang === 'en') return [specPath];
+  if (/^https?:\/\//i.test(specPath)) return [specPath];
+  return [langSpecPath(specPath, lang), specPath];
+}

package/vendored/lib/page-isr-helpers.ts

@@ -9,7 +9,10 @@
  * Check if ISR mode is enabled.
  */
 export function isIsrMode(): boolean {
-  return process.env.ISR_MODE === 'true';
+  // Trim guards against trailing whitespace/newline picked up when the env
+  // var is set via the Vercel UI or piped-stdin CLI — a single stray \n
+  // silently disables ISR mode and returns 404 for every project.
+  return process.env.ISR_MODE?.trim() === 'true';
 }
 
 /**

package/vendored/lib/public-paths-resolver.ts

@@ -1,5 +1,8 @@
 import type { DocsConfig } from './docs-types.js';
 import { matchPublicPath } from './glob-match.js';
+import { findFirstNavPage } from './find-first-nav-page.js';
+
+export { findFirstNavPage };
 
 interface PageWithFrontmatter {
   slug: string;
@@ -11,48 +14,6 @@ interface Input {
   pagesWithFrontmatter: PageWithFrontmatter[];
 }
 
-/**
- * Walk the navigation tree and return the slug of the first leaf page.
- * Matches the resolution used by `app/[[...slug]]/page.tsx:findFirstPage`
- * so specific-pages mode can keep the root path public when the first
- * nav page is public. Returns null if no leaf page is found.
- */
-export function findFirstNavPage(nav: unknown): string | null {
-  if (!nav || typeof nav !== 'object') return null;
-  const node = nav as Record<string, unknown>;
-  const pages = node.pages;
-
-  if (Array.isArray(pages)) {
-    for (const p of pages) {
-      if (typeof p === 'string' && p.length > 0) return '/' + p;
-      if (p && typeof p === 'object') {
-        const pageVal = (p as Record<string, unknown>).page;
-        if (typeof pageVal === 'string' && pageVal.length > 0) {
-          return '/' + pageVal;
-        }
-        const nested = findFirstNavPage(p);
-        if (nested) return nested;
-      }
-    }
-    // A group is an atomic container — exhaust its pages rather than
-    // falling through to the sibling-key loop below (which is for
-    // top-level nav shapes like tabs/anchors/languages, not group contents).
-    if ('group' in node) return null;
-  }
-
-  for (const key of ['groups', 'tabs', 'anchors', 'versions', 'languages']) {
-    const arr = node[key];
-    if (Array.isArray(arr)) {
-      for (const item of arr) {
-        const nested = findFirstNavPage(item);
-        if (nested) return nested;
-      }
-    }
-  }
-
-  return null;
-}
-
 function collectPublicGroupPages(
   nav: unknown,
   inPublicGroup: boolean = false,

package/vendored/lib/ui-strings.ts

@@ -0,0 +1,54 @@
+import type { LanguageCode } from './docs-types';
+
+export interface UiStrings {
+  search: string;
+  askAi: string;
+  more: string;
+  toggleMenu: string;
+  selectLanguage: string;
+}
+
+const EN: UiStrings = {
+  search: 'Search',
+  askAi: 'Ask AI',
+  more: 'More',
+  toggleMenu: 'Toggle menu',
+  selectLanguage: 'Select language',
+};
+
+const ZH: Partial<UiStrings> = {
+  search: '搜索',
+  askAi: '询问 AI',
+  more: '更多',
+  toggleMenu: '切换菜单',
+  selectLanguage: '选择语言',
+};
+
+const OVERRIDES: Partial<Record<LanguageCode, Partial<UiStrings>>> = {
+  fr: {
+    search: 'Rechercher',
+    askAi: "Demander à l'IA",
+    more: 'Plus',
+    toggleMenu: 'Basculer le menu',
+    selectLanguage: 'Choisir la langue',
+  },
+  es: {
+    search: 'Buscar',
+    askAi: 'Preguntar a la IA',
+    more: 'Más',
+    toggleMenu: 'Alternar menú',
+    selectLanguage: 'Elegir idioma',
+  },
+  zh: ZH,
+  cn: ZH,
+};
+
+// Pre-merge so repeated calls return a stable object reference.
+const MERGED: Partial<Record<LanguageCode, UiStrings>> = {};
+for (const [code, overrides] of Object.entries(OVERRIDES) as [LanguageCode, Partial<UiStrings>][]) {
+  MERGED[code] = { ...EN, ...overrides };
+}
+
+export function getUiStrings(lang: LanguageCode | undefined): UiStrings {
+  return (lang && MERGED[lang]) || EN;
+}

package/vendored/schema/docs-schema.json

@@ -303,6 +303,11 @@
                                     "label": {
                                         "type": "string"
                                     },
+                                    "labels": {
+                                        "type": "object",
+                                        "additionalProperties": { "type": "string" },
+                                        "description": "Per-language label overrides keyed by language code (e.g. fr, es). Falls back to label."
+                                    },
                                     "icon": {
                                         "$ref": "#/definitions/iconSchema",
                                         "description": "Icon to display alongside this navigation item"
@@ -331,6 +336,11 @@
                                         "label": {
                                             "type": "string"
                                         },
+                                        "labels": {
+                                            "type": "object",
+                                            "additionalProperties": { "type": "string" },
+                                            "description": "Per-language label overrides keyed by language code (e.g. fr, es). Falls back to label."
+                                        },
                                         "href": {
                                             "$ref": "#/definitions/hrefSchema"
                                         }
@@ -349,6 +359,11 @@
                                             "type": "string",
                                             "const": "github"
                                         },
+                                        "labels": {
+                                            "type": "object",
+                                            "additionalProperties": { "type": "string" },
+                                            "description": "Per-language label overrides keyed by language code (e.g. fr, es). Falls back to 'GitHub'."
+                                        },
                                         "href": {
                                             "$ref": "#/definitions/hrefSchema"
                                         }

package/vendored/themes/jam/variables.css

@@ -782,19 +782,19 @@ body[data-theme="jam"] .prose video {
 /* Phase 2: Touch Targets for Sidebar */
 @media (max-width: 1023px) {
   :root {
-    --sidebar-item-spacing: 6px;
+    --sidebar-item-spacing: 3px;
   }
 
   .sidebar-scroll ul li a {
-    padding-top: 10px !important;
-    padding-bottom: 10px !important;
-    min-height: 44px;
+    padding-top: 7px !important;
+    padding-bottom: 7px !important;
+    min-height: 36px;
   }
 
   .sidebar-scroll .nav-group-l1 {
-    padding-top: 10px !important;
-    padding-bottom: 10px !important;
-    min-height: 44px;
+    padding-top: 7px !important;
+    padding-bottom: 7px !important;
+    min-height: 36px;
   }
 }
 

package/vendored/themes/nebula/variables.css

@@ -141,19 +141,19 @@
 /* Phase 2: Touch Targets for Sidebar */
 @media (max-width: 1023px) {
   :root {
-    --sidebar-item-spacing: 6px;
+    --sidebar-item-spacing: 3px;
   }
 
   .sidebar-scroll ul li a {
-    padding-top: 10px !important;
-    padding-bottom: 10px !important;
-    min-height: 44px;
+    padding-top: 7px !important;
+    padding-bottom: 7px !important;
+    min-height: 36px;
   }
 
   .sidebar-scroll .nav-group-l1 {
-    padding-top: 10px !important;
-    padding-bottom: 10px !important;
-    min-height: 44px;
+    padding-top: 7px !important;
+    padding-bottom: 7px !important;
+    min-height: 36px;
   }
 }
 

package/vendored/themes/pulsar/variables.css

@@ -896,19 +896,19 @@ body[data-theme="pulsar"] header [data-theme-toggle] {
 /* Phase 3: Touch Targets for Sidebar */
 @media (max-width: 1023px) {
   :root {
-    --sidebar-item-spacing: 6px;
+    --sidebar-item-spacing: 3px;
   }
 
   .sidebar-scroll ul li a {
-    padding-top: 10px !important;
-    padding-bottom: 10px !important;
-    min-height: 44px;
+    padding-top: 7px !important;
+    padding-bottom: 7px !important;
+    min-height: 36px;
   }
 
   .sidebar-scroll .nav-group-l1 {
-    padding-top: 10px !important;
-    padding-bottom: 10px !important;
-    min-height: 44px;
+    padding-top: 7px !important;
+    padding-bottom: 7px !important;
+    min-height: 36px;
   }
 }