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):
- Nodes run and store their outputs. A view never runs anything.
- The view's
view.jsonnames the nodes it reads. Those are the only outputs it can reach, and they are its edges on the graph. - 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. - The code asks for data through the
exuviamodule: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. - 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"]
}readsis 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.
runtimeisreact(the default and, for now, the only one) andentryis the component file (App.tsxby default;.tsx,.ts,.jsxor.js).titledefaults 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 andnode_modules/is ignored. - Views are read statically, like nodes: a missing or broken
view.json, an unknown key, a missing entry file or areadsentry naming a node that does not exist still lists the view, with aparse_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 | |
|---|---|
ready | every read node has a fresh output for this parameter set |
missing | a read node has no output for it yet (reason names them) |
stale | every read node has an output, but one is out of date or being refreshed (reason names them and their state) |
error | the 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;./dirfindsdir/index.tsx), never outside its folder; .cssfiles (added to the page),.json(the parsed value),.svg(adata:URL);- by bare name, only what the runtime ships:
react(+react/jsx-runtime),react-dom(+/client),apache-arrow,vega-embed(Vega-Lite charts) andexuvia. 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):
| direction | message | |
|---|---|---|
| frame → page | boot | the bootstrap is listening |
| page → frame | runtime {source} | the runtime script, evaluated by the bootstrap |
| frame → page | ready | the runtime loaded |
| page → frame | load {view, params, dark} | the view's files ({path: source}), entry and reads, and the parameter set |
| frame → page | request {id, method, args} | table {node}, json {node}, query {sql}, params {}, setParams {params} |
| page → frame | response {id, ok, result | error} | Arrow IPC bytes for table/query (transferred, not copied), the value for json, {params, specs} for the parameter calls |
| page → frame | changed {nodes, params} | outputs the view reads were replaced; driven by /api/events |
| page → frame | theme {dark} | |
| frame → page | status {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.