feat: Persist Studio manual edits via manifest

[vanceingalls]

Summary

Studio manual geometry edits now persist as a project-local manifest instead of being baked into composition source on each gesture.

The manifest lives at:

.hyperframes/studio-manual-edits.json

It is the source of truth for manual drag, resize, rotation, inspector geometry edits, group moves, and selected-layer reset.

Architecture

• Manifest-backed edits: each edit stores a kind (path-offset, box-size, rotation), a source-scoped target, and the edit values.
• Source-scoped resolution: targets include sourceFile, id, selector, and selectorIndex, so duplicate selectors in nested compositions resolve against the owning source file.
• Additive CSS layer: move uses CSS translate, resize writes stable dimensions/flex sizing, and rotation uses CSS rotate over the authored base.
• Shared replay runtime: Studio preview, thumbnails, frame capture, producer renders, and CLI Studio renders/thumbnails all use the same core manual-edit render script.
• Animation-safe replay: Studio reapplies the manual layer after load, refresh, timeline seeks, player operations, playback frames, thumbnail seeks, and render seeks instead of rewriting GSAP timelines.
• History and handoff: the manifest is a normal project file, so undo/redo and agent edits can preserve, modify, or remove manual visual edits explicitly.

User Impact

Users can move, resize, rotate, group-move, and reset supported layers from the canvas or inspector, then refresh, capture thumbnails/screenshots, play animated compositions, and render videos without manual edits drifting away from the edited state.

Main Files

• packages/studio/src/components/editor/manualEdits.ts
• packages/studio/src/components/editor/DomEditOverlay.tsx
• packages/studio/src/components/editor/PropertyPanel.tsx
• packages/studio/src/App.tsx
• packages/core/src/studio-api/helpers/manualEditsRenderScript.ts
• packages/studio/vite.config.ts
• packages/cli/src/server/studioServer.ts
• packages/core/src/compiler/htmlBundler.ts
• packages/producer/src/services/htmlCompiler.ts
• packages/core/src/studio-api/routes/thumbnail.ts
• packages/producer/src/services/fileServer.ts
• packages/producer/src/services/renderOrchestrator.ts

Test Plan

volta run --node 22.20.0 bun run build
volta run --node 22.20.0 bun run --filter @hyperframes/core test -- src/studio-api/helpers/manualEditsRenderScript.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 bun run --filter @hyperframes/cli 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

[miguel-heygen]

I would not merge this as-is. The manifest direction looks good, but I found two correctness issues that can make Studio preview diverge from render or lose authored inline state.

1. [P1] Preserve source metadata for rendered manual edits. Manual edits made inside a sub-composition are stored with target.sourceFile set to that composition path, but producer compilation inlines the sub-composition and removes data-composition-src without preserving an equivalent data-composition-file marker. The render-time manifest runtime only resolves nested targets through data-composition-file / data-composition-src and otherwise falls back to index.html, so those manifest edits cannot match in the compiled render DOM. I reproduced this with a compiled-style DOM: a manifest rotation targeting sourceFile="compositions/scene.html" left the nested card unrotated. This means Studio preview and final render can diverge for drilled-in manual edits. The affected render path is around packages/producer/src/services/htmlCompiler.ts where data-composition-src is removed during inline compilation, and the resolver is in packages/studio/src/components/editor/manualEditsRenderScript.ts.

2. [P2] Restore authored translate when clearing offsets. Path offsets overwrite the inline translate longhand, but clearStudioPathOffset only removes translate instead of restoring any authored inline translate value. Undoing or clearing a manual offset on an element that already had style="translate: ..." leaves the Studio preview without the original translate until a full reload. I reproduced this by applying a manual path offset to an element with translate: 10px 20px, then applying an empty manifest; translate became empty. See packages/studio/src/components/editor/manualEdits.ts around clearStudioPathOffset.

Verification I ran locally on head 117f6acc: Studio focused tests passed, core thumbnail test passed, producer file server test passed. I also ran the two small reproduction snippets above; both reproduced the issues.

[miguel-heygen]

Requesting changes for two correctness issues I found on the current head. The previous producer/source-metadata and authored-translate blockers look fixed in the main preview/render paths, but these two paths can still produce incorrect user-visible behavior.

[miguel-heygen]

Several new refresh/overlay paths call findElementForSelection with selection.sourceFile as the fallback active composition. In master view that makes root elements with no data-composition-file look like they belong to the nested source, so duplicate ids/classes can resolve to the root element after selection refresh or overlay lookup. I reproduced this on head 3eda023b with root #card plus nested scenes/nested.html #card: resolving the nested selection with selection.sourceFile returned the root card. These callers need the real active composition path, or null for master view, instead of the target source file.

[miguel-heygen]

The thumbnail manifest applier has its own path offset logic and overwrites translate with only the Studio offset variables. The preview/render helpers now preserve authored/computed translate values, so thumbnails can show a different position from Studio preview and final render for manually moved elements that already had translate. The same helper also has a narrower source resolver at lines 100-107, so composition-file hosts without data-composition-id are handled differently from the shared manual edit helpers.

[miguel-heygen]

The two requested-change blockers are addressed on current head b2c6d64.

What I rechecked:

• Re-resolution now uses the real active composition path in App and DomEditOverlay, and the added duplicate-id master-view regression passes.
• Thumbnail manual edit application now preserves authored translate and resolves source-file hosts consistently with preview/render.
• Local targeted suites passed, Studio typecheck passed, and I browser-smoked a root/nested duplicate #card fixture with authored translate plus manifest offsets. The preview applied root and nested edits to the correct source elements, and the nested thumbnail route returned the cropped nested card without picking the root duplicate.

CI note: perf/preview checks were green when checked; several long regression shards were still pending.

[vanceingalls]

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

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