From 39f2ac80bbbccfb2ac408c5c90bdeb944ed85599 Mon Sep 17 00:00:00 2001
From: Shy Alter <puemos@users.noreply.github.com>
Date: Wed, 22 Jul 2026 13:03:31 +0200
Subject: [PATCH] Add HTML document canvases with anchored teammate comments

A new "html" canvas template lets the agent generate standalone HTML
documents (reports, specs, one-pagers) alongside freeform React
canvases, published through the same desktop-file-system canvas flow.
Documents render in a null-origin sandboxed iframe with a locked-down
CSP and an injected annotation shim; teammates can comment by selecting
text, picking an element, or on the whole page, with numbered pins and
a side-panel thread view backed by PostHog's comments API.

Generated-By: PostHog Code
Task-Id: b6ef557f-b02a-45d6-9128-577e1fbad8b1
---
 .claude/skills/canvas-templates/SKILL.md      |   9 +
 .../src/renderer/desktop-contributions.ts     |   2 +
 apps/web/src/web-container.ts                 |   2 +
 packages/api-client/src/posthog-client.ts     |  61 ++
 .../core/src/canvas/canvasComments.module.ts  |  10 +
 .../core/src/canvas/canvasCommentsSchemas.ts  |  44 ++
 .../src/canvas/canvasCommentsService.test.ts  | 187 +++++
 .../core/src/canvas/canvasCommentsService.ts  | 135 ++++
 packages/core/src/canvas/canvasTemplates.ts   |  76 +-
 .../core/src/canvas/htmlCanvasSchemas.test.ts | 124 ++++
 packages/core/src/canvas/htmlCanvasSchemas.ts | 184 +++++
 .../components/WebsiteChannelArtifacts.tsx    |   3 +-
 .../components/WebsiteDashboardsIndex.tsx     |  40 +-
 .../canvas/components/canvasTemplateIcon.tsx  |   7 +-
 .../canvas/freeform/CanvasSidePanel.tsx       |  62 +-
 .../canvas/freeform/FreeformCanvasView.tsx    | 117 +++-
 .../canvas/freeform/FreeformGenerateBar.tsx   |   9 +-
 .../features/canvas/freeformPrompt.test.ts    |  36 +
 .../ui/src/features/canvas/freeformPrompt.ts  |  70 +-
 .../canvas/hooks/useCanvasComments.ts         |  90 +++
 .../canvas/html/CanvasCommentsPanel.tsx       | 305 ++++++++
 .../canvas/html/HtmlArtifactFrame.tsx         | 231 +++++++
 .../features/canvas/html/HtmlCanvasBody.tsx   | 226 ++++++
 .../canvas/html/annotationShim.test.ts        | 150 ++++
 .../features/canvas/html/annotationShim.ts    | 653 ++++++++++++++++++
 .../features/canvas/html/htmlSandbox.test.ts  |  66 ++
 .../src/features/canvas/html/htmlSandbox.ts   |  52 ++
 .../canvas/stores/canvasCommentsStore.ts      |  51 ++
 28 files changed, 2931 insertions(+), 71 deletions(-)
 create mode 100644 packages/core/src/canvas/canvasComments.module.ts
 create mode 100644 packages/core/src/canvas/canvasCommentsSchemas.ts
 create mode 100644 packages/core/src/canvas/canvasCommentsService.test.ts
 create mode 100644 packages/core/src/canvas/canvasCommentsService.ts
 create mode 100644 packages/core/src/canvas/htmlCanvasSchemas.test.ts
 create mode 100644 packages/core/src/canvas/htmlCanvasSchemas.ts
 create mode 100644 packages/ui/src/features/canvas/hooks/useCanvasComments.ts
 create mode 100644 packages/ui/src/features/canvas/html/CanvasCommentsPanel.tsx
 create mode 100644 packages/ui/src/features/canvas/html/HtmlArtifactFrame.tsx
 create mode 100644 packages/ui/src/features/canvas/html/HtmlCanvasBody.tsx
 create mode 100644 packages/ui/src/features/canvas/html/annotationShim.test.ts
 create mode 100644 packages/ui/src/features/canvas/html/annotationShim.ts
 create mode 100644 packages/ui/src/features/canvas/html/htmlSandbox.test.ts
 create mode 100644 packages/ui/src/features/canvas/html/htmlSandbox.ts
 create mode 100644 packages/ui/src/features/canvas/stores/canvasCommentsStore.ts

diff --git a/.claude/skills/canvas-templates/SKILL.md b/.claude/skills/canvas-templates/SKILL.md
index 9bc9490e74..52f9f15279 100644
--- a/.claude/skills/canvas-templates/SKILL.md
+++ b/.claude/skills/canvas-templates/SKILL.md
@@ -17,6 +17,15 @@ A canvas's `kind` (set at create time, persisted in file meta) decides everythin
 | --- | --- | --- | --- | --- |
 | **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 |
+| **HTML document** | templateId `"html"` | a complete standalone HTML page | sandboxed `<iframe>` (`HtmlArtifactFrame`, no warm pool) | none — static; the agent bakes MCP-queried values in at generation time |
+
+The HTML tier (`HTML_TEMPLATE_ID` / `isHtmlTemplate` in
+`packages/core/src/canvas/htmlCanvasSchemas.ts`) is the artifact tier for
+documents (reports, specs, one-pagers): no `ph` shim, a locked-down CSP
+(`packages/ui/src/features/canvas/html/htmlSandbox.ts` — no network egress),
+and an injected annotation shim (`annotationShim.ts`) that powers anchored
+teammate comments (text-quote / element / page anchors, stored on PostHog's
+comments API via `CanvasCommentsService`, scope `code_canvas`).
 
 Which template maps to which tier: `REACT_TIER_TEMPLATE_IDS` in
 `packages/core/src/canvas/freeformSchemas.ts`. Today `dashboard`, `web-analytics`,
diff --git a/apps/code/src/renderer/desktop-contributions.ts b/apps/code/src/renderer/desktop-contributions.ts
index c3565ea3eb..e690ebdd64 100644
--- a/apps/code/src/renderer/desktop-contributions.ts
+++ b/apps/code/src/renderer/desktop-contributions.ts
@@ -1,5 +1,6 @@
 import { agentChatCoreModule } from "@posthog/core/agent-chat/agentChat.module";
 import { autoresearchCoreModule } from "@posthog/core/autoresearch/autoresearch.module";
+import { canvasCommentsCoreModule } from "@posthog/core/canvas/canvasComments.module";
 import { taskThreadCoreModule } from "@posthog/core/canvas/taskThread.module";
 import { inboxCoreModule } from "@posthog/core/inbox/inbox.module";
 import { githubConnectModule } from "@posthog/core/integrations/githubConnect.module";
@@ -36,6 +37,7 @@ export function registerDesktopContributions(): void {
     authUiModule,
     autoresearchCoreModule,
     billingUiModule,
+    canvasCommentsCoreModule,
     taskThreadCoreModule,
     browserTabsUiModule,
     cloneUiModule,
diff --git a/apps/web/src/web-container.ts b/apps/web/src/web-container.ts
index b3ecf20d45..a8cef65ceb 100644
--- a/apps/web/src/web-container.ts
+++ b/apps/web/src/web-container.ts
@@ -26,6 +26,7 @@ import {
   type IAuthTokenCipher,
 } from "@posthog/core/auth/identifiers";
 import { canvasCoreModule } from "@posthog/core/canvas/canvas.module";
+import { canvasCommentsCoreModule } from "@posthog/core/canvas/canvasComments.module";
 import { taskThreadCoreModule } from "@posthog/core/canvas/taskThread.module";
 import type { CloudTaskService } from "@posthog/core/cloud-task/cloud-task";
 import { cloudTaskModule } from "@posthog/core/cloud-task/cloud-task.module";
@@ -468,6 +469,7 @@ container.bind(CLOUD_TASK_AUTH).toDynamicValue((ctx) => ({
 // API), so the web host binds them by loading the same core module desktop does;
 // the web host router forwards its canvas routers to these.
 container.load(canvasCoreModule);
+container.load(canvasCommentsCoreModule);
 container.load(taskThreadCoreModule);
 
 // SessionService is built from host-agnostic deps (host tRPC client + UI
diff --git a/packages/api-client/src/posthog-client.ts b/packages/api-client/src/posthog-client.ts
index a2fee35964..f8dae1ddfb 100644
--- a/packages/api-client/src/posthog-client.ts
+++ b/packages/api-client/src/posthog-client.ts
@@ -2666,6 +2666,67 @@ export class PostHogAPIClient {
     return (await response.json()) as TaskThreadMessage;
   }
 
+  // --- Comments (discussions) ----------------------------------------------
+  // PostHog's generic comments surface: a comment attaches to any resource via
+  // a free-form `scope` + `item_id` pair, carries an arbitrary JSON
+  // `item_context` (we store comment anchors there — see canvas comments in
+  // core), and threads via `source_comment`. DELETE is disabled server-side
+  // (405); deletion is a soft PATCH `deleted: true`.
+
+  async listComments(
+    scope: string,
+    itemId: string,
+  ): Promise<Schemas.Comment[]> {
+    const COMMENTS_MAX_PAGES = 20;
+    const teamId = await this.getTeamId();
+    const all: Schemas.Comment[] = [];
+    let cursor: string | undefined;
+    for (let i = 0; i < COMMENTS_MAX_PAGES; i++) {
+      const page = await this.api.get("/api/projects/{project_id}/comments/", {
+        path: { project_id: teamId.toString() },
+        query: { scope, item_id: itemId, ...(cursor ? { cursor } : {}) },
+      });
+      all.push(...page.results);
+      if (!page.next) return all;
+      // `next` is a full URL; the typed endpoint paginates by `cursor` param.
+      cursor = new URL(page.next).searchParams.get("cursor") ?? undefined;
+      if (!cursor) return all;
+    }
+    log.warn(
+      `listComments hit MAX_PAGES (${COMMENTS_MAX_PAGES}); returning partial results`,
+      { returned: all.length },
+    );
+    return all;
+  }
+
+  async createComment(input: {
+    content: string;
+    scope: string;
+    item_id: string;
+    item_context?: Record<string, unknown>;
+    source_comment?: string;
+  }): Promise<Schemas.Comment> {
+    const teamId = await this.getTeamId();
+    // The generated Comment type demands server-stamped fields (id, created_by,
+    // version, …) and types the JSON `item_context` as `null`, so the write
+    // shape needs the same cast createTask uses.
+    return await this.api.post("/api/projects/{project_id}/comments/", {
+      path: { project_id: teamId.toString() },
+      body: input as unknown as Schemas.Comment,
+    });
+  }
+
+  async patchComment(
+    id: string,
+    patch: { deleted?: boolean; content?: string },
+  ): Promise<Schemas.Comment> {
+    const teamId = await this.getTeamId();
+    return await this.api.patch("/api/projects/{project_id}/comments/{id}/", {
+      path: { project_id: teamId.toString(), id },
+      body: patch as Schemas.PatchedComment,
+    });
+  }
+
   // Everyone in the current organization — the pool of taggable teammates for
   // thread @-mentions. Membership churn is slow, so callers cache aggressively.
   async listOrganizationMembers(): Promise<OrganizationMemberBasic[]> {
diff --git a/packages/core/src/canvas/canvasComments.module.ts b/packages/core/src/canvas/canvasComments.module.ts
new file mode 100644
index 0000000000..ef3e0ac08b
--- /dev/null
+++ b/packages/core/src/canvas/canvasComments.module.ts
@@ -0,0 +1,10 @@
+import { ContainerModule } from "inversify";
+import {
+  CANVAS_COMMENTS_SERVICE,
+  CanvasCommentsService,
+} from "./canvasCommentsService";
+
+export const canvasCommentsCoreModule = new ContainerModule(({ bind }) => {
+  bind(CanvasCommentsService).toSelf().inSingletonScope();
+  bind(CANVAS_COMMENTS_SERVICE).toService(CanvasCommentsService);
+});
diff --git a/packages/core/src/canvas/canvasCommentsSchemas.ts b/packages/core/src/canvas/canvasCommentsSchemas.ts
new file mode 100644
index 0000000000..6b0dc9dc61
--- /dev/null
+++ b/packages/core/src/canvas/canvasCommentsSchemas.ts
@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { commentAnchorSchema } from "./htmlCanvasSchemas";
+
+// The comments scope for canvas artifacts on PostHog's generic comments API
+// (`scope` is a free-form discriminator there). One constant so every reader
+// and writer agrees; `item_id` is the canvas's file-system row id.
+export const CANVAS_COMMENTS_SCOPE = "code_canvas";
+
+// What we store in a comment's `item_context` JSON. Roots carry the anchor
+// (where in the document the comment points); replies carry no anchor — they
+// inherit their root's. `canvasVersionId` records which canvas version the
+// anchor was made against, for diagnostics and a future "view at that version".
+export const canvasCommentContextSchema = z.object({
+  version: z.literal(1),
+  anchor: commentAnchorSchema.optional(),
+  canvasVersionId: z.string().optional(),
+});
+export type CanvasCommentContext = z.infer<typeof canvasCommentContextSchema>;
+
+// A canvas comment as the app consumes it — parsed from the API row, with the
+// anchor already extracted from `item_context` (null = page-level, a reply, or
+// an unparseable/foreign context; the panel treats null as unanchored).
+export const canvasCommentSchema = z.object({
+  id: z.string(),
+  content: z.string(),
+  createdAt: z.number(),
+  createdBy: z.object({
+    uuid: z.string(),
+    name: z.string(),
+    email: z.string(),
+  }),
+  anchor: commentAnchorSchema.nullable(),
+  sourceCommentId: z.string().nullable(),
+});
+export type CanvasComment = z.infer<typeof canvasCommentSchema>;
+
+// A root comment with its replies. `index` is the 1-based pin number painted
+// in the document and shown beside the thread in the panel.
+export const canvasCommentThreadSchema = z.object({
+  root: canvasCommentSchema,
+  replies: z.array(canvasCommentSchema),
+  index: z.number().int(),
+});
+export type CanvasCommentThread = z.infer<typeof canvasCommentThreadSchema>;
diff --git a/packages/core/src/canvas/canvasCommentsService.test.ts b/packages/core/src/canvas/canvasCommentsService.test.ts
new file mode 100644
index 0000000000..5f3a8730b0
--- /dev/null
+++ b/packages/core/src/canvas/canvasCommentsService.test.ts
@@ -0,0 +1,187 @@
+import type { Schemas } from "@posthog/api-client/generated";
+import type { PostHogAPIClient } from "@posthog/api-client/posthog-client";
+import {
+  CanvasCommentsService,
+  groupThreads,
+  parseCanvasComment,
+} from "@posthog/core/canvas/canvasCommentsService";
+import type { CanvasComment } from "@posthog/core/canvas/canvasCommentsSchemas";
+import { describe, expect, it, vi } from "vitest";
+
+function apiComment(overrides: Partial<Schemas.Comment> = {}): Schemas.Comment {
+  return {
+    id: "c1",
+    created_by: {
+      id: 1,
+      uuid: "u-1",
+      first_name: "Ada",
+      last_name: "Lovelace",
+      email: "ada@example.com",
+      hedgehog_config: null,
+    } as Schemas.Comment["created_by"],
+    version: 0,
+    created_at: "2026-07-01T10:00:00Z",
+    content: "Looks off",
+    scope: "code_canvas",
+    item_id: "dash-1",
+    ...overrides,
+  };
+}
+
+describe("parseCanvasComment", () => {
+  it("maps an anchored root comment", () => {
+    const parsed = parseCanvasComment(
+      apiComment({
+        item_context: {
+          version: 1,
+          anchor: { type: "text", quote: "18%", prefix: "grew ", suffix: " q" },
+        } as unknown as Schemas.Comment["item_context"],
+      }),
+    );
+    expect(parsed).toMatchObject({
+      id: "c1",
+      content: "Looks off",
+      createdBy: {
+        uuid: "u-1",
+        name: "Ada Lovelace",
+        email: "ada@example.com",
+      },
+      anchor: { type: "text", quote: "18%", prefix: "grew ", suffix: " q" },
+      sourceCommentId: null,
+    });
+    expect(parsed?.createdAt).toBe(Date.parse("2026-07-01T10:00:00Z"));
+  });
+
+  it("drops deleted rows", () => {
+    expect(parseCanvasComment(apiComment({ deleted: true }))).toBeNull();
+  });
+
+  it("degrades an unparseable item_context to a null anchor", () => {
+    const parsed = parseCanvasComment(
+      apiComment({
+        item_context: {
+          version: 99,
+          anchor: { type: "wat" },
+        } as unknown as Schemas.Comment["item_context"],
+      }),
+    );
+    expect(parsed?.anchor).toBeNull();
+  });
+
+  it("falls back to the email when the name is empty", () => {
+    const parsed = parseCanvasComment(
+      apiComment({
+        created_by: {
+          id: 2,
+          uuid: "u-2",
+          first_name: "",
+          email: "no-name@example.com",
+          hedgehog_config: null,
+        } as Schemas.Comment["created_by"],
+      }),
+    );
+    expect(parsed?.createdBy.name).toBe("no-name@example.com");
+  });
+});
+
+describe("groupThreads", () => {
+  function comment(overrides: Partial<CanvasComment>): CanvasComment {
+    return {
+      id: "x",
+      content: "",
+      createdAt: 0,
+      createdBy: { uuid: "u", name: "U", email: "u@example.com" },
+      anchor: null,
+      sourceCommentId: null,
+      ...overrides,
+    };
+  }
+
+  it("groups replies under roots, oldest-first, with 1-based indexes", () => {
+    const threads = groupThreads([
+      comment({ id: "b", createdAt: 2 }),
+      comment({ id: "a", createdAt: 1 }),
+      comment({ id: "r2", createdAt: 4, sourceCommentId: "a" }),
+      comment({ id: "r1", createdAt: 3, sourceCommentId: "a" }),
+    ]);
+    expect(threads.map((t) => t.root.id)).toEqual(["a", "b"]);
+    expect(threads.map((t) => t.index)).toEqual([1, 2]);
+    expect(threads[0]?.replies.map((r) => r.id)).toEqual(["r1", "r2"]);
+    expect(threads[1]?.replies).toEqual([]);
+  });
+
+  it("promotes a reply whose root is missing to its own root", () => {
+    const threads = groupThreads([
+      comment({ id: "orphan", createdAt: 5, sourceCommentId: "gone" }),
+    ]);
+    expect(threads).toHaveLength(1);
+    expect(threads[0]?.root.id).toBe("orphan");
+  });
+});
+
+describe("CanvasCommentsService", () => {
+  it("lists, filters deleted, and threads comments", async () => {
+    const client = {
+      listComments: vi.fn().mockResolvedValue([
+        apiComment({ id: "root", created_at: "2026-07-01T10:00:00Z" }),
+        apiComment({
+          id: "reply",
+          created_at: "2026-07-01T11:00:00Z",
+          source_comment: "root",
+        }),
+        apiComment({ id: "zombie", deleted: true }),
+      ]),
+    } as unknown as PostHogAPIClient;
+    const threads = await new CanvasCommentsService().listThreads(
+      client,
+      "dash-1",
+    );
+    expect(client.listComments).toHaveBeenCalledWith("code_canvas", "dash-1");
+    expect(threads).toHaveLength(1);
+    expect(threads[0]?.root.id).toBe("root");
+    expect(threads[0]?.replies.map((r) => r.id)).toEqual(["reply"]);
+  });
+
+  it("creates roots with the anchor context and replies without one", async () => {
+    const createComment = vi.fn().mockResolvedValue(apiComment());
+    const patchComment = vi.fn().mockResolvedValue(apiComment());
+    const client = {
+      createComment,
+      patchComment,
+    } as unknown as PostHogAPIClient;
+    const service = new CanvasCommentsService();
+
+    await service.addComment(client, {
+      dashboardId: "dash-1",
+      content: "hm",
+      anchor: { type: "page" },
+      canvasVersionId: "v9",
+    });
+    expect(createComment).toHaveBeenCalledWith({
+      content: "hm",
+      scope: "code_canvas",
+      item_id: "dash-1",
+      item_context: {
+        version: 1,
+        anchor: { type: "page" },
+        canvasVersionId: "v9",
+      },
+    });
+
+    await service.addReply(client, {
+      dashboardId: "dash-1",
+      content: "agreed",
+      rootId: "root-1",
+    });
+    expect(createComment).toHaveBeenCalledWith({
+      content: "agreed",
+      scope: "code_canvas",
+      item_id: "dash-1",
+      item_context: { version: 1 },
+      source_comment: "root-1",
+    });
+
+    await service.remove(client, "c-9");
+    expect(patchComment).toHaveBeenCalledWith("c-9", { deleted: true });
+  });
+});
diff --git a/packages/core/src/canvas/canvasCommentsService.ts b/packages/core/src/canvas/canvasCommentsService.ts
new file mode 100644
index 0000000000..a527e4896c
--- /dev/null
+++ b/packages/core/src/canvas/canvasCommentsService.ts
@@ -0,0 +1,135 @@
+import type { Schemas } from "@posthog/api-client/generated";
+import type { PostHogAPIClient } from "@posthog/api-client/posthog-client";
+import { injectable } from "inversify";
+import {
+  CANVAS_COMMENTS_SCOPE,
+  type CanvasComment,
+  type CanvasCommentContext,
+  type CanvasCommentThread,
+  canvasCommentContextSchema,
+} from "./canvasCommentsSchemas";
+import type { CommentAnchor } from "./htmlCanvasSchemas";
+
+export const CANVAS_COMMENTS_SERVICE = Symbol.for(
+  "posthog.core.canvas.commentsService",
+);
+
+// Map an API comment row to the app shape. Deleted rows return null (soft
+// delete: the API keeps them, filtered here). A context that fails to parse —
+// a foreign writer, an older schema — degrades to `anchor: null` rather than
+// throwing, so one bad row can never take down the whole panel.
+export function parseCanvasComment(raw: Schemas.Comment): CanvasComment | null {
+  if (raw.deleted) return null;
+  const context = canvasCommentContextSchema.safeParse(raw.item_context);
+  const createdBy = raw.created_by;
+  const name =
+    [createdBy?.first_name, createdBy?.last_name]
+      .filter(Boolean)
+      .join(" ")
+      .trim() ||
+    createdBy?.email ||
+    "Unknown";
+  return {
+    id: raw.id,
+    content: raw.content ?? "",
+    createdAt: Date.parse(raw.created_at) || 0,
+    createdBy: {
+      uuid: createdBy?.uuid ?? "",
+      name,
+      email: createdBy?.email ?? "",
+    },
+    anchor: context.success ? (context.data.anchor ?? null) : null,
+    sourceCommentId: raw.source_comment ?? null,
+  };
+}
+
+// Group parsed comments into threads: roots oldest-first with 1-based pin
+// indexes, replies oldest-first under their root. A reply whose root is
+// missing (root hard-deleted / not returned) is promoted to its own root so
+// the content stays reachable.
+export function groupThreads(comments: CanvasComment[]): CanvasCommentThread[] {
+  const byCreated = [...comments].sort((a, b) => a.createdAt - b.createdAt);
+  const rootIds = new Set(
+    byCreated.filter((c) => !c.sourceCommentId).map((c) => c.id),
+  );
+  const roots: CanvasComment[] = [];
+  const repliesByRoot = new Map<string, CanvasComment[]>();
+  for (const comment of byCreated) {
+    const rootId = comment.sourceCommentId;
+    if (rootId && rootIds.has(rootId)) {
+      const replies = repliesByRoot.get(rootId) ?? [];
+      replies.push(comment);
+      repliesByRoot.set(rootId, replies);
+    } else {
+      roots.push(comment);
+    }
+  }
+  return roots.map((root, i) => ({
+    root,
+    replies: repliesByRoot.get(root.id) ?? [],
+    index: i + 1,
+  }));
+}
+
+// Comments on a canvas artifact, stored on PostHog's generic comments API
+// (scope CANVAS_COMMENTS_SCOPE, item_id = the canvas's file-system id, the
+// anchor riding in `item_context`). Client-as-parameter like TaskThreadService:
+// the renderer resolves the authenticated client and passes it per call.
+@injectable()
+export class CanvasCommentsService {
+  async listThreads(
+    client: PostHogAPIClient,
+    dashboardId: string,
+  ): Promise<CanvasCommentThread[]> {
+    const raw = await client.listComments(CANVAS_COMMENTS_SCOPE, dashboardId);
+    const parsed = raw
+      .map(parseCanvasComment)
+      .filter((c): c is CanvasComment => c !== null);
+    return groupThreads(parsed);
+  }
+
+  async addComment(
+    client: PostHogAPIClient,
+    input: {
+      dashboardId: string;
+      content: string;
+      anchor: CommentAnchor;
+      canvasVersionId?: string;
+    },
+  ): Promise<CanvasComment | null> {
+    const context: CanvasCommentContext = {
+      version: 1,
+      anchor: input.anchor,
+      ...(input.canvasVersionId
+        ? { canvasVersionId: input.canvasVersionId }
+        : {}),
+    };
+    const created = await client.createComment({
+      content: input.content,
+      scope: CANVAS_COMMENTS_SCOPE,
+      item_id: input.dashboardId,
+      item_context: context,
+    });
+    return parseCanvasComment(created);
+  }
+
+  async addReply(
+    client: PostHogAPIClient,
+    input: { dashboardId: string; content: string; rootId: string },
+  ): Promise<CanvasComment | null> {
+    const context: CanvasCommentContext = { version: 1 };
+    const created = await client.createComment({
+      content: input.content,
+      scope: CANVAS_COMMENTS_SCOPE,
+      item_id: input.dashboardId,
+      item_context: context,
+      source_comment: input.rootId,
+    });
+    return parseCanvasComment(created);
+  }
+
+  // Soft delete — the API disables DELETE (405); deletion is a PATCH.
+  async remove(client: PostHogAPIClient, commentId: string): Promise<void> {
+    await client.patchComment(commentId, { deleted: true });
+  }
+}
diff --git a/packages/core/src/canvas/canvasTemplates.ts b/packages/core/src/canvas/canvasTemplates.ts
index d75cfba72b..befcce6740 100644
--- a/packages/core/src/canvas/canvasTemplates.ts
+++ b/packages/core/src/canvas/canvasTemplates.ts
@@ -1,5 +1,6 @@
 import { FREEFORM_TEMPLATE_ID } from "./freeformSchemas";
 import { FREEFORM_WHITELIST } from "./freeformWhitelist";
+import { HTML_TEMPLATE_ID } from "./htmlCanvasSchemas";
 import type { CanvasSuggestion } from "./templateSchemas";
 
 export interface CanvasTemplate {
@@ -151,6 +152,44 @@ const FREEFORM_WEB_ANALYTICS_RULES = [
 
 const FREEFORM_SYSTEM_PROMPT = buildFreeformPrompt();
 
+// HTML-document canvas: the agent writes a complete, standalone HTML page (a
+// report, spec, one-pager, …) instead of a React app. It renders in the same
+// null-origin sandboxed iframe, but with a locked-down CSP and NO `ph` data
+// shim — the document is a static artifact teammates read and comment on
+// (anchored to exact text and elements), so structural stability matters.
+const HTML_BASE = [
+  "You are PostHog Canvas, an agent that writes a standalone HTML document (a report, spec, one-pager, runbook, …) for the user's team. The document renders in a sandboxed iframe where teammates read it and leave comments anchored to exact text and elements.",
+  "",
+  "OUTPUT FORMAT — every turn:",
+  "- Write a SHORT sentence of prose, then the COMPLETE document as ONE fenced code block tagged html (```html ... ```).",
+  "- FULL-FILE REWRITE: always output the entire document, even for a tiny change. Never output a partial file, a diff, or multiple code blocks.",
+  "- The document MUST be a full page: `<!doctype html>` through `</html>`, with `<head>` and `<body>`.",
+  "",
+  "SELF-CONTAINED — the sandbox's Content-Security-Policy blocks ALL network access, so everything must be inline:",
+  "- All CSS in `<style>` blocks; all JavaScript in inline `<script>` blocks.",
+  "- FORBIDDEN: external resources of any kind — no CDN `<script src>` or `<link href>`, no `fetch()` / XMLHttpRequest, no remote images, fonts, or iframes. They will be blocked and the page will look broken.",
+  "- Images: inline SVG or `data:` URIs only. Fonts: a system font stack (e.g. ui-sans-serif, system-ui).",
+  "",
+  "SANDBOX CONSTRAINTS — the iframe has a null origin:",
+  "- No cookies, localStorage, or sessionStorage; no `window.top` / `window.parent`; no navigation, external links that must open, or form submissions.",
+  "- The document scrolls itself. Self-contained interactive JS (tabs, sortable tables, toggles, print styling) is fine.",
+  "",
+  "DATA — this document is STATIC. There is no runtime data shim (`ph.*` does not exist here). If the document needs PostHog numbers, query them NOW via the PostHog MCP tools (mcp__posthog__*) and bake the values into the HTML. Never emit fetch()/XHR to load data at view time.",
+  "",
+  "COMMENT-FRIENDLY STRUCTURE — teammates anchor comments to exact text and elements, and anchors break when the underlying text or structure changes:",
+  "- Use semantic structure: real headings (h1–h4), sections, tables, lists.",
+  "- Give every major section and table a stable `id`, and KEEP existing ids when editing.",
+  "- When editing, change ONLY what was asked. Do not reword text you weren't asked to change — rewording orphans the comments anchored to it.",
+  "",
+  "STYLE:",
+  "- The document owns its entire design (there is no host theme inside the sandbox) — pick a clean, readable, self-consistent style with good typography, spacing, and a sensible max content width. Make it responsive.",
+  "- Write real, specific copy — never lorem ipsum.",
+  "",
+  "Do NOT write files, edit code on disk, or run shell commands. Your entire document is the single fenced html block in your reply.",
+];
+
+const HTML_SYSTEM_PROMPT = HTML_BASE.join("\n");
+
 // System prompts keyed by templateId for the canvas gen path; the generic
 // freeform sandbox is the fallback. The create-picker only offers "freeform"
 // today, but legacy canvases carrying the older "dashboard" / "web-analytics"
@@ -159,6 +198,7 @@ const FREEFORM_SYSTEM_PROMPTS: Record<string, string> = {
   [FREEFORM_TEMPLATE_ID]: FREEFORM_SYSTEM_PROMPT,
   dashboard: buildFreeformPrompt(FREEFORM_DASHBOARD_RULES),
   "web-analytics": buildFreeformPrompt(FREEFORM_WEB_ANALYTICS_RULES),
+  [HTML_TEMPLATE_ID]: HTML_SYSTEM_PROMPT,
 };
 
 // The React-tier prompt for a templateId, falling back to the generic sandbox.
@@ -197,8 +237,38 @@ const FREEFORM_TEMPLATE: CanvasTemplate = {
   systemPrompt: FREEFORM_SYSTEM_PROMPT,
 };
 
-/** Built-in templates offered by the create-picker. Only the freeform (React)
- * template exists today; more can be appended later. */
-export const BUILT_IN_TEMPLATES: CanvasTemplate[] = [FREEFORM_TEMPLATE];
+const HTML_SUGGESTIONS: CanvasSuggestion[] = [
+  {
+    label: "Quarterly report",
+    prompt:
+      "Write a one-page quarterly product report: a headline summary, a table of key metrics from our PostHog data, and a short outlook section.",
+  },
+  {
+    label: "Launch one-pager",
+    prompt:
+      "Write a launch one-pager for an upcoming feature: the problem, the solution, rollout plan, and success metrics.",
+  },
+  {
+    label: "Runbook",
+    prompt:
+      "Write an incident runbook: severity levels, escalation steps, and a checklist table for first responders.",
+  },
+];
+
+const HTML_TEMPLATE: CanvasTemplate = {
+  id: HTML_TEMPLATE_ID,
+  name: "Document (HTML)",
+  description:
+    "A standalone HTML page — reports, specs, one-pagers. Teammates can comment on exact text and elements.",
+  builtIn: true,
+  suggestions: HTML_SUGGESTIONS,
+  systemPrompt: HTML_SYSTEM_PROMPT,
+};
+
+/** Built-in templates offered by the create-picker. */
+export const BUILT_IN_TEMPLATES: CanvasTemplate[] = [
+  FREEFORM_TEMPLATE,
+  HTML_TEMPLATE,
+];
 
 export const DEFAULT_TEMPLATE_ID = FREEFORM_TEMPLATE_ID;
diff --git a/packages/core/src/canvas/htmlCanvasSchemas.test.ts b/packages/core/src/canvas/htmlCanvasSchemas.test.ts
new file mode 100644
index 0000000000..fe6475910c
--- /dev/null
+++ b/packages/core/src/canvas/htmlCanvasSchemas.test.ts
@@ -0,0 +1,124 @@
+import {
+  HTML_CANVAS_MESSAGE_CHANNEL,
+  commentAnchorSchema,
+  hostToHtmlCanvasMessageSchema,
+  htmlCanvasToHostMessageSchema,
+  isHtmlTemplate,
+} from "@posthog/core/canvas/htmlCanvasSchemas";
+import { describe, expect, it } from "vitest";
+
+const channel = HTML_CANVAS_MESSAGE_CHANNEL;
+const rect = { top: 10, left: 20, width: 100, height: 40 };
+
+describe("isHtmlTemplate", () => {
+  it.each([
+    ["html", true],
+    ["freeform", false],
+    ["dashboard", false],
+    [undefined, false],
+  ])("templateId %s -> %s", (id, expected) => {
+    expect(isHtmlTemplate(id as string | undefined)).toBe(expected);
+  });
+});
+
+describe("commentAnchorSchema", () => {
+  it("parses each anchor kind and defaults text context to empty strings", () => {
+    const text = commentAnchorSchema.parse({ type: "text", quote: "revenue" });
+    expect(text).toEqual({
+      type: "text",
+      quote: "revenue",
+      prefix: "",
+      suffix: "",
+    });
+    expect(
+      commentAnchorSchema.parse({ type: "element", selector: "#pricing" }),
+    ).toEqual({ type: "element", selector: "#pricing", label: "" });
+    expect(commentAnchorSchema.parse({ type: "page" })).toEqual({
+      type: "page",
+    });
+  });
+
+  it("rejects unknown kinds and empty required fields", () => {
+    expect(commentAnchorSchema.safeParse({ type: "line" }).success).toBe(false);
+    expect(
+      commentAnchorSchema.safeParse({ type: "text", quote: "" }).success,
+    ).toBe(false);
+    expect(
+      commentAnchorSchema.safeParse({ type: "element", selector: "" }).success,
+    ).toBe(false);
+  });
+});
+
+describe("host <-> shim protocol", () => {
+  it("round-trips host -> shim frames", () => {
+    const frames = [
+      {
+        channel,
+        type: "set-annotations",
+        annotations: [
+          { id: "c1", index: 1, anchor: { type: "page" } },
+          {
+            id: "c2",
+            index: 2,
+            anchor: { type: "text", quote: "q", prefix: "", suffix: "" },
+          },
+        ],
+      },
+      { channel, type: "set-pick-mode", active: true },
+      { channel, type: "set-active", id: "c1", scroll: true },
+      { channel, type: "set-active", id: null, scroll: false },
+      { channel, type: "clear-draft" },
+    ];
+    for (const frame of frames) {
+      expect(hostToHtmlCanvasMessageSchema.parse(frame)).toEqual(frame);
+    }
+  });
+
+  it("round-trips shim -> host frames", () => {
+    const frames = [
+      { channel, type: "ready" },
+      {
+        channel,
+        type: "selection",
+        anchor: { type: "text", quote: "q", prefix: "a", suffix: "b" },
+        rect,
+      },
+      { channel, type: "selection-cleared" },
+      {
+        channel,
+        type: "element-picked",
+        anchor: { type: "element", selector: "#x", label: "div" },
+        rect,
+      },
+      {
+        channel,
+        type: "annotations-resolved",
+        results: [
+          { id: "c1", resolved: true, rect },
+          { id: "c2", resolved: false },
+        ],
+      },
+      { channel, type: "marker-clicked", id: "c1", rect },
+      { channel, type: "error", message: "boom" },
+    ];
+    for (const frame of frames) {
+      expect(htmlCanvasToHostMessageSchema.parse(frame)).toEqual(frame);
+    }
+  });
+
+  it("rejects frames missing the channel stamp or with unknown types", () => {
+    expect(
+      htmlCanvasToHostMessageSchema.safeParse({ type: "ready" }).success,
+    ).toBe(false);
+    expect(
+      htmlCanvasToHostMessageSchema.safeParse({
+        channel: "posthog-canvas",
+        type: "ready",
+      }).success,
+    ).toBe(false);
+    expect(
+      hostToHtmlCanvasMessageSchema.safeParse({ channel, type: "init" })
+        .success,
+    ).toBe(false);
+  });
+});
diff --git a/packages/core/src/canvas/htmlCanvasSchemas.ts b/packages/core/src/canvas/htmlCanvasSchemas.ts
new file mode 100644
index 0000000000..728f4e9225
--- /dev/null
+++ b/packages/core/src/canvas/htmlCanvasSchemas.ts
@@ -0,0 +1,184 @@
+import { z } from "zod";
+
+// The template id for HTML-document canvases. Stored on a canvas's meta like
+// the freeform id, so the generation path can resolve the right system prompt
+// and the renderer can pick the HTML frame instead of the React sandbox.
+export const HTML_TEMPLATE_ID = "html";
+
+// Whether a canvas templateId renders as a raw HTML document (vs freeform React).
+export function isHtmlTemplate(id: string | undefined): boolean {
+  return id === HTML_TEMPLATE_ID;
+}
+
+// ---------------------------------------------------------------------------
+// Host <-> annotation-shim postMessage protocol. An HTML canvas renders in a
+// null-origin sandboxed iframe (like freeform), with a small annotation shim
+// script injected into the artifact document. The shim owns everything that
+// must happen inside the iframe's DOM — text selection, element picking,
+// painting highlights/pins — and the host owns comment state and persistence.
+// Structured-clone messages, Zod-validated on both ends, are the only channel.
+//
+// Deliberately absent vs the freeform protocol: no `init`/`code` frame (the
+// artifact IS the srcDoc), no `data-request` (no `ph` shim — the document is
+// static), and no `set-theme` (the artifact owns its own styling).
+// ---------------------------------------------------------------------------
+
+// Stamped on every frame so pages hosting multiple iframes (or other
+// postMessage traffic) can route unambiguously. Distinct from the freeform
+// canvas stamp so the two protocols can never cross wires.
+const HTML_CANVAS_CHANNEL = "posthog-html-canvas" as const;
+export const HTML_CANVAS_MESSAGE_CHANNEL = HTML_CANVAS_CHANNEL;
+
+// A rectangle in the iframe's viewport coordinates. The host iframe fills its
+// wrapper, so these double as wrapper-relative coordinates for positioning
+// composers/popovers without any offset math.
+export const htmlCanvasRectSchema = z.object({
+  top: z.number(),
+  left: z.number(),
+  width: z.number(),
+  height: z.number(),
+});
+export type HtmlCanvasRect = z.infer<typeof htmlCanvasRectSchema>;
+
+// ---------------------------------------------------------------------------
+// Comment anchors — how a comment points back into the document. These are
+// BOTH the wire shape (shim <-> host) and the stored contract (they ride in
+// the PostHog comment's `item_context` JSON, see canvasCommentsSchemas.ts).
+// ---------------------------------------------------------------------------
+
+// A W3C-style text-quote selector: the selected text plus ~32 normalized chars
+// of context on each side to disambiguate repeated quotes. Resolved by
+// searching the document's normalized text — robust to the quote MOVING in the
+// document, orphaned when the text itself is reworded.
+export const textQuoteAnchorSchema = z.object({
+  type: z.literal("text"),
+  quote: z.string().min(1),
+  prefix: z.string().default(""),
+  suffix: z.string().default(""),
+});
+export type TextQuoteAnchor = z.infer<typeof textQuoteAnchorSchema>;
+
+// An element anchor: a CSS selector path ("#id" shortcut when the element has
+// a unique id, else a tag:nth-of-type path) plus a human-readable label so the
+// panel can describe the target even when the selector no longer resolves.
+export const elementAnchorSchema = z.object({
+  type: z.literal("element"),
+  selector: z.string().min(1),
+  label: z.string().default(""),
+});
+export type ElementAnchor = z.infer<typeof elementAnchorSchema>;
+
+// A page-level comment — attached to the document as a whole, nothing to paint.
+export const pageAnchorSchema = z.object({ type: z.literal("page") });
+
+export const commentAnchorSchema = z.discriminatedUnion("type", [
+  textQuoteAnchorSchema,
+  elementAnchorSchema,
+  pageAnchorSchema,
+]);
+export type CommentAnchor = z.infer<typeof commentAnchorSchema>;
+
+// One annotation the host wants painted: a root comment's id, its 1-based pin
+// number (the panel shows the same number), and where it anchors.
+export const htmlCanvasAnnotationSchema = z.object({
+  id: z.string(),
+  index: z.number().int(),
+  anchor: commentAnchorSchema,
+});
+export type HtmlCanvasAnnotation = z.infer<typeof htmlCanvasAnnotationSchema>;
+
+// host -> shim
+export const hostToHtmlCanvasMessageSchema = z.discriminatedUnion("type", [
+  // Idempotent full replace of everything to paint (highlights + numbered
+  // pins). Sent after `ready` and again whenever the comment set changes.
+  z.object({
+    channel: z.literal(HTML_CANVAS_CHANNEL),
+    type: z.literal("set-annotations"),
+    annotations: z.array(htmlCanvasAnnotationSchema),
+  }),
+  // Toggle element-pick mode (hover outline + click-to-anchor). Text selection
+  // is always live and needs no mode.
+  z.object({
+    channel: z.literal(HTML_CANVAS_CHANNEL),
+    type: z.literal("set-pick-mode"),
+    active: z.boolean(),
+  }),
+  // Emphasize one annotation (e.g. the panel row was clicked). `scroll` also
+  // scrolls its anchor into view. `id: null` clears the emphasis.
+  z.object({
+    channel: z.literal(HTML_CANVAS_CHANNEL),
+    type: z.literal("set-active"),
+    id: z.string().nullable(),
+    scroll: z.boolean(),
+  }),
+  // Drop the pending draft highlight (the composer was submitted or dismissed).
+  z.object({
+    channel: z.literal(HTML_CANVAS_CHANNEL),
+    type: z.literal("clear-draft"),
+  }),
+]);
+export type HostToHtmlCanvasMessage = z.infer<
+  typeof hostToHtmlCanvasMessageSchema
+>;
+
+// shim -> host
+export const htmlCanvasToHostMessageSchema = z.discriminatedUnion("type", [
+  // Shim installed and the DOM above it is parsed; the host may now push
+  // annotations and mode state.
+  z.object({
+    channel: z.literal(HTML_CANVAS_CHANNEL),
+    type: z.literal("ready"),
+  }),
+  // A non-empty text selection settled (debounced). The host shows the
+  // floating comment affordance at `rect`.
+  z.object({
+    channel: z.literal(HTML_CANVAS_CHANNEL),
+    type: z.literal("selection"),
+    anchor: textQuoteAnchorSchema,
+    rect: htmlCanvasRectSchema,
+  }),
+  // The selection collapsed/cleared without becoming a draft.
+  z.object({
+    channel: z.literal(HTML_CANVAS_CHANNEL),
+    type: z.literal("selection-cleared"),
+  }),
+  // Pick mode: the user clicked an element. The shim freezes a draft outline
+  // on it; the host opens the composer and later confirms exit via
+  // `set-pick-mode { active: false }`.
+  z.object({
+    channel: z.literal(HTML_CANVAS_CHANNEL),
+    type: z.literal("element-picked"),
+    anchor: elementAnchorSchema,
+    rect: htmlCanvasRectSchema,
+  }),
+  // After each set-annotations application (and each repaint on resize or DOM
+  // mutation): which anchors resolved and where. Unresolved anchors render as
+  // "orphaned" in the panel instead of painting anything.
+  z.object({
+    channel: z.literal(HTML_CANVAS_CHANNEL),
+    type: z.literal("annotations-resolved"),
+    results: z.array(
+      z.object({
+        id: z.string(),
+        resolved: z.boolean(),
+        rect: htmlCanvasRectSchema.optional(),
+      }),
+    ),
+  }),
+  // The user clicked a pin or highlight — the host opens that thread.
+  z.object({
+    channel: z.literal(HTML_CANVAS_CHANNEL),
+    type: z.literal("marker-clicked"),
+    id: z.string(),
+    rect: htmlCanvasRectSchema.optional(),
+  }),
+  // A shim-internal failure, surfaced for logging; never blocks the artifact.
+  z.object({
+    channel: z.literal(HTML_CANVAS_CHANNEL),
+    type: z.literal("error"),
+    message: z.string(),
+  }),
+]);
+export type HtmlCanvasToHostMessage = z.infer<
+  typeof htmlCanvasToHostMessageSchema
+>;
diff --git a/packages/ui/src/features/canvas/components/WebsiteChannelArtifacts.tsx b/packages/ui/src/features/canvas/components/WebsiteChannelArtifacts.tsx
index d91d91d5b4..35d94d957c 100644
--- a/packages/ui/src/features/canvas/components/WebsiteChannelArtifacts.tsx
+++ b/packages/ui/src/features/canvas/components/WebsiteChannelArtifacts.tsx
@@ -1,6 +1,7 @@
 import { CaretRightIcon } from "@phosphor-icons/react";
 import type { ChannelTaskRecord } from "@posthog/core/canvas/channelTaskSchemas";
 import type { DashboardSummary } from "@posthog/core/canvas/dashboardSchemas";
+import { isHtmlTemplate } from "@posthog/core/canvas/htmlCanvasSchemas";
 import {
   getPrVisualConfig,
   parsePrNumber,
@@ -150,7 +151,7 @@ export function WebsiteChannelArtifacts({ channelId }: { channelId: string }) {
                     className: "text-violet-9",
                   })}
                   title={item.title}
-                  subtitle={`Canvas · ${formatRelativeTimeShort(item.ts)}`}
+                  subtitle={`${isHtmlTemplate(item.templateId) ? "Document" : "Canvas"} · ${formatRelativeTimeShort(item.ts)}`}
                   onClick={() => openCanvas(item.dashboardId)}
                 />
               ) : (
diff --git a/packages/ui/src/features/canvas/components/WebsiteDashboardsIndex.tsx b/packages/ui/src/features/canvas/components/WebsiteDashboardsIndex.tsx
index e4f359ead2..b34fb1b789 100644
--- a/packages/ui/src/features/canvas/components/WebsiteDashboardsIndex.tsx
+++ b/packages/ui/src/features/canvas/components/WebsiteDashboardsIndex.tsx
@@ -1,5 +1,6 @@
 import { DotsThreeIcon, LinkIcon, TrashIcon } from "@phosphor-icons/react";
 import type { DashboardSummary } from "@posthog/core/canvas/dashboardSchemas";
+import { isHtmlTemplate } from "@posthog/core/canvas/htmlCanvasSchemas";
 import {
   Badge,
   Button,
@@ -17,6 +18,7 @@ import { ANALYTICS_EVENTS } from "@posthog/shared/analytics-events";
 import { NewCanvasMenu } from "@posthog/ui/features/canvas/components/NewCanvasMenu";
 import { FreeformCanvas } from "@posthog/ui/features/canvas/freeform/FreeformCanvas";
 import { handleFreeformDataRequest } from "@posthog/ui/features/canvas/freeform/freeformDataBridge";
+import { buildHtmlArtifactDocument } from "@posthog/ui/features/canvas/html/htmlSandbox";
 import { useCanvasTemplates } from "@posthog/ui/features/canvas/hooks/useCanvasTemplates";
 import {
   useDashboardMutations,
@@ -125,7 +127,10 @@ const DashboardCard = memo(function DashboardCard({
         }
       >
         <Card className="gap-0 overflow-hidden p-0">
-          <FreeformPreview code={summary.code} />
+          <FreeformPreview
+            code={summary.code}
+            templateId={summary.templateId}
+          />
           <CardContent className="flex flex-col gap-0.5 p-3">
             <Flex align="center" justify="between" gap="2">
               <Text size="sm" weight="medium" className="truncate">
@@ -157,8 +162,16 @@ const DashboardCard = memo(function DashboardCard({
 
 // A freeform (React-in-iframe) canvas preview: the app rendered at PREVIEW_SCALE
 // in a clipped frame, the same shape as DashboardPreview. Deferred until near
-// the viewport, and runs with NO analytics so it fires no events.
-function FreeformPreview({ code }: { code?: string }) {
+// the viewport, and runs with NO analytics so it fires no events. HTML-document
+// canvases skip the React sandbox (their code isn't tsx — Babel would choke)
+// and render the raw document in a bare sandboxed iframe instead.
+function FreeformPreview({
+  code,
+  templateId,
+}: {
+  code?: string;
+  templateId?: string;
+}) {
   const [ref, inView] = useInView<HTMLDivElement>(PREVIEW_VIEWPORT);
 
   // Preview data handler: swallow captures so a thumbnail never emits analytics
@@ -196,11 +209,22 @@ function FreeformPreview({ code }: { code?: string }) {
               resetKey={code}
               fallback={<PreviewPlaceholder label="Preview unavailable" />}
             >
-              <FreeformCanvas
-                code={code}
-                mode="edit"
-                onDataRequest={onDataRequest}
-              />
+              {isHtmlTemplate(templateId) ? (
+                <iframe
+                  title="Document preview"
+                  // Same isolation as the full view: null origin, and the
+                  // composed document's CSP blocks network access.
+                  sandbox="allow-scripts"
+                  srcDoc={buildHtmlArtifactDocument(code)}
+                  className="h-full w-full border-0 bg-white"
+                />
+              ) : (
+                <FreeformCanvas
+                  code={code}
+                  mode="edit"
+                  onDataRequest={onDataRequest}
+                />
+              )}
             </ErrorBoundary>
           </Box>
         ) : (
diff --git a/packages/ui/src/features/canvas/components/canvasTemplateIcon.tsx b/packages/ui/src/features/canvas/components/canvasTemplateIcon.tsx
index 693dc20150..ff580fd813 100644
--- a/packages/ui/src/features/canvas/components/canvasTemplateIcon.tsx
+++ b/packages/ui/src/features/canvas/components/canvasTemplateIcon.tsx
@@ -1,16 +1,19 @@
 import {
   ChartBarIcon,
   ChartLineIcon,
+  FileHtmlIcon,
   FileIcon,
   ShapesIcon,
 } from "@phosphor-icons/react";
 import { FREEFORM_TEMPLATE_ID } from "@posthog/core/canvas/freeformSchemas";
+import { HTML_TEMPLATE_ID } from "@posthog/core/canvas/htmlCanvasSchemas";
 import type { ReactNode } from "react";
 
 // A canvas's leading icon, chosen from its template so the tree and header read
 // at a glance: bar chart for json-render dashboards, line chart for web
 // analytics, shapes for the generic freeform canvas (until it's classified as
-// something more specific), plain file for blank canvases.
+// something more specific), plain file for blank canvases, html file for
+// HTML documents.
 export function iconForTemplate(
   templateId: string,
   opts?: { size?: number; className?: string },
@@ -24,6 +27,8 @@ export function iconForTemplate(
       return <FileIcon size={size} className={className} />;
     case FREEFORM_TEMPLATE_ID:
       return <ShapesIcon size={size} className={className} />;
+    case HTML_TEMPLATE_ID:
+      return <FileHtmlIcon size={size} className={className} />;
     default:
       return <ChartBarIcon size={size} className={className} />;
   }
diff --git a/packages/ui/src/features/canvas/freeform/CanvasSidePanel.tsx b/packages/ui/src/features/canvas/freeform/CanvasSidePanel.tsx
index dc967a7d48..3bccda6719 100644
--- a/packages/ui/src/features/canvas/freeform/CanvasSidePanel.tsx
+++ b/packages/ui/src/features/canvas/freeform/CanvasSidePanel.tsx
@@ -1,5 +1,6 @@
 import {
   ChatCircleIcon,
+  ChatsCircleIcon,
   PencilSimpleIcon,
   SidebarSimpleIcon,
   SpinnerGapIcon,
@@ -11,7 +12,7 @@ import { EmbeddedSessionView } from "@posthog/ui/features/sessions/components/Em
 import { taskDetailQuery } from "@posthog/ui/features/tasks/queries";
 import { Flex, Text, Tooltip } from "@radix-ui/themes";
 import { useQuery } from "@tanstack/react-query";
-import type { Ref } from "react";
+import type { ReactNode, Ref } from "react";
 
 // The canvas's right-hand dock. While a generation/edit run is in flight it
 // shows that run's live chat (steering/queue included); otherwise it shows the
@@ -28,6 +29,9 @@ export function CanvasSidePanel({
   currentCode,
   editorRef,
   onStarted,
+  commentsPanel,
+  tab = "main",
+  onTabChange,
 }: {
   effectiveTaskId: string | null;
   onMinimize: () => void;
@@ -40,8 +44,15 @@ export function CanvasSidePanel({
   // Exposes the edit composer's editor so self-repair can prefill it.
   editorRef?: Ref<EditorHandle>;
   onStarted?: (taskId: string) => void;
+  // When provided (HTML canvases), the panel grows a second "Comments" tab
+  // alongside the chat/edit surface.
+  commentsPanel?: ReactNode;
+  tab?: "main" | "comments";
+  onTabChange?: (tab: "main" | "comments") => void;
 }) {
   const isChat = !!effectiveTaskId;
+  const showComments = !!commentsPanel && tab === "comments";
+  const mainLabel = isChat ? "Chat" : "Edit";
 
   return (
     <Flex direction="column" className="h-full min-w-0 bg-gray-1">
@@ -50,16 +61,41 @@ export function CanvasSidePanel({
         justify="between"
         className="h-10 shrink-0 items-center border-b bg-chrome px-3"
       >
-        <Flex align="center" gap="2" className="min-w-0">
-          {isChat ? (
-            <ChatCircleIcon size={15} className="shrink-0 text-gray-10" />
-          ) : (
-            <PencilSimpleIcon size={15} className="shrink-0 text-gray-10" />
-          )}
-          <Text size="2" weight="medium" className="truncate text-gray-12">
-            {isChat ? "Chat" : "Edit canvas"}
-          </Text>
-        </Flex>
+        {commentsPanel ? (
+          <Flex align="center" gap="1" className="min-w-0">
+            <Button
+              size="sm"
+              variant={tab === "main" ? "default" : "outline"}
+              onClick={() => onTabChange?.("main")}
+            >
+              {isChat ? (
+                <ChatCircleIcon size={14} />
+              ) : (
+                <PencilSimpleIcon size={14} />
+              )}
+              {mainLabel}
+            </Button>
+            <Button
+              size="sm"
+              variant={tab === "comments" ? "default" : "outline"}
+              onClick={() => onTabChange?.("comments")}
+            >
+              <ChatsCircleIcon size={14} />
+              Comments
+            </Button>
+          </Flex>
+        ) : (
+          <Flex align="center" gap="2" className="min-w-0">
+            {isChat ? (
+              <ChatCircleIcon size={15} className="shrink-0 text-gray-10" />
+            ) : (
+              <PencilSimpleIcon size={15} className="shrink-0 text-gray-10" />
+            )}
+            <Text size="2" weight="medium" className="truncate text-gray-12">
+              {isChat ? "Chat" : "Edit canvas"}
+            </Text>
+          </Flex>
+        )}
         <Tooltip content="Minimize panel">
           <Button
             size="icon"
@@ -73,7 +109,9 @@ export function CanvasSidePanel({
       </Flex>
 
       <div className="min-h-0 flex-1">
-        {effectiveTaskId ? (
+        {showComments ? (
+          commentsPanel
+        ) : effectiveTaskId ? (
           <CanvasChatLoader taskId={effectiveTaskId} />
         ) : (
           <Flex direction="column" className="h-full p-3">
diff --git a/packages/ui/src/features/canvas/freeform/FreeformCanvasView.tsx b/packages/ui/src/features/canvas/freeform/FreeformCanvasView.tsx
index d59ac286a4..7cad22f872 100644
--- a/packages/ui/src/features/canvas/freeform/FreeformCanvasView.tsx
+++ b/packages/ui/src/features/canvas/freeform/FreeformCanvasView.tsx
@@ -2,12 +2,16 @@ import {
   ArrowCounterClockwiseIcon,
   ArrowUUpLeftIcon,
   ArrowUUpRightIcon,
+  ChatCircleIcon,
+  CursorClickIcon,
+  FileHtmlIcon,
   ShapesIcon,
   SidebarSimpleIcon,
   SpinnerGapIcon,
   WarningIcon,
 } from "@phosphor-icons/react";
 import type { CanvasAnalyticsConfig } from "@posthog/core/canvas/freeformSchemas";
+import { isHtmlTemplate } from "@posthog/core/canvas/htmlCanvasSchemas";
 import { useHostTRPC } from "@posthog/host-router/react";
 import {
   Button,
@@ -23,7 +27,11 @@ import {
   isCanvasGenerationRunning,
 } from "@posthog/ui/features/canvas/freeform/canvasGenerationStatus";
 import { useChannels } from "@posthog/ui/features/canvas/hooks/useChannels";
+import { useCanvasComments } from "@posthog/ui/features/canvas/hooks/useCanvasComments";
+import { CanvasCommentsPanel } from "@posthog/ui/features/canvas/html/CanvasCommentsPanel";
+import { HtmlCanvasBody } from "@posthog/ui/features/canvas/html/HtmlCanvasBody";
 import { useCanvasChatPanelStore } from "@posthog/ui/features/canvas/stores/canvasChatPanelStore";
+import { useCanvasCommentsStore } from "@posthog/ui/features/canvas/stores/canvasCommentsStore";
 import {
   useFreeformChatStore,
   useFreeformThread,
@@ -103,6 +111,20 @@ export function FreeformCanvasView({
   );
   const genTaskId = dashboard?.generationTaskId ?? null;
   const channelId = dashboard?.channelId ?? "";
+  // HTML-document canvases render in their own frame (no warm pool, no data
+  // shim) and carry the anchored-comments surface.
+  const isHtml = isHtmlTemplate(dashboard?.templateId);
+  const pickMode = useCanvasCommentsStore((s) => s.pickMode);
+  const setPickMode = useCanvasCommentsStore((s) => s.setPickMode);
+  const panelTab = useCanvasCommentsStore((s) => s.panelTab);
+  const setPanelTab = useCanvasCommentsStore((s) => s.setPanelTab);
+  const { threads: commentThreads } = useCanvasComments(
+    isHtml ? dashboardId : undefined,
+  );
+  const openThread = useCallback(() => {
+    setCollapsed(false);
+    setPanelTab("comments");
+  }, [setCollapsed, setPanelTab]);
 
   // Reconcile the optimistic bridge against the polled record during render
   // (not via an effect, which would flash a stale frame): once the record
@@ -342,6 +364,35 @@ export function FreeformCanvasView({
                   </>
                 )
               )}
+              {isHtml && showCanvas && (
+                <>
+                  <Tooltip content="Comment on an element">
+                    <Button
+                      size="icon"
+                      variant={pickMode ? "primary" : "default"}
+                      aria-label="Comment on an element"
+                      onClick={() => setPickMode(!pickMode)}
+                    >
+                      <CursorClickIcon size={16} />
+                    </Button>
+                  </Tooltip>
+                  <Tooltip content="Comments">
+                    <Button
+                      size="sm"
+                      variant="default"
+                      aria-label="Comments"
+                      onClick={openThread}
+                    >
+                      <ChatCircleIcon size={16} />
+                      {commentThreads.length > 0 && (
+                        <span className="text-[11px]">
+                          {commentThreads.length}
+                        </span>
+                      )}
+                    </Button>
+                  </Tooltip>
+                </>
+              )}
               {showPanel && collapsed && (
                 <Tooltip
                   content={effectiveTaskId ? "Show chat" : "Edit canvas"}
@@ -371,20 +422,34 @@ export function FreeformCanvasView({
             }
           />
           {showCanvas ? (
-            // The iframe lives in the persistent warm-frame pool (CanvasFrameHost);
-            // this placeholder just reserves the viewport box and owns scroll via
-            // the host's overlay, so the canvas survives navigation without a reload.
-            <Box className="h-full w-full">
-              <CanvasFramePlaceholder
-                dashboardId={dashboardId}
-                code={renderCode}
-                analytics={analytics}
-                onDataRequest={onDataRequest}
-                onError={onError}
-                onRendered={onRendered}
-                onNavigate={onNavigate}
-              />
-            </Box>
+            isHtml ? (
+              // HTML documents render in their own inline frame — no warm pool
+              // (nothing to amortize: static HTML, no compile) — wrapped with
+              // the anchored-comment affordances.
+              <Box className="h-full w-full">
+                <HtmlCanvasBody
+                  dashboardId={dashboardId}
+                  html={renderCode}
+                  canvasVersionId={currentVersionId ?? undefined}
+                  onOpenThread={openThread}
+                />
+              </Box>
+            ) : (
+              // The iframe lives in the persistent warm-frame pool (CanvasFrameHost);
+              // this placeholder just reserves the viewport box and owns scroll via
+              // the host's overlay, so the canvas survives navigation without a reload.
+              <Box className="h-full w-full">
+                <CanvasFramePlaceholder
+                  dashboardId={dashboardId}
+                  code={renderCode}
+                  analytics={analytics}
+                  onDataRequest={onDataRequest}
+                  onError={onError}
+                  onRendered={onRendered}
+                  onNavigate={onNavigate}
+                />
+              </Box>
+            )
           ) : (
             <ScrollArea className="h-full">
               {showGeneratingState ? (
@@ -398,11 +463,19 @@ export function FreeformCanvasView({
                 <Empty className="h-full border-0">
                   <EmptyHeader>
                     <EmptyMedia variant="icon">
-                      <ShapesIcon size={24} />
+                      {isHtml ? (
+                        <FileHtmlIcon size={24} />
+                      ) : (
+                        <ShapesIcon size={24} />
+                      )}
                     </EmptyMedia>
-                    <EmptyTitle>Freeform canvas</EmptyTitle>
+                    <EmptyTitle>
+                      {isHtml ? "HTML document" : "Freeform canvas"}
+                    </EmptyTitle>
                     <EmptyDescription>
-                      This canvas is empty. Hit Edit to build it with an agent.
+                      {isHtml
+                        ? "This document is empty. Hit Edit to write it with an agent."
+                        : "This canvas is empty. Hit Edit to build it with an agent."}
                     </EmptyDescription>
                   </EmptyHeader>
                 </Empty>
@@ -435,6 +508,16 @@ export function FreeformCanvasView({
             currentCode={renderCode || undefined}
             editorRef={editorRef}
             onStarted={setStartedTaskId}
+            commentsPanel={
+              isHtml ? (
+                <CanvasCommentsPanel
+                  dashboardId={dashboardId}
+                  canvasVersionId={currentVersionId ?? undefined}
+                />
+              ) : undefined
+            }
+            tab={panelTab}
+            onTabChange={setPanelTab}
           />
         </ResizableSidebar>
       )}
diff --git a/packages/ui/src/features/canvas/freeform/FreeformGenerateBar.tsx b/packages/ui/src/features/canvas/freeform/FreeformGenerateBar.tsx
index c56b124bcb..8eb411e5c1 100644
--- a/packages/ui/src/features/canvas/freeform/FreeformGenerateBar.tsx
+++ b/packages/ui/src/features/canvas/freeform/FreeformGenerateBar.tsx
@@ -1,3 +1,4 @@
+import { isHtmlTemplate } from "@posthog/core/canvas/htmlCanvasSchemas";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@posthog/quill";
 import { useGenerateFreeformCanvas } from "@posthog/ui/features/canvas/hooks/useGenerateFreeformCanvas";
 import { PromptInput } from "@posthog/ui/features/message-editor/components/PromptInput";
@@ -53,8 +54,10 @@ export const FreeformGenerateBar = forwardRef<
   // 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.
+  // empty canvas, so the toggle is hidden in edit mode — and for HTML
+  // documents, whose tier has no scaffold (it's a React app).
   const isEdit = !!currentCode?.trim();
+  const isHtml = isHtmlTemplate(templateId);
   const [useStarter, setUseStarter] = useState(true);
 
   // Generation always runs in the cloud, except the dev-only picker below lets a
@@ -70,7 +73,7 @@ export const FreeformGenerateBar = forwardRef<
       templateId,
       instruction,
       currentCode,
-      useStarter: !isEdit && useStarter,
+      useStarter: !isEdit && !isHtml && useStarter,
       workspaceMode,
     });
     if (taskId) onStarted?.(taskId);
@@ -89,7 +92,7 @@ export const FreeformGenerateBar = forwardRef<
         hideDefaultToolbar
         onSubmit={(text) => void run(text)}
       />
-      {!isEdit && (
+      {!isEdit && !isHtml && (
         <label className="flex cursor-pointer select-none items-center gap-1.5 self-start px-1 text-muted-foreground text-xs">
           <input
             type="checkbox"
diff --git a/packages/ui/src/features/canvas/freeformPrompt.test.ts b/packages/ui/src/features/canvas/freeformPrompt.test.ts
index 647f4cb465..9917befde7 100644
--- a/packages/ui/src/features/canvas/freeformPrompt.test.ts
+++ b/packages/ui/src/features/canvas/freeformPrompt.test.ts
@@ -36,4 +36,40 @@ describe("buildFreeformGenerationPrompt", () => {
     expect(extracted?.body).toContain("export const App = () => null;");
     expect(extracted?.body).toContain("Edit the freeform React canvas");
   });
+
+  it("switches to the HTML contract for the html template", () => {
+    const prompt = buildFreeformGenerationPrompt({
+      ...base,
+      templateId: "html",
+      // The React starter is meaningless for a document; must be ignored.
+      useStarter: true,
+    });
+    const extracted = extractCanvasInstructions(prompt);
+    expect(extracted?.body).toContain("Build a HTML document canvas");
+    expect(extracted?.body).toContain("```html block");
+    expect(extracted?.body).toContain("the COMPLETE standalone HTML document");
+    // Static tier: no ph shim, no live-data rules, no React scaffold.
+    expect(extracted?.body).toContain("the document is STATIC");
+    expect(extracted?.body).not.toContain("Starter scaffold");
+    expect(extracted?.body).not.toContain("ph.loadInsight(short_id");
+    // Same publish path as React canvases.
+    expect(extracted?.body).toContain(
+      "desktop-file-system-canvas-partial-update",
+    );
+  });
+
+  it("fences the current document as html when editing an html canvas", () => {
+    const prompt = buildFreeformGenerationPrompt({
+      ...base,
+      templateId: "html",
+      currentCode: "<!doctype html><html><body>hi</body></html>",
+    });
+    const extracted = extractCanvasInstructions(prompt);
+    expect(extracted?.body).toContain("Edit the HTML document canvas");
+    expect(extracted?.body).toContain("```html");
+    expect(extracted?.body).toContain(
+      "<!doctype html><html><body>hi</body></html>",
+    );
+    expect(extracted?.body).toContain("Rewrite the WHOLE document");
+  });
 });
diff --git a/packages/ui/src/features/canvas/freeformPrompt.ts b/packages/ui/src/features/canvas/freeformPrompt.ts
index 32631fc0c7..e73481f76c 100644
--- a/packages/ui/src/features/canvas/freeformPrompt.ts
+++ b/packages/ui/src/features/canvas/freeformPrompt.ts
@@ -1,15 +1,16 @@
 import { freeformSystemPromptFor } from "@posthog/core/canvas/canvasTemplates";
 import { FREEFORM_STARTER_CODE } from "@posthog/core/canvas/freeformStarter";
+import { isHtmlTemplate } from "@posthog/core/canvas/htmlCanvasSchemas";
 
-// 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
-// picked up front), so the agent has the default system prompt — the freeform
-// authoring contract
-// (imports, the `ph` data shim, Quill/style rules) therefore has to live in the
-// task's content (its first user message). The canvas is not a file on disk — it
-// lives in PostHog — so the agent publishes the result via the PostHog MCP tool
-// `desktop-file-system-canvas-partial-update` rather than replying with code or
-// writing a file.
+// Builds the prompt for the task that generates a freeform (React) or HTML
+// canvas. Like CONTEXT.md generation, this runs as a normal repo-less agent
+// task (no repo picked up front), so the agent has the default system prompt —
+// the authoring contract (imports, the `ph` data shim, Quill/style rules for
+// React; the self-contained document rules for HTML) therefore has to live in
+// the task's content (its first user message). The canvas is not a file on
+// disk — it lives in PostHog — so the agent publishes the result via the
+// PostHog MCP tool `desktop-file-system-canvas-partial-update` rather than
+// replying with code or writing a file.
 export function buildFreeformGenerationPrompt(input: {
   dashboardId: string;
   name: string;
@@ -20,7 +21,8 @@ export function buildFreeformGenerationPrompt(input: {
   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.
+  // app instead of authoring boilerplate from scratch. Ignored when editing,
+  // and for HTML documents (the scaffold is React-only).
   useStarter?: boolean;
 }): string {
   const {
@@ -35,26 +37,47 @@ export function buildFreeformGenerationPrompt(input: {
 
   const contract = freeformSystemPromptFor(templateId);
   const isEdit = !!currentCode?.trim();
+  const isHtml = isHtmlTemplate(templateId);
+
+  // What the agent is building: a React app or a raw HTML document. Drives the
+  // wording + the fenced-block language throughout.
+  const noun = isHtml ? "HTML document canvas" : "freeform React canvas";
+  const fence = isHtml ? "html" : "tsx";
+  const codeDescription = isHtml
+    ? "the COMPLETE standalone HTML document"
+    : "the COMPLETE single-file React source for the canvas";
 
   // The header points back to the user's request, which leads the message
   // (outside this block). Without that pointer the agent can read the header as
   // a self-contained task and under-weight the actual instruction above.
   const header = isEdit
-    ? `Edit the freeform React canvas "${name}" in the channel "${channelName}", per the user's request at the start of this message.`
-    : `Build a freeform React canvas "${name}" for the channel "${channelName}", per the user's request at the start of this message.`;
+    ? `Edit the ${noun} "${name}" in the channel "${channelName}", per the user's request at the start of this message.`
+    : `Build a ${noun} "${name}" for the channel "${channelName}", per the user's request at the start of this message.`;
 
   const currentBlock = isEdit
-    ? `\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`
+    ? `\n[Current code] — the canvas as it stands now. Rewrite the WHOLE ${isHtml ? "document" : "file"} with the change applied; do not output a partial ${isHtml ? "document" : "file"}.\n\n\`\`\`${fence}\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).
+  // First-build only (React tier): 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). HTML documents have no scaffold — they start from the contract.
   const starterBlock =
-    !isEdit && useStarter
+    !isEdit && useStarter && !isHtml
       ? `\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`
       : "";
 
+  // Data rules differ by tier: React canvases load live data through saved
+  // insights + the `ph` shim; HTML documents are static, so any numbers are
+  // queried NOW (via MCP) and baked in.
+  const dataBlock = isHtml
+    ? `DATA — the document is STATIC (there is no \`ph.*\` shim and the sandbox blocks network access). If it needs PostHog numbers, query them NOW via the PostHog MCP tools and bake the values into the HTML. Never emit fetch()/XHR.`
+    : `DATA — for each metric, first SAVE an insight via the PostHog MCP insight tools
+(prefer an insight query type — Trends, Funnels, Retention, web-analytics kinds —
+over raw SQL), record the \`short_id\` it returns, and load it in the canvas with
+\`ph.loadInsight(short_id, { dateRange })\`. Fall back to inline \`ph.query(...)\`/HogQL
+only when no insight can express the metric.`;
+
   // 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
@@ -63,27 +86,22 @@ export function buildFreeformGenerationPrompt(input: {
   // the request leads, mirroring how channel CONTEXT.md is appended.
   const instructions = `${header}
 ${currentBlock}${starterBlock}
-Follow this authoring contract for the canvas (imports, the \`ph\` data shim, and
-style rules):
+Follow this authoring contract for the canvas:
 
 ${contract}
 
 PUBLISHING — this OVERRIDES any instruction above about replying with the code in
-a fenced \`\`\`tsx block. In this task you do NOT reply with the code. When the
+a fenced \`\`\`${fence} block. In this task you do NOT reply with the code. When the
 canvas is ready, PUBLISH it by calling the PostHog MCP tool
 \`desktop-file-system-canvas-partial-update\` exactly once with:
 - id: "${dashboardId}"
-- code: the COMPLETE single-file React source for the canvas.
+- code: ${codeDescription}.
 
 The canvas lives in PostHog, not on disk — calling that MCP tool is what saves it.
 Do not write a local file. Verify event/property names via the PostHog MCP before
 using them, and operate only on this project.
 
-DATA — for each metric, first SAVE an insight via the PostHog MCP insight tools
-(prefer an insight query type — Trends, Funnels, Retention, web-analytics kinds —
-over raw SQL), record the \`short_id\` it returns, and load it in the canvas with
-\`ph.loadInsight(short_id, { dateRange })\`. Fall back to inline \`ph.query(...)\`/HogQL
-only when no insight can express the metric.`;
+${dataBlock}`;
 
   return `${instruction}
 
diff --git a/packages/ui/src/features/canvas/hooks/useCanvasComments.ts b/packages/ui/src/features/canvas/hooks/useCanvasComments.ts
new file mode 100644
index 0000000000..90922d9045
--- /dev/null
+++ b/packages/ui/src/features/canvas/hooks/useCanvasComments.ts
@@ -0,0 +1,90 @@
+import type { CanvasCommentThread } from "@posthog/core/canvas/canvasCommentsSchemas";
+import {
+  CANVAS_COMMENTS_SERVICE,
+  type CanvasCommentsService,
+} from "@posthog/core/canvas/canvasCommentsService";
+import type { CommentAnchor } from "@posthog/core/canvas/htmlCanvasSchemas";
+import { useService } from "@posthog/di/react";
+import { useOptionalAuthenticatedClient } from "@posthog/ui/features/auth/authClient";
+import { useAuthenticatedQuery } from "@posthog/ui/hooks/useAuthenticatedQuery";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+// Multi-user sync is poll-based (no realtime channel exists); matches the
+// channel feed's cadence.
+const CANVAS_COMMENTS_POLL_INTERVAL_MS = 15_000;
+
+export function canvasCommentsQueryKey(dashboardId: string | undefined) {
+  return ["canvas-comments", dashboardId ?? "none"] as const;
+}
+
+export function useCanvasComments(dashboardId: string | undefined): {
+  threads: CanvasCommentThread[];
+  isLoading: boolean;
+} {
+  const service = useService<CanvasCommentsService>(CANVAS_COMMENTS_SERVICE);
+  const query = useAuthenticatedQuery<CanvasCommentThread[]>(
+    canvasCommentsQueryKey(dashboardId),
+    (client) => service.listThreads(client, dashboardId as string),
+    {
+      enabled: !!dashboardId,
+      refetchInterval: CANVAS_COMMENTS_POLL_INTERVAL_MS,
+      staleTime: CANVAS_COMMENTS_POLL_INTERVAL_MS,
+    },
+  );
+  return { threads: query.data ?? [], isLoading: query.isLoading };
+}
+
+export function useAddCanvasComment(dashboardId: string | undefined) {
+  const client = useOptionalAuthenticatedClient();
+  const queryClient = useQueryClient();
+  const service = useService<CanvasCommentsService>(CANVAS_COMMENTS_SERVICE);
+  const mutation = useMutation({
+    mutationFn: async (input: {
+      content: string;
+      anchor: CommentAnchor;
+      canvasVersionId?: string;
+    }) => {
+      if (!client || !dashboardId) throw new Error("Not authenticated");
+      return service.addComment(client, { dashboardId, ...input });
+    },
+    onSuccess: () =>
+      queryClient.invalidateQueries({
+        queryKey: canvasCommentsQueryKey(dashboardId),
+      }),
+  });
+  return { addComment: mutation.mutateAsync, isAdding: mutation.isPending };
+}
+
+export function useAddCanvasReply(dashboardId: string | undefined) {
+  const client = useOptionalAuthenticatedClient();
+  const queryClient = useQueryClient();
+  const service = useService<CanvasCommentsService>(CANVAS_COMMENTS_SERVICE);
+  const mutation = useMutation({
+    mutationFn: async (input: { content: string; rootId: string }) => {
+      if (!client || !dashboardId) throw new Error("Not authenticated");
+      return service.addReply(client, { dashboardId, ...input });
+    },
+    onSuccess: () =>
+      queryClient.invalidateQueries({
+        queryKey: canvasCommentsQueryKey(dashboardId),
+      }),
+  });
+  return { addReply: mutation.mutateAsync, isReplying: mutation.isPending };
+}
+
+export function useRemoveCanvasComment(dashboardId: string | undefined) {
+  const client = useOptionalAuthenticatedClient();
+  const queryClient = useQueryClient();
+  const service = useService<CanvasCommentsService>(CANVAS_COMMENTS_SERVICE);
+  const mutation = useMutation({
+    mutationFn: async (commentId: string) => {
+      if (!client) throw new Error("Not authenticated");
+      return service.remove(client, commentId);
+    },
+    onSuccess: () =>
+      queryClient.invalidateQueries({
+        queryKey: canvasCommentsQueryKey(dashboardId),
+      }),
+  });
+  return { removeComment: mutation.mutateAsync };
+}
diff --git a/packages/ui/src/features/canvas/html/CanvasCommentsPanel.tsx b/packages/ui/src/features/canvas/html/CanvasCommentsPanel.tsx
new file mode 100644
index 0000000000..dd40d1c297
--- /dev/null
+++ b/packages/ui/src/features/canvas/html/CanvasCommentsPanel.tsx
@@ -0,0 +1,305 @@
+import {
+  ChatCircleIcon,
+  LinkBreakIcon,
+  TrashIcon,
+} from "@phosphor-icons/react";
+import type {
+  CanvasComment,
+  CanvasCommentThread,
+} from "@posthog/core/canvas/canvasCommentsSchemas";
+import { formatRelativeTimeShort } from "@posthog/shared";
+import {
+  Badge,
+  Button,
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+  Textarea,
+} from "@posthog/quill";
+import { useOptionalAuthenticatedClient } from "@posthog/ui/features/auth/authClient";
+import { useCurrentUser } from "@posthog/ui/features/auth/useCurrentUser";
+import {
+  useAddCanvasComment,
+  useAddCanvasReply,
+  useCanvasComments,
+  useRemoveCanvasComment,
+} from "@posthog/ui/features/canvas/hooks/useCanvasComments";
+import { useCanvasCommentsStore } from "@posthog/ui/features/canvas/stores/canvasCommentsStore";
+import { Flex, ScrollArea, Text } from "@radix-ui/themes";
+import { useState } from "react";
+
+// The side panel's Comments tab: every thread on the canvas, numbered to
+// match the on-document pins. Clicking a thread emphasizes + scrolls to its
+// anchor; anchors that no longer resolve get an "original context missing"
+// badge instead. Content renders as plain text only — comments are
+// user-authored and never interpreted as markup.
+export function CanvasCommentsPanel({
+  dashboardId,
+  canvasVersionId,
+}: {
+  dashboardId: string;
+  canvasVersionId?: string;
+}) {
+  const { threads, isLoading } = useCanvasComments(dashboardId);
+  const { addComment, isAdding } = useAddCanvasComment(dashboardId);
+  const client = useOptionalAuthenticatedClient();
+  const { data: currentUser } = useCurrentUser({ client });
+
+  const [pageComposerOpen, setPageComposerOpen] = useState(false);
+  const [pageContent, setPageContent] = useState("");
+
+  const submitPageComment = async () => {
+    const content = pageContent.trim();
+    if (!content) return;
+    await addComment({ content, anchor: { type: "page" }, canvasVersionId });
+    setPageContent("");
+    setPageComposerOpen(false);
+  };
+
+  return (
+    <Flex direction="column" className="h-full min-h-0">
+      <Flex direction="column" gap="2" className="shrink-0 border-b p-3">
+        {pageComposerOpen ? (
+          <>
+            <Textarea
+              autoFocus
+              rows={3}
+              placeholder="Comment on this document…"
+              value={pageContent}
+              onChange={(e) => setPageContent(e.target.value)}
+            />
+            <Flex justify="end" gap="2">
+              <Button
+                size="sm"
+                variant="outline"
+                onClick={() => setPageComposerOpen(false)}
+              >
+                Cancel
+              </Button>
+              <Button
+                size="sm"
+                variant="primary"
+                disabled={!pageContent.trim() || isAdding}
+                onClick={() => void submitPageComment()}
+              >
+                Comment
+              </Button>
+            </Flex>
+          </>
+        ) : (
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={() => setPageComposerOpen(true)}
+          >
+            <ChatCircleIcon size={14} />
+            Comment on page
+          </Button>
+        )}
+        <Text size="1" className="text-gray-9">
+          Select text or pick an element in the document to comment on it.
+        </Text>
+      </Flex>
+      <ScrollArea className="min-h-0 flex-1">
+        {threads.length === 0 ? (
+          <Empty className="h-full border-0">
+            <EmptyHeader>
+              <EmptyMedia variant="icon">
+                <ChatCircleIcon size={24} />
+              </EmptyMedia>
+              <EmptyTitle>No comments yet</EmptyTitle>
+              <EmptyDescription>
+                {isLoading
+                  ? "Loading comments…"
+                  : "Select text or an element in the document to start a thread."}
+              </EmptyDescription>
+            </EmptyHeader>
+          </Empty>
+        ) : (
+          <Flex direction="column" className="p-2">
+            {threads.map((thread) => (
+              <CommentThread
+                key={thread.root.id}
+                thread={thread}
+                dashboardId={dashboardId}
+                currentUserUuid={currentUser?.uuid}
+              />
+            ))}
+          </Flex>
+        )}
+      </ScrollArea>
+    </Flex>
+  );
+}
+
+// Where the thread anchors, for the panel row: the quoted text, the element
+// label, or "Page".
+function anchorSummary(root: CanvasComment): string {
+  const anchor = root.anchor;
+  if (anchor?.type === "text") {
+    const quote =
+      anchor.quote.length > 80 ? `${anchor.quote.slice(0, 80)}…` : anchor.quote;
+    return `“${quote}”`;
+  }
+  if (anchor?.type === "element") return anchor.label || anchor.selector;
+  return "Page";
+}
+
+function CommentThread({
+  thread,
+  dashboardId,
+  currentUserUuid,
+}: {
+  thread: CanvasCommentThread;
+  dashboardId: string;
+  currentUserUuid?: string;
+}) {
+  const activeCommentId = useCanvasCommentsStore((s) => s.activeCommentId);
+  const setActiveCommentId = useCanvasCommentsStore(
+    (s) => s.setActiveCommentId,
+  );
+  const resolved = useCanvasCommentsStore((s) => s.resolved);
+  const { addReply, isReplying } = useAddCanvasReply(dashboardId);
+  const { removeComment } = useRemoveCanvasComment(dashboardId);
+
+  const [replyOpen, setReplyOpen] = useState(false);
+  const [replyContent, setReplyContent] = useState("");
+
+  const root = thread.root;
+  const isActive = activeCommentId === root.id;
+  const anchoredInDoc = root.anchor && root.anchor.type !== "page";
+  const orphaned = anchoredInDoc && resolved[root.id] === false;
+
+  const submitReply = async () => {
+    const content = replyContent.trim();
+    if (!content) return;
+    await addReply({ content, rootId: root.id });
+    setReplyContent("");
+    setReplyOpen(false);
+  };
+
+  return (
+    <Flex
+      direction="column"
+      gap="1"
+      className={`cursor-pointer rounded-lg border p-2.5 transition-colors ${
+        isActive
+          ? "border-accent-7 bg-accent-2"
+          : "border-transparent hover:bg-gray-2"
+      }`}
+      onClick={() => setActiveCommentId(isActive ? null : root.id)}
+    >
+      <Flex align="center" gap="2">
+        <span className="flex size-[18px] shrink-0 items-center justify-center rounded-full bg-indigo-9 font-bold text-[10px] text-white">
+          {thread.index}
+        </span>
+        <Text size="1" className="truncate text-gray-9">
+          {anchorSummary(root)}
+        </Text>
+        {orphaned && (
+          <Badge variant="warning">
+            <LinkBreakIcon size={11} />
+            Context missing
+          </Badge>
+        )}
+      </Flex>
+      <CommentBody
+        comment={root}
+        canDelete={!!currentUserUuid && root.createdBy.uuid === currentUserUuid}
+        onDelete={() => void removeComment(root.id)}
+      />
+      {thread.replies.map((reply) => (
+        <div key={reply.id} className="border-gray-4 border-l-2 pl-2">
+          <CommentBody
+            comment={reply}
+            canDelete={
+              !!currentUserUuid && reply.createdBy.uuid === currentUserUuid
+            }
+            onDelete={() => void removeComment(reply.id)}
+          />
+        </div>
+      ))}
+      {replyOpen ? (
+        <Flex direction="column" gap="1" onClick={(e) => e.stopPropagation()}>
+          <Textarea
+            autoFocus
+            rows={2}
+            placeholder="Reply…"
+            value={replyContent}
+            onChange={(e) => setReplyContent(e.target.value)}
+          />
+          <Flex justify="end" gap="2">
+            <Button
+              size="xs"
+              variant="outline"
+              onClick={() => setReplyOpen(false)}
+            >
+              Cancel
+            </Button>
+            <Button
+              size="xs"
+              variant="primary"
+              disabled={!replyContent.trim() || isReplying}
+              onClick={() => void submitReply()}
+            >
+              Reply
+            </Button>
+          </Flex>
+        </Flex>
+      ) : (
+        <button
+          type="button"
+          className="self-start text-[11px] text-gray-9 hover:text-gray-12"
+          onClick={(e) => {
+            e.stopPropagation();
+            setReplyOpen(true);
+          }}
+        >
+          Reply
+        </button>
+      )}
+    </Flex>
+  );
+}
+
+function CommentBody({
+  comment,
+  canDelete,
+  onDelete,
+}: {
+  comment: CanvasComment;
+  canDelete: boolean;
+  onDelete: () => void;
+}) {
+  return (
+    <Flex direction="column" gap="1" className="group/comment">
+      <Flex align="center" gap="2">
+        <Text size="1" weight="medium" className="truncate text-gray-12">
+          {comment.createdBy.name}
+        </Text>
+        <Text size="1" className="shrink-0 text-gray-9">
+          {formatRelativeTimeShort(comment.createdAt)}
+        </Text>
+        {canDelete && (
+          <button
+            type="button"
+            aria-label="Delete comment"
+            className="ml-auto text-gray-8 opacity-0 transition-opacity hover:text-red-11 group-hover/comment:opacity-100"
+            onClick={(e) => {
+              e.stopPropagation();
+              onDelete();
+            }}
+          >
+            <TrashIcon size={13} />
+          </button>
+        )}
+      </Flex>
+      {/* Plain text on purpose — never rendered as markdown/HTML. */}
+      <Text size="2" className="whitespace-pre-wrap break-words text-gray-12">
+        {comment.content}
+      </Text>
+    </Flex>
+  );
+}
diff --git a/packages/ui/src/features/canvas/html/HtmlArtifactFrame.tsx b/packages/ui/src/features/canvas/html/HtmlArtifactFrame.tsx
new file mode 100644
index 0000000000..9ab5468653
--- /dev/null
+++ b/packages/ui/src/features/canvas/html/HtmlArtifactFrame.tsx
@@ -0,0 +1,231 @@
+import {
+  type ElementAnchor,
+  HTML_CANVAS_MESSAGE_CHANNEL,
+  type HostToHtmlCanvasMessage,
+  type HtmlCanvasAnnotation,
+  type HtmlCanvasRect,
+  type HtmlCanvasToHostMessage,
+  htmlCanvasToHostMessageSchema,
+  type TextQuoteAnchor,
+} from "@posthog/core/canvas/htmlCanvasSchemas";
+import { logger } from "@posthog/ui/shell/logger";
+import { useCallback, useLayoutEffect, useMemo, useRef } from "react";
+import { buildHtmlArtifactDocument } from "./htmlSandbox";
+
+const log = logger.scope("html-artifact-frame");
+
+export interface HtmlArtifactFrameProps {
+  /** The complete HTML document to render (the canvas's `code`). */
+  html: string;
+  /** Root comments to paint as highlights + numbered pins. */
+  annotations: HtmlCanvasAnnotation[];
+  /** Element-pick mode: hover outline + click-to-anchor inside the iframe. */
+  pickMode: boolean;
+  /** The emphasized annotation; changing to a non-null id scrolls to it. */
+  activeId: string | null;
+  /**
+   * Whether a draft (pending composer) exists host-side. While true the shim
+   * keeps the draft highlight painted; on true -> false it is cleared.
+   */
+  hasDraft: boolean;
+  /** A text selection settled inside the document. */
+  onSelection: (anchor: TextQuoteAnchor, rect: HtmlCanvasRect) => void;
+  /** The selection collapsed without becoming a draft. */
+  onSelectionCleared: () => void;
+  /** Pick mode: the user clicked an element. */
+  onElementPicked: (anchor: ElementAnchor, rect: HtmlCanvasRect) => void;
+  /** The user clicked a pin/highlight — open that thread. */
+  onMarkerClicked: (id: string, rect?: HtmlCanvasRect) => void;
+  /** Which anchors resolved after a repaint (unresolved = orphaned). */
+  onAnnotationsResolved: (
+    results: { id: string; resolved: boolean; rect?: HtmlCanvasRect }[],
+  ) => void;
+  onError?: (message: string) => void;
+}
+
+// Renders an HTML artifact inside a null-origin sandboxed iframe and brokers
+// the annotation postMessage protocol with the injected shim. Unlike the
+// freeform canvas there is no `init` frame — the artifact IS the srcDoc — so
+// a code change reloads the iframe (cheap: static HTML, no compile step).
+export function HtmlArtifactFrame({
+  html,
+  annotations,
+  pickMode,
+  activeId,
+  hasDraft,
+  onSelection,
+  onSelectionCleared,
+  onElementPicked,
+  onMarkerClicked,
+  onAnnotationsResolved,
+  onError,
+}: HtmlArtifactFrameProps) {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  // Whether the current document's shim has announced `ready`. Ref, not
+  // state: it only gates imperative postMessages.
+  const readyRef = useRef(false);
+
+  const srcDoc = useMemo(() => buildHtmlArtifactDocument(html), [html]);
+
+  // Latest props for the once-bound listener and the stable state push.
+  const latest = useRef({
+    annotations,
+    pickMode,
+    activeId,
+    hasDraft,
+    onSelection,
+    onSelectionCleared,
+    onElementPicked,
+    onMarkerClicked,
+    onAnnotationsResolved,
+    onError,
+  });
+  latest.current = {
+    annotations,
+    pickMode,
+    activeId,
+    hasDraft,
+    onSelection,
+    onSelectionCleared,
+    onElementPicked,
+    onMarkerClicked,
+    onAnnotationsResolved,
+    onError,
+  };
+
+  const post = useCallback((msg: HostToHtmlCanvasMessage) => {
+    iframeRef.current?.contentWindow?.postMessage(msg, "*");
+  }, []);
+
+  // Push the full paintable state — idempotent, sent on ready/load and reused
+  // by the prop-change effects below.
+  const pushState = useCallback(() => {
+    const p = latest.current;
+    post({
+      channel: HTML_CANVAS_MESSAGE_CHANNEL,
+      type: "set-annotations",
+      annotations: p.annotations,
+    });
+    post({
+      channel: HTML_CANVAS_MESSAGE_CHANNEL,
+      type: "set-pick-mode",
+      active: p.pickMode,
+    });
+    post({
+      channel: HTML_CANVAS_MESSAGE_CHANNEL,
+      type: "set-active",
+      id: p.activeId,
+      scroll: false,
+    });
+  }, [post]);
+
+  // A new document reloads the iframe; its shim re-announces `ready`.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: srcDoc identity tracks a reload.
+  useLayoutEffect(() => {
+    readyRef.current = false;
+  }, [srcDoc]);
+
+  // Bound once; reads latest props via the ref. Layout effect so the listener
+  // exists before the iframe's load task can post its one-shot `ready`.
+  useLayoutEffect(() => {
+    const route = (msg: HtmlCanvasToHostMessage) => {
+      const p = latest.current;
+      switch (msg.type) {
+        case "ready":
+          readyRef.current = true;
+          pushState();
+          break;
+        case "selection":
+          p.onSelection(msg.anchor, msg.rect);
+          break;
+        case "selection-cleared":
+          p.onSelectionCleared();
+          break;
+        case "element-picked":
+          p.onElementPicked(msg.anchor, msg.rect);
+          break;
+        case "marker-clicked":
+          p.onMarkerClicked(msg.id, msg.rect);
+          break;
+        case "annotations-resolved":
+          p.onAnnotationsResolved(msg.results);
+          break;
+        case "error":
+          log.warn("HTML artifact shim error", { message: msg.message });
+          p.onError?.(msg.message);
+          break;
+      }
+    };
+
+    const onMessage = (event: MessageEvent) => {
+      // A null-origin sandbox can't be trusted by origin; identify the frame
+      // by its window reference + the channel tag instead.
+      if (event.source !== iframeRef.current?.contentWindow) return;
+      const parsed = htmlCanvasToHostMessageSchema.safeParse(event.data);
+      if (!parsed.success) return;
+      route(parsed.data);
+    };
+
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [pushState]);
+
+  // Prop-driven pushes, skipped until the shim is ready (ready/load push the
+  // full state anyway).
+  useLayoutEffect(() => {
+    if (!readyRef.current) return;
+    post({
+      channel: HTML_CANVAS_MESSAGE_CHANNEL,
+      type: "set-annotations",
+      annotations,
+    });
+  }, [annotations, post]);
+
+  useLayoutEffect(() => {
+    if (!readyRef.current) return;
+    post({
+      channel: HTML_CANVAS_MESSAGE_CHANNEL,
+      type: "set-pick-mode",
+      active: pickMode,
+    });
+  }, [pickMode, post]);
+
+  // Panel-driven focus: emphasize + scroll to the active annotation.
+  useLayoutEffect(() => {
+    if (!readyRef.current) return;
+    post({
+      channel: HTML_CANVAS_MESSAGE_CHANNEL,
+      type: "set-active",
+      id: activeId,
+      scroll: activeId !== null,
+    });
+  }, [activeId, post]);
+
+  // Draft lifecycle: the shim keeps the draft highlight while the composer is
+  // open; clearing happens on the true -> false transition.
+  useLayoutEffect(() => {
+    if (!readyRef.current) return;
+    if (!hasDraft) {
+      post({ channel: HTML_CANVAS_MESSAGE_CHANNEL, type: "clear-draft" });
+    }
+  }, [hasDraft, post]);
+
+  return (
+    <iframe
+      ref={iframeRef}
+      title="Document"
+      // allow-scripts WITHOUT allow-same-origin = null origin = no access to
+      // host cookies/storage/DOM. Do not add allow-same-origin.
+      sandbox="allow-scripts"
+      srcDoc={srcDoc}
+      // Race-free init: by `load` the shim has executed (it sits at the end of
+      // body), so pushing state here delivers even if the one-shot `ready`
+      // was missed. Pushes are idempotent.
+      onLoad={() => {
+        readyRef.current = true;
+        pushState();
+      }}
+      className="h-full w-full border-0 bg-white"
+    />
+  );
+}
diff --git a/packages/ui/src/features/canvas/html/HtmlCanvasBody.tsx b/packages/ui/src/features/canvas/html/HtmlCanvasBody.tsx
new file mode 100644
index 0000000000..67fe6007d5
--- /dev/null
+++ b/packages/ui/src/features/canvas/html/HtmlCanvasBody.tsx
@@ -0,0 +1,226 @@
+import type {
+  HtmlCanvasAnnotation,
+  HtmlCanvasRect,
+} from "@posthog/core/canvas/htmlCanvasSchemas";
+import { Button, Textarea } from "@posthog/quill";
+import {
+  useAddCanvasComment,
+  useCanvasComments,
+} from "@posthog/ui/features/canvas/hooks/useCanvasComments";
+import { useCanvasCommentsStore } from "@posthog/ui/features/canvas/stores/canvasCommentsStore";
+import { logger } from "@posthog/ui/shell/logger";
+import { Box, Flex } from "@radix-ui/themes";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { HtmlArtifactFrame } from "./HtmlArtifactFrame";
+
+const log = logger.scope("html-canvas-body");
+
+const COMPOSER_WIDTH = 320;
+
+// The HTML-artifact canvas body: the sandboxed document plus the peek-style
+// comment affordances — select text → floating "+" → composer, or element
+// pick mode → click → composer. The iframe fills this wrapper, so the shim's
+// viewport rects are wrapper coordinates directly (no offset math).
+export function HtmlCanvasBody({
+  dashboardId,
+  html,
+  canvasVersionId,
+  onOpenThread,
+}: {
+  dashboardId: string;
+  html: string;
+  canvasVersionId?: string;
+  /** Open the given comment thread in the side panel. */
+  onOpenThread: (id: string) => void;
+}) {
+  const pickMode = useCanvasCommentsStore((s) => s.pickMode);
+  const activeCommentId = useCanvasCommentsStore((s) => s.activeCommentId);
+  const draft = useCanvasCommentsStore((s) => s.draft);
+  const setDraft = useCanvasCommentsStore((s) => s.setDraft);
+  const setPickMode = useCanvasCommentsStore((s) => s.setPickMode);
+  const setActiveCommentId = useCanvasCommentsStore(
+    (s) => s.setActiveCommentId,
+  );
+  const setResolved = useCanvasCommentsStore((s) => s.setResolved);
+  const reset = useCanvasCommentsStore((s) => s.reset);
+
+  // Comment state is per-canvas; entering another canvas starts clean.
+  useEffect(() => {
+    reset();
+    return () => reset();
+  }, [reset]);
+
+  const { threads } = useCanvasComments(dashboardId);
+  const { addComment, isAdding } = useAddCanvasComment(dashboardId);
+
+  // Roots with a parseable anchor become paintable annotations (page anchors
+  // resolve trivially and paint nothing; null anchors can't be painted).
+  const annotations = useMemo<HtmlCanvasAnnotation[]>(
+    () =>
+      threads.flatMap((t) =>
+        t.root.anchor
+          ? [{ id: t.root.id, index: t.index, anchor: t.root.anchor }]
+          : [],
+      ),
+    [threads],
+  );
+
+  const onSelection = useCallback(
+    (anchor: HtmlCanvasAnnotation["anchor"], rect: HtmlCanvasRect) => {
+      // A fresh selection replaces any pending affordance, but never an open
+      // composer (typing there must not lose the draft).
+      const current = useCanvasCommentsStore.getState().draft;
+      if (current?.composing) return;
+      setDraft({ anchor, rect, composing: false });
+    },
+    [setDraft],
+  );
+
+  const onSelectionCleared = useCallback(() => {
+    const current = useCanvasCommentsStore.getState().draft;
+    if (current && !current.composing) setDraft(null);
+  }, [setDraft]);
+
+  const onElementPicked = useCallback(
+    (anchor: HtmlCanvasAnnotation["anchor"], rect: HtmlCanvasRect) => {
+      setDraft({ anchor, rect, composing: true });
+      setPickMode(false);
+    },
+    [setDraft, setPickMode],
+  );
+
+  const onMarkerClicked = useCallback(
+    (id: string) => {
+      setActiveCommentId(id);
+      onOpenThread(id);
+    },
+    [setActiveCommentId, onOpenThread],
+  );
+
+  const onAnnotationsResolved = useCallback(
+    (results: { id: string; resolved: boolean }[]) => {
+      setResolved(Object.fromEntries(results.map((r) => [r.id, r.resolved])));
+    },
+    [setResolved],
+  );
+
+  const onError = useCallback((message: string) => {
+    // Shim errors are non-fatal — the document still renders.
+    log.warn("annotation shim error", { message });
+  }, []);
+
+  const submitDraft = useCallback(
+    async (content: string) => {
+      const current = useCanvasCommentsStore.getState().draft;
+      if (!current) return;
+      const created = await addComment({
+        content,
+        anchor: current.anchor,
+        canvasVersionId,
+      });
+      setDraft(null);
+      if (created) setActiveCommentId(created.id);
+    },
+    [addComment, canvasVersionId, setDraft, setActiveCommentId],
+  );
+
+  return (
+    <Box position="relative" className="h-full w-full overflow-hidden">
+      <HtmlArtifactFrame
+        html={html}
+        annotations={annotations}
+        pickMode={pickMode}
+        activeId={activeCommentId}
+        hasDraft={!!draft}
+        onSelection={onSelection}
+        onSelectionCleared={onSelectionCleared}
+        onElementPicked={onElementPicked}
+        onMarkerClicked={onMarkerClicked}
+        onAnnotationsResolved={onAnnotationsResolved}
+        onError={onError}
+      />
+      {draft?.rect && !draft.composing && (
+        <button
+          type="button"
+          aria-label="Comment on selection"
+          onClick={() => setDraft({ ...draft, composing: true })}
+          className="absolute z-30 flex size-7 items-center justify-center rounded-full border border-border bg-primary text-primary-foreground shadow-md transition-transform hover:scale-110"
+          style={{
+            left: `clamp(8px, ${draft.rect.left + draft.rect.width / 2 - 14}px, calc(100% - 36px))`,
+            top: `clamp(8px, ${draft.rect.top - 34}px, calc(100% - 36px))`,
+          }}
+        >
+          <span className="font-semibold text-[15px] leading-none">+</span>
+        </button>
+      )}
+      {draft?.composing && (
+        <DraftComposer
+          rect={draft.rect}
+          isSubmitting={isAdding}
+          onSubmit={submitDraft}
+          onCancel={() => setDraft(null)}
+        />
+      )}
+    </Box>
+  );
+}
+
+// The floating composer card, anchored under the draft's rect (or centered
+// for a rect-less draft). Escape cancels; Cmd/Ctrl+Enter submits.
+function DraftComposer({
+  rect,
+  isSubmitting,
+  onSubmit,
+  onCancel,
+}: {
+  rect: HtmlCanvasRect | null;
+  isSubmitting: boolean;
+  onSubmit: (content: string) => void;
+  onCancel: () => void;
+}) {
+  const [content, setContent] = useState("");
+  const canSubmit = content.trim().length > 0 && !isSubmitting;
+
+  const style = rect
+    ? {
+        left: `clamp(8px, ${rect.left + rect.width / 2 - COMPOSER_WIDTH / 2}px, calc(100% - ${COMPOSER_WIDTH + 8}px))`,
+        top: `clamp(8px, ${rect.top + rect.height + 8}px, calc(100% - 148px))`,
+      }
+    : { left: `calc(50% - ${COMPOSER_WIDTH / 2}px)`, top: "24px" };
+
+  return (
+    <Flex
+      direction="column"
+      gap="2"
+      className="absolute z-30 rounded-lg border border-border bg-card p-2 shadow-lg"
+      style={{ width: COMPOSER_WIDTH, ...style }}
+    >
+      <Textarea
+        autoFocus
+        rows={3}
+        placeholder="Add a comment…"
+        value={content}
+        onChange={(e) => setContent(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === "Escape") onCancel();
+          if (e.key === "Enter" && (e.metaKey || e.ctrlKey) && canSubmit) {
+            onSubmit(content.trim());
+          }
+        }}
+      />
+      <Flex justify="end" gap="2">
+        <Button size="sm" variant="outline" onClick={onCancel}>
+          Cancel
+        </Button>
+        <Button
+          size="sm"
+          variant="primary"
+          disabled={!canSubmit}
+          onClick={() => onSubmit(content.trim())}
+        >
+          {isSubmitting ? "Commenting…" : "Comment"}
+        </Button>
+      </Flex>
+    </Flex>
+  );
+}
diff --git a/packages/ui/src/features/canvas/html/annotationShim.test.ts b/packages/ui/src/features/canvas/html/annotationShim.test.ts
new file mode 100644
index 0000000000..2f47b30952
--- /dev/null
+++ b/packages/ui/src/features/canvas/html/annotationShim.test.ts
@@ -0,0 +1,150 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  ANNOTATION_OVERLAY_ID,
+  buildAnnotationShimScript,
+  buildTextIndex,
+  cssPathFor,
+  labelFor,
+  resolveTextQuote,
+  textQuoteFromSelection,
+} from "./annotationShim";
+
+beforeEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("buildTextIndex", () => {
+  it("collapses whitespace and skips scripts, styles, and the overlay", () => {
+    document.body.innerHTML = [
+      "<p>Hello \n\t  world</p>",
+      "<script>var hidden = 1;</script>",
+      "<style>.x { color: red }</style>",
+      `<div id="${ANNOTATION_OVERLAY_ID}">pin text</div>`,
+      "<p> again </p>",
+    ].join("");
+    const index = buildTextIndex(document, ANNOTATION_OVERLAY_ID);
+    expect(index.text).toBe("Hello world again");
+    expect(index.charNode.length).toBe(index.text.length);
+    expect(index.charOff.length).toBe(index.text.length);
+  });
+});
+
+describe("resolveTextQuote", () => {
+  it("resolves a quote spanning multiple nodes to the exact range", () => {
+    document.body.innerHTML =
+      "<p>Revenue <strong>grew 18%</strong> quarter over quarter.</p>";
+    const index = buildTextIndex(document, ANNOTATION_OVERLAY_ID);
+    const range = resolveTextQuote(
+      document,
+      { type: "text", quote: "grew 18% quarter", prefix: "", suffix: "" },
+      index,
+    );
+    expect(range).not.toBeNull();
+    expect(range?.toString().replace(/\s+/g, " ")).toBe("grew 18% quarter");
+  });
+
+  it("disambiguates repeated quotes by prefix/suffix context", () => {
+    document.body.innerHTML =
+      "<p>alpha target beta</p><p>gamma target delta</p>";
+    const index = buildTextIndex(document, ANNOTATION_OVERLAY_ID);
+    const range = resolveTextQuote(
+      document,
+      { type: "text", quote: "target", prefix: "gamma ", suffix: " delta" },
+      index,
+    );
+    expect(range).not.toBeNull();
+    expect(range?.startContainer.parentElement?.textContent).toBe(
+      "gamma target delta",
+    );
+  });
+
+  it("returns null when the quote no longer exists", () => {
+    document.body.innerHTML = "<p>nothing to see</p>";
+    const index = buildTextIndex(document, ANNOTATION_OVERLAY_ID);
+    expect(
+      resolveTextQuote(
+        document,
+        { type: "text", quote: "vanished", prefix: "", suffix: "" },
+        index,
+      ),
+    ).toBeNull();
+  });
+});
+
+describe("textQuoteFromSelection", () => {
+  it("captures the selected text with normalized context", () => {
+    document.body.innerHTML =
+      "<p>Headline: revenue grew 18% quarter over quarter, driven by expansion.</p>";
+    const textNode = document.querySelector("p")?.firstChild as Text;
+    const start = textNode.data.indexOf("grew 18%");
+    const range = document.createRange();
+    range.setStart(textNode, start);
+    range.setEnd(textNode, start + "grew 18%".length);
+    const selection = window.getSelection();
+    selection?.removeAllRanges();
+    selection?.addRange(range);
+
+    const anchor = textQuoteFromSelection(document, 32, 1000);
+    expect(anchor).toMatchObject({ type: "text", quote: "grew 18%" });
+    expect(anchor?.prefix.endsWith("revenue ")).toBe(true);
+    expect(anchor?.suffix.startsWith(" quarter over")).toBe(true);
+  });
+
+  it("returns null for collapsed and oversized selections", () => {
+    document.body.innerHTML = "<p>short text</p>";
+    window.getSelection()?.removeAllRanges();
+    expect(textQuoteFromSelection(document, 32, 1000)).toBeNull();
+
+    const textNode = document.querySelector("p")?.firstChild as Text;
+    const range = document.createRange();
+    range.setStart(textNode, 0);
+    range.setEnd(textNode, 10);
+    window.getSelection()?.addRange(range);
+    expect(textQuoteFromSelection(document, 32, 3)).toBeNull();
+  });
+});
+
+describe("cssPathFor", () => {
+  it("shortcuts to a unique id", () => {
+    document.body.innerHTML = '<section id="pricing"><p>hi</p></section>';
+    const el = document.querySelector("p") as Element;
+    const section = document.getElementById("pricing") as Element;
+    expect(cssPathFor(section, document)).toBe("#pricing");
+    // The nested element roots its path at the id'd ancestor.
+    expect(cssPathFor(el, document)).toBe("#pricing > p:nth-of-type(1)");
+  });
+
+  it("builds an nth-of-type path that round-trips through querySelector", () => {
+    document.body.innerHTML =
+      "<table><tbody><tr><td>a</td></tr><tr><td>b</td></tr><tr><td>c</td></tr></tbody></table>";
+    const target = document.querySelectorAll("tr")[2] as Element;
+    const selector = cssPathFor(target, document);
+    expect(document.querySelector(selector)).toBe(target);
+  });
+});
+
+describe("labelFor", () => {
+  it("combines the tag with a trimmed text snippet", () => {
+    document.body.innerHTML =
+      "<table><tbody><tr><td>  Enterprise   $1.2M   +8% and lots more text that keeps going on</td></tr></tbody></table>";
+    const label = labelFor(document.querySelector("tr") as Element);
+    expect(label.startsWith("tr — Enterprise $1.2M +8%")).toBe(true);
+    expect(label.length).toBeLessThanOrEqual("tr — ".length + 40);
+  });
+
+  it("falls back to the bare tag for empty elements", () => {
+    document.body.innerHTML = "<hr>";
+    expect(labelFor(document.querySelector("hr") as Element)).toBe("hr");
+  });
+});
+
+describe("buildAnnotationShimScript", () => {
+  it("produces a self-contained script bound to the protocol channel", () => {
+    const script = buildAnnotationShimScript();
+    expect(script).toContain('"posthog-html-canvas"');
+    expect(script).toContain(ANNOTATION_OVERLAY_ID);
+    // Everything must be serialized in — no module imports can survive.
+    expect(script).not.toContain("import ");
+    expect(script).not.toContain("require(");
+  });
+});
diff --git a/packages/ui/src/features/canvas/html/annotationShim.ts b/packages/ui/src/features/canvas/html/annotationShim.ts
new file mode 100644
index 0000000000..162445243c
--- /dev/null
+++ b/packages/ui/src/features/canvas/html/annotationShim.ts
@@ -0,0 +1,653 @@
+// The annotation shim that runs INSIDE an HTML-artifact iframe. It owns
+// everything that must happen in the artifact's own document — text selection
+// capture, element picking, resolving stored anchors back to DOM positions,
+// and painting highlights/pins — and talks to the host exclusively over the
+// postMessage protocol in @posthog/core/canvas/htmlCanvasSchemas.
+//
+// Like sandboxRuntime.ts, the injected script is composed by serializing real
+// functions with `fn.toString()` so the algorithms are unit-testable here in
+// module scope. Two rules keep that safe under bundling/minification:
+//   1. every serialized function is SELF-CONTAINED — it references only its
+//      parameters and browser globals, never another module binding (a
+//      minifier may rename those);
+//   2. functions are handed to the runtime via an explicit `env` object, so
+//      the generated script never depends on the original identifier names.
+
+import type {
+  CommentAnchor,
+  ElementAnchor,
+  HtmlCanvasAnnotation,
+  HtmlCanvasRect,
+  TextQuoteAnchor,
+} from "@posthog/core/canvas/htmlCanvasSchemas";
+import { HTML_CANVAS_MESSAGE_CHANNEL } from "@posthog/core/canvas/htmlCanvasSchemas";
+
+// The overlay layer's element id — also used to exclude the shim's own DOM
+// from text indexing, element picking, and mutation-triggered repaints.
+export const ANNOTATION_OVERLAY_ID = "__ph-canvas-annotations";
+
+// How much normalized context to keep around a text quote. Enough to
+// disambiguate repeats, small enough to keep item_context lean.
+const CONTEXT_CHARS = 32;
+// Selections longer than this are rejected rather than truncated (a truncated
+// quote would silently anchor to the wrong span).
+const MAX_QUOTE_CHARS = 1000;
+
+// The document's visible text, whitespace-collapsed, with a per-character map
+// back to the text node + offset it came from — the search space for
+// text-quote anchors and the bridge from a match back to a DOM Range.
+export interface ShimTextIndex {
+  text: string;
+  nodes: Text[];
+  charNode: number[];
+  charOff: number[];
+}
+
+// Collapse whitespace runs to single spaces and trim — the one normalization
+// both capture and resolution apply, so quotes match the index text.
+export function normalizeText(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+// Build the searchable text index. Walks text nodes in document order,
+// skipping non-content containers and the shim's own overlay, collapsing
+// whitespace as it goes so the result matches `normalizeText` output.
+export function buildTextIndex(
+  doc: Document,
+  overlayId: string,
+): ShimTextIndex {
+  const nodes: Text[] = [];
+  const charNode: number[] = [];
+  const charOff: number[] = [];
+  let text = "";
+  let lastWasSpace = true;
+  const walker = doc.createTreeWalker(doc.body, NodeFilter.SHOW_TEXT, {
+    acceptNode(node) {
+      const parent = node.parentElement;
+      if (!parent) return NodeFilter.FILTER_REJECT;
+      if (parent.closest("script,style,noscript,template"))
+        return NodeFilter.FILTER_REJECT;
+      const overlay = doc.getElementById(overlayId);
+      if (overlay?.contains(parent)) return NodeFilter.FILTER_REJECT;
+      return NodeFilter.FILTER_ACCEPT;
+    },
+  });
+  for (
+    let node = walker.nextNode() as Text | null;
+    node;
+    node = walker.nextNode() as Text | null
+  ) {
+    const nodeIndex = nodes.push(node) - 1;
+    const data = node.data;
+    for (let i = 0; i < data.length; i++) {
+      const ch = data[i] as string;
+      if (/\s/.test(ch)) {
+        if (lastWasSpace) continue;
+        text += " ";
+        lastWasSpace = true;
+      } else {
+        text += ch;
+        lastWasSpace = false;
+      }
+      charNode.push(nodeIndex);
+      charOff.push(i);
+    }
+  }
+  // Drop a trailing collapsed space so the text matches normalizeText output.
+  if (text.endsWith(" ")) {
+    text = text.slice(0, -1);
+    charNode.pop();
+    charOff.pop();
+  }
+  return { text, nodes, charNode, charOff };
+}
+
+// Capture the current selection as a text-quote anchor: the normalized quote
+// plus surrounding context. Returns null for collapsed/empty/oversized
+// selections. `maxQuote`/`contextChars` are parameters (not module consts) so
+// the serialized copy stays self-contained.
+export function textQuoteFromSelection(
+  doc: Document,
+  contextChars: number,
+  maxQuote: number,
+): TextQuoteAnchor | null {
+  // Context keeps boundary whitespace (collapse WITHOUT trim): the index text
+  // has a space between the quote and its neighbors, and trimming it here
+  // would misalign every prefix/suffix character during resolve scoring.
+  const collapse = (value: string) => value.replace(/\s+/g, " ");
+  const sel = doc.getSelection();
+  if (!sel || sel.isCollapsed || sel.rangeCount === 0) return null;
+  const range = sel.getRangeAt(0);
+  const quote = collapse(range.toString()).trim();
+  if (!quote || quote.length > maxQuote) return null;
+  let prefix = "";
+  let suffix = "";
+  try {
+    const before = doc.createRange();
+    before.selectNodeContents(doc.body);
+    before.setEnd(range.startContainer, range.startOffset);
+    prefix = collapse(before.toString()).slice(-contextChars);
+    const after = doc.createRange();
+    after.selectNodeContents(doc.body);
+    after.setStart(range.endContainer, range.endOffset);
+    suffix = collapse(after.toString()).slice(0, contextChars);
+  } catch {
+    // A selection straddling odd boundaries still anchors by quote alone.
+  }
+  return { type: "text", quote, prefix, suffix };
+}
+
+// Resolve a text-quote anchor to a DOM Range using the index. Every occurrence
+// of the quote is scored by how much of the stored prefix/suffix matches
+// around it; the best occurrence wins. Null = orphaned (quote no longer in
+// the document).
+export function resolveTextQuote(
+  doc: Document,
+  anchor: TextQuoteAnchor,
+  index: ShimTextIndex,
+): Range | null {
+  const { text } = index;
+  const quote = anchor.quote;
+  if (!quote) return null;
+  const positions: number[] = [];
+  for (
+    let at = text.indexOf(quote);
+    at !== -1;
+    at = text.indexOf(quote, at + 1)
+  ) {
+    positions.push(at);
+    if (positions.length > 100) break;
+  }
+  if (positions.length === 0) return null;
+  let best = positions[0] as number;
+  if (positions.length > 1) {
+    let bestScore = -1;
+    for (const pos of positions) {
+      let score = 0;
+      const pre = text.slice(Math.max(0, pos - anchor.prefix.length), pos);
+      for (
+        let i = 0;
+        i < pre.length &&
+        pre[pre.length - 1 - i] === anchor.prefix[anchor.prefix.length - 1 - i];
+        i++
+      )
+        score++;
+      const post = text.slice(
+        pos + quote.length,
+        pos + quote.length + anchor.suffix.length,
+      );
+      for (let i = 0; i < post.length && post[i] === anchor.suffix[i]; i++)
+        score++;
+      if (score > bestScore) {
+        bestScore = score;
+        best = pos;
+      }
+    }
+  }
+  const endChar = best + quote.length - 1;
+  const startNode = index.nodes[index.charNode[best] as number];
+  const endNode = index.nodes[index.charNode[endChar] as number];
+  if (!startNode || !endNode) return null;
+  const range = doc.createRange();
+  range.setStart(startNode, index.charOff[best] as number);
+  range.setEnd(endNode, (index.charOff[endChar] as number) + 1);
+  return range;
+}
+
+// A stable-ish CSS selector for an element: its own unique id when it has
+// one, else a tag:nth-of-type path from the nearest uniquely-id'd ancestor
+// (or body), capped in depth.
+export function cssPathFor(el: Element, doc: Document): string {
+  const esc = (value: string) => {
+    const cssGlobal = (
+      globalThis as { CSS?: { escape?: (v: string) => string } }
+    ).CSS;
+    return cssGlobal?.escape
+      ? cssGlobal.escape(value)
+      : value.replace(/([^a-zA-Z0-9_-])/g, "\\$1");
+  };
+  const uniqueId = (candidate: Element) =>
+    candidate.id && doc.querySelectorAll(`#${esc(candidate.id)}`).length === 1;
+  if (uniqueId(el)) return `#${esc(el.id)}`;
+  const segments: string[] = [];
+  let current: Element | null = el;
+  for (let depth = 0; current && current !== doc.body && depth < 12; depth++) {
+    if (uniqueId(current)) {
+      segments.unshift(`#${esc(current.id)}`);
+      return segments.join(" > ");
+    }
+    const tag = current.tagName.toLowerCase();
+    let nth = 1;
+    for (
+      let sibling = current.previousElementSibling;
+      sibling;
+      sibling = sibling.previousElementSibling
+    ) {
+      if (sibling.tagName === current.tagName) nth++;
+    }
+    segments.unshift(`${tag}:nth-of-type(${nth})`);
+    current = current.parentElement;
+  }
+  if (current === doc.body) segments.unshift("body");
+  return segments.join(" > ");
+}
+
+// A human label for an element anchor, shown in the panel even when the
+// selector no longer resolves: the tag plus a trimmed text snippet.
+export function labelFor(el: Element): string {
+  const tag = el.tagName.toLowerCase();
+  const text = (el.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 40);
+  return text ? `${tag} — ${text}` : tag;
+}
+
+// The environment handed to the serialized runtime: the channel stamp, tuning
+// constants, and the algorithms above (as generated-scope bindings).
+interface ShimEnv {
+  channel: string;
+  overlayId: string;
+  contextChars: number;
+  maxQuote: number;
+  buildTextIndex: typeof buildTextIndex;
+  textQuoteFromSelection: typeof textQuoteFromSelection;
+  resolveTextQuote: typeof resolveTextQuote;
+  cssPathFor: typeof cssPathFor;
+  labelFor: typeof labelFor;
+}
+
+// The shim runtime. Serialized wholesale into the artifact document, so it
+// references only `env`, its own locals, and browser globals. Runs from the
+// end of <body>, so the artifact DOM above is parsed when it starts.
+function annotationShimMain(env: ShimEnv): void {
+  const doc = document;
+  const post = (msg: Record<string, unknown>) => {
+    window.parent.postMessage({ channel: env.channel, ...msg }, "*");
+  };
+  const toRect = (rect: DOMRect): HtmlCanvasRect => ({
+    top: rect.top,
+    left: rect.left,
+    width: rect.width,
+    height: rect.height,
+  });
+
+  let annotations: HtmlCanvasAnnotation[] = [];
+  let activeId: string | null = null;
+  let pickMode = false;
+  let draftRange: Range | null = null;
+  let draftElement: Element | null = null;
+  let hadSelection = false;
+
+  const overlay = doc.createElement("div");
+  overlay.id = env.overlayId;
+  overlay.style.cssText =
+    "position:absolute;top:0;left:0;width:0;height:0;overflow:visible;pointer-events:none;z-index:2147483000;";
+  const hoverBox = doc.createElement("div");
+  hoverBox.style.cssText =
+    "position:absolute;display:none;pointer-events:none;border:2px solid rgba(79,70,229,.9);background:rgba(79,70,229,.08);border-radius:3px;";
+  const pickCursorStyle = doc.createElement("style");
+  pickCursorStyle.textContent = "* { cursor: crosshair !important; }";
+
+  const ensureOverlay = () => {
+    // Re-append if artifact JS replaced/clobbered the body contents.
+    if (!overlay.isConnected) doc.body.appendChild(overlay);
+    return overlay;
+  };
+
+  const boxIn = (host: Element, rect: DOMRect, css: string) => {
+    const el = doc.createElement("div");
+    el.style.cssText = `position:absolute;pointer-events:none;left:${rect.left + window.scrollX}px;top:${rect.top + window.scrollY}px;width:${rect.width}px;height:${rect.height}px;${css}`;
+    host.appendChild(el);
+    return el;
+  };
+
+  const pinAt = (host: Element, rect: DOMRect, id: string, index: number) => {
+    const pin = doc.createElement("button");
+    pin.type = "button";
+    pin.textContent = String(index);
+    const left = Math.max(2, rect.left + window.scrollX - 22);
+    const top = Math.max(2, rect.top + window.scrollY - 8);
+    pin.style.cssText = `position:absolute;pointer-events:auto;cursor:pointer;left:${left}px;top:${top}px;width:18px;height:18px;border-radius:9999px;border:2px solid #fff;background:${id === activeId ? "#312e81" : "#4f46e5"};color:#fff;font:700 10px/14px ui-sans-serif,system-ui,sans-serif;text-align:center;padding:0;box-shadow:0 1px 3px rgba(0,0,0,.35);`;
+    pin.addEventListener("click", (event) => {
+      event.preventDefault();
+      event.stopPropagation();
+      activeId = id;
+      schedulePaint();
+      post({
+        type: "marker-clicked",
+        id,
+        rect: toRect(pin.getBoundingClientRect()),
+      });
+    });
+    host.appendChild(pin);
+  };
+
+  const drawRange = (
+    host: Element,
+    range: Range,
+    active: boolean,
+    isDraft: boolean,
+  ) => {
+    const fill = isDraft
+      ? "background:rgba(79,70,229,.18);"
+      : active
+        ? "background:rgba(245,158,11,.45);"
+        : "background:rgba(245,158,11,.28);";
+    const rects = range.getClientRects();
+    for (let i = 0; i < rects.length; i++) {
+      const rect = rects[i] as DOMRect;
+      if (rect.width === 0 && rect.height === 0) continue;
+      boxIn(host, rect, `${fill}border-radius:2px;`);
+    }
+  };
+
+  const drawElementBox = (
+    host: Element,
+    el: Element,
+    active: boolean,
+    isDraft: boolean,
+  ) => {
+    const style = isDraft
+      ? "border:2px dashed rgba(79,70,229,.9);background:rgba(79,70,229,.08);"
+      : active
+        ? "border:2px solid rgba(245,158,11,1);background:rgba(245,158,11,.14);"
+        : "border:2px solid rgba(245,158,11,.75);";
+    boxIn(host, el.getBoundingClientRect(), `${style}border-radius:3px;`);
+  };
+
+  const resolveElement = (selector: string): Element | null => {
+    try {
+      const el = doc.querySelector(selector);
+      return el && !overlay.contains(el) && el !== overlay ? el : null;
+    } catch {
+      return null;
+    }
+  };
+
+  const paint = () => {
+    const host = ensureOverlay();
+    while (host.firstChild) host.removeChild(host.firstChild);
+    let index: ReturnType<typeof env.buildTextIndex> | null = null;
+    const getIndex = () => {
+      if (!index) index = env.buildTextIndex(doc, env.overlayId);
+      return index;
+    };
+    const results: Array<{
+      id: string;
+      resolved: boolean;
+      rect?: HtmlCanvasRect;
+    }> = [];
+    for (const annotation of annotations) {
+      const anchor = annotation.anchor;
+      if (anchor.type === "page") {
+        results.push({ id: annotation.id, resolved: true });
+        continue;
+      }
+      if (anchor.type === "text") {
+        const range = env.resolveTextQuote(doc, anchor, getIndex());
+        if (!range) {
+          results.push({ id: annotation.id, resolved: false });
+          continue;
+        }
+        drawRange(host, range, annotation.id === activeId, false);
+        pinAt(
+          host,
+          range.getBoundingClientRect(),
+          annotation.id,
+          annotation.index,
+        );
+        results.push({
+          id: annotation.id,
+          resolved: true,
+          rect: toRect(range.getBoundingClientRect()),
+        });
+        continue;
+      }
+      const el = resolveElement(anchor.selector);
+      if (!el) {
+        results.push({ id: annotation.id, resolved: false });
+        continue;
+      }
+      drawElementBox(host, el, annotation.id === activeId, false);
+      pinAt(host, el.getBoundingClientRect(), annotation.id, annotation.index);
+      results.push({
+        id: annotation.id,
+        resolved: true,
+        rect: toRect(el.getBoundingClientRect()),
+      });
+    }
+    if (draftRange) drawRange(host, draftRange, false, true);
+    if (draftElement?.isConnected)
+      drawElementBox(host, draftElement, false, true);
+    host.appendChild(hoverBox);
+    post({ type: "annotations-resolved", results });
+  };
+
+  let paintTimer: ReturnType<typeof setTimeout> | undefined;
+  const schedulePaint = () => {
+    clearTimeout(paintTimer);
+    paintTimer = setTimeout(() => {
+      try {
+        paint();
+      } catch (err) {
+        post({
+          type: "error",
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }, 120);
+  };
+
+  // Selection capture — always live (no mode). Debounced so we report settled
+  // selections, not every drag tick. The captured range is kept as the draft
+  // so the highlight survives the selection collapsing when the host composer
+  // takes focus; the host clears it with `clear-draft`.
+  let selectionTimer: ReturnType<typeof setTimeout> | undefined;
+  doc.addEventListener("selectionchange", () => {
+    clearTimeout(selectionTimer);
+    selectionTimer = setTimeout(() => {
+      if (pickMode) return;
+      const sel = doc.getSelection();
+      if (!sel || sel.isCollapsed || sel.rangeCount === 0) {
+        if (hadSelection) {
+          hadSelection = false;
+          post({ type: "selection-cleared" });
+        }
+        return;
+      }
+      const anchor = env.textQuoteFromSelection(
+        doc,
+        env.contextChars,
+        env.maxQuote,
+      );
+      if (!anchor) return;
+      hadSelection = true;
+      draftRange = sel.getRangeAt(0).cloneRange();
+      schedulePaint();
+      post({
+        type: "selection",
+        anchor,
+        rect: toRect(sel.getRangeAt(0).getBoundingClientRect()),
+      });
+    }, 200);
+  });
+
+  // Element pick mode: hover outline + capture-phase click.
+  doc.addEventListener(
+    "mouseover",
+    (event) => {
+      if (!pickMode) return;
+      const target = event.target;
+      if (
+        !(target instanceof Element) ||
+        overlay.contains(target) ||
+        target === doc.body ||
+        target === doc.documentElement
+      ) {
+        hoverBox.style.display = "none";
+        return;
+      }
+      const rect = target.getBoundingClientRect();
+      hoverBox.style.display = "block";
+      hoverBox.style.left = `${rect.left + window.scrollX}px`;
+      hoverBox.style.top = `${rect.top + window.scrollY}px`;
+      hoverBox.style.width = `${rect.width}px`;
+      hoverBox.style.height = `${rect.height}px`;
+    },
+    true,
+  );
+  doc.addEventListener(
+    "click",
+    (event) => {
+      if (!pickMode) return;
+      event.preventDefault();
+      event.stopPropagation();
+      const target = event.target;
+      if (
+        !(target instanceof Element) ||
+        overlay.contains(target) ||
+        target === doc.body ||
+        target === doc.documentElement
+      )
+        return;
+      draftElement = target;
+      draftRange = null;
+      hoverBox.style.display = "none";
+      const anchor: ElementAnchor = {
+        type: "element",
+        selector: env.cssPathFor(target, doc),
+        label: env.labelFor(target),
+      };
+      schedulePaint();
+      post({
+        type: "element-picked",
+        anchor,
+        rect: toRect(target.getBoundingClientRect()),
+      });
+    },
+    true,
+  );
+
+  // Repaint when the document reflows or mutates (ignoring our own overlay).
+  window.addEventListener("resize", schedulePaint);
+  const observer = new MutationObserver((records) => {
+    for (const record of records) {
+      const target = record.target;
+      if (
+        target === overlay ||
+        (target instanceof Node && overlay.contains(target)) ||
+        target === pickCursorStyle
+      )
+        continue;
+      schedulePaint();
+      return;
+    }
+  });
+  observer.observe(doc.documentElement, {
+    childList: true,
+    subtree: true,
+    characterData: true,
+    attributes: true,
+  });
+
+  const scrollToAnnotation = (id: string) => {
+    const annotation = annotations.find((a) => a.id === id);
+    if (!annotation) return;
+    const anchor: CommentAnchor = annotation.anchor;
+    if (anchor.type === "text") {
+      const range = env.resolveTextQuote(
+        doc,
+        anchor,
+        env.buildTextIndex(doc, env.overlayId),
+      );
+      const el = range?.startContainer.parentElement;
+      el?.scrollIntoView({ block: "center", behavior: "smooth" });
+    } else if (anchor.type === "element") {
+      resolveElement(anchor.selector)?.scrollIntoView({
+        block: "center",
+        behavior: "smooth",
+      });
+    }
+  };
+
+  window.addEventListener("message", (event) => {
+    if (event.source !== window.parent) return;
+    const data = event.data as Record<string, unknown> | null;
+    if (!data || data.channel !== env.channel) return;
+    try {
+      switch (data.type) {
+        case "set-annotations":
+          annotations = Array.isArray(data.annotations)
+            ? (data.annotations as HtmlCanvasAnnotation[])
+            : [];
+          schedulePaint();
+          break;
+        case "set-pick-mode": {
+          const active = data.active === true;
+          if (active === pickMode) break;
+          pickMode = active;
+          if (active) {
+            doc.head.appendChild(pickCursorStyle);
+          } else {
+            pickCursorStyle.remove();
+            hoverBox.style.display = "none";
+          }
+          break;
+        }
+        case "set-active":
+          activeId = typeof data.id === "string" ? data.id : null;
+          schedulePaint();
+          if (data.scroll === true && activeId) scrollToAnnotation(activeId);
+          break;
+        case "clear-draft":
+          draftRange = null;
+          draftElement = null;
+          schedulePaint();
+          break;
+      }
+    } catch (err) {
+      post({
+        type: "error",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  });
+
+  ensureOverlay();
+  post({ type: "ready" });
+}
+
+// Compose the injectable script. Every helper is bound to a fresh, literal
+// name in the generated scope and handed to the runtime through `env`, so the
+// output is immune to bundler identifier renaming.
+export function buildAnnotationShimScript(): string {
+  return `;(() => {
+  "use strict";
+  const __phBuildTextIndex = ${buildTextIndex.toString()};
+  const __phTextQuoteFromSelection = ${textQuoteFromSelection.toString()};
+  const __phResolveTextQuote = ${resolveTextQuote.toString()};
+  const __phCssPathFor = ${cssPathFor.toString()};
+  const __phLabelFor = ${labelFor.toString()};
+  const __phMain = ${annotationShimMain.toString()};
+  try {
+    __phMain({
+      channel: ${JSON.stringify(HTML_CANVAS_MESSAGE_CHANNEL)},
+      overlayId: ${JSON.stringify(ANNOTATION_OVERLAY_ID)},
+      contextChars: ${CONTEXT_CHARS},
+      maxQuote: ${MAX_QUOTE_CHARS},
+      buildTextIndex: __phBuildTextIndex,
+      textQuoteFromSelection: __phTextQuoteFromSelection,
+      resolveTextQuote: __phResolveTextQuote,
+      cssPathFor: __phCssPathFor,
+      labelFor: __phLabelFor,
+    });
+  } catch (err) {
+    window.parent.postMessage(
+      {
+        channel: ${JSON.stringify(HTML_CANVAS_MESSAGE_CHANNEL)},
+        type: "error",
+        message: err instanceof Error ? err.message : String(err),
+      },
+      "*",
+    );
+  }
+})();`;
+}
diff --git a/packages/ui/src/features/canvas/html/htmlSandbox.test.ts b/packages/ui/src/features/canvas/html/htmlSandbox.test.ts
new file mode 100644
index 0000000000..e715515a23
--- /dev/null
+++ b/packages/ui/src/features/canvas/html/htmlSandbox.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { buildHtmlArtifactDocument } from "./htmlSandbox";
+
+const CSP_MARKER = '<meta http-equiv="Content-Security-Policy"';
+
+describe("buildHtmlArtifactDocument", () => {
+  it("injects the CSP after <head> and the shim before </body>", () => {
+    const html =
+      "<!doctype html><html><head><title>R</title></head><body><p>hi</p></body></html>";
+    const doc = buildHtmlArtifactDocument(html);
+    expect(doc.indexOf(CSP_MARKER)).toBe(
+      doc.indexOf("<head>") + "<head>".length,
+    );
+    const shimAt = doc.indexOf("<script>");
+    expect(shimAt).toBeGreaterThan(doc.indexOf("<p>hi</p>"));
+    expect(doc.indexOf("</body>")).toBeGreaterThan(shimAt);
+  });
+
+  it("handles case-insensitive tags and head attributes", () => {
+    const html =
+      '<HTML><HEAD lang="en"><TITLE>R</TITLE></HEAD><BODY>x</BODY></HTML>';
+    const doc = buildHtmlArtifactDocument(html);
+    expect(doc.indexOf(CSP_MARKER)).toBe(
+      doc.indexOf('<HEAD lang="en">') + '<HEAD lang="en">'.length,
+    );
+    expect(doc.indexOf("<script>")).toBeLessThan(doc.indexOf("</BODY>"));
+  });
+
+  it("creates a head when only <html> exists and appends the shim without </body>", () => {
+    const doc = buildHtmlArtifactDocument("<html><p>frag</p></html>");
+    expect(doc).toContain(`<html><head>${CSP_MARKER}`);
+    expect(doc.endsWith("</script>")).toBe(true);
+  });
+
+  it("prepends the CSP to a bare fragment", () => {
+    const doc = buildHtmlArtifactDocument("<p>frag</p>");
+    expect(doc.startsWith(CSP_MARKER)).toBe(true);
+    expect(doc.endsWith("</script>")).toBe(true);
+  });
+
+  it("injects before the LAST </body> so an inline code sample can't hijack placement", () => {
+    const html =
+      "<html><head></head><body><pre>&lt;/body&gt;</pre><p>real</p></body></html>";
+    const doc = buildHtmlArtifactDocument(html);
+    const shimAt = doc.indexOf("<script>");
+    expect(shimAt).toBeGreaterThan(doc.indexOf("<p>real</p>"));
+  });
+
+  it("leaves the artifact bytes otherwise untouched", () => {
+    const html =
+      '<!doctype html><html><head><meta charset="utf-8"></head><body><p>précis &amp; more</p></body></html>';
+    const doc = buildHtmlArtifactDocument(html);
+    const stripped = doc
+      .replace(/<meta http-equiv="Content-Security-Policy"[^>]*>/, "")
+      .replace(/<script>[\s\S]*<\/script>/, "");
+    expect(stripped).toBe(html);
+  });
+
+  it("locks down network access in the CSP", () => {
+    const doc = buildHtmlArtifactDocument("<html><body>x</body></html>");
+    const csp = doc.match(/content="([^"]+)"/)?.[1] ?? "";
+    expect(csp).toContain("default-src 'none'");
+    expect(csp).toContain("script-src 'unsafe-inline'");
+    expect(csp).not.toContain("connect-src");
+  });
+});
diff --git a/packages/ui/src/features/canvas/html/htmlSandbox.ts b/packages/ui/src/features/canvas/html/htmlSandbox.ts
new file mode 100644
index 0000000000..2fcc9de99e
--- /dev/null
+++ b/packages/ui/src/features/canvas/html/htmlSandbox.ts
@@ -0,0 +1,52 @@
+import { buildAnnotationShimScript } from "./annotationShim";
+
+// Composes the srcDoc for an HTML-artifact iframe. The frame itself is
+// mounted with sandbox="allow-scripts" and NO allow-same-origin (null origin
+// — no host cookies/storage/DOM), and this adds the two document-level
+// pieces: a locked-down CSP and the annotation shim.
+//
+// The artifact bytes are otherwise untouched: both injections are plain
+// string splices (never a parse/re-serialize round trip, which could alter
+// the document the agent authored).
+
+// No connect-src / script-src URLs / frame-src → fetch()/XHR, external
+// scripts, and nested frames are all blocked; inline script+style keep the
+// self-contained document (and the shim) working. https images/fonts stay
+// allowed so a pasted-in document with a remote logo doesn't hard-break.
+const HTML_ARTIFACT_CSP =
+  "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob: https:; font-src data: https:; media-src data: blob:; form-action 'none'";
+
+const CSP_META_TAG = `<meta http-equiv="Content-Security-Policy" content="${HTML_ARTIFACT_CSP}">`;
+
+export function buildHtmlArtifactDocument(html: string): string {
+  let doc = html;
+
+  // CSP first, as early in <head> as possible (a meta CSP only governs what
+  // is parsed after it). No <head>? Splice one in after <html>; no <html>
+  // either? Prepend — browsers hoist the meta into the synthesized head.
+  const headOpen = doc.match(/<head(\s[^>]*)?>/i);
+  if (headOpen && headOpen.index !== undefined) {
+    const at = headOpen.index + headOpen[0].length;
+    doc = `${doc.slice(0, at)}${CSP_META_TAG}${doc.slice(at)}`;
+  } else {
+    const htmlOpen = doc.match(/<html(\s[^>]*)?>/i);
+    if (htmlOpen && htmlOpen.index !== undefined) {
+      const at = htmlOpen.index + htmlOpen[0].length;
+      doc = `${doc.slice(0, at)}<head>${CSP_META_TAG}</head>${doc.slice(at)}`;
+    } else {
+      doc = `${CSP_META_TAG}${doc}`;
+    }
+  }
+
+  // The annotation shim goes at the END of <body> so the artifact DOM above it
+  // is parsed when the shim runs (it posts `ready` immediately).
+  const shimTag = `<script>${buildAnnotationShimScript()}</script>`;
+  const bodyClose = doc.match(/<\/body\s*>(?![\s\S]*<\/body\s*>)/i);
+  if (bodyClose && bodyClose.index !== undefined) {
+    doc = `${doc.slice(0, bodyClose.index)}${shimTag}${doc.slice(bodyClose.index)}`;
+  } else {
+    doc = `${doc}${shimTag}`;
+  }
+
+  return doc;
+}
diff --git a/packages/ui/src/features/canvas/stores/canvasCommentsStore.ts b/packages/ui/src/features/canvas/stores/canvasCommentsStore.ts
new file mode 100644
index 0000000000..c9d8850c28
--- /dev/null
+++ b/packages/ui/src/features/canvas/stores/canvasCommentsStore.ts
@@ -0,0 +1,51 @@
+import type {
+  CommentAnchor,
+  HtmlCanvasRect,
+} from "@posthog/core/canvas/htmlCanvasSchemas";
+import { create } from "zustand";
+
+// A pending comment: the anchor captured in the document plus where its
+// affordance/composer should sit (iframe-viewport coords, null for the
+// page-level composer which lives in the panel). `composing` flips when the
+// user clicks the affordance and the composer opens.
+export interface CanvasCommentDraft {
+  anchor: CommentAnchor;
+  rect: HtmlCanvasRect | null;
+  composing: boolean;
+}
+
+// View state for HTML-canvas commenting: which panel tab is showing, element
+// pick mode, the emphasized thread, the pending draft, and which anchors
+// resolved on the last shim repaint. State only — persistence and threading
+// live in CanvasCommentsService.
+interface CanvasCommentsState {
+  panelTab: "main" | "comments";
+  pickMode: boolean;
+  activeCommentId: string | null;
+  draft: CanvasCommentDraft | null;
+  resolved: Record<string, boolean>;
+  setPanelTab: (tab: "main" | "comments") => void;
+  setPickMode: (active: boolean) => void;
+  setActiveCommentId: (id: string | null) => void;
+  setDraft: (draft: CanvasCommentDraft | null) => void;
+  setResolved: (resolved: Record<string, boolean>) => void;
+  reset: () => void;
+}
+
+const initialState = {
+  panelTab: "main" as const,
+  pickMode: false,
+  activeCommentId: null,
+  draft: null,
+  resolved: {},
+};
+
+export const useCanvasCommentsStore = create<CanvasCommentsState>((set) => ({
+  ...initialState,
+  setPanelTab: (panelTab) => set({ panelTab }),
+  setPickMode: (pickMode) => set({ pickMode }),
+  setActiveCommentId: (activeCommentId) => set({ activeCommentId }),
+  setDraft: (draft) => set({ draft }),
+  setResolved: (resolved) => set({ resolved }),
+  reset: () => set(initialState),
+}));