From d0abe90a826a7d50dcca700916c36ef3105a4323 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Sun, 3 May 2026 23:06:11 -0700 Subject: [PATCH] feat: Persist Studio manual edits via manifest (#593) ## 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: ```text .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 ```bash 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 volta run --node 22.20.0 bunx oxfmt --check git diff --check ``` --- docs/contributing.mdx | 8 + .../studio-manual-dom-editing.mdx | 315 ++ docs/docs.json | 3 +- packages/cli/src/server/studioServer.ts | 47 +- packages/core/package.json | 8 + .../core/src/compiler/htmlBundler.test.ts | 2 + packages/core/src/compiler/htmlBundler.ts | 19 +- .../src/compiler/rewriteSubCompPaths.test.ts | 21 +- .../core/src/compiler/rewriteSubCompPaths.ts | 22 + packages/core/src/lint/rules/captions.test.ts | 22 + packages/core/src/lint/rules/captions.ts | 3 +- .../core/src/studio-api/createStudioApi.ts | 2 + .../helpers/manualEditsRenderScript.test.ts | 382 +++ .../helpers/manualEditsRenderScript.ts | 369 +++ .../src/studio-api/helpers/screenshotClip.ts | 11 +- .../studio-api/helpers/subComposition.test.ts | 3 + .../src/studio-api/helpers/subComposition.ts | 14 +- packages/core/src/studio-api/index.ts | 4 + packages/core/src/studio-api/routes/fonts.ts | 247 ++ .../core/src/studio-api/routes/projects.ts | 2 +- .../src/studio-api/routes/thumbnail.test.ts | 82 +- .../core/src/studio-api/routes/thumbnail.ts | 27 +- packages/core/src/studio-api/types.ts | 1 + .../producer/src/services/fileServer.test.ts | 34 + packages/producer/src/services/fileServer.ts | 7 +- .../src/services/htmlCompiler.test.ts | 5 + .../producer/src/services/htmlCompiler.ts | 2 + .../src/services/renderOrchestrator.ts | 4 + packages/studio/src/App.tsx | 2162 ++++++++++++- packages/studio/src/components/LintModal.tsx | 7 +- .../components/editor/DomEditOverlay.test.ts | 241 ++ .../src/components/editor/DomEditOverlay.tsx | 1300 ++++++++ .../src/components/editor/PropertyPanel.tsx | 2694 +++++++++++++++-- .../src/components/editor/colorValue.test.ts | 82 + .../src/components/editor/colorValue.ts | 175 ++ .../src/components/editor/domEditing.test.ts | 669 ++++ .../src/components/editor/domEditing.ts | 733 +++++ .../components/editor/floatingPanel.test.ts | 34 + .../src/components/editor/floatingPanel.ts | 54 + .../src/components/editor/fontAssets.ts | 32 + .../src/components/editor/fontCatalog.ts | 126 + .../components/editor/gradientValue.test.ts | 89 + .../src/components/editor/gradientValue.ts | 445 +++ .../src/components/editor/manualEdits.test.ts | 945 ++++++ .../src/components/editor/manualEdits.ts | 1397 +++++++++ .../editor/manualOffsetDrag.test.ts | 140 + .../src/components/editor/manualOffsetDrag.ts | 307 ++ .../studio/src/components/nle/NLELayout.tsx | 13 +- .../studio/src/components/nle/NLEPreview.tsx | 55 +- .../src/components/renders/RenderQueue.tsx | 13 +- .../src/components/sidebar/AssetsTab.tsx | 7 +- .../sidebar/CompositionsTab.test.ts | 17 +- .../components/sidebar/CompositionsTab.tsx | 162 +- .../src/components/sidebar/LeftSidebar.tsx | 119 +- .../hooks/usePersistentEditHistory.test.ts | 256 ++ .../src/hooks/usePersistentEditHistory.ts | 337 +++ packages/studio/src/icons/SystemIcons.tsx | 2 + .../components/CompositionThumbnail.test.ts | 19 + .../components/CompositionThumbnail.tsx | 54 +- .../src/player/components/EditModal.tsx | 25 +- .../studio/src/player/components/Player.tsx | 64 +- .../src/player/components/Timeline.test.ts | 12 + .../studio/src/player/components/Timeline.tsx | 71 +- .../src/player/components/TimelineClip.tsx | 27 +- .../player/components/timelineEditing.test.ts | 6 +- .../src/player/components/timelineEditing.ts | 4 +- .../player/hooks/useTimelinePlayer.test.ts | 47 +- .../src/player/hooks/useTimelinePlayer.ts | 9 +- packages/studio/src/utils/clipboard.test.ts | 89 + packages/studio/src/utils/clipboard.ts | 57 + packages/studio/src/utils/editHistory.test.ts | 244 ++ packages/studio/src/utils/editHistory.ts | 218 ++ .../src/utils/editHistoryStorage.test.ts | 37 + .../studio/src/utils/editHistoryStorage.ts | 99 + packages/studio/src/utils/mediaTypes.ts | 2 +- .../studio/src/utils/sourcePatcher.test.ts | 129 +- packages/studio/src/utils/sourcePatcher.ts | 148 +- .../src/utils/studioFileHistory.test.ts | 156 + .../studio/src/utils/studioFileHistory.ts | 61 + .../src/utils/timelineAssetDrop.test.ts | 42 +- .../studio/src/utils/timelineAssetDrop.ts | 24 +- packages/studio/vite.config.ts | 145 +- 82 files changed, 15351 insertions(+), 717 deletions(-) create mode 100644 docs/contributing/studio-manual-dom-editing.mdx create mode 100644 packages/core/src/studio-api/helpers/manualEditsRenderScript.test.ts create mode 100644 packages/core/src/studio-api/helpers/manualEditsRenderScript.ts create mode 100644 packages/core/src/studio-api/routes/fonts.ts create mode 100644 packages/studio/src/components/editor/DomEditOverlay.test.ts create mode 100644 packages/studio/src/components/editor/DomEditOverlay.tsx create mode 100644 packages/studio/src/components/editor/colorValue.test.ts create mode 100644 packages/studio/src/components/editor/colorValue.ts create mode 100644 packages/studio/src/components/editor/domEditing.test.ts create mode 100644 packages/studio/src/components/editor/domEditing.ts create mode 100644 packages/studio/src/components/editor/floatingPanel.test.ts create mode 100644 packages/studio/src/components/editor/floatingPanel.ts create mode 100644 packages/studio/src/components/editor/fontAssets.ts create mode 100644 packages/studio/src/components/editor/fontCatalog.ts create mode 100644 packages/studio/src/components/editor/gradientValue.test.ts create mode 100644 packages/studio/src/components/editor/gradientValue.ts create mode 100644 packages/studio/src/components/editor/manualEdits.test.ts create mode 100644 packages/studio/src/components/editor/manualEdits.ts create mode 100644 packages/studio/src/components/editor/manualOffsetDrag.test.ts create mode 100644 packages/studio/src/components/editor/manualOffsetDrag.ts create mode 100644 packages/studio/src/hooks/usePersistentEditHistory.test.ts create mode 100644 packages/studio/src/hooks/usePersistentEditHistory.ts create mode 100644 packages/studio/src/player/components/CompositionThumbnail.test.ts create mode 100644 packages/studio/src/utils/clipboard.test.ts create mode 100644 packages/studio/src/utils/clipboard.ts create mode 100644 packages/studio/src/utils/editHistory.test.ts create mode 100644 packages/studio/src/utils/editHistory.ts create mode 100644 packages/studio/src/utils/editHistoryStorage.test.ts create mode 100644 packages/studio/src/utils/editHistoryStorage.ts create mode 100644 packages/studio/src/utils/studioFileHistory.test.ts create mode 100644 packages/studio/src/utils/studioFileHistory.ts diff --git a/docs/contributing.mdx b/docs/contributing.mdx index 8029fa01b..0dc7845f4 100644 --- a/docs/contributing.mdx +++ b/docs/contributing.mdx @@ -53,6 +53,14 @@ bun run build # Build all packages bun run --filter '*' typecheck # Type-check all packages ``` +### Studio Editing Work + +If you are changing Studio's visual editing surface, read +[Studio Manual DOM Editing](/contributing/studio-manual-dom-editing) before +editing code. The inspector intentionally exposes only interactions it can +persist safely back to HTML, so changes should preserve the capability gates, +source patching model, and documented limitations. + ### Running Tests diff --git a/docs/contributing/studio-manual-dom-editing.mdx b/docs/contributing/studio-manual-dom-editing.mdx new file mode 100644 index 000000000..e2a343afe --- /dev/null +++ b/docs/contributing/studio-manual-dom-editing.mdx @@ -0,0 +1,315 @@ +--- +title: Studio Manual DOM Editing +description: What the Studio manual DOM editing inspector ships today, including capabilities, UX, and constraints. +--- + +This page documents the current manual DOM editing surface in HyperFrames Studio. It reflects the implementation that ships in the Studio inspector today, not the earlier design draft that explored third-party transform engines. + +## What Shipped + +Studio now supports a direct DOM editing workflow inside the preview: + +- select supported elements directly in the preview +- see an editor-owned overlay around the current selection +- move and resize supported elements on canvas when geometry is safe +- detach eligible layout-controlled layers with an explicit `Make movable` action +- edit style properties from the right-side `Design` inspector +- edit text layers for safe text-bearing selections, including empty text values +- add and remove child text layers for multi-text selections +- edit solid fills, gradients, project-asset image fills, external image fills, opacity, radius, flex metadata, typography, and blend mode +- drill into nested compositions from master view instead of pretending every inner node is editable in place +- generate an element-scoped `Ask agent` prompt bundle from the right inspector + +The important rule is conservative: Studio only exposes interactions it can round-trip back to authored HTML with deterministic behavior. + +## Current User Experience + +### Preview selection + +- Single click selects a patchable element in the preview. +- The selection overlay is rendered in Studio chrome, not injected into authored content. +- The overlay is cleared when: + - the `Inspector` panel is closed + - the user clicks an empty area in the preview + - the underlying element disappears after a source refresh + +### Overlay behavior + +The overlay provides: + +- selection bounds +- drag behavior for supported elements +- a resize handle when width and height are safely patchable +- blocked-drag feedback for unsupported movement + +The overlay intentionally does not include a floating action toolbar. `Ask agent` lives in the right inspector header, and style controls live in the `Design` panel. + +The current implementation uses Studio-owned pointer handling in `DomEditOverlay.tsx`. It does **not** use `Moveable`. + +### Inspector behavior + +The `Design` panel currently includes: + +- `Layout` + - X / Y / W / H fields + - wheel and arrow-key numeric scrubbing + - `Make movable` for block-ish layout-controlled layers that can be detached safely +- `Flex` + - direction, justify, align, gap, clip content +- `Radius` + - slider + live readout +- `Blending` + - opacity slider + live readout + - blend mode +- `Fill` + - solid color + - multi-stop gradient editing + - project asset image fills + - inline image upload into the project assets list + - external image URL fill + - text color +- `Color picker` + - viewport-clamped floating picker + - saturation / brightness crosshair + - hue and alpha sliders + - hex input +- `Text` + - direct text layer editing when the selection is safe to patch + - add / remove text layers for child text selections + - font size, weight, and family controls +- `Selection colors` + - a summary of detected colors for the current selection + +The inspector is intentionally split from `Renders` with a `Design / Renders` tab control in the right panel. Switching to `Renders` does not mean the header-level `Inspector` panel is closed. + +## What Counts As Editable + +Studio builds a `DomEditSelection` and `DomEditCapabilities` object for each selection. + +### Selection requirements + +A node is only useful to Studio if it can be identified with a stable patch target, for example: + +- `id` +- stable selector +- selector index scoped to the correct source file +- composition host mapping when master view is involved + +### Move support + +Move is allowed only when the selected element: + +- has a stable patch target +- is `absolute` or `fixed` +- has `left` and `top` values that resolve to pixel values +- is not transform-driven (`transform: none`) + +### Resize support + +Resize is allowed only when move is already allowed and Studio can also safely patch pixel `width` and/or `height`. + +### Detach from layout support + +Some block-ish layers are selectable and style-editable, but cannot be moved directly because flex, grid, or normal document flow owns their position. + +For those layers, Studio can expose `Make movable` instead of silently converting on drag. The action measures the current visual rect relative to the composition root and writes conservative inline geometry: + +- `position: absolute` +- `left`, `top`, `width`, and `height` in pixels +- `margin: 0` + +The UI explains that this detaches the layer from flex/grid flow and preserves the current visual position. Inline text nodes are not detached directly. + +### Text editing support + +Text editing is allowed only for safe text-bearing selections: + +- supported text-bearing tags such as `div`, `span`, `p`, `strong`, and headings +- self text selections or leaf child text layers +- empty text values after a user clears the content +- not a composition host + +For multi-text selections, Studio shows a text-layer list. Users can select a specific text layer, edit content live, change size, weight, and font family, add a sibling text layer, or remove the active layer. + +### Unsupported examples + +Studio intentionally withholds direct geometry editing for: + +- flex/grid children whose position is emergent from layout, unless the user chooses `Make movable` +- transform-driven geometry +- nested composition internals while the user is still in master view +- nodes without a stable patch target +- inline text spans as geometry targets + +When geometry is blocked but style edits are still safe, the inspector shows the selection and the reason direct geometry editing is unavailable. + +If the user tries to drag a blocked layer, Studio shows a toast. Layout-owned layers point users to `Make movable`; transform-driven or unsafe targets explain that direct move/resize is limited to absolute or fixed pixel geometry with no transform-driven layout. + +## Nested Composition Rules + +Nested compositions are handled explicitly. + +### In master view + +- clicking content inside a nested composition maps back to the composition host +- supported composition hosts can move as a whole when their host geometry is safe +- Studio does not expose direct inner-node geometry edits from the master preview +- double click drills into the subcomposition + +### After drill-down + +- Studio resolves selections inside that composition normally +- direct move/resize becomes available again if the selected inner node meets the capability rules +- text, fill, gradient, image, radius, opacity, and typography edits apply to the selected inner node + +This keeps Studio honest about what it can patch safely from the current editing context. + +## Source Patching Model + +Studio still uses authored HTML as the source of truth. + +The manual DOM editing flow patches source through the existing patch pipeline in `packages/studio/src/utils/sourcePatcher.ts`. + +Current patch types used by the inspector include: + +- inline style patches +- attribute patches for timeline-linked editing paths +- text-content patches +- detach-from-layout style patches + +The flow is: + +1. user selects or manipulates an element in the preview +2. Studio resolves a stable target +3. the preview is updated optimistically for interaction feedback +4. the patch is written back to source +5. the preview refreshes and selection is reattached + +## Gradient Editing + +The current gradient editor is a structured Studio control, not a raw CSS text field. + +It supports: + +- `linear`, `radial`, and `conic` gradients +- repeating variants +- multiple stops +- stop insertion by clicking the preview strip +- stop removal +- angle control +- radial shape and size controls +- radial/conic center controls + +The editor still serializes back to CSS `background-image`, but the inspector works with a parsed gradient model instead of forcing the user to type raw gradient syntax. + +## Image Fill Editing + +The image fill editor is no longer just a raw `background-image` input. + +It supports: + +- selecting an existing project image asset +- uploading an image from the fill panel, which also adds it to the Assets tab +- previewing the selected project asset in the panel +- entering an external URL when the image is not a project asset + +Studio serializes project asset selections back to `background-image: url(...)`, and rewrites asset URLs so nested subcomposition previews still resolve the image correctly. + +## Color Editing + +The color editor is a custom Studio popover instead of the native browser color dialog. + +It supports: + +- opening from the whole color row +- staying inside the viewport near the clicked color +- saturation / brightness picking with visible crosshair guides +- hue and alpha controls with visible handles +- a current color swatch, readout, and hex input + +The picker writes CSS `rgb(...)` or `rgba(...)` values and preserves alpha through edits. + +## Numeric Scrubbing + +Numeric layout/detail inputs support lightweight design-tool-style nudging: + +- mouse wheel over the focused field +- `ArrowUp` / `ArrowDown` +- `Shift` for larger steps +- `Alt` for finer steps + +This is currently used across the numeric commit fields in the inspector, including layout metrics and other numeric text inputs that parse cleanly as values plus units. + +## Files That Own The Feature + +The main implementation lives in: + +- `packages/studio/src/App.tsx` + - overall inspector wiring + - selection lifecycle + - preview hit testing + - persistence hooks + - detach-from-layout commit flow +- `packages/studio/src/components/editor/DomEditOverlay.tsx` + - overlay box, drag, resize, blocked-drag feedback +- `packages/studio/src/components/editor/PropertyPanel.tsx` + - right-side inspector UI +- `packages/studio/src/components/editor/domEditing.ts` + - selection resolution + - capability gating + - text field modeling + - prompt generation +- `packages/studio/src/components/editor/colorValue.ts` + - color parsing, HSV conversion, and CSS color serialization +- `packages/studio/src/components/editor/floatingPanel.ts` + - viewport-safe floating panel placement for color picking +- `packages/studio/src/components/editor/fontAssets.ts` + - imported font asset helpers +- `packages/studio/src/components/editor/fontCatalog.ts` + - Google font catalog metadata and stylesheet URLs +- `packages/studio/src/components/editor/gradientValue.ts` + - gradient parsing, serialization, and stop editing helpers +- `packages/studio/src/utils/sourcePatcher.ts` + - source patch persistence + +Supporting Studio shell changes also landed in: + +- `packages/studio/src/components/nle/NLELayout.tsx` +- `packages/studio/src/components/nle/NLEPreview.tsx` +- `packages/studio/src/components/sidebar/CompositionsTab.tsx` +- `packages/studio/src/components/sidebar/LeftSidebar.tsx` +- `packages/studio/src/player/components/Player.tsx` +- `packages/studio/src/player/components/Timeline.tsx` +- `packages/studio/src/player/components/TimelineClip.tsx` +- `packages/studio/src/player/hooks/useTimelinePlayer.ts` +- `packages/studio/src/utils/mediaTypes.ts` + +## Current Constraints + +This feature is intentionally **not** a full general-purpose visual builder. + +Still out of scope today: + +- rotation +- arbitrary transforms +- snapping and alignment guides +- multi-select +- marquee selection +- freeform editing of every DOM node regardless of layout model +- editing nested subcomposition internals directly from the master preview without drill-down +- automatic conversion to absolute positioning on drag without user confirmation +- direct geometry editing of inline text spans + +## Bottom Line + +Studio manual DOM editing is now a narrow, deterministic visual editing layer over authored HTML. + +It does **not** try to make the whole DOM freely editable. Instead it: + +- keeps source HTML as the source of truth +- exposes only patchable interactions +- uses a Studio-owned overlay layer for direct manipulation +- gives users a real inspector for safe style and text edits +- treats nested compositions as drill-down boundaries instead of flattening them into an unsafe editing surface + +That tradeoff is the reason the current feature feels reliable instead of deceptive. diff --git a/docs/docs.json b/docs/docs.json index 3c7092e08..090a8e85d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -202,7 +202,8 @@ "pages": [ "contributing", "contributing/release-channels", - "contributing/testing-local-changes" + "contributing/testing-local-changes", + "contributing/studio-manual-dom-editing" ] }, { diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts index ccceccffb..5c4e1df53 100644 --- a/packages/cli/src/server/studioServer.ts +++ b/packages/cli/src/server/studioServer.ts @@ -13,6 +13,7 @@ import { createProjectWatcher, type ProjectWatcher } from "./fileWatcher.js"; import { loadRuntimeSource } from "./runtimeSource.js"; import { VERSION as version } from "../version.js"; import { + createStudioManualEditsRenderBodyScript, createStudioApi, getMimeType, type StudioApiAdapter, @@ -22,6 +23,8 @@ import { import { getElementScreenshotClip } from "@hyperframes/core/studio-api/screenshot-clip"; import type { ScreenshotClip } from "@hyperframes/core/studio-api/screenshot-clip"; +const STUDIO_MANUAL_EDITS_PATH = ".hyperframes/studio-manual-edits.json"; + // ── Path resolution ───────────────────────────────────────────────────────── function resolveDistDir(): string { @@ -77,6 +80,38 @@ function resolveRuntimePath(): string { return builtPath; } +function readStudioManualEditManifestContent(projectDir: string): string { + const manifestPath = join(projectDir, STUDIO_MANUAL_EDITS_PATH); + if (!existsSync(manifestPath)) return ""; + try { + return readFileSync(manifestPath, "utf-8"); + } catch { + return ""; + } +} + +async function applyStudioManualEditsToThumbnailPage( + page: import("puppeteer-core").Page, + manifestContent: string, + activeCompositionPath: string, +): Promise { + const script = createStudioManualEditsRenderBodyScript(manifestContent, { + activeCompositionPath, + }); + if (!script) return; + await page.addScriptTag({ content: script }); +} + +async function reapplyStudioManualEditsToThumbnailPage( + page: import("puppeteer-core").Page, +): Promise { + await page.evaluate(() => { + const apply = (window as Window & { __hfStudioManualEditsApply?: () => number }) + .__hfStudioManualEditsApply; + if (typeof apply === "function") apply(); + }); +} + // ── Shared thumbnail browser (singleton per process) ──────────────────────── // One browser instance is reused across all composition thumbnail requests. // Spawning a new Puppeteer process per request adds 2-5s overhead and causes @@ -198,10 +233,13 @@ export function createStudioServer(options: StudioServerOptions): StudioServer { // Continue without — acquireBrowser will try its own resolution } + const manifestContent = readStudioManualEditManifestContent(opts.project.dir); + const manualEditsRenderScript = createStudioManualEditsRenderBodyScript(manifestContent); const job = createRenderJob({ fps: opts.fps as 24 | 30 | 60, quality: opts.quality as "draft" | "standard" | "high", format: opts.format, + ...(manualEditsRenderScript ? { renderBodyScripts: [manualEditsRenderScript] } : {}), }); const startTime = Date.now(); const onProgress = (j: { progress: number; currentStage?: string }) => { @@ -258,11 +296,14 @@ export function createStudioServer(options: StudioServerOptions): StudioServer { win.__timeline.seek(t); } }, opts.seekTime); + const manifestContent = readStudioManualEditManifestContent(opts.project.dir); + await applyStudioManualEditsToThumbnailPage(page, manifestContent, opts.compPath); // Let the seek render settle. await new Promise((r) => setTimeout(r, 200)); + await reapplyStudioManualEditsToThumbnailPage(page); let clip: ScreenshotClip | undefined; if (opts.selector) { - clip = await page.evaluate(getElementScreenshotClip, opts.selector); + clip = await page.evaluate(getElementScreenshotClip, opts.selector, opts.selectorIndex); } const screenshot = (await page.screenshot( opts.format === "png" @@ -318,8 +359,8 @@ export function createStudioServer(options: StudioServerOptions): StudioServer { app.get("/api/events", (c) => { return streamSSE(c, async (stream) => { - const listener = () => { - stream.writeSSE({ event: "file-change", data: "{}" }).catch(() => {}); + const listener = (path: string) => { + stream.writeSSE({ event: "file-change", data: JSON.stringify({ path }) }).catch(() => {}); }; watcher.addListener(listener); while (true) { diff --git a/packages/core/package.json b/packages/core/package.json index 614b34e64..fe9b4f7ec 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -42,6 +42,10 @@ "import": "./src/studio-api/helpers/screenshotClip.ts", "types": "./src/studio-api/helpers/screenshotClip.ts" }, + "./studio-api/manual-edits-render-script": { + "import": "./src/studio-api/helpers/manualEditsRenderScript.ts", + "types": "./src/studio-api/helpers/manualEditsRenderScript.ts" + }, "./text": { "import": "./src/text/index.ts", "types": "./src/text/index.ts" @@ -81,6 +85,10 @@ "import": "./dist/studio-api/helpers/screenshotClip.js", "types": "./dist/studio-api/helpers/screenshotClip.d.ts" }, + "./studio-api/manual-edits-render-script": { + "import": "./dist/studio-api/helpers/manualEditsRenderScript.js", + "types": "./dist/studio-api/helpers/manualEditsRenderScript.d.ts" + }, "./text": { "import": "./dist/text/index.js", "types": "./dist/text/index.d.ts" diff --git a/packages/core/src/compiler/htmlBundler.test.ts b/packages/core/src/compiler/htmlBundler.test.ts index e6a24ddb0..527c3a482 100644 --- a/packages/core/src/compiler/htmlBundler.test.ts +++ b/packages/core/src/compiler/htmlBundler.test.ts @@ -255,9 +255,11 @@ describe("bundleToSingleHtml", () => { const host = document.querySelector("#scene-host"); expect(host?.getAttribute("data-composition-id")).toBe("scene"); + expect(host?.getAttribute("data-composition-file")).toBe("compositions/scene.html"); expect(host?.getAttribute("data-start")).toBe("intro"); expect(host?.getAttribute("data-width")).toBe("1920"); expect(host?.querySelector(".title")?.textContent).toBe("Scene"); + expect(host?.querySelector(".title")?.closest("[data-composition-file]")).toBe(host); expect( Array.from(host?.children ?? []).some( (child) => child.getAttribute("data-composition-id") === "scene", diff --git a/packages/core/src/compiler/htmlBundler.ts b/packages/core/src/compiler/htmlBundler.ts index 3a80d58c9..c374672eb 100644 --- a/packages/core/src/compiler/htmlBundler.ts +++ b/packages/core/src/compiler/htmlBundler.ts @@ -7,7 +7,11 @@ import { parseHTMLContent, stripEmbeddedRuntimeScripts, } from "./htmlDocument"; -import { rewriteAssetPaths, rewriteCssAssetUrls } from "./rewriteSubCompPaths"; +import { + rewriteAssetPaths, + rewriteCssAssetUrls, + rewriteInlineStyleAssetUrls, +} from "./rewriteSubCompPaths"; import { scopeCssToComposition, wrapScopedCompositionScript } from "./compositionScoping"; import { validateHyperframeHtmlContract } from "./staticGuard"; @@ -501,18 +505,31 @@ export async function bundleToSingleHtml( el.setAttribute(attr, val); }, ); + const styledEls = innerRoot + ? innerRoot.querySelectorAll("[style]") + : contentDoc.querySelectorAll("[style]"); + rewriteInlineStyleAssetUrls( + styledEls, + src, + (el: Element) => el.getAttribute("style"), + (el: Element, val: string) => { + el.setAttribute("style", val); + }, + ); if (innerRoot) { const innerW = innerRoot.getAttribute("data-width"); const innerH = innerRoot.getAttribute("data-height"); if (innerW && !hostEl.getAttribute("data-width")) hostEl.setAttribute("data-width", innerW); if (innerH && !hostEl.getAttribute("data-height")) hostEl.setAttribute("data-height", innerH); + innerRoot.setAttribute("data-composition-file", src); for (const child of [...innerRoot.querySelectorAll("style, script")]) child.remove(); hostEl.innerHTML = compId ? innerRoot.innerHTML || "" : innerRoot.outerHTML || ""; } else { for (const child of [...contentDoc.querySelectorAll("style, script")]) child.remove(); hostEl.innerHTML = contentDoc.body.innerHTML || ""; } + hostEl.setAttribute("data-composition-file", src); hostEl.removeAttribute("data-composition-src"); } diff --git a/packages/core/src/compiler/rewriteSubCompPaths.test.ts b/packages/core/src/compiler/rewriteSubCompPaths.test.ts index d2048a195..7de4f42f0 100644 --- a/packages/core/src/compiler/rewriteSubCompPaths.test.ts +++ b/packages/core/src/compiler/rewriteSubCompPaths.test.ts @@ -1,5 +1,9 @@ import { describe, expect, it } from "vitest"; -import { rewriteAssetPath, rewriteCssAssetUrls } from "./rewriteSubCompPaths.js"; +import { + rewriteAssetPath, + rewriteCssAssetUrls, + rewriteInlineStyleAssetUrls, +} from "./rewriteSubCompPaths.js"; describe("rewriteAssetPath", () => { it("rewrites `../` against the sub-composition dir", () => { @@ -36,4 +40,19 @@ describe("rewriteAssetPath", () => { expect(out).not.toMatch(/\\/); expect(out).not.toMatch(/:\\/); }); + + it("rewrites CSS urls inside inline style attributes", () => { + const elements = [{ style: `background-image: url("../cover.png")` }]; + + rewriteInlineStyleAssetUrls( + elements, + "compositions/scene.html", + (el) => el.style, + (el, value) => { + el.style = value; + }, + ); + + expect(elements[0]?.style).toBe(`background-image: url("cover.png")`); + }); }); diff --git a/packages/core/src/compiler/rewriteSubCompPaths.ts b/packages/core/src/compiler/rewriteSubCompPaths.ts index 23ea579e9..72bc1ba23 100644 --- a/packages/core/src/compiler/rewriteSubCompPaths.ts +++ b/packages/core/src/compiler/rewriteSubCompPaths.ts @@ -96,6 +96,28 @@ export function rewriteAssetPaths( } } +/** + * Rewrite CSS url(...) references inside inline style attributes. + */ +export function rewriteInlineStyleAssetUrls( + elements: Iterable, + compSrcPath: string, + getStyle: (el: T) => string | null | undefined, + setStyle: (el: T, value: string) => void, +): void { + const compDir = dirname(compSrcPath); + if (!compDir || compDir === ".") return; + + for (const el of elements) { + const style = getStyle(el); + if (!style) continue; + const rewritten = rewriteCssAssetUrls(style, compSrcPath); + if (rewritten !== style) { + setStyle(el, rewritten); + } + } +} + /** * Rewrite CSS url(...) references in a sub-composition's inline styles so * ../foo.woff2 remains valid after the CSS is hoisted into the root document. diff --git a/packages/core/src/lint/rules/captions.test.ts b/packages/core/src/lint/rules/captions.test.ts index 3c0a59cbc..9ae3c02c3 100644 --- a/packages/core/src/lint/rules/captions.test.ts +++ b/packages/core/src/lint/rules/captions.test.ts @@ -50,6 +50,28 @@ describe("caption rules", () => { expect(finding).toBeUndefined(); }); + it("does not warn for generic GSAP opacity exits in non-caption loops", () => { + const html = ` + +
+ +
+`; + const result = lintHyperframeHtml(html); + const finding = result.findings.find((f) => f.code === "caption_exit_missing_hard_kill"); + expect(finding).toBeUndefined(); + }); + it("warns when caption group has nowrap without max-width", () => { const html = ` diff --git a/packages/core/src/lint/rules/captions.ts b/packages/core/src/lint/rules/captions.ts index f8e0f531a..94f09f7f4 100644 --- a/packages/core/src/lint/rules/captions.ts +++ b/packages/core/src/lint/rules/captions.ts @@ -12,7 +12,8 @@ export const captionRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> content, ); const hasCaptionLoop = - /forEach|\.forEach\s*\(/.test(content) && /createElement|caption|group|cg-/.test(content); + /forEach|\.forEach\s*\(/.test(content) && + /karaoke|caption[-_]?(?:group|word|line|block)|cg-/.test(content); if (hasCaptionLoop && hasExitTween && !hasHardKill) { findings.push({ code: "caption_exit_missing_hard_kill", diff --git a/packages/core/src/studio-api/createStudioApi.ts b/packages/core/src/studio-api/createStudioApi.ts index a7a94bb62..04492aad4 100644 --- a/packages/core/src/studio-api/createStudioApi.ts +++ b/packages/core/src/studio-api/createStudioApi.ts @@ -7,6 +7,7 @@ import { registerLintRoutes } from "./routes/lint.js"; import { registerRenderRoutes } from "./routes/render.js"; import { registerThumbnailRoutes } from "./routes/thumbnail.js"; import { registerWaveformRoutes } from "./routes/waveform.js"; +import { registerFontRoutes } from "./routes/fonts.js"; /** * Create a Hono sub-app with all studio API routes. @@ -24,6 +25,7 @@ export function createStudioApi(adapter: StudioApiAdapter): Hono { registerRenderRoutes(api, adapter); registerThumbnailRoutes(api, adapter); registerWaveformRoutes(api, adapter); + registerFontRoutes(api); return api; } diff --git a/packages/core/src/studio-api/helpers/manualEditsRenderScript.test.ts b/packages/core/src/studio-api/helpers/manualEditsRenderScript.test.ts new file mode 100644 index 000000000..3e41a15f2 --- /dev/null +++ b/packages/core/src/studio-api/helpers/manualEditsRenderScript.test.ts @@ -0,0 +1,382 @@ +import { describe, expect, it } from "vitest"; +import { Window } from "happy-dom"; +import { createStudioManualEditsRenderBodyScript } from "./manualEditsRenderScript"; + +function runScript( + window: Window, + script: string, + getComputedStyle: typeof window.getComputedStyle = window.getComputedStyle.bind(window), + timers: { + setInterval?: typeof globalThis.setInterval; + clearInterval?: typeof globalThis.clearInterval; + } = {}, +): void { + const execute = new Function( + "window", + "document", + "HTMLElement", + "getComputedStyle", + "setInterval", + "clearInterval", + script, + ); + execute( + window, + window.document, + window.HTMLElement, + getComputedStyle, + timers.setInterval ?? + (((callback: TimerHandler) => { + void callback; + return 0 as never; + }) as typeof globalThis.setInterval), + timers.clearInterval ?? globalThis.clearInterval, + ); +} + +describe("createStudioManualEditsRenderBodyScript", () => { + it("returns null for an empty manifest", () => { + expect(createStudioManualEditsRenderBodyScript("")).toBeNull(); + }); + + it("applies manual edits and reapplies them after render seeks", () => { + const window = new Window(); + window.document.body.innerHTML = '
'; + const card = window.document.getElementById("card"); + if (!(card instanceof window.HTMLElement)) { + throw new Error("card fixture missing"); + } + + let seekCalls = 0; + ( + window as unknown as { + __hf: { seek: (time: number) => void }; + } + ).__hf = { + seek: () => { + seekCalls += 1; + card.style.removeProperty("translate"); + }, + }; + + const script = createStudioManualEditsRenderBodyScript( + JSON.stringify({ + version: 1, + edits: [ + { + kind: "path-offset", + target: { sourceFile: "index.html", id: "card" }, + x: 12, + y: 24, + }, + { + kind: "box-size", + target: { sourceFile: "index.html", id: "card" }, + width: 120, + height: 64, + }, + { + kind: "rotation", + target: { sourceFile: "index.html", id: "card" }, + angle: 15, + }, + ], + }), + ); + if (!script) throw new Error("script fixture missing"); + + const computedStyle = (element: Element) => + ({ + display: element === card ? "block" : "block", + flexDirection: "row", + }) as CSSStyleDeclaration; + + const intervalCallbacks: Array<() => void> = []; + runScript(window, script, computedStyle, { + setInterval: ((callback: TimerHandler) => { + if (typeof callback === "function") intervalCallbacks.push(callback as () => void); + return 0 as never; + }) as typeof globalThis.setInterval, + }); + + expect(card.style.getPropertyValue("translate")).toContain("--hf-studio-offset-x"); + expect(card.style.getPropertyValue("width")).toBe("120px"); + expect(card.style.getPropertyValue("height")).toBe("64px"); + expect(card.style.getPropertyValue("rotate")).toContain("--hf-studio-rotation"); + expect(card.style.getPropertyValue("transform-origin")).toBe("center center"); + + ( + window as unknown as { + __hf: { seek: (time: number) => void }; + } + ).__hf.seek(1); + + expect(seekCalls).toBe(1); + expect(card.style.getPropertyValue("translate")).toContain("--hf-studio-offset-x"); + + ( + window as unknown as { + __hf: { seek: (time: number) => void }; + } + ).__hf.seek = () => { + card.style.removeProperty("rotate"); + }; + intervalCallbacks.forEach((callback) => callback()); + ( + window as unknown as { + __hf: { seek: (time: number) => void }; + } + ).__hf.seek(2); + expect(card.style.getPropertyValue("rotate")).toContain("--hf-studio-rotation"); + + ( + window as unknown as { + __player: { renderSeek: (time: number) => void }; + } + ).__player = { + renderSeek: () => { + card.style.removeProperty("rotate"); + }, + }; + intervalCallbacks.forEach((callback) => callback()); + ( + window as unknown as { + __player: { renderSeek: (time: number) => void }; + } + ).__player.renderSeek(3); + expect(card.style.getPropertyValue("rotate")).toContain("--hf-studio-rotation"); + }); + + it("applies render edits to the matching source file target", () => { + const window = new Window(); + window.document.body.innerHTML = ` +
+
+
+
+
+
+ `; + const cards = Array.from(window.document.getElementsByTagName("*")).filter( + (element): element is HTMLElement => + element instanceof window.HTMLElement && element.id === "card", + ); + const rootCard = cards[0]; + const nestedCard = cards[1]; + if (!rootCard || !nestedCard) { + throw new Error("source-scoped render fixture missing"); + } + + const script = createStudioManualEditsRenderBodyScript( + JSON.stringify({ + version: 1, + edits: [ + { + kind: "rotation", + target: { sourceFile: "scenes/nested.html", id: "card" }, + angle: 21, + }, + ], + }), + ); + if (!script) throw new Error("script fixture missing"); + + runScript(window, script); + + expect(rootCard.style.getPropertyValue("rotate")).toBe(""); + expect(nestedCard.style.getPropertyValue("rotate")).toContain("--hf-studio-rotation"); + }); + + it("applies render edits inside composition-file hosts without composition ids", () => { + const window = new Window(); + window.document.body.innerHTML = ` +
+
+
+
+
+
+ `; + const cards = Array.from(window.document.getElementsByTagName("*")).filter( + (element): element is HTMLElement => + element instanceof window.HTMLElement && element.id === "card", + ); + const rootCard = cards[0]; + const nestedCard = cards[1]; + if (!rootCard || !nestedCard) { + throw new Error("anonymous composition render fixture missing"); + } + + const script = createStudioManualEditsRenderBodyScript( + JSON.stringify({ + version: 1, + edits: [ + { + kind: "path-offset", + target: { sourceFile: "scenes/anonymous.html", id: "card" }, + x: 12, + y: 24, + }, + ], + }), + ); + if (!script) throw new Error("script fixture missing"); + + runScript(window, script); + + expect(rootCard.style.getPropertyValue("translate")).toBe(""); + expect(nestedCard.style.getPropertyValue("translate")).toContain("--hf-studio-offset-x"); + }); + + it("uses the active composition path as the unscoped document fallback", () => { + const window = new Window(); + window.document.body.innerHTML = `
`; + const card = window.document.getElementById("card"); + if (!(card instanceof window.HTMLElement)) { + throw new Error("card fixture missing"); + } + + const script = createStudioManualEditsRenderBodyScript( + JSON.stringify({ + version: 1, + edits: [ + { + kind: "path-offset", + target: { sourceFile: "compositions/scene-2.html", id: "card" }, + x: 12, + y: 24, + }, + ], + }), + { activeCompositionPath: "compositions/scene-2.html" }, + ); + if (!script) throw new Error("script fixture missing"); + + runScript(window, script); + + expect(card.style.getPropertyValue("translate")).toContain("--hf-studio-offset-x"); + }); + + it("preserves computed transform longhands as render edit bases", () => { + const window = new Window(); + window.document.body.innerHTML = `
`; + const card = window.document.getElementById("card"); + if (!(card instanceof window.HTMLElement)) { + throw new Error("card fixture missing"); + } + + const script = createStudioManualEditsRenderBodyScript( + JSON.stringify({ + version: 1, + edits: [ + { + kind: "path-offset", + target: { sourceFile: "index.html", id: "card" }, + x: 12, + y: 24, + }, + { + kind: "rotation", + target: { sourceFile: "index.html", id: "card" }, + angle: 15, + }, + ], + }), + ); + if (!script) throw new Error("script fixture missing"); + + const computedStyle = (element: Element) => + ({ + getPropertyValue: (property: string) => { + if (element !== card) return ""; + if (property === "translate") return "10px 20px"; + if (property === "rotate") return "8deg"; + return ""; + }, + }) as CSSStyleDeclaration; + + runScript(window, script, computedStyle); + + expect(card.style.getPropertyValue("translate")).toContain("calc(10px +"); + expect(card.style.getPropertyValue("translate")).toContain("calc(20px +"); + expect(card.style.getPropertyValue("rotate")).toContain("8deg"); + expect(card.style.getPropertyValue("rotate")).toContain("--hf-studio-rotation"); + expect(card.style.getPropertyValue("transform-origin")).toBe("center center"); + }); + + it("does not compound stale studio variables during render reapply", () => { + const window = new Window(); + window.document.body.innerHTML = ` +
+ `; + const card = window.document.getElementById("card"); + if (!(card instanceof window.HTMLElement)) { + throw new Error("card fixture missing"); + } + + const script = createStudioManualEditsRenderBodyScript( + JSON.stringify({ + version: 1, + edits: [ + { + kind: "path-offset", + target: { sourceFile: "index.html", id: "card" }, + x: 12, + y: 24, + }, + { + kind: "rotation", + target: { sourceFile: "index.html", id: "card" }, + angle: 15, + }, + ], + }), + ); + if (!script) throw new Error("script fixture missing"); + + runScript(window, script); + + expect(card.style.getPropertyValue("translate")).toBe( + "var(--hf-studio-offset-x, 0px) var(--hf-studio-offset-y, 0px)", + ); + expect(card.style.getPropertyValue("rotate")).toBe("var(--hf-studio-rotation, 0deg)"); + }); + + it("exposes a render reapply hook for thumbnails after layout settles", () => { + const window = new Window(); + window.document.body.innerHTML = `
`; + const card = window.document.getElementById("card"); + if (!(card instanceof window.HTMLElement)) { + throw new Error("card fixture missing"); + } + + const script = createStudioManualEditsRenderBodyScript( + JSON.stringify({ + version: 1, + edits: [ + { + kind: "path-offset", + target: { sourceFile: "index.html", id: "card" }, + x: 12, + y: 24, + }, + ], + }), + ); + if (!script) throw new Error("script fixture missing"); + + runScript(window, script); + card.style.removeProperty("translate"); + + ( + window as unknown as { + __hfStudioManualEditsApply?: () => number; + } + ).__hfStudioManualEditsApply?.(); + + expect(card.style.getPropertyValue("translate")).toContain("--hf-studio-offset-x"); + }); +}); diff --git a/packages/core/src/studio-api/helpers/manualEditsRenderScript.ts b/packages/core/src/studio-api/helpers/manualEditsRenderScript.ts new file mode 100644 index 000000000..714b86de4 --- /dev/null +++ b/packages/core/src/studio-api/helpers/manualEditsRenderScript.ts @@ -0,0 +1,369 @@ +export interface StudioManualEditsRenderScriptOptions { + activeCompositionPath?: string | null; +} + +export function createStudioManualEditsRenderBodyScript( + manifestContent: string, + options: StudioManualEditsRenderScriptOptions = {}, +): string | null { + if (!manifestContent.trim()) return null; + return `(${studioManualEditsRenderRuntime.toString()})(${JSON.stringify(manifestContent)}, ${JSON.stringify(options.activeCompositionPath ?? null)});`; +} + +function studioManualEditsRenderRuntime( + manifestContent: string, + activeCompositionPath: string | null, +): void { + const OFFSET_X_PROP = "--hf-studio-offset-x"; + const OFFSET_Y_PROP = "--hf-studio-offset-y"; + const WIDTH_PROP = "--hf-studio-width"; + const HEIGHT_PROP = "--hf-studio-height"; + const ROTATION_PROP = "--hf-studio-rotation"; + const PATH_OFFSET_ATTR = "data-hf-studio-path-offset"; + const BOX_SIZE_ATTR = "data-hf-studio-box-size"; + const ROTATION_ATTR = "data-hf-studio-rotation"; + const ORIGINAL_TRANSLATE_ATTR = "data-hf-studio-original-translate"; + const ORIGINAL_ROTATE_ATTR = "data-hf-studio-original-rotate"; + const WRAPPED_SEEK_PROP = "__hfStudioManualEditsWrapped"; + const ROTATION_TRANSFORM_ORIGIN = "center center"; + + const finiteNumber = (value: unknown): number | null => + typeof value === "number" && Number.isFinite(value) ? value : null; + + const objectRecord = (value: unknown): Record | null => + value && typeof value === "object" ? (value as Record) : null; + + const runtimeWindow = window as Window & { + __hf?: { seek?: (time: number) => unknown }; + __hfStudioManualEditsApply?: () => number; + __player?: { renderSeek?: (time: number) => unknown }; + }; + + const parsedManifest = (() => { + try { + return objectRecord(JSON.parse(manifestContent)); + } catch { + return null; + } + })(); + const manifestEdits = Array.isArray(parsedManifest?.edits) ? parsedManifest.edits : []; + if (manifestEdits.length === 0) return; + + const sourceFileForElement = (element: HTMLElement): string => { + let current: HTMLElement | null = element; + while (current) { + const sourceFile = + current.getAttribute("data-composition-file") ?? + current.getAttribute("data-composition-src"); + if (sourceFile) return sourceFile; + current = current.parentElement; + } + return activeCompositionPath ?? "index.html"; + }; + + const elementMatchesSourceFile = (element: HTMLElement, sourceFile: string): boolean => + sourceFileForElement(element) === sourceFile; + + const styleUsesStudioOffset = (value: string): boolean => + value.includes(OFFSET_X_PROP) || value.includes(OFFSET_Y_PROP); + + const styleUsesStudioRotation = (value: string): boolean => value.includes(ROTATION_PROP); + + const splitTopLevelWhitespace = (value: string): string[] => { + const parts: string[] = []; + let depth = 0; + let current = ""; + for (const char of value.trim()) { + if (char === "(") depth += 1; + if (char === ")") depth = Math.max(0, depth - 1); + if (/\s/.test(char) && depth === 0) { + if (current) parts.push(current); + current = ""; + } else { + current += char; + } + } + if (current) parts.push(current); + return parts; + }; + + const composeTranslate = (element: HTMLElement, x: string, y: string): string => { + const original = element.getAttribute(ORIGINAL_TRANSLATE_ATTR)?.trim(); + if (!original || original === "none") return `${x} ${y}`; + + const parts = splitTopLevelWhitespace(original); + if (parts.length === 1) return `calc(${parts[0]} + ${x}) ${y}`; + if (parts.length === 2) return `calc(${parts[0]} + ${x}) calc(${parts[1]} + ${y})`; + if (parts.length === 3) { + return `calc(${parts[0]} + ${x}) calc(${parts[1]} + ${y}) ${parts[2]}`; + } + return `${x} ${y}`; + }; + + const readStyleOrComputed = (element: HTMLElement, property: string): string => { + try { + return ( + element.style.getPropertyValue(property) || + getComputedStyle(element).getPropertyValue(property) + ); + } catch { + return element.style.getPropertyValue(property); + } + }; + + const readTransformLonghandBase = ( + element: HTMLElement, + property: "translate" | "rotate", + ): string => { + const value = readStyleOrComputed(element, property).trim(); + return value === "none" ? "" : value; + }; + + const preparePathOffsetBase = (element: HTMLElement): void => { + const currentTranslate = readTransformLonghandBase(element, "translate"); + const hasMarker = element.hasAttribute(PATH_OFFSET_ATTR); + const wasResetByAnimation = !styleUsesStudioOffset(currentTranslate); + if (!hasMarker) { + element.setAttribute(ORIGINAL_TRANSLATE_ATTR, wasResetByAnimation ? currentTranslate : ""); + } else if (wasResetByAnimation) { + element.setAttribute(ORIGINAL_TRANSLATE_ATTR, currentTranslate); + } + }; + + const prepareRotationBase = (element: HTMLElement): void => { + const currentRotate = readTransformLonghandBase(element, "rotate"); + const hasMarker = element.hasAttribute(ROTATION_ATTR); + const wasResetByAnimation = !styleUsesStudioRotation(currentRotate); + if (!hasMarker) { + element.setAttribute(ORIGINAL_ROTATE_ATTR, wasResetByAnimation ? currentRotate : ""); + } else if (wasResetByAnimation) { + element.setAttribute(ORIGINAL_ROTATE_ATTR, currentRotate); + } + }; + + const querySelectorCandidates = (selector: string): HTMLElement[] => { + const isCandidate = (element: Element): element is HTMLElement => + element instanceof HTMLElement; + + const className = selector.match(/^\.([A-Za-z0-9_-]+)$/)?.[1]; + if (className) { + return Array.from(document.getElementsByTagName("*")).filter( + (element): element is HTMLElement => + isCandidate(element) && element.classList.contains(className), + ); + } + + if (/^[A-Za-z][A-Za-z0-9-]*$/.test(selector)) { + return Array.from(document.getElementsByTagName(selector)).filter(isCandidate); + } + + return Array.from(document.querySelectorAll(selector)).filter(isCandidate); + }; + + const resolveTarget = (edit: Record): HTMLElement | null => { + const targetRecord = objectRecord(edit.target); + if (!targetRecord) return null; + + const sourceFile = typeof targetRecord.sourceFile === "string" ? targetRecord.sourceFile : ""; + if (!sourceFile) return null; + + const id = typeof targetRecord.id === "string" ? targetRecord.id : ""; + if (id) { + const byId = document.getElementById(id); + if (byId instanceof HTMLElement && elementMatchesSourceFile(byId, sourceFile)) return byId; + + const matchesById = [ + document.documentElement, + ...Array.from(document.getElementsByTagName("*")), + ].filter( + (element): element is HTMLElement => + element instanceof HTMLElement && + element.id === id && + elementMatchesSourceFile(element, sourceFile), + ); + if (matchesById[0]) return matchesById[0]; + } + + const selector = typeof targetRecord.selector === "string" ? targetRecord.selector : ""; + if (!selector) return null; + + try { + const matches = querySelectorCandidates(selector).filter((element) => + elementMatchesSourceFile(element, sourceFile), + ); + const selectorIndex = finiteNumber(targetRecord.selectorIndex) ?? 0; + return matches[Math.max(0, Math.floor(selectorIndex))] ?? null; + } catch { + return null; + } + }; + + const roundRotationAngle = (angle: number): number => Math.round(angle * 10) / 10; + + const isSimpleRotateAngle = (value: string): boolean => + /^-?(?:\d+(?:\.\d+)?|\.\d+)(?:deg|rad|turn|grad)$/.test(value.trim()); + + const composeRotation = (element: HTMLElement, rotationValue: string): string => { + const original = element.getAttribute(ORIGINAL_ROTATE_ATTR)?.trim(); + if (!original || original === "none" || !isSimpleRotateAngle(original)) { + return rotationValue; + } + return `calc(${original} + ${rotationValue})`; + }; + + const applyPathOffset = (element: HTMLElement, edit: Record): void => { + const x = finiteNumber(edit.x); + const y = finiteNumber(edit.y); + if (x == null || y == null) return; + preparePathOffsetBase(element); + element.setAttribute(PATH_OFFSET_ATTR, "true"); + element.style.setProperty(OFFSET_X_PROP, `${Math.round(x)}px`); + element.style.setProperty(OFFSET_Y_PROP, `${Math.round(y)}px`); + element.style.setProperty( + "translate", + composeTranslate(element, `var(${OFFSET_X_PROP}, 0px)`, `var(${OFFSET_Y_PROP}, 0px)`), + ); + }; + + const readParentFlexBasisPixels = ( + element: HTMLElement, + size: { width: number; height: number }, + ): number | null => { + const parent = element.parentElement; + if (!parent) return null; + const styles = getComputedStyle(parent); + if (styles.display !== "flex" && styles.display !== "inline-flex") return null; + return Math.round( + Math.max(1, styles.flexDirection.startsWith("column") ? size.height : size.width), + ); + }; + + const applyBoxSize = (element: HTMLElement, edit: Record): void => { + const width = finiteNumber(edit.width); + const height = finiteNumber(edit.height); + if (width == null || height == null || width <= 0 || height <= 0) return; + + const rounded = { + width: Math.round(Math.max(1, width)), + height: Math.round(Math.max(1, height)), + }; + element.setAttribute(BOX_SIZE_ATTR, "true"); + element.style.setProperty(WIDTH_PROP, `${rounded.width}px`); + element.style.setProperty(HEIGHT_PROP, `${rounded.height}px`); + element.style.setProperty("box-sizing", "border-box"); + element.style.setProperty("width", `${rounded.width}px`); + element.style.setProperty("height", `${rounded.height}px`); + element.style.setProperty("min-width", "0px"); + element.style.setProperty("min-height", "0px"); + element.style.setProperty("max-width", "none"); + element.style.setProperty("max-height", "none"); + + const flexBasis = readParentFlexBasisPixels(element, rounded); + if (flexBasis != null) { + element.style.setProperty("flex-basis", `${flexBasis}px`); + element.style.setProperty("flex-grow", "0"); + element.style.setProperty("flex-shrink", "0"); + } + if (getComputedStyle(element).display === "inline") { + element.style.setProperty("display", "inline-block"); + } + }; + + const applyRotation = (element: HTMLElement, edit: Record): void => { + const angle = finiteNumber(edit.angle); + if (angle == null) return; + prepareRotationBase(element); + element.setAttribute(ROTATION_ATTR, "true"); + element.style.setProperty(ROTATION_PROP, `${roundRotationAngle(angle)}deg`); + element.style.setProperty("transform-origin", ROTATION_TRANSFORM_ORIGIN); + element.style.setProperty("rotate", composeRotation(element, `var(${ROTATION_PROP}, 0deg)`)); + }; + + const applyManifest = (): number => { + let applied = 0; + for (const edit of manifestEdits) { + const editRecord = objectRecord(edit); + if (!editRecord) continue; + const element = resolveTarget(editRecord); + if (!element) continue; + if (editRecord.kind === "path-offset") applyPathOffset(element, editRecord); + if (editRecord.kind === "box-size") applyBoxSize(element, editRecord); + if (editRecord.kind === "rotation") applyRotation(element, editRecord); + applied += 1; + } + return applied; + }; + runtimeWindow.__hfStudioManualEditsApply = applyManifest; + + const markWrapped = (fn: (time: number) => unknown): void => { + try { + Object.defineProperty(fn, WRAPPED_SEEK_PROP, { + configurable: false, + enumerable: false, + value: true, + }); + } catch { + try { + (fn as unknown as Record)[WRAPPED_SEEK_PROP] = true; + } catch { + // Ignore non-extensible functions. + } + } + }; + + const isWrapped = (fn: (time: number) => unknown): boolean => + Boolean((fn as unknown as Record)[WRAPPED_SEEK_PROP]); + + const wrapFunction = ( + get: () => ((time: number) => unknown) | undefined, + set: (fn: (time: number) => unknown) => void, + ): boolean => { + const fn = get(); + if (!fn) return false; + const seek = fn as (time: number) => unknown; + if (isWrapped(seek)) { + applyManifest(); + return true; + } + + const wrappedSeek = function (this: unknown, time: number): unknown { + const result = seek.call(this, time); + applyManifest(); + return result; + }; + markWrapped(wrappedSeek); + set(wrappedSeek); + applyManifest(); + return true; + }; + + const wrapSeekFunctions = (): boolean => { + const wrappedHfSeek = wrapFunction( + () => runtimeWindow.__hf?.seek, + (fn) => { + if (runtimeWindow.__hf) runtimeWindow.__hf.seek = fn; + }, + ); + const wrappedPlayerRenderSeek = wrapFunction( + () => runtimeWindow.__player?.renderSeek, + (fn) => { + if (runtimeWindow.__player) runtimeWindow.__player.renderSeek = fn; + }, + ); + return wrappedHfSeek || wrappedPlayerRenderSeek; + }; + + if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", () => applyManifest(), { once: true }); + } else { + applyManifest(); + } + + wrapSeekFunctions(); + let remainingSeekWrapAttempts = 120; + const seekWrapInterval = setInterval(() => { + wrapSeekFunctions(); + remainingSeekWrapAttempts -= 1; + if (remainingSeekWrapAttempts <= 0) clearInterval(seekWrapInterval); + }, 50); +} diff --git a/packages/core/src/studio-api/helpers/screenshotClip.ts b/packages/core/src/studio-api/helpers/screenshotClip.ts index 715132daf..a1db59033 100644 --- a/packages/core/src/studio-api/helpers/screenshotClip.ts +++ b/packages/core/src/studio-api/helpers/screenshotClip.ts @@ -5,8 +5,15 @@ export interface ScreenshotClip { height: number; } -export function getElementScreenshotClip(selector: string): ScreenshotClip | undefined { - const el = document.querySelector(selector); +export function getElementScreenshotClip( + selector: string, + selectorIndex?: number, +): ScreenshotClip | undefined { + const matches = Array.from(document.querySelectorAll(selector)).filter( + (el): el is HTMLElement => el instanceof HTMLElement, + ); + const safeIndex = Math.max(0, Math.min(matches.length - 1, Math.floor(selectorIndex ?? 0))); + const el = matches[safeIndex] ?? null; if (!(el instanceof HTMLElement)) return undefined; const rect = el.getBoundingClientRect(); if (rect.width < 4 || rect.height < 4) return undefined; diff --git a/packages/core/src/studio-api/helpers/subComposition.test.ts b/packages/core/src/studio-api/helpers/subComposition.test.ts index 9d4378d73..e2121b12f 100644 --- a/packages/core/src/studio-api/helpers/subComposition.test.ts +++ b/packages/core/src/studio-api/helpers/subComposition.test.ts @@ -23,6 +23,7 @@ describe("buildSubCompositionHtml", () => { "compositions/hero.html": `