AeroFig

AeroFig is a diagram editor for VS Code and VS Code for the Web. Keep an editable *.aerofig.json document alongside your code, then export a self-contained HTML file that includes the same editor. Recipients can view, pan, zoom, edit, and download their changes without an extension, account, server, or network access.

First diagram

1. Run AeroFig: New Diagram and choose a *.aerofig.json filename.
2. Click a shape in the palette, or drag it onto the canvas.
3. Choose Connect, then click the source and target shapes.
4. Drag shapes to move them. Select a shape and drag its bottom-right handle to resize it. Double-click a shape or connection to edit its label.
5. Use Save or VS Code's native Save command, then Export HTML to share.

Open examples/architecture.aerofig.json for a small infrastructure diagram. Use Reopen Editor With → Text Editor to edit the JSON directly.

Editing

• Process, decision, start/end, service, database, container, and embedded-image shapes.
• Attached straight or orthogonal arrows, with editable connection labels.
• Shift-click for multiple selection; group, ungroup, duplicate, delete, and align left.
• Moving a container also moves its descendants. Membership is explicit in parentId; placing a shape visually inside a container does not automatically reparent it.
• Grid snapping, arrow-key nudging, pan with Space + drag, wheel zoom, and Fit.
• Undo/redo uses VS Code's document history inside the extension, and a bounded in-memory history in standalone HTML.
• Semantic fill/stroke colors and geometry are editable in the inspector. Literal color overrides, text colors, and font sizes can also be set in JSON.
• PNG, JPEG, and WebP images are embedded in the document. The file picker allows up to 4 MiB per image; total encoded assets are limited to 12 MiB.
• SVG export for scalable static diagrams.

Keyboard shortcuts: V select, C connect, Escape cancel, Delete remove, Ctrl/Cmd+D duplicate, Ctrl/Cmd+A select shapes, Ctrl/Cmd+Z undo, Ctrl/Cmd+Shift+Z redo, and Ctrl/Cmd+S save/download JSON. Shortcuts leave text inputs alone. Arrow keys move selected shapes by one unit, or ten with Shift.

Files and portability

The HTML starts in viewing mode. Edit diagram enables the same canvas editor. Download JSON saves an editable source file; Export HTML downloads an updated HTML file that still includes the editor. Browser editing does not overwrite the original file automatically, so download your changes before closing the page. SVG downloads are static images and do not contain the editor.

Open exported *.aerofig.html files in AeroFig to edit them, or run AeroFig: Import HTML as JSON to recover their JSON source. HTML imports extract only the application/aerofig+json document block; the extension always uses its bundled runtime. Imported scripts are never executed in the extension.

Repository theme

Run AeroFig: Configure Workspace Theme, or commit .aerofig/theme.json:

{
  "version": 1,
  "name": "Team",
  "colors": {
    "background": "#f5f7fb",
    "foreground": "#192b40",
    "accent": "#4263eb",
    "surface": "#ffffff",
    "muted": "#738398",
    "success": "#16866c",
    "warning": "#bf7c16",
    "danger": "#d64c63"
  },
  "typography": { "fontFamily": "system-ui, sans-serif" },
  "shapes": { "radius": 12, "strokeWidth": 2 },
  "connectors": { "routing": "orthogonal" }
}

The version, colors, and its background, foreground, and accent entries match AeroDeck's theme convention. Optional diagram-specific defaults describe shapes and connectors. Colors use hex notation or transparent; fonts use installed font families with a system fallback, with no external font downloads.

New diagrams copy the theme from their own workspace folder. Existing diagrams keep their theme snapshot until Apply Repository Theme is invoked. Shapes can reference tokens such as accent and surface; explicit hex overrides remain unchanged when a theme is applied. Standalone HTML supports importing the same theme JSON. VS Code applies changes through its document edit API, so theme changes can be undone and reviewed in Source Control.

Document contract

The document declares type: "aerofig/diagram" and version: 1. It contains title, theme, nodes, edges, and assets. Nodes have stable IDs, absolute canvas coordinates, dimensions, labels, and an optional container parentId. Edges reference node IDs. assets contains { "id", "data" } embedded raster images; image nodes refer to an assetId.

The editor schema is in schema/diagram.schema.json; repository themes use schema/theme.schema.json. Runtime validation also checks cross-references, unique IDs, container cycles, and size limits. Unknown versions are rejected. Additional fields are preserved so ordinary JSON editing does not discard metadata. The canvas viewport and selection are UI state and are not committed to the model.

The extension uses vscode.workspace.fs and a CustomTextEditorProvider, including in virtual repositories. Edits carry a document version and are validated before application. Conflicting or failed edits preserve a recovery snapshot in webview state; Recover canvas writes it to a separate JSON file. Malformed source files are never replaced by an empty starter diagram.

Releases and Marketplace publishing

The repository secret VSCE_TOKEN authenticates publishing as bpcarson.aerofig. The publishing step passes it to VSCE through VSCE_PAT; it is not needed for PR verification or packaged into the extension.

• Auto Patch Version follows the shared bpcarson/actions workflow after a successful Verify push run on main. Product changes without a version change receive a patch-version PR, which the shared workflow merges before dispatching the release workflow. Explicit version changes are preserved.
• Release on version bump creates a GitHub release when package.json changes version on main, then calls Publish VSIX directly. This direct call also works for releases created with GITHUB_TOKEN.
• Publish VSIX checks out the release tag, checks the version and publisher, runs the full verification suite, packages aerofig.vsix, attaches it to the GitHub release, and publishes that same package to the VS Code Marketplace. A missing publishing token fails visibly. Retries skip an already-published Marketplace version.

For the first release after these workflows are merged, run Release on version bump → Run workflow on main. It releases the current package version even without another version edit. To retry an existing release, run Publish VSIX with its tag (for example v0.1.0).

The shared auto-patch workflow requires GitHub Actions permission to create and merge pull requests, as in the other Aero repositories.

Development

Requires Node.js 22 or newer.

npm ci
npx playwright install --with-deps chromium
npm run verify
npm run test:web
npm run package:vsix

verify checks syntax, bundles the browser-compatible extension, runs document and host-adapter tests, and drives the actual offline editor in Chromium. test:web opens the extension in pinned VS Code Web 1.100.0 and exercises a native virtual-workspace save. package:vsix produces aerofig.vsix for installation; CI uploads the package and verification screenshots without publishing a release.

The renderer and document modules are shared between the extension and exported HTML. The extension bundle externalizes only vscode; it needs no Node APIs at runtime. scripts/schema.mjs regenerates the JSON schemas.

This initial release does not yet include vendor icon libraries, automatic graph layout, obstacle-avoiding connector routing, Excalidraw/draw.io format interchange, PNG export, collaboration, or dedicated AeroCode tools/AeroKit evaluation adapters. Normal file tools can already read and edit the JSON document. Large diagrams are bounded to 2,000 nodes and 4,000 edges; those limits are validation bounds, not a performance guarantee. Long labels are wrapped and visually truncated to fit their shape; their complete text remains in the document and tooltip.

AeroFig is independent of Excalidraw, draw.io, and Bento. MIT licensed.

AeroCode and agent tools

The extension bundles the aerofig chat skill and registers four language-model tools:

These tools work in VS Code Web without a terminal. Creation accepts a complete document; ordinary source edits use the agent's file tools. All paths are workspace-relative (prefix the unique folder name in multi-root workspaces). Writes reject unsaved destinations and require overwrite: true to replace existing files.

Results follow the AeroDeck protocol-v1 envelope: ok, capabilityStatus, recoverable, effectOutcome, text, artifacts, and an optional error. A file can be committed even when opening the editor fails; callers should inspect effectOutcome before retrying.

The release also includes a standalone aerofig-cli.js (Node.js 22+):

node aerofig-cli.js create diagrams/example.aerofig.json
node aerofig-cli.js validate diagrams/example.aerofig.json
node aerofig-cli.js export diagrams/example.aerofig.json diagrams/example.aerofig.html
node aerofig-cli.js preview diagrams/example.aerofig.json
node aerofig-cli.js tools
node aerofig-cli.js tool aerofig_validateDiagram --input '{"filePath":"diagrams/example.aerofig.json"}'

Run from the repository root. create accepts --input with a complete document JSON; create/export accept --force for replacement. The bundled CLI carries its HTML editor assets and works outside the source checkout. CLI create/open validate the document but report degraded visual-editor capability. preview writes an editable HTML file to a temporary directory and prints its URL.

Appearance and screenshot gallery

The default light/dark palettes pair indigo accents with teal data/start/end shapes and amber decisions. Explicit shape styles override these defaults. Dark appearance adapts semantic colors for readability without rewriting the source theme or export colors; custom repository colors are preserved.

npm run test:browser captures six Playwright screenshots in test-results/screenshots/: light/dark desktop, selected-node properties, and mobile layouts. CI uploads them as aerofig-playwright-screenshots. To run only the gallery after installing Playwright Chromium:

node --test --test-name-pattern="screenshot gallery" test/editor.browser.cjs

These are review screenshots, not pixel-difference baselines. Palette tests check label contrast and preservation of custom theme values.

Screenshots

Captured by Playwright from the light/dark palette update. CI generates fresh captures in the aerofig-playwright-screenshots artifact; these checked-in images provide a browsable reference.

Light	Dark