jamdesk 1.1.95 → 1.1.97

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.95",
+  "version": "1.1.97",
   "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,29 @@
 'use client';
 
 import dynamic from 'next/dynamic';
+import { useMemo, useRef, 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; a cache hit refines it to the exact diagram
+// height pre-paint, and once the diagram renders the floor is released
+// entirely (see the layout effect below).
+const DEFAULT_MERMAID_RESERVE_PX = 192;
+
+// Sentinel: floor released, MermaidInner's own min-height governs the box.
+const FLOOR_RELEASED_PX = 0;
+
+// A rendered diagram (or the error box) is always taller than this; the empty
+// pre-render container is 0px. Distinguishes "content has painted" from "still
+// reserving the gap" so the floor is released only once it is dead weight.
+const RENDERED_FLOOR_RELEASE_PX = 8;
 
-// 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 +34,74 @@ interface MermaidProps {
 }
 
 export function Mermaid({ children, className, minWidth }: MermaidProps) {
-  return <MermaidInner className={className} minWidth={minWidth}>{children}</MermaidInner>;
+  const wrapperRef = useRef<HTMLDivElement>(null);
+
+  // 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);
+
+  // The reserved min-height only bridges the pre-render gap; it must never
+  // outlive the diagram or it leaves dead space under any diagram shorter
+  // than the floor (the cache-miss path never refines it down).
+  useIsomorphicLayoutEffect(() => {
+    const wrapper = wrapperRef.current;
+
+    // Relies on MermaidInner rendering exactly one HTMLElement root (the
+    // diagram container or the error box); if that contract changes, this
+    // height probe silently targets the wrong node.
+    const releaseIfRendered = (): boolean => {
+      const content = wrapper?.firstElementChild as HTMLElement | null;
+      if (content && content.clientHeight > RENDERED_FLOOR_RELEASE_PX) {
+        setReservedPx(FLOOR_RELEASED_PX);
+        return true;
+      }
+      return false;
+    };
+
+    // Already painted (warm soft-nav: SVG hydrated synchronously from cache) —
+    // the floor is already dead weight, skip the cache refine entirely.
+    if (releaseIfRendered()) return;
+
+    // Not yet painted: cache hit → reserve the exact height pre-paint (zero
+    // shift); cache miss / new diagram → hold the default floor for its gap.
+    const cached = readCachedHeight(children);
+    setReservedPx(cached > 0 ? cached : DEFAULT_MERMAID_RESERVE_PX);
+
+    if (!wrapper || typeof MutationObserver === 'undefined') return;
+    // childList only — no `attributes`: MermaidInner's post-commit style pass
+    // mutates SVG child styles heavily; observing attributes would fire a
+    // callback storm. The SVG-insert is a childList mutation, all we need.
+    const mo = new MutationObserver(() => {
+      if (releaseIfRendered()) mo.disconnect();
+    });
+    mo.observe(wrapper, { childList: true, subtree: true });
+    return () => mo.disconnect();
+  }, [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 ref={wrapperRef} 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,73 +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;
-}
-
-// 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;
-}
+// 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;