jamdesk 1.1.94 → 1.1.96

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.94",
+  "version": "1.1.96",
   "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",

package/vendored/components/mdx/Mermaid.tsx

@@ -1,26 +1,20 @@
 'use client';
 
 import dynamic from 'next/dynamic';
+import { useMemo, useState } from 'react';
+import { readCachedHeight } from './mermaidCache';
+import { useIsomorphicLayoutEffect } from '../../hooks/useIsomorphicLayoutEffect';
 
-// Skeleton shown during lazy load
-function MermaidSkeleton({ className }: { className?: string }) {
-  return (
-    <div
-      className={`my-6 flex justify-center ${className || ''}`}
-      data-testid="mermaid-skeleton"
-    >
-      <div className="animate-pulse bg-gray-200 dark:bg-gray-700 rounded-lg w-full max-w-xl h-48" />
-    </div>
-  );
-}
+// Neutral floor reserved in the SSR markup itself (present on the browser's
+// first paint, before any JS) so a cache miss / pre-hydration window shows
+// correctly-sized empty space instead of a collapse or a grey pulse. Roughly
+// the prior skeleton footprint; refined to the exact diagram height on a
+// cache hit by the layout effect below.
+const DEFAULT_MERMAID_RESERVE_PX = 192;
 
-// Dynamic import - ssr: false because mermaid requires browser APIs
 const MermaidInner = dynamic(
   () => import('./MermaidInner').then(mod => ({ default: mod.MermaidInner })),
-  {
-    ssr: false,
-    loading: () => <MermaidSkeleton />
-  }
+  { ssr: false, loading: () => null }
 );
 
 interface MermaidProps {
@@ -31,5 +25,46 @@ interface MermaidProps {
 }
 
 export function Mermaid({ children, className, minWidth }: MermaidProps) {
-  return <MermaidInner className={className} minWidth={minWidth}>{children}</MermaidInner>;
+  // Server + first (hydration) render emit the constant default — identical
+  // markup, so no hydration mismatch. The sessionStorage read happens only
+  // in the post-hydration layout effect, never in this initializer.
+  const [reservedPx, setReservedPx] = useState(DEFAULT_MERMAID_RESERVE_PX);
+
+  // Fires once, after the hydration commit, synchronously before that
+  // commit's paint — and BEFORE the MermaidInner chunk has resolved or
+  // injected anything. On a cache hit, refine the reserved space to the
+  // exact diagram height so the SVG paints into already-exact space.
+  // Distinct from the reverted spike: one pre-paint settle before injection,
+  // never a re-render around an already-injected node. minWidth still flows
+  // to MermaidInner unchanged; the wrapper owns height only.
+  useIsomorphicLayoutEffect(() => {
+    const h = readCachedHeight(children);
+    if (h > 0) setReservedPx(h);
+  }, [children]);
+
+  // Stable element identity across reservedPx changes. The pre-paint
+  // setReservedPx above re-renders this wrapper; without this memo that
+  // re-render also re-renders the dynamic MermaidInner, making React
+  // re-commit its raw-HTML injection and discard the DOM that MermaidInner
+  // imperatively themed post-commit. That theming is reapplied only on a
+  // genuine content change, not on this re-commit, so on soft-navigation the
+  // diagram paints raw mermaid "neutral" colors instead of the active theme.
+  // Memoizing the element makes the wrapper own min-height ONLY.
+  // Soundness depends on MermaidInner being a stable reference: the dynamic()
+  // call MUST stay module-scoped (above) — moving it into this component
+  // would memoize an element closed over a stale component identity.
+  const inner = useMemo(
+    () => (
+      <MermaidInner className={className} minWidth={minWidth}>
+        {children}
+      </MermaidInner>
+    ),
+    [children, className, minWidth]
+  );
+
+  return (
+    <div data-testid="mermaid-wrapper" style={{ minHeight: reservedPx }}>
+      {inner}
+    </div>
+  );
 }

package/vendored/components/mdx/MermaidInner.tsx

@@ -2,6 +2,14 @@
 
 import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import mermaid from 'mermaid';
+import {
+  CACHE_KEY_PREFIX,
+  hashDiagram,
+  readCache,
+  writeCache,
+  readSvgHeight,
+  type CachedDiagram,
+} from './mermaidCache';
 
 mermaid.initialize({
   startOnLoad: false,
@@ -12,74 +20,15 @@ mermaid.initialize({
   },
 });
 
-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;
-}
+// readCachedHeight intentionally not re-exported; Mermaid.tsx imports it directly from mermaidCache
+export {
+  CACHE_KEY_PREFIX,
+  hashDiagram,
+  readCache,
+  writeCache,
+  readSvgHeight,
+};
+export type { CachedDiagram };
 
 interface MermaidInnerProps {
   children: string;

package/vendored/components/mdx/mermaidCache.ts

@@ -0,0 +1,75 @@
+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;
+}
+
+// Coarse tamper check, NOT a sanitizer. mermaid's securityLevel:'strict' is
+// the real defense (it sanitizes at render). This only guards the cache-read
+// path, which re-injects stored bytes via React's raw inner-HTML prop without
+// re-sanitizing — so a tampered same-origin sessionStorage entry is rejected
+// here, forcing a fresh re-sanitized render. Catches the obvious signatures
+// only (non-<svg> root, <script>, inline on*= handlers).
+function looksTampered(svg: string): boolean {
+  return (
+    !/^\s*<svg/.test(svg) ||
+    /<script\b/i.test(svg) ||
+    /<[^>]+\son[a-z]+\s*=/i.test(svg)
+  );
+}
+
+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;
+    if (looksTampered(parsed.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 has no `height` attribute (it sizes via viewBox +
+// max-width), so fall back to the viewBox height; an explicit `height` still
+// wins when present (other/older renderers). Markup-parsing instead of
+// getBoundingClientRect keeps this jsdom-safe and reflow-free on the 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;
+}
+
+// Cached pixel height for a diagram, or 0 when not cached. Lets the
+// always-loaded Mermaid.tsx shell refine its reserved space to the exact
+// diagram height before the mermaid chunk loads, without reaching into the
+// cache entry shape itself.
+export function readCachedHeight(source: string): number {
+  return readCache(source)?.height ?? 0;
+}

package/vendored/hooks/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,8 @@
+import { useEffect, useLayoutEffect } from 'react';
+
+// useLayoutEffect on the client (runs after commit, synchronously before
+// paint), useEffect on the server (no-op) — avoids React's SSR warning and
+// keeps the rules-of-hooks lint happy (single named hook, no conditional
+// hook-through-a-variable at the call site).
+export const useIsomorphicLayoutEffect =
+  typeof window !== 'undefined' ? useLayoutEffect : useEffect;