feat(javascript): add JS runtime + render harness + Chart.js, D3.js, ECharts (Phase 1) (#8244)

Closes #8241.

Adds **JavaScript** as anyplot's fourth language and ships the three
framework-agnostic Phase-1 libraries: **Chart.js**, **D3.js**, **Apache
ECharts**. This is the foundation of the JS rollout — the Highcharts
migration (#8242) and the MUI X React path (#8243) build on it. Matches
the one-pass `feat(makie)` (#7613) discipline.

## The genuinely new piece: anyplot's first browser-rendered runtime

R (`Rscript`) and Julia (`julia`) are CLI runtimes that write a PNG
directly. JS charting libraries render in a browser DOM — there is no
headless CLI that produces a PNG. So this introduces a **Node 22 +
Playwright headless-Chromium render harness**. The authored artifact is
an **idiomatic snippet** (`new Chart(...)`, `d3.select(...)`,
`echarts.init(...)`) drawing into `#container`; the harness wraps it in
HTML, loads the pinned bundle, awaits a render-complete signal,
screenshots the mount at **exact pixels**, and emits **both** the
gallery PNG and the self-contained interactive HTML — the same "HTML is
the deliverable, PNG is derived" model anyplot already uses for its
Python interactive libraries.

## Validated end-to-end (real Playwright + Chromium)

All three libraries, both themes, landscape + square:
- Exact **3200×1800** / **2400×2400** (verified straight from the PNG
IHDR)
- First categorical series renders in brand green `#009E73`
- Theme-adaptive chrome (paper `#FAF8F1` / ink `#1A1A17` backgrounds,
soft grid)
- Snippet errors fail the render with a non-zero exit (no silent blank
PNGs)

## What changed

**Registry (`core/constants.py`)**
- `SUPPORTED_LANGUAGES += javascript`; `LANGUAGES_METADATA` entry (Node
22).
- `SUPPORTED_LIBRARIES += chartjs, d3, echarts` (alpha-sorted); the
three in `INTERACTIVE_LIBRARIES`.
- **`framework`** field (`none|react|vue|svelte|angular`, default
`none`) on every library — lets one `javascript` entry later cover React
libs (#8243) without duplicating the registry (§6). Backed by a new
`libraries.framework` column + alembic migration.
- **Per-library `file_extension` override** mechanism +
`language_file_extensions()`, honored by `sync_to_postgres` so a future
`.tsx` React entry is a one-line change. Phase-1 libs are all `.js`.
*(This is the one real schema wrinkle JS adds — called out explicitly.)*
- DB seeds now project metadata dicts onto model columns, so
metadata-only keys never break the bulk insert.

**Runtime + harness**
- `package.json` + committed `package-lock.json` (chart.js, d3, echarts
+ playwright, esbuild) — the JS sibling of `Project.toml` / the Posit
snapshot.
- `.github/actions/setup-node` composite action: `npm ci` → Playwright
Chromium → render smoke test asserting exact 3200×1800.
- `automation/js-render/render.mjs` — the shared harness (theme tokens,
per-library bundle, `//# anyplot-orientation:` directive,
render-complete wait, exact-pixel screenshot, self-contained HTML).

**Workflows** — `javascript` arm in the `(LANGUAGE, EXT)` case of
`impl-generate` / `impl-repair` / `impl-review` / `impl-merge`;
`setup-node` step in generate + repair; Node + npm version extraction;
per-library canvas hints + a `//` header-rewrite branch (preserving
`//#` directives) in review; libs added to generate/bulk-generate
choices + `ALL_LIBRARIES`.

**Prompts** — new `prompts/library/{chartjs,d3,echarts}.md` (mount-node
contract, `ANYPLOT_THEME` tokens, canvas hard rule, no-workarounds,
forbidden patterns); JS render contract added to the generate + repair
workflow prompts.

**Frontend** — `javascript` in `LIBRARIES` / `LIB_ABBREV` /
`LIB_TO_LANG` / `LANG_DISPLAY` / `LANG_EXT`; Prism `javascript` grammar
registered; ext/runner ternaries extended in `PlotOfTheDay(+Terminal)`.

**Tests** — constants tests updated for 14 libraries / 4 languages, the
`framework` field, and the extension-override helpers.

## Test results
- `tests/unit` Python: constants (43), sync + workflows (337), DB
repositories with the new `framework` column (37) — all pass.
*(Pre-existing GCS-font image tests fail only for lack of GCS creds in
the sandbox; unrelated.)*
- Frontend: `tsc` clean, ESLint clean (4 pre-existing warnings), **524
vitest tests pass**.
- All edited/new YAML parses; alembic resolves to a single head
(`f7a2c9d4e8b1`).

## Notes / decisions
- **Plotly stays Python**, no `plotly.js` entry (most-used-variant rule,
§6). Same for `plotly (R)` / `highcharter (R)`.
- JS & TS are one language; snippets authored in plain JS.
React/Vue/etc. are a `framework` flag, not a language.
- `esbuild` is pinned and the harness's `framework=react` branch is
scaffolded but **not exercised** until #8243.
- Versions in metadata (`chart.js` 4.4, `d3` 7.9, `echarts` 5.5; Node
22) should be reconfirmed on the first CI run, per the issue.

https://claude.ai/code/session_019awsxNrPnEZStvLfwarTzQ

---
_Generated by [Claude
Code](https://claude.ai/code/session_019awsxNrPnEZStvLfwarTzQ)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: MarkusNeusinger

.github/actions/setup-node/action.yml

@@ -0,0 +1,65 @@
+name: "Setup Node + JS render harness"
+description: >-
+  Installs Node.js, the pinned JavaScript charting toolchain (Chart.js, D3,
+  ECharts) and the headless-browser render harness (Playwright + Chromium) used
+  by anyplot's JavaScript implementations. The toolchain is restored exactly
+  from the committed top-level package-lock.json (`npm ci`) for reproducibility —
+  the JS sibling of setup-r's Posit snapshot and setup-julia's Manifest.toml.
+inputs:
+  node-version:
+    description: "Node.js version to install"
+    required: false
+    default: "22"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+        # Restore npm's download cache keyed on the committed lockfile so cold
+        # `npm ci` runs stay fast.
+        cache: "npm"
+        cache-dependency-path: package-lock.json
+
+    - name: Install JS toolchain (npm ci)
+      # `npm ci` installs the exact locked tree from package-lock.json and fails
+      # if package.json and the lockfile disagree — the strict, reproducible
+      # restore (vs. `npm install`, which may rewrite the lockfile).
+      shell: bash
+      run: npm ci
+
+    - name: Install Playwright Chromium
+      # Bundled, version-pinned Chromium (no webdriver-manager drift). `--with-deps`
+      # pulls the apt libraries headless Chromium needs on the runner image.
+      shell: bash
+      run: npx playwright install --with-deps chromium
+
+    - name: Smoke-test the render harness produces a PNG
+      shell: bash
+      run: |
+        set -euo pipefail
+        TMP="$(mktemp -d)"
+        cat > "$TMP/chartjs.js" <<'JS'
+        const t = window.ANYPLOT_TOKENS;
+        const canvas = document.createElement("canvas");
+        document.getElementById("container").appendChild(canvas);
+        new Chart(canvas, {
+          type: "bar",
+          data: { labels: ["a", "b", "c"], datasets: [{ data: [3, 1, 2], backgroundColor: t.palette[0] }] },
+          options: { responsive: true, maintainAspectRatio: false, animation: false },
+        });
+        JS
+        ( cd "$TMP" && ANYPLOT_THEME=light node "$GITHUB_WORKSPACE/automation/js-render/render.mjs" chartjs.js )
+        PNG="$TMP/plot-light.png"
+        test -f "$PNG"
+        test -s "$PNG"
+        # Confirm exact landscape pixels (3200×1800) straight from the PNG IHDR.
+        node -e '
+          const fs = require("fs");
+          const b = fs.readFileSync(process.argv[1]);
+          const w = b.readUInt32BE(16), h = b.readUInt32BE(20);
+          if (w !== 3200 || h !== 1800) { console.error(`smoke-test PNG is ${w}x${h}, expected 3200x1800`); process.exit(1); }
+          console.log(`ok: ${process.argv[1]} (${w}x${h}, ${b.length} bytes)`);
+        ' "$PNG"

.github/workflows/bulk-generate.yml

@@ -30,6 +30,9 @@ on:
           - letsplot
           - ggplot2
           - makie
+          - chartjs
+          - d3
+          - echarts
       dry_run:
         description: "List what would be generated without executing"
         type: boolean
@@ -54,7 +57,7 @@ on:
         default: '{}'
 
 env:
-  ALL_LIBRARIES: "matplotlib seaborn plotly bokeh altair plotnine pygal highcharts letsplot ggplot2 makie"
+  ALL_LIBRARIES: "matplotlib seaborn plotly bokeh altair plotnine pygal highcharts letsplot ggplot2 makie chartjs d3 echarts"
 
 # Serialise bulk-generate runs. Each run paces its own dispatches with
 # `pace_seconds`; letting two runs overlap would interleave their

.github/workflows/impl-generate.yml

@@ -31,6 +31,9 @@ on:
           - letsplot
           - ggplot2
           - makie
+          - chartjs
+          - d3
+          - echarts
       issue_number:
         description: "Issue number (optional, for tracking)"
         required: false
@@ -124,6 +127,10 @@ jobs:
               LANGUAGE="julia"
               EXT=".jl"
               ;;
+            chartjs|d3|echarts)
+              LANGUAGE="javascript"
+              EXT=".js"
+              ;;
             *)
               LANGUAGE="python"
               EXT=".py"
@@ -255,6 +262,10 @@ jobs:
         if: steps.inputs.outputs.language == 'julia'
         uses: ./.github/actions/setup-julia
 
+      - name: Setup Node + browser render harness
+        if: steps.inputs.outputs.language == 'javascript'
+        uses: ./.github/actions/setup-node
+
       # ========================================================================
       # Generate: Create implementation branch and code
       # ========================================================================
@@ -526,6 +537,10 @@ jobs:
             # if julia exits non-zero after partial stdout.
             LANGUAGE_VERSION=$(julia -e 'print(VERSION)' 2>/dev/null | tail -n1)
             is_version "$LANGUAGE_VERSION" || LANGUAGE_VERSION="unknown"
+          elif [ "$LANGUAGE" = "javascript" ]; then
+            # `node --version` prints `v22.x.y`; strip the leading `v`.
+            LANGUAGE_VERSION=$(node --version 2>/dev/null | sed 's/^v//' | tail -n1)
+            is_version "$LANGUAGE_VERSION" || LANGUAGE_VERSION="unknown"
           else
             LANGUAGE_VERSION="$PYTHON_VERSION"
           fi
@@ -558,6 +573,14 @@ jobs:
             " 2>/dev/null | tail -n1)
             is_version "$v" && printf '%s' "$v"
           }
+          get_npm_version() {
+            # Read the installed version straight out of the package's own
+            # package.json (restored by `npm ci` from the committed lockfile).
+            # `require('<pkg>/package.json')` resolves the subpath reliably.
+            local v
+            v=$(node -p "require('$1/package.json').version" 2>/dev/null | tail -n1)
+            is_version "$v" && printf '%s' "$v"
+          }
 
           if [ "$LANGUAGE" = "r" ]; then
             LIBRARY_VERSION=$(get_r_version "$LIBRARY")
@@ -572,6 +595,17 @@ jobs:
                 LIBRARY_VERSION=$(get_julia_version "$LIBRARY")
                 ;;
             esac
+          elif [ "$LANGUAGE" = "javascript" ]; then
+            # Catalogue id `chartjs` maps to the npm package `chart.js`; `d3` and
+            # `echarts` match their npm names directly.
+            case "$LIBRARY" in
+              chartjs)
+                LIBRARY_VERSION=$(get_npm_version "chart.js")
+                ;;
+              *)
+                LIBRARY_VERSION=$(get_npm_version "$LIBRARY")
+                ;;
+            esac
           else
             case "$LIBRARY" in
               letsplot)

.github/workflows/impl-merge.yml

@@ -113,6 +113,10 @@ jobs:
               LANGUAGE="julia"
               EXT=".jl"
               ;;
+            chartjs|d3|echarts)
+              LANGUAGE="javascript"
+              EXT=".js"
+              ;;
             *)
               LANGUAGE="python"
               EXT=".py"

.github/workflows/impl-repair.yml

@@ -79,6 +79,10 @@ jobs:
               LANGUAGE="julia"
               EXT=".jl"
               ;;
+            chartjs|d3|echarts)
+              LANGUAGE="javascript"
+              EXT=".js"
+              ;;
             *)
               LANGUAGE="python"
               EXT=".py"
@@ -127,6 +131,10 @@ jobs:
         if: steps.lang.outputs.language == 'julia'
         uses: ./.github/actions/setup-julia
 
+      - name: Setup Node + browser render harness
+        if: steps.lang.outputs.language == 'javascript'
+        uses: ./.github/actions/setup-node
+
       - name: Extract AI feedback from PR
         id: feedback
         env:

.github/workflows/impl-review.yml

@@ -109,6 +109,10 @@ jobs:
               LANGUAGE="julia"
               EXT=".jl"
               ;;
+            chartjs|d3|echarts)
+              LANGUAGE="javascript"
+              EXT=".js"
+              ;;
             *)
               LANGUAGE="python"
               EXT=".py"
@@ -268,6 +272,9 @@ jobs:
               "letsplot":   "Check `ggsize(W, H)` and `ggsave(..., scale=4)` pair — only the two canonical pairs land on target.",
               "ggplot2":    "Check `ggsave(width=…, height=…, units='in', dpi=400)` with `ragg::agg_png`.",
               "makie":      "Check `Figure(resolution=(1600, 900))` + `save(..., px_per_unit=2)` (landscape) or `resolution=(1200, 1200)` + `px_per_unit=2` (square) — those are the only two canonical pairs.",
+              "chartjs":    "The harness owns exact pixels (Playwright deviceScaleFactor 2 over a fixed mount). Drift means the snippet forced its own canvas size: set `responsive: true` + `maintainAspectRatio: false` and let the canvas fill `#container` — do NOT set canvas width/height. Use `//# anyplot-orientation: square` only for square specs.",
+              "d3":         "The harness owns exact pixels (Playwright deviceScaleFactor 2 over a fixed mount). Size the `<svg>` to `window.ANYPLOT_SIZE` (1600×900 landscape / 1200×1200 square) — never hard-code other dimensions. Use `//# anyplot-orientation: square` only for square specs.",
+              "echarts":    "The harness owns exact pixels (Playwright deviceScaleFactor 2 over a fixed mount). Call `echarts.init(document.getElementById('container'))` with no explicit width/height so it fills the mount; do not pass a `devicePixelRatio` (the page already runs at 2×). Use `//# anyplot-orientation: square` only for square specs.",
           }
           cause = causes.get(LIBRARY, f"Review `prompts/library/{LIBRARY}.md` 'Canvas — hard rule' section.")
 
@@ -645,7 +652,9 @@ jobs:
 
           # Human-readable runtime label for the header. Extend this map when a new
           # language joins the catalog.
-          RUNTIME_LABEL = {"python": "Python", "r": "R", "julia": "Julia"}.get(language, language.capitalize())
+          RUNTIME_LABEL = {"python": "Python", "r": "R", "julia": "Julia", "javascript": "JavaScript"}.get(
+              language, language.capitalize()
+          )
 
           with open(impl_file, "r") as f:
               content = f.read()
@@ -694,6 +703,29 @@ jobs:
                   new_content = re.sub(pattern, new_header + "\n", content, count=1)
               else:
                   new_content = new_header + "\n" + content
+          elif language == "javascript":
+              # JavaScript has no docstring syntax; anyplot uses a leading `//`
+              # line-comment block, mirroring the Julia/R conventions.
+              title_safe = title.replace("\n", " ")
+              new_header = (
+                  "// anyplot.ai\n"
+                  f"// {spec_id}: {title_safe}\n"
+                  f"// Library: {library} {lib_version} | {RUNTIME_LABEL} {lang_version}\n"
+                  f"// Quality: {score}/100 | {date_info}"
+              )
+              # Match a leading run of `//`-comment lines (the existing header).
+              # The negative lookahead `(?!#)` excludes `//#`-prefixed lines —
+              # those are anyplot directives (e.g. `//# anyplot-orientation:
+              # square`) the harness reads, NOT header lines, so they must
+              # survive the rewrite. The run therefore stops at the first
+              # directive; if a directive is the first line of the file the
+              # regex falls through and the canonical header is prepended above
+              # it. (#6947 prepend-fallback.)
+              pattern = r"\A(?://(?!#)[^\n]*\n)+"
+              if re.match(pattern, content):
+                  new_content = re.sub(pattern, new_header + "\n", content, count=1)
+              else:
+                  new_content = new_header + "\n" + content
           else:
               # Python: triple-quoted module docstring at the top of the file.
               title_safe = title.replace('"""', '\\"\\"\\"')

alembic/versions/f7a2c9d4e8b1_add_framework_to_libraries.py

@@ -0,0 +1,35 @@
+"""add_framework_to_libraries
+
+Adds the `framework` column to the libraries table. It models the UI-framework
+runtime constraint a charting library imposes (none | react | vue | svelte |
+angular) so a single `javascript` language entry can cover both
+framework-agnostic libraries (Chart.js, D3, ECharts) and React-only libraries
+without duplicating the registry — see docs/concepts/library-expansion.md §6.
+All existing libraries are framework-agnostic, so the column defaults to "none".
+
+Revision ID: f7a2c9d4e8b1
+Revises: 7efe9fc8bde1
+Create Date: 2026-06-02 20:00:00.000000
+
+"""
+
+from typing import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = "f7a2c9d4e8b1"
+down_revision: str | None = "7efe9fc8bde1"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column("libraries", sa.Column("framework", sa.String(length=20), nullable=False, server_default="none"))
+
+
+def downgrade() -> None:
+    op.drop_column("libraries", "framework")

app/src/components/CodeHighlighter.tsx

@@ -2,18 +2,21 @@ import SyntaxHighlighter from 'react-syntax-highlighter/dist/esm/prism-light';
 import python from 'react-syntax-highlighter/dist/esm/languages/prism/python';
 import r from 'react-syntax-highlighter/dist/esm/languages/prism/r';
 import julia from 'react-syntax-highlighter/dist/esm/languages/prism/julia';
+import javascript from 'react-syntax-highlighter/dist/esm/languages/prism/javascript';
 import { typography } from '../theme';
 
 SyntaxHighlighter.registerLanguage('python', python);
 SyntaxHighlighter.registerLanguage('r', r);
 SyntaxHighlighter.registerLanguage('julia', julia);
+SyntaxHighlighter.registerLanguage('javascript', javascript);
 
 // Map anyplot language IDs → Prism grammar names. Anything we don't know about
 // falls back to plain text so the block still renders, just unhighlighted.
 const PRISM_LANGUAGE: Record<string, string> = {
   python: 'python',
   r: 'r',
   julia: 'julia',
+  javascript: 'javascript',
 };
 
 // Theme-aware imprint syntax theme. All colors come from CSS variables in

app/src/components/PlotOfTheDay.tsx

@@ -103,11 +103,11 @@ export function PlotOfTheDay() {
           <Typography sx={{ fontFamily: mono, fontSize: fontSize.xs, color: colors.primary, fontWeight: 600 }}>$</Typography>
           {(() => {
             // Per-language file extension + runner command. Anyplot ships Python
-            // for nine libraries, R for ggplot2, and Julia for makie; the chip
-            // mimics what a user would actually type into a shell, so the
-            // runner label flips too.
-            const ext = data.language === 'r' ? '.R' : data.language === 'julia' ? '.jl' : '.py';
-            const runner = data.language === 'r' ? 'Rscript' : data.language === 'julia' ? 'julia --project=.' : 'python';
+            // for nine libraries, R for ggplot2, Julia for makie, and JavaScript
+            // for chartjs/d3/echarts; the chip mimics what a user would actually
+            // type into a shell, so the runner label flips too.
+            const ext = data.language === 'r' ? '.R' : data.language === 'julia' ? '.jl' : data.language === 'javascript' ? '.js' : '.py';
+            const runner = data.language === 'r' ? 'Rscript' : data.language === 'julia' ? 'julia --project=.' : data.language === 'javascript' ? 'node' : 'python';
             return (
               <Typography
                 component="a"
@@ -265,7 +265,7 @@ export function PlotOfTheDay() {
             │
           </Typography>
           <Typography sx={{ fontFamily: mono, fontSize: fontSize.xxs, color: semanticColors.mutedText, whiteSpace: 'nowrap' }}>
-            {data.library_name}{data.library_version && data.library_version !== 'unknown' ? ` ${data.library_version}` : ''} · {data.language === 'r' ? 'R' : data.language === 'julia' ? 'Julia' : 'Python'} {data.language_version || data.python_version || (data.language === 'r' ? '4.4' : data.language === 'julia' ? '1.11' : '3.13')}
+            {data.library_name}{data.library_version && data.library_version !== 'unknown' ? ` ${data.library_version}` : ''} · {data.language === 'r' ? 'R' : data.language === 'julia' ? 'Julia' : data.language === 'javascript' ? 'JavaScript' : 'Python'} {data.language_version || data.python_version || (data.language === 'r' ? '4.4' : data.language === 'julia' ? '1.11' : data.language === 'javascript' ? '22' : '3.13')}
           </Typography>
         </Box>
       </Box>

app/src/components/PlotOfTheDayTerminal.tsx

@@ -45,9 +45,10 @@ export function PlotOfTheDayTerminal({
   // File extension + runner command follow the implementation language:
   // - ggplot2 (R) ships as .R + Rscript
   // - makie (Julia) ships as .jl + `julia --project=.`
+  // - chartjs/d3/echarts (JavaScript) ship as .js + node (browser render harness)
   // - every Python library as .py + python
-  const ext = potd.language === 'r' ? '.R' : potd.language === 'julia' ? '.jl' : '.py';
-  const runner = potd.language === 'r' ? 'Rscript' : potd.language === 'julia' ? 'julia --project=.' : 'python';
+  const ext = potd.language === 'r' ? '.R' : potd.language === 'julia' ? '.jl' : potd.language === 'javascript' ? '.js' : '.py';
+  const runner = potd.language === 'r' ? 'Rscript' : potd.language === 'julia' ? 'julia --project=.' : potd.language === 'javascript' ? 'node' : 'python';
   const displayFilename = `plots/${potd.spec_id}/${potd.library_id}${ext}`;
   const implPath = specPath(potd.spec_id, potd.language, potd.library_id);
   const githubFileUrl = `${GITHUB_URL}/blob/main/plots/${potd.spec_id}/implementations/${potd.language}/${potd.library_id}${ext}`;