feat(vscode): export diagrams as SVG/PNG from the Docify preview panel

[YoofiTT96]

Feature Proposal

Target Project:

calm-plugins/vscode — the CALM VSCode extension.

Description of Feature:

Adds an Export dropdown to the diagram toolbar in the extension's Docify preview panel, letting users save any rendered Mermaid diagram directly to disk as an SVG or PNG file — without leaving the IDE.

User Stories:

• As an architect, I want to export a rendered CALM diagram as an SVG so that I can embed a vector-quality image in documentation or presentations.
• As a developer, I want to export a diagram as a PNG so that I can share a snapshot with team members who don't have the extension installed.
• As a tech writer, I want a one-click export from the preview panel so that I don't have to run the CLI's --export-diagrams flag separately just to get an image of a single diagram.

Current Limitations:

The CLI's --export-diagrams flag (merged in #2634) renders all Mermaid blocks in a documentation output directory via a local browser. That works well for batch documentation generation, but the VSCode extension's Docify preview panel has no export capability of its own. Users who want a single diagram image must either:

• Run calm docify --export-diagrams svg from the terminal and hunt for the output file, or
• Take a screenshot of the preview panel.

Proposed Implementation:

Webview side (calm-plugins/vscode/src/features/preview/webview/):

Screen.Recording.2026-06-18.at.4.58.22.PM.mov

• diagram-export.ts — captures the live SVG from the diagram container and applies three fixes before serialising. For PNG rasterises it via html-to-image.
• diagram-controls.ts — replaces the former separate SVG/PNG buttons with a single Export dropdown using <vscode-button> + <vscode-context-menu> from @vscode-elements/elements.

Extension host side (calm-plugins/vscode/src/features/preview/):

• commands.ts — new ExportDiagramCmd command receives the exportDiagram message from the webview.
• preview-panel.ts — handleExportDiagram() shows VSCode's native save dialog (pre-filled with <arch-basename>-diagram-<n>.<ext> in the same directory as the open file), then writes the SVG string or base64-decoded PNG buffer via vscode.workspace.fs.

API changes: none — communication uses the existing webview message bus.
Data model changes: none.
Dependencies added: html-to-image (webview rasterisation); @vscode-elements/elements is already used elsewhere in the extension.

Alternatives Considered:

• Separate SVG and PNG buttons: Implemented first, replaced with the Export dropdown to keep the toolbar compact as more export formats could be added in future.
• Reuse the CLI's browser-based renderer: The CLI launches a Playwright browser to render Mermaid server-side. Pulling that into the extension host would add significant startup latency per diagram and require bundling Playwright; the webview already has a live, fully-rendered SVG, so capturing it client-side is lighter and instant.
• Canvas-based PNG export: Considered drawSvgToCanvas approaches but html-to-image handles off-screen layout and style computation more reliably across the range of SVG shapes Mermaid produces.

Testing Strategy:

• Unit tests (diagram-export.spec.ts): cover serializeSvgElement, rasterizeSvgElementToPng, exportDiagram, and each of the three SVG fix helpers (inlineResolvedFont, restoreDiagramViewBox, preventForeignObjectClipping) with jsdom mocks.
• Unit tests (diagram-controls.spec.ts): verify the Export dropdown is rendered when callbacks are provided, is absent when neither callback is provided, and fires the correct callback on menu selection.
• Unit tests (preview-panel.spec.ts): verify handleExportDiagram calls vscode.window.showSaveDialog, writes the correct buffer, and shows the confirmation message.
• Manual / E2E: open a CALM architecture file in the Extension Development Host, switch to the Docify tab, use the Export dropdown, and verify the saved SVG opens correctly in a browser and the PNG is a valid image.

Documentation Requirements:

• Update calm-plugins/vscode/README.md to document the Export dropdown in the Docify preview panel.
• Update calm-plugins/vscode/AGENTS.md under the Webview Preview section to reference the new diagram-export.ts and diagram-controls.ts modules.

Implementation Checklist:

• Design reviewed and approved
• Implementation completed
• Tests written and passing
• Documentation updated
• Relevant workflows updated (if needed)
• Performance impact assessed

Additional Context:

This feature is the VSCode companion to the CLI --export-diagrams flag (merged in #2634). Both share the same underlying goal — high-fidelity diagram export — but serve different workflows: the CLI targets batch documentation pipelines, while this targets interactive single-diagram export from within the IDE.