@open-agent-toolkit/docs-theme 0.3.34 → 0.3.36

package/README.md

@@ -62,9 +62,15 @@ export function Page({ toc, chart }) {
     `@source '../node_modules/@open-agent-toolkit/docs-theme/dist/**/*.js';`
     to your Tailwind CSS so those theme classes are generated.
 
-`Mermaid` diagrams take their colors from the site's Fumadocs color tokens
-(`--color-fd-*`) in light and dark mode, and open in the same full-screen view
-when clicked.
+`Mermaid` renders Mermaid diagram source with [Pele](https://pele.run), loading
+each diagram type on demand. Diagrams take their colors from the site's
+Fumadocs color tokens (`--color-fd-*`) through Pele's `--pele-*` CSS variables,
+so they follow light and dark mode without re-rendering, and open in the same
+full-screen view when clicked. To recolor diagrams, set the `--color-fd-*`
+tokens: the component sets `--pele-*` inline, which overrides any `--pele-*`
+values in a stylesheet. Equations written as `$$...$$` in labels and messages
+render as MathML through KaTeX, which loads only for diagrams that contain
+them; no KaTeX stylesheet is needed.
 
 ## Docs
 

package/dist/mermaid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../src/mermaid.tsx"],"names":[],"mappings":"AAQA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,YAAY,2CA4D9C"}
+{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../src/mermaid.tsx"],"names":[],"mappings":"AAQA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,YAAY,2CAqD9C"}

package/dist/mermaid.js

@@ -1,27 +1,26 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useTheme } from 'next-themes';
-import { useEffect, useRef, useState } from 'react';
-import { siteMermaidThemeVariables } from './mermaid-theme.js';
+import { useEffect, useId, useRef, useState } from 'react';
+import { sitePeleTheme } from './pele-theme.js';
+import { measureIn, renderChart } from './render-chart.js';
 import { ZoomFrame } from './zoom-frame.js';
 export function Mermaid({ chart }) {
     const containerRef = useRef(null);
-    const [svg, setSvg] = useState('');
-    const { resolvedTheme } = useTheme();
+    const [svg, setSvg] = useState({ inline: '', zoomed: '' });
+    // Unique per instance so the inline and full-screen copies of every diagram
+    // on a page get distinct element IDs (title, desc, markers).
+    const idPrefix = `pele-${useId().replace(/[^\w-]/g, '')}`;
     useEffect(() => {
         let cancelled = false;
         async function render() {
-            const mermaid = (await import('mermaid')).default;
-            const dark = resolvedTheme === 'dark';
-            const themeVariables = siteMermaidThemeVariables(dark);
-            mermaid.initialize({
-                startOnLoad: false,
-                ...(themeVariables
-                    ? { theme: 'base', themeVariables }
-                    : { theme: dark ? 'dark' : 'default' }),
+            const host = containerRef.current;
+            if (!host)
+                return;
+            const rendered = await renderChart(chart, {
+                idPrefix,
+                fontFamily: getComputedStyle(host).fontFamily,
+                measure: measureIn(host),
             });
-            const id = `mermaid-${Math.random().toString(36).slice(2, 9)}`;
-            const { svg: rendered } = await mermaid.render(id, chart);
             if (!cancelled) {
                 setSvg(rendered);
             }
@@ -30,12 +29,10 @@ export function Mermaid({ chart }) {
         return () => {
             cancelled = true;
         };
-    }, [chart, resolvedTheme]);
-    return (_jsx(ZoomFrame, { label: 'Diagram', disabled: !svg, zoomed: _jsx("div", { className: 'mermaid', 
-            // oxlint-disable-next-line react/no-danger -- same trusted SVG as above
-            dangerouslySetInnerHTML: {
-                __html: svg.replace(/<svg\b([^>]*?)\sstyle="[^"]*"/, '<svg$1 style="width:100%;height:auto;max-width:none"'),
-            } }), children: _jsx("div", { ref: containerRef, className: 'mermaid', 
-            // oxlint-disable-next-line react/no-danger -- mermaid renders SVG from trusted chart definitions
-            dangerouslySetInnerHTML: { __html: svg } }) }));
+    }, [chart, idPrefix]);
+    return (_jsx(ZoomFrame, { label: 'Diagram', disabled: !svg.inline, zoomed: _jsx("div", { className: 'mermaid', style: sitePeleTheme, 
+            // oxlint-disable-next-line react/no-danger -- same trusted source as above
+            dangerouslySetInnerHTML: { __html: svg.zoomed } }), children: _jsx("div", { ref: containerRef, className: 'mermaid', style: sitePeleTheme, 
+            // oxlint-disable-next-line react/no-danger -- Pele escapes diagram text and filters links and styles; KaTeX escapes math with trust off
+            dangerouslySetInnerHTML: { __html: svg.inline } }) }));
 }

package/dist/pele-theme.d.ts

@@ -0,0 +1,13 @@
+import type { CSSProperties } from 'react';
+/**
+ * Maps Pele's theme variables to the site's Fumadocs color tokens, so diagrams
+ * follow the docs palette in light and dark mode.
+ *
+ * Applied as inline custom properties on the diagram wrapper, the same way the
+ * other components here reference `--color-fd-*` tokens, so consumers need no
+ * extra stylesheet. Pele's SVG reads `var(--pele-*)` from its ancestors, so a
+ * theme switch recolors diagrams without re-rendering. A token the site does
+ * not define leaves the variable invalid, and Pele falls back to its default.
+ */
+export declare const sitePeleTheme: CSSProperties;
+//# sourceMappingURL=pele-theme.d.ts.map

package/dist/pele-theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pele-theme.d.ts","sourceRoot":"","sources":["../src/pele-theme.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,EASrB,aAAa,CAAC"}

package/dist/pele-theme.js

@@ -0,0 +1,20 @@
+/**
+ * Maps Pele's theme variables to the site's Fumadocs color tokens, so diagrams
+ * follow the docs palette in light and dark mode.
+ *
+ * Applied as inline custom properties on the diagram wrapper, the same way the
+ * other components here reference `--color-fd-*` tokens, so consumers need no
+ * extra stylesheet. Pele's SVG reads `var(--pele-*)` from its ancestors, so a
+ * theme switch recolors diagrams without re-rendering. A token the site does
+ * not define leaves the variable invalid, and Pele falls back to its default.
+ */
+export const sitePeleTheme = {
+    '--pele-bg': 'var(--color-fd-card)',
+    '--pele-fg': 'var(--color-fd-foreground)',
+    '--pele-muted': 'var(--color-fd-muted-foreground)',
+    '--pele-line': 'var(--color-fd-muted-foreground)',
+    '--pele-surface': 'var(--color-fd-secondary)',
+    '--pele-surface-alt': 'var(--color-fd-muted)',
+    '--pele-border': 'var(--color-fd-primary)',
+    '--pele-accent': 'var(--color-fd-primary)',
+};

package/dist/render-chart.d.ts

@@ -0,0 +1,22 @@
+/** Size of rendered math markup at a font size, in CSS pixels. */
+export type MeasureMath = (html: string, size: number) => {
+    width: number;
+    height: number;
+} | null;
+export interface RenderChartOptions {
+    idPrefix: string;
+    fontFamily?: string;
+    measure: MeasureMath;
+}
+export interface RenderedChart {
+    inline: string;
+    zoomed: string;
+}
+/**
+ * Renders a chart's inline SVG and its full-screen copy with distinct element
+ * IDs. KaTeX loads only for charts that contain `$$`.
+ */
+export declare function renderChart(chart: string, { idPrefix, fontFamily, measure }: RenderChartOptions): Promise<RenderedChart>;
+/** Measures math markup in a hidden probe inside `host`, inheriting its fonts. */
+export declare function measureIn(host: HTMLElement): MeasureMath;
+//# sourceMappingURL=render-chart.d.ts.map

package/dist/render-chart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-chart.d.ts","sourceRoot":"","sources":["../src/render-chart.ts"],"names":[],"mappings":"AAIA,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,KACT;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AA6BD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,kBAAkB,GACpD,OAAO,CAAC,aAAa,CAAC,CAYxB;AAED,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAYxD"}

package/dist/render-chart.js

@@ -0,0 +1,57 @@
+import { fillWidth } from './zoom-svg.js';
+// Pele places `$$...$$` equations from labels and messages through this
+// resolver and needs their size up front. KaTeX's MathML output renders
+// natively in browsers, so no KaTeX stylesheet is required.
+async function loadMath(measure) {
+    const { default: katex } = await import('katex');
+    return (tex, size) => {
+        const html = katex.renderToString(tex, {
+            output: 'mathml',
+            // Mermaid renders `$$...$$` as display math, which `\tag` needs.
+            displayMode: true,
+            throwOnError: false,
+            // Pele inserts this markup unsanitized; keep KaTeX's escaping strict.
+            trust: false,
+        });
+        // A host that is not laid out yet (a hidden tab or collapsed section)
+        // measures 0x0; estimate from the source so the equation still renders.
+        return { html, ...(measure(html, size) ?? estimateBox(tex, size)) };
+    };
+}
+function estimateBox(tex, size) {
+    return {
+        width: Math.ceil(tex.length * size * 0.6),
+        height: Math.ceil(size * 1.5),
+    };
+}
+/**
+ * Renders a chart's inline SVG and its full-screen copy with distinct element
+ * IDs. KaTeX loads only for charts that contain `$$`.
+ */
+export async function renderChart(chart, { idPrefix, fontFamily, measure }) {
+    const [{ renderAsync }, math] = await Promise.all([
+        import('pele/lazy'),
+        chart.includes('$$') ? loadMath(measure) : undefined,
+    ]);
+    const inline = await renderAsync(chart, { idPrefix, fontFamily, math });
+    const zoomed = await renderAsync(chart, {
+        idPrefix: `${idPrefix}-zoom`,
+        fontFamily,
+        math,
+    });
+    return { inline: inline.svg, zoomed: fillWidth(zoomed.svg) };
+}
+/** Measures math markup in a hidden probe inside `host`, inheriting its fonts. */
+export function measureIn(host) {
+    return (html, size) => {
+        const probe = host.ownerDocument.createElement('span');
+        probe.style.cssText = `position:absolute;visibility:hidden;left:0;top:0;white-space:nowrap;line-height:normal;font-size:${size}px`;
+        probe.innerHTML = html;
+        host.append(probe);
+        const { width, height } = probe.getBoundingClientRect();
+        probe.remove();
+        return width > 0 && height > 0
+            ? { width: Math.ceil(width), height: Math.ceil(height) }
+            : null;
+    };
+}

package/dist/zoom-svg.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sizes a rendered diagram to fill the full-screen view. Pele sizes its root
+ * `<svg>` to the diagram's natural width, capped at the container, and keeps
+ * its theme variables in the same style attribute, so append the sizing
+ * rather than replace the attribute; the later declarations win.
+ */
+export declare function fillWidth(svg: string): string;
+//# sourceMappingURL=zoom-svg.d.ts.map

package/dist/zoom-svg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zoom-svg.d.ts","sourceRoot":"","sources":["../src/zoom-svg.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK7C"}

package/dist/zoom-svg.js

@@ -0,0 +1,9 @@
+/**
+ * Sizes a rendered diagram to fill the full-screen view. Pele sizes its root
+ * `<svg>` to the diagram's natural width, capped at the container, and keeps
+ * its theme variables in the same style attribute, so append the sizing
+ * rather than replace the attribute; the later declarations win.
+ */
+export function fillWidth(svg) {
+    return svg.replace(/^(<svg\b[^>]*?\sstyle=")([^"]*)"/, '$1$2;width:100%;height:auto;max-width:none"');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/docs-theme",
-  "version": "0.3.34",
+  "version": "0.3.36",
   "private": false,
   "description": "Theme components for OAT documentation sites",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/docs-theme",
@@ -30,8 +30,8 @@
     "access": "public"
   },
   "dependencies": {
-    "mermaid": "^11.6.0",
-    "next-themes": "^0.4.6"
+    "katex": "0.19.1",
+    "pele": "1.10.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/dist/mermaid-theme.d.ts

@@ -1,7 +0,0 @@
-/**
- * Mermaid theme variables for the current page, or `undefined` when the site
- * does not define the Fumadocs color tokens (Mermaid then uses its stock
- * theme).
- */
-export declare function siteMermaidThemeVariables(dark: boolean): Record<string, string | boolean> | undefined;
-//# sourceMappingURL=mermaid-theme.d.ts.map

package/dist/mermaid-theme.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"mermaid-theme.d.ts","sourceRoot":"","sources":["../src/mermaid-theme.ts"],"names":[],"mappings":"AAiCA;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,SAAS,CAqD9C"}

package/dist/mermaid-theme.js

@@ -1,88 +0,0 @@
-// Builds Mermaid `base` theme variables from the site's Fumadocs color tokens
-// so diagrams follow the docs site's palette in light and dark mode.
-const TOKENS = {
-    background: '--color-fd-background',
-    card: '--color-fd-card',
-    foreground: '--color-fd-foreground',
-    mutedForeground: '--color-fd-muted-foreground',
-    muted: '--color-fd-muted',
-    secondary: '--color-fd-secondary',
-    border: '--color-fd-border',
-    primary: '--color-fd-primary',
-};
-// Mermaid derives shades from its theme variables and only understands sRGB
-// hex/rgb input, while sites may define tokens in any CSS color space. Paint
-// the color into a 1x1 canvas and read the sRGB pixel back.
-function toHex(color, ctx) {
-    if (!color)
-        return undefined;
-    ctx.clearRect(0, 0, 1, 1);
-    ctx.fillStyle = '#000';
-    ctx.fillStyle = color;
-    ctx.fillRect(0, 0, 1, 1);
-    const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
-    if (a === 0)
-        return undefined;
-    return `#${[r, g, b].map((n) => n.toString(16).padStart(2, '0')).join('')}`;
-}
-/**
- * Mermaid theme variables for the current page, or `undefined` when the site
- * does not define the Fumadocs color tokens (Mermaid then uses its stock
- * theme).
- */
-export function siteMermaidThemeVariables(dark) {
-    if (typeof document === 'undefined')
-        return undefined;
-    const ctx = document
-        .createElement('canvas')
-        .getContext('2d', { willReadFrequently: true });
-    if (!ctx)
-        return undefined;
-    const style = getComputedStyle(document.documentElement);
-    const c = {};
-    for (const [name, prop] of Object.entries(TOKENS)) {
-        const hex = toHex(style.getPropertyValue(prop).trim(), ctx);
-        if (!hex)
-            return undefined;
-        c[name] = hex;
-    }
-    return {
-        darkMode: dark,
-        fontFamily: getComputedStyle(document.body).fontFamily,
-        background: c.card,
-        textColor: c.foreground,
-        titleColor: c.foreground,
-        lineColor: c.mutedForeground,
-        primaryColor: c.secondary,
-        primaryTextColor: c.foreground,
-        primaryBorderColor: c.primary,
-        secondaryColor: c.muted,
-        secondaryTextColor: c.foreground,
-        secondaryBorderColor: c.border,
-        tertiaryColor: c.card,
-        tertiaryTextColor: c.foreground,
-        tertiaryBorderColor: c.border,
-        mainBkg: c.secondary,
-        nodeBorder: c.primary,
-        nodeTextColor: c.foreground,
-        clusterBkg: c.muted,
-        clusterBorder: c.border,
-        edgeLabelBackground: c.card,
-        noteBkgColor: c.muted,
-        noteTextColor: c.foreground,
-        noteBorderColor: c.border,
-        actorBkg: c.secondary,
-        actorBorder: c.primary,
-        actorTextColor: c.foreground,
-        actorLineColor: c.mutedForeground,
-        signalColor: c.foreground,
-        signalTextColor: c.foreground,
-        labelBoxBkgColor: c.secondary,
-        labelBoxBorderColor: c.border,
-        labelTextColor: c.foreground,
-        loopTextColor: c.foreground,
-        activationBkgColor: c.muted,
-        activationBorderColor: c.primary,
-        sequenceNumberColor: c.card,
-    };
-}