jamdesk 1.1.28 → 1.1.30

package/vendored/lib/embedding-chunker.ts

@@ -14,8 +14,15 @@ export interface EmbeddingChunk {
   pageSlug: string;
   /** Heading of the section this chunk belongs to */
   sectionHeading: string;
-  /** Plain text content, stripped of markdown and JSX */
+  /** Plain-text body, stripped of markdown and JSX. Used for display (LLM context, search snippets). */
   content: string;
+  /**
+   * `<pageTitle> > <sectionHeading>\n` breadcrumb (plus `API Reference — METHOD /path\n`
+   * for API pages) that gets prepended to `content` when embedding — so BM25 finds
+   * chunks by page-title terms even when the body never uses them. Kept as a
+   * separate field so snippet consumers don't have to strip it.
+   */
+  prefix: string;
   /** Page title from frontmatter, or slug-derived fallback */
   pageTitle: string;
 }
@@ -111,18 +118,82 @@ function titleFromSlug(slug: string): string {
 }
 
 /**
- * Detect if a page is an API reference page and return a prefix label.
- * API pages get a prefix like "API Reference — POST /post\n" so the
- * embedding model clusters them distinctly from guides/tutorials.
+ * Build the per-chunk prefix that gets prepended to the cleaned content
+ * before embedding/upsert. Two purposes:
+ *
+ * 1. Title-breadcrumb: `<pageTitle> > <sectionHeading>` gives every chunk
+ *    a literal occurrence of its page title in the indexed text — so BM25
+ *    finds e.g. the `Changelog > April 2026` chunk for a "changelog" query
+ *    even when the month's content (Password Protection, YouTube Shorts)
+ *    never mentions the word "changelog" itself. Without this, pages that
+ *    happen to discuss a concept frequently (like `components/update`
+ *    documenting the `<Update>` MDX tag) outrank the actual answer chunks.
+ *
+ * 2. API-method tag: API-reference pages additionally get an
+ *    `API Reference — POST /endpoint` line so HTTP-method-specific queries
+ *    ("how do I POST to /analytics") cluster to the right endpoint page.
+ *
+ * Both lines end in `\n` so they stay visually separated from the content
+ * body when the chat model reads the full context block.
  */
 function getEmbeddingPrefix(
+  pageTitle: string,
+  sectionHeading: string,
   slug: string,
   frontmatter: Record<string, unknown>,
 ): string {
   const apiMethod = (frontmatter.api as string) || (frontmatter.openapi as string);
-  if (apiMethod) return `API Reference — ${apiMethod}\n`;
-  if (slug.startsWith('apis/')) return 'API Reference\n';
-  return '';
+  const apiLabel = apiMethod
+    ? `API Reference — ${apiMethod}\n`
+    : slug.startsWith('apis/') ? 'API Reference\n' : '';
+  const titleLabel = sectionHeading ? `${pageTitle} > ${sectionHeading}` : pageTitle;
+  return `${apiLabel}${titleLabel}\n`;
+}
+
+/**
+ * Without this, changelog-style pages that use `<Update>` wrappers (a
+ * Mintlify convention) collapse into a single heading-less blob — features
+ * in April get merged with features in March, and retrieval can't target
+ * a specific release. Promoting each label to a synthetic `### <label>`
+ * heading lets the existing heading splitter separate them.
+ *
+ * Matches `label` regardless of attribute order, handles self-closing tags,
+ * and leaves Update tags without a `label` attribute alone for
+ * `stripForEmbedding` to handle.
+ *
+ * Fenced code blocks are masked so Update tags inside ``` ... ``` examples
+ * (e.g. `components/update.mdx` pages that document the component itself)
+ * don't produce spurious chunks. `[^><]*?` (not `[^>]*?`) prevents a
+ * malformed opener (missing `>`) from greedily matching through to the
+ * next `</Update>` and silently eating body text.
+ */
+function preprocessUpdateBlocks(content: string): string {
+  const preserved: string[] = [];
+  const masked = content.replace(/```[\s\S]*?```/g, (m) => {
+    preserved.push(m);
+    return `\x00${preserved.length - 1}\x00`;
+  });
+
+  const transformed = masked
+    .replace(
+      /<Update\b[^><]*?\blabel="([^"]+)"[^><]*?\/?>/g,
+      (_, label: string) => {
+        const clean = sanitizeHeadingText(label);
+        return clean ? `\n### ${clean}\n` : '\n';
+      },
+    )
+    .replace(/<\/Update>/g, '\n');
+
+  return transformed.replace(/\x00(\d+)\x00/g, (_, i) => preserved[parseInt(i)]);
+}
+
+/**
+ * Collapse whitespace and drop leading `#` runs so a synthetic heading
+ * derived from a label (or a page title flowing into the breadcrumb) can't
+ * inject extra markdown heading depth or span multiple lines.
+ */
+function sanitizeHeadingText(raw: string): string {
+  return raw.replace(/^#+\s*/, '').replace(/\s+/g, ' ').trim();
 }
 
 /**
@@ -137,11 +208,11 @@ export function chunkPageForEmbedding(
   maxChars = 2000,
 ): EmbeddingChunk[] {
   const slug = page.path.replace(/\.mdx?$/, '').replace(/\\/g, '/');
-  const pageTitle = (page.frontmatter.title as string) || titleFromSlug(slug);
-  const embeddingPrefix = getEmbeddingPrefix(slug, page.frontmatter);
+  const rawTitle = (page.frontmatter.title as string) || titleFromSlug(slug);
+  const pageTitle = sanitizeHeadingText(rawTitle) || titleFromSlug(slug);
 
   // Normalize Windows line endings before extracting sections
-  const normalizedContent = page.content.replace(/\r\n/g, '\n');
+  const normalizedContent = preprocessUpdateBlocks(page.content.replace(/\r\n/g, '\n'));
 
   const sections = extractSections(normalizedContent);
   const chunks: EmbeddingChunk[] = [];
@@ -156,13 +227,16 @@ export function chunkPageForEmbedding(
       ? [cleanContent]
       : splitAtSentenceBoundaries(cleanContent, maxChars);
 
+    const prefix = getEmbeddingPrefix(pageTitle, section.heading, slug, page.frontmatter);
+
     for (const piece of pieces) {
       if (!piece.trim()) continue;
       chunks.push({
         id: `${slug}#${chunkIndex}`,
         pageSlug: slug,
         sectionHeading: section.heading,
-        content: embeddingPrefix + piece,
+        content: piece,
+        prefix,
         pageTitle,
       });
       chunkIndex++;

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/query-rewriter.ts

@@ -0,0 +1,91 @@
+/**
+ * Lightweight query rewriter for AI chat retrieval.
+ *
+ * Translates vague/natural-language user queries into doc-search vocabulary
+ * using Claude Haiku. Runs in parallel with the original query in the chat
+ * route, so latency is masked — if the rewrite is slow or fails, the caller
+ * falls back to the original query without penalty.
+ *
+ * Design notes:
+ * - Returns null on ANY failure path (no client, API error, empty response).
+ *   Callers must handle null by using the original query.
+ * - max_tokens is capped at 80 — rewrites are 3-10 words typically.
+ * - Conversation history is included so follow-ups like "what about the other
+ *   one" can be disambiguated against the prior user message.
+ */
+import { getAnthropicClient } from '@/lib/anthropic-client';
+
+const REWRITE_MODEL = 'claude-haiku-4-5-20251001';
+const MAX_REWRITE_CHARS = 200;
+
+export const SYSTEM_PROMPT = `You rewrite a user's chat question into a short documentation search query.
+
+Rules:
+- Output ONLY the rewritten query — no quotes, no explanation, no prefix.
+- Use terminology that would appear in technical documentation.
+- Keep it short (3-10 words is ideal).
+- If the user's question already uses technical vocabulary, output it unchanged.
+- If conversation history is provided, use it to disambiguate references like "the other one" or "that".
+
+Examples:
+Q: how do I make my docs live → deploy documentation site
+Q: change colors → theme customization
+Q: can it do auth → authentication setup
+Q: what about the other one (after discussing analytics) → link analytics
+Q: what is the most recent feature → changelog latest updates new features
+Q: what's new → changelog new features updates
+Q: latest release → changelog release notes updates
+Q: any updates recently → changelog recent updates new features`;
+
+export interface HistoryMessage {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * Rewrite a user query into doc-search vocabulary.
+ * Returns null on any failure — caller should fall back to the original query.
+ */
+export async function rewriteQueryForSearch(
+  message: string,
+  history: HistoryMessage[],
+): Promise<string | null> {
+  const anthropic = getAnthropicClient();
+  if (!anthropic) return null;
+
+  // Compose the user prompt: include the last user message from history (if any)
+  // so follow-up references resolve. Ignore assistant replies — they'd contaminate
+  // the rewrite with doc-flavored phrasing that might mask the user's real intent.
+  const priorUserMsg = [...history].reverse().find(
+    h => h.role === 'user' && h.content !== message,
+  );
+
+  const userPrompt = priorUserMsg
+    ? `Previous question: ${priorUserMsg.content}\nCurrent question: ${message}\n\nRewrite the current question:`
+    : `Question: ${message}\n\nRewrite:`;
+
+  try {
+    const response = await anthropic.messages.create({
+      model: REWRITE_MODEL,
+      max_tokens: 80,
+      temperature: 0.1,
+      system: SYSTEM_PROMPT,
+      messages: [{ role: 'user', content: userPrompt }],
+    });
+
+    const textBlock = response.content.find(c => c.type === 'text');
+    if (!textBlock || textBlock.type !== 'text') return null;
+
+    let rewrite = textBlock.text.trim();
+
+    // Strip surrounding quotes if Claude wrapped the output
+    rewrite = rewrite.replace(/^["'`]+|["'`]+$/g, '').trim();
+
+    if (!rewrite) return null;
+
+    // Defensive cap — prevents a runaway response from bloating the search query
+    return rewrite.slice(0, MAX_REWRITE_CHARS);
+  } catch {
+    return null;
+  }
+}

package/vendored/lib/ui-strings.ts

@@ -0,0 +1,52 @@
+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 STRINGS: Partial<Record<LanguageCode, Partial<UiStrings>>> = {
+  en: EN,
+  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,
+};
+
+export function getUiStrings(lang: LanguageCode | undefined): UiStrings {
+  if (!lang) return EN;
+  const overrides = STRINGS[lang];
+  if (!overrides) return EN;
+  return { ...EN, ...overrides };
+}

package/vendored/lib/vector-store.ts

@@ -44,8 +44,8 @@ const HYBRID_QUERY_OPTS = {
  */
 const MIN_SCORE = 0.3;
 
-/** Max chunks per page — ensures diverse results across pages */
-const MAX_CHUNKS_PER_PAGE = 3;
+/** Max chunks per page — raised from 3 to 4 to match broader topK retrieval budget */
+const MAX_CHUNKS_PER_PAGE = 4;
 
 /** Create a namespaced Upstash Vector index for a project. */
 function getNamespace(projectId: string) {
@@ -80,7 +80,9 @@ export async function upsertChunks(
     await ns.upsert(
       batch.map(c => ({
         id: c.id,
-        data: c.content,
+        // Prefix + body goes to Upstash for embedding/BM25; metadata.content
+        // stays prefix-free so consumers display clean body text.
+        data: c.prefix + c.content,
         metadata: {
           pageSlug: c.pageSlug,
           sectionHeading: c.sectionHeading,

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