feat(comments): canvas commenting and historical version replay

products/desktop/packages/api-client/src/generated.ts

@@ -4366,7 +4366,7 @@ export namespace Schemas {
   export type ColorMode = "light" | "dark";
   export type Comment = {
     id: string;
-    created_by: UserBasic & unknown;
+    created_by: (UserBasic & unknown) | null;
     deleted?: (boolean | null) | undefined;
     mentions?: Array<number> | undefined;
     slug?: string | undefined;
@@ -4375,9 +4375,10 @@ export namespace Schemas {
     version: number;
     created_at: string;
     item_id?: (string | null) | undefined;
-    item_context?: null | undefined;
+    item_context?: unknown;
     scope: string;
     source_comment?: (string | null) | undefined;
+    completed_at?: (string | null) | undefined;
   };
   export type CompareItem = { label: string; value: string };
   export type ConclusionEnum = "won" | "lost" | "inconclusive" | "stopped_early" | "invalid";
@@ -18454,7 +18455,7 @@ export namespace Endpoints {
     path: "/api/projects/{project_id}/comments/";
     requestFormat: "json";
     parameters: {
-      query: Partial<{ cursor: string; item_id: string; scope: string; search: string; source_comment: string }>;
+      query: Partial<{ cursor: string; item_id: string; task_id: string; scope: string; search: string; source_comment: string }>;
       path: { project_id: string };
     };
     responses: { 200: Schemas.PaginatedCommentList };

products/desktop/packages/api-client/src/posthog-client.ts

@@ -209,6 +209,29 @@ export interface TaskSessionStorageAccess {
   content_sha256: string | null;
 }
 
+/**
+ * The commentable resources this client knows how to address. `scope` is a
+ * free-form column on the backend `Comment` model, so adding a resource is a
+ * new member here plus a caller — no migration and no endpoint.
+ */
+export type CommentScope = "task_artifact" | "desktop_canvas" | "task";
+
+/** Named `Resource*` so it never collides with the DOM's global `Comment`.
+ * Optimistic rows do not have a server version yet, while item_context is a
+ * real JSON value despite the generated serializer's historically narrow type. */
+export type ResourceComment = Omit<Schemas.Comment, "version"> & {
+  version?: number;
+};
+
+export interface CreateResourceCommentRequest {
+  scope: CommentScope;
+  itemId: string;
+  content: string;
+  context: unknown;
+  sourceCommentId?: string;
+  mentions?: number[];
+}
+
 /** Thrown when the backend rejects a cloud run with a 429 usage-limit error. */
 export class CloudUsageLimitError extends Error {
   limitType: UsageLimitType;
@@ -2708,8 +2731,7 @@ export class PostHogAPIClient {
     return (await response.json()) as TaskMention[];
   }
 
-  // Tasks the current user is involved in (created, mentioned, or messaged),
-  // one row per task, newest activity first.
+  // Task lifecycle and individual comment activity, newest first.
   async getTaskActivity(options?: {
     before?: string;
     beforeId?: string;
@@ -2732,8 +2754,7 @@ export class PostHogAPIClient {
     return (await response.json()) as TaskActivityPage;
   }
 
-  // Read state is per task, so callers name the tasks the user has seen rather than
-  // clearing the whole feed.
+  // Task lifecycle activity clears by task timestamp; comment activity clears by row id.
   async markTaskActivityRead(
     activities: TaskActivityReadMarker[],
   ): Promise<TaskActivityMarkReadResult> {
@@ -3227,6 +3248,54 @@ export class PostHogAPIClient {
     return data.url;
   }
 
+  async getResourceComments(
+    scope: CommentScope,
+    itemId: string,
+    taskId: string,
+  ): Promise<ResourceComment[]> {
+    const MAX_COMMENT_PAGES = 50;
+    const teamId = await this.getTeamId();
+    const comments: ResourceComment[] = [];
+    let cursor: string | undefined;
+    for (let pageIndex = 0; pageIndex < MAX_COMMENT_PAGES; pageIndex++) {
+      const page = await this.api.get("/api/projects/{project_id}/comments/", {
+        path: { project_id: String(teamId) },
+        query: { scope, item_id: itemId, task_id: taskId, cursor },
+      });
+      comments.push(...page.results);
+      cursor = page.next
+        ? (new URL(page.next).searchParams.get("cursor") ?? undefined)
+        : undefined;
+      if (!cursor) return comments;
+    }
+    log.warn(
+      `getResourceComments hit MAX_PAGES (${MAX_COMMENT_PAGES}); returning partial results`,
+      { scope, itemId, returned: comments.length },
+    );
+    return comments;
+  }
+
+  async createResourceComment(
+    request: CreateResourceCommentRequest,
+  ): Promise<ResourceComment> {
+    const teamId = await this.getTeamId();
+    const payload = {
+      content: request.content,
+      scope: request.scope,
+      item_id: request.itemId,
+      item_context: request.context,
+      source_comment: request.sourceCommentId ?? null,
+      mentions: request.mentions ?? [],
+      // Resolution is represented by a thread-state reply so this stays on the
+      // same PAT-compatible write path as ordinary comments.
+      is_task: false,
+    };
+    return await this.api.post("/api/projects/{project_id}/comments/", {
+      path: { project_id: String(teamId) },
+      body: payload as unknown as Schemas.Comment,
+    });
+  }
+
   async getTaskSessionStorageAccess(
     taskId: string,
     runId: string,

products/desktop/packages/core/src/canvas/canvasBuildSchemas.test.ts

@@ -4,6 +4,7 @@ import {
   type CanvasBuildRecord,
   currentHeadBuildFailure,
   hasActiveCanvasBuild,
+  historicalCanvasBuild,
   latestFinishedCanvasBuild,
   publishedCanvasBuild,
 } from "./canvasBuildSchemas";
@@ -74,6 +75,32 @@ describe("canvas build lifecycle", () => {
     expect(publishedCanvasBuild(value)).toBe(ready);
   });
 
+  it("selects a retained ready artifact for a historical version", () => {
+    const ready = build("historical", "ready");
+    ready.sourceVersionId = "version-1";
+
+    expect(
+      historicalCanvasBuild(
+        lifecycle([build("latest", "ready"), ready]),
+        "version-1",
+      ),
+    ).toBe(ready);
+  });
+
+  it.each([
+    ["an unfinished build", build("historical", "building")],
+    [
+      "a ready build without a retained artifact",
+      { ...build("historical", "ready"), artifactUrl: null },
+    ],
+  ])("rejects %s for a historical version", (_name, candidate) => {
+    candidate.sourceVersionId = "version-1";
+
+    expect(
+      historicalCanvasBuild(lifecycle([candidate]), "version-1"),
+    ).toBeNull();
+  });
+
   it("surfaces a failed build of the current head even when an older published build is also ready", () => {
     // b_old (sv-old) is the pinned/published live build; a newer publish (b_new,
     // sv-new = current head) failed. latestFinishedCanvasBuild returns the first
@@ -136,7 +163,7 @@ describe("canvas build lifecycle", () => {
       },
     } as unknown as ProjectApiClient);
 
-    const result = await service.getBuilds("canvas-1");
+    const result = await service.getBuilds({ id: "canvas-1" });
 
     expect(result.publishedBuildId).toBe("b0");
     expect(result.builds[0]).toMatchObject({

products/desktop/packages/core/src/canvas/canvasBuildSchemas.ts

@@ -42,6 +42,20 @@ export function publishedCanvasBuild(
   );
 }
 
+export function historicalCanvasBuild(
+  lifecycle: CanvasBuildLifecycle,
+  versionId: string,
+): CanvasBuildRecord | null {
+  return (
+    lifecycle.builds.find(
+      (build) =>
+        build.sourceVersionId === versionId &&
+        build.buildStatus === "ready" &&
+        !!build.artifactUrl,
+    ) ?? null
+  );
+}
+
 export const canvasBuildLifecycleSchema = z.object({
   /** The live (last successful, still-eligible) build, null until one completes. */
   publishedBuildId: z.string().nullable(),

products/desktop/packages/core/src/canvas/dashboardSchemas.ts

@@ -73,6 +73,11 @@ export const createDashboardInput = z.object({
 
 export const dashboardIdInput = z.object({ id: z.string().min(1) });
 
+export const canvasBuildsInput = z.object({
+  id: z.string().min(1),
+  versionId: z.string().min(1).optional(),
+});
+
 export const canvasSourceInput = z.object({
   id: z.string().min(1),
   // Read a historical version's files instead of the head.

products/desktop/packages/core/src/canvas/dashboardsService.test.ts

@@ -77,7 +77,7 @@ describe("DashboardsService.list", () => {
 describe("DashboardsService.getBuilds", () => {
   it("normalizes the lifecycle payload", async () => {
     const { api } = fakeApi({
-      "canvases/c1/builds/": {
+      "canvases/c1/builds/?version_id=v1": {
         published_build_id: "b1",
         current_version_id: "v1",
         builds: [
@@ -97,7 +97,7 @@ describe("DashboardsService.getBuilds", () => {
     });
     const service = new DashboardsService(api);
 
-    const lifecycle = await service.getBuilds("c1");
+    const lifecycle = await service.getBuilds({ id: "c1", versionId: "v1" });
 
     expect(lifecycle.publishedBuildId).toBe("b1");
     expect(lifecycle.currentVersionId).toBe("v1");

products/desktop/packages/core/src/canvas/dashboardsService.ts

@@ -258,12 +258,21 @@ export class DashboardsService {
 
   // Read a canvas's build lifecycle (pointers + recent builds). Publishing
   // queues a build server-side; callers poll this until it settles.
-  async getBuilds(id: string): Promise<CanvasBuildLifecycle> {
+  async getBuilds(input: {
+    id: string;
+    versionId?: string;
+  }): Promise<CanvasBuildLifecycle> {
+    const suffix = input.versionId
+      ? `?version_id=${encodeURIComponent(input.versionId)}`
+      : "";
     const body = await this.api.json<{
       published_build_id: string | null;
       current_version_id: string | null;
       builds: Record<string, unknown>[];
-    }>(`canvases/${encodeURIComponent(id)}/builds/`, "load canvas builds");
+    }>(
+      `canvases/${encodeURIComponent(input.id)}/builds/${suffix}`,
+      "load canvas builds",
+    );
     // Each build row is already validated by tryToBuildRecord; this endpoint is
     // polled every couple of seconds during builds, so don't re-run the whole
     // lifecycle schema (which would zod-parse every record a second time).

products/desktop/packages/core/src/canvas/freeformSchemas.test.ts

@@ -1,7 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { canvasToHostMessageSchema } from "./freeformSchemas";
+import {
+  canvasToHostMessageSchema,
+  hostToCanvasMessageSchema,
+  limitCanvasCommentHighlights,
+} from "./freeformSchemas";
 
-describe("canvasToHostMessageSchema open-external", () => {
+describe("canvasToHostMessageSchema", () => {
   const message = (url: string) => ({
     channel: "posthog-canvas",
     type: "open-external",
@@ -32,4 +36,109 @@ describe("canvasToHostMessageSchema open-external", () => {
       false,
     );
   });
+
+  it("accepts a bounded text selection and rejects oversized selected text", () => {
+    const selection = {
+      channel: "posthog-canvas",
+      type: "text-selection",
+      selection: {
+        quote: "selected text",
+        prefix: "before ",
+        suffix: " after",
+        start: 7,
+        end: 20,
+        rect: { top: 10, right: 80, bottom: 30, left: 20 },
+      },
+    };
+
+    expect(canvasToHostMessageSchema.safeParse(selection).success).toBe(true);
+    expect(
+      canvasToHostMessageSchema.safeParse({
+        ...selection,
+        selection: { ...selection.selection, quote: "x".repeat(10_001) },
+      }).success,
+    ).toBe(false);
+  });
+
+  it("accepts an explicit selection-cleared event", () => {
+    expect(
+      canvasToHostMessageSchema.safeParse({
+        channel: "posthog-canvas",
+        type: "text-selection-cleared",
+      }).success,
+    ).toBe(true);
+  });
+
+  it("accepts a bounded comment activation", () => {
+    expect(
+      canvasToHostMessageSchema.safeParse({
+        channel: "posthog-canvas",
+        type: "comment-activate",
+        id: "comment-1",
+      }).success,
+    ).toBe(true);
+  });
+
+  it("accepts bounded comment highlights", () => {
+    expect(
+      hostToCanvasMessageSchema.safeParse({
+        channel: "posthog-canvas",
+        type: "set-comment-highlights",
+        highlights: [
+          {
+            id: "comment-1",
+            active: false,
+            anchor: {
+              quote: "selected text",
+              prefix: "before ",
+              suffix: " after",
+              start: 7,
+              end: 20,
+            },
+          },
+        ],
+      }).success,
+    ).toBe(true);
+  });
+
+  it.each([
+    {
+      name: "protocol item limit",
+      count: 501,
+      quote: "x",
+      expected: 500,
+    },
+    {
+      name: "aggregate anchor text budget",
+      count: 11,
+      quote: "x".repeat(10_000),
+      expected: 10,
+    },
+  ])("limits highlights by $name", ({ count, quote, expected }) => {
+    const highlights = Array.from({ length: count }, (_, index) => ({
+      id: `comment-${index}`,
+      active: false,
+      anchor: {
+        quote,
+        prefix: "",
+        suffix: "",
+        start: 0,
+        end: quote.length,
+      },
+    }));
+
+    expect(limitCanvasCommentHighlights(highlights)).toHaveLength(expected);
+  });
+
+  it("accepts a host request to clear native text selection", () => {
+    expect(
+      hostToCanvasMessageSchema.parse({
+        channel: "posthog-canvas",
+        type: "clear-text-selection",
+      }),
+    ).toEqual({
+      channel: "posthog-canvas",
+      type: "clear-text-selection",
+    });
+  });
 });