Canvases
A canvas is a React input screen for a workflow, written in canvas/
Without a canvas, the run screen's Inputs tab shows a standard form built from the workflow's declared inputs. A canvas replaces that form with your own screen: a deck map to click, a plate layout, a table of samples. It is a React component in a .tsx file in the project.
You or your coding agent write the canvas file and sync it. The web app renders the canvas; it has no canvas editor. The starter's two workflows each have one to start from: canvas/plate_transfer_screen.tsx and canvas/plate_through_shaker_screen.tsx (pick the objects from the world, Confirm setup, then Run).
Create one
zeon new canvas my_transfercreated canvas for workflow my_transfer
- canvas/my_transfer_screen.tsx
- workflows/my_transfer.json (patched canvas_ui)
Edit canvas/my_transfer_screen.tsx to get started.
The argument is the workflow id; the workflow must exist. The command writes a starter component and adds this block to the workflow:
"canvas_ui": {
"kind": "react",
"source_ref": "canvas/my_transfer_screen.tsx",
"enabled": true,
"version": 1,
"updated_at": "2026-11-08T12:00:00.000Z"
}It stops without writing anything when the workflow is missing, already has a canvas_ui block, or the .tsx file exists.
To attach a canvas by hand, write the file under canvas/ and add the block yourself. source_ref must be canvas/<name>.tsx with a lowercase name of letters, digits and underscores. "enabled": false turns the canvas off and brings back the standard form.
What a canvas can do
The file must export default a React component. It is compiled in the browser (TypeScript and JSX) and runs in a sandboxed frame:
- it can import only
reactandreact-dom; - it has no network access;
- it talks to the run screen through a global object,
zeon.
zeon. | What it is |
|---|---|
schema | The workflow's declared inputs (name, type, description, defaultValue, ...). |
defaults | Starting values for the inputs. |
worldObjects | The objects in the loaded world: uuid (the instance id), name, displayName, meshType, pose (xyz in metres, wxyz quaternion). |
submit(values) | Send the input values. The run screen checks them against the schema. |
onValidationErrors(callback) | Called with [{path, message}] when submitted values fail the check. |
inputPresets, onInputPresets(callback) | Presets from the project's inputs/ folder (below). |
tipBoxes, onTipCounts(callback), resetTipBox(uuid) | Live tip counts of the world's tip boxes, and a request to mark a box as replaced (the app asks the user to confirm). |
resetInputs() | Ask the run screen to clear the staged inputs and mount the canvas empty. |
setConfirmed(bool) | Report whether the values on screen are the confirmed ones: true enables Run, false disables it. Call setConfirmed(true) only after a successful submit. |
setDirty(bool) | Report unsaved edits, so the page warns before a reload discards them. |
Run gating
While a canvas is shown, Run stays disabled until the canvas has called zeon.submit(values) with values that pass the check against the workflow's inputs, or has called zeon.setConfirmed(true). The submitted values become the run's inputs. A typical canvas has its own confirm button that calls submit.
If the canvas fails to compile or throws while rendering, the Inputs tab shows Canvas unavailable with the error and a Use standard form instead button.
Input presets
A project can carry named sets of input values in inputs/<id>.json (the id lowercase letters, digits and underscores). Each file is a flat JSON object of input values, with an optional _label for the name shown:
{
"_label": "Stand 1 to stand 2",
"plate": "wellplate",
"start_stand": "wellplate_stand_1",
"end_stand": "wellplate_stand_2"
}The canvas receives them as zeon.inputPresets ([{id, name, values}]) and can offer them as a choice. A file that is not a JSON object is skipped.
Preview it
Sync the canvas, load the project on your instance, and open the canvas in the app:
zeon sync
zeon up
zeon app my_transferThe link opens the run screen on the Inputs tab with the canvas rendered against the simulated world. zeon app needs CLI 1.5.5 or newer (older versions: zeon open --canvas my_transfer). The link signs the browser in without a password; it is personal, works once and is valid for 5 minutes, so open it promptly or run zeon app my_transfer again for a fresh one (see Login links from the CLI). While that page is open, it re-reads the canvas every few seconds and shows a new version after each zeon sync; a new version starts fresh, so its inputs reset and Run waits for a new submit. See Working with a coding agent.
Updated about 19 hours ago