Building canvases
A canvas is a client-side browser application that runs in a sandboxed iframe inside Flind.
Its source lives in Flind — 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.
Canvas work can start from any ordinary task. A dedicated canvas mode or pre-created canvas is
not required. When the user asks for a board, document, form, visualization, or small app that
should live in Flind, treat that as a canvas request and follow this skill.
This skill owns freeform canvases (standalone apps). Two other canvas kinds exist: grid
canvases (widget grids, including the user's home canvas) and component canvases (reusable
widgets grids place). When the target is a grid or home canvas, a placement, or a reusable
widget/component, load composing-grid-canvases instead — it owns the store search → configure →
fork → build ladder and the layout patch loop. Authoring a component's source still uses the
implementation companions below.
Resolve the target canvas
- If the task names a canvas id (canvas-initiated tasks do), that is the target. Do not create another.
- Otherwise the target channel is the one the task was created in — named in the task's context
(the
channel_context block or the generation instructions). List that channel's canvases with
canvas-list (scope with channel). 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 that same channel, named
with a short descriptive title drawn from the request — never "Untitled canvas".
- Never survey channels to choose a target yourself: use
channel-list only to resolve a channel
the USER named to its id. Its listing puts the personal #me channel first, and #me is never a
default — a canvas filed there is invisible to everyone else. If the task names neither a canvas
nor a channel, ask which channel to use instead of guessing.
Load the companion skills for the implementation
This skill owns canvas selection and the authoring lifecycle. The companion skills hold the
implementation contracts. Load every companion that applies before writing source:
building-react-quill-canvases for dashboards, data boards, forms, tools, application-like
state, or anything that should look native to Flind. It owns allowed imports, Quill composition,
theming, charts, loading and error states, and the date picker.
building-html-canvases for documents, articles, focused experiments, generative graphics,
<canvas>, or WebGL work where application components add no useful structure. It owns semantic
markup, direct browser APIs, animation cleanup, and non-Quill theming.
querying-canvas-data whenever the canvas reads Flind data, captures events, or navigates.
It owns the ph SDK, saved-insight preference, result shapes, variables, date ranges, progressive
per-query loading, and declared data capabilities. Load it alongside either implementation skill
when data is involved.
validating-and-publishing-canvases for every canvas. It owns project shape, capability
declarations, validation diagnostics, guarded publishes, drafts, builds, and conflict recovery.
Mix implementation approaches when appropriate: React can own application chrome while browser
graphics 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.
Blocks
A canvas can contain premade blocks: numbers, goals, trends, top lists, funnels, retention, saved insights, live event feeds, SQL tables, filters, compare and refresh controls, and callouts.
They are React components in src/blocks/ that people drag into the canvas in the desktop app, so they are part of your source.
Read references/blocks.md before you change a canvas that has src/blocks/runtime.tsx.
Params
Expose the values a person may want to change as params. They can then change them in the desktop editor without a new task.
Params are optional, but add them to each panel, card, or tool that has values worth changing: titles, copy, events, properties, thresholds, limits, colors.
Params need React components. A plain HTML canvas has no params.
How the editor uses editable()
In the desktop editor, a person can select any element of the canvas: a heading, a paragraph, a section. They can move, duplicate, or delete it, and double-click text to change it. This works with no editable() call.
editable() makes a component one block. The editor then treats the block as one unit:
- A click selects the full block, not the element inside it.
- Move, duplicate, and delete act on the full block.
- The side panel shows the block's params as fields. A change writes the new value into the block's props in the source.
- To reach the elements inside a block, the person double-clicks the block to open it.
So use editable() on the parts a person thinks of as one thing and configures as one thing: a card, a chart, a table, a form. Keep the page layout around them as plain JSX. The person can then select a card as a block, and still select a page heading or section directly. If the component that holds the full page uses editable(), the full page becomes one block, and each click selects all of it.
Adding params
- Put each panel in its own component. The component takes these values as props, with defaults.
- Spread
editable(name, props, params) from @posthog/canvas-sdk on the root element of the component. name is the component name. params maps each prop name to its field.
- Use the component with literal props, for example
<SignupFunnel blockId="b-k3m9x2" title="Signup" windowDays={14} />. The editor writes changes into these props, so do not compute them inline.
- Give each use a unique
blockId prop, for example <SignupFunnel blockId="b-k3m9x2" … />, so a person can point the agent at one card. Use only letters, digits, _, -, ., and :, or the editor ignores the ID. In a list, build it from a stable key of the item: blockId={`kpi-${item.id}`}.
import { editable } from '@posthog/canvas-sdk'
export function SignupFunnel(props: { blockId?: string; title?: string; steps?: string[]; windowDays?: number }) {
const { title = 'Signup funnel', steps = ['$pageview', 'signed_up'], windowDays = 14 } = props
return (
<Card
{...editable('SignupFunnel', props, {
title: { type: 'text', label: 'Title', default: 'Signup funnel' },
steps: { type: 'events', label: 'Steps', default: ['$pageview', 'signed_up'] },
windowDays: { type: 'number', label: 'Conversion window (days)', min: 1, max: 90, default: 14 },
})}
>
…
</Card>
)
}
Field types: text, longtext, number (min, max, step; with both min and max the editor shows a slider), boolean, select (options: strings or { value, label }), event, events, property, insight (a saved insight's short id), color. Each field can also have a description.
Give each field the same default as its prop default, for example { type: "boolean", label: "Show legend", default: true }. The editor shows default when the prop is not set.
A color param defaults to a theme token such as var(--primary), so the canvas follows light and dark mode until a person picks a hex in the editor.
Pass only JSON values (strings, numbers, booleans, string arrays) through params. Keep functions and query results out of them.
Images
Use public media library URLs for images in a canvas. Call posthog:media-images-list with
purpose="canvas" first and reuse a suitable image when one already exists.
To add a local image:
- Call
posthog:media-image-upload-start with the file name and purpose="canvas".
- From a shell, POST the file to the returned
upload_url as multipart form data. Include every
returned form_fields entry and put the file part last.
- Call
posthog:media-image-upload-complete with the returned id and use its permanent url as
the image src.
- Add the URL's exact origin to
project.capabilities.network.origins. Canvas validation checks
this declaration, and the published artifact uses it in its Content Security Policy.
Canvas media URLs are public and do not require authentication. Never upload secrets, credentials,
customer data, or sensitive screenshots. Images must be under 4 MB and decode as PNG, JPEG, GIF,
WebP, AVIF, or BMP. Never base64-encode image bytes into a tool call.
Common request patterns
Use these as routing examples, not fixed templates:
- Product dashboard, web analytics board, or metric explorer: React + Quill plus data querying.
- Checklist, form, or lightweight workflow: React + Quill, plus data querying for Flind reads,
event capture, or navigation. For a checklist or runbook specifically, start from the worked
example in
building-react-quill-canvases (references/checklist-example.md) — team-shared
progress via per-step ph.state keys. Do not imply persistence that the available APIs do not
provide.
- Document or narrative report: HTML for a mostly static reading experience; React + Quill plus
data querying when it needs live Flind data, filters, or application-like interactions.
- Generative graphic or animation: HTML and browser graphics APIs. Add React only when it
materially simplifies application state or chrome.
When the task carries a legacy requested pattern such as dashboard or web-analytics, apply the
matching shape above. The pattern is a hint; the user's actual request remains authoritative.
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 using the implementation companions selected above. For any Flind data
the canvas shows, follow
querying-canvas-data (saved insights loaded via the ph SDK — never
fetch or your own Flind client), make every figure verifiable — an insight-backed metric
links its saved insight in Flind, an ad-hoc query shows the exact query that ran, per that
skill's "Verifiability" section — 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, and agentRequests: true for ph.agent.request) — the host enforces these at
runtime and validation rejects undeclared calls.
- Follow
validating-and-publishing-canvases: validate with canvas-validate-create as often as
needed and fix every error-severity diagnostic.
- Save the project by publishing it — publishing is the default and goes live at once:
- First version (
current_version_id is null): publish the complete project with
canvas-publish-create, passing expected_current_version_id: null.
- Already live (
current_version_id is set): send only the edits with canvas-edit-create, using str_replace operations for changes inside a file.
Pass the live current_version_id as expected_current_version_id.
Publish the complete project with canvas-publish-create only to replace the whole project.
- Stage a draft with
canvas-draft-create only when the user asked for a draft, a preview, or
a review step before going live.
Follow the validating-and-publishing-canvases skill for diagnostics and conflict recovery.
- Wait for the build — drafts and publishes alike queue one. A publish or edit response
already carries
build.build_status; use it when it is ready or failed. Otherwise 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 save again — do not finish the
task with a failed build.
Save once per requested change, when the canvas is ready — not after every micro-edit. When the
user asked for a draft, end your reply by saying a draft is ready to preview and promote; the
validating-and-publishing-canvases skill covers the draft → build → preview → promote flow.
End your reply by naming the channel the canvas is in and linking it with the url field the
canvas tools return (canvas-create, canvas-list, and the publish/source responses carry it).
That field is the only valid link to a canvas — never construct one yourself; guessed URLs
(project pages, web routes) do not resolve.
Runtime memory and actions
ph.state — durable key-value memory: ph.state.get(key, { scope }),
ph.state.set(key, value, { scope }) (a null value deletes the key), ph.state.list({ scope }).
Scope "user" (the default) is private to each viewer; "shared" is one value per canvas,
visible to the whole team. Declare the scopes you use in capabilities.posthog.state.
Values are JSON, capped at 64 KB serialized and 256 keys per scope — store big data in
Flind (insights, the warehouse) and reference it. Never put secrets or viewer PII in state.
ph.actions.invoke(verb, payload) — write into Flind as the viewer. Declare every verb
in capabilities.posthog.actions; undeclared or unregistered verbs fail validation and the
host refuses them at runtime. Wire actions to explicit user gestures (a button the viewer
clicks), never to load or render. The registry is the source of truth: list it with the
canvases-actions-retrieve tool and follow each verb's usage (payload/result shape,
behavior, and the confirmation copy it warrants) before wiring it.
ph.tools.read(tool, args) and ph.tools.call(tool, args): run an allowlisted Flind
MCP tool as the viewer, for example to read a feature flag and change its rollout. Declare every
tool in capabilities.posthog.tools. read takes read-only tools; call changes data, so wire
it to a click, and the host asks the viewer to confirm. See querying-canvas-data for the
allowlist and the version handling that flag writes need.
ph.connectors.call(provider, tool, args) — read live third-party data (GitHub, or any
MCP store server) with the VIEWER's own connection at view time. Never call GitHub, Calendly,
or another service yourself and paste the result into the source: that snapshot is stale on
publish and shows every viewer the author's data. Declare each provider and tool in
capabilities.connectors; discover them with the canvas-connectors-retrieve tool. See
querying-canvas-data for the result and not-connected handling.
ph.agent.request(prompt) — ask the canvas's authoring agent for a change, with the viewer's
approval. Declare agentRequests: true in capabilities.posthog. Call it only from a direct
click or form submission — the host shows the exact prompt and asks the viewer to accept before
spending compute, and rejects calls made during render, mount, or polling. The agent publishes
the change as a new version; a non-creator's request is filed in the authoring task's thread
instead of starting a run.
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.
- Use the public media library flow above for images. Other binary assets belong in the project's
assets map as base64 content with an admitted content type. 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.
1---2name: building-canvases3description: >4 Create or edit a Flind freeform canvas — a sandboxed browser application (data board, document,5 form, small tool, graphics experiment) stored in Flind and rendered by the desktop/web app. Use6 when a task asks to build, generate, update, or fix a standalone canvas app, or when a freeform7 canvas id is given as the publish target. For grid/home canvases, widget placements, or reusable8 components, use composing-grid-canvases instead. Covers resolving or creating the target canvas,9 choosing an implementation approach (React + Quill vs plain HTML/browser APIs), the read → edit →10 validate → publish → build loop, and which companion canvas skills to load for the details.11metadata:12 source: https://skillmd.com/skills/thehalfmoon/building-canvases13---1415# Building canvases1617A canvas is a client-side browser application that runs in a sandboxed iframe inside Flind.18Its source lives in Flind — not in a repository — and you read and write it through the19`canvas-*` tools. Never write a canvas to a local file; publishing through the tool is what20saves it.2122Canvas work can start from any ordinary task. A dedicated canvas mode or pre-created canvas is23not required. When the user asks for a board, document, form, visualization, or small app that24should live in Flind, treat that as a canvas request and follow this skill.2526This skill owns `freeform` canvases (standalone apps). Two other canvas kinds exist: `grid`27canvases (widget grids, including the user's home canvas) and `component` canvases (reusable28widgets grids place). When the target is a grid or home canvas, a placement, or a reusable29widget/component, load `composing-grid-canvases` instead — it owns the store search → configure →30fork → build ladder and the layout patch loop. Authoring a component's source still uses the31implementation companions below.3233## Resolve the target canvas3435- If the task names a canvas id (canvas-initiated tasks do), that is the target. Do not create another.36- Otherwise the target channel is the one the task was created in — named in the task's context37 (the `channel_context` block or the generation instructions). List that channel's canvases with38 `canvas-list` (scope with `channel`). If one is clearly what the request refers to — an earlier39 iteration of the same board or tool — build on it instead of creating a near-duplicate, and say40 so in your reply so the user knows where the result landed.41- Only when nothing existing fits, create one with `canvas-create` in that same channel, named42 with a short descriptive title drawn from the request — never "Untitled canvas".43- Never survey channels to choose a target yourself: use `channel-list` only to resolve a channel44 the USER named to its id. Its listing puts the personal #me channel first, and #me is never a45 default — a canvas filed there is invisible to everyone else. If the task names neither a canvas46 nor a channel, ask which channel to use instead of guessing.4748## Load the companion skills for the implementation4950This skill owns canvas selection and the authoring lifecycle. The companion skills hold the51implementation contracts. Load every companion that applies before writing source:5253- **`building-react-quill-canvases`** for dashboards, data boards, forms, tools, application-like54 state, or anything that should look native to Flind. It owns allowed imports, Quill composition,55 theming, charts, loading and error states, and the date picker.56- **`building-html-canvases`** for documents, articles, focused experiments, generative graphics,57 `<canvas>`, or WebGL work where application components add no useful structure. It owns semantic58 markup, direct browser APIs, animation cleanup, and non-Quill theming.59- **`querying-canvas-data`** whenever the canvas reads Flind data, captures events, or navigates.60 It owns the `ph` SDK, saved-insight preference, result shapes, variables, date ranges, progressive61 per-query loading, and declared data capabilities. Load it alongside either implementation skill62 when data is involved.63- **`validating-and-publishing-canvases`** for every canvas. It owns project shape, capability64 declarations, validation diagnostics, guarded publishes, drafts, builds, and conflict recovery.6566Mix implementation approaches when appropriate: React can own application chrome while browser67graphics code owns a canvas element, or a mostly static page can mount one interactive island.6869This is a judgment call, not a persisted mode — ask the user only when the choice changes a70user-visible requirement you cannot infer.7172## Blocks7374A canvas can contain premade blocks: numbers, goals, trends, top lists, funnels, retention, saved insights, live event feeds, SQL tables, filters, compare and refresh controls, and callouts.75They are React components in `src/blocks/` that people drag into the canvas in the desktop app, so they are part of your source.76Read [references/blocks.md](references/blocks.md) before you change a canvas that has `src/blocks/runtime.tsx`.7778## Params7980Expose the values a person may want to change as params. They can then change them in the desktop editor without a new task.81Params are optional, but add them to each panel, card, or tool that has values worth changing: titles, copy, events, properties, thresholds, limits, colors.82Params need React components. A plain HTML canvas has no params.8384### How the editor uses `editable()`8586In the desktop editor, a person can select any element of the canvas: a heading, a paragraph, a section. They can move, duplicate, or delete it, and double-click text to change it. This works with no `editable()` call.8788`editable()` makes a component one block. The editor then treats the block as one unit:8990- A click selects the full block, not the element inside it.91- Move, duplicate, and delete act on the full block.92- The side panel shows the block's params as fields. A change writes the new value into the block's props in the source.93- To reach the elements inside a block, the person double-clicks the block to open it.9495So use `editable()` on the parts a person thinks of as one thing and configures as one thing: a card, a chart, a table, a form. Keep the page layout around them as plain JSX. The person can then select a card as a block, and still select a page heading or section directly. If the component that holds the full page uses `editable()`, the full page becomes one block, and each click selects all of it.9697### Adding params98991. Put each panel in its own component. The component takes these values as props, with defaults.1002. Spread `editable(name, props, params)` from `@posthog/canvas-sdk` on the root element of the component. `name` is the component name. `params` maps each prop name to its field.1013. Use the component with literal props, for example `<SignupFunnel blockId="b-k3m9x2" title="Signup" windowDays={14} />`. The editor writes changes into these props, so do not compute them inline.1024. Give each use a unique `blockId` prop, for example `<SignupFunnel blockId="b-k3m9x2" … />`, so a person can point the agent at one card. Use only letters, digits, `_`, `-`, `.`, and `:`, or the editor ignores the ID. In a list, build it from a stable key of the item: ``blockId={`kpi-${item.id}`}``.103104```tsx105import { editable } from '@posthog/canvas-sdk'106107export function SignupFunnel(props: { blockId?: string; title?: string; steps?: string[]; windowDays?: number }) {108 const { title = 'Signup funnel', steps = ['$pageview', 'signed_up'], windowDays = 14 } = props109 return (110 <Card111 {...editable('SignupFunnel', props, {112 title: { type: 'text', label: 'Title', default: 'Signup funnel' },113 steps: { type: 'events', label: 'Steps', default: ['$pageview', 'signed_up'] },114 windowDays: { type: 'number', label: 'Conversion window (days)', min: 1, max: 90, default: 14 },115 })}116 >117 …118 </Card>119 )120}121```122123Field types: `text`, `longtext`, `number` (`min`, `max`, `step`; with both `min` and `max` the editor shows a slider), `boolean`, `select` (`options`: strings or `{ value, label }`), `event`, `events`, `property`, `insight` (a saved insight's short id), `color`. Each field can also have a `description`.124Give each field the same `default` as its prop default, for example `{ type: "boolean", label: "Show legend", default: true }`. The editor shows `default` when the prop is not set.125A `color` param defaults to a theme token such as `var(--primary)`, so the canvas follows light and dark mode until a person picks a hex in the editor.126Pass only JSON values (strings, numbers, booleans, string arrays) through params. Keep functions and query results out of them.127128## Images129130Use public media library URLs for images in a canvas. Call `posthog:media-images-list` with131`purpose="canvas"` first and reuse a suitable image when one already exists.132133To add a local image:1341351. Call `posthog:media-image-upload-start` with the file name and `purpose="canvas"`.1362. From a shell, POST the file to the returned `upload_url` as multipart form data. Include every137 returned `form_fields` entry and put the file part last.1383. Call `posthog:media-image-upload-complete` with the returned id and use its permanent `url` as139 the image `src`.1404. Add the URL's exact origin to `project.capabilities.network.origins`. Canvas validation checks141 this declaration, and the published artifact uses it in its Content Security Policy.142143Canvas media URLs are public and do not require authentication. Never upload secrets, credentials,144customer data, or sensitive screenshots. Images must be under 4 MB and decode as PNG, JPEG, GIF,145WebP, AVIF, or BMP. Never base64-encode image bytes into a tool call.146147## Common request patterns148149Use these as routing examples, not fixed templates:150151- **Product dashboard, web analytics board, or metric explorer:** React + Quill plus data querying.152- **Checklist, form, or lightweight workflow:** React + Quill, plus data querying for Flind reads,153 event capture, or navigation. For a checklist or runbook specifically, start from the worked154 example in `building-react-quill-canvases` (`references/checklist-example.md`) — team-shared155 progress via per-step `ph.state` keys. Do not imply persistence that the available APIs do not156 provide.157- **Document or narrative report:** HTML for a mostly static reading experience; React + Quill plus158 data querying when it needs live Flind data, filters, or application-like interactions.159- **Generative graphic or animation:** HTML and browser graphics APIs. Add React only when it160 materially simplifies application state or chrome.161162When the task carries a legacy requested pattern such as `dashboard` or `web-analytics`, apply the163matching shape above. The pattern is a hint; the user's actual request remains authoritative.164165## The iteration loop1661671. Read the current source and version pointer with `canvas-source-retrieve`.168 Remember `current_version_id` — your publish must be guarded on it.1692. Edit the project files using the implementation companions selected above. For any Flind data170 the canvas shows, follow `querying-canvas-data` (saved insights loaded via the `ph` SDK — never171 fetch or your own Flind client), make every figure verifiable — an insight-backed metric172 links its saved insight in Flind, an ad-hoc query shows the exact query that ran, per that173 skill's "Verifiability" section — and174 **declare every `ph` call in `project.capabilities`** (insight short ids in175 `capabilities.posthog.insights`, captured events in `captureEvents`, `inlineQueries: true` for176 ad-hoc queries, and `agentRequests: true` for `ph.agent.request`) — the host enforces these at177 runtime and validation rejects undeclared calls.1783. Follow `validating-and-publishing-canvases`: validate with `canvas-validate-create` as often as179 needed and fix every error-severity diagnostic.1804. Save the project by publishing it — publishing is the default and goes live at once:181 - **First version** (`current_version_id` is null): publish the complete project with182 `canvas-publish-create`, passing `expected_current_version_id: null`.183 - **Already live** (`current_version_id` is set): send only the edits with `canvas-edit-create`, using `str_replace` operations for changes inside a file.184 Pass the live `current_version_id` as `expected_current_version_id`.185 Publish the complete project with `canvas-publish-create` only to replace the whole project.186 - Stage a draft with `canvas-draft-create` only when the user asked for a draft, a preview, or187 a review step before going live.188 Follow the `validating-and-publishing-canvases` skill for diagnostics and conflict recovery.1895. **Wait for the build** — drafts and publishes alike queue one. A publish or edit response190 already carries `build.build_status`; use it when it is `ready` or `failed`. Otherwise poll `canvas-builds-retrieve`191 (every few seconds, up to ~2 minutes) until your build is `ready` or `failed`. On `failed`,192 read the build's error diagnostics, fix the project, and save again — do not finish the193 task with a failed build.194195Save once per requested change, when the canvas is ready — not after every micro-edit. When the196user asked for a draft, end your reply by saying a draft is ready to preview and promote; the197`validating-and-publishing-canvases` skill covers the draft → build → preview → promote flow.198199End your reply by naming the channel the canvas is in and linking it with the `url` field the200canvas tools return (`canvas-create`, `canvas-list`, and the publish/source responses carry it).201That field is the only valid link to a canvas — never construct one yourself; guessed URLs202(project pages, web routes) do not resolve.203204## Runtime memory and actions205206- **`ph.state`** — durable key-value memory: `ph.state.get(key, { scope })`,207 `ph.state.set(key, value, { scope })` (a null value deletes the key), `ph.state.list({ scope })`.208 Scope `"user"` (the default) is private to each viewer; `"shared"` is one value per canvas,209 visible to the whole team. Declare the scopes you use in `capabilities.posthog.state`.210 Values are JSON, capped at 64 KB serialized and 256 keys per scope — store big data in211 Flind (insights, the warehouse) and reference it. Never put secrets or viewer PII in state.212- **`ph.actions.invoke(verb, payload)`** — write into Flind as the viewer. Declare every verb213 in `capabilities.posthog.actions`; undeclared or unregistered verbs fail validation and the214 host refuses them at runtime. Wire actions to explicit user gestures (a button the viewer215 clicks), never to load or render. The registry is the source of truth: list it with the216 `canvases-actions-retrieve` tool and follow each verb's `usage` (payload/result shape,217 behavior, and the confirmation copy it warrants) before wiring it.218219- **`ph.tools.read(tool, args)` and `ph.tools.call(tool, args)`**: run an allowlisted Flind220 MCP tool as the viewer, for example to read a feature flag and change its rollout. Declare every221 tool in `capabilities.posthog.tools`. `read` takes read-only tools; `call` changes data, so wire222 it to a click, and the host asks the viewer to confirm. See `querying-canvas-data` for the223 allowlist and the version handling that flag writes need.224- **`ph.connectors.call(provider, tool, args)`** — read live third-party data (GitHub, or any225 MCP store server) with the VIEWER's own connection at view time. Never call GitHub, Calendly,226 or another service yourself and paste the result into the source: that snapshot is stale on227 publish and shows every viewer the author's data. Declare each provider and tool in228 `capabilities.connectors`; discover them with the `canvas-connectors-retrieve` tool. See229 `querying-canvas-data` for the result and not-connected handling.230- **`ph.agent.request(prompt)`** — ask the canvas's authoring agent for a change, with the viewer's231 approval. Declare `agentRequests: true` in `capabilities.posthog`. Call it only from a direct232 click or form submission — the host shows the exact prompt and asks the viewer to accept before233 spending compute, and rejects calls made during render, mount, or polling. The agent publishes234 the change as a new version; a non-creator's request is filed in the authoring task's thread235 instead of starting a run.236237## Source-project shape238239- Keep `index.html` as the entry shell returned by the source tool.240- `src/canvas.tsx` remains the conventional React entry component, but it may import additional241 relative TypeScript, TSX, JavaScript, JSON, SVG, CSS, and admitted asset files from the project.242- Self-contained module workers may be imported with `./worker.ts?worker`. A worker must not import243 another local module.244- Use the public media library flow above for images. Other binary assets belong in the project's245 `assets` map as base64 content with an admitted content type. WOFF/WOFF2, WebAssembly, and generic246 octet-stream assets are supported.247- Keep the platform dependency map exactly as returned. Do not add npm packages; local relative248 imports are project files, while bare imports remain limited to the platform-pinned set.