From 361bd117e174f18a6ec2747bf3f6fabdc066c5b4 Mon Sep 17 00:00:00 2001
From: Adam Leith <adamleithp@users.noreply.github.com>
Date: Fri, 26 Jun 2026 12:32:36 +0100
Subject: [PATCH 1/2] feat(canvas): scaffold-by-default freeform builds +
 Tailwind v4 JIT
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Seed freeform canvas generation with a known-good starter scaffold by
default (opt out in the generate bar): the agent edits a compiling app
instead of authoring boilerplate from scratch — faster, fewer first-render
errors. Threaded as a useStarter flag through the generate hook + prompt
builder; the scaffold wires the easy-to-get-wrong bits (date picker,
theme tokens, loading skeletons, typed-node result reading, refresh).

Swap the edit-mode sandbox Tailwind engine from the v3 Play CDN to the v4
browser JIT (Quill is authored for v4). v4's layered preflight, native
not-* variants, and @theme inline token mapping let us drop the
preflight-off hack, the not-disabled shim, the hand-rolled reset, and the
hand-mirrored color map. Pinned to 4.3.1; v3 kept behind a flag.

Tighten the authoring contract: Tailwind utilities over inline style;
token-only color with the status-token foreground convention
(text-success-foreground, not bare text-success); date picker rendered
bare with PopoverContent w-auto p-0 and no compact.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/core/src/canvas/canvasTemplates.ts   |  15 +-
 packages/core/src/canvas/freeformSchemas.ts   |   2 +-
 packages/core/src/canvas/freeformStarter.ts   | 186 ++++++++++++++++++
 packages/core/src/canvas/posthogApi.ts        |   2 +-
 .../canvas/freeform/FreeformGenerateBar.tsx   |  52 +++--
 .../canvas/freeform/sandboxRuntime.ts         | 163 ++++++++++-----
 .../ui/src/features/canvas/freeformPrompt.ts  |  16 +-
 .../canvas/hooks/useGenerateFreeformCanvas.ts |   3 +
 8 files changed, 369 insertions(+), 70 deletions(-)
 create mode 100644 packages/core/src/canvas/freeformStarter.ts

diff --git a/packages/core/src/canvas/canvasTemplates.ts b/packages/core/src/canvas/canvasTemplates.ts
index b7da100ee5..d75cfba72b 100644
--- a/packages/core/src/canvas/canvasTemplates.ts
+++ b/packages/core/src/canvas/canvasTemplates.ts
@@ -55,14 +55,18 @@ const FREEFORM_BASE = [
 const FREEFORM_STYLE = [
   "",
   "STYLE:",
-  "- You may use inline `style` objects, `@posthog/quill` components, or a `<style>` block in your JSX. Write real, specific copy — never lorem ipsum.",
+  "- STYLING — use Tailwind utility classes (the sandbox loads Tailwind) and `@posthog/quill` components for ALL styling. Do NOT reach for inline `style={{…}}` for anything a class can express (color, spacing, sizing, layout, borders, radius, typography) — agents over-use `style` and it bypasses the theme. Reserve `style` ONLY for a genuinely dynamic runtime value that no utility can name (e.g. a width/height computed at runtime). For a fixed size use an arbitrary-value utility instead (e.g. `h-[280px] w-full`), not `style`. A `<style>` block is fine for keyframes or complex selectors. Write real, specific copy — never lorem ipsum.",
   '- SPECIAL CHARACTERS: write Unicode glyphs (curly quotes “ ” ‘ ’, ellipsis …, middot ·, en/em dashes – —, arrows, emoji) as the LITERAL character directly in the source. Do NOT use `\\uXXXX` escape sequences in JSX text or attribute values — `\\u` escapes are only decoded inside JavaScript string/template literals, so in JSX text they render verbatim (e.g. `\\u201c` shows up as the text `u201c`). If you must use an escape, wrap it in an expression container: `{"\\u2026"}`.',
   "- Build ANYTHING the user asks: dashboards, tools, forms, reports, small apps. Keep it self-contained in the one file.",
   "",
   "THEME (light / dark) — the canvas renders in the user's current PostHog theme, and that can switch at runtime. The host puts a `.dark` class on the document root in dark mode (exactly like the main app), so your styles MUST adapt to both:",
   "- Prefer `@posthog/quill` components and the design tokens — they already flip between light and dark automatically, so you get correct theming for free.",
-  "- For any custom styling, derive colors from the Quill CSS variables — e.g. `var(--background)`, `var(--foreground)`, `var(--card)`, `var(--card-foreground)`, `var(--border)`, `var(--muted-foreground)`, `var(--primary)` — or the matching Tailwind token utilities (`bg-background`, `text-foreground`, `bg-card`, `border-border`, `text-muted-foreground`). These all track the theme.",
-  '- NEVER hardcode a light-only color (e.g. `#fff`, `#111`, `color: black`, `background: white`) — it looks broken in the other theme. If you must special-case dark mode, use the `dark:` Tailwind variant (e.g. `className="bg-white dark:bg-zinc-900"`), which is wired to the `.dark` class.',
+  "- COLOR ONLY from Quill's design-token Tailwind utilities — never an invented or hardcoded color. The sandbox maps these (each tracks light/dark automatically): surfaces `bg-background` `bg-card` `bg-muted` `bg-primary` `bg-success` `bg-warning` `bg-info` `bg-destructive`; neutral text/icons `text-foreground` `text-muted-foreground` `text-card-foreground`; readable status accents `text-success-foreground` `text-warning-foreground` `text-info-foreground` `text-destructive-foreground`; borders/rings `border-border` `ring-ring`; state fills `bg-fill-hover` `bg-fill-selected`.",
+  "- STATUS TOKENS (success / warning / info / destructive) INVERT the usual convention: the BARE token is a PALE BACKGROUND fill, and `-foreground` is the STRONG, READABLE color. So colored TEXT or ICONS ALWAYS use the `-foreground` utility — `text-success-foreground` for an up delta, `text-destructive-foreground` for a down delta. NEVER bare `text-success` / `text-destructive` for text: that is the pale fill and is nearly invisible (this is the #1 mistake). A filled pill/badge uses the pair `bg-success text-success-foreground` (fill + its readable content). Never `bg-*-foreground`.",
+  '- PRIMARY follows the NORMAL convention instead: `bg-primary` is the strong brand color with `text-primary-foreground` (white) on it; `text-primary` is the brand color used as text. (Prefer the Quill `Badge` component for deltas — `variant="success"` / `"destructive"` — so you don\'t hand-pick any of this.)',
+  "- DO NOT use `bg-secondary` / `text-secondary` / `bg-accent` / `bg-popover` — those tokens are NOT defined in the canvas and render transparent. Stick to the tokens listed above.",
+  "- Only drop to a CSS variable (`var(--primary)`, `var(--border)`, `var(--muted-foreground)`) where a className can't reach — i.e. a prop that takes a raw color string (recharts `stroke`/`fill`), never in `className` or `style` where a utility works.",
+  '- NEVER hardcode a light-only color (e.g. `#fff`, `#111`, `color: black`, `background: white`) — it looks broken in the other theme. If you must special-case dark mode, use the `dark:` Tailwind variant (e.g. `className="bg-card dark:bg-muted"`), which is wired to the `.dark` class.',
   '- recharts strokes/fills must use the token CSS variables too (e.g. `stroke="var(--primary)"`, grid/axis in `var(--border)` / `var(--muted-foreground)`) so charts adapt as well.',
   "",
   "Do NOT write files, edit code on disk, or run shell commands. Your entire app is the single fenced tsx block in your reply.",
@@ -114,8 +118,9 @@ const FREEFORM_QUILL_RULES = [
 // React templates; correctness rules mirror the json-render tier's window logic.
 const FREEFORM_DATE_CONTROL_RULES = [
   "DATE WINDOW — your app owns the date control. Render Quill's `DateTimePicker` (the real PostHog date picker) — NEVER a custom Select, a native `<input type=date>`, or a hand-rolled control.",
-  '- Wire it up exactly like this: `import { Button, DateTimePicker, Popover, PopoverContent, PopoverTrigger, quickRanges } from "@posthog/quill"`. Seed window state from a quick range: `const def = quickRanges.find((r) => r.name === "Last 30 days") ?? quickRanges[0]; const [win, setWin] = useState({ start: def.rangeSetter(new Date()), end: new Date(), range: def });`. Render a `Popover` whose `PopoverTrigger` is a Quill `Button` (label `{win.range.name}`), with `<DateTimePicker compact value={win} onApply={(v) => { setWin(v); setOpen(false); }} onCancel={() => setOpen(false)} />` inside `PopoverContent`. Do NOT import the `DateTimeValue` TYPE — the sandbox strips types at runtime; use the values only.',
-  "- ALWAYS pass the `compact` prop to `DateTimePicker`. Without it the picker auto-detects screen size via a media query against the iframe viewport (which is full-width), picks the WIDE dual-calendar layout, and overflows the popover. `compact` forces the single-calendar layout that fits a popover.",
+  '- Wire it up exactly like this: `import { Button, DateTimePicker, Popover, PopoverContent, PopoverTrigger, quickRanges } from "@posthog/quill"`. Seed window state from a quick range: `const def = quickRanges.find((r) => r.name === "Last 30 days") ?? quickRanges[0]; const [win, setWin] = useState({ start: def.rangeSetter(new Date()), end: new Date(), range: def });`. Render a `Popover` whose `PopoverTrigger` is a Quill `Button` (label `{win.range.name}`), with `<DateTimePicker value={win} onApply={(v) => { setWin(v); setOpen(false); }} onCancel={() => setOpen(false)} />` inside `<PopoverContent className="w-auto p-0">`. Do NOT import the `DateTimeValue` TYPE — the sandbox strips types at runtime; use the values only.',
+  "- Do NOT pass the `compact` prop and do NOT constrain the picker's width: `DateTimePicker` self-adjusts (it media-queries its own window and drops to the single-calendar layout in the narrow canvas pane). Forcing `compact` or a fixed width is unnecessary and fights its responsiveness.",
+  '- ALWAYS give `PopoverContent` exactly `className="w-auto p-0"` — its default fixed width + padding squeeze the self-sizing picker and clip the quick-range tabs. That is the ONLY className it may have; add NOTHING (no `className`, `style`, or width) to `DateTimePicker` or `PopoverTrigger`. The picker is fully styled and self-sizing — let it be. The ONLY props on `DateTimePicker` are `value` / `onApply` / `onCancel`.',
   "- Drive your data `useEffect` off `win` and re-run EVERY query when it changes.",
   "- PREFERRED — pass the window to `ph.loadInsight` as `dateRange`: `ph.loadInsight(shortId, { dateRange: { date_from: win.start.toISOString(), date_to: win.end.toISOString() } })`. The saved insight re-scopes to your window — you write NO time SQL. (A SAVED SQL insight may ignore this and use its own window; that's a reason to express metrics as insight query types, not SQL.)",
   "- If you fall back to an ad-hoc typed node, feed the window into its `dateRange` the same way: `dateRange: { date_from: win.start.toISOString(), date_to: win.end.toISOString() }`. The query runner handles timezone/bucketing/half-open — no time SQL.",
diff --git a/packages/core/src/canvas/freeformSchemas.ts b/packages/core/src/canvas/freeformSchemas.ts
index 422b5b555c..8f683bfa33 100644
--- a/packages/core/src/canvas/freeformSchemas.ts
+++ b/packages/core/src/canvas/freeformSchemas.ts
@@ -100,7 +100,7 @@ export type CanvasDataResult = z.infer<typeof canvasDataResultSchema>;
 export const canvasLoadInsightInput = z.object({
   shortId: z.string().min(1),
   dateRange: z
-    .object({ date_from: z.string(), date_to: z.string() })
+    .object({ date_from: z.string().nullish(), date_to: z.string().nullish() })
     .optional(),
 });
 export type CanvasLoadInsightInput = z.infer<typeof canvasLoadInsightInput>;
diff --git a/packages/core/src/canvas/freeformStarter.ts b/packages/core/src/canvas/freeformStarter.ts
new file mode 100644
index 0000000000..424ca5128e
--- /dev/null
+++ b/packages/core/src/canvas/freeformStarter.ts
@@ -0,0 +1,186 @@
+// A known-good STARTER scaffold for a freeform (React) canvas. Experimental:
+// instead of authoring the whole single-file app from scratch every time, the
+// generation path can seed this working baseline as the agent's starting point
+// (opt-in via the generate bar toggle). It already wires the pieces that are
+// easy to get wrong — the COMPACT date picker, theme-aware tokens, per-card
+// loading skeletons, and reading a TYPED-NODE result correctly — so the agent
+// edits a compiling app instead of re-deriving boilerplate.
+//
+// Stored as a string (like the prompt contracts) — it is injected into the
+// generation prompt, not compiled here. It imports ONLY whitelisted packages
+// (see freeformWhitelist) and uses the runtime `ph` global for data. The sample
+// metric is "all events" (math:total, event:null) so it renders on ANY project;
+// the agent replaces it with the user's real metrics.
+export const FREEFORM_STARTER_CODE = `import React, { useEffect, useState } from "react";
+import {
+  Button,
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  DateTimePicker,
+  Heading,
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+  quickRanges,
+  SkeletonText,
+} from "@posthog/quill";
+import { RefreshCw } from "lucide-react";
+import {
+  CartesianGrid,
+  Line,
+  LineChart,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from "recharts";
+
+// Starter scaffold. Replace the sample "total events" metric and the layout
+// with what the user asked for — but KEEP the wiring below (date picker, theme
+// tokens, skeletons, typed-node result reading), it is already correct.
+export default function Canvas() {
+  const def =
+    quickRanges.find((r) => r.name === "Last 30 days") ?? quickRanges[0];
+  const [win, setWin] = useState({
+    start: def.rangeSetter(new Date()),
+    end: new Date(),
+    range: def,
+  });
+  const [open, setOpen] = useState(false);
+
+  const [loading, setLoading] = useState(true);
+  const [total, setTotal] = useState(0);
+  const [series, setSeries] = useState([]);
+  // Refresh plumbing: bump this nonce to re-run the data effect on demand. The
+  // effect already re-runs when the date window changes; the Refresh button just
+  // forces a re-run with the same window.
+  const [nonce, setNonce] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    // PREFERRED data path: a TYPED query node, computed by PostHog's own runner
+    // so the numbers match the UI exactly. \`event: null\` = all events (works on
+    // any project). Swap in the real metric — ideally a SAVED insight loaded
+    // with \`ph.loadInsight(shortId, { dateRange })\`.
+    ph.query({
+      kind: "TrendsQuery",
+      series: [
+        { kind: "EventsNode", event: null, name: "All events", math: "total" },
+      ],
+      dateRange: {
+        date_from: win.start.toISOString(),
+        date_to: win.end.toISOString(),
+      },
+    })
+      .then((res) => {
+        if (cancelled) return;
+        // Typed-node result: \`results\` is an array of SERIES OBJECTS, not rows.
+        const s = res.results[0] ?? {};
+        setTotal(s.count ?? 0);
+        setSeries(
+          (s.days ?? []).map((day, i) => ({ day, value: s.data?.[i] ?? 0 })),
+        );
+        setLoading(false);
+      })
+      .catch(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [win, nonce]);
+
+  return (
+    <div className="flex flex-col gap-4 p-6">
+      <div className="flex items-center justify-between">
+        <Heading size="xl" className="mb-4">Canvas</Heading>
+        <div className="flex items-center gap-2">
+          <Popover open={open} onOpenChange={setOpen}>
+            <PopoverTrigger
+              render={<Button variant="outline">{win.range.name}</Button>}
+            />
+            {/* PopoverContent needs w-auto p-0 so its default fixed width +
+                padding don't squeeze the self-sizing picker (which clips the
+                quick-range tabs). No other styles on it or the picker. */}
+            <PopoverContent className="w-auto p-0">
+              <DateTimePicker
+                value={win}
+                onApply={(v) => {
+                  setWin(v);
+                  setOpen(false);
+                }}
+                onCancel={() => setOpen(false)}
+              />
+            </PopoverContent>
+          </Popover>
+          <Button
+            variant="outline"
+            disabled={loading}
+            onClick={() => setNonce((n) => n + 1)}
+          >
+            <RefreshCw size={14} className={loading ? "animate-spin" : undefined} />
+            Refresh
+          </Button>
+        </div>
+      </div>
+
+      <div className="grid gap-4 md:grid-cols-3">
+        <Card size="sm">
+          <CardHeader>
+            <CardTitle>Total events</CardTitle>
+          </CardHeader>
+          <CardContent>
+            {loading ? (
+              <SkeletonText lines={1} className="text-3xl" />
+            ) : (
+              <Heading size="2xl">{total.toLocaleString()}</Heading>
+            )}
+          </CardContent>
+        </Card>
+      </div>
+
+      <Card size="sm">
+        <CardHeader>
+          <CardTitle>Events over time</CardTitle>
+        </CardHeader>
+        <CardContent>
+          {loading ? (
+            <SkeletonText lines={6} />
+          ) : (
+            <div className="h-[280px] w-full">
+              <ResponsiveContainer>
+                <LineChart data={series}>
+                  <CartesianGrid
+                    stroke="var(--border)"
+                    strokeDasharray="3 3"
+                  />
+                  <XAxis
+                    dataKey="day"
+                    stroke="var(--muted-foreground)"
+                    tick={{ fontSize: 12 }}
+                  />
+                  <YAxis
+                    stroke="var(--muted-foreground)"
+                    tick={{ fontSize: 12 }}
+                  />
+                  <Tooltip />
+                  <Line
+                    type="monotone"
+                    dataKey="value"
+                    stroke="var(--primary)"
+                    dot={false}
+                    strokeWidth={2}
+                  />
+                </LineChart>
+              </ResponsiveContainer>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+`;
diff --git a/packages/core/src/canvas/posthogApi.ts b/packages/core/src/canvas/posthogApi.ts
index 00e9ab3721..36679408e5 100644
--- a/packages/core/src/canvas/posthogApi.ts
+++ b/packages/core/src/canvas/posthogApi.ts
@@ -110,7 +110,7 @@ export interface InsightFetchResult {
 export async function fetchInsightByShortId(
   authService: AuthService,
   shortId: string,
-  opts?: { dateRange?: { date_from: string; date_to: string } },
+  opts?: { dateRange?: { date_from?: string | null; date_to?: string | null } },
 ): Promise<InsightFetchResult> {
   const { apiHost } = await authService.getValidAccessToken();
   const projectId = authService.getState().currentProjectId;
diff --git a/packages/ui/src/features/canvas/freeform/FreeformGenerateBar.tsx b/packages/ui/src/features/canvas/freeform/FreeformGenerateBar.tsx
index 0a11a14351..c99424b23e 100644
--- a/packages/ui/src/features/canvas/freeform/FreeformGenerateBar.tsx
+++ b/packages/ui/src/features/canvas/freeform/FreeformGenerateBar.tsx
@@ -1,7 +1,7 @@
 import { useGenerateFreeformCanvas } from "@posthog/ui/features/canvas/hooks/useGenerateFreeformCanvas";
 import { PromptInput } from "@posthog/ui/features/message-editor/components/PromptInput";
 import type { EditorHandle } from "@posthog/ui/features/message-editor/types";
-import { forwardRef } from "react";
+import { forwardRef, useState } from "react";
 
 // Composer that kicks off freeform canvas generation as a dedicated task: the
 // user describes what they want and the agent builds + publishes the canvas. No
@@ -48,24 +48,50 @@ export const FreeformGenerateBar = forwardRef<
     templateId,
   });
 
+  // On a FIRST build we seed the agent with a known-good starter scaffold by
+  // default (faster, more consistent than authoring from scratch). Uncheck to
+  // opt out and have the agent build from a blank canvas. Only meaningful on an
+  // empty canvas, so the toggle is hidden in edit mode.
+  const isEdit = !!currentCode?.trim();
+  const [useStarter, setUseStarter] = useState(true);
+
   const run = async (text: string) => {
     const instruction = text.trim();
     if (!instruction) return;
-    const taskId = await generate({ instruction, currentCode });
+    const taskId = await generate({
+      instruction,
+      currentCode,
+      useStarter: !isEdit && useStarter,
+    });
     if (taskId) onStarted?.(taskId);
   };
 
   return (
-    <PromptInput
-      ref={ref}
-      sessionId={sessionId}
-      editorHeight="large"
-      disabled={isStarting}
-      isLoading={isStarting}
-      enableCommands
-      enableBashMode={false}
-      hideDefaultToolbar
-      onSubmit={(text) => void run(text)}
-    />
+    <div className="flex flex-col gap-1.5">
+      <PromptInput
+        ref={ref}
+        sessionId={sessionId}
+        editorHeight="large"
+        disabled={isStarting}
+        isLoading={isStarting}
+        enableCommands
+        enableBashMode={false}
+        hideDefaultToolbar
+        onSubmit={(text) => void run(text)}
+      />
+      {!isEdit && (
+        <label className="flex cursor-pointer select-none items-center gap-1.5 self-start px-1 text-muted-foreground text-xs">
+          <input
+            type="checkbox"
+            className="cursor-pointer"
+            checked={useStarter}
+            disabled={isStarting}
+            onChange={(e) => setUseStarter(e.target.checked)}
+          />
+          Start from scaffold (faster, more consistent — uncheck to build from
+          scratch)
+        </label>
+      )}
+    </div>
   );
 });
diff --git a/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts b/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts
index 0315f308c9..4010925f5d 100644
--- a/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts
+++ b/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts
@@ -21,48 +21,86 @@ import {
 //     and forbids third-party egress entirely.
 export type SandboxMode = "edit" | "view";
 
-export function buildSandboxDocument(
-  mode: SandboxMode,
-  // The PostHog host, when in-iframe analytics/replay is enabled. Opens CSP for
-  // posthog-js to load its recorder and POST events/replay to ingest.
-  analyticsApiHost?: string,
-): string {
-  const importMap = JSON.stringify(buildImportMap());
-  const csp = contentSecurityPolicy(mode, analyticsApiHost);
+// Which in-browser Tailwind engine the EDIT-mode sandbox runs. "v4" matches the
+// Quill version we ship (Quill is authored for Tailwind v4) and lets us drop the
+// v3 Play CDN's preflight-off hack, the `not-disabled` variant shim, the manual
+// `@layer base` reset, and the hand-mirrored color map — v4's layered preflight
+// and `@theme inline` token mapping cover all of it. "v3" keeps the legacy Play
+// CDN path as a one-line fallback while v4 is validated against real canvases.
+const TAILWIND_ENGINE: "v3" | "v4" = "v4";
 
-  // Quill components emit Tailwind utility classes (layout — `inline-flex`,
-  // `items-center` — AND token colors like `bg-card`, `text-muted-foreground`)
-  // ALONGSIDE their `.quill-*` BEM classes. The linked Quill stylesheets style
-  // the BEM half; the utilities are dead without Tailwind, so components mislay
-  // out. The sandbox has no build step, so in EDIT mode we load the Tailwind Play
-  // CDN (JIT-in-browser; a MutationObserver picks up classes as the app mounts)
-  // and map Quill's semantic color tokens to the CSS variables tokens.css defines.
-  // View/published mode forbids the CDN (locked egress) — that tier must self-host
-  // a compiled stylesheet (Phase 2).
-  const tailwind =
-    mode === "edit"
-      ? `<script src="https://cdn.tailwindcss.com"></script>
+// Tailwind v4 browser JIT. `@import "tailwindcss"` brings in v4's layered theme/
+// base(preflight)/components/utilities — so preflight sits in `@layer base`,
+// BELOW Quill's `@layer components` (primitives.css), and can't clobber Quill
+// the way v3's unlayered preflight did. `@theme inline` maps Quill's CSS-variable
+// tokens to v4 color keys so `bg-card`, `text-muted-foreground`, `bg-fill-hover`
+// etc. generate, referencing the vars tokens.css defines on :root/.dark. Only
+// DEFINED tokens are mapped (no secondary/accent/popover — those have no vars).
+// The version is PINNED (frozen, like freeformWhitelist) so every canvas renders
+// against a known Tailwind build and can't drift onto a new release silently.
+const TAILWIND_V4 = `<script type="module" src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4.3.1"></script>
+<style type="text/tailwindcss">
+@import "tailwindcss";
+/* Drive \`dark:\` off the \`.dark\` class the host toggles (not prefers-color-scheme),
+   so the canvas follows the user's PostHog theme even when it differs from the OS. */
+@custom-variant dark (&:where(.dark, .dark *));
+@theme inline {
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chrome: var(--chrome);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+  --color-fill-hover: var(--fill-hover);
+  --color-fill-selected: var(--fill-selected);
+  --color-fill-expanded: var(--fill-expanded);
+  --radius-lg: var(--radius);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-sm: calc(var(--radius) - 4px);
+}
+</style>`;
+
+// A LAYERED element reset for the LEGACY v3 path only. v3's Play CDN preflight is
+// unlayered (it clobbers Quill's `@layer components`), so we run it with preflight
+// off and ship this minimal reset in `@layer base` — pinned below `components` so
+// Quill keeps winning and bare HTML elements still get tamed. v4 doesn't need it
+// (its own preflight is correctly layered).
+const LEGACY_RESET = `<style>
+@layer base, components, utilities;
+@layer base {
+  h1, h2, h3, h4, h5, h6, p, figure, blockquote, dl, dd { margin: 0; }
+  h1, h2, h3, h4, h5, h6 { font-size: inherit; font-weight: inherit; }
+  ul, ol { margin: 0; padding: 0; list-style: none; }
+  a { color: inherit; text-decoration: inherit; }
+  img, svg, video, canvas { display: block; max-width: 100%; }
+  button, input, select, textarea { font: inherit; color: inherit; }
+  button { padding: 0; background: none; border: 0; cursor: pointer; }
+  table { border-collapse: collapse; }
+}
+</style>`;
+
+// Legacy Tailwind v3 Play CDN path (preflight off + hand-mirrored token map).
+// Retained as a fallback behind TAILWIND_ENGINE while v4 is validated.
+const TAILWIND_V3 = `<script src="https://cdn.tailwindcss.com"></script>
 <script>
   tailwind.config = {
-  // Preflight OFF: its UNLAYERED form reset (e.g. \`button{background-color:transparent}\`)
-  // beats Quill's component styles, which live in \`@layer components\` — unlayered always
-  // wins over layered. That stripped Quill buttons (e.g. the Select trigger) of their
-  // border/background while box-shadow-bordered Cards survived. Quill self-styles and we
-  // ship our own minimal reset, so Preflight isn't needed; utilities still generate.
-  // The FULL Quill color/fill token map (mirrors the @theme inline block in
-  // quill/tokens.css). Pure-utility components like DateTimePicker have NO BEM
-  // fallback in primitives.css — they rely entirely on these utilities (e.g. the
-  // calendar's \`bg-fill-hover\`, \`bg-fill-selected\`), so every token Quill maps
-  // must be here or the component renders half-styled.
   corePlugins: { preflight: false },
-  // Drive \`dark:\` utilities off the \`.dark\` class (which the host toggles via
-  // the init theme), NOT prefers-color-scheme — so the canvas follows the user's
-  // PostHog theme, matching the main app, even when it differs from the OS.
   darkMode: "class",
   plugins: [
-    // Quill authors for Tailwind v4; \`not-disabled:\` is a v4 variant the Play
-    // CDN (v3) lacks. The calendar uses \`not-disabled:hover:bg-fill-hover\`, so
-    // register it (composes with \`hover:\`) or those day-cell styles never generate.
     tailwind.plugin(({ addVariant }) => {
       addVariant("not-disabled", "&:not(:disabled)");
     }),
@@ -73,17 +111,12 @@ export function buildSandboxDocument(
       background: "var(--background)", foreground: "var(--foreground)",
       chrome: "var(--chrome)",
       primary: { DEFAULT: "var(--primary)", foreground: "var(--primary-foreground)" },
-      secondary: { DEFAULT: "var(--secondary)", foreground: "var(--secondary-foreground)" },
       destructive: { DEFAULT: "var(--destructive)", foreground: "var(--destructive-foreground)" },
       muted: { DEFAULT: "var(--muted)", foreground: "var(--muted-foreground)" },
-      accent: { DEFAULT: "var(--accent)", foreground: "var(--accent-foreground)" },
-      popover: { DEFAULT: "var(--popover)", foreground: "var(--popover-foreground)" },
       card: { DEFAULT: "var(--card)", foreground: "var(--card-foreground)" },
       success: { DEFAULT: "var(--success)", foreground: "var(--success-foreground)" },
       warning: { DEFAULT: "var(--warning)", foreground: "var(--warning-foreground)" },
       info: { DEFAULT: "var(--info)", foreground: "var(--info-foreground)" },
-      // Surface fills the calendar (and other stateful primitives) use for
-      // hover / selected / expanded backgrounds.
       fill: {
         hover: "var(--fill-hover)",
         selected: "var(--fill-selected)",
@@ -92,8 +125,38 @@ export function buildSandboxDocument(
     },
     borderRadius: { lg: "var(--radius)", md: "calc(var(--radius) - 2px)", sm: "calc(var(--radius) - 4px)" },
   } } };
-</script>`
+</script>`;
+
+export function buildSandboxDocument(
+  mode: SandboxMode,
+  // The PostHog host, when in-iframe analytics/replay is enabled. Opens CSP for
+  // posthog-js to load its recorder and POST events/replay to ingest.
+  analyticsApiHost?: string,
+): string {
+  const importMap = JSON.stringify(buildImportMap());
+  const csp = contentSecurityPolicy(mode, analyticsApiHost);
+
+  // Quill components emit Tailwind utility classes (layout — `inline-flex`,
+  // `items-center` — AND token colors like `bg-card`, `text-muted-foreground`)
+  // ALONGSIDE their `.quill-*` BEM classes. The linked Quill stylesheets style
+  // the BEM half; the utilities are dead without Tailwind, so the sandbox runs a
+  // JIT-in-browser Tailwind in EDIT mode (View/published mode forbids the CDN —
+  // that tier self-hosts a compiled stylesheet, Phase 2). Quill is authored for
+  // Tailwind v4, so we run the v4 browser engine: its preflight is properly
+  // `@layer base` (sorts BELOW Quill's `@layer components`, so it can't clobber
+  // them — no preflight-off hack, no hand-rolled reset), it has native `not-*`
+  // variants (no `not-disabled` shim), and `@theme inline` maps Quill's tokens
+  // straight to v4 color keys. The whole hand-mirrored color map + reset the v3
+  // Play CDN forced us into collapses to the token block below.
+  const tailwind =
+    mode === "edit"
+      ? TAILWIND_ENGINE === "v4"
+        ? TAILWIND_V4
+        : TAILWIND_V3
       : "";
+  // v4 preflight is the layered reset; only the legacy v3 path needs the manual
+  // `@layer base` reset (v3's Play CDN preflight is unlayered, so it's off).
+  const reset = mode === "edit" && TAILWIND_ENGINE === "v3" ? LEGACY_RESET : "";
 
   // The bootstrap module. It is static (no user input) so it can be inlined
   // safely. It waits for `init`, transpiles the canvas with Babel, runs it from
@@ -298,6 +361,7 @@ export function buildSandboxDocument(
 <meta http-equiv="Content-Security-Policy" content="${csp}" />
 <script type="importmap">${importMap}</script>
 ${tailwind}
+${reset}
 ${FREEFORM_QUILL_CSS_URLS.map(
   (href) => `<link rel="stylesheet" href="${href}" />`,
 ).join("\n")}
@@ -340,17 +404,18 @@ function contentSecurityPolicy(
     return [
       "default-src 'none'",
       // Inline bootstrap + esm.sh modules + the transpiled Blob module + the
-      // posthog-js recorder script + the Tailwind Play CDN (which JIT-compiles
-      // in-browser, so it needs 'unsafe-eval'). The CDN is edit-mode ONLY — view
-      // mode keeps egress locked and self-hosts styles instead.
-      `script-src 'unsafe-inline' 'unsafe-eval' blob: https://cdn.tailwindcss.com ${esm} ${ph}`,
+      // posthog-js recorder script + the in-browser Tailwind engine (v4 browser
+      // build from jsdelivr, or the legacy v3 Play CDN) — both JIT-compile, so
+      // 'unsafe-eval' is required. Edit-mode ONLY — view mode keeps egress locked
+      // and self-hosts styles instead.
+      `script-src 'unsafe-inline' 'unsafe-eval' blob: https://cdn.tailwindcss.com https://cdn.jsdelivr.net ${esm} ${ph}`,
       `style-src 'unsafe-inline' ${esm}`,
       `font-src data: ${esm}`,
       "img-src data: blob: https:",
       `worker-src blob:`,
-      // esm.sh sub-fetches; canvas DATA goes over postMessage (not connect), but
-      // posthog-js events/replay DO use connect to the PostHog hosts.
-      `connect-src ${esm} ${ph}`,
+      // esm.sh + jsdelivr sub-fetches; canvas DATA goes over postMessage (not
+      // connect), but posthog-js events/replay DO use connect to the PostHog hosts.
+      `connect-src ${esm} https://cdn.jsdelivr.net ${ph}`,
     ].join("; ");
   }
   // view / published: self-hosted, frozen. Only egress is PostHog analytics.
diff --git a/packages/ui/src/features/canvas/freeformPrompt.ts b/packages/ui/src/features/canvas/freeformPrompt.ts
index 08d300c431..32631fc0c7 100644
--- a/packages/ui/src/features/canvas/freeformPrompt.ts
+++ b/packages/ui/src/features/canvas/freeformPrompt.ts
@@ -1,4 +1,5 @@
 import { freeformSystemPromptFor } from "@posthog/core/canvas/canvasTemplates";
+import { FREEFORM_STARTER_CODE } from "@posthog/core/canvas/freeformStarter";
 
 // Builds the prompt for the task that generates a freeform (React) canvas. Like
 // CONTEXT.md generation, this runs as a normal repo-less agent task (no repo
@@ -17,6 +18,10 @@ export function buildFreeformGenerationPrompt(input: {
   instruction: string;
   // The current source, when editing an existing canvas. Omitted for a first build.
   currentCode?: string;
+  // Default on (opt out via the generate bar): seed a known-good starter
+  // scaffold as the agent's baseline on a FIRST build, so it edits a compiling
+  // app instead of authoring boilerplate from scratch. Ignored when editing.
+  useStarter?: boolean;
 }): string {
   const {
     dashboardId,
@@ -25,6 +30,7 @@ export function buildFreeformGenerationPrompt(input: {
     templateId,
     instruction,
     currentCode,
+    useStarter,
   } = input;
 
   const contract = freeformSystemPromptFor(templateId);
@@ -41,6 +47,14 @@ export function buildFreeformGenerationPrompt(input: {
     ? `\n[Current code] — the canvas as it stands now. Rewrite the WHOLE file with the change applied; do not output a partial file.\n\n\`\`\`tsx\n${currentCode}\n\`\`\`\n`
     : "";
 
+  // First-build only: hand the agent a working scaffold to build ON instead of
+  // authoring from zero. It already wires the easy-to-get-wrong bits (date
+  // picker, theme tokens, loading skeletons, typed-node result reading).
+  const starterBlock =
+    !isEdit && useStarter
+      ? `\n[Starter scaffold] — begin from this WORKING baseline instead of authoring from scratch. It already wires the things that are easy to get wrong: the date picker, theme-aware tokens, per-card loading skeletons, and reading a typed-node result correctly. KEEP that wiring; replace the sample "total events" metric and the layout with what the user asked for, and output the COMPLETE rewritten file.\n\n\`\`\`tsx\n${FREEFORM_STARTER_CODE}\n\`\`\`\n`
+      : "";
+
   // The standing authoring contract + publishing/data rules are the same
   // boilerplate on every canvas generation — the user never typed them. Wrap
   // them in a `<canvas_generation_instructions>` element so the conversation UI
@@ -48,7 +62,7 @@ export function buildFreeformGenerationPrompt(input: {
   // inline (see extractCanvasInstructions). Kept after the user's instruction so
   // the request leads, mirroring how channel CONTEXT.md is appended.
   const instructions = `${header}
-${currentBlock}
+${currentBlock}${starterBlock}
 Follow this authoring contract for the canvas (imports, the \`ph\` data shim, and
 style rules):
 
diff --git a/packages/ui/src/features/canvas/hooks/useGenerateFreeformCanvas.ts b/packages/ui/src/features/canvas/hooks/useGenerateFreeformCanvas.ts
index f01465a2e7..7391e40c81 100644
--- a/packages/ui/src/features/canvas/hooks/useGenerateFreeformCanvas.ts
+++ b/packages/ui/src/features/canvas/hooks/useGenerateFreeformCanvas.ts
@@ -53,6 +53,8 @@ export function useGenerateFreeformCanvas(args: {
     async (opts: {
       instruction: string;
       currentCode?: string;
+      // Default on (opt out in the bar): seed the starter scaffold on first build.
+      useStarter?: boolean;
     }): Promise<string | null> => {
       setIsStarting(true);
       try {
@@ -65,6 +67,7 @@ export function useGenerateFreeformCanvas(args: {
               templateId,
               instruction: opts.instruction,
               currentCode: opts.currentCode,
+              useStarter: opts.useStarter,
             }),
             taskDescription: `Generate canvas "${name}"`,
             // Unattended generation: run in auto mode so it doesn't stall on edit-approval prompts.

From 891932702f51dd4eed7863fbaf1b06d01d71f13d Mon Sep 17 00:00:00 2001
From: Adam Leith <adamleithp@users.noreply.github.com>
Date: Fri, 26 Jun 2026 12:46:27 +0100
Subject: [PATCH 2/2] fix(canvas): scope edit-mode CSP to the active Tailwind
 CDN; fix stale starter doc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address PR review:
- CSP now trusts only the ACTIVE engine's CDN (not both v3 + v4), and the v4
  build is path-scoped to cdn.jsdelivr.net/npm/@tailwindcss/ rather than the
  whole jsdelivr origin — narrows the sandbox's egress to what it fetches.
  Re-validated live: v4 still compiles, canvas renders styled, no CSP errors.
- Correct the freeformStarter.ts header (drop stale "COMPACT" / "opt-in";
  scaffold is on by default and the picker self-sizes without compact).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/core/src/canvas/freeformStarter.ts   | 14 ++++++------
 .../canvas/freeform/sandboxRuntime.ts         | 22 +++++++++++++------
 2 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/packages/core/src/canvas/freeformStarter.ts b/packages/core/src/canvas/freeformStarter.ts
index 424ca5128e..6570e1a5b2 100644
--- a/packages/core/src/canvas/freeformStarter.ts
+++ b/packages/core/src/canvas/freeformStarter.ts
@@ -1,10 +1,10 @@
-// A known-good STARTER scaffold for a freeform (React) canvas. Experimental:
-// instead of authoring the whole single-file app from scratch every time, the
-// generation path can seed this working baseline as the agent's starting point
-// (opt-in via the generate bar toggle). It already wires the pieces that are
-// easy to get wrong — the COMPACT date picker, theme-aware tokens, per-card
-// loading skeletons, and reading a TYPED-NODE result correctly — so the agent
-// edits a compiling app instead of re-deriving boilerplate.
+// A known-good STARTER scaffold for a freeform (React) canvas. Instead of
+// authoring the whole single-file app from scratch every time, the generation
+// path seeds this working baseline as the agent's starting point (on by default;
+// opt out via the generate bar toggle). It already wires the pieces that are
+// easy to get wrong — the date picker (self-sizing, no `compact`), theme-aware
+// tokens, per-card loading skeletons, and reading a TYPED-NODE result correctly
+// — so the agent edits a compiling app instead of re-deriving boilerplate.
 //
 // Stored as a string (like the prompt contracts) — it is injected into the
 // generation prompt, not compiled here. It imports ONLY whitelisted packages
diff --git a/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts b/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts
index 4010925f5d..8f7f6fee9b 100644
--- a/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts
+++ b/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts
@@ -401,21 +401,29 @@ function contentSecurityPolicy(
     : "";
 
   if (mode === "edit") {
+    // Only the ACTIVE Tailwind engine's CDN is trusted (not both), and the v4
+    // build is path-scoped to the @tailwindcss namespace on jsdelivr rather than
+    // the whole origin — both narrow the code-execution sandbox's egress to
+    // exactly what it fetches. v3's Play CDN loads from arbitrary sub-paths, so
+    // it stays origin-scoped (it's only the fallback, off by default).
+    const twCdn =
+      TAILWIND_ENGINE === "v4"
+        ? "https://cdn.jsdelivr.net/npm/@tailwindcss/"
+        : "https://cdn.tailwindcss.com";
     return [
       "default-src 'none'",
       // Inline bootstrap + esm.sh modules + the transpiled Blob module + the
-      // posthog-js recorder script + the in-browser Tailwind engine (v4 browser
-      // build from jsdelivr, or the legacy v3 Play CDN) — both JIT-compile, so
-      // 'unsafe-eval' is required. Edit-mode ONLY — view mode keeps egress locked
-      // and self-hosts styles instead.
-      `script-src 'unsafe-inline' 'unsafe-eval' blob: https://cdn.tailwindcss.com https://cdn.jsdelivr.net ${esm} ${ph}`,
+      // posthog-js recorder script + the in-browser Tailwind engine (JIT-compiles,
+      // so 'unsafe-eval' is required). Edit-mode ONLY — view mode keeps egress
+      // locked and self-hosts styles instead.
+      `script-src 'unsafe-inline' 'unsafe-eval' blob: ${twCdn} ${esm} ${ph}`,
       `style-src 'unsafe-inline' ${esm}`,
       `font-src data: ${esm}`,
       "img-src data: blob: https:",
       `worker-src blob:`,
-      // esm.sh + jsdelivr sub-fetches; canvas DATA goes over postMessage (not
+      // esm.sh + Tailwind CDN sub-fetches; canvas DATA goes over postMessage (not
       // connect), but posthog-js events/replay DO use connect to the PostHog hosts.
-      `connect-src ${esm} https://cdn.jsdelivr.net ${ph}`,
+      `connect-src ${esm} ${twCdn} ${ph}`,
     ].join("; ");
   }
   // view / published: self-hosted, frozen. Only egress is PostHog analytics.