figfoundry 0.1.0__tar.gz

figfoundry-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+# Normalize line endings to LF in the repo (cross-platform Python standard).
+* text=auto eol=lf
+*.bat text eol=crlf
+*.npz binary

figfoundry-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Environments / caches
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store

figfoundry-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tai D. Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

figfoundry-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: figfoundry
+Version: 0.1.0
+Summary: WYSIWYG matplotlib figure composer: load data (.npz/.pkl), drag signals onto a canvas to build plots, and export clean reproducible code.
+Project-URL: Homepage, https://github.com/ductai199x/figfoundry
+Project-URL: Repository, https://github.com/ductai199x/figfoundry
+Project-URL: Issues, https://github.com/ductai199x/figfoundry/issues
+Author-email: Tai Duc Nguyen <taiducnguyen.drexel@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-visualization,figures,matplotlib,plotting,scientific-figures,wysiwyg
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: uvicorn>=0.29
+Provides-Extra: dev
+Requires-Dist: httpx2>=2.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Fig Foundry
+
+A WYSIWYG matplotlib figure composer. Load your data (`.npz` / `.pkl` / `.csv`),
+drag signals onto a free canvas to build plots, arrange and style them, and export
+clean, reproducible Python.
+
+**The preview renders by executing the generated code**, so what you see is
+byte-for-byte what the exported `.py` produces. There is no second renderer to
+drift.
+
+Fig Foundry is a standalone local app with no dependency on any particular
+project's data. It ships with a small neutral `sample.npz` (1-D signals plus a
+2-D field) so a fresh install has something to open; load your own dataset to work
+with real data.
+
+## Install
+
+```bash
+uv tool install ./path/to/fig_editor     # installs a `figfoundry` command
+# or, from a git repo:
+uv tool install figfoundry --from "git+https://github.com/<you>/<repo>.git"
+```
+
+Then run:
+
+```bash
+figfoundry             # starts the web app on http://127.0.0.1:8037 and opens the browser
+figfoundry serve --port 9000 --no-browser
+```
+
+## Command line
+
+The same engines are available as subcommands for scripting:
+
+```bash
+figfoundry list                              # list saved figures
+figfoundry new --name my-fig                 # create a blank figure, print its slug
+figfoundry export SLUG [--out PATH]          # write a figure's generated .py
+figfoundry render SLUG --format svg|pdf|png  # render a figure to a file
+figfoundry datasets                          # list available datasets
+```
+
+## Data
+
+A *dataset* is a named collection of signals (arrays). Supported formats:
+
+- **`.npz`** — numpy zip of named arrays. Safe by construction.
+- **`.pkl`** — Python pickle, loaded through a **whitelist unpickler** that only
+  permits numpy arrays and plain containers (blocks `os`, `subprocess`, `socket`,
+  `ctypes`, …). A malicious pickle cannot execute code.
+- **`.csv`** — a table with a header row; each numeric column becomes a signal.
+
+1-D and 2-D arrays are both supported (2-D for image/contour/vector plots). Load a
+dataset with the **Load data…** button in the toolbar; each canvas is tied to one
+dataset, and its signals populate the library.
+
+Your figures, datasets, and exports live in `~/.figfoundry/`.
+
+## What you can do
+
+- Drag a signal onto the canvas to make a plot (or onto an existing plot to
+  overlay a line / σ-band / error bars / replace).
+- **Plot types (23):** line, step, scatter, grouped scatter (clustering), bar,
+  bar (horizontal), histogram, box plot, violin plot, 2-D histogram, hexbin, image,
+  contour (filled / lines), pcolormesh, vector field, streamplot, decision boundary,
+  pie, polar, 3-D scatter, surface (3-D), wireframe (3-D).
+- Move, resize (with snapping), and nudge (arrow keys) plots and elements.
+- Multi-select (Shift+click) to nudge / move / delete several at once.
+- Per-plot: data, color, line/marker, σ-band, error bars, ticks, labels, limits,
+  spines, title, colormap + colorbar, and artists (vline, hline, text, annotate,
+  arrow, box, circle, ellipse, polygon, span, legend).
+- **Suggest accessible colors** — one click applies the colorblind-safe Okabe-Ito
+  palette to a plot's series.
+- **LaTeX mathtext** in labels, titles, and text (e.g. `$x_0$`).
+- Layout: grid, align, distribute, margins, sync axis ranges.
+- Figure elements: axis labels, legend, suptitle, free text.
+- Name / duplicate / delete figures. Export the `.py` (copy or download), and the
+  figure itself as **PNG / SVG / PDF** (SVG and PDF are vector, for publication).
+
+Everything is also available through a small JSON API (`/api/canvases`,
+`/api/datasets`, `/api/palettes`, `/api/canvases/{slug}/render|code|figure|download`).
+
+## Testing
+
+The test suite lives in `tests/` (outside the package, so it is never shipped).
+It proves the WYSIWYG invariant (for every plot type), the pickle-safety
+whitelist, and dataset I/O (npz/pkl/csv), each against a throwaway data dir:
+
+```bash
+uv run --extra dev pytest -q
+```

figfoundry-0.1.0/README.md

@@ -0,0 +1,91 @@
+# Fig Foundry
+
+A WYSIWYG matplotlib figure composer. Load your data (`.npz` / `.pkl` / `.csv`),
+drag signals onto a free canvas to build plots, arrange and style them, and export
+clean, reproducible Python.
+
+**The preview renders by executing the generated code**, so what you see is
+byte-for-byte what the exported `.py` produces. There is no second renderer to
+drift.
+
+Fig Foundry is a standalone local app with no dependency on any particular
+project's data. It ships with a small neutral `sample.npz` (1-D signals plus a
+2-D field) so a fresh install has something to open; load your own dataset to work
+with real data.
+
+## Install
+
+```bash
+uv tool install ./path/to/fig_editor     # installs a `figfoundry` command
+# or, from a git repo:
+uv tool install figfoundry --from "git+https://github.com/<you>/<repo>.git"
+```
+
+Then run:
+
+```bash
+figfoundry             # starts the web app on http://127.0.0.1:8037 and opens the browser
+figfoundry serve --port 9000 --no-browser
+```
+
+## Command line
+
+The same engines are available as subcommands for scripting:
+
+```bash
+figfoundry list                              # list saved figures
+figfoundry new --name my-fig                 # create a blank figure, print its slug
+figfoundry export SLUG [--out PATH]          # write a figure's generated .py
+figfoundry render SLUG --format svg|pdf|png  # render a figure to a file
+figfoundry datasets                          # list available datasets
+```
+
+## Data
+
+A *dataset* is a named collection of signals (arrays). Supported formats:
+
+- **`.npz`** — numpy zip of named arrays. Safe by construction.
+- **`.pkl`** — Python pickle, loaded through a **whitelist unpickler** that only
+  permits numpy arrays and plain containers (blocks `os`, `subprocess`, `socket`,
+  `ctypes`, …). A malicious pickle cannot execute code.
+- **`.csv`** — a table with a header row; each numeric column becomes a signal.
+
+1-D and 2-D arrays are both supported (2-D for image/contour/vector plots). Load a
+dataset with the **Load data…** button in the toolbar; each canvas is tied to one
+dataset, and its signals populate the library.
+
+Your figures, datasets, and exports live in `~/.figfoundry/`.
+
+## What you can do
+
+- Drag a signal onto the canvas to make a plot (or onto an existing plot to
+  overlay a line / σ-band / error bars / replace).
+- **Plot types (23):** line, step, scatter, grouped scatter (clustering), bar,
+  bar (horizontal), histogram, box plot, violin plot, 2-D histogram, hexbin, image,
+  contour (filled / lines), pcolormesh, vector field, streamplot, decision boundary,
+  pie, polar, 3-D scatter, surface (3-D), wireframe (3-D).
+- Move, resize (with snapping), and nudge (arrow keys) plots and elements.
+- Multi-select (Shift+click) to nudge / move / delete several at once.
+- Per-plot: data, color, line/marker, σ-band, error bars, ticks, labels, limits,
+  spines, title, colormap + colorbar, and artists (vline, hline, text, annotate,
+  arrow, box, circle, ellipse, polygon, span, legend).
+- **Suggest accessible colors** — one click applies the colorblind-safe Okabe-Ito
+  palette to a plot's series.
+- **LaTeX mathtext** in labels, titles, and text (e.g. `$x_0$`).
+- Layout: grid, align, distribute, margins, sync axis ranges.
+- Figure elements: axis labels, legend, suptitle, free text.
+- Name / duplicate / delete figures. Export the `.py` (copy or download), and the
+  figure itself as **PNG / SVG / PDF** (SVG and PDF are vector, for publication).
+
+Everything is also available through a small JSON API (`/api/canvases`,
+`/api/datasets`, `/api/palettes`, `/api/canvases/{slug}/render|code|figure|download`).
+
+## Testing
+
+The test suite lives in `tests/` (outside the package, so it is never shipped).
+It proves the WYSIWYG invariant (for every plot type), the pickle-safety
+whitelist, and dataset I/O (npz/pkl/csv), each against a throwaway data dir:
+
+```bash
+uv run --extra dev pytest -q
+```

figfoundry-0.1.0/figfoundry/__init__.py

@@ -0,0 +1,7 @@
+"""Fig Foundry -- a WYSIWYG matplotlib figure composer.
+
+Load a dataset (.npz / .pkl), drag signals onto a canvas to make plots, arrange
+and style them freely, and export clean, reproducible Python. The preview renders
+by executing the generated code, so what you see is exactly what the .py produces.
+"""
+__version__ = "0.1.0"

figfoundry-0.1.0/figfoundry/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

figfoundry-0.1.0/figfoundry/app.py

@@ -0,0 +1,378 @@
+"""Fig Foundry -- FastAPI backend.
+
+The spec (a scene graph of the figure) is the single source of truth. The browser
+manipulates it; the backend renders it by EXECUTING the generated code (so the
+preview is byte-identical to the export); and it can serialize the spec to a
+standalone .py that references the dataset.
+"""
+import contextlib
+import json
+import os
+import re
+import threading
+import time
+
+from fastapi import FastAPI, File, HTTPException, UploadFile
+from fastapi.responses import FileResponse, JSONResponse, Response
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+from . import canvas, data_io
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+USER_DIR = data_io.USER_DIR
+CANVAS_DIR = os.path.join(USER_DIR, "canvases")
+OUT_DIR = os.path.join(USER_DIR, "out")
+os.makedirs(CANVAS_DIR, exist_ok=True)
+os.makedirs(OUT_DIR, exist_ok=True)
+
+app = FastAPI(title="Fig Foundry")
+
+
+@app.middleware("http")
+async def no_cache(request, call_next):
+    """Local tool: never let the browser serve stale JS/HTML/CSS after an update."""
+    resp = await call_next(request)
+    resp.headers["Cache-Control"] = "no-store, no-cache, must-revalidate, max-age=0"
+    resp.headers["Pragma"] = "no-cache"
+    resp.headers["Expires"] = "0"
+    return resp
+
+
+class CanvasBody(BaseModel):
+    spec: dict | None = None
+    draft: bool = False
+
+
+class NewCanvasBody(BaseModel):
+    mode: str = "blank"
+
+
+class UpdateCanvasBody(BaseModel):
+    name: str | None = None
+    spec: dict | None = None
+
+
+def _cpath(slug):
+    return os.path.join(CANVAS_DIR, f"{slug}.json")
+
+
+def _check_slug(slug):
+    # Slugs are generated as <timestamp>-<hex>; reject anything with path separators
+    # (including %-decoded ones, e.g. "..%2F..%2Fetc") so a crafted slug can't
+    # traverse out of the canvases dir.
+    if not re.fullmatch(r"[A-Za-z0-9_-]+", slug):
+        raise HTTPException(404, "canvas not found")
+
+
+def _read(slug):
+    _check_slug(slug)
+    p = _cpath(slug)
+    if not os.path.exists(p):
+        raise HTTPException(404, "canvas not found")
+    try:
+        with open(p) as f:
+            doc = json.load(f)
+    except (OSError, ValueError) as e:  # ValueError covers json.JSONDecodeError
+        raise HTTPException(500, "canvas file is corrupt") from e
+    # Every endpoint below does doc["spec"] / doc["spec"].get(...); a partial or
+    # hand-edited file without a dict spec would be a raw 500 KeyError/AttributeError.
+    if not isinstance(doc, dict) or not isinstance(doc.get("spec"), dict):
+        raise HTTPException(500, "canvas file is corrupt: missing spec")
+    return doc
+
+
+def _check_dataset_name(name):
+    if os.path.basename(name) != name or name in (".", ".."):
+        raise HTTPException(400, "invalid dataset name")
+
+
+_write_lock = threading.Lock()
+
+
+def _write(slug, doc):
+    # Serialize writes (threadpool) and make each atomic (temp + rename) so a reader
+    # never sees a partial/corrupt file. On Windows a concurrent reader's open handle
+    # can briefly refuse the rename, so retry it; clean up the temp on any failure.
+    with _write_lock:
+        tmp = _cpath(slug) + ".tmp"
+        try:
+            with open(tmp, "w") as f:
+                json.dump(doc, f, indent=2)
+            last = None
+            for _ in range(20):
+                try:
+                    os.replace(tmp, _cpath(slug))
+                    last = None
+                    break
+                except PermissionError as e:
+                    last = e
+                    time.sleep(0.02)
+            if last is not None:
+                raise last
+        except BaseException:
+            if os.path.exists(tmp):
+                os.remove(tmp)
+            raise
+
+
+def _list_canvases():
+    out = []
+    for f in sorted(os.listdir(CANVAS_DIR), reverse=True):
+        if not f.endswith(".json"):
+            continue
+        try:
+            with open(os.path.join(CANVAS_DIR, f)) as fh:
+                doc = json.load(fh)
+            out.append({"slug": f[:-5], "name": doc.get("name", "Untitled"),
+                        "plots": len(doc.get("spec", {}).get("plots", [])), "updated": doc.get("updated")})
+        except Exception:
+            continue
+    return out
+
+
+# --------------------------------------------------------------------------- pages
+@app.get("/")
+def index():
+    return FileResponse(os.path.join(HERE, "static", "index.html"))
+
+
+@app.get("/canvas")
+def canvas_page():
+    return FileResponse(os.path.join(HERE, "static", "canvas.html"))
+
+
+# --------------------------------------------------------------------------- datasets
+# The picker calls this on every open; re-parsing (unpickling!) each dataset file
+# every time is pure waste for large files. Cache per-file summaries keyed by
+# (mtime, size) -- a re-upload of the same name changes both, so it invalidates.
+_ds_list_cache = {}
+
+
+@app.get("/api/datasets")
+def list_datasets():
+    out = []
+    for f in sorted(os.listdir(data_io.DATA_DIR)):
+        if f.endswith((".npz", ".pkl", ".pickle", ".csv")):
+            p = os.path.join(data_io.DATA_DIR, f)
+            try:
+                st = os.stat(p)
+            except OSError:
+                continue
+            hit = _ds_list_cache.get(f)
+            if hit is not None and hit[0] == st.st_mtime and hit[1] == st.st_size:
+                out.append(hit[2])
+                continue
+            try:
+                arrays, kind = data_io.load_arrays(p)
+                info = {"name": f, "kind": kind, "n_signals": len(arrays)}
+            except Exception as e:
+                info = {"name": f, "kind": "?", "n_signals": 0, "error": str(e)}
+            _ds_list_cache[f] = (st.st_mtime, st.st_size, info)
+            out.append(info)
+    return {"datasets": out}
+
+
+@app.get("/api/datasets/{name}/signals")
+def dataset_signals(name):
+    """The signals in a specific dataset file (independent of any canvas)."""
+    _check_dataset_name(name)
+    path = os.path.join(data_io.DATA_DIR, name)
+    if not os.path.exists(path):
+        raise HTTPException(404, "dataset not found")
+    try:
+        arrays, kind = data_io.load_arrays(path)
+    except Exception as e:
+        raise HTTPException(400, f"could not load dataset: {e}") from e
+    return {"dataset": name, "kind": kind, "signals": data_io.list_signals(arrays)}
+
+
+@app.post("/api/datasets")
+async def upload_dataset(file: UploadFile = File(...)):
+    """Upload a .npz / .pkl / .csv dataset. pkl goes through the whitelist
+    SafeUnpickler. The payload is validated before it is written, so a bad upload
+    can never clobber an existing dataset of the same name."""
+    name = os.path.basename(file.filename or "upload")
+    if not name.endswith((".npz", ".pkl", ".pickle", ".csv")):
+        raise HTTPException(400, "only .npz / .pkl / .csv datasets are supported")
+    payload = await file.read()
+    try:
+        arrays, kind = data_io.load_arrays_bytes(payload, name)
+    except Exception as e:
+        raise HTTPException(400, f"could not load dataset: {e}") from e
+    try:
+        _write_atomic_bytes(os.path.join(data_io.DATA_DIR, name), payload)
+    except OSError as e:  # e.g. a filename character the OS refuses (newline on Windows)
+        raise HTTPException(400, f"could not save dataset: {e}") from e
+    # Belt and braces: canvas.get_dataset_arrays already invalidates by
+    # (mtime, size) on read, but dropping the entry here too guarantees the next
+    # signal-list call re-stats and re-loads the freshly uploaded file.
+    canvas._ds_cache.pop(name, None)
+    return {"name": name, "kind": kind, "n_signals": len(arrays), "signals": data_io.list_signals(arrays)}
+
+
+def _write_atomic_bytes(path, payload):
+    """Atomic byte write (unique temp + rename) so a reader never sees a partial
+    file and two concurrent uploads of the same name can't clobber each other's
+    temp. The temp name is unique per thread: a shared "<path>.tmp" would let one
+    thread's os.replace grab the other's in-progress write. On Windows a
+    concurrent reader's handle can briefly refuse the rename, so retry it."""
+    tmp = f"{path}.{threading.get_ident()}.tmp"
+    try:
+        with open(tmp, "wb") as f:
+            f.write(payload)
+        last = None
+        for _ in range(20):
+            try:
+                os.replace(tmp, path)
+                last = None
+                break
+            except PermissionError as e:
+                last = e
+                time.sleep(0.02)
+        if last is not None:
+            raise last
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.remove(tmp)
+        raise
+
+
+# --------------------------------------------------------------------------- canvases
+@app.get("/api/canvases")
+def list_canvases():
+    return {"canvases": _list_canvases()}
+
+
+@app.post("/api/canvases")
+def new_canvas(body: NewCanvasBody):
+    slug = time.strftime("%Y%m%d-%H%M%S") + "-" + os.urandom(2).hex()
+    spec = canvas.blank_spec()  # always blank; load a dataset to get signals
+    _write(slug, {"name": "Untitled", "spec": spec, "updated": time.time()})
+    return {"slug": slug, "name": "Untitled"}
+
+
+@app.get("/api/canvases/{slug}")
+def get_canvas(slug):
+    doc = _read(slug)
+    return {"slug": slug, "name": doc.get("name", "Untitled"), "spec": doc["spec"]}
+
+
+@app.put("/api/canvases/{slug}")
+def update_canvas(slug, body: UpdateCanvasBody):
+    doc = _read(slug)
+    if body.name is not None:
+        doc["name"] = body.name
+    if body.spec is not None:
+        doc["spec"] = body.spec
+    doc["updated"] = time.time()
+    _write(slug, doc)
+    return {"ok": True}
+
+
+@app.delete("/api/canvases/{slug}")
+def delete_canvas(slug):
+    _check_slug(slug)
+    p = _cpath(slug)
+    if os.path.exists(p):
+        os.remove(p)
+    return {"ok": True}
+
+
+@app.post("/api/canvases/{slug}/duplicate")
+def duplicate_canvas(slug):
+    doc = _read(slug)
+    newslug = time.strftime("%Y%m%d-%H%M%S") + "-" + os.urandom(2).hex()
+    name = str(doc.get("name") or "Untitled")  # a hand-edited file may hold a non-str
+    newdoc = {"name": name + " copy", "spec": json.loads(json.dumps(doc["spec"])), "updated": time.time()}
+    _write(newslug, newdoc)
+    return {"slug": newslug, "name": newdoc["name"]}
+
+
+@app.get("/api/canvases/{slug}/signals")
+def canvas_signals(slug):
+    """The signal library for a canvas = the signals in its dataset (empty if none)."""
+    doc = _read(slug)
+    ds = doc["spec"].get("dataset")
+    if not ds:
+        return {"dataset": None, "signals": []}
+    try:
+        arrays = canvas.get_dataset_arrays(ds)
+    except HTTPException:
+        raise
+    except Exception as e:  # dataset deleted from disk, or a non-str name in a hand-edited spec
+        raise HTTPException(400, f"could not load dataset: {e}") from e
+    return {"dataset": ds, "signals": data_io.list_signals(arrays)}
+
+
+@app.post("/api/canvases/{slug}/render")
+def render_canvas(slug, body: CanvasBody | None = None):
+    spec = body.spec if (body is not None and body.spec is not None) else _read(slug)["spec"]
+    draft = body.draft if body is not None else False
+    try:
+        return canvas.render_to_png(spec, draft=draft)
+    except Exception as e:
+        raise HTTPException(400, f"render failed: {e}") from e
+
+
+@app.get("/api/canvases/{slug}/code")
+def code_canvas(slug):
+    try:
+        code = canvas.codegen_canvas(_read(slug)["spec"])
+    except HTTPException:
+        raise  # _read's 404/500 must not be re-wrapped as a codegen failure
+    except Exception as e:
+        raise HTTPException(400, f"codegen failed: {e}") from e
+    return JSONResponse({"code": code})
+
+
+@app.get("/api/canvases/{slug}/download")
+def download_canvas(slug):
+    doc = _read(slug)
+    try:
+        code = canvas.codegen_canvas(doc["spec"])
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(400, f"codegen failed: {e}") from e
+    # Same filename-safe character set as export_figure: the name is client-
+    # controlled, and FileResponse's Content-Disposition handling of it has
+    # changed across starlette versions (older ones quoted it raw).
+    base = str(doc.get("name") or "canvas").strip().replace(" ", "_") or "canvas"
+    fname = re.sub(r"[^A-Za-z0-9._-]", "_", base) + ".py"
+    path = os.path.join(OUT_DIR, f"canvas_{slug}.py")
+    with open(path, "w") as f:
+        f.write(code)
+    return FileResponse(path, filename=fname, media_type="text/x-python")
+
+
+_FIG_CT = {"png": "image/png", "svg": "image/svg+xml", "pdf": "application/pdf"}
+
+
+@app.get("/api/canvases/{slug}/figure")
+def export_figure(slug, format: str = "png"):
+    """Render the figure (by executing the code) and return it as png / svg / pdf.
+    svg and pdf are vector, suitable for publication."""
+    if format not in _FIG_CT:
+        raise HTTPException(400, "format must be png, svg, or pdf")
+    doc = _read(slug)
+    try:
+        data = canvas.render_to_bytes(doc["spec"], fmt=format)
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(400, f"render failed: {e}") from e
+    base = str(doc.get("name") or "figure").strip().replace(" ", "_") or "figure"
+    # The canvas name is client-controlled; keep the hand-built header value to
+    # filename-safe characters so a quote/newline can't break Content-Disposition.
+    fname = re.sub(r"[^A-Za-z0-9._-]", "_", base) + "." + format
+    return Response(content=data, media_type=_FIG_CT[format],
+                    headers={"Content-Disposition": f'attachment; filename="{fname}"'})
+
+
+@app.get("/api/palettes")
+def palettes():
+    return {"palettes": canvas.get_palettes()}
+
+
+app.mount("/static", StaticFiles(directory=os.path.join(HERE, "static")), name="static")