docusaurus-plugin-docusynx 0.1.1 → 0.1.3

package/dist/assets.d.ts

@@ -3,5 +3,6 @@ export declare class AssetCollector {
     #private;
     constructor(outputDirectory: string);
     add(sourcePath: string, mimeType?: string): Promise<string>;
+    addBytes(content: string | Uint8Array, extension: string, mimeType?: string): Promise<string>;
     values(): BundleAsset[];
 }

package/dist/assets.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
-import { copyFile, mkdir, readFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { assertSafeSvg } from './svg.js';
 const MIME_BY_EXTENSION = {
     '.gif': 'image/gif',
     '.jpeg': 'image/jpeg',
@@ -17,21 +18,47 @@ export class AssetCollector {
     }
     async add(sourcePath, mimeType) {
         const bytes = await readFile(sourcePath);
+        return this.addBytes(bytes, path.extname(sourcePath).toLowerCase(), mimeType);
+    }
+    async addBytes(content, extension, mimeType) {
+        if (!/^\.[a-z0-9]+$/.test(extension)) {
+            throw new Error(`invalid asset extension ${JSON.stringify(extension)}`);
+        }
+        const bytes = typeof content === 'string' ? Buffer.from(content, 'utf8') : content;
         const digest = createHash('sha256').update(bytes).digest('hex');
-        const extension = path.extname(sourcePath).toLowerCase();
         const id = `sha256:${digest}`;
         const relativePath = `assets/${digest}${extension}`;
-        if (!this.#assets.has(id)) {
+        const resolvedMimeType = mimeType ??
+            MIME_BY_EXTENSION[extension] ??
+            'application/octet-stream';
+        if (extension === '.svg' ||
+            resolvedMimeType.split(';', 1)[0]?.trim().toLowerCase() ===
+                'image/svg+xml') {
+            let svg;
+            try {
+                svg = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            }
+            catch {
+                throw new Error('unsafe SVG content: invalid UTF-8');
+            }
+            assertSafeSvg(svg);
+        }
+        const existing = this.#assets.get(id);
+        if (existing) {
+            if (existing.path !== relativePath ||
+                existing.mimeType !== resolvedMimeType) {
+                throw new Error(`asset metadata conflicts for ${id}`);
+            }
+        }
+        else {
             await mkdir(path.join(this.#outputDirectory, 'assets'), {
                 recursive: true,
             });
-            await copyFile(sourcePath, path.join(this.#outputDirectory, relativePath));
+            await writeFile(path.join(this.#outputDirectory, relativePath), bytes);
             this.#assets.set(id, {
                 id,
                 path: relativePath,
-                mimeType: mimeType ??
-                    MIME_BY_EXTENSION[extension] ??
-                    'application/octet-stream',
+                mimeType: resolvedMimeType,
                 hash: id,
             });
         }

package/dist/diagram-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/diagram-worker.js

@@ -0,0 +1,152 @@
+import { createHash } from 'node:crypto';
+import { parentPort, workerData } from 'node:worker_threads';
+import { assertSafeSvg } from './svg.js';
+const input = workerData;
+async function renderMermaid(source) {
+    const [{ createHTMLWindow }, { default: createDOMPurify }, { JSDOM }] = await Promise.all([
+        import('svgdom'),
+        import('dompurify'),
+        import('jsdom'),
+    ]);
+    const purificationWindow = new JSDOM('').window;
+    Object.assign(createDOMPurify, createDOMPurify(purificationWindow));
+    Object.defineProperty(globalThis, 'CSSStyleSheet', {
+        configurable: true,
+        value: purificationWindow.CSSStyleSheet,
+    });
+    const window = createHTMLWindow();
+    Object.assign(globalThis, { window, document: window.document });
+    const { default: mermaid } = await import('mermaid');
+    const digest = createHash('sha256').update(source).digest('hex');
+    mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: 'strict',
+        htmlLabels: false,
+        flowchart: {
+            htmlLabels: false,
+        },
+        deterministicIds: true,
+        deterministicIDSeed: digest,
+        theme: 'neutral',
+    });
+    const { svg } = await mermaid.render(`docusynx-${digest.slice(0, 16)}`, source);
+    return normalizeSvg(svg);
+}
+async function renderExcalidraw(source) {
+    const { JSDOM } = await import('jsdom');
+    const dom = new JSDOM('<!doctype html><html><body></body></html>', {
+        pretendToBeVisual: true,
+        url: 'http://localhost/',
+    });
+    installDomGlobals(dom.window);
+    const scene = parseExcalidraw(source);
+    validateExcalidrawFiles(scene.files ?? {});
+    const excalidraw = (await import('@excalidraw/utils'));
+    const svg = await excalidraw.exportToSvg({
+        data: {
+            elements: scene.elements,
+            appState: {
+                exportBackground: scene.appState?.exportBackground !== false,
+                exportPadding: scene.appState?.exportPadding,
+                exportScale: 1,
+                viewBackgroundColor: scene.appState?.viewBackgroundColor ?? '#ffffff',
+                exportWithDarkMode: false,
+                exportEmbedScene: false,
+            },
+            files: (scene.files ?? {}),
+        },
+        config: { skipInliningFonts: true },
+    });
+    return normalizeSvg(svg.outerHTML);
+}
+function parseExcalidraw(source) {
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch (error) {
+        throw new Error(`invalid Excalidraw JSON: ${errorMessage(error)}`);
+    }
+    if (typeof value !== 'object' ||
+        value === null ||
+        !('type' in value) ||
+        value.type !== 'excalidraw' ||
+        !('elements' in value) ||
+        !Array.isArray(value.elements)) {
+        throw new Error('invalid Excalidraw scene');
+    }
+    return value;
+}
+function validateExcalidrawFiles(files) {
+    for (const [fileID, file] of Object.entries(files)) {
+        if (typeof file !== 'object' ||
+            file === null ||
+            !('dataURL' in file) ||
+            typeof file.dataURL !== 'string' ||
+            !isSafeRasterDataURL(file.dataURL)) {
+            throw new Error(`Excalidraw file ${JSON.stringify(fileID)} must use a base64 raster data URL`);
+        }
+    }
+}
+function installDomGlobals(window) {
+    const values = window;
+    for (const name of [
+        'Blob',
+        'CSSStyleDeclaration',
+        'CSSStyleSheet',
+        'DOMParser',
+        'Element',
+        'FileReader',
+        'HTMLCanvasElement',
+        'HTMLElement',
+        'HTMLImageElement',
+        'Image',
+        'Node',
+        'SVGElement',
+        'XMLSerializer',
+        'document',
+        'getComputedStyle',
+        'navigator',
+        'window',
+    ]) {
+        Object.defineProperty(globalThis, name, {
+            configurable: true,
+            value: values[name],
+        });
+    }
+    Object.defineProperty(globalThis, 'devicePixelRatio', {
+        configurable: true,
+        value: 1,
+    });
+    Object.defineProperty(globalThis, 'requestAnimationFrame', {
+        configurable: true,
+        value: (callback) => setTimeout(() => callback(0), 0),
+    });
+    Object.defineProperty(globalThis, 'cancelAnimationFrame', {
+        configurable: true,
+        value: clearTimeout,
+    });
+    Object.defineProperty(globalThis, 'ResizeObserver', {
+        configurable: true,
+        value: class {
+            observe() { }
+            unobserve() { }
+            disconnect() { }
+        },
+    });
+}
+function normalizeSvg(svg) {
+    const normalized = svg.replaceAll('\r\n', '\n').trim();
+    assertSafeSvg(normalized);
+    return normalized + '\n';
+}
+function isSafeRasterDataURL(value) {
+    return /^data:image\/(?:avif|gif|jpeg|png|webp);base64,[a-z0-9+/]+={0,2}$/i.test(value);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+const svg = input.kind === 'mermaid'
+    ? await renderMermaid(input.source)
+    : await renderExcalidraw(input.source);
+parentPort?.postMessage({ svg });

package/dist/diagrams.d.ts

@@ -0,0 +1,4 @@
+export type DiagramKind = 'excalidraw' | 'mermaid';
+export declare function renderDiagramSvg(kind: DiagramKind, source: string): Promise<string>;
+export declare function renderMermaidSvg(source: string): Promise<string>;
+export declare function renderExcalidrawSvg(source: string): Promise<string>;

package/dist/diagrams.js

@@ -0,0 +1,60 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+const RENDER_TIMEOUT_MS = 30_000;
+export async function renderDiagramSvg(kind, source) {
+    if (!source.trim())
+        throw new Error(`${kind} source is empty`);
+    return new Promise((resolve, reject) => {
+        const worker = new Worker(diagramWorkerUrl(), {
+            workerData: { kind, source },
+        });
+        let settled = false;
+        const timeout = setTimeout(() => {
+            settled = true;
+            void worker.terminate();
+            reject(new Error(`${kind} renderer timed out`));
+        }, RENDER_TIMEOUT_MS);
+        worker.once('message', (message) => {
+            clearTimeout(timeout);
+            settled = true;
+            if (typeof message !== 'object' ||
+                message === null ||
+                !('svg' in message) ||
+                typeof message.svg !== 'string') {
+                reject(new Error(`${kind} renderer returned an invalid response`));
+                return;
+            }
+            resolve(message.svg);
+        });
+        worker.once('error', (error) => {
+            clearTimeout(timeout);
+            settled = true;
+            reject(error);
+        });
+        worker.once('exit', (code) => {
+            clearTimeout(timeout);
+            if (!settled && code !== 0) {
+                reject(new Error(`${kind} renderer exited with code ${code}`));
+            }
+            else if (!settled) {
+                reject(new Error(`${kind} renderer exited without an SVG`));
+            }
+        });
+    });
+}
+function diagramWorkerUrl() {
+    const adjacent = new URL('./diagram-worker.js', import.meta.url);
+    if (existsSync(fileURLToPath(adjacent)))
+        return adjacent;
+    const built = new URL('../dist/diagram-worker.js', import.meta.url);
+    if (existsSync(fileURLToPath(built)))
+        return built;
+    return adjacent;
+}
+export async function renderMermaidSvg(source) {
+    return renderDiagramSvg('mermaid', source);
+}
+export async function renderExcalidrawSvg(source) {
+    return renderDiagramSvg('excalidraw', source);
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { default } from './plugin.js';
 export { contentHash, canonicalJson } from './canonical.js';
+export { renderDiagramSvg, renderExcalidrawSvg, renderMermaidSvg, } from './diagrams.js';
 export { defineComponentHandler } from './types.js';
+export type { DiagramKind } from './diagrams.js';
 export type { Block, BundleAsset, BundleDocument, BundleSource, ComponentHandler, ComponentHandlerAssetInput, ComponentHandlerContext, ComponentHandlerRegistration, DocumentBundle, Inline, LinkInline, MdxAstNode, PluginOptions, TextInline, TextMark, } from './types.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { default } from './plugin.js';
 export { contentHash, canonicalJson } from './canonical.js';
+export { renderDiagramSvg, renderExcalidrawSvg, renderMermaidSvg, } from './diagrams.js';
 export { defineComponentHandler } from './types.js';

package/dist/markdown.js

@@ -184,7 +184,9 @@ async function transformComponent(node, context) {
         siteDir: context.siteDir,
         sourcePath: context.sourcePath,
         readSiteFile: async (requestedPath) => readFile(resolveSitePath(context.siteDir, requestedPath), 'utf8'),
-        addAsset: async (input) => context.assets.add(resolveSitePath(context.siteDir, input.path), input.mimeType),
+        addAsset: async (input) => 'path' in input
+            ? context.assets.add(resolveSitePath(context.siteDir, input.path), input.mimeType)
+            : context.assets.addBytes(input.content, input.extension, input.mimeType),
         transformChildren: async () => transformBlockChildren(children, context),
     };
     const result = await handler.transform(handlerContext);

package/dist/svg.d.ts

@@ -0,0 +1 @@
+export declare function assertSafeSvg(svg: string): void;

package/dist/svg.js

@@ -0,0 +1,223 @@
+import { createRequire } from 'node:module';
+import { JSDOM } from 'jsdom';
+const cssTree = createRequire(import.meta.url)('css-tree');
+const cssValueAttributes = new Set([
+    'clip-path',
+    'color',
+    'cursor',
+    'fill',
+    'filter',
+    'flood-color',
+    'lighting-color',
+    'marker-end',
+    'marker-mid',
+    'marker-start',
+    'mask',
+    'stop-color',
+    'stroke',
+]);
+const externalCssFunctions = new Set(['cross-fade', '-webkit-cross-fade', 'image', 'image-set', '-webkit-image-set', 'src']);
+const unsafeSvgElements = new Set(['animate', 'animatecolor', 'animatemotion', 'animatetransform', 'foreignobject', 'script', 'set']);
+const xmlDeclaration = /^\s*<\?xml\s+version\s*=\s*(?:"1\.0"|'1\.0')(?:\s+encoding\s*=\s*(?:"[Uu][Tt][Ff]-8"|'[Uu][Tt][Ff]-8'))?(?:\s+standalone\s*=\s*(?:"(?:yes|no)"|'(?:yes|no)'))?\s*\?>/;
+export function assertSafeSvg(svg) {
+    if (/<!doctype\b/i.test(svg)) {
+        throw unsafe('document type declaration');
+    }
+    const declaration = svg.match(xmlDeclaration)?.[0] ?? '';
+    if (/<\?/.test(svg.slice(declaration.length))) {
+        throw unsafe('processing instruction');
+    }
+    let document;
+    try {
+        document = new JSDOM(svg, { contentType: 'image/svg+xml' }).window.document;
+    }
+    catch (error) {
+        throw unsafe(`invalid XML: ${errorMessage(error)}`);
+    }
+    if (document.doctype) {
+        throw unsafe('document type declaration');
+    }
+    for (const child of document.childNodes) {
+        if (child.nodeType === child.PROCESSING_INSTRUCTION_NODE) {
+            throw unsafe('processing instruction');
+        }
+    }
+    const root = document.documentElement;
+    if (root.localName.toLowerCase() !== 'svg' || (root.namespaceURI && root.namespaceURI !== 'http://www.w3.org/2000/svg')) {
+        throw unsafe('invalid root element');
+    }
+    for (const element of document.querySelectorAll('*')) {
+        const elementName = element.localName.toLowerCase();
+        if (unsafeSvgElements.has(elementName)) {
+            throw unsafe(elementName);
+        }
+        if (elementName === 'style') {
+            validateCss(element.textContent ?? '', 'stylesheet');
+        }
+        for (const attribute of element.attributes) {
+            const name = attribute.localName.toLowerCase();
+            if (name === 'base' && attribute.namespaceURI === 'http://www.w3.org/XML/1998/namespace') {
+                throw unsafe('xml:base attribute');
+            }
+            if (name.startsWith('on')) {
+                throw unsafe('event handler');
+            }
+            if (name === 'href' || name === 'src') {
+                validateReference(elementName, attribute.value);
+            }
+            else if (name === 'style') {
+                validateCss(attribute.value, 'declarationList');
+            }
+            else if (cssValueAttributes.has(name)) {
+                validateCss(attribute.value, 'value');
+            }
+        }
+    }
+}
+function validateReference(elementName, reference) {
+    const navigation = elementName === 'a' && /^(?:https?:|mailto:|#)/i.test(reference);
+    if (!navigation && !reference.startsWith('#') && !isSafeRasterDataUrl(reference)) {
+        throw unsafe('external reference');
+    }
+}
+function validateCss(source, context) {
+    const canonical = canonicalizeCss(source);
+    assertBalancedCss(canonical);
+    let ast;
+    try {
+        ast = cssTree.parse(canonical, {
+            context,
+            onParseError(error) {
+                throw error;
+            },
+        });
+    }
+    catch (error) {
+        throw unsafe(`invalid CSS: ${errorMessage(error)}`);
+    }
+    cssTree.walk(ast, (node) => {
+        const name = typeof node.name === 'string' ? node.name.toLowerCase() : undefined;
+        if (node.type === 'Atrule' && name === 'import') {
+            throw unsafe('CSS import');
+        }
+        if (node.type === 'Url') {
+            if (typeof node.value !== 'string' || !node.value.startsWith('#')) {
+                throw unsafe('CSS external reference');
+            }
+        }
+        if (node.type === 'Function' && name && externalCssFunctions.has(name)) {
+            throw unsafe('CSS external resource function');
+        }
+        if (node.type === 'Raw' && /(?:@import\b|\burl\s*\()/i.test(node.value ?? '')) {
+            throw unsafe('CSS external reference');
+        }
+    });
+}
+function assertBalancedCss(source) {
+    const pairs = { '(': ')', '[': ']', '{': '}' };
+    const closing = new Set(Object.values(pairs));
+    const stack = [];
+    let quote = '';
+    for (let index = 0; index < source.length; index += 1) {
+        const character = source[index];
+        if (quote) {
+            if (character === '\\') {
+                index += 1;
+            }
+            else if (character === quote) {
+                quote = '';
+            }
+            else if (/[\n\r\f]/.test(character)) {
+                throw unsafe('invalid CSS string');
+            }
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+        }
+        else if (pairs[character]) {
+            stack.push(character);
+        }
+        else if (closing.has(character)) {
+            const open = stack.pop();
+            if (!open || pairs[open] !== character) {
+                throw unsafe('unbalanced CSS delimiter');
+            }
+        }
+    }
+    if (quote || stack.length > 0) {
+        throw unsafe('unbalanced CSS delimiter');
+    }
+}
+function canonicalizeCss(source) {
+    let output = '';
+    let quote = '';
+    for (let index = 0; index < source.length;) {
+        const character = source[index];
+        if (!quote && character === '/' && source[index + 1] === '*') {
+            const end = source.indexOf('*/', index + 2);
+            if (end < 0) {
+                throw unsafe('invalid CSS comment');
+            }
+            index = end + 2;
+            continue;
+        }
+        if (character === '\\') {
+            const decoded = decodeCssEscape(source, index);
+            if (quote && (decoded.value === quote || decoded.value === '\\')) {
+                output += '\\';
+            }
+            output += decoded.value;
+            index = decoded.next;
+            continue;
+        }
+        output += character;
+        index += 1;
+        if ((character === '"' || character === "'") && (!quote || quote === character)) {
+            quote = quote ? '' : character;
+        }
+    }
+    if (quote) {
+        throw unsafe('invalid CSS string');
+    }
+    if (output.includes('/*') || output.includes('*/')) {
+        throw unsafe('invalid CSS comment');
+    }
+    return output;
+}
+function decodeCssEscape(source, start) {
+    let index = start + 1;
+    if (index >= source.length || /[\n\r\f]/.test(source[index])) {
+        throw unsafe('invalid CSS escape');
+    }
+    let hex = '';
+    while (index < source.length && hex.length < 6 && /[0-9a-f]/i.test(source[index])) {
+        hex += source[index];
+        index += 1;
+    }
+    if (!hex) {
+        const codePoint = source.codePointAt(index);
+        return { value: String.fromCodePoint(codePoint), next: index + (codePoint > 0xffff ? 2 : 1) };
+    }
+    if (index < source.length && /[\t\n\f\r ]/.test(source[index])) {
+        if (source[index] === '\r' && source[index + 1] === '\n')
+            index += 1;
+        index += 1;
+    }
+    const codePoint = Number.parseInt(hex, 16);
+    return {
+        value: codePoint === 0 || codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)
+            ? '\ufffd'
+            : String.fromCodePoint(codePoint),
+        next: index,
+    };
+}
+function isSafeRasterDataUrl(value) {
+    return /^data:image\/(?:avif|gif|jpeg|png|webp);base64,[a-z0-9+/]+={0,2}$/i.test(value);
+}
+function unsafe(detail) {
+    return new Error(`unsafe SVG content: ${detail}`);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/types.d.ts

@@ -98,10 +98,14 @@ export interface DocumentBundle {
     assets: BundleAsset[];
     hash: string;
 }
-export interface ComponentHandlerAssetInput {
+export type ComponentHandlerAssetInput = {
     path: string;
     mimeType?: string;
-}
+} | {
+    content: string | Uint8Array;
+    extension: '.svg';
+    mimeType: 'image/svg+xml';
+};
 export interface ComponentHandlerContext {
     readonly node: MdxAstNode;
     readonly props: Readonly<Record<string, unknown>>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "docusaurus-plugin-docusynx",
-    "version": "0.1.1",
+    "version": "0.1.3",
     "description": "Export a deterministic Docusaurus document bundle for docusynx",
     "license": "Apache-2.0",
     "repository": {
@@ -35,7 +35,7 @@
         "README.md"
     ],
     "engines": {
-        "node": ">=20"
+        "node": ">=22.13"
     },
     "peerDependencies": {
         "@docusaurus/core": "^3.10.0"
@@ -50,25 +50,33 @@
         "registry": "https://registry.npmjs.org/"
     },
     "dependencies": {
+        "@excalidraw/utils": "0.1.5",
         "cheerio": "1.0.0",
+        "css-tree": "2.3.1",
         "domhandler": "5.0.3",
+        "dompurify": "3.4.15",
         "gray-matter": "4.0.3",
+        "jsdom": "26.1.0",
         "mdast-util-to-string": "4.0.0",
+        "mermaid": "11.17.2",
         "remark-directive": "4.0.0",
         "remark-frontmatter": "5.0.0",
         "remark-gfm": "4.0.1",
         "remark-mdx": "3.1.1",
         "remark-parse": "11.0.0",
+        "svgdom": "0.1.29",
         "unified": "11.0.5"
     },
     "devDependencies": {
+        "@types/jsdom": "21.1.7",
         "@types/node": "22.15.3",
+        "@types/svgdom": "0.1.2",
         "typescript": "5.8.3",
         "vitest": "3.1.2"
     },
     "scripts": {
         "build": "tsc -p tsconfig.build.json",
-        "test": "vitest run",
+        "test": "pnpm build && vitest run",
         "typecheck": "tsc -p tsconfig.json --noEmit"
     }
 }