Studio Canvas: Node-Based AI Generation Workflows

The Studio Canvas is WZRD Studio’s visual programming environment for AI media generation. Rather than a linear queue of tasks, the Canvas exposes your entire pipeline as a directed acyclic graph — every node is a generation step, every edge is a data dependency, and clicking Execute streams live status back to each node in the graph. You can build a simple image → video chain in seconds, or compose a multi-branch workflow that fans out across models and media types.

Navigating to the Studio

The Canvas lives at /projects/:projectId/studio. Open it from any project’s navigation bar or by selecting Studio from the app sidebar. On desktop you see the full three-panel layout. On mobile, the left sidebar and right panel collapse into sheet drawers accessible via the Tools and Inspect buttons in the top bar.

The Canvas is optimized for desktop use. On smaller screens a banner appears with a direct link to the Storyboard (Timeline) page where touch interactions are smoother.

Layout Overview

Left Sidebar

Browse and drag node types onto the canvas, or insert project assets directly as seed nodes. Each node category (Image, Video, Audio, Text, Action, Workflow) has its own section.

Canvas

The React Flow (@xyflow/react) graph surface. Pan, zoom, select multiple nodes, and wire outputs to inputs by dragging connection handles between ports.

Right Panel

Inspect and edit the properties of the selected node — prompts, model selection, parameters — and trigger AI-assisted workflow generation from a text description.

A Settings Panel overlay (accessible from the App Header) surfaces project-level configuration such as aspect ratio and default models.

The `computeFlowStore`

All canvas state lives in the Zustand store exported from src/store/computeFlowStore.ts. The key actions you’ll encounter in code and in logs are:

addNode / createNode

createNode(kind, position) scaffolds a fully normalised NodeDefinition with typed ports. addNode(node) pushes it into the graph and records a history entry.

saveGraph

Serialises the current graph (nodes + edges + view state) and calls the save_compute_graph Supabase RPC. Uses optimistic revision tracking to reject stale writes.

executeGraphStreaming

Posts to POST /functions/v1/compute-execute and processes the SSE response, forwarding per-node status, progress, and preview events live.

addGeneratedWorkflow

Ingests an AI-generated NodeDefinition[] + EdgeDefinition[] pair, normalises all IDs to UUIDs, validates edge port references, and stages the workflow for a two-phase React Flow flush.

Undo / Redo

Every mutation that calls addNode, updateNode, addEdge, or removeNode pushes a snapshot to ComputeFlowHistoryManager. Call undo() / redo() on the store, or use the keyboard shortcuts in the canvas. Edit sessions (beginEditSession / endEditSession) coalesce rapid keystrokes in node parameter fields into a single history entry.

Node Types

Nodes are typed by their kind field, which maps to an entry in NODE_TYPE_CONFIGS and the media action registry.

Generation Nodes

Image, Video, Audio, Text — each wraps a specific AI model call. Port datatypes enforce valid connections: an image output cannot feed a text input.

Action Nodes

Backed by MediaActionDefinition entries in the action registry. Action nodes carry an actionId, pre-configured default params, and typed inputs/outputs inferred from the action definition.

Workflow Nodes

Container nodes that encapsulate a reusable sub-graph. Generated by the AI workflow builder and imported via addGeneratedWorkflow.

Local FFmpeg Nodes

Action nodes with executor: 'ffmpeg' and providerPreference including 'local'. These require the WZRD Electron desktop app and prompt the user to select an export folder before running.

Executing the Graph

Save the graph

The Canvas auto-saves on a debounced timer. You can also force a save before execution. saveGraph calls the Supabase RPC save_compute_graph with the current revision number; a mismatch error means another client saved a newer version.

POST to compute-execute

executeGraphStreaming sends:

POST /functions/v1/compute-execute
Content-Type: application/json
Authorization: Bearer <access_token>

{ "projectId": "uuid", "nodeIds": ["uuid", ...] }

Omit nodeIds to execute all nodes. The function returns a text/event-stream response.

Handle SSE events

The store processes four event types from the stream:

Event	Payload fields	Action
`meta`	`run_id`, `total_nodes`	Seeds execution progress
`node_status`	`node_id`, `status`, `output`, `error`	Updates node status + preview
`node_progress`	`node_id`, `progress`	Updates progress percentage
`complete`	`completed_nodes`, `total_nodes`	Marks run finished
`error`	`error`	Marks run failed

Node statuses follow the state machine: idle → queued → running → succeeded | failed | skipped. Out-of-order events that violate the machine are silently dropped.

View results

Completed nodes show their output preview inline. Image and video previews render directly on the node card. Select a node to inspect its full output in the Right Panel.

If a run exhausts your credit balance, compute-execute returns a structured InsufficientCredits error. The store intercepts this and routes you to the billing top-up page automatically.

API Reference

`POST /functions/v1/compute-execute`

Executes one or more nodes in the saved graph and streams progress via SSE.

projectId

string

required

The UUID of the project whose saved graph should be executed.

nodeIds

string[]

Optional subset of node IDs to execute. When omitted, all nodes run.

Response: text/event-stream — FIFO sequence of meta, node_status, node_progress, complete, and error events.

`POST /functions/v1/compute-save-graph` (via RPC)

Saves the graph atomically via the save_compute_graph Postgres RPC. Called internally by saveGraph.

p_project_id

string

required

Target project UUID.

p_expected_revision

number

required

Optimistic concurrency revision. The RPC rejects the write if the stored revision is newer.

p_nodes

NodeDefinition[]

required

Full list of serialised node objects.

p_edges

EdgeDefinition[]

required

Full list of serialised edge objects.

Agent Integration: `run_studio_graph`

The run_studio_graph MCP tool lets an AI agent execute a saved Studio graph programmatically without any UI interaction. Skill: agent-skills/run-studio-graph/skill.md

POST /functions/v1/compute-execute
Content-Type: application/json

{ "project_id": "uuid" }

The endpoint streams { node_id, status, progress, artifacts } events back to the agent until all nodes complete. The agent can use intermediate artifacts (image URLs, video URLs) as inputs to subsequent tool calls.

Combine run_studio_graph with make_magic for a fully automated pipeline: generate a storyline, run the Studio graph to produce assets, then assemble with Director’s Cut — all without leaving your agent session.

Voice Actions

The Studio page registers two voice actions via useRegisterVoiceActions that the WZRD voice agent can invoke within the studio scope:

Action	Description
`studio_create_node`	Adds a new node of the specified type to the canvas. Requires confirmation (`risk: 'write'`). Accepts `type`, `x`, `y`, and optional `seed` parameters.
`studio_select_node`	Selects an existing node by `nodeId`, scrolling the right panel to show its properties.

Both actions return a VoiceActionResult with ok, status, and message fields so the voice agent can confirm the operation to the user.

Inserting Assets from the Gallery

Drop any project asset from the Assets Gallery panel in the left sidebar onto the canvas to seed a generation node pre-loaded with that asset. Supported asset types map to node kinds as follows:

Asset type	Node kind	Output port datatype
`image`	`Image`	`image`
`video`	`Video`	`video`
`audio`	`Transform`	`audio`

The node’s params are populated with assetId, assetUrl, and imageUrl so downstream generation nodes can reference the asset immediately.

Creation Pipeline

Editing & Export

Publishing & Assets

Studio Canvas: Node-Based AI Generation Workflows

Navigating to the Studio

Layout Overview

Left Sidebar

Canvas

Right Panel

The `computeFlowStore`

addNode / createNode

saveGraph

executeGraphStreaming

addGeneratedWorkflow

Undo / Redo

Node Types

Generation Nodes

Action Nodes

Workflow Nodes

Local FFmpeg Nodes

Executing the Graph

API Reference

`POST /functions/v1/compute-execute`

`POST /functions/v1/compute-save-graph` (via RPC)

Agent Integration: `run_studio_graph`

Voice Actions

Inserting Assets from the Gallery

Build docs developers (and LLMs) love

Creation Pipeline

Editing & Export

Publishing & Assets

Documentation Index

​Navigating to the Studio

​Layout Overview

Left Sidebar

Canvas

Right Panel

​The computeFlowStore

addNode / createNode

saveGraph

executeGraphStreaming

addGeneratedWorkflow

​Undo / Redo

​Node Types

Generation Nodes

Action Nodes

Workflow Nodes

Local FFmpeg Nodes

​Executing the Graph

​API Reference

​POST /functions/v1/compute-execute

​POST /functions/v1/compute-save-graph (via RPC)

​Agent Integration: run_studio_graph

​Voice Actions

​Inserting Assets from the Gallery

Build docs developers (and LLMs) love

Navigating to the Studio

Layout Overview

The `computeFlowStore`

Undo / Redo

Node Types

Executing the Graph

API Reference

`POST /functions/v1/compute-execute`

`POST /functions/v1/compute-save-graph` (via RPC)

Agent Integration: `run_studio_graph`

Voice Actions

Inserting Assets from the Gallery