jamdesk 1.1.91 → 1.1.93

package/dist/lib/deps.js

@@ -58,7 +58,7 @@ export const REQUIRED_DEPS = {
     'remark-math': '^6.0.0',
     'remark-smartypants': '^3.0.2',
     // Math/LaTeX rendering
-    'katex': '^0.16.45',
+    'katex': '^0.16.46',
     // Diagrams
     'mermaid': '^11.14.0',
     // YAML parsing (for OpenAPI specs)
@@ -88,7 +88,7 @@ export const REQUIRED_DEPS = {
     '@upstash/redis': '^1.37.0',
     // TypeScript (needed for Next.js to avoid auto-install breaking symlink)
     'typescript': '^6.0.3',
-    '@types/node': '^25.6.2',
+    '@types/node': '^25.8.0',
     '@types/react': '^19.2.14',
     '@types/react-dom': '^19.0.0',
     '@next/third-parties': '^16.2.6',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.91",
+  "version": "1.1.93",
   "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",
@@ -120,7 +120,7 @@
   "devDependencies": {
     "@mdx-js/mdx": "^3.1.1",
     "@types/fs-extra": "^11.0.0",
-    "@types/node": "^25.6.2",
+    "@types/node": "^25.8.0",
     "typescript": "^6.0.2",
     "vitest": "^4.1.5"
   },

package/vendored/components/mdx/MermaidInner.tsx

@@ -1,8 +1,65 @@
 'use client';
 
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import mermaid from 'mermaid';
 
+mermaid.initialize({
+  startOnLoad: false,
+  theme: 'neutral', // Works well with both light and dark modes
+  securityLevel: 'strict', // Sanitizes SVG output to prevent XSS
+  gitGraph: {
+    mainBranchName: 'main',
+  },
+});
+
+export const CACHE_KEY_PREFIX = 'mermaid:v1:';
+
+// djb2; collisions are theoretically possible but the input space is tiny for a docs site.
+export function hashDiagram(source: string): string {
+  let h = 5381;
+  for (let i = 0; i < source.length; i++) {
+    h = ((h << 5) + h) ^ source.charCodeAt(i);
+  }
+  return (h >>> 0).toString(36);
+}
+
+export interface CachedDiagram {
+  svg: string;
+  height: number;
+}
+
+export function readCache(source: string): CachedDiagram | null {
+  try {
+    const raw = sessionStorage.getItem(CACHE_KEY_PREFIX + hashDiagram(source));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<CachedDiagram>;
+    if (typeof parsed?.svg !== 'string') return null;
+    // Normalize the shape so the return honestly matches CachedDiagram:
+    // legacy v1 entries predate height tracking, and a tampered/foreign
+    // entry could carry a non-numeric height. Coerce both to a number.
+    return {
+      svg: parsed.svg,
+      height: typeof parsed.height === 'number' ? parsed.height : 0,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeCache(source: string, entry: CachedDiagram): void {
+  try {
+    sessionStorage.setItem(CACHE_KEY_PREFIX + hashDiagram(source), JSON.stringify(entry));
+  } catch {}
+}
+
+// Mermaid always emits a `height` attribute on the root <svg>. Reading it
+// from the markup (rather than getBoundingClientRect) works in jsdom and
+// avoids a forced reflow on the production hot path.
+export function readSvgHeight(svgMarkup: string): number {
+  const match = svgMarkup.match(/<svg\b[^>]*\bheight=["']([\d.]+)(?:px)?["']/i);
+  return match ? parseFloat(match[1]) : 0;
+}
+
 interface MermaidInnerProps {
   children: string;
   className?: string;
@@ -10,7 +67,6 @@ interface MermaidInnerProps {
   minWidth?: string;
 }
 
-// Color palette for theming diagram elements
 interface ColorPalette {
   text: string;
   line: string;
@@ -232,40 +288,70 @@ function applyLightModeCleanup(svgEl: SVGElement): void {
  */
 export function MermaidInner({ children, className, minWidth }: MermaidInnerProps) {
   const containerRef = useRef<HTMLDivElement>(null);
-  const [svg, setSvg] = useState<string>('');
+  const [svg, setSvg] = useState<string>(() => {
+    if (typeof window === 'undefined') return '';
+    return readCache(children)?.svg ?? '';
+  });
   const [error, setError] = useState<string | null>(null);
 
+  // Reserves space so the skeleton → SVG swap doesn't shift layout below it.
+  // Derived from svg (not separate state) so it can't desync. The regex is
+  // cheap (small string, no backtracking).
+  const minHeightPx = useMemo(() => (svg ? readSvgHeight(svg) : 0), [svg]);
+
   useEffect(() => {
-    mermaid.initialize({
-      startOnLoad: false,
-      theme: 'neutral', // Works well with both light and dark modes
-      securityLevel: 'strict', // Sanitizes SVG output to prevent XSS
-      gitGraph: {
-        mainBranchName: 'main',
-      },
-    });
+    let cancelled = false;
+
+    const cached = readCache(children);
+    if (cached) {
+      // Already hydrated from cache via useState initializer on first mount;
+      // on subsequent `children` changes, sync state to the cached value.
+      setSvg(cached.svg);
+      setError(null);
+      // Synchronous path: no async work to cancel, so no cleanup needed.
+      // StrictMode re-invokes this effect, but both setters are idempotent
+      // (state already equals these values), so the repeat is a no-op.
+      return;
+    }
+
+    // Cache miss — clear previous diagram so user sees skeleton/empty
+    // while the new render is in flight, not stale styled markup.
+    setSvg('');
+    setError(null);
 
     const renderDiagram = async () => {
       try {
         if (!children || typeof children !== 'string') {
-          setError('Invalid diagram content');
+          if (!cancelled) setError('Invalid diagram content');
           return;
         }
         // Generate unique ID for each render to avoid conflicts with React StrictMode
         const uniqueId = `mermaid-${Math.random().toString(36).substring(2, 11)}`;
         const { svg: renderedSvg } = await mermaid.render(uniqueId, children.trim());
+        // writeCache runs UNGATED — the entry is keyed by source string and is
+        // correct regardless of which `children` the component currently displays.
+        writeCache(children, { svg: renderedSvg, height: readSvgHeight(renderedSvg) });
+        if (cancelled) return;
         setSvg(renderedSvg);
         setError(null);
       } catch (err) {
-        setError(err instanceof Error ? err.message : 'Failed to render diagram');
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : 'Failed to render diagram');
+        }
       }
     };
 
     renderDiagram();
+
+    return () => {
+      cancelled = true;
+    };
   }, [children]);
 
-  // Apply styles to SVG after render for dark mode compatibility
-  useEffect(() => {
+  // Apply styles to SVG after commit, before paint, for dark mode compatibility.
+  // useLayoutEffect — not useEffect — so the theme palette is applied in the same
+  // visual frame as the SVG markup, eliminating an unstyled-SVG flash.
+  useLayoutEffect(() => {
     if (!containerRef.current) return;
 
     const svgEl = containerRef.current.querySelector('svg');
@@ -298,7 +384,7 @@ export function MermaidInner({ children, className, minWidth }: MermaidInnerProp
       applyLightModeStyles();
     }
 
-    // Add class to SVG for potential CSS targeting
+    // CSS hook for global mermaid styling.
     svgEl.classList.add('mermaid-svg');
 
     // Watch for dark mode changes
@@ -336,6 +422,7 @@ export function MermaidInner({ children, className, minWidth }: MermaidInnerProp
     <div
       ref={containerRef}
       className={`mermaid-container my-6 flex justify-center overflow-x-auto ${className || ''}`}
+      style={minHeightPx ? { minHeight: `${minHeightPx}px` } : undefined}
       dangerouslySetInnerHTML={{ __html: svg }}
     />
   );

package/vendored/components/navigation/LanguageSelector.tsx

@@ -14,6 +14,7 @@ import {
   toHreflang,
 } from '@/lib/language-utils';
 import { useLinkPrefix } from '@/lib/link-prefix-context';
+import { useProjectSlug } from '@/lib/project-slug-context';
 import { getUiStrings } from '@/lib/ui-strings';
 
 interface LanguageSelectorProps {
@@ -35,6 +36,7 @@ export function LanguageSelector({
 }: LanguageSelectorProps) {
   const router = useRouter();
   const linkPrefix = useLinkPrefix();
+  const projectSlug = useProjectSlug();
   const pathname = usePathname() ?? '';
   const ui = getUiStrings(extractLanguageFromPath(pathname || '/'));
   const [isOpen, setIsOpen] = useState(false);
@@ -83,7 +85,7 @@ export function LanguageSelector({
   // fight the user's in-session navigation choices (they may have explicitly
   // switched languages this session, which we don't want to revert).
   useEffect(() => {
-    const savedPref = getLanguagePreference();
+    const savedPref = getLanguagePreference(projectSlug);
     if (savedPref && currentLanguage && savedPref !== currentLanguage.code) {
       // Only redirect if on default language URL (no explicit language in path)
       const hasLangInPath = languages.some(
@@ -117,7 +119,7 @@ export function LanguageSelector({
         return;
       }
 
-      saveLanguagePreference(lang.code);
+      saveLanguagePreference(lang.code, projectSlug);
 
       const basePath = transformLanguagePath(
         pathname || '/docs',
@@ -130,7 +132,7 @@ export function LanguageSelector({
       onNavigate(url);
       router.push(url);
     },
-    [isNavigating, currentLanguage?.code, actualDefault, pathname, linkPrefix, router, onNavigate]
+    [isNavigating, currentLanguage?.code, actualDefault, pathname, linkPrefix, router, onNavigate, projectSlug]
   );
 
   // Handle keyboard navigation

package/vendored/lib/language-utils.ts

@@ -419,17 +419,28 @@ export function resolveLocaleWithLoweredSet(
 }
 
 /**
- * localStorage key for language preference
+ * localStorage key prefix for project-scoped language preferences. The actual
+ * key is `${LANGUAGE_STORAGE_KEY_PREFIX}${slug}`. Scoping by project prevents
+ * a `cn` preference saved on Project A from forcing a `/cn/...` redirect on
+ * Project B that only declares `zh-Hans` (would 404).
  */
-export const LANGUAGE_STORAGE_KEY = 'jamdesk-language-preference';
+export const LANGUAGE_STORAGE_KEY_PREFIX = 'jamdesk-language-preference:';
+
+/** Legacy unscoped key — read-once for one-time migration to per-project storage. */
+const LEGACY_LANGUAGE_STORAGE_KEY = 'jamdesk-language-preference';
+
+function storageKey(projectSlug: string): string {
+  return `${LANGUAGE_STORAGE_KEY_PREFIX}${projectSlug}`;
+}
 
 /**
- * Save language preference to localStorage
- * Handles private browsing mode gracefully
+ * Save language preference to localStorage, scoped to project slug.
+ * Handles private browsing mode gracefully.
  */
-export function saveLanguagePreference(code: LanguageCode): void {
+export function saveLanguagePreference(code: LanguageCode, projectSlug: string): void {
+  if (!projectSlug) return;
   try {
-    localStorage.setItem(LANGUAGE_STORAGE_KEY, code);
+    localStorage.setItem(storageKey(projectSlug), code);
   } catch {
     // localStorage not available (private browsing, etc.)
     // Fail silently
@@ -437,15 +448,24 @@ export function saveLanguagePreference(code: LanguageCode): void {
 }
 
 /**
- * Get saved language preference from localStorage
- * Returns undefined if not set or localStorage unavailable
+ * Get saved language preference for a project from localStorage.
+ * Returns undefined if not set or localStorage unavailable.
  */
-export function getLanguagePreference(): LanguageCode | undefined {
+export function getLanguagePreference(projectSlug: string): LanguageCode | undefined {
+  if (!projectSlug) return undefined;
   try {
-    const saved = localStorage.getItem(LANGUAGE_STORAGE_KEY);
+    const saved = localStorage.getItem(storageKey(projectSlug));
     if (saved && isValidLanguageCode(saved)) {
       return saved as LanguageCode;
     }
+    // One-time read of legacy unscoped key — promotes it to the per-project
+    // slot the first time a returning user visits and clears the legacy entry.
+    const legacy = localStorage.getItem(LEGACY_LANGUAGE_STORAGE_KEY);
+    if (legacy && isValidLanguageCode(legacy)) {
+      localStorage.setItem(storageKey(projectSlug), legacy);
+      localStorage.removeItem(LEGACY_LANGUAGE_STORAGE_KEY);
+      return legacy as LanguageCode;
+    }
   } catch {
     // localStorage not available
   }
@@ -453,11 +473,12 @@ export function getLanguagePreference(): LanguageCode | undefined {
 }
 
 /**
- * Clear saved language preference
+ * Clear saved language preference for a project.
  */
-export function clearLanguagePreference(): void {
+export function clearLanguagePreference(projectSlug: string): void {
+  if (!projectSlug) return;
   try {
-    localStorage.removeItem(LANGUAGE_STORAGE_KEY);
+    localStorage.removeItem(storageKey(projectSlug));
   } catch {
     // localStorage not available
   }

package/vendored/lib/seo.ts

@@ -188,7 +188,7 @@ function getLanguagePagePaths(langConfig: LanguageConfig): Set<string> {
  * @param languages - Array of language configurations from docs.json
  * @returns Record of language code to URL for alternates.languages
  */
-function buildHreflangAlternates(
+export function buildHreflangAlternates(
   baseUrl: string,
   pagePath: string,
   languages: LanguageConfig[]

package/vendored/lib/static-artifacts.ts

@@ -5,7 +5,7 @@
  * for ISR projects. These are uploaded to R2 alongside the MDX content.
  */
 
-import type { NavigationConfig } from './docs-types.js';
+import type { NavigationConfig, LanguageConfig } from './docs-types.js';
 import { RECURSE_KEYS } from './enhance-navigation.js';
 import { filterVisibility } from './visibility-filter.js';
 import {
@@ -13,6 +13,7 @@ import {
   resolveLocaleFromPath,
   resolveLocaleWithLoweredSet,
 } from './language-utils.js';
+import { buildHreflangAlternates } from './seo.js';
 
 /**
  * Page metadata for artifact generation.
@@ -44,6 +45,13 @@ export interface SitemapOptions {
   hostAtDocs?: boolean;
   /** Block all crawlers - generates empty sitemap */
   noindex?: boolean;
+  /**
+   * Language configurations from docs.json navigation. When provided, the
+   * sitemap emits `<xhtml:link rel="alternate" hreflang>` siblings per URL
+   * for every language that declares the page — Google's recommended sitemap
+   * localization signal (in addition to in-page hreflang link tags).
+   */
+  languages?: LanguageConfig[];
 }
 
 /**
@@ -53,7 +61,7 @@ export interface SitemapOptions {
  * @returns XML string
  */
 export function generateSitemap(options: SitemapOptions): string {
-  const { baseUrl, pages, hostAtDocs = false, noindex = false } = options;
+  const { baseUrl, pages, hostAtDocs = false, noindex = false, languages } = options;
 
   if (noindex) {
     return `<?xml version="1.0" encoding="UTF-8"?>
@@ -62,6 +70,11 @@ export function generateSitemap(options: SitemapOptions): string {
   }
 
   const urlPrefix = hostAtDocs ? '/docs' : '';
+  const hreflangBaseUrl = hostAtDocs ? `${baseUrl}/docs` : baseUrl;
+  const multiLang = languages && languages.length > 1;
+  const urlsetAttrs = multiLang
+    ? 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml"'
+    : 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"';
 
   const entries = pages
     .filter(p => !p.noindex && !p.hidden)
@@ -70,16 +83,32 @@ export function generateSitemap(options: SitemapOptions): string {
       const lastmod = p.lastModified || new Date().toISOString().split('T')[0];
       const priority = p.path === 'introduction' ? '1.0' : '0.8';
 
+      // Per Google's spec, emit hreflang siblings only when the page has
+      // translations. buildHreflangAlternates already filters to languages
+      // whose navigation declares this page, so we won't point at 404s.
+      let hreflangLinks = '';
+      if (multiLang) {
+        const alternates = buildHreflangAlternates(hreflangBaseUrl, p.path, languages);
+        if (alternates) {
+          hreflangLinks = Object.entries(alternates)
+            .map(
+              ([tag, href]) =>
+                `\n    <xhtml:link rel="alternate" hreflang="${escapeXml(tag)}" href="${escapeXml(href)}"/>`,
+            )
+            .join('');
+        }
+      }
+
       return `  <url>
-    <loc>${url}</loc>
+    <loc>${escapeXml(url)}</loc>
     <lastmod>${lastmod}</lastmod>
     <changefreq>weekly</changefreq>
-    <priority>${priority}</priority>
+    <priority>${priority}</priority>${hreflangLinks}
   </url>`;
     });
 
   return `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<urlset ${urlsetAttrs}>
 ${entries.join('\n')}
 </urlset>`;
 }
@@ -353,6 +382,8 @@ export interface GenerateAllOptions {
   rssPages?: RssPageInfo[];
   /** Pages with full content (for llms-full.txt generation) */
   llmsFullPages?: LlmsFullPageInfo[];
+  /** Language configurations (forwarded to sitemap for hreflang siblings) */
+  languages?: LanguageConfig[];
 }
 
 /**
@@ -374,10 +405,10 @@ export interface GeneratedArtifacts {
  */
 export function generateAllArtifacts(options: GenerateAllOptions): GeneratedArtifacts {
   const {
-    baseUrl, name, description, pages, hostAtDocs, noindex, rssPages, llmsFullPages,
+    baseUrl, name, description, pages, hostAtDocs, noindex, rssPages, llmsFullPages, languages,
   } = options;
 
-  const sitemap = generateSitemap({ baseUrl, pages, hostAtDocs, noindex });
+  const sitemap = generateSitemap({ baseUrl, pages, hostAtDocs, noindex, languages });
   const llmsTxt = generateLlmsTxt({
     name, description, baseUrl, pages, hostAtDocs, noindex,
   });

package/vendored/workspace-package-lock.json

@@ -22,7 +22,7 @@
         "@shikijs/transformers": "^4.0.1",
         "@tailwindcss/postcss": "^4.2.4",
         "@tailwindcss/typography": "^0.5.10",
-        "@types/node": "^25.6.2",
+        "@types/node": "^25.8.0",
         "@types/react": "^19.2.14",
         "@types/react-dom": "^19.0.0",
         "@upstash/redis": "^1.37.0",
@@ -37,7 +37,7 @@
         "gray-matter": "^4.0.3",
         "js-yaml": "^4.1.1",
         "json5": "^2.2.3",
-        "katex": "^0.16.45",
+        "katex": "^0.16.46",
         "lucide-react": "^0.562.0",
         "mermaid": "^11.14.0",
         "next": "^16.2.6",
@@ -2134,9 +2134,9 @@
       }
     },
     "node_modules/baseline-browser-mapping": {
-      "version": "2.10.29",
-      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.29.tgz",
-      "integrity": "sha512-Asa2krT+XTPZINCS+2QcyS8WTkObE77RwkydwF7h6DmnKqbvlalz93m/dnphUyCa6SWSP51VgtEUf2FN+gelFQ==",
+      "version": "2.10.30",
+      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.30.tgz",
+      "integrity": "sha512-xjOFN16Ha1+Rz4nFYKqHU/LSB+gx/Vi3yQLX7r7sAW+Wa+8hhF2h4pvqTrTMc8+WcDBEunnUurr46Jvv0jk3Vg==",
       "license": "Apache-2.0",
       "bin": {
         "baseline-browser-mapping": "dist/cli.cjs"
@@ -2197,9 +2197,9 @@
       "license": "MIT"
     },
     "node_modules/caniuse-lite": {
-      "version": "1.0.30001792",
-      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001792.tgz",
-      "integrity": "sha512-hVLMUZFgR4JJ6ACt1uEESvQN1/dBVqPAKY0hgrV70eN3391K6juAfTjKZLKvOMsx8PxA7gsY1/tLMMTcfFLLpw==",
+      "version": "1.0.30001793",
+      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001793.tgz",
+      "integrity": "sha512-iwSsYWaCOoh26cV8NwNRViHlrfUvYsHDfRVcbtmw0Kg6PJIZZXwMkj1442FYLBGkeUf1juAsU3DTfxW579mrPA==",
       "funding": [
         {
           "type": "opencollective",
@@ -2913,9 +2913,9 @@
       }
     },
     "node_modules/dompurify": {
-      "version": "3.4.3",
-      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.3.tgz",
-      "integrity": "sha512-VVwJidIJcp1hpg2OMXML3ZVRPYSZiq4aX7qBh83BSIpOaRDqI+qxhXjjIWnpzkOXhmp0L81lnoME1mnCc9H48A==",
+      "version": "3.4.4",
+      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.4.tgz",
+      "integrity": "sha512-r8K7KGKEcztXfA/nfabSYB2hg9tDphORJTdf8xprN/luSLGmNhOBN8dm1/SYjqLLet6YUFEXOcrdTuwryp/Bew==",
       "license": "(MPL-2.0 OR Apache-2.0)",
       "optionalDependencies": {
         "@types/trusted-types": "^2.0.7"
@@ -2928,9 +2928,9 @@
       "license": "MIT"
     },
     "node_modules/electron-to-chromium": {
-      "version": "1.5.355",
-      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.355.tgz",
-      "integrity": "sha512-LUPZhKzZPYSPme1jEYohpkA+ybYCJztr1quAdBd7E7h3+VOBVcKkwwtBJu41nrjawrRzfb8mtMfzWozoaK0ZIQ==",
+      "version": "1.5.357",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.357.tgz",
+      "integrity": "sha512-NHlTIQDK8fmVwHwuIzmXYEJ1Ewq3D9wDNc0cWXxDGysP6Pb21giwGNkxiTifyKy/4SoPuN5l6GLP1W9Sv7zB2g==",
       "license": "ISC"
     },
     "node_modules/enhanced-resolve": {
@@ -3739,9 +3739,9 @@
       }
     },
     "node_modules/katex": {
-      "version": "0.16.46",
-      "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.46.tgz",
-      "integrity": "sha512-WHy4Coo+bGZyH7NwJKHkS04YFsFcarWbAEOAC3EMndzdN6VSZqklLLIgfxzyaW9jDoeGYJX9SWbJPKpecox0Uw==",
+      "version": "0.16.47",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.47.tgz",
+      "integrity": "sha512-Eeo8Ys1doU1z+x8AZsPpQu+p/QcZBI5PeOo7QGQdy2x2m0MU/hYagBbGOmXwr5KVbEfVuWv9LpnQWeehogurjg==",
       "funding": [
         "https://opencollective.com/katex",
         "https://github.com/sponsors/katex"