WAIT — Mixed signals — read the receipts

• Last commit 7w ago
• 18 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ Scorecard: marked unmaintained (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

An unofficial VS Code extension that embeds the Draw.io (diagrams.net) diagramming editor directly into VS Code, allowing users to create and edit .drawio, .drawio.svg, and .drawio.png files without leaving the editor. It uses an offline Draw.io instance, supports multiple themes, and enables collaborative editing via VS Code Liveshare and code-to-diagram linking via the 'code link' feature. Hybrid monorepo structure: src/ contains the main VS Code extension logic (TypeScript), while drawio-custom-plugins/ is a separate webpack-bundled package that builds plugins for the embedded Draw.io instance (drawio-custom-plugins/src/). The extension defines two custom editors in package.json (text-based .drawio and binary .drawio.png handlers). Examples and documentation live in docs/ and examples/.

Software architects, UML modelers, and technical teams who need to create, version-control, and collaboratively edit diagrams (architecture diagrams, flowcharts, ERDs) alongside code without relying on external SaaS tools. Contributors should have TypeScript/webpack experience and familiarity with VS Code extension APIs.

Production-ready and actively maintained. The extension is at version 1.9.0 and is officially mentioned in the diagrams.net blog. The repo has CI/CD pipelines (GitHub Actions in .github/workflows/), comprehensive TypeScript codebase (139KB), and clear release notes in CHANGELOG.md. Last activity indicates ongoing development.

Single maintainer (Henning Dieterichs) creates maintenance risk. The extension depends on an embedded Draw.io instance (a large external project), and the custom plugin system (drawio-custom-plugins/) adds complexity. No visible test suite structure in the top-level file list, which is a gap for an extension handling file I/O and Liveshare synchronization. Breaking changes are possible with VS Code API updates (requires >=1.70.0).

The extension is in steady maintenance: v1.9.0 is current, workflows are running tests and deployments, and the code has been recently touched (GitHub Actions logs suggest active CI). Focus areas appear to be stability of Liveshare integration, code-link symbol resolution improvements, and theme handling. CHANGELOG.md would reveal the latest feature additions.

git clone https://github.com/hediet/vscode-drawio.git
cd vscode-drawio
npm install
npm run dev  # or check package.json scripts for exact build/watch commands

Then open .vscode/launch.json to debug the extension in VS Code itself.

Daily commands:

npm run watch  # Watch TypeScript and webpack in development
# OR
npm run build  # Single production build
# Then press F5 in VS Code to launch the extension in a debug instance

Check package.json "scripts" section for exact targets (likely scripts like compile, watch, test).

• src/index.ts — Extension entry point that initializes all features, commands, and registers editor providers—every contributor must understand how the extension activates.
• src/Extension.ts — Core extension class managing lifecycle, feature coordination, and VS Code API integration—central to all extension behavior.
• src/DrawioClient/DrawioClient.ts — Abstraction layer communicating with the Draw.io application via postMessage API—critical for diagram editing functionality.
• src/DrawioEditorProviderBinary.ts — Custom editor provider for binary formats (.drawio, .png, .svg)—implements the core file handling and persistence logic.
• src/DrawioClient/webview-content.html — HTML/JS bootstrap for the webview containing the Draw.io editor instance—defines the editor UI boundary.
• drawio-custom-plugins/src/index.ts — Custom plugin entry point injected into Draw.io webview, enabling VS Code-specific features like code linking and liveshare.
• package.json — Defines extension manifest, activation events, commands, and all build/runtime dependencies—configuration source of truth.

Add a New Custom Plugin Feature

1. Create a new TypeScript file in drawio-custom-plugins/src/ implementing your feature (e.g., myFeature.ts). Export a default function that receives the Draw.io instance and api parameters. (drawio-custom-plugins/src/index.ts)
2. Import and register your feature in the plugin index by adding an initialization call: myFeature(instance, api); (drawio-custom-plugins/src/index.ts)
3. Implement communication with VS Code extension via window.vscodeApi.postMessage() for bidirectional messages. (drawio-custom-plugins/src/vscode.ts)
4. Rebuild plugins: run npm run build at the repo root to bundle your feature via webpack. (drawio-custom-plugins/webpack.config.ts)

Add a New VS Code Command

1. Define the command in the VS Code extension manifest by adding an entry to the contributes.commands array in package.json with a unique command ID and title. (package.json)
2. Register the command handler in src/Extension.ts within the constructor, calling context.subscriptions.push(vscode.commands.registerCommand('your.command.id', handler)). (src/Extension.ts)
3. Implement the handler logic in the Extension class or a dedicated feature class (e.g., src/features/MyFeature.ts) with access to editor and DrawioClient instances. (src/Extension.ts)

Add Support for a New Diagram File Format

1. Register a new editor provider in package.json under contributes.customEditors, specifying the file glob pattern (e.g., *.myformat) and viewType. (package.json)
2. Create a new editor provider class (e.g., src/DrawioEditorProviderMyFormat.ts) extending the base pattern from DrawioEditorProviderBinary.ts, implementing serialization logic specific to your format. (src/DrawioEditorProviderBinary.ts)
3. Register the provider in src/Extension.ts within the registerEditors() method using context.subscriptions.push(vscode.window.registerCustomEditorProvider(viewType, provider)). (src/Extension.ts)

Add a New Configuration Setting

1. Define the setting in package.json under contributes.configuration.properties with a unique scope prefix (e.g., drawio.myNewSetting). (package.json)
2. Read the setting in src/Config.ts using vscode.workspace.getConfiguration('drawio').get('myNewSetting'). (src/Config.ts)
3. Pass the configuration value to the DrawioClient via the webview initialization data in DrawioEditorProviderBinary.ts so it can be used in the custom plugin. (src/DrawioEditorProviderBinary.ts)

• VS Code Extension API — Only way to deeply integrate custom editors and commands into VS Code; provides webview isolation, file system access, and command palette integration.
• Draw.io (diagrams.net) Web App — Mature, feature-complete diagramming tool with embedded mode; offline-capable; avoids reimplementing diagram rendering logic.
• postMessage API (webview ↔ extension) — Only secure way to communicate between isolated webview process and VS Code extension process; prevents XSS and maintains security model.
• TypeScript + Webpack — Type safety for large codebase; webpack bundles plugins into single file for webview delivery; matches VS Code extension development conventions.
• Live Share API — Enables collaborative editing without reimplementing sync logic; VS Code native feature with low latency.

• Offline Draw.io bundled in extension vs. CDN-hosted

  • Why: Users need reliability and avoid network dependency; offline version avoids external service calls.
  • Consequence: Larger extension package size (~10+ MB); requires manual updates when Draw.io upstream changes.

• Custom plugin injection into Draw.io webview

  • Why: Only way to add VS Code features (code linking, live share) without forking Draw.io; Draw.io has plugin API.
  • Consequence: Plugin code runs in Draw.io's JavaScript context; tightly coupled to Draw.io internal APIs; fragile across version updates.

• Support multiple file formats (.drawio, .drawio.png, .drawio.svg) with embedded

  • Why: undefined
  • Consequence: undefined

No obvious environment variables required, but the extension relies on an offline Draw.io distribution (bundled or fetched) that may need to be present at build time—check webpack config for asset references. Liveshare synchronization is text-based: simultaneous edits in the Draw.io XML can conflict; the extension acknowledges this in the README but doesn't fully prevent it. Custom editor priority: both text and binary editors are registered with 'default' priority, so VS Code's selection logic matters. File format conversions (.drawio ↔ .drawio.svg ↔ .drawio.png) require correct XML wrapping and PNG/SVG metadata handling, which may have edge cases.

• VS Code Custom Editors — This extension implements two custom editor types (viewType) to display .drawio and .drawio.png files; understanding the custom editor lifecycle (onDidChangeDocument, onDidChangeViewState) is fundamental to modifying file handling
• Embedded SVG/PNG with XML Metadata — .drawio.svg and .drawio.png files are valid image files with embedded Draw.io XML in metadata; the extension must parse, update, and re-embed this XML while preserving image validity
• VS Code Liveshare CRDT Synchronization — The extension uses Liveshare's shared text documents to sync diagram changes across participants; understanding conflict resolution and eventual consistency is critical for the collaborative editing feature
• Webpack Module Federation / Plugin Architecture — The drawio-custom-plugins/ package is bundled separately and injected into the embedded Draw.io instance as a plugin; understanding this plugin loading mechanism is key to extending Draw.io functionality
• Workspace Symbol Search (Code Link Feature) — The code-link feature uses VS Code's workspace symbol provider to resolve #SymbolName labels in diagram nodes to source code; this requires familiarity with language server protocol (LSP) symbol kinds
• File Format Conversion (Format Agnostic Storage) — The extension supports lossless conversion between .drawio (XML), .drawio.svg (embedded XML + SVG), and .drawio.png (embedded XML + PNG) while preserving the diagram; this requires robust XML parsing and image format handling
• TypeScript Monorepo with Separate Webpack Builds — The project uses separate TypeScript compilation for the main extension (src/) and the Draw.io plugin bundle (drawio-custom-plugins/); understanding the two build outputs and how they communicate is critical for local development

• jgraph/drawio — The official Draw.io repository; this extension embeds and wraps the actual Draw.io editor, so understanding the core project is essential for plugin development
• microsoft/vscode-extension-samples — Official VS Code extension examples demonstrating custom editor APIs, file system integration, and Liveshare support patterns used in this extension
• excalidraw/excalidraw — Alternative whiteboard/diagram tool with similar collaborative features; users often evaluate both for remote diagramming use cases
• mermaid-js/mermaid — Diagram-as-code alternative using markdown syntax; competes for similar use cases (architecture docs embedded in repos) but with a different paradigm
• microsoft/vscode-liveshare — The VS Code Liveshare extension that this project integrates with for collaborative editing; understanding its document synchronization model is vital for the sync feature

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for custom plugins (drawio-custom-plugins)

The drawio-custom-plugins directory contains multiple TypeScript modules (focus.ts, linkSelectedNodeWithData.ts, liveshare.ts, menu-entries.ts, propertiesDialog.ts, vscode.ts) but there's no visible test suite. Given these handle critical VS Code integration features like code linking and LiveShare support, automated tests would prevent regressions and document expected behavior.

• [ ] Create drawio-custom-plugins/tests/ directory with test files matching src/ modules
• [ ] Add Jest or Vitest configuration to drawio-custom-plugins/tsconfig.json
• [ ] Write tests for vscode.ts integration with VS Code API mocks
• [ ] Write tests for linkSelectedNodeWithData.ts code-linking functionality
• [ ] Add test script to package.json and integrate into .github/workflows/test.yml

Document plugin system and custom plugin API in docs/plugins.md

The docs/plugins.md file exists but there's no corresponding detailed documentation visible. The drawio-custom-plugins directory contains a complete plugin system (types.d.ts, drawio-types.d.ts, vscode.ts exports) used for features like code linking and LiveShare, but new contributors can't understand how to extend it without API documentation.

• [ ] Document the plugin lifecycle and initialization in drawio-custom-plugins/src/index.ts
• [ ] Add TypeScript interface documentation from drawio-types.d.ts and types.d.ts to plugins.md
• [ ] Create a 'Building Custom Plugins' section with example code showing how to add menu entries and handle vscode commands
• [ ] Document the vscode.ts API surface (getActiveEditor, etc.) with examples
• [ ] Add a section explaining how plugins integrate with the webpack bundle in drawio-custom-plugins/webpack.config.ts

Add E2E tests for format conversion and export workflows

The extension supports conversion between multiple formats (.drawio, .dio.svg, .drawio.png) and has export/convert commands registered in package.json, but there are no visible E2E tests validating these workflows work correctly. The examples/formats/ directory has test files but they're unused.

• [ ] Create .github/workflows/e2e-tests.yml workflow using VS Code Testing Library or Playwright
• [ ] Add test file in tests/e2e/ directory that opens example files from examples/formats/ and tests 'Draw.io: Convert To' command
• [ ] Test conversion between all supported formats (.drawio → .drawio.svg → .drawio.png round-trip)
• [ ] Test that .drawio.svg and .drawio.png files remain valid SVG/PNG format after editing
• [ ] Verify the export command generates correct output formats using examples/formats/Example.* as reference

• Add unit tests for drawio-custom-plugins/src/linkSelectedNodeWithData.ts to validate code-link symbol resolution across different language file types (.ts, .java, .py, etc.). Currently no test structure visible.
• Enhance drawio-custom-plugins/src/menu-entries.ts to expose Draw.io's native alignment/distribution tools as VS Code commands; these are useful but not surfaced in the command palette.
• Document the plugin API contract in drawio-custom-plugins/src/types.d.ts and drawio-custom-plugins/src/drawio-types.d.ts with JSDoc comments; the types are minimal and unclear for contributors extending the plugin system.

The vscode-drawio extension has moderate security posture with notable risks. The primary concerns are: (1) Potential XSS vulnerabilities from diagram content rendering in webviews, (2) Custom

• High · Webview Content Injection Risk — src/DrawioClient/webview-content.html, src/DrawioClient/CustomizedDrawioClient.ts. The extension loads Draw.io in a webview (src/DrawioClient/webview-content.html) which could be vulnerable to XSS attacks if user-supplied diagram content is not properly sanitized. Draw.io files are XML-based and could contain malicious scripts if not properly escaped when rendered. Fix: Ensure all diagram content is properly sanitized before rendering in the webview. Use VS Code's webview security context (contentSecurityPolicy, scripts) and validate/escape all user input from .drawio files. Consider using DOMPurify or similar for sanitizing XML content.
• High · Plugin System Security Risk — drawio-custom-plugins/, src/DrawioClient/CustomizedDrawioClient.ts. The extension supports custom plugins (drawio-custom-plugins directory) loaded dynamically. This creates a significant attack surface as malicious plugins could execute arbitrary code within the VS Code context and access file system, sensitive data, or VS Code APIs. Fix: Implement strict plugin validation, code signing, and sandboxing. Only load plugins from trusted sources. Consider restricting plugin capabilities through a permission system. Validate plugin manifests and code before execution.
• Medium · Missing Dependency Lock File Visibility — package.json (no lock file shown). The package.json is provided but package-lock.json or yarn.lock is not visible in the file structure. This makes it difficult to verify if dependencies have been pinned to specific versions, increasing risk of supply chain attacks through transitive dependency updates. Fix: Ensure package-lock.json (for npm) or yarn.lock is committed to version control and reviewed. Use exact versions (not ^ or ~) for critical dependencies. Run npm audit regularly and address vulnerabilities.
• Medium · External Draw.io Resource Loading — src/DrawioClient/DrawioClient.ts, src/DrawioClient/webview-content.html. The extension integrates with Draw.io (diagrams.net) which involves loading external resources and potentially communicating with remote servers. The README mentions 'Uses an offline version' but the actual security implementation for network requests is not visible in the provided files. Fix: Verify that only offline Draw.io components are used and no unnecessary external network requests are made. If network communication is required, implement certificate pinning, validate all responses, and use HTTPS exclusively. Document all external dependencies.
• Medium · Vague File Format Handling — src/DrawioEditorProviderBinary.ts, src/DrawioEditorProviderText.ts. The extension handles multiple file formats (.drawio, .dio, .drawio.svg, .drawio.png) with different parsers (Binary and Text editors). SVG and PNG files with embedded diagram data could be exploited if the parsing logic doesn't properly validate file structure and content. Fix: Implement strict validation for all file formats. For SVG files, sanitize XML content before parsing. For PNG files, validate the file structure and embedded data format. Use safe parsing libraries and handle errors gracefully without exposing debug information.
• Low · Unclear Untrusted Workspace Handling — package.json, drawio-custom-plugins/. While the extension declares 'untrustedWorkspaces.supported: true', it's unclear what restrictions are actually enforced when running in untrusted workspaces. The custom plugins feature could be particularly dangerous in untrusted environments. Fix: Document and implement specific restrictions for untrusted workspace mode. Disable or heavily restrict plugin loading in untrusted workspaces. Disable potentially dangerous operations like file system access or external network requests.
• Low · Missing Security Headers Documentation — src/DrawioClient/webview-content.html. No visible Content Security Policy (CSP) or security headers configuration is evident for the webview component, which could allow injection attacks. Fix: Implement strict Content Security Policy headers in the webview. Use nonce-based script loading, disable inline scripts, and restrict resource loading to trusted sources only.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/hediet/vscode-drawio shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live hediet/vscode-drawio repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hediet/vscode-drawio.

What it runs against: a local clone of hediet/vscode-drawio — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in hediet/vscode-drawio | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 80 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of hediet/vscode-drawio. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/hediet/vscode-drawio.git
#   cd vscode-drawio
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of hediet/vscode-drawio and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "hediet/vscode-drawio(\\.git)?\\b" \\
  && ok "origin remote is hediet/vscode-drawio" \\
  || miss "origin remote is not hediet/vscode-drawio (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/index.ts" \\
  && ok "src/index.ts" \\
  || miss "missing critical file: src/index.ts"
test -f "src/Extension.ts" \\
  && ok "src/Extension.ts" \\
  || miss "missing critical file: src/Extension.ts"
test -f "src/DrawioClient/DrawioClient.ts" \\
  && ok "src/DrawioClient/DrawioClient.ts" \\
  || miss "missing critical file: src/DrawioClient/DrawioClient.ts"
test -f "src/DrawioEditorProviderBinary.ts" \\
  && ok "src/DrawioEditorProviderBinary.ts" \\
  || miss "missing critical file: src/DrawioEditorProviderBinary.ts"
test -f "src/DrawioClient/webview-content.html" \\
  && ok "src/DrawioClient/webview-content.html" \\
  || miss "missing critical file: src/DrawioClient/webview-content.html"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 80 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~50d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/hediet/vscode-drawio"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.