@karmaniverous/jeeves-server 3.0.0-0

package/client/src/components/DirectoryRow.tsx

@@ -0,0 +1,62 @@
+import { FileText, FolderOpen } from 'lucide-react';
+import { Link } from 'react-router-dom';
+
+import { DownloadDropdown } from '@/components/DownloadDropdown';
+import { LinkDropdown } from '@/components/LinkDropdown';
+import type { DirectoryEntry, ShareSettings } from '@/lib/api';
+
+function formatSize(bytes: number | null): string {
+  if (bytes === null) return '-';
+  if (bytes === 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const val = bytes / Math.pow(1024, i);
+  return `${val < 10 ? val.toFixed(1) : Math.round(val)} ${units[i]}`;
+}
+
+interface DirectoryRowProps {
+  entry: DirectoryEntry;
+  basePath: string;
+  isInsider: boolean;
+  shareSettings: ShareSettings;
+  onShareSettingsChange: (settings: ShareSettings) => void;
+}
+
+export function DirectoryRow({ entry, basePath, isInsider, shareSettings, onShareSettingsChange }: DirectoryRowProps) {
+  const entryPath = basePath ? `${basePath}/${entry.name}` : entry.name;
+  const isDir = entry.type === 'directory';
+  const hasRaw = !isDir;
+  const urlPath = `/${entryPath}`;
+  const typeLabel = isDir ? 'Directory' : entry.ext ? entry.ext.slice(1).toUpperCase() : 'File';
+
+  return (
+    <tr className="border-b border-border last:border-0 hover:bg-accent/50 transition-colors">
+      <td className="px-4 py-2.5">
+        <div className="flex items-center gap-2">
+          <Link
+            to={`/browse/${entryPath}`}
+            className="text-blue-500 hover:underline flex items-center gap-2 min-w-0"
+          >
+            {isDir ? <FolderOpen className="h-4 w-4 text-yellow-500 shrink-0" /> : <FileText className="h-4 w-4 text-zinc-400 shrink-0" />}
+            <span className="truncate">{entry.name}</span>
+          </Link>
+          {isInsider && (
+            <div className="ml-auto flex items-center gap-0.5 shrink-0">
+              <LinkDropdown path={urlPath} shareSettings={shareSettings} onShareSettingsChange={onShareSettingsChange} showRaw={hasRaw} compact isDirectory={isDir} />
+              <DownloadDropdown
+                reqPath={entryPath}
+                file={isDir ? null : { fileName: entry.name, type: entry.ext }}
+                isDirectory={isDir}
+                isInsider={isInsider}
+                compact
+              />
+            </div>
+          )}
+        </div>
+      </td>
+      <td className="px-4 py-2.5 text-muted-foreground text-sm">{typeLabel}</td>
+      <td className="px-4 py-2.5 text-muted-foreground text-sm">{formatSize(entry.size)}</td>
+      <td className="px-4 py-2.5 text-muted-foreground text-sm">{entry.mtime ?? '-'}</td>
+    </tr>
+  );
+}

package/client/src/components/DirectoryTable.tsx

@@ -0,0 +1,42 @@
+import { DirectoryRow } from '@/components/DirectoryRow';
+import type { DirectoryEntry, ShareSettings } from '@/lib/api';
+
+interface DirectoryTableProps {
+  entries: DirectoryEntry[];
+  basePath: string;
+  isInsider: boolean;
+  shareSettings: ShareSettings;
+  onShareSettingsChange: (settings: ShareSettings) => void;
+}
+
+export function DirectoryTable({ entries, basePath, isInsider, shareSettings, onShareSettingsChange }: DirectoryTableProps) {
+  return (
+    <div>
+      <p className="text-muted-foreground text-sm mb-4">{entries.length} items</p>
+      <div className="bg-muted/50 rounded-lg overflow-hidden border border-border">
+        <table className="w-full">
+          <thead>
+            <tr className="border-b border-border">
+              <th className="text-left px-4 py-2.5 text-xs font-semibold text-muted-foreground uppercase tracking-wider">Name</th>
+              <th className="text-left px-4 py-2.5 text-xs font-semibold text-muted-foreground uppercase tracking-wider">Type</th>
+              <th className="text-left px-4 py-2.5 text-xs font-semibold text-muted-foreground uppercase tracking-wider">Size</th>
+              <th className="text-left px-4 py-2.5 text-xs font-semibold text-muted-foreground uppercase tracking-wider">Modified</th>
+            </tr>
+          </thead>
+          <tbody>
+            {entries.map((entry) => (
+              <DirectoryRow
+                key={entry.name}
+                entry={entry}
+                basePath={basePath}
+                isInsider={isInsider}
+                shareSettings={shareSettings}
+                onShareSettingsChange={onShareSettingsChange}
+              />
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}

package/client/src/components/DownloadDropdown.tsx

@@ -0,0 +1,116 @@
+import { CloudDownload } from 'lucide-react';
+
+import { DropdownMenuSeparator, DropdownMenuItem } from '@/components/ui/dropdown-menu';
+import { ActionDropdown, DropdownErrorBanner, type ActionState } from '@/components/ActionDropdown';
+import { useActionState } from '@/components/useActionState';
+import { clearCache, withKey } from '@/lib/api';
+
+interface DownloadDropdownProps {
+  reqPath: string;
+  file: { fileName: string; type: string } | null;
+  isDirectory?: boolean;
+  isInsider?: boolean;
+  compact?: boolean;
+  variant?: 'header' | 'default' | 'menuItem';
+  onError?: (error: string) => void;
+  onStateChange?: (state: ActionState) => void;
+}
+
+interface DownloadItem {
+  label: string;
+  href: string;
+  filename: string;
+}
+
+function getDownloadItems(reqPath: string, file: { fileName: string; type: string } | null, isDirectory?: boolean): DownloadItem[] {
+  const items: DownloadItem[] = [];
+
+  if (isDirectory || !file) {
+    items.push({ label: 'ZIP', href: `/api/export/${reqPath}?format=zip`, filename: `${reqPath.split('/').pop() ?? 'archive'}.zip` });
+    return items;
+  }
+
+  const baseName = file.fileName.replace(/\.[^.]+$/, '');
+  items.push({ label: 'Raw', href: `/api/raw/${reqPath}`, filename: file.fileName });
+
+  if (file.type === 'markdown' || file.type === '.md') {
+    items.push({ label: 'PDF', href: `/api/export/${reqPath}?format=pdf`, filename: `${baseName}.pdf` });
+    items.push({ label: 'DOCX', href: `/api/export/${reqPath}?format=docx`, filename: `${baseName}.docx` });
+  }
+
+  if (file.type === 'mermaid' || file.type === '.mmd') {
+    items.push({ label: 'SVG', href: `/api/mermaid-export/${reqPath}?format=svg`, filename: `${baseName}.svg` });
+    items.push({ label: 'PNG', href: `/api/mermaid-export/${reqPath}?format=png`, filename: `${baseName}.png` });
+    items.push({ label: 'PDF', href: `/api/mermaid-export/${reqPath}?format=pdf`, filename: `${baseName}.pdf` });
+  }
+
+  if (file.type === 'plantuml' || ['.puml', '.plantuml', '.pu'].includes(file.type)) {
+    items.push({ label: 'SVG', href: `/api/plantuml-export/${reqPath}?format=svg`, filename: `${baseName}.svg` });
+    items.push({ label: 'PNG', href: `/api/plantuml-export/${reqPath}?format=png`, filename: `${baseName}.png` });
+    items.push({ label: 'PDF', href: `/api/plantuml-export/${reqPath}?format=pdf`, filename: `${baseName}.pdf` });
+    items.push({ label: 'EPS', href: `/api/plantuml-export/${reqPath}?format=eps`, filename: `${baseName}.eps` });
+  }
+
+  return items;
+}
+
+async function downloadBlob(href: string, filename: string) {
+  const res = await fetch(withKey(href), { credentials: 'include' });
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(body || `Download failed (${String(res.status)})`);
+  }
+  const blob = await res.blob();
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+}
+
+export function DownloadDropdown({ reqPath, file, isDirectory, isInsider, compact, variant = 'default', onError, onStateChange }: DownloadDropdownProps) {
+  const { state, errorMsg, handleAction, resetOnClose } = useActionState(
+    (msg) => { onError?.(msg); alert(`Download failed: ${msg}`); },
+    onStateChange,
+  );
+  const items = getDownloadItems(reqPath, file, isDirectory);
+
+  if (items.length === 0) return null;
+
+  return (
+    <ActionDropdown
+      icon={CloudDownload}
+      label="Download"
+      title="Download"
+      variant={variant}
+      compact={compact}
+      state={state}
+      onOpenChange={resetOnClose}
+      errorSlot={<DropdownErrorBanner message={errorMsg} />}
+    >
+      {items.map((item) => (
+        <DropdownMenuItem
+          key={item.label}
+          onSelect={() => void handleAction(() => downloadBlob(item.href, item.filename))}
+          className="cursor-pointer"
+        >
+          {item.label}
+        </DropdownMenuItem>
+      ))}
+      {isInsider && !isDirectory && (
+        <>
+          <DropdownMenuSeparator />
+          <DropdownMenuItem
+            onSelect={() => void handleAction(async () => { await clearCache(reqPath); })}
+            className="cursor-pointer text-muted-foreground"
+          >
+            Clear Cache
+          </DropdownMenuItem>
+        </>
+      )}
+    </ActionDropdown>
+  );
+}

package/client/src/components/DriveList.tsx

@@ -0,0 +1,54 @@
+import { Link } from 'react-router-dom';
+
+import { LinkDropdown } from '@/components/LinkDropdown';
+import type { DriveEntry, ShareSettings } from '@/lib/api';
+
+interface DriveListProps {
+  drives: DriveEntry[];
+  isInsider: boolean;
+  shareSettings: ShareSettings;
+  onShareSettingsChange: (settings: ShareSettings) => void;
+}
+
+export function DriveList({ drives, isInsider, shareSettings, onShareSettingsChange }: DriveListProps) {
+  return (
+    <div>
+      <p className="text-muted-foreground text-sm mb-4">{drives.length} drives</p>
+      <div className="bg-muted/50 rounded-lg overflow-hidden border border-border">
+        <table className="w-full">
+          <thead>
+            <tr className="border-b border-border">
+              <th className="text-left px-4 py-2.5 text-xs font-semibold text-muted-foreground uppercase tracking-wider">Name</th>
+              <th className="text-left px-4 py-2.5 text-xs font-semibold text-muted-foreground uppercase tracking-wider">Type</th>
+            </tr>
+          </thead>
+          <tbody>
+            {drives.map((drive) => {
+              const drivePath = `/${drive.letter.toLowerCase()}`;
+              return (
+                <tr key={drive.letter} className="border-b border-border last:border-0 hover:bg-accent/50 transition-colors">
+                  <td className="px-4 py-2.5">
+                    <div className="flex items-center gap-2">
+                      <Link
+                        to={`/browse/${drive.letter.toLowerCase()}`}
+                        className="text-blue-500 hover:underline flex items-center gap-2 min-w-0"
+                      >
+                        💾 {drive.letter}:\{drive.label ? ` (${drive.label})` : ''}
+                      </Link>
+                      {isInsider && (
+                        <div className="ml-auto flex items-center gap-0.5 shrink-0">
+                          <LinkDropdown path={drivePath} shareSettings={shareSettings} onShareSettingsChange={onShareSettingsChange} compact isDirectory />
+                        </div>
+                      )}
+                    </div>
+                  </td>
+                  <td className="px-4 py-2.5 text-muted-foreground text-sm">Drive</td>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}

package/client/src/components/EmbeddedDiagramPanzoom.ts

@@ -0,0 +1,28 @@
+/**
+ * Add Panzoom to embedded diagram SVGs rendered server-side in markdown.
+ *
+ * Finds .embedded-diagram-rendered containers with inline <svg> elements
+ * and wraps them with Panzoom for wheel-zoom and drag-pan.
+ */
+import { createPanzoomWrapper } from './panzoom';
+
+export function initEmbeddedDiagramPanzoom(article: HTMLElement): () => void {
+  const cleanups: (() => void)[] = [];
+
+  const containers = article.querySelectorAll<HTMLDivElement>('.embedded-diagram-rendered');
+
+  for (const container of containers) {
+    const svg = container.querySelector('svg');
+    if (!svg) continue;
+
+    const { wrapper, initPanzoom, cleanup } = createPanzoomWrapper(svg, container, {
+      wrapperExtraClass: 'embedded-diagram-panzoom',
+    });
+
+    container.replaceWith(wrapper);
+    initPanzoom();
+    cleanups.push(cleanup);
+  }
+
+  return () => { for (const cleanup of cleanups) cleanup(); };
+}

package/client/src/components/FileContentView.tsx

@@ -0,0 +1,155 @@
+/**
+ * Dispatches to the correct viewer based on file type.
+ */
+import { Loader2 } from 'lucide-react';
+import { useRef } from 'react';
+import { lazy, Suspense, useEffect } from 'react';
+
+const CodeEditor = lazy(() => import('@/components/CodeEditor').then(m => ({ default: m.CodeEditor })));
+const CodeViewer = lazy(() => import('@/components/CodeViewer').then(m => ({ default: m.CodeViewer })));
+import { MermaidViewer } from '@/components/MermaidViewer';
+import { PlantUmlViewer } from '@/components/PlantUmlViewer';
+import { SvgViewer } from '@/components/SvgViewer';
+import { MarkdownView } from '@/components/MarkdownView';
+import { scrollToIdInContainer } from '@/components/scrollUtils';
+import { isRenderable } from '@/components/renderableUtils';
+import { useScrollAnchor } from '@/hooks/useScrollAnchor';
+import type { FileContent } from '@/lib/api';
+
+interface FileContentViewProps {
+  reqPath: string;
+  file: FileContent | null;
+  fileRaw: FileContent | null;
+  fileRendered: FileContent | null;
+  viewTab: 'rendered' | 'raw';
+  editing: boolean;
+  setEditing: (editing: boolean) => void;
+  proseWidth: 'narrow' | 'medium' | 'wide';
+  topBarHeight: number;
+  mainRef: React.RefObject<HTMLElement | null>;
+  mobileTocOpen: boolean;
+  setMobileTocOpen: (open: boolean) => void;
+  onSave: (content: string) => Promise<void>;
+  loading: boolean;
+}
+
+export function FileContentView({
+  reqPath, file, fileRaw, fileRendered, viewTab,
+  editing, setEditing,
+  proseWidth, topBarHeight, mainRef,
+  mobileTocOpen, setMobileTocOpen,
+  onSave,
+}: FileContentViewProps) {
+  const contentRef = useRef<HTMLDivElement>(null);
+  useScrollAnchor(mainRef, contentRef);
+  const renderable = file ? isRenderable(file) : false;
+  const activeTab = renderable ? viewTab : 'raw';
+  const fileLoading = !file;
+
+  // Scroll to hash on file load
+  useEffect(() => {
+    const hash = window.location.hash.slice(1);
+    if (hash && file) {
+      const timer = setTimeout(() => scrollToIdInContainer(mainRef.current, hash), 100);
+      return () => clearTimeout(timer);
+    }
+  }, [file, mainRef]);
+
+  return (
+    <div ref={contentRef} className="px-4 md:px-6 pt-4">
+      {/* Loading state */}
+      {fileLoading && (
+        <div className="flex items-center gap-2 text-muted-foreground text-sm py-8 justify-center">
+          <Loader2 className="h-4 w-4 animate-spin" /> Loading...
+        </div>
+      )}
+
+      {/* Raw view */}
+      {(fileRaw ?? file)?.content && activeTab === 'raw' && !editing && (
+        <Suspense fallback={
+          <pre className="rounded-lg overflow-x-auto text-sm border border-border p-4 bg-muted text-foreground">
+            <code>{(fileRaw ?? file)!.content!.slice(0, 500)}…</code>
+          </pre>
+        }>
+          <CodeViewer
+            content={(fileRaw ?? file)!.content!}
+            fileName={(fileRaw ?? file)!.fileName}
+          />
+        </Suspense>
+      )}
+
+      {/* Editor */}
+      {editing && (fileRaw ?? file)?.content != null && activeTab === 'raw' && (
+        <Suspense fallback={
+          <div className="flex items-center gap-2 text-muted-foreground text-sm py-8 justify-center">
+            <Loader2 className="h-4 w-4 animate-spin" /> Loading editor…
+          </div>
+        }>
+          <div style={{ height: `calc(100vh - ${topBarHeight + 16}px)` }}>
+            <CodeEditor
+              content={(fileRaw ?? file)!.content!}
+              fileName={(fileRaw ?? file)!.fileName}
+              onSave={onSave}
+              onCancel={() => setEditing(false)}
+            />
+          </div>
+        </Suspense>
+      )}
+
+      {/* Rendering spinner */}
+      {!fileRendered && renderable && activeTab === 'rendered' && !fileLoading && (
+        <div className="flex items-center gap-2 text-muted-foreground text-sm py-8 justify-center">
+          <Loader2 className="h-4 w-4 animate-spin" /> Rendering...
+        </div>
+      )}
+
+      {/* Markdown */}
+      {fileRendered?.type === 'markdown' && fileRendered.html && activeTab === 'rendered' && (
+        <MarkdownView
+          fileRendered={fileRendered}
+          proseWidth={proseWidth}
+          topBarHeight={topBarHeight}
+          mainRef={mainRef}
+          mobileTocOpen={mobileTocOpen}
+          setMobileTocOpen={setMobileTocOpen}
+        />
+      )}
+
+      {/* SVG */}
+      {fileRendered?.type === 'svg' && fileRendered.content && activeTab === 'rendered' && (
+        <SvgViewer content={fileRendered.content} />
+      )}
+
+      {/* Mermaid */}
+      {fileRendered?.type === 'mermaid' && activeTab === 'rendered' && (
+        <MermaidViewer html={fileRendered.html ?? null} content={fileRendered.content ?? ''} />
+      )}
+
+      {/* PlantUML */}
+      {fileRendered?.type === 'plantuml' && activeTab === 'rendered' && (
+        <PlantUmlViewer html={fileRendered.html ?? null} content={fileRendered.content ?? ''} />
+      )}
+
+      {/* Image */}
+      {file?.type === 'image' && (
+        <div className="flex justify-center p-4">
+          <img src={`/api/raw/${reqPath}`} alt={file.fileName} className="max-w-full rounded-lg shadow-md" />
+        </div>
+      )}
+
+      {/* Binary download */}
+      {file?.type === 'binary' && (
+        <div className="text-center p-8">
+          <p className="text-muted-foreground mb-4">{file.fileName}</p>
+          <a
+            href={`/api/raw/${reqPath}`}
+            download={file.fileName}
+            className="inline-flex items-center gap-2 px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90"
+          >
+            Download
+          </a>
+        </div>
+      )}
+    </div>
+  );
+}

package/client/src/components/InlineSvgPanzoom.ts

@@ -0,0 +1,60 @@
+/**
+ * Post-processes a rendered markdown article to add Panzoom to embedded SVG images.
+ *
+ * Finds <img> elements with .svg sources, fetches the SVG content,
+ * and replaces them with interactive Panzoom containers with fullscreen support.
+ */
+import { withKey } from '@/lib/api';
+import { createPanzoomWrapper } from './panzoom';
+
+export function initInlineSvgPanzoom(article: HTMLElement): () => void {
+  const cleanups: (() => void)[] = [];
+  const imgs = Array.from(article.querySelectorAll<HTMLImageElement>('img')).filter(
+    (img) => /\.svg(\?|&|$)/i.test(img.getAttribute('src') ?? ''),
+  );
+
+  for (const img of imgs) {
+    const src = img.getAttribute('src');
+    if (!src) continue;
+
+    const rawSrc = src.includes('raw=1') ? src : (src.includes('?') ? `${src}&raw=1` : `${src}?raw=1`);
+
+    // Create a temporary placeholder
+    const placeholder = document.createElement('div');
+    placeholder.className = 'inline-svg-panzoom relative bg-white rounded-lg border border-border overflow-hidden my-4';
+    placeholder.style.cursor = 'grab';
+    placeholder.innerHTML = '<div class="overflow-hidden w-full min-h-[200px]"><div class="flex items-center justify-center p-4">Loading SVG…</div></div>';
+
+    img.parentElement?.replaceChild(placeholder, img);
+
+    // Fetch SVG content and init Panzoom
+    fetch(withKey(rawSrc))
+      .then((r) => {
+        if (!r.ok) throw new Error(`Failed to fetch SVG: ${String(r.status)}`);
+        return r.text();
+      })
+      .then((svgContent) => {
+        const tempDiv = document.createElement('div');
+        tempDiv.innerHTML = svgContent;
+        const svg = tempDiv.querySelector('svg');
+        if (!svg) throw new Error('No SVG element found');
+
+        const { wrapper, initPanzoom, cleanup } = createPanzoomWrapper(svg, placeholder, {
+          wrapperExtraClass: 'inline-svg-panzoom',
+          viewportMinHeight: '200px',
+        });
+
+        placeholder.replaceWith(wrapper);
+        initPanzoom();
+        cleanups.push(cleanup);
+      })
+      .catch(() => {
+        // Fallback: put the img back
+        placeholder.replaceWith(img);
+      });
+  }
+
+  return () => {
+    for (const cleanup of cleanups) cleanup();
+  };
+}

package/client/src/components/LazyDiagram.ts

@@ -0,0 +1,93 @@
+/**
+ * Lazy-load embedded diagrams in markdown.
+ *
+ * Finds .embedded-diagram-lazy placeholders and fetches their rendered SVGs
+ * via /api/diagram/:type/:hash.svg when they scroll into view.
+ * After loading, initializes panzoom on the diagram.
+ */
+import { withKey } from '@/lib/api';
+import { normalizeSvg } from '@/lib/svg';
+import { createPanzoomWrapper } from './panzoom';
+
+/**
+ * Initialize lazy diagram loading for all placeholders in the given article.
+ * Returns a cleanup function.
+ */
+export function initLazyDiagrams(article: HTMLElement): () => void {
+  const cleanups: (() => void)[] = [];
+  const placeholders = article.querySelectorAll<HTMLDivElement>('.embedded-diagram-lazy');
+
+  if (placeholders.length === 0) return () => {};
+
+  for (const placeholder of placeholders) {
+    const type = placeholder.dataset.diagramType ?? 'diagram';
+    placeholder.innerHTML = `<div class="embedded-diagram-loading"><div class="diagram-spinner"></div><span>Rendering ${type} diagram…</span></div>`;
+    void loadDiagram(placeholder, cleanups);
+  }
+
+  return () => { for (const cleanup of cleanups) cleanup(); };
+}
+
+async function loadDiagram(
+  placeholder: HTMLDivElement,
+  cleanups: (() => void)[],
+): Promise<void> {
+  const type = placeholder.dataset.diagramType;
+  const hash = placeholder.dataset.diagramHash;
+  if (!type || !hash) return;
+
+  try {
+    const url = withKey(`/api/diagram/${type}/${hash}.svg`);
+    const resp = await fetch(url);
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({ error: 'Render failed' })) as { error?: string };
+      throw new Error(err.error ?? `HTTP ${String(resp.status)}`);
+    }
+    const svgText = await resp.text();
+
+    // Normalize SVG for responsive display
+    const normalizedSvg = normalizeSvg(svgText);
+
+    const container = document.createElement('div');
+    container.className = 'embedded-diagram-rendered';
+    container.dataset.type = type;
+    container.innerHTML = normalizedSvg;
+
+    const svg = container.querySelector('svg');
+    if (!svg) {
+      placeholder.replaceWith(container);
+      return;
+    }
+
+    // Use shared panzoom wrapper
+    const { wrapper, initPanzoom, cleanup } = createPanzoomWrapper(svg, container, {
+      wrapperExtraClass: 'embedded-diagram-panzoom',
+    });
+
+    placeholder.replaceWith(wrapper);
+    initPanzoom();
+    cleanups.push(cleanup);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Unknown error';
+    const label = type ? type.charAt(0).toUpperCase() + type.slice(1) : 'Diagram';
+    const retries = Number(placeholder.dataset.retryCount ?? '0');
+    const reloadHint = retries > 0
+      ? '<div class="diagram-reload-hint">Still failing? Try reloading the page — the diagram source may have changed.</div>'
+      : '';
+    placeholder.innerHTML = `<div class="embedded-diagram-error" data-type="${type}"><div class="diagram-error-label">${label} render failed: ${escapeHtml(message)}</div>${reloadHint}<button class="diagram-retry-btn">Retry</button></div>`;
+
+    const retryBtn = placeholder.querySelector('.diagram-retry-btn');
+    retryBtn?.addEventListener('click', () => {
+      placeholder.dataset.retryCount = String(retries + 1);
+      placeholder.innerHTML = `<div class="embedded-diagram-loading"><div class="diagram-spinner"></div><span>Rendering ${type} diagram…</span></div>`;
+      void loadDiagram(placeholder, cleanups);
+    });
+  }
+}
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}