jamdesk 1.1.92 → 1.1.94

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.92",
+  "version": "1.1.94",
   "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,86 @@
 '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;
+    // Defense-in-depth: mermaid sanitizes at render time (securityLevel:
+    // 'strict'), but the cache-read path injects the stored bytes via React's
+    // raw inner-HTML prop without re-sanitizing. A tampered sessionStorage
+    // entry must not be trusted — reject anything that isn't a bare <svg> root
+    // or that carries a <script> or an inline on*= event handler. On rejection
+    // we return null so the caller falls back to a fresh, re-sanitized render.
+    const svg = parsed.svg.trimStart();
+    if (
+      !svg.startsWith('<svg') ||
+      /<script\b/i.test(svg) ||
+      /<[^>]+\son[a-z]+\s*=/i.test(svg)
+    ) {
+      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 {}
+}
+
+// Real mermaid output does NOT carry a `height` attribute — it sizes the root
+// <svg> via `viewBox` + `style="max-width"`. So read the explicit `height`
+// attribute first (covers other renderers / older mermaid), then fall back to
+// the 4th `viewBox` token (its height). Parsing 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 attr = svgMarkup.match(/<svg\b[^>]*\bheight=["']([\d.]+)(?:px)?["']/i);
+  if (attr) return parseFloat(attr[1]);
+  const viewBox = svgMarkup.match(
+    /<svg\b[^>]*\bviewBox=["']\s*[\d.+-]+\s+[\d.+-]+\s+[\d.+-]+\s+([\d.]+)/i
+  );
+  return viewBox ? parseFloat(viewBox[1]) : 0;
+}
+
 interface MermaidInnerProps {
   children: string;
   className?: string;
@@ -10,7 +88,6 @@ interface MermaidInnerProps {
   minWidth?: string;
 }
 
-// Color palette for theming diagram elements
 interface ColorPalette {
   text: string;
   line: string;
@@ -232,40 +309,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 +405,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 +443,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/lib/static-artifacts.ts

@@ -93,14 +93,14 @@ export function generateSitemap(options: SitemapOptions): string {
           hreflangLinks = Object.entries(alternates)
             .map(
               ([tag, href]) =>
-                `\n    <xhtml:link rel="alternate" hreflang="${tag}" href="${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>${hreflangLinks}

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"