fix: make caption overrides refresh-safe (#609)

## Summary

This stacked PR makes caption overrides refresh-safe.

Caption edits are still saved to `caption-overrides.json`, but override targets are now stable across preview refreshes and regenerated caption HTML.

## Architecture

- **Stable word identity**: generated caption HTML preserves optional transcript word IDs in the `TRANSCRIPT` array and emits those IDs on word spans.
- **Parser continuity**: the caption parser preserves existing transcript word `id` fields instead of regenerating index-only identity.
- **Override loading**: Studio loads saved overrides by `wordId` first, with the existing `wordIndex` fallback kept for older overrides.
- **Idempotent runtime wrapping**: transform overrides reuse an existing `data-caption-wrapper="true"` wrapper instead of nesting wrappers on every refresh.
- **Animation compatibility**: overrides still wrap the word so inner word-level GSAP animation can continue to target the original span.

## User Impact

Users can edit caption word position, scale, rotation, color, opacity, font size, font weight, and font family, then refresh without overrides drifting to the wrong word or accumulating nested wrappers.

## Main Files

- `packages/core/src/runtime/captionOverrides.ts`
- `packages/studio/src/captions/generator.ts`
- `packages/studio/src/captions/parser.ts`
- `packages/studio/src/captions/hooks/useCaptionSync.ts`

## Test Plan

```bash
volta run --node 22.20.0 bun run --filter @hyperframes/core test -- src/runtime/captionOverrides.test.ts
volta run --node 22.20.0 packages/studio/node_modules/.bin/vitest run --root packages/studio --config /dev/null src/captions/parser.test.ts src/captions/generator.test.ts
volta run --node 22.20.0 bun run --filter @hyperframes/core typecheck
volta run --node 22.20.0 bun run --filter @hyperframes/studio typecheck
volta run --node 22.20.0 bunx oxlint <changed files>
volta run --node 22.20.0 bunx oxfmt --check <changed files>
git diff --check
```

packages/studio/src/captions/generator.test.ts

@@ -137,6 +137,25 @@ describe("generateCaptionHtml", () => {
       expect(html).toContain('"end": 2.7');
     });
 
+    it("includes stable word ids in the transcript and generated word spans", () => {
+      const transcript: TranscriptWord[] = [
+        { id: "word-a", text: "Hello", start: 0, end: 0.4 },
+        { id: "word-b", text: "world", start: 0.5, end: 1 },
+      ];
+      const model = buildCaptionModel(transcript, {
+        width: 1920,
+        height: 1080,
+        duration: 2,
+      });
+
+      const html = generateCaptionHtml(model);
+
+      expect(html).toContain('"id": "word-a"');
+      expect(html).toContain('"id": "word-b"');
+      expect(html).toContain('w_segment_0.id = "word-a";');
+      expect(html).toContain('w_segment_1.id = "word-b";');
+    });
+
     it("TRANSCRIPT contains all 7 words from the sample", () => {
       const model = buildTestModel();
       const html = generateCaptionHtml(model);

packages/studio/src/captions/generator.ts

@@ -261,14 +261,19 @@ function hexToRgba(color: string, opacity: number): string {
 
 function generateJs(model: CaptionModel): string {
   // Collect all segments across all groups in order
-  const allSegments: Array<{ text: string; start: number; end: number }> = [];
+  const allSegments: Array<{ id?: string; text: string; start: number; end: number }> = [];
   for (const groupId of model.groupOrder) {
     const group = model.groups.get(groupId);
     if (!group) continue;
     for (const segId of group.segmentIds) {
       const seg = model.segments.get(segId);
       if (!seg) continue;
-      allSegments.push({ text: seg.text, start: seg.start, end: seg.end });
+      allSegments.push({
+        ...(seg.wordId ? { id: seg.wordId } : {}),
+        text: seg.text,
+        start: seg.start,
+        end: seg.end,
+      });
     }
   }
 
@@ -300,9 +305,11 @@ function generateJs(model: CaptionModel): string {
     const wordLines: string[] = groupSegments.map((seg) => {
       const escaped = seg.text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
       const segVar = `w_${seg.id.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+      const idLine = seg.wordId ? `\n  ${segVar}.id = ${JSON.stringify(seg.wordId)};` : "";
       return (
         `  const ${segVar} = document.createElement('span');` +
         `\n  ${segVar}.className = 'word clip';` +
+        idLine +
         `\n  ${segVar}.textContent = '${escaped}';` +
         `\n  ${segVar}.dataset.start = '${seg.start}';` +
         `\n  ${segVar}.dataset.end = '${seg.end}';` +

packages/studio/src/captions/hooks/useCaptionSync.ts

@@ -124,17 +124,22 @@ export function useCaptionSync(projectId: string | null) {
 
       const model = state.model;
       const allSegIds: string[] = [];
+      const segIdByWordId = new Map<string, string>();
       for (const groupId of model.groupOrder) {
         const group = model.groups.get(groupId);
         if (!group) continue;
         for (const segId of group.segmentIds) {
           allSegIds.push(segId);
+          const seg = model.segments.get(segId);
+          if (seg?.wordId) segIdByWordId.set(seg.wordId, segId);
         }
       }
 
       const newSegments = new Map(model.segments);
       for (const override of overrides) {
-        const segId = allSegIds[override.wordIndex];
+        const segId =
+          (override.wordId ? segIdByWordId.get(override.wordId) : undefined) ??
+          allSegIds[override.wordIndex];
         if (!segId) continue;
         const seg = newSegments.get(segId);
         if (!seg) continue;

packages/studio/src/captions/parser.test.ts

@@ -102,6 +102,20 @@ describe("extractTranscript", () => {
       expect(words).toHaveLength(1);
       expect(words[0]).toEqual({ text: "Hello", start: 0.0, end: 0.5 });
     });
+
+    it("preserves stable word ids when present", () => {
+      const words = extractTranscript(`
+        const TRANSCRIPT = [
+          { id: "word-a", text: "Hello", start: 0, end: 0.4 },
+          { id: "word-b", text: "world", start: 0.5, end: 1 },
+        ];
+      `);
+
+      expect(words).toEqual([
+        { id: "word-a", text: "Hello", start: 0, end: 0.4 },
+        { id: "word-b", text: "world", start: 0.5, end: 1 },
+      ]);
+    });
   });
 
   describe("script variable name", () => {

packages/studio/src/captions/parser.ts

@@ -303,6 +303,7 @@ function parseTranscriptArray(arrayLiteral: string): TranscriptWord[] {
     ) {
       const entry = item as Record<string, unknown>;
       words.push({
+        ...(typeof entry.id === "string" ? { id: entry.id } : {}),
         text: entry.text as string,
         start: entry.start as number,
         end: entry.end as number,