TECHNICAL REFERENCE

Architecture

System design for technical readers. How the canvas, panels, and agents work together.

CanvasEngine SPI

The CanvasEngine Service Provider Interface abstracts the rendering substrate. Today we ship with a tldraw-based implementation and a lightweight DOM app-shell engine.

CanvasEngine
├── tldrawAdapter (default)
│   └── shape registry + camera sync
└── DOMAppShell
    └── panel host + event bridge

PanelDefinition contract

All panels are defined using a validated schema. The contract guarantees consistent behavior across static, schema-driven, agent-composed, and custom React panels.

interface PanelDefinition {
  id: string;
  tier: 'static' | 'schema' | 'agent' | 'custom';
  schema?: JSONSchema;
  component?: React.ComponentType;
  permissions: Permission[];
}

DataAdapter

The DataAdapter provides a unified boundary for query, mutate, and subscribe operations. Agents and the canvas interact with data exclusively through this interface.

DataAdapter
├── query(panelId, filter)
├── mutate(action, payload)
└── subscribe(panelId, callback)

createCanvasHost API surface

The primary entry point for embedding and hosting a canvas. Returns a fully initialized host instance with panel catalog and agent registry attached.

const host = createCanvasHost({
  tenant: "acme",
  canvasMode: "infinite",
  primaryColor: "#2563EB"
});

host.mount(document.getElementById("canvas"));

WorkspaceDigest + AgentRegistry

The blackboard pattern enables agents to share context. WorkspaceDigest captures the current state while AgentRegistry tracks active agents and their capabilities.

WorkspaceDigest
├── panels: PanelInstance[]
├── agents: AgentRef[]
└── mutations: PendingMutation[]

AgentRegistry
└── register(agent) → capabilities

CanvasMode

Three supported modes give hosts full control over the spatial experience.

infinite — unbounded panning and zooming
bounded — constrained viewport
fixed — static layout

EXAMPLE USAGE

<agentable-canvas
canvas-mode="infinite"
tenant="acme">
</agentable-canvas>

Page session model

Multiple <agentable-canvas> embeds can participate in a single shared session. All instances communicate through the same WorkspaceDigest, enabling consistent state across different parts of a page or even across tabs.

Security model

No untrusted code ever executes in the trusted context. Agent-composed panels run inside a dedicated sandbox tier for code preview and execution.

Security Layers
├── Trusted context (host)
├── Sandbox tier (agent panels)
│   └── isolated iframe + CSP
└── HITL mutation gates