Build

Views

A view is custom UI over node outputs, kept apart from the graph. In a notebook the UI lives in each cell and is built from Python: widget calls, or HTML and JavaScript held in strings. Here the nodes compute outputs in Python and SQL, and a view is front-end code that only reads them: TypeScript, React and CSS in files of their own, with components, imports and types. The canvas, inspector and SQL box stay as they are.

How a view works, in short ("Rendering a view" below has the detail):

  1. Nodes run and store their outputs. A view never runs anything.
  2. The view's view.json names the nodes it reads. Those are the only outputs it can reach, and they are its edges on the graph.
  3. The workbench loads the view's files into a sandboxed frame, compiles them in the browser (there is no build step and no npm install) and renders the entry file's default export.
  4. The code asks for data through the exuvia module: useTable("node") for a whole output, useQuery("select …") for DuckDB SQL over the nodes it reads. Tables arrive as typed Arrow data, not as HTML or JSON text.
  5. When a run replaces an output the view reads, its hooks reload. When one of its files is saved, the frame is rebuilt.

The agent writes views with the same kind of tools it has for nodes. Whoever wrote it, a view runs in the sandbox and can only read.

Views are React, rendered inside the workbench. An app written in anything else reads the same outputs over HTTP, as Arrow streams or Parquet files (see Binary data).

A view is a folder views/<name>/ next to nodes/ and lib/, holding a view.json manifest and its source files:

views/vol_board/
  view.json
  App.tsx
  components/Chart.tsx
  styles.css
{
  "title": "Vol board",
  "description": "Realized vol per ticker, as of the selected date",
  "runtime": "react",
  "entry": "App.tsx",
  "reads": ["rolling_vol", "universe"]
}
  • reads is the whole of what a view can see: the outputs of those nodes, nothing else. Like a node's upstreams it gives the graph edges, a state, and the list of outputs a view depends on.
  • Rendering never runs compute. A view reads outputs that exist; it does not trigger runs. Work a view needs belongs in a node it reads.
  • runtime is react (the default and, for now, the only one) and entry is the component file (App.tsx by default; .tsx, .ts, .jsx or .js). title defaults to the folder name.
  • View names follow the node-name rule (snake_case). Files are text with one of .tsx .ts .jsx .js .css .json .html .md .svg, at most 512 KB each, in plain relative paths (up to 8 levels); other files in the folder are not part of the view and node_modules/ is ignored.
  • Views are read statically, like nodes: a missing or broken view.json, an unknown key, a missing entry file or a reads entry naming a node that does not exist still lists the view, with a parse_error.
  • Every file of a view is versioned like node files (see "Execution model"), so any version can be restored and a deleted view brought back. The file watcher picks up edits made on disk.
  • Views are not shipped to a remote executor: no node can read them, so editing a view never ships a new project bundle.

GET /api/project (and GET /api/views) list each view with its state for the requested parameter set, derived from the nodes it reads:

state
readyevery read node has a fresh output for this parameter set
missinga read node has no output for it yet (reason names them)
staleevery read node has an output, but one is out of date or being refreshed (reason names them and their state)
errorthe view itself is broken; reason is its parse_error

Each view also carries outputs: per read node, its state, kind and the artifact_id of the output the view would show now. Artifact ids name their content, so a client can fetch /api/artifacts/{node}/{artifact_id}.parquet once and cache it for good. hash covers every file of the view, so a client can tell when its code changed.

Rendering a view

The UI's Views mode (next to the graph) lists the views with their state and reason, shows the nodes each one reads (click one to open it on the canvas), lets you pick the run parameters, and renders the selected view. Compile and runtime errors from the view are listed under it with the file they came from. examples/markets ships one (views/vol_board).

A view runs in an <iframe sandbox="allow-scripts"> built from a srcdoc: an opaque origin, so no cookies, no API token and no access to the page. The frame fetches nothing at all: its Content-Security-Policy names no URL (default-src 'none', connect-src 'none', images and fonts only from data:/blob:) and lets only its own bootstrap script run (by nonce), plus code that script evaluates. The page fetches the runtime once and posts its source to the bootstrap. (Chromium does not let an opaque-origin frame load scripts from a local server anyway, so <script src> from the frame would fail for exuvia serve on localhost.) The view's only way to data is asking the page, and the page answers only for the nodes in reads.

The runtime (ui/src/views/runtime.tsx, built to exuvia/static/view-runtime/runtime.js and served at GET /api/view-runtime/runtime.js) is bundled with exuvia; nothing is fetched from a CDN, so views work where exuvia has no internet. It compiles each file in the browser with Sucrase (TypeScript + JSX to CommonJS) the first time it is imported, then renders the entry file's export default with React 18. A view can import:

  • its own files by relative path, with or without the extension (./Chart, ../lib/format.ts; ./dir finds dir/index.tsx), never outside its folder;
  • .css files (added to the page), .json (the parsed value), .svg (a data: URL);
  • by bare name, only what the runtime ships: react (+ react/jsx-runtime), react-dom (+ /client), apache-arrow, vega-embed (Vega-Lite charts) and exuvia. Anything else is a compile error naming the file: there is no package install and no network.

exuvia is the view's API:

import { rows, useParams, useQuery, useTable } from "exuvia";

export default function App() {
  const vol = useTable("rolling_vol");              // {data, error, loading}; data is an Arrow Table
  const top = useQuery("select * from sector_summary order by avg_vol desc limit 3");
  const [params, setParams, declared] = useParams();
  if (vol.error) return <p>{vol.error}</p>;
  return <pre>{JSON.stringify(rows(top.data), null, 2)}</pre>;
}
useTable(node), table(node)a read node's current table output, as an Arrow Table
useJson(node), json(node)a read node's current JSON output
useQuery(sql), query(sql)DuckDB SQL that sees only the read nodes (<node> and <node>__runs), as an Arrow Table
useParams(), getParams(), setParams(values)the run parameters the view shows; setting them changes which outputs it reads, never runs anything
onChange(fn)called with the nodes whose output was replaced
rows(table)Arrow rows as plain objects (64-bit integers become numbers when they fit)
useView(), useDark()the view's name, title and reads; whether the page is in dark mode

The hooks reload by themselves when an output they read is replaced (a run finished, or the parameters changed) and keep the previous data while reloading. The page's CSS variables (--bg, --panel, --line, --text, --muted, --accent, --fresh, --failed, --mono, --sans) are set in the frame and follow light and dark mode.

The protocol between the frame and the page is postMessage, defined in one typed module, ui/src/views/protocol.ts. Every message carries channel: "exuvia-view/1", and each side also checks the sender (the frame's origin is "null", so the origin says nothing):

directionmessage
frame → pagebootthe bootstrap is listening
page → frameruntime {source}the runtime script, evaluated by the bootstrap
frame → pagereadythe runtime loaded
page → frameload {view, params, dark}the view's files ({path: source}), entry and reads, and the parameter set
frame → pagerequest {id, method, args}table {node}, json {node}, query {sql}, params {}, setParams {params}
page → frameresponse {id, ok, result | error}Arrow IPC bytes for table/query (transferred, not copied), the value for json, {params, specs} for the parameter calls
page → framechanged {nodes, params}outputs the view reads were replaced; driven by /api/events
page → frametheme {dark}
frame → pagestatus {phase}compiled, rendered, or compile/runtime with error, file, stack

The page refuses table/json for a node not in reads and sends every request to the view-scoped routes below, which refuse it again on the server. It caches table answers by artifact_id (an id names its content). When the view's files change (its hash), the frame is rebuilt.

View-scoped data routes. GET /api/views/{name}/data/{node} is /api/nodes/{node}/data (JSON or Arrow, ?params=) that answers 403 unless the view reads node. POST /api/views/{name}/query is /api/query over a DuckDB connection that holds only the views of the nodes in reads (and their __runs) and is then locked: external access is off except for those exact output files, extensions cannot load, and the configuration cannot be changed back, so the SQL cannot read_parquet another node's file, COPY out, ATTACH a file or INSTALL anything.