orz-plot

A VS Code custom editor for interactive Plotly charts. Write your chart as JSONC — comments included — and see a live preview side-by-side.

GitHub: https://github.com/wangyu16/orz-plot-vscode

Author: Yu Wang · yuwang@orz.how

Quick Start with an AI Agent

You don't need to learn Plotly JSON by hand. Open the file in VS Code, then ask any AI coding assistant (Claude, Copilot, ChatGPT, etc.):

"Create a bar chart of monthly sales in 2024. Use the Scientific theme. Place the legend horizontally below the chart."

The agent will write the complete JSONC spec and paste it into your file. Built-in Agent Skills available to guide AI agent work properly with this editor.

Tips for AI-assisted charting

Give the agent your raw data and describe the chart type, colours, and style you want. It will handle the Plotly syntax.
For major revisions — new trace types, different layouts, theme changes — let the agent rewrite the spec entirely.
For minor tweaks (axis label, a single number, one colour) you can edit directly in the Monaco editor on the left.
Add // line comments or /* block comments */ anywhere in the JSONC as author notes. They are preserved on every save and invisible to Plotly.

Features

Live custom editor for .plot.html and .plot.svg
JSONC source with // and /* */ comments preserved on save
Monaco editor with IntelliSense for the Plotly JSON schema
Live Plotly preview with Zoom selector (25 % – 200 %, default 100 %)
Adjustable editor/preview split; position is persisted per file
MathJax rendering — inline $...$ , display $$...$$, chemistry \ce{...} via mhchem
Save back to the same format as the opened file
Format-aware export:
- .plot.html source → export SVG
- .plot.svg source → export HTML
7 built-in templates to start a new chart
Export always captures at the dimensions defined in layout.width / layout.height, regardless of the zoom level

Supported Trace Types

plotly-basic is bundled (~1 MB vs the ~3 MB full Plotly build), which covers:

bar · scatter · pie · heatmap · histogram

Editor UI

Control	Location	Purpose
Monaco editor	left pane	Edit JSONC source; full IntelliSense
Splitter	centre	Drag to resize editor vs preview
Zoom selector	action bar (top right)	Scale preview: 25 % – 200 %
Save button	action bar	Save and re-render at original dimensions
Export button	action bar	Export to the other format (SVG ↔ HTML)

File Formats

`.plot.html` (canonical)

JSONC stored in <script id="orz-chart-meta" type="application/orz-plot+jsonc">
Static rendered output saved alongside for standalone browser viewing

`.plot.svg` (editable compatibility)

JSONC stored in <metadata id="orz-chart-meta"><![CDATA[...]]></metadata>
Regenerated entirely on every save; JSONC is the single source of truth

Bare JSONC

Plain .json / .jsonc chart specs are accepted on open and hydrated into the current format on first save.

Example JSONC

{
  // GDP per capita — illustrative values, World Bank basis
  "data": [
    {
      "type": "scatter",
      "mode": "lines+markers",
      "name": "East Asia",
      "x": [2010, 2012, 2014, 2016, 2018, 2020, 2022, 2023],
      "y": [8.1, 9.4, 10.8, 12.1, 13.9, 13.2, 15.7, 16.8],
      "line": { "color": "#4C78A8", "width": 2.5 }
    }
  ],
  "layout": {
    "title": { "text": "GDP per Capita by Region" },
    "width": 860,
    "height": 500,
    "xaxis": { "title": { "text": "Year" } },
    "yaxis": { "title": { "text": "USD thousands (2015 prices)" } },
    "legend": {
      "orientation": "h",
      "x": 0.5, "xanchor": "center",
      "y": -0.15, "yanchor": "top"
    }
  }
}

Text Formatting

Need	Syntax	Example
Superscript	`<sup>…</sup>`	`"m/s<sup>2</sup>"`
Subscript	`<sub>…</sub>`	`"H<sub>2</sub>O"`
Bold / Italic	`<b>`, `<i>`	`"<b>Note</b>"`
Unicode	plain UTF-8	`"α"`, `"μ"`, `"°C"`, `"→"`
LaTeX inline	$...$	`"$k_{\\text{cat}}$"`
LaTeX display	`$$...$$`	`"$$\\frac{dC}{dt}=-kC^2$$"`
Chemistry	$\\ce{...}$	`"$\\ce{H2SO4}$"`

Legend Positioning

Common placements for the "legend" key inside "layout":

// Horizontal, centred below the chart  ← most common
"legend": { "orientation": "h", "x": 0.5, "xanchor": "center", "y": -0.15, "yanchor": "top" }

// Inside top-left corner of the plot
"legend": { "x": 0.01, "y": 0.99, "xanchor": "left", "yanchor": "top" }

// Inside top-right corner
"legend": { "x": 0.99, "y": 0.99, "xanchor": "right", "yanchor": "top" }

// Hidden
"showlegend": false

Important: Always include "xanchor": "center" when using "x": 0.5 for a horizontal legend, otherwise Plotly places the legend's left edge at the centre and it appears shifted to the right.

Legend style fields: bgcolor, bordercolor, borderwidth, font, title, itemsizing, traceorder.

Included Templates

New empty files open a template gallery. Available templates:

bar · line · scatter · pie · heatmap · histogram · area

Example Files

examples/ contains six ready-to-open .plot.svg charts:

browser-market-share.plot.svg
gdp-by-region.plot.svg
gene-expression-heatmap.plot.svg
portfolio-performance.plot.svg
reaction-kinetics.plot.svg
score-distributions.plot.svg

Development

Requirements: Node.js, npm, VS Code

npm install          # install deps
npm run build        # compile with esbuild
npm run package      # produce orz-plot-0.1.0.vsix

Run in development: open the repo in VS Code and press F5.

Architecture

File	Role
`src/ChartEditorProvider.ts`	VS Code `CustomTextEditorProvider` integration
`src/webview/main.ts`	Monaco/editor UI, zoom selector, message bridge
`src/webview/renderer.ts`	Plotly rendering, zoom-based sizing, offscreen export capture
`src/parser.ts`	JSONC extraction and document serialisation
`src/shared/messages.ts`	Host ↔ webview message protocol

Constraints

plotly-basic only (no full Plotly)
No JavaScript callbacks in chart config
No external resource URLs in saved documents
.plot.html is the preferred long-term source format; .plot.svg is a supported compatibility format

Orz Plot

Yu Wang