VRYO
FeaturesGetting StartedPricingFAQDocs
GitHubLog InSign Up

Introduction

  • Getting Started
  • Concepts

Workspace

  • Workspace Guide

Reference

  • Widget Reference
  • API Reference

Examples

  • Recipes

Resources

  • Templates
Reference

API Reference

Full reference for all exports from @vryo/client, @vryo/core, and @vryo/server.

@vryo/core

Pure types and Zod schemas. Safe to import anywhere — server, client, Edge.

CanvasState

PropTypeDefaultDescription
revision*number—Monotonically incrementing integer. Bumped on every patch.
widgets*Record<string, Widget>—Flat map from widget ID to widget object.

AgentPatch

PropTypeDefaultDescription
agentId*string—Identifier for the agent that produced this patch.
baseRevision*number—Canvas revision the patch was computed against.
rationalestring—Human-readable explanation of the patch.
upsertWidgetInput[]—Widgets to create or update.
removestring[]—Widget IDs to delete.

Widget Types

6 widget types, each validated by Zod schemas: chart (13 chart types), table, note, kpi, gauge, filter. See the Widget Reference for full property documentation.

@vryo/client

VryoProvider

The top-level React component. Renders a tldraw canvas with all VRYO shape utils registered.

PropTypeDefaultDescription
styleReact.CSSProperties—Container styles. Typically set width + height.
classNamestring—Container class name.
initialStateCanvasState—Initial widget layout. Defaults to an empty canvas.
agentEndpointstring—URL for the agent POST endpoint.
onStateChange(state: CanvasState) => void—Called whenever CanvasState changes.
refRef<VryoProviderRef>—Imperative handle — exposes applyPatch, getState, undo, redo.

VryoProviderRef

PropTypeDefaultDescription
applyPatch(patch: AgentPatch) => void—Apply a patch to the canvas.
getState() => CanvasState—Get the current canvas state snapshot.
undo() => void—Undo the last tldraw action.
redo() => void—Redo the last undone action.

useVryo()

Access the VryoContext inside any child component of VryoProvider.

const { editor, canvasState, applyPatch } = useVryo();

useArrowData(binding)

PropTypeDefaultDescription
binding*DataBinding | undefined—DataBinding from widget props. Returns empty data if undefined.

Returns { data: Record<string, unknown>[], status, error }.

useWidgetSelection()

Tracks tldraw selection state, returning the selected VRYO widgets.

PropTypeDefaultDescription
selectedIdsstring[]—Widget IDs currently selected on the canvas.
selectedWidgetsWidget[]—Full widget objects for selected IDs.
hasSingleSelectionboolean—True when exactly one widget is selected.
activeWidgetWidget | null—The single selected widget, or null.

usePersistence(storageKey)

PropTypeDefaultDescription
storageKey*string—localStorage key to persist under.
restoredStateCanvasState | null—The previously saved state, if any.
saveState(state: CanvasState) => void—Save the current state to localStorage.
clearState() => void—Clear the saved state.

useExportCanvas()

PropTypeDefaultDescription
exportJSON(filename?: string) => void—Download the canvas state as a .json file.
exportTableCSV(widgetId: string, filename?: string) => void—Download a table widget's data as a .csv file.
serializeToString() => string—Return the canvas state as a JSON string.

useWidget(widgetId)

Subscribe to a single widget by ID. Returns the widget state plus typed update/remove functions.

PropTypeDefaultDescription
widgetAnyWidget | undefined—The widget object, or undefined if not found.
existsboolean—Whether the widget exists on the canvas.
update(changes: Partial<Widget>) => void—Merge partial changes into the widget via an AgentPatch.
remove() => void—Delete the widget from the canvas.
const { widget, update, remove } = useWidget("revenue-chart");

// Update a property
update({ title: "Q1 Revenue" });

// Remove from canvas
remove();

useDataSource(config)

Fetch external data from REST APIs or CSV endpoints with auto-refresh, column inference, and transform support.

PropTypeDefaultDescription
config.urlstring—URL to fetch data from.
config.type"json" | "csv"—Data format. Defaults to "json".
config.recordsRecord<string, unknown>[]—Static records instead of fetching.
config.refreshIntervalnumber—Auto-refresh interval in ms (0 = disabled).
config.transform(records) => records—Transform records after fetch.
config.enabledboolean—Whether to fetch. Defaults to true.

Returns { data, columns, loading, error, lastFetched, refetch }.

const { data, columns, loading, refetch } = useDataSource({
  url: "/api/analytics/revenue",
  type: "json",
  refreshInterval: 30_000, // auto-refresh every 30s
});

useDashboardActions()

All common dashboard operations in one hook — add, remove, duplicate, clear, export, import.

PropTypeDefaultDescription
widgetCountnumber—Total widgets on canvas.
revisionnumber—Current canvas revision.
widgetsAnyWidget[]—All widget objects.
addWidget(widget: AnyWidget) => void—Add a single widget.
addWidgets(widgets: AnyWidget[]) => void—Add multiple widgets at once.
removeWidget(id: string) => void—Remove a widget by ID.
duplicateWidget(id, position?) => void—Clone a widget with optional new position.
clearAll() => void—Remove all widgets from the canvas.
exportJSON() => string—Serialize the full canvas state to JSON.
importWidgets(widgets: AnyWidget[]) => void—Replace all widgets with a new set.
const { addWidget, duplicateWidget, exportJSON, clearAll } = useDashboardActions();

// Add a new chart
addWidget({ id: "new", type: "chart", title: "Revenue", ... });

// Duplicate an existing widget
duplicateWidget("revenue-chart", { x: 600, y: 200 });

// Export current state
const json = exportJSON();

@vryo/server

callAgentWithCanvas(canvasState, message, options?)

One-shot Claude call. Returns a parsed AgentPatch.

PropTypeDefaultDescription
canvasState*CanvasState—Current canvas state to include in the prompt.
message*string—User message / instruction for the agent.
optionsAgentOptions—model, maxTokens, systemHints, apiKey overrides.

streamAgentWithCanvas(canvasState, message, options?)

Returns an AsyncGenerator that yields text chunks as they stream from Claude.

callOpenAIAgentWithCanvas(canvasState, message, options?)

Same as Claude variant but targeting any OpenAI-compatible API (GPT-4, Groq, Ollama, etc).

PropTypeDefaultDescription
options.baseURLstring—Override to use a different OpenAI-compatible endpoint.
options.modelstringgpt-4oModel ID to use.

collectStreamingPatch(stream, onChunk?)

Consumes an AsyncGenerator of text chunks, parses the JSON patch from the final output.

buildCanvasPrompt(ctx, options?)

Serializes a CanvasContext into a prompt string ready to send to an LLM.