@tdacorp/hyle-sdk 0.2.0 → 0.3.0

package/README.md

@@ -127,12 +127,25 @@ export default async function sitemap() {
 
 ## Host requirements
 
+Bundler only: `@tdacorp/hyle-sdk/next` and `/next/use-cache` import `next/navigation` and `next/cache` the way a Next app does, so plain Node ESM cannot import them. Real `next build` runs of the packed package passed with Next 16.2.7, 16.3.4 and 16.4.2 (Turbopack, the default).
+
 No layout or page above the mount may export `dynamicParams = false`. hyle content (an article published after your last build) is by definition not known at build time, and Next inherits a parent's `false` for every child route: the route is compiled with `"fallback": false`, so each path not generated at build time is a hard 404 that falls through to any `[locale]/[...rest]` catch-all (observed: `x-matched-path: /[locale]/[...rest]`, content looks missing). Setting `dynamicParams = true` on the page does not override a parent's `false`.
 
 Verify after `next build`: `.next/prerender-manifest.json` must not show `"fallback": false` for the route that mounts `hylePage`, and a request for a published article that did not exist at build time must return 200.
 
 Locale-prefixed hosts: you may keep `generateStaticParams` for the locales, but validate the locale in the layout (call `notFound()` for an unknown one) and set `dynamicParams = true` there, so unknown locales are still rejected.
 
+## Mermaid diagrams
+
+Zero setup. A Mermaid fence arrives from hyle as a sandboxed `<iframe srcdoc>` that loads a script from cdnjs, and a `srcdoc` frame inherits the host page's CSP, so a host with `script-src 'self'` would show a blank box. The SDK therefore reads the diagram text out of that document (only after it matched hyle's exact template) and renders it in your page with the Mermaid library it bundles as a dependency (`mermaid` `~11.9.0`, MIT). No cdnjs, no extra package, no config.
+
+- What loads when: the server renders a no-JavaScript fallback, a `<figure class="hyle-mermaid">` holding the source as a `language-mermaid` code block. On a page with a diagram, the browser then imports `mermaid` (a dynamic import, so your bundler emits it as lazy chunks served from your own origin) and swaps in the SVG. Pages without a diagram never load it: the client component is not even in their JavaScript. In the e2e app (Next 16.2.7, Turbopack) the lazy chunks total about 2.8 MB raw, 0.8 MB gzipped across every diagram type; a page loads only the ones its diagram type needs. `mermaid` itself is 64 MB on disk in `node_modules` (it is not shipped to browsers).
+- Rendering: a diagram renders when it is within 200 px of the viewport, one at a time, each limited to 10 s (a slower one falls back to the code block and the note). Per-diagram configuration (`%%{init}%%` directives and frontmatter) is stripped, see Security model. A re-render (theme change) keeps the previous SVG on screen until the new one is ready, and keeps it if the new one fails.
+- Themes: dark or default is chosen from the figure's computed background (falling back to `prefers-color-scheme`), and the diagram re-renders when `data-act`, `data-theme` or `class` change on `<html>` or the OS scheme changes.
+- Fallback: if the source cannot be extracted (over 20,000 characters, or not the renderer's template) the old sandboxed frame is used, which needs cdnjs in your CSP. If Mermaid cannot render the source (a syntax error), the code block stays and a short "diagram could not be rendered" note appears.
+- Host CSP: `script-src 'self'` is enough (plus `'unsafe-inline'` or nonces for Next's own inline scripts, as for any Next app); `style-src 'unsafe-inline'` is required because Mermaid's SVG carries inline styles; `img-src` decides whether images that a diagram label references load. Checked under `default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:` in headless Chromium on Next 16.2.7, 16.3.4 and 16.4.2 (`node scripts/e2e-next-build.mjs --browser`).
+- Override: `components.Mermaid` still replaces all of this. It receives `{ srcDoc, source, title }`; `source` is the diagram text, or `undefined` when it could not be extracted. `MermaidDiagram` (`{ source, title, errorText }`) is exported from `./react` if you want to wrap it. It is the SDK's only client component and takes nothing but those strings: no token or client ever crosses the boundary.
+
 ## Styling
 
 Import `@tdacorp/hyle-sdk/styles.css`. It is the design kit's stylesheet: every value comes from a public `--hyle-*` custom property with a SIGNAL fallback (`--sig-*` from `@tdacorp/signal-tokens`, so dark and light acts flip with no extra code). Set variables on `:root`, `body` or any wrapper above the mount; the SDK never declares them:
@@ -147,7 +160,7 @@ The 52 variables are listed in the token block at the top of `styles.css`. Layou
 
 `components` replaces how a part is drawn, `slots` fills named places. Both are props of the pages and options of `hylePage`.
 
-- Component slots: `Link` (every internal link, breadcrumb and in-page link: pass your router's Link), `Image`, `CodeBlock` (receives `code`, `language`, and the default `children`; the stock block has no copy button because that needs client JavaScript), `Mermaid` (receives hyle's sandboxed `srcDoc`), `Callout` (GFM alerts such as `> [!NOTE]`). The raw element overrides `a`, `img`, `code`, `pre`, `table`, `blockquote` and `h1` to `h6` also work.
+- Component slots: `Link` (every internal link, breadcrumb and in-page link: pass your router's Link), `Image`, `CodeBlock` (receives `code`, `language`, and the default `children`; the stock block has no copy button because that needs client JavaScript), `Mermaid` (receives hyle's sandboxed `srcDoc` and the extracted `source`; the default renders the diagram in the page, see "Mermaid diagrams"), `Callout` (GFM alerts such as `> [!NOTE]`). The raw element overrides `a`, `img`, `code`, `pre`, `table`, `blockquote` and `h1` to `h6` also work.
 - Visual slots: `article.before`, `article.meta`, `article.aside`, `article.after`, `list.header`, `list.item` (a component that receives the item), `list.empty`, `docs.sidebar-header`, `docs.version`, `docs.sidebar-footer`, `docs.after`, `notfound.body`, `notfound.actions`, `redirecting.body`. An unfilled slot renders nothing.
 - Layout: `layout: "docs"` renders articles as `DocsPage` (tree navigation from `ancestors`, `children` and `breadcrumbs`).
 
@@ -157,7 +170,8 @@ Chrome strings exist for en, fr and es (fr and es are unreviewed drafts). The pa
 
 - The token is sent only as an `Authorization` header from the server. It is never placed in a URL, logged or put in an error message. Keep it out of client components. The client requires an https `baseUrl` (http only for localhost, or with `allowInsecureHttp`), refuses redirects, aborts after `timeoutMs` (default 10 s) and refuses responses over `maxResponseBytes` (default 5 MiB).
 - The path is sent as a query parameter (encoded once); catch-all segments are decoded and refused if they contain `/`, `\`, control characters, `.` or `..`.
-- The `hast` tree is rendered through an allowlist (`sanitizeHast`) even though hyle sanitizes server-side: only known tags and properties with accepted value shapes survive; no `on*` attributes, `style` only inside KaTeX output and only for the properties KaTeX emits with small values (no `position:absolute`, `z-index`, `left` or large sizes), ids and in-page fragments scoped with the server's `user-content-` prefix (so heading ids, footnote links and TOC links still resolve), `href` and `src` limited to site-relative paths and `http(s)` (and `mailto` for links), unknown tags are unwrapped, `script` and `style` are dropped, and an `iframe` is kept only with `sandbox="allow-scripts"` and a `srcdoc` that is exactly the document hyle's renderer builds for a Mermaid fence (pinned script URL, at most 64 KiB); the SDK adds `referrerpolicy="no-referrer"` and a `csp` that allows only that script (checked in headless Chromium: the diagram still renders). A tree over 20,000 nodes or 512 KiB of text fails closed with `HastLimitError` and a safe notice. `dangerouslySetInnerHTML` is used in exactly one place, `TrustedServerHtml`, the escape hatch for `content.format === "html"`: it renders HTML as is, so pass it only HTML that came straight from hyle's resolve endpoint, never user input.
+- The `hast` tree is rendered through an allowlist (`sanitizeHast`) even though hyle sanitizes server-side: only known tags and properties with accepted value shapes survive; no `on*` attributes, `style` only inside KaTeX output and only for the properties KaTeX emits with small values (no `position:absolute`, `z-index`, `left` or large sizes), ids and in-page fragments scoped with the server's `user-content-` prefix (so heading ids, footnote links and TOC links still resolve), `href` and `src` limited to site-relative paths and `http(s)` (and `mailto` for links), unknown tags are unwrapped, `script` and `style` are dropped, and an `iframe` is kept only with `sandbox="allow-scripts"` and a `srcdoc` that is exactly the document hyle's renderer builds for a Mermaid fence (pinned script URL, at most 64 KiB); the SDK adds `referrerpolicy="no-referrer"` and a `csp` that allows only that script (checked in headless Chromium: the diagram still renders). A tree over 20,000 nodes or 512 KiB of text fails closed with `HastLimitError` and a safe notice. `dangerouslySetInnerHTML` is used in exactly two places: the Mermaid SVG sink (below) and `TrustedServerHtml`, the escape hatch for `content.format === "html"`: it renders HTML as is, so pass it only HTML that came straight from hyle's resolve endpoint, never user input.
+- Mermaid renders into your page, so: the source comes only from hyle content, passes the exact-template check and a 20,000 character cap, and is rendered with `securityLevel: "strict"` (Mermaid's own DOMPurify pass, no raw HTML labels) and `maxTextSize` set to the cap. The SDK strips every `%%{ ... }%%` directive (multi-line, unterminated and `init`, `initialize`, `config`, `wrap` forms) and a leading YAML frontmatter block from the source before rendering, and keeps plain `%% comment` lines. Reason: Mermaid's `themeCSS` (set by a directive or by frontmatter `config:`) is injected into the page as CSS and its sanitizer only checks brace balance, so a diagram could make the page fetch a URL or overlay the host UI; verified against Mermaid 11.9.0 with a loopback canary server, which received requests when the stripping was disabled and none with it. Consequence: authors cannot configure a diagram per diagram; a diagram that carries an init directive renders with the SDK's defaults. As a second guard `.hyle-mermaid-svg` uses `contain: paint` and the SVG is `position: static !important`, so diagram CSS cannot place anything over the host page. Flowchart `style` and `classDef` lines cannot carry `url(...)` (they fail to parse). What remains: Mermaid keeps an `<img>` inside a label (event handlers are stripped), so an author can make the page request an image, and your CSP `img-src` governs that exactly as for Markdown images (the e2e proves a strict `img-src 'self' data:` stops it); a `click A "https://..."` line makes a clickable link, a phishing-link capability inside author-controlled content, so treat hyle authors as trusted to link. Nothing is executed: the SDK ignores Mermaid's `bindFunctions`, and the hostile `click ... call`, `<img onerror>` and `securityLevel: "loose"` payloads did nothing in the browser check. The host CSP needs `style-src 'unsafe-inline'`.
 - Webhooks are verified with HMAC-SHA256 over the raw body (read with a running 64 KiB cap), a 300 s timestamp tolerance and constant-time comparison, with dual-secret rotation (empty secrets are never candidates), a payload shape check (400, not 500), tag validation, and delivery-id dedupe that records an id only after every purge succeeded, so a failed delivery can be retried.
 
 ## Not included

package/dist/{chunk-MHVWHSKC.js → chunk-EARQBSMF.js}

@@ -39,6 +39,12 @@ function Icon({ name, className }) {
   return /* @__PURE__ */ jsx("svg", { className: className ? `hyle-ic ${className}` : "hyle-ic", viewBox: "0 0 16 16", "aria-hidden": "true", children: SHAPES[name] });
 }
 
+// src/react/content.tsx
+import { MermaidDiagram } from "./mermaid-diagram.js";
+
+// src/react/mermaid-config.ts
+var MAX_MERMAID_SOURCE = 2e4;
+
 // src/react/sanitize.ts
 var HastLimitError = class extends Error {
   constructor(message) {
@@ -97,9 +103,14 @@ var isHref = (v) => isSafeUrl(v, "href") && (typeof v !== "string" || !v.trim().
 var isSrc = (v) => isSafeUrl(v, "src");
 var MERMAID_SCRIPT_URL = "https://cdnjs.cloudflare.com/ajax/libs/mermaid/11.9.0/mermaid.min.js";
 var MERMAID_SRCDOC = new RegExp(
-  `^<!doctype html><html><head><meta charset="utf-8"></head><body><div class="mermaid">[^<]*</div><script src="${MERMAID_SCRIPT_URL.replace(/[.]/g, "\\.")}"></script><script>mermaid\\.initialize\\(\\{ startOnLoad: true, securityLevel: "strict" \\}\\);</script></body></html>$`
+  `^<!doctype html><html><head><meta charset="utf-8"></head><body><div class="mermaid">([^<]*)</div><script src="${MERMAID_SCRIPT_URL.replace(/[.]/g, "\\.")}"></script><script>mermaid\\.initialize\\(\\{ startOnLoad: true, securityLevel: "strict" \\}\\);</script></body></html>$`
 );
 var isMermaidSrcdoc = (v) => typeof v === "string" && v.length <= MAX_SRCDOC && MERMAID_SRCDOC.test(v);
+var ENTITIES = { "&#x3c;": "<", "&#x26;": "&", "&lt;": "<", "&gt;": ">", "&amp;": "&", "&quot;": '"', "&#x27;": "'" };
+function mermaidSource(srcDoc) {
+  const text = MERMAID_SRCDOC.exec(srcDoc)?.[1]?.replace(/&(?:#x3c|#x26|#x27|lt|gt|amp|quot);/gi, (e) => ENTITIES[e.toLowerCase()]);
+  return text === void 0 || text.length > MAX_MERMAID_SOURCE ? void 0 : text;
+}
 var MERMAID_FRAME_CSP = `default-src 'none'; script-src ${MERMAID_SCRIPT_URL} 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:`;
 var heading = { id: isIdValue, className: isClass };
 var ATTRS = new Map(
@@ -225,6 +236,7 @@ var en = {
   tip: "Tip",
   caution: "Caution",
   diagram: "Diagram",
+  diagramError: "This diagram could not be rendered.",
   contentError: "This content cannot be displayed.",
   fallbackTitle: "Not translated into {language} yet.",
   fallbackBody: "You are reading the original.",
@@ -264,6 +276,7 @@ var fr = {
   tip: "Astuce",
   caution: "Danger",
   diagram: "Sch\xE9ma",
+  diagramError: "Ce sch\xE9ma n'a pas pu \xEAtre affich\xE9.",
   contentError: "Ce contenu ne peut pas \xEAtre affich\xE9.",
   fallbackTitle: "Pas encore traduit en {language}.",
   fallbackBody: "Vous lisez l'original.",
@@ -303,6 +316,7 @@ var es = {
   tip: "Consejo",
   caution: "Peligro",
   diagram: "Diagrama",
+  diagramError: "No se pudo mostrar este diagrama.",
   contentError: "No se puede mostrar este contenido.",
   fallbackTitle: "A\xFAn no est\xE1 traducida al {language}.",
   fallbackBody: "Est\xE1s leyendo el original.",
@@ -390,7 +404,9 @@ function buildComponents(c, s) {
   };
   const Frame = ({ srcDoc, sandbox }) => {
     if (typeof srcDoc !== "string") return null;
-    if (c.Mermaid) return /* @__PURE__ */ jsx3(c.Mermaid, { srcDoc, title: s.diagram });
+    const source = mermaidSource(srcDoc);
+    if (c.Mermaid) return /* @__PURE__ */ jsx3(c.Mermaid, { srcDoc, source, title: s.diagram });
+    if (source !== void 0) return /* @__PURE__ */ jsx3(MermaidDiagram, { source, title: s.diagram, errorText: s.diagramError });
     return /* @__PURE__ */ jsx3("figure", { className: "hyle-mermaid", "data-slot-component": "Mermaid", children: /* @__PURE__ */ jsx3("iframe", { srcDoc, sandbox: String(sandbox), title: s.diagram, loading: "lazy", referrerPolicy: "no-referrer", ...{ csp: MERMAID_FRAME_CSP } }) });
   };
   const Heading = (level) => function HyleHeading({ id, children, ...rest }) {
@@ -430,6 +446,9 @@ function TrustedServerHtml({ html }) {
   return /* @__PURE__ */ jsx3("div", { dangerouslySetInnerHTML: { __html: html } });
 }
 
+// src/react/index.ts
+import { MermaidDiagram as MermaidDiagram2 } from "./mermaid-diagram.js";
+
 // src/react/pages.tsx
 import { Fragment as Fragment4, jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
 function Slot({ name, slots, tag: Tag = "div", className }) {
@@ -732,5 +751,6 @@ export {
   DocsPage,
   NotFound,
   Unavailable,
-  Redirecting
+  Redirecting,
+  MermaidDiagram2 as MermaidDiagram
 };

package/dist/mermaid-diagram.cjs

@@ -0,0 +1,144 @@
+"use strict";
+"use client";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react/mermaid-diagram.tsx
+var mermaid_diagram_exports = {};
+__export(mermaid_diagram_exports, {
+  MermaidDiagram: () => MermaidDiagram
+});
+module.exports = __toCommonJS(mermaid_diagram_exports);
+var import_react = require("react");
+
+// src/react/mermaid-config.ts
+var MAX_MERMAID_SOURCE = 2e4;
+function luminance(css) {
+  const m = /^(rgba?)\(([^)]*)\)$|^color\(srgb ([^)]*)\)$/.exec(css.trim());
+  if (!m) return void 0;
+  const parts = (m[2] ?? m[3] ?? "").split(/[\s,/]+/).filter(Boolean).map(Number);
+  const [r, g, b] = parts.map((v) => m[3] ? v : v / 255);
+  const alpha = parts[3] ?? 1;
+  if (r === void 0 || g === void 0 || b === void 0 || [r, g, b, alpha].some(Number.isNaN) || alpha < 0.5) return void 0;
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function pickMermaidTheme(background, prefersDark) {
+  const l = luminance(background);
+  return (l === void 0 ? prefersDark : l < 0.5) ? "dark" : "default";
+}
+var RENDER_TIMEOUT_MS = 1e4;
+var NEAR_VIEWPORT_MARGIN = "200px";
+var FRONTMATTER = /^\s*-{3}[^\S\n]*\n[\s\S]*?\n-{3}[^\S\n]*(?:\n|$)/;
+var DIRECTIVE = /%%\{(?:(?!\}%%)[\s\S])*(?:\}%%)?/g;
+function stripMermaidConfig(source) {
+  let text = source.replace(/\r\n?/g, "\n");
+  for (let previous = ""; previous !== text; ) {
+    previous = text;
+    text = text.replace(FRONTMATTER, "").replace(DIRECTIVE, "");
+  }
+  return text;
+}
+var counter = 0;
+var nextMermaidId = () => `hyle-mermaid-${++counter}`;
+function withTimeout(promise, ms) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error("timeout")), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+function whenNearViewport(el, onNear, Observer = globalThis.IntersectionObserver) {
+  if (!Observer) {
+    onNear();
+    return () => {
+    };
+  }
+  const observer = new Observer((entries) => {
+    if (entries.some((e) => e.isIntersecting)) {
+      observer.disconnect();
+      onNear();
+    }
+  }, { rootMargin: NEAR_VIEWPORT_MARGIN });
+  observer.observe(el);
+  return () => observer.disconnect();
+}
+
+// src/react/mermaid-diagram.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var queue = Promise.resolve();
+async function renderSvg(id, source, theme) {
+  const { default: mermaid } = await import("mermaid");
+  mermaid.initialize({ startOnLoad: false, securityLevel: "strict", theme, maxTextSize: MAX_MERMAID_SOURCE, suppressErrorRendering: true });
+  try {
+    return (await mermaid.render(id, stripMermaidConfig(source))).svg;
+  } finally {
+    document.getElementById(`d${id}`)?.remove();
+  }
+}
+var THEME_ATTRS = ["data-act", "data-theme", "class"];
+function MermaidDiagram({ source, title, errorText }) {
+  const figure = (0, import_react.useRef)(null);
+  const [theme, setTheme] = (0, import_react.useState)(null);
+  const [near, setNear] = (0, import_react.useState)(false);
+  const [svg, setSvg] = (0, import_react.useState)(null);
+  const [failed, setFailed] = (0, import_react.useState)(false);
+  (0, import_react.useEffect)(() => {
+    const scheme = window.matchMedia("(prefers-color-scheme: dark)");
+    const update = () => figure.current && setTheme(pickMermaidTheme(getComputedStyle(figure.current).backgroundColor, scheme.matches));
+    update();
+    const observer = new MutationObserver(update);
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: THEME_ATTRS });
+    scheme.addEventListener("change", update);
+    return () => {
+      observer.disconnect();
+      scheme.removeEventListener("change", update);
+    };
+  }, []);
+  (0, import_react.useEffect)(() => figure.current ? whenNearViewport(figure.current, () => setNear(true)) : void 0, []);
+  (0, import_react.useEffect)(() => {
+    if (theme === null || !near) return;
+    let current = true;
+    const id = nextMermaidId();
+    queue = queue.then(() => current ? withTimeout(renderSvg(id, source, theme), RENDER_TIMEOUT_MS) : void 0).then(
+      (out) => current && out !== void 0 && (setSvg(out), setFailed(false)),
+      () => current && setFailed(true)
+    );
+    return () => {
+      current = false;
+    };
+  }, [source, theme, near]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("figure", { ref: figure, className: "hyle-mermaid", "data-slot-component": "Mermaid", children: [
+    svg === null ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("pre", { tabIndex: 0, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("code", { className: "language-mermaid", children: source }) }) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "hyle-mermaid-svg", role: "img", "aria-label": title, dangerouslySetInnerHTML: { __html: svg } }),
+    failed ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "hyle-mermaid-note", role: "status", children: errorText }) : null,
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("figcaption", { className: "sr-only", children: title })
+  ] });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MermaidDiagram
+});

package/dist/mermaid-diagram.d.cts

@@ -0,0 +1,17 @@
+import * as react from 'react';
+
+/**
+ * The SDK's only client component. It receives the diagram text and presentational strings and nothing else: never a token,
+ * base URL or client (a test pins this). Mermaid is a dynamic import, so the chunk loads only on pages that have a diagram,
+ * from the host's own origin.
+ */
+interface MermaidDiagramProps {
+    source: string;
+    /** Accessible name of the diagram. */
+    title: string;
+    /** Shown when Mermaid cannot render the source. */
+    errorText: string;
+}
+declare function MermaidDiagram({ source, title, errorText }: MermaidDiagramProps): react.JSX.Element;
+
+export { MermaidDiagram, type MermaidDiagramProps };

package/dist/mermaid-diagram.d.ts

@@ -0,0 +1,17 @@
+import * as react from 'react';
+
+/**
+ * The SDK's only client component. It receives the diagram text and presentational strings and nothing else: never a token,
+ * base URL or client (a test pins this). Mermaid is a dynamic import, so the chunk loads only on pages that have a diagram,
+ * from the host's own origin.
+ */
+interface MermaidDiagramProps {
+    source: string;
+    /** Accessible name of the diagram. */
+    title: string;
+    /** Shown when Mermaid cannot render the source. */
+    errorText: string;
+}
+declare function MermaidDiagram({ source, title, errorText }: MermaidDiagramProps): react.JSX.Element;
+
+export { MermaidDiagram, type MermaidDiagramProps };

package/dist/mermaid-diagram.js

@@ -0,0 +1,110 @@
+"use client";
+
+// src/react/mermaid-diagram.tsx
+import { useEffect, useRef, useState } from "react";
+
+// src/react/mermaid-config.ts
+var MAX_MERMAID_SOURCE = 2e4;
+function luminance(css) {
+  const m = /^(rgba?)\(([^)]*)\)$|^color\(srgb ([^)]*)\)$/.exec(css.trim());
+  if (!m) return void 0;
+  const parts = (m[2] ?? m[3] ?? "").split(/[\s,/]+/).filter(Boolean).map(Number);
+  const [r, g, b] = parts.map((v) => m[3] ? v : v / 255);
+  const alpha = parts[3] ?? 1;
+  if (r === void 0 || g === void 0 || b === void 0 || [r, g, b, alpha].some(Number.isNaN) || alpha < 0.5) return void 0;
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function pickMermaidTheme(background, prefersDark) {
+  const l = luminance(background);
+  return (l === void 0 ? prefersDark : l < 0.5) ? "dark" : "default";
+}
+var RENDER_TIMEOUT_MS = 1e4;
+var NEAR_VIEWPORT_MARGIN = "200px";
+var FRONTMATTER = /^\s*-{3}[^\S\n]*\n[\s\S]*?\n-{3}[^\S\n]*(?:\n|$)/;
+var DIRECTIVE = /%%\{(?:(?!\}%%)[\s\S])*(?:\}%%)?/g;
+function stripMermaidConfig(source) {
+  let text = source.replace(/\r\n?/g, "\n");
+  for (let previous = ""; previous !== text; ) {
+    previous = text;
+    text = text.replace(FRONTMATTER, "").replace(DIRECTIVE, "");
+  }
+  return text;
+}
+var counter = 0;
+var nextMermaidId = () => `hyle-mermaid-${++counter}`;
+function withTimeout(promise, ms) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error("timeout")), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+function whenNearViewport(el, onNear, Observer = globalThis.IntersectionObserver) {
+  if (!Observer) {
+    onNear();
+    return () => {
+    };
+  }
+  const observer = new Observer((entries) => {
+    if (entries.some((e) => e.isIntersecting)) {
+      observer.disconnect();
+      onNear();
+    }
+  }, { rootMargin: NEAR_VIEWPORT_MARGIN });
+  observer.observe(el);
+  return () => observer.disconnect();
+}
+
+// src/react/mermaid-diagram.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var queue = Promise.resolve();
+async function renderSvg(id, source, theme) {
+  const { default: mermaid } = await import("mermaid");
+  mermaid.initialize({ startOnLoad: false, securityLevel: "strict", theme, maxTextSize: MAX_MERMAID_SOURCE, suppressErrorRendering: true });
+  try {
+    return (await mermaid.render(id, stripMermaidConfig(source))).svg;
+  } finally {
+    document.getElementById(`d${id}`)?.remove();
+  }
+}
+var THEME_ATTRS = ["data-act", "data-theme", "class"];
+function MermaidDiagram({ source, title, errorText }) {
+  const figure = useRef(null);
+  const [theme, setTheme] = useState(null);
+  const [near, setNear] = useState(false);
+  const [svg, setSvg] = useState(null);
+  const [failed, setFailed] = useState(false);
+  useEffect(() => {
+    const scheme = window.matchMedia("(prefers-color-scheme: dark)");
+    const update = () => figure.current && setTheme(pickMermaidTheme(getComputedStyle(figure.current).backgroundColor, scheme.matches));
+    update();
+    const observer = new MutationObserver(update);
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: THEME_ATTRS });
+    scheme.addEventListener("change", update);
+    return () => {
+      observer.disconnect();
+      scheme.removeEventListener("change", update);
+    };
+  }, []);
+  useEffect(() => figure.current ? whenNearViewport(figure.current, () => setNear(true)) : void 0, []);
+  useEffect(() => {
+    if (theme === null || !near) return;
+    let current = true;
+    const id = nextMermaidId();
+    queue = queue.then(() => current ? withTimeout(renderSvg(id, source, theme), RENDER_TIMEOUT_MS) : void 0).then(
+      (out) => current && out !== void 0 && (setSvg(out), setFailed(false)),
+      () => current && setFailed(true)
+    );
+    return () => {
+      current = false;
+    };
+  }, [source, theme, near]);
+  return /* @__PURE__ */ jsxs("figure", { ref: figure, className: "hyle-mermaid", "data-slot-component": "Mermaid", children: [
+    svg === null ? /* @__PURE__ */ jsx("pre", { tabIndex: 0, children: /* @__PURE__ */ jsx("code", { className: "language-mermaid", children: source }) }) : /* @__PURE__ */ jsx("div", { className: "hyle-mermaid-svg", role: "img", "aria-label": title, dangerouslySetInnerHTML: { __html: svg } }),
+    failed ? /* @__PURE__ */ jsx("p", { className: "hyle-mermaid-note", role: "status", children: errorText }) : null,
+    /* @__PURE__ */ jsx("figcaption", { className: "sr-only", children: title })
+  ] });
+}
+export {
+  MermaidDiagram
+};

package/dist/next.cjs

@@ -352,6 +352,12 @@ function Icon({ name, className }) {
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("svg", { className: className ? `hyle-ic ${className}` : "hyle-ic", viewBox: "0 0 16 16", "aria-hidden": "true", children: SHAPES[name] });
 }
 
+// src/react/content.tsx
+var import_mermaid_diagram = require("./mermaid-diagram.cjs");
+
+// src/react/mermaid-config.ts
+var MAX_MERMAID_SOURCE = 2e4;
+
 // src/react/sanitize.ts
 var HastLimitError = class extends Error {
   constructor(message) {
@@ -410,9 +416,14 @@ var isHref = (v) => isSafeUrl(v, "href") && (typeof v !== "string" || !v.trim().
 var isSrc = (v) => isSafeUrl(v, "src");
 var MERMAID_SCRIPT_URL = "https://cdnjs.cloudflare.com/ajax/libs/mermaid/11.9.0/mermaid.min.js";
 var MERMAID_SRCDOC = new RegExp(
-  `^<!doctype html><html><head><meta charset="utf-8"></head><body><div class="mermaid">[^<]*</div><script src="${MERMAID_SCRIPT_URL.replace(/[.]/g, "\\.")}"></script><script>mermaid\\.initialize\\(\\{ startOnLoad: true, securityLevel: "strict" \\}\\);</script></body></html>$`
+  `^<!doctype html><html><head><meta charset="utf-8"></head><body><div class="mermaid">([^<]*)</div><script src="${MERMAID_SCRIPT_URL.replace(/[.]/g, "\\.")}"></script><script>mermaid\\.initialize\\(\\{ startOnLoad: true, securityLevel: "strict" \\}\\);</script></body></html>$`
 );
 var isMermaidSrcdoc = (v) => typeof v === "string" && v.length <= MAX_SRCDOC && MERMAID_SRCDOC.test(v);
+var ENTITIES = { "&#x3c;": "<", "&#x26;": "&", "&lt;": "<", "&gt;": ">", "&amp;": "&", "&quot;": '"', "&#x27;": "'" };
+function mermaidSource(srcDoc) {
+  const text = MERMAID_SRCDOC.exec(srcDoc)?.[1]?.replace(/&(?:#x3c|#x26|#x27|lt|gt|amp|quot);/gi, (e) => ENTITIES[e.toLowerCase()]);
+  return text === void 0 || text.length > MAX_MERMAID_SOURCE ? void 0 : text;
+}
 var MERMAID_FRAME_CSP = `default-src 'none'; script-src ${MERMAID_SCRIPT_URL} 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:`;
 var heading = { id: isIdValue, className: isClass };
 var ATTRS = new Map(
@@ -538,6 +549,7 @@ var en = {
   tip: "Tip",
   caution: "Caution",
   diagram: "Diagram",
+  diagramError: "This diagram could not be rendered.",
   contentError: "This content cannot be displayed.",
   fallbackTitle: "Not translated into {language} yet.",
   fallbackBody: "You are reading the original.",
@@ -577,6 +589,7 @@ var fr = {
   tip: "Astuce",
   caution: "Danger",
   diagram: "Sch\xE9ma",
+  diagramError: "Ce sch\xE9ma n'a pas pu \xEAtre affich\xE9.",
   contentError: "Ce contenu ne peut pas \xEAtre affich\xE9.",
   fallbackTitle: "Pas encore traduit en {language}.",
   fallbackBody: "Vous lisez l'original.",
@@ -616,6 +629,7 @@ var es = {
   tip: "Consejo",
   caution: "Peligro",
   diagram: "Diagrama",
+  diagramError: "No se pudo mostrar este diagrama.",
   contentError: "No se puede mostrar este contenido.",
   fallbackTitle: "A\xFAn no est\xE1 traducida al {language}.",
   fallbackBody: "Est\xE1s leyendo el original.",
@@ -703,7 +717,9 @@ function buildComponents(c, s) {
   };
   const Frame = ({ srcDoc, sandbox }) => {
     if (typeof srcDoc !== "string") return null;
-    if (c.Mermaid) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(c.Mermaid, { srcDoc, title: s.diagram });
+    const source = mermaidSource(srcDoc);
+    if (c.Mermaid) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(c.Mermaid, { srcDoc, source, title: s.diagram });
+    if (source !== void 0) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_mermaid_diagram.MermaidDiagram, { source, title: s.diagram, errorText: s.diagramError });
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("figure", { className: "hyle-mermaid", "data-slot-component": "Mermaid", children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("iframe", { srcDoc, sandbox: String(sandbox), title: s.diagram, loading: "lazy", referrerPolicy: "no-referrer", ...{ csp: MERMAID_FRAME_CSP } }) });
   };
   const Heading = (level) => function HyleHeading({ id, children, ...rest }) {
@@ -743,6 +759,9 @@ function TrustedServerHtml({ html }) {
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { dangerouslySetInnerHTML: { __html: html } });
 }
 
+// src/react/index.ts
+var import_mermaid_diagram2 = require("./mermaid-diagram.cjs");
+
 // src/react/pages.tsx
 var import_jsx_runtime4 = require("react/jsx-runtime");
 function Slot({ name, slots, tag: Tag = "div", className }) {

package/dist/next.d.cts

@@ -1,5 +1,5 @@
 import { ReactElement } from 'react';
-import { H as HyleComponents, a as HyleSlots } from './types-DLWvqanV.cjs';
+import { H as HyleComponents, a as HyleSlots } from './types-D0qoLh4E.cjs';
 import { F as FetchResolverOptions, H as HyleResolver } from './resolve-B_p0p4Zn.cjs';
 export { f as fetchResolver, w as workspaceTags } from './resolve-B_p0p4Zn.cjs';
 import { MetadataRoute, Metadata } from 'next';

package/dist/next.d.ts

@@ -1,5 +1,5 @@
 import { ReactElement } from 'react';
-import { H as HyleComponents, a as HyleSlots } from './types-BNaGecO7.js';
+import { H as HyleComponents, a as HyleSlots } from './types-CBvLhUPr.js';
 import { F as FetchResolverOptions, H as HyleResolver } from './resolve-fMx2W8RR.js';
 export { f as fetchResolver, w as workspaceTags } from './resolve-fMx2W8RR.js';
 import { MetadataRoute, Metadata } from 'next';

package/dist/next.js

@@ -2,7 +2,7 @@ import {
   ArticlePage,
   DocsPage,
   ListPage
-} from "./chunk-MHVWHSKC.js";
+} from "./chunk-EARQBSMF.js";
 import {
   fetchResolver,
   workspaceTags
@@ -14,10 +14,10 @@ import {
 } from "./chunk-HFUJRNFP.js";
 
 // src/next/page.tsx
-import { notFound, permanentRedirect, redirect } from "next/navigation.js";
+import { notFound, permanentRedirect, redirect } from "next/navigation";
 
 // src/next/options.ts
-import { unstable_rethrow } from "next/navigation.js";
+import { unstable_rethrow } from "next/navigation";
 
 // src/next/paths.ts
 function normalizeBasePath(basePath) {
@@ -185,7 +185,7 @@ function hyleMetadata(options) {
 }
 
 // src/next/revalidate.ts
-import { revalidateTag } from "next/cache.js";
+import { revalidateTag } from "next/cache";
 var isSwitchedOff = (value) => ["0", "false"].includes(value?.trim().toLowerCase() ?? "");
 function createRevalidateRoute(options) {
   let cached;

package/dist/react.cjs

@@ -25,6 +25,7 @@ __export(react_exports, {
   HastContent: () => HastContent,
   HastLimitError: () => HastLimitError,
   ListPage: () => ListPage,
+  MermaidDiagram: () => import_mermaid_diagram2.MermaidDiagram,
   NotFound: () => NotFound,
   Redirecting: () => Redirecting,
   TrustedServerHtml: () => TrustedServerHtml,
@@ -77,6 +78,12 @@ function Icon({ name, className }) {
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("svg", { className: className ? `hyle-ic ${className}` : "hyle-ic", viewBox: "0 0 16 16", "aria-hidden": "true", children: SHAPES[name] });
 }
 
+// src/react/content.tsx
+var import_mermaid_diagram = require("./mermaid-diagram.cjs");
+
+// src/react/mermaid-config.ts
+var MAX_MERMAID_SOURCE = 2e4;
+
 // src/react/sanitize.ts
 var HastLimitError = class extends Error {
   constructor(message) {
@@ -135,9 +142,14 @@ var isHref = (v) => isSafeUrl(v, "href") && (typeof v !== "string" || !v.trim().
 var isSrc = (v) => isSafeUrl(v, "src");
 var MERMAID_SCRIPT_URL = "https://cdnjs.cloudflare.com/ajax/libs/mermaid/11.9.0/mermaid.min.js";
 var MERMAID_SRCDOC = new RegExp(
-  `^<!doctype html><html><head><meta charset="utf-8"></head><body><div class="mermaid">[^<]*</div><script src="${MERMAID_SCRIPT_URL.replace(/[.]/g, "\\.")}"></script><script>mermaid\\.initialize\\(\\{ startOnLoad: true, securityLevel: "strict" \\}\\);</script></body></html>$`
+  `^<!doctype html><html><head><meta charset="utf-8"></head><body><div class="mermaid">([^<]*)</div><script src="${MERMAID_SCRIPT_URL.replace(/[.]/g, "\\.")}"></script><script>mermaid\\.initialize\\(\\{ startOnLoad: true, securityLevel: "strict" \\}\\);</script></body></html>$`
 );
 var isMermaidSrcdoc = (v) => typeof v === "string" && v.length <= MAX_SRCDOC && MERMAID_SRCDOC.test(v);
+var ENTITIES = { "&#x3c;": "<", "&#x26;": "&", "&lt;": "<", "&gt;": ">", "&amp;": "&", "&quot;": '"', "&#x27;": "'" };
+function mermaidSource(srcDoc) {
+  const text = MERMAID_SRCDOC.exec(srcDoc)?.[1]?.replace(/&(?:#x3c|#x26|#x27|lt|gt|amp|quot);/gi, (e) => ENTITIES[e.toLowerCase()]);
+  return text === void 0 || text.length > MAX_MERMAID_SOURCE ? void 0 : text;
+}
 var MERMAID_FRAME_CSP = `default-src 'none'; script-src ${MERMAID_SCRIPT_URL} 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:`;
 var heading = { id: isIdValue, className: isClass };
 var ATTRS = new Map(
@@ -263,6 +275,7 @@ var en = {
   tip: "Tip",
   caution: "Caution",
   diagram: "Diagram",
+  diagramError: "This diagram could not be rendered.",
   contentError: "This content cannot be displayed.",
   fallbackTitle: "Not translated into {language} yet.",
   fallbackBody: "You are reading the original.",
@@ -302,6 +315,7 @@ var fr = {
   tip: "Astuce",
   caution: "Danger",
   diagram: "Sch\xE9ma",
+  diagramError: "Ce sch\xE9ma n'a pas pu \xEAtre affich\xE9.",
   contentError: "Ce contenu ne peut pas \xEAtre affich\xE9.",
   fallbackTitle: "Pas encore traduit en {language}.",
   fallbackBody: "Vous lisez l'original.",
@@ -341,6 +355,7 @@ var es = {
   tip: "Consejo",
   caution: "Peligro",
   diagram: "Diagrama",
+  diagramError: "No se pudo mostrar este diagrama.",
   contentError: "No se puede mostrar este contenido.",
   fallbackTitle: "A\xFAn no est\xE1 traducida al {language}.",
   fallbackBody: "Est\xE1s leyendo el original.",
@@ -428,7 +443,9 @@ function buildComponents(c, s) {
   };
   const Frame = ({ srcDoc, sandbox }) => {
     if (typeof srcDoc !== "string") return null;
-    if (c.Mermaid) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(c.Mermaid, { srcDoc, title: s.diagram });
+    const source = mermaidSource(srcDoc);
+    if (c.Mermaid) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(c.Mermaid, { srcDoc, source, title: s.diagram });
+    if (source !== void 0) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_mermaid_diagram.MermaidDiagram, { source, title: s.diagram, errorText: s.diagramError });
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("figure", { className: "hyle-mermaid", "data-slot-component": "Mermaid", children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("iframe", { srcDoc, sandbox: String(sandbox), title: s.diagram, loading: "lazy", referrerPolicy: "no-referrer", ...{ csp: MERMAID_FRAME_CSP } }) });
   };
   const Heading = (level) => function HyleHeading({ id, children, ...rest }) {
@@ -468,6 +485,9 @@ function TrustedServerHtml({ html }) {
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { dangerouslySetInnerHTML: { __html: html } });
 }
 
+// src/react/index.ts
+var import_mermaid_diagram2 = require("./mermaid-diagram.cjs");
+
 // src/react/pages.tsx
 var import_jsx_runtime4 = require("react/jsx-runtime");
 function Slot({ name, slots, tag: Tag = "div", className }) {
@@ -763,6 +783,7 @@ function Redirecting({ from, to, ...base }) {
   HastContent,
   HastLimitError,
   ListPage,
+  MermaidDiagram,
   NotFound,
   Redirecting,
   TrustedServerHtml,

package/dist/react.d.cts

@@ -1,6 +1,7 @@
+import * as react from 'react';
 import { ReactElement } from 'react';
-import { H as HyleComponents, P as PageBaseProps } from './types-DLWvqanV.cjs';
-export { C as CalloutKind, b as CalloutProps, c as CodeBlockProps, a as HyleSlots, I as ImageProps, L as LinkProps, d as ListItemProps, M as MermaidProps } from './types-DLWvqanV.cjs';
+import { H as HyleComponents, P as PageBaseProps } from './types-D0qoLh4E.cjs';
+export { C as CalloutKind, b as CalloutProps, c as CodeBlockProps, a as HyleSlots, I as ImageProps, L as LinkProps, d as ListItemProps, M as MermaidProps } from './types-D0qoLh4E.cjs';
 import { Root } from 'hast';
 import { b as ResolvedArticle, d as ResolvedList } from './types-DjXf6iPo.cjs';
 
@@ -23,6 +24,20 @@ declare function TrustedServerHtml({ html }: {
     html: string;
 }): ReactElement;
 
+/**
+ * The SDK's only client component. It receives the diagram text and presentational strings and nothing else: never a token,
+ * base URL or client (a test pins this). Mermaid is a dynamic import, so the chunk loads only on pages that have a diagram,
+ * from the host's own origin.
+ */
+interface MermaidDiagramProps {
+    source: string;
+    /** Accessible name of the diagram. */
+    title: string;
+    /** Shown when Mermaid cannot render the source. */
+    errorText: string;
+}
+declare function MermaidDiagram({ source, title, errorText }: MermaidDiagramProps): react.JSX.Element;
+
 /**
  * Defense in depth. hyle sanitizes server-side (packages/renderer/src/render.ts); this guard repeats the same allowlist
  * so a compromised or buggy response still cannot put script, event handlers or `javascript:` URLs on the page. It
@@ -91,6 +106,7 @@ declare const en: {
     tip: string;
     caution: string;
     diagram: string;
+    diagramError: string;
     contentError: string;
     fallbackTitle: string;
     fallbackBody: string;
@@ -118,4 +134,4 @@ type Strings = typeof en;
 /** Strings for a BCP 47 tag; the primary subtag decides, anything unknown falls back to English. */
 declare function stringsFor(locale: string | undefined): Strings;
 
-export { ArticlePage, type ArticlePageProps, DocsPage, HastContent, type HastContentProps, HastLimitError, HyleComponents, ListPage, type ListPageProps, NotFound, type NotFoundProps, PageBaseProps, Redirecting, type RedirectingProps, type Strings, TrustedServerHtml, Unavailable, isSafeUrl, sanitizeHast, scopeId, stringsFor };
+export { ArticlePage, type ArticlePageProps, DocsPage, HastContent, type HastContentProps, HastLimitError, HyleComponents, ListPage, type ListPageProps, MermaidDiagram, type MermaidDiagramProps, NotFound, type NotFoundProps, PageBaseProps, Redirecting, type RedirectingProps, type Strings, TrustedServerHtml, Unavailable, isSafeUrl, sanitizeHast, scopeId, stringsFor };

package/dist/react.d.ts

@@ -1,6 +1,7 @@
+import * as react from 'react';
 import { ReactElement } from 'react';
-import { H as HyleComponents, P as PageBaseProps } from './types-BNaGecO7.js';
-export { C as CalloutKind, b as CalloutProps, c as CodeBlockProps, a as HyleSlots, I as ImageProps, L as LinkProps, d as ListItemProps, M as MermaidProps } from './types-BNaGecO7.js';
+import { H as HyleComponents, P as PageBaseProps } from './types-CBvLhUPr.js';
+export { C as CalloutKind, b as CalloutProps, c as CodeBlockProps, a as HyleSlots, I as ImageProps, L as LinkProps, d as ListItemProps, M as MermaidProps } from './types-CBvLhUPr.js';
 import { Root } from 'hast';
 import { b as ResolvedArticle, d as ResolvedList } from './types-DjXf6iPo.js';
 
@@ -23,6 +24,20 @@ declare function TrustedServerHtml({ html }: {
     html: string;
 }): ReactElement;
 
+/**
+ * The SDK's only client component. It receives the diagram text and presentational strings and nothing else: never a token,
+ * base URL or client (a test pins this). Mermaid is a dynamic import, so the chunk loads only on pages that have a diagram,
+ * from the host's own origin.
+ */
+interface MermaidDiagramProps {
+    source: string;
+    /** Accessible name of the diagram. */
+    title: string;
+    /** Shown when Mermaid cannot render the source. */
+    errorText: string;
+}
+declare function MermaidDiagram({ source, title, errorText }: MermaidDiagramProps): react.JSX.Element;
+
 /**
  * Defense in depth. hyle sanitizes server-side (packages/renderer/src/render.ts); this guard repeats the same allowlist
  * so a compromised or buggy response still cannot put script, event handlers or `javascript:` URLs on the page. It
@@ -91,6 +106,7 @@ declare const en: {
     tip: string;
     caution: string;
     diagram: string;
+    diagramError: string;
     contentError: string;
     fallbackTitle: string;
     fallbackBody: string;
@@ -118,4 +134,4 @@ type Strings = typeof en;
 /** Strings for a BCP 47 tag; the primary subtag decides, anything unknown falls back to English. */
 declare function stringsFor(locale: string | undefined): Strings;
 
-export { ArticlePage, type ArticlePageProps, DocsPage, HastContent, type HastContentProps, HastLimitError, HyleComponents, ListPage, type ListPageProps, NotFound, type NotFoundProps, PageBaseProps, Redirecting, type RedirectingProps, type Strings, TrustedServerHtml, Unavailable, isSafeUrl, sanitizeHast, scopeId, stringsFor };
+export { ArticlePage, type ArticlePageProps, DocsPage, HastContent, type HastContentProps, HastLimitError, HyleComponents, ListPage, type ListPageProps, MermaidDiagram, type MermaidDiagramProps, NotFound, type NotFoundProps, PageBaseProps, Redirecting, type RedirectingProps, type Strings, TrustedServerHtml, Unavailable, isSafeUrl, sanitizeHast, scopeId, stringsFor };

package/dist/react.js

@@ -4,6 +4,7 @@ import {
   HastContent,
   HastLimitError,
   ListPage,
+  MermaidDiagram,
   NotFound,
   Redirecting,
   TrustedServerHtml,
@@ -12,13 +13,14 @@ import {
   sanitizeHast,
   scopeId,
   stringsFor
-} from "./chunk-MHVWHSKC.js";
+} from "./chunk-EARQBSMF.js";
 export {
   ArticlePage,
   DocsPage,
   HastContent,
   HastLimitError,
   ListPage,
+  MermaidDiagram,
   NotFound,
   Redirecting,
   TrustedServerHtml,

package/dist/styles.css

@@ -355,7 +355,7 @@
 .hyle-callout .bd{font-size:.9375em;line-height:1.6}
 
 /* mermaid placeholder frame */
-.hyle-mermaid{margin-inline:0;border:var(--h-border-width) dashed var(--h-border);border-radius:var(--h-radius);background:var(--h-surface);overflow:hidden}
+.hyle-mermaid{margin-inline:0;border:var(--h-border-width) dashed var(--h-border);border-radius:var(--h-radius);background:var(--h-surface);overflow-x:auto}
 .hyle-mermaid .hyle-stage{display:flex;align-items:center;justify-content:center;gap:0;padding:32px 16px;flex-wrap:wrap;row-gap:12px}
 .hyle-mermaid .node{display:grid;place-items:center;min-width:104px;height:40px;padding:0 12px;border:var(--h-border-width) solid var(--h-border);border-radius:min(var(--h-radius),8px);background:var(--h-surface-2);font:500 13px/1 var(--h-font-mono);color:var(--h-text-muted)}
 .hyle-mermaid .edge{width:32px;height:1px;background:var(--h-border);position:relative}
@@ -401,3 +401,8 @@
 /* ---- additions not in the design kit (the kit mocks these; the real hast needs them) ---- */
 .hyle .sr-only{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}
 .hyle-mermaid iframe{display:block;width:100%;min-height:240px;border:0;background:transparent}
+.hyle-mermaid>pre{padding:16px}
+/* contain:paint clips the SVG and makes it the containing block of any absolute or fixed descendant, so diagram CSS cannot overlay the host page */
+.hyle-mermaid-svg{display:flex;justify-content:center;padding:16px;contain:paint}
+.hyle-mermaid-svg svg{position:static!important;max-width:100%;height:auto}
+.hyle-mermaid-note{margin:0;padding:8px 16px;border-top:1px dashed var(--h-border);font-size:13px;color:var(--h-warn)}

package/dist/{types-BNaGecO7.d.ts → types-CBvLhUPr.d.ts}

@@ -23,6 +23,8 @@ interface CodeBlockProps {
 interface MermaidProps {
     /** The sandboxed document hyle produced for the diagram. Render it only inside an iframe with `sandbox="allow-scripts"`. */
     srcDoc: string;
+    /** The diagram text, extracted from `srcDoc` (at most 20,000 characters); undefined when it could not be extracted. */
+    source: string | undefined;
     title: string;
 }
 interface CalloutProps {

package/dist/{types-DLWvqanV.d.cts → types-D0qoLh4E.d.cts}

@@ -23,6 +23,8 @@ interface CodeBlockProps {
 interface MermaidProps {
     /** The sandboxed document hyle produced for the diagram. Render it only inside an iframe with `sandbox="allow-scripts"`. */
     srcDoc: string;
+    /** The diagram text, extracted from `srcDoc` (at most 20,000 characters); undefined when it could not be extracted. */
+    source: string | undefined;
     title: string;
 }
 interface CalloutProps {

package/dist/use-cache.js

@@ -7,7 +7,7 @@ import {
 } from "./chunk-HFUJRNFP.js";
 
 // src/next/use-cache.ts
-import { cacheLife, cacheTag } from "next/cache.js";
+import { cacheLife, cacheTag } from "next/cache";
 var MAX_TAGS = 128;
 var DISABLED_REVALIDATE = 30;
 var tokens = /* @__PURE__ */ new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tdacorp/hyle-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "hyle SDK: a typed client for hyle's resolve endpoint, a hast renderer for React, and a Next.js catch-all page with tag-based revalidation.",
   "license": "MIT",
   "repository": {
@@ -71,7 +71,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "hast-util-to-jsx-runtime": "^2.3.6"
+    "hast-util-to-jsx-runtime": "^2.3.6",
+    "mermaid": "~11.9.0"
   },
   "peerDependencies": {
     "next": ">=16",
@@ -106,7 +107,7 @@
     "tdacorp"
   ],
   "scripts": {
-    "build": "tsup && cp src/styles.css dist/styles.css",
+    "build": "rimraf dist && tsup && cp src/styles.css dist/styles.css",
     "clean": "rimraf dist",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",