canvas-templates

name

canvas-templates

description

How PostHog "canvas" dashboards work end-to-end — the two rendering tiers (json-render vs freeform React-in-iframe), the agent system prompts that steer each, and the RIGHT way to fetch PostHog data (typed query nodes through ph.query, not hand-rolled HogQL). Use when changing canvas templates, the freeform sandbox, the ph.* data shim, canvas data fetching, or the agent prompts that build dashboards / web-analytics boards.

Canvas templates & data

PostHog "canvases" are agent-built dashboards/apps. There are two rendering tiers and a strict data path. Get the tier and the data path right and most canvas work is straightforward; get them wrong and you ship correctness bugs.

The two tiers

A canvas's kind (set at create time, persisted in file meta) decides everything:

Tier	kind	What the agent writes	Renderer	Data path
json-render	"json-render"	JSONL patches against a component catalog	ViewRenderer (Quill component tree)	state.queries HogQL, re-run by dashboardsService on refresh
freeform / React	"freeform"	a single-file React app	sandboxed <iframe> (FreeformCanvas)	the ph.* shim → host → PostHog

Which template maps to which tier: REACT_TIER_TEMPLATE_IDS in packages/core/src/canvas/freeformSchemas.ts. Today dashboard, web-analytics, and the generic freeform template render React; everything else is json-render. Legacy canvases created before a template moved tiers keep their stored kind — there is no migration, so both renderers must keep working.

Key files:

• packages/core/src/canvas/canvasTemplates.ts — the agent system prompts + per-template rules. This is where you steer agent behavior. Two prompt families:
  • BASE_RULES + DASHBOARD_RULES / WEB_ANALYTICS_RULES → json-render (catalog-built).
  • FREEFORM_BASE + buildFreeformPrompt(...) → React tier. freeformSystemPromptFor(id) picks the prompt for a kind:"freeform" canvas by templateId.
• packages/core/src/canvas/canvasDataService.ts — host-side ph.query / ph.capture.
• packages/ui/src/features/canvas/freeform/ — the iframe: FreeformCanvas.tsx (postMessage broker), sandboxRuntime.ts (the iframe HTML + the ph shim), freeformDataBridge.ts (routes a ph.* call to the host tRPC).

Data: the RIGHT way (read this before touching queries)

Reuse PostHog's query runners; don't reinvent metrics in SQL.

The freeform app talks to PostHog ONLY through the injected ph global — the host holds the token, the iframe never sees it. The one call that matters:

const { columns, results } = await ph.query(arg)

arg is either a typed query node or an inline HogQL string:

• PREFERRED — a typed query node: ph.query({ kind: "TrendsQuery", series: [...], dateRange: {...} }). The product's OWN query runners compute it, so the numbers match the PostHog UI exactly (sessionization, unique users, breakdowns, math, bounce rate) and the node's dateRange handles the window. The agent gets the node by creating/ opening an insight via the PostHog MCP tools and copying its query node.
• ESCAPE HATCH — inline HogQL: ph.query("SELECT …"). Only for shapes a typed node can't express. The agent owns the SQL and its correctness.

Why this split exists: hand-rolled HogQL for standard metrics (especially web analytics — bounce rate, channel attribution, sessionization) subtly diverges from the product's numbers. Typed nodes are the same wheel the UI uses; don't re-cut it.

⚠️ The result SHAPE differs by kind — get it wrong and every value reads 0.

• HogQL → { columns: string[], results: rows[][] } (read results[row][col]).
• Typed node (TrendsQuery/etc.) → results is an array of series objects ({ data: number[], days: string[], count, aggregated_value, compare_label, … }), NOT rows. KPI total = results[0].count/.aggregated_value; series = results[0].data; the compareFilter previous period is a second series (match compare_label === "previous", don't assume index order). CanvasDataService.query passes typed-node results through untouched and only row-coerces HogQL — see the isTyped branch. The first build of this missed it and rendered all-zeros despite the query running fine.

The data path end-to-end

ph.query(arg)                                   iframe  (sandboxRuntime.ts shim)
  └─ postMessage "data-request"
       └─ FreeformCanvas route()                 ui      (FreeformCanvas.tsx)
            └─ handleFreeformDataRequest("query") ui      (freeformDataBridge.ts)
                 └─ tRPC canvasData.query         host    (canvas-data.router.ts)
                      └─ CanvasDataService.query   core    (canvasDataService.ts)
                           └─ runQuery(node)        core   (posthogApi.ts)
                                └─ POST /api/projects/<id>/query/
                                     { query: <node>, refresh: "blocking" }

• runQuery(authService, node, { refresh }) is the one place that POSTs to the query endpoint. runHogQLQuery(...) is a thin wrapper that boxes a string into { kind: "HogQLQuery", query }. Both live in posthogApi.ts.
• refresh: "blocking" = the cached avenue (serve a fresh cached result, else compute). Same cache insights use — so typed nodes are cached, not recomputed.
• canvasDataQueryInput (freeformSchemas.ts) accepts { query?, hogql?, params? } and refines that exactly one of query / hogql is present.

To add a new ph.* capability: add the method to the shim (sandboxRuntime.ts window.ph), route it in freeformDataBridge.ts, add a tRPC procedure (canvas-data.router.ts) backed by a CanvasDataService method. Never let the iframe hold a token — it posts a request; the host runs the authenticated call.

ph.run(insightShortId) is stubbed (freeformDataBridge.ts throws). It's the view/published tier's model: a shared canvas can't ship inline queries to anonymous viewers, so publish converts validated query nodes → saved insights + an allowlist and the canvas references them by id. Implement it there, not in edit.

Dates

The freeform app owns its date control (the toolbar picker is hidden for freeform — it drove json-render state.queries, see WebsiteLayout.tsx). The agent renders Quill's DateTimePicker and feeds the window into the typed node's dateRange ({ date_from, date_to }) — the runner handles timezone/bucketing/half-open.

DateTimePicker must be compact in the canvas. Without the compact prop it auto-detects layout via useMediaQuery('(min-width: 64rem)') against the iframe viewport — which is full-width, so it picks the wide dual-calendar layout and overflows the popover it's anchored in. The prompt forces compact. The inline-HogQL fallback must use half-open timestamp >= toDateTime(fromUnix) AND timestamp < toDateTime(toUnix) (integer unix = UTC), never now() / INTERVAL / inclusive <= to. These rules live in FREEFORM_DATE_CONTROL_RULES.

Styling (freeform sandbox)

The iframe loads Quill's compiled CSS + tokens AND the Tailwind Play CDN (sandboxRuntime.ts), with Preflight disabled (its unlayered form reset overrode Quill's @layer components styles). So in a freeform canvas: build from @posthog/quill components, Tailwind utilities work, and you do NOT restyle Quill components. Allowed imports are the FREEFORM_WHITELIST (freeformWhitelist.ts); the Quill version is QUILL_VERSION there (must match the CSS <link> URLs).

Editing the agent prompts

• Steer the React data templates by editing the rule arrays in canvasTemplates.ts (FREEFORM_QUILL_RULES, FREEFORM_DATE_CONTROL_RULES, FREEFORM_DASHBOARD_RULES, FREEFORM_WEB_ANALYTICS_RULES). Generic freeform stays rule-free ("anything goes").
• The agent can't WebFetch at runtime (denied tool) — prompt rules must be self-contained; URLs are knowledge pointers only.
• Prompt strings are plain TS array entries; biome lints the file. Avoid ${...} inside a normal string literal (biome flags it as a template placeholder).

Checks after any change

pnpm --filter @posthog/core typecheck && pnpm --filter @posthog/core test -- --run
pnpm --filter @posthog/ui typecheck
npx biome lint packages/core/src/canvas packages/ui/src/features/canvas

Then verify in the running app — most of this tier (sandbox styling, the data path, the date picker, refresh) is not covered by unit tests. Use the test-electron-app skill to drive a real canvas over CDP.