@openforge-app/plugin-sdk 0.2.10 → 0.3.0

package/README.md

@@ -1,26 +1,238 @@
 # @openforge-app/plugin-sdk
 
-Public SDK for building OpenForge plugins. [`docs/plugin-authoring.md`](../../docs/plugin-authoring.md) is the canonical guide for the package, runtime, Svelte-sharing, and CSS-loading contract.
+TypeScript SDK for building trusted OpenForge plugins. It includes API version 1 types, frontend and backend entry-point helpers, package metadata validation, testing fakes, Vite helpers, and shared Svelte components.
 
-Styled frontend plugins must declare Vite/Svelte's emitted CSS artifacts in `package.json#openforge.frontendStyles`:
+OpenForge plugins run trusted code. Install plugins only from authors you trust.
+
+## Install
+
+```sh
+pnpm add @openforge-app/plugin-sdk
+```
+
+Frontend plugins also use the Svelte 5 runtime supplied by OpenForge. Add Svelte as a peer dependency and as a development dependency in the plugin package:
+
+```sh
+pnpm add -D svelte@^5 @sveltejs/vite-plugin-svelte vite
+```
+
+```json
+{
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  }
+}
+```
+
+## Package metadata
+
+Declare the plugin in `package.json#openforge` and publish every built file named by the metadata:
 
 ```json
 {
+  "name": "@acme/openforge-notes",
+  "version": "1.0.0",
+  "type": "module",
+  "files": ["dist"],
+  "dependencies": {
+    "@openforge-app/plugin-sdk": "latest"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
   "openforge": {
+    "id": "acme.notes",
+    "apiVersion": 1,
+    "displayName": "Notes",
+    "description": "Project notes",
+    "icon": "notebook-text",
     "frontend": "./dist/frontend.js",
-    "frontendStyles": ["./dist/plugin.css"]
+    "frontendStyles": ["./dist/plugin.css"],
+    "backend": "./dist/backend.mjs",
+    "requires": ["views", "storage", "backend"]
   }
 }
 ```
 
-The host validates, attaches, reloads, and removes these package-relative stylesheets with the frontend plugin lifecycle.
+`openforge.apiVersion` controls compatibility with the OpenForge host. It is separate from the npm package version. The current host contract uses API version `1`.
+
+OpenForge loads built artifacts from the installed package. It does not compile plugin source during installation.
+
+## Frontend entry point
+
+Use `@openforge-app/plugin-sdk/frontend` for renderer contributions such as views, task UI, settings, commands, and events:
+
+```ts
+import { defineFrontendPlugin } from '@openforge-app/plugin-sdk/frontend'
+
+export default defineFrontendPlugin({
+  activate(openforge, context) {
+    context.subscriptions.add(openforge.views.register({
+      id: 'notes',
+      title: 'Notes',
+      icon: 'notebook-text',
+      placement: 'rail',
+      component: () => import('./NotesView.svelte'),
+    }))
+  },
+})
+```
+
+Add every registration and cleanup handle to `context.subscriptions`. OpenForge disposes them when it deactivates or reloads the plugin.
+
+Task reads support project-filtered invalidation subscriptions. Notifications may be coalesced and contain identity plus a reason, not a Task snapshot. Repeat only the bounded read your view needs:
+
+```ts
+export default defineFrontendPlugin({
+  activate(openforge, context) {
+    const projectId = openforge.context.getSnapshot().projectId
+    if (!projectId) return
+
+    context.subscriptions.add(openforge.tasks.onDidChange(projectId, (event) => {
+      const refresh = event.taskId
+        ? openforge.tasks.detail(event.projectId, event.taskId)
+        : openforge.tasks.active(event.projectId)
+      void refresh.then((result) => {
+        // Update plugin-owned state from the bounded result.
+      }).catch(console.error)
+    }))
+  },
+})
+```
+
+The reason is one of `created`, `updated`, `completed`, `attention`, or `execution`. Add the returned disposable to `context.subscriptions`; explicit disposal, deactivation, reload, and uninstall then stop delivery.
+
+Frontend bundles must share Svelte with the host. Use the SDK's Vite external helper:
+
+```ts
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+import { openforgePluginViteExternals } from '@openforge-app/plugin-sdk/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [svelte()],
+  build: {
+    lib: {
+      entry: 'src/frontend.ts',
+      formats: ['es'],
+      fileName: 'frontend',
+    },
+    rollupOptions: {
+      external: openforgePluginViteExternals,
+    },
+  },
+})
+```
+
+Svelte library builds emit CSS separately. List each emitted CSS file in `openforge.frontendStyles`; otherwise OpenForge will not load it.
+
+## Backend entry point
+
+Use `@openforge-app/plugin-sdk/backend` for Node dependencies, plugin-local RPC methods, and background services:
+
+```ts
+import { defineBackendPlugin } from '@openforge-app/plugin-sdk/backend'
+
+export default defineBackendPlugin({
+  activate(openforge, context) {
+    context.subscriptions.add(openforge.backend.registerMethod('ping', {
+      input: { type: 'object', additionalProperties: false },
+      output: {
+        type: 'object',
+        required: ['ok'],
+        properties: { ok: { type: 'boolean' } },
+      },
+      handler: async () => ({ ok: true }),
+    }))
+  },
+})
+```
+
+Backend plugins run in the trusted Node plugin host. They cannot register Svelte views, task UI, settings sections, or frontend navigation.
+
+## Testing
+
+`@openforge-app/plugin-sdk/testing` provides mock APIs and a registry fake for registration, capability, storage, and cleanup tests:
+
+```ts
+import { describe, expect, it } from 'vitest'
+import { createOpenForgeRegistryFake } from '@openforge-app/plugin-sdk/testing'
+import plugin from '../src/frontend'
+
+describe('frontend plugin', () => {
+  it('registers its view', async () => {
+    const registry = createOpenForgeRegistryFake({
+      pluginId: 'acme.notes',
+      projectId: 'P-1',
+    })
+
+    await registry.activateFrontend(plugin)
+
+    expect(registry.snapshot.views).toMatchObject([
+      { id: 'notes', qualifiedId: 'acme.notes.notes', title: 'Notes' },
+    ])
+  })
+})
+```
+
+Use `registry.emitTaskChange(...)` to drive invalidation behavior without importing host events or renderer stores:
+
+```ts
+registry.emitTaskChange({
+  projectId: 'P-1',
+  taskId: 'T-42',
+  reason: 'updated',
+})
+```
+
+## Public entry points
+
+The package exports these modules:
+
+| Import | Purpose |
+| --- | --- |
+| `@openforge-app/plugin-sdk` | Shared types, metadata validation, constants, and domain helpers |
+| `@openforge-app/plugin-sdk/frontend` | Frontend plugin definition and renderer types |
+| `@openforge-app/plugin-sdk/backend` | Backend plugin definition and Node-host types |
+| `@openforge-app/plugin-sdk/testing` | Mock APIs, storage, subscriptions, and registry fakes |
+| `@openforge-app/plugin-sdk/vite` | Host-runtime externals for plugin builds |
+| `@openforge-app/plugin-sdk/package-metadata-schema.json` | JSON Schema for `package.json#openforge` |
+| `@openforge-app/plugin-sdk/domain` | Shared OpenForge domain types |
+| `@openforge-app/plugin-sdk/prStatusPresentation` | Pull request status presentation helpers |
+| `@openforge-app/plugin-sdk/markdown` | Markdown rendering helpers |
+| `@openforge-app/plugin-sdk/numberParsing` | Numeric parsing helpers |
+| `@openforge-app/plugin-sdk/projectFileTree` | Project file tree helpers |
+| `@openforge-app/plugin-sdk/sanitize` | HTML and SVG sanitization helpers |
+| `@openforge-app/plugin-sdk/pluginIcons` | Plugin icon validation and sanitization |
+| `@openforge-app/plugin-sdk/fileIcons` | File-type icon lookup helpers |
+| `@openforge-app/plugin-sdk/collapsibleSectionState` | Persisted collapse-state helpers |
+| `@openforge-app/plugin-sdk/taskBrowserDevToolsShortcuts` | Task Browser DevTools shortcut helpers |
+
+Shared Svelte components use explicit imports. The package exports:
+
+- `@openforge-app/plugin-sdk/ui/Button.svelte`
+- `@openforge-app/plugin-sdk/ui/Checkbox.svelte`
+- `@openforge-app/plugin-sdk/ui/CollapsibleSection.svelte`
+- `@openforge-app/plugin-sdk/ui/FileTypeIcon.svelte`
+- `@openforge-app/plugin-sdk/ui/MarkdownContent.svelte`
+- `@openforge-app/plugin-sdk/ui/Modal.svelte`
+- `@openforge-app/plugin-sdk/ui/PluginPageHeader.svelte`
+- `@openforge-app/plugin-sdk/ui/PluginPageShell.svelte`
+- `@openforge-app/plugin-sdk/ui/PluginSidebarLink.svelte`
+- `@openforge-app/plugin-sdk/ui/PluginViewState.svelte`
+- `@openforge-app/plugin-sdk/ui/ProjectFileTree.svelte`
+- `@openforge-app/plugin-sdk/ui/ResizablePanel.svelte`
+Use only documented package exports. Do not import OpenForge renderer stores, Electron or preload APIs, Rust internals, app IPC wrappers, or files under this package's `src/` directory.
+
+## Documentation
 
-## Publishing
+- [Plugin authoring guide](https://github.com/koenvg/openforge/blob/main/docs/plugin-authoring.md)
+- [SDK reference](https://github.com/koenvg/openforge/blob/main/docs/plugins/sdk-reference.md)
 
-Automated releases use npm trusted publishing rather than a long-lived npm token. Configure the package's npm Trusted Publisher with repository `koenvg/openforge`, workflow `publish-plugin-sdk.yml`, and environment `npm-publish`. The workflow is the caller npm validates even though the shared publish steps live in `reusable-publish-plugin-sdk.yml`. For a failed tag release, dispatch this workflow manually with the missing `package_version` and disable dry-run.
+The authoring guide documents package metadata, capabilities, frontend and backend runtime boundaries, storage, task APIs, browser surfaces, and CSS loading. The SDK reference lists the public types and shared UI components.
 
 ## License
 
-`@openforge-app/plugin-sdk` is licensed under the MIT License. Plugin authors may use it for personal, internal, open source, or commercial plugin development, including redistribution and modification under the MIT terms.
+The SDK is available under the [MIT License](./LICENSE). Plugins may use, modify, and redistribute it under those terms, including in commercial and private plugins.
 
-This MIT license applies to the SDK package only. The OpenForge desktop application is licensed separately under the repository root `LICENSE` and is source-available/proprietary; the app may not be commercially resold or redistributed without permission.
+The OpenForge desktop application has a separate license. The SDK license does not grant permission to commercially resell or redistribute the app.

package/dist/domain.d.ts

@@ -14,8 +14,10 @@ export type WritableBoardStatus = Exclude<BoardStatus, 'done'>;
 export type WorktreeSource = 'newBranchFromMain' | 'existingBranch' | 'disabled';
 export interface Task {
     id: string;
+    /** @deprecated Use `TaskDetail.prompt` in the bounded Task read APIs. */
     initial_prompt: string;
     status: BoardStatus;
+    /** @deprecated Legacy execution override retained for API version 1 compatibility. */
     prompt: string | null;
     /** Explicit display title; null means fall back to the prompt-derived title. */
     title: string | null;
@@ -37,6 +39,53 @@ export interface Task {
     created_at: number;
     updated_at: number;
 }
+export interface TaskLabel {
+    id: number;
+    projectId: string;
+    name: string;
+}
+export interface TaskReference {
+    id: string;
+    status: BoardStatus;
+    projectId: string;
+    title: string;
+    dependsOn: string[];
+}
+export interface TaskSummary extends TaskReference {
+    createdAt: number;
+    updatedAt: number;
+    promptPreview: string;
+    labels: TaskLabel[];
+    sourceTicketUrl: string | null;
+}
+export interface TaskDetail extends TaskSummary {
+    prompt: string;
+    agent: string | null;
+    permissionMode: string | null;
+    worktreeSource: WorktreeSource | null;
+    worktreeBranch: string | null;
+    titleSource: 'manual' | 'generated' | null;
+    titleGeneratedAt: number | null;
+}
+export interface ActiveTasks {
+    tasks: TaskDetail[];
+    related: TaskReference[];
+}
+export interface CompletedTaskQuery {
+    /** At most 200 Unicode characters. ASCII case-insensitive; non-ASCII casing is exact. */
+    search?: string;
+    /** At most 20 Task Label names; each trimmed name is at most 40 Unicode characters. */
+    labels?: string[];
+    cursor?: string | null;
+}
+export interface CompletedTaskPage {
+    tasks: TaskSummary[];
+    nextCursor: string | null;
+}
+export interface TaskRead {
+    task: TaskDetail;
+    related: TaskReference[];
+}
 export interface GitBranchInfo {
     name: string;
     is_current: boolean;
@@ -601,7 +650,7 @@ export interface FileEntry {
 }
 /** File content with type information */
 export interface FileContent {
-    type: 'text' | 'image' | 'binary' | 'document' | 'large-file';
+    type: 'text' | 'image' | 'video' | 'binary' | 'document' | 'large-file';
     content: string;
     mimeType: string | null;
     size: number;

package/dist/fileIcons.js

@@ -35,6 +35,7 @@ const EXTENSION_ICONS = {
     svg: 'svg',
     png: 'image', jpg: 'image', jpeg: 'image', gif: 'image',
     webp: 'image', bmp: 'image', ico: 'image', avif: 'image',
+    mp4: 'video', m4v: 'video', webm: 'video', ogv: 'video', ogg: 'video', mov: 'video',
     pdf: 'pdf',
     zip: 'zip', tar: 'zip', gz: 'zip', tgz: 'zip', rar: 'zip', '7z': 'zip',
     lock: 'lock',

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { BrowserSurfaceCapture, BrowserSurfaceFeedbackSelection, BrowserSur
 export { OPENFORGE_PACKAGE_METADATA_SCHEMA, OPENFORGE_PLUGIN_CAPABILITIES, isOpenForgePackageMetadata, isPluginPackageMetadata, isSupportedOpenForgeApiVersion, validateOpenForgePackageMetadata, validatePluginPackageMetadata, } from './manifest';
 export { createMemoryPluginStorage, createMockBackendOpenForgeApi, createMockFrontendOpenForgeApi, createMockOpenForgeApi, createMockPluginContext, createOpenForgeRegistryFake, createTestingCalls, TestingOpenForgeRegistryFake, TestingSubscriptionSink, } from './testing';
 export { MAX_AGENT_SESSION_PAGE_SIZE, DEFAULT_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES, MAX_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES, MIN_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES, TaskFollowUpError, MAX_SUPPORTED_API_VERSION, MIN_SUPPORTED_API_VERSION, OPENFORGE_PLUGIN_API_VERSION, SUPPORTED_OPENFORGE_API_VERSIONS, isPluginViewKey, resolveExternalTextFileChunkSize, makePluginViewKey, parsePluginViewKey, } from './types';
-export type { AgentSessionCursor, AgentSessionOverlap, AgentSessionsAPI, AgentSessionSummary, AgentSessionSummaryPage, AgentSessionTaskSummary, AgentSessionWorkspace, AgentCommandDescriptor, AgentCommandMetadata, AgentCommandRuntime, AttentionAPI, BackendReadyState, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, ConfigureStartPromptContributionRequest, CreateTaskRequest, Disposable, BackendFileSystemAPI, ExternalFileMetadata, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadTextFileChunksRequest, ExternalReadFileSystemAPI, FileSystemAPI, UserDataDirectoryRequest, UserDataFileAppendResult, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, ImplementationRun, ListAgentSessionsRequest, ListTaskSessionsRequest, InjectionPointLocation, JsonObject, JsonPrimitive, JsonSchema, JsonValue, MaybePromise, KeyValueConfigAPI, NotificationRequest, NavigationAPI, NotificationsAPI, OpenForgeCommonAPI, OpenForgeContextChangeHandler, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, OpenForgePluginCapability, OpenForgePluginContext, OpenForgePluginPackageJson, PluginCommandInvocationContext, PluginCommandInvocationSource, PluginComponentLoader, PluginComponentModule, PluginEntry, PluginIcon, PluginSidebarNavigationProps, PluginSidebarViewIdentity, PluginInjectionPointProps, PluginSettingsSectionProps, PluginState, PluginSvgIcon, PluginTaskPaneProps, PluginTaskUISectionProps, PluginViewProps, PluginStorage, PluginStorageScope, PluginViewKey, ProjectsAPI, PtyBufferState, ShellAPI, ShellResizeRequest, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, TerminalImageProtocol, TerminalViewSnapshot, ShellSessionRequest, ShellSpawnRequest, ShellWriteRequest, StartPromptContribution, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskFollowUpDisposition, TaskFollowUpErrorCode, TaskFollowUpReceipt, SubscriptionSink, SupportedOpenForgeApiVersion, SystemAPI, TasksAPI, ValidationError, } from './types';
+export type { AgentSessionCursor, AgentSessionOverlap, AgentSessionsAPI, AgentSessionSummary, AgentSessionSummaryPage, AgentSessionTaskSummary, AgentSessionWorkspace, AgentCommandDescriptor, AgentCommandMetadata, AgentCommandRuntime, AttentionAPI, BackendReadyState, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, ConfigureStartPromptContributionRequest, CreateTaskRequest, Disposable, BackendFileSystemAPI, ExternalFileMetadata, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadTextFileChunksRequest, ExternalReadFileSystemAPI, FileSystemAPI, UserDataDirectoryRequest, UserDataFileAppendResult, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, ImplementationRun, ListAgentSessionsRequest, ListTaskSessionsRequest, InjectionPointLocation, JsonObject, JsonPrimitive, JsonSchema, JsonValue, MaybePromise, KeyValueConfigAPI, NotificationRequest, NavigationAPI, NotificationsAPI, OpenForgeCommonAPI, OpenForgeContextChangeHandler, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, OpenForgePluginCapability, OpenForgePluginContext, OpenForgePluginPackageJson, PluginCommandInvocationContext, PluginCommandInvocationSource, PluginComponentLoader, PluginComponentModule, PluginEntry, PluginIcon, PluginSidebarNavigationProps, PluginSidebarViewIdentity, PluginInjectionPointProps, PluginSettingsSectionProps, PluginState, PluginSvgIcon, PluginTaskPaneProps, PluginTaskUISectionProps, PluginViewProps, PluginStorage, PluginStorageScope, PluginViewKey, ProjectsAPI, PtyBufferState, ShellAPI, ShellResizeRequest, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, TerminalImageProtocol, TerminalViewSnapshot, ShellSessionRequest, ShellSpawnRequest, ShellWriteRequest, StartPromptContribution, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskFollowUpDisposition, TaskFollowUpErrorCode, TaskFollowUpReceipt, SubscriptionSink, SupportedOpenForgeApiVersion, SystemAPI, TaskChangeEvent, TaskChangeReason, TaskOperationsAPI, TasksAPI, ValidationError, } from './types';
 export type { MockBackendOpenForgeAPI, MockFrontendOpenForgeAPI, TestingBackgroundServiceContribution, TestingBackendMethodContribution, TestingCommandContribution, TestingContributionBase, TestingExternalTextFile, TestingExternalTextFileChunksCall, TestingEventListenerContribution, TestingOpenForgeApiCalls, TestingOpenForgeApiOptions, TestingOpenForgeRegistrySnapshot, TestingRuntimeKind, TestingRuntimeScope, TestingSettingsSectionContribution, TestingTaskPaneTabContribution, TestingTaskUISectionContribution, TestingViewContribution, } from './testing';
 export { parseStrictFiniteNumber } from './numberParsing';
 export { buildProjectFileTree, flattenVisibleProjectFileTree, formatProjectFileTreeSize, getProjectFileTreeDepth, getProjectFileTreeItemAccessibility, getProjectFileTreeKeyboardAction, getProjectFileTreeParentPath, hasProjectFileTreeShortcutModifier, projectFileTreePathToId, } from './projectFileTree';

package/dist/markdown.js

@@ -1,10 +1,16 @@
-import { marked } from 'marked';
+import { marked, Renderer } from 'marked';
 import { sanitizeHtml } from './sanitize';
 /** Attribute holding the original URL of a `<img>`/`<a>` awaiting resolution. */
 export const MARKDOWN_REMOTE_MEDIA_ATTRIBUTE = 'data-markdown-remote-src';
+class MarkdownRenderer extends Renderer {
+    table(token) {
+        return `<div class="markdown-table-scroll">${super.table(token)}</div>`;
+    }
+}
 const markedOptions = {
     gfm: true,
     breaks: true,
+    renderer: new MarkdownRenderer(),
 };
 const RENDERED_MARKDOWN_CACHE_CAPACITY = 100;
 const renderedMarkdownCache = new Map();

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;