fix(telemetry): attribute studio renders to the browser user (joinable funnel) (#1492)

Studio-triggered renders emit render_complete / render_error from the CLI
preview-server process, which stamps every event with the install's
anonymousId (client.ts drainQueueToPayload). The browser, meanwhile, fires
studio_session_start / studio_render_start under its own getAnonymousId(). So
the render outcome and the render start never share a person_id — verified in
data: of 15,125 users who started a studio render in 30d, ZERO have any
render_complete under any source, and the 898 studio-tagged completers are
disjoint server UUIDs. The studio render funnel — the product's core value
moment and strongest retention signal — is therefore unmeasurable.

Thread the browser's telemetry id through to the render-outcome events:

- client.ts: trackEvent takes an optional distinctId; drainQueueToPayload uses
  `event.distinctId ?? config.anonymousId`. CLI renders unchanged.
- events.ts: trackRenderComplete/trackRenderError forward an optional distinctId.
- studioRenderTelemetry.ts: emitStudioRender* pass opts.distinctId through.
- core studio-api (types.ts + routes/render.ts): the render route reads
  `telemetryDistinctId` from the request body (validated string) and passes it
  to the adapter's startRender, which already forwards opts to the emitters.
- studio (useRenderQueue.ts): include getAnonymousId() as telemetryDistinctId
  in the render POST — the same id studio_* events already use.

Result: studio render_complete/error now carry the browser user's id and join
studio_session_start / studio_render_start. Older clients that don't send the
field fall back to anonymousId (no regression). No new tracking surface — it's
the existing anonymous studio id.

Tests: per-event override forwarding (events), studio render distinctId
threading + older-client fallback (studioRenderTelemetry), and route body →
adapter forwarding incl. non-string rejection (core render route).

packages/core/src/studio-api/routes/render.test.ts

@@ -428,3 +428,63 @@ describe("GET /projects/:id/renders/file/* — path safety", () => {
     expect(await res.text()).toBe("nested-bytes");
   });
 });
+
+describe("POST /projects/:id/render — telemetryDistinctId forwarding", () => {
+  it("forwards the browser telemetryDistinctId to the adapter as distinctId", async () => {
+    const spy = vi.fn();
+    const { app, cleanup } = buildApp(spy);
+    try {
+      const res = await app.request("http://localhost/projects/demo/render", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          fps: 30,
+          quality: "standard",
+          format: "mp4",
+          telemetryDistinctId: "browser-user-123",
+        }),
+      });
+      expect(res.status).toBe(200);
+      expect(spy.mock.calls[0][0].distinctId).toBe("browser-user-123");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("passes undefined when no telemetryDistinctId is sent (older clients)", async () => {
+    const spy = vi.fn();
+    const { app, cleanup } = buildApp(spy);
+    try {
+      const res = await app.request("http://localhost/projects/demo/render", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4" }),
+      });
+      expect(res.status).toBe(200);
+      expect(spy.mock.calls[0][0].distinctId).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("ignores a non-string telemetryDistinctId", async () => {
+    const spy = vi.fn();
+    const { app, cleanup } = buildApp(spy);
+    try {
+      const res = await app.request("http://localhost/projects/demo/render", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          fps: 30,
+          quality: "standard",
+          format: "mp4",
+          telemetryDistinctId: 42,
+        }),
+      });
+      expect(res.status).toBe(200);
+      expect(spy.mock.calls[0][0].distinctId).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+});

packages/core/src/studio-api/routes/render.ts

@@ -61,6 +61,9 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
       format?: string;
       resolution?: string;
       composition?: string;
+      // Browser telemetry id, so the server-emitted render outcome is
+      // attributed to the user who triggered the render (joinable funnel).
+      telemetryDistinctId?: string;
     };
     const VALID_FORMATS = new Set(["mp4", "webm", "mov"]);
     const FORMAT_EXT: Record<string, string> = { mp4: ".mp4", webm: ".webm", mov: ".mov" };
@@ -108,6 +111,8 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
       jobId,
       outputResolution,
       composition,
+      distinctId:
+        typeof body.telemetryDistinctId === "string" ? body.telemetryDistinctId : undefined,
     });
     (jobState as RenderJobState & { createdAt: number }).createdAt = Date.now();
     renderJobs.set(jobId, jobState as RenderJobState & { createdAt: number });

packages/core/src/studio-api/types.ts

@@ -91,6 +91,13 @@ export interface StudioApiAdapter {
     outputResolution?: CanvasResolution;
     /** Entry file relative to projectDir (e.g. "compositions/intro.html"). Defaults to index.html. */
     composition?: string;
+    /**
+     * Telemetry id of the browser user who triggered the render. Lets the
+     * adapter attribute the server-emitted render_complete/render_error to
+     * that user so the studio render funnel is joinable. Undefined for older
+     * clients → falls back to the install's anonymous id.
+     */
+    distinctId?: string;
   }): RenderJobState;
 
   /** Optional: generate a JPEG thumbnail via Puppeteer or similar. */