fix: make caption overrides refresh-safe

[vanceingalls]

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

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

[vanceingalls]

• fix: make caption overrides refresh-safe #609 👈 (View in Graphite)
• feat: Persist Studio manual edits via manifest #593
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miguel-heygen]

No blocking findings.

I reviewed this on top of #593 at 6161c790e2c4923988071a6de16a2b11a7ecd9ea. The wrapper reuse path is idempotent, wordId propagation through parser/generator/runtime is stable, and the legacy wordIndex fallback remains covered.

Validated locally:

• bun run --filter @hyperframes/core test -- src/runtime/captionOverrides.test.ts
• packages/studio/node_modules/.bin/vitest run --root packages/studio --config /dev/null src/captions/parser.test.ts src/captions/generator.test.ts
• bun run --filter @hyperframes/core typecheck
• bun run --filter @hyperframes/studio typecheck
• bunx oxlint / bunx oxfmt --check on the changed caption files

Browser smoke: loaded a temporary Studio preview project with stable word IDs plus caption-overrides.json, confirmed the runtime applied the wordId override, reloaded, and confirmed it still had exactly one caption wrapper with the expected transform/font size.

CI is green except Graphite mergeability still appears pending, which I do not consider a code blocker for this review.

[vanceingalls]

Merge activity

• May 4, 6:29 AM UTC: @vanceingalls merged this pull request with Graphite.