@matfsw/docusaurus-plantuml-plugin 0.1.0

package/dist/options.js

@@ -0,0 +1,131 @@
+import { PLUGIN_NAME } from './constants.js';
+export const DEFAULT_OPTIONS = {
+    languages: ['plantuml', 'puml'],
+    theme: 'auto',
+    lazy: true,
+    cache: 'memory',
+    sanitizeSvg: true,
+    showSourceOnError: true,
+    renderTimeoutMs: 20_000,
+    cacheMaxEntries: 50,
+};
+const CACHE_MODES = ['none', 'memory', 'session'];
+const THEMES = ['auto', 'light', 'dark'];
+const MIN_RENDER_TIMEOUT_MS = 100;
+const MAX_RENDER_TIMEOUT_MS = 600_000;
+/** Thrown for invalid plugin options so Docusaurus fails the build with a useful message. */
+export class PlantUmlOptionsError extends Error {
+    constructor(message) {
+        super(`[${PLUGIN_NAME}] ${message}`);
+        this.name = 'PlantUmlOptionsError';
+    }
+}
+function fail(message) {
+    throw new PlantUmlOptionsError(message);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function quoteList(values) {
+    return values.map((value) => `'${value}'`).join(', ');
+}
+function validateBoolean(value, key, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean') {
+        fail(`options.${key} must be a boolean, received ${JSON.stringify(value)}.`);
+    }
+    return value;
+}
+function validateLanguages(value) {
+    if (value === undefined)
+        return [...DEFAULT_OPTIONS.languages];
+    if (!Array.isArray(value)) {
+        fail(`options.languages must be an array of strings, received ${JSON.stringify(value)}.`);
+    }
+    if (value.length === 0) {
+        fail('options.languages must contain at least one language.');
+    }
+    const normalized = value.map((entry, index) => {
+        if (typeof entry !== 'string' || entry.trim() === '') {
+            fail(`options.languages[${index}] must be a non-empty string, received ${JSON.stringify(entry)}.`);
+        }
+        return entry.trim().toLowerCase();
+    });
+    const duplicates = normalized.filter((entry, index) => normalized.indexOf(entry) !== index);
+    if (duplicates.length > 0) {
+        fail(`options.languages contains duplicate entries: ${quoteList([...new Set(duplicates)])}.`);
+    }
+    return normalized;
+}
+function validateRenderTimeout(value) {
+    if (value === undefined)
+        return DEFAULT_OPTIONS.renderTimeoutMs;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        fail(`options.renderTimeoutMs must be a finite number, received ${JSON.stringify(value)}.`);
+    }
+    if (!Number.isInteger(value)) {
+        fail(`options.renderTimeoutMs must be an integer, received ${value}.`);
+    }
+    if (value < MIN_RENDER_TIMEOUT_MS || value > MAX_RENDER_TIMEOUT_MS) {
+        fail(`options.renderTimeoutMs must be between ${MIN_RENDER_TIMEOUT_MS} and ` +
+            `${MAX_RENDER_TIMEOUT_MS} milliseconds, received ${value}.`);
+    }
+    return value;
+}
+function validateCacheMaxEntries(value) {
+    if (value === undefined)
+        return DEFAULT_OPTIONS.cacheMaxEntries;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+        fail(`options.cacheMaxEntries must be a positive integer, received ${JSON.stringify(value)}.`);
+    }
+    return value;
+}
+/**
+ * Validates raw plugin options and applies defaults.
+ *
+ * Unknown keys are rejected rather than ignored: a typo in `docusaurus.config.ts` would
+ * otherwise silently disable the option the author meant to set.
+ */
+export function resolveOptions(rawOptions) {
+    if (rawOptions === undefined || rawOptions === null) {
+        return { ...DEFAULT_OPTIONS, languages: [...DEFAULT_OPTIONS.languages] };
+    }
+    if (!isPlainObject(rawOptions)) {
+        fail(`options must be an object, received ${JSON.stringify(rawOptions)}.`);
+    }
+    const allowedKeys = new Set([
+        'languages',
+        'theme',
+        'lazy',
+        'cache',
+        'sanitizeSvg',
+        'showSourceOnError',
+        'renderTimeoutMs',
+        'cacheMaxEntries',
+        // Docusaurus injects `id` for multi-instance plugins.
+        'id',
+    ]);
+    const unknownKeys = Object.keys(rawOptions).filter((key) => !allowedKeys.has(key));
+    if (unknownKeys.length > 0) {
+        fail(`Unknown option${unknownKeys.length > 1 ? 's' : ''} ${quoteList(unknownKeys)}. ` +
+            `Supported options: ${quoteList([...allowedKeys].filter((key) => key !== 'id'))}.`);
+    }
+    const { theme, cache } = rawOptions;
+    if (theme !== undefined && !THEMES.includes(theme)) {
+        fail(`options.theme must be one of ${quoteList(THEMES)}, received ${JSON.stringify(theme)}.`);
+    }
+    if (cache !== undefined && !CACHE_MODES.includes(cache)) {
+        fail(`options.cache must be one of ${quoteList(CACHE_MODES)}, received ${JSON.stringify(cache)}.`);
+    }
+    return {
+        languages: validateLanguages(rawOptions.languages),
+        theme: theme ?? DEFAULT_OPTIONS.theme,
+        lazy: validateBoolean(rawOptions.lazy, 'lazy', DEFAULT_OPTIONS.lazy),
+        cache: cache ?? DEFAULT_OPTIONS.cache,
+        sanitizeSvg: validateBoolean(rawOptions.sanitizeSvg, 'sanitizeSvg', DEFAULT_OPTIONS.sanitizeSvg),
+        showSourceOnError: validateBoolean(rawOptions.showSourceOnError, 'showSourceOnError', DEFAULT_OPTIONS.showSourceOnError),
+        renderTimeoutMs: validateRenderTimeout(rawOptions.renderTimeoutMs),
+        cacheMaxEntries: validateCacheMaxEntries(rawOptions.cacheMaxEntries),
+    };
+}

package/dist/runtime/assetLoader.d.ts

@@ -0,0 +1,23 @@
+import type { PlantUmlCoreModule } from './types.js';
+export interface LoadRuntimeOptions {
+    /** Absolute, `baseUrl`-prefixed directory URL containing the two runtime files. */
+    assetsBaseUrl: string;
+    /** Give up if the runtime has not loaded within this many milliseconds. */
+    timeoutMs: number;
+    /**
+     * Seam for tests: the real implementation is a bundler-ignored dynamic import, which
+     * cannot run under a Node test runner.
+     */
+    importModule?: (url: string) => Promise<unknown>;
+}
+/**
+ * Resolves the PlantUML engine, loading it on first use.
+ *
+ * Concurrent callers share one in-flight promise; a failed load clears the cache so a later
+ * diagram can retry rather than inheriting a permanent failure.
+ */
+export declare function loadPlantUmlRuntime(options: LoadRuntimeOptions): Promise<PlantUmlCoreModule>;
+/** Whether the runtime has been requested on this page. Used by tests and diagnostics. */
+export declare function isRuntimeRequested(): boolean;
+/** Test-only: forgets the cached runtime and removes the injected script tag. */
+export declare function resetRuntimeLoader(): void;

package/dist/runtime/assetLoader.js

@@ -0,0 +1,125 @@
+import { PLANTUML_MODULE_FILENAME, VIZ_SCRIPT_FILENAME } from '../constants.js';
+import { PlantUmlError } from './errors.js';
+/**
+ * Loads the PlantUML browser runtime exactly once per page session.
+ *
+ * `viz-global.js` is a classic script that installs the Graphviz layout engine on `window`,
+ * and it must have finished executing before `plantuml.js` is imported. Both files are
+ * served from the Docusaurus origin under `baseUrl`, never from a CDN.
+ */
+const SCRIPT_MARKER = 'data-plantuml-runtime';
+let cachedRuntime = null;
+function isBrowser() {
+    return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+function joinUrl(base, file) {
+    return `${base.replace(/\/+$/, '')}/${file}`;
+}
+function defaultImportModule(url) {
+    // webpackIgnore keeps this a real runtime import of a copied asset instead of letting
+    // webpack try to bundle the 6.8 MB engine into the site's JavaScript.
+    return import(/* webpackIgnore: true */ url);
+}
+/**
+ * Injects `viz-global.js` as a classic script, reusing an existing tag.
+ *
+ * Client-side navigation re-mounts diagram components but does not reload the document, so
+ * the marker attribute is what keeps a second `<script>` from ever being appended.
+ */
+function loadVizGlobal(url, timeoutMs) {
+    const existing = document.querySelector(`script[${SCRIPT_MARKER}]`);
+    if (existing) {
+        if (existing.dataset.plantumlRuntimeState === 'loaded')
+            return Promise.resolve();
+        if (existing.dataset.plantumlRuntimeState === 'error') {
+            return Promise.reject(new PlantUmlError('load', `Failed to load the PlantUML Graphviz runtime from ${url}.`));
+        }
+        return waitForScript(existing, url, timeoutMs);
+    }
+    const script = document.createElement('script');
+    script.setAttribute(SCRIPT_MARKER, '');
+    script.dataset.plantumlRuntimeState = 'loading';
+    script.async = false;
+    script.src = url;
+    const promise = waitForScript(script, url, timeoutMs);
+    document.head.appendChild(script);
+    return promise;
+}
+function waitForScript(script, url, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let done = false;
+        const finish = (fn) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            script.removeEventListener('load', onLoad);
+            script.removeEventListener('error', onError);
+            fn();
+        };
+        const onLoad = () => {
+            script.dataset.plantumlRuntimeState = 'loaded';
+            finish(resolve);
+        };
+        const onError = () => {
+            script.dataset.plantumlRuntimeState = 'error';
+            finish(() => reject(new PlantUmlError('load', `Failed to load the PlantUML Graphviz runtime from ${url}. ` +
+                'Check that the asset is served under your Docusaurus baseUrl with a JavaScript MIME type.')));
+        };
+        const timer = setTimeout(() => {
+            finish(() => reject(new PlantUmlError('load', `Timed out after ${timeoutMs} ms loading ${url}.`)));
+        }, timeoutMs);
+        script.addEventListener('load', onLoad);
+        script.addEventListener('error', onError);
+    });
+}
+function assertCoreModule(value, url) {
+    const candidate = value;
+    if (!candidate ||
+        typeof candidate.render !== 'function' ||
+        typeof candidate.renderToString !== 'function') {
+        throw new PlantUmlError('load', `The module at ${url} does not export the expected PlantUML render functions. ` +
+            'This usually means a proxy or service worker returned the wrong file.');
+    }
+    return candidate;
+}
+/**
+ * Resolves the PlantUML engine, loading it on first use.
+ *
+ * Concurrent callers share one in-flight promise; a failed load clears the cache so a later
+ * diagram can retry rather than inheriting a permanent failure.
+ */
+export function loadPlantUmlRuntime(options) {
+    if (!isBrowser()) {
+        return Promise.reject(new PlantUmlError('load', 'The PlantUML runtime cannot be loaded during server-side rendering.'));
+    }
+    if (cachedRuntime)
+        return cachedRuntime;
+    const { assetsBaseUrl, timeoutMs, importModule = defaultImportModule } = options;
+    const vizUrl = joinUrl(assetsBaseUrl, VIZ_SCRIPT_FILENAME);
+    const moduleUrl = joinUrl(assetsBaseUrl, PLANTUML_MODULE_FILENAME);
+    const runtime = loadVizGlobal(vizUrl, timeoutMs)
+        .then(() => importModule(moduleUrl))
+        .then((module) => assertCoreModule(module, moduleUrl))
+        .catch((error) => {
+        cachedRuntime = null;
+        throw error instanceof PlantUmlError
+            ? error
+            : new PlantUmlError('load', `Failed to load the PlantUML engine from ${moduleUrl}.`, {
+                cause: error,
+            });
+    });
+    cachedRuntime = runtime;
+    return runtime;
+}
+/** Whether the runtime has been requested on this page. Used by tests and diagnostics. */
+export function isRuntimeRequested() {
+    return cachedRuntime !== null;
+}
+/** Test-only: forgets the cached runtime and removes the injected script tag. */
+export function resetRuntimeLoader() {
+    cachedRuntime = null;
+    if (typeof document !== 'undefined') {
+        document.querySelectorAll(`script[${SCRIPT_MARKER}]`).forEach((node) => node.remove());
+    }
+}

package/dist/runtime/cache.d.ts

@@ -0,0 +1,20 @@
+import type { CacheMode } from '../options.js';
+export interface CacheKeyInput {
+    source: string;
+    dark: boolean;
+    sanitized: boolean;
+    coreVersion: string;
+}
+export interface DiagramCache {
+    readonly mode: CacheMode;
+    get(key: string): string | undefined;
+    set(key: string, svg: string): void;
+    clear(): void;
+    /** Number of entries currently held. Exposed for tests and the documented size limit. */
+    size(): number;
+}
+export declare function computeCacheKey({ source, dark, sanitized, coreVersion }: CacheKeyInput): string;
+export declare function createDiagramCache(mode: CacheMode, maxEntries: number): DiagramCache;
+export declare function getSharedCache(mode: CacheMode, maxEntries: number): DiagramCache;
+/** Test-only: drops every shared cache instance. */
+export declare function resetSharedCaches(): void;

package/dist/runtime/cache.js

@@ -0,0 +1,219 @@
+/**
+ * Rendered SVG is cached under a key that folds in everything that can change the output.
+ * Colour mode is part of the key, so toggling dark mode can never serve the other mode's
+ * picture, and the `@plantuml/core` version is part of it so an engine upgrade invalidates
+ * every stored entry.
+ */
+const STORAGE_PREFIX = 'plantuml-client:';
+const ENTRY_VERSION = 1;
+/** FNV-1a. Not cryptographic — this only needs to be fast, stable and short. */
+function hash(input) {
+    let value = 0x811c9dc5;
+    for (let index = 0; index < input.length; index += 1) {
+        value ^= input.charCodeAt(index);
+        value = Math.imul(value, 0x01000193) >>> 0;
+    }
+    return value.toString(36).padStart(7, '0');
+}
+export function computeCacheKey({ source, dark, sanitized, coreVersion }) {
+    const mode = dark ? 'dark' : 'light';
+    const clean = sanitized ? 'san' : 'raw';
+    // The length guards against the (astronomically unlikely) 32-bit hash collision between
+    // two different sources that happen to share every other key component.
+    return `${coreVersion}|${mode}|${clean}|${source.length}|${hash(source)}`;
+}
+class MemoryCache {
+    mode = 'memory';
+    #entries = new Map();
+    #maxEntries;
+    constructor(maxEntries) {
+        this.#maxEntries = maxEntries;
+    }
+    get(key) {
+        const value = this.#entries.get(key);
+        if (value === undefined)
+            return undefined;
+        // Re-insert so the Map's insertion order doubles as LRU recency.
+        this.#entries.delete(key);
+        this.#entries.set(key, value);
+        return value;
+    }
+    set(key, svg) {
+        this.#entries.delete(key);
+        this.#entries.set(key, svg);
+        while (this.#entries.size > this.#maxEntries) {
+            const oldest = this.#entries.keys().next();
+            if (oldest.done)
+                break;
+            this.#entries.delete(oldest.value);
+        }
+    }
+    clear() {
+        this.#entries.clear();
+    }
+    size() {
+        return this.#entries.size;
+    }
+}
+class NoopCache {
+    mode = 'none';
+    get() {
+        return undefined;
+    }
+    set() {
+        /* intentionally not stored */
+    }
+    clear() {
+        /* nothing to clear */
+    }
+    size() {
+        return 0;
+    }
+}
+/**
+ * `sessionStorage` is best-effort by design: it is unavailable in private modes and some
+ * embedded browsers, it throws on quota exhaustion, and its contents can be edited by hand.
+ * Every access is therefore guarded, and a bad read is discarded rather than propagated.
+ */
+class SessionCache {
+    mode = 'session';
+    #maxEntries;
+    #fallback;
+    constructor(maxEntries) {
+        this.#maxEntries = maxEntries;
+        this.#fallback = new MemoryCache(maxEntries);
+    }
+    #storage() {
+        try {
+            const storage = globalThis.sessionStorage;
+            return storage ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    get(key) {
+        const storage = this.#storage();
+        if (!storage)
+            return this.#fallback.get(key);
+        let raw;
+        try {
+            raw = storage.getItem(STORAGE_PREFIX + key);
+        }
+        catch {
+            return this.#fallback.get(key);
+        }
+        // A miss in storage still has to consult the fallback: entries written while storage was
+        // rejecting writes (quota, private mode) live only there.
+        if (raw === null)
+            return this.#fallback.get(key);
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed?.v !== ENTRY_VERSION || typeof parsed.svg !== 'string') {
+                this.#drop(storage, key);
+                return this.#fallback.get(key);
+            }
+            return parsed.svg;
+        }
+        catch {
+            this.#drop(storage, key);
+            return this.#fallback.get(key);
+        }
+    }
+    set(key, svg) {
+        const storage = this.#storage();
+        if (!storage) {
+            this.#fallback.set(key, svg);
+            return;
+        }
+        const entry = { v: ENTRY_VERSION, svg };
+        try {
+            this.#evictIfNeeded(storage);
+            storage.setItem(STORAGE_PREFIX + key, JSON.stringify(entry));
+        }
+        catch {
+            // Quota exceeded or storage disabled mid-session: keep rendering, just stop persisting.
+            this.#fallback.set(key, svg);
+        }
+    }
+    #ownKeys(storage) {
+        const keys = [];
+        for (let index = 0; index < storage.length; index += 1) {
+            const key = storage.key(index);
+            if (key?.startsWith(STORAGE_PREFIX))
+                keys.push(key);
+        }
+        return keys;
+    }
+    #evictIfNeeded(storage) {
+        const keys = this.#ownKeys(storage);
+        // `sessionStorage` has no recency information, so this is a plain FIFO trim of our own
+        // namespace. The documented bound is what matters; exact eviction order is not.
+        for (let index = 0; index <= keys.length - this.#maxEntries; index += 1) {
+            const key = keys[index];
+            if (key !== undefined)
+                storage.removeItem(key);
+        }
+    }
+    #drop(storage, key) {
+        try {
+            storage.removeItem(STORAGE_PREFIX + key);
+        }
+        catch {
+            /* nothing more we can do */
+        }
+    }
+    clear() {
+        this.#fallback.clear();
+        const storage = this.#storage();
+        if (!storage)
+            return;
+        try {
+            this.#ownKeys(storage).forEach((key) => storage.removeItem(key));
+        }
+        catch {
+            /* nothing more we can do */
+        }
+    }
+    size() {
+        const storage = this.#storage();
+        if (!storage)
+            return this.#fallback.size();
+        try {
+            return this.#ownKeys(storage).length;
+        }
+        catch {
+            return this.#fallback.size();
+        }
+    }
+}
+export function createDiagramCache(mode, maxEntries) {
+    switch (mode) {
+        case 'none':
+            return new NoopCache();
+        case 'session':
+            return new SessionCache(maxEntries);
+        case 'memory':
+        default:
+            return new MemoryCache(maxEntries);
+    }
+}
+/**
+ * One cache per (mode, limit) pair, shared by every diagram on the page so that the same
+ * source rendered twice is only rendered once.
+ */
+const sharedCaches = new Map();
+export function getSharedCache(mode, maxEntries) {
+    const key = `${mode}:${maxEntries}`;
+    let cache = sharedCaches.get(key);
+    if (!cache) {
+        cache = createDiagramCache(mode, maxEntries);
+        sharedCaches.set(key, cache);
+    }
+    return cache;
+}
+/** Test-only: drops every shared cache instance. */
+export function resetSharedCaches() {
+    sharedCaches.forEach((cache) => cache.clear());
+    sharedCaches.clear();
+}

package/dist/runtime/errors.d.ts

@@ -0,0 +1,31 @@
+export type PlantUmlErrorKind = 'load' | 'engine' | 'diagram' | 'timeout' | 'config' | 'aborted';
+/** Every failure surfaced to the UI is one of these, so the panel can explain what broke. */
+export declare class PlantUmlError extends Error {
+    readonly kind: PlantUmlErrorKind;
+    constructor(kind: PlantUmlErrorKind, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * PlantUML reports invalid diagrams by *successfully* rendering an error picture rather
+ * than by calling the error callback, so a rendered SVG still has to be inspected.
+ *
+ * Each signature requires two co-occurring markers to avoid misreading a legitimate
+ * diagram that merely contains the words "syntax error" in a note.
+ *
+ * @returns a human-readable message, or `null` when the SVG is a real diagram.
+ */
+export declare function detectDiagramError(svg: string): string | null;
+/**
+ * Normalizes whatever the engine hands to its error callback into a readable string.
+ *
+ * The engine is TeaVM-compiled Java, so a rejection can be an `Error`, a bare string, or a
+ * host object with its own `toString`. Anything without a meaningful string form is
+ * described rather than rendered as `[object Object]`.
+ */
+export declare function describeEngineError(raw: unknown): string;
+/**
+ * Coerces an unknown rejection into an `Error`, preserving {@link PlantUmlError} instances
+ * so their `kind` survives a trip through the render queue.
+ */
+export declare function toError(value: unknown): Error;

package/dist/runtime/errors.js

@@ -0,0 +1,108 @@
+/** Every failure surfaced to the UI is one of these, so the panel can explain what broke. */
+export class PlantUmlError extends Error {
+    kind;
+    constructor(kind, message, options) {
+        super(message, options);
+        this.name = 'PlantUmlError';
+        this.kind = kind;
+    }
+}
+/**
+ * Noise that PlantUML prepends to its error diagrams. Dropping it keeps the message about
+ * the user's diagram rather than about the engine's build metadata.
+ */
+const BOILERPLATE_PATTERNS = [
+    /^PlantUML version /,
+    /^This version of PlantUML is \d+ days old/,
+    /^consider upgrading from /,
+    /^\s*$/,
+];
+const NOT_SUPPORTED_HEADING = 'Diagram not supported by this release of PlantUML';
+function textNodesOf(svg) {
+    if (typeof DOMParser === 'undefined')
+        return [];
+    let doc;
+    try {
+        doc = new DOMParser().parseFromString(svg, 'image/svg+xml');
+    }
+    catch {
+        return [];
+    }
+    if (doc.querySelector('parsererror'))
+        return [];
+    return Array.from(doc.querySelectorAll('text')).map((node) => node.textContent ?? '');
+}
+/**
+ * PlantUML reports invalid diagrams by *successfully* rendering an error picture rather
+ * than by calling the error callback, so a rendered SVG still has to be inspected.
+ *
+ * Each signature requires two co-occurring markers to avoid misreading a legitimate
+ * diagram that merely contains the words "syntax error" in a note.
+ *
+ * @returns a human-readable message, or `null` when the SVG is a real diagram.
+ */
+export function detectDiagramError(svg) {
+    const texts = textNodesOf(svg);
+    if (texts.length === 0)
+        return null;
+    const isSyntaxError = texts.some((text) => /Syntax Error\?/.test(text) && text.includes('(Assumed diagram type:'));
+    const isEmptyDescription = texts.some((text) => /Empty description/.test(text) && text.includes('(Assumed diagram type:'));
+    const isUnsupported = texts.some((text) => text.includes(NOT_SUPPORTED_HEADING)) &&
+        texts.some((text) => text.includes('is not recognized.'));
+    if (!isSyntaxError && !isEmptyDescription && !isUnsupported)
+        return null;
+    const meaningful = texts
+        .map((text) => text.replace(/\s+$/, ''))
+        .filter((text) => !BOILERPLATE_PATTERNS.some((pattern) => pattern.test(text)));
+    const message = meaningful.join('\n').trim();
+    return message.length > 0 ? message : 'PlantUML reported an error for this diagram.';
+}
+const UNKNOWN_ERROR = 'The PlantUML engine reported an unknown error.';
+const UNPRINTABLE_ERROR = 'The PlantUML engine reported an unstringifiable error.';
+/**
+ * Normalizes whatever the engine hands to its error callback into a readable string.
+ *
+ * The engine is TeaVM-compiled Java, so a rejection can be an `Error`, a bare string, or a
+ * host object with its own `toString`. Anything without a meaningful string form is
+ * described rather than rendered as `[object Object]`.
+ */
+export function describeEngineError(raw) {
+    if (raw instanceof Error)
+        return raw.message;
+    if (typeof raw === 'string')
+        return raw;
+    if (raw === null || raw === undefined)
+        return UNKNOWN_ERROR;
+    if (typeof raw === 'number' || typeof raw === 'boolean' || typeof raw === 'bigint') {
+        return String(raw);
+    }
+    if (typeof raw === 'symbol')
+        return raw.toString();
+    if (typeof raw === 'function')
+        return UNKNOWN_ERROR;
+    const candidate = raw;
+    if (typeof candidate.toString === 'function' &&
+        candidate.toString !== Object.prototype.toString) {
+        try {
+            const text = candidate.toString();
+            if (typeof text === 'string' && text !== '')
+                return text;
+        }
+        catch {
+            return UNPRINTABLE_ERROR;
+        }
+    }
+    try {
+        return JSON.stringify(raw) ?? UNKNOWN_ERROR;
+    }
+    catch {
+        return UNPRINTABLE_ERROR;
+    }
+}
+/**
+ * Coerces an unknown rejection into an `Error`, preserving {@link PlantUmlError} instances
+ * so their `kind` survives a trip through the render queue.
+ */
+export function toError(value) {
+    return value instanceof Error ? value : new PlantUmlError('engine', describeEngineError(value));
+}

package/dist/runtime/queue.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The PlantUML engine keeps its in-flight render state in module-level globals, so two
+ * overlapping calls corrupt each other: in a browser spike, three concurrent
+ * `renderToString` calls produced exactly one callback and two permanent hangs.
+ *
+ * Every render therefore goes through this module-level FIFO queue, which runs one task at
+ * a time and always advances — a rejected, timed-out or aborted task can never wedge it.
+ */
+export interface EnqueueOptions {
+    /** Reject the task if it has not settled this many milliseconds after it started. */
+    timeoutMs: number;
+    /** Drop the task before it starts, and stop waiting for it once it has. */
+    signal?: AbortSignal;
+}
+/**
+ * Queues `task` behind every previously queued task.
+ *
+ * `task` receives a signal that is aborted on timeout or caller abort, so long-running
+ * work can bail out instead of writing into a discarded render.
+ */
+export declare function enqueueRender<T>(task: (signal: AbortSignal) => Promise<T>, options: EnqueueOptions): Promise<T>;
+/** Number of tasks waiting to start. Exposed for tests and diagnostics. */
+export declare function pendingRenderCount(): number;
+/** Whether a task is currently running. Exposed for tests and diagnostics. */
+export declare function isRenderActive(): boolean;
+/** Test-only: drops queued work and clears the active flag. */
+export declare function resetRenderQueue(): void;