jamdesk 1.1.29 → 1.1.30

package/dist/lib/deps.js

@@ -73,8 +73,8 @@ export const REQUIRED_DEPS = {
     'unified': '^11.0.0',
     'unist-util-visit': '^5.0.0',
     // CSS
-    'tailwindcss': '^4.2.2',
-    '@tailwindcss/postcss': '^4.2.2',
+    'tailwindcss': '^4.2.4',
+    '@tailwindcss/postcss': '^4.2.4',
     '@tailwindcss/typography': '^0.5.10',
     'postcss': '^8.5.10',
     'autoprefixer': '^10.4.24',
@@ -83,7 +83,7 @@ export const REQUIRED_DEPS = {
     'json5': '^2.2.3',
     'glob': '^13.0.6',
     // TypeScript (needed for Next.js to avoid auto-install breaking symlink)
-    'typescript': '^6.0.2',
+    'typescript': '^6.0.3',
     '@types/node': '^25.5.2',
     '@types/react': '^19.2.14',
     '@types/react-dom': '^19.0.0',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.29",
+  "version": "1.1.30",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",
@@ -114,7 +114,7 @@
     "json5": "^2.2.3",
     "nspell": "^2.1.5",
     "open": "^11.0.0",
-    "ora": "^9.3.0",
+    "ora": "^9.4.0",
     "tar": "^7.5.9"
   },
   "devDependencies": {
@@ -122,7 +122,7 @@
     "@types/fs-extra": "^11.0.0",
     "@types/node": "^25.5.0",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.3"
+    "vitest": "^4.1.5"
   },
   "engines": {
     "node": ">=20.0.0"

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

@@ -74,6 +74,9 @@ import {
   type CodeExample,
   type AuthMethod,
 } from '@/lib/openapi';
+import { extractLanguageFromPath, isValidLanguageCode } from '@/lib/language-utils';
+import { findFirstNavPage } from '@/lib/find-first-nav-page';
+import { candidateSpecPaths } from '@/lib/openapi/lang-spec-path';
 import { ApiEndpoint } from '@/components/mdx/ApiEndpoint';
 import { ImagePriorityProvider } from '@/components/mdx/ImagePriorityProvider';
 import { AIActionsMenu } from '@/components/AIActionsMenu';
@@ -182,100 +185,19 @@ function getAllDocPaths(): string[] {
   return paths;
 }
 
-/**
- * Find the first page in navigation (used to resolve empty root slug in place).
- */
-function findFirstPage(config: DocsConfig): string {
-  const navigation = config.navigation;
-
-  // Helper to extract page path from a page entry
-  const getPagePath = (page: unknown): string | null => {
-    if (typeof page === 'string') return page;
-    if (typeof page === 'object' && page && 'page' in page) {
-      return (page as { page: string }).page;
-    }
-    return null;
-  };
-
-  // Helper to extract first page from a group
-  const extractFirstFromGroup = (group: { pages?: unknown[] }): string | null => {
-    const itemPages = group.pages || [];
-    for (const page of itemPages) {
-      if (typeof page === 'object' && page && 'group' in page) {
-        const result = extractFirstFromGroup(page as { pages?: unknown[] });
-        if (result) return result;
-        continue;
-      }
-      const pagePath = getPagePath(page);
-      if (pagePath) return pagePath;
-    }
-    return null;
-  };
-
-  // Check languages first (multi-language navigation structure)
-  if (navigation.languages && navigation.languages.length > 0) {
-    const firstLang = navigation.languages[0];
-    if (firstLang.tabs && firstLang.tabs.length > 0) {
-      for (const tab of firstLang.tabs) {
-        if (tab.groups) {
-          for (const group of tab.groups) {
-            const result = extractFirstFromGroup(group);
-            if (result) return result;
-          }
-        }
-      }
-    }
-  }
-
-  // Check tabs first
-  if (navigation.tabs && navigation.tabs.length > 0) {
-    for (const tab of navigation.tabs) {
-      if (tab.groups) {
-        for (const group of tab.groups) {
-          const result = extractFirstFromGroup(group);
-          if (result) return result;
-        }
-      }
-    }
-  }
-
-  // Check top-level groups
-  if (navigation.groups && navigation.groups.length > 0) {
-    for (const group of navigation.groups) {
-      const result = extractFirstFromGroup(group);
-      if (result) return result;
-    }
-  }
-
-  // Check anchors
-  if (navigation.anchors && navigation.anchors.length > 0) {
-    for (const anchor of navigation.anchors) {
-      if (anchor.groups) {
-        for (const group of anchor.groups) {
-          const result = extractFirstFromGroup(group);
-          if (result) return result;
-        }
-      }
-    }
-  }
+function findFirstPage(config: DocsConfig, lang?: string): string {
+  const nav = config.navigation;
+  const langBlock = lang ? nav.languages?.find((l) => l.language === lang) : undefined;
+  const result = (langBlock && findFirstNavPage(langBlock)) || findFirstNavPage(nav);
+  return result ? result.replace(/^\//, '') : 'introduction';
+}
 
-  // Check pages array (flat format with groups inside pages)
-  if (navigation.pages && Array.isArray(navigation.pages)) {
-    for (const item of navigation.pages) {
-      // Could be a string page
-      const directPath = getPagePath(item);
-      if (directPath) return directPath;
-
-      // Could be a group object { group: "...", pages: [...] }
-      if (item && typeof item === 'object' && 'group' in item) {
-        const result = extractFirstFromGroup(item as { pages?: unknown[] });
-        if (result) return result;
-      }
-    }
+function resolveSlug(normalizedSlug: string[], config: DocsConfig): string[] {
+  if (normalizedSlug.length === 0) return pathToSlug(findFirstPage(config));
+  if (normalizedSlug.length === 1 && isValidLanguageCode(normalizedSlug[0])) {
+    return pathToSlug(findFirstPage(config, normalizedSlug[0]));
   }
-
-  // Fallback
-  return 'introduction';
+  return normalizedSlug;
 }
 
 export async function generateStaticParams() {
@@ -342,17 +264,12 @@ export async function generateMetadata({ params }: PageProps) {
   // Normalize slug: strip /docs prefix when hostAtDocs=true.
   // Empty root → resolve to first page (see DocPage for the full rationale).
   const normalizedSlug = normalizeSlugForContent(resolvedParams.slug || [], hostAtDocs);
+  const config = await loader.getConfig();
+  const slug = resolveSlug(normalizedSlug, config);
   const isRoot = normalizedSlug.length === 0;
-  const slug = isRoot
-    ? pathToSlug(findFirstPage(await loader.getConfig()))
-    : normalizedSlug;
   const pagePath = slug.join('/');
 
-  // Fetch content and config in parallel
-  const [fileContents, config] = await Promise.all([
-    loader.getContent(pagePath).catch(() => null),
-    loader.getConfig(),
-  ]);
+  const fileContents = await loader.getContent(pagePath).catch(() => null);
 
   if (!fileContents) {
     return {
@@ -428,14 +345,11 @@ export default async function DocPage({ params }: PageProps) {
   // redirect() emits cache-control: private, blocking CDN caching. Canonical
   // + noindex in generateMetadata prevent duplicate indexing.
   const normalizedSlug = normalizeSlugForContent(resolvedParams.slug || [], hostAtDocs);
-  const slug = normalizedSlug.length === 0
-    ? pathToSlug(findFirstPage(await loader.getConfig()))
-    : normalizedSlug;
+  const config = await loader.getConfig();
+  const slug = resolveSlug(normalizedSlug, config);
   const pagePath = slug.join('/');
-  const [fileContents, config] = await Promise.all([
-    loader.getContent(pagePath).catch(() => null),
-    loader.getConfig(),
-  ]);
+  const currentLang = extractLanguageFromPath(`/${pagePath}`);
+  const fileContents = await loader.getContent(pagePath).catch(() => null);
 
   // Check if content exists (getContent returns null via catch if not found)
   if (!fileContents) {
@@ -567,9 +481,13 @@ export default async function DocPage({ params }: PageProps) {
         allSpecPaths.length > 0 ? allSpecPaths : undefined
       );
 
-      const specsToTry = parsed.isShortFormat && allSpecPaths.length > 1
+      const baseSpecs = parsed.isShortFormat && allSpecPaths.length > 1
         ? allSpecPaths
         : [parsed.specPath];
+      // For each base spec, expand into [<base>.<lang>.ext, <base>.ext] when
+      // the page is under a localized URL. Resolver tries each in order; the
+      // first that loads wins. Missing lang variant falls back to English.
+      const specsToTry = baseSpecs.flatMap(p => candidateSpecPaths(p, currentLang));
 
       // Hoist mode-dependent values before the loop
       const useIsr = isIsrMode() && !!projectSlug;
@@ -580,7 +498,8 @@ export default async function DocPage({ params }: PageProps) {
 
       let lastError: unknown = null;
 
-      for (const specPath of specsToTry) {
+      for (let i = 0; i < specsToTry.length; i++) {
+        const specPath = specsToTry[i];
         try {
           if (resolveSpec && projectSlug) {
             const spec = await resolveSpec(projectSlug, specPath);
@@ -598,6 +517,14 @@ export default async function DocPage({ params }: PageProps) {
           break;
         } catch (err) {
           lastError = err;
+          const isLast = i === specsToTry.length - 1;
+          if (!isLast) {
+            // Lang variant (or intermediate candidate) failed — log so we
+            // notice transient R2 errors that silently fall through to English.
+            console.warn(
+              `[openapi] spec candidate "${specPath}" failed; trying next: ${(err as Error).message}`
+            );
+          }
         }
       }
 

package/vendored/app/api/assets/[...path]/route.ts

@@ -8,6 +8,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { fetchAsset } from '@/lib/r2-content';
 import { log } from '@/lib/logger';
+import { isIsrMode } from '@/lib/page-isr-helpers';
 
 // Cache durations by content type (in seconds)
 const CACHE_DURATIONS: Record<string, number> = {
@@ -27,8 +28,7 @@ export async function GET(
   request: NextRequest,
   { params }: { params: Promise<{ path: string[] }> }
 ) {
-  // Check if ISR mode is enabled
-  if (process.env.ISR_MODE !== 'true') {
+  if (!isIsrMode()) {
     return new NextResponse('Asset serving only available in ISR mode', {
       status: 404,
     });

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

@@ -23,6 +23,7 @@
 import { NextRequest } from 'next/server';
 import { querySimilarChunks } from '@/lib/vector-store';
 import { buildSystemPrompt, isCannedIdentityReply, resolveSiteName } from '@/lib/chat-prompt';
+import { stripHedge, isHedgeReply } from '@/lib/hedge-strip';
 import { getDocsPath, getBaseUrl, trackChatAnalytics } from '@/lib/route-helpers';
 import { getAnthropicClient } from '@/lib/anthropic-client';
 import { rewriteQueryForSearch } from '@/lib/query-rewriter';
@@ -38,6 +39,9 @@ const CHAT_MODEL = 'claude-haiku-4-5-20251001';
 const RATE_LIMIT = 10;
 const RATE_WINDOW_SECONDS = 60;
 const MAX_HISTORY = 10;
+/** Messages shorter than this with prior history are treated as follow-ups.
+ *  Used both for searchQuery enrichment and to skip the rewriter. */
+const SHORT_FOLLOWUP_LEN = 60;
 const VALID_ROLES = new Set<string>(['user', 'assistant']);
 
 export async function POST(
@@ -93,11 +97,12 @@ export async function POST(
     })
     .map((h) => ({ role: h.role, content: h.content.slice(0, 4000) }));
 
-  // Enrich short messages with conversation context for better vector search.
-  // When user picks a clarification option (e.g., "Post Analytics"), the message
-  // alone is too short for good retrieval. Combine with the preceding question.
+  const isShortFollowUp = message.length < SHORT_FOLLOWUP_LEN && history.length > 0;
+
+  // When a user picks a clarification option (e.g. "Post Analytics"), the
+  // message alone is too short for good retrieval — combine with the prior turn.
   let searchQuery = message;
-  if (message.length < 60 && history.length > 0) {
+  if (isShortFollowUp) {
     const prevUserMsg = [...history].reverse().find(
       h => h.role === 'user' && h.content !== message,
     );
@@ -127,16 +132,21 @@ export async function POST(
   // original query still returns results so chat doesn't fail.
   const originalQueryPromise = querySimilarChunks(project, searchQuery, 15);
 
+  // Skipping the rewriter on short follow-ups avoids 500-2000ms of serial
+  // Anthropic latency — `searchQuery` above is already enriched with prior-turn
+  // context using the same threshold, so the rewrite has no retrieval benefit.
   const rewrittenPathPromise: Promise<Awaited<ReturnType<typeof querySimilarChunks>>> =
-    rewriteQueryForSearch(message, history)
-      .catch(() => null)
-      .then(rewritten => {
-        // Compare against `message` (the rewriter's input), not `searchQuery`
-        // (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(() => []);
-      });
+    isShortFollowUp
+      ? Promise.resolve([])
+      : rewriteQueryForSearch(message, history)
+          .catch(() => null)
+          .then(rewritten => {
+            // Compare against `message` (the rewriter's input), not `searchQuery`
+            // (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(() => []);
+          });
 
   let originalChunks: Awaited<ReturnType<typeof querySimilarChunks>>;
   let rewrittenChunks: Awaited<ReturnType<typeof querySimilarChunks>>;
@@ -228,23 +238,53 @@ export async function POST(
       let emittedMarkdownLength = 0;
       let emittedQuestionLength = 0;
 
-      stream.on('inputJson', (_partialJson, jsonSnapshot) => {
-        if (!jsonSnapshot || typeof jsonSnapshot !== 'object') return;
+      // Incrementally extract a still-open string field from partial tool_use JSON.
+      // The SDK's jsonSnapshot only exposes a field once its string literal closes,
+      // so a ~1000-char answer lands in one snapshot update and the client sees it
+      // in one flash. Instead, accumulate the raw partial_json and close the string
+      // + object ourselves to read the in-progress value.
+      let accumulatedJson = '';
+      function extractPartialString(field: 'markdown' | 'question'): string | null {
+        // A trailing odd number of backslashes means we're mid-escape. Appending
+        // `"}` would turn `\` into `\"` — a valid escaped quote — producing a
+        // bogus literal `"` in the extracted string that gets streamed as text.
+        const trailing = accumulatedJson.match(/\\+$/)?.[0].length ?? 0;
+        if (trailing % 2 !== 0) return null;
+        try {
+          const parsed = JSON.parse(accumulatedJson + '"}') as Record<string, unknown>;
+          const value = parsed[field];
+          return typeof value === 'string' ? value : null;
+        } catch {
+          return null;
+        }
+      }
+
+      stream.on('inputJson', (partialJson, jsonSnapshot) => {
+        accumulatedJson += typeof partialJson === 'string' ? partialJson : '';
 
         // Gate on toolName — emitting before content_block_start resolves
         // would leak clarification JSON into the answer text channel.
         if (toolName === 'answer') {
-          const snap = jsonSnapshot as AnswerInput;
-          if (typeof snap.markdown === 'string' && snap.markdown.length > emittedMarkdownLength) {
-            const newContent = snap.markdown.slice(emittedMarkdownLength);
-            emittedMarkdownLength = snap.markdown.length;
-            controller.enqueue(sendEvent({ type: 'text', content: newContent }));
+          const snap = jsonSnapshot as AnswerInput | null | undefined;
+          const md = typeof snap?.markdown === 'string'
+            ? snap.markdown
+            : extractPartialString('markdown');
+          if (md !== null) {
+            const trimmed = stripHedge(md);
+            if (trimmed.length > emittedMarkdownLength) {
+              const newContent = trimmed.slice(emittedMarkdownLength);
+              emittedMarkdownLength = trimmed.length;
+              controller.enqueue(sendEvent({ type: 'text', content: newContent }));
+            }
           }
         } else if (toolName === 'ask_clarification') {
-          const snap = jsonSnapshot as ClarificationInput;
-          if (typeof snap.question === 'string' && snap.question.length > emittedQuestionLength) {
-            const newContent = snap.question.slice(emittedQuestionLength);
-            emittedQuestionLength = snap.question.length;
+          const snap = jsonSnapshot as ClarificationInput | null | undefined;
+          const q = typeof snap?.question === 'string'
+            ? snap.question
+            : extractPartialString('question');
+          if (q !== null && q.length > emittedQuestionLength) {
+            const newContent = q.slice(emittedQuestionLength);
+            emittedQuestionLength = q.length;
             controller.enqueue(sendEvent({ type: 'text', content: newContent }));
           }
         }
@@ -275,15 +315,17 @@ export async function POST(
         if (toolUse.name === 'answer') {
           const input = toolUse.input as AnswerInput;
           const slugs = Array.isArray(input.cited_page_slugs) ? input.cited_page_slugs : [];
-          const markdownText = typeof input.markdown === 'string' ? input.markdown : '';
-          // Suppress citations on the canned identity reply — otherwise the
-          // top-2 fallback would attach unrelated docs under "I'm the
-          // documentation assistant for …".
-          const isIdentityReply = isCannedIdentityReply(markdownText, siteName);
+          const rawMarkdown = typeof input.markdown === 'string' ? input.markdown : '';
+          const markdownText = stripHedge(rawMarkdown);
+          // Suppress citations on identity + hedge replies — the top-2 fallback
+          // would otherwise attach unrelated docs under "I'm the documentation
+          // assistant…" or under "I don't have information…".
+          const suppressCitations =
+            isCannedIdentityReply(markdownText, siteName) || isHedgeReply(rawMarkdown);
 
           const seen = new Set<string>();
           const explicitSources: Citation[] = [];
-          if (!isIdentityReply) {
+          if (!suppressCitations) {
             for (const slug of slugs) {
               const chunk = chunks.find(c => c.pageSlug === slug);
               if (chunk && !seen.has(chunk.pageSlug)) {
@@ -296,10 +338,8 @@ export async function POST(
               }
             }
           }
-          // Identity replies set hadExplicitCitations=true to mark intentional
-          // no-cite; non-identity answers fall back to top-2 when Claude omits slugs.
-          hadExplicitCitations = isIdentityReply || explicitSources.length > 0;
-          sources = isIdentityReply
+          hadExplicitCitations = suppressCitations || explicitSources.length > 0;
+          sources = suppressCitations
             ? []
             : explicitSources.length > 0
               ? explicitSources
@@ -354,8 +394,9 @@ export async function POST(
   return new Response(readable, {
     headers: {
       'Content-Type': 'text/event-stream',
-      'Cache-Control': 'no-cache',
+      'Cache-Control': 'no-cache, no-transform',
       'Connection': 'keep-alive',
+      'X-Accel-Buffering': 'no',
     },
   });
 }

package/vendored/app/api/isr-health/route.ts

@@ -9,6 +9,7 @@ import { NextResponse } from 'next/server';
 import { getConfigCacheSize } from '@/lib/r2-content';
 import { getSnippetCacheSize } from '@/lib/snippet-compiler-isr';
 import { getOpenApiCacheSize } from '@/lib/openapi-isr';
+import { isIsrMode } from '@/lib/page-isr-helpers';
 
 interface HealthCheck {
   status: 'ok' | 'degraded' | 'unhealthy';
@@ -31,8 +32,6 @@ interface HealthCheck {
 const startTime = Date.now();
 
 export async function GET() {
-  const isIsrMode = process.env.ISR_MODE === 'true';
-
   // Memory usage
   const memUsage = process.memoryUsage();
   const memory = {
@@ -54,7 +53,7 @@ export async function GET() {
     memory,
     uptime: Math.round((Date.now() - startTime) / 1000),
     timestamp: new Date().toISOString(),
-    isrMode: isIsrMode,
+    isrMode: isIsrMode(),
   };
 
   return NextResponse.json(health, {

package/vendored/app/layout.tsx

@@ -7,6 +7,7 @@ import { LayoutWrapper } from '@/components/layout/LayoutWrapper';
 import { CodeBlockCopyButton } from '@/components/CodeBlockCopyButton';
 import { HeaderLinkCopy } from '@/components/HeaderLinkCopy';
 import { FontAwesomeLoader } from '@/components/FontAwesomeLoader';
+import { JdReadySentinel } from '@/components/JdReadySentinel';
 import { FA_CSS_HREF } from '@/lib/font-awesome';
 import { getDocsConfig } from '@/lib/docs';
 import { getDocsConfig as getIsrDocsConfig } from '@/lib/docs-isr';
@@ -580,6 +581,7 @@ export default async function RootLayout({
         {config.integrations?.ga4?.measurementId && (
           <ConditionalGA gaId={config.integrations.ga4.measurementId} />
         )}
+        <JdReadySentinel />
       </body>
     </html>
   );

package/vendored/components/JdReadySentinel.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { useEffect } from 'react';
+
+/**
+ * Sets document.body.dataset.jdReady = 'true' after window.load so the
+ * pdf-service (and any future browser automation) can wait on a reliable
+ * signal that the page is fully rendered and resources have settled.
+ */
+export function JdReadySentinel(): null {
+  useEffect(() => {
+    const mark = () => {
+      document.body.dataset.jdReady = 'true';
+    };
+    if (document.readyState === 'complete') {
+      mark();
+    } else {
+      window.addEventListener('load', mark, { once: true });
+    }
+    // removeEventListener with an unregistered listener is a no-op, so the
+    // cleanup is safe whether or not the branch above registered it.
+    return () => window.removeEventListener('load', mark);
+  }, []);
+  return null;
+}

package/vendored/components/navigation/Breadcrumb.tsx

@@ -267,7 +267,7 @@ export function Breadcrumb({ slug, config }: BreadcrumbProps) {
       {/* Home link */}
       <Link
         href={homeLink}
-        prefetch={false}
+        prefetch={true}
         className="text-[var(--color-marker)] hover:text-[var(--color-text-primary)] transition-colors flex items-center"
         aria-label="Home"
       >
@@ -284,7 +284,7 @@ export function Breadcrumb({ slug, config }: BreadcrumbProps) {
           ) : item.path ? (
             <Link
               href={`${linkPrefix}/${item.path}`}
-              prefetch={false}
+              prefetch={true}
               className="text-[var(--color-marker)] hover:text-[var(--color-text-primary)] transition-colors"
             >
               {item.label}