@openforge-app/plugin-sdk 0.2.10 → 0.2.11

package/dist/mermaid.d.ts

@@ -0,0 +1,13 @@
+export type MermaidTheme = 'default' | 'dark';
+export declare const MERMAID_DIAGRAM_CLASS = "mermaid-diagram";
+export declare const MERMAID_EXPAND_ACTION_CLASS = "mermaid-diagram-expand";
+export declare function resolveMermaidTheme(doc?: Document): MermaidTheme;
+export interface RenderedMermaidDiagram {
+    trigger: HTMLButtonElement;
+    wrapper: HTMLDivElement;
+    svg: string;
+}
+export declare function getRenderedMermaidSvg(wrapper: HTMLDivElement): string | null;
+export declare function getRenderedMermaidDiagram(target: Element): RenderedMermaidDiagram | null;
+export declare function renderMermaidDiagrams(root: HTMLElement, isCurrent?: () => boolean): Promise<void>;
+export declare function observeMermaidTheme(doc: Document, onChange: () => void): () => void;

package/dist/mermaid.js

@@ -0,0 +1,221 @@
+import { sanitizeMermaidSvg } from './sanitize';
+const MERMAID_CODE_SELECTOR = 'pre > code.language-mermaid';
+export const MERMAID_DIAGRAM_CLASS = 'mermaid-diagram';
+export const MERMAID_EXPAND_ACTION_CLASS = 'mermaid-diagram-expand';
+const MERMAID_FAILURE_CLASS = 'mermaid-diagram-fallback';
+const MERMAID_EXTERNAL_RESOURCE_PATTERN = /(?:\b(?:https?|ftp|file|data|javascript|vbscript):|(?:^|[\s("'=])\/\/|@import|\burl\s*\()/im;
+const MERMAID_ESCAPED_STYLE_PATTERN = /\b(?:classDef|style|linkStyle)\b[^\r\n]*\\/i;
+let diagramId = 0;
+let renderQueue = Promise.resolve();
+const mermaidThemeObservations = new WeakMap();
+function loadMermaid() {
+    return import('mermaid').then(module => module.default);
+}
+export function resolveMermaidTheme(doc = document) {
+    const themeName = doc.documentElement.getAttribute('data-theme');
+    if (themeName)
+        return themeName.includes('dark') ? 'dark' : 'default';
+    if (doc.defaultView?.matchMedia?.('(prefers-color-scheme: dark)').matches)
+        return 'dark';
+    return 'default';
+}
+function queueMermaidRender(operation) {
+    const result = renderQueue.then(operation, operation);
+    renderQueue = result.then(() => undefined, () => undefined);
+    return result;
+}
+function assertSafeMermaidSource(source) {
+    if (MERMAID_EXTERNAL_RESOURCE_PATTERN.test(source) || MERMAID_ESCAPED_STYLE_PATTERN.test(source)) {
+        throw new Error('Mermaid source contains an external resource');
+    }
+}
+async function renderMermaidSvg(source, theme) {
+    assertSafeMermaidSource(source);
+    return queueMermaidRender(async () => {
+        const mermaid = await loadMermaid();
+        mermaid.initialize({
+            startOnLoad: false,
+            securityLevel: 'strict',
+            suppressErrorRendering: true,
+            maxTextSize: 50_000,
+            maxEdges: 500,
+            secure: [
+                'secure',
+                'securityLevel',
+                'startOnLoad',
+                'suppressErrorRendering',
+                'maxTextSize',
+                'maxEdges',
+                'theme',
+                'themeVariables',
+                'themeCSS',
+                'fontFamily',
+                'altFontFamily',
+                'dompurifyConfig',
+                'htmlLabels',
+                'flowchart',
+            ],
+            theme,
+            htmlLabels: false,
+            flowchart: { htmlLabels: false },
+        });
+        const { svg } = await mermaid.render(`openforge-mermaid-${++diagramId}`, source);
+        return sanitizeMermaidSvg(svg);
+    });
+}
+function prepareDiagram(code) {
+    const fallback = code.parentElement;
+    if (!(fallback instanceof HTMLPreElement))
+        return null;
+    const existingWrapper = fallback.parentElement;
+    if (existingWrapper instanceof HTMLDivElement && existingWrapper.classList.contains(MERMAID_DIAGRAM_CLASS)) {
+        return { wrapper: existingWrapper, source: code.textContent?.trim() ?? '', fallback };
+    }
+    const wrapper = document.createElement('div');
+    wrapper.className = MERMAID_DIAGRAM_CLASS;
+    wrapper.setAttribute('role', 'group');
+    wrapper.setAttribute('aria-label', 'Mermaid diagram');
+    fallback.before(wrapper);
+    wrapper.append(fallback);
+    return { wrapper, source: code.textContent?.trim() ?? '', fallback };
+}
+function clearRenderedDiagram(wrapper, fallback) {
+    const expandAction = wrapper.querySelector(`:scope > button.${MERMAID_EXPAND_ACTION_CLASS}`);
+    for (const child of Array.from(wrapper.children)) {
+        if (child !== fallback && child !== expandAction)
+            child.remove();
+    }
+    if (expandAction)
+        expandAction.hidden = true;
+    fallback.hidden = false;
+    wrapper.classList.remove('mermaid-diagram-rendered', MERMAID_FAILURE_CLASS);
+}
+function showRenderFailure(wrapper, fallback) {
+    clearRenderedDiagram(wrapper, fallback);
+    const message = document.createElement('p');
+    message.className = 'mermaid-diagram-error';
+    message.setAttribute('role', 'status');
+    message.textContent = 'Unable to render Mermaid diagram. Showing source instead.';
+    wrapper.prepend(message);
+    wrapper.classList.add(MERMAID_FAILURE_CLASS);
+}
+function fitSvgToRenderedContent(svg) {
+    if (typeof svg.getBBox !== 'function')
+        return;
+    try {
+        const bounds = svg.getBBox();
+        if (![bounds.x, bounds.y, bounds.width, bounds.height].every(Number.isFinite))
+            return;
+        if (bounds.width <= 0 || bounds.height <= 0)
+            return;
+        const padding = 8;
+        const width = bounds.width + padding * 2;
+        const height = bounds.height + padding * 2;
+        svg.setAttribute('viewBox', [
+            bounds.x - padding,
+            bounds.y - padding,
+            width,
+            height,
+        ].join(' '));
+        svg.style.maxWidth = `${Math.ceil(width)}px`;
+    }
+    catch {
+        // Keep Mermaid's original viewport when the browser cannot measure SVG geometry.
+    }
+}
+function createDiagramExpandAction(doc) {
+    const button = doc.createElement('button');
+    button.type = 'button';
+    button.className = MERMAID_EXPAND_ACTION_CLASS;
+    button.setAttribute('aria-label', 'Expand Mermaid diagram');
+    button.title = 'Expand Mermaid diagram';
+    button.textContent = 'Expand';
+    return button;
+}
+export function getRenderedMermaidSvg(wrapper) {
+    if (!wrapper.isConnected || !wrapper.classList.contains('mermaid-diagram-rendered'))
+        return null;
+    return wrapper.querySelector(':scope > svg')?.outerHTML ?? null;
+}
+export function getRenderedMermaidDiagram(target) {
+    const trigger = target.closest(`button.${MERMAID_EXPAND_ACTION_CLASS}`);
+    if (!(trigger instanceof HTMLButtonElement))
+        return null;
+    const wrapper = trigger.closest(`.${MERMAID_DIAGRAM_CLASS}`);
+    if (!(wrapper instanceof HTMLDivElement))
+        return null;
+    const svg = getRenderedMermaidSvg(wrapper);
+    return svg ? { trigger, wrapper, svg } : null;
+}
+function showRenderedDiagram(wrapper, fallback, sanitizedSvg) {
+    const template = document.createElement('template');
+    template.innerHTML = sanitizedSvg;
+    const svg = template.content.querySelector('svg');
+    if (!svg)
+        return false;
+    if (!svg.hasAttribute('role'))
+        svg.setAttribute('role', 'img');
+    if (!svg.hasAttribute('aria-label') && !svg.hasAttribute('aria-labelledby')) {
+        svg.setAttribute('aria-label', 'Mermaid diagram');
+    }
+    clearRenderedDiagram(wrapper, fallback);
+    wrapper.insertBefore(template.content, fallback);
+    fitSvgToRenderedContent(svg);
+    const expandAction = wrapper.querySelector(`:scope > button.${MERMAID_EXPAND_ACTION_CLASS}`)
+        ?? createDiagramExpandAction(wrapper.ownerDocument);
+    expandAction.hidden = false;
+    if (!expandAction.parentElement)
+        wrapper.insertBefore(expandAction, fallback);
+    fallback.hidden = true;
+    wrapper.classList.add('mermaid-diagram-rendered');
+    return true;
+}
+export async function renderMermaidDiagrams(root, isCurrent = () => true) {
+    const diagrams = Array.from(root.querySelectorAll(MERMAID_CODE_SELECTOR))
+        .map(prepareDiagram)
+        .filter((diagram) => diagram !== null);
+    const theme = resolveMermaidTheme(root.ownerDocument);
+    await Promise.all(diagrams.map(async ({ wrapper, source, fallback }) => {
+        clearRenderedDiagram(wrapper, fallback);
+        if (!source) {
+            showRenderFailure(wrapper, fallback);
+            return;
+        }
+        try {
+            const svg = await renderMermaidSvg(source, theme);
+            if (!isCurrent() || !wrapper.isConnected)
+                return;
+            if (!showRenderedDiagram(wrapper, fallback, svg))
+                showRenderFailure(wrapper, fallback);
+        }
+        catch {
+            if (isCurrent() && wrapper.isConnected)
+                showRenderFailure(wrapper, fallback);
+        }
+    }));
+}
+export function observeMermaidTheme(doc, onChange) {
+    let observation = mermaidThemeObservations.get(doc);
+    if (!observation) {
+        const listeners = new Set();
+        const notify = () => listeners.forEach(listener => listener());
+        const observer = new MutationObserver((mutations) => {
+            if (mutations.some(mutation => mutation.attributeName === 'data-theme'))
+                notify();
+        });
+        observer.observe(doc.documentElement, { attributes: true, attributeFilter: ['data-theme'] });
+        const media = doc.defaultView?.matchMedia?.('(prefers-color-scheme: dark)');
+        media?.addEventListener?.('change', notify);
+        observation = { listeners, observer, media, notify };
+        mermaidThemeObservations.set(doc, observation);
+    }
+    observation.listeners.add(onChange);
+    return () => {
+        observation.listeners.delete(onChange);
+        if (observation.listeners.size > 0)
+            return;
+        observation.observer.disconnect();
+        observation.media?.removeEventListener?.('change', observation.notify);
+        mermaidThemeObservations.delete(doc);
+    };
+}

package/dist/mermaidZoom.d.ts

@@ -0,0 +1,23 @@
+export declare const MIN_MERMAID_ZOOM = 0.25;
+export declare const MAX_MERMAID_ZOOM = 4;
+export declare const MERMAID_ZOOM_STEP = 0.25;
+export interface MermaidSize {
+    width: number;
+    height: number;
+}
+export type MermaidZoomState = {
+    mode: 'fit';
+} | {
+    mode: 'manual';
+    scale: number;
+};
+export declare const FIT_MERMAID_ZOOM: MermaidZoomState;
+export declare function calculateMermaidFitScale(content: MermaidSize, viewport: MermaidSize): number | null;
+export declare function createManualMermaidZoom(scale: number): MermaidZoomState;
+export declare function resolveMermaidZoomScale(state: MermaidZoomState, fitScale: number | null): number;
+export declare function zoomMermaidIn(state: MermaidZoomState, fitScale: number | null): MermaidZoomState;
+export declare function zoomMermaidOut(state: MermaidZoomState, fitScale: number | null): MermaidZoomState;
+export declare function resetMermaidZoom(): MermaidZoomState;
+export declare function canZoomMermaidIn(state: MermaidZoomState, fitScale: number | null): boolean;
+export declare function canZoomMermaidOut(state: MermaidZoomState, fitScale: number | null): boolean;
+export declare function formatMermaidZoomLabel(state: MermaidZoomState, fitScale: number | null): string;

package/dist/mermaidZoom.js

@@ -0,0 +1,52 @@
+export const MIN_MERMAID_ZOOM = 0.25;
+export const MAX_MERMAID_ZOOM = 4;
+export const MERMAID_ZOOM_STEP = 0.25;
+export const FIT_MERMAID_ZOOM = { mode: 'fit' };
+function isPositiveSize(size) {
+    return Number.isFinite(size.width)
+        && Number.isFinite(size.height)
+        && size.width > 0
+        && size.height > 0;
+}
+function clampManualScale(scale) {
+    if (!Number.isFinite(scale))
+        return 1;
+    return Math.min(MAX_MERMAID_ZOOM, Math.max(MIN_MERMAID_ZOOM, scale));
+}
+function normalizeScale(scale) {
+    return Math.round(scale * 10_000) / 10_000;
+}
+export function calculateMermaidFitScale(content, viewport) {
+    if (!isPositiveSize(content) || !isPositiveSize(viewport))
+        return null;
+    return Math.min(viewport.width / content.width, viewport.height / content.height);
+}
+export function createManualMermaidZoom(scale) {
+    return { mode: 'manual', scale: clampManualScale(scale) };
+}
+export function resolveMermaidZoomScale(state, fitScale) {
+    if (state.mode === 'manual')
+        return state.scale;
+    return fitScale && fitScale > 0 ? fitScale : 1;
+}
+export function zoomMermaidIn(state, fitScale) {
+    const currentScale = resolveMermaidZoomScale(state, fitScale);
+    return createManualMermaidZoom(normalizeScale(currentScale + MERMAID_ZOOM_STEP));
+}
+export function zoomMermaidOut(state, fitScale) {
+    const currentScale = resolveMermaidZoomScale(state, fitScale);
+    return createManualMermaidZoom(normalizeScale(currentScale - MERMAID_ZOOM_STEP));
+}
+export function resetMermaidZoom() {
+    return createManualMermaidZoom(1);
+}
+export function canZoomMermaidIn(state, fitScale) {
+    return resolveMermaidZoomScale(state, fitScale) < MAX_MERMAID_ZOOM;
+}
+export function canZoomMermaidOut(state, fitScale) {
+    return resolveMermaidZoomScale(state, fitScale) > MIN_MERMAID_ZOOM;
+}
+export function formatMermaidZoomLabel(state, fitScale) {
+    const percentage = Math.round(resolveMermaidZoomScale(state, fitScale) * 100);
+    return state.mode === 'fit' ? `Fit (${percentage}%)` : `${percentage}%`;
+}

package/dist/publicEntrypoints.d.mts

@@ -20,6 +20,7 @@ export function createOpenForgePluginSdkPackageExports(): Record<
 
 export function createOpenForgePluginSdkTypeScriptPaths(): Record<string, [string]>
 
+export function loadOpenForgePluginSdkTypeScriptPaths(workspaceRoot: string): Promise<Record<string, unknown>>
 export function assertOpenForgePluginSdkEntrypointRegistries(registries: {
   packageExports: unknown
   typeScriptPaths: unknown

package/dist/publicEntrypoints.mjs

@@ -1,4 +1,6 @@
-import { isDeepStrictEqual } from 'node:util'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { assertRegistryMatchesCanonicalManifest } from './registryValidation.mjs'
 import { OPENFORGE_PLUGIN_SDK_PUBLIC_UI_EXPORTS } from './publicUiExports.mjs'
 
 const PLUGIN_SDK_PACKAGE_NAME = '@openforge-app/plugin-sdk'
@@ -77,27 +79,26 @@ export function createOpenForgePluginSdkTypeScriptPaths() {
   )
 }
 
-export function assertOpenForgePluginSdkEntrypointRegistries({ packageExports, typeScriptPaths }) {
-  assertRegistryMatches('package exports', packageExports, createOpenForgePluginSdkPackageExports())
-  assertRegistryMatches('root TypeScript paths', typeScriptPaths, createOpenForgePluginSdkTypeScriptPaths())
-}
-
-function assertRegistryMatches(registryName, actual, expected) {
-  if (!actual || typeof actual !== 'object' || Array.isArray(actual)) {
-    throw new Error(`Plugin SDK ${registryName} must be an object`)
-  }
-
-  const missingOrMismatched = Object.entries(expected)
-    .filter(([key, value]) => !isDeepStrictEqual(actual[key], value))
-    .map(([key]) => key)
-  const unexpected = Object.keys(actual).filter((key) => !(key in expected))
-
-  if (missingOrMismatched.length === 0 && unexpected.length === 0) return
+export async function loadOpenForgePluginSdkTypeScriptPaths(workspaceRoot) {
+  const typeScriptConfig = JSON.parse(
+    (await readFile(resolve(workspaceRoot, 'tsconfig.json'), 'utf8')).replace(/\/\*[\s\S]*?\*\//g, ''),
+  )
 
-  const details = [
-    missingOrMismatched.length > 0 ? `missing or mismatched: ${missingOrMismatched.join(', ')}` : null,
-    unexpected.length > 0 ? `not in the canonical manifest: ${unexpected.join(', ')}` : null,
-  ].filter(Boolean)
+  return Object.fromEntries(
+    Object.entries(typeScriptConfig.compilerOptions.paths)
+      .filter(([specifier]) => specifier === PLUGIN_SDK_PACKAGE_NAME || specifier.startsWith(`${PLUGIN_SDK_PACKAGE_NAME}/`)),
+  )
+}
 
-  throw new Error(`Plugin SDK ${registryName} drifted from the canonical manifest (${details.join('; ')})`)
+export function assertOpenForgePluginSdkEntrypointRegistries({ packageExports, typeScriptPaths }) {
+  assertRegistryMatchesCanonicalManifest({
+    registryName: 'Plugin SDK package exports',
+    actual: packageExports,
+    expected: createOpenForgePluginSdkPackageExports(),
+  })
+  assertRegistryMatchesCanonicalManifest({
+    registryName: 'Plugin SDK root TypeScript paths',
+    actual: typeScriptPaths,
+    expected: createOpenForgePluginSdkTypeScriptPaths(),
+  })
 }

package/dist/publicUiExports.mjs

@@ -1,3 +1,5 @@
+import { assertRegistryMatchesCanonicalManifest } from './registryValidation.mjs'
+
 const PLUGIN_SDK_PACKAGE_NAME = '@openforge-app/plugin-sdk'
 
 const PUBLIC_UI_COMPONENT_NAMES = Object.freeze([
@@ -38,26 +40,12 @@ export function createOpenForgePluginSdkPublicUiPackageExports() {
 }
 
 export function assertOpenForgePluginSdkPublicUiPackageExports(packageExports) {
-  if (!packageExports || typeof packageExports !== 'object' || Array.isArray(packageExports)) {
-    throw new Error('Plugin SDK package.json must define an exports object')
-  }
-
-  const expected = createOpenForgePluginSdkPublicUiPackageExports()
-  const actual = Object.fromEntries(
-    Object.entries(packageExports).filter(([subpath]) => subpath.startsWith('./ui/')),
-  )
-  const expectedEntries = Object.entries(expected)
-  const missingOrMismatched = expectedEntries
-    .filter(([subpath, distPath]) => actual[subpath] !== distPath)
-    .map(([subpath, distPath]) => `${subpath} -> ${distPath}`)
-  const unexpected = Object.keys(actual).filter((subpath) => !(subpath in expected))
-
-  if (missingOrMismatched.length === 0 && unexpected.length === 0) return
-
-  const details = [
-    missingOrMismatched.length > 0 ? `missing or mismatched: ${missingOrMismatched.join(', ')}` : null,
-    unexpected.length > 0 ? `not in the canonical manifest: ${unexpected.join(', ')}` : null,
-  ].filter(Boolean)
-
-  throw new Error(`Plugin SDK public UI exports drifted from the canonical manifest (${details.join('; ')})`)
+  assertRegistryMatchesCanonicalManifest({
+    registryName: 'Plugin SDK public UI exports',
+    actual: packageExports,
+    expected: createOpenForgePluginSdkPublicUiPackageExports(),
+    invalidRegistryMessage: 'Plugin SDK package.json must define an exports object',
+    includeActualEntry: ([subpath]) => subpath.startsWith('./ui/'),
+    formatMissingOrMismatched: ([subpath, distPath]) => `${subpath} -> ${distPath}`,
+  })
 }

package/dist/registryValidation.d.mts

@@ -0,0 +1,11 @@
+type Registry = Record<string, unknown>
+type RegistryEntry = [string, unknown]
+
+export function assertRegistryMatchesCanonicalManifest(options: {
+  registryName: string
+  actual: unknown
+  expected: Registry
+  invalidRegistryMessage?: string
+  includeActualEntry?: (entry: RegistryEntry) => boolean
+  formatMissingOrMismatched?: (entry: RegistryEntry) => string
+}): void

package/dist/registryValidation.mjs

@@ -0,0 +1,30 @@
+import { isDeepStrictEqual } from 'node:util'
+
+export function assertRegistryMatchesCanonicalManifest({
+  registryName,
+  actual,
+  expected,
+  invalidRegistryMessage = `${registryName} must be an object`,
+  includeActualEntry = () => true,
+  formatMissingOrMismatched = ([key]) => key,
+}) {
+  if (!actual || typeof actual !== 'object' || Array.isArray(actual)) {
+    throw new Error(invalidRegistryMessage)
+  }
+
+  const comparableActual = Object.fromEntries(Object.entries(actual).filter(includeActualEntry))
+
+  const missingOrMismatched = Object.entries(expected)
+    .filter(([key, value]) => !isDeepStrictEqual(comparableActual[key], value))
+    .map(formatMissingOrMismatched)
+  const unexpected = Object.keys(comparableActual).filter((key) => !(key in expected))
+
+  if (missingOrMismatched.length === 0 && unexpected.length === 0) return
+
+  const details = [
+    missingOrMismatched.length > 0 ? `missing or mismatched: ${missingOrMismatched.join(', ')}` : null,
+    unexpected.length > 0 ? `not in the canonical manifest: ${unexpected.join(', ')}` : null,
+  ].filter(Boolean)
+
+  throw new Error(`${registryName} drifted from the canonical manifest (${details.join('; ')})`)
+}

package/dist/sanitize.d.ts

@@ -4,3 +4,5 @@
  * Allows safe structural/formatting HTML through.
  */
 export declare function sanitizeHtml(dirty: string): string;
+/** Sanitize generated Mermaid SVG before it is inserted into the document. */
+export declare function sanitizeMermaidSvg(dirty: string): string;

package/dist/sanitize.js

@@ -11,3 +11,134 @@ export function sanitizeHtml(dirty) {
         FORBID_ATTR: ['style'],
     });
 }
+const SAFE_MERMAID_STYLE_PROPERTIES = new Set([
+    'color',
+    'dominant-baseline',
+    'fill',
+    'fill-opacity',
+    'font-family',
+    'font-size',
+    'font-style',
+    'font-weight',
+    'max-width',
+    'opacity',
+    'stroke',
+    'stroke-dasharray',
+    'stroke-dashoffset',
+    'stroke-linecap',
+    'stroke-linejoin',
+    'stroke-opacity',
+    'stroke-width',
+    'text-align',
+    'text-anchor',
+    'white-space',
+]);
+function getSafeMermaidStyleDeclarations(style) {
+    const safeDeclarations = [];
+    for (const property of Array.from(style)) {
+        if (!SAFE_MERMAID_STYLE_PROPERTIES.has(property))
+            continue;
+        const value = style.getPropertyValue(property);
+        if (/url\s*\(|expression\s*\(|javascript:|data:|@import|var\s*\(/i.test(value))
+            continue;
+        const priority = style.getPropertyPriority(property);
+        safeDeclarations.push(`${property}: ${value}${priority ? ` !${priority}` : ''}`);
+    }
+    return safeDeclarations;
+}
+function removeCssAtRules(css) {
+    let result = '';
+    let index = 0;
+    while (index < css.length) {
+        if (css[index] !== '@') {
+            result += css[index++];
+            continue;
+        }
+        let depth = 0;
+        let quote = '';
+        for (; index < css.length; index++) {
+            const character = css[index];
+            if (quote) {
+                if (character === '\\')
+                    index++;
+                else if (character === quote)
+                    quote = '';
+                continue;
+            }
+            if (character === '"' || character === "'") {
+                quote = character;
+            }
+            else if (character === '{') {
+                depth++;
+            }
+            else if (character === '}') {
+                if (--depth <= 0) {
+                    index++;
+                    break;
+                }
+            }
+            else if (character === ';' && depth === 0) {
+                index++;
+                break;
+            }
+        }
+    }
+    return result;
+}
+function sanitizeMermaidStylesheet(css, styleParser) {
+    const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, '');
+    const safeRuleSource = removeCssAtRules(withoutComments);
+    const rules = [];
+    const rulePattern = /([^{}]+)\{([^{}]*)\}/g;
+    let consumedUntil = 0;
+    let match;
+    while ((match = rulePattern.exec(safeRuleSource)) !== null) {
+        if (safeRuleSource.slice(consumedUntil, match.index).trim())
+            return '';
+        consumedUntil = rulePattern.lastIndex;
+        const selector = match[1].trim();
+        if (!selector || /[{}@\\]/.test(selector))
+            continue;
+        styleParser.setAttribute('style', match[2]);
+        const declarations = getSafeMermaidStyleDeclarations(styleParser.style);
+        if (declarations.length > 0)
+            rules.push(`${selector} { ${declarations.join('; ')} }`);
+    }
+    if (safeRuleSource.slice(consumedUntil).trim())
+        return '';
+    return rules.join('\n');
+}
+function sanitizeMermaidStyles(svg) {
+    const template = document.createElement('template');
+    template.innerHTML = svg;
+    const styleParser = document.createElement('span');
+    for (const element of template.content.querySelectorAll('[style]')) {
+        styleParser.setAttribute('style', element.getAttribute('style') ?? '');
+        const safeDeclarations = getSafeMermaidStyleDeclarations(styleParser.style);
+        if (safeDeclarations.length > 0) {
+            element.setAttribute('style', safeDeclarations.join('; '));
+        }
+        else {
+            element.removeAttribute('style');
+        }
+    }
+    for (const style of template.content.querySelectorAll('style')) {
+        const sanitized = sanitizeMermaidStylesheet(style.textContent ?? '', styleParser);
+        if (sanitized) {
+            style.textContent = sanitized;
+        }
+        else {
+            style.remove();
+        }
+    }
+    return template.innerHTML;
+}
+/** Sanitize generated Mermaid SVG before it is inserted into the document. */
+export function sanitizeMermaidSvg(dirty) {
+    const sanitized = DOMPurify.sanitize(dirty, {
+        USE_PROFILES: { svg: true, svgFilters: true },
+        FORBID_TAGS: ['script', 'foreignObject', 'iframe', 'object', 'embed', 'image', 'a'],
+        FORBID_ATTR: ['href', 'xlink:href', 'target'],
+    });
+    return sanitizeMermaidStyles(sanitized);
+}

package/dist/testing/commonApiFake.js

@@ -2,6 +2,39 @@ import { MAX_AGENT_SESSION_PAGE_SIZE, resolveExternalTextFileChunkSize } from '.
 import { assertFunction, assertTitle, commandDescriptor, createDisposable, isJsonValue, normalizeAgentCommandMetadata, } from './support.js';
 const UTF8_ENCODER = new TextEncoder();
 const UTF8_DECODER = new TextDecoder('utf-8', { fatal: true });
+function readTestingUserDataDir(files, directoryPath) {
+    const prefix = directoryPath ? `${directoryPath}/` : '';
+    const entries = new Map();
+    for (const [filePath, content] of files) {
+        if (!filePath.startsWith(prefix))
+            continue;
+        const childPath = filePath.slice(prefix.length);
+        const separatorIndex = childPath.indexOf('/');
+        const name = separatorIndex === -1 ? childPath : childPath.slice(0, separatorIndex);
+        if (!name)
+            continue;
+        entries.set(name, separatorIndex === -1
+            ? {
+                name,
+                path: `${prefix}${name}`,
+                isDir: false,
+                size: UTF8_ENCODER.encode(content).byteLength,
+                modifiedAt: null,
+            }
+            : {
+                name,
+                path: `${prefix}${name}`,
+                isDir: true,
+                size: null,
+                modifiedAt: null,
+            });
+    }
+    return [...entries.values()].sort((left, right) => {
+        if (left.isDir !== right.isDir)
+            return left.isDir ? -1 : 1;
+        return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
+    });
+}
 const TERMINAL_AGENT_SESSION_STATUSES = new Set(['completed', 'failed', 'interrupted']);
 function encodeAgentSessionCursor(payload) {
     const bytes = UTF8_ENCODER.encode(JSON.stringify(payload));
@@ -379,7 +412,7 @@ export class TestingCommonApiFake {
                 userData: {
                     readDir: async (request = {}) => {
                         this.services.calls.fsUserDataReadDirs.push(request);
-                        return [];
+                        return readTestingUserDataDir(this.services.userDataTextFiles, request.path);
                     },
                     readTextFile: async (request) => {
                         this.services.calls.fsUserDataReads.push(request);

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { Component } from 'svelte';
 import type { BrowserSurfacesAPI } from './browserSurfaces';
-import type { BoardStatus, AgentSession, CommandInfo, FileContent, FileEntry, Project, ProjectAttention, ReviewPullRequest, Task, TaskWorkspaceInfo, WritableBoardStatus } from './domain';
+import type { BoardStatus, AgentSession, CommandInfo, FileContent, FileEntry, Project, ProjectAttention, ReviewPullRequest, Task, TaskWorkspaceInfo, WorktreeSource, WritableBoardStatus } from './domain';
 export type SupportedOpenForgeApiVersion = 1;
 export declare const SUPPORTED_OPENFORGE_API_VERSIONS: readonly [1, ...1[]];
 export declare const OPENFORGE_PLUGIN_API_VERSION: SupportedOpenForgeApiVersion;
@@ -501,6 +501,14 @@ export interface ComposeTaskRequest {
     initialPrompt: string;
     sourceTicketUrl?: string | null;
     title?: string | null;
+    /** Seeds the dialog's worktree source instead of the project default. */
+    worktreeSource?: WorktreeSource | null;
+    /**
+     * When `worktreeSource` is `existingBranch`, seeds the branch selector.
+     * Pull-request head refs may be short names; the host maps them onto the
+     * stored selector value (`origin/<name>` when origin has the branch).
+     */
+    worktreeBranch?: string | null;
 }
 export interface ComposeTaskResult {
     task: Task;
@@ -618,7 +626,9 @@ export interface TasksAPI {
     /**
      * Opens the host's create-task dialog pre-filled, letting the user edit the
      * prompt — including anything contributed at that injection point —
-     * before the task exists.
+     * before the task exists. Optional `worktreeSource` / `worktreeBranch` seed
+     * the environment controls the same way `title` and `sourceTicketUrl` seed
+     * their fields.
      * Resolves null if they dismiss it.
      */
     compose(request: ComposeTaskRequest): Promise<ComposeTaskResult | null>;

package/dist/ui/MarkdownContent.svelte

@@ -1,5 +1,7 @@
 <script lang="ts">
   import { onDestroy } from 'svelte'
+  import { getRenderedMermaidDiagram, getRenderedMermaidSvg, observeMermaidTheme, renderMermaidDiagrams, type RenderedMermaidDiagram } from '../mermaid'
+  import MermaidDiagramPreview from './MermaidDiagramPreview.svelte'
   import {
     getMarkdownRepositoryLinkSuffix,
     MARKDOWN_REMOTE_MEDIA_ATTRIBUTE,
@@ -37,7 +39,11 @@
   }: Props = $props()
 
   let root = $state<HTMLDivElement | null>(null)
+  let activeMermaidDiagram = $state<RenderedMermaidDiagram | null>(null)
   let imageResolutionId = 0
+  let mermaidRenderId = 0
+  let mermaidThemeRevision = $state(0)
+  let stopObservingMermaidTheme: (() => void) | undefined
   let html = $derived(renderMarkdownHtml(content, {
     imageBaseUrl: resolveRepositoryImage ? null : imageBaseUrl,
     markdownFilePath,
@@ -137,6 +143,31 @@
     }))
   }
 
+  function synchronizeActiveMermaidDiagram() {
+    if (!activeMermaidDiagram) return
+
+    const svg = getRenderedMermaidSvg(activeMermaidDiagram.wrapper)
+    activeMermaidDiagram = svg ? { ...activeMermaidDiagram, svg } : null
+  }
+
+  $effect(() => {
+    if (!root || stopObservingMermaidTheme) return
+    stopObservingMermaidTheme = observeMermaidTheme(root.ownerDocument, () => {
+      mermaidThemeRevision++
+    })
+  })
+
+  $effect(() => {
+    const runId = ++mermaidRenderId
+    void html
+    void mermaidThemeRevision
+    if (!root) return
+
+    void renderMermaidDiagrams(root, () => runId === mermaidRenderId).then(() => {
+      if (runId === mermaidRenderId) synchronizeActiveMermaidDiagram()
+    })
+  })
+
   $effect(() => {
     const runId = ++imageResolutionId
     void html
@@ -149,6 +180,9 @@
 
   onDestroy(() => {
     imageResolutionId++
+    mermaidRenderId++
+    activeMermaidDiagram = null
+    stopObservingMermaidTheme?.()
   })
 
   function openMarkdownLink(href: string, absoluteHref: string) {
@@ -190,6 +224,14 @@
   function handleClick(event: MouseEvent) {
     if (!(event.target instanceof Element)) return
 
+    const diagram = getRenderedMermaidDiagram(event.target)
+    if (diagram) {
+      event.preventDefault()
+      diagram.trigger.focus()
+      activeMermaidDiagram = diagram
+      return
+    }
+
     const image = findEventImage(event.target)
     if (image && onOpenImage && image.getAttribute('src')) {
       event.preventDefault()
@@ -221,3 +263,7 @@
 <div bind:this={root} role="presentation" class="markdown-body" onclick={handleClick} onkeydown={handleKeydown}>
   {@html html}
 </div>
+
+{#if activeMermaidDiagram}
+  <MermaidDiagramPreview svg={activeMermaidDiagram.svg} onClose={() => { activeMermaidDiagram = null }} />
+{/if}

package/dist/ui/MermaidDiagramPreview.svelte

@@ -0,0 +1,216 @@
+<script lang="ts">
+  import { onDestroy } from 'svelte'
+  import {
+    FIT_MERMAID_ZOOM,
+    calculateMermaidFitScale,
+    canZoomMermaidIn,
+    canZoomMermaidOut,
+    formatMermaidZoomLabel,
+    resetMermaidZoom,
+    resolveMermaidZoomScale,
+    zoomMermaidIn,
+    zoomMermaidOut,
+    type MermaidSize,
+    type MermaidZoomState,
+  } from '../mermaidZoom'
+  import Modal from './Modal.svelte'
+
+  interface Props {
+    svg: string
+    onClose: () => void
+  }
+
+  let { svg, onClose }: Props = $props()
+  let viewport = $state<HTMLDivElement | null>(null)
+  let svgHost = $state<HTMLDivElement | null>(null)
+  let closeButton = $state<HTMLButtonElement | null>(null)
+  let viewportSize = $state<MermaidSize>({ width: 0, height: 0 })
+  let zoom = $state<MermaidZoomState>(FIT_MERMAID_ZOOM)
+  let resizeObserver: ResizeObserver | undefined
+
+  function readSvgSize(markup: string): MermaidSize | null {
+    const template = document.createElement('template')
+    template.innerHTML = markup
+    const element = template.content.querySelector('svg')
+    if (!element) return null
+
+    const viewBox = element.getAttribute('viewBox')
+      ?.trim()
+      .split(/[\s,]+/)
+      .map(Number)
+    if (viewBox?.length === 4 && viewBox.every(Number.isFinite) && viewBox[2] > 0 && viewBox[3] > 0) {
+      return { width: viewBox[2], height: viewBox[3] }
+    }
+
+    const width = Number.parseFloat(element.getAttribute('width') ?? '')
+    const height = Number.parseFloat(element.getAttribute('height') ?? '')
+    return Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0
+      ? { width, height }
+      : null
+  }
+
+  let diagramSize = $derived(readSvgSize(svg))
+  let fitScale = $derived(diagramSize
+    ? calculateMermaidFitScale(diagramSize, viewportSize)
+    : null)
+  let renderedScale = $derived(resolveMermaidZoomScale(zoom, fitScale))
+  let zoomLabel = $derived(formatMermaidZoomLabel(zoom, fitScale))
+  let renderedWidth = $derived(diagramSize ? diagramSize.width * renderedScale : null)
+  let renderedHeight = $derived(diagramSize ? diagramSize.height * renderedScale : null)
+
+  function updateViewportSize(width: number, height: number) {
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return
+    viewportSize = { width, height }
+  }
+
+  $effect(() => {
+    if (!viewport || resizeObserver) return
+
+    const bounds = viewport.getBoundingClientRect()
+    updateViewportSize(bounds.width, bounds.height)
+    if (typeof ResizeObserver !== 'function') return
+
+    resizeObserver = new ResizeObserver((entries) => {
+      const entry = entries.find(candidate => candidate.target === viewport)
+      if (entry) updateViewportSize(entry.contentRect.width, entry.contentRect.height)
+    })
+    resizeObserver.observe(viewport)
+  })
+
+  $effect(() => {
+    void svg
+    if (!svgHost || renderedWidth === null || renderedHeight === null) return
+
+    const element = svgHost.querySelector('svg') as SVGSVGElement | null
+    if (!element) return
+    element.style.display = 'block'
+    element.style.width = `${renderedWidth}px`
+    element.style.height = `${renderedHeight}px`
+    element.style.maxWidth = 'none'
+  })
+
+  onDestroy(() => {
+    resizeObserver?.disconnect()
+    resizeObserver = undefined
+  })
+
+  function zoomIn() {
+    zoom = zoomMermaidIn(zoom, fitScale)
+  }
+
+  function zoomOut() {
+    zoom = zoomMermaidOut(zoom, fitScale)
+  }
+
+  function resetZoom() {
+    zoom = resetMermaidZoom()
+  }
+
+  function fitToWindow() {
+    zoom = FIT_MERMAID_ZOOM
+  }
+
+  function handleKeydown(event: KeyboardEvent): boolean | void {
+    if (event.metaKey || event.ctrlKey || event.altKey || event.defaultPrevented) return
+
+    if (event.key === '+' || event.key === '=') {
+      if (canZoomMermaidIn(zoom, fitScale)) zoomIn()
+    } else if (event.key === '-') {
+      if (canZoomMermaidOut(zoom, fitScale)) zoomOut()
+    } else if (event.key === '0') {
+      resetZoom()
+    } else if (event.key.toLowerCase() === 'f') {
+      fitToWindow()
+    } else {
+      return
+    }
+
+    event.preventDefault()
+    return true
+  }
+</script>
+
+<Modal
+  {onClose}
+  ariaLabel="Mermaid diagram preview"
+  showHeader={false}
+  maxWidth="calc(100vw - 2rem)"
+  boxClass="mermaid-diagram-preview h-[calc(100vh-2rem)] !max-h-[calc(100vh-2rem)] w-[calc(100vw-2rem)]"
+  initialFocus={() => closeButton}
+  onKeydown={handleKeydown}
+>
+  <div class="flex min-h-0 flex-1 flex-col bg-base-300/40">
+    <header class="mermaid-diagram-preview-toolbar flex min-h-14 shrink-0 items-center gap-2 border-b border-base-300 bg-base-100 px-4 py-2">
+      <h2 class="m-0 min-w-0 flex-1 truncate text-sm font-semibold text-base-content">Mermaid diagram preview</h2>
+
+      <div class="flex items-center gap-1" role="group" aria-label="Diagram zoom controls">
+        <button
+          type="button"
+          class="btn btn-ghost btn-sm h-11 min-h-11 w-11 p-0"
+          aria-label="Zoom out"
+          title="Zoom out (-)"
+          disabled={!canZoomMermaidOut(zoom, fitScale)}
+          onclick={zoomOut}
+        >
+          <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
+            <circle cx="11" cy="11" r="8" />
+            <path d="m21 21-4.3-4.3M8 11h6" />
+          </svg>
+        </button>
+
+        <output class="min-w-20 text-center text-xs tabular-nums text-base-content/70" aria-live="polite">{zoomLabel}</output>
+
+        <button
+          type="button"
+          class="btn btn-ghost btn-sm h-11 min-h-11 w-11 p-0"
+          aria-label="Zoom in"
+          title="Zoom in (+)"
+          disabled={!canZoomMermaidIn(zoom, fitScale)}
+          onclick={zoomIn}
+        >
+          <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
+            <circle cx="11" cy="11" r="8" />
+            <path d="m21 21-4.3-4.3M11 8v6M8 11h6" />
+          </svg>
+        </button>
+
+        <button
+          type="button"
+          class="btn btn-ghost btn-sm h-11 min-h-11 px-3"
+          aria-label="Reset zoom to 100%"
+          title="Reset zoom to 100% (0)"
+          onclick={resetZoom}
+        >100%</button>
+
+        <button
+          type="button"
+          class="btn btn-ghost btn-sm h-11 min-h-11 px-3"
+          aria-label="Fit diagram to window"
+          aria-pressed={zoom.mode === 'fit'}
+          title="Fit diagram to window (F)"
+          onclick={fitToWindow}
+        >Fit</button>
+      </div>
+
+      <button
+        bind:this={closeButton}
+        type="button"
+        class="btn btn-ghost btn-sm h-11 min-h-11 w-11 p-0"
+        aria-label="Close diagram preview"
+        onclick={onClose}
+      >
+        <svg class="size-5" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
+          <path d="M18 6 6 18M6 6l12 12" />
+        </svg>
+      </button>
+    </header>
+
+    <div bind:this={viewport} data-testid="mermaid-preview-viewport" class="mermaid-diagram-preview-viewport min-h-0 flex-1 overflow-auto p-4">
+      <div data-testid="mermaid-preview-canvas" class="mermaid-diagram-preview-canvas flex h-max min-h-full w-max min-w-full items-center justify-center">
+        <div bind:this={svgHost} class="shrink-0">
+          {@html svg}
+        </div>
+      </div>
+    </div>
+  </div>
+</Modal>

package/dist/ui/Modal.svelte

@@ -179,7 +179,12 @@
         {#if header}
           {@render header()}
         {/if}
-        <button class="btn btn-ghost btn-xs shrink-0" aria-label={closeLabel} onclick={handleCloseButtonClick} type="button" disabled={closeDisabled}>✕</button>
+        <button class="btn btn-ghost h-11 min-h-11 w-11 min-w-11 shrink-0 p-0" aria-label={closeLabel} onclick={handleCloseButtonClick} type="button" disabled={closeDisabled}>
+          <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
+            <path d="M18 6 6 18" />
+            <path d="m6 6 12 12" />
+          </svg>
+        </button>
       </div>
     {/if}
     {@render children()}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openforge-app/plugin-sdk",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -94,15 +94,16 @@
     "access": "public"
   },
   "dependencies": {
-    "dompurify": "^3.4.13",
-    "marked": "^18.0.10"
+    "dompurify": "^3.4.14",
+    "marked": "^18.0.11",
+    "mermaid": "^11.17.2"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"
   },
   "devDependencies": {
-    "@types/node": "26.2.0",
-    "svelte": "5.56.9",
+    "@types/node": "26.3.0",
+    "svelte": "5.56.10",
     "semver": "^7.8.5",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",