@pokedocs/plugin-mermaid-ssr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wesley Huber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @pokedocs/plugin-mermaid-ssr — build-time mermaid rendering (PRD F1.3).
+ *
+ * Every mermaid code fence compiles to inline SVG during the build (S1.3.1),
+ * the verbatim source is preserved in a data attribute for AI agents
+ * (S1.3.2), and a syntax error fails the build with file and line (S1.3.3).
+ *
+ * Engine per ADR-0001: rehype-mermaid `inline-svg`. This package is the CJS
+ * wrapper that ADR requires — it defers the ESM-only import to transform
+ * time (the Docusaurus config loader cannot import ESM), and shares ONE
+ * inner transformer across all files (a per-file transformer launches a
+ * browser per file and costs 12x).
+ */
+import { type HastNode } from './preserve-source.js';
+export interface MermaidSsrOptions {
+    /**
+     * Keep the raw mermaid source on the wrapper element as
+     * `data-mermaid-source` (S1.3.2). Defaults to true — this is the
+     * agent-readability contract; turning it off violates the PRD's
+     * "mermaid sources are never discarded" rule.
+     */
+    preserveSource?: boolean;
+    /** Mermaid theme variables forwarded to mermaid.initialize. */
+    themeVariables?: Record<string, string>;
+    /** Full mermaid config passthrough (merged over themeVariables). */
+    mermaidConfig?: Record<string, unknown>;
+}
+/**
+ * Engine decision (ADR-0001, S1.3.4): rehype-mermaid `inline-svg`, wrapped in
+ * this CJS package with a deferred ESM import, ONE shared transformer across
+ * all files (per-file transformers cost 12x), and a source-preservation
+ * pre-pass. mermaid-cli was rejected: slower, a second CI browser, and no
+ * file/line error story.
+ */
+export declare const MERMAID_SSR_ENGINE = "rehype-mermaid";
+/** CSS class on the wrapper that carries the preserved source. */
+export declare const WRAPPER_CLASS = "pokedocs-mermaid";
+interface VFileLike {
+    path?: string;
+    fail(reason: string, place?: unknown, origin?: string): never;
+}
+/**
+ * The rehype plugin. Wire it into the Docusaurus docs pipeline via
+ * `beforeDefaultRehypePlugins` (the preset does this automatically once
+ * S1.2.1 lands). `markdown.mermaid` and `@docusaurus/theme-mermaid` must be
+ * OFF — otherwise fences become React components before rehype sees them.
+ */
+export declare function rehypeMermaidSsr(options?: MermaidSsrOptions): (tree: HastNode, file: VFileLike) => Promise<void>;
+export default rehypeMermaidSsr;
+export { wrapMermaidFences } from './preserve-source.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAEL,KAAK,QAAQ,EAEd,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD,kEAAkE;AAClE,eAAO,MAAM,aAAa,qBAAqB,CAAC;AAIhD,UAAU,SAAS;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC/D;AA8CD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,IAEhD,MAAM,QAAQ,EAAE,MAAM,SAAS,KAAG,OAAO,CAAC,IAAI,CAAC,CAW9D;AAED,eAAe,gBAAgB,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * @pokedocs/plugin-mermaid-ssr — build-time mermaid rendering (PRD F1.3).
+ *
+ * Every mermaid code fence compiles to inline SVG during the build (S1.3.1),
+ * the verbatim source is preserved in a data attribute for AI agents
+ * (S1.3.2), and a syntax error fails the build with file and line (S1.3.3).
+ *
+ * Engine per ADR-0001: rehype-mermaid `inline-svg`. This package is the CJS
+ * wrapper that ADR requires — it defers the ESM-only import to transform
+ * time (the Docusaurus config loader cannot import ESM), and shares ONE
+ * inner transformer across all files (a per-file transformer launches a
+ * browser per file and costs 12x).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapMermaidFences = exports.WRAPPER_CLASS = exports.MERMAID_SSR_ENGINE = void 0;
+exports.rehypeMermaidSsr = rehypeMermaidSsr;
+const preserve_source_js_1 = require("./preserve-source.js");
+/**
+ * Engine decision (ADR-0001, S1.3.4): rehype-mermaid `inline-svg`, wrapped in
+ * this CJS package with a deferred ESM import, ONE shared transformer across
+ * all files (per-file transformers cost 12x), and a source-preservation
+ * pre-pass. mermaid-cli was rejected: slower, a second CI browser, and no
+ * file/line error story.
+ */
+exports.MERMAID_SSR_ENGINE = 'rehype-mermaid';
+/** CSS class on the wrapper that carries the preserved source. */
+exports.WRAPPER_CLASS = 'pokedocs-mermaid';
+// ONE inner transformer per options-shape for the whole build process —
+// mermaid-isomorphic batches diagrams and reuses its in-flight browser only
+// when the transformer instance is shared (ADR-0001 finding: 12x otherwise).
+const transformerCache = new Map();
+async function getInnerTransformer(options) {
+    const key = JSON.stringify([options.themeVariables, options.mermaidConfig]);
+    let cached = transformerCache.get(key);
+    if (!cached) {
+        cached = (async () => {
+            // Dynamic import (preserved as real import() under NodeNext): the
+            // ESM-only engine loads at transform time, never at config time.
+            const { default: rehypeMermaid } = await import('rehype-mermaid');
+            const attacher = rehypeMermaid;
+            return attacher({
+                strategy: 'inline-svg',
+                mermaidConfig: {
+                    ...(options.themeVariables
+                        ? { themeVariables: options.themeVariables }
+                        : {}),
+                    ...options.mermaidConfig,
+                },
+            });
+        })();
+        transformerCache.set(key, cached);
+    }
+    return cached;
+}
+/** Strip rehype-mermaid's serialized hast dump from an error, keep the parse message. */
+function cleanErrorReason(err) {
+    const raw = err.reason ?? err.message ?? String(err);
+    const dumpStart = raw.search(/\n\s*[[{]"/);
+    const message = dumpStart > 0 ? raw.slice(0, dumpStart) : raw;
+    return `Invalid mermaid diagram: ${message.trim()}`;
+}
+/**
+ * The rehype plugin. Wire it into the Docusaurus docs pipeline via
+ * `beforeDefaultRehypePlugins` (the preset does this automatically once
+ * S1.2.1 lands). `markdown.mermaid` and `@docusaurus/theme-mermaid` must be
+ * OFF — otherwise fences become React components before rehype sees them.
+ */
+function rehypeMermaidSsr(options = {}) {
+    const preserve = options.preserveSource !== false;
+    return async (tree, file) => {
+        const wrapped = preserve ? (0, preserve_source_js_1.wrapMermaidFences)(tree) : 0;
+        const transformer = await getInnerTransformer(options);
+        try {
+            await transformer(tree, file);
+        }
+        catch (err) {
+            const e = err;
+            file.fail(cleanErrorReason(e), e.place, 'pokedocs:mermaid-ssr');
+        }
+        void wrapped;
+    };
+}
+exports.default = rehypeMermaidSsr;
+var preserve_source_js_2 = require("./preserve-source.js");
+Object.defineProperty(exports, "wrapMermaidFences", { enumerable: true, get: function () { return preserve_source_js_2.wrapMermaidFences; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AA2FH,4CAaC;AAtGD,6DAI8B;AAgB9B;;;;;;GAMG;AACU,QAAA,kBAAkB,GAAG,gBAAgB,CAAC;AAEnD,kEAAkE;AACrD,QAAA,aAAa,GAAG,kBAAkB,CAAC;AAchD,wEAAwE;AACxE,4EAA4E;AAC5E,6EAA6E;AAC7E,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAgC,CAAC;AAEjE,KAAK,UAAU,mBAAmB,CAChC,OAA0B;IAE1B,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;IAC5E,IAAI,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,CAAC,KAAK,IAAI,EAAE;YACnB,kEAAkE;YAClE,iEAAiE;YACjE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;YAClE,MAAM,QAAQ,GAAG,aAAuD,CAAC;YACzE,OAAO,QAAQ,CAAC;gBACd,QAAQ,EAAE,YAAY;gBACtB,aAAa,EAAE;oBACb,GAAG,CAAC,OAAO,CAAC,cAAc;wBACxB,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE;wBAC5C,CAAC,CAAC,EAAE,CAAC;oBACP,GAAG,OAAO,CAAC,aAAa;iBACzB;aACF,CAAC,CAAC;QACL,CAAC,CAAC,EAAE,CAAC;QACL,gBAAgB,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,yFAAyF;AACzF,SAAS,gBAAgB,CAAC,GAAqB;IAC7C,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;IACrD,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC9D,OAAO,4BAA4B,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,UAA6B,EAAE;IAC9D,MAAM,QAAQ,GAAG,OAAO,CAAC,cAAc,KAAK,KAAK,CAAC;IAClD,OAAO,KAAK,EAAE,IAAc,EAAE,IAAe,EAAiB,EAAE;QAC9D,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAA,sCAAiB,EAAC,IAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtE,MAAM,WAAW,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC;QACvD,IAAI,CAAC;YACH,MAAM,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,GAAuB,CAAC;YAClC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,sBAAsB,CAAC,CAAC;QAClE,CAAC;QACD,KAAK,OAAO,CAAC;IACf,CAAC,CAAC;AACJ,CAAC;AAED,kBAAe,gBAAgB,CAAC;AAChC,2DAAyD;AAAhD,uHAAA,iBAAiB,OAAA"}

package/dist/preserve-source.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Source-preservation pre-pass (S1.3.2, ADR-0001).
+ *
+ * Before the engine replaces each mermaid fence with SVG, wrap the fence in
+ * `<div class="pokedocs-mermaid" data-mermaid-source="…">`. The engine
+ * replaces the inner <pre> in place and leaves the wrapper — so every built
+ * page carries BOTH the rendered SVG and the verbatim mermaid source.
+ *
+ * Hand-rolled hast walk: the unist utilities are ESM-only, and this tiny
+ * traversal isn't worth the interop cost in a CJS package.
+ */
+export interface HastNode {
+    type: string;
+    value?: string;
+    children?: HastNode[];
+}
+export interface HastElement extends HastNode {
+    tagName?: string;
+    properties?: Record<string, unknown>;
+}
+/**
+ * Wrap every mermaid fence in the tree; returns how many were wrapped.
+ * Mutates the tree in place (children arrays are replaced element-wise).
+ */
+export declare function wrapMermaidFences(tree: HastElement): number;
+//# sourceMappingURL=preserve-source.d.ts.map

package/dist/preserve-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preserve-source.d.ts","sourceRoot":"","sources":["../src/preserve-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAoBD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CA0B3D"}

package/dist/preserve-source.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Source-preservation pre-pass (S1.3.2, ADR-0001).
+ *
+ * Before the engine replaces each mermaid fence with SVG, wrap the fence in
+ * `<div class="pokedocs-mermaid" data-mermaid-source="…">`. The engine
+ * replaces the inner <pre> in place and leaves the wrapper — so every built
+ * page carries BOTH the rendered SVG and the verbatim mermaid source.
+ *
+ * Hand-rolled hast walk: the unist utilities are ESM-only, and this tiny
+ * traversal isn't worth the interop cost in a CJS package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapMermaidFences = wrapMermaidFences;
+function textContent(node) {
+    if (node.type === 'text')
+        return node.value ?? '';
+    return (node.children ?? []).map(textContent).join('');
+}
+function isMermaidPre(node) {
+    if (node.tagName !== 'pre')
+        return false;
+    return (node.children ?? []).some((child) => {
+        const el = child;
+        const cls = el.properties?.className;
+        return (el.tagName === 'code' &&
+            Array.isArray(cls) &&
+            cls.some((c) => c === 'language-mermaid' || c === 'mermaid'));
+    });
+}
+/**
+ * Wrap every mermaid fence in the tree; returns how many were wrapped.
+ * Mutates the tree in place (children arrays are replaced element-wise).
+ */
+function wrapMermaidFences(tree) {
+    let wrapped = 0;
+    const walk = (node) => {
+        const children = node.children;
+        if (!children)
+            return;
+        for (let i = 0; i < children.length; i++) {
+            const child = children[i];
+            if (child && isMermaidPre(child)) {
+                const source = textContent(child).trimEnd();
+                children[i] = {
+                    type: 'element',
+                    tagName: 'div',
+                    properties: {
+                        className: ['pokedocs-mermaid'],
+                        dataMermaidSource: source,
+                    },
+                    children: [child],
+                };
+                wrapped++;
+            }
+            else if (child) {
+                walk(child);
+            }
+        }
+    };
+    walk(tree);
+    return wrapped;
+}
+//# sourceMappingURL=preserve-source.js.map

package/dist/preserve-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preserve-source.js","sourceRoot":"","sources":["../src/preserve-source.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAmCH,8CA0BC;AAhDD,SAAS,WAAW,CAAC,IAAc;IACjC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,YAAY,CAAC,IAAiB;IACrC,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACzC,OAAO,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;QAC1C,MAAM,EAAE,GAAG,KAAoB,CAAC;QAChC,MAAM,GAAG,GAAG,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC;QACrC,OAAO,CACL,EAAE,CAAC,OAAO,KAAK,MAAM;YACrB,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAClB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,kBAAkB,IAAI,CAAC,KAAK,SAAS,CAAC,CAC7D,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,IAAiB;IACjD,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,IAAI,GAAG,CAAC,IAAiB,EAAQ,EAAE;QACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAqC,CAAC;QAC5D,IAAI,CAAC,QAAQ;YAAE,OAAO;QACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,KAAK,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjC,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;gBAC5C,QAAQ,CAAC,CAAC,CAAC,GAAG;oBACZ,IAAI,EAAE,SAAS;oBACf,OAAO,EAAE,KAAK;oBACd,UAAU,EAAE;wBACV,SAAS,EAAE,CAAC,kBAAkB,CAAC;wBAC/B,iBAAiB,EAAE,MAAM;qBAC1B;oBACD,QAAQ,EAAE,CAAC,KAAK,CAAC;iBAClB,CAAC;gBACF,OAAO,EAAE,CAAC;YACZ,CAAC;iBAAM,IAAI,KAAK,EAAE,CAAC;gBACjB,IAAI,CAAC,KAAK,CAAC,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,IAAI,CAAC,IAAI,CAAC,CAAC;IACX,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@pokedocs/plugin-mermaid-ssr",
+  "version": "0.1.0",
+  "description": "Build-time mermaid rendering for Docusaurus — SVG baked into static HTML, source preserved for agents, build fails on bad syntax",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wbaxterh/pokedocs.git",
+    "directory": "packages/plugin-mermaid-ssr"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "playwright": "^1.61.1",
+    "rehype-mermaid": "^3.0.0"
+  }
+}