Building Canvases

Building canvases

A canvas is a client-side browser application that runs in a sandboxed iframe inside PostHog.

Its source lives in PostHog — not in a repository — and you read and write it through the

canvas-* tools. Never write a canvas to a local file; publishing through the tool is what

saves it.

Resolve the target canvas

• If the task names a canvas id (canvas-initiated tasks do), that is the target. Do not create another.
• Otherwise — channel-composer tasks give the channel, not a canvas — list the channel's canvases

with canvas-list (scope with channel; resolve a bare channel name with channel-list first).

If one is clearly what the request refers to — an earlier iteration of the same board or tool —

build on it instead of creating a near-duplicate, and say so in your reply so the user knows

where the result landed.

• Only when nothing existing fits, create one with canvas-create in the right channel, named

with a short descriptive title drawn from the request — never "Untitled canvas".

Choose the least complex implementation that meets the request

• React + Quill — PostHog data products, dashboards, forms, application-like state, and anything

that should look native to PostHog. Load the building-react-quill-canvases skill.

• Semantic HTML, CSS, and direct browser APIs — static documents, focused experiments, generative

graphics, <canvas>/WebGL work where React adds no structure. Load the building-html-canvases skill.

• Mix them when appropriate: React can own the application chrome while Three-style code owns a

canvas element, or a mostly static page can mount one interactive island.

This is a judgment call, not a persisted mode — ask the user only when the choice changes a

user-visible requirement you cannot infer.

The iteration loop

• Read the current source and version pointer with canvas-source-retrieve.

Remember current_version_id — your publish must be guarded on it.

• Edit the project files. For any PostHog data the canvas shows, follow the querying-canvas-data

skill (saved insights loaded via the ph SDK — never fetch or your own PostHog client), and

declare every ph call in project.capabilities (insight short ids in

capabilities.posthog.insights, captured events in captureEvents, inlineQueries: true for

ad-hoc queries) — the host enforces these at runtime and validation rejects undeclared calls.

• Validate with canvas-validate-create as often as needed and fix every error-severity

diagnostic.

• Publish the complete project with canvas-publish-create, passing expected_current_version_id.

Follow the validating-and-publishing-canvases skill for diagnostics and conflict recovery.

• Wait for the build. A publish queues a server-side build; poll canvas-builds-retrieve

(every few seconds, up to ~2 minutes) until your build is ready or failed. On failed,

read the build's error diagnostics, fix the project, and publish again — do not finish the

task with a failed build.

Publish once per requested change, when the canvas is ready — not after every micro-edit.

Source-project shape

• Keep index.html as the entry shell returned by the source tool.
• src/canvas.tsx remains the conventional React entry component, but it may import additional

relative TypeScript, TSX, JavaScript, JSON, SVG, CSS, and admitted asset files from the project.

• Self-contained module workers may be imported with ./worker.ts?worker. A worker must not import

another local module.

• Binary assets belong in the project's assets map as base64 content with an admitted content type.

PNG, JPEG, GIF, WebP, AVIF, WOFF/WOFF2, WebAssembly, and generic octet-stream assets are supported.

• Keep the platform dependency map exactly as returned. Do not add npm packages; local relative

imports are project files, while bare imports remain limited to the platform-pinned set.