feat(studio): timeline comments with agent resolution

.filesize-allowlist

@@ -1,5 +1,8 @@
 packages/studio/src/player/hooks/useTimelinePlayer.ts
 packages/studio/src/hooks/useManifestPersistence.ts
 packages/studio/src/player/components/PlayerControls.tsx
+packages/studio/src/player/components/Timeline.tsx
+packages/studio/src/App.tsx
 packages/studio/src/components/editor/manualEdits.test.ts
+packages/studio/src/player/components/timelineEditing.test.ts
 packages/studio/src/components/editor/manualEditsDom.ts

packages/cli/package.json

@@ -25,6 +25,7 @@
   },
   "dependencies": {
     "@hono/node-server": "^1.8.0",
+    "@nimrobo/superconnector": "^0.2.1",
     "@puppeteer/browsers": "^2.13.0",
     "adm-zip": "^0.5.16",
     "citty": "^0.2.1",

packages/cli/src/server/fileWatcher.test.ts

@@ -15,5 +15,6 @@ describe("shouldWatchProjectFile", () => {
     expect(shouldWatchProjectFile("renders/output.mp4")).toBe(false);
     expect(shouldWatchProjectFile("dist/index.html")).toBe(false);
     expect(shouldWatchProjectFile(".hyperframes/cache.json")).toBe(false);
+    expect(shouldWatchProjectFile(".superconnector/config.json")).toBe(false);
   });
 });

packages/cli/src/server/fileWatcher.ts

@@ -13,6 +13,7 @@ const WATCHER_EXCLUDED_DIRS = new Set([
   ".git",
   ".hyperframes",
   ".next",
+  ".superconnector",
   ".vite",
   "build",
   "coverage",

packages/core/package.json

@@ -135,6 +135,7 @@
   },
   "dependencies": {
     "@chenglou/pretext": "^0.0.5",
+    "@nimrobo/superconnector": "^0.2.1",
     "postcss": "^8.5.8"
   },
   "devDependencies": {

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

@@ -8,6 +8,7 @@ import { registerRenderRoutes } from "./routes/render.js";
 import { registerThumbnailRoutes } from "./routes/thumbnail.js";
 import { registerWaveformRoutes } from "./routes/waveform.js";
 import { registerFontRoutes } from "./routes/fonts.js";
+import { registerTimelineCommentRoutes } from "./routes/timelineComments.js";
 
 /**
  * Create a Hono sub-app with all studio API routes.
@@ -26,6 +27,7 @@ export function createStudioApi(adapter: StudioApiAdapter): Hono {
   registerThumbnailRoutes(api, adapter);
   registerWaveformRoutes(api, adapter);
   registerFontRoutes(api);
+  registerTimelineCommentRoutes(api, adapter);
 
   return api;
 }

packages/core/src/studio-api/helpers/timelineComments.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { parseHTML } from "linkedom";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  insertTimelineComment,
+  parseTimelineCommentsFromHtml,
+  removeTimelineComment,
+  removeTimelineCommentFromProject,
+  writeTimelineCommentToProject,
+} from "./timelineComments";
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function createProjectDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "hf-comments-helper-test-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+describe("timeline comments", () => {
+  it("inserts a source comment before a target id", () => {
+    const html = '<main><section id="hero" data-start="1">Hero</section></main>';
+    const result = insertTimelineComment(html, {
+      id: "hfc_test",
+      filePath: "index.html",
+      rangeStart: 1,
+      rangeEnd: 4,
+      prompt: "Make hero faster",
+      elements: [{ id: "hero", tag: "section", start: 1, duration: 3, track: 0 }],
+      target: { id: "hero" },
+    });
+
+    expect(result.indexOf("hyperframes-comment")).toBeLessThan(result.indexOf('id="hero"'));
+    expect(result).toContain("<!-- hyperframes-comment {");
+    expect(result).not.toContain("<!-- /hyperframes-comment -->");
+    expect(parseTimelineCommentsFromHtml(result, "index.html")).toMatchObject([
+      {
+        id: "hfc_test",
+        filePath: "index.html",
+        rangeStart: 1,
+        rangeEnd: 4,
+        prompt: "Make hero faster",
+      },
+    ]);
+  });
+
+  it("removes only the matching source comment", () => {
+    const html = insertTimelineComment(
+      insertTimelineComment("<div>Body</div>", {
+        id: "hfc_keep",
+        filePath: "index.html",
+        rangeStart: 0,
+        rangeEnd: 1,
+        prompt: "Keep",
+        elements: [],
+      }),
+      {
+        id: "hfc_remove",
+        filePath: "index.html",
+        rangeStart: 2,
+        rangeEnd: 3,
+        prompt: "Remove",
+        elements: [],
+      },
+    );
+
+    const result = removeTimelineComment(html, "hfc_remove");
+
+    expect(result).toContain("hfc_keep");
+    expect(result).not.toContain("hfc_remove");
+  });
+
+  it("removes a comment id from every .html file that contains it", () => {
+    const projectDir = createProjectDir();
+    writeFileSync(join(projectDir, "a.html"), "<div>A</div>", "utf-8");
+    writeFileSync(join(projectDir, "b.html"), "<div>B</div>", "utf-8");
+
+    writeTimelineCommentToProject(projectDir, {
+      id: "hfc_dup",
+      filePath: "a.html",
+      rangeStart: 0,
+      rangeEnd: 1,
+      prompt: "dup",
+      elements: [],
+    });
+    writeTimelineCommentToProject(projectDir, {
+      id: "hfc_dup",
+      filePath: "b.html",
+      rangeStart: 0,
+      rangeEnd: 1,
+      prompt: "dup",
+      elements: [],
+    });
+
+    const result = removeTimelineCommentFromProject(projectDir, "hfc_dup");
+
+    expect(result.changed).toBe(true);
+    expect(readFileSync(join(projectDir, "a.html"), "utf-8")).not.toContain("hfc_dup");
+    expect(readFileSync(join(projectDir, "b.html"), "utf-8")).not.toContain("hfc_dup");
+  });
+
+  it("does not create visible text nodes in the rendered document", () => {
+    const html = insertTimelineComment(
+      '<main><section id="hero" data-start="1">Hero</section></main>',
+      {
+        id: "hfc_hidden",
+        filePath: "index.html",
+        rangeStart: 1,
+        rangeEnd: 4,
+        prompt: "Make hero faster",
+        elements: [],
+        target: { id: "hero" },
+      },
+    );
+
+    const { document } = parseHTML(html);
+
+    expect(document.body?.textContent ?? document.textContent).not.toContain("Make hero faster");
+    expect(document.body?.textContent ?? document.textContent).not.toContain("hfc_hidden");
+  });
+});