insights/products/canvas/skills/building-canvases/SKILL.md

name, description

name

description

building-canvases

Create or edit a Insights canvas — a sandboxed browser application (data board, document, form, small tool, graphics experiment) stored in Insights and rendered by the desktop/web app. Use when a task asks to build, generate, update, or fix a canvas, or when a canvas id is given as the publish target. Covers resolving or creating the target canvas, choosing an implementation approach (React + Quill vs plain HTML/browser APIs), the read → edit → validate → publish → build loop, and which companion canvas skills to load for the details.

Building canvases

A canvas is a client-side browser application that runs in a sandboxed iframe inside Insights. Its source lives in Insights — 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 — Insights data products, dashboards, forms, application-like state, and anything that should look native to Insights. 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

1. Read the current source and version pointer with canvas-source-retrieve. Remember current_version_id — your publish must be guarded on it.
2. Edit the project files. For any Insights data the canvas shows, follow the querying-canvas-data skill (saved insights loaded via the ph SDK — never fetch or your own Insights client), and declare every ph call in project.capabilities (insight short ids in capabilities.insights.insights, captured events in captureEvents, inlineQueries: true for ad-hoc queries) — the host enforces these at runtime and validation rejects undeclared calls.
3. Validate with canvas-validate-create as often as needed and fix every error-severity diagnostic.
4. 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.
5. 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.