Canvas Templates

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.